@lotics/cli 0.56.0 → 0.60.1

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 {};

package/dist/generate_app_fields.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "vitest";
+import { generateAppFields, slugifyAlias } from "./generate_app_fields.js";
+describe("slugifyAlias", () => {
+    it("strips Vietnamese diacritics so accented + unaccented names don't collide on the accent", () => {
+        expect(slugifyAlias("Lô hàng", true)).toBe("LO_HANG");
+        expect(slugifyAlias("Đơn vị", true)).toBe("DON_VI");
+        expect(slugifyAlias("trạng thái", false)).toBe("trang_thai");
+    });
+    it("collapses non-alnum runs to a single underscore and trims edges", () => {
+        expect(slugifyAlias("  Báo giá / CTA  ", true)).toBe("BAO_GIA_CTA");
+        expect(slugifyAlias("a---b", false)).toBe("a_b");
+    });
+    it("prefixes a leading digit (identifiers can't start with one)", () => {
+        expect(slugifyAlias("40HC cont", false)).toBe("_40hc_cont");
+    });
+    it("falls back to '_' for an all-symbol or empty name", () => {
+        expect(slugifyAlias("***", false)).toBe("_");
+        expect(slugifyAlias("", true)).toBe("_");
+    });
+});
+describe("generateAppFields", () => {
+    it("emits empty F/OPT maps that still compile when no tables are in scope", () => {
+        const out = generateAppFields([]);
+        expect(out).toContain("export const F = {} as const;");
+        expect(out).toContain("export const OPT = {} as const;");
+    });
+    it("emits F entries keyed by slugified table + field names", () => {
+        const tables = [
+            {
+                id: "tbl_1",
+                name: "Lô hàng",
+                fields: [
+                    { id: "fld_status", name: "Trạng thái" },
+                    { id: "fld_eta", name: "ETA" },
+                ],
+            },
+        ];
+        const out = generateAppFields(tables);
+        expect(out).toContain("LO_HANG: {");
+        expect(out).toContain('trang_thai: "fld_status"');
+        expect(out).toContain('eta: "fld_eta"');
+    });
+    it("emits OPT only for fields that carry options, keyed by option label", () => {
+        const tables = [
+            {
+                id: "tbl_1",
+                name: "Shipments",
+                fields: [
+                    {
+                        id: "fld_status",
+                        name: "Status",
+                        options: [
+                            { id: "opt_open", label: "Open" },
+                            { id: "opt_cleared", label: "Cleared" },
+                        ],
+                    },
+                    { id: "fld_eta", name: "ETA" },
+                ],
+            },
+        ];
+        const out = generateAppFields(tables);
+        expect(out).toContain("SHIPMENTS: {");
+        expect(out).toContain('open: "opt_open"');
+        expect(out).toContain('cleared: "opt_cleared"');
+        // No options on ETA → it must not appear in the OPT block.
+        const optBlock = out.slice(out.indexOf("export const OPT"));
+        expect(optBlock).not.toContain("eta:");
+    });
+    it("omits a table from OPT entirely when none of its fields have options", () => {
+        const tables = [
+            { id: "tbl_1", name: "Plain", fields: [{ id: "fld_a", name: "A" }] },
+        ];
+        const out = generateAppFields(tables);
+        expect(out).toContain("export const OPT = {} as const;");
+    });
+    it("dedupes collided aliases with _2/_3 in stable field order", () => {
+        const tables = [
+            {
+                id: "tbl_1",
+                name: "T",
+                fields: [
+                    { id: "fld_a", name: "Ngày" },
+                    { id: "fld_b", name: "ngày" }, // slugifies to the same `ngay`
+                    { id: "fld_c", name: "Ngày!" }, // also `ngay`
+                ],
+            },
+        ];
+        const out = generateAppFields(tables);
+        expect(out).toContain('ngay: "fld_a"');
+        expect(out).toContain('ngay_2: "fld_b"');
+        expect(out).toContain('ngay_3: "fld_c"');
+    });
+    it("quotes a non-identifier alias only when slugify could not produce one", () => {
+        // An all-symbol name slugifies to "_", a valid identifier — so it's bare.
+        const tables = [
+            { id: "tbl_1", name: "***", fields: [{ id: "fld_a", name: "@@@" }] },
+        ];
+        const out = generateAppFields(tables);
+        expect(out).toContain("_: {");
+        expect(out).toContain('_: "fld_a"');
+    });
+    it("is deterministic — same schema → byte-identical output", () => {
+        const tables = [
+            { id: "tbl_1", name: "A", fields: [{ id: "fld_a", name: "X" }] },
+        ];
+        expect(generateAppFields(tables)).toBe(generateAppFields(tables));
+    });
+});

package/dist/inputs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared JSON-args ingestion for `lotics run` and `lotics app workflow`.
+ *
+ * A tool/workflow payload can arrive three ways, all of which bypass the OS
+ * `ARG_MAX` limit so bulk inputs (a knowledge-doc `content`, a batch update)
+ * don't overflow the inline arg:
+ *   - inline:  `… '<json>'`
+ *   - `@file`: `… @args.json`   (a leading `@` is unambiguous — JSON starts `{`)
+ *   - stdin:   `… < args.json`  or  `cat args.json | …`
+ *
+ * Kept apart from `cli.ts` (which runs `main()` on import) so the file/JSON
+ * branches are unit-testable; `readStdin` is injected so the tests don't touch
+ * the real process stdin.
+ */
+export type IngestResult = {
+    kind: "ok";
+    args: Record<string, unknown>;
+} | {
+    kind: "error";
+    message: string;
+};
+export interface IngestOptions {
+    /** The positional arg as parsed (`'<json>'`, `@file`, or undefined). */
+    rawArg: string | undefined;
+    /** Whether stdin is a TTY — when false and no rawArg, read piped stdin. */
+    stdinIsTTY: boolean;
+    /** Reads a UTF-8 file. Injected for testability. */
+    readFile: (path: string) => string;
+    /** Reads all of stdin. Injected for testability. */
+    readStdin: () => Promise<string>;
+}
+/**
+ * Resolve the raw payload string, then JSON.parse it. An absent payload (no
+ * arg, no piped stdin) is a valid empty `{}` — some tools/workflows take no
+ * inputs. A `@file` read failure or invalid JSON is a typed error the caller
+ * surfaces; this function never throws or exits.
+ */
+export declare function ingestJsonArgs(opts: IngestOptions): Promise<IngestResult>;

package/dist/inputs.js

@@ -0,0 +1,50 @@
+/**
+ * Shared JSON-args ingestion for `lotics run` and `lotics app workflow`.
+ *
+ * A tool/workflow payload can arrive three ways, all of which bypass the OS
+ * `ARG_MAX` limit so bulk inputs (a knowledge-doc `content`, a batch update)
+ * don't overflow the inline arg:
+ *   - inline:  `… '<json>'`
+ *   - `@file`: `… @args.json`   (a leading `@` is unambiguous — JSON starts `{`)
+ *   - stdin:   `… < args.json`  or  `cat args.json | …`
+ *
+ * Kept apart from `cli.ts` (which runs `main()` on import) so the file/JSON
+ * branches are unit-testable; `readStdin` is injected so the tests don't touch
+ * the real process stdin.
+ */
+/**
+ * Resolve the raw payload string, then JSON.parse it. An absent payload (no
+ * arg, no piped stdin) is a valid empty `{}` — some tools/workflows take no
+ * inputs. A `@file` read failure or invalid JSON is a typed error the caller
+ * surfaces; this function never throws or exits.
+ */
+export async function ingestJsonArgs(opts) {
+    let raw = opts.rawArg;
+    if (raw && raw.startsWith("@")) {
+        const argsPath = raw.slice(1);
+        try {
+            raw = opts.readFile(argsPath);
+        }
+        catch (err) {
+            return {
+                kind: "error",
+                message: `Cannot read args file "${argsPath}": ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    else if (!raw && !opts.stdinIsTTY) {
+        raw = await opts.readStdin();
+    }
+    if (!raw)
+        return { kind: "ok", args: {} };
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { kind: "error", message: `JSON args must be an object, got: ${raw}` };
+        }
+        return { kind: "ok", args: parsed };
+    }
+    catch {
+        return { kind: "error", message: `Invalid JSON: ${raw}` };
+    }
+}

package/dist/inputs.test.d.ts

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

package/dist/inputs.test.js

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "vitest";
+import { ingestJsonArgs } from "./inputs.js";
+const neverFile = () => {
+    throw new Error("readFile should not be called");
+};
+const neverStdin = async () => {
+    throw new Error("readStdin should not be called");
+};
+describe("ingestJsonArgs", () => {
+    it("parses an inline JSON object arg without touching file/stdin", async () => {
+        const r = await ingestJsonArgs({
+            rawArg: '{"table_id":"tbl_1"}',
+            stdinIsTTY: true,
+            readFile: neverFile,
+            readStdin: neverStdin,
+        });
+        expect(r).toEqual({ kind: "ok", args: { table_id: "tbl_1" } });
+    });
+    it("reads @file args (bypassing ARG_MAX)", async () => {
+        const r = await ingestJsonArgs({
+            rawArg: "@args.json",
+            stdinIsTTY: true,
+            readFile: (p) => {
+                expect(p).toBe("args.json");
+                return '{"big":"payload"}';
+            },
+            readStdin: neverStdin,
+        });
+        expect(r).toEqual({ kind: "ok", args: { big: "payload" } });
+    });
+    it("surfaces a typed error when the @file can't be read", async () => {
+        const r = await ingestJsonArgs({
+            rawArg: "@missing.json",
+            stdinIsTTY: true,
+            readFile: () => {
+                throw new Error("ENOENT");
+            },
+            readStdin: neverStdin,
+        });
+        expect(r.kind).toBe("error");
+        if (r.kind === "error")
+            expect(r.message).toContain("missing.json");
+    });
+    it("reads piped stdin when there's no arg and stdin is not a TTY", async () => {
+        const r = await ingestJsonArgs({
+            rawArg: undefined,
+            stdinIsTTY: false,
+            readFile: neverFile,
+            readStdin: async () => '{"from":"stdin"}',
+        });
+        expect(r).toEqual({ kind: "ok", args: { from: "stdin" } });
+    });
+    it("treats an absent payload (no arg, TTY stdin) as empty {}", async () => {
+        const r = await ingestJsonArgs({
+            rawArg: undefined,
+            stdinIsTTY: true,
+            readFile: neverFile,
+            readStdin: neverStdin,
+        });
+        expect(r).toEqual({ kind: "ok", args: {} });
+    });
+    it("errors on invalid JSON", async () => {
+        const r = await ingestJsonArgs({
+            rawArg: "{not json",
+            stdinIsTTY: true,
+            readFile: neverFile,
+            readStdin: neverStdin,
+        });
+        expect(r.kind).toBe("error");
+        if (r.kind === "error")
+            expect(r.message).toContain("Invalid JSON");
+    });
+    it("rejects a non-object top-level JSON (array / scalar)", async () => {
+        const arr = await ingestJsonArgs({
+            rawArg: "[1,2,3]",
+            stdinIsTTY: true,
+            readFile: neverFile,
+            readStdin: neverStdin,
+        });
+        expect(arr.kind).toBe("error");
+        const scalar = await ingestJsonArgs({
+            rawArg: "42",
+            stdinIsTTY: true,
+            readFile: neverFile,
+            readStdin: neverStdin,
+        });
+        expect(scalar.kind).toBe("error");
+    });
+});