@lotics/cli 0.65.0 → 0.67.0

package/README.md

@@ -181,8 +181,14 @@ lotics app workflow pull                    # rewrite src/workflows/*.ts + globa
 lotics app workflow check                   # typecheck every body locally ([alias] for one)
 lotics app workflow set issueInvoice        # push the edited src/workflows/issueInvoice.ts
 
-# Dev-link @lotics/ui to the monorepo's packages/ui/src for live HMR (monorepo only)
-lotics ui link card                        # edits to packages/ui/src go live
+# Iterate on a named query WITHOUT a deploy: push package.json#lotics.queries.<alias>
+# to apps.queries (server-validated like a deploy). apps.queries is manifest-
+# authoritative, so the next `app deploy` re-syncs it — keep the manifest current.
+lotics app query set openInvoices           # push package.json#lotics.queries.openInvoices
+
+# Dev-link @lotics/ui to packages/ui/src for live HMR (Vite alias; deploy bundles it)
+lotics ui link card                        # monorepo: packages/ui/src found automatically
+lotics ui link card --ui-src /abs/monorepo/packages/ui/src   # external app (e.g. ~/lotics_apps)
 lotics ui link card --remove               # finalize: PR + publish, then drop the alias
 ```
 

package/dist/app_commands.d.ts

@@ -303,6 +303,23 @@ export declare function appExecuteWorkflow(client: LoticsClient, args: {
 export declare function appWorkflowSet(client: LoticsClient, args: {
     alias: string;
 }): Promise<void>;
+/**
+ * `lotics app query set <alias>` — push `package.json#lotics.queries.<alias>` to
+ * `apps.queries` through `set_app_query`, WITHOUT a deploy. The deploy-free inner
+ * loop for named queries, parallel to `lotics app workflow set` for workflows.
+ *
+ * The declaration (`{ ast, params? }`) is read from the manifest — the same map
+ * `useQuery` codegen reads and `lotics app deploy` syncs authoritatively. The
+ * server validates it exactly as a deploy does (alias identifier, workspace-only
+ * tables, resolvable fields, declared params). Because `apps.queries` is
+ * manifest-authoritative, the next `lotics app deploy` overwrites this from the
+ * manifest — so keep the manifest as the source of truth; this only skips the
+ * build/upload round-trip while iterating. Errors (unbound alias, validation
+ * failure) print to stderr and exit non-zero.
+ */
+export declare function appQuerySet(client: LoticsClient, args: {
+    alias: string;
+}): Promise<void>;
 /**
  * `lotics app workflow pull` — rewrite every `src/workflows/<alias>.ts` from the
  * server without a full `lotics app pull` (no source archive, no npm install).
@@ -346,4 +363,5 @@ export declare function appUiLink(args: {
     projectDir?: string;
     component: string;
     remove?: boolean;
+    uiSrc?: string;
 }): void;

package/dist/app_commands.js

@@ -896,9 +896,13 @@ args) {
                 // `capabilities` block turns every capability OFF on the next deploy
                 // (fail-safe; the declaration is the grant).
                 capabilities: meta.capabilities ?? {},
-                // Workflow bindings are NOT a deploy concern — set_app_workflow /
-                // remove_app_workflow own apps.workflows. The manifest's `workflows`
-                // map is a pulled reflection used only for the .d.ts codegen above.
+                // Workflow BINDINGS are NOT a deploy concern — set_app_workflow /
+                // remove_app_workflow own apps.workflows. But the alias KEYS of the
+                // manifest's `workflows` map ARE sent (never the bindings): they record
+                // which aliases this bundle declares, so remove_app_workflow can refuse
+                // to unbind an alias the served version still calls. Drop an alias from
+                // the manifest + redeploy to lift that guard before removing its binding.
+                workflow_aliases: Object.keys(meta.workflows ?? {}),
             });
             writeAppMeta(projectDir, {
                 ...meta,
@@ -907,7 +911,16 @@ args) {
             });
             console.error(`Deployed v${result.version_number} (${result.version_id})`);
             console.error(`Bundle size: ${(result.bundle_size_bytes / 1024).toFixed(1)} KB`);
-            await warnIfUnbranded(client, meta.app_id);
+            // One post-deploy getApp feeds both advisory nudges (branding, unbound
+            // aliases). Deploy already succeeded — a failed check must not mask that.
+            try {
+                const app = await client.getApp(meta.app_id);
+                warnIfUnbranded(app);
+                warnIfUnboundAliases(app, meta.workflows ?? {}, meta.agents ?? {});
+            }
+            catch (err) {
+                console.error(`(skipped post-deploy checks: ${err.message})`);
+            }
         }
         catch (err) {
             const e = err;
@@ -931,24 +944,44 @@ args) {
  * generic tile in the launcher. Branding is set via `update_app` (the single
  * setter) — this only reminds; it never fails the deploy.
  */
-async function warnIfUnbranded(client, appId) {
-    try {
-        const app = await client.getApp(appId);
-        const missing = [];
-        if (!app.icon)
-            missing.push("icon");
-        if (!app.theme?.color)
-            missing.push("color");
-        if (missing.length === 0)
-            return;
-        console.error(`\n⚠ This app has no ${missing.join(" or ")} set — it shows a generic tile in the launcher.\n` +
-            `  Set it:  lotics run update_app '{"app_id":"${appId}","icon":"<lucide-name>","theme":{"color":"blue"}}'\n` +
-            `  Find an icon:  lotics run search_app_icons '{"query":"<word>"}'`);
-    }
-    catch (err) {
-        // Deploy already succeeded; a failed branding check must not mask that.
-        console.error(`(skipped branding check: ${err.message})`);
-    }
+function warnIfUnbranded(app) {
+    const missing = [];
+    if (!app.icon)
+        missing.push("icon");
+    if (!app.theme?.color)
+        missing.push("color");
+    if (missing.length === 0)
+        return;
+    console.error(`\n⚠ This app has no ${missing.join(" or ")} set — it shows a generic tile in the launcher.\n` +
+        `  Set it:  lotics run update_app '{"app_id":"${app.id}","icon":"<lucide-name>","theme":{"color":"blue"}}'\n` +
+        `  Find an icon:  lotics run search_app_icons '{"query":"<word>"}'`);
+}
+/**
+ * Non-blocking nudge after a successful deploy: catch manifest workflow/agent aliases
+ * that are NOT bound on the server. Deploy ships code + queries only — it never binds
+ * workflows/agents (`set_app_workflow` / `set_app_agent` own `apps.workflows`/`apps.agents`;
+ * the manifest maps are a pulled reflection). So an alias hand-added to `lotics.workflows`
+ * / `lotics.agents` (or bound then removed) compiles + deploys clean and only throws when
+ * the app first calls `useWorkflow` / `useAgentRun`. Surface that divergence HERE — at
+ * deploy time — instead of at the user's first click. Advisory only; never fails the deploy.
+ */
+function warnIfUnboundAliases(app, declaredWorkflows, declaredAgents) {
+    const boundWorkflows = new Set(Object.keys(app.workflows ?? {}));
+    const boundAgents = new Set(Object.keys(app.agents ?? {}));
+    const unboundWorkflows = Object.keys(declaredWorkflows).filter((a) => !boundWorkflows.has(a));
+    const unboundAgents = Object.keys(declaredAgents).filter((a) => !boundAgents.has(a));
+    if (unboundWorkflows.length === 0 && unboundAgents.length === 0)
+        return;
+    const lines = [
+        "\n⚠ The manifest declares aliases that are NOT bound on the server. Deploy ships code +",
+        "  queries only — it does NOT bind workflows/agents, so the app will throw \"has no … alias\"",
+        "  the first time it calls them. Bind each one:",
+    ];
+    for (const alias of unboundWorkflows)
+        lines.push(`  • workflow "${alias}"  →  lotics app workflow set ${alias}`);
+    for (const alias of unboundAgents)
+        lines.push(`  • agent "${alias}"  →  bind with set_app_agent (lotics run set_app_agent …)`);
+    console.error(lines.join("\n"));
 }
 /**
  * `lotics app dev [path] [--port=5174] [--vite-port=5173]`
@@ -1198,6 +1231,37 @@ export async function appWorkflowSet(client, args) {
         console.error(`  result.data schema: ${JSON.stringify(result.outputs)}`);
     }
 }
+/**
+ * `lotics app query set <alias>` — push `package.json#lotics.queries.<alias>` to
+ * `apps.queries` through `set_app_query`, WITHOUT a deploy. The deploy-free inner
+ * loop for named queries, parallel to `lotics app workflow set` for workflows.
+ *
+ * The declaration (`{ ast, params? }`) is read from the manifest — the same map
+ * `useQuery` codegen reads and `lotics app deploy` syncs authoritatively. The
+ * server validates it exactly as a deploy does (alias identifier, workspace-only
+ * tables, resolvable fields, declared params). Because `apps.queries` is
+ * manifest-authoritative, the next `lotics app deploy` overwrites this from the
+ * manifest — so keep the manifest as the source of truth; this only skips the
+ * build/upload round-trip while iterating. Errors (unbound alias, validation
+ * failure) print to stderr and exit non-zero.
+ */
+export async function appQuerySet(client, args) {
+    const projectDir = process.cwd();
+    const meta = readAppMeta(projectDir);
+    const declaration = meta.queries?.[args.alias];
+    if (!declaration) {
+        console.error(`No query "${args.alias}" in package.json#lotics.queries. ` +
+            `Declare it there (alias → { ast, params? }) first.`);
+        process.exit(1);
+    }
+    const res = await client.setAppQuery(meta.app_id, args.alias, declaration);
+    if (res.error) {
+        console.error(`Failed to set query "${args.alias}": ${res.error}`);
+        process.exit(1);
+    }
+    console.error(`Set query "${args.alias}" on ${meta.app_id}. ` +
+        `(apps.queries is manifest-authoritative — the next 'lotics app deploy' re-syncs it.)`);
+}
 /**
  * `lotics app workflow pull` — rewrite every `src/workflows/<alias>.ts` from the
  * server without a full `lotics app pull` (no source archive, no npm install).
@@ -1358,11 +1422,18 @@ export function appUiLink(args) {
     if (!fs.existsSync(viteConfigPath)) {
         throw new Error(`No vite.config.ts at ${projectDir}. Run inside a 'lotics app' project directory.`);
     }
-    const uiSrc = findUiSrcDir(projectDir);
-    if (!uiSrc) {
-        throw new Error("Cannot find packages/ui/src by walking up from this directory — `lotics ui link` " +
-            "requires a monorepo checkout. External apps consume @lotics/ui from npm; bump the " +
-            "package version and widen the app's dependency range instead.");
+    // Resolve packages/ui/src. An explicit --ui-src / LOTICS_UI_SRC wins — that's how
+    // an EXTERNAL app (one that consumes @lotics/ui from npm, with no monorepo above
+    // it) links the local kit; otherwise walk up for a monorepo checkout.
+    const explicit = args.uiSrc ?? process.env.LOTICS_UI_SRC;
+    const uiSrc = explicit ? path.resolve(explicit) : findUiSrcDir(projectDir);
+    if (!uiSrc || !fs.existsSync(uiSrc) || !fs.statSync(uiSrc).isDirectory()) {
+        throw new Error(explicit
+            ? `--ui-src / LOTICS_UI_SRC points at '${explicit}', which is not a directory. ` +
+                `Pass the absolute path to the monorepo's packages/ui/src.`
+            : "Cannot find packages/ui/src by walking up from this directory. For an EXTERNAL app " +
+                "(consuming @lotics/ui from npm), pass --ui-src=<abs path to packages/ui/src> or set " +
+                "LOTICS_UI_SRC; inside a monorepo checkout it is found automatically.");
     }
     // Validate the named component exists in src so a typo fails loud (the alias
     // itself stays package-wide — this is the advisory check the spec calls for).
@@ -1403,6 +1474,10 @@ export function appUiLink(args) {
     fs.writeFileSync(viteConfigPath, updated);
     console.error(`Dev-linked @lotics/ui → ${uiSrc} in ${viteConfigPath}.`);
     console.error("Restart `lotics app dev` and rm -rf node_modules/.vite to clear cached modules.");
+    // The app's tsc still resolves @lotics/ui from node_modules (the published .d.ts) —
+    // the kit `src` can't be typechecked in an app because it's RN-Web (uses
+    // react-native-web types the app resolves as base react-native). Typecheck the kit
+    // in packages/ui; the finalize publish restores the app's own typecheck.
     console.error("Finalize: PR the packages/ui change → publish → `lotics ui link <component> --remove` + bump the app's dep.");
 }
 /** Escape a string for literal use inside a RegExp. */

package/dist/app_commands.test.js

@@ -208,8 +208,9 @@ describe("appCodegen (.d.ts-only path)", () => {
 });
 /**
  * `appUiLink` edits the app's vite.config.ts resolve.alias to dev-link
- * @lotics/ui at the monorepo's packages/ui/src. It fails loud outside a
- * monorepo, validates the component exists, and insert/remove is idempotent.
+ * @lotics/ui at packages/ui/src — auto-found in a monorepo checkout, or given
+ * explicitly via --ui-src for an external app. It validates the src + component,
+ * fails loud when neither resolves, and insert/remove is idempotent.
  */
 describe("appUiLink", () => {
     let root;
@@ -264,16 +265,30 @@ describe("appUiLink", () => {
     it("fails loud when the named component does not exist in packages/ui/src", () => {
         expect(() => appUiLink({ projectDir: appDir, component: "nonexistent" })).toThrow(/nonexistent/);
     });
-    it("fails loud when there is no monorepo packages/ui/src above the project", () => {
+    it("fails loud when there is no packages/ui/src and no --ui-src override", () => {
         const lonely = fs.mkdtempSync(path.join(tmpdir(), "lotics-lonely-app-"));
         fs.writeFileSync(path.join(lonely, "vite.config.ts"), "export default { resolve: { alias: [] } };");
         try {
-            expect(() => appUiLink({ projectDir: lonely, component: "card" })).toThrow(/monorepo checkout/);
+            expect(() => appUiLink({ projectDir: lonely, component: "card" })).toThrow(/--ui-src/);
         }
         finally {
             fs.rmSync(lonely, { recursive: true, force: true });
         }
     });
+    it("links an EXTERNAL app (no monorepo above) via an explicit --ui-src", () => {
+        const ext = fs.mkdtempSync(path.join(tmpdir(), "lotics-external-app-"));
+        fs.writeFileSync(path.join(ext, "vite.config.ts"), "export default { resolve: { alias: [] } };");
+        try {
+            appUiLink({ projectDir: ext, component: "card", uiSrc });
+            expect(fs.readFileSync(path.join(ext, "vite.config.ts"), "utf-8")).toContain(uiSrc);
+        }
+        finally {
+            fs.rmSync(ext, { recursive: true, force: true });
+        }
+    });
+    it("fails loud when --ui-src is not a directory", () => {
+        expect(() => appUiLink({ projectDir: appDir, component: "card", uiSrc: path.join(root, "nope") })).toThrow(/not a directory/);
+    });
 });
 /**
  * The workflow body files are how AA-1 Option B becomes "open a file → edit →

package/dist/args.d.ts

@@ -23,6 +23,8 @@ export declare function parseArgs(argv: string[]): {
         apiKey?: string;
         workspace?: string;
         viewAs?: string;
+        /** `--ui-src <path>`: absolute packages/ui/src for `ui link` in an external app. */
+        uiSrc?: string;
         name?: string;
         timezone?: string;
         message?: string;

package/dist/args.js

@@ -19,6 +19,7 @@ export function parseArgs(argv) {
         apiKey: undefined,
         workspace: undefined,
         viewAs: undefined,
+        uiSrc: undefined,
         name: undefined,
         timezone: undefined,
         message: undefined,
@@ -60,6 +61,9 @@ export function parseArgs(argv) {
             case "--view-as":
                 flags.viewAs = argv[++i];
                 break;
+            case "--ui-src":
+                flags.uiSrc = argv[++i];
+                break;
             case "--name":
                 flags.name = argv[++i];
                 break;

package/dist/cli.js

@@ -13,7 +13,7 @@ net.setDefaultAutoSelectFamilyAttemptTimeout(2000);
 import { LoticsClient, API_BASE_URL } from "./client.js";
 import { resolveContext, deleteConfig, getConfigPath, loadGlobalConfig, saveGlobalConfig, loadLocalConfig, upsertProfile, removeProfile, setActiveOrg, setSelectedWorkspace, resolveProfileByNameOrId, checkForUpdate, } from "./config.js";
 import { VERSION } from "./version.js";
-import { appCreate, appPull, appDeploy, appDev, appSetSubdomain, appRename, appVersions, appCodegen, appExecuteWorkflow, appWorkflowSet, appWorkflowPull, appWorkflowCheck, appUiLink, } from "./app_commands.js";
+import { appCreate, appPull, appDeploy, appDev, appSetSubdomain, appRename, appVersions, appCodegen, appExecuteWorkflow, appWorkflowSet, appWorkflowPull, appWorkflowCheck, appQuerySet, appUiLink, } from "./app_commands.js";
 import { parseArgs } from "./args.js";
 import { ingestJsonArgs } from "./inputs.js";
 import { runXlsxCommand } from "./xlsx.js";
@@ -90,11 +90,16 @@ COMMANDS
   lotics app workflow pull             Rewrite src/workflows/*.ts from the server
   lotics app workflow check [alias]    Typecheck src/workflows bodies locally (one
                                        isolated program per alias; the app's own tsc)
+  lotics app query set <alias>         Push package.json#lotics.queries.<alias> to
+                                       apps.queries via set_app_query (no deploy;
+                                       re-synced by the next deploy from the manifest)
   lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
   lotics app rename "<new name>"       Rename the app's display name (launcher title)
   lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
-  lotics ui link <component> [--remove] Dev-link @lotics/ui to the monorepo's
-                                       packages/ui/src for live HMR (monorepo only)
+  lotics ui link <component> [--ui-src <path>] [--remove]
+                                       Dev-link @lotics/ui to packages/ui/src (Vite alias
+                                       + tsc paths) for live HMR + typecheck. Monorepo apps
+                                       auto-find it; external apps pass --ui-src / LOTICS_UI_SRC
   lotics xlsx <subcommand> ...         Read/write/edit .xlsx files on your local filesystem
                                        (uses the bundled Lotics xlsx engine; prefer over
                                        npm xlsx/exceljs for round-trip fidelity)
@@ -493,17 +498,19 @@ async function main() {
         if (subcommand === "link") {
             const component = toolArgs;
             if (!component) {
-                console.error("Usage: lotics ui link <component> [--remove]");
-                console.error("Dev-links @lotics/ui to the monorepo's packages/ui/src for live HMR.");
+                console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
+                console.error("Dev-links @lotics/ui to packages/ui/src (Vite + tsc) for live HMR + typecheck.");
+                console.error("Monorepo apps find packages/ui/src automatically; external apps pass --ui-src / LOTICS_UI_SRC.");
                 process.exit(1);
             }
             // `--remove` isn't a value-taking flag, so the parser leaves it as a
-            // trailing positional (the component took `toolArgs`).
-            appUiLink({ component, remove: restArgs.includes("--remove") });
+            // trailing positional (the component took `toolArgs`); `--ui-src` IS a
+            // value flag (flags.uiSrc), falling back to LOTICS_UI_SRC inside appUiLink.
+            appUiLink({ component, uiSrc: flags.uiSrc, remove: restArgs.includes("--remove") });
             return;
         }
         console.error(`Unknown ui subcommand: ${subcommand ?? "(none)"}`);
-        console.error("Usage: lotics ui link <component> [--remove]");
+        console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
         process.exit(1);
     }
     // --- lotics app workflow check [alias] — local typecheck, no auth, no network ---
@@ -606,6 +613,7 @@ async function main() {
         console.error("  lotics app workflow set <alias>           Push the edited src/workflows/<alias>.ts body");
         console.error("  lotics app workflow pull                  Rewrite src/workflows/*.ts from the server");
         console.error("  lotics app workflow check [alias]         Typecheck src/workflows bodies locally");
+        console.error("  lotics app query set <alias>              Push lotics.queries.<alias> to apps.queries (no deploy)");
         console.error("  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address");
         console.error("  lotics app rename \"<new name>\"        Rename the app's display name (launcher title)");
         console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
@@ -826,6 +834,25 @@ async function main() {
             }
             workflowUsage();
         }
+        if (subcommand === "query") {
+            // `lotics app query set <alias>` — push package.json#lotics.queries.<alias>
+            // to apps.queries via set_app_query, no deploy. `toolArgs` is the verb;
+            // `restArgs` carries the alias.
+            const action = toolArgs;
+            if (action === "set") {
+                const alias = restArgs[0];
+                if (!alias) {
+                    console.error("Usage: lotics app query set <alias>");
+                    console.error("Pushes package.json#lotics.queries.<alias> to apps.queries via set_app_query (no deploy).");
+                    process.exit(1);
+                }
+                await appQuerySet(client, { alias });
+                return;
+            }
+            console.error("Usage:");
+            console.error("  lotics app query set <alias>   Push package.json#lotics.queries.<alias> to apps.queries (no deploy)");
+            process.exit(1);
+        }
         if (subcommand === "dev") {
             // First positional is an optional project path (defaults to cwd).
             // --port and --vite-port can override the wrapper / Vite ports.

package/dist/client.d.ts

@@ -277,6 +277,18 @@ export declare class LoticsClient {
         name?: string;
         description?: string;
     }): Promise<ToolExecuteResult>;
+    /**
+     * Bind (create or replace) an app query by alias via the `set_app_query` tool
+     * — the deploy-free authoring path for `apps.queries`, parallel to
+     * `setAppWorkflow`. `declaration` is the `{ ast, params? }` from
+     * `package.json#lotics.queries.<alias>`. The server validates it exactly as a
+     * deploy validates the manifest. Note: `apps.queries` is manifest-authoritative,
+     * so the next `lotics app deploy` overwrites this from the manifest.
+     */
+    setAppQuery(app_id: string, alias: string, declaration: {
+        ast: unknown;
+        params?: Record<string, unknown>;
+    }): Promise<ToolExecuteResult>;
     /**
      * Fetch one app workflow's faithful source + bound input/output schemas via
      * `get_app_workflow`. `source` is the JS-subset body re-rendered from the
@@ -375,6 +387,14 @@ export declare class LoticsClient {
         capabilities?: {
             comments?: boolean;
         };
+        /**
+         * The manifest's `lotics.workflows` KEYS — the workflow aliases the deployed
+         * code declares (NOT the bindings; `set_app_workflow` / `remove_app_workflow`
+         * own `apps.workflows`). Recorded on the new version so `remove_app_workflow`
+         * refuses to unbind an alias the served version still calls. Always sent
+         * (empty array when none declared).
+         */
+        workflow_aliases?: string[];
     }): Promise<{
         version_id: string;
         version_number: number;

package/dist/client.js

@@ -333,6 +333,17 @@ export class LoticsClient {
             ...(body.description ? { description: body.description } : {}),
         });
     }
+    /**
+     * Bind (create or replace) an app query by alias via the `set_app_query` tool
+     * — the deploy-free authoring path for `apps.queries`, parallel to
+     * `setAppWorkflow`. `declaration` is the `{ ast, params? }` from
+     * `package.json#lotics.queries.<alias>`. The server validates it exactly as a
+     * deploy validates the manifest. Note: `apps.queries` is manifest-authoritative,
+     * so the next `lotics app deploy` overwrites this from the manifest.
+     */
+    async setAppQuery(app_id, alias, declaration) {
+        return this.execute("set_app_query", { app_id, alias, declaration });
+    }
     /**
      * Fetch one app workflow's faithful source + bound input/output schemas via
      * `get_app_workflow`. `source` is the JS-subset body re-rendered from the
@@ -427,6 +438,10 @@ export class LoticsClient {
         if (args.capabilities !== undefined) {
             formData.append("capabilities", JSON.stringify(args.capabilities));
         }
+        // Always send the declared workflow aliases (empty array when none) so the
+        // server records what the served version calls — the remove_app_workflow
+        // guard reads this back. These are the manifest KEYS only, never bindings.
+        formData.append("workflow_aliases", JSON.stringify(args.workflow_aliases ?? []));
         const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
         const response = await fetch(url, {
             method: "POST",

package/dist/src/cli.js

@@ -29881,6 +29881,17 @@ var LoticsClient = class {
       ...body.description ? { description: body.description } : {}
     });
   }
+  /**
+   * Bind (create or replace) an app query by alias via the `set_app_query` tool
+   * — the deploy-free authoring path for `apps.queries`, parallel to
+   * `setAppWorkflow`. `declaration` is the `{ ast, params? }` from
+   * `package.json#lotics.queries.<alias>`. The server validates it exactly as a
+   * deploy validates the manifest. Note: `apps.queries` is manifest-authoritative,
+   * so the next `lotics app deploy` overwrites this from the manifest.
+   */
+  async setAppQuery(app_id, alias, declaration) {
+    return this.execute("set_app_query", { app_id, alias, declaration });
+  }
   /**
    * Fetch one app workflow's faithful source + bound input/output schemas via
    * `get_app_workflow`. `source` is the JS-subset body re-rendered from the
@@ -30004,6 +30015,7 @@ var LoticsClient = class {
     if (args.capabilities !== void 0) {
       formData.append("capabilities", JSON.stringify(args.capabilities));
     }
+    formData.append("workflow_aliases", JSON.stringify(args.workflow_aliases ?? []));
     const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
     const response = await fetch(url, {
       method: "POST",
@@ -32730,10 +32742,14 @@ async function appDeploy(client, args) {
         // defaulting to `{}` when the manifest declares none — so deleting the
         // `capabilities` block turns every capability OFF on the next deploy
         // (fail-safe; the declaration is the grant).
-        capabilities: meta.capabilities ?? {}
-        // Workflow bindings are NOT a deploy concern — set_app_workflow /
-        // remove_app_workflow own apps.workflows. The manifest's `workflows`
-        // map is a pulled reflection used only for the .d.ts codegen above.
+        capabilities: meta.capabilities ?? {},
+        // Workflow BINDINGS are NOT a deploy concern — set_app_workflow /
+        // remove_app_workflow own apps.workflows. But the alias KEYS of the
+        // manifest's `workflows` map ARE sent (never the bindings): they record
+        // which aliases this bundle declares, so remove_app_workflow can refuse
+        // to unbind an alias the served version still calls. Drop an alias from
+        // the manifest + redeploy to lift that guard before removing its binding.
+        workflow_aliases: Object.keys(meta.workflows ?? {})
       });
       writeAppMeta(projectDir, {
         ...meta,
@@ -32742,7 +32758,13 @@ async function appDeploy(client, args) {
       });
       console.error(`Deployed v${result.version_number} (${result.version_id})`);
       console.error(`Bundle size: ${(result.bundle_size_bytes / 1024).toFixed(1)} KB`);
-      await warnIfUnbranded(client, meta.app_id);
+      try {
+        const app = await client.getApp(meta.app_id);
+        warnIfUnbranded(app);
+        warnIfUnboundAliases(app, meta.workflows ?? {}, meta.agents ?? {});
+      } catch (err2) {
+        console.error(`(skipped post-deploy checks: ${err2.message})`);
+      }
     } catch (err2) {
       const e = err2;
       if (e.code === "VERSION_CONFLICT") {
@@ -32758,22 +32780,32 @@ async function appDeploy(client, args) {
     if (fs4.existsSync(tmpDist)) fs4.unlinkSync(tmpDist);
   }
 }
-async function warnIfUnbranded(client, appId) {
-  try {
-    const app = await client.getApp(appId);
-    const missing = [];
-    if (!app.icon) missing.push("icon");
-    if (!app.theme?.color) missing.push("color");
-    if (missing.length === 0) return;
-    console.error(
-      `
+function warnIfUnbranded(app) {
+  const missing = [];
+  if (!app.icon) missing.push("icon");
+  if (!app.theme?.color) missing.push("color");
+  if (missing.length === 0) return;
+  console.error(
+    `
 \u26A0 This app has no ${missing.join(" or ")} set \u2014 it shows a generic tile in the launcher.
-  Set it:  lotics run update_app '{"app_id":"${appId}","icon":"<lucide-name>","theme":{"color":"blue"}}'
+  Set it:  lotics run update_app '{"app_id":"${app.id}","icon":"<lucide-name>","theme":{"color":"blue"}}'
   Find an icon:  lotics run search_app_icons '{"query":"<word>"}'`
-    );
-  } catch (err2) {
-    console.error(`(skipped branding check: ${err2.message})`);
-  }
+  );
+}
+function warnIfUnboundAliases(app, declaredWorkflows, declaredAgents) {
+  const boundWorkflows = new Set(Object.keys(app.workflows ?? {}));
+  const boundAgents = new Set(Object.keys(app.agents ?? {}));
+  const unboundWorkflows = Object.keys(declaredWorkflows).filter((a) => !boundWorkflows.has(a));
+  const unboundAgents = Object.keys(declaredAgents).filter((a) => !boundAgents.has(a));
+  if (unboundWorkflows.length === 0 && unboundAgents.length === 0) return;
+  const lines = [
+    "\n\u26A0 The manifest declares aliases that are NOT bound on the server. Deploy ships code +",
+    '  queries only \u2014 it does NOT bind workflows/agents, so the app will throw "has no \u2026 alias"',
+    "  the first time it calls them. Bind each one:"
+  ];
+  for (const alias of unboundWorkflows) lines.push(`  \u2022 workflow "${alias}"  \u2192  lotics app workflow set ${alias}`);
+  for (const alias of unboundAgents) lines.push(`  \u2022 agent "${alias}"  \u2192  bind with set_app_agent (lotics run set_app_agent \u2026)`);
+  console.error(lines.join("\n"));
 }
 async function appDev(client, args) {
   const projectDir = path5.resolve(args.projectDir ?? process.cwd());
@@ -32942,6 +32974,25 @@ async function appWorkflowSet(client, args) {
     console.error(`  result.data schema: ${JSON.stringify(result.outputs)}`);
   }
 }
+async function appQuerySet(client, args) {
+  const projectDir = process.cwd();
+  const meta = readAppMeta(projectDir);
+  const declaration = meta.queries?.[args.alias];
+  if (!declaration) {
+    console.error(
+      `No query "${args.alias}" in package.json#lotics.queries. Declare it there (alias \u2192 { ast, params? }) first.`
+    );
+    process.exit(1);
+  }
+  const res = await client.setAppQuery(meta.app_id, args.alias, declaration);
+  if (res.error) {
+    console.error(`Failed to set query "${args.alias}": ${res.error}`);
+    process.exit(1);
+  }
+  console.error(
+    `Set query "${args.alias}" on ${meta.app_id}. (apps.queries is manifest-authoritative \u2014 the next 'lotics app deploy' re-syncs it.)`
+  );
+}
 async function appWorkflowPull(client) {
   const projectDir = process.cwd();
   const meta = readAppMeta(projectDir);
@@ -33050,10 +33101,11 @@ function appUiLink(args) {
       `No vite.config.ts at ${projectDir}. Run inside a 'lotics app' project directory.`
     );
   }
-  const uiSrc = findUiSrcDir(projectDir);
-  if (!uiSrc) {
+  const explicit = args.uiSrc ?? process.env.LOTICS_UI_SRC;
+  const uiSrc = explicit ? path5.resolve(explicit) : findUiSrcDir(projectDir);
+  if (!uiSrc || !fs4.existsSync(uiSrc) || !fs4.statSync(uiSrc).isDirectory()) {
     throw new Error(
-      "Cannot find packages/ui/src by walking up from this directory \u2014 `lotics ui link` requires a monorepo checkout. External apps consume @lotics/ui from npm; bump the package version and widen the app's dependency range instead."
+      explicit ? `--ui-src / LOTICS_UI_SRC points at '${explicit}', which is not a directory. Pass the absolute path to the monorepo's packages/ui/src.` : "Cannot find packages/ui/src by walking up from this directory. For an EXTERNAL app (consuming @lotics/ui from npm), pass --ui-src=<abs path to packages/ui/src> or set LOTICS_UI_SRC; inside a monorepo checkout it is found automatically."
     );
   }
   const hasComponent = fs4.existsSync(path5.join(uiSrc, `${args.component}.tsx`)) || fs4.existsSync(path5.join(uiSrc, `${args.component}.ts`)) || fs4.existsSync(path5.join(uiSrc, args.component));
@@ -33108,6 +33160,7 @@ function parseArgs(argv) {
     apiKey: void 0,
     workspace: void 0,
     viewAs: void 0,
+    uiSrc: void 0,
     name: void 0,
     timezone: void 0,
     message: void 0,
@@ -33149,6 +33202,9 @@ function parseArgs(argv) {
       case "--view-as":
         flags.viewAs = argv[++i2];
         break;
+      case "--ui-src":
+        flags.uiSrc = argv[++i2];
+        break;
       case "--name":
         flags.name = argv[++i2];
         break;
@@ -42676,6 +42732,7 @@ function readCfbStreams(bytes) {
     throw new Error("Unsupported .xls: invalid OLE2 sector size");
   }
   const sectorOffset = (n) => sectorSize * (n + 1);
+  const maxSectors = Math.ceil(bytes.length / sectorSize) + 1;
   const difat = [];
   for (let i2 = 0; i2 < 109; i2++) {
     const v = u32(76 + i2 * 4);
@@ -42683,7 +42740,9 @@ function readCfbStreams(bytes) {
   }
   let ds = firstDifatSector;
   const entriesPerSector = sectorSize / 4;
-  for (let guard = 0; ds !== ENDOFCHAIN && ds !== FREESECT && guard < 1 << 20; guard++) {
+  const seenDifat = /* @__PURE__ */ new Set();
+  while (ds !== ENDOFCHAIN && ds !== FREESECT && ds < maxSectors && !seenDifat.has(ds)) {
+    seenDifat.add(ds);
     const base = sectorOffset(ds);
     for (let i2 = 0; i2 < entriesPerSector - 1; i2++) {
       const v = u32(base + i2 * 4);
@@ -42693,14 +42752,18 @@ function readCfbStreams(bytes) {
   }
   const fat = [];
   for (const fatSector of difat) {
+    if (fat.length >= maxSectors) break;
+    if (fatSector >= maxSectors) continue;
     const base = sectorOffset(fatSector);
-    for (let i2 = 0; i2 < entriesPerSector; i2++) fat.push(u32(base + i2 * 4));
+    for (let i2 = 0; i2 < entriesPerSector && fat.length < maxSectors; i2++) {
+      fat.push(u32(base + i2 * 4));
+    }
   }
   const readChain = (src, start, size, ss, offOf, chain) => {
-    const maxSectors = Math.floor(src.length / ss) + 2;
+    const maxSectors2 = Math.floor(src.length / ss) + 2;
     const parts = [];
     let s = start;
-    for (let guard = 0; s !== ENDOFCHAIN && s !== FREESECT && s < chain.length && guard < maxSectors; guard++) {
+    for (let guard = 0; s !== ENDOFCHAIN && s !== FREESECT && s < chain.length && guard < maxSectors2; guard++) {
       const o = offOf(s);
       parts.push(src.subarray(o, o + ss));
       s = chain[s];
@@ -49650,11 +49713,16 @@ COMMANDS
   lotics app workflow pull             Rewrite src/workflows/*.ts from the server
   lotics app workflow check [alias]    Typecheck src/workflows bodies locally (one
                                        isolated program per alias; the app's own tsc)
+  lotics app query set <alias>         Push package.json#lotics.queries.<alias> to
+                                       apps.queries via set_app_query (no deploy;
+                                       re-synced by the next deploy from the manifest)
   lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
   lotics app rename "<new name>"       Rename the app's display name (launcher title)
   lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
-  lotics ui link <component> [--remove] Dev-link @lotics/ui to the monorepo's
-                                       packages/ui/src for live HMR (monorepo only)
+  lotics ui link <component> [--ui-src <path>] [--remove]
+                                       Dev-link @lotics/ui to packages/ui/src (Vite alias
+                                       + tsc paths) for live HMR + typecheck. Monorepo apps
+                                       auto-find it; external apps pass --ui-src / LOTICS_UI_SRC
   lotics xlsx <subcommand> ...         Read/write/edit .xlsx files on your local filesystem
                                        (uses the bundled Lotics xlsx engine; prefer over
                                        npm xlsx/exceljs for round-trip fidelity)
@@ -50018,15 +50086,16 @@ async function main() {
     if (subcommand === "link") {
       const component = toolArgs;
       if (!component) {
-        console.error("Usage: lotics ui link <component> [--remove]");
-        console.error("Dev-links @lotics/ui to the monorepo's packages/ui/src for live HMR.");
+        console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
+        console.error("Dev-links @lotics/ui to packages/ui/src (Vite + tsc) for live HMR + typecheck.");
+        console.error("Monorepo apps find packages/ui/src automatically; external apps pass --ui-src / LOTICS_UI_SRC.");
         process.exit(1);
       }
-      appUiLink({ component, remove: restArgs.includes("--remove") });
+      appUiLink({ component, uiSrc: flags.uiSrc, remove: restArgs.includes("--remove") });
       return;
     }
     console.error(`Unknown ui subcommand: ${subcommand ?? "(none)"}`);
-    console.error("Usage: lotics ui link <component> [--remove]");
+    console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
     process.exit(1);
   }
   if (command === "app" && subcommand === "workflow" && toolArgs === "check") {
@@ -50119,6 +50188,7 @@ async function main() {
     console.error("  lotics app workflow set <alias>           Push the edited src/workflows/<alias>.ts body");
     console.error("  lotics app workflow pull                  Rewrite src/workflows/*.ts from the server");
     console.error("  lotics app workflow check [alias]         Typecheck src/workflows bodies locally");
+    console.error("  lotics app query set <alias>              Push lotics.queries.<alias> to apps.queries (no deploy)");
     console.error("  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address");
     console.error(`  lotics app rename "<new name>"        Rename the app's display name (launcher title)`);
     console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
@@ -50324,6 +50394,26 @@ Available workspaces:`);
       }
       workflowUsage();
     }
+    if (subcommand === "query") {
+      const action = toolArgs;
+      if (action === "set") {
+        const alias = restArgs[0];
+        if (!alias) {
+          console.error("Usage: lotics app query set <alias>");
+          console.error(
+            "Pushes package.json#lotics.queries.<alias> to apps.queries via set_app_query (no deploy)."
+          );
+          process.exit(1);
+        }
+        await appQuerySet(client, { alias });
+        return;
+      }
+      console.error("Usage:");
+      console.error(
+        "  lotics app query set <alias>   Push package.json#lotics.queries.<alias> to apps.queries (no deploy)"
+      );
+      process.exit(1);
+    }
     if (subcommand === "dev") {
       const projectDir = toolArgs;
       let port;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.65.0",
+  "version": "0.67.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {
@@ -26,7 +26,7 @@
     "@types/node": "^22.15.21",
     "esbuild": "^0.28.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.9"
   },
   "keywords": [
     "lotics",