@lotics/cli 0.22.0 → 0.24.0

package/dist/src/app_commands.d.ts

@@ -1,4 +1,35 @@
 import { LoticsClient } from "./client.js";
+/**
+ * Manifest declaration for one workflow alias:
+ *   `"alias": { workflow_id, inputs?: { key: { type, … } } }`
+ *
+ * When `inputs` is declared, the CLI codegen emits a typed `AppWorkflows[alias]`
+ * entry and the server validates payloads against it at execute time. Omit
+ * `inputs` for workflows that accept no typed inputs.
+ */
+export type AppWorkflowDeclaration = {
+    workflow_id: string;
+    inputs?: Record<string, unknown>;
+};
+/**
+ * Stamp the post-extraction manifest with server-authoritative meta. Called
+ * by `appPull` after the source archive lands on disk.
+ *
+ * Crucially, `workflows` is sourced from `app.workflows` (live DB state),
+ * NOT from whatever the extracted archive's package.json contains. The
+ * archive's embedded `lotics.workflows` is a frozen snapshot from deploy
+ * time and would silently overwrite any agent-authored bindings made via
+ * `set_app_workflow` since the last deploy. Exported for direct unit
+ * testing — the rest of `appPull` involves shelling out to `tar`/`npm`,
+ * which doesn't reward integration coverage.
+ */
+export declare function stampPulledManifest(projectDir: string, args: {
+    app_id: string;
+    workspace_id: string;
+    current_version_id: string;
+    version_number: number;
+    workflows: Record<string, AppWorkflowDeclaration>;
+}): void;
 /**
  * `lotics app create <name> [path]`
  *
@@ -23,9 +54,16 @@ export declare function appCreate(client: LoticsClient, args: {
  * Bootstraps a full local dev environment for an existing app:
  *   1. Fetch the current version's source archive from R2 (presigned URL).
  *   2. Extract into the target directory.
- *   3. Write package.json's `lotics` field with app_id + version metadata.
- *   4. Run `npm install`.
- *   5. (TODO) Generate `.lotics/types.ts` with workspace-typed augmentations.
+ *   3. Stamp package.json's `lotics` field with app_id + version metadata,
+ *      and the live `apps.workflows` map from the server (NOT the manifest
+ *      embedded in the source archive — that's a frozen snapshot from deploy
+ *      time and would silently overwrite any agent-authored bindings made via
+ *      `set_app_workflow` since the last deploy).
+ *   4. Regenerate `.lotics/app_workflows.d.ts` from the live workflows so
+ *      `useWorkflow<"alias">` is typed at pull time.
+ *   5. Run `npm install`.
+ *   6. (TODO) Generate `.lotics/types.ts` with workspace tables augmentation —
+ *      pending a `client.getWorkspaceSchema()` endpoint.
  */
 export declare function appPull(client: LoticsClient, args: {
     app_id: string;
@@ -42,6 +80,7 @@ export declare function appPull(client: LoticsClient, args: {
 export declare function appDeploy(client: LoticsClient, args: {
     projectDir?: string;
     message?: string;
+    forceWorkflowSync?: boolean;
 }): Promise<void>;
 /**
  * `lotics app dev [path] [--port=5174] [--vite-port=5173]`

package/dist/src/app_commands.js

@@ -17,6 +17,7 @@ import { spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { buildStarterTemplate } from "./starter_template.js";
 import { startDevServer, openBrowser } from "./dev/server.js";
+import { generateAppWorkflowsDts } from "./generate_app_workflows_dts.js";
 /** Run `tar` and resolve when it exits cleanly. Throws with stderr on failure. */
 function runTar(args, cwd) {
     return new Promise((resolve, reject) => {
@@ -71,6 +72,40 @@ function writeAppMeta(projectDir, meta) {
     pkg.lotics = meta;
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
+/**
+ * Write `.lotics/app_workflows.d.ts` from the manifest's `workflows` map.
+ * Called from `app pull`, `app dev`, and `app deploy` so the augmented
+ * `AppWorkflows` types stay in sync with the manifest. The starter
+ * tsconfig.json includes `.lotics/` so tsc + Vite pick it up automatically.
+ */
+function writeAppWorkflowsDts(projectDir, workflows) {
+    const dotLotics = path.join(projectDir, ".lotics");
+    fs.mkdirSync(dotLotics, { recursive: true });
+    const dts = generateAppWorkflowsDts(workflows);
+    fs.writeFileSync(path.join(dotLotics, "app_workflows.d.ts"), dts);
+}
+/**
+ * Stamp the post-extraction manifest with server-authoritative meta. Called
+ * by `appPull` after the source archive lands on disk.
+ *
+ * Crucially, `workflows` is sourced from `app.workflows` (live DB state),
+ * NOT from whatever the extracted archive's package.json contains. The
+ * archive's embedded `lotics.workflows` is a frozen snapshot from deploy
+ * time and would silently overwrite any agent-authored bindings made via
+ * `set_app_workflow` since the last deploy. Exported for direct unit
+ * testing — the rest of `appPull` involves shelling out to `tar`/`npm`,
+ * which doesn't reward integration coverage.
+ */
+export function stampPulledManifest(projectDir, args) {
+    writeAppMeta(projectDir, {
+        app_id: args.app_id,
+        workspace_id: args.workspace_id,
+        current_version_id: args.current_version_id,
+        version_number: args.version_number,
+        workflows: args.workflows,
+    });
+    writeAppWorkflowsDts(projectDir, args.workflows);
+}
 async function downloadToFile(url, destPath) {
     const response = await fetch(url);
     if (!response.ok) {
@@ -117,6 +152,10 @@ export async function appCreate(client, args) {
         fs.writeFileSync(fullPath, file.content);
     }
     console.error(`Scaffolded ${files.length} files into ${targetPath}`);
+    // Codegen pass for AppWorkflows typing. Empty manifest on first create —
+    // emits a base augmentation file so future deploys produce idempotent diffs
+    // rather than introducing a new tracked file later.
+    writeAppWorkflowsDts(targetPath, {});
     console.error("Installing npm dependencies...");
     await runNpm(["install"], targetPath);
     console.error("Building initial version...");
@@ -135,9 +174,16 @@ export async function appCreate(client, args) {
  * Bootstraps a full local dev environment for an existing app:
  *   1. Fetch the current version's source archive from R2 (presigned URL).
  *   2. Extract into the target directory.
- *   3. Write package.json's `lotics` field with app_id + version metadata.
- *   4. Run `npm install`.
- *   5. (TODO) Generate `.lotics/types.ts` with workspace-typed augmentations.
+ *   3. Stamp package.json's `lotics` field with app_id + version metadata,
+ *      and the live `apps.workflows` map from the server (NOT the manifest
+ *      embedded in the source archive — that's a frozen snapshot from deploy
+ *      time and would silently overwrite any agent-authored bindings made via
+ *      `set_app_workflow` since the last deploy).
+ *   4. Regenerate `.lotics/app_workflows.d.ts` from the live workflows so
+ *      `useWorkflow<"alias">` is typed at pull time.
+ *   5. Run `npm install`.
+ *   6. (TODO) Generate `.lotics/types.ts` with workspace tables augmentation —
+ *      pending a `client.getWorkspaceSchema()` endpoint.
  */
 export async function appPull(client, args) {
     const app = await client.getApp(args.app_id);
@@ -160,11 +206,17 @@ export async function appPull(client, args) {
         if (fs.existsSync(tmpFile))
             fs.unlinkSync(tmpFile);
     }
-    writeAppMeta(targetPath, {
+    // Workflows live on the App row, not in the source archive. The R2 archive
+    // is for code; pull the workflows live from `apps.workflows` so agent-
+    // authored bindings (via set_app_workflow) land in the local manifest. The
+    // archive's embedded `lotics.workflows` is a deploy-time snapshot and would
+    // be stale relative to anything authored since.
+    stampPulledManifest(targetPath, {
         app_id: app.id,
         workspace_id: app.workspace_id,
         current_version_id: app.current_version_id,
         version_number: version.version,
+        workflows: app.workflows ?? {},
     });
     console.error(`Installing npm dependencies...`);
     await runNpm(["install"], targetPath);
@@ -184,6 +236,10 @@ export async function appPull(client, args) {
 export async function appDeploy(client, args) {
     const projectDir = path.resolve(args.projectDir ?? process.cwd());
     const meta = readAppMeta(projectDir);
+    // Regenerate AppWorkflows typing before the build picks up source. Keeps
+    // .lotics/app_workflows.d.ts in sync with the manifest's workflows map
+    // every time the developer ships.
+    writeAppWorkflowsDts(projectDir, meta.workflows);
     // Build locally so the server doesn't need a build sandbox in v1.
     console.error("Building...");
     await runNpm(["run", "build"], projectDir);
@@ -219,6 +275,9 @@ export async function appDeploy(client, args) {
                 // Sync apps.workflows from the manifest. Server validates each
                 // workflow_id exists in the workspace before committing.
                 workflows: meta.workflows ?? {},
+                // Opt into destructive workflow removal. Default false — the server
+                // rejects deploys whose manifest is missing aliases the App row has.
+                force_workflow_sync: args.forceWorkflowSync,
             });
             writeAppMeta(projectDir, {
                 ...meta,
@@ -261,6 +320,10 @@ export async function appDeploy(client, args) {
 export async function appDev(client, args) {
     const projectDir = path.resolve(args.projectDir ?? process.cwd());
     const meta = readAppMeta(projectDir);
+    // Regenerate AppWorkflows typing before Vite spins up so the dev typecheck
+    // sees the current shape. Doesn't watch for manifest changes mid-session —
+    // re-running `lotics app dev` after editing the manifest is the loop.
+    writeAppWorkflowsDts(projectDir, meta.workflows);
     // Sanity: confirm the app exists in the workspace the CLI is auth'd into.
     // Surfaces a clear error if the project's app_id has been deleted or the
     // CLI is pointed at the wrong workspace.

package/dist/src/app_commands.test.d.ts

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

package/dist/src/app_commands.test.js

@@ -0,0 +1,103 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { stampPulledManifest } from "./app_commands.js";
+/**
+ * `appPull` reads workflows from the live App row (server response), NOT from
+ * the manifest embedded in the extracted source archive. The frozen archive
+ * snapshot would silently overwrite any agent-authored bindings (via
+ * `set_app_workflow`) that landed on the App row after the last deploy.
+ *
+ * Tests `stampPulledManifest` directly — the part of `appPull` that decides
+ * which workflows source wins. The rest of `appPull` shells out to
+ * `tar`/`npm`, which is integration territory.
+ */
+describe("stampPulledManifest", () => {
+    let workDir;
+    beforeEach(() => {
+        workDir = fs.mkdtempSync(path.join(tmpdir(), "lotics-sdk-test-"));
+    });
+    afterEach(() => {
+        fs.rmSync(workDir, { recursive: true, force: true });
+    });
+    function writeExtractedPackageJson(workflows) {
+        fs.writeFileSync(path.join(workDir, "package.json"), JSON.stringify({
+            name: "sample-app",
+            lotics: {
+                // Stale archived map — must NOT survive the stamp.
+                app_id: "app_old",
+                workspace_id: "wks_old",
+                current_version_id: "apv_old",
+                version_number: 1,
+                workflows,
+            },
+        }, null, 2));
+    }
+    function readStampedManifest() {
+        const pkg = JSON.parse(fs.readFileSync(path.join(workDir, "package.json"), "utf-8"));
+        return pkg.lotics;
+    }
+    it("writes workflows from the live argument, overriding the archive-embedded manifest", () => {
+        // Simulate the source archive's embedded manifest containing a stale
+        // alias — the kind of thing that ships when an agent-authored workflow
+        // hasn't yet been propagated to a developer's local checkout.
+        writeExtractedPackageJson({
+            stale_archive_alias: { workflow_id: "wfl_archived_at_deploy_time" },
+        });
+        // Live state from the server — what `client.getApp()` returns. This
+        // includes the agent-authored alias added since the last deploy.
+        stampPulledManifest(workDir, {
+            app_id: "app_live",
+            workspace_id: "wks_live",
+            current_version_id: "apv_live",
+            version_number: 7,
+            workflows: {
+                agent_authored: { workflow_id: "wfl_authored_by_agent" },
+                renamed: { workflow_id: "wfl_renamed_on_server" },
+            },
+        });
+        const stamped = readStampedManifest();
+        expect(stamped.app_id).toBe("app_live");
+        expect(stamped.workspace_id).toBe("wks_live");
+        expect(stamped.current_version_id).toBe("apv_live");
+        expect(stamped.version_number).toBe(7);
+        // Only the live workflows are present. The archive's stale_archive_alias
+        // does not survive — proving we're not reading from the extracted manifest.
+        expect(stamped.workflows).toEqual({
+            agent_authored: { workflow_id: "wfl_authored_by_agent" },
+            renamed: { workflow_id: "wfl_renamed_on_server" },
+        });
+        expect(stamped.workflows).not.toHaveProperty("stale_archive_alias");
+    });
+    it("clears the local workflows when the server has none", () => {
+        writeExtractedPackageJson({
+            stale_archive_alias: { workflow_id: "wfl_should_disappear" },
+        });
+        stampPulledManifest(workDir, {
+            app_id: "app_x",
+            workspace_id: "wks_x",
+            current_version_id: "apv_x",
+            version_number: 2,
+            workflows: {},
+        });
+        const stamped = readStampedManifest();
+        expect(stamped.workflows).toEqual({});
+    });
+    it("emits .lotics/app_workflows.d.ts from the live workflows", () => {
+        writeExtractedPackageJson({});
+        stampPulledManifest(workDir, {
+            app_id: "app_y",
+            workspace_id: "wks_y",
+            current_version_id: "apv_y",
+            version_number: 3,
+            workflows: {
+                only_live: { workflow_id: "wfl_only_live" },
+            },
+        });
+        const dtsPath = path.join(workDir, ".lotics", "app_workflows.d.ts");
+        expect(fs.existsSync(dtsPath)).toBe(true);
+        const dts = fs.readFileSync(dtsPath, "utf-8");
+        expect(dts).toContain("only_live");
+    });
+});

package/dist/src/cli.js

@@ -46,7 +46,10 @@ COMMANDS
                                        Download all files on a record file field
   lotics app create <name> [path]      Create a new custom-code app + scaffold locally
   lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
-  lotics app deploy [-m <message>]     Build + upload current dir as a new version
+  lotics app deploy [-m <message>] [--force-workflow-sync]
+                                       Build + upload current dir as a new version
+                                       (--force-workflow-sync wipes server-only
+                                       workflow aliases; default refuses)
   lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
 
 FLAGS
@@ -403,7 +406,8 @@ async function main() {
         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 deploy [-m <message>] [--force-workflow-sync]");
+        console.error("                                       Build + upload the current directory");
         console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
         process.exit(1);
     }
@@ -520,8 +524,11 @@ async function main() {
         if (subcommand === "deploy") {
             // -m / --message can be passed via toolArgs or after a flag-like delimiter.
             // Keep it simple: any positional arg after `deploy` is treated as the message.
+            // --force-workflow-sync is a separate flag captured upstream via restArgs
+            // because it has no value (boolean toggle).
             const message = toolArgs;
-            await appDeploy(client, { message });
+            const forceWorkflowSync = restArgs.includes("--force-workflow-sync");
+            await appDeploy(client, { message, forceWorkflowSync });
             return;
         }
         if (subcommand === "dev") {

package/dist/src/client.d.ts

@@ -75,6 +75,17 @@ export declare class LoticsClient {
         name: string;
         workspace_id: string;
         current_version_id: string | null;
+        /**
+         * Live alias → workflow declaration map from `apps.workflows`. Source of
+         * truth for `lotics app pull` — supersedes the manifest embedded in the
+         * source archive so agent-authored bindings (via `set_app_workflow`)
+         * survive the pull/edit/deploy loop. Null/undefined on apps that have
+         * never had a workflow declared.
+         */
+        workflows?: Record<string, {
+            workflow_id: string;
+            inputs?: Record<string, unknown>;
+        }> | null;
     }>;
     createApp(body: {
         name: string;
@@ -124,12 +135,26 @@ export declare class LoticsClient {
         prev_version_id?: string | null;
         message?: string | null;
         /**
-         * Alias → workflow_id map from the app's package.json `lotics.workflows`.
-         * Always sent (empty object when none declared) so the server can
-         * overwrite apps.workflows authoritatively. Deleting an alias from the
-         * manifest removes it from the DB on next deploy.
+         * Alias → workflow declaration map from the app's `package.json#lotics.workflows`.
+         * Each value is a `{ workflow_id, inputs? }` object — inputs declares a typed
+         * schema or is omitted when the workflow accepts no typed inputs. Always sent
+         * (empty object when none declared) so the server can overwrite apps.workflows
+         * authoritatively. Deleting an alias from the manifest removes it from the DB
+         * on next deploy — gated by the destructive-removal guard unless
+         * `force_workflow_sync` is true.
+         */
+        workflows?: Record<string, {
+            workflow_id: string;
+            inputs?: Record<string, unknown>;
+        }>;
+        /**
+         * Opt into destructive workflow removal. When false/absent, the server
+         * rejects a deploy whose `workflows` map is missing aliases that exist
+         * on the App row. Set true to deploy anyway and wipe the missing aliases —
+         * the user is asserting they know what they're doing. Wired to CLI flag
+         * `--force-workflow-sync`.
          */
-        workflows?: Record<string, string>;
+        force_workflow_sync?: boolean;
     }): Promise<{
         version_id: string;
         version_number: number;

package/dist/src/client.js

@@ -205,6 +205,12 @@ export class LoticsClient {
         // Always send workflows — empty object is meaningful (clears any
         // previously-declared aliases). Server validates each entry.
         formData.append("workflows", JSON.stringify(args.workflows ?? {}));
+        // Only post the override flag when the user explicitly opts in. The
+        // server defaults to "honor the guard" — opt-in is loud, opt-out
+        // requires intent.
+        if (args.force_workflow_sync) {
+            formData.append("force_workflow_sync", "true");
+        }
         const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
         const response = await fetch(url, {
             method: "POST",

package/dist/src/generate_app_workflows_dts.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Codegen: emit `.lotics/app_workflows.d.ts` from the app's manifest.
+ *
+ * The starter tsconfig.json includes `.lotics/` in its `include` list, so this
+ * file is auto-discovered by `tsc --noEmit` and the bundler. The augmentation
+ * adds a typed entry to `AppWorkflows` for every alias declared in
+ * `package.json#lotics.workflows`:
+ *
+ *   - Shorthand `"alias": "wfl_..."`        → `alias: Record<string, unknown>`
+ *     (untyped — callsite accepts any payload)
+ *   - Full `"alias": { workflow_id, inputs }` → `alias: { …declared shape… }`
+ *     (typed — `useWorkflow<"alias">` returns a callable with shaped inputs)
+ *
+ * Pure function. Same inputs → same output. Idempotent.
+ */
+import type { AppWorkflowDeclaration } from "./app_commands.js";
+export declare function generateAppWorkflowsDts(workflows: Record<string, AppWorkflowDeclaration> | undefined): string;

package/dist/src/generate_app_workflows_dts.js

@@ -0,0 +1,123 @@
+/**
+ * Codegen: emit `.lotics/app_workflows.d.ts` from the app's manifest.
+ *
+ * The starter tsconfig.json includes `.lotics/` in its `include` list, so this
+ * file is auto-discovered by `tsc --noEmit` and the bundler. The augmentation
+ * adds a typed entry to `AppWorkflows` for every alias declared in
+ * `package.json#lotics.workflows`:
+ *
+ *   - Shorthand `"alias": "wfl_..."`        → `alias: Record<string, unknown>`
+ *     (untyped — callsite accepts any payload)
+ *   - Full `"alias": { workflow_id, inputs }` → `alias: { …declared shape… }`
+ *     (typed — `useWorkflow<"alias">` returns a callable with shaped inputs)
+ *
+ * Pure function. Same inputs → same output. Idempotent.
+ */
+const HEADER = `// Auto-generated by 'lotics app pull/dev/deploy'.
+// DO NOT EDIT — regenerated from package.json#lotics.workflows.
+//
+// This file gives \`useWorkflow("alias")\` a typed input parameter at call
+// sites by augmenting the @lotics/app-sdk \`AppWorkflows\` interface.
+
+import "@lotics/app-sdk";
+`;
+export function generateAppWorkflowsDts(workflows) {
+    const entries = Object.entries(workflows ?? {});
+    if (entries.length === 0) {
+        return `${HEADER}
+// No workflows declared in package.json#lotics.workflows.
+// Add an entry to enable typed useWorkflow<"alias"> at call sites.
+declare module "@lotics/app-sdk" {
+  interface AppWorkflows {}
+}
+`;
+    }
+    // Sort alphabetically for deterministic output across regenerations.
+    entries.sort(([a], [b]) => a.localeCompare(b));
+    const lines = [];
+    for (const [alias, declaration] of entries) {
+        // declaration is always `{ workflow_id, inputs? }` per manifest schema.
+        // Workflows with no typed inputs omit `inputs:` and get an untyped
+        // `Record<string, unknown>` callable surface.
+        const valueType = declaration.inputs
+            ? inputsToType(declaration.inputs)
+            : "Record<string, unknown>";
+        const aliasKey = isValidIdentifier(alias) ? alias : JSON.stringify(alias);
+        lines.push(`    ${aliasKey}: ${valueType};`);
+    }
+    return `${HEADER}
+declare module "@lotics/app-sdk" {
+  interface AppWorkflows {
+${lines.join("\n")}
+  }
+}
+`;
+}
+/**
+ * Map an `inputs: { key: AppWorkflowInput }` schema to a TS literal type
+ * string. Mirrors the backend .d.ts generator's behavior — same vocabulary,
+ * same conventions — so workflow body types and app call-site types agree.
+ *
+ * Note: `inputs` here is `Record<string, unknown>` rather than typed because
+ * the CLI doesn't import zod or the apps schema (zero-dep policy in @lotics/sdk).
+ * We pattern-match on the `type` field and let unknown shapes fall through
+ * to `unknown` rather than throwing — the server's deploy-time schema parse
+ * catches structurally-invalid declarations before they reach us.
+ */
+function inputsToType(inputs) {
+    const fields = [];
+    for (const [key, decl] of Object.entries(inputs)) {
+        if (decl === null || typeof decl !== "object")
+            continue;
+        const d = decl;
+        const tsType = inputDeclToTsType(d);
+        const optional = d.required === false ? "?" : "";
+        const fieldKey = isValidIdentifier(key) ? key : JSON.stringify(key);
+        fields.push(`      ${fieldKey}${optional}: ${tsType};`);
+    }
+    if (fields.length === 0)
+        return "Record<string, never>";
+    return `{\n${fields.join("\n")}\n    }`;
+}
+function inputDeclToTsType(decl) {
+    const type = decl.type;
+    switch (type) {
+        case "text":
+        case "email":
+        case "date":
+        case "datetime":
+            return "string";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "record_link":
+        case "member": {
+            const inner = "string";
+            return decl.multi === true ? `ReadonlyArray<${inner}>` : inner;
+        }
+        case "select": {
+            const options = Array.isArray(decl.options) ? decl.options : [];
+            const literals = options
+                .map((o) => {
+                if (o !== null && typeof o === "object" && "value" in o && typeof o.value === "string") {
+                    return JSON.stringify(o.value);
+                }
+                return null;
+            })
+                .filter((v) => v !== null);
+            const inner = literals.length > 0 ? literals.join(" | ") : "string";
+            return decl.multi === true ? `ReadonlyArray<${inner}>` : inner;
+        }
+        case "date_range":
+            return "{ start: string; end: string }";
+        case "json":
+            return "unknown";
+        default:
+            return "unknown";
+    }
+}
+const IDENTIFIER_REGEX = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+function isValidIdentifier(name) {
+    return IDENTIFIER_REGEX.test(name);
+}

package/dist/src/starter_template.js

@@ -161,6 +161,20 @@ export default defineConfig({
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>${escapeHtml(args.app_name)}</title>
+    <style>
+      /*
+       * Full-viewport container chain for iframe apps. @lotics/ui's DataGrid
+       * (and any layout that uses \`flex: 1\` to fill available space) relies
+       * on a measured parent height. The browser default of html/body being
+       * content-sized collapses every \`flex: 1\` to 0 and the surface shrinks
+       * to fit only its rendered content.
+       *
+       * Also: #root is made a flex column so the outermost RN \`<View flex:1>\`
+       * inside App.tsx claims the full iframe height.
+       */
+      html, body, #root { height: 100%; margin: 0; }
+      #root { display: flex; flex-direction: column; }
+    </style>
   </head>
   <body>
     <div id="root"></div>
@@ -180,34 +194,55 @@ mount(<App />);
         },
         {
             path: "src/App.tsx",
-            // Static welcome screen using @lotics/ui primitives — no useTable call
-            // so the freshly-deployed v1 renders cleanly without needing a real
-            // table id. The user's first edit is to replace this with their app.
+            // Welcome screen demonstrates the full-container layout pattern that
+            // real apps (data grids, dashboards, full-page surfaces) rely on:
+            //   - Outer <View flex:1> claims the full iframe height (works because
+            //     index.html sets html/body/#root to 100% + #root is a flex column).
+            //   - Inner View is content-sized + centered for a card layout.
+            //
+            // We deliberately do NOT use @lotics/ui/stack for the outer chain.
+            // Stack wraps each child in an unstyled <View>, which breaks `flex: 1`
+            // propagation to children that need to claim flexible height (e.g., a
+            // DataGrid that fills the remaining space below a header + search).
+            // Use plain <View> with `flexDirection` + `gap` for any outer layout
+            // that hosts a flex-filling child; Stack is fine for content-sized
+            // groupings inside such a chain.
             content: `import { View } from "react-native";
-import { Stack } from "@lotics/ui/stack";
 import { Card } from "@lotics/ui/card";
 import { Text } from "@lotics/ui/text";
 import { Button } from "@lotics/ui/button";
 
+// Outer <View flex:1> claims the full iframe height — works because
+// index.html sets html/body/#root to 100% and #root is a flex column.
+// For real layouts with a fill-remaining-space child (DataGrid etc.),
+// keep this flex chain plain — @lotics/ui/stack wraps each child in an
+// unstyled <View> that breaks \`flex: 1\` propagation.
 export default function App() {
   return (
-    <View style={{ padding: 24, maxWidth: 640, marginHorizontal: "auto" }}>
-      <Stack gap={16}>
+    <View
+      style={{
+        flex: 1,
+        padding: 24,
+        justifyContent: "center",
+        alignItems: "center",
+      }}
+    >
+      <View style={{ maxWidth: 640, width: "100%", gap: 16 }}>
         <Text size="xl" weight="semibold">${escapeHtml(args.app_name)}</Text>
         <Card>
-          <Stack gap={8} style={{ padding: 16 }}>
+          <View style={{ padding: 16, gap: 8 }}>
             <Text>This is your new Lotics app.</Text>
             <Text color="muted">
               Edit <Text weight="medium">src/App.tsx</Text> and run{" "}
               <Text weight="medium">lotics app deploy</Text> to publish.
             </Text>
-          </Stack>
+          </View>
         </Card>
         <Text color="muted" size="sm">
           Hooks from @lotics/app-sdk: useTable, useMutate, useAction, useQuery, useWorkflow.
         </Text>
         <Button title="Get started" onPress={() => {}} color="primary" />
-      </Stack>
+      </View>
     </View>
   );
 }
@@ -230,6 +265,58 @@ declare module "lucide-react-native/dist/esm/icons/*" {
   }>;
   export default Icon;
 }
+`,
+        },
+        {
+            path: "src/css_modules.d.ts",
+            content: `declare module "*.module.css" {
+  const classes: { [key: string]: string };
+  export default classes;
+}
+`,
+        },
+        {
+            path: "src/react_native.d.ts",
+            content: `import "react-native";
+
+// Augments react-native's types with the web-only fields @lotics/ui consumes:
+// Pressable's \`hovered\` callback state, plus web-only ViewStyle / TextStyle
+// properties (cursor, outline, boxShadow, etc.) used by the grid + primitives.
+// Each iframe app needs its own copy — TypeScript doesn't auto-pick-up
+// \`.d.ts\` files inside dependencies. \`@lotics/ui\`'s grid sources include a
+// triple-slash reference to its own copy of this file so the augmentation
+// kicks in transitively.
+declare module "react-native" {
+  interface PressableStateCallbackType {
+    hovered: boolean;
+  }
+
+  interface ViewStyle {
+    backdropFilter?: string;
+    backgroundImage?: string;
+    boxShadow?: string;
+    boxSizing?: string;
+    cursor?: string;
+    touchAction?: string;
+    transitionDuration?: string;
+    transitionProperty?: string;
+    appearance?: string;
+    outline?: string;
+    outlineColor?: string;
+    outlineStyle?: string;
+    outlineWidth?: number;
+    outlineOffset?: number;
+  }
+
+  interface TextStyle {
+    outline?: string;
+    outlineColor?: string;
+    outlineStyle?: string;
+    outlineWidth?: number;
+    outlineOffset?: number;
+    appearance?: string;
+  }
+}
 `,
         },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {
@@ -16,8 +16,12 @@
   "scripts": {
     "build": "tsgo",
     "typecheck": "tsgo --noEmit",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
+  "devDependencies": {
+    "vitest": "^4.0.15"
+  },
   "keywords": [
     "lotics",
     "sdk",