@wafflebase/cli 0.3.6 → 0.3.7

package/README.md

@@ -0,0 +1,129 @@
+# @wafflebase/cli
+
+`wafflebase` — terminal access to the Wafflebase REST API for data
+pipelines, scripting, CSV/JSON import/export, document management, and
+word-processor (`docs content / export / import`) operations.
+
+## Install
+
+```bash
+# Local install (recommended for scripts)
+npm install -D @wafflebase/cli
+npx wafflebase --help
+
+# Global install (recommended for interactive use)
+npm install -g @wafflebase/cli
+wafflebase --help
+```
+
+## Auth
+
+Two paths, in priority order:
+
+1. **API key** (recommended for scripts) — pass `--api-key` /
+   `WAFFLEBASE_API_KEY`, or set `api-key:` in `~/.wafflebase/config.yaml`.
+2. **OAuth session** — `wafflebase login` opens a browser, completes
+   GitHub OAuth, and writes a JWT session to `~/.wafflebase/session.json`.
+
+Always pair API keys with a workspace ID:
+
+```bash
+export WAFFLEBASE_API_KEY=wfb_…
+export WAFFLEBASE_WORKSPACE=ws-…
+```
+
+## Command Tree (v0.3.7)
+
+Plural namespaces are canonical; singular forms are accepted as
+aliases for back-compat with earlier scripts.
+
+```
+wafflebase
+├── login / logout / status                Browser OAuth + session
+├── ctx list / switch <name|id>            Workspace context
+│
+├── docs (aliases: doc, document, documents)
+│   ├── list [--type doc|sheet]
+│   ├── create <title> [--type doc|sheet]
+│   ├── get <doc-id>
+│   ├── rename <doc-id> <title>
+│   ├── delete <doc-id>
+│   ├── content <doc-id>                   --format json|md|text + --pages
+│   ├── export <doc-id> <file>             --format pdf|docx + --pages (PDF)
+│   └── import <file>                      --replace <id> --yes for in-place
+│
+├── sheets (aliases: sheet, spreadsheet, spreadsheets)
+│   ├── tabs (alias: tab) list <doc-id>
+│   ├── cells (alias: cell)
+│   │   ├── get <doc-id> [<range>]
+│   │   ├── set <doc-id> <ref> <value>     --formula
+│   │   ├── batch <doc-id>                 --data <json> | stdin
+│   │   └── delete <doc-id> <ref>
+│   ├── import <doc-id> <file>             CSV/JSON
+│   └── export <doc-id> <file>             CSV/JSON
+│
+├── api-keys (alias: api-key)
+│   ├── create <name>
+│   ├── list
+│   └── revoke <key-id>
+│
+└── schema [<command>]                     Discover parameters/safety
+```
+
+**Global flags**: `--server`, `--api-key`, `--workspace`, `--profile`,
+`--format json|table|csv` (default `json`), `--quiet`, `--verbose`,
+`--dry-run`. The `--format` flag also doubles as the per-content shape
+on `docs content` (`json|md|text`) and the export type override on
+`docs export` (`pdf|docx`).
+
+## Examples
+
+```bash
+# Documents
+wafflebase docs list
+wafflebase docs create "Q1 Notes" --type doc
+
+# Spreadsheets
+wafflebase sheets cells get abc-123 A1:D100
+echo '{"A1":"Name","B1":"Score"}' | wafflebase sheets cells batch abc-123
+wafflebase sheets export abc-123 out.csv
+
+# Word-processor docs
+wafflebase docs content abc-123 --format md
+wafflebase docs export abc-123 out.pdf --pages 1-3
+wafflebase docs import draft.docx --title "Final Draft"
+wafflebase docs import revision.docx --replace abc-123 --yes
+
+# Schema introspection (singular aliases resolve too)
+wafflebase schema docs.content
+wafflebase schema cell.get          # → sheets.cells.get
+```
+
+## Output Conventions
+
+- **Text results** (json/md/text): stdout by default; `--out <file>` to
+  redirect; `-` writes to stdout explicitly. `--force` is required to
+  overwrite an existing `--out` target.
+- **Binary results** (pdf/docx): positional `<file>`; `-` writes to stdout.
+  `--force` is required to overwrite an existing target.
+- **Errors**: a single JSON line on stderr —
+  `{"error":{"code":"…","message":"…"}}`. Typed errors (e.g.,
+  `INVALID_DOCX`, `TYPE_MISMATCH`, `CONFIRMATION_REQ`) carry a
+  command-specific `code` agents can branch on; everything else
+  reports `"ERROR"`.
+- **Exit codes**: `0` success, `1` user error (bad input, 404, type
+  mismatch), `2` system error (network, auth).
+
+## Skills (for AI agents)
+
+Skill files live in `skills/` and ship with the package — namespace
+prefixed (`docs-…`, `sheets-…`, `recipe-…`). Agents load them, read
+the YAML frontmatter for safety + tool list, and `wafflebase schema
+<command>` for parameter shapes. See [`skills/SKILL.md`](skills/SKILL.md)
+for the index.
+
+## Design
+
+Full design in [`/docs/design/rest-api-and-cli.md`](../../docs/design/rest-api-and-cli.md)
+and [`/docs/design/docs-cli.md`](../../docs/design/docs-cli.md) (the
+docs-side `content / export / import` pipeline).

package/dist/bin.js

@@ -1,26 +1,20 @@
 #!/usr/bin/env node
 import { createProgram } from './commands/root.js';
-import { registerDocumentCommand } from './commands/document.js';
-import { registerTabCommand } from './commands/tab.js';
-import { registerCellCommand } from './commands/cell.js';
-import { registerApiKeyCommand } from './commands/api-key.js';
+import { registerDocsCommand } from './commands/docs.js';
+import { registerSheetsCommand } from './commands/sheets.js';
+import { registerApiKeysCommand } from './commands/api-keys.js';
 import { registerSchemaCommand } from './commands/schema.js';
 import { registerLoginCommand } from './commands/login.js';
 import { registerLogoutCommand } from './commands/logout.js';
 import { registerStatusCommand } from './commands/status.js';
 import { registerCtxCommand } from './commands/ctx.js';
-import { registerImportCommand } from './commands/import.js';
-import { registerExportCommand } from './commands/export.js';
 const program = createProgram();
 registerLoginCommand(program);
 registerLogoutCommand(program);
 registerStatusCommand(program);
 registerCtxCommand(program);
-registerDocumentCommand(program);
-registerTabCommand(program);
-registerCellCommand(program);
-registerApiKeyCommand(program);
-registerImportCommand(program);
-registerExportCommand(program);
+registerDocsCommand(program);
+registerSheetsCommand(program);
+registerApiKeysCommand(program);
 registerSchemaCommand(program);
 program.parse();

package/dist/client/http-client.d.ts

@@ -1,3 +1,4 @@
+import type { Document } from '@wafflebase/docs';
 import type { CliConfig } from '../config/config.js';
 export interface ApiResponse<T = unknown> {
     ok: boolean;
@@ -22,10 +23,12 @@ export declare class HttpClient {
     private refreshSession;
     request<T>(method: string, path: string, body?: unknown): Promise<ApiResponse<T>>;
     listDocuments(): Promise<ApiResponse<unknown[]>>;
-    createDocument(title: string): Promise<ApiResponse<unknown>>;
+    createDocument(title: string, type?: 'doc' | 'sheet'): Promise<ApiResponse<unknown>>;
     getDocument(id: string): Promise<ApiResponse<unknown>>;
     updateDocument(id: string, title: string): Promise<ApiResponse<unknown>>;
     deleteDocument(id: string): Promise<ApiResponse<unknown>>;
+    getDocContent(docId: string): Promise<ApiResponse<Document>>;
+    putDocContent(docId: string, doc: Document): Promise<ApiResponse<Document>>;
     listTabs(docId: string): Promise<ApiResponse<unknown[]>>;
     getCells(docId: string, tabId: string, range?: string): Promise<ApiResponse<unknown>>;
     getCell(docId: string, tabId: string, sref: string): Promise<ApiResponse<unknown>>;

package/dist/client/http-client.js

@@ -94,8 +94,11 @@ export class HttpClient {
     listDocuments() {
         return this.request('GET', '/documents');
     }
-    createDocument(title) {
-        return this.request('POST', '/documents', { title });
+    createDocument(title, type) {
+        const body = { title };
+        if (type)
+            body.type = type;
+        return this.request('POST', '/documents', body);
     }
     getDocument(id) {
         return this.request('GET', `/documents/${id}`);
@@ -106,6 +109,13 @@ export class HttpClient {
     deleteDocument(id) {
         return this.request('DELETE', `/documents/${id}`);
     }
+    // Docs (word-processor) content
+    getDocContent(docId) {
+        return this.request('GET', `/documents/${docId}/content`);
+    }
+    putDocContent(docId, doc) {
+        return this.request('PUT', `/documents/${docId}/content`, doc);
+    }
     // Tabs
     listTabs(docId) {
         return this.request('GET', `/documents/${docId}/tabs`);

package/dist/commands/api-keys.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerApiKeysCommand(program: Command): void;

package/dist/commands/{api-key.js → api-keys.js}

@@ -1,7 +1,10 @@
 import { getGlobalOpts, getClient } from './root.js';
 import { output, outputError } from '../output/formatter.js';
-export function registerApiKeyCommand(program) {
-    const apiKey = program.command('api-key').description('Manage API keys');
+export function registerApiKeysCommand(program) {
+    const apiKey = program
+        .command('api-keys')
+        .alias('api-key')
+        .description('Manage API keys');
     apiKey
         .command('create <name>')
         .description('Create a new API key')

package/dist/commands/cells.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerCellsCommand(parent: Command): void;

package/dist/commands/{cell.js → cells.js}

@@ -1,8 +1,11 @@
 import { getGlobalOpts, getClient, getConfig } from './root.js';
 import { output, outputError } from '../output/formatter.js';
 import { printDryRun } from '../client/dry-run.js';
-export function registerCellCommand(program) {
-    const cell = program.command('cell').description('Read and write cells');
+export function registerCellsCommand(parent) {
+    const cell = parent
+        .command('cells')
+        .alias('cell')
+        .description('Read and write cells');
     cell
         .command('get <doc-id> [range]')
         .description('Get cells (default: all, or A1, or A1:C10)')

package/dist/commands/docs.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerDocsCommand(program: Command): void;
+export declare function registerDocsImportCommand(doc: Command): void;

package/dist/commands/docs.js

@@ -0,0 +1,306 @@
+import { extname } from 'node:path';
+import { getGlobalOpts, getClient, getConfig } from './root.js';
+import { output, outputError } from '../output/formatter.js';
+import { printDryRun } from '../client/dry-run.js';
+import { parseContentFormat, runDocsContent } from '../docs/content.js';
+import { exportPdf } from '../docs/pdf-export.js';
+import { exportDocx } from '../docs/docx-export.js';
+import { parsePageRange } from '../docs/page-range.js';
+import { writeBinary } from '../output/binary.js';
+import { runDocsImport } from '../docs/import.js';
+function parseType(value) {
+    if (value === undefined)
+        return undefined;
+    if (value !== 'doc' && value !== 'sheet') {
+        throw new Error(`Invalid --type "${value}". Use "doc" or "sheet".`);
+    }
+    return value;
+}
+const VALID_EXPORT_FORMATS = ['pdf', 'docx'];
+function detectExportFormat(file, formatFlag) {
+    if (formatFlag) {
+        if (!VALID_EXPORT_FORMATS.includes(formatFlag)) {
+            throw new Error(`Invalid --format "${formatFlag}". Use one of: ${VALID_EXPORT_FORMATS.join(', ')}.`);
+        }
+        return formatFlag;
+    }
+    const ext = extname(file).toLowerCase();
+    if (ext === '.pdf')
+        return 'pdf';
+    if (ext === '.docx')
+        return 'docx';
+    throw new Error(`Cannot infer format from "${file}". Pass --format pdf|docx, or use a .pdf/.docx extension.`);
+}
+export function registerDocsCommand(program) {
+    const doc = program
+        .command('docs')
+        .alias('doc')
+        .alias('document')
+        .alias('documents')
+        .description('Manage documents');
+    doc
+        .command('list')
+        .description('List documents in workspace')
+        .option('--type <type>', 'Filter by document type (doc|sheet)')
+        .action(async function () {
+        const opts = getGlobalOpts(this);
+        const { type: typeStr } = this.opts();
+        try {
+            const filterType = parseType(typeStr);
+            const res = await getClient(opts).listDocuments();
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            let data = res.data;
+            if (filterType && Array.isArray(data)) {
+                data = data.filter((d) => (d.type ?? 'sheet') === filterType);
+            }
+            output(data, opts.format, opts.quiet);
+        }
+        catch (e) {
+            outputError(e, opts.quiet);
+        }
+    });
+    doc
+        .command('create <title>')
+        .description('Create a new document')
+        .option('--type <type>', 'Document type (doc|sheet)', 'sheet')
+        .action(async function (title) {
+        const opts = getGlobalOpts(this);
+        const { type: typeStr } = this.opts();
+        try {
+            const type = parseType(typeStr) ?? 'sheet';
+            if (opts.dryRun) {
+                printDryRun(getConfig(opts), 'POST', '/documents', { title, type });
+                return;
+            }
+            const res = await getClient(opts).createDocument(title, type);
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            output(res.data, opts.format, opts.quiet);
+        }
+        catch (e) {
+            outputError(e, opts.quiet);
+        }
+    });
+    doc
+        .command('get <doc-id>')
+        .description('Show document metadata')
+        .action(async function (docId) {
+        const opts = getGlobalOpts(this);
+        try {
+            const res = await getClient(opts).getDocument(docId);
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            output(res.data, opts.format, opts.quiet);
+        }
+        catch (e) {
+            outputError(e, opts.quiet);
+        }
+    });
+    doc
+        .command('rename <doc-id> <title>')
+        .description('Rename a document')
+        .action(async function (docId, title) {
+        const opts = getGlobalOpts(this);
+        if (opts.dryRun) {
+            printDryRun(getConfig(opts), 'PATCH', `/documents/${docId}`, { title });
+            return;
+        }
+        try {
+            const res = await getClient(opts).updateDocument(docId, title);
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            output(res.data, opts.format, opts.quiet);
+        }
+        catch (e) {
+            outputError(e, opts.quiet);
+        }
+    });
+    doc
+        .command('delete <doc-id>')
+        .description('Delete a document')
+        .action(async function (docId) {
+        const opts = getGlobalOpts(this);
+        if (opts.dryRun) {
+            printDryRun(getConfig(opts), 'DELETE', `/documents/${docId}`);
+            return;
+        }
+        try {
+            const res = await getClient(opts).deleteDocument(docId);
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            output(res.data, opts.format, opts.quiet);
+        }
+        catch (e) {
+            outputError(e, opts.quiet);
+        }
+    });
+    doc
+        .command('content <doc-id>')
+        .description('Read document content as JSON, Markdown, or plain text')
+        // NOTE: `--format` is intentionally not redeclared here. The global
+        // `--format` option (declared in `createProgram`) catches the user's
+        // value because commander resolves duplicate-named flags through the
+        // earliest parent that owns them. Reading via `opts.format` (the
+        // merged form) keeps a single source of truth and lets
+        // `parseContentFormat` validate that the value is one of json|md|text.
+        .option('--pages <range>', 'Page range to include (e.g. 1-3,5)')
+        .option('--include-header-footer', 'Include header/footer (md/text)', false)
+        .option('--inline-images', 'Inline data: image URLs (md only)', false)
+        .option('--out <file>', 'Output file (- for stdout)')
+        .option('--force', 'Overwrite existing output file', false)
+        .action(async function (docId) {
+        const opts = getGlobalOpts(this);
+        const local = this.opts();
+        try {
+            const format = parseContentFormat(opts.format);
+            if (opts.dryRun) {
+                printDryRun(getConfig(opts), 'GET', `/documents/${docId}/content`);
+                return;
+            }
+            const res = await getClient(opts).getDocContent(docId);
+            if (!res.ok) {
+                const body = res.data;
+                if (body?.error) {
+                    // Surface backend-shaped errors (e.g., TYPE_MISMATCH) verbatim
+                    // so agents reading stderr can act on the `code` field.
+                    console.error(JSON.stringify(body, null, 2));
+                    process.exitCode = 1;
+                    return;
+                }
+                throw new Error(`HTTP ${res.status}`);
+            }
+            runDocsContent({
+                doc: res.data,
+                format,
+                pages: local.pages,
+                includeHeaderFooter: local.includeHeaderFooter,
+                inlineImages: local.inlineImages,
+                out: local.out,
+                force: local.force,
+                quiet: opts.quiet,
+            });
+        }
+        catch (e) {
+            outputError(e, opts.quiet);
+        }
+    });
+    doc
+        .command('export <doc-id> <file>')
+        .description('Export a document to PDF or DOCX')
+        // NOTE: `--format` reuses the global option for the same reason
+        // documented on `docs content` above; we route through `opts.format`
+        // and use commander's `getOptionValueSourceWithGlobals` to tell a
+        // user-supplied value from the implicit default. That keeps an
+        // explicit `--format json` from silently falling through to the
+        // extension — it now surfaces as the documented "invalid format"
+        // error.
+        .option('--pages <range>', 'Page range to export (PDF only)')
+        .option('--include-header-footer', 'Include header/footer regions', true)
+        .option('--force', 'Overwrite existing output file', false)
+        .action(async function (docId, file) {
+        const opts = getGlobalOpts(this);
+        const local = this.opts();
+        try {
+            // `'cli'` source means the user typed the flag (or its alias)
+            // on the command line; anything else (`'default'`, `'env'`,
+            // `'config'`) is treated as "no override intended" so the
+            // file extension wins.
+            const formatSource = this.getOptionValueSourceWithGlobals('format');
+            const formatOverride = formatSource === 'cli' ? opts.format : undefined;
+            const format = detectExportFormat(file, formatOverride);
+            if (opts.dryRun) {
+                printDryRun(getConfig(opts), 'GET', `/documents/${docId}/content`);
+                return;
+            }
+            const res = await getClient(opts).getDocContent(docId);
+            if (!res.ok) {
+                const body = res.data;
+                if (body?.error) {
+                    console.error(JSON.stringify(body, null, 2));
+                    process.exitCode = 1;
+                    return;
+                }
+                throw new Error(`HTTP ${res.status}`);
+            }
+            const fetchedDoc = res.data;
+            let bytes;
+            if (format === 'pdf') {
+                // Pagination uses the FontkitMeasurer's coarse Latin estimate
+                // when no Korean fonts are needed; we still pre-page to know
+                // the document's page count for `parsePageRange`. PdfExporter
+                // does the authoritative paint-time pagination internally.
+                let pageRange = undefined;
+                if (local.pages) {
+                    // Resolve pages against the rendered PDF's page count
+                    // (rather than running our own paginator twice). We render
+                    // the full PDF first, then strip non-selected pages —
+                    // see `extractPages` in pdf-export.ts.
+                    const fullPdf = await exportPdf(fetchedDoc, {
+                        includeHeaderFooter: local.includeHeaderFooter,
+                    });
+                    const total = await pdfPageCount(fullPdf);
+                    pageRange = parsePageRange(local.pages, total);
+                    if (!opts.quiet) {
+                        for (const w of pageRange.warnings)
+                            console.error(w);
+                    }
+                    bytes = await exportPdf(fetchedDoc, {
+                        includeHeaderFooter: local.includeHeaderFooter,
+                        pages: pageRange,
+                    });
+                }
+                else {
+                    bytes = await exportPdf(fetchedDoc, {
+                        includeHeaderFooter: local.includeHeaderFooter,
+                    });
+                }
+            }
+            else {
+                if (local.pages && !opts.quiet) {
+                    console.error('DOCX has no page concept — exporting full document, --pages ignored.');
+                }
+                bytes = await exportDocx(fetchedDoc, {
+                    includeHeaderFooter: local.includeHeaderFooter,
+                });
+            }
+            writeBinary(bytes, file, { force: local.force, quiet: opts.quiet });
+        }
+        catch (e) {
+            outputError(e, opts.quiet);
+        }
+    });
+    registerDocsImportCommand(doc);
+}
+async function pdfPageCount(bytes) {
+    const { PDFDocument } = await import('pdf-lib');
+    const pdf = await PDFDocument.load(bytes);
+    return pdf.getPageCount();
+}
+export function registerDocsImportCommand(doc) {
+    doc
+        .command('import <file>')
+        .description('Import a .docx file as a new (or replacement) document')
+        .option('--title <title>', 'Document title (default: file basename)')
+        .option('--replace <doc-id>', 'Replace content of an existing document')
+        .option('--yes', 'Skip --replace confirmation prompt', false)
+        .action(async function (file) {
+        const opts = getGlobalOpts(this);
+        const local = this.opts();
+        try {
+            const result = await runDocsImport({
+                file,
+                title: local.title,
+                replace: local.replace,
+                yes: local.yes,
+                quiet: opts.quiet,
+                dryRun: opts.dryRun,
+            }, getClient(opts));
+            if (result.exitCode !== 0)
+                process.exitCode = result.exitCode;
+        }
+        catch (e) {
+            outputError(e, opts.quiet);
+        }
+    });
+}

package/dist/commands/sheets-export.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerSheetsExportCommand(parent: Command): void;

package/dist/commands/{export.js → sheets-export.js}

@@ -17,8 +17,8 @@ function detectFormat(file, formatFlag) {
         return 'json';
     return 'csv';
 }
-export function registerExportCommand(program) {
-    program
+export function registerSheetsExportCommand(parent) {
+    parent
         .command('export <doc-id> <file>')
         .description('Export tab data to CSV/JSON')
         .option('--tab <tab-id>', 'Source tab', 'tab-1')

package/dist/commands/sheets-import.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerSheetsImportCommand(parent: Command): void;

package/dist/commands/{import.js → sheets-import.js}

@@ -23,8 +23,8 @@ function readInput(file) {
     }
     return readFileSync(file, 'utf-8');
 }
-export function registerImportCommand(program) {
-    program
+export function registerSheetsImportCommand(parent) {
+    parent
         .command('import <doc-id> <file>')
         .description('Import CSV/JSON into a tab')
         .option('--tab <tab-id>', 'Target tab', 'tab-1')

package/dist/commands/sheets.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerSheetsCommand(program: Command): Command;

package/dist/commands/sheets.js

@@ -0,0 +1,17 @@
+import { registerCellsCommand } from './cells.js';
+import { registerTabsCommand } from './tabs.js';
+import { registerSheetsImportCommand } from './sheets-import.js';
+import { registerSheetsExportCommand } from './sheets-export.js';
+export function registerSheetsCommand(program) {
+    const sheets = program
+        .command('sheets')
+        .alias('sheet')
+        .alias('spreadsheet')
+        .alias('spreadsheets')
+        .description('Spreadsheet commands');
+    registerTabsCommand(sheets);
+    registerCellsCommand(sheets);
+    registerSheetsImportCommand(sheets);
+    registerSheetsExportCommand(sheets);
+    return sheets;
+}

package/dist/commands/tabs.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerTabsCommand(parent: Command): void;

package/dist/commands/{tab.js → tabs.js}

@@ -1,7 +1,7 @@
 import { getGlobalOpts, getClient } from './root.js';
 import { output, outputError } from '../output/formatter.js';
-export function registerTabCommand(program) {
-    const tab = program.command('tab').description('Manage tabs');
+export function registerTabsCommand(parent) {
+    const tab = parent.command('tabs').alias('tab').description('Manage tabs');
     tab
         .command('list <doc-id>')
         .description('List tabs in a document')

package/dist/docs/content.d.ts

@@ -0,0 +1,37 @@
+import { type Document } from '@wafflebase/docs';
+export declare const VALID_CONTENT_FORMATS: readonly ["json", "md", "text"];
+export type ContentFormat = (typeof VALID_CONTENT_FORMATS)[number];
+export declare const LOSSY_NOTICE = "Lossy conversion: see docs-cli design for the exact mapping";
+export declare const PAGES_FONT_WARNING: string;
+export declare function parseContentFormat(value: string): ContentFormat;
+/**
+ * Surface for `runDocsContent` to talk back to the CLI without taking a
+ * direct dependency on `process.stdout` / `process.stderr` / `fs`. The
+ * command wires the real implementations; tests inject in-memory
+ * collectors.
+ */
+export interface ContentIO {
+    stdout: (text: string) => void;
+    stderr: (line: string) => void;
+    /** Write `text` to `path`. Throws if the file exists and `force` is false. */
+    writeFile: (path: string, text: string, force: boolean) => void;
+}
+export declare const defaultIO: ContentIO;
+export interface RunContentArgs {
+    doc: Document;
+    format: ContentFormat;
+    pages?: string;
+    includeHeaderFooter?: boolean;
+    inlineImages?: boolean;
+    out?: string;
+    force?: boolean;
+    quiet?: boolean;
+}
+/**
+ * Pure orchestration for `docs content`: takes an already-fetched
+ * Document plus user flags, produces the rendered output, and routes it
+ * through the supplied IO surface. Everything between the HTTP fetch
+ * and the side-effecting IO lives here so it can be tested without
+ * spawning the CLI binary.
+ */
+export declare function runDocsContent(args: RunContentArgs, io?: ContentIO): void;