@lotics/cli 0.57.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

@@ -162,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
@@ -224,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

@@ -187,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
@@ -260,6 +302,49 @@ export class LoticsClient {
             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
      * caller reads `res.body`). Unlike `request`, this does not buffer/parse the

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;

package/dist/generate_app_fields.js

@@ -0,0 +1,148 @@
+/**
+ * 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.
+ */
+import { isValidIdentifier } from "./generate_app_workflows_dts.js";
+const HEADER = `// Auto-generated by 'lotics app codegen' (and app pull/dev/deploy).
+// DO NOT EDIT — regenerated from the workspace schema.
+//
+// Runtime field + option ids addressed by stable display-name aliases:
+//   record.data[F.<TABLE>.<field>]            → "fld_…"
+//   value === OPT.<TABLE>.<field>.<option>    → "opt_…"
+// A rename on the platform re-runs codegen and moves these in lockstep.
+`;
+/**
+ * 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 function slugifyAlias(name, upper) {
+    const stripped = name
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "") // combining diacritical marks
+        .replace(/đ/g, "d")
+        .replace(/Đ/g, "D"); // not a combining mark — map explicitly
+    const cased = upper ? stripped.toUpperCase() : stripped.toLowerCase();
+    const slug = cased
+        .replace(/[^a-zA-Z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (slug === "")
+        return "_";
+    return /^[0-9]/.test(slug) ? `_${slug}` : slug;
+}
+/**
+ * Assign each input a unique alias, preserving input order. The first claim on
+ * a slug keeps it; later collisions get `_2`, `_3`, … so the mapping is stable
+ * across regenerations (order is the schema's field/option order). Returns the
+ * aliases positionally aligned with `names`.
+ */
+function dedupeAliases(names, upper) {
+    const used = new Map();
+    return names.map((name) => {
+        const base = slugifyAlias(name, upper);
+        const seen = used.get(base);
+        if (seen === undefined) {
+            used.set(base, 1);
+            return base;
+        }
+        let n = seen + 1;
+        while (used.has(`${base}_${n}`))
+            n++;
+        used.set(base, n);
+        used.set(`${base}_${n}`, 1);
+        return `${base}_${n}`;
+    });
+}
+/** A property key for an object literal — bare when a valid identifier, else quoted. */
+function propKey(alias) {
+    return isValidIdentifier(alias) ? alias : JSON.stringify(alias);
+}
+/** Resolve table + field aliases once, so the `F`/`OPT` maps and the union types agree. */
+function aliasTables(tables) {
+    const tableAliases = dedupeAliases(tables.map((t) => t.name), true);
+    return tables.map((table, i) => {
+        const fieldAliases = dedupeAliases(table.fields.map((f) => f.name), false);
+        return {
+            alias: tableAliases[i],
+            table,
+            fields: table.fields.map((field, j) => ({ alias: fieldAliases[j], field })),
+        };
+    });
+}
+/** Emit the `F` map: `{ TABLE: { field: "fld_…" } }` plus its literal-union type. */
+function emitFieldMap(aliased) {
+    const tableBlocks = aliased.map(({ alias, fields }) => {
+        const fieldLines = fields.map(({ alias: fieldAlias, field }) => `    ${propKey(fieldAlias)}: ${JSON.stringify(field.id)},`);
+        return `  ${propKey(alias)}: {\n${fieldLines.join("\n")}\n  },`;
+    });
+    return `export const F = {\n${tableBlocks.join("\n")}\n} as const;`;
+}
+/**
+ * Emit the `OPT` map: `{ TABLE: { selectField: { option: "opt_…" } } }`. Only
+ * fields that carry options appear. Tables and fields with no options are
+ * omitted entirely (so `OPT.SHIPMENTS` may be absent — that's by design).
+ */
+function emitOptionMap(aliased) {
+    const tableBlocks = [];
+    for (const { alias, fields } of aliased) {
+        const fieldBlocks = [];
+        for (const { alias: fieldAlias, field } of fields) {
+            const options = field.options ?? [];
+            if (options.length === 0)
+                continue;
+            const optionAliases = dedupeAliases(options.map((o) => o.label), false);
+            const optionLines = options.map((option, i) => `      ${propKey(optionAliases[i])}: ${JSON.stringify(option.id)},`);
+            fieldBlocks.push(`    ${propKey(fieldAlias)}: {\n${optionLines.join("\n")}\n    },`);
+        }
+        if (fieldBlocks.length === 0)
+            continue;
+        tableBlocks.push(`  ${propKey(alias)}: {\n${fieldBlocks.join("\n")}\n  },`);
+    }
+    if (tableBlocks.length === 0)
+        return `export const OPT = {} as const;`;
+    return `export const OPT = {\n${tableBlocks.join("\n")}\n} as const;`;
+}
+/**
+ * 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 function generateAppFields(tables) {
+    if (tables.length === 0) {
+        return `${HEADER}
+export const F = {} as const;
+
+export const OPT = {} as const;
+
+/** Field-id alias map (empty — no tables in scope). */
+export type AppFields = typeof F;
+/** Select-option alias map (empty — no tables in scope). */
+export type AppOptions = typeof OPT;
+`;
+    }
+    const aliased = aliasTables(tables);
+    return `${HEADER}
+${emitFieldMap(aliased)}
+
+${emitOptionMap(aliased)}
+
+/** Field-id alias map: \`F[<TABLE>][<field>]\` is the \`fld_…\` id (literal-typed). */
+export type AppFields = typeof F;
+/** Select-option alias map: \`OPT[<TABLE>][<field>][<option>]\` is the \`opt_…\` id. */
+export type AppOptions = typeof OPT;
+`;
+}

package/dist/generate_app_fields.test.d.ts

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