@ryanyahya/opendoc 0.4.0

package/src/server/edits.ts

@@ -0,0 +1,249 @@
+import { readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { readFileSync, realpathSync, renameSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type { DocumentState, TextEditPreview } from '../shared/types';
+import type { ManualEditSummary, TextEditBatchInput, TextEditChange, TextEditInput, TextSourceValue } from '../shared/selection';
+import { containedFile } from './files';
+import { documentEntry, renderOnce } from './render';
+import { Conflict } from './comments';
+import { serializeSourceValue, textDigest, validateTextSyntax } from './text-source';
+import type { SourceOverride } from './source-overrides';
+
+type EditInput = TextEditInput | TextEditBatchInput;
+interface FileChange { path: string; file: string; before: string; after: string; beforeDigest: string; afterDigest: string }
+interface UndoRecord { summary: ManualEditSummary; files: FileChange[] }
+interface Prepared { files: FileChange[]; overrides: SourceOverride[]; summary: Omit<ManualEditSummary, 'id' | 'at' | 'canUndo'>; entry: string }
+interface PreviewRecord { id: string; directory: string; at: number; pages: number }
+
+function current(state: DocumentState, input: Pick<TextEditInput, 'revision' | 'hash'>, id: string) {
+  if (state.id !== id || state.status !== 'ready' || !state.artifact || state.revision !== input.revision || state.artifact.hash !== input.hash) throw new Conflict('This document changed. Your unsaved edits are still available; refresh or discard them before saving.');
+}
+
+/** Session-local grouped Save/Undo. Authored files stay authoritative until Save. */
+export class TextEditService {
+  private records = new Map<string, UndoRecord>();
+  private queues = new Map<string, Promise<unknown>>();
+  private previews = new Map<string, PreviewRecord>();
+  constructor(private root: string) {}
+
+  /** Keep folder operations from racing an in-flight Save or Undo. */
+  withDocument<T>(id: string, operation: () => Promise<T>) { return this.serialize(id, operation); }
+
+  private serialize<T>(id: string, operation: () => Promise<T>): Promise<T> {
+    const previous = this.queues.get(id) ?? Promise.resolve();
+    const next = previous.catch(() => undefined).then(operation);
+    this.queues.set(id, next);
+    void next.finally(() => { if (this.queues.get(id) === next) this.queues.delete(id); }).catch(() => undefined);
+    return next;
+  }
+
+  changedFiles(id: string) { return this.records.get(id)?.files.map(file => file.file) ?? []; }
+
+  async summary(id: string): Promise<ManualEditSummary | undefined> {
+    const record = this.records.get(id);
+    if (!record) return undefined;
+    let canUndo = record.summary.canUndo;
+    if (canUndo) {
+      try {
+        const entry = await documentEntry(this.root, id);
+        for (const item of record.files) {
+          const file = await containedFile(dirname(entry), resolve(this.root, item.file));
+          if (file !== item.path || textDigest(await readFile(file, 'utf8')) !== item.afterDigest) { canUndo = false; break; }
+        }
+      } catch { canUndo = false; }
+    }
+    return { ...record.summary, canUndo };
+  }
+
+  private async prepare(id: string, input: EditInput, state: DocumentState): Promise<Prepared> {
+    const batch = !!input && typeof input === 'object' && 'edits' in input;
+    const changes: TextEditChange[] = batch ? (input as TextEditBatchInput).edits : [input as TextEditInput];
+    if (!input || !Number.isInteger(input.revision) || typeof input.hash !== 'string' || !Array.isArray(changes) || !changes.length || changes.length > 100) throw new Error('Save between 1 and 100 text edits from the current document.');
+    let length = 0;
+    for (const change of changes) {
+      if (!change || typeof change.targetId !== 'string' || !Number.isInteger(change.start) || !Number.isInteger(change.end) || change.start < 0 || change.end <= change.start || typeof change.replacement !== 'string' || change.replacement.length > 8_000) throw new Error('Select one text range and enter a correction of up to 8,000 characters.');
+      length += change.replacement.length;
+    }
+    if (length > 128_000) throw new Error('Save a smaller group of text edits.');
+    current(state, input, id);
+    const entry = await documentEntry(this.root, id);
+    const workspaceRoot = await realpath(this.root);
+    const comments = await realpath(resolve(dirname(entry), 'comments.json')).catch(() => '');
+    const files = new Map<string, FileChange>();
+    const groups = new Map<string, { source: TextSourceValue; file: FileChange; edits: { start: number; end: number; replacement: string }[] }>();
+    let first: Prepared['summary'] | undefined;
+    for (const change of changes) {
+      const target = state.artifact!.textTargets?.find(target => target.id === change.targetId);
+      if (!target || change.end > target.text.length) throw new Conflict('This selected text is no longer available. Refresh the selection.');
+      const runs = target.runs.filter(run => run.start <= change.start && run.end >= change.end);
+      const run = runs.length === 1 ? runs[0] : undefined;
+      if (!run?.source || run.protected || target.text.slice(run.start, run.end) !== run.source.value) throw new Error('This selection spans separate values or generated content. Ask your agent to change it.');
+      const source = run.source;
+      const path = await containedFile(dirname(entry), resolve(this.root, source.file));
+      if (path === comments) throw new Error('Feedback cannot be changed through a text correction.');
+      if (!/\.(?:tsx?|json)$/.test(path)) throw new Error('This source does not support text corrections.');
+      let file = files.get(path);
+      if (!file) {
+        const before = await readFile(path, 'utf8');
+        file = { path, file: relative(workspaceRoot, path), before, after: before, beforeDigest: textDigest(before), afterDigest: '' };
+        files.set(path, file);
+      }
+      if (file.beforeDigest !== source.digest) throw new Conflict('The source changed elsewhere. Your unsaved edits have not been applied.');
+      if (!Number.isInteger(source.start) || !Number.isInteger(source.end) || source.start < 0 || source.end <= source.start || source.end > file.before.length) throw new Error('This source binding is invalid. Refresh the document.');
+      if (source.kind === 'json-string') {
+        const dataFile = state.artifact!.provenance?.dataFile;
+        if (!dataFile || await containedFile(dirname(entry), resolve(this.root, dataFile)) !== path) throw new Error('This data is not bound to the selected document.');
+      }
+      const key = JSON.stringify([path, source.start, source.end]);
+      let group = groups.get(key);
+      if (!group) { group = { source, file, edits: [] }; groups.set(key, group); }
+      if (group.source.value !== source.value || group.source.kind !== source.kind) throw new Conflict('Linked text has inconsistent bindings. Refresh the document.');
+      const local = { start: change.start - run.start, end: change.end - run.start, replacement: change.replacement };
+      if (group.edits.some(edit => edit.start === local.start && edit.end === local.end && edit.replacement === local.replacement)) continue;
+      if (group.edits.some(edit => edit.start < local.end && local.start < edit.end)) throw new Conflict('Two edits overlap the same source text. Keep one final correction for that text before saving.');
+      if (target.text.slice(change.start, change.end) === change.replacement) continue;
+      group.edits.push(local);
+      first ??= { blockId: target.blockId, targetId: target.id, before: target.text.slice(change.start, change.end), after: change.replacement };
+    }
+    const overrides: SourceOverride[] = [];
+    let count = 0;
+    for (const file of files.values()) {
+      const changes = [...groups.values()].filter(group => group.file === file && group.edits.length).sort((a, b) => a.source.start - b.source.start);
+      if (!changes.length) continue;
+      if (changes.some((group, index) => index > 0 && group.source.start < changes[index - 1].source.end)) throw new Conflict('These text bindings overlap. Refresh the document before saving.');
+      const replacements: SourceOverride['replacements'] = [];
+      for (const group of changes) {
+        let value = group.source.value;
+        for (const edit of group.edits.sort((a, b) => b.start - a.start)) value = value.slice(0, edit.start) + edit.replacement + value.slice(edit.end);
+        const token = serializeSourceValue(group.source, value);
+        replacements.push({ start: group.source.start, end: group.source.end, tokenLength: token.length, value });
+      }
+      for (let index = changes.length - 1; index >= 0; index--) {
+        const { source } = changes[index];
+        file.after = file.after.slice(0, source.start) + serializeSourceValue(source, replacements[index].value) + file.after.slice(source.end);
+      }
+      validateTextSyntax(file.path, file.after);
+      file.afterDigest = textDigest(file.after);
+      overrides.push({ file: file.path, contents: file.after, originalDigest: file.beforeDigest, replacements });
+      count += changes.length;
+    }
+    if (!count || !first) throw new Error('Change some text before saving.');
+    return { entry, files: [...files.values()].filter(file => file.afterDigest), overrides, summary: { ...first, count } };
+  }
+
+  /** Stage everything before replacement; rollback only bytes written by this operation. */
+  private async commit(files: FileChange[], check: () => void) {
+    const staged: { file: FileChange; temporary: string }[] = [];
+    const written: FileChange[] = [];
+    try {
+      for (const file of files) {
+        const temporary = `${file.path}.${randomUUID()}.tmp`;
+        staged.push({ file, temporary });
+        await writeFile(temporary, file.after);
+      }
+      check();
+      // No awaits between the final checks and renames, so our own watcher cannot
+      // publish an intermediate batch. Independent files have no OS-wide rename.
+      for (const file of files) {
+        if (realpathSync(resolve(this.root, file.file)) !== file.path || textDigest(readFileSync(file.path, 'utf8')) !== file.beforeDigest) throw new Conflict('The source changed during validation. Your edits have not been applied.');
+      }
+      for (const item of staged) {
+        if (realpathSync(resolve(this.root, item.file.file)) !== item.file.path || textDigest(readFileSync(item.file.path, 'utf8')) !== item.file.beforeDigest) throw new Conflict('The source changed during saving. Your edits have not been applied.');
+        renameSync(item.temporary, item.file.path); written.push(item.file);
+      }
+    } catch (error) {
+      let incomplete = false;
+      for (const file of written.reverse()) {
+        let temporary: string | undefined;
+        try {
+          if (realpathSync(resolve(this.root, file.file)) !== file.path || textDigest(readFileSync(file.path, 'utf8')) !== file.afterDigest) { incomplete = true; continue; }
+          temporary = `${file.path}.${randomUUID()}.tmp`;
+          await writeFile(temporary, file.before);
+          if (realpathSync(resolve(this.root, file.file)) !== file.path || textDigest(readFileSync(file.path, 'utf8')) !== file.afterDigest) { incomplete = true; continue; }
+          renameSync(temporary, file.path);
+        } catch { incomplete = true; }
+        finally { if (temporary) await rm(temporary, { force: true }).catch(() => {}); }
+      }
+      if (incomplete) throw new Conflict('The source changed while saving. Some edits could not be restored safely; review the document before continuing.');
+      throw error;
+    } finally { await Promise.all(staged.map(item => rm(item.temporary, { force: true }))); }
+  }
+
+  private async verifySources(prepared: Prepared, input: EditInput, state: DocumentState, id: string) {
+    current(state, input, id);
+    for (const file of prepared.files) {
+      if (await containedFile(dirname(prepared.entry), resolve(this.root, file.file)) !== file.path || textDigest(await readFile(file.path, 'utf8')) !== file.beforeDigest) throw new Conflict('The source changed during validation. Your unsaved edits have not been applied.');
+    }
+    current(state, input, id);
+  }
+
+  preview(id: string, input: TextEditBatchInput, state: DocumentState): Promise<TextEditPreview> {
+    return this.serialize(id, async () => {
+      const prepared = await this.prepare(id, input, state);
+      const result = await renderOnce(this.root, id, 30_000, prepared.overrides);
+      try {
+        await this.verifySources(prepared, input, state, id);
+        const key = randomUUID();
+        this.previews.set(key, { id, directory: result.directory, at: Date.now(), pages: result.artifact.pages.length });
+        await this.prunePreviews();
+        return { artifact: result.artifact, pdfUrl: `/api/documents/${id}/edits/previews/${key}/pdf` };
+      } catch (error) { await rm(result.directory, { recursive: true, force: true }); throw error; }
+    });
+  }
+
+  async previewPDF(id: string, key: string) {
+    const preview = this.previews.get(key);
+    if (!preview || preview.id !== id || Date.now() - preview.at > 10 * 60_000) throw new Conflict('This draft preview expired. Update an edit to render it again.');
+    return readFile(resolve(preview.directory, 'document.pdf'));
+  }
+
+  previewPageCount(id: string) {
+    return Math.max(1, ...[...this.previews.values()].filter(preview => preview.id === id && Date.now() - preview.at <= 10 * 60_000).map(preview => preview.pages));
+  }
+
+  private async prunePreviews() {
+    const previews = [...this.previews.entries()];
+    const keep = new Set(previews.slice(-24).map(([key]) => key));
+    const counts = new Map<string, number>();
+    for (const [key, preview] of previews.reverse()) {
+      const count = (counts.get(preview.id) ?? 0) + 1; counts.set(preview.id, count);
+      if (keep.has(key) && count <= 8 && Date.now() - preview.at <= 10 * 60_000) continue;
+      this.previews.delete(key); await rm(preview.directory, { recursive: true, force: true });
+    }
+  }
+
+  apply(id: string, input: EditInput, state: DocumentState): Promise<ManualEditSummary> {
+    return this.serialize(id, async () => {
+      const prepared = await this.prepare(id, input, state);
+      const result = await renderOnce(this.root, id, 30_000, prepared.overrides);
+      await rm(result.directory, { recursive: true, force: true });
+      await this.verifySources(prepared, input, state, id);
+      await this.commit(prepared.files, () => current(state, input, id));
+      const summary: ManualEditSummary = { ...prepared.summary, id: randomUUID(), at: new Date().toISOString(), canUndo: true };
+      this.records.set(id, { summary, files: prepared.files });
+      return { ...summary };
+    });
+  }
+
+  undo(id: string, editId: string): Promise<ManualEditSummary> {
+    return this.serialize(id, async () => {
+      const record = this.records.get(id);
+      if (!record || record.summary.id !== editId || !record.summary.canUndo) throw new Conflict('That correction is no longer the latest undoable edit.');
+      const entry = await documentEntry(this.root, id);
+      for (const file of record.files) {
+        const path = await containedFile(dirname(entry), resolve(this.root, file.file));
+        if (path !== file.path || textDigest(await readFile(path, 'utf8')) !== file.afterDigest) throw new Conflict('The source changed after these edits. Undo would overwrite newer work; ask your agent to restore the wording.');
+      }
+      await this.commit(record.files.map(file => ({ ...file, before: file.after, after: file.before, beforeDigest: file.afterDigest, afterDigest: file.beforeDigest })), () => {});
+      record.summary = { ...record.summary, canUndo: false };
+      return { ...record.summary };
+    });
+  }
+
+  async close() {
+    await Promise.allSettled([...this.queues.values()]);
+    await Promise.all([...this.previews.values()].map(preview => rm(preview.directory, { recursive: true, force: true })));
+    this.previews.clear();
+  }
+}

package/src/server/export-batch.ts

@@ -0,0 +1,105 @@
+import { access, readdir, rm, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { ReviewIssue } from '../shared/types';
+import type { PreviewSession } from './export-preview';
+import { ExportResponseLost } from './export-errors';
+import { RenderFailure } from './render-error';
+import { documentEntry, renderOnce, validId } from './render';
+import { publishRenderedPDF, publishFile } from './export-file';
+import { readPresentationBytes } from './pptx';
+import { exportInfo, type ExportFormat } from '../shared/export';
+import { captureExportInputs } from './export-inputs';
+
+export type ExportResult = {
+  id: string; status: 'success'; pages: number; hash: string; path: string; source: 'preview' | 'render'; warning?: string;
+} | {
+  id: string; status: 'error'; error: string; path: string; updated: false | 'unknown'; previousOutputRetained: boolean; issues?: ReviewIssue[];
+};
+export interface ExportOptions { requestTimeoutMs?: number; readyTimeoutMs?: number; renderTimeoutMs?: number; format?: ExportFormat; mode?: 'preview' | 'direct' }
+export const exportUsage = 'Usage: npx opendoc export <document-id> [more-ids...] [--format pdf|pptx] [--json]\n       npx opendoc export --all [--format pdf|pptx] [--json]';
+
+export function parseExportArgs(args: string[]) {
+  let all = false, json = false;
+  const ids: string[] = [];
+  let format: ExportFormat | undefined;
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--format') {
+      const next = args[++index];
+      if (format || (next !== 'pdf' && next !== 'pptx')) throw new Error(`Choose one --format pdf or --format pptx.\n${exportUsage}`);
+      format = next; continue;
+    }
+    parseArgument(arg);
+  }
+  function parseArgument(arg: string) {
+    if (arg === '--') return;
+    if (arg === '--all') { if (all) throw new Error(`Duplicate --all option.\n${exportUsage}`); all = true; }
+    else if (arg === '--json') { if (json) throw new Error(`Duplicate --json option.\n${exportUsage}`); json = true; }
+    else if (!validId(arg)) throw new Error(`Invalid argument: ${arg}\n${exportUsage}`);
+    else if (!ids.includes(arg)) ids.push(arg);
+  }
+  if ((all && ids.length) || (!all && !ids.length)) throw new Error(exportUsage);
+  return { all, json, ids, ...(format ? { format } : {}) };
+}
+
+export async function discoverDocumentIds(root: string) {
+  const ids: string[] = [];
+  for (const dir of await readdir(resolve(root, 'documents'), { withFileTypes: true })) {
+    if (!dir.isDirectory() || !validId(dir.name)) continue;
+    try { await access(resolve(root, 'documents', dir.name, 'index.tsx')); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue; throw error; }
+    ids.push(dir.name);
+  }
+  return ids.sort();
+}
+
+export async function exportDocuments(root: string, requestedIds: string[], supplied: ExportOptions = {}): Promise<ExportResult[]> {
+  const ids = [...new Set(requestedIds)];
+  if (ids.some(id => !validId(id))) throw new Error('Invalid document ID.');
+  if (!ids.length) throw new Error('No documents were found to export.');
+  const options = { requestTimeoutMs: 5_000, readyTimeoutMs: 35_000, renderTimeoutMs: 30_000, ...supplied, format: supplied.format ?? 'pdf' };
+  let session: PreviewSession | null = null, sessionError: unknown;
+  // Direct production never inspects a GUI session or loads its HTTP adapter.
+  const preview = options.mode === 'direct' ? undefined : await import('./export-preview');
+  if (preview) try { session = await preview.currentSession(root, options.requestTimeoutMs); } catch (error) { sessionError = error; }
+  const results: ExportResult[] = new Array(ids.length);
+  let next = 0;
+  async function run() {
+    while (next < ids.length) {
+      const index = next++, id = ids[index], path = resolve(root, 'output', `${id}${exportInfo(options.format).extension}`);
+      try {
+        if (sessionError) throw sessionError;
+        // Validate containment for online and offline requests alike.
+        await documentEntry(root, id);
+        if (session && preview) results[index] = await preview.exportPreview(root, id, session, options);
+        else {
+          const unchanged = await captureExportInputs(root, id);
+          const result = await renderOnce(root, id, options.renderTimeoutMs);
+          let exported: Extract<ExportResult, { status: 'success' }> | undefined;
+          try {
+            if (options.format === 'pptx') {
+              if (result.artifact.format !== 'presentation') throw new Error('PowerPoint export is available for presentations only.');
+              const bytes = await readPresentationBytes(result.directory, result.artifact.hash);
+              await publishFile(root, id, bytes, 'pptx', unchanged);
+            } else await publishRenderedPDF(root, id, result.directory, unchanged);
+            exported = { id, status: 'success', pages: result.artifact.pages.length, hash: result.artifact.hash, path, source: 'render' };
+            results[index] = exported;
+          } finally {
+            try { await rm(result.directory, { recursive: true, force: true }); }
+            catch (error) {
+              if (!exported) throw error;
+              exported.warning = `The file was saved, but temporary render files could not be removed: ${error instanceof Error ? error.message : String(error)}`;
+            }
+          }
+        }
+      } catch (error) {
+        const updated = error instanceof ExportResponseLost ? 'unknown' : false;
+        let previousOutputRetained = false;
+        if (updated === false) try { previousOutputRetained = (await stat(path)).isFile(); } catch { /* No prior export. */ }
+        results[index] = { id, status: 'error', error: error instanceof Error ? error.message : String(error), path, updated, previousOutputRetained, ...(error instanceof RenderFailure ? { issues: error.issues } : {}) };
+      }
+    }
+  }
+  await Promise.all([run(), run()]);
+  return results;
+}

package/src/server/export-errors.ts

@@ -0,0 +1,2 @@
+/** The GUI may have committed an export before its response was lost. */
+export class ExportResponseLost extends Error {}

package/src/server/export-file.ts

@@ -0,0 +1,57 @@
+import { lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { lstatSync, renameSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { validId } from './render';
+import { exportInfo, type ExportFormat } from '../shared/export';
+
+export class ExportChangedError extends Error {
+  constructor() { super('The document changed during export. Wait for the latest preview and try again.'); }
+}
+
+/** Prepare bytes first, then publish atomically while the revision is still current. */
+export async function publishFile(root: string, id: string, bytes: Uint8Array, format: ExportFormat, isCurrent: () => boolean = () => true, collection?: 'themes' | 'templates') {
+  if (!validId(id)) throw new Error('Invalid document ID.');
+  const folder = await outputFolder(root, collection ? [collection] : []);
+  const output = resolve(folder, `${id}${exportInfo(format).extension}`);
+  const previous = await lstat(output).catch(error => { if (error.code === 'ENOENT') return undefined; throw error; });
+  if (previous && (!previous.isFile() || previous.isSymbolicLink())) throw new Error('The export destination must be a regular local file.');
+  const temporary = resolve(folder, `.${id}.${randomUUID()}.tmp`);
+  let published = false;
+  try {
+    await writeFile(temporary, bytes, { flag: 'wx' });
+    for (const parent of new Set([resolve(root, 'output'), folder])) {
+      const info = lstatSync(parent);
+      if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('The export output folder changed during preparation.');
+    }
+    const current = (() => { try { return lstatSync(output); } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; throw error; } })();
+    if (current && (!current.isFile() || current.isSymbolicLink())) throw new Error('The export destination must be a regular local file.');
+    if (!isCurrent()) throw new ExportChangedError();
+    // No event-loop turn may separate the revision check from publication.
+    renameSync(temporary, output);
+    published = true;
+    return output;
+  } finally { if (!published) await rm(temporary, { force: true }); }
+}
+
+export async function publishRenderedPDF(root: string, id: string, directory: string, isCurrent?: () => boolean) {
+  const bytes = await readFile(resolve(directory, 'document.pdf'));
+  return publishPDF(root, id, bytes, isCurrent);
+}
+
+export function publishPDF(root: string, id: string, bytes: Uint8Array, isCurrent?: () => boolean, collection?: 'themes' | 'templates') {
+  return publishFile(root, id, bytes, 'pdf', isCurrent, collection);
+}
+
+/** Create output parents one at a time without traversing a linked directory. */
+export async function outputFolder(root: string, segments: string[] = []) {
+  let folder = root;
+  for (const segment of ['output', ...segments]) {
+    if (!validId(segment)) throw new Error('Invalid output folder.');
+    folder = resolve(folder, segment);
+    await mkdir(folder).catch(error => { if (error.code !== 'EEXIST') throw error; });
+    const info = await lstat(folder);
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('Exports need regular local output folders; symbolic links are not supported.');
+  }
+  return folder;
+}

package/src/server/export-inputs.ts

@@ -0,0 +1,66 @@
+import { readdir, realpath, stat } from 'node:fs/promises';
+import { readdirSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { documentDependencies, isManagedAssetPath, isThemeAssetDefaultsPath } from './dependencies';
+import { documentEntry } from './render';
+import { ExportChangedError } from './export-file';
+
+type Stamp = { size: bigint; mtimeNs: bigint; ctimeNs: bigint; ino: bigint };
+const signature = (value: Stamp) => `${value.size}:${value.mtimeNs}:${value.ctimeNs}:${value.ino}`;
+
+const sharedCompanions = ['templates', 'themes', 'assets'];
+
+/** Capture local inputs before rendering; the final check stays synchronous with publication. */
+export async function captureExportInputs(root: string, id: string): Promise<() => boolean> {
+  return captureEntryExportInputs(root, await documentEntry(root, id), [`documents/${id}`, ...sharedCompanions]);
+}
+
+/** Specimens include transient defaults, while authored documents include only their exact pins. */
+export async function captureEntryExportInputs(root: string, entry: string, companionFolders: string[] = sharedCompanions): Promise<() => boolean> {
+  const entryBefore = signature(await stat(entry, { bigint: true }));
+  const dependencies = await documentDependencies(root, entry);
+  const inputs = new Map<string, { stamp: string; directory: boolean; missing?: boolean; emptyWhenMissing?: boolean }>();
+  const visited = new Set<string>();
+  const included = (parent: string, name: string) => name !== 'comments.json' && !name.startsWith('.forme-render-') && !name.endsWith('.tmp')
+    && (dependencies.readsFiles || (!isManagedAssetPath(root, resolve(parent, name)) && !isThemeAssetDefaultsPath(root, resolve(parent, name))));
+  async function collect(path: string) {
+    // A newly created managed logo container is equivalent to an empty catalog;
+    // loose legacy artwork in that container remains a conservative shared input.
+    const emptyWhenMissing = !dependencies.readsFiles && path === resolve(root, 'assets/logos');
+    let info;
+    try { info = await stat(path, { bigint: true }); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      inputs.set(path, emptyWhenMissing ? { stamp: '[]', directory: true, emptyWhenMissing: true } : { stamp: '', directory: false, missing: true }); return;
+    }
+    if (!info.isDirectory()) { inputs.set(path, { stamp: signature(info), directory: false }); return; }
+    const children = (await readdir(path)).filter(name => included(path, name)).sort();
+    inputs.set(path, { stamp: JSON.stringify(children), directory: true, ...(emptyWhenMissing ? { emptyWhenMissing: true } : {}) });
+    const actual = await realpath(path);
+    if (visited.has(actual)) return;
+    visited.add(actual);
+    for (const child of children) await collect(resolve(path, child));
+  }
+  // Explicit dependencies bypass broad-library exclusions, including paths currently absent.
+  for (const path of dependencies.files) await collect(path);
+  for (const folder of [...new Set([...companionFolders, ...(dependencies.readsFiles ? ['documents'] : [])])]) await collect(resolve(root, folder));
+  if (!dependencies.readsFiles && companionFolders.some(folder => ['assets', 'assets/logos'].includes(folder))) await collect(resolve(root, 'assets/logos'));
+  const unchanged = () => {
+    try {
+      return [...inputs].every(([file, input]) => {
+        if (input.missing) {
+          try { statSync(file); return false; } catch (error) { return (error as NodeJS.ErrnoException).code === 'ENOENT'; }
+        }
+        if (input.emptyWhenMissing) {
+          try { return JSON.stringify(readdirSync(file).filter(name => included(file, name)).sort()) === input.stamp; }
+          catch (error) { return (error as NodeJS.ErrnoException).code === 'ENOENT' && input.stamp === '[]'; }
+        }
+        return (input.directory
+          ? JSON.stringify(readdirSync(file).filter(name => included(file, name)).sort())
+          : signature(statSync(file, { bigint: true }))) === input.stamp;
+      });
+    } catch { return false; }
+  };
+  if (signature(await stat(entry, { bigint: true })) !== entryBefore || !unchanged()) throw new ExportChangedError();
+  return unchanged;
+}

package/src/server/export-preview.ts

@@ -0,0 +1,69 @@
+import { resolve } from 'node:path';
+import type { DocumentState } from '../shared/types';
+import { exportInfo } from '../shared/export';
+import { readJSON } from './files';
+import type { ExportOptions, ExportResult } from './export-batch';
+import { ExportResponseLost } from './export-errors';
+
+interface Connection { origin: string; token: string }
+export interface PreviewSession { connection: Connection; states: DocumentState[] }
+type Session = PreviewSession;
+
+async function responseError(response: Response, fallback: string) {
+  try { const data = await response.json() as { error?: unknown }; return typeof data.error === 'string' ? data.error : fallback; }
+  catch { return fallback; }
+}
+
+async function request(url: string, timeout: number, init?: RequestInit) {
+  return fetch(url, { ...init, signal: AbortSignal.timeout(timeout), redirect: 'error' });
+}
+
+async function readStates(connection: Connection, timeout: number) {
+  const response = await request(`${connection.origin}/api/documents`, timeout);
+  if (!response.ok) throw new Error(await responseError(response, `The local OpenDoc session refused the request (${response.status}).`));
+  const states = await response.json() as DocumentState[];
+  if (!Array.isArray(states)) throw new Error('The local OpenDoc session returned an invalid document list.');
+  return states;
+}
+
+export async function currentSession(root: string, timeout: number): Promise<Session | null> {
+  const connection = await readJSON<Connection | null>(resolve(root, '.opendoc/server.json'), null);
+  if (!connection) return null;
+  if (typeof connection.origin !== 'string' || !/^http:\/\/127\.0\.0\.1:\d+$/.test(connection.origin) || typeof connection.token !== 'string' || !connection.token) {
+    throw new Error('The local OpenDoc session file is invalid. Restart OpenDoc before exporting.');
+  }
+  try { return { connection, states: await readStates(connection, timeout) }; }
+  catch (error) {
+    // Only an unavailable server permits an offline render. A live error stays authoritative.
+    const code = (error as { cause?: { code?: string } }).cause?.code;
+    if (code === 'ECONNREFUSED' || code === 'ENOTFOUND') return null;
+    throw error;
+  }
+}
+
+export async function exportPreview(root: string, id: string, session: Session, options: Required<Pick<ExportOptions, 'requestTimeoutMs' | 'readyTimeoutMs' | 'format'>>): Promise<ExportResult> {
+  const deadline = Date.now() + options.readyTimeoutMs;
+  let state = session.states.find(item => item.id === id);
+  while (state?.status === 'rendering' && Date.now() < deadline) {
+    await new Promise(accept => setTimeout(accept, Math.min(120, Math.max(1, deadline - Date.now()))));
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    state = (await readStates(session.connection, Math.min(options.requestTimeoutMs, remaining))).find(item => item.id === id);
+  }
+  if (!state) throw new Error(`Document "${id}" was not found in the current OpenDoc session.`);
+  if (state.status !== 'ready' || !state.artifact) throw new Error(state.error ?? 'The current document is still rendering. Wait for its preview before exporting.');
+  let response: Response;
+  try {
+    response = await request(`${session.connection.origin}/api/documents/${id}/export`, options.requestTimeoutMs, {
+      method: 'POST', headers: { 'Content-Type': 'application/json', 'X-OpenDoc-Token': session.connection.token },
+      body: JSON.stringify({ hash: state.artifact.hash, format: options.format }),
+    });
+  } catch {
+    throw new ExportResponseLost('The local session stopped responding during export. The output may have been saved; its status could not be confirmed.');
+  }
+  if (!response.ok) throw new Error(await responseError(response, `Export failed (${response.status}).`));
+  // The endpoint saves locally before returning 200; the CLI needs no duplicate PDF download.
+  await response.body?.cancel().catch(() => {});
+  return { id, status: 'success', pages: state.artifact.pages.length, hash: state.artifact.hash, path: resolve(root, 'output', `${id}${exportInfo(options.format).extension}`), source: 'preview' };
+}
+

package/src/server/export.ts

@@ -0,0 +1,32 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { discoverDocumentIds, exportDocuments, exportUsage, parseExportArgs, type ExportOptions } from './export-batch';
+
+export async function runExportCli(args: string[], root = process.cwd(), settings: Pick<ExportOptions, 'mode'> = {}): Promise<void> {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(args.includes('--json') ? JSON.stringify({ usage: exportUsage }, null, 2) : exportUsage);
+    return;
+  }
+  const options = parseExportArgs(args);
+  const ids = options.all ? await discoverDocumentIds(root) : options.ids;
+  const results = await exportDocuments(root, ids, { format: options.format, ...settings });
+  if (options.json) console.log(JSON.stringify({ results }, null, 2));
+  else for (const result of results) {
+    if (result.status === 'success') {
+      console.log(`Exported ${result.id} (${result.pages} ${result.pages === 1 ? 'page' : 'pages'}): ${result.path}`);
+      if (result.warning) console.error(result.warning);
+    }
+    else console.error(`${result.id}: ${result.error}\n${result.updated === 'unknown' ? `Check ${result.path} before retrying.` : result.previousOutputRetained ? 'Previous export retained; it was not updated.' : 'No file was written.'}`);
+  }
+  if (results.some(result => result.status === 'error')) process.exitCode = 1;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try { await runExportCli(process.argv.slice(2)); }
+  catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (process.argv.includes('--json')) console.log(JSON.stringify({ error: message, results: [] }, null, 2));
+    else console.error(message);
+    process.exitCode = 1;
+  }
+}