@lotics/cli 0.69.0 → 0.71.0

package/dist/render_page.js.LEGAL.txt

@@ -0,0 +1,14 @@
+Bundled license information:
+
+jszip/dist/jszip.min.js:
+  /*!
+  
+  JSZip v3.10.1 - A JavaScript class for generating and reading zip files
+  <http://stuartk.com/jszip>
+  
+  (c) 2009-2016 Stuart Knightley <stuart [at] stuartk.com>
+  Dual licenced under the MIT license or GPLv3. See https://raw.github.com/Stuk/jszip/main/LICENSE.markdown.
+  
+  JSZip uses the library pako released under the MIT license :
+  https://github.com/nodeca/pako/blob/main/LICENSE
+  */

package/dist/src/cli.js

@@ -20127,7 +20127,7 @@ var require_BufferList = __commonJS({
         this.head = this.tail = null;
         this.length = 0;
       };
-      BufferList.prototype.join = function join(s) {
+      BufferList.prototype.join = function join2(s) {
         if (this.length === 0) return "";
         var p = this.head;
         var ret = "" + p.data;
@@ -22102,8 +22102,8 @@ var require_lib2 = __commonJS({
         return this;
       }
       var p = this.constructor;
-      return this.then(resolve2, reject3);
-      function resolve2(value) {
+      return this.then(resolve3, reject3);
+      function resolve3(value) {
         function yes() {
           return value;
         }
@@ -22256,8 +22256,8 @@ var require_lib2 = __commonJS({
       }
       return out;
     }
-    Promise2.resolve = resolve;
-    function resolve(value) {
+    Promise2.resolve = resolve2;
+    function resolve2(value) {
       if (value instanceof this) {
         return value;
       }
@@ -22788,10 +22788,10 @@ var require_utils4 = __commonJS({
       var promise = external.Promise.resolve(inputData).then(function(data) {
         var isBlob = support.blob && (data instanceof Blob || ["[object File]", "[object Blob]"].indexOf(Object.prototype.toString.call(data)) !== -1);
         if (isBlob && typeof FileReader !== "undefined") {
-          return new external.Promise(function(resolve, reject2) {
+          return new external.Promise(function(resolve2, reject2) {
             var reader = new FileReader();
             reader.onload = function(e) {
-              resolve(e.target.result);
+              resolve2(e.target.result);
             };
             reader.onerror = function(e) {
               reject2(e.target.error);
@@ -23346,7 +23346,7 @@ var require_StreamHelper = __commonJS({
       }
     }
     function accumulate(helper, updateCallback) {
-      return new external.Promise(function(resolve, reject2) {
+      return new external.Promise(function(resolve2, reject2) {
         var dataArray = [];
         var chunkType = helper._internalType, resultType = helper._outputType, mimeType = helper._mimeType;
         helper.on("data", function(data, meta) {
@@ -23360,7 +23360,7 @@ var require_StreamHelper = __commonJS({
         }).on("end", function() {
           try {
             var result = transformZipOutput(resultType, concat2(chunkType, dataArray), mimeType);
-            resolve(result);
+            resolve2(result);
           } catch (e) {
             reject2(e);
           }
@@ -29473,7 +29473,7 @@ var require_load = __commonJS({
     var Crc32Probe = require_Crc32Probe();
     var nodejsUtils = require_nodejsUtils();
     function checkEntryCRC32(zipEntry) {
-      return new external.Promise(function(resolve, reject2) {
+      return new external.Promise(function(resolve2, reject2) {
         var worker = zipEntry.decompressed.getContentWorker().pipe(new Crc32Probe());
         worker.on("error", function(e) {
           reject2(e);
@@ -29481,7 +29481,7 @@ var require_load = __commonJS({
           if (worker.streamInfo.crc32 !== zipEntry.decompressed.crc32) {
             reject2(new Error("Corrupted zip : CRC32 mismatch"));
           } else {
-            resolve();
+            resolve2();
           }
         }).resume();
       });
@@ -31553,8 +31553,8 @@ async function startDevServer(args) {
   );
   let stopped = false;
   let stoppingResolve = null;
-  const stoppingPromise = new Promise((resolve) => {
-    stoppingResolve = resolve;
+  const stoppingPromise = new Promise((resolve2) => {
+    stoppingResolve = resolve2;
   });
   viteChild.on("exit", (code, signal) => {
     if (!stopped) {
@@ -31655,11 +31655,11 @@ async function startDevServer(args) {
     res.writeHead(404, { "Content-Type": "text/plain" });
     res.end("Not Found");
   });
-  await new Promise((resolve, reject2) => {
+  await new Promise((resolve2, reject2) => {
     server.once("error", reject2);
     server.listen(wrapperPort, () => {
       server.off("error", reject2);
-      resolve();
+      resolve2();
     });
   });
   async function stopAll() {
@@ -31668,11 +31668,11 @@ async function startDevServer(args) {
     if (!viteChild.killed) {
       viteChild.kill("SIGINT");
     }
-    await new Promise((resolve) => server.close(() => resolve()));
+    await new Promise((resolve2) => server.close(() => resolve2()));
     stoppingResolve?.();
   }
-  const ready = new Promise((resolve) => {
-    setTimeout(resolve, 800);
+  const ready = new Promise((resolve2) => {
+    setTimeout(resolve2, 800);
   });
   return {
     port: wrapperPort,
@@ -31688,22 +31688,22 @@ async function pickPort(preferred, ...avoid) {
   if (!avoid.includes(preferred) && await isPortFree(preferred)) {
     return preferred;
   }
-  return new Promise((resolve, reject2) => {
+  return new Promise((resolve2, reject2) => {
     const srv = net.createServer();
     srv.once("error", reject2);
     srv.listen(0, () => {
       const addr = srv.address();
       const port = typeof addr === "object" && addr ? addr.port : 0;
-      srv.close(() => port ? resolve(port) : reject2(new Error("Failed to pick port")));
+      srv.close(() => port ? resolve2(port) : reject2(new Error("Failed to pick port")));
     });
   });
 }
 function isPortFree(port) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const srv = net.createServer();
-    srv.once("error", () => resolve(false));
+    srv.once("error", () => resolve2(false));
     srv.listen(port, () => {
-      srv.close(() => resolve(true));
+      srv.close(() => resolve2(true));
     });
   });
 }
@@ -31759,7 +31759,7 @@ declare module "@lotics/app-sdk" {
   const inputLines = [];
   const resultLines = [];
   for (const [alias, declaration] of entries) {
-    const valueType = declaration.inputs ? inputsToType(declaration.inputs) : "Record<string, unknown>";
+    const valueType = declaration.inputs ? inputsToType(declaration.inputs, { nullableOptional: true }) : "Record<string, unknown>";
     const aliasKey = isValidIdentifier(alias) ? alias : JSON.stringify(alias);
     inputLines.push(`    ${aliasKey}: ${valueType};`);
     if (declaration.outputs) {
@@ -31778,15 +31778,18 @@ ${inputLines.join("\n")}
 }
 `;
 }
-function inputsToType(inputs) {
+function inputsToType(inputs, opts) {
+  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>";
   return `{
@@ -32334,7 +32337,7 @@ async function fetchWorkflowGlobals(client, projectDir, app_id, alias) {
   }
 }
 function runTar(args, cwd) {
-  return new Promise((resolve, reject2) => {
+  return new Promise((resolve2, reject2) => {
     const proc = spawn2("tar", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
     let stderr = "";
     proc.stderr.on("data", (chunk) => {
@@ -32342,17 +32345,17 @@ function runTar(args, cwd) {
     });
     proc.on("error", reject2);
     proc.on("exit", (code) => {
-      if (code === 0) resolve();
+      if (code === 0) resolve2();
       else reject2(new Error(`tar ${args.join(" ")} failed with exit ${code}: ${stderr}`));
     });
   });
 }
 function runNpm(args, cwd) {
-  return new Promise((resolve, reject2) => {
+  return new Promise((resolve2, reject2) => {
     const proc = spawn2("npm", args, { cwd, stdio: "inherit", env: ipv4ChildEnv(process.env) });
     proc.on("error", reject2);
     proc.on("exit", (code) => {
-      if (code === 0) resolve();
+      if (code === 0) resolve2();
       else reject2(new Error(`npm ${args.join(" ")} exited with code ${code}`));
     });
   });
@@ -32848,11 +32851,11 @@ async function appDev(client, args) {
   console.error(`  Ctrl-C to stop.
 `);
   openBrowser(url);
-  await new Promise((resolve) => {
+  await new Promise((resolve2) => {
     const onSig = () => {
       process.off("SIGINT", onSig);
       process.off("SIGTERM", onSig);
-      resolve();
+      resolve2();
     };
     process.on("SIGINT", onSig);
     process.on("SIGTERM", onSig);
@@ -49652,6 +49655,198 @@ async function runDocxCommand(subcommand, toolArgs, restArgs) {
   }
 }
 
+// src/preview.ts
+import { spawn as spawn3 } from "node:child_process";
+import { createServer } from "node:http";
+import { readFileSync as readFileSync2, writeFileSync, existsSync, mkdtempSync, rmSync, readdirSync } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join, dirname, resolve, extname, basename } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { setTimeout as sleep } from "node:timers/promises";
+var HERE = dirname(fileURLToPath2(import.meta.url));
+function fail2(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+function findChrome() {
+  const env = process.env.LOTICS_CHROME || process.env.CHROME_PATH;
+  if (env && existsSync(env)) return env;
+  const home = process.env.HOME || "";
+  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 rev2 of revs) {
+      for (const r of rel) {
+        const bin = join(pwDir, rev2, 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;
+}
+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 = /* @__PURE__ */ new Map();
+  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 i2 = ++id;
+    pending.set(i2, (r) => res(r));
+    ws.send(JSON.stringify({ id: i2, method, params }));
+  });
+  return { send, close: () => ws.close() };
+}
+async function runPreviewCommand(filePath, flags) {
+  if (!filePath) fail2("Usage: lotics preview <file.docx|.xlsx> [--out <file.png>]");
+  const abs = resolve(filePath);
+  if (!existsSync(abs)) fail2(`File not found: ${abs}`);
+  const ext = extname(abs).toLowerCase();
+  const type = ext === ".docx" ? "docx" : ext === ".xlsx" || ext === ".xls" || ext === ".csv" ? "xlsx" : null;
+  if (!type) fail2(`Unsupported file type "${ext}" \u2014 preview supports .docx and .xlsx/.csv. (PDFs open directly \u2014 no preview needed.)`);
+  if (typeof WebSocket === "undefined") {
+    fail2("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)) fail2(`Render bundle missing at ${bundlePath} \u2014 reinstall @lotics/cli (build step failed).`);
+  const chrome = findChrome();
+  if (!chrome) {
+    fail2(
+      "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 = readFileSync2(abs).toString("base64");
+  const bundle = readFileSync2(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(tmpdir2(), "lotics-render-"));
+  const child = spawn3(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 {
+    }
+    try {
+      server.close();
+    } catch {
+    }
+    try {
+      rmSync(udd, { recursive: true, force: true });
+    } catch {
+    }
+  };
+  try {
+    let cdpPort = 0;
+    const portFile = join(udd, "DevToolsActivePort");
+    for (let i2 = 0; i2 < 100 && !cdpPort; i2++) {
+      if (existsSync(portFile)) {
+        const p = parseInt(readFileSync2(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 i2 = 0; i2 < 60 && !target?.webSocketDebuggerUrl; i2++) {
+      try {
+        const list = await (await fetch(`http://127.0.0.1:${cdpPort}/json/list`)).json();
+        target = list.find((t) => t.type === "page");
+      } catch {
+      }
+      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}/` });
+    let err2;
+    let done = false;
+    const warnings = [];
+    for (let i2 = 0; i2 < 200; i2++) {
+      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;
+        err2 = v.err || void 0;
+        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 (err2) throw new Error(`Render engine error: ${err2}`);
+    const metrics = await cdp.send("Page.getLayoutMetrics");
+    const size = metrics.cssContentSize ?? metrics.contentSize ?? { width: 1240, height: 1600 };
+    const MAX_CAPTURE = 15e3;
+    const w = Math.ceil(size.width);
+    const h = Math.ceil(size.height);
+    if (w > MAX_CAPTURE || h > MAX_CAPTURE) {
+      warnings.push(`content ${w}\xD7${h}px clipped to ${Math.min(w, MAX_CAPTURE)}\xD7${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)} \u2192 ${outPath}  (${Math.min(w, MAX_CAPTURE)}\xD7${Math.min(h, MAX_CAPTURE)}, via ${basename(chrome)})`);
+    for (const warn of warnings) console.error(`  \u26A0 ${warn}`);
+  } finally {
+    cleanup();
+  }
+}
+
 // src/cli.ts
 dns.setDefaultResultOrder("ipv4first");
 net2.setDefaultAutoSelectFamilyAttemptTimeout(2e3);
@@ -49703,10 +49898,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
@@ -49744,6 +49935,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)
@@ -49821,10 +50018,10 @@ Resolution precedence (highest first):
   > global active profile. LOTICS_WORKSPACE / --workspace override the workspace.`);
 }
 function readStdin() {
-  return new Promise((resolve, reject2) => {
+  return new Promise((resolve2, reject2) => {
     const chunks = [];
     process.stdin.on("data", (chunk) => chunks.push(chunk));
-    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8").trim()));
+    process.stdin.on("end", () => resolve2(Buffer.concat(chunks).toString("utf-8").trim()));
     process.stdin.on("error", reject2);
   });
 }
@@ -49833,10 +50030,10 @@ function prompt(question) {
     input: process.stdin,
     output: process.stderr
   });
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     rl.question(question, (answer) => {
       rl.close();
-      resolve(answer.trim());
+      resolve2(answer.trim());
     });
   });
 }
@@ -50003,7 +50200,18 @@ 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;
+  if (command === "file") {
+    if (!subcommand) {
+      printHelp();
+      return;
+    }
+    command = subcommand;
+    subcommand = toolArgs;
+    toolArgs = restArgs.shift();
+  }
   if (flags.help || !command && !flags.version) {
     printHelp();
     return;
@@ -50097,6 +50305,10 @@ async function main() {
     await runDocxCommand(subcommand, toolArgs, restArgs);
     return;
   }
+  if (command === "preview") {
+    await runPreviewCommand(subcommand, flags);
+    return;
+  }
   if (command === "ui") {
     if (subcommand === "link") {
       const component = toolArgs;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.69.0",
+  "version": "0.71.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {