@uniweb/unipress 0.2.2

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@uniweb/unipress",
+  "version": "0.2.2",
+  "description": "Compile a content directory into a document (PDF, EPUB, Paged.js HTML, Typst source bundle, DOCX, XLSX) using a Uniweb foundation. Five built-in templates: book, monograph, report, data-report, directory.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "unipress": "src/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "RELEASING.md"
+  ],
+  "keywords": [
+    "uniweb",
+    "unipress",
+    "cli",
+    "document",
+    "docx",
+    "xlsx",
+    "pdf",
+    "typst",
+    "foundation"
+  ],
+  "author": "Proximify",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uniweb/unipress.git"
+  },
+  "homepage": "https://github.com/uniweb/unipress#readme",
+  "bugs": {
+    "url": "https://github.com/uniweb/unipress/issues"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "dependencies": {
+    "handlebars": "^4.7.8",
+    "js-yaml": "^4.1.0",
+    "prompts": "^2.4.2",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@uniweb/content-reader": "1.1.5",
+    "@uniweb/semantic-parser": "1.1.11",
+    "@uniweb/runtime": "0.8.4",
+    "@uniweb/core": "0.7.3",
+    "@uniweb/build": "0.11.2"
+  },
+  "scripts": {
+    "test": "echo \"no tests yet\" && exit 0",
+    "lint": "echo \"no lint yet\" && exit 0"
+  }
+}

package/src/catalog.js

@@ -0,0 +1,23 @@
+// Foundation catalog loader.
+//
+// The catalog (`src/foundations-data.js`) enumerates the Press-based
+// foundations unipress knows how to drive — each entry pairs a foundation
+// source URL with a content scaffold. The `create` command uses it to
+// present choices at scaffold time; the foundation-loader uses it to
+// resolve a catalog id to a URL when document.yml's `foundation:` names a
+// catalog entry.
+//
+// Stored as a JS module (not YAML) so `bun build --compile` can inline the
+// data at bundle time — see foundations-data.js for the rationale.
+
+import { FOUNDATIONS } from './foundations-data.js'
+
+const byId = new Map(FOUNDATIONS.map((e) => [e.id, e]))
+
+export function findCatalogEntry(id) {
+  return byId.get(id) || null
+}
+
+export function listCatalog() {
+  return FOUNDATIONS
+}

package/src/cli.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util'
+import { inspect } from './commands/inspect.js'
+import { compileCommand } from './commands/compile.js'
+import { createCommand, listTemplatesCommand } from './commands/create.js'
+import { UnipressError } from './errors.js'
+// Import assertion inlines package.json at bundle time. Required for
+// `bun build --compile`: reading the file at runtime fails because the
+// compiled binary's virtual filesystem (/$bunfs) doesn't hold it.
+import pkg from '../package.json' with { type: 'json' }
+
+const HELP = `unipress ${pkg.version}
+
+Compile a content directory into a document using a Uniweb foundation.
+
+Usage:
+  unipress <command> [options]
+
+Commands:
+  compile <dir>          Compile a content directory into a document
+                           --format <fmt>      output format (pdf | typst | docx | xlsx | epub)
+                                                 overrides format: in document.yml
+                                                 pdf compiles via typst source bundle
+                           --foundation <ref>  override document.yml's foundation: field
+                           --out <path>        output file (default: ./<dir>.<ext>)
+                           --config <path>     explicit config file (default: <dir>/unipress.config.js)
+                           --typst-binary <p>  path to a typst binary (skips managed download)
+                           --keep-temp         keep the typst temp dir on failure (for debugging)
+  create <dir>           Scaffold a new unipress project from a template
+                           --template <id>     template to use (interactive picker if omitted)
+                           --title <str>       document title (prompts if omitted)
+                           --author <str>      document author (prompts if omitted)
+                           --force             overwrite non-empty <dir>
+                           --yes               skip prompts (requires --template)
+  inspect <dir>          Dump the parsed content as JSON
+                           --full              include web-only fields (assets, icons, ...)
+                           --summary           replace pages[] with route strings only
+                           --page <route>      keep only the page matching <route>
+                           --depth <n>         truncate nested values beyond depth n
+                           --foundation <ref>  override the foundation in document.yml (a name or URL)
+                           --no-orchestrate    skip running the foundation; show only the parsed content
+  list-templates         List the templates available
+
+Options:
+  -h, --help             Show this help
+  -v, --version          Show version
+      --verbose          Include stack traces in error output
+`
+
+function printHelp() {
+  process.stdout.write(HELP)
+}
+
+function printVersion() {
+  process.stdout.write(`${pkg.version}\n`)
+}
+
+function unknownCommand(name) {
+  process.stderr.write(`error: unknown command \`${name}\`\n`)
+  process.stderr.write(`run \`unipress --help\` to see available commands\n`)
+  process.exit(1)
+}
+
+function notImplemented(name) {
+  process.stderr.write(`error: \`${name}\` is not implemented yet (M1 — package scaffold)\n`)
+  process.exit(2)
+}
+
+async function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: {
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' },
+      full: { type: 'boolean' },
+      summary: { type: 'boolean' },
+      page: { type: 'string' },
+      depth: { type: 'string' },
+      foundation: { type: 'string' },
+      template: { type: 'string' },
+      format: { type: 'string' },
+      out: { type: 'string' },
+      config: { type: 'string' },
+      title: { type: 'string' },
+      author: { type: 'string' },
+      force: { type: 'boolean' },
+      yes: { type: 'boolean' },
+      'typst-binary': { type: 'string' },
+      'keep-temp': { type: 'boolean' },
+      'no-orchestrate': { type: 'boolean' },
+      verbose: { type: 'boolean' }
+    },
+    allowPositionals: true,
+    strict: false
+  })
+
+  if (values.version) {
+    printVersion()
+    process.exit(0)
+  }
+
+  const [command, ...rest] = positionals
+
+  if (!command || values.help) {
+    printHelp()
+    process.exit(0)
+  }
+
+  try {
+    switch (command) {
+      case 'inspect':
+        await inspect({
+          dir: rest[0],
+          full: values.full,
+          summary: values.summary,
+          page: values.page ?? null,
+          depth: values.depth != null ? Number(values.depth) : null,
+          foundation: values.foundation ?? null,
+          orchestrate: !values['no-orchestrate']
+        })
+        break
+      case 'compile':
+        await compileCommand({
+          dir: rest[0],
+          format: values.format ?? null,
+          foundation: values.foundation ?? null,
+          out: values.out ?? null,
+          config: values.config ?? null,
+          typstBinary: values['typst-binary'] ?? null,
+          keepTemp: !!values['keep-temp'],
+          verbose: !!values.verbose
+        })
+        break
+      case 'create':
+        if (values.foundation != null) {
+          process.stderr.write(`error: --foundation is not valid for 'create'; use --template instead\n`)
+          process.exit(1)
+        }
+        await createCommand({
+          dir: rest[0],
+          template: values.template ?? null,
+          title: values.title ?? null,
+          author: values.author ?? null,
+          force: !!values.force,
+          yes: !!values.yes,
+        })
+        break
+      case 'list-templates':
+        await listTemplatesCommand()
+        break
+      case 'list-foundations':
+        process.stderr.write(`error: 'list-foundations' has been renamed to 'list-templates'\n`)
+        process.exit(1)
+        break
+      default:
+        unknownCommand(command)
+    }
+  } catch (err) {
+    // UnipressError = user-addressable problem (bad args, missing file,
+    // misconfigured foundation). Exit 1. .format() renders the structured
+    // `error:` header + indented `hint:` / `cause:` lines.
+    //
+    // Anything else = internal bug (TypeError, unhandled rejection from
+    // a library we didn't wrap). Exit 2. Always print a `(re-run with
+    // --verbose for a stack trace)` pointer unless verbose is already on.
+    const verbose = !!values.verbose
+    if (err instanceof UnipressError) {
+      process.stderr.write(err.format() + '\n')
+      if (verbose && err.stack) process.stderr.write(err.stack + '\n')
+      process.exit(1)
+    }
+    process.stderr.write(`internal error: ${err?.message ?? err}\n`)
+    if (verbose && err?.stack) {
+      process.stderr.write(err.stack + '\n')
+    } else {
+      process.stderr.write(`    hint: re-run with --verbose for a stack trace\n`)
+    }
+    process.exit(2)
+  }
+
+  // Defensive force-exit. Originally added because importing a built
+  // foundation kept a MessagePort alive (react-dom/server got bundled
+  // into a foundation chunk and ran React's scheduler at module-eval).
+  // Fixed at the source in @uniweb/build by externalizing react-dom/*
+  // properly, but kept here as a backstop: foundations published before
+  // the fix still leak, and any future module that creates a long-lived
+  // handle at import-time would do the same. CLIs shouldn't wait for
+  // non-essential handles regardless.
+  process.exit(0)
+}
+
+main(process.argv.slice(2))

package/src/commands/compile.js

@@ -0,0 +1,37 @@
+// `unipress compile <dir>` — CLI adapter for src/compile.js.
+//
+// Writes verbose progress to stderr so stdout stays clean for the
+// single success summary line.
+
+import { compile } from '../compile.js'
+
+export async function compileCommand({ dir, format = null, foundation = null, out = null, config = null, typstBinary = null, keepTemp = false, verbose = false } = {}) {
+  if (!dir) {
+    process.stderr.write('error: `compile` requires a directory argument\n')
+    process.stderr.write('usage: unipress compile <dir> [--format <fmt>] [--foundation <ref>] [--out <path>] [--config <path>] [--typst-binary <path>] [--keep-temp] [--verbose]\n')
+    process.exit(1)
+  }
+
+  const onProgress = verbose
+    ? (msg) => process.stderr.write(`[compile] ${msg}\n`)
+    : () => {}
+
+  const result = await compile({
+    dir,
+    format,
+    foundationRef: foundation,
+    outPath: out,
+    configPath: config,
+    typstBinaryPath: typstBinary,
+    keepTemp,
+    onProgress
+  })
+
+  const pressFormatNote =
+    result.pressFormat && result.pressFormat !== result.format
+      ? ` via ${result.pressFormat}`
+      : ''
+  process.stdout.write(
+    `wrote ${result.outPath} (${result.bytes} bytes, ${result.format}${pressFormatNote}, ${result.pageCount} pages)\n`
+  )
+}

package/src/commands/create.js

@@ -0,0 +1,165 @@
+// `unipress create <dir>` — scaffold a content directory from a catalog
+// template. A template pins a foundation and ships starter content; the
+// foundation it pins is the runtime artifact unipress loads at compile.
+//
+// Flow:
+//   1. If --template is not given and not --yes, interactively pick from
+//      the catalog. If --yes without --template, fail.
+//   2. Look up the catalog entry — resolves to a scaffold name.
+//   3. Collect scaffold vars (title, author, year) via prompts unless
+//      --yes is set (then defaults are used; flags override).
+//   4. Copy templates/<scaffold>/ to <dir> with Handlebars substitution.
+//   5. Print next steps.
+//
+// Result is a content-only folder — no package.json, no node_modules. On
+// first compile, unipress downloads the foundation from the catalog URL
+// into the shared cache and imports it.
+
+import { resolve } from 'node:path'
+import prompts from 'prompts'
+import { listCatalog, findCatalogEntry } from '../catalog.js'
+import { scaffold } from '../scaffold.js'
+import { TemplateError } from '../errors.js'
+
+function log(line) {
+  process.stdout.write(line + '\n')
+}
+function err(line) {
+  process.stderr.write(line + '\n')
+}
+
+async function pickTemplate() {
+  const entries = listCatalog()
+  if (entries.length === 0) {
+    throw new TemplateError(
+      `catalog is empty — no templates available for scaffolding\n` +
+      `hint: edit foundations.yml to add a template entry`
+    )
+  }
+  const response = await prompts({
+    type: 'select',
+    name: 'id',
+    message: 'Pick a template',
+    choices: entries.map((e) => ({
+      title: e.name || e.id,
+      description: e.description ? String(e.description).trim().replace(/\s+/g, ' ') : undefined,
+      value: e.id,
+    })),
+  })
+  if (!response.id) {
+    throw new TemplateError('no template selected — aborting')
+  }
+  return response.id
+}
+
+async function collectVars({ flagTitle, flagAuthor, interactive }) {
+  const now = new Date()
+  const defaults = {
+    title: flagTitle || 'Untitled document',
+    author: flagAuthor || '',
+    year: String(now.getFullYear()),
+    date: now.toISOString().slice(0, 10),
+  }
+  if (!interactive) return defaults
+  const answers = await prompts([
+    { type: flagTitle ? null : 'text', name: 'title', message: 'Title', initial: defaults.title },
+    { type: flagAuthor ? null : 'text', name: 'author', message: 'Author', initial: defaults.author },
+  ])
+  return {
+    title: flagTitle || answers.title || defaults.title,
+    author: flagAuthor || answers.author || defaults.author,
+    year: defaults.year,
+    date: defaults.date,
+  }
+}
+
+export async function createCommand({ dir, template, title, author, force = false, yes = false }) {
+  if (!dir) {
+    throw new TemplateError(
+      `usage: unipress create <dir> [--template <id>] [--title <t>] [--author <a>]`
+    )
+  }
+  const targetDir = resolve(dir)
+
+  let templateId = template
+  if (!templateId) {
+    if (yes) {
+      throw new TemplateError(
+        `--yes requires --template (no interactive selection when --yes is set)`
+      )
+    }
+    templateId = await pickTemplate()
+  }
+
+  const entry = findCatalogEntry(templateId)
+  if (!entry) {
+    throw new TemplateError(
+      `template '${templateId}' is not in the catalog\n` +
+      `hint: run 'unipress list-templates' to see available entries`
+    )
+  }
+
+  const scaffoldName = entry.scaffold
+  if (!scaffoldName) {
+    throw new TemplateError(
+      `catalog entry '${templateId}' has no scaffold declared\n` +
+      `hint: add 'scaffold: <name>' to the entry in foundations.yml`
+    )
+  }
+
+  const vars = await collectVars({ flagTitle: title, flagAuthor: author, interactive: !yes })
+  vars.foundation = templateId
+
+  log(`scaffolding ${targetDir}`)
+  log(`  template:  ${entry.name || entry.id} (id: ${entry.id})`)
+  log(`  scaffold:  ${scaffoldName}`)
+
+  await scaffold({
+    templateName: scaffoldName,
+    targetDir,
+    vars,
+    force,
+    onProgress: (msg) => log(`  ${msg}`),
+  })
+
+  log('')
+  log(`✓ ready`)
+  log(`  next: cd ${dir}`)
+  const formats = Array.isArray(entry.outputs) && entry.outputs.length > 0
+    ? entry.outputs.join(' | ')
+    : 'pdf'
+  log(`        unipress compile --format <${formats}>`)
+  log('')
+  const foundationUrl = entry.foundation?.source?.url ?? entry.source?.url
+  const foundationRef = entry.foundation?.ref
+  if (foundationRef) {
+    log(`note: the document.yml pins ${foundationRef}`)
+  }
+  if (foundationUrl) {
+    log(`      it will be fetched from ${foundationUrl}`)
+    log(`      and cached on the first compile.`)
+  }
+}
+
+export async function listTemplatesCommand() {
+  const entries = listCatalog()
+  if (entries.length === 0) {
+    err('catalog is empty')
+    return
+  }
+  for (const e of entries) {
+    log(`${e.id}`)
+    if (e.name) log(`  ${e.name}`)
+    if (e.description) {
+      const desc = String(e.description).trim().replace(/\s+/g, ' ')
+      log(`  ${desc}`)
+    }
+    if (Array.isArray(e.outputs) && e.outputs.length > 0) {
+      log(`  outputs: ${e.outputs.join(', ')}`)
+    }
+    if (e.foundation?.ref) log(`  pins:    ${e.foundation.ref}`)
+    const url = e.foundation?.source?.url ?? e.source?.url
+    if (url) log(`  source:  ${url}`)
+    log('')
+  }
+}

package/src/commands/inspect.js

@@ -0,0 +1,182 @@
+// `unipress inspect <dir>` — load a content directory and dump the resolved
+// object as JSON. Used as a debugging aid and as the visible output of M2.
+//
+// Filtering knobs:
+//   --full              include the web-only fields stripped by default
+//                       (assets, icons, hasExplicitPoster/Preview)
+//   --summary           replace pages[] with route strings only
+//   --page <route>      keep only the page matching <route>; errors if no match
+//   --depth <n>         truncate nested values beyond depth n
+//   --foundation <ref>  override document.yml's foundation: field
+//
+// As of M3a, inspect also resolves the foundation reference and reports
+// the resolved path in __unipress.foundation. It does NOT import the
+// foundation; M3b does that.
+
+import { loadContent } from '../content-loader.js'
+import { resolveFoundation } from '../foundation-loader.js'
+import { loadAndInit } from '../orchestrator.js'
+
+const SKIP_KEYS = new Set([
+  'assets',
+  'hasExplicitPoster',
+  'hasExplicitPreview',
+  'icons'
+])
+
+const TRUNCATED = '__truncated__'
+
+export async function inspect({ dir, full = false, summary = false, page = null, depth = null, foundation: foundationCliRef = null, orchestrate = true } = {}) {
+  if (!dir) {
+    process.stderr.write('error: `inspect` requires a directory argument\n')
+    process.stderr.write('usage: unipress inspect <dir> [--full] [--summary] [--page <route>] [--depth <n>] [--foundation <ref>] [--no-orchestrate]\n')
+    process.exit(1)
+  }
+
+  if (depth !== null && (!Number.isInteger(depth) || depth < 0)) {
+    process.stderr.write(`error: --depth must be a non-negative integer (got ${depth})\n`)
+    process.exit(1)
+  }
+
+  const { content, configFile, sitePath } = await loadContent(dir)
+
+  // Resolve foundation reference. Failure to resolve is reported in
+  // __unipress.foundation as { ref, error } so the rest of inspect still
+  // works — it's a debugging tool, the user wants to see what loaded even
+  // if one piece broke.
+  let foundationInfo
+  try {
+    foundationInfo = await resolveFoundation({
+      cliRef: foundationCliRef,
+      configRef: content.config?.foundation,
+      anchorDir: sitePath
+    })
+  } catch (err) {
+    foundationInfo = { ref: foundationCliRef ?? content.config?.foundation ?? null, error: err.message }
+  }
+
+  // Orchestrate (M3b): import the foundation and run initPrerender to
+  // populate the Website graph. Surface a summary, not the raw graph
+  // (which has back-references and isn't JSON-friendly). Orchestration
+  // failures are non-fatal for the same reason resolution failures are.
+  let websiteInfo = null
+  if (orchestrate && foundationInfo.resolvedPath) {
+    try {
+      const { uniweb } = await loadAndInit({
+        content,
+        resolvedPath: foundationInfo.resolvedPath
+      })
+      websiteInfo = summarizeWebsite(uniweb, { route: page })
+    } catch (err) {
+      websiteInfo = { error: err.message }
+    }
+  }
+
+  let view = full ? { ...content } : trimSkipKeys(content)
+
+  if (page) {
+    view = filterToPage(view, page)
+  } else if (summary) {
+    view = summarizePages(view)
+  }
+
+  view.__unipress = { sitePath, configFile, foundation: foundationInfo, website: websiteInfo }
+
+  const output = depth !== null ? truncate(view, depth) : view
+  process.stdout.write(JSON.stringify(output, replacer, 2) + '\n')
+}
+
+// Summarize the populated Website graph for inspect output. The full
+// graph has cycles (page.website ↔ website.pages, block.page ↔ page)
+// and won't survive JSON.stringify; this returns a tree with no
+// back-refs and the per-block info that matters for "did the graph
+// build correctly" debugging.
+//
+// Page exposes blocks via `bodyBlocks` (and `getPageBlocks()` which
+// merges header/body/footer from the layout). We report bodyBlocks
+// here — header/footer come from layout areas, not page content.
+function summarizeWebsite(uniweb, { route = null } = {}) {
+  const w = uniweb?.activeWebsite
+  if (!w) return { error: 'uniweb.activeWebsite is null' }
+
+  const allPages = w.pages ?? []
+  const pages = (route ? allPages.filter(p => p.route === route) : allPages).map(p => {
+    const blocks = p.bodyBlocks ?? []
+    return {
+      route: p.route,
+      blockCount: blocks.length,
+      blocks: blocks.map(b => ({
+        type: b.type ?? null,
+        hasContent: b.parsedContent != null,
+        childBlockCount: (b.childBlocks ?? []).length,
+        insetCount: (b.insets ?? []).length
+      }))
+    }
+  })
+
+  return {
+    pageCount: allPages.length,
+    activePage: w.activePage?.route ?? null,
+    basePath: w.basePath ?? '/',
+    pages
+  }
+}
+
+function trimSkipKeys(content) {
+  const out = {}
+  for (const [key, value] of Object.entries(content)) {
+    if (SKIP_KEYS.has(key)) continue
+    out[key] = value
+  }
+  return out
+}
+
+function filterToPage(view, route) {
+  if (!Array.isArray(view.pages)) {
+    process.stderr.write(`error: content has no pages[] to filter\n`)
+    process.exit(1)
+  }
+  const match = view.pages.find(p => p.route === route)
+  if (!match) {
+    const available = view.pages.map(p => p.route).join(', ') || '(none)'
+    process.stderr.write(`error: no page with route '${route}'\n`)
+    process.stderr.write(`available routes: ${available}\n`)
+    process.exit(1)
+  }
+  return { ...view, pages: [match] }
+}
+
+function summarizePages(view) {
+  if (!Array.isArray(view.pages)) return view
+  return {
+    ...view,
+    pages: view.pages.map(p => p.route)
+  }
+}
+
+// Walk the value, replacing anything beyond `maxDepth` with TRUNCATED.
+// Depth counts from the root: depth 0 truncates everything inside the root.
+// Arrays preserve length so the user can still see "this had 12 items."
+function truncate(value, maxDepth, currentDepth = 0) {
+  if (value === null || typeof value !== 'object') return value
+  if (currentDepth >= maxDepth) {
+    if (Array.isArray(value)) return value.length === 0 ? [] : [TRUNCATED, `(${value.length} items)`]
+    return TRUNCATED
+  }
+  if (Array.isArray(value)) {
+    return value.map(item => truncate(item, maxDepth, currentDepth + 1))
+  }
+  const out = {}
+  for (const [key, child] of Object.entries(value)) {
+    out[key] = truncate(child, maxDepth, currentDepth + 1)
+  }
+  return out
+}
+
+// JSON.stringify can't serialize Sets / Maps. The content object has a few
+// of these; convert them to plain values so output is readable.
+function replacer(_key, value) {
+  if (value instanceof Set) return [...value]
+  if (value instanceof Map) return Object.fromEntries(value)
+  return value
+}