@lotics/cli 0.45.2 → 0.47.0

package/dist/app_commands.d.ts

@@ -102,6 +102,12 @@ export declare function appPull(client: LoticsClient, args: {
     app_id: string;
     targetPath?: string;
 }): Promise<void>;
+/**
+ * Capabilities the source CALLS but the manifest does not DECLARE — each one
+ * silently 403s at runtime (GAP-29). Pure over the concatenated source text so
+ * it's unit-testable; the deploy warns (non-blocking) on a non-empty result.
+ */
+export declare function undeclaredCapabilities(sourceText: string, declared: Record<string, boolean | undefined> | undefined): string[];
 /**
  * `lotics app deploy [-m <message>]`
  *
@@ -113,7 +119,6 @@ export declare function appPull(client: LoticsClient, args: {
 export declare function appDeploy(client: LoticsClient, args: {
     projectDir?: string;
     message?: string;
-    forceWorkflowSync?: boolean;
 }): Promise<void>;
 /**
  * `lotics app dev [path] [--port=5174] [--vite-port=5173]`

package/dist/app_commands.js

@@ -289,6 +289,48 @@ export async function appPull(client, args) {
     console.error(`  # edit src/App.tsx`);
     console.error(`  lotics app deploy`);
 }
+/**
+ * SDK calls that only work when the matching capability is declared in
+ * `package.json#lotics.capabilities`. Used by the deploy pre-flight (GAP-29):
+ * code that calls one of these but omits the capability silently 403s at
+ * runtime, with no build or deploy error. Extend this map when a new capability
+ * gate ships in `@lotics/app-sdk`.
+ */
+const CAPABILITY_GATED_CALLS = {
+    comments: ["useComments", "createComment", "updateComment", "deleteComment"],
+};
+/**
+ * Capabilities the source CALLS but the manifest does not DECLARE — each one
+ * silently 403s at runtime (GAP-29). Pure over the concatenated source text so
+ * it's unit-testable; the deploy warns (non-blocking) on a non-empty result.
+ */
+export function undeclaredCapabilities(sourceText, declared) {
+    const used = [];
+    for (const [capability, calls] of Object.entries(CAPABILITY_GATED_CALLS)) {
+        const isCalled = calls.some((call) => new RegExp(`\\b${call}\\b`).test(sourceText));
+        if (isCalled && declared?.[capability] !== true)
+            used.push(capability);
+    }
+    return used;
+}
+/** Concatenated text of the app's `src/` files — the input to the capability pre-flight. */
+function readAppSourceText(projectDir) {
+    const srcDir = path.join(projectDir, "src");
+    if (!fs.existsSync(srcDir))
+        return "";
+    const parts = [];
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (/\.(ts|tsx|js|jsx)$/.test(entry.name))
+                parts.push(fs.readFileSync(full, "utf8"));
+        }
+    };
+    walk(srcDir);
+    return parts.join("\n");
+}
 /**
  * `lotics app deploy [-m <message>]`
  *
@@ -300,6 +342,16 @@ export async function appPull(client, args) {
 export async function appDeploy(client, args) {
     const projectDir = path.resolve(args.projectDir ?? process.cwd());
     const meta = readAppMeta(projectDir);
+    // Pre-flight (GAP-29): a capability the code calls but the manifest doesn't
+    // declare silently 403s at runtime with no other signal — warn before shipping
+    // it. Non-blocking, like the unbranded nudge below.
+    const undeclared = undeclaredCapabilities(readAppSourceText(projectDir), meta.capabilities);
+    if (undeclared.length > 0) {
+        const block = JSON.stringify(Object.fromEntries(undeclared.map((c) => [c, true])));
+        console.error(`\n⚠ This app calls capability-gated SDK functions for ${undeclared.join(", ")} but the ` +
+            `manifest doesn't declare ${undeclared.length > 1 ? "them" : "it"} — those calls will 403 at runtime.\n` +
+            `  Add to package.json#lotics.capabilities:  ${block}`);
+    }
     // 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.
@@ -336,20 +388,17 @@ export async function appDeploy(client, args) {
                 dist_archive: fs.readFileSync(tmpDist),
                 prev_version_id: meta.current_version_id,
                 message: args.message,
-                // 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 ?? {},
-                // Capabilities are manifest-authoritative (like workflows/queries):
-                // always send, 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 are manifest-authoritative (like queries): always send,
+                // 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 ?? {},
-                // 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,
+                // 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.
             });
             writeAppMeta(projectDir, {
                 ...meta,

package/dist/app_commands.test.js

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import { tmpdir } from "node:os";
-import { stampPulledManifest } from "./app_commands.js";
+import { stampPulledManifest, undeclaredCapabilities } from "./app_commands.js";
 /**
  * `appPull` reads workflows from the live App row (server response), NOT from
  * the manifest embedded in the extracted source archive. The frozen archive
@@ -104,3 +104,31 @@ describe("stampPulledManifest", () => {
         expect(dts).toContain("only_live");
     });
 });
+/**
+ * The deploy pre-flight that catches GAP-29: source that CALLS a capability-gated
+ * SDK function while the manifest omits that capability would silently 403 at
+ * runtime. `undeclaredCapabilities` is the pure decision the warning is built on.
+ */
+describe("undeclaredCapabilities", () => {
+    const commentsSource = `import { useComments } from "@lotics/app-sdk";\nconst { available } = useComments({ record_id });`;
+    it("flags a capability that's called but not declared", () => {
+        expect(undeclaredCapabilities(commentsSource, undefined)).toEqual(["comments"]);
+        expect(undeclaredCapabilities(commentsSource, {})).toEqual(["comments"]);
+        expect(undeclaredCapabilities(commentsSource, { comments: false })).toEqual(["comments"]);
+    });
+    it("stays quiet when the called capability is declared", () => {
+        expect(undeclaredCapabilities(commentsSource, { comments: true })).toEqual([]);
+    });
+    it("stays quiet when the capability isn't used at all", () => {
+        expect(undeclaredCapabilities(`const x = createInvoice();`, undefined)).toEqual([]);
+        expect(undeclaredCapabilities("", { comments: true })).toEqual([]);
+    });
+    it("matches on whole identifiers, not substrings", () => {
+        // `myUseCommentsHelper` is not a call to the gated `useComments`.
+        expect(undeclaredCapabilities(`const x = myUseCommentsHelper();`, undefined)).toEqual([]);
+    });
+    it("detects any of a capability's gated calls", () => {
+        expect(undeclaredCapabilities(`await createComment({ body });`, {})).toEqual(["comments"]);
+        expect(undeclaredCapabilities(`await deleteComment(id);`, {})).toEqual(["comments"]);
+    });
+});

package/dist/args.d.ts

@@ -4,8 +4,8 @@
  * Splits `process.argv.slice(2)` into a command / subcommand / positional
  * (`toolArgs`) / remaining-positionals (`restArgs`) shape plus typed `flags`.
  * Value-taking flags (`-m`, `--api-key`, …) consume the next token; boolean
- * flags (`--force-workflow-sync`, `--json`, …) toggle. Anything not matching a
- * known flag is positional.
+ * flags (`--json`, `--local`, …) toggle. Anything not matching a known flag is
+ * positional.
  *
  * Lives apart from `cli.ts` so it can be unit-tested — `cli.ts` runs `main()`
  * on import, so importing the parser from there would execute the CLI.
@@ -26,7 +26,6 @@ export declare function parseArgs(argv: string[]): {
         name?: string;
         timezone?: string;
         message?: string;
-        forceWorkflowSync: boolean;
         local: boolean;
         all: boolean;
         version: boolean;

package/dist/args.js

@@ -4,8 +4,8 @@
  * Splits `process.argv.slice(2)` into a command / subcommand / positional
  * (`toolArgs`) / remaining-positionals (`restArgs`) shape plus typed `flags`.
  * Value-taking flags (`-m`, `--api-key`, …) consume the next token; boolean
- * flags (`--force-workflow-sync`, `--json`, …) toggle. Anything not matching a
- * known flag is positional.
+ * flags (`--json`, `--local`, …) toggle. Anything not matching a known flag is
+ * positional.
  *
  * Lives apart from `cli.ts` so it can be unit-tested — `cli.ts` runs `main()`
  * on import, so importing the parser from there would execute the CLI.
@@ -22,7 +22,6 @@ export function parseArgs(argv) {
         name: undefined,
         timezone: undefined,
         message: undefined,
-        forceWorkflowSync: false,
         local: false,
         all: false,
         version: false,
@@ -69,9 +68,6 @@ export function parseArgs(argv) {
             case "--message":
                 flags.message = argv[++i];
                 break;
-            case "--force-workflow-sync":
-                flags.forceWorkflowSync = true;
-                break;
             case "--local":
                 flags.local = true;
                 break;

package/dist/args.test.js

@@ -8,8 +8,8 @@ describe("parseArgs", () => {
         expect(r.toolArgs).toBe("my message");
         expect(r.restArgs).toEqual([]);
     });
-    // `app deploy` regression: `-m` and `--force-workflow-sync` must be parsed
-    // as flags, not silently consumed as the positional message.
+    // `app deploy` regression: `-m` must be parsed as a flag, not silently
+    // consumed as the positional message.
     it("parses -m as the message flag", () => {
         const r = parseArgs(["app", "deploy", "-m", "a message"]);
         expect(r.flags.message).toBe("a message");
@@ -19,19 +19,8 @@ describe("parseArgs", () => {
         const r = parseArgs(["app", "deploy", "--message", "a message"]);
         expect(r.flags.message).toBe("a message");
     });
-    it("parses --force-workflow-sync as a boolean flag", () => {
-        const r = parseArgs(["app", "deploy", "msg", "--force-workflow-sync"]);
-        expect(r.flags.forceWorkflowSync).toBe(true);
-        expect(r.toolArgs).toBe("msg");
-    });
-    it("parses --force-workflow-sync before -m without eating the message", () => {
-        const r = parseArgs(["app", "deploy", "--force-workflow-sync", "-m", "msg"]);
-        expect(r.flags.forceWorkflowSync).toBe(true);
-        expect(r.flags.message).toBe("msg");
-    });
-    it("defaults forceWorkflowSync to false and message to undefined", () => {
+    it("defaults message to undefined for a bare deploy", () => {
         const r = parseArgs(["app", "deploy"]);
-        expect(r.flags.forceWorkflowSync).toBe(false);
         expect(r.flags.message).toBeUndefined();
     });
     it("parses --workspace as a value flag", () => {

package/dist/cli.js

@@ -60,10 +60,9 @@ COMMANDS
                                        Download all files on a record file field
   lotics app create <name> [path]      Create a new custom-code app + scaffold locally
   lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
-  lotics app deploy [-m <message>] [--force-workflow-sync]
-                                       Build + upload current dir as a new version
-                                       (--force-workflow-sync wipes server-only
-                                       workflow aliases; default refuses)
+  lotics app deploy [-m <message>]     Build + upload current dir as a new version
+                                       (code + queries only — workflow bindings are
+                                       managed by set_app_workflow / remove_app_workflow)
   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)
@@ -527,8 +526,7 @@ async function main() {
         console.error("Usage:");
         console.error("  lotics app create <name> [path]      Scaffold a new app locally");
         console.error("  lotics app pull <app_id> [path]      Pull an existing app for local editing");
-        console.error("  lotics app deploy [-m <message>] [--force-workflow-sync]");
-        console.error("                                       Build + upload the current directory");
+        console.error("  lotics app deploy [-m <message>]     Build + upload the current directory");
         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");
@@ -650,11 +648,9 @@ async function main() {
             return;
         }
         if (subcommand === "deploy") {
-            // The message is either `-m <message>` or a bare positional arg after
-            // `deploy`. `--force-workflow-sync` is a parsed boolean flag, valid in
-            // any position.
+            // The message is either `-m <message>` or a bare positional arg after `deploy`.
             const message = flags.message ?? toolArgs;
-            await appDeploy(client, { message, forceWorkflowSync: flags.forceWorkflowSync });
+            await appDeploy(client, { message });
             return;
         }
         if (subcommand === "subdomain") {

package/dist/client.d.ts

@@ -235,19 +235,6 @@ export declare class LoticsClient {
         dist_archive: Buffer;
         prev_version_id?: string | null;
         message?: string | null;
-        /**
-         * Alias → workflow declaration map from the app's `package.json#lotics.workflows`.
-         * Each value is a `{ workflow_id, inputs? }` object — inputs declares a typed
-         * schema or is omitted when the workflow accepts no typed inputs. Always sent
-         * (empty object when none declared) so the server can overwrite apps.workflows
-         * authoritatively. Deleting an alias from the manifest removes it from the DB
-         * on next deploy — gated by the destructive-removal guard unless
-         * `force_workflow_sync` is true.
-         */
-        workflows?: Record<string, {
-            workflow_id: string;
-            inputs?: Record<string, unknown>;
-        }>;
         /**
          * Alias → query declaration map from `package.json#lotics.queries`. Each
          * value is `{ ast, params? }` — a fixed query AST template and an optional
@@ -267,14 +254,6 @@ export declare class LoticsClient {
         capabilities?: {
             comments?: boolean;
         };
-        /**
-         * Opt into destructive workflow removal. When false/absent, the server
-         * rejects a deploy whose `workflows` map is missing aliases that exist
-         * on the App row. Set true to deploy anyway and wipe the missing aliases —
-         * the user is asserting they know what they're doing. Wired to CLI flag
-         * `--force-workflow-sync`.
-         */
-        force_workflow_sync?: boolean;
     }): Promise<{
         version_id: string;
         version_number: number;

package/dist/client.js

@@ -239,11 +239,9 @@ export class LoticsClient {
         if (args.message) {
             formData.append("message", args.message);
         }
-        // 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.
+        // named queries. Server validates each template. (Workflow bindings are
+        // not sent: set_app_workflow / remove_app_workflow own apps.workflows.)
         formData.append("queries", JSON.stringify(args.queries ?? {}));
         // capabilities is manifest-authoritative — the caller always passes it
         // (`{}` when none declared), so a deploy turns off any capability the
@@ -251,12 +249,6 @@ export class LoticsClient {
         if (args.capabilities !== undefined) {
             formData.append("capabilities", JSON.stringify(args.capabilities));
         }
-        // Only post the override flag when the user explicitly opts in. The
-        // server defaults to "honor the guard" — opt-in is loud, opt-out
-        // requires intent.
-        if (args.force_workflow_sync) {
-            formData.append("force_workflow_sync", "true");
-        }
         const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
         const response = await fetch(url, {
             method: "POST",

package/dist/src/cli.js

@@ -29858,14 +29858,10 @@ var LoticsClient = class {
     if (args.message) {
       formData.append("message", args.message);
     }
-    formData.append("workflows", JSON.stringify(args.workflows ?? {}));
     formData.append("queries", JSON.stringify(args.queries ?? {}));
     if (args.capabilities !== void 0) {
       formData.append("capabilities", JSON.stringify(args.capabilities));
     }
-    if (args.force_workflow_sync) {
-      formData.append("force_workflow_sync", "true");
-    }
     const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
     const response = await fetch(url, {
       method: "POST",
@@ -31570,9 +31566,43 @@ Ready. Next steps:`);
   console.error(`  # edit src/App.tsx`);
   console.error(`  lotics app deploy`);
 }
+var CAPABILITY_GATED_CALLS = {
+  comments: ["useComments", "createComment", "updateComment", "deleteComment"]
+};
+function undeclaredCapabilities(sourceText, declared) {
+  const used = [];
+  for (const [capability, calls] of Object.entries(CAPABILITY_GATED_CALLS)) {
+    const isCalled = calls.some((call) => new RegExp(`\\b${call}\\b`).test(sourceText));
+    if (isCalled && declared?.[capability] !== true) used.push(capability);
+  }
+  return used;
+}
+function readAppSourceText(projectDir) {
+  const srcDir = path4.join(projectDir, "src");
+  if (!fs3.existsSync(srcDir)) return "";
+  const parts = [];
+  const walk = (dir) => {
+    for (const entry of fs3.readdirSync(dir, { withFileTypes: true })) {
+      const full = path4.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) parts.push(fs3.readFileSync(full, "utf8"));
+    }
+  };
+  walk(srcDir);
+  return parts.join("\n");
+}
 async function appDeploy(client, args) {
   const projectDir = path4.resolve(args.projectDir ?? process.cwd());
   const meta = readAppMeta(projectDir);
+  const undeclared = undeclaredCapabilities(readAppSourceText(projectDir), meta.capabilities);
+  if (undeclared.length > 0) {
+    const block = JSON.stringify(Object.fromEntries(undeclared.map((c) => [c, true])));
+    console.error(
+      `
+\u26A0 This app calls capability-gated SDK functions for ${undeclared.join(", ")} but the manifest doesn't declare ${undeclared.length > 1 ? "them" : "it"} \u2014 those calls will 403 at runtime.
+  Add to package.json#lotics.capabilities:  ${block}`
+    );
+  }
   writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries });
   console.error("Building...");
   await runNpm(["run", "build"], projectDir);
@@ -31609,20 +31639,17 @@ async function appDeploy(client, args) {
         dist_archive: fs3.readFileSync(tmpDist),
         prev_version_id: meta.current_version_id,
         message: args.message,
-        // 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 ?? {},
-        // Capabilities are manifest-authoritative (like workflows/queries):
-        // always send, 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 ?? {},
-        // 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
+        // Capabilities are manifest-authoritative (like queries): always send,
+        // 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.
       });
       writeAppMeta(projectDir, {
         ...meta,
@@ -31722,7 +31749,6 @@ function parseArgs(argv) {
     name: void 0,
     timezone: void 0,
     message: void 0,
-    forceWorkflowSync: false,
     local: false,
     all: false,
     version: false,
@@ -31769,9 +31795,6 @@ function parseArgs(argv) {
       case "--message":
         flags.message = argv[++i2];
         break;
-      case "--force-workflow-sync":
-        flags.forceWorkflowSync = true;
-        break;
       case "--local":
         flags.local = true;
         break;
@@ -47561,10 +47584,9 @@ COMMANDS
                                        Download all files on a record file field
   lotics app create <name> [path]      Create a new custom-code app + scaffold locally
   lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
-  lotics app deploy [-m <message>] [--force-workflow-sync]
-                                       Build + upload current dir as a new version
-                                       (--force-workflow-sync wipes server-only
-                                       workflow aliases; default refuses)
+  lotics app deploy [-m <message>]     Build + upload current dir as a new version
+                                       (code + queries only \u2014 workflow bindings are
+                                       managed by set_app_workflow / remove_app_workflow)
   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)
@@ -47993,8 +48015,7 @@ async function main() {
     console.error("Usage:");
     console.error("  lotics app create <name> [path]      Scaffold a new app locally");
     console.error("  lotics app pull <app_id> [path]      Pull an existing app for local editing");
-    console.error("  lotics app deploy [-m <message>] [--force-workflow-sync]");
-    console.error("                                       Build + upload the current directory");
+    console.error("  lotics app deploy [-m <message>]     Build + upload the current directory");
     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");
@@ -48111,7 +48132,7 @@ Available workspaces:`);
     }
     if (subcommand === "deploy") {
       const message = flags.message ?? toolArgs;
-      await appDeploy(client, { message, forceWorkflowSync: flags.forceWorkflowSync });
+      await appDeploy(client, { message });
       return;
     }
     if (subcommand === "subdomain") {

package/package.json

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