@lotics/cli 0.32.0 → 0.34.0

package/dist/{src/dev → dev}/wrapper_page.js

@@ -3,10 +3,12 @@
  *
  * The wrapper page is served at http://localhost:<port>/ and embeds the
  * project's Vite dev server in an iframe with the same
- * sandbox="allow-scripts allow-same-origin" attribute production uses —
- * safe because the Vite iframe is cross-origin to this wrapper (different
- * port), so the app gets its own real origin (and Web Storage) without
- * being able to reach the wrapper. The iframe sends postMessage RPCs to
+ * sandbox="allow-scripts allow-same-origin allow-downloads" attribute
+ * production uses — safe because the Vite iframe is cross-origin to this
+ * wrapper (different port), so the app gets its own real origin (and Web
+ * Storage) without being able to reach the wrapper. `allow-downloads` lets
+ * apps trigger file downloads (generated xlsx / pdf etc.) — Chrome blocks
+ * every download path from sandboxed iframes without it. The iframe sends postMessage RPCs to
  * this wrapper, which forwards them to the local /_rpc endpoint, which
  * dispatches to api.lotics.ai with the CLI's API key.
  *
@@ -58,7 +60,7 @@ export function buildWrapperPage(args) {
     <span>workspace <code>${escapeHtml(workspace_id)}</code></span>
     <span>RPC → <code>${escapeHtml(api_url)}</code></span>
   </header>
-  <iframe id="app" sandbox="allow-scripts allow-same-origin" allow="clipboard-write"></iframe>
+  <iframe id="app" sandbox="allow-scripts allow-same-origin allow-downloads" allow="clipboard-write"></iframe>
   <script>
     (function () {
       const APP_ID = ${JSON.stringify(app_id)};
@@ -89,6 +91,38 @@ export function buildWrapperPage(args) {
       // The iframe SDK sends one "upload" op carrying a File. A File can't
       // cross the JSON /_rpc hop, so the upload runs here in the browser:
       // mint a presigned URL, PUT the bytes to storage, then finalize.
+      //
+      // Retry policy parity with the production SDK
+      // (packages/app-sdk/src/upload/transport.ts): 3 PUT attempts with
+      // 1s/2s/4s backoff on 5xx + network errors. 4xx is terminal. Image
+      // compression is intentionally NOT inlined here — dev networks are
+      // stable enough, and end-user mobile cases are handled by the SDK
+      // and bridged host directly.
+      async function putWithRetry(url, file) {
+        const MAX_ATTEMPTS = 3;
+        let lastError;
+        for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+          try {
+            const res = await fetch(url, {
+              method: "PUT",
+              body: file,
+              headers: { "Content-Type": file.type },
+            });
+            if (res.ok) return res;
+            // 4xx is terminal — retrying a malformed/expired URL is pointless.
+            if (res.status >= 400 && res.status < 500) return res;
+            lastError = new Error("Storage PUT returned " + res.status);
+          } catch (err) {
+            lastError = err;
+          }
+          if (attempt < MAX_ATTEMPTS) {
+            const delayMs = 1000 * Math.pow(2, attempt - 1);
+            await new Promise(function (r) { setTimeout(r, delayMs); });
+          }
+        }
+        throw lastError || new Error("Storage PUT failed");
+      }
+
       async function handleUpload(payload) {
         const file = payload && payload.file;
         if (!(file instanceof File)) {
@@ -99,11 +133,7 @@ export function buildWrapperPage(args) {
           mime_type: file.type,
           file_size: file.size,
         });
-        const putRes = await fetch(init.upload_url, {
-          method: "PUT",
-          body: file,
-          headers: { "Content-Type": file.type },
-        });
+        const putRes = await putWithRetry(init.upload_url, file);
         if (!putRes.ok) {
           throw new Error("Storage upload failed (" + putRes.status + ")");
         }

package/dist/docx.d.ts

@@ -0,0 +1,2 @@
+export declare function printDocxHelp(): void;
+export declare function runDocxCommand(subcommand: string | undefined, toolArgs: string | undefined, restArgs: string[]): Promise<void>;

package/dist/docx.js

@@ -0,0 +1,341 @@
+import fs from "node:fs";
+import { fail, writeFileAtomic } from "./file_command_io.js";
+import { parseDocx, serializeDocx, } from "@lotics/docx";
+const DEFAULT_DOC_ATTRS = {
+    "@_xmlns:w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
+};
+async function loadFile(filePath) {
+    if (!fs.existsSync(filePath))
+        fail(`File not found: ${filePath}`);
+    const bytes = fs.readFileSync(filePath);
+    return parseDocx(new Uint8Array(bytes));
+}
+async function writeDoc(filePath, doc) {
+    const bytes = await serializeDocx(doc);
+    writeFileAtomic(filePath, bytes);
+}
+// =============================================================================
+// Block construction (typed, immutable)
+// =============================================================================
+function buildParagraph(text, style) {
+    const properties = style ? [buildPStyle(style)] : null;
+    const content = [buildRun(text)];
+    return { kind: "paragraph", properties, content };
+}
+function buildPStyle(styleId) {
+    return { "w:pStyle": [], ":@": { "@_w:val": styleId } };
+}
+function buildRun(text) {
+    // Split on \n so newlines render as Word line breaks (<w:br/>) instead of
+    // collapsing into a single line — multi-line agent input is common.
+    const segments = text.split("\n");
+    const content = [];
+    for (let i = 0; i < segments.length; i++) {
+        const value = segments[i];
+        if (value !== "") {
+            content.push({
+                kind: "text",
+                value,
+                preserveSpace: value.startsWith(" ") || value.endsWith(" "),
+            });
+        }
+        if (i < segments.length - 1) {
+            content.push({ kind: "opaque_run_child", xml: { "w:br": [] } });
+        }
+    }
+    if (content.length === 0)
+        content.push({ kind: "text", value: "", preserveSpace: false });
+    return { kind: "run", properties: null, content };
+}
+function replaceChildren(doc, children) {
+    return {
+        parts: doc.parts,
+        documentAttrs: doc.documentAttrs,
+        body: { children },
+    };
+}
+// =============================================================================
+// Read: project body to a simplified shape
+// =============================================================================
+function readToJson(doc, includeOpaque) {
+    const blocks = doc.body.children.map((block, index) => projectBlock(block, index, includeOpaque));
+    return { documentAttrs: doc.documentAttrs, blocks };
+}
+function projectBlock(block, index, includeOpaque) {
+    switch (block.kind) {
+        case "paragraph":
+            return {
+                kind: "paragraph",
+                index,
+                text: extractText(block),
+                style: extractStyleId(block.properties),
+            };
+        case "body_sect_pr":
+            return includeOpaque
+                ? { kind: "body_sect_pr", index, xml: block.xml }
+                : { kind: "body_sect_pr", index };
+        case "opaque_block":
+            return includeOpaque
+                ? { kind: "opaque_block", index, tag: firstTagName(block.xml), xml: block.xml }
+                : { kind: "opaque_block", index, tag: firstTagName(block.xml) };
+    }
+}
+function extractText(para) {
+    let out = "";
+    for (const inline of para.content) {
+        if (inline.kind !== "run")
+            continue;
+        for (const child of inline.content) {
+            if (child.kind === "text")
+                out += child.value;
+            else if (child.kind === "opaque_run_child" && firstTagName(child.xml) === "w:br")
+                out += "\n";
+        }
+    }
+    return out;
+}
+function extractStyleId(properties) {
+    if (!properties)
+        return undefined;
+    for (const prop of properties) {
+        if (firstTagName(prop) !== "w:pStyle")
+            continue;
+        const attrs = prop[":@"];
+        if (attrs?.["@_w:val"])
+            return attrs["@_w:val"];
+    }
+    return undefined;
+}
+function firstTagName(el) {
+    for (const key of Object.keys(el)) {
+        if (key !== ":@" && key !== "#text")
+            return key;
+    }
+    return undefined;
+}
+// =============================================================================
+// Write: build DocxDocument from a SimpleDoc
+// =============================================================================
+function buildDoc(input) {
+    if (!input || !Array.isArray(input.blocks))
+        fail("docx write JSON must include a `blocks` array");
+    const children = [];
+    for (let i = 0; i < input.blocks.length; i++) {
+        const b = input.blocks[i];
+        if (!b || typeof b !== "object")
+            fail(`blocks[${i}] must be an object`);
+        if (b.kind === "paragraph") {
+            if (typeof b.text !== "string")
+                fail(`blocks[${i}].text must be a string`);
+            if (b.style !== undefined && typeof b.style !== "string")
+                fail(`blocks[${i}].style must be a string`);
+            children.push(buildParagraph(b.text, b.style));
+        }
+        else if (b.kind === "opaque_block") {
+            fail(`blocks[${i}]: opaque_block cannot be created from JSON; read+modify an existing .docx instead`);
+        }
+        else {
+            const kind = b.kind;
+            fail(`blocks[${i}]: unknown kind ${JSON.stringify(kind)} (expected "paragraph")`);
+        }
+    }
+    const documentAttrs = { ...DEFAULT_DOC_ATTRS, ...(input.documentAttrs ?? {}) };
+    return { parts: new Map(), documentAttrs, body: { children } };
+}
+// =============================================================================
+// Subcommand handlers
+// =============================================================================
+async function docxRead(filePath, rest) {
+    if (!filePath)
+        fail("Usage: lotics docx read <file> [--include-opaque]");
+    const includeOpaque = rest.includes("--include-opaque");
+    const doc = await loadFile(filePath);
+    console.log(JSON.stringify(readToJson(doc, includeOpaque), null, 2));
+}
+async function docxWrite(filePath, json) {
+    if (!filePath || !json)
+        fail("Usage: lotics docx write <file> '<json>'");
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (e) {
+        fail(`Invalid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const doc = buildDoc(parsed);
+    await writeDoc(filePath, doc);
+}
+function getStyleFlag(rest) {
+    for (const arg of rest) {
+        if (arg.startsWith("--style="))
+            return arg.slice("--style=".length);
+    }
+    return undefined;
+}
+function getAtFlag(rest) {
+    for (const arg of rest) {
+        if (arg.startsWith("--at=")) {
+            const n = parseInt(arg.slice("--at=".length), 10);
+            return Number.isFinite(n) ? n : undefined;
+        }
+    }
+    return undefined;
+}
+function firstPositional(rest) {
+    return rest.find((a) => !a.startsWith("--"));
+}
+async function docxAppendParagraph(filePath, rest) {
+    const text = firstPositional(rest);
+    if (!filePath || text === undefined)
+        fail("Usage: lotics docx append-paragraph <file> '<text>' [--style=NAME]");
+    const style = getStyleFlag(rest);
+    const doc = await loadFile(filePath);
+    const para = buildParagraph(text, style);
+    const newChildren = [...doc.body.children, para];
+    await writeDoc(filePath, replaceChildren(doc, newChildren));
+}
+async function docxInsertParagraph(filePath, rest) {
+    const text = firstPositional(rest);
+    const at = getAtFlag(rest);
+    if (!filePath || text === undefined || at === undefined) {
+        fail("Usage: lotics docx insert-paragraph <file> '<text>' --at=<index> [--style=NAME]");
+    }
+    const style = getStyleFlag(rest);
+    const doc = await loadFile(filePath);
+    if (at < 0 || at > doc.body.children.length) {
+        fail(`--at=${at} out of range (0..${doc.body.children.length})`);
+    }
+    const para = buildParagraph(text, style);
+    const newChildren = [...doc.body.children];
+    newChildren.splice(at, 0, para);
+    await writeDoc(filePath, replaceChildren(doc, newChildren));
+}
+async function docxDeleteBlock(filePath, rest) {
+    const at = getAtFlag(rest);
+    if (!filePath || at === undefined)
+        fail("Usage: lotics docx delete-block <file> --at=<index>");
+    const doc = await loadFile(filePath);
+    if (at < 0 || at >= doc.body.children.length) {
+        fail(`--at=${at} out of range (0..${doc.body.children.length - 1})`);
+    }
+    const newChildren = doc.body.children.filter((_, i) => i !== at);
+    await writeDoc(filePath, replaceChildren(doc, newChildren));
+}
+async function docxReplaceText(filePath, rest) {
+    const [search, replace] = rest;
+    if (!filePath || !search || replace === undefined) {
+        fail("Usage: lotics docx replace-text <file> '<search>' '<replace>'");
+    }
+    const doc = await loadFile(filePath);
+    const newChildren = doc.body.children.map((b) => (b.kind === "paragraph" ? replaceInParagraph(b, search, replace) : b));
+    await writeDoc(filePath, replaceChildren(doc, newChildren));
+}
+function replaceInParagraph(p, search, replace) {
+    const content = p.content.map((inline) => {
+        if (inline.kind !== "run")
+            return inline;
+        const newChildren = inline.content.map((c) => c.kind === "text"
+            ? { kind: "text", value: c.value.split(search).join(replace), preserveSpace: c.preserveSpace }
+            : c);
+        return { kind: "run", properties: inline.properties, content: newChildren };
+    });
+    return { kind: "paragraph", properties: p.properties, content };
+}
+async function docxBatch(filePath, json) {
+    if (!filePath || !json)
+        fail("Usage: lotics docx batch <file> '<json-array-of-ops>'");
+    let ops;
+    try {
+        ops = JSON.parse(json);
+    }
+    catch (e) {
+        fail(`Invalid batch JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!Array.isArray(ops))
+        fail("Batch must be a JSON array of ops");
+    for (let i = 0; i < ops.length; i++) {
+        const op = ops[i];
+        if (!op || typeof op !== "object" || typeof op.op !== "string") {
+            fail(`[op ${i}] each op must be an object with an "op" string field`);
+        }
+    }
+    let doc = await loadFile(filePath);
+    for (let i = 0; i < ops.length; i++) {
+        doc = applyBatchOp(doc, ops[i], i);
+    }
+    await writeDoc(filePath, doc);
+}
+function applyBatchOp(doc, op, index) {
+    switch (op.op) {
+        case "append-paragraph": {
+            const para = buildParagraph(op.text, op.style);
+            return replaceChildren(doc, [...doc.body.children, para]);
+        }
+        case "insert-paragraph": {
+            if (op.at < 0 || op.at > doc.body.children.length) {
+                fail(`[op ${index}] at=${op.at} out of range`);
+            }
+            const next = [...doc.body.children];
+            next.splice(op.at, 0, buildParagraph(op.text, op.style));
+            return replaceChildren(doc, next);
+        }
+        case "delete-block": {
+            if (op.at < 0 || op.at >= doc.body.children.length) {
+                fail(`[op ${index}] at=${op.at} out of range`);
+            }
+            return replaceChildren(doc, doc.body.children.filter((_, i) => i !== op.at));
+        }
+        case "replace-text": {
+            const next = doc.body.children.map((b) => (b.kind === "paragraph" ? replaceInParagraph(b, op.search, op.replace) : b));
+            return replaceChildren(doc, next);
+        }
+        default: {
+            const exhaustive = op;
+            void exhaustive;
+            fail(`[op ${index}] Unknown op: ${JSON.stringify(op)}`);
+        }
+    }
+}
+// =============================================================================
+// Dispatch + help
+// =============================================================================
+export function printDocxHelp() {
+    console.error(`Lotics docx commands — manipulate .docx files in place.
+Uses Lotics' own OOXML engine; round-trips faithfully with the Lotics editor and templates.
+
+  lotics docx read <file> [--include-opaque]               Dump file as JSON (blocks with text/style)
+  lotics docx write <file> '<json>'                        Create .docx from {"blocks":[{"kind":"paragraph","text":...}]}
+  lotics docx append-paragraph <file> '<text>' [--style=NAME]
+                                                           Append a paragraph (styles: Title, Heading1..3, Quote, Code)
+  lotics docx insert-paragraph <file> '<text>' --at=<i> [--style=NAME]
+                                                           Insert a paragraph at index <i> (0-based)
+  lotics docx delete-block <file> --at=<i>                 Remove the block at index <i>
+  lotics docx replace-text <file> '<search>' '<replace>'   Replace text in all paragraph runs
+  lotics docx batch <file> '<json-array-of-ops>'           Apply many ops in one parse/serialize cycle
+
+Edit ops mutate the file atomically (temp file + rename). Opaque blocks (tables, custom XML) are preserved verbatim.`);
+}
+export async function runDocxCommand(subcommand, toolArgs, restArgs) {
+    switch (subcommand) {
+        case "read":
+            return docxRead(toolArgs, restArgs);
+        case "write":
+            return docxWrite(toolArgs, restArgs[0]);
+        case "append-paragraph":
+            return docxAppendParagraph(toolArgs, restArgs);
+        case "insert-paragraph":
+            return docxInsertParagraph(toolArgs, restArgs);
+        case "delete-block":
+            return docxDeleteBlock(toolArgs, restArgs);
+        case "replace-text":
+            return docxReplaceText(toolArgs, restArgs);
+        case "batch":
+            return docxBatch(toolArgs, restArgs[0]);
+        default: {
+            if (subcommand)
+                console.error(`Unknown docx subcommand: ${subcommand}\n`);
+            printDocxHelp();
+            process.exit(subcommand ? 1 : 0);
+        }
+    }
+}

package/dist/docx.test.js

@@ -0,0 +1,145 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { parseDocx } from "@lotics/docx";
+import { runDocxCommand } from "./docx.js";
+import { CliError } from "./file_command_io.js";
+let tmpDir;
+let file;
+beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "docx-test-"));
+    file = path.join(tmpDir, "test.docx");
+    vi.spyOn(console, "error").mockImplementation(() => { });
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+async function writeFresh(json) {
+    await runDocxCommand("write", file, [json]);
+}
+async function readBlocks() {
+    const stdout = vi.spyOn(console, "log").mockImplementation(() => { });
+    try {
+        await runDocxCommand("read", file, []);
+        const printed = stdout.mock.calls[0]?.[0];
+        const out = JSON.parse(printed);
+        return out.blocks
+            .filter((b) => b.kind === "paragraph")
+            .map((b) => ({ text: b.text ?? "", style: b.style }));
+    }
+    finally {
+        stdout.mockRestore();
+    }
+}
+describe("docx write + read", () => {
+    it("round-trips paragraphs with styles", async () => {
+        await writeFresh(JSON.stringify({
+            blocks: [
+                { kind: "paragraph", text: "Title", style: "Heading1" },
+                { kind: "paragraph", text: "Body" },
+            ],
+        }));
+        expect(await readBlocks()).toEqual([
+            { text: "Title", style: "Heading1" },
+            { text: "Body", style: undefined },
+        ]);
+    });
+    it("renders multi-line text as <w:br/> line breaks and round-trips through read", async () => {
+        await writeFresh(JSON.stringify({ blocks: [{ kind: "paragraph", text: "L1\nL2\nL3" }] }));
+        expect(await readBlocks()).toEqual([{ text: "L1\nL2\nL3", style: undefined }]);
+    });
+});
+describe("docx single-op mutations", () => {
+    beforeEach(async () => {
+        await writeFresh(JSON.stringify({ blocks: [{ kind: "paragraph", text: "first" }] }));
+    });
+    it("append-paragraph adds at end", async () => {
+        await runDocxCommand("append-paragraph", file, ["second"]);
+        expect((await readBlocks()).map((b) => b.text)).toEqual(["first", "second"]);
+    });
+    it("append-paragraph carries a style flag", async () => {
+        await runDocxCommand("append-paragraph", file, ["heading", "--style=Heading2"]);
+        expect((await readBlocks())[1]).toEqual({ text: "heading", style: "Heading2" });
+    });
+    it("append-paragraph does NOT consume --style as positional text", async () => {
+        // Regression: an earlier draft picked rest[0] without filtering flags,
+        // so `--style=X` became the paragraph text.
+        await expect(runDocxCommand("append-paragraph", file, ["--style=Heading1"])).rejects.toBeInstanceOf(CliError);
+    });
+    it("insert-paragraph splices at index", async () => {
+        await runDocxCommand("insert-paragraph", file, ["front", "--at=0"]);
+        expect((await readBlocks()).map((b) => b.text)).toEqual(["front", "first"]);
+    });
+    it("delete-block removes by index", async () => {
+        await runDocxCommand("append-paragraph", file, ["second"]);
+        await runDocxCommand("delete-block", file, ["--at=0"]);
+        expect((await readBlocks()).map((b) => b.text)).toEqual(["second"]);
+    });
+    it("replace-text rewrites all paragraph runs", async () => {
+        await runDocxCommand("append-paragraph", file, ["the {{name}}"]);
+        await runDocxCommand("replace-text", file, ["{{name}}", "Acme"]);
+        expect((await readBlocks()).map((b) => b.text)).toEqual(["first", "the Acme"]);
+    });
+});
+describe("docx batch", () => {
+    it("applies many ops in one parse/serialize cycle", async () => {
+        await writeFresh(JSON.stringify({ blocks: [{ kind: "paragraph", text: "a" }] }));
+        const ops = [
+            { op: "append-paragraph", text: "b" },
+            { op: "insert-paragraph", text: "front", at: 0 },
+            { op: "replace-text", search: "b", replace: "B" },
+        ];
+        await runDocxCommand("batch", file, [JSON.stringify(ops)]);
+        expect((await readBlocks()).map((b) => b.text)).toEqual(["front", "a", "B"]);
+    });
+    it("rejects batch op without an 'op' string", async () => {
+        await writeFresh(JSON.stringify({ blocks: [{ kind: "paragraph", text: "x" }] }));
+        await expect(runDocxCommand("batch", file, [JSON.stringify([{ text: "y" }])])).rejects.toBeInstanceOf(CliError);
+    });
+});
+describe("docx round-trip preserves opaque blocks", () => {
+    it("a table (parsed as opaque_block) survives replace-text + write back", async () => {
+        // Build a docx by hand with a paragraph + a synthetic table cell.
+        // Use the live parse/serialize path to confirm opaque content survives.
+        await writeFresh(JSON.stringify({ blocks: [{ kind: "paragraph", text: "before" }] }));
+        // We can't construct an opaque_block via write JSON, so just verify
+        // that the round-trip of a doc containing only paragraphs is stable
+        // and that error path for opaque_block is hit on write.
+        await expect(runDocxCommand("write", file, [JSON.stringify({
+                blocks: [{ kind: "opaque_block" }],
+            })])).rejects.toBeInstanceOf(CliError);
+    });
+});
+describe("docx error paths", () => {
+    it("fails on missing file", async () => {
+        await expect(runDocxCommand("append-paragraph", path.join(tmpDir, "no.docx"), ["x"])).rejects.toBeInstanceOf(CliError);
+    });
+    it("fails on invalid write JSON", async () => {
+        await expect(runDocxCommand("write", file, ["{not json"])).rejects.toBeInstanceOf(CliError);
+    });
+    it("fails on missing blocks array", async () => {
+        await expect(runDocxCommand("write", file, [JSON.stringify({})])).rejects.toBeInstanceOf(CliError);
+    });
+    it("fails on out-of-range --at on insert-paragraph", async () => {
+        await writeFresh(JSON.stringify({ blocks: [{ kind: "paragraph", text: "only" }] }));
+        await expect(runDocxCommand("insert-paragraph", file, ["x", "--at=99"])).rejects.toBeInstanceOf(CliError);
+    });
+    it("fails on out-of-range --at on delete-block", async () => {
+        await writeFresh(JSON.stringify({ blocks: [{ kind: "paragraph", text: "only" }] }));
+        await expect(runDocxCommand("delete-block", file, ["--at=5"])).rejects.toBeInstanceOf(CliError);
+    });
+});
+// Verify parseDocx is callable from this test (sanity that the barrel import
+// works under tsgo + vitest) — write a doc, parse with the library directly,
+// confirm at least one paragraph block.
+describe("docx barrel sanity", () => {
+    it("parseDocx is reachable from @lotics/docx", async () => {
+        await writeFresh(JSON.stringify({ blocks: [{ kind: "paragraph", text: "hi" }] }));
+        const bytes = fs.readFileSync(file);
+        const doc = await parseDocx(new Uint8Array(bytes));
+        const paragraphs = doc.body.children.filter((b) => b.kind === "paragraph");
+        expect(paragraphs.length).toBeGreaterThanOrEqual(1);
+    });
+});

package/dist/file_command_io.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Throw a tagged user-facing error from a CLI subcommand.
+ *
+ * The top-level CLI catch (`main().catch` in cli.ts) prints `message` to
+ * stderr and exits 1, so callers get the same UX as `process.exit(1)` but
+ * tests can catch the throw without killing the test runner.
+ */
+export declare class CliError extends Error {
+    constructor(message: string);
+}
+export declare function fail(message: string): never;
+export declare function writeFileAtomic(filePath: string, bytes: Uint8Array): void;

package/dist/file_command_io.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Throw a tagged user-facing error from a CLI subcommand.
+ *
+ * The top-level CLI catch (`main().catch` in cli.ts) prints `message` to
+ * stderr and exits 1, so callers get the same UX as `process.exit(1)` but
+ * tests can catch the throw without killing the test runner.
+ */
+export class CliError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CliError";
+    }
+}
+export function fail(message) {
+    throw new CliError(message);
+}
+export function writeFileAtomic(filePath, bytes) {
+    const dir = path.dirname(path.resolve(filePath));
+    const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    fs.writeFileSync(tmp, bytes);
+    try {
+        fs.renameSync(tmp, filePath);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* best-effort cleanup */ }
+        throw error;
+    }
+    console.error(`Wrote ${filePath}`);
+}