@ryanyahya/opendoc 0.4.0

package/src/assets/usage.ts

@@ -0,0 +1,118 @@
+import { lstat, readdir, readFile, realpath } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import ts from 'typescript';
+import type { AssetKind, AssetRef, AssetUsage, DocumentAssets } from '../shared/assets';
+import type { DocumentState, RenderArtifact } from '../shared/types';
+import { assertAssetId, assertKind, readDocumentAssetsAt, readThemeAssetDefaults, safeAssetPath, validAssetId, validRevision } from './files';
+
+async function directories(root: string, folder: string) {
+  try {
+    const path = safeAssetPath(root, folder, true);
+    return (await readdir(path, { withFileTypes: true })).filter(item => item.isDirectory()).map(item => item.name).sort();
+  } catch { return []; }
+}
+async function localText(root: string, file: string, maximum = 512_000) {
+  try { const path = safeAssetPath(root, file); if ((await lstat(path)).size > maximum) return undefined; return await readFile(path, 'utf8'); }
+  catch { return undefined; }
+}
+async function localJson(root: string, file: string, maximum?: number): Promise<any> {
+  const text = await localText(root, file, maximum);
+  if (text === undefined) return undefined;
+  try { return JSON.parse(text); } catch { return undefined; }
+}
+function literalName(contents: string | undefined, property: 'name' | 'title', themeId?: string) {
+  if (!contents) return undefined;
+  const source = ts.createSourceFile('index.tsx', contents, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  let found: string | undefined;
+  function value(node: ts.ObjectLiteralExpression, key: string) {
+    for (const field of node.properties) if (ts.isPropertyAssignment(field) && (ts.isIdentifier(field.name) || ts.isStringLiteral(field.name)) && field.name.text === key && (ts.isStringLiteral(field.initializer) || ts.isNoSubstitutionTemplateLiteral(field.initializer))) return field.initializer.text;
+  }
+  function visit(node: ts.Node) {
+    if (found) return;
+    if (ts.isObjectLiteralExpression(node) && (themeId ? value(node, 'id') === themeId : ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name) && node.parent.name.text === 'meta')) found = value(node, property)?.trim() || undefined;
+    ts.forEachChild(node, visit);
+  }
+  visit(source);
+  return found;
+}
+function bindingRoles(bindings: DocumentAssets, kind: AssetKind) {
+  const entries: [string, AssetRef | undefined][] = kind === 'logo'
+    ? [['logo', bindings.logo], ...Object.entries(bindings.logos ?? {}).map(([name, ref]) => [`logo:${name}`, ref] as [string, AssetRef])]
+    : [['body', bindings.bodyFont], ['headings', bindings.headingFont]];
+  return entries.filter((entry): entry is [string, AssetRef] => !!entry[1]);
+}
+const choices = (bindings: DocumentAssets, kind: AssetKind, id: string) => bindingRoles(bindings, kind).filter(([, reference]) => reference.id === id);
+function actualRevisions(artifact: RenderArtifact | undefined, kind: AssetKind, id: string) {
+  return new Set((Array.isArray(artifact?.assets) ? artifact.assets : []).filter(use => use && use.kind === kind && use.id === id && validRevision(use.revision)).map(use => use.revision));
+}
+
+/** Read relationships without rendering a theme, evaluating document source, or guessing PDF usage. */
+export async function assetUsage(workspace: string, kind: AssetKind, id: string, states?: DocumentState[]): Promise<AssetUsage> {
+  assertKind(kind); assertAssetId(id);
+  const root = await realpath(workspace);
+  const usage: AssetUsage = { themes: [], documents: [] };
+  for (const themeId of await directories(root, resolve(root, 'themes'))) {
+    if (!validAssetId(themeId)) continue;
+    try {
+      const defaults = readThemeAssetDefaults(root, themeId);
+      const roles = kind === 'logo' ? defaults.logo?.id === id ? ['logo'] : [] : [defaults.bodyFont === id ? 'body' : '', defaults.headingFont === id ? 'headings' : ''].filter(Boolean);
+      if (roles.length) usage.themes.push({ id: themeId, name: literalName(await localText(root, resolve(root, 'themes', themeId, 'index.ts')), 'name', themeId) ?? themeId, roles });
+    } catch { /* An invalid neighboring theme is reported by its own inspector. */ }
+  }
+  const projectManifest = await localJson(root, resolve(root, 'projects.json'), 1_000_000);
+  const names = projectManifest?.names && typeof projectManifest.names === 'object' ? projectManifest.names as Record<string, unknown> : {};
+  const live = new Map((states ?? []).map(state => [state.id, state]));
+  const documents: { id: string; folder: string; name?: string; trashed?: boolean; deletedAt?: number }[] = [];
+  for (const documentId of await directories(root, resolve(root, 'documents'))) {
+    if (!validAssetId(documentId)) continue;
+    const folder = resolve(root, 'documents', documentId);
+    if (await localText(root, resolve(folder, 'index.tsx')) === undefined) continue;
+    documents.push({ id: documentId, folder });
+  }
+  for (const restoreId of await directories(root, resolve(root, '.opendoc/trash'))) {
+    const receipt = await localJson(root, resolve(root, '.opendoc/trash', restoreId, 'receipt.json'), 4096);
+    if (!validAssetId(receipt?.id)) continue;
+    const folder = resolve(root, '.opendoc/trash', restoreId, 'document');
+    if (await localText(root, resolve(folder, 'index.tsx')) === undefined) continue;
+    documents.push({ id: receipt.id, folder, trashed: true, ...(Number.isFinite(Date.parse(receipt.deletedAt)) ? { deletedAt: Date.parse(receipt.deletedAt) } : {}), ...(typeof receipt.name === 'string' && receipt.name.trim() ? { name: receipt.name } : {}) });
+  }
+  // Live states carry the authoritative last successful PDF. CLI readers may use
+  // persisted render artifacts as historical evidence, never as current readiness.
+  const persisted = new Map<string, RenderArtifact>();
+  const needed = documents.filter(doc => doc.trashed || !live.get(doc.id)?.artifact);
+  const neededIds = new Set(needed.map(doc => doc.id));
+  if (needed.length) for (const folder of await directories(root, resolve(root, '.opendoc/renders'))) {
+    const documentId = folder.replace(/-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/, '');
+    if (!neededIds.has(documentId)) continue;
+    const artifact = await localJson(root, resolve(root, '.opendoc/renders', folder, 'artifact.json'), 16_000_000) as RenderArtifact | undefined;
+    if (artifact?.provenance?.entry !== `documents/${documentId}/index.tsx` || !Number.isFinite(Date.parse(artifact.renderedAt))) continue;
+    for (const document of needed.filter(doc => doc.id === documentId)) {
+      // IDs can be reused after deleting a document. A newer PDF must never be
+      // attributed to the old copy in Trash merely because its path once matched.
+      if (document.trashed && (document.deletedAt === undefined || Date.parse(artifact.renderedAt) > document.deletedAt)) continue;
+      const previous = persisted.get(document.folder);
+      if (!previous || Date.parse(previous.renderedAt) < Date.parse(artifact.renderedAt)) persisted.set(document.folder, artifact);
+    }
+  }
+  for (const document of documents) {
+    const state = document.trashed ? undefined : live.get(document.id);
+    const artifact = state?.artifact ?? persisted.get(document.folder);
+    let bindings: DocumentAssets = { version: 1 };
+    try { bindings = readDocumentAssetsAt(root, document.folder); } catch { /* Retain actual PDF evidence even when the saved choices need repair. */ }
+    const bound = choices(bindings, kind, id), rendered = actualRevisions(artifact, kind, id);
+    const revisions = new Set([...bound.map(([, reference]) => reference.revision), ...rendered]);
+    if (!revisions.size) continue;
+    const savedName = !document.trashed && typeof names[document.id] === 'string' ? names[document.id] as string : undefined;
+    const name = document.name ?? state?.name ?? savedName ?? (typeof artifact?.meta?.title === 'string' ? artifact.meta.title : undefined) ?? literalName(await localText(root, resolve(document.folder, 'index.tsx')), 'title') ?? document.id;
+    for (const revision of revisions) {
+      const renderedBindings = artifact?.assetBindings;
+      const roles = new Set(bound.filter(([, reference]) => reference.revision === revision).map(([role]) => role));
+      if (rendered.has(revision) && renderedBindings) for (const [role, reference] of choices(renderedBindings, kind, id)) if (reference.revision === revision) roles.add(role);
+      const rebound = [...roles].some(role => !bindingRoles(bindings, kind).some(([currentRole, reference]) => currentRole === role && reference.id === id && reference.revision === revision));
+      usage.documents.push({ id: document.id, name, revision, roles: [...roles], rendered: rendered.has(revision), current: !!state && state.status === 'ready' && rendered.has(revision) && !rebound, ...(document.trashed ? { trashed: true } : {}) });
+    }
+  }
+  usage.themes.sort((a, b) => a.name.localeCompare(b.name));
+  usage.documents.sort((a, b) => a.name.localeCompare(b.name) || Number(!!a.trashed) - Number(!!b.trashed) || a.revision.localeCompare(b.revision));
+  return usage;
+}

package/src/cli/check.ts

@@ -0,0 +1,25 @@
+import { dirname, resolve } from 'node:path';
+import { access, readFile } from 'node:fs/promises';
+import { runtimeResolve, applicationRoot } from '../runtime/paths';
+import { runProcess } from './process';
+import { packageIdentity, packageMetadata } from './workspace';
+
+export async function validateInstallation() {
+  const { edition } = packageIdentity(await packageMetadata());
+  await Promise.all([...(edition === 'normal' ? ['dist/index.html'] : []), 'src/server/worker.ts', 'src/assets/import-worker.ts', 'tsconfig.workspace.json'].map(path => access(resolve(applicationRoot, path))));
+  const core = runtimeResolve('@formepdf/core');
+  const manifest = JSON.parse(await readFile(resolve(dirname(core), '../package.json'), 'utf8'));
+  if (manifest.version !== '0.20.1-opendoc.3') throw new Error('The repaired OpenDoc rendering engine is missing. Reinstall this OpenDoc release.');
+  const { transform } = await import('esbuild');
+  await transform('const ok: boolean = true', { loader: 'ts' });
+}
+
+export async function checkWorkspace(root: string, json = false, quiet = false) {
+  const compiler = runtimeResolve('typescript/lib/tsc.js');
+  const result = await runProcess(process.execPath, [compiler, '--project', resolve(root, 'tsconfig.json'), '--noEmit'], root, { capture: true });
+  if (result.code) {
+    if (result.stdout.trim()) process.stderr.write(result.stdout);
+    throw new Error('Workspace typecheck failed. Correct the authoring errors above and run npx opendoc check again.');
+  }
+  if (!quiet) console.log(json ? JSON.stringify({ ok: true, workspace: root }) : 'Workspace authoring files typecheck successfully.');
+}

package/src/cli/init.ts

@@ -0,0 +1,119 @@
+import { cp, lstat, mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from 'node:util';
+import { applicationRoot } from '../runtime/paths';
+import { dependencyPin, installedApplication, packageIdentity, packageMetadata, packageNames, workspaceFormat, type Edition, type PackageIdentity } from './workspace';
+import { runProcess } from './process';
+
+const usageFor = (edition: Edition) => edition === 'headless'
+  ? `Usage: npx --yes ${packageNames.headless} init <folder> [--json]\nCreates a headless workspace without starting a server. The folder must be new or empty.`
+  : `Usage: npx --yes ${packageNames.normal} init [folder] [--no-start] [--no-open] [--json]\nCreates a new workspace. The folder must be new or empty.`;
+const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
+const skills = ['opendoc-create', 'opendoc-current-document', 'opendoc-apply-comments', 'opendoc-create-theme', 'opendoc-create-template', 'opendoc-review-document'];
+const instructions = `# OpenDoc workspace\n\nThis folder contains your documents, presentations, projects, themes, templates, and assets.\n\nRead [the OpenDoc agent guide](node_modules/opendoc/AGENTS.md) before authoring or editing. Use the matching OpenDoc skill below; its substantive instructions live with the installed runtime. Resolve document and catalog paths from this workspace, not from the installed package.\n\nUse \`npx opendoc\` commands from this folder or a subfolder. Start the app with \`npx opendoc start\`; check authoring with \`npx opendoc check\`. Keep stable content identities and saved corrections. Finish authorized work through reviewed exports.\n\nDo not edit \`node_modules/opendoc\` to change a document or theme. The workspace-owned \`themes/\` and \`templates/\` are editable. Runtime updates use \`npx opendoc update\` after stopping OpenDoc with Ctrl+C.\n`;
+const headlessInstructions = `# OpenDoc Headless workspace\n\nThis folder contains your documents, presentations, projects, themes, templates, and assets. OpenDoc runs in the agent's environment; recipients receive finished PDF and PowerPoint files and need no OpenDoc installation.\n\nRead [the OpenDoc Headless agent guide](node_modules/opendoc/AGENTS.md) before authoring or editing. Use the matching OpenDoc skill; its substantive instructions live with the installed runtime. Resolve document and catalog paths from this workspace, not from the installed package.\n\nUse \`npx opendoc\` commands from this folder or a subfolder. Author from the user's brief, run \`npx opendoc check\`, then \`npx opendoc review <id> --json\`. Inspect every generated page image and the extracted text, correct issues, and export the final PDF with \`npx opendoc export <id>\`. For presentations also export editable PowerPoint with \`npx opendoc export <id> --format pptx\`. Deliver the requested files through your existing channel. Keep stable content identities and saved corrections. The workflow does not require a browser or persistent server.\n\nDo not edit \`node_modules/opendoc\` to change a document or theme. The workspace-owned \`themes/\` and \`templates/\` are editable. Keep this workspace when future revisions or reusable themes and templates are needed. Runtime updates use \`npx opendoc update\` and preserve the Headless edition and workspace content.\n`;
+
+export async function requireEmptyDestination(root: string) {
+  try {
+    const info = await lstat(root);
+    if (!info.isDirectory() || info.isSymbolicLink() || (await readdir(root)).length) throw new Error(`Refusing to overwrite ${root}. Choose a new or empty directory.`);
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+}
+
+export type InitDependencies = {
+  install?: (stage: string, version: string, identity: PackageIdentity) => Promise<void>;
+  validate?: (stage: string) => Promise<void>;
+};
+
+async function copyContents(source: string, destination: string) {
+  for (const entry of await readdir(source)) {
+    await cp(resolve(source, entry), resolve(destination, entry), { recursive: true, force: false, errorOnExist: true, verbatimSymlinks: true });
+  }
+}
+
+/** Prepare privately, then copy without ever overwriting a destination file. */
+export async function initializeWorkspace(destination: string, options: { sourceRoot?: string; tarball?: string } = {}, dependencies: InitDependencies = {}) {
+  if (!['darwin', 'linux'].includes(process.platform)) throw new Error('OpenDoc 0.4 supports macOS and Linux.');
+  const root = resolve(destination === '~' ? homedir() : destination.startsWith('~/') ? resolve(homedir(), destination.slice(2)) : destination);
+  await requireEmptyDestination(root);
+  const sourceRoot = options.sourceRoot ?? applicationRoot;
+  const identity = packageIdentity(await packageMetadata(sourceRoot));
+  const { version, edition } = identity;
+  const pin = dependencyPin(identity);
+  await mkdir(dirname(root), { recursive: true });
+  const stage = await mkdtemp(resolve(dirname(root), '.opendoc-init-'));
+  try {
+    await copyContents(resolve(sourceRoot, 'starter'), stage);
+    const manifest = { name: 'opendoc-workspace', private: true, type: 'module', dependencies: { opendoc: pin } };
+    await writeFile(resolve(stage, 'package.json'), JSON.stringify(manifest, null, 2) + '\n', { flag: 'wx' });
+    await writeFile(resolve(stage, 'tsconfig.json'), JSON.stringify({ extends: 'opendoc/tsconfig.workspace.json', include: ['documents', 'templates', 'themes'] }, null, 2) + '\n', { flag: 'wx' });
+    await mkdir(resolve(stage, '.opendoc'), { recursive: true });
+    await writeFile(resolve(stage, '.opendoc/workspace.json'), JSON.stringify({ formatVersion: workspaceFormat, createdWith: version, edition }, null, 2) + '\n', { flag: 'wx' });
+    await writeFile(resolve(stage, 'AGENTS.md'), edition === 'headless' ? headlessInstructions : instructions, { flag: 'wx' });
+    await writeFile(resolve(stage, 'CLAUDE.md'), '# OpenDoc\n\nRead and follow [AGENTS.md](AGENTS.md), including its installed OpenDoc guide and skills.\n', { flag: 'wx' });
+    await writeFile(resolve(stage, '.gitignore'), 'node_modules/\n.opendoc/*\n!.opendoc/workspace.json\noutput/\n.DS_Store\n', { flag: 'wx' });
+    for (const skill of skills) {
+      const source = await readFile(resolve(sourceRoot, '.agents/skills', skill, 'SKILL.md'), 'utf8');
+      const frontmatter = source.match(/^---\r?\n[\s\S]*?\r?\n---/)?.[0] ?? `---\nname: ${skill}\ndescription: OpenDoc authoring workflow.\n---`;
+      const directory = resolve(stage, '.agents/skills', skill);
+      await mkdir(directory, { recursive: true });
+      await writeFile(resolve(directory, 'SKILL.md'), `${frontmatter}\n\nRead and follow [the installed ${skill} skill](../../../node_modules/opendoc/.agents/skills/${skill}/SKILL.md). Resolve document and catalog paths from this workspace; the installed file contains version-matched instructions.\n`, { flag: 'wx' });
+    }
+    console.error(`Installing OpenDoc${edition === 'headless' ? ' Headless' : ''} ${version}…`);
+    if (dependencies.install) await dependencies.install(stage, version, identity);
+    else {
+      const tarball = options.tarball ?? process.env.OPENDOC_PACKAGE_TARBALL;
+      const args = ['install', '--ignore-scripts', '--no-audit', '--no-fund', ...(tarball ? ['--save-exact', `opendoc@file:${resolve(tarball)}`] : [])];
+      const result = await runProcess('npm', args, stage, { diagnostics: true });
+      if (result.code) throw new Error(`npm install failed (exit ${result.code}).`);
+      // Local release acceptance uses a tarball; keep the public workspace contract exactly pinned.
+      if (tarball) {
+        await writeFile(resolve(stage, 'package.json'), JSON.stringify(manifest, null, 2) + '\n');
+        const lockPath = resolve(stage, 'package-lock.json');
+        const lock = JSON.parse(await readFile(lockPath, 'utf8'));
+        lock.packages[''].dependencies.opendoc = pin;
+        await writeFile(lockPath, JSON.stringify(lock, null, 2) + '\n');
+      }
+    }
+    await installedApplication(stage);
+    if (dependencies.validate) await dependencies.validate(stage);
+    else {
+      const result = await runProcess(process.execPath, [resolve(stage, 'node_modules/opendoc/bin/opendoc.mjs'), 'check', '--json'], stage, { capture: true });
+      if (result.code) throw new Error('The installed workspace did not pass its authoring check.');
+    }
+    await requireEmptyDestination(root);
+    await mkdir(root, { recursive: true });
+    await copyContents(stage, root);
+    await rm(stage, { recursive: true, force: true });
+    return { workspace: root, version, edition };
+  } catch (error) {
+    throw new Error(`${(error as Error).message}\nThe destination was not overwritten. Prepared files remain at ${stage}.\nTo recover, inspect that folder, run npm install there, then npx opendoc check${edition === 'normal' ? ' and npx opendoc start' : ''}. Or retry initialization in a new empty folder.`, { cause: error });
+  }
+}
+
+export async function runInit(args: string[]) {
+  const { edition } = packageIdentity(await packageMetadata());
+  const usage = usageFor(edition);
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { 'no-start': { type: 'boolean' }, 'no-open': { type: 'boolean' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } } });
+  if (values.help) { console.log(values.json ? JSON.stringify({ usage }) : usage); return; }
+  if (positionals.length > 1) throw new Error(usage);
+  let destination = positionals[0];
+  if (!destination) {
+    if (edition === 'headless') throw new Error(`OpenDoc Headless requires an explicit workspace folder: npx --yes ${packageNames.headless} init <folder>`);
+    if (!process.stdin.isTTY) throw new Error(`Provide a workspace folder when input is not interactive: npx --yes ${packageNames.normal} init <folder> --no-start`);
+    const prompt = createInterface({ input: process.stdin, output: process.stderr });
+    try { destination = (await prompt.question('Workspace folder [~/Documents/My OpenDoc]: ')).trim() || resolve(homedir(), 'Documents/My OpenDoc'); }
+    finally { prompt.close(); }
+  }
+  const result = await initializeWorkspace(destination);
+  if (edition === 'headless') console.log(values.json ? JSON.stringify(result) : `Created ${result.workspace}\nRead its AGENTS.md, then author, review, and deliver finished PDF or PowerPoint files with npx opendoc.`);
+  else if (values['no-start']) console.log(values.json ? JSON.stringify(result) : `Created ${result.workspace}\nOpen this folder in your coding agent.\nStart OpenDoc: npx opendoc start ${quote(result.workspace)}`);
+  else {
+    console.error(`Created ${result.workspace}. Open this folder in your coding agent.`);
+    // Launch the installed runtime, including when init came from npm's temporary cache.
+    const child = await runProcess(process.execPath, [resolve(result.workspace, 'node_modules/opendoc/bin/opendoc.mjs'), 'start', ...(values['no-open'] ? ['--no-open'] : []), ...(values.json ? ['--json'] : [])], result.workspace);
+    if (child.code) process.exitCode = child.code;
+  }
+}

package/src/cli/lock.ts

@@ -0,0 +1,34 @@
+import { mkdir, open, readFile, unlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+/** Startup, update activation, and Headless commands share the workspace runtime lock. */
+export async function withWorkspaceLock<T>(root: string, action: () => Promise<T>): Promise<T> {
+  const file = resolve(root, '.opendoc/update.lock');
+  await mkdir(resolve(root, '.opendoc'), { recursive: true });
+  const contents = JSON.stringify({ pid: process.pid, id: randomUUID() });
+  try {
+    const handle = await open(file, 'wx', 0o600);
+    try { await handle.writeFile(contents); } finally { await handle.close(); }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+    const recovery = `Confirm no OpenDoc command is running, then remove ${file} and retry.`;
+    let owner: { pid?: number };
+    try { owner = JSON.parse(await readFile(file, 'utf8')); } catch { throw new Error(`OpenDoc has an incomplete workspace runtime lock. ${recovery}`); }
+    if (!owner || !Number.isSafeInteger(owner.pid) || owner.pid! <= 0 || owner.pid! > 2 ** 31 - 1) throw new Error(`Invalid OpenDoc workspace runtime lock. ${recovery}`);
+    try { process.kill(owner.pid!, 0); }
+    catch (ownerError) {
+      if ((ownerError as NodeJS.ErrnoException).code !== 'ESRCH') throw ownerError;
+      // Stat-then-unlink recovery could delete a new contender's lock. Leave stale locks intact.
+      throw new Error(`The previous OpenDoc command stopped before releasing its lock. ${recovery}`);
+    }
+    throw new Error('Another OpenDoc command is in progress. Wait for it to finish, then retry.');
+  }
+  try { return await action(); }
+  finally {
+    try { if (await readFile(file, 'utf8') === contents) await unlink(file); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') console.error(`OpenDoc could not remove its workspace runtime lock after the operation: ${error instanceof Error ? error.message : String(error)}. Confirm no OpenDoc command is running, then remove ${file} and retry.`);
+    }
+  }
+}

package/src/cli/main.ts

@@ -0,0 +1,118 @@
+import { resolve } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { applicationRoot } from '../runtime/paths';
+import { discoverWorkspace, explicitWorkspace, installedApplication, packageIdentity, packageMetadata, packageNames, type Edition } from './workspace';
+import { runProcess } from './process';
+import { withWorkspaceLock } from './lock';
+import { RenderFailure } from '../server/render-error';
+
+const usageFor = (edition: Edition) => `OpenDoc${edition === 'headless' ? ' Headless — remote document production for agents' : ' — local documents and editable presentations'}
+
+${edition === 'headless'
+    ? `  npx --yes ${packageNames.headless} init <folder>\n                                   Create a workspace without a server`
+    : `  npx --yes ${packageNames.normal} init [folder]\n                                   Create a workspace and open OpenDoc\n  npx opendoc start [folder]         Start its installed runtime`}
+  npx opendoc create <id>            Create a document or presentation
+  npx opendoc projects              Manage projects and membership
+  npx opendoc templates             Inspect, check, and preview templates
+  npx opendoc themes                Inspect, check, and preview themes
+  npx opendoc assets                Manage fonts, logos, and bindings
+  npx opendoc media                 Manage document-owned media
+  npx opendoc comments              Read and resolve feedback
+  npx opendoc export <id...>         Export PDF or editable PowerPoint
+  npx opendoc review <id>            Generate page images, text, and review issues
+  npx opendoc check                 Typecheck workspace authoring
+  npx opendoc update [--check]       Explicitly update the runtime
+
+Commands discover the workspace from this folder or an ancestor.
+Use --workspace <folder> to select one and --json for structured results.
+Use <command> --help for options, or --version for the active version.`;
+
+export function parseGlobalArgs(args: string[]) {
+  const rest: string[] = [];
+  let workspace: string | undefined;
+  let json = false;
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--') { rest.push(...args.slice(index)); break; }
+    if (arg === '--workspace' || arg.startsWith('--workspace=')) {
+      if (workspace !== undefined) throw new Error('Provide --workspace only once.');
+      workspace = arg === '--workspace' ? args[++index] : arg.slice('--workspace='.length);
+      if (!workspace || workspace.startsWith('--')) throw new Error('Provide a folder after --workspace.');
+    } else if (arg === '--json') json = true;
+    else rest.push(arg);
+  }
+  return { args: rest, workspace, json };
+}
+
+export async function main(rawArgs = process.argv.slice(2)) {
+  let json = rawArgs.includes('--json');
+  try {
+    if (Number(process.versions.node.split('.')[0]) < 24) throw new Error('OpenDoc requires Node.js 24 or newer. Install Node.js 24, then retry.');
+    const parsed = parseGlobalArgs(rawArgs);
+    json = parsed.json;
+    const identity = packageIdentity(await packageMetadata());
+    const usage = usageFor(identity.edition);
+    const [command, ...args] = parsed.args;
+    if (!command || ['--help', '-h', 'help'].includes(command)) {
+      console.log(json ? JSON.stringify({ usage }) : usage); return;
+    }
+    if (command === 'init') {
+      if (parsed.workspace) throw new Error('Use init <folder> to choose the new workspace.');
+      const { runInit } = await import('./init');
+      await runInit([...(json ? ['--json'] : []), ...args]); return;
+    }
+    let startFolder: string | undefined;
+    if (command === 'start') {
+      const index = args.findIndex(arg => !arg.startsWith('-'));
+      if (index >= 0) startFolder = args.splice(index, 1)[0];
+      if (startFolder && parsed.workspace) throw new Error('Choose start <folder> or --workspace <folder>, not both.');
+    }
+    const root = parsed.workspace || startFolder
+      ? await explicitWorkspace(parsed.workspace ?? startFolder!)
+      : await discoverWorkspace();
+    if (root) {
+      const active = await installedApplication(root);
+      if (active !== await realpath(applicationRoot)) {
+        const result = await runProcess(process.execPath, [resolve(active, 'bin/opendoc.mjs'), ...rawArgs], process.cwd());
+        if (result.code) process.exitCode = result.code;
+        return;
+      }
+    }
+    if (command === '--version' || command === '-v') {
+      if (args.length) throw new Error('Use --version without other arguments.');
+      const { version } = await packageMetadata();
+      console.log(json ? JSON.stringify({ version }) : version); return;
+    }
+    if (!root) throw new Error(`No OpenDoc workspace found. Run npx --yes ${identity.name} init <folder>, or use --workspace <folder> for an existing workspace.`);
+    const flags = [...(json ? ['--json'] : []), ...args];
+    const dispatch = async () => {
+      switch (command) {
+        case 'start': await (await import('./start')).runStart(flags, root); break;
+        case 'create': await (await import('../server/create-cli')).runCreateCli(flags, root); break;
+        case 'projects': await (await import('../server/projects-cli')).runProjectsCli(flags, root); break;
+        case 'templates': await (await import('../server/templates-cli')).runTemplatesCli(flags, root); break;
+        case 'themes': await (await import('../server/themes-cli')).runThemesCli(flags, root); break;
+        case 'assets': await (await import('../server/assets-cli')).runAssetsCli(flags, root); break;
+        case 'media': await (await import('../server/media-cli')).runMediaCli(flags, root); break;
+        case 'comments': await (await import('../server/comments-cli')).runCommentsCli(flags, root, { mode: identity.edition === 'headless' ? 'direct' : 'auto' }); break;
+        case 'export': await (await import('../server/export')).runExportCli(flags, root, { mode: identity.edition === 'headless' ? 'direct' : 'preview' }); break;
+        case 'review': await (await import('../server/review-cli')).runReviewCli(flags, root); break;
+        case 'update': await (await import('./update')).runUpdate(flags, root); break;
+        case 'check': {
+          if (args.includes('--help') || args.includes('-h')) { const help = 'Usage: npx opendoc check [--json]\nTypechecks workspace documents, themes, and templates.'; console.log(json ? JSON.stringify({ usage: help }) : help); break; }
+          if (args.length) throw new Error('Usage: npx opendoc check [--json]');
+          const { checkWorkspace, validateInstallation } = await import('./check');
+          await validateInstallation(); await checkWorkspace(root, json); break;
+        }
+        default: throw new Error(`Unknown command: ${command}. Use npx opendoc --help.`);
+      }
+    };
+    if (identity.edition === 'headless' && !['update', 'start'].includes(command)) await withWorkspaceLock(root, dispatch);
+    else await dispatch();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    if (json) console.log(JSON.stringify({ error: message, ...(error instanceof RenderFailure ? { issues: error.issues } : {}) }));
+    if (!process.exitCode) process.exitCode = 1;
+  }
+}

package/src/cli/process.ts

@@ -0,0 +1,19 @@
+import { spawn } from 'node:child_process';
+
+export async function runProcess(command: string, args: string[], cwd: string, options: { capture?: boolean; diagnostics?: boolean } = {}) {
+  return await new Promise<{ stdout: string; code: number }>((accept, reject) => {
+    const child = spawn(command, args, { cwd, stdio: ['inherit', options.capture || options.diagnostics ? 'pipe' : 'inherit', 'inherit'] });
+    let stdout = '';
+    let canceled = false;
+    child.stdout?.on('data', chunk => { if (options.capture) stdout += String(chunk); else process.stderr.write(chunk); });
+    const cancel = () => { canceled = true; child.kill('SIGINT'); };
+    process.on('SIGINT', cancel);
+    child.once('error', error => { process.off('SIGINT', cancel); reject(error); });
+    child.once('exit', (code, signal) => {
+      process.off('SIGINT', cancel);
+      if (canceled || signal === 'SIGINT') { process.exitCode = 130; reject(new Error('Operation canceled.')); }
+      else if (signal) reject(new Error(`${command} stopped (${signal}).`));
+      else accept({ stdout, code: code ?? 1 });
+    });
+  });
+}

package/src/cli/start.ts

@@ -0,0 +1,96 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { setTimeout } from 'node:timers/promises';
+import { parseArgs } from 'node:util';
+import { runtimeResolve, runtimeSource } from '../runtime/paths';
+import { packageIdentity, packageMetadata } from './workspace';
+import { withWorkspaceLock } from './lock';
+import { validateInstallation } from './check';
+
+export async function runningSession(root: string): Promise<{ origin: string; pid: number } | null> {
+  let session: { origin: string; token: string; pid: number };
+  try { session = JSON.parse(await readFile(resolve(root, '.opendoc/server.json'), 'utf8')); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null; throw new Error('Cannot read the OpenDoc session. Check .opendoc/server.json before starting another server.'); }
+  if (!/^http:\/\/127\.0\.0\.1:\d+$/.test(session?.origin ?? '') || typeof session.token !== 'string' || !session.token) throw new Error('The OpenDoc session record is invalid. Check .opendoc/server.json before starting another server.');
+  let response;
+  try { response = await fetch(`${session.origin}/api/session`, { signal: AbortSignal.timeout(1500), redirect: 'error' }); }
+  catch (error) {
+    if ((error as { cause?: { code?: string } }).cause?.code === 'ECONNREFUSED') {
+      if (Number.isSafeInteger(session.pid) && session.pid > 0 && session.pid <= 2 ** 31 - 1) {
+        try { process.kill(session.pid, 0); }
+        catch (ownerError) { if ((ownerError as NodeJS.ErrnoException).code === 'ESRCH') return null; throw ownerError; }
+        throw new Error('OpenDoc is still finishing its previous session. Wait for its terminal to stop, then retry.');
+      }
+      return null;
+    }
+    throw new Error('Cannot verify whether OpenDoc is running. Check its terminal before starting another server.');
+  }
+  const live = await response.json().catch(() => null);
+  if (response.ok && live?.token === session.token) return { origin: session.origin, pid: session.pid };
+  throw new Error('The recorded OpenDoc session no longer matches the server at its address. Stop the previous server and remove the stale .opendoc/server.json before retrying.');
+}
+
+async function openBrowser(origin: string) {
+  const command = process.platform === 'darwin' ? 'open' : 'xdg-open';
+  await new Promise<void>(accept => {
+    const child = spawn(command, [origin], { stdio: 'ignore' });
+    child.once('error', () => { console.error(`Open ${origin} in your browser.`); accept(); });
+    child.once('exit', code => { if (code) console.error(`Open ${origin} in your browser.`); accept(); });
+  });
+}
+
+export async function runStart(args: string[], root: string) {
+  if (packageIdentity(await packageMetadata()).edition === 'headless') throw new Error('OpenDoc Headless has no browser service. Use npx opendoc create, review, and export to produce files, then deliver the PDF or PowerPoint directly.');
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { 'no-open': { type: 'boolean' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } } });
+  const usage = 'Usage: npx opendoc start [folder] [--no-open] [--json]\nRuns the installed workspace version. Ctrl+C stops the server.';
+  if (values.help) { console.log(values.json ? JSON.stringify({ usage }) : usage); return; }
+  if (positionals.length) throw new Error(usage);
+  let child: ChildProcess | undefined;
+  let exited: Promise<{ code: number | null; signal: NodeJS.Signals | null }> | undefined;
+  let stopped: { code: number | null; signal: NodeJS.Signals | null } | undefined;
+  let startupFailure: Error | undefined;
+  const forwardInterrupt = () => child?.kill('SIGINT');
+  const forwardTerminate = () => child?.kill('SIGTERM');
+  process.on('SIGINT', forwardInterrupt);
+  process.on('SIGTERM', forwardTerminate);
+  try {
+    const ready = await withWorkspaceLock(root, async () => {
+      const existing = await runningSession(root);
+      if (existing) return { ...existing, reused: true };
+      await validateInstallation();
+      child = spawn(process.execPath, ['--import', runtimeResolve('tsx'), runtimeSource('server/index.ts'), '--production'], { cwd: root, stdio: ['inherit', values.json ? 'pipe' : 'inherit', 'inherit'] });
+      if (values.json) child.stdout?.on('data', data => process.stderr.write(data));
+      exited = new Promise((accept, reject) => {
+        child!.once('error', error => { startupFailure = error; reject(error); });
+        child!.once('exit', (code, signal) => { stopped = { code, signal }; accept(stopped); });
+      });
+      // Attach a handler immediately so a spawn error cannot become an unhandled rejection.
+      void exited.catch(() => {});
+      const deadline = Date.now() + 30_000;
+      while (Date.now() < deadline) {
+        if (startupFailure) throw startupFailure;
+        if (stopped) throw new Error(`OpenDoc stopped during startup (${stopped.signal ?? stopped.code}).`);
+        const session = await runningSession(root);
+        if (session && child.pid && session.pid === child.pid) return { ...session, reused: false };
+        await setTimeout(100);
+      }
+      throw new Error('OpenDoc did not become ready within 30 seconds. See its terminal output.');
+    });
+    const { version } = await packageMetadata();
+    if (values.json) console.log(JSON.stringify({ workspace: root, version, origin: ready.origin, reused: ready.reused }));
+    else if (ready.reused) console.log(`OpenDoc is already running at ${ready.origin}`);
+    if (!values['no-open']) await openBrowser(ready.origin);
+    if (exited) {
+      const result = await exited;
+      if (result.code) process.exitCode = result.code;
+      else if (result.signal && !['SIGINT', 'SIGTERM'].includes(result.signal)) process.exitCode = 1;
+    }
+  } catch (error) {
+    child?.kill('SIGTERM');
+    throw error;
+  } finally {
+    process.off('SIGINT', forwardInterrupt);
+    process.off('SIGTERM', forwardTerminate);
+  }
+}