@wafflebase/cli 0.3.5 → 0.3.7

package/dist/docs/content.js

@@ -0,0 +1,90 @@
+import { writeFileSync, existsSync } from 'node:fs';
+import { serializeJson, serializeMarkdown, serializeText, } from '@wafflebase/docs';
+import { FontkitMeasurer } from './fontkit-measurer.js';
+import { parsePageRange } from './page-range.js';
+import { sliceBlocksByPages } from './page-slice.js';
+import { paginateForCli } from './paginate.js';
+export const VALID_CONTENT_FORMATS = ['json', 'md', 'text'];
+export const LOSSY_NOTICE = 'Lossy conversion: see docs-cli design for the exact mapping';
+export const PAGES_FONT_WARNING = 'Note: --pages uses approximate pagination (no document fonts loaded). ' +
+    'Page boundaries may drift on CJK or font-heavy documents — ' +
+    'use `docs export pdf --pages` for exact subsets.';
+export function parseContentFormat(value) {
+    if (!VALID_CONTENT_FORMATS.includes(value)) {
+        throw new Error(`Invalid --format "${value}". Use one of: ${VALID_CONTENT_FORMATS.join(', ')}.`);
+    }
+    return value;
+}
+export const defaultIO = {
+    stdout: (text) => {
+        process.stdout.write(text);
+        if (!text.endsWith('\n'))
+            process.stdout.write('\n');
+    },
+    stderr: (line) => {
+        console.error(line);
+    },
+    writeFile: (path, text, force) => {
+        if (existsSync(path) && !force) {
+            throw new Error(`Refusing to overwrite "${path}". Pass --force to allow overwrite.`);
+        }
+        writeFileSync(path, text.endsWith('\n') ? text : text + '\n', 'utf-8');
+    },
+};
+/**
+ * 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 function runDocsContent(args, io = defaultIO) {
+    const { format, pages, includeHeaderFooter = false, inlineImages = false, out, force = false, quiet = false, } = args;
+    let working = args.doc;
+    let layout;
+    if (pages) {
+        const measurer = new FontkitMeasurer();
+        // `docs content --pages` paginates with a font-less measurer, so
+        // every glyph falls back to the 0.5em estimate. That's accurate
+        // enough for ASCII-heavy docs but underestimates CJK by ~50% and
+        // mis-sizes narrow glyphs (`i`, `:`, `.`) — page boundaries can
+        // drift by ±1 page on real documents. `docs export pdf` doesn't
+        // suffer from this because PdfPainter does its own measurement at
+        // paint time. Pre-loading document fonts here is tracked as a
+        // follow-up; until then we surface the limitation on stderr.
+        if (!quiet) {
+            io.stderr(PAGES_FONT_WARNING);
+        }
+        const fullLayout = paginateForCli(working, measurer);
+        const range = parsePageRange(pages, fullLayout.pages.length);
+        if (!quiet) {
+            for (const w of range.warnings)
+                io.stderr(w);
+        }
+        const slice = sliceBlocksByPages(working, fullLayout, range, format);
+        working = { ...working, blocks: slice.blocks };
+        layout = fullLayout;
+    }
+    if (format === 'md' && !quiet) {
+        io.stderr(LOSSY_NOTICE);
+    }
+    let text;
+    switch (format) {
+        case 'json':
+            text = JSON.stringify(serializeJson(working, layout), null, 2);
+            break;
+        case 'md':
+            text = serializeMarkdown(working, { includeHeaderFooter, inlineImages });
+            break;
+        case 'text':
+            text = serializeText(working, { includeHeaderFooter });
+            break;
+    }
+    if (!out || out === '-') {
+        io.stdout(text);
+        return;
+    }
+    io.writeFile(out, text, force);
+    if (!quiet)
+        io.stderr(`Wrote to ${out}`);
+}

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

@@ -0,0 +1,23 @@
+import { type Document, type DocxImageFetcher } from '@wafflebase/docs';
+export interface CliDocxExportOptions {
+    /** Mirrors `--include-header-footer`; informational only — DOCX always
+     *  emits the document's `header` / `footer` regions when they exist. */
+    includeHeaderFooter?: boolean;
+    /** Test seam: provide a stub image fetcher so `exportDocx` doesn't
+     *  reach out to the network for image inlines. The aliased
+     *  `DocxImageFetcher` (vs. the bare `ImageFetcher`) survives the
+     *  Node-bundle resolution path; the bare alias only exists on the
+     *  browser bundle, so importing it would silently break under any TS
+     *  config that prefers the `node` exports condition. */
+    imageFetcher?: DocxImageFetcher;
+}
+/**
+ * Render `doc` to a `.docx` byte buffer via the shared `DocxExporter`.
+ *
+ * `--pages` is intentionally not handled here — the design (§5.2) says
+ * the docx path warns and ignores it; the CLI command emits that
+ * warning before calling this function so the helper itself stays a
+ * pure renderer. Throws if the document contains image inlines and no
+ * `imageFetcher` is supplied (matching `DocxExporter.export` behavior).
+ */
+export declare function exportDocx(doc: Document, opts?: CliDocxExportOptions): Promise<Uint8Array>;

package/dist/docs/docx-export.js

@@ -0,0 +1,14 @@
+import { DocxExporter, } from '@wafflebase/docs';
+/**
+ * Render `doc` to a `.docx` byte buffer via the shared `DocxExporter`.
+ *
+ * `--pages` is intentionally not handled here — the design (§5.2) says
+ * the docx path warns and ignores it; the CLI command emits that
+ * warning before calling this function so the helper itself stays a
+ * pure renderer. Throws if the document contains image inlines and no
+ * `imageFetcher` is supplied (matching `DocxExporter.export` behavior).
+ */
+export async function exportDocx(doc, opts = {}) {
+    const blob = await DocxExporter.export(doc, opts.imageFetcher);
+    return new Uint8Array(await blob.arrayBuffer());
+}

package/dist/docs/docx-import.d.ts

@@ -0,0 +1,36 @@
+import './dom-polyfill.js';
+import { type Document, type ImageUploader } from '@wafflebase/docs';
+/**
+ * Default `ImageUploader` for the CLI: encodes each image inline as a
+ * `data:` URL. The Yorkie store treats inline-image `src` values as
+ * opaque strings, so a self-contained data URL round-trips cleanly
+ * without needing a backend image upload endpoint.
+ *
+ * The MIME type is derived from the filename's extension (matching what
+ * `DocxImporter` infers from `.rels` content types). Unknown
+ * extensions fall back to `application/octet-stream` — pdf-lib /
+ * browser image rendering will refuse to display those, but at least
+ * the document round-trip stays lossless at the JSON layer.
+ */
+export declare const inlineBase64Uploader: ImageUploader;
+export interface CliDocxImportOptions {
+    /** Override the default base64 uploader — primarily for tests. */
+    imageUploader?: ImageUploader;
+}
+/**
+ * Parse a .docx byte buffer into a `Document` using the editor's
+ * `DocxImporter`. The polyfill side-effect import at the top of this
+ * file installs `DOMParser` from `@xmldom/xmldom` so the importer's
+ * browser-targeted XML parsing works in Node.
+ *
+ * Throws a wrapped `INVALID_DOCX` error when the underlying importer
+ * cannot make sense of the buffer (missing `word/document.xml`,
+ * malformed XML, unsupported zip layout). The CLI command translates
+ * the wrapper into the documented `{ error.code: 'INVALID_DOCX' }`
+ * exit body without leaking implementation details.
+ */
+export declare function importDocx(buf: Uint8Array, opts?: CliDocxImportOptions): Promise<Document>;
+export declare class InvalidDocxError extends Error {
+    readonly code = "INVALID_DOCX";
+    constructor(message: string);
+}

package/dist/docs/docx-import.js

@@ -0,0 +1,70 @@
+import './dom-polyfill.js';
+import { DocxImporter, } from '@wafflebase/docs';
+/**
+ * Default `ImageUploader` for the CLI: encodes each image inline as a
+ * `data:` URL. The Yorkie store treats inline-image `src` values as
+ * opaque strings, so a self-contained data URL round-trips cleanly
+ * without needing a backend image upload endpoint.
+ *
+ * The MIME type is derived from the filename's extension (matching what
+ * `DocxImporter` infers from `.rels` content types). Unknown
+ * extensions fall back to `application/octet-stream` — pdf-lib /
+ * browser image rendering will refuse to display those, but at least
+ * the document round-trip stays lossless at the JSON layer.
+ */
+export const inlineBase64Uploader = async (blob, filename) => {
+    const arrayBuf = await blob.arrayBuffer();
+    const base64 = Buffer.from(arrayBuf).toString('base64');
+    const mime = blob.type || mimeFromFilename(filename) || 'application/octet-stream';
+    return `data:${mime};base64,${base64}`;
+};
+function mimeFromFilename(filename) {
+    const dot = filename.lastIndexOf('.');
+    if (dot < 0)
+        return undefined;
+    const ext = filename.slice(dot + 1).toLowerCase();
+    switch (ext) {
+        case 'png':
+            return 'image/png';
+        case 'jpg':
+        case 'jpeg':
+            return 'image/jpeg';
+        case 'gif':
+            return 'image/gif';
+        case 'webp':
+            return 'image/webp';
+        case 'bmp':
+            return 'image/bmp';
+        default:
+            return undefined;
+    }
+}
+/**
+ * Parse a .docx byte buffer into a `Document` using the editor's
+ * `DocxImporter`. The polyfill side-effect import at the top of this
+ * file installs `DOMParser` from `@xmldom/xmldom` so the importer's
+ * browser-targeted XML parsing works in Node.
+ *
+ * Throws a wrapped `INVALID_DOCX` error when the underlying importer
+ * cannot make sense of the buffer (missing `word/document.xml`,
+ * malformed XML, unsupported zip layout). The CLI command translates
+ * the wrapper into the documented `{ error.code: 'INVALID_DOCX' }`
+ * exit body without leaking implementation details.
+ */
+export async function importDocx(buf, opts = {}) {
+    const arrayBuf = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+    try {
+        return await DocxImporter.import(arrayBuf, opts.imageUploader ?? inlineBase64Uploader);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        throw new InvalidDocxError(message);
+    }
+}
+export class InvalidDocxError extends Error {
+    code = 'INVALID_DOCX';
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidDocxError';
+    }
+}

package/dist/docs/dom-polyfill.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/docs/dom-polyfill.js

@@ -0,0 +1,29 @@
+import { DOMParser as XmldomParser } from '@xmldom/xmldom';
+/**
+ * Make `DOMParser` available globally so `@wafflebase/docs`'s
+ * `DocxImporter` can call `new DOMParser()` from a Node CLI process.
+ *
+ * `DocxImporter` was originally written for the browser and parses
+ * `.docx` XML through the WHATWG DOMParser. Node has no built-in DOM,
+ * so we substitute `@xmldom/xmldom`'s implementation — it's an XML-only
+ * parser (no HTML quirks, no full DOM tree mutation) but covers the
+ * `getElementsByTagNameNS` / `textContent` / `getAttribute` surface the
+ * importer actually touches.
+ *
+ * The shim is idempotent: if a real `DOMParser` is already present
+ * (jsdom-environment tests, future Node releases that ship one) we
+ * leave it alone so production code continues to use the more featureful
+ * implementation.
+ *
+ * Side-effect import — bring this file in *before* any code path that
+ * calls `DocxImporter.import`.
+ */
+const g = globalThis;
+if (typeof g.DOMParser === 'undefined') {
+    // Assign through an `unknown` cast because `@xmldom/xmldom`'s
+    // `DOMParser` shape is a runtime superset of WHATWG's but uses its
+    // own type declarations. `DocxImporter` only consumes the XML subset
+    // both implementations share, so the runtime contract holds even
+    // though the static types don't unify.
+    g.DOMParser = XmldomParser;
+}

package/dist/docs/fontkit-measurer.d.ts

@@ -0,0 +1,41 @@
+import { Buffer } from 'node:buffer';
+import type { TextMeasurer, ResolvedFont } from '@wafflebase/docs';
+export interface FontkitMeasurerOptions {
+    /**
+     * Width per character in em-units used when no font is registered for
+     * the requested variant. Multiplied by `font.size` to produce a px value.
+     * Defaults to `0.5` — a coarse proportional-font approximation that
+     * keeps pagination from collapsing to zero when a font is missing.
+     *
+     * Callers that pre-load every font referenced by a document never hit
+     * this path; the fallback exists so a single missing variant does not
+     * crash the CLI mid-pagination.
+     */
+    fallbackEmWidth?: number;
+}
+/**
+ * `TextMeasurer` backed by `fontkit` for use in Node CLI contexts where
+ * no Canvas 2D API is available. Width is computed as
+ * `glyphRun.advanceWidth ÷ unitsPerEm × size` for each registered font.
+ *
+ * Measurement is synchronous; callers must `register()` every font
+ * variant they need *before* invoking `paginateLayout` / `measureWidth`.
+ * Loading is async (file/network IO) but the layout pipeline is not, so
+ * we split the two phases.
+ */
+export declare class FontkitMeasurer implements TextMeasurer {
+    private readonly fonts;
+    private readonly fallbackEmWidth;
+    constructor(opts?: FontkitMeasurerOptions);
+    /**
+     * Register a font buffer for a specific variant. Subsequent
+     * `measureWidth` calls whose `(family, weight, style)` matches will use
+     * this font's metrics. A `FontCollection` (.ttc) input is rejected
+     * here — the caller must pick the desired face out of the collection
+     * first to keep the cache key unambiguous.
+     */
+    register(family: string, weight: ResolvedFont['weight'], style: ResolvedFont['style'], buffer: Uint8Array | ArrayBuffer | Buffer): void;
+    /** True when the variant has a registered font (no fallback path). */
+    has(family: string, weight: ResolvedFont['weight'], style: ResolvedFont['style']): boolean;
+    measureWidth(text: string, font: ResolvedFont): number;
+}

package/dist/docs/fontkit-measurer.js

@@ -0,0 +1,64 @@
+import { Buffer } from 'node:buffer';
+import * as fontkit from 'fontkit';
+/**
+ * Variant key for the in-memory font cache. Lowercased family name plus
+ * weight/style ensures `'Helvetica'` and `'helvetica'` resolve to the same
+ * registered buffer — Canvas measurement is case-insensitive on family
+ * lookups, so we mirror that here so the CLI matches browser pagination.
+ */
+function variantKey(family, weight, style) {
+    return `${family.toLowerCase()}|${weight}|${style}`;
+}
+/**
+ * `TextMeasurer` backed by `fontkit` for use in Node CLI contexts where
+ * no Canvas 2D API is available. Width is computed as
+ * `glyphRun.advanceWidth ÷ unitsPerEm × size` for each registered font.
+ *
+ * Measurement is synchronous; callers must `register()` every font
+ * variant they need *before* invoking `paginateLayout` / `measureWidth`.
+ * Loading is async (file/network IO) but the layout pipeline is not, so
+ * we split the two phases.
+ */
+export class FontkitMeasurer {
+    fonts = new Map();
+    fallbackEmWidth;
+    constructor(opts = {}) {
+        this.fallbackEmWidth = opts.fallbackEmWidth ?? 0.5;
+    }
+    /**
+     * Register a font buffer for a specific variant. Subsequent
+     * `measureWidth` calls whose `(family, weight, style)` matches will use
+     * this font's metrics. A `FontCollection` (.ttc) input is rejected
+     * here — the caller must pick the desired face out of the collection
+     * first to keep the cache key unambiguous.
+     */
+    register(family, weight, style, buffer) {
+        const buf = toBuffer(buffer);
+        const parsed = fontkit.create(buf);
+        if ('fonts' in parsed) {
+            throw new Error(`FontkitMeasurer.register("${family}"): TrueType collections (.ttc) ` +
+                `must be split into individual faces before registration.`);
+        }
+        this.fonts.set(variantKey(family, weight, style), parsed);
+    }
+    /** True when the variant has a registered font (no fallback path). */
+    has(family, weight, style) {
+        return this.fonts.has(variantKey(family, weight, style));
+    }
+    measureWidth(text, font) {
+        if (text.length === 0)
+            return 0;
+        const f = this.fonts.get(variantKey(font.family, font.weight, font.style));
+        if (!f)
+            return text.length * this.fallbackEmWidth * font.size;
+        const run = f.layout(text);
+        return (run.advanceWidth / f.unitsPerEm) * font.size;
+    }
+}
+function toBuffer(input) {
+    if (Buffer.isBuffer(input))
+        return input;
+    if (input instanceof ArrayBuffer)
+        return Buffer.from(new Uint8Array(input));
+    return Buffer.from(input);
+}

package/dist/docs/import.d.ts

@@ -0,0 +1,72 @@
+import type { Document, ImageUploader } from '@wafflebase/docs';
+/**
+ * Minimal HTTP surface `runDocsImport` needs from the CLI's
+ * `HttpClient`. Spelled out so tests can pass a stub without depending
+ * on the full client.
+ */
+export interface ImportClient {
+    createDocument: (title: string, type?: 'doc' | 'sheet') => Promise<{
+        ok: boolean;
+        status: number;
+        data: unknown;
+    }>;
+    putDocContent: (docId: string, doc: Document) => Promise<{
+        ok: boolean;
+        status: number;
+        data: unknown;
+    }>;
+}
+export interface ImportIO {
+    /** Final structured payload — written to stdout as JSON. */
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+    /**
+     * Read the docx bytes for `path`. `'-'` reads from stdin.
+     *
+     * Split out so tests can inject in-memory buffers without juggling
+     * tmp files; the default reads `process.stdin` (or the file
+     * synchronously) at the action site.
+     */
+    readBytes: (path: string) => Promise<Uint8Array>;
+    /**
+     * Prompt the user for a yes/no answer when running interactively.
+     * Returns `true` for affirmative responses (case-insensitive `y` /
+     * `yes`); anything else (including end-of-stream) → `false`.
+     */
+    confirm: (prompt: string) => Promise<boolean>;
+    /** Whether the current process is interactive (a TTY on stdin).   *  Tests inject `false` to exercise the non-interactive branches. */
+    isTTY: boolean;
+}
+export declare const defaultImportIO: ImportIO;
+export interface RunImportArgs {
+    /** Source path. `'-'` reads from stdin. */
+    file: string;
+    /** Override the doc title. Falls back to the file basename. */
+    title?: string;
+    /** Existing document ID to overwrite. Pairs with `--yes`. */
+    replace?: string;
+    /** Skip the interactive `--replace` confirmation. */
+    yes?: boolean;
+    /** Override the default base64 image uploader. Tests pass a no-op. */
+    imageUploader?: ImageUploader;
+    /** Suppress informational stderr output (errors still reported). */
+    quiet?: boolean;
+    /** Print the request that *would* fire instead of issuing it. */
+    dryRun?: boolean;
+}
+export interface RunImportResult {
+    /** Process exit code. The action sets `process.exitCode` accordingly. */
+    exitCode: number;
+}
+/**
+ * Pure orchestration for `docs import`. Reads the source `.docx`,
+ * parses it into a `Document`, then either creates a new document
+ * (default) or overwrites an existing one (`--replace`).
+ *
+ * Why split out from the command action: the action's layered handling
+ * of stdin / TTY / interactive prompt is the easiest path to test
+ * regressions in. Mocking `process.stdin` at the harness level is
+ * fragile; passing in an `ImportIO` lets us drive every branch
+ * deterministically.
+ */
+export declare function runDocsImport(args: RunImportArgs, client: ImportClient, io?: ImportIO): Promise<RunImportResult>;

package/dist/docs/import.js

@@ -0,0 +1,146 @@
+import { readFileSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { importDocx, InvalidDocxError } from './docx-import.js';
+export const defaultImportIO = {
+    stdout: (line) => {
+        process.stdout.write(line);
+        if (!line.endsWith('\n'))
+            process.stdout.write('\n');
+    },
+    stderr: (line) => {
+        console.error(line);
+    },
+    readBytes: async (path) => {
+        if (path === '-') {
+            return new Promise((resolve, reject) => {
+                const chunks = [];
+                process.stdin.on('data', (c) => chunks.push(c));
+                process.stdin.on('end', () => resolve(new Uint8Array(Buffer.concat(chunks))));
+                process.stdin.on('error', reject);
+            });
+        }
+        return new Uint8Array(readFileSync(path));
+    },
+    confirm: (prompt) => {
+        return new Promise((resolve) => {
+            const rl = createInterface({ input: process.stdin, output: process.stderr });
+            rl.question(prompt, (answer) => {
+                rl.close();
+                const a = answer.trim().toLowerCase();
+                resolve(a === 'y' || a === 'yes');
+            });
+        });
+    },
+    isTTY: process.stdin.isTTY ?? false,
+};
+/**
+ * Pure orchestration for `docs import`. Reads the source `.docx`,
+ * parses it into a `Document`, then either creates a new document
+ * (default) or overwrites an existing one (`--replace`).
+ *
+ * Why split out from the command action: the action's layered handling
+ * of stdin / TTY / interactive prompt is the easiest path to test
+ * regressions in. Mocking `process.stdin` at the harness level is
+ * fragile; passing in an `ImportIO` lets us drive every branch
+ * deterministically.
+ */
+export async function runDocsImport(args, client, io = defaultImportIO) {
+    const { file, replace, yes = false, imageUploader, quiet = false, dryRun = false } = args;
+    const inferredTitle = args.title ?? defaultTitleFor(file);
+    if (replace) {
+        // `--replace` is destructive: confirm interactively unless `--yes`.
+        if (!yes) {
+            if (!io.isTTY) {
+                io.stderr(JSON.stringify({
+                    error: {
+                        code: 'CONFIRMATION_REQ',
+                        message: `Pass --yes to confirm replacing document "${replace}".`,
+                    },
+                }, null, 2));
+                return { exitCode: 1 };
+            }
+            const ok = await io.confirm(`This will replace content of ${replace}. Continue? [y/N] `);
+            if (!ok) {
+                if (!quiet)
+                    io.stderr('Aborted.');
+                return { exitCode: 0 };
+            }
+        }
+        const buf = await io.readBytes(file);
+        const parsed = await safeImportDocx(buf, imageUploader, io);
+        if (parsed === null)
+            return { exitCode: 1 };
+        const doc = parsed;
+        if (dryRun) {
+            io.stdout(JSON.stringify({ method: 'PUT', path: `/documents/${replace}/content`, body: doc }, null, 2));
+            return { exitCode: 0 };
+        }
+        const res = await client.putDocContent(replace, doc);
+        if (!res.ok) {
+            io.stderr(JSON.stringify(res.data ?? { error: { code: 'HTTP_ERROR' } }, null, 2));
+            return { exitCode: 1 };
+        }
+        io.stdout(JSON.stringify({ id: replace, replaced: true }, null, 2));
+        return { exitCode: 0 };
+    }
+    // Default flow: POST + PUT.
+    const buf = await io.readBytes(file);
+    const parsedNew = await safeImportDocx(buf, imageUploader, io);
+    if (parsedNew === null)
+        return { exitCode: 1 };
+    const doc = parsedNew;
+    if (dryRun) {
+        io.stdout(JSON.stringify({
+            method: 'POST',
+            path: '/documents',
+            body: { title: inferredTitle, type: 'doc' },
+            followUp: { method: 'PUT', path: '/documents/<new-id>/content' },
+        }, null, 2));
+        return { exitCode: 0 };
+    }
+    const created = await client.createDocument(inferredTitle, 'doc');
+    if (!created.ok) {
+        io.stderr(JSON.stringify(created.data ?? { error: { code: 'HTTP_ERROR' } }, null, 2));
+        return { exitCode: 1 };
+    }
+    const newId = created.data?.id;
+    if (!newId) {
+        io.stderr(JSON.stringify({ error: { code: 'INVALID_RESPONSE', message: 'Server did not return an id' } }, null, 2));
+        return { exitCode: 1 };
+    }
+    const put = await client.putDocContent(newId, doc);
+    if (!put.ok) {
+        io.stderr(JSON.stringify(put.data ?? { error: { code: 'HTTP_ERROR' } }, null, 2));
+        return { exitCode: 1 };
+    }
+    io.stdout(JSON.stringify({ id: newId, title: inferredTitle }, null, 2));
+    return { exitCode: 0 };
+}
+/** Strip the directory and extension to produce a default doc title. */
+function defaultTitleFor(file) {
+    if (file === '-')
+        return 'Untitled';
+    return basename(file, extname(file)) || 'Untitled';
+}
+/**
+ * Run `importDocx` and turn `InvalidDocxError` into a structured
+ * stderr body + `null` return so callers can short-circuit with
+ * `exitCode: 1` while keeping the rest of the error envelope
+ * (`HTTP_ERROR`, `INVALID_RESPONSE`, etc.) consistent. The action's
+ * `outputError` would technically also surface the error code today
+ * (post-B1), but catching here keeps the contract local to this file
+ * and matches every other failure path in `runDocsImport`.
+ */
+async function safeImportDocx(buf, imageUploader, io) {
+    try {
+        return await importDocx(buf, { imageUploader });
+    }
+    catch (e) {
+        if (e instanceof InvalidDocxError) {
+            io.stderr(JSON.stringify({ error: { code: e.code, message: e.message } }, null, 2));
+            return null;
+        }
+        throw e;
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Resolved page selection produced by {@link parsePageRange}.
+ *
+ * `pages` is the deduplicated set of 1-based page numbers requested by
+ * the user, after clamping to the document's actual page count.
+ *
+ * `warnings` collects clamp/duplicate notices the caller should emit to
+ * stderr (parsing succeeded; the user just asked for pages that don't
+ * exist). Hard errors throw instead — see {@link parsePageRange}.
+ */
+export interface PageRange {
+    pages: ReadonlySet<number>;
+    warnings: ReadonlyArray<string>;
+}
+/**
+ * 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 declare function parsePageRange(input: string, totalPages: number): PageRange;