@lotics/cli 0.69.0 → 0.71.0

package/dist/cli.js

@@ -18,6 +18,7 @@ import { parseArgs } from "./args.js";
 import { ingestJsonArgs } from "./inputs.js";
 import { runXlsxCommand } from "./xlsx.js";
 import { runDocxCommand } from "./docx.js";
+import { runPreviewCommand } from "./preview.js";
 function printHelp() {
     console.log(`Lotics CLI v${VERSION} — AI agent interface for Lotics
 
@@ -66,10 +67,6 @@ COMMANDS
   lotics run <tool> '<json>'           Execute a tool
   lotics run <tool> @args.json         Read JSON args from a file (large payloads)
   cat args.json | lotics run <tool>    Read JSON args from stdin (large payloads)
-  lotics upload <file|dir...>          Upload files (directories expand to their immediate files)
-  lotics download <file_id>            Download a file by ID
-  lotics download record <record_id> <field_key>
-                                       Download all files on a record file field
   lotics app create <name> [path]      Create a new custom-code app + scaffold locally
   lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
   lotics app deploy -m <message>       Build + upload current dir as a new version
@@ -107,6 +104,12 @@ COMMANDS
   lotics docx <subcommand> ...         Read/write/edit .docx files on your local filesystem
                                        (uses the bundled Lotics OOXML engine; preserves
                                        tables, images, and unknown markup verbatim)
+  lotics file upload <file|dir...>     Upload files (alias: lotics upload)
+  lotics file download <file_id>       Download a file by ID (alias: lotics download)
+  lotics file download record <record_id> <field_key>
+                                       Download all files on a record file field
+  lotics file preview <file> [-o png]  Render a .docx/.xlsx to a PNG (frontend engines;
+                                       needs a Chrome/Chromium on the machine)
 
 FLAGS
   --json             Full JSON output (default is human-readable text)
@@ -392,7 +395,22 @@ function resolveUploadPaths(rawPaths) {
     return result;
 }
 async function main() {
-    const { command, subcommand, toolArgs, restArgs, flags } = parseArgs(process.argv.slice(2));
+    const parsed = parseArgs(process.argv.slice(2));
+    const { restArgs, flags } = parsed;
+    let { command, subcommand, toolArgs } = parsed;
+    // `file` is a thin noun-group over the file verbs: `lotics file <upload|download|preview>
+    // <args…>` strips the prefix and re-dispatches to the same handlers as the top-level
+    // verbs (which stay as aliases). Positional shift only — flags are untouched, and
+    // `download record <id> <field>` still works as `file download record <id> <field>`.
+    if (command === "file") {
+        if (!subcommand) {
+            printHelp();
+            return;
+        }
+        command = subcommand;
+        subcommand = toolArgs;
+        toolArgs = restArgs.shift();
+    }
     if (flags.help || (!command && !flags.version)) {
         printHelp();
         return;
@@ -494,6 +512,10 @@ async function main() {
         await runDocxCommand(subcommand, toolArgs, restArgs);
         return;
     }
+    if (command === "preview") {
+        await runPreviewCommand(subcommand, flags);
+        return;
+    }
     // --- lotics ui link <component> [--remove] — local vite.config edit, no auth ---
     if (command === "ui") {
         if (subcommand === "link") {

package/dist/generate_app_workflows_dts.d.ts

@@ -26,7 +26,9 @@ export declare function generateAppWorkflowsDts(workflows: Record<string, AppWor
  * to `unknown` rather than throwing — the server's deploy-time schema parse
  * catches structurally-invalid declarations before they reach us.
  */
-export declare function inputsToType(inputs: Record<string, unknown>): string;
+export declare function inputsToType(inputs: Record<string, unknown>, opts?: {
+    nullableOptional?: boolean;
+}): string;
 /**
  * Map an output `fields` map (also the top-level `outputs`) to a TS object type.
  * Mirrors the backend `outputObjectToTsType`; recursive for nested object/array.

package/dist/generate_app_workflows_dts.js

@@ -41,7 +41,7 @@ declare module "@lotics/app-sdk" {
         // No typed inputs ⇒ untyped `Record<string, unknown>` callable. An alias with
         // declared `outputs` also gets an `AppWorkflowResults` entry → typed result.data.
         const valueType = declaration.inputs
-            ? inputsToType(declaration.inputs)
+            ? inputsToType(declaration.inputs, { nullableOptional: true })
             : "Record<string, unknown>";
         const aliasKey = isValidIdentifier(alias) ? alias : JSON.stringify(alias);
         inputLines.push(`    ${aliasKey}: ${valueType};`);
@@ -74,16 +74,27 @@ ${inputLines.join("\n")}
  * to `unknown` rather than throwing — the server's deploy-time schema parse
  * catches structurally-invalid declarations before they reach us.
  */
-export function inputsToType(inputs) {
+export function inputsToType(inputs, opts) {
+    // A WORKFLOW optional input also accepts `null` — the diff-write "clear this
+    // field" signal (the backend validates it, the body forwards it to
+    // `update_records({ set: { fld: null } })`). So `useWorkflow` call sites can
+    // pass `null` to unset a field without a loose `Record<string, unknown>` cast.
+    // Query params + agent inputs have no "clear", so they stay `T` (the caller
+    // omits the flag). Only the TOP level is nullable: a nested object's optional
+    // field mirrors the backend's plain `.optional()` (the recursive call below
+    // omits the flag), so the type never claims a nested clear the server rejects.
+    const nullableOptional = opts?.nullableOptional === true;
     const fields = [];
     for (const [key, decl] of Object.entries(inputs)) {
         if (decl === null || typeof decl !== "object")
             continue;
         const d = decl;
         const tsType = inputDeclToTsType(d);
-        const optional = d.required === false ? "?" : "";
+        const isOptional = d.required === false;
+        const fieldType = isOptional && nullableOptional ? `${tsType} | null` : tsType;
+        const optional = isOptional ? "?" : "";
         const fieldKey = isValidIdentifier(key) ? key : JSON.stringify(key);
-        fields.push(`      ${fieldKey}${optional}: ${tsType};`);
+        fields.push(`      ${fieldKey}${optional}: ${fieldType};`);
     }
     if (fields.length === 0)
         return "Record<string, never>";

package/dist/generate_app_workflows_dts.test.js

@@ -58,6 +58,32 @@ describe("generateAppWorkflowsDts", () => {
         expect(dts).toContain("note?: string;");
         expect(dts).toContain("ref: string;");
     });
+    it("types a TOP-LEVEL optional workflow input as `T | null` (the diff-write clear signal), required stays `T`, nested stays plain optional", () => {
+        const dts = generateAppWorkflowsDts({
+            updateTask: {
+                workflow_id: "wfl_u",
+                inputs: {
+                    record_id: { type: "record_link", table_id: "tbl_x" },
+                    due: { type: "date", required: false },
+                    status: { type: "select", required: false, options: [{ label: "Done", value: "opt_done" }] },
+                    tags: { type: "select", multi: true, required: false, options: [{ label: "A", value: "opt_a" }] },
+                    meta: {
+                        type: "object",
+                        required: false,
+                        fields: { note: { type: "text", required: false } },
+                    },
+                },
+            },
+        });
+        expect(dts).toContain("record_id: string;"); // required → NOT nullable
+        expect(dts).toContain("due?: string | null;"); // optional scalar → clearable
+        expect(dts).toContain('status?: "opt_done" | null;');
+        expect(dts).toContain('tags?: ReadonlyArray<"opt_a"> | null;'); // optional multi
+        // The object itself is a top-level optional → nullable; its NESTED optional
+        // field mirrors the backend's plain `.optional()` (no `| null`).
+        expect(dts).toContain("note?: string;");
+        expect(dts).not.toContain("note?: string | null;");
+    });
     it("maps record_link/select outputs the same way as inputs", () => {
         const dts = generateAppWorkflowsDts({
             lookup: {

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();
+    }
+}