@lotics/cli 0.20.0 → 0.21.0

package/dist/src/app_commands.d.ts

@@ -43,3 +43,21 @@ export declare function appDeploy(client: LoticsClient, args: {
     projectDir?: string;
     message?: string;
 }): Promise<void>;
+/**
+ * `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
+ * iframe matches the production sandbox attributes exactly — null origin,
+ * allow-scripts — so prod-equivalent runtime behavior surfaces in dev.
+ *
+ * Lifecycle: Vite as a child process (HMR over WebSocket), HTTP server on a
+ * sibling port serving the wrapper HTML + the /_rpc dispatcher. SIGINT kills
+ * both cleanly.
+ */
+export declare function appDev(client: LoticsClient, args: {
+    projectDir?: string;
+    port?: number;
+    vitePort?: number;
+}): Promise<void>;

package/dist/src/app_commands.js

@@ -16,6 +16,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { buildStarterTemplate } from "./starter_template.js";
+import { startDevServer, openBrowser } from "./dev/server.js";
 /** Run `tar` and resolve when it exits cleanly. Throws with stderr on failure. */
 function runTar(args, cwd) {
     return new Promise((resolve, reject) => {
@@ -244,3 +245,56 @@ export async function appDeploy(client, args) {
             fs.unlinkSync(tmpDist);
     }
 }
+/**
+ * `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
+ * iframe matches the production sandbox attributes exactly — null origin,
+ * allow-scripts — so prod-equivalent runtime behavior surfaces in dev.
+ *
+ * Lifecycle: Vite as a child process (HMR over WebSocket), HTTP server on a
+ * sibling port serving the wrapper HTML + the /_rpc dispatcher. SIGINT kills
+ * both cleanly.
+ */
+export async function appDev(client, args) {
+    const projectDir = path.resolve(args.projectDir ?? process.cwd());
+    const meta = readAppMeta(projectDir);
+    // 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.
+    const app = await client.getApp(meta.app_id);
+    const handle = await startDevServer({
+        projectDir,
+        app_id: meta.app_id,
+        app_name: app.name,
+        workspace_id: meta.workspace_id,
+        api_url: client.baseUrl,
+        port: args.port,
+        vitePort: args.vitePort,
+        client,
+    });
+    await handle.ready;
+    const url = `http://localhost:${handle.port}`;
+    console.error(`\n  lotics app dev`);
+    console.error(`  app:       ${app.name} (${meta.app_id})`);
+    console.error(`  workspace: ${meta.workspace_id}`);
+    console.error(`  vite:      http://localhost:${handle.vitePort}/`);
+    console.error(`  open:      ${url}`);
+    console.error(`  rpc:       ${client.baseUrl} (via Bearer API key)\n`);
+    console.error(`  Ctrl-C to stop.\n`);
+    openBrowser(url);
+    // Block until SIGINT.
+    await new Promise((resolve) => {
+        const onSig = () => {
+            process.off("SIGINT", onSig);
+            process.off("SIGTERM", onSig);
+            resolve();
+        };
+        process.on("SIGINT", onSig);
+        process.on("SIGTERM", onSig);
+    });
+    console.error("\nStopping…");
+    await handle.stop();
+}

package/dist/src/cli.js

@@ -5,7 +5,7 @@ import readline from "node:readline";
 import { LoticsClient, API_BASE_URL } from "./client.js";
 import { resolveAuth, loadConfig, saveConfig, deleteConfig, checkForUpdate } from "./config.js";
 import { VERSION } from "./version.js";
-import { appCreate, appPull, appDeploy } from "./app_commands.js";
+import { appCreate, appPull, appDeploy, appDev } from "./app_commands.js";
 function printHelp() {
     console.log(`Lotics CLI v${VERSION} — AI agent interface for Lotics
 
@@ -47,6 +47,7 @@ COMMANDS
   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>]     Build + upload current dir as a new version
+  lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
 
 FLAGS
   --json             Full JSON output (default is human-readable text)
@@ -403,6 +404,7 @@ async function main() {
         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>]     Build + upload the current directory");
+        console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
         process.exit(1);
     }
     if (command === "run" && !subcommand) {
@@ -522,6 +524,23 @@ async function main() {
             await appDeploy(client, { message });
             return;
         }
+        if (subcommand === "dev") {
+            // First positional is an optional project path (defaults to cwd).
+            // --port and --vite-port can override the wrapper / Vite ports.
+            const projectDir = toolArgs;
+            let port;
+            let vitePort;
+            for (const a of restArgs) {
+                const portMatch = /^--port=(\d+)$/.exec(a);
+                const vitePortMatch = /^--vite-port=(\d+)$/.exec(a);
+                if (portMatch)
+                    port = Number(portMatch[1]);
+                else if (vitePortMatch)
+                    vitePort = Number(vitePortMatch[1]);
+            }
+            await appDev(client, { projectDir, port, vitePort });
+            return;
+        }
         console.error(`Unknown app subcommand: ${subcommand}`);
         console.error("Run 'lotics app' for usage.");
         process.exit(1);

package/dist/src/client.d.ts

@@ -35,7 +35,10 @@ export declare const API_BASE_URL: string;
 export declare class LoticsClient {
     private apiKey;
     private workspaceId;
-    private baseUrl;
+    /** API URL the client is configured against. Read-only after construction.
+     *  Surfaced for callers that need to display or log it (e.g., `lotics app dev`
+     *  shows it in the banner). */
+    readonly baseUrl: string;
     constructor(options: LoticsClientOptions);
     private throwResponseError;
     private buildHeaders;
@@ -92,6 +95,28 @@ export declare class LoticsClient {
         build_status: string;
     }>;
     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.
+     */
+    appQuery(app_id: string, ast: 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.
+     */
+    appWorkflow(app_id: string, alias: string, inputs: unknown): Promise<unknown>;
     deployAppVersion(args: {
         app_id: string;
         source_archive: Buffer;

package/dist/src/client.js

@@ -49,6 +49,9 @@ export const API_BASE_URL = process.env.LOTICS_API_URL ?? "https://api.lotics.ai
 export class LoticsClient {
     apiKey;
     workspaceId;
+    /** API URL the client is configured against. Read-only after construction.
+     *  Surfaced for callers that need to display or log it (e.g., `lotics app dev`
+     *  shows it in the banner). */
     baseUrl;
     constructor(options) {
         this.apiKey = options.apiKey;
@@ -153,6 +156,39 @@ export class LoticsClient {
         const result = await this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/versions/${encodeURIComponent(version_id)}/source`);
         return result.url;
     }
+    // ── App iframe RPC endpoints ──────────────────────────────────────────────
+    // These mirror the four 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.
+     */
+    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 });
+    }
+    /**
+     * Execute a workflow by alias declared in package.json#lotics.workflows.
+     * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
+     */
+    async appWorkflow(app_id, alias, inputs) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/execute`, { inputs });
+    }
     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

@@ -0,0 +1,15 @@
+/**
+ * Stateless dispatcher: takes a parsed RPC envelope from the wrapper page
+ * and routes to the matching LoticsClient method.
+ *
+ * Errors are thrown — the HTTP server caller serializes them to a 500 with
+ * { message }. Same shape as the production iframe-host's error path.
+ */
+import { LoticsClient } from "../client.js";
+export type RpcOp = "query" | "mutate" | "action" | "workflow";
+export interface RpcRequest {
+    app_id: string;
+    op: RpcOp;
+    payload: unknown;
+}
+export declare function dispatchRpc(client: LoticsClient, body: RpcRequest): Promise<unknown>;

package/dist/src/dev/rpc_handler.js

@@ -0,0 +1,51 @@
+/**
+ * Stateless dispatcher: takes a parsed RPC envelope from the wrapper page
+ * and routes to the matching LoticsClient method.
+ *
+ * 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"]);
+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");
+    }
+    if (!SUPPORTED_OPS.has(body.op)) {
+        throw new Error(`Unknown RPC op: ${body.op}`);
+    }
+    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`");
+            }
+            return client.appAction(body.app_id, p.action_id, p.inputs);
+        }
+        case "workflow": {
+            const p = body.payload;
+            if (!p || typeof p.alias !== "string") {
+                throw new Error("workflow payload must include `alias`");
+            }
+            return client.appWorkflow(body.app_id, p.alias, p.inputs);
+        }
+        default: {
+            // Unreachable — SUPPORTED_OPS gates above.
+            throw new Error(`Unhandled RPC op: ${body.op}`);
+        }
+    }
+}

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

@@ -0,0 +1,45 @@
+/**
+ * `lotics app dev` orchestrator.
+ *
+ * Two child processes managed in one Node lifecycle:
+ *   1. Vite dev server (npx vite --port <vite-port>) — child_process.spawn,
+ *      stdio inherited so Vite's own logging surfaces to the developer.
+ *   2. node:http server on <port> serving:
+ *        GET  /        → wrapper HTML (cached: no)
+ *        POST /_rpc    → JSON in, dispatched via rpc_handler, JSON out
+ *        *             → 404
+ *
+ * SIGINT (Ctrl-C) → kill Vite child, close HTTP server, exit 0.
+ */
+import { type ChildProcess } from "node:child_process";
+import { LoticsClient } from "../client.js";
+export interface DevServerArgs {
+    projectDir: string;
+    app_id: string;
+    app_name: string;
+    workspace_id: string;
+    /** API URL the CLI is configured against — shown in the header banner. */
+    api_url: string;
+    /** Preferred wrapper port. If taken, auto-picks a free one. */
+    port?: number;
+    /** Preferred Vite port. If taken, auto-picks a free one. */
+    vitePort?: number;
+    client: LoticsClient;
+}
+export interface DevServerHandle {
+    port: number;
+    vitePort: number;
+    /** Resolves when both Vite + HTTP server are listening. */
+    ready: Promise<void>;
+    /** Stops Vite + HTTP server. Safe to call multiple times. */
+    stop: () => Promise<void>;
+}
+export declare function startDevServer(args: DevServerArgs): Promise<DevServerHandle>;
+/** Used by the CLI command for cross-platform `open <url>`. Best-effort —
+ *  if the platform opener isn't installed (common in WSL, headless CI, some
+ *  Linux minimal images), we log a note and keep the dev server running so
+ *  the developer can copy/paste the URL manually. */
+export declare function openBrowser(url: string): void;
+declare global {
+    type _UnusedChildProcess = ChildProcess;
+}

package/dist/src/dev/server.js

@@ -0,0 +1,198 @@
+/**
+ * `lotics app dev` orchestrator.
+ *
+ * Two child processes managed in one Node lifecycle:
+ *   1. Vite dev server (npx vite --port <vite-port>) — child_process.spawn,
+ *      stdio inherited so Vite's own logging surfaces to the developer.
+ *   2. node:http server on <port> serving:
+ *        GET  /        → wrapper HTML (cached: no)
+ *        POST /_rpc    → JSON in, dispatched via rpc_handler, JSON out
+ *        *             → 404
+ *
+ * SIGINT (Ctrl-C) → kill Vite child, close HTTP server, exit 0.
+ */
+import http from "node:http";
+import net from "node:net";
+import { spawn } from "node:child_process";
+import { dispatchRpc } from "./rpc_handler.js";
+import { buildWrapperPage } from "./wrapper_page.js";
+const DEFAULT_PORT = 5174;
+const DEFAULT_VITE_PORT = 5173;
+export async function startDevServer(args) {
+    const wrapperPort = await pickPort(args.port ?? DEFAULT_PORT);
+    const vitePort = await pickPort(args.vitePort ?? DEFAULT_VITE_PORT, wrapperPort);
+    const viteUrl = `http://localhost:${vitePort}/`;
+    const html = buildWrapperPage({
+        app_name: args.app_name,
+        app_id: args.app_id,
+        workspace_id: args.workspace_id,
+        vite_url: viteUrl,
+        api_url: args.api_url,
+    });
+    // ── Vite child ──────────────────────────────────────────────────────────
+    // `npx vite` resolves to the project's installed Vite (devDependency in
+    // the starter). Inherit stdio so the dev sees Vite's own banner + HMR logs.
+    const viteChild = spawn("npx", ["vite", "--port", String(vitePort), "--strictPort"], {
+        cwd: args.projectDir,
+        stdio: "inherit",
+        env: { ...process.env, FORCE_COLOR: "1" },
+    });
+    let stopped = false;
+    let stoppingResolve = null;
+    const stoppingPromise = new Promise((resolve) => {
+        stoppingResolve = resolve;
+    });
+    viteChild.on("exit", (code, signal) => {
+        if (!stopped) {
+            console.error(`Vite exited unexpectedly (code=${code} signal=${signal})`);
+            void stopAll();
+        }
+    });
+    // Belt and suspenders: kill Vite if the parent dies for any reason.
+    // process.on('exit') runs synchronously on every termination path
+    // (including uncaught exceptions). spawn() returns immediately so we
+    // can grab the pid before any failure mode.
+    const killViteOnExit = () => {
+        if (!viteChild.killed && viteChild.pid) {
+            try {
+                process.kill(viteChild.pid, "SIGTERM");
+            }
+            catch {
+                // process already gone — fine
+            }
+        }
+    };
+    process.once("exit", killViteOnExit);
+    // ── HTTP server ────────────────────────────────────────────────────────
+    const server = http.createServer(async (req, res) => {
+        const url = req.url ?? "/";
+        if (req.method === "GET" && (url === "/" || url === "/index.html")) {
+            res.writeHead(200, {
+                "Content-Type": "text/html; charset=utf-8",
+                "Cache-Control": "no-cache, no-store, must-revalidate",
+            });
+            res.end(html);
+            return;
+        }
+        if (req.method === "POST" && url === "/_rpc") {
+            try {
+                const body = await readJson(req);
+                const startedAt = Date.now();
+                const result = await dispatchRpc(args.client, {
+                    app_id: body.app_id,
+                    op: body.op,
+                    payload: body.payload,
+                });
+                const ms = Date.now() - startedAt;
+                process.stderr.write(`[rpc] ${body.op} ${ms}ms\n`);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(result));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[rpc] ERROR ${message}\n`);
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ message }));
+            }
+            return;
+        }
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not Found");
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(wrapperPort, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    // ── Lifecycle ───────────────────────────────────────────────────────────
+    async function stopAll() {
+        if (stopped)
+            return;
+        stopped = true;
+        if (!viteChild.killed) {
+            viteChild.kill("SIGINT");
+        }
+        await new Promise((resolve) => server.close(() => resolve()));
+        stoppingResolve?.();
+    }
+    // Vite startup is async — we don't get a "ready" signal cleanly across
+    // versions, so we wait for a fixed grace period before resolving `ready`.
+    // The wrapper page handles iframe load failures (Vite still warming up =
+    // the iframe shows a brief refused-connection until Vite responds).
+    const ready = new Promise((resolve) => {
+        setTimeout(resolve, 800);
+    });
+    // Expose stoppingPromise on stop() so callers can await it cleanly.
+    return {
+        port: wrapperPort,
+        vitePort,
+        ready,
+        stop: async () => {
+            await stopAll();
+            await stoppingPromise;
+        },
+    };
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+async function pickPort(preferred, ...avoid) {
+    // Try preferred first. If it's taken or in `avoid`, ask the OS for any
+    // free port via listen(0).
+    if (!avoid.includes(preferred) && (await isPortFree(preferred))) {
+        return preferred;
+    }
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.once("error", reject);
+        srv.listen(0, () => {
+            const addr = srv.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            srv.close(() => (port ? resolve(port) : reject(new Error("Failed to pick port"))));
+        });
+    });
+}
+function isPortFree(port) {
+    return new Promise((resolve) => {
+        const srv = net.createServer();
+        srv.once("error", () => resolve(false));
+        srv.listen(port, () => {
+            srv.close(() => resolve(true));
+        });
+    });
+}
+async function readJson(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(chunk);
+    }
+    const raw = Buffer.concat(chunks).toString("utf-8");
+    if (!raw)
+        throw new Error("empty request body");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.app_id !== "string" || typeof parsed.op !== "string") {
+        throw new Error("body must include app_id and op");
+    }
+    return parsed;
+}
+/** Used by the CLI command for cross-platform `open <url>`. Best-effort —
+ *  if the platform opener isn't installed (common in WSL, headless CI, some
+ *  Linux minimal images), we log a note and keep the dev server running so
+ *  the developer can copy/paste the URL manually. */
+export function openBrowser(url) {
+    const cmd = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "start"
+            : "xdg-open";
+    const child = spawn(cmd, [url], { stdio: "ignore", detached: true });
+    child.on("error", (err) => {
+        if (err.code === "ENOENT") {
+            process.stderr.write(`Note: ${cmd} not available — open ${url} manually.\n`);
+        }
+        else {
+            process.stderr.write(`Note: could not auto-open browser (${err.message}).\n`);
+        }
+    });
+    child.unref();
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Builds the wrapper HTML for `lotics app dev`.
+ *
+ * The wrapper page is served at http://localhost:<port>/ and embeds the
+ * project's Vite dev server in a sandboxed iframe with the same
+ * sandbox="allow-scripts" attribute production uses. The iframe sends
+ * postMessage RPCs to this wrapper, which forwards them to the local
+ * /_rpc endpoint, which dispatches to api.lotics.ai with the CLI's API
+ * key.
+ *
+ * Protocol matches `frontend/features/app_ui/app_iframe_host.tsx` exactly:
+ *   iframe → wrapper: { id: number, op: string, payload: unknown }
+ *   wrapper → iframe: { id, type: "result", data } | { id, type: "error", message }
+ */
+export interface WrapperPageArgs {
+    app_name: string;
+    app_id: string;
+    workspace_id: string;
+    vite_url: string;
+    api_url: string;
+}
+export declare function buildWrapperPage(args: WrapperPageArgs): string;

package/dist/src/dev/wrapper_page.js

@@ -0,0 +1,106 @@
+/**
+ * Builds the wrapper HTML for `lotics app dev`.
+ *
+ * The wrapper page is served at http://localhost:<port>/ and embeds the
+ * project's Vite dev server in a sandboxed iframe with the same
+ * sandbox="allow-scripts" attribute production uses. The iframe sends
+ * postMessage RPCs to this wrapper, which forwards them to the local
+ * /_rpc endpoint, which dispatches to api.lotics.ai with the CLI's API
+ * key.
+ *
+ * Protocol matches `frontend/features/app_ui/app_iframe_host.tsx` exactly:
+ *   iframe → wrapper: { id: number, op: string, payload: unknown }
+ *   wrapper → iframe: { id, type: "result", data } | { id, type: "error", message }
+ */
+export function buildWrapperPage(args) {
+    const { app_name, app_id, workspace_id, vite_url, api_url } = args;
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${escapeHtml(app_name)} — lotics app dev</title>
+  <style>
+    html, body { margin: 0; height: 100%; }
+    body {
+      display: flex; flex-direction: column;
+      font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+      background: #f4f4f5;
+    }
+    header {
+      padding: 8px 14px;
+      background: #18181b;
+      color: #fafafa;
+      font-size: 12px;
+      display: flex; align-items: center; gap: 12px;
+      flex-shrink: 0;
+    }
+    header strong { font-size: 13px; }
+    header code {
+      font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+      font-size: 11px;
+      background: rgba(255,255,255,0.08);
+      padding: 1px 6px; border-radius: 3px;
+    }
+    header span { color: #a1a1aa; }
+    iframe { border: 0; flex: 1; width: 100%; background: #fff; }
+  </style>
+</head>
+<body>
+  <header>
+    <strong>${escapeHtml(app_name)}</strong>
+    <span>app_id <code>${escapeHtml(app_id)}</code></span>
+    <span>workspace <code>${escapeHtml(workspace_id)}</code></span>
+    <span>RPC → <code>${escapeHtml(api_url)}</code></span>
+  </header>
+  <iframe id="app" sandbox="allow-scripts" src="${escapeAttr(vite_url)}"></iframe>
+  <script>
+    (function () {
+      const APP_ID = ${JSON.stringify(app_id)};
+      const iframe = document.getElementById("app");
+
+      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 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 }, "*");
+        } catch (err) {
+          const message = err && err.message ? err.message : String(err);
+          console.error("[lotics-dev] " + msg.op + " failed:", message);
+          iframe.contentWindow.postMessage(
+            { id: msg.id, type: "error", message: message },
+            "*"
+          );
+        }
+      });
+    })();
+  </script>
+</body>
+</html>
+`;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+function escapeAttr(s) {
+    return escapeHtml(s).replace(/"/g, "&quot;");
+}

package/package.json

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