@lotics/cli 0.32.0 → 0.34.0

package/dist/cli.js

@@ -0,0 +1,673 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { LoticsClient, API_BASE_URL } from "./client.js";
+import { resolveAuth, loadConfig, saveConfig, deleteConfig, getConfigPath, checkForUpdate } from "./config.js";
+import { VERSION } from "./version.js";
+import { appCreate, appPull, appDeploy, appDev, appSetSubdomain } from "./app_commands.js";
+import { parseArgs } from "./args.js";
+import { runXlsxCommand } from "./xlsx.js";
+import { runDocxCommand } from "./docx.js";
+function printHelp() {
+    console.log(`Lotics CLI v${VERSION} — AI agent interface for Lotics
+
+Lotics is an AI-powered operations platform. Through this CLI you can:
+  - Manage tables, records, and views (structured data with typed fields)
+  - Generate documents from templates (Excel, Word, PDF, Email)
+  - Build and run automations — schedules, webhooks, table lifecycle workflows,
+    button actions, and app-action workflows; inspect execution and version history
+  - Administer the workspace — invite members, manage groups, share resources,
+    transfer ownership, browse connected accounts (OAuth attach is web-only)
+  - Create and manage apps, knowledge docs, and files
+
+AUTHENTICATION
+  lotics auth                          Show auth help
+  lotics auth signup <email>           Create account (run "lotics auth" for details)
+
+USAGE
+  1. lotics auth signup <email>        Create account or authenticate
+  2. lotics workspace                  Check current workspace (auto-selects if only one)
+  3. lotics tools                      List available tools by category
+  4. lotics tools <name>               Show tool description and full input schema
+  5. lotics run <tool> '<json>'        Execute a tool with JSON arguments
+
+  Always inspect the schema (step 4) before calling a tool.
+  Tools are grouped by category (tables, records, views, etc.).
+  Query tools return IDs used as arguments to other tools.
+
+COMMANDS
+  lotics workspace                     List workspaces (marks current)
+  lotics workspace select <id>         Switch to a different workspace
+  lotics workspace create <name>       Create a new workspace (admin only)
+  lotics tools                         List all available tools
+  lotics tools <name>                  Show tool description and input schema
+  lotics run <tool> '<json>'           Execute a tool
+  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>] [--force-workflow-sync]
+                                       Build + upload current dir as a new version
+                                       (--force-workflow-sync wipes server-only
+                                       workflow aliases; default refuses)
+  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
+  lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
+  lotics xlsx <subcommand> ...         Read/write/edit .xlsx files on your local filesystem
+                                       (uses the bundled Lotics xlsx engine; prefer over
+                                       npm xlsx/exceljs for round-trip fidelity)
+  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)
+
+FLAGS
+  --json             Full JSON output (default is human-readable text)
+  --timeout <ms>     Timeout for tool execution (default: 60000)
+  -o <path>          Output dir for downloads
+  --as <name>        Override upload filename
+  --api-key <key>    API key (overrides saved config and LOTICS_API_KEY)
+  --local            (lotics auth) Save credentials to ./.lotics/config.json
+  --version          Show version
+
+CONFIG
+  Credentials resolve from a .lotics/config.json found by walking up from the
+  current directory, else the global ~/.lotics/config.json. Run "lotics auth
+  api-key <key> --local" inside a directory (e.g. a worktree) to pin it to its
+  own account and workspace.
+
+OUTPUT
+  Default output is a compact text summary optimized for AI agents —
+  use it directly, no parsing needed. --json returns raw structured
+  JSON for machine-to-machine pipelines (scripts, CI). Errors print
+  to stderr and exit with code 1.
+
+FILES
+  Some tools generate files and return { file_id, url, filename }.
+  Use lotics download to save locally:
+
+    lotics run generate_excel_from_template '{"..."}'
+    lotics download <file_id> -o ./output/
+
+  Upload files before referencing them in tool args:
+
+    lotics upload ./data.csv ./report.pdf ./documents/
+    lotics run create_records '{"table_id":"tbl_...","records":[{"fld_file":["fil_..."]}]}'
+
+STDIN
+  Pipe JSON arguments via stdin instead of inline:
+
+    echo '{"table_id":"tbl_..."}' | lotics run query_records`);
+}
+function printAuthHelp() {
+    console.log(`Authentication commands:
+
+  lotics auth signup <email>           Create account, org, workspace, and API key
+  lotics auth api-key [key]            Save an existing API key (e.g. from the web app)
+  lotics auth web                      Send a magic link email to access the web app
+  lotics auth whoami                   Show the current account's name, email, and organization
+  lotics auth logout                   Remove saved credentials
+
+Auth flags:
+  --local                Save credentials to ./.lotics/config.json (this directory)
+                         instead of the global ~/.lotics — applies to signup + api-key
+  --name <name>          (signup) Display name (defaults to email prefix)
+  --timezone <timezone>  (signup) Workspace timezone (defaults to UTC, e.g. Asia/Ho_Chi_Minh)
+
+Signup sends a magic link email so you can access the Lotics web app.
+Use lotics auth web to request a new magic link at any time.
+
+Auth priority: --api-key flag > LOTICS_API_KEY env > config file.
+Config file: .lotics/config.json found by walking up from the current directory,
+else ~/.lotics/config.json. A per-directory config pins a project or worktree to
+its own account and workspace; --local creates one. Note: an exported
+LOTICS_API_KEY env var overrides the config file's key.`);
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        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("error", reject);
+    });
+}
+function prompt(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+async function publicPost(path, body) {
+    const response = await fetch(`${API_BASE_URL}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const data = await response.json();
+    return { ok: response.ok, status: response.status, data };
+}
+async function handleSignup(positionalEmail, flags) {
+    const email = positionalEmail ?? (process.stdin.isTTY ? await prompt("Email: ") : "");
+    if (!email) {
+        console.error("Email is required. Usage: lotics auth signup <email>");
+        process.exit(1);
+    }
+    const name = flags.name ?? (process.stdin.isTTY ? await prompt("Name (enter to use email): ") : undefined);
+    const body = { email };
+    if (name)
+        body.name = name;
+    if (flags.timezone)
+        body.timezone = flags.timezone;
+    const { ok, status, data } = await publicPost("/v1/cli/signup", body);
+    if (!ok) {
+        if (status === 409) {
+            console.error("An account with this email already exists. Use: lotics auth api-key");
+        }
+        else if (status === 429) {
+            console.error("Too many signup attempts. Try again later.");
+        }
+        else {
+            console.error(`Signup failed: ${data.message ?? JSON.stringify(data)}`);
+        }
+        process.exit(1);
+    }
+    const scope = flags.local ? "local" : "auto";
+    const existing = loadConfig(scope) ?? {};
+    saveConfig({
+        ...existing,
+        api_key: data.api_key,
+        email: data.email,
+        workspace_id: data.workspace_id,
+    }, scope);
+    console.error(`Account created. You can now use the CLI.`);
+    console.error(`  Email:  ${data.email}`);
+    console.error(`  Config: ${getConfigPath(scope)}`);
+    console.error(`\nCheck your email for a magic link to access the Lotics web app.`);
+    console.error(`Run "lotics auth web" to request a new link at any time.`);
+}
+async function handleSetup(providedKey, local) {
+    const apiKey = providedKey ?? await prompt("Enter your API key: ");
+    if (!apiKey) {
+        console.error("No API key provided.");
+        process.exit(1);
+    }
+    const client = new LoticsClient({ apiKey });
+    let email;
+    try {
+        const info = await client.whoami();
+        email = info.email;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Authentication failed: ${message}`);
+        process.exit(1);
+    }
+    const scope = local ? "local" : "auto";
+    const existing = loadConfig(scope) ?? {};
+    const newConfig = { ...existing, api_key: apiKey, email };
+    // Auto-resolve workspace
+    try {
+        const workspaces = await client.listWorkspaces();
+        if (workspaces.length === 1) {
+            newConfig.workspace_id = workspaces[0].id;
+        }
+        else if (workspaces.length > 1) {
+            console.error(`\nMultiple workspaces found. Run "lotics workspace select <id>" to choose one:`);
+            printWorkspaceList(workspaces);
+        }
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(`Warning: could not resolve workspace: ${msg}`);
+    }
+    saveConfig(newConfig, scope);
+    console.error("Authenticated.");
+    console.error(`  Config: ${getConfigPath(scope)}`);
+}
+function requireClient(flags) {
+    const auth = resolveAuth(flags);
+    if (!auth) {
+        console.error('Not authenticated. Run "lotics auth signup" or set LOTICS_API_KEY.');
+        process.exit(1);
+    }
+    const config = loadConfig();
+    return new LoticsClient({ apiKey: auth.apiKey, workspaceId: config?.workspace_id });
+}
+function printWorkspaceList(workspaces, currentId) {
+    for (const ws of workspaces) {
+        const marker = ws.id === currentId ? " (current)" : "";
+        console.error(`  ${ws.id}  ${ws.name}  ${ws.timezone}  ${ws.default_currency}${marker}`);
+    }
+}
+async function resolveWorkspace(client) {
+    const config = loadConfig();
+    if (config?.workspace_id)
+        return;
+    let workspaces;
+    try {
+        workspaces = await client.listWorkspaces();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Failed to list workspaces: ${message}`);
+        process.exit(1);
+    }
+    if (workspaces.length === 0) {
+        console.error("No workspaces found for this organization.");
+        process.exit(1);
+    }
+    if (workspaces.length === 1) {
+        const existing = config ?? {};
+        saveConfig({ ...existing, workspace_id: workspaces[0].id });
+        client.setWorkspaceId(workspaces[0].id);
+        return;
+    }
+    // Multiple workspaces, none selected
+    console.error("Multiple workspaces available. Select one with:\n");
+    console.error('  lotics workspace select <id>\n');
+    printWorkspaceList(workspaces);
+    console.error("");
+    process.exit(1);
+}
+/**
+ * Resolve upload paths: files pass through, directories expand to their immediate files.
+ */
+function resolveUploadPaths(rawPaths) {
+    const result = [];
+    for (const p of rawPaths) {
+        const resolved = path.resolve(p);
+        const stat = fs.statSync(resolved);
+        if (stat.isDirectory()) {
+            const entries = fs.readdirSync(resolved, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isFile()) {
+                    result.push(path.join(resolved, entry.name));
+                }
+            }
+        }
+        else {
+            result.push(resolved);
+        }
+    }
+    return result;
+}
+async function main() {
+    const { command, subcommand, toolArgs, restArgs, flags } = parseArgs(process.argv.slice(2));
+    if (flags.help || (!command && !flags.version)) {
+        printHelp();
+        return;
+    }
+    if (flags.version) {
+        console.log(VERSION);
+        return;
+    }
+    // --- lotics auth <subcommand> ---
+    if (command === "auth") {
+        if (subcommand === "signup") {
+            await handleSignup(toolArgs, flags);
+            return;
+        }
+        if (subcommand === "api-key") {
+            await handleSetup(toolArgs ?? flags.apiKey, flags.local);
+            return;
+        }
+        if (subcommand === "whoami") {
+            const auth = resolveAuth(flags);
+            if (!auth) {
+                console.error('Not authenticated. Run "lotics auth signup" or set LOTICS_API_KEY.');
+                process.exit(1);
+            }
+            const client = new LoticsClient({ apiKey: auth.apiKey });
+            const info = await client.whoami();
+            const existing = loadConfig() ?? {};
+            saveConfig({ ...existing, email: info.email });
+            if (flags.json) {
+                console.log(JSON.stringify(info, null, 2));
+            }
+            else {
+                console.log(`Name:    ${info.name}`);
+                console.log(`Email:   ${info.email}`);
+                console.log(`Org:     ${info.organization_name} (${info.organization_id})`);
+            }
+            console.error(`Config:  ${getConfigPath()}`);
+            return;
+        }
+        if (subcommand === "logout") {
+            deleteConfig();
+            console.error("Logged out. Credentials removed.");
+            return;
+        }
+        if (subcommand === "web") {
+            const client = requireClient(flags);
+            const { email } = await client.login();
+            console.error(`Magic link sent to ${email}. Check your email to access the Lotics web app.`);
+            return;
+        }
+        if (subcommand) {
+            console.error(`Unknown auth subcommand: ${subcommand}\n`);
+        }
+        printAuthHelp();
+        return;
+    }
+    // --- Local file commands — no auth required ---
+    if (command === "xlsx") {
+        await runXlsxCommand(subcommand, toolArgs, restArgs);
+        return;
+    }
+    if (command === "docx") {
+        await runDocxCommand(subcommand, toolArgs, restArgs);
+        return;
+    }
+    // --- Validate command before auth ---
+    if (command !== "tools" && command !== "upload" && command !== "run" && command !== "download" && command !== "workspace" && command !== "app") {
+        console.error(`Unknown command: ${command}`);
+        console.error('Run "lotics --help" for usage.');
+        process.exit(1);
+    }
+    if (command === "app" && !subcommand) {
+        console.error("Usage:");
+        console.error("  lotics app create <name> [path]      Scaffold a new app locally");
+        console.error("  lotics app pull <app_id> [path]      Pull an existing app for local editing");
+        console.error("  lotics app deploy [-m <message>] [--force-workflow-sync]");
+        console.error("                                       Build + upload the current directory");
+        console.error("  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address");
+        console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
+        process.exit(1);
+    }
+    if (command === "run" && !subcommand) {
+        console.error('Usage: lotics run <tool> \'<json_args>\'');
+        console.error('Run "lotics tools" to see available tools.');
+        process.exit(1);
+    }
+    if (command === "upload" && !subcommand) {
+        console.error('Usage: lotics upload <file|dir...> [--as <name>]');
+        console.error('Uploads files and returns their file_ids. Directories expand to their immediate files.');
+        process.exit(1);
+    }
+    if (command === "download" && !subcommand) {
+        console.error('Usage:');
+        console.error('  lotics download <file_id> [-o <dir>]');
+        console.error('  lotics download record <record_id> <field_key> [-o <dir>]');
+        console.error('File IDs come from upload results or generate_* tool output (--json).');
+        process.exit(1);
+    }
+    if (command === "download" && subcommand === "record" && (!toolArgs || restArgs.length === 0)) {
+        console.error('Usage: lotics download record <record_id> <field_key> [-o <dir>]');
+        console.error('Downloads every file on the given file field into the output dir.');
+        process.exit(1);
+    }
+    const client = requireClient(flags);
+    // lotics workspace / lotics workspace list / lotics workspace select <id>
+    if (command === "workspace") {
+        const workspaces = await client.listWorkspaces();
+        const config = loadConfig();
+        if (subcommand === "select") {
+            const targetId = toolArgs;
+            if (!targetId) {
+                console.error('Usage: lotics workspace select <workspace_id>');
+                process.exit(1);
+            }
+            const target = workspaces.find((ws) => ws.id === targetId);
+            if (!target) {
+                console.error(`Workspace not found: ${targetId}\n\nAvailable workspaces:`);
+                printWorkspaceList(workspaces, config?.workspace_id);
+                process.exit(1);
+            }
+            const existing = config ?? {};
+            saveConfig({ ...existing, workspace_id: target.id });
+            console.error(`Switched to workspace: ${target.name} (${target.id})`);
+            return;
+        }
+        if (subcommand === "create") {
+            const name = toolArgs;
+            if (!name) {
+                console.error('Usage: lotics workspace create <name> [--timezone <tz>]');
+                process.exit(1);
+            }
+            const timezone = flags.timezone;
+            const created = await client.createWorkspace({ name, timezone });
+            const existing = config ?? {};
+            saveConfig({ ...existing, workspace_id: created.id });
+            client.setWorkspaceId(created.id);
+            if (flags.json) {
+                console.log(JSON.stringify(created, null, 2));
+            }
+            else {
+                console.error(`Created workspace: ${created.name} (${created.id})`);
+                console.error(`Switched to ${created.id}`);
+            }
+            return;
+        }
+        // Default: list workspaces
+        if (subcommand && subcommand !== "list") {
+            console.error(`Unknown workspace subcommand: ${subcommand}`);
+            console.error('Usage: lotics workspace [list | select <id> | create <name>]');
+            process.exit(1);
+        }
+        if (flags.json) {
+            console.log(JSON.stringify(workspaces, null, 2));
+        }
+        else {
+            if (workspaces.length === 0) {
+                console.error("No workspaces found.");
+            }
+            else {
+                for (const ws of workspaces) {
+                    const marker = ws.id === config?.workspace_id ? " (current)" : "";
+                    console.log(`${ws.id}  ${ws.name}  ${ws.timezone}  ${ws.default_currency}${marker}`);
+                }
+            }
+        }
+        console.error(`Config: ${getConfigPath()}`);
+        return;
+    }
+    // Ensure workspace is resolved for all remaining commands
+    await resolveWorkspace(client);
+    // lotics app create / pull / deploy
+    if (command === "app") {
+        if (subcommand === "create") {
+            const name = toolArgs;
+            if (!name) {
+                console.error("Usage: lotics app create <name> [path]");
+                process.exit(1);
+            }
+            const targetPath = restArgs[0];
+            await appCreate(client, { name, targetPath });
+            return;
+        }
+        if (subcommand === "pull") {
+            const appId = toolArgs;
+            if (!appId) {
+                console.error("Usage: lotics app pull <app_id> [path]");
+                process.exit(1);
+            }
+            const targetPath = restArgs[0];
+            await appPull(client, { app_id: appId, targetPath });
+            return;
+        }
+        if (subcommand === "deploy") {
+            // The message is either `-m <message>` or a bare positional arg after
+            // `deploy`. `--force-workflow-sync` is a parsed boolean flag, valid in
+            // any position.
+            const message = flags.message ?? toolArgs;
+            await appDeploy(client, { message, forceWorkflowSync: flags.forceWorkflowSync });
+            return;
+        }
+        if (subcommand === "subdomain") {
+            const newSubdomain = toolArgs;
+            if (!newSubdomain) {
+                console.error("Usage: lotics app subdomain <new-subdomain>");
+                console.error("Renames the app's public address — https://<slug>.lotics.app");
+                process.exit(1);
+            }
+            await appSetSubdomain(client, { subdomain: newSubdomain });
+            return;
+        }
+        if (subcommand === "dev") {
+            // First positional is an optional project path (defaults to cwd).
+            // --port and --vite-port can override the wrapper / Vite ports.
+            const projectDir = toolArgs;
+            let port;
+            let vitePort;
+            for (const a of restArgs) {
+                const portMatch = /^--port=(\d+)$/.exec(a);
+                const vitePortMatch = /^--vite-port=(\d+)$/.exec(a);
+                if (portMatch)
+                    port = Number(portMatch[1]);
+                else if (vitePortMatch)
+                    vitePort = Number(vitePortMatch[1]);
+            }
+            await appDev(client, { projectDir, port, vitePort });
+            return;
+        }
+        console.error(`Unknown app subcommand: ${subcommand}`);
+        console.error("Run 'lotics app' for usage.");
+        process.exit(1);
+    }
+    // lotics tools / lotics tools <name>
+    if (command === "tools") {
+        if (subcommand) {
+            const info = await client.getTool(subcommand);
+            if (flags.json) {
+                console.log(JSON.stringify(info, null, 2));
+            }
+            else {
+                console.log(`${info.name}\n\n${info.description}\n\nInput schema:\n${JSON.stringify(info.input_schema, null, 2)}`);
+            }
+        }
+        else {
+            const { categories } = await client.listTools();
+            if (flags.json) {
+                console.log(JSON.stringify(categories, null, 2));
+            }
+            else {
+                for (const [category, { description, tools }] of Object.entries(categories)) {
+                    console.log(description ? `\n## ${category} — ${description}` : `\n## ${category}`);
+                    console.log(`  ${tools.join(", ")}`);
+                }
+                console.log("");
+            }
+        }
+        return;
+    }
+    // lotics upload <file|dir...> [--as <name>]
+    if (command === "upload") {
+        const rawPaths = [subcommand, ...(toolArgs ? [toolArgs] : []), ...restArgs];
+        const filePaths = resolveUploadPaths(rawPaths);
+        if (filePaths.length === 0) {
+            console.error("No files found in the specified paths.");
+            process.exit(1);
+        }
+        if (flags.as && filePaths.length > 1) {
+            console.error("Cannot use --as with multiple files.");
+            process.exit(1);
+        }
+        const upload = await client.uploadFiles(filePaths, {
+            filenames: flags.as ? [flags.as] : undefined,
+        });
+        if (upload.files.length === 0 && upload.errors.length > 0) {
+            console.error(`Upload failed: ${upload.errors.map((e) => `${e.filename}: ${e.error}`).join(", ")}`);
+            process.exit(1);
+        }
+        if (flags.json) {
+            console.log(JSON.stringify({ files: upload.files, errors: upload.errors }, null, 2));
+        }
+        else {
+            for (let i = 0; i < upload.files.length; i++) {
+                const file = upload.files[i];
+                console.log(`[${i + 1}] ${file.id}  ${file.filename}  ${file.mime_type}`);
+            }
+            for (const error of upload.errors) {
+                console.error(`FAILED  ${error.filename}  ${error.error}`);
+            }
+        }
+        return;
+    }
+    // lotics download <file_id> [-o <path>]
+    // lotics download record <record_id> <field_key> [-o <path>]
+    if (command === "download") {
+        if (subcommand === "record") {
+            const recordId = toolArgs;
+            const fieldKey = restArgs[0];
+            const files = await client.downloadRecordFiles(recordId, fieldKey, flags.output);
+            if (flags.json) {
+                console.log(JSON.stringify(files, null, 2));
+            }
+            else {
+                for (const f of files) {
+                    console.log(`${f.file_id}  ${f.path}  ${f.filename}`);
+                }
+                console.error(`Downloaded ${files.length} file${files.length === 1 ? "" : "s"} from ${recordId}.${fieldKey}`);
+            }
+            return;
+        }
+        const { path: filePath, filename } = await client.downloadFileById(subcommand, flags.output);
+        console.error(`Downloaded: ${filePath} (${filename})`);
+        return;
+    }
+    // lotics run <tool> [json_args]
+    if (command === "run") {
+        const toolName = subcommand;
+        let rawArgs = toolArgs;
+        if (!rawArgs && !process.stdin.isTTY) {
+            rawArgs = await readStdin();
+        }
+        let args = {};
+        if (rawArgs) {
+            try {
+                args = JSON.parse(rawArgs);
+            }
+            catch {
+                console.error(`Invalid JSON: ${rawArgs}`);
+                process.exit(1);
+            }
+        }
+        const timeoutMs = flags.timeout ?? 60000;
+        // Always request text format so model_output is available; --json only affects CLI output
+        const result = await client.execute(toolName, args, { format: "text", timeoutMs });
+        if (result.error) {
+            if (flags.json) {
+                console.log(JSON.stringify({ error: result.error }, null, 2));
+            }
+            else {
+                console.error(result.error);
+                console.error(`\nHint: run "lotics tools ${toolName}" to see the expected input schema.`);
+            }
+            process.exit(1);
+        }
+        if (flags.json) {
+            console.log(JSON.stringify(result.result, null, 2));
+        }
+        else if (result.model_output) {
+            console.log(result.model_output);
+        }
+        else {
+            // Fallback: compact JSON when no text output is available
+            console.log(JSON.stringify(result.result, null, 2));
+        }
+        return;
+    }
+}
+main()
+    .then(() => checkForUpdate(VERSION))
+    .catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("fetch failed") || message.includes("ECONNREFUSED")) {
+        console.error("Could not connect to the Lotics API.");
+    }
+    else if (message.includes("ENOENT")) {
+        const pathMatch = message.match(/open '([^']+)'/);
+        console.error(`File not found: ${pathMatch?.[1] ?? message}`);
+    }
+    else {
+        console.error(message);
+    }
+    process.exit(1);
+});

package/dist/{src/dev → dev}/wrapper_page.d.ts

@@ -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.
  *