Merge pull request #46 from unicef/nicpottier/package-adt-web

Add ADT web packaging flow and runtime assets

Author: nicpottier

apps/api/src/app.ts

@@ -18,6 +18,7 @@ import { createProofRoutes } from "./routes/proof.js"
 import { createMasterService } from "./services/master-service.js"
 import { createMasterRunner } from "./services/master-runner.js"
 import { createMasterRoutes } from "./routes/master.js"
+import { createPackageRoutes } from "./routes/package.js"
 
 // Resolve paths relative to monorepo root (2 levels up from apps/api/)
 const projectRoot = path.resolve(
@@ -28,6 +29,9 @@ const promptsDir = path.resolve(process.env.PROMPTS_DIR ?? path.join(projectRoot
 const configPath = path.resolve(
   process.env.CONFIG_PATH ?? path.join(projectRoot, "config.yaml")
 )
+const webAssetsDir = path.resolve(
+  process.env.WEB_ASSETS_DIR ?? path.join(projectRoot, "assets", "web")
+)
 
 const pipelineRunner = createPipelineRunner()
 const pipelineService = createPipelineService(pipelineRunner)
@@ -63,5 +67,6 @@ app.route("/api", createMasterRoutes(masterService, booksDir, promptsDir, config
 app.route("/api", createGlossaryRoutes(booksDir))
 app.route("/api", createDebugRoutes(pipelineService, booksDir, promptsDir, configPath))
 app.route("/api", createQuizRoutes(booksDir))
+app.route("/api", createPackageRoutes(booksDir, webAssetsDir, configPath))
 
 export default app

apps/api/src/routes/books.ts

@@ -15,6 +15,23 @@ import {
 } from "../services/book-service.js"
 import { exportBook } from "../services/export-service.js"
 
+const MIME_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".mp3": "audio/mpeg",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".ico": "image/x-icon",
+  ".webp": "image/webp",
+}
+
 export function createBookRoutes(booksDir: string): Hono {
   const app = new Hono()
 
@@ -217,5 +234,65 @@ export function createBookRoutes(booksDir: string): Hono {
     }
   })
 
+  // GET /books/:label/adt/* — Serve packaged ADT static files
+  // When no file path is given, redirect to the first page.
+  app.get("/books/:label/adt/*", (c) => {
+    const { label } = c.req.param()
+    let safeLabel: string
+    try {
+      safeLabel = parseBookLabel(label)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      throw new HTTPException(400, { message })
+    }
+    const adtDir = path.join(path.resolve(booksDir), safeLabel, "adt")
+    if (!fs.existsSync(adtDir)) {
+      throw new HTTPException(404, {
+        message: `ADT not packaged for book: ${safeLabel}`,
+      })
+    }
+
+    // Extract file path from URL — c.req.param("*") is unreliable in sub-routers
+    const adtPrefix = `/books/${safeLabel}/adt/`
+    const reqPath = c.req.path
+    const prefixIdx = reqPath.indexOf(adtPrefix)
+    const filePath = prefixIdx >= 0 ? reqPath.slice(prefixIdx + adtPrefix.length) : ""
+    if (!filePath) {
+      // Root request — redirect to first page
+      const pagesPath = path.join(adtDir, "content", "pages.json")
+      if (!fs.existsSync(pagesPath)) {
+        throw new HTTPException(404, {
+          message: `ADT not packaged for book: ${safeLabel}`,
+        })
+      }
+      const pages = JSON.parse(fs.readFileSync(pagesPath, "utf-8")) as Array<{ href: string }>
+      if (pages.length === 0) {
+        throw new HTTPException(404, { message: "ADT has no pages" })
+      }
+      return c.redirect(`/api/books/${safeLabel}/adt/${pages[0].href}`)
+    }
+
+    const resolvedPath = path.resolve(adtDir, filePath)
+    if (!resolvedPath.startsWith(adtDir + path.sep)) {
+      throw new HTTPException(400, { message: "Invalid path" })
+    }
+
+    let stat: fs.Stats
+    try {
+      stat = fs.statSync(resolvedPath)
+    } catch {
+      throw new HTTPException(404, { message: `Not found: ${filePath}` })
+    }
+    if (!stat.isFile()) {
+      throw new HTTPException(404, { message: `Not found: ${filePath}` })
+    }
+
+    const fileBuffer = fs.readFileSync(resolvedPath)
+    const ext = path.extname(resolvedPath).toLowerCase()
+    c.header("Content-Type", MIME_TYPES[ext] ?? "application/octet-stream")
+    c.header("Cache-Control", "public, max-age=3600")
+    return c.body(fileBuffer)
+  })
+
   return app
 }

apps/api/src/routes/package.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { Hono } from "hono"
+import { createBookStorage } from "@adt/storage"
+import { errorHandler } from "../middleware/error-handler.js"
+import { createPackageRoutes } from "./package.js"
+
+describe("Package routes", () => {
+  let tmpDir: string
+  let webAssetsDir: string
+  let app: Hono
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "package-routes-"))
+    webAssetsDir = path.join(tmpDir, "web-assets")
+    fs.mkdirSync(webAssetsDir, { recursive: true })
+
+    app = new Hono()
+    app.onError(errorHandler)
+    app.route("/api", createPackageRoutes(tmpDir, webAssetsDir))
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  function createTestBook(label: string): void {
+    const storage = createBookStorage(label, tmpDir)
+    storage.close()
+  }
+
+  describe("POST /api/books/:label/package-adt", () => {
+    it("returns 404 for missing book", async () => {
+      const res = await app.request("/api/books/missing/package-adt", {
+        method: "POST",
+      })
+      expect(res.status).toBe(404)
+    })
+
+    it("returns 409 when master is not completed", async () => {
+      createTestBook("book1")
+
+      const res = await app.request("/api/books/book1/package-adt", {
+        method: "POST",
+      })
+
+      expect(res.status).toBe(409)
+      const body = await res.json()
+      expect(body.error).toContain("Master phase must be completed")
+    })
+  })
+
+  describe("GET /api/books/:label/package-adt/status", () => {
+    it("returns hasAdt=false when pages.json is missing", async () => {
+      createTestBook("book2")
+
+      const res = await app.request("/api/books/book2/package-adt/status")
+      expect(res.status).toBe(200)
+      expect(await res.json()).toEqual({ label: "book2", hasAdt: false })
+    })
+
+    it("returns hasAdt=false when pages.json is invalid JSON", async () => {
+      createTestBook("book3")
+      const pagesPath = path.join(tmpDir, "book3", "adt", "content", "pages.json")
+      fs.mkdirSync(path.dirname(pagesPath), { recursive: true })
+      fs.writeFileSync(pagesPath, "{not-json")
+
+      const res = await app.request("/api/books/book3/package-adt/status")
+      expect(res.status).toBe(200)
+      expect(await res.json()).toEqual({ label: "book3", hasAdt: false })
+    })
+
+    it("returns hasAdt=false when pages.json has no href entries", async () => {
+      createTestBook("book4")
+      const pagesPath = path.join(tmpDir, "book4", "adt", "content", "pages.json")
+      fs.mkdirSync(path.dirname(pagesPath), { recursive: true })
+      fs.writeFileSync(pagesPath, JSON.stringify([{ section_id: "pg001" }]))
+
+      const res = await app.request("/api/books/book4/package-adt/status")
+      expect(res.status).toBe(200)
+      expect(await res.json()).toEqual({ label: "book4", hasAdt: false })
+    })
+
+    it("returns hasAdt=true when pages.json has at least one href entry", async () => {
+      createTestBook("book5")
+      const pagesPath = path.join(tmpDir, "book5", "adt", "content", "pages.json")
+      fs.mkdirSync(path.dirname(pagesPath), { recursive: true })
+      fs.writeFileSync(
+        pagesPath,
+        JSON.stringify([{ section_id: "pg001", href: "pg001.html" }]),
+      )
+
+      const res = await app.request("/api/books/book5/package-adt/status")
+      expect(res.status).toBe(200)
+      expect(await res.json()).toEqual({ label: "book5", hasAdt: true })
+    })
+  })
+})

apps/api/src/routes/package.ts

@@ -0,0 +1,133 @@
+import fs from "node:fs"
+import path from "node:path"
+import { Hono } from "hono"
+import { HTTPException } from "hono/http-exception"
+import { parseBookLabel } from "@adt/types"
+import { createBookStorage } from "@adt/storage"
+import { packageAdtWeb, loadBookConfig } from "@adt/pipeline"
+
+export function createPackageRoutes(
+  booksDir: string,
+  webAssetsDir: string,
+  configPath?: string
+): Hono {
+  const app = new Hono()
+
+  // POST /books/:label/package-adt — Package the ADT web application
+  app.post("/books/:label/package-adt", async (c) => {
+    const { label } = c.req.param()
+    let safeLabel: string
+    try {
+      safeLabel = parseBookLabel(label)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      throw new HTTPException(400, { message })
+    }
+
+    const resolvedBooksDir = path.resolve(booksDir)
+    const bookDir = path.join(resolvedBooksDir, safeLabel)
+    if (!fs.existsSync(path.join(bookDir, `${safeLabel}.db`))) {
+      throw new HTTPException(404, {
+        message: `Book not found: ${safeLabel}`,
+      })
+    }
+
+    if (!fs.existsSync(webAssetsDir)) {
+      throw new HTTPException(500, {
+        message: "Web assets directory not found",
+      })
+    }
+
+    const storage = createBookStorage(safeLabel, booksDir)
+    try {
+      const masterStatusRow = storage.getLatestNodeData("master-status", "book")
+      const masterStatus = masterStatusRow?.data as { status?: string } | undefined
+      if (masterStatus?.status !== "completed") {
+        throw new HTTPException(409, {
+          message: "Master phase must be completed before packaging ADT",
+        })
+      }
+
+      // Load config for language settings
+      const config = loadBookConfig(safeLabel, booksDir, configPath)
+
+      // Get language from metadata or config
+      const metadataRow = storage.getLatestNodeData("metadata", "book")
+      const metadata = metadataRow?.data as {
+        title?: string | null
+        language_code?: string | null
+      } | null
+      const language =
+        config.editing_language ?? metadata?.language_code ?? "en"
+      const outputLanguages =
+        config.output_languages && config.output_languages.length > 0
+          ? config.output_languages
+          : [language]
+      const title = metadata?.title ?? safeLabel
+
+      await packageAdtWeb(storage, {
+        bookDir,
+        label: safeLabel,
+        language,
+        outputLanguages,
+        title,
+        webAssetsDir,
+      })
+
+      return c.json({ status: "completed", label: safeLabel })
+    } catch (err) {
+      if (err instanceof HTTPException) {
+        throw err
+      }
+      const message = err instanceof Error ? err.message : String(err)
+      throw new HTTPException(500, {
+        message: `Packaging failed: ${message}`,
+      })
+    } finally {
+      storage.close()
+    }
+  })
+
+  // GET /books/:label/package-adt/status — Check if ADT is packaged
+  app.get("/books/:label/package-adt/status", (c) => {
+    const { label } = c.req.param()
+    let safeLabel: string
+    try {
+      safeLabel = parseBookLabel(label)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      throw new HTTPException(400, { message })
+    }
+
+    const bookDir = path.join(path.resolve(booksDir), safeLabel)
+    const pagesPath = path.join(bookDir, "adt", "content", "pages.json")
+    const hasAdt = hasPackagedAdtPages(pagesPath)
+
+    return c.json({ label: safeLabel, hasAdt })
+  })
+
+  return app
+}
+
+function hasPackagedAdtPages(pagesPath: string): boolean {
+  if (!fs.existsSync(pagesPath)) {
+    return false
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(pagesPath, "utf-8")) as unknown
+    if (!Array.isArray(parsed)) {
+      return false
+    }
+
+    return parsed.some((entry) => {
+      if (typeof entry !== "object" || entry === null) {
+        return false
+      }
+      const href = (entry as { href?: unknown }).href
+      return typeof href === "string" && href.length > 0
+    })
+  } catch {
+    return false
+  }
+}

apps/studio/src/api/client.ts

@@ -10,6 +10,10 @@ function resolveBaseUrl(): string {
 
 const BASE_URL = resolveBaseUrl()
 
+export function getAdtUrl(label: string): string {
+  return `${BASE_URL}/books/${label}/adt`
+}
+
 async function request<T>(path: string, options?: RequestInit): Promise<T> {
   const url = `${BASE_URL}${path}`
   const res = await fetch(url, {
@@ -392,6 +396,17 @@ export const api = {
   getQuizzes: (label: string) =>
     request<QuizzesResponse>(`/books/${label}/quizzes`),
 
+  packageAdt: (label: string) =>
+    request<{ status: string; label: string }>(
+      `/books/${label}/package-adt`,
+      { method: "POST" }
+    ),
+
+  getPackageAdtStatus: (label: string) =>
+    request<{ label: string; hasAdt: boolean }>(
+      `/books/${label}/package-adt/status`
+    ),
+
   exportBook: async (label: string): Promise<Blob> => {
     const url = `${BASE_URL}/books/${label}/export`
     const res = await fetch(url)

apps/studio/src/components/debug/LlmLogsTab.tsx

@@ -46,6 +46,7 @@ const STEP_LABELS: Record<StepName, string> = {
   "text-catalog": "Text Catalog",
   "catalog-translation": "Translate Catalog",
   tts: "Speech",
+  "package-web": "Package",
 }
 
 interface LlmLogsTabProps {

apps/studio/src/components/pipeline/StepIndicator.tsx

@@ -36,6 +36,7 @@ const STEP_LABELS: Record<StepName, string> = {
   "text-catalog": "Build Text Catalog",
   "catalog-translation": "Translate Catalog",
   tts: "Generate Speech",
+  "package-web": "Package ADT",
 }
 
 export { STEP_ORDER, STEP_LABELS }