@lotics/cli 0.70.0 → 0.73.0

package/dist/package_commands.test.d.ts

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

package/dist/package_commands.test.js

@@ -0,0 +1,303 @@
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { parseAppPackageContract, validateAppPackageContract, } from "@lotics/shared/schemas/app_packages";
+import { starterContract, readPackageProject, writePackageManifest, sanitizePackageJsonForSource, stagePackageSource, parseResolveFlags, assertDevWorkspace, draftPackageProjectFromApp, parseAdoptBindingFile, formatExtractReport, } from "./package_commands.js";
+describe("starterContract", () => {
+    it("scaffolds a structurally + referentially valid contract", () => {
+        const raw = starterContract("Acme CRM");
+        // Structurally valid against the canonical contract schema.
+        const contract = parseAppPackageContract(raw);
+        // Cross-references (query from_entity, etc.) resolve — zero violations, so the
+        // scaffold publishes without the server's contract validator rejecting it.
+        expect(validateAppPackageContract(contract)).toEqual([]);
+    });
+    it("uses the package name as the entity label", () => {
+        const contract = parseAppPackageContract(starterContract("Widgets"));
+        expect(contract.entities[0].label).toBe("Widgets");
+        expect(contract.config[0].default).toBe("Widgets");
+    });
+});
+describe("package manifest round-trip", () => {
+    function makeProject() {
+        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-pkg-test-"));
+        fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({
+            name: "acme-crm",
+            version: "0.0.1",
+            lotics: {
+                package: { id: null, name: "Acme CRM", description: null, version: null, dev: {} },
+            },
+        }, null, 2) + "\n");
+        return dir;
+    }
+    it("reads the package manifest off package.json#lotics.package", () => {
+        const dir = makeProject();
+        try {
+            const { manifest } = readPackageProject(dir);
+            expect(manifest).toEqual({
+                id: null,
+                name: "Acme CRM",
+                description: null,
+                version: null,
+                dev: {},
+            });
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("persists publish + dev-installation pins and reads them back", () => {
+        const dir = makeProject();
+        try {
+            const project = readPackageProject(dir);
+            project.manifest.id = "apg_test";
+            project.manifest.version = 3;
+            project.manifest.dev["wsp_dev"] = { app_id: "app_dev", version: 3 };
+            writePackageManifest(dir, project);
+            const reread = readPackageProject(dir);
+            expect(reread.manifest.id).toBe("apg_test");
+            expect(reread.manifest.version).toBe(3);
+            expect(reread.manifest.dev).toEqual({ wsp_dev: { app_id: "app_dev", version: 3 } });
+            // Non-lotics package.json fields survive the manifest write.
+            expect(reread.pkgJson.name).toBe("acme-crm");
+            expect(reread.pkgJson.version).toBe("0.0.1");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("writes the manifest atomically, leaving no temp file behind", () => {
+        const dir = makeProject();
+        try {
+            const project = readPackageProject(dir);
+            project.manifest.id = "apg_atomic";
+            writePackageManifest(dir, project);
+            // The atomic write renames a temp file into place; nothing stray remains.
+            const leftovers = fs.readdirSync(dir).filter((f) => f.startsWith("package.json."));
+            expect(leftovers).toEqual([]);
+            expect(readPackageProject(dir).manifest.id).toBe("apg_atomic");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+describe("sanitizePackageJsonForSource", () => {
+    it("strips the author-local lotics.package.dev map", () => {
+        const sanitized = sanitizePackageJsonForSource({
+            name: "acme-crm",
+            version: "0.0.1",
+            lotics: {
+                package: {
+                    id: "apg_x",
+                    name: "Acme CRM",
+                    description: "d",
+                    version: 4,
+                    dev: { wsp_dev: { app_id: "app_dev", version: 4 } },
+                },
+            },
+        });
+        const lotics = sanitized.lotics;
+        // The private dev bookkeeping is gone…
+        expect("dev" in lotics.package).toBe(false);
+        // …while the package identity + other fields survive untouched.
+        expect(lotics.package).toEqual({
+            id: "apg_x",
+            name: "Acme CRM",
+            description: "d",
+            version: 4,
+        });
+        expect(sanitized.name).toBe("acme-crm");
+        expect(sanitized.version).toBe("0.0.1");
+    });
+    it("does not mutate the input package.json", () => {
+        const input = {
+            name: "acme-crm",
+            lotics: { package: { id: "apg_x", name: "Acme CRM", dev: { wsp_dev: { app_id: "a", version: 1 } } } },
+        };
+        sanitizePackageJsonForSource(input);
+        expect(input.lotics.package.dev).toEqual({ wsp_dev: { app_id: "a", version: 1 } });
+    });
+});
+describe("assertDevWorkspace", () => {
+    it("passes a dev workspace", () => {
+        expect(() => assertDevWorkspace({ id: "wsp_d", name: "Dev", is_dev: true })).not.toThrow();
+    });
+    it("fails loud on a non-dev workspace", () => {
+        expect(() => assertDevWorkspace({ id: "wsp_p", name: "Prod", is_dev: false })).toThrow(/not a dev workspace/);
+    });
+    it("fails closed when is_dev is absent (server doesn't serialize it)", () => {
+        expect(() => assertDevWorkspace({ id: "wsp_u", name: "Unknown" })).toThrow(/not a dev workspace/);
+    });
+    it("rejects a directory that is not a package project", () => {
+        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-pkg-test-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({ name: "plain-app" }));
+            expect(() => readPackageProject(dir)).toThrow(/not a package project/);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+describe("parseResolveFlags", () => {
+    it("maps 'recreate' and ids to their resolution shapes", () => {
+        expect(parseResolveFlags(["fields.deal.stage=recreate", "templates.quote=dtl_abc"])).toEqual({
+            "fields.deal.stage": "recreate",
+            "templates.quote": { bind_to: "dtl_abc" },
+        });
+    });
+    it("maps modified-core consents 'revert' and 'keep' as literals", () => {
+        expect(parseResolveFlags(["queries.tasks=revert", "workflows.notify=keep"])).toEqual({
+            "queries.tasks": "revert",
+            "workflows.notify": "keep",
+        });
+    });
+    it("rejects entries without a key=value shape", () => {
+        expect(() => parseResolveFlags(["fields.deal.stage"])).toThrow(/Invalid --resolve/);
+        expect(() => parseResolveFlags(["=recreate"])).toThrow(/Invalid --resolve/);
+        expect(() => parseResolveFlags(["fields.deal.stage="])).toThrow(/Invalid --resolve/);
+    });
+});
+describe("draftPackageProjectFromApp", () => {
+    it("strips the app manifest and grafts an unpublished package manifest", () => {
+        const project = draftPackageProjectFromApp({
+            name: "acme-crm",
+            version: "0.0.1",
+            dependencies: { "@lotics/app-sdk": "^1.0.0" },
+            lotics: {
+                app_id: "app_x",
+                workspace_id: "wsp_y",
+                current_version_id: "apv_z",
+                workflows: { notify: { workflow_id: "wfl_1" } },
+            },
+        }, { name: "Acme CRM", description: null });
+        // The app manifest (app_id/workspace_id/workflows) is gone entirely…
+        expect("lotics" in project.pkgJson).toBe(false);
+        // …the package manifest is fresh + unpublished…
+        expect(project.manifest).toEqual({
+            id: null,
+            name: "Acme CRM",
+            description: null,
+            version: null,
+            dev: {},
+        });
+        // …and non-lotics fields survive verbatim.
+        expect(project.pkgJson.name).toBe("acme-crm");
+        expect(project.pkgJson.version).toBe("0.0.1");
+        expect(project.pkgJson.dependencies).toEqual({ "@lotics/app-sdk": "^1.0.0" });
+    });
+    it("round-trips through writePackageManifest to a valid package project on disk", () => {
+        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-pkg-test-"));
+        try {
+            writePackageManifest(dir, draftPackageProjectFromApp({ name: "acme-crm", lotics: { app_id: "app_x", workspace_id: "wsp_y" } }, { name: "Acme CRM", description: "A CRM" }));
+            // readPackageProject only accepts a real package project (lotics.package).
+            const { manifest, pkgJson } = readPackageProject(dir);
+            expect(manifest).toEqual({
+                id: null,
+                name: "Acme CRM",
+                description: "A CRM",
+                version: null,
+                dev: {},
+            });
+            // The old app manifest keys never made it to disk.
+            const lotics = pkgJson.lotics;
+            expect("app_id" in lotics).toBe(false);
+            expect("workspace_id" in lotics).toBe(false);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("does not mutate the input package.json", () => {
+        const input = { name: "acme-crm", lotics: { app_id: "app_x", workspace_id: "wsp_y" } };
+        draftPackageProjectFromApp(input, { name: "Acme CRM", description: null });
+        expect(input.lotics).toEqual({ app_id: "app_x", workspace_id: "wsp_y" });
+    });
+});
+describe("parseAdoptBindingFile", () => {
+    const validPin = {
+        app_id: "app_x",
+        workspace_id: "wsp_y",
+        binding: { entities: { item: "tbl_1" }, fields: {}, options: {}, templates: {}, roles: {}, workflows: {} },
+    };
+    it("accepts a pin whose app_id matches the app being adopted", () => {
+        const pin = parseAdoptBindingFile(validPin, "app_x");
+        expect(pin.app_id).toBe("app_x");
+        expect(pin.workspace_id).toBe("wsp_y");
+        expect(pin.binding.entities).toEqual({ item: "tbl_1" });
+    });
+    it("REFUSES a pin recorded for a different app", () => {
+        expect(() => parseAdoptBindingFile(validPin, "app_OTHER")).toThrow(/records app app_x, but you are adopting app_OTHER/);
+    });
+    it("rejects a malformed pin", () => {
+        expect(() => parseAdoptBindingFile({ app_id: "app_x" }, "app_x")).toThrow(/Malformed/);
+        expect(() => parseAdoptBindingFile(null, "app_x")).toThrow(/Malformed/);
+        expect(() => parseAdoptBindingFile({ app_id: "app_x", workspace_id: "wsp_y" }, "app_x")).toThrow(/Malformed/);
+    });
+});
+describe("formatExtractReport", () => {
+    it("groups findings errors → warnings → info and formats each line", () => {
+        const { lines, hasError } = formatExtractReport([
+            { severity: "info", area: "queries.items", message: "inverted cleanly" },
+            { severity: "error", area: "fields.deal.stage", message: "button field is not portable" },
+            { severity: "warning", area: "workflows.notify", message: "legacy key retained" },
+            { severity: "error", area: "queries.deals", message: "round-trip mismatch" },
+        ]);
+        expect(lines).toEqual([
+            "  [error] fields.deal.stage: button field is not portable",
+            "  [error] queries.deals: round-trip mismatch",
+            "  [warning] workflows.notify: legacy key retained",
+            "  [info] queries.items: inverted cleanly",
+        ]);
+        expect(hasError).toBe(true);
+    });
+    it("reports no error when only warnings/info are present", () => {
+        const { lines, hasError } = formatExtractReport([
+            { severity: "warning", area: "a", message: "w" },
+            { severity: "info", area: "b", message: "i" },
+        ]);
+        expect(lines).toEqual(["  [warning] a: w", "  [info] b: i"]);
+        expect(hasError).toBe(false);
+    });
+    it("handles an empty report", () => {
+        expect(formatExtractReport([])).toEqual({ lines: [], hasError: false });
+    });
+});
+describe("stagePackageSource", () => {
+    it("keeps nested dist-named dirs, drops top-level excludes, sanitizes package.json", () => {
+        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-stage-test-"));
+        const stage = fs.mkdtempSync(path.join(tmpdir(), "lotics-stage-out-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({
+                name: "pkg",
+                lotics: { package: { id: "apg_x", name: "pkg", version: 3, dev: { wsp_a: "app_1" } } },
+            }));
+            fs.mkdirSync(path.join(dir, "src"));
+            fs.writeFileSync(path.join(dir, "src", "main.tsx"), "export {}");
+            // A nested dir NAMED dist must ship — only the top-level dist is a build output.
+            fs.mkdirSync(path.join(dir, "templates", "dist"), { recursive: true });
+            fs.writeFileSync(path.join(dir, "templates", "dist", "quote.xlsx"), "bytes");
+            fs.mkdirSync(path.join(dir, "dist"));
+            fs.writeFileSync(path.join(dir, "dist", "index.js"), "built");
+            fs.mkdirSync(path.join(dir, "node_modules", "x"), { recursive: true });
+            fs.writeFileSync(path.join(dir, "node_modules", "x", "i.js"), "dep");
+            fs.writeFileSync(path.join(dir, "tsconfig.tsbuildinfo"), "{}");
+            stagePackageSource(dir, stage);
+            expect(fs.existsSync(path.join(stage, "src", "main.tsx"))).toBe(true);
+            expect(fs.existsSync(path.join(stage, "templates", "dist", "quote.xlsx"))).toBe(true);
+            expect(fs.existsSync(path.join(stage, "dist"))).toBe(false);
+            expect(fs.existsSync(path.join(stage, "node_modules"))).toBe(false);
+            expect(fs.existsSync(path.join(stage, "tsconfig.tsbuildinfo"))).toBe(false);
+            // The staged package.json is the sanitized one — dev pins stripped.
+            const staged = JSON.parse(fs.readFileSync(path.join(stage, "package.json"), "utf-8"));
+            expect(staged.lotics.package.dev).toBeUndefined();
+            expect(staged.lotics.package.id).toBe("apg_x");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+            fs.rmSync(stage, { recursive: true, force: true });
+        }
+    });
+});

package/dist/preview.d.ts

@@ -0,0 +1,3 @@
+export declare function runPreviewCommand(filePath: string | undefined, flags: {
+    output?: string;
+}): Promise<void>;

package/dist/preview.js

@@ -0,0 +1,233 @@
+// `lotics preview <file.docx|.xlsx> [--out x.png]` — render a generated document to
+// a PNG using the SAME engines the frontend FilePreview uses. No npm deps: drives a
+// headless Chrome over CDP with Node built-ins (WebSocket/fetch/http/child_process),
+// keeping the CLI a single bundled binary. The render logic lives in the esbuild
+// browser bundle dist/render_page.js (built by build_cli.mjs); this file orchestrates
+// Chrome. Chrome itself is external (system Chrome / Playwright chromium / CHROME_PATH)
+// — inherent to rendering docx/xlsx, which are browser-rendered formats.
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { readFileSync, writeFileSync, existsSync, mkdtempSync, rmSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname, resolve, extname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { setTimeout as sleep } from "node:timers/promises";
+const HERE = dirname(fileURLToPath(import.meta.url));
+function fail(msg) {
+    console.error(msg);
+    process.exit(1);
+}
+/** Locate a Chrome/Chromium binary: explicit env → Playwright's install → system. */
+function findChrome() {
+    const env = process.env.LOTICS_CHROME || process.env.CHROME_PATH;
+    if (env && existsSync(env))
+        return env;
+    const home = process.env.HOME || "";
+    // Playwright installs under ms-playwright/chromium-<rev>/…  Enumerate with readdirSync
+    // (Node 10+) — NOT node:fs globSync, which is Node 22+; a globSync import would fail to
+    // load the whole bundled CLI on the Node 18+ it supports.
+    const pwDir = process.platform === "darwin"
+        ? `${home}/Library/Caches/ms-playwright`
+        : `${home}/.cache/ms-playwright`;
+    if (existsSync(pwDir)) {
+        const rel = process.platform === "darwin"
+            ? ["chrome-mac/Chromium.app/Contents/MacOS/Chromium"]
+            : ["chrome-linux/chrome", "chrome-linux/headless_shell"];
+        const revs = readdirSync(pwDir)
+            .filter((n) => n.startsWith("chromium-") || n.startsWith("chromium_headless_shell-"))
+            .sort()
+            .reverse();
+        for (const rev of revs) {
+            for (const r of rel) {
+                const bin = join(pwDir, rev, r);
+                if (existsSync(bin))
+                    return bin;
+            }
+        }
+    }
+    const systemPaths = [
+        "/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium",
+        "/usr/bin/chromium-browser", "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    ];
+    return systemPaths.find((p) => existsSync(p)) ?? null;
+}
+/** Minimal CDP client over the built-in WebSocket. */
+async function cdpConnect(wsUrl) {
+    const ws = new WebSocket(wsUrl);
+    await new Promise((res, rej) => {
+        ws.onopen = () => res();
+        ws.onerror = () => rej(new Error("CDP websocket failed to open"));
+    });
+    let id = 0;
+    const pending = new Map();
+    // If Chrome exits mid-render the socket closes with no reply — settle every in-flight
+    // request so `send()` rejects instead of hanging forever (the finally then cleans up).
+    ws.onclose = () => {
+        for (const done of pending.values())
+            done(Promise.reject(new Error("CDP connection closed (Chrome exited?)")));
+        pending.clear();
+    };
+    ws.onmessage = (e) => {
+        const m = JSON.parse(String(e.data));
+        if (m.id != null && pending.has(m.id)) {
+            const done = pending.get(m.id);
+            pending.delete(m.id);
+            done(m.error ? Promise.reject(new Error(m.error.message)) : m.result);
+        }
+    };
+    const send = (method, params = {}) => new Promise((res) => {
+        const i = ++id;
+        pending.set(i, (r) => res(r));
+        ws.send(JSON.stringify({ id: i, method, params }));
+    });
+    return { send, close: () => ws.close() };
+}
+export async function runPreviewCommand(filePath, flags) {
+    if (!filePath)
+        fail("Usage: lotics preview <file.docx|.xlsx> [--out <file.png>]");
+    const abs = resolve(filePath);
+    if (!existsSync(abs))
+        fail(`File not found: ${abs}`);
+    const ext = extname(abs).toLowerCase();
+    const type = ext === ".docx" ? "docx" : (ext === ".xlsx" || ext === ".xls" || ext === ".csv") ? "xlsx" : null;
+    if (!type)
+        fail(`Unsupported file type "${ext}" — preview supports .docx and .xlsx/.csv. (PDFs open directly — no preview needed.)`);
+    // preview drives Chrome over CDP via the built-in WebSocket (Node 22+). The rest of the
+    // CLI supports Node 18, so fail this one command clearly rather than with "WebSocket is
+    // not defined" — and before launching Chrome.
+    if (typeof WebSocket === "undefined") {
+        fail("lotics preview needs Node 22+ (it drives Chrome over CDP via the built-in WebSocket). Upgrade Node and retry.");
+    }
+    const bundlePath = join(HERE, "..", "render_page.js");
+    if (!existsSync(bundlePath))
+        fail(`Render bundle missing at ${bundlePath} — reinstall @lotics/cli (build step failed).`);
+    const chrome = findChrome();
+    if (!chrome) {
+        fail("No Chrome/Chromium found. Set CHROME_PATH to a Chrome binary, or install one:\n" +
+            "  npx playwright install chromium   (then it's auto-detected)\n" +
+            "  or install Google Chrome / Chromium via your package manager.");
+    }
+    const b64 = readFileSync(abs).toString("base64");
+    const bundle = readFileSync(bundlePath, "utf8");
+    const html = `<!doctype html><html><head><meta charset="utf-8"><style>body{margin:0;background:#fff;font-family:sans-serif}` +
+        `#root{padding:20px;max-width:1240px;margin:0 auto}</style></head><body><div id="root"></div>` +
+        `<script>window.__LOTICS_RENDER=${JSON.stringify({ type, b64 })}</script>` +
+        `<script src="/render_page.js"></script></body></html>`;
+    const server = createServer((req, res) => {
+        if (req.url === "/render_page.js") {
+            res.writeHead(200, { "content-type": "application/javascript" });
+            res.end(bundle);
+        }
+        else {
+            res.writeHead(200, { "content-type": "text/html" });
+            res.end(html);
+        }
+    });
+    await new Promise((r) => server.listen(0, "127.0.0.1", () => r()));
+    const httpPort = server.address().port;
+    const udd = mkdtempSync(join(tmpdir(), "lotics-render-"));
+    const child = spawn(chrome, [
+        "--headless=new", "--disable-gpu", "--no-sandbox", "--hide-scrollbars",
+        // Large multi-sheet renders exhaust the (often tiny) /dev/shm in containers/WSL2 and
+        // crash the tab; back shared memory with /tmp instead.
+        "--disable-dev-shm-usage",
+        "--force-device-scale-factor=2", "--remote-debugging-port=0", `--user-data-dir=${udd}`,
+        "about:blank",
+    ], { stdio: "ignore" });
+    const cleanup = () => {
+        try {
+            child.kill();
+        }
+        catch { /* ignore */ }
+        try {
+            server.close();
+        }
+        catch { /* ignore */ }
+        try {
+            rmSync(udd, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+    };
+    try {
+        // Chrome writes the chosen debug port to DevToolsActivePort (first line).
+        let cdpPort = 0;
+        const portFile = join(udd, "DevToolsActivePort");
+        for (let i = 0; i < 100 && !cdpPort; i++) {
+            if (existsSync(portFile)) {
+                const p = parseInt(readFileSync(portFile, "utf8").split("\n")[0], 10);
+                if (p)
+                    cdpPort = p;
+            }
+            if (!cdpPort)
+                await sleep(100);
+        }
+        if (!cdpPort)
+            throw new Error("Chrome did not expose a debugging port (launch failed?).");
+        let target;
+        for (let i = 0; i < 60 && !target?.webSocketDebuggerUrl; i++) {
+            try {
+                const list = await (await fetch(`http://127.0.0.1:${cdpPort}/json/list`)).json();
+                target = list.find((t) => t.type === "page");
+            }
+            catch { /* not ready */ }
+            if (!target?.webSocketDebuggerUrl)
+                await sleep(100);
+        }
+        if (!target?.webSocketDebuggerUrl)
+            throw new Error("No Chrome page target available.");
+        const cdp = await cdpConnect(target.webSocketDebuggerUrl);
+        await cdp.send("Page.enable");
+        await cdp.send("Runtime.enable");
+        await cdp.send("Page.navigate", { url: `http://127.0.0.1:${httpPort}/` });
+        // Poll for the render-done flag the page sets.
+        let err;
+        let done = false;
+        const warnings = [];
+        for (let i = 0; i < 200; i++) {
+            const r = await cdp.send("Runtime.evaluate", {
+                expression: "({done: !!window.__loticsDone, err: window.__loticsError || '', warnings: window.__loticsWarnings || []})",
+                returnByValue: true,
+            });
+            const v = r.result?.value;
+            if (v?.done) {
+                done = true;
+                err = v.err || undefined;
+                if (v.warnings?.length)
+                    warnings.push(...v.warnings);
+                break;
+            }
+            await sleep(75);
+        }
+        if (!done)
+            throw new Error("Render timed out (page never signaled completion).");
+        if (err)
+            throw new Error(`Render engine error: ${err}`);
+        // Size the capture to the full rendered content, then screenshot beyond viewport.
+        // Clamp to Chrome's ceiling: the PNG is 2× (device scale) the CSS clip, so a CSS side
+        // over ~15000px would blow past the ~32767px canvas limit. A very long docx or several
+        // huge sheets hit this — clamp explicitly and WARN, never clip in silence.
+        const metrics = await cdp.send("Page.getLayoutMetrics");
+        const size = metrics.cssContentSize ?? metrics.contentSize ?? { width: 1240, height: 1600 };
+        const MAX_CAPTURE = 15000; // CSS px; ×2 device scale → ≤30000px PNG
+        const w = Math.ceil(size.width);
+        const h = Math.ceil(size.height);
+        if (w > MAX_CAPTURE || h > MAX_CAPTURE) {
+            warnings.push(`content ${w}×${h}px clipped to ${Math.min(w, MAX_CAPTURE)}×${Math.min(h, MAX_CAPTURE)}px (exceeds the ${MAX_CAPTURE}px capture limit)`);
+        }
+        const shot = await cdp.send("Page.captureScreenshot", {
+            format: "png",
+            captureBeyondViewport: true,
+            clip: { x: 0, y: 0, width: Math.min(w, MAX_CAPTURE), height: Math.min(h, MAX_CAPTURE), scale: 1 },
+        });
+        cdp.close();
+        const outPath = flags.output ? resolve(flags.output) : join(dirname(abs), basename(abs, ext) + ".png");
+        writeFileSync(outPath, Buffer.from(shot.data, "base64"));
+        console.log(`Rendered ${basename(abs)} → ${outPath}  (${Math.min(w, MAX_CAPTURE)}×${Math.min(h, MAX_CAPTURE)}, via ${basename(chrome)})`);
+        for (const warn of warnings)
+            console.error(`  ⚠ ${warn}`);
+    }
+    finally {
+        cleanup();
+    }
+}