@ryanyahya/opendoc-headless 0.4.0

package/src/server/assets-cli.ts

@@ -0,0 +1,162 @@
+import { readFile, stat } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { AssetStore } from '../assets/store';
+import type { UploadFile } from '../assets/imports';
+import type { AssetKind, ThemeAssetDefaults } from '../shared/assets';
+
+const usage = `Usage: npx opendoc assets list [logo|font] [--archived]
+       npx opendoc assets inspect <logo|font> <id> [--revision <revision>]
+       npx opendoc assets import logo --file <svg-or-png> --name "Name" [--id <id>] [--description "Guidance"] [--variation-name "Name"] [--variation-description "When to use"]
+       npx opendoc assets import font --file <ttf-or-otf> [--file <another-face> ...] [--id <id>] [--name "Name"] [--description "Guidance"]
+       npx opendoc assets revise <logo|font> <id> --metadata <json-file>
+       npx opendoc assets add-variation <logo-id> --file <svg-or-png> --name "Name" --expected-revision <revision> [--id <variation-id>] [--description "When to use"] [--replace <variation-id>]
+       npx opendoc assets add-faces <font-id> --file <ttf-or-otf> [--file <another-face> ...] --expected-revision <revision>
+       npx opendoc assets archive <logo|font> <id> --expected-revision <revision> [--clear-defaults]
+       npx opendoc assets restore <logo|font> <id> --expected-revision <revision>
+       npx opendoc assets defaults <theme-id> [--metadata <json-file> --expected-revision <revision>]
+       npx opendoc assets bind <document-id> <logo|body-font|heading-font> <asset-id> [--revision <revision>] [--variation <variation-id>] [--name <logo-binding>]
+       npx opendoc assets unbind <document-id> <logo|body-font|heading-font> [--name <logo-binding>]
+
+Successful commands print JSON. Inspect before editing: revisions prevent overwriting another writer.
+revise metadata requires expectedRevision plus the fields to change. defaults metadata is the complete ThemeAssetDefaults object.
+Binding saves an exact version now; changing a theme default affects only new documents.
+See docs/ASSETS.md for file contracts and authoring examples.`;
+
+function kind(value: string | undefined): AssetKind {
+  if (value !== 'logo' && value !== 'font') throw new Error('Choose asset kind logo or font.\n' + usage);
+  return value;
+}
+
+function role(value: string | undefined): 'logo' | 'body-font' | 'heading-font' {
+  if (value !== 'logo' && value !== 'body-font' && value !== 'heading-font') throw new Error('Choose document role logo, body-font, or heading-font.\n' + usage);
+  return value;
+}
+
+async function localFile(file: string): Promise<UploadFile> {
+  const path = resolve(file);
+  const info = await stat(path);
+  if (!info.isFile()) throw new Error(`Choose a regular local file: ${file}`);
+  if (!info.size || info.size > 100 * 1024 * 1024) throw new Error('Choose a nonempty asset file no larger than 100 MB.');
+  const bytes = await readFile(path);
+  if (!bytes.length || bytes.length > 100 * 1024 * 1024) throw new Error('Choose a nonempty asset file no larger than 100 MB.');
+  return { filename: basename(path), bytes };
+}
+
+async function metadata(file: string) {
+  const path = resolve(file);
+  const info = await stat(path);
+  if (!info.isFile() || info.size > 256_000) throw new Error('Choose a regular JSON metadata file no larger than 256 KB.');
+  const bytes = await readFile(path);
+  if (bytes.length > 256_000) throw new Error('Asset metadata must be no larger than 256 KB.');
+  const data: unknown = JSON.parse(bytes.toString('utf8'));
+  if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('Asset metadata must be a JSON object.');
+  return data as Record<string, unknown>;
+}
+
+/** The CLI and HTTP routes deliberately delegate all asset rules to the same store. */
+export async function runAssetsCli(args: string[], root = process.cwd()) {
+  const { values, positionals } = parseArgs({
+    args: args[0] === '--' ? args.slice(1) : args, allowPositionals: true,
+    options: {
+      help: { type: 'boolean', short: 'h' }, json: { type: 'boolean' }, archived: { type: 'boolean' },
+      file: { type: 'string', multiple: true }, name: { type: 'string' }, id: { type: 'string' },
+      description: { type: 'string' }, 'variation-name': { type: 'string' }, 'variation-description': { type: 'string' },
+      revision: { type: 'string' }, 'expected-revision': { type: 'string' }, metadata: { type: 'string' },
+      variation: { type: 'string' }, replace: { type: 'string' }, 'clear-defaults': { type: 'boolean' },
+    },
+  });
+  if (values.help) { console.log(values.json ? JSON.stringify({ usage }, null, 2) : usage); return; }
+  const [command = 'list', first, second, third] = positionals;
+  const store = new AssetStore(root);
+  const shape = (count: number | number[], flags: string[]) => {
+    if (!(Array.isArray(count) ? count : [count]).includes(positionals.length)) throw new Error(usage);
+    const unexpected = Object.keys(values).filter(key => !['json', ...flags].includes(key));
+    if (unexpected.length) throw new Error(`Option --${unexpected[0]} is not used by ${command}.\n${usage}`);
+  };
+  const required = (value: string | undefined, name: string) => {
+    if (!value?.trim()) throw new Error(`Provide --${name}.\n${usage}`);
+    return value;
+  };
+  const expected = () => required(values['expected-revision'], 'expected-revision');
+  const files = async (single = false) => {
+    if (!values.file?.length || (single && values.file.length !== 1)) throw new Error(`Provide ${single ? 'exactly one --file' : 'at least one --file'}.\n${usage}`);
+    if (values.file.length > 24) throw new Error('Import at most 24 font faces together.');
+    const uploads: UploadFile[] = [];
+    let total = 0;
+    for (const path of values.file) {
+      const upload = await localFile(path);
+      total += upload.bytes.byteLength;
+      if (total > 100 * 1024 * 1024) throw new Error('A font import must be 100 MB or smaller.');
+      uploads.push(upload);
+    }
+    return uploads;
+  };
+  let result: unknown;
+  switch (command) {
+    case 'list':
+      shape([0, 1, 2], ['archived']);
+      result = await store.list(first === undefined ? undefined : kind(first), values.archived ?? false);
+      break;
+    case 'inspect':
+      shape(3, ['revision']);
+      result = await store.inspect(kind(first), second, values.revision);
+      break;
+    case 'import': {
+      const assetKind = kind(first);
+      shape(2, ['file', 'id', 'name', 'description', ...(assetKind === 'logo' ? ['variation-name', 'variation-description'] : [])]);
+      result = assetKind === 'logo'
+        ? await store.createLogo({ id: values.id, name: required(values.name, 'name'), description: values.description, variationName: values['variation-name'], variationDescription: values['variation-description'] }, (await files(true))[0])
+        : await store.createFont({ id: values.id, name: values.name, description: values.description }, await files());
+      break;
+    }
+    case 'revise': {
+      shape(3, ['metadata']);
+      const input = await metadata(required(values.metadata, 'metadata'));
+      if (typeof input.expectedRevision !== 'string' || !input.expectedRevision) throw new Error('Revision metadata needs expectedRevision from the latest inspection.');
+      result = await store.revise(kind(first), second, input as Parameters<AssetStore['revise']>[2]);
+      break;
+    }
+    case 'add-variation':
+      shape(2, ['file', 'name', 'id', 'description', 'expected-revision', 'replace']);
+      result = await store.addVariation(first, { expectedRevision: expected(), id: values.id, name: required(values.name, 'name'), description: values.description, replaceId: values.replace }, (await files(true))[0]);
+      break;
+    case 'add-faces':
+      shape(2, ['file', 'expected-revision']);
+      result = await store.addFaces(first, { expectedRevision: expected() }, await files());
+      break;
+    case 'archive':
+      shape(3, ['expected-revision', 'clear-defaults']);
+      result = await store.archive(kind(first), second, expected(), values['clear-defaults'] ?? false);
+      break;
+    case 'restore':
+      shape(3, ['expected-revision']);
+      result = await store.restore(kind(first), second, expected());
+      break;
+    case 'defaults':
+      shape(2, values.metadata ? ['metadata', 'expected-revision'] : []);
+      result = values.metadata
+        ? await store.setDefaults(first, await metadata(values.metadata) as unknown as ThemeAssetDefaults, expected())
+        : await store.defaults(first);
+      break;
+    case 'bind': {
+      const documentRole = role(second);
+      shape(4, ['revision', ...(documentRole === 'logo' ? ['variation', 'name'] : [])]);
+      result = await store.bind(first, documentRole, third, { revision: values.revision, variation: values.variation, name: values.name });
+      break;
+    }
+    case 'unbind': {
+      const documentRole = role(second);
+      shape(3, documentRole === 'logo' ? ['name'] : []);
+      result = await store.unbind(first, documentRole, values.name);
+      break;
+    }
+    default: throw new Error(usage);
+  }
+  console.log(JSON.stringify(result, null, 2));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  runAssetsCli(process.argv.slice(2)).catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });
+}

package/src/server/assets-http.ts

@@ -0,0 +1,100 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { AssetStore } from '../assets/store';
+import { AssetError, assertKind, assetFile, readAssetRevision, revisionFiles } from '../assets/files';
+import type { UploadFile } from '../assets/imports';
+import { importMedia, editMedia } from './media-mutations';
+import { themeFile } from './themes';
+
+type Send = (res: ServerResponse, value: unknown, status?: number) => void;
+type Body = (req: IncomingMessage, limit?: number) => Promise<any>;
+function object(value: unknown, fields: string[]): asserts value is Record<string, any> {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !fields.includes(key))) throw new AssetError('Invalid asset request. Reload the form and try again.');
+}
+/** Use the platform multipart parser, with a byte bound before parsing or publication. */
+export async function assetUpload(req: IncomingMessage, multiple = false): Promise<{ metadata: Record<string, any>; files: UploadFile[] }> {
+  const type = req.headers['content-type'];
+  if (!type?.startsWith('multipart/form-data;')) throw new AssetError('Choose files using a multipart upload.');
+  const chunks: Buffer[] = []; let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > 100 * 1024 * 1024) throw new AssetError('Keep the complete upload below 100 MB.', 413);
+    chunks.push(Buffer.from(chunk));
+  }
+  let form: FormData;
+  try { form = await new Response(new Uint8Array(Buffer.concat(chunks)), { headers: { 'Content-Type': type } }).formData(); }
+  catch { throw new AssetError('The upload was interrupted or malformed. Choose the files and try again.'); }
+  if ([...form.keys()].some(key => !['metadata', multiple ? 'files' : 'file'].includes(key)) || form.getAll('metadata').length !== 1) throw new AssetError('Include one metadata record and the chosen files.');
+  let metadata: unknown;
+  const raw = form.get('metadata');
+  if (typeof raw !== 'string' || raw.length > 32_000) throw new AssetError('The upload metadata is too large or missing.');
+  try { metadata = JSON.parse(raw); } catch { throw new AssetError('The upload metadata must be valid JSON.'); }
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) throw new AssetError('Include an upload metadata object.');
+  const entries = form.getAll(multiple ? 'files' : 'file');
+  if (!entries.length || entries.length > (multiple ? 24 : 1) || entries.some(entry => typeof entry === 'string')) throw new AssetError(multiple ? 'Choose between one and 24 static font files.' : 'Choose one image file.');
+  const files = await Promise.all((entries as File[]).map(async file => ({ filename: file.name, bytes: new Uint8Array(await file.arrayBuffer()) })));
+  return { metadata: metadata as Record<string, any>, files };
+}
+
+/** Called after the server's local-session write guard. App and CLI share AssetStore. */
+export async function handleAssetRequest(root: string, store: AssetStore, req: IncomingMessage, res: ServerResponse, url: URL, json: Send, body: Body, changed: () => void): Promise<boolean> {
+  if (url.pathname === '/api/assets' && req.method === 'GET') {
+    const kind = url.searchParams.get('kind') ?? undefined; if (kind) assertKind(kind);
+    json(res, await store.list(kind as 'logo' | 'font' | undefined, url.searchParams.get('archived') === 'true')); return true;
+  }
+  const defaults = url.pathname.match(/^\/api\/themes\/([a-z0-9-]+)\/assets$/);
+  if (defaults) {
+    await themeFile(root, defaults[1], 'index.ts');
+    if (req.method === 'GET') { json(res, await store.defaults(defaults[1])); return true; }
+    if (req.method === 'PUT') { const input = await body(req); object(input, ['defaults', 'expectedRevision']); json(res, await store.setDefaults(defaults[1], input.defaults, input.expectedRevision)); changed(); return true; }
+  }
+  const media = url.pathname.match(/^\/api\/materials\/([a-z0-9-]+)\/(import|meta)$/);
+  if (media?.[2] === 'import' && req.method === 'POST') {
+    const upload = await assetUpload(req); object(upload.metadata, ['id', 'title', 'description', 'kind', 'alt', 'attribution', 'sources']);
+    json(res, await importMedia(root, media[1], upload.metadata as Parameters<typeof importMedia>[2], upload.files[0]), 201); changed(); return true;
+  }
+  if (media?.[2] === 'meta' && req.method === 'PATCH') {
+    const input = await body(req); object(input, ['expectedRevision', 'meta']);
+    json(res, await editMedia(root, media[1], url.searchParams.get('item') ?? '', input as Parameters<typeof editMedia>[3])); changed(); return true;
+  }
+  const route = url.pathname.match(/^\/api\/assets\/(logo|font)(?:\/([a-z0-9-]+)(?:\/(file|variations|faces|archive|restore))?)?$/);
+  if (!route) return false;
+  const [, kindValue, id, action] = route; assertKind(kindValue); const kind = kindValue;
+  if (!id && req.method === 'POST') {
+    const { metadata, files } = await assetUpload(req, kind === 'font');
+    object(metadata, kind === 'logo' ? ['id', 'name', 'description', 'variationName', 'variationDescription'] : ['id', 'name', 'description']);
+    const result = kind === 'logo' ? await store.createLogo(metadata as Parameters<AssetStore['createLogo']>[0], files[0]) : await store.createFont(metadata, files);
+    json(res, result, 201); changed(); return true;
+  }
+  if (!id) throw new AssetError('Asset not found.', 404);
+  if (req.method === 'GET' && !action) { json(res, await store.inspect(kind, id, url.searchParams.get('revision') ?? undefined)); return true; }
+  if (req.method === 'GET' && action === 'file') {
+    const revision = url.searchParams.get('revision'); if (!revision) throw new AssetError('Choose the saved version for this asset file.');
+    const asset = readAssetRevision(root, kind, id, revision);
+    const file = revisionFiles(asset).find(file => file.file === url.searchParams.get('file'));
+    if (!file) throw new AssetError('This file is not part of the chosen asset version.', 404);
+    const bytes = await readFile(assetFile(root, kind, id, file));
+    const extension = file.file.split('.').at(-1)!;
+    const mime = ({ png: 'image/png', svg: 'image/svg+xml', ttf: 'font/ttf', otf: 'font/otf', pdf: 'application/pdf' } as Record<string, string>)[extension];
+    res.writeHead(200, { 'Content-Type': mime, 'Content-Length': bytes.length, 'Content-Disposition': `${extension === 'svg' ? 'attachment' : 'inline'}; filename="${id}.${extension}"`, 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', ...(extension === 'svg' ? { 'Content-Security-Policy': "default-src 'none'; sandbox" } : {}) });
+    res.end(bytes); return true;
+  }
+  if (req.method === 'PATCH' && !action) {
+    const input = await body(req); object(input, ['expectedRevision', 'name', 'description', 'defaultVariation', 'variation', 'removeVariation', 'removeFace']);
+    json(res, await store.revise(kind, id, input as Parameters<AssetStore['revise']>[2])); changed(); return true;
+  }
+  if (req.method === 'POST' && (action === 'archive' || action === 'restore')) {
+    const input = await body(req); object(input, action === 'archive' ? ['expectedRevision', 'clearDefaults'] : ['expectedRevision']);
+    if (input.clearDefaults !== undefined && typeof input.clearDefaults !== 'boolean') throw new AssetError('Confirm whether theme defaults should be cleared.');
+    json(res, action === 'archive' ? await store.archive(kind, id, input.expectedRevision, input.clearDefaults) : await store.restore(kind, id, input.expectedRevision)); changed(); return true;
+  }
+  if (req.method === 'POST' && kind === 'logo' && action === 'variations') {
+    const { metadata, files } = await assetUpload(req); object(metadata, ['expectedRevision', 'id', 'name', 'description', 'replaceId']);
+    json(res, await store.addVariation(id, metadata as Parameters<AssetStore['addVariation']>[1], files[0])); changed(); return true;
+  }
+  if (req.method === 'POST' && kind === 'font' && action === 'faces') {
+    const { metadata, files } = await assetUpload(req, true); object(metadata, ['expectedRevision']);
+    json(res, await store.addFaces(id, metadata as Parameters<AssetStore['addFaces']>[1], files)); changed(); return true;
+  }
+  throw new AssetError('Asset action not found.', 404);
+}

package/src/server/client.ts

@@ -0,0 +1,50 @@
+import { createReadStream, existsSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { extname, relative, resolve, sep } from 'node:path';
+import { containedFile } from './files';
+
+const contentTypes: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp',
+  '.ico': 'image/x-icon', '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.otf': 'font/otf', '.wasm': 'application/wasm', '.json': 'application/json',
+};
+
+/** Production serves only the built browser app; authoring and PDF APIs stay live. */
+export async function builtClient(root: string) {
+  const directory = resolve(root, 'dist');
+  const repair = existsSync(resolve(root, 'vite.config.ts')) ? 'Run pnpm build, then pnpm start.' : 'Run npm ci in your workspace, then npx opendoc start.';
+  try { await readFile(await containedFile(directory, resolve(directory, 'index.html'))); }
+  catch { throw new Error(`The built OpenDoc app is missing. ${repair}`); }
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    const fail = (status: number, message: string) => {
+      res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store' });
+      res.end(req.method === 'HEAD' ? undefined : message);
+    };
+    if (req.method !== 'GET' && req.method !== 'HEAD') { fail(405, 'Method not allowed.'); return; }
+    let path: string;
+    try { path = decodeURIComponent(new URL(req.url ?? '/', 'http://localhost').pathname); }
+    catch { fail(400, 'Invalid local path.'); return; }
+    if (path.includes('\\') || path.includes('\0') || path.split('/').some(part => part.startsWith('.'))) { fail(404, 'Not found.'); return; }
+    const file = resolve(directory, `.${path === '/' ? '/index.html' : path}`);
+    const local = relative(directory, file);
+    if (local === '..' || local.startsWith(`..${sep}`)) { fail(404, 'Not found.'); return; }
+    try {
+      const actual = await containedFile(directory, file);
+      const info = await stat(actual);
+      if (!info.isFile()) { fail(404, 'Not found.'); return; }
+      res.writeHead(200, {
+        'Content-Type': contentTypes[extname(actual)] ?? 'application/octet-stream', 'Content-Length': info.size,
+        'Cache-Control': path.startsWith('/assets/') ? 'public, max-age=31536000, immutable' : 'no-cache',
+        'X-Content-Type-Options': 'nosniff',
+      });
+      if (req.method === 'HEAD') { res.end(); return; }
+      const stream = createReadStream(actual);
+      stream.on('error', () => res.destroy());
+      stream.pipe(res);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT' || (error instanceof Error && error.message === 'Path is outside the workspace.')) fail(404, 'Not found.');
+      else fail(500, `This app file could not be read. ${repair}`);
+    }
+  };
+}

package/src/server/clipboard.ts

@@ -0,0 +1,22 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+export const canCopyFile = process.platform === 'darwin';
+
+// Pass paths as arguments, never as executable script text. A named pasteboard
+// lets native integration checks exercise this without changing the user's clipboard.
+export async function copyFileToClipboard(path: string, pasteboardName?: string) {
+  if (!canCopyFile) throw new Error('Copying files to the clipboard is currently available on macOS. Use Download a copy instead.');
+  const script = `ObjC.import('AppKit');
+function run(argv) {
+  var url = $.NSURL.fileURLWithPath($(argv[0]));
+  var board = argv.length > 1 ? $.NSPasteboard.pasteboardWithName($(argv[1])) : $.NSPasteboard.generalPasteboard;
+  board.clearContents;
+  if (!board.writeObjects($.NSArray.arrayWithObject(url)) || ObjC.unwrap(board.stringForType('public.file-url')) !== ObjC.unwrap(url.absoluteString)) throw new Error('The clipboard could not accept this file.');
+}`;
+  try {
+    await promisify(execFile)('/usr/bin/osascript', ['-l', 'JavaScript', '-e', script, path, ...(pasteboardName ? [pasteboardName] : [])], { timeout: 10_000 });
+  } catch {
+    throw new Error('The file could not be copied to the clipboard. Try again or use Download a copy.');
+  }
+}

package/src/server/comments-cli.ts

@@ -0,0 +1,64 @@
+import { readComments, changeComment, addComment } from './comments';
+import { readJSON } from './files';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { rm } from 'node:fs/promises';
+import { renderOnce, validId } from './render';
+import { captureExportInputs } from './export-inputs';
+import { getBlock, type DocumentState } from '../shared/types';
+
+const usage = 'Usage: npx opendoc comments list <doc> [--json]\n       npx opendoc comments resolve <doc> <comment-id> [--json]\n       npx opendoc comments reopen <doc> <comment-id> [--json]\n       npx opendoc comments add <doc> <block-id> "text" [--json]';
+
+async function request<T>(origin: string, path: string, init?: RequestInit): Promise<T> {
+  let response: Response;
+  try { response = await fetch(`${origin}${path}`, { ...init, signal: AbortSignal.timeout(5_000) }); }
+  catch { throw new Error('OpenDoc is unavailable. Start or restart it before adding a comment.'); }
+  const result = await response.json();
+  if (!response.ok) throw new Error(result.error ?? 'OpenDoc could not save this comment.');
+  return result as T;
+}
+
+export async function runCommentsCli(args: string[], root = process.cwd(), options: { mode?: 'auto' | 'direct' } = {}): Promise<void> {
+  const { values, positionals } = parseArgs({ args: args[0] === '--' ? args.slice(1) : args, allowPositionals: true, options: {
+    json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+  } });
+  if (values.help) { console.log(values.json ? JSON.stringify({ usage }, null, 2) : usage); return; }
+  const [action, doc, target, ...words] = positionals;
+  if (!doc || !validId(doc)) throw new Error(usage);
+  else if (action === 'list' && positionals.length === 2) console.log(JSON.stringify(await readComments(root, doc), null, 2));
+  else if ((action === 'resolve' || action === 'reopen') && target && positionals.length === 3) {
+    const comment = (await readComments(root, doc)).find(c => c.id === target);
+    if (!comment) throw new Error('Comment not found.');
+    const comments = await changeComment(root, doc, target, action === 'resolve' ? 'resolved' : 'open', comment.version);
+    console.log(values.json ? JSON.stringify(comments.find(c => c.id === target), null, 2) : `${action === 'resolve' ? 'Resolved' : 'Reopened'} ${target}`);
+  } else if (action === 'add' && target && words.length) {
+    if (options.mode === 'direct') {
+      const unchanged = await captureExportInputs(root, doc);
+      const rendered = await renderOnce(root, doc);
+      try {
+        const block = getBlock(rendered.artifact, target);
+        if (!block) throw new Error('The target block does not exist in the current document. Inspect its review output to find the block ID.');
+        const comments = await addComment(root, doc, { blockId: target, text: words.join(' '), quote: block.text }, unchanged);
+        console.log(values.json ? JSON.stringify(comments, null, 2) : `Added comment on ${target}`);
+      } finally { await rm(rendered.directory, { recursive: true, force: true }); }
+      return;
+    }
+    const server = await readJSON<{ origin: string; token: string } | null>(resolve(root, '.opendoc/server.json'), null);
+    if (!server) throw new Error('Start OpenDoc before adding a comment, so the target can be verified.');
+    if (typeof server.origin !== 'string' || !/^http:\/\/127\.0\.0\.1:\d+$/.test(server.origin) || typeof server.token !== 'string' || !server.token) throw new Error('The local OpenDoc session file is invalid. Restart OpenDoc before adding a comment.');
+    const docs = await request<DocumentState[]>(server.origin, '/api/documents');
+    const state = docs.find(d => d.id === doc);
+    const block = getBlock(state?.artifact, target);
+    if (state?.status !== 'ready' || !block) throw new Error('Target is unavailable or still rendering.');
+    const comments = await request(server.origin, `/api/documents/${doc}/comments`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json', Origin: server.origin, 'X-OpenDoc-Token': server.token },
+      body: JSON.stringify({ blockId: target, text: words.join(' '), hash: state.artifact!.hash }),
+    });
+    console.log(values.json ? JSON.stringify(comments, null, 2) : `Added comment on ${target}`);
+  } else throw new Error(`Unknown comments command or missing arguments.\n${usage}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  runCommentsCli(process.argv.slice(2)).catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });
+}

package/src/server/comments.ts

@@ -0,0 +1,130 @@
+import { mkdir, rm } from 'node:fs/promises';
+import { lstatSync, readFileSync, rmSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { atomicWrite, readJSON, containedFile } from './files';
+import { documentEntry } from './render';
+import type { Comment } from '../shared/types';
+import type { TextAnchor } from '../shared/selection';
+
+export class Conflict extends Error {}
+const validDate = (value: unknown): value is string => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const nonempty = (value: unknown): value is string => typeof value === 'string' && value.length > 0;
+
+function validAnchor(anchor: unknown): anchor is TextAnchor {
+  if (!anchor || typeof anchor !== 'object') return false;
+  const value = anchor as TextAnchor;
+  return typeof value.targetId === 'string' && value.targetId.length > 0 && value.targetId.length <= 1000
+    && Number.isInteger(value.start) && Number.isInteger(value.end) && value.start >= 0 && value.end > value.start
+    && typeof value.quote === 'string' && value.quote.length > 0 && value.quote.length <= 8000
+    && value.end - value.start === value.quote.length
+    && typeof value.prefix === 'string' && value.prefix.length <= 40
+    && typeof value.suffix === 'string' && value.suffix.length <= 40;
+}
+export async function readComments(root: string, id: string): Promise<Comment[]> {
+  const entry = await documentEntry(root, id);
+  const file = resolve(dirname(entry), 'comments.json');
+  try { await containedFile(dirname(entry), file); } catch (e) { if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e; }
+  const rows = await readJSON<unknown>(file, []);
+  if (!Array.isArray(rows) || new Set(rows.map(row => row?.id)).size !== rows.length || rows.some(row => !row
+    || !nonempty(row.id) || !nonempty(row.blockId) || !nonempty(row.text) || typeof row.quote !== 'string'
+    || !['open', 'resolved', 'deleted'].includes(row.status) || !Number.isInteger(row.version) || row.version < 1
+    || !validDate(row.createdAt) || !validDate(row.updatedAt) || !Array.isArray(row.history) || !row.history.length
+    || row.history.some((event: Comment['history'][number]) => !event || !validDate(event.at)
+      || !['created', 'resolved', 'reopened', 'edited', 'deleted'].includes(event.action)
+      || (event.previousText !== undefined && typeof event.previousText !== 'string'))
+    || (row.anchor !== undefined && !validAnchor(row.anchor)))) throw new Error(`Invalid comments file for ${id}. Restore valid JSON; existing feedback has not been overwritten.`);
+  return rows as Comment[];
+}
+
+/** A crash before owner publication must not permanently strand a document. */
+function removeAbandonedLock(lock: string) {
+  try {
+    const before = lstatSync(lock);
+    let pid: number | undefined;
+    try { pid = JSON.parse(readFileSync(resolve(lock, 'owner.json'), 'utf8')).pid; } catch { /* An interrupted acquisition may have no owner yet. */ }
+    if (Number.isSafeInteger(pid) && pid! > 0) {
+      try { process.kill(pid!, 0); return; } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ESRCH') return;
+      }
+    } else if (Date.now() - before.mtimeMs < 30_000) return;
+    const current = lstatSync(lock);
+    if (current.dev === before.dev && current.ino === before.ino && current.mtimeMs === before.mtimeMs) rmSync(lock, { recursive: true, force: true });
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+}
+
+export async function withCommentLock<T>(root: string, id: string, operation: () => Promise<T>) {
+  const lock = resolve(root, '.opendoc/locks', `${id}.lock`);
+  await mkdir(dirname(lock), { recursive: true });
+  let acquired = false;
+  for (let attempt = 0; attempt < 80; attempt++) {
+    try {
+      await mkdir(lock); acquired = true;
+      await atomicWrite(resolve(lock, 'owner.json'), JSON.stringify({ pid: process.pid }));
+      break;
+    } catch (e) {
+      if (acquired) { await rm(lock, { recursive: true, force: true }); throw e; }
+      if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e;
+      removeAbandonedLock(lock);
+      await new Promise(r => setTimeout(r, 25));
+    }
+  }
+  if (!acquired) throw new Conflict('Feedback is being updated. Retry in a moment.');
+  try {
+    return await operation();
+  } finally { await rm(lock, { recursive: true, force: true }); }
+}
+
+async function mutate(root: string, id: string, fn: (rows: Comment[]) => Comment[], unchanged?: () => boolean) {
+  await documentEntry(root, id);
+  return withCommentLock(root, id, async () => {
+    const entry = await documentEntry(root, id);
+    const updated = fn(await readComments(root, id));
+    if (unchanged && !unchanged()) throw new Conflict('The document changed while verifying the comment target. Retry against the current source.');
+    await atomicWrite(resolve(dirname(entry), 'comments.json'), JSON.stringify(updated, null, 2) + '\n');
+    return updated;
+  });
+}
+
+export async function addComment(root: string, id: string, input: { blockId: string; text: string; quote: string; anchor?: TextAnchor; exactQuote?: boolean }, unchanged?: () => boolean) {
+  if (typeof input.text !== 'string' || !input.text.trim() || input.text.length > 8000) throw new Error('Write a comment between 1 and 8,000 characters.');
+  if (typeof input.blockId !== 'string' || !input.blockId) throw new Error('Select a document element first.');
+  if (typeof input.quote !== 'string') throw new Error('Select the document element again before commenting.');
+  if (input.anchor !== undefined && !validAnchor(input.anchor)) throw new Error('Select the phrase again before commenting.');
+  const at = new Date().toISOString();
+  return mutate(root, id, rows => [...rows, { id: randomUUID(), blockId: input.blockId, text: input.text.trim(), quote: input.anchor?.quote ?? input.quote.slice(0, input.exactQuote ? 8000 : 500), ...(input.anchor ? { anchor: input.anchor } : {}), status: 'open', createdAt: at, updatedAt: at, version: 1, history: [{ at, action: 'created' }] }], unchanged);
+}
+
+/** Every mutation checks the same current record before appending its history. */
+async function updateComment(root: string, documentId: string, commentId: string, version: number, update: (comment: Comment, at: string) => Partial<Comment> | undefined) {
+  return mutate(root, documentId, rows => {
+    const comment = rows.find(row => row.id === commentId);
+    if (!comment) throw new Error('Comment not found.');
+    if (comment.status === 'deleted' || comment.version !== version) throw new Conflict('This comment changed elsewhere. Refresh and try again.');
+    const at = new Date().toISOString();
+    const changes = update(comment, at);
+    if (!changes) return rows;
+    return rows.map(row => row === comment ? { ...row, ...changes, version: row.version + 1, updatedAt: at } : row);
+  });
+}
+
+export async function changeComment(root: string, documentId: string, commentId: string, status: 'open' | 'resolved', version: number) {
+  if (!['open', 'resolved'].includes(status)) throw new Error('Invalid comment status.');
+  return updateComment(root, documentId, commentId, version, (comment, at) => {
+    if (comment.status === status) return undefined;
+    return { status, history: [...comment.history, { at, action: status === 'resolved' ? 'resolved' : 'reopened' }] };
+  });
+}
+
+export async function editComment(root: string, documentId: string, commentId: string, text: string, version: number) {
+  if (typeof text !== 'string' || !text.trim() || text.length > 8000) throw new Error('Write a comment between 1 and 8,000 characters.');
+  return updateComment(root, documentId, commentId, version, (comment, at) => {
+    if (comment.text === text.trim()) return undefined;
+    return { text: text.trim(), history: [...comment.history, { at, action: 'edited', previousText: comment.text }] };
+  });
+}
+
+/** Keep the local audit history while removing deleted feedback from the app. */
+export async function deleteComment(root: string, documentId: string, commentId: string, version: number) {
+  return updateComment(root, documentId, commentId, version, (comment, at) => ({ status: 'deleted', history: [...comment.history, { at, action: 'deleted' }] }));
+}

package/src/server/create-cli.ts

@@ -0,0 +1,33 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { createDocument, CreateDocumentError, listStarters } from './create';
+import { createFromTemplate } from './templates';
+
+const invalid = (message: string) => new CreateDocumentError(message, 'INVALID_INPUT', 400);
+const usage = 'Usage: npx opendoc create [<id>] --project <project-id> --title "Document title" [--theme <theme-id>] [--format document|presentation]\n       Add --template <template-id> for a reusable template or --starter <starter> for an example draft.\n       npx opendoc create --list [--json]';
+
+export async function runCreateCli(args: string[], root = process.cwd()): Promise<void> {
+  const { values, positionals } = parseArgs({ args: args[0] === '--' ? args.slice(1) : args, allowPositionals: true, options: {
+    format: { type: 'string' }, starter: { type: 'string' }, template: { type: 'string' }, title: { type: 'string' }, project: { type: 'string' }, theme: { type: 'string' }, list: { type: 'boolean' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+  } });
+  if (values.help) { console.log(values.json ? JSON.stringify({ usage }, null, 2) : usage); return; }
+  if (values.list) {
+    if (positionals.length || values.title || values.starter || values.template || values.project || values.theme || values.format) throw invalid('--list cannot be combined with document creation.');
+    console.log(values.json ? JSON.stringify({ starters: listStarters() }, null, 2) : listStarters().map(item => `${item.id.padEnd(16)}${item.name} — ${item.description}`).join('\n'));
+    return;
+  }
+  if (positionals.length > 1) throw invalid('Provide one document ID. Use --title for the document title.');
+  if (values.starter && values.template) throw invalid('Choose --starter or --template, not both.');
+  if (values.format && !['document', 'presentation'].includes(values.format)) throw invalid('Choose document or presentation format.');
+  const input = { id: positionals[0], title: values.title, projectId: values.project, theme: values.theme, format: values.format };
+  const result = values.template
+    ? await createFromTemplate(root, values.template, input)
+    : await createDocument(root, { ...input, starter: values.starter, format: values.format });
+  console.log(values.json ? JSON.stringify(result, null, 2) : `Created ${result.entry}\nOpen it in OpenDoc, then ask Codex to develop it using your brief and sources.`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try { await runCreateCli(process.argv.slice(2)); }
+  catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
+}