@lotics/cli 0.56.0 → 0.60.1

package/dist/cli.js

@@ -1,12 +1,21 @@
 #!/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 } from "./app_commands.js";
+import { appCreate, appPull, appDeploy, appDev, appSetSubdomain, appRename, appCodegen, appExecuteWorkflow, appWorkflowSet, appWorkflowPull, 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";
 function printHelp() {
@@ -65,9 +74,21 @@ COMMANDS
   lotics app deploy [-m <message>]     Build + upload current dir as a new version
                                        (code + queries only — workflow bindings are
                                        managed by set_app_workflow / remove_app_workflow)
+  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 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> [--remove] Dev-link @lotics/ui to the monorepo's
+                                       packages/ui/src for live HMR (monorepo only)
   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)
@@ -461,6 +482,40 @@ async function main() {
         await runDocxCommand(subcommand, toolArgs, restArgs);
         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> [--remove]");
+                console.error("Dev-links @lotics/ui to the monorepo's packages/ui/src for live HMR.");
+                process.exit(1);
+            }
+            // `--remove` isn't a value-taking flag, so the parser leaves it as a
+            // trailing positional (the component took `toolArgs`).
+            appUiLink({ component, remove: restArgs.includes("--remove") });
+            return;
+        }
+        console.error(`Unknown ui subcommand: ${subcommand ?? "(none)"}`);
+        console.error("Usage: lotics ui link <component> [--remove]");
+        process.exit(1);
+    }
+    // --- 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() ?? {};
@@ -524,11 +579,17 @@ async function main() {
         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");
+        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 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");
@@ -677,6 +738,64 @@ async function main() {
             await appRename(client, { name: newName });
             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");
+                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 === "dev") {
             // First positional is an optional project path (defaults to cwd).
             // --port and --vite-port can override the wrapper / Vite ports.
@@ -782,36 +901,19 @@ async function main() {
     // lotics run <tool> [json_args]
     if (command === "run") {
         const toolName = subcommand;
-        let rawArgs = toolArgs;
-        if (rawArgs && rawArgs.startsWith("@")) {
-            // `@<path>` — read the JSON args from a local file. JSON args always
-            // start with `{`, so a leading `@` is unambiguous. This (and piped
-            // stdin below) carries payloads too large for an inline arg, which the
-            // OS caps (ARG_MAX) — e.g. a knowledge doc's `content` or a bulk update.
-            // Reads only a file the caller explicitly named; no new trust boundary.
-            const argsPath = rawArgs.slice(1);
-            try {
-                rawArgs = fs.readFileSync(argsPath, "utf-8");
-            }
-            catch (err) {
-                console.error(`Cannot read args file "${argsPath}": ${err instanceof Error ? err.message : String(err)}`);
-                process.exit(1);
-            }
-        }
-        else if (!rawArgs && !process.stdin.isTTY) {
-            // Piped/redirected stdin — `… | lotics run <tool>` or `< file.json`.
-            rawArgs = await readStdin();
-        }
-        let args = {};
-        if (rawArgs) {
-            try {
-                args = JSON.parse(rawArgs);
-            }
-            catch {
-                console.error(`Invalid JSON: ${rawArgs}`);
-                process.exit(1);
-            }
+        // `@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 });

package/dist/client.d.ts

@@ -1,3 +1,11 @@
+/**
+ * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
+ * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
+ * 5xx, or a JSON body without a `message` falls back to a body-free,
+ * status-derived message. `parsed` is the JSON.parse of the body, or `null`.
+ * In parity (by value, no shared dep) with `packages/app-sdk/src/rpc.ts`.
+ */
+export declare function transportErrorMessage(status: number, parsed: unknown): string;
 /** One sort key forwarded to the app query RPC (wire shape of a `TableRecordSort` entry). */
 export interface AppQuerySortKey {
     field_key: string;
@@ -154,6 +162,25 @@ export declare class LoticsClient {
         workspace_id: string;
         current_version_id: string | null;
     }>;
+    /**
+     * Resolve the display name + fields (incl. select options) of the given tables
+     * — the schema `lotics app codegen` turns into the runtime `.lotics/app_fields.ts`
+     * alias maps. One `get_table` call per id (the tool surface has no batch
+     * variant); a missing/inaccessible table is dropped rather than throwing, so a
+     * stale id in the scope set never fails codegen.
+     */
+    getWorkspaceSchema(tableIds: string[]): Promise<Array<{
+        id: string;
+        name: string;
+        fields: Array<{
+            id: string;
+            name: string;
+            options?: Array<{
+                id: string;
+                label: string;
+            }>;
+        }>;
+    }>>;
     /**
      * Rename an app's public subdomain — its `<slug>.lotics.app` address.
      * Mirrors PUT /v1/apps/{app_id}/subdomain. The old subdomain stops
@@ -216,6 +243,45 @@ export declare class LoticsClient {
      * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
      */
     appWorkflow(app_id: string, alias: string, inputs: unknown): Promise<unknown>;
+    /**
+     * Bind (create or replace) an app workflow by alias via the `set_app_workflow`
+     * tool — the SINGLE author of `apps.workflows` + the workflow row. `source` is
+     * the verbatim JS-subset body (no `on({...})` trigger). `inputs`/`outputs` are
+     * the typed schemas declared in `package.json#lotics.workflows.<alias>`. The
+     * server re-verifies the body and echoes the bound `outputs` (declared, else
+     * DERIVED from `return({ data })`), so the CLI can show the author what shape
+     * `result.data` will carry. Wraps the tool rather than a bespoke endpoint so
+     * the file flow stays a convenience over the existing single-author contract.
+     */
+    setAppWorkflow(app_id: string, alias: string, body: {
+        source: string;
+        inputs?: Record<string, unknown>;
+        outputs?: Record<string, unknown>;
+        name?: string;
+        description?: string;
+    }): Promise<ToolExecuteResult>;
+    /**
+     * Fetch one app workflow's faithful source + bound input/output schemas via
+     * `get_app_workflow`. `source` is the JS-subset body re-rendered from the
+     * persisted step tree (incl. the `return({ data })` clause, opaque field/option
+     * keys) — the exact text `lotics app workflow set` would push back. Feeds
+     * `lotics app pull`, which writes it to `src/workflows/<alias>.ts`.
+     */
+    getAppWorkflow(app_id: string, alias: string): Promise<ToolExecuteResult>;
+    /**
+     * Fetch the server-generated workspace `.d.ts` + the wrapper envelope that
+     * make a `src/workflows/<alias>.ts` body locally typecheckable (GAP-59).
+     * The server is the single source of the type model — the CLI never
+     * re-implements it. `envelope_prefix`/`envelope_suffix` are the exact
+     * `async function __workflow(): …` wrapper the server compiles inside, so the
+     * local typecheck mirrors the set-time verdict. Mirrors
+     * POST /v1/apps/{app_id}/workflows/{alias}/dts.
+     */
+    getAppWorkflowDts(app_id: string, alias: string): Promise<{
+        dts: string;
+        envelope_prefix: string;
+        envelope_suffix: string;
+    }>;
     /**
      * Open a streaming agent run and return the RAW streamed `Response` (the
      * caller reads `res.body`). Unlike `request`, this does not buffer/parse the

package/dist/client.js

@@ -1,5 +1,36 @@
 import fs from "node:fs";
 import path from "node:path";
+/**
+ * A user-facing message for a transport/gateway failure — derived from the HTTP
+ * status, never from the response body. A 524 (edge timeout on a long run), any
+ * 5xx, or a non-JSON body (an HTML error page) must NOT surface its raw body. In
+ * parity (by value, no shared dep) with the published transport in
+ * `packages/app-sdk/src/rpc.ts`.
+ */
+function gatewayErrorMessage(status) {
+    if (status === 524) {
+        return "The request took too long to finish (gateway timeout). It may still be running — check back in a moment, or try again.";
+    }
+    if (status >= 500) {
+        return "The service is temporarily unavailable. Please try again shortly.";
+    }
+    return "The service returned an unexpected response. Please try again.";
+}
+/**
+ * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
+ * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
+ * 5xx, or a JSON body without a `message` falls back to a body-free,
+ * status-derived message. `parsed` is the JSON.parse of the body, or `null`.
+ * In parity (by value, no shared dep) with `packages/app-sdk/src/rpc.ts`.
+ */
+export function transportErrorMessage(status, parsed) {
+    const jsonMessage = parsed && typeof parsed.message === "string"
+        ? parsed.message
+        : null;
+    return parsed === null || status >= 500 || jsonMessage === null
+        ? gatewayErrorMessage(status)
+        : jsonMessage;
+}
 function findAvailableFilename(dir, filename, reserved) {
     // `reserved` tracks absolute paths claimed by in-flight downloads in the same
     // batch — required for parallel callers because the file may not be on disk
@@ -156,6 +187,48 @@ export class LoticsClient {
     async createApp(body) {
         return this.request("POST", "/v1/apps", body);
     }
+    /**
+     * Resolve the display name + fields (incl. select options) of the given tables
+     * — the schema `lotics app codegen` turns into the runtime `.lotics/app_fields.ts`
+     * alias maps. One `get_table` call per id (the tool surface has no batch
+     * variant); a missing/inaccessible table is dropped rather than throwing, so a
+     * stale id in the scope set never fails codegen.
+     */
+    async getWorkspaceSchema(tableIds) {
+        const tables = await Promise.all(tableIds.map(async (table_id) => {
+            // JSON (the default) — `res.result` is the structured `get_table` output
+            // already; `text` would only also run `toModelOutput` per table for
+            // nothing. The field id is `key` and an option's id is `key` / label is
+            // `name` (the `TableField` / select-option schema shapes).
+            const res = await this.execute("get_table", { table_id });
+            if (res.error || res.result === null || typeof res.result !== "object")
+                return null;
+            const table = res.result;
+            if (typeof table.id !== "string" || typeof table.name !== "string" || !Array.isArray(table.fields)) {
+                return null;
+            }
+            const fields = table.fields.flatMap((field) => {
+                if (field === null || typeof field !== "object")
+                    return [];
+                const f = field;
+                if (typeof f.key !== "string" || typeof f.name !== "string")
+                    return [];
+                const options = Array.isArray(f.options)
+                    ? f.options.flatMap((opt) => {
+                        if (opt === null || typeof opt !== "object")
+                            return [];
+                        const o = opt;
+                        return typeof o.key === "string" && typeof o.name === "string"
+                            ? [{ id: o.key, label: o.name }]
+                            : [];
+                    })
+                    : undefined;
+                return [{ id: f.key, name: f.name, ...(options && options.length > 0 ? { options } : {}) }];
+            });
+            return { id: table.id, name: table.name, fields };
+        }));
+        return tables.filter((t) => t !== null);
+    }
     /**
      * Rename an app's public subdomain — its `<slug>.lotics.app` address.
      * Mirrors PUT /v1/apps/{app_id}/subdomain. The old subdomain stops
@@ -200,7 +273,77 @@ export class LoticsClient {
      * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
      */
     async appWorkflow(app_id, alias, inputs) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/execute`, { inputs });
+        // Its own transport (not the generic `request`, whose `throwResponseError`
+        // shape is the CLI contract elsewhere): a transport/gateway failure resolves
+        // to a `WorkflowResult` error `{ status, message }` — never a thrown HTML
+        // body — so the dev RPC bridge forwards `{status:"error"}` to the iframe,
+        // matching the deployed standalone SDK (`@lotics/app-sdk` standaloneWorkflow).
+        const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/execute`;
+        const headers = this.buildHeaders();
+        headers["Content-Type"] = "application/json";
+        let response;
+        try {
+            response = await fetch(url, { method: "POST", headers, body: JSON.stringify({ inputs }) });
+        }
+        catch (err) {
+            return { status: "error", message: err instanceof Error ? err.message : "The workflow request failed." };
+        }
+        const text = await response.text();
+        let parsed = null;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                // non-JSON body (e.g. a gateway HTML error page) — never echoed
+            }
+        }
+        if (response.ok)
+            return parsed ?? {};
+        return { status: "error", message: transportErrorMessage(response.status, parsed) };
+    }
+    /**
+     * Bind (create or replace) an app workflow by alias via the `set_app_workflow`
+     * tool — the SINGLE author of `apps.workflows` + the workflow row. `source` is
+     * the verbatim JS-subset body (no `on({...})` trigger). `inputs`/`outputs` are
+     * the typed schemas declared in `package.json#lotics.workflows.<alias>`. The
+     * server re-verifies the body and echoes the bound `outputs` (declared, else
+     * DERIVED from `return({ data })`), so the CLI can show the author what shape
+     * `result.data` will carry. Wraps the tool rather than a bespoke endpoint so
+     * the file flow stays a convenience over the existing single-author contract.
+     */
+    async setAppWorkflow(app_id, alias, body) {
+        return this.execute("set_app_workflow", {
+            app_id,
+            alias,
+            source: body.source,
+            ...(body.inputs ? { inputs: body.inputs } : {}),
+            ...(body.outputs ? { outputs: body.outputs } : {}),
+            ...(body.name ? { name: body.name } : {}),
+            ...(body.description ? { description: body.description } : {}),
+        });
+    }
+    /**
+     * Fetch one app workflow's faithful source + bound input/output schemas via
+     * `get_app_workflow`. `source` is the JS-subset body re-rendered from the
+     * persisted step tree (incl. the `return({ data })` clause, opaque field/option
+     * keys) — the exact text `lotics app workflow set` would push back. Feeds
+     * `lotics app pull`, which writes it to `src/workflows/<alias>.ts`.
+     */
+    async getAppWorkflow(app_id, alias) {
+        return this.execute("get_app_workflow", { app_id, alias });
+    }
+    /**
+     * Fetch the server-generated workspace `.d.ts` + the wrapper envelope that
+     * make a `src/workflows/<alias>.ts` body locally typecheckable (GAP-59).
+     * The server is the single source of the type model — the CLI never
+     * re-implements it. `envelope_prefix`/`envelope_suffix` are the exact
+     * `async function __workflow(): …` wrapper the server compiles inside, so the
+     * local typecheck mirrors the set-time verdict. Mirrors
+     * POST /v1/apps/{app_id}/workflows/{alias}/dts.
+     */
+    async getAppWorkflowDts(app_id, alias) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/dts`);
     }
     /**
      * Open a streaming agent run and return the RAW streamed `Response` (the

package/dist/client.test.d.ts

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

package/dist/client.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { LoticsClient, transportErrorMessage } from "./client.js";
+describe("transportErrorMessage", () => {
+    it("returns a body-free gateway message for a non-JSON 524 (never the HTML)", () => {
+        const msg = transportErrorMessage(524, null);
+        expect(msg).not.toMatch(/<html|<!DOCTYPE/i);
+        expect(msg.toLowerCase()).toContain("gateway timeout");
+    });
+    it("returns a friendly message for any 5xx, ignoring a JSON body", () => {
+        expect(transportErrorMessage(503, { message: "internal detail" })).not.toBe("internal detail");
+        expect(transportErrorMessage(503, { message: "internal detail" })).not.toMatch(/<html/i);
+    });
+    it("surfaces a genuine 4xx JSON error message verbatim", () => {
+        expect(transportErrorMessage(400, { message: "record_id is required" })).toBe("record_id is required");
+    });
+    it("never leaks a non-JSON 4xx body (WAF / redirect HTML)", () => {
+        expect(transportErrorMessage(403, null)).not.toMatch(/<html|<!DOCTYPE/i);
+    });
+    it("falls back to a friendly message for a JSON body with no message field", () => {
+        expect(transportErrorMessage(409, { error_code: "CONFLICT" })).toBeTruthy();
+        expect(transportErrorMessage(409, { error_code: "CONFLICT" })).not.toMatch(/<html/i);
+    });
+});
+describe("LoticsClient.appWorkflow", () => {
+    afterEach(() => vi.unstubAllGlobals());
+    const client = new LoticsClient({ apiKey: "ltk_test", workspaceId: "wsp_test" });
+    it("normalizes a 524 HTML gateway response to a WorkflowResult error (no raw HTML)", async () => {
+        const html = "<!DOCTYPE html><html><head><title>error</title></head><body>524: A timeout occurred</body></html>";
+        vi.stubGlobal("fetch", vi.fn(async () => new Response(html, { status: 524 })));
+        const result = (await client.appWorkflow("app_1", "wf", {}));
+        expect(result.status).toBe("error");
+        expect(result.message).not.toMatch(/<html|<!DOCTYPE/i);
+    });
+    it("passes a 200 workflow result through unchanged", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ status: "success", data: { x: 1 } }), { status: 200 })));
+        const result = await client.appWorkflow("app_1", "wf", {});
+        expect(result).toEqual({ status: "success", data: { x: 1 } });
+    });
+    it("returns a WorkflowResult error (not a throw) on a network failure", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => {
+            throw new Error("ECONNREFUSED");
+        }));
+        const result = (await client.appWorkflow("app_1", "wf", {}));
+        expect(result.status).toBe("error");
+        expect(result.message).toContain("ECONNREFUSED");
+    });
+});

package/dist/dev/server.js

@@ -14,6 +14,7 @@
 import http from "node:http";
 import net from "node:net";
 import { spawn } from "node:child_process";
+import { ipv4ChildEnv } from "../child_env.js";
 import { dispatchRpc } from "./rpc_handler.js";
 import { buildWrapperPage } from "./wrapper_page.js";
 const DEFAULT_PORT = 5174;
@@ -55,7 +56,7 @@ export async function startDevServer(args) {
     const viteChild = spawn("npx", ["vite", "--port", String(vitePort), "--strictPort"], {
         cwd: args.projectDir,
         stdio: [process.stdin.isTTY ? "inherit" : "ignore", "inherit", "inherit"],
-        env: { ...process.env, FORCE_COLOR: "1" },
+        env: ipv4ChildEnv({ ...process.env, FORCE_COLOR: "1" }),
     });
     let stopped = false;
     let stoppingResolve = null;

package/dist/generate_app_fields.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Codegen: emit a RUNTIME `.lotics/app_fields.ts` from a workspace schema.
+ *
+ * Unlike the `.d.ts` companions (which only augment types), this is a real
+ * `.ts` module: apps import the string VALUES at runtime to address fields and
+ * select options by a stable, human-readable alias instead of pasting opaque
+ * `fld_…` / `opt_…` ids into their source:
+ *
+ *   import { F, OPT } from "../.lotics/app_fields";
+ *   record.data[F.SHIPMENTS.status]            // "fld_…"
+ *   if (status === OPT.SHIPMENTS.status.cleared) // "opt_…"
+ *
+ * Aliases are derived from display names (NFD-stripped, non-alnum → `_`, deduped
+ * in stable order), so a rename on the platform re-runs codegen and the app's
+ * call sites move with it. Pure function — same schema → same bytes. Idempotent.
+ */
+/** One select option as it appears in a field's metadata. */
+export interface TableFieldOption {
+    /** Stable id (`opt_…`) — the value persisted in record data. */
+    id: string;
+    /** Display label the option alias is slugified from. */
+    label: string;
+}
+/** A single table field with the metadata codegen needs. */
+export interface TableFieldSchema {
+    /** Stable id (`fld_…`) — the value emitted under `F`. */
+    id: string;
+    /** Display name the field alias is slugified from. */
+    name: string;
+    /** Present only for select/multi-select fields — drives the `OPT` map. */
+    options?: TableFieldOption[];
+}
+/** The schema of one table, as returned by `client.getWorkspaceSchema`. */
+export interface TableSchema {
+    /** Stable id (`tbl_…`). Carried for fidelity; not emitted by name. */
+    id: string;
+    /** Display name the TABLE alias is slugified from. */
+    name: string;
+    fields: TableFieldSchema[];
+}
+/**
+ * Slugify a display name to a valid TS identifier. NFD-normalize then strip
+ * diacritics so "Lô hàng" and "Lo hang" don't collide on the accent, lowercase,
+ * non-alnum → `_`, collapse runs, trim edge `_`. A leading digit (identifiers
+ * can't start with one) and the empty result both get a `_` prefix/placeholder.
+ * `upper` uppercases the result (TABLE aliases read as constants).
+ */
+export declare function slugifyAlias(name: string, upper: boolean): string;
+/**
+ * Generate the full `.lotics/app_fields.ts` source. `tables` is the resolved
+ * workspace schema (the subset the app touches). An empty list yields valid,
+ * empty `F`/`OPT` maps so the file always compiles and imports resolve.
+ */
+export declare function generateAppFields(tables: TableSchema[]): string;