@lotics/cli 0.28.0 → 0.30.0

package/dist/src/args.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CLI argument parser.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare function parseArgs(argv: string[]): {
+    command?: string;
+    subcommand?: string;
+    toolArgs?: string;
+    restArgs: string[];
+    flags: {
+        json: boolean;
+        timeout?: number;
+        output?: string;
+        as?: string;
+        apiKey?: string;
+        name?: string;
+        timezone?: string;
+        message?: string;
+        forceWorkflowSync: boolean;
+        local: boolean;
+        version: boolean;
+        help: boolean;
+    };
+};

package/dist/src/args.js

@@ -0,0 +1,94 @@
+/**
+ * CLI argument parser.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export function parseArgs(argv) {
+    const flags = {
+        json: false,
+        timeout: undefined,
+        output: undefined,
+        as: undefined,
+        apiKey: undefined,
+        name: undefined,
+        timezone: undefined,
+        message: undefined,
+        forceWorkflowSync: false,
+        local: false,
+        version: false,
+        help: false,
+    };
+    let command;
+    let subcommand;
+    let toolArgs;
+    const restArgs = [];
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--json":
+                flags.json = true;
+                break;
+            case "--timeout":
+                flags.timeout = parseInt(argv[++i], 10);
+                break;
+            case "--output":
+            case "-o":
+                flags.output = argv[++i];
+                break;
+            case "--as":
+                flags.as = argv[++i];
+                break;
+            case "--api-key":
+                flags.apiKey = argv[++i];
+                break;
+            case "--name":
+                flags.name = argv[++i];
+                break;
+            case "--timezone":
+                flags.timezone = argv[++i];
+                break;
+            case "-m":
+            case "--message":
+                flags.message = argv[++i];
+                break;
+            case "--force-workflow-sync":
+                flags.forceWorkflowSync = true;
+                break;
+            case "--local":
+                flags.local = true;
+                break;
+            case "--version":
+            case "-v":
+                flags.version = true;
+                break;
+            case "--help":
+            case "-h":
+                flags.help = true;
+                break;
+            default:
+                if (!command) {
+                    command = arg;
+                }
+                else if (!subcommand) {
+                    subcommand = arg;
+                }
+                else if (!toolArgs) {
+                    toolArgs = arg;
+                }
+                else {
+                    restArgs.push(arg);
+                }
+                break;
+        }
+        i++;
+    }
+    return { command, subcommand, toolArgs, restArgs, flags };
+}

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

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

package/dist/src/args.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { parseArgs } from "./args.js";
+describe("parseArgs", () => {
+    it("splits command / subcommand / positional", () => {
+        const r = parseArgs(["app", "deploy", "my message"]);
+        expect(r.command).toBe("app");
+        expect(r.subcommand).toBe("deploy");
+        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.
+    it("parses -m as the message flag", () => {
+        const r = parseArgs(["app", "deploy", "-m", "a message"]);
+        expect(r.flags.message).toBe("a message");
+        expect(r.toolArgs).toBeUndefined();
+    });
+    it("parses --message as the message flag", () => {
+        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", () => {
+        const r = parseArgs(["app", "deploy"]);
+        expect(r.flags.forceWorkflowSync).toBe(false);
+        expect(r.flags.message).toBeUndefined();
+    });
+});

package/dist/src/cli.js

@@ -6,6 +6,7 @@ import { LoticsClient, API_BASE_URL } from "./client.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";
+import { parseArgs } from "./args.js";
 function printHelp() {
     console.log(`Lotics CLI v${VERSION} — AI agent interface for Lotics
 
@@ -114,79 +115,6 @@ 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 = {
-        json: false,
-        timeout: undefined,
-        output: undefined,
-        as: undefined,
-        apiKey: undefined,
-        name: undefined,
-        timezone: undefined,
-        local: false,
-        version: false,
-        help: false,
-    };
-    let command;
-    let subcommand;
-    let toolArgs;
-    const restArgs = [];
-    let i = 0;
-    while (i < argv.length) {
-        const arg = argv[i];
-        switch (arg) {
-            case "--json":
-                flags.json = true;
-                break;
-            case "--timeout":
-                flags.timeout = parseInt(argv[++i], 10);
-                break;
-            case "--output":
-            case "-o":
-                flags.output = argv[++i];
-                break;
-            case "--as":
-                flags.as = argv[++i];
-                break;
-            case "--api-key":
-                flags.apiKey = argv[++i];
-                break;
-            case "--name":
-                flags.name = argv[++i];
-                break;
-            case "--timezone":
-                flags.timezone = argv[++i];
-                break;
-            case "--local":
-                flags.local = true;
-                break;
-            case "--version":
-            case "-v":
-                flags.version = true;
-                break;
-            case "--help":
-            case "-h":
-                flags.help = true;
-                break;
-            default:
-                if (!command) {
-                    command = arg;
-                }
-                else if (!subcommand) {
-                    subcommand = arg;
-                }
-                else if (!toolArgs) {
-                    toolArgs = arg;
-                }
-                else {
-                    restArgs.push(arg);
-                }
-                break;
-        }
-        i++;
-    }
-    return { command, subcommand, toolArgs, restArgs, flags };
-}
 function readStdin() {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -546,13 +474,11 @@ async function main() {
             return;
         }
         if (subcommand === "deploy") {
-            // -m / --message can be passed via toolArgs or after a flag-like delimiter.
-            // Keep it simple: any positional arg after `deploy` is treated as the message.
-            // --force-workflow-sync is a separate flag captured upstream via restArgs
-            // because it has no value (boolean toggle).
-            const message = toolArgs;
-            const forceWorkflowSync = restArgs.includes("--force-workflow-sync");
-            await appDeploy(client, { message, forceWorkflowSync });
+            // 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.
+            const message = flags.message ?? toolArgs;
+            await appDeploy(client, { message, forceWorkflowSync: flags.forceWorkflowSync });
             return;
         }
         if (subcommand === "dev") {

package/dist/src/client.d.ts

@@ -129,6 +129,36 @@ export declare class LoticsClient {
      * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
      */
     appWorkflow(app_id: string, alias: string, inputs: unknown): Promise<unknown>;
+    /**
+     * Mint a presigned URL for uploading a file into an app. Mirrors
+     * POST /v1/apps/{app_id}/files/upload-url.
+     */
+    appRequestFileUpload(app_id: string, body: {
+        filename: string;
+        mime_type: string;
+        file_size: number;
+    }): Promise<{
+        file_id: string;
+        file_storage_key: string;
+        upload_url: string;
+    }>;
+    /**
+     * Finalize a presigned upload once the bytes are in storage. Mirrors
+     * POST /v1/apps/{app_id}/files/complete.
+     */
+    appCompleteFileUpload(app_id: string, body: {
+        file_id: string;
+        file_storage_key: string;
+        filename: string;
+    }): Promise<{
+        file: {
+            id: string;
+            filename: string;
+            mime_type: string;
+            url?: string;
+            thumbnail_url?: string;
+        };
+    }>;
     deployAppVersion(args: {
         app_id: string;
         source_archive: Buffer;

package/dist/src/client.js

@@ -175,6 +175,20 @@ export class LoticsClient {
     async appWorkflow(app_id, alias, inputs) {
         return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/execute`, { inputs });
     }
+    /**
+     * Mint a presigned URL for uploading a file into an app. Mirrors
+     * POST /v1/apps/{app_id}/files/upload-url.
+     */
+    async appRequestFileUpload(app_id, body) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/files/upload-url`, body);
+    }
+    /**
+     * Finalize a presigned upload once the bytes are in storage. Mirrors
+     * POST /v1/apps/{app_id}/files/complete.
+     */
+    async appCompleteFileUpload(app_id, body) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/files/complete`, body);
+    }
     async deployAppVersion(args) {
         const formData = new FormData();
         // Wrap Buffers as Uint8Array views so the Blob constructor accepts them

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" | "workflow";
+export type RpcOp = "query" | "workflow" | "upload_url" | "upload_complete";
 export interface RpcRequest {
     app_id: string;
     op: RpcOp;

package/dist/src/dev/rpc_handler.js

@@ -5,7 +5,12 @@
  * 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", "workflow"]);
+const SUPPORTED_OPS = new Set([
+    "query",
+    "workflow",
+    "upload_url",
+    "upload_complete",
+]);
 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");
@@ -28,6 +33,34 @@ export async function dispatchRpc(client, body) {
             }
             return client.appWorkflow(body.app_id, p.alias, p.inputs);
         }
+        case "upload_url": {
+            const p = body.payload;
+            if (!p ||
+                typeof p.filename !== "string" ||
+                typeof p.mime_type !== "string" ||
+                typeof p.file_size !== "number") {
+                throw new Error("upload_url payload must include filename, mime_type, file_size");
+            }
+            return client.appRequestFileUpload(body.app_id, {
+                filename: p.filename,
+                mime_type: p.mime_type,
+                file_size: p.file_size,
+            });
+        }
+        case "upload_complete": {
+            const p = body.payload;
+            if (!p ||
+                typeof p.file_id !== "string" ||
+                typeof p.file_storage_key !== "string" ||
+                typeof p.filename !== "string") {
+                throw new Error("upload_complete payload must include file_id, file_storage_key, filename");
+            }
+            return client.appCompleteFileUpload(body.app_id, {
+                file_id: p.file_id,
+                file_storage_key: p.file_storage_key,
+                filename: p.filename,
+            });
+        }
         default: {
             // Unreachable — SUPPORTED_OPS gates above.
             throw new Error(`Unhandled RPC op: ${body.op}`);

package/dist/src/dev/wrapper_page.js

@@ -59,24 +59,59 @@ export function buildWrapperPage(args) {
       const APP_ID = ${JSON.stringify(app_id)};
       const iframe = document.getElementById("app");
 
+      async function rpc(op, payload) {
+        const res = await fetch("/_rpc", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ app_id: APP_ID, op: op, payload: payload }),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+          let detail = text;
+          try { detail = JSON.parse(text).message ?? text; } catch (_) {}
+          throw new Error(detail || ("HTTP " + res.status));
+        }
+        return JSON.parse(text);
+      }
+
+      // The iframe SDK sends one "upload" op carrying a File. A File can't
+      // cross the JSON /_rpc hop, so the upload runs here in the browser:
+      // mint a presigned URL, PUT the bytes to storage, then finalize.
+      async function handleUpload(payload) {
+        const file = payload && payload.file;
+        if (!(file instanceof File)) {
+          throw new Error("upload payload must include a File");
+        }
+        const init = await rpc("upload_url", {
+          filename: file.name,
+          mime_type: file.type,
+          file_size: file.size,
+        });
+        const putRes = await fetch(init.upload_url, {
+          method: "PUT",
+          body: file,
+          headers: { "Content-Type": file.type },
+        });
+        if (!putRes.ok) {
+          throw new Error("Storage upload failed (" + putRes.status + ")");
+        }
+        const completed = await rpc("upload_complete", {
+          file_id: init.file_id,
+          file_storage_key: init.file_storage_key,
+          filename: file.name,
+        });
+        return completed.file;
+      }
+
       window.addEventListener("message", async function (event) {
         if (event.source !== iframe.contentWindow) return;
         const msg = event.data;
         if (!msg || typeof msg.id !== "number" || typeof msg.op !== "string") return;
         const startedAt = performance.now();
         try {
-          const res = await fetch("/_rpc", {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ app_id: APP_ID, op: msg.op, payload: msg.payload }),
-          });
-          const text = await res.text();
-          if (!res.ok) {
-            let detail = text;
-            try { detail = JSON.parse(text).message ?? text; } catch (_) {}
-            throw new Error(detail || ("HTTP " + res.status));
-          }
-          const data = JSON.parse(text);
+          const data = msg.op === "upload"
+            ? await handleUpload(msg.payload)
+            : await rpc(msg.op, msg.payload);
           const ms = Math.round(performance.now() - startedAt);
           console.debug("[lotics-dev] " + msg.op + " " + ms + "ms", data);
           iframe.contentWindow.postMessage({ id: msg.id, type: "result", data: data }, "*");

package/dist/src/generate_app_workflows_dts.js

@@ -111,6 +111,8 @@ function inputDeclToTsType(decl) {
         }
         case "date_range":
             return "{ start: string; end: string }";
+        case "file":
+            return "string";
         case "json":
             return "unknown";
         default:

package/dist/src/starter_template.d.ts

@@ -10,8 +10,10 @@
  *
  * Conventions (locked decisions):
  *   - Vite + React + TypeScript (strict mode).
- *   - Entry: src/App.tsx with `export default`. main.tsx wires `mount(<App/>)`
- *     and imports @lotics/ui/index.css (base style reset) + @lotics/ui/fonts.css
+ *   - Entry: src/App.tsx with `export default`. main.tsx wires
+ *     `mount(<PortalHost><App/></PortalHost>)` — PortalHost is the render
+ *     target @lotics/ui overlays (Popover/Tooltip/Dialog) need — and imports
+ *     @lotics/ui/index.css (base style reset) + @lotics/ui/fonts.css
  *     (path-independent Inter @font-face bundle — Text renders unstyled without it).
  *   - Vite default `base: "/"` so emitted asset URLs are absolute; the render
  *     endpoint rewrites root-relative paths to `/v1/apps/{id}/asset/...`.

package/dist/src/starter_template.js

@@ -10,8 +10,10 @@
  *
  * Conventions (locked decisions):
  *   - Vite + React + TypeScript (strict mode).
- *   - Entry: src/App.tsx with `export default`. main.tsx wires `mount(<App/>)`
- *     and imports @lotics/ui/index.css (base style reset) + @lotics/ui/fonts.css
+ *   - Entry: src/App.tsx with `export default`. main.tsx wires
+ *     `mount(<PortalHost><App/></PortalHost>)` — PortalHost is the render
+ *     target @lotics/ui overlays (Popover/Tooltip/Dialog) need — and imports
+ *     @lotics/ui/index.css (base style reset) + @lotics/ui/fonts.css
  *     (path-independent Inter @font-face bundle — Text renders unstyled without it).
  *   - Vite default `base: "/"` so emitted asset URLs are absolute; the render
  *     endpoint rewrites root-relative paths to `/v1/apps/{id}/asset/...`.
@@ -48,7 +50,7 @@ export function buildStarterTemplate(args) {
                     test: "vitest run",
                 },
                 dependencies: {
-                    "@lotics/app-sdk": "^0.5.0",
+                    "@lotics/app-sdk": "^0.6.0",
                     "@lotics/ui": "^1.3.0",
                     "@react-native-picker/picker": "^2.7.0",
                     "expo-image": "~3.0.9",
@@ -194,10 +196,17 @@ export default defineConfig({
             path: "src/main.tsx",
             content: `import "@lotics/ui/index.css";
 import "@lotics/ui/fonts.css";
+import { PortalHost } from "@lotics/ui/portal";
 import { mount } from "@lotics/app-sdk";
 import App from "./App";
 
-mount(<App />);
+// PortalHost is the render target for @lotics/ui overlays (Popover, Tooltip,
+// Dialog). Without it, Portal renders nothing — keep it wrapping the app.
+mount(
+  <PortalHost>
+    <App />
+  </PortalHost>,
+);
 `,
         },
         {

package/package.json

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