@wafflebase/cli 0.3.5 → 0.3.7

package/dist/docs/page-range.js

@@ -0,0 +1,74 @@
+const SINGLE = /^\d+$/;
+const RANGE = /^(\d+)-(\d+)$/;
+/**
+ * Parse a `--pages` flag value (e.g., `"1-3,5,7-9"`) against a known
+ * page count.
+ *
+ * Throws `Error` on malformed input — empty strings, non-numeric tokens,
+ * a `0` page (1-based), or a reversed range (`"3-1"`). Out-of-range
+ * upper bounds are *not* errors: they get clamped to `totalPages` with a
+ * stderr-bound warning string in the result. Tokens whose entire range
+ * sits past `totalPages` collapse to no pages with a warning, never an
+ * error — this lets `--pages 1-99` work on a 3-page doc.
+ *
+ * `totalPages` of 0 is a valid input (empty doc) and yields an empty set
+ * with a single "document has no pages" warning, regardless of input.
+ */
+export function parsePageRange(input, totalPages) {
+    if (totalPages < 0) {
+        throw new Error(`parsePageRange: totalPages must be ≥ 0, got ${totalPages}`);
+    }
+    const trimmed = input.trim();
+    if (trimmed === '') {
+        throw new Error('Page range is empty.');
+    }
+    const tokens = trimmed.split(',').map((t) => t.trim());
+    for (const tok of tokens) {
+        if (tok === '') {
+            throw new Error(`Empty token in page range "${input}"`);
+        }
+    }
+    const pages = new Set();
+    const warnings = [];
+    if (totalPages === 0) {
+        warnings.push('Document has no pages.');
+        return { pages, warnings };
+    }
+    for (const tok of tokens) {
+        if (SINGLE.test(tok)) {
+            const n = Number(tok);
+            if (n < 1) {
+                throw new Error(`Page numbers are 1-based; got "${tok}"`);
+            }
+            if (n > totalPages) {
+                warnings.push(`Page ${n} is beyond document end (${totalPages}); ignored.`);
+                continue;
+            }
+            pages.add(n);
+            continue;
+        }
+        const m = RANGE.exec(tok);
+        if (!m) {
+            throw new Error(`Invalid page token "${tok}" in "${input}"`);
+        }
+        const lo = Number(m[1]);
+        const hi = Number(m[2]);
+        if (lo < 1 || hi < 1) {
+            throw new Error(`Page numbers are 1-based; got "${tok}"`);
+        }
+        if (lo > hi) {
+            throw new Error(`Reversed range "${tok}" — start must be ≤ end.`);
+        }
+        if (lo > totalPages) {
+            warnings.push(`Range ${tok} starts beyond document end (${totalPages}); ignored.`);
+            continue;
+        }
+        const clampedHi = Math.min(hi, totalPages);
+        if (clampedHi < hi) {
+            warnings.push(`Range ${tok} clamped to ${lo}-${clampedHi} (document has ${totalPages} pages).`);
+        }
+        for (let p = lo; p <= clampedHi; p++)
+            pages.add(p);
+    }
+    return { pages, warnings };
+}

package/dist/docs/page-slice.d.ts

@@ -0,0 +1,45 @@
+import type { Block, BlockPageMeta, Document, PaginatedLayout } from '@wafflebase/docs';
+import type { PageRange } from './page-range.js';
+/**
+ * Output formats supported by the CLI's `docs content --pages` flow.
+ *
+ * `'json'` keeps full structural fidelity and triggers `pageMeta`
+ * emission so consumers can recover page boundaries without re-running
+ * pagination. `'md'` and `'text'` drop the metadata since the
+ * serializers themselves are page-blind — block selection alone is
+ * enough.
+ */
+export type SliceFormat = 'json' | 'md' | 'text';
+export interface PageSliceResult {
+    /**
+     * Subset of `doc.blocks` whose layout lines intersect the requested
+     * pages, in original document order. A block that spans multiple
+     * requested pages appears exactly once.
+     */
+    blocks: Block[];
+    /**
+     * Per-block 1-based page indices for the included blocks. Present
+     * only when `format === 'json'` so the JSON serializer's `_pageMeta`
+     * field stays accurate after slicing. Always in the same order as
+     * `blocks`.
+     */
+    pageMeta?: BlockPageMeta[];
+}
+/**
+ * Select the blocks of `doc` that participate in any of the pages named
+ * by `range`, optionally producing per-block page metadata for the JSON
+ * format. Block ordering matches `doc.blocks` — the slicer never
+ * reorders content, only filters it.
+ *
+ * Selection rule (per `docs/design/docs-cli.md` §5.2): include any block
+ * whose layout has at least one line on a requested page. Blocks emit
+ * whole — there is no mid-block cut. A block that straddles the
+ * boundary between a requested page and a non-requested one still
+ * appears in the result, in full.
+ *
+ * Blocks with no layout lines (e.g., zero-height collapsed blocks the
+ * paginator omitted) drop out entirely; if a future block type needs
+ * "always include" semantics, the caller should pre-tag those blocks
+ * before calling this function.
+ */
+export declare function sliceBlocksByPages(doc: Document, layout: PaginatedLayout, range: PageRange, format: SliceFormat): PageSliceResult;

package/dist/docs/page-slice.js

@@ -0,0 +1,61 @@
+/**
+ * Select the blocks of `doc` that participate in any of the pages named
+ * by `range`, optionally producing per-block page metadata for the JSON
+ * format. Block ordering matches `doc.blocks` — the slicer never
+ * reorders content, only filters it.
+ *
+ * Selection rule (per `docs/design/docs-cli.md` §5.2): include any block
+ * whose layout has at least one line on a requested page. Blocks emit
+ * whole — there is no mid-block cut. A block that straddles the
+ * boundary between a requested page and a non-requested one still
+ * appears in the result, in full.
+ *
+ * Blocks with no layout lines (e.g., zero-height collapsed blocks the
+ * paginator omitted) drop out entirely; if a future block type needs
+ * "always include" semantics, the caller should pre-tag those blocks
+ * before calling this function.
+ */
+export function sliceBlocksByPages(doc, layout, range, format) {
+    const wantedPages = range.pages;
+    // Group all line pageIndices by blockIndex so we can both decide
+    // inclusion and reuse the lookup for `pageMeta`. Walking pages in
+    // order keeps the per-block `lines` list in document order.
+    //
+    // Duplicates are intentional: `BlockPageMeta.lines` is contractually
+    // "one entry per layout line, in order" — a block with three lines
+    // all on page 1 yields `[1, 1, 1]`. See `serialize/json.ts` for the
+    // canonical contract; the consumer is meant to count entries to
+    // recover the per-block line count, not treat the array as a set.
+    const linesByBlock = new Map();
+    for (const page of layout.pages) {
+        for (const pl of page.lines) {
+            const bucket = linesByBlock.get(pl.blockIndex);
+            if (bucket)
+                bucket.push(pl.pageIndex);
+            else
+                linesByBlock.set(pl.blockIndex, [pl.pageIndex]);
+        }
+    }
+    const blocks = [];
+    const pageMeta = [];
+    for (let i = 0; i < doc.blocks.length; i++) {
+        const lines = linesByBlock.get(i);
+        if (!lines || lines.length === 0)
+            continue;
+        let intersects = false;
+        for (const p of lines) {
+            if (wantedPages.has(p)) {
+                intersects = true;
+                break;
+            }
+        }
+        if (!intersects)
+            continue;
+        const block = doc.blocks[i];
+        blocks.push(block);
+        if (format === 'json') {
+            pageMeta.push({ blockId: block.id, lines });
+        }
+    }
+    return format === 'json' ? { blocks, pageMeta } : { blocks };
+}

package/dist/docs/paginate.d.ts

@@ -0,0 +1,13 @@
+import { type Document, type PaginatedLayout, type TextMeasurer } from '@wafflebase/docs';
+/**
+ * Run `computeLayout` + `paginateLayout` for a fetched `Document` using
+ * the supplied measurer. The CLI calls this only when `--pages` is set
+ * (or any other flag that needs page boundaries) — the bare `docs
+ * content` JSON path skips pagination entirely.
+ *
+ * Page setup falls back to `DEFAULT_PAGE_SETUP` (US Letter portrait, 1in
+ * margins) when the document doesn't carry one. Content width is the
+ * effective page width minus left/right margins, matching what the
+ * editor's `DocCanvas` computes.
+ */
+export declare function paginateForCli(doc: Document, measurer: TextMeasurer): PaginatedLayout;

package/dist/docs/paginate.js

@@ -0,0 +1,19 @@
+import { computeLayout, paginateLayout, resolvePageSetup, getEffectiveDimensions, } from '@wafflebase/docs';
+/**
+ * Run `computeLayout` + `paginateLayout` for a fetched `Document` using
+ * the supplied measurer. The CLI calls this only when `--pages` is set
+ * (or any other flag that needs page boundaries) — the bare `docs
+ * content` JSON path skips pagination entirely.
+ *
+ * Page setup falls back to `DEFAULT_PAGE_SETUP` (US Letter portrait, 1in
+ * margins) when the document doesn't carry one. Content width is the
+ * effective page width minus left/right margins, matching what the
+ * editor's `DocCanvas` computes.
+ */
+export function paginateForCli(doc, measurer) {
+    const pageSetup = resolvePageSetup(doc.pageSetup);
+    const { width: paperWidth } = getEffectiveDimensions(pageSetup);
+    const contentWidth = paperWidth - pageSetup.margins.left - pageSetup.margins.right;
+    const { layout } = computeLayout(doc.blocks, measurer, contentWidth);
+    return paginateLayout(layout, pageSetup);
+}

package/dist/docs/pdf-export.d.ts

@@ -0,0 +1,38 @@
+import { type Document, type PdfFontsOptions } from '@wafflebase/docs';
+import type { PageRange } from './page-range.js';
+/**
+ * Options for the CLI PDF export pipeline.
+ *
+ * `pages` is the resolved selection from `parsePageRange`; when present
+ * we render the full PDF first and then strip non-selected pages via
+ * `pdf-lib` (cheaper than re-implementing a partial paint path inside
+ * `PdfExporter`). The future plan is to push a `pageIndices` option
+ * down into `PdfExporter` itself; for now the post-process is correct
+ * but pays for layout/paint work it then throws away.
+ *
+ * `fontSources` lets tests inject in-memory buffers via `PdfFonts` so
+ * `exportPdf` can run without hitting jsdelivr.
+ */
+export interface CliPdfExportOptions {
+    pages?: PageRange;
+    /** Currently informational — `PdfExporter` always paints
+     *  header/footer when `doc.header`/`doc.footer` are present. The CLI
+     *  surfaces the flag for parity with `docs export --include-header-footer`
+     *  and to leave room for a future "strip header/footer" mode. */
+    includeHeaderFooter?: boolean;
+    fontSources?: PdfFontsOptions['sources'];
+}
+/**
+ * Render `doc` to a PDF byte buffer using the same `PdfExporter` the
+ * editor uses, with a `fontkit`-backed measurer in place of the browser
+ * Canvas measurer. Korean fonts referenced by the document are
+ * pre-loaded through `PdfFonts` and registered with the measurer so
+ * pagination matches what the painter then draws.
+ *
+ * Latin text falls back to the measurer's coarse 0.5em estimate
+ * (Helvetica/Times metrics aren't bundled). Pure-ASCII docs may
+ * therefore line-break differently in the CLI than in the browser; the
+ * paint output stays correct because `PdfPainter` uses pdf-lib's
+ * StandardFonts at draw time.
+ */
+export declare function exportPdf(doc: Document, opts?: CliPdfExportOptions): Promise<Uint8Array>;

package/dist/docs/pdf-export.js

@@ -0,0 +1,91 @@
+import { PDFDocument } from 'pdf-lib';
+import { PdfExporter, PdfFonts, scanFontsUsed, } from '@wafflebase/docs';
+import { FontkitMeasurer } from './fontkit-measurer.js';
+/**
+ * Render `doc` to a PDF byte buffer using the same `PdfExporter` the
+ * editor uses, with a `fontkit`-backed measurer in place of the browser
+ * Canvas measurer. Korean fonts referenced by the document are
+ * pre-loaded through `PdfFonts` and registered with the measurer so
+ * pagination matches what the painter then draws.
+ *
+ * Latin text falls back to the measurer's coarse 0.5em estimate
+ * (Helvetica/Times metrics aren't bundled). Pure-ASCII docs may
+ * therefore line-break differently in the CLI than in the browser; the
+ * paint output stays correct because `PdfPainter` uses pdf-lib's
+ * StandardFonts at draw time.
+ */
+export async function exportPdf(doc, opts = {}) {
+    const usage = scanFontsUsed(doc);
+    const fonts = new PdfFonts({ sources: opts.fontSources });
+    const measurer = new FontkitMeasurer();
+    await preloadKoreanFonts(fonts, measurer, usage);
+    const blob = await PdfExporter.export(doc, { measurer, fonts });
+    const fullBytes = new Uint8Array(await blob.arrayBuffer());
+    if (!opts.pages || opts.pages.pages.size === 0) {
+        return fullBytes;
+    }
+    return extractPages(fullBytes, opts.pages);
+}
+/**
+ * Load every Korean variant `usage` reports as needed and register each
+ * loaded buffer with the measurer under both the canonical `'Noto …'`
+ * family name and the editor-side aliases (`바탕`, `Batang`) so inline
+ * styles that pick a non-canonical family still hit a real font instead
+ * of the fallback estimate.
+ */
+async function preloadKoreanFonts(fonts, measurer, usage) {
+    const variants = [];
+    if (usage.needsKR) {
+        variants.push({
+            key: 'kr-sans-regular',
+            weight: 'normal',
+            families: ['Noto Sans KR'],
+        });
+    }
+    if (usage.needsKR && usage.needsBold) {
+        variants.push({
+            key: 'kr-sans-bold',
+            weight: 'bold',
+            families: ['Noto Sans KR'],
+        });
+    }
+    if (usage.needsKRSerif) {
+        variants.push({
+            key: 'kr-serif-regular',
+            weight: 'normal',
+            families: ['Noto Serif KR', '바탕', 'Batang'],
+        });
+    }
+    if (usage.needsKRSerif && usage.needsBold) {
+        variants.push({
+            key: 'kr-serif-bold',
+            weight: 'bold',
+            families: ['Noto Serif KR', '바탕', 'Batang'],
+        });
+    }
+    for (const v of variants) {
+        const buf = await fonts.load(v.key);
+        for (const family of v.families) {
+            measurer.register(family, v.weight, 'normal', buf);
+        }
+    }
+}
+/**
+ * Keep only the pages named by `range` and return the new PDF bytes.
+ *
+ * Iterates from the highest index down so each `removePage(idx)` call
+ * doesn't shift the indices of pages we haven't visited yet. Pages in
+ * `range.pages` are 1-based; pdf-lib indexes from 0.
+ */
+async function extractPages(bytes, range) {
+    const pdf = await PDFDocument.load(bytes);
+    const total = pdf.getPageCount();
+    for (let i = total - 1; i >= 0; i--) {
+        const oneBased = i + 1;
+        if (!range.pages.has(oneBased)) {
+            pdf.removePage(i);
+        }
+    }
+    const out = await pdf.save();
+    return out;
+}

package/dist/output/binary.d.ts

@@ -0,0 +1,37 @@
+export interface WriteBinaryOptions {
+    /** Allow overwriting an existing file. Without this flag, `writeBinary`
+     *  refuses to clobber and throws. Mirrors `--force` on the CLI. */
+    force?: boolean;
+    /** Suppress informational stderr output. The bytes themselves still
+     *  reach stdout/the file regardless of this flag. */
+    quiet?: boolean;
+}
+/**
+ * Write `bytes` to `target`, where `target` is either a filesystem path
+ * or `'-'` for stdout. The default behavior refuses to overwrite an
+ * existing file because exports are usually irreversible (the source
+ * doc is the canonical store but a stale local copy can still mislead).
+ *
+ * The function is split out from the command action so binary output
+ * paths can be unit-tested without spawning the CLI binary; the action
+ * supplies real `process.stdout.write` and the IO surface forwards it.
+ *
+ * The default `writeFile` honors `force` via the `'w'` (overwrite) /
+ * `'wx'` (exclusive create) `fs` flags, folding the existence check
+ * and the write into a single syscall — avoids a TOCTOU window where
+ * something else could create the file between the check and the
+ * write.
+ */
+export declare function writeBinary(bytes: Uint8Array, target: string, opts?: WriteBinaryOptions, io?: BinaryIO): void;
+export interface BinaryIO {
+    stdout: (bytes: Uint8Array) => void;
+    stderr: (line: string) => void;
+    /**
+     * Write `bytes` to `path`. When `force` is `false`, the
+     * implementation MUST refuse to overwrite an existing file and
+     * throw — the production `defaultBinaryIO` does this via the
+     * exclusive-create `'wx'` flag.
+     */
+    writeFile: (path: string, bytes: Uint8Array, force: boolean) => void;
+}
+export declare const defaultBinaryIO: BinaryIO;

package/dist/output/binary.js

@@ -0,0 +1,47 @@
+import { writeFileSync } from 'node:fs';
+/**
+ * Write `bytes` to `target`, where `target` is either a filesystem path
+ * or `'-'` for stdout. The default behavior refuses to overwrite an
+ * existing file because exports are usually irreversible (the source
+ * doc is the canonical store but a stale local copy can still mislead).
+ *
+ * The function is split out from the command action so binary output
+ * paths can be unit-tested without spawning the CLI binary; the action
+ * supplies real `process.stdout.write` and the IO surface forwards it.
+ *
+ * The default `writeFile` honors `force` via the `'w'` (overwrite) /
+ * `'wx'` (exclusive create) `fs` flags, folding the existence check
+ * and the write into a single syscall — avoids a TOCTOU window where
+ * something else could create the file between the check and the
+ * write.
+ */
+export function writeBinary(bytes, target, opts = {}, io = defaultBinaryIO) {
+    if (target === '-') {
+        io.stdout(bytes);
+        return;
+    }
+    io.writeFile(target, bytes, opts.force === true);
+    if (!opts.quiet)
+        io.stderr(`Wrote ${bytes.length} bytes to ${target}`);
+}
+export const defaultBinaryIO = {
+    stdout: (bytes) => {
+        process.stdout.write(bytes);
+    },
+    stderr: (line) => {
+        console.error(line);
+    },
+    writeFile: (path, bytes, force) => {
+        try {
+            writeFileSync(path, bytes, { flag: force ? 'w' : 'wx' });
+        }
+        catch (err) {
+            if (err instanceof Error &&
+                'code' in err &&
+                err.code === 'EEXIST') {
+                throw new Error(`Refusing to overwrite "${path}". Pass --force to allow overwrite.`);
+            }
+            throw err;
+        }
+    },
+};

package/dist/output/formatter.js

@@ -16,12 +16,26 @@ export function output(data, fmt, quiet) {
         return;
     console.log(format(data, fmt));
 }
+/**
+ * Preserve a structured `code` from any thrown `Error` subclass that
+ * carries one (e.g., `InvalidDocxError`'s `code = 'INVALID_DOCX'`).
+ * Skill files document those codes, so silently flattening every
+ * failure to `'ERROR'` made agents unable to branch on the cause.
+ */
+function errorCode(error) {
+    if (error instanceof Error && 'code' in error) {
+        const code = error.code;
+        if (typeof code === 'string' && code.length > 0)
+            return code;
+    }
+    return 'ERROR';
+}
 export function outputError(error, quiet) {
     if (quiet) {
         process.exitCode = 1;
         return;
     }
     const message = error instanceof Error ? error.message : String(error);
-    console.error(JSON.stringify({ error: { code: 'ERROR', message } }, null, 2));
+    console.error(JSON.stringify({ error: { code: errorCode(error), message } }, null, 2));
     process.exitCode = 1;
 }

package/dist/schema/registry.d.ts

@@ -1,4 +1,17 @@
 export type SafetyLevel = 'read-only' | 'write' | 'destructive';
+/**
+ * Per-command safety variant — used by `docs.import` to spell out that
+ * the same command is `write` by default but `destructive` with
+ * `--replace`. Skill agents read this to decide when extra confirmation
+ * is needed.
+ */
+export interface SafetyVariant {
+    when: string;
+    safety: SafetyLevel;
+    creates?: string;
+    modifies?: string;
+    removes?: string;
+}
 export interface CommandSchema {
     name: string;
     description: string;
@@ -10,6 +23,20 @@ export interface CommandSchema {
         default?: string;
     }>;
     response: Record<string, unknown>;
+    /**
+     * Singular / legacy / namespace-stripped names that should resolve to
+     * this canonical entry. `getCommandSchema('cell.get')` returns the
+     * `sheets.cells.get` schema because `'cell.get'` appears here.
+     */
+    aliases?: string[];
+    /** Optional per-flag safety overrides (currently only `docs.import`). */
+    variants?: SafetyVariant[];
 }
+/**
+ * Look up a schema entry by canonical name or any registered alias.
+ * Aliases let scripts and skills written against the v0.3.x singular
+ * names (`cell.get`, `doc.list`, `import`) keep working after the
+ * v0.3.7 namespace shuffle.
+ */
 export declare function getCommandSchema(name: string): CommandSchema | undefined;
 export declare function getAllCommandSchemas(): CommandSchema[];