@lotics/cli 0.24.1 → 0.27.0

package/README.md

@@ -46,9 +46,23 @@ lotics auth api-key                  # interactive prompt
 lotics auth api-key ltk_...          # non-interactive
 ```
 
-API key is saved to `~/.lotics/config.json`. Run `lotics auth logout` to remove saved credentials.
+API key is saved to the config file. Run `lotics auth logout` to remove saved credentials.
 
-Auth priority: `--api-key` flag > `LOTICS_API_KEY` env > `~/.lotics/config.json`.
+Auth priority: `--api-key` flag > `LOTICS_API_KEY` env > config file.
+
+### Config file location
+
+The CLI resolves `.lotics/config.json` by walking up from the current working directory — the first ancestor that has one wins, otherwise the global `~/.lotics/config.json`. A per-directory config lets a project or worktree pin its own account and workspace; commands run from a subdirectory still resolve to it.
+
+Create one by passing `--local` to `lotics auth`:
+
+```bash
+cd my-worktree
+lotics auth api-key ltk_... --local      # writes ./.lotics/config.json
+lotics workspace select wks_...          # auto-resolves to the local config
+```
+
+`.lotics/` should be gitignored. Note: an exported `LOTICS_API_KEY` overrides the config file's key.
 
 ## Workspaces
 

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/cli.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline";
 import { LoticsClient, API_BASE_URL } from "./client.js";
-import { resolveAuth, loadConfig, saveConfig, deleteConfig, checkForUpdate } from "./config.js";
+import { resolveAuth, loadConfig, saveConfig, deleteConfig, getConfigPath, checkForUpdate } from "./config.js";
 import { VERSION } from "./version.js";
 import { appCreate, appPull, appDeploy, appDev } from "./app_commands.js";
 function printHelp() {
@@ -58,8 +58,15 @@ FLAGS
   -o <path>          Output dir for downloads
   --as <name>        Override upload filename
   --api-key <key>    API key (overrides saved config and LOTICS_API_KEY)
+  --local            (lotics auth) Save credentials to ./.lotics/config.json
   --version          Show version
 
+CONFIG
+  Credentials resolve from a .lotics/config.json found by walking up from the
+  current directory, else the global ~/.lotics/config.json. Run "lotics auth
+  api-key <key> --local" inside a directory (e.g. a worktree) to pin it to its
+  own account and workspace.
+
 OUTPUT
   Default output is a compact text summary optimized for AI agents —
   use it directly, no parsing needed. --json returns raw structured
@@ -92,13 +99,20 @@ function printAuthHelp() {
   lotics auth whoami                   Show the current account's name, email, and organization
   lotics auth logout                   Remove saved credentials
 
-Signup flags:
-  --name <name>          Display name (defaults to email prefix)
-  --timezone <timezone>  Workspace timezone (defaults to UTC, e.g. Asia/Ho_Chi_Minh)
+Auth flags:
+  --local                Save credentials to ./.lotics/config.json (this directory)
+                         instead of the global ~/.lotics — applies to signup + api-key
+  --name <name>          (signup) Display name (defaults to email prefix)
+  --timezone <timezone>  (signup) Workspace timezone (defaults to UTC, e.g. Asia/Ho_Chi_Minh)
 
 Signup sends a magic link email so you can access the Lotics web app.
 Use lotics auth web to request a new magic link at any time.
-Auth priority: --api-key flag > LOTICS_API_KEY env > saved config.`);
+
+Auth priority: --api-key flag > LOTICS_API_KEY env > config file.
+Config file: .lotics/config.json found by walking up from the current directory,
+else ~/.lotics/config.json. A per-directory config pins a project or worktree to
+its own account and workspace; --local creates one. Note: an exported
+LOTICS_API_KEY env var overrides the config file's key.`);
 }
 function parseArgs(argv) {
     const flags = {
@@ -109,6 +123,7 @@ function parseArgs(argv) {
         apiKey: undefined,
         name: undefined,
         timezone: undefined,
+        local: false,
         version: false,
         help: false,
     };
@@ -142,6 +157,9 @@ function parseArgs(argv) {
             case "--timezone":
                 flags.timezone = argv[++i];
                 break;
+            case "--local":
+                flags.local = true;
+                break;
             case "--version":
             case "-v":
                 flags.version = true;
@@ -223,19 +241,21 @@ async function handleSignup(positionalEmail, flags) {
         }
         process.exit(1);
     }
-    const existing = loadConfig() ?? {};
+    const scope = flags.local ? "local" : "auto";
+    const existing = loadConfig(scope) ?? {};
     saveConfig({
         ...existing,
         api_key: data.api_key,
         email: data.email,
         workspace_id: data.workspace_id,
-    });
+    }, scope);
     console.error(`Account created. You can now use the CLI.`);
-    console.error(`  Email: ${data.email}`);
+    console.error(`  Email:  ${data.email}`);
+    console.error(`  Config: ${getConfigPath(scope)}`);
     console.error(`\nCheck your email for a magic link to access the Lotics web app.`);
     console.error(`Run "lotics auth web" to request a new link at any time.`);
 }
-async function handleSetup(providedKey) {
+async function handleSetup(providedKey, local) {
     const apiKey = providedKey ?? await prompt("Enter your API key: ");
     if (!apiKey) {
         console.error("No API key provided.");
@@ -252,7 +272,8 @@ async function handleSetup(providedKey) {
         console.error(`Authentication failed: ${message}`);
         process.exit(1);
     }
-    const existing = loadConfig() ?? {};
+    const scope = local ? "local" : "auto";
+    const existing = loadConfig(scope) ?? {};
     const newConfig = { ...existing, api_key: apiKey, email };
     // Auto-resolve workspace
     try {
@@ -269,8 +290,9 @@ async function handleSetup(providedKey) {
         const msg = error instanceof Error ? error.message : String(error);
         console.error(`Warning: could not resolve workspace: ${msg}`);
     }
-    saveConfig(newConfig);
+    saveConfig(newConfig, scope);
     console.error("Authenticated.");
+    console.error(`  Config: ${getConfigPath(scope)}`);
 }
 function requireClient(flags) {
     const auth = resolveAuth(flags);
@@ -356,7 +378,7 @@ async function main() {
             return;
         }
         if (subcommand === "api-key") {
-            await handleSetup(toolArgs ?? flags.apiKey);
+            await handleSetup(toolArgs ?? flags.apiKey, flags.local);
             return;
         }
         if (subcommand === "whoami") {
@@ -377,6 +399,7 @@ async function main() {
                 console.log(`Email:   ${info.email}`);
                 console.log(`Org:     ${info.organization_name} (${info.organization_id})`);
             }
+            console.error(`Config:  ${getConfigPath()}`);
             return;
         }
         if (subcommand === "logout") {
@@ -495,6 +518,7 @@ async function main() {
                 }
             }
         }
+        console.error(`Config: ${getConfigPath()}`);
         return;
     }
     // Ensure workspace is resolved for all remaining commands

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/config.d.ts

@@ -5,10 +5,22 @@ export interface LoticsConfig {
     last_update_check?: number;
     latest_version?: string;
 }
-export declare function loadConfig(): LoticsConfig | null;
-export declare function saveConfig(config: LoticsConfig): void;
-export declare function deleteConfig(): void;
-export declare function getConfigPath(): string;
+/**
+ * Where a config operation reads from or writes to.
+ *
+ * - `"auto"` — walk up from the current working directory; the first ancestor
+ *   containing `.lotics/config.json` wins, else the global `~/.lotics`. This
+ *   lets a project or worktree pin its own account and workspace, and keeps
+ *   resolution stable when commands run from a subdirectory.
+ * - `"local"` — `.lotics/config.json` directly under the current working
+ *   directory. Used to bootstrap a per-directory config (`lotics auth --local`)
+ *   before any local file exists for `"auto"` to discover.
+ */
+export type ConfigScope = "auto" | "local";
+export declare function loadConfig(scope?: ConfigScope): LoticsConfig | null;
+export declare function saveConfig(config: LoticsConfig, scope?: ConfigScope): void;
+export declare function deleteConfig(scope?: ConfigScope): void;
+export declare function getConfigPath(scope?: ConfigScope): string;
 /**
  * Check for a newer CLI version. Synchronous — prints a warning to stderr
  * if the cached latest version is newer than current. Kicks off a background

package/dist/src/config.js

@@ -1,31 +1,59 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-const CONFIG_DIR = path.join(os.homedir(), ".lotics");
-const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
-export function loadConfig() {
+/**
+ * Resolve the config file for a scope.
+ *
+ * Resolution keys on the `config.json` *file*, never the `.lotics` directory:
+ * scaffolded custom-code apps already use `.lotics/` for generated types, so
+ * directory presence cannot signal a local config.
+ */
+function configFileForScope(scope) {
+    if (scope === "local") {
+        return path.join(process.cwd(), ".lotics", "config.json");
+    }
+    let dir = process.cwd();
+    for (;;) {
+        const candidate = path.join(dir, ".lotics", "config.json");
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return path.join(os.homedir(), ".lotics", "config.json");
+}
+export function loadConfig(scope = "auto") {
     try {
-        const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+        const raw = fs.readFileSync(configFileForScope(scope), "utf-8");
         return JSON.parse(raw);
     }
     catch {
         return null;
     }
 }
-export function saveConfig(config) {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true });
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", "utf-8");
+export function saveConfig(config, scope = "auto") {
+    const file = configFileForScope(scope);
+    // The config file holds an API key — keep it owner-only. `mode` on
+    // writeFileSync applies only when the file is created, so chmod after to
+    // also tighten a config written before this protection existed.
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
+    fs.chmodSync(file, 0o600);
 }
-export function deleteConfig() {
+export function deleteConfig(scope = "auto") {
     try {
-        fs.unlinkSync(CONFIG_FILE);
+        fs.unlinkSync(configFileForScope(scope));
     }
     catch {
         // Already deleted or never existed
     }
 }
-export function getConfigPath() {
-    return CONFIG_FILE;
+export function getConfigPath(scope = "auto") {
+    return configFileForScope(scope);
 }
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
 /**

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

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

package/dist/src/config.test.js

@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { loadConfig, saveConfig, deleteConfig, getConfigPath } from "./config.js";
+/**
+ * Config resolution walks up from the current working directory: the first
+ * ancestor with a `.lotics/config.json` wins, otherwise the global
+ * `~/.lotics/config.json`. This lets a project or worktree pin its own
+ * account/workspace and keeps resolution stable when commands run from a
+ * subdirectory. Scope `"local"` targets the current directory exactly — used
+ * to bootstrap a per-directory config before any local file exists.
+ *
+ * These tests pin both `os.homedir()` and `process.cwd()` to temp dirs so the
+ * real home directory is never touched.
+ */
+describe("config file resolution", () => {
+    let homeDir;
+    let projectDir;
+    let originalCwd;
+    beforeEach(() => {
+        originalCwd = process.cwd();
+        homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "lotics-home-"));
+        projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "lotics-project-"));
+        vi.spyOn(os, "homedir").mockReturnValue(homeDir);
+        process.chdir(projectDir);
+    });
+    afterEach(() => {
+        process.chdir(originalCwd);
+        vi.restoreAllMocks();
+        fs.rmSync(homeDir, { recursive: true, force: true });
+        fs.rmSync(projectDir, { recursive: true, force: true });
+    });
+    const globalFile = () => path.join(homeDir, ".lotics", "config.json");
+    const localFile = (dir = projectDir) => path.join(dir, ".lotics", "config.json");
+    function write(file, data) {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(data));
+    }
+    function read(file) {
+        return JSON.parse(fs.readFileSync(file, "utf-8"));
+    }
+    function chdirInto(...segments) {
+        const dir = path.join(projectDir, ...segments);
+        fs.mkdirSync(dir, { recursive: true });
+        process.chdir(dir);
+        return dir;
+    }
+    it("returns null when no config exists anywhere", () => {
+        expect(loadConfig()).toBeNull();
+    });
+    it("reads the global config when no local config exists", () => {
+        write(globalFile(), { api_key: "ltk_global" });
+        expect(loadConfig()?.api_key).toBe("ltk_global");
+        expect(getConfigPath()).toBe(globalFile());
+    });
+    it("prefers a .lotics/config.json in the current directory over the global one", () => {
+        write(globalFile(), { api_key: "ltk_global" });
+        write(localFile(), { api_key: "ltk_local" });
+        expect(loadConfig()?.api_key).toBe("ltk_local");
+        expect(getConfigPath()).toBe(localFile());
+    });
+    it("walks up to an ancestor's config when run from a subdirectory", () => {
+        write(localFile(), { api_key: "ltk_project_root" });
+        chdirInto("backend", "features");
+        expect(loadConfig()?.api_key).toBe("ltk_project_root");
+        expect(getConfigPath()).toBe(localFile());
+    });
+    it("auto saveConfig writes the resolved ancestor file, not the subdirectory", () => {
+        write(localFile(), { api_key: "ltk_old" });
+        const nested = chdirInto("sub");
+        saveConfig({ api_key: "ltk_new" });
+        expect(read(localFile()).api_key).toBe("ltk_new");
+        expect(fs.existsSync(localFile(nested))).toBe(false);
+    });
+    it("auto saveConfig writes the global config when no local config exists", () => {
+        saveConfig({ api_key: "ltk_new" });
+        expect(fs.existsSync(localFile())).toBe(false);
+        expect(read(globalFile()).api_key).toBe("ltk_new");
+    });
+    it("scope 'local' creates ./.lotics/config.json even when none existed", () => {
+        saveConfig({ api_key: "ltk_pinned" }, "local");
+        expect(read(localFile()).api_key).toBe("ltk_pinned");
+        expect(getConfigPath("local")).toBe(localFile());
+    });
+    it("saveConfig writes the credentials file owner-only (0600)", () => {
+        saveConfig({ api_key: "ltk_secret" }, "local");
+        expect(fs.statSync(localFile()).mode & 0o777).toBe(0o600);
+    });
+    it("saveConfig tightens an over-permissive pre-existing config file", () => {
+        write(localFile(), { api_key: "ltk_old" });
+        fs.chmodSync(localFile(), 0o644);
+        saveConfig({ api_key: "ltk_new" }, "local");
+        expect(fs.statSync(localFile()).mode & 0o777).toBe(0o600);
+    });
+    it("loadConfig('local') never inherits the global config", () => {
+        write(globalFile(), { api_key: "ltk_global" });
+        expect(loadConfig("local")).toBeNull();
+    });
+    it("loadConfig('local') ignores an ancestor's config — it reads the exact cwd only", () => {
+        write(localFile(), { api_key: "ltk_root" });
+        chdirInto("sub");
+        expect(loadConfig("local")).toBeNull();
+    });
+    it("deleteConfig removes the active local config, leaving the global one untouched", () => {
+        write(globalFile(), { api_key: "ltk_global" });
+        write(localFile(), { api_key: "ltk_local" });
+        deleteConfig();
+        expect(fs.existsSync(localFile())).toBe(false);
+        expect(fs.existsSync(globalFile())).toBe(true);
+    });
+});

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.24.1",
+  "version": "0.27.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {