@lotics/cli 0.25.0 → 0.27.0

package/dist/src/app_commands.d.ts

@@ -11,6 +11,18 @@ export type AppWorkflowDeclaration = {
     workflow_id: string;
     inputs?: Record<string, unknown>;
 };
+/**
+ * Manifest declaration for one named query:
+ *   `"alias": { ast, params?: { key: { type, … } } }`
+ *
+ * `ast` is a fixed query AST template; `params` declares the typed value
+ * holes (`{{params.<name>}}`) the app fills via `useQuery(alias, params)`.
+ * Custom-code apps never send a raw AST — this declaration is the contract.
+ */
+export type AppQueryDeclaration = {
+    ast: unknown;
+    params?: Record<string, unknown>;
+};
 /**
  * Stamp the post-extraction manifest with server-authoritative meta. Called
  * by `appPull` after the source archive lands on disk.
@@ -29,6 +41,7 @@ export declare function stampPulledManifest(projectDir: string, args: {
     current_version_id: string;
     version_number: number;
     workflows: Record<string, AppWorkflowDeclaration>;
+    queries: Record<string, AppQueryDeclaration>;
 }): void;
 /**
  * `lotics app create <name> [path]`
@@ -86,8 +99,8 @@ export declare function appDeploy(client: LoticsClient, args: {
  * `lotics app dev [path] [--port=5174] [--vite-port=5173]`
  *
  * Local dev mode for iframe apps. Spawns Vite + a postMessage RPC forwarder
- * that bridges the iframe's hooks (useQuery, useMutate, useAction,
- * useWorkflow) to api.lotics.ai using the CLI's stored API key. Wrapper
+ * that bridges the iframe's hooks (useQuery, useWorkflow) to api.lotics.ai
+ * using the CLI's stored API key. Wrapper
  * iframe matches the production sandbox attributes exactly — null origin,
  * allow-scripts — so prod-equivalent runtime behavior surfaces in dev.
  *

package/dist/src/app_commands.js

@@ -18,6 +18,7 @@ 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";
+import { generateAppQueriesDts } from "./generate_app_queries_dts.js";
 /** Run `tar` and resolve when it exits cleanly. Throws with stderr on failure. */
 function runTar(args, cwd) {
     return new Promise((resolve, reject) => {
@@ -64,6 +65,7 @@ function readAppMeta(projectDir) {
         current_version_id: pkg.lotics.current_version_id ?? null,
         version_number: pkg.lotics.version_number ?? null,
         workflows: pkg.lotics.workflows ?? {},
+        queries: pkg.lotics.queries ?? {},
     };
 }
 function writeAppMeta(projectDir, meta) {
@@ -73,16 +75,17 @@ function writeAppMeta(projectDir, 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.
+ * Write `.lotics/app_workflows.d.ts` + `.lotics/app_queries.d.ts` from the
+ * manifest's `workflows` / `queries` maps. Called from `app create / pull /
+ * dev / deploy` so the augmented `AppWorkflows` / `AppQueries` types stay in
+ * sync with the manifest. The starter tsconfig.json includes `.lotics/` so
+ * tsc + Vite pick the files up automatically.
  */
-function writeAppWorkflowsDts(projectDir, workflows) {
+function writeAppDts(projectDir, manifest) {
     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);
+    fs.writeFileSync(path.join(dotLotics, "app_workflows.d.ts"), generateAppWorkflowsDts(manifest.workflows));
+    fs.writeFileSync(path.join(dotLotics, "app_queries.d.ts"), generateAppQueriesDts(manifest.queries));
 }
 /**
  * Stamp the post-extraction manifest with server-authoritative meta. Called
@@ -103,8 +106,9 @@ export function stampPulledManifest(projectDir, args) {
         current_version_id: args.current_version_id,
         version_number: args.version_number,
         workflows: args.workflows,
+        queries: args.queries,
     });
-    writeAppWorkflowsDts(projectDir, args.workflows);
+    writeAppDts(projectDir, { workflows: args.workflows, queries: args.queries });
 }
 async function downloadToFile(url, destPath) {
     const response = await fetch(url);
@@ -155,7 +159,7 @@ export async function appCreate(client, args) {
     // 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, {});
+    writeAppDts(targetPath, {});
     console.error("Installing npm dependencies...");
     await runNpm(["install"], targetPath);
     console.error("Building initial version...");
@@ -217,6 +221,7 @@ export async function appPull(client, args) {
         current_version_id: app.current_version_id,
         version_number: version.version,
         workflows: app.workflows ?? {},
+        queries: app.queries ?? {},
     });
     console.error(`Installing npm dependencies...`);
     await runNpm(["install"], targetPath);
@@ -239,7 +244,7 @@ export async function appDeploy(client, args) {
     // 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);
+    writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries });
     // Build locally so the server doesn't need a build sandbox in v1.
     console.error("Building...");
     await runNpm(["run", "build"], projectDir);
@@ -275,6 +280,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 ?? {},
+                // Sync apps.queries from the manifest. Server validates each query
+                // template (parseQueryNode, table access, param coverage).
+                queries: meta.queries ?? {},
                 // 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,
@@ -308,8 +316,8 @@ export async function appDeploy(client, args) {
  * `lotics app dev [path] [--port=5174] [--vite-port=5173]`
  *
  * Local dev mode for iframe apps. Spawns Vite + a postMessage RPC forwarder
- * that bridges the iframe's hooks (useQuery, useMutate, useAction,
- * useWorkflow) to api.lotics.ai using the CLI's stored API key. Wrapper
+ * that bridges the iframe's hooks (useQuery, useWorkflow) to api.lotics.ai
+ * using the CLI's stored API key. Wrapper
  * iframe matches the production sandbox attributes exactly — null origin,
  * allow-scripts — so prod-equivalent runtime behavior surfaces in dev.
  *
@@ -323,7 +331,7 @@ export async function appDev(client, args) {
     // 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);
+    writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries });
     // 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.js

@@ -56,6 +56,7 @@ describe("stampPulledManifest", () => {
                 agent_authored: { workflow_id: "wfl_authored_by_agent" },
                 renamed: { workflow_id: "wfl_renamed_on_server" },
             },
+            queries: {},
         });
         const stamped = readStampedManifest();
         expect(stamped.app_id).toBe("app_live");
@@ -80,6 +81,7 @@ describe("stampPulledManifest", () => {
             current_version_id: "apv_x",
             version_number: 2,
             workflows: {},
+            queries: {},
         });
         const stamped = readStampedManifest();
         expect(stamped.workflows).toEqual({});
@@ -94,6 +96,7 @@ describe("stampPulledManifest", () => {
             workflows: {
                 only_live: { workflow_id: "wfl_only_live" },
             },
+            queries: {},
         });
         const dtsPath = path.join(workDir, ".lotics", "app_workflows.d.ts");
         expect(fs.existsSync(dtsPath)).toBe(true);

package/dist/src/client.d.ts

@@ -86,6 +86,14 @@ export declare class LoticsClient {
             workflow_id: string;
             inputs?: Record<string, unknown>;
         }> | null;
+        /**
+         * Live alias → query declaration map from `apps.queries`. Source of truth
+         * for `lotics app pull`. Null/undefined on apps with no declared queries.
+         */
+        queries?: Record<string, {
+            ast: unknown;
+            params?: Record<string, unknown>;
+        }> | null;
     }>;
     createApp(body: {
         name: string;
@@ -107,22 +115,15 @@ export declare class LoticsClient {
     }>;
     getAppVersionSourceUrl(app_id: string, version_id: string): Promise<string>;
     /**
-     * Run a query AST scoped to an app's IAM principal.
-     * Mirrors POST /v1/apps/{app_id}/query.
+     * Run a named query declared in the app's manifest, scoped to the app's IAM
+     * principal. Mirrors POST /v1/apps/{app_id}/query.
      */
-    appQuery(app_id: string, ast: unknown): Promise<{
+    appQuery(app_id: string, body: {
+        alias: string;
+        params?: Record<string, unknown>;
+    }): Promise<{
         rows: unknown[];
     }>;
-    /**
-     * Update records in a workspace table scoped to an app's IAM principal.
-     * Mirrors PATCH /v1/apps/{app_id}/tables/{table_id}/records.
-     */
-    appMutate(app_id: string, table_id: string, records: unknown): Promise<unknown>;
-    /**
-     * Execute an app-declared action.
-     * Mirrors POST /v1/apps/{app_id}/actions/{action_id}.
-     */
-    appAction(app_id: string, action_id: string, inputs: unknown): Promise<unknown>;
     /**
      * Execute a workflow by alias declared in package.json#lotics.workflows.
      * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
@@ -147,6 +148,16 @@ export declare class LoticsClient {
             workflow_id: string;
             inputs?: Record<string, unknown>;
         }>;
+        /**
+         * Alias → query declaration map from `package.json#lotics.queries`. Each
+         * value is `{ ast, params? }` — a fixed query AST template and an optional
+         * typed param schema. Always sent (empty object when none declared) so the
+         * server overwrites apps.queries authoritatively.
+         */
+        queries?: Record<string, {
+            ast: unknown;
+            params?: Record<string, unknown>;
+        }>;
         /**
          * Opt into destructive workflow removal. When false/absent, the server
          * rejects a deploy whose `workflows` map is missing aliases that exist

package/dist/src/client.js

@@ -157,30 +157,16 @@ export class LoticsClient {
         return result.url;
     }
     // ── App iframe RPC endpoints ──────────────────────────────────────────────
-    // These mirror the four ops handled by frontend/features/app_ui/app_iframe_host.tsx.
+    // These mirror the two ops handled by frontend/features/app_ui/app_iframe_host.tsx.
     // The deployed iframe sends postMessage to the parent frontend, which calls
     // these same endpoints via the user's session cookie. `lotics app dev`
     // forwards the iframe's postMessage to these methods using the CLI's API key.
     /**
-     * Run a query AST scoped to an app's IAM principal.
-     * Mirrors POST /v1/apps/{app_id}/query.
+     * Run a named query declared in the app's manifest, scoped to the app's IAM
+     * principal. Mirrors POST /v1/apps/{app_id}/query.
      */
-    async appQuery(app_id, ast) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/query`, { ast });
-    }
-    /**
-     * Update records in a workspace table scoped to an app's IAM principal.
-     * Mirrors PATCH /v1/apps/{app_id}/tables/{table_id}/records.
-     */
-    async appMutate(app_id, table_id, records) {
-        return this.request("PATCH", `/v1/apps/${encodeURIComponent(app_id)}/tables/${encodeURIComponent(table_id)}/records`, { records });
-    }
-    /**
-     * Execute an app-declared action.
-     * Mirrors POST /v1/apps/{app_id}/actions/{action_id}.
-     */
-    async appAction(app_id, action_id, inputs) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/actions/${encodeURIComponent(action_id)}`, { inputs });
+    async appQuery(app_id, body) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/query`, body);
     }
     /**
      * Execute a workflow by alias declared in package.json#lotics.workflows.
@@ -205,6 +191,9 @@ 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 ?? {}));
+        // Always send queries — empty object clears any previously-declared
+        // named queries. Server validates each template.
+        formData.append("queries", JSON.stringify(args.queries ?? {}));
         // 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.

package/dist/src/dev/rpc_handler.d.ts

@@ -6,7 +6,7 @@
  * { message }. Same shape as the production iframe-host's error path.
  */
 import { LoticsClient } from "../client.js";
-export type RpcOp = "query" | "mutate" | "action" | "workflow";
+export type RpcOp = "query" | "workflow";
 export interface RpcRequest {
     app_id: string;
     op: RpcOp;

package/dist/src/dev/rpc_handler.js

@@ -5,7 +5,7 @@
  * Errors are thrown — the HTTP server caller serializes them to a 500 with
  * { message }. Same shape as the production iframe-host's error path.
  */
-const SUPPORTED_OPS = new Set(["query", "mutate", "action", "workflow"]);
+const SUPPORTED_OPS = new Set(["query", "workflow"]);
 export async function dispatchRpc(client, body) {
     if (!body || typeof body.app_id !== "string" || typeof body.op !== "string") {
         throw new Error("RPC envelope must include app_id and op");
@@ -16,25 +16,10 @@ export async function dispatchRpc(client, body) {
     switch (body.op) {
         case "query": {
             const p = body.payload;
-            const ast = p?.ast;
-            if (ast === undefined) {
-                throw new Error("query payload must include `ast`");
-            }
-            return client.appQuery(body.app_id, ast);
-        }
-        case "mutate": {
-            const p = body.payload;
-            if (!p || typeof p.table_id !== "string") {
-                throw new Error("mutate payload must include `table_id`");
-            }
-            return client.appMutate(body.app_id, p.table_id, p.records);
-        }
-        case "action": {
-            const p = body.payload;
-            if (!p || typeof p.action_id !== "string") {
-                throw new Error("action payload must include `action_id`");
+            if (!p || typeof p.alias !== "string") {
+                throw new Error("query payload must include `alias`");
             }
-            return client.appAction(body.app_id, p.action_id, p.inputs);
+            return client.appQuery(body.app_id, { alias: p.alias, params: p.params });
         }
         case "workflow": {
             const p = body.payload;

package/dist/src/generate_app_queries_dts.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Codegen: emit `.lotics/app_queries.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 `AppQueries` for every alias declared in
+ * `package.json#lotics.queries`, mapping each to its declared param shape:
+ *
+ *   - `params` declared → `alias: { …declared shape… }`
+ *   - `params` omitted  → `alias: Record<string, never>` (no params)
+ *
+ * Result: `useQuery("alias", params)` is typed against the manifest, and an
+ * undeclared alias is a compile-time error.
+ *
+ * The typed-input → TS-type mappers are shared with the workflow codegen —
+ * both surfaces use the same `AppWorkflowInput` vocabulary.
+ *
+ * Pure function. Same inputs → same output. Idempotent.
+ */
+import type { AppQueryDeclaration } from "./app_commands.js";
+export declare function generateAppQueriesDts(queries: Record<string, AppQueryDeclaration> | undefined): string;

package/dist/src/generate_app_queries_dts.js

@@ -0,0 +1,57 @@
+/**
+ * Codegen: emit `.lotics/app_queries.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 `AppQueries` for every alias declared in
+ * `package.json#lotics.queries`, mapping each to its declared param shape:
+ *
+ *   - `params` declared → `alias: { …declared shape… }`
+ *   - `params` omitted  → `alias: Record<string, never>` (no params)
+ *
+ * Result: `useQuery("alias", params)` is typed against the manifest, and an
+ * undeclared alias is a compile-time error.
+ *
+ * The typed-input → TS-type mappers are shared with the workflow codegen —
+ * both surfaces use the same `AppWorkflowInput` vocabulary.
+ *
+ * Pure function. Same inputs → same output. Idempotent.
+ */
+import { inputsToType, isValidIdentifier } from "./generate_app_workflows_dts.js";
+const HEADER = `// Auto-generated by 'lotics app pull/dev/deploy'.
+// DO NOT EDIT — regenerated from package.json#lotics.queries.
+//
+// This file gives \`useQuery("alias", params)\` typed params at call sites by
+// augmenting the @lotics/app-sdk \`AppQueries\` interface.
+
+import "@lotics/app-sdk";
+`;
+export function generateAppQueriesDts(queries) {
+    const entries = Object.entries(queries ?? {});
+    if (entries.length === 0) {
+        return `${HEADER}
+// No queries declared in package.json#lotics.queries.
+// Add an entry to enable typed useQuery("alias", params) at call sites.
+declare module "@lotics/app-sdk" {
+  interface AppQueries {}
+}
+`;
+    }
+    // Sort alphabetically for deterministic output across regenerations.
+    entries.sort(([a], [b]) => a.localeCompare(b));
+    const lines = [];
+    for (const [alias, declaration] of entries) {
+        // `inputsToType` returns `Record<string, never>` for an empty/absent
+        // param schema — exactly the no-params placeholder `useQuery` expects.
+        const valueType = inputsToType(declaration.params ?? {});
+        const aliasKey = isValidIdentifier(alias) ? alias : JSON.stringify(alias);
+        lines.push(`    ${aliasKey}: ${valueType};`);
+    }
+    return `${HEADER}
+declare module "@lotics/app-sdk" {
+  interface AppQueries {
+${lines.join("\n")}
+  }
+}
+`;
+}

package/dist/src/generate_app_workflows_dts.d.ts

@@ -15,3 +15,16 @@
  */
 import type { AppWorkflowDeclaration } from "./app_commands.js";
 export declare function generateAppWorkflowsDts(workflows: Record<string, AppWorkflowDeclaration> | undefined): string;
+/**
+ * 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.
+ */
+export declare function inputsToType(inputs: Record<string, unknown>): string;
+export declare function isValidIdentifier(name: string): boolean;

package/dist/src/generate_app_workflows_dts.js

@@ -64,7 +64,7 @@ ${lines.join("\n")}
  * to `unknown` rather than throwing — the server's deploy-time schema parse
  * catches structurally-invalid declarations before they reach us.
  */
-function inputsToType(inputs) {
+export function inputsToType(inputs) {
     const fields = [];
     for (const [key, decl] of Object.entries(inputs)) {
         if (decl === null || typeof decl !== "object")
@@ -118,6 +118,6 @@ function inputDeclToTsType(decl) {
     }
 }
 const IDENTIFIER_REGEX = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
-function isValidIdentifier(name) {
+export function isValidIdentifier(name) {
     return IDENTIFIER_REGEX.test(name);
 }

package/dist/src/starter_template.js

@@ -47,7 +47,7 @@ export function buildStarterTemplate(args) {
                     test: "vitest run",
                 },
                 dependencies: {
-                    "@lotics/app-sdk": "^0.2.0",
+                    "@lotics/app-sdk": "^0.5.0",
                     "@lotics/ui": "^0.2.0",
                     "@react-native-picker/picker": "^2.7.0",
                     "expo-image": "~3.0.9",
@@ -239,7 +239,7 @@ export default function App() {
           </View>
         </Card>
         <Text color="muted" size="sm">
-          Hooks from @lotics/app-sdk: useTable, useMutate, useAction, useQuery, useWorkflow.
+          Hooks from @lotics/app-sdk: useQuery, useWorkflow.
         </Text>
         <Button title="Get started" onPress={() => {}} color="primary" />
       </View>
@@ -400,7 +400,7 @@ lotics app deploy -m "what"    # with a commit-message-style note
 ## SDK + UI components
 
 \`\`\`tsx
-import { mount, useTable, useMutate, useAction, useQuery, useWorkflow } from "@lotics/app-sdk";
+import { mount, useQuery, useWorkflow } from "@lotics/app-sdk";
 import { Stack } from "@lotics/ui/stack";
 import { Card } from "@lotics/ui/card";
 import { Button } from "@lotics/ui/button";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {