@lotics/cli 0.88.0 → 0.89.1

package/dist/cli.js

@@ -1,1095 +0,0 @@
-#!/usr/bin/env node
-import dns from "node:dns";
-import net from "node:net";
-import fs from "node:fs";
-import path from "node:path";
-import readline from "node:readline";
-// WSL2 + Node 24's Happy-Eyeballs races IPv4/IPv6 and intermittently stalls on a
-// dead IPv6 route to api.lotics.ai (curl works; node fetch ETIMEDOUTs). Prefer
-// IPv4 and cap the per-family attempt so a bad IPv6 path fails fast to IPv4.
-// Bin-only side effect — client.ts stays pure for SDK consumers.
-dns.setDefaultResultOrder("ipv4first");
-net.setDefaultAutoSelectFamilyAttemptTimeout(2000);
-import { LoticsClient, API_BASE_URL } from "./client.js";
-import { resolveContext, deleteConfig, getConfigPath, loadGlobalConfig, saveGlobalConfig, loadLocalConfig, upsertProfile, removeProfile, setActiveOrg, setSelectedWorkspace, resolveProfileByNameOrId, checkForUpdate, } from "./config.js";
-import { VERSION } from "./version.js";
-import { appCreate, appPull, appDeploy, appDev, appSetSubdomain, appRename, appVersions, appCodegen, appExecuteWorkflow, appWorkflowSet, appWorkflowPull, appWorkflowCheck, appQuerySet, appUiLink, } from "./app_commands.js";
-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
-
-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)
-  lotics auth api-key <key>            Save a key — registers its org as a profile
-
-ORGANIZATIONS
-  Each saved API key belongs to one org. Register a key per org once, then
-  switch between them with no re-pasting. Workspaces live inside an org.
-  lotics org                           List saved orgs (marks active)
-  lotics org use <name|id>             Switch the active org
-  lotics org use <name|id> --local     Pin THIS directory to an org (worktrees)
-
-USAGE
-  1. lotics auth signup <email>        Create account or authenticate
-  2. lotics org                        See saved orgs / which one is active
-  3. lotics workspace                  Check current workspace (auto-selects if only one)
-  4. lotics tools                      List available tools by category
-  5. lotics tools <name>               Show tool description and full input schema
-  6. 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 org                           List saved orgs (marks active)
-  lotics org use <name|id> [--local]   Switch active org (--local pins this dir)
-  lotics workspace                     List workspaces in the active org (marks current)
-  lotics workspace select <id>         Switch to a different workspace
-  lotics workspace create <name>       Create a new workspace (admin only)
-  lotics workspace delete <id> --yes   Delete a workspace (admin only; soft delete, recoverable)
-  lotics workspace doctor              Report dangling schema references (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 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 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 — COMMIT
-                                       (-m is required — it's the version's audit trail;
-                                       carries code + queries only — workflow bindings are
-                                       managed by set_app_workflow / remove_app_workflow)
-  lotics app versions [app_id]         Show deploy history newest-first (version,
-                                       timestamp, deployer, build status, -m message;
-                                       * marks the currently served version)
-  lotics app codegen [path]            Regenerate .lotics/* (types + field/option ids)
-                                       from the manifest + workspace schema — no deploy
-  lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end
-                                       (inputs: inline JSON, @file, or stdin;
-                                        --print-created reports created records +
-                                        a paste-ready cleanup plan; --cleanup also
-                                        deletes those records — NOT a rollback)
-  lotics app workflow set <alias>      Push the edited src/workflows/<alias>.ts body
-                                       through set_app_workflow (server verifies)
-  lotics app workflow pull             Rewrite src/workflows/*.ts from the server
-  lotics app workflow check [alias]    Typecheck src/workflows bodies locally (one
-                                       isolated program per alias; the app's own tsc)
-  lotics app query set <alias>         Push package.json#lotics.queries.<alias> to
-                                       apps.queries via set_app_query (no deploy;
-                                       re-synced by the next deploy from the manifest)
-  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
-  lotics app rename "<new name>"       Rename the app's display name (launcher title)
-  lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
-  lotics ui link <component> [--ui-src <path>] [--remove]
-                                       Dev-link @lotics/ui to packages/ui/src (Vite alias
-                                       + tsc paths) for live HMR + typecheck. Monorepo apps
-                                       auto-find it; external apps pass --ui-src / LOTICS_UI_SRC
-  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)
-  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)
-  --timeout <ms>     Timeout for tool execution (default: 60000)
-  -o <path>          Output dir for downloads
-  --as <name>        Override upload filename
-  --api-key <key>    One-off API key (overrides saved config + env)
-  --workspace <id>   One-off workspace override (alias: -w)
-  --view-as <id>     Admin "View as": run every request as this member, so
-                     is_current_member / row-scoping resolve to them (also
-                     LOTICS_VIEW_AS env; admin key only; writes stay yours)
-  --local            Pin the current directory (lotics org use / auth api-key)
-  --all              (lotics auth logout) Remove every saved credential
-  --version          Show version
-
-CONFIG
-  API keys are stored once per org in the global ~/.lotics/config.json as named
-  profiles. Switch with "lotics org use <name|id>" — no re-pasting. A directory
-  (e.g. a git worktree) can pin its own org/workspace with "lotics org use
-  <name|id> --local", which writes a .lotics/config.json pointer (the key is
-  resolved from the global store) — so a global switch never disturbs it.
-
-  Resolution precedence (highest first):
-    --api-key flag  >  LOTICS_API_KEY env  >  LOTICS_ORG env  >
-    local .lotics/config.json  >  global active profile
-  LOTICS_WORKSPACE (or --workspace) overrides the workspace at any level.
-
-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 API key — registers its org as a profile
-  lotics auth web                      Send a magic link email to access the web app
-  lotics auth whoami                   Show the active account, org, workspace, and source
-  lotics auth logout [<name|id>]       Remove a saved credential (default: the active org,
-                                       or unpin the current directory)
-  lotics auth logout --all             Remove every saved credential
-
-Auth flags:
-  --local                Pin the current directory instead of the global store.
-                         signup/api-key write a self-contained ./.lotics/config.json
-                         (inline key) — for a hermetic worktree or CI.
-  --name <name>          (signup) Display name (defaults to email prefix)
-  --timezone <timezone>  (signup) Workspace timezone (defaults to UTC, e.g. Asia/Ho_Chi_Minh)
-
-API keys are stored once per org as named profiles in ~/.lotics/config.json.
-Registering a second key adds a profile — it does not overwrite the first.
-Switch active org with "lotics org use <name|id>".
-
-Resolution precedence (highest first):
-  --api-key flag > LOTICS_API_KEY env > LOTICS_ORG env > local .lotics/config.json
-  > global active profile. LOTICS_WORKSPACE / --workspace override the workspace.`);
-}
-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 apiKey = data.api_key;
-    const orgId = data.organization_id;
-    const workspaceId = data.workspace_id;
-    // The org is created with the display name; mirror the server's email-prefix
-    // default when none was supplied. Use `||` (not `??`) so an empty-string name
-    // falls through exactly as the server's `if (name)` truthiness check does.
-    const orgName = name || email.split("@")[0];
-    // The key always lives in the global store as a profile; --local additionally
-    // pins this directory to it (a pointer), instead of making it the global default.
-    upsertProfile(orgId, { api_key: apiKey, org_name: orgName, workspace_id: workspaceId });
-    const existing = loadGlobalConfig() ?? {};
-    saveGlobalConfig({ ...existing, email });
-    setActiveOrg(orgId, flags.local ? "local" : "global");
-    console.error(`Account created. You can now use the CLI.`);
-    console.error(`  Email:  ${email}`);
-    console.error(`  Org:    ${orgName} (${orgId})`);
-    console.error(flags.local
-        ? `  Pinned this directory: ${getConfigPath("local")}`
-        : `  Saved to the "${orgName}" profile in ~/.lotics (now active)`);
-    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 info;
-    try {
-        info = await client.whoami();
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.error(`Authentication failed: ${message}`);
-        process.exit(1);
-    }
-    // Auto-resolve workspace (only when the org has exactly one).
-    let workspaceId;
-    try {
-        const workspaces = await client.listWorkspaces();
-        if (workspaces.length === 1) {
-            workspaceId = workspaces[0].id;
-        }
-        else if (workspaces.length > 1) {
-            console.error(`\nMultiple workspaces in ${info.organization_name}. 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}`);
-    }
-    // The key always lives in the global store as a profile; --local additionally
-    // pins this directory to it (a pointer), instead of making it the global default.
-    upsertProfile(info.organization_id, {
-        api_key: apiKey,
-        org_name: info.organization_name,
-        workspace_id: workspaceId,
-    });
-    const existing = loadGlobalConfig() ?? {};
-    saveGlobalConfig({ ...existing, email: info.email });
-    setActiveOrg(info.organization_id, local ? "local" : "global");
-    if (local) {
-        console.error(`Authenticated as ${info.email} in ${info.organization_name}.`);
-        console.error(`  Pinned this directory: ${getConfigPath("local")}`);
-    }
-    else {
-        console.error(`Authenticated as ${info.email} in ${info.organization_name} (now active).`);
-        console.error(`  Saved to the "${info.organization_name}" profile in ~/.lotics`);
-    }
-}
-function requireClient(flags) {
-    const ctx = resolveContext(flags);
-    if (!ctx) {
-        console.error('Not authenticated. Run "lotics auth signup", "lotics auth api-key <key>", or set LOTICS_API_KEY.');
-        process.exit(1);
-    }
-    // Admin "View as": flag wins over env. The server enforces admin-only; a
-    // non-admin key gets a clear 403 on the first request.
-    const viewAsMemberId = flags.viewAs ?? process.env.LOTICS_VIEW_AS;
-    return {
-        client: new LoticsClient({ apiKey: ctx.apiKey, workspaceId: ctx.workspaceId, viewAsMemberId }),
-        ctx,
-    };
-}
-const SOURCE_LABELS = {
-    flag: "--api-key flag",
-    env_key: "LOTICS_API_KEY env",
-    env_org: "LOTICS_ORG env",
-    local_pointer: "local .lotics/config.json (pin)",
-    global_profile: "global active profile",
-};
-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, ctx) {
-    if (ctx.workspaceId) {
-        client.setWorkspaceId(ctx.workspaceId);
-        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) {
-        // Persist the auto-resolution where the credential lives; null means it
-        // came from --api-key/env with no profile, so it's an in-memory selection.
-        setSelectedWorkspace(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 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;
-    }
-    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 ctx = resolveContext(flags);
-            if (!ctx) {
-                console.error('Not authenticated. Run "lotics auth signup", "lotics auth api-key <key>", or set LOTICS_API_KEY.');
-                process.exit(1);
-            }
-            const client = new LoticsClient({ apiKey: ctx.apiKey });
-            const info = await client.whoami();
-            const existing = loadGlobalConfig() ?? {};
-            saveGlobalConfig({ ...existing, email: info.email });
-            const viewAs = flags.viewAs ?? process.env.LOTICS_VIEW_AS;
-            if (flags.json) {
-                console.log(JSON.stringify({ ...info, workspace_id: ctx.workspaceId ?? null, source: ctx.source, view_as: viewAs ?? null }, null, 2));
-            }
-            else {
-                console.log(`Name:       ${info.name}`);
-                console.log(`Email:      ${info.email}`);
-                console.log(`Org:        ${info.organization_name} (${info.organization_id})`);
-                console.log(`Workspace:  ${ctx.workspaceId ?? "(none selected)"}`);
-                console.log(`Source:     ${SOURCE_LABELS[ctx.source]}`);
-                if (viewAs)
-                    console.log(`View as:    ${viewAs} (admin preview; requires an admin key)`);
-            }
-            return;
-        }
-        if (subcommand === "logout") {
-            const local = loadLocalConfig();
-            // Bare logout inside a pinned directory just unpins it.
-            if (local && !flags.all && !toolArgs) {
-                deleteConfig();
-                console.error("Removed the local pin for this directory.");
-                return;
-            }
-            if (flags.all) {
-                const g = loadGlobalConfig();
-                saveGlobalConfig({ last_update_check: g?.last_update_check, latest_version: g?.latest_version });
-                console.error("Removed all saved credentials.");
-                return;
-            }
-            const g = loadGlobalConfig() ?? {};
-            const profiles = g.profiles ?? {};
-            let resolved;
-            if (toolArgs) {
-                resolved = resolveProfileByNameOrId(profiles, toolArgs);
-            }
-            else if (g.active_org && profiles[g.active_org]) {
-                resolved = [g.active_org, profiles[g.active_org]];
-            }
-            else {
-                resolved = null;
-            }
-            if (!resolved) {
-                console.error(toolArgs
-                    ? `No saved credential matches "${toolArgs}".`
-                    : 'No active credential to remove. Pass an org name/id, or use --all.');
-                process.exit(1);
-            }
-            const [orgId, profile] = resolved;
-            removeProfile(orgId);
-            console.error(`Removed the "${profile.org_name}" credential (${orgId}).`);
-            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;
-    }
-    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") {
-            const component = toolArgs;
-            if (!component) {
-                console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
-                console.error("Dev-links @lotics/ui to packages/ui/src (Vite + tsc) for live HMR + typecheck.");
-                console.error("Monorepo apps find packages/ui/src automatically; external apps pass --ui-src / LOTICS_UI_SRC.");
-                process.exit(1);
-            }
-            // `--remove` isn't a value-taking flag, so the parser leaves it as a
-            // trailing positional (the component took `toolArgs`); `--ui-src` IS a
-            // value flag (flags.uiSrc), falling back to LOTICS_UI_SRC inside appUiLink.
-            appUiLink({ component, uiSrc: flags.uiSrc, remove: restArgs.includes("--remove") });
-            return;
-        }
-        console.error(`Unknown ui subcommand: ${subcommand ?? "(none)"}`);
-        console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
-        process.exit(1);
-    }
-    // --- lotics app workflow check [alias] — local typecheck, no auth, no network ---
-    // Reads src/workflows/*.ts + .lotics/workflows/*.globals.d.ts and the app's own
-    // typescript; builds one isolated program per alias. Handled before the auth
-    // gate (like `ui link`) since it never touches the API.
-    if (command === "app" && subcommand === "workflow" && toolArgs === "check") {
-        await appWorkflowCheck({ alias: restArgs[0] });
-        return;
-    }
-    // --- lotics app codegen [path] — regenerate .lotics/* without a deploy ---
-    // The .d.ts companions need no auth; app_fields.ts needs a workspace, resolved
-    // when credentials are available (offline/unauth still does the .d.ts work).
-    if (command === "app" && subcommand === "codegen") {
-        const projectDir = toolArgs;
-        const ctx = resolveContext(flags);
-        if (!ctx) {
-            await appCodegen({ projectDir });
-            return;
-        }
-        const viewAsMemberId = flags.viewAs ?? process.env.LOTICS_VIEW_AS;
-        const client = new LoticsClient({ apiKey: ctx.apiKey, workspaceId: ctx.workspaceId, viewAsMemberId });
-        await resolveWorkspace(client, ctx);
-        await appCodegen({ projectDir, client });
-        return;
-    }
-    // --- lotics org [list | use <name|id> [--local]] — credential store, config-only ---
-    if (command === "org") {
-        const global = loadGlobalConfig() ?? {};
-        const profiles = global.profiles ?? {};
-        const local = loadLocalConfig();
-        if (subcommand === "use") {
-            if (!toolArgs) {
-                console.error("Usage: lotics org use <name|id> [--local]");
-                process.exit(1);
-            }
-            const resolved = resolveProfileByNameOrId(profiles, toolArgs);
-            if (!resolved) {
-                console.error(`No saved credential for "${toolArgs}". Run "lotics auth api-key <key>" while authenticated to that org, or "lotics org" to list.`);
-                process.exit(1);
-            }
-            const [orgId, profile] = resolved;
-            if (flags.local) {
-                setActiveOrg(orgId, "local");
-                console.error(`Pinned this directory to ${profile.org_name} (${orgId}).`);
-            }
-            else {
-                setActiveOrg(orgId, "global");
-                console.error(`Switched active org to ${profile.org_name} (${orgId}).`);
-                if (local?.active_org) {
-                    console.error("Note: a local pin (.lotics/config.json) overrides the global default in this directory. Use --local to change the pin here.");
-                }
-            }
-            return;
-        }
-        if (subcommand && subcommand !== "list") {
-            console.error(`Unknown org subcommand: ${subcommand}`);
-            console.error("Usage: lotics org [list | use <name|id> [--local]]");
-            process.exit(1);
-        }
-        const orgIds = Object.keys(profiles);
-        if (orgIds.length === 0) {
-            console.error('No saved orgs. Run "lotics auth api-key <key>" to add one.');
-            return;
-        }
-        // The active org in THIS directory: a local pin wins over the global default.
-        const effectiveActive = local?.active_org ?? global.active_org;
-        if (flags.json) {
-            console.log(JSON.stringify(orgIds.map((id) => ({
-                org_id: id,
-                org_name: profiles[id].org_name,
-                workspace_id: profiles[id].workspace_id ?? null,
-                active: id === effectiveActive,
-            })), null, 2));
-        }
-        else {
-            for (const id of orgIds) {
-                const marker = id === effectiveActive ? " (active)" : "";
-                console.log(`${id}  ${profiles[id].org_name}${marker}`);
-            }
-        }
-        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);
-    }
-    // `ui` and `app codegen` are handled above (no-auth / optional-client) and
-    // return before this guard — they never reach the requireClient path.
-    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>       Build + upload the current directory (-m required)");
-        console.error("  lotics app versions [app_id]         Show deploy history (version, when, who, message)");
-        console.error("  lotics app codegen [path]            Regenerate .lotics/* (types + field ids) — no deploy");
-        console.error("  lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end");
-        console.error("  lotics app workflow set <alias>           Push the edited src/workflows/<alias>.ts body");
-        console.error("  lotics app workflow pull                  Rewrite src/workflows/*.ts from the server");
-        console.error("  lotics app workflow check [alias]         Typecheck src/workflows bodies locally");
-        console.error("  lotics app query set <alias>              Push lotics.queries.<alias> to apps.queries (no deploy)");
-        console.error("  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address");
-        console.error("  lotics app rename \"<new name>\"        Rename the app's display name (launcher title)");
-        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>'\n" +
-            "       lotics run <tool> @args.json   (read args from a file — for large payloads)\n" +
-            "       cat args.json | lotics run <tool>   (read args from stdin)");
-        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, ctx } = requireClient(flags);
-    // lotics workspace / lotics workspace list / lotics workspace select <id>
-    if (command === "workspace") {
-        if (subcommand === "doctor") {
-            // The workspace command family runs before the global workspace
-            // resolution — doctor needs the same first-workspace fallback every
-            // data command gets.
-            await resolveWorkspace(client, ctx);
-            const dangling = await client.getWorkspaceDanglingReferences();
-            if (dangling.length === 0) {
-                console.error("Workspace references: healthy — every referenced schema id resolves.");
-                return;
-            }
-            console.error(`Dangling schema references (${dangling.length}):`);
-            for (const d of dangling) {
-                console.error(`  - ${d.referent.kind} "${d.referent.name}" (${d.referent.id}) → ${d.namespace} ${d.id} (missing)`);
-            }
-            console.error("Each referent points at schema that no longer exists — edit or archive it, or recreate the missing schema.");
-            process.exitCode = 1;
-            return;
-        }
-        const workspaces = await client.listWorkspaces();
-        const currentWorkspaceId = ctx.workspaceId;
-        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, currentWorkspaceId);
-                process.exit(1);
-            }
-            const written = setSelectedWorkspace(target.id);
-            if (!written) {
-                console.error(`Switched to ${target.name} (${target.id}) for this command, but it could not be saved — credentials came from --api-key/LOTICS_API_KEY with no saved profile. Run "lotics auth api-key <key>" to persist a default.`);
-                return;
-            }
-            const where = written.scope === "local" ? " (pinned to this directory)" : "";
-            console.error(`Switched to workspace: ${target.name} (${target.id})${where}`);
-            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 });
-            setSelectedWorkspace(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;
-        }
-        if (subcommand === "delete") {
-            const targetId = toolArgs;
-            if (!targetId) {
-                console.error('Usage: lotics workspace delete <workspace_id> --yes');
-                process.exit(1);
-            }
-            const target = workspaces.find((ws) => ws.id === targetId);
-            if (!target) {
-                console.error(`Workspace not found: ${targetId}\n\nAvailable workspaces:`);
-                printWorkspaceList(workspaces, currentWorkspaceId);
-                process.exit(1);
-            }
-            // Destructive + irreversible-looking to the user — require an explicit
-            // confirmation (this CLI is used non-interactively by agents and scripts).
-            if (!flags.yes) {
-                console.error(`This deletes workspace "${target.name}" (${target.id}) — every table, app, record, and template inside it becomes inaccessible (soft delete: retained and recoverable by an admin).`);
-                console.error(`Re-run with --yes to confirm:  lotics workspace delete ${target.id} --yes`);
-                process.exit(1);
-            }
-            const deleted = await client.deleteWorkspace(target.id);
-            if (flags.json) {
-                console.log(JSON.stringify(deleted, null, 2));
-            }
-            else {
-                console.error(`Deleted workspace: ${target.name} (${target.id})`);
-                if (currentWorkspaceId === target.id) {
-                    console.error('This was your selected workspace — select another with "lotics workspace select <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> | delete <id> --yes]');
-            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 === currentWorkspaceId ? " (current)" : "";
-                    console.log(`${ws.id}  ${ws.name}  ${ws.timezone}  ${ws.default_currency}${marker}`);
-                }
-            }
-        }
-        if (ctx.orgName)
-            console.error(`Org: ${ctx.orgName}`);
-        return;
-    }
-    // Ensure workspace is resolved for all remaining commands
-    await resolveWorkspace(client, ctx);
-    // 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`.
-            // Required: every deploy is a version row, and `lotics app versions` reads
-            // the message back — a blank one makes the deploy history useless.
-            const message = (flags.message ?? toolArgs)?.trim();
-            if (!message) {
-                console.error('Usage: lotics app deploy -m "<what changed + why>"');
-                console.error("A deploy message is required — it's the version's audit trail (see `lotics app versions`).");
-                process.exit(1);
-            }
-            await appDeploy(client, { message });
-            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 === "rename") {
-            const newName = toolArgs;
-            if (!newName) {
-                console.error('Usage: lotics app rename "<new name>"');
-                console.error("Changes the app's display name (run inside the app directory).");
-                process.exit(1);
-            }
-            await appRename(client, { name: newName });
-            return;
-        }
-        if (subcommand === "versions") {
-            // Optional positional app_id (inspect any app); else read the local manifest.
-            const appId = toolArgs || undefined;
-            await appVersions(client, { app_id: appId });
-            return;
-        }
-        if (subcommand === "workflow") {
-            // `lotics app workflow <run|set|pull> …` — disambiguated subcommands so an
-            // alias can never collide with the verb. `toolArgs` is the verb; `restArgs`
-            // carries the alias (+ inputs for run). No bare `workflow <alias>` form.
-            const action = toolArgs;
-            const workflowUsage = () => {
-                console.error("Usage:");
-                console.error("  lotics app workflow run <alias> '<json>'   Execute a bound app workflow");
-                console.error("  lotics app workflow set <alias>            Push src/workflows/<alias>.ts");
-                console.error("  lotics app workflow pull                   Rewrite src/workflows/*.ts from the server");
-                console.error("  lotics app workflow check [alias]          Typecheck src/workflows bodies locally");
-                process.exit(1);
-            };
-            if (action === "run") {
-                // `run <alias> '<json>'` — inputs use the SAME ingestion as `lotics run`
-                // (inline / @file / stdin) so bulk inputs bypass ARG_MAX.
-                const alias = restArgs[0];
-                if (!alias) {
-                    console.error("Usage: lotics app workflow run <alias> '<json>'");
-                    console.error("       lotics app workflow run <alias> @inputs.json   (read inputs from a file)");
-                    console.error("       cat inputs.json | lotics app workflow run <alias>   (read inputs from stdin)");
-                    console.error("Flags: --print-created (report created records + cleanup plan + caveat)");
-                    console.error("       --cleanup (also delete the created records — records only, NOT a rollback)");
-                    process.exit(1);
-                }
-                const ingested = await ingestJsonArgs({
-                    rawArg: restArgs[1],
-                    stdinIsTTY: process.stdin.isTTY ?? false,
-                    readFile: (p) => fs.readFileSync(p, "utf-8"),
-                    readStdin,
-                });
-                if (ingested.kind === "error") {
-                    console.error(ingested.message);
-                    process.exit(1);
-                }
-                await appExecuteWorkflow(client, {
-                    alias,
-                    inputs: ingested.args,
-                    printCreated: flags.printCreated,
-                    cleanup: flags.cleanup,
-                });
-                return;
-            }
-            if (action === "set") {
-                const alias = restArgs[0];
-                if (!alias) {
-                    console.error("Usage: lotics app workflow set <alias>");
-                    console.error("Pushes the edited src/workflows/<alias>.ts body via set_app_workflow.");
-                    process.exit(1);
-                }
-                await appWorkflowSet(client, { alias });
-                return;
-            }
-            if (action === "pull") {
-                await appWorkflowPull(client);
-                return;
-            }
-            workflowUsage();
-        }
-        if (subcommand === "query") {
-            // `lotics app query set <alias>` — push package.json#lotics.queries.<alias>
-            // to apps.queries via set_app_query, no deploy. `toolArgs` is the verb;
-            // `restArgs` carries the alias.
-            const action = toolArgs;
-            if (action === "set") {
-                const alias = restArgs[0];
-                if (!alias) {
-                    console.error("Usage: lotics app query set <alias>");
-                    console.error("Pushes package.json#lotics.queries.<alias> to apps.queries via set_app_query (no deploy).");
-                    process.exit(1);
-                }
-                await appQuerySet(client, { alias });
-                return;
-            }
-            console.error("Usage:");
-            console.error("  lotics app query set <alias>   Push package.json#lotics.queries.<alias> to apps.queries (no deploy)");
-            process.exit(1);
-        }
-        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;
-        // `@file` / piped stdin carry payloads too large for an inline arg (the OS
-        // caps ARG_MAX). Shared with `lotics app workflow` so both ingest identically.
-        const ingested = await ingestJsonArgs({
-            rawArg: toolArgs,
-            stdinIsTTY: process.stdin.isTTY ?? false,
-            readFile: (p) => fs.readFileSync(p, "utf-8"),
-            readStdin,
-        });
-        if (ingested.kind === "error") {
-            console.error(ingested.message);
-            process.exit(1);
-        }
-        const args = ingested.args;
-        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 {
-                // Execution errors (not-found, refusals) carry the server's message;
-                // the input already passed schema validation, so no schema hint —
-                // validation 400s bring the server's own hint via throwResponseError.
-                console.error(result.error);
-            }
-            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);
-});