@lotics/cli 0.88.0 → 0.89.1

package/dist/dev/server.js

@@ -1,443 +0,0 @@
-/**
- * `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
- *        POST /_agent_run     → SSE, piped from the run
- *        PUT  /_upload/:id    → file bytes in  (relayed to storage)
- *        GET  /_file/:token   → file bytes out (relayed from storage)
- *        *                    → 404
- *
- * SIGINT (Ctrl-C) → kill Vite child, close HTTP server, exit 0.
- *
- * Why the byte relays exist: dev runs against the PROD bucket (there is no dev
- * bucket), whose CORS allowlist holds the real app origins (`https://*.lotics.app`),
- * not `http://localhost:<port>`. So a browser transfer straight to/from the presigned
- * URL is blocked before it leaves the page — no upload could complete, and no preview
- * engine (PDF/Word/Excel all FETCH the bytes) could read a file. Relaying through THIS
- * server fixes both: Node has no same-origin policy, and the one cross-origin hop that
- * remains (the app iframe reading from us) is OUR response to allow.
- *
- * Neither relay ever takes a destination from the client: the page sends a `file_id`
- * or an opaque token, and the server transfers only to/from a URL IT minted or observed
- * for that id. No client-controlled target ⇒ no SSRF surface, nothing to allowlist.
- *
- * Production is untouched — it transfers direct-to-storage, keeping every byte off the
- * API server.
- */
-import http from "node:http";
-import net from "node:net";
-import { spawn } from "node:child_process";
-import { ipv4ChildEnv } from "../child_env.js";
-import { dispatchRpc } from "./rpc_handler.js";
-import { buildWrapperPage } from "./wrapper_page.js";
-import { createUploadRelay } from "./upload_relay.js";
-import { createFileRelay } from "./file_relay.js";
-const DEFAULT_PORT = 5174;
-const DEFAULT_VITE_PORT = 5173;
-/**
- * Serialize an RPC result for the HTTP response body. Ops with no return
- * value (e.g. comments.delete) resolve `undefined` — in production they
- * travel over postMessage where undefined structured-clones fine, but
- * `JSON.stringify(undefined)` is not a string, so the body would be EMPTY
- * and the wrapper's `JSON.parse` throws "Unexpected end of JSON input".
- * Serialize those as `null`.
- */
-export function serializeRpcResult(result) {
-    return JSON.stringify(result ?? null);
-}
-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). stdout/stderr are inherited so the dev sees Vite's banner
-    // + HMR logs.
-    //
-    // stdin is inherited ONLY under a TTY. Vite's dev server quits when a
-    // non-interactive stdin (a backgrounded launch, `</dev/null`, a closing
-    // pipe) reaches EOF — so inheriting it would kill the dev server the moment
-    // `lotics app dev` runs under an agent, CI, or `nohup`. A non-TTY launch
-    // gets `/dev/null` (`"ignore"`) instead, decoupling Vite's lifetime from
-    // however the wrapper was started. Vite's CLI shortcuts (`r`/`q`/`u`) are
-    // only meaningful under a TTY anyway.
-    const viteChild = spawn("npx", ["vite", "--port", String(vitePort), "--strictPort"], {
-        cwd: args.projectDir,
-        stdio: [process.stdin.isTTY ? "inherit" : "ignore", "inherit", "inherit"],
-        env: ipv4ChildEnv({ ...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);
-    const uploads = createUploadRelay();
-    // The app iframe is served from Vite's origin, so the file URLs it receives must be
-    // absolute against THIS server, and its byte reads are cross-origin to us — which is
-    // ours to allow (unlike the storage bucket's policy, which is not).
-    const wrapperOrigin = `http://localhost:${wrapperPort}`;
-    const viteOrigin = `http://localhost:${vitePort}`;
-    const files = createFileRelay(wrapperOrigin);
-    const fileCors = {
-        "Access-Control-Allow-Origin": viteOrigin,
-        "Access-Control-Allow-Headers": "range, content-type",
-        "Access-Control-Expose-Headers": "content-length, content-range, accept-ranges, content-type, content-disposition, etag",
-    };
-    // Headers a byte-reader actually needs: the type to decode, the length/range to seek.
-    const PASS_THROUGH = [
-        "content-type",
-        "content-length",
-        "content-range",
-        "accept-ranges",
-        "etag",
-        "last-modified",
-        "content-disposition",
-    ];
-    // ── HTTP server ────────────────────────────────────────────────────────
-    const server = http.createServer(async (req, res) => {
-        const url = req.url ?? "/";
-        // Route by pathname — `useUrlState` writes a query string onto the wrapper
-        // URL, so a refresh / shared link requests `/?…`; the page must still serve.
-        const pathname = url.split("?")[0];
-        if (req.method === "GET" && (pathname === "/" || pathname === "/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,
-                }, { commentsEnabled: args.commentsEnabled });
-                const ms = Date.now() - startedAt;
-                process.stderr.write(`[rpc] ${body.op} ${ms}ms\n`);
-                res.writeHead(200, { "Content-Type": "application/json" });
-                // `upload_url` mints a PUT destination (upload relay); every other op may carry
-                // presigned file URLs the app will read bytes from (file relay).
-                res.end(serializeRpcResult(body.op === "upload_url" ? uploads.rewriteMint(result) : files.rewrite(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;
-        }
-        // Streaming agent run — the one op /_rpc can't carry (its response is a
-        // stream, not a single JSON value). Open the run with the CLI key and pipe
-        // the SSE body straight back to the wrapper page, which forwards chunks to
-        // the iframe. A wrapper disconnect (the app aborted) aborts the upstream.
-        if (req.method === "POST" && url === "/_agent_run") {
-            // Abort the upstream run only when the CLIENT disconnects — keyed on the
-            // RESPONSE closing before we finished writing it. `req.on("close")` is
-            // wrong here: in modern Node it fires as soon as the request BODY stream
-            // ends (right after readJson consumes it), which would abort every run the
-            // instant it started — a silent empty 200, no chunks.
-            const ac = new AbortController();
-            res.on("close", () => {
-                if (!res.writableEnded)
-                    ac.abort();
-            });
-            try {
-                const body = await readJson(req);
-                const p = (body.payload ?? {});
-                if (typeof p.alias !== "string" || typeof p.session_id !== "string") {
-                    throw new Error("agentRun payload must include `alias` and `session_id`");
-                }
-                const upstream = await args.client.appAgentRunStream(body.app_id, p.alias, { session_id: p.session_id, input: p.input ?? {} }, ac.signal);
-                if (!upstream.body)
-                    throw new Error("agent run returned no stream body");
-                res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache, no-transform" });
-                const reader = upstream.body.getReader();
-                for (;;) {
-                    const { value, done } = await reader.read();
-                    if (done)
-                        break;
-                    res.write(Buffer.from(value));
-                }
-                res.end();
-            }
-            catch (err) {
-                if (ac.signal.aborted) {
-                    res.end();
-                    return;
-                }
-                const message = err instanceof Error ? err.message : String(err);
-                process.stderr.write(`[agent_run] ERROR ${message}\n`);
-                if (!res.headersSent) {
-                    res.writeHead(500, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ message }));
-                }
-                else {
-                    res.end();
-                }
-            }
-            return;
-        }
-        // File relay — the app reads file bytes from here instead of straight from storage,
-        // whose CORS doesn't admit a localhost origin. The app is on Vite's origin, so this
-        // IS cross-origin — but it's our response, so we allow it. Serving from here also
-        // means <img>/<video> and openExternal keep working unchanged.
-        if (pathname.startsWith("/_file/")) {
-            if (req.method === "OPTIONS") {
-                res.writeHead(204, fileCors);
-                res.end();
-                return;
-            }
-            if (req.method !== "GET" && req.method !== "HEAD") {
-                res.writeHead(405, { ...fileCors, Allow: "GET, HEAD, OPTIONS" });
-                res.end();
-                return;
-            }
-            const token = decodeURIComponent(pathname.slice("/_file/".length));
-            const destination = files.destinationFor(token);
-            if (!destination) {
-                // Not a URL this server handed out (or its presign has aged out). Reading from
-                // anywhere else is the thing this design refuses to do.
-                process.stderr.write(`[file] ERROR unknown or expired token ${token}\n`);
-                res.writeHead(404, { ...fileCors, "Content-Type": "application/json" });
-                res.end(JSON.stringify({ message: "No file for this token" }));
-                return;
-            }
-            try {
-                // Forward Range verbatim: a PDF reader seeks rather than reading the whole file,
-                // and media scrubbing depends on 206s coming back intact.
-                const range = req.headers.range;
-                const upstream = await fetch(destination, {
-                    method: req.method,
-                    headers: range ? { Range: range } : undefined,
-                });
-                const headers = { ...fileCors };
-                for (const name of PASS_THROUGH) {
-                    const value = upstream.headers.get(name);
-                    if (value)
-                        headers[name] = value;
-                }
-                // Same one-line-per-transfer visibility as [rpc] and [upload] — a preview that
-                // silently serves nothing is exactly the thing this relay exists to make legible.
-                const size = headers["content-length"] ?? "?";
-                process.stderr.write(`[file] ${token} ${upstream.status} ${size}B\n`);
-                res.writeHead(upstream.status, headers);
-                if (req.method === "HEAD" || !upstream.body) {
-                    res.end();
-                    return;
-                }
-                const reader = upstream.body.getReader();
-                for (;;) {
-                    const { value, done } = await reader.read();
-                    if (done)
-                        break;
-                    res.write(Buffer.from(value));
-                }
-                res.end();
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                process.stderr.write(`[file] ERROR ${token} ${message}\n`);
-                if (!res.headersSent) {
-                    res.writeHead(502, { ...fileCors, "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ message }));
-                }
-                else {
-                    res.end();
-                }
-            }
-            return;
-        }
-        // Upload relay — the wrapper page PUTs the bytes here (same-origin, so the
-        // browser never applies CORS), and Node forwards them to the presigned URL.
-        if (req.method === "PUT" && pathname.startsWith("/_upload/")) {
-            const fileId = decodeURIComponent(pathname.slice("/_upload/".length));
-            const destination = uploads.destinationFor(fileId);
-            if (!destination) {
-                // Not a URL this server minted (or its presign has aged out). Relaying
-                // anywhere else is exactly the thing this design refuses to do.
-                process.stderr.write(`[upload] ERROR unknown or expired file_id ${fileId}\n`);
-                res.writeHead(404, { "Content-Type": "application/json" });
-                res.end(JSON.stringify({ message: `No presigned upload pending for ${fileId}` }));
-                return;
-            }
-            try {
-                // Buffer rather than stream: the presign signs `content-length`, and a
-                // streamed body would go out chunked and fail the signature. Dev-only,
-                // and the size ceiling is the API's own upload limit.
-                const chunks = [];
-                for await (const chunk of req)
-                    chunks.push(chunk);
-                const bytes = Buffer.concat(chunks);
-                const startedAt = Date.now();
-                const upstream = await fetch(destination, {
-                    method: "PUT",
-                    body: bytes,
-                    headers: { "Content-Type": req.headers["content-type"] ?? "application/octet-stream" },
-                });
-                const ms = Date.now() - startedAt;
-                if (upstream.ok) {
-                    uploads.settle(fileId);
-                    process.stderr.write(`[upload] ${fileId} ${bytes.length}B ${ms}ms\n`);
-                }
-                else {
-                    // Keep the mint: the wrapper retries 5xx, and the presign is still valid.
-                    process.stderr.write(`[upload] ERROR ${fileId} storage returned ${upstream.status}\n`);
-                }
-                res.writeHead(upstream.status);
-                res.end();
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                process.stderr.write(`[upload] ERROR ${fileId} ${message}\n`);
-                if (!res.headersSent) {
-                    res.writeHead(502, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ message }));
-                }
-                else {
-                    res.end();
-                }
-            }
-            return;
-        }
-        res.writeHead(404, { "Content-Type": "text/plain" });
-        res.end("Not Found");
-    });
-    await new Promise((resolve, reject) => {
-        server.once("error", reject);
-        // Loopback ONLY — never 0.0.0.0. `/_rpc` dispatches with the developer's API key, so a
-        // server bound to every interface hands anyone on the same network full read/write on the
-        // workspace (and, since the relays, the file bytes too). Vite already binds loopback; this
-        // socket is strictly more sensitive than that one.
-        server.listen(wrapperPort, "127.0.0.1", () => {
-            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/dev/upload_relay.d.ts

@@ -1,36 +0,0 @@
-/**
- * Dev-only upload relay: the bookkeeping that lets `lotics app dev` upload a file.
- *
- * Dev runs against the PROD bucket (there is no dev bucket), whose CORS allowlist
- * holds the real app origins (`https://*.lotics.app`), not `http://localhost:<port>`.
- * A browser PUT straight to the presigned URL is blocked before it leaves the page,
- * so without a relay no file-touching app can be exercised locally at all.
- *
- * The dev server therefore relays the bytes: the wrapper page PUTs same-origin (no
- * preflight, no CORS) and Node — which has no same-origin policy — forwards them on.
- *
- * The security property, and the reason the page never names its destination: a
- * relay that forwarded to a client-supplied URL would be an open proxy. So the page
- * sends only a `file_id`, and the relay writes ONLY to a presigned URL it minted
- * itself for that id, moments earlier, via its own authenticated API call. There is
- * no client-controlled target — hence nothing to allowlist, and no SSRF surface.
- *
- * Production is untouched: it PUTs direct-to-storage, keeping every byte off the
- * API server.
- */
-export interface UploadRelay {
-    /**
-     * Record the presigned PUT from an `upload_url` mint and return the result the
-     * page should see — identical but for a same-origin `upload_url`. A result that
-     * carries no mint passes through untouched: nothing is recorded, nothing is
-     * rewritten, and the page's PUT fails loudly rather than uploading into a void.
-     */
-    rewriteMint(result: unknown): unknown;
-    /** The presigned URL minted for this id — `null` if unknown or expired. */
-    destinationFor(fileId: string): string | null;
-    /** Drop a mint once its bytes have landed. One presign, one object. */
-    settle(fileId: string): void;
-    /** Outstanding mints — for tests. */
-    size(): number;
-}
-export declare function createUploadRelay(now?: () => number): UploadRelay;

package/dist/dev/upload_relay.js

@@ -1,61 +0,0 @@
-/**
- * Dev-only upload relay: the bookkeeping that lets `lotics app dev` upload a file.
- *
- * Dev runs against the PROD bucket (there is no dev bucket), whose CORS allowlist
- * holds the real app origins (`https://*.lotics.app`), not `http://localhost:<port>`.
- * A browser PUT straight to the presigned URL is blocked before it leaves the page,
- * so without a relay no file-touching app can be exercised locally at all.
- *
- * The dev server therefore relays the bytes: the wrapper page PUTs same-origin (no
- * preflight, no CORS) and Node — which has no same-origin policy — forwards them on.
- *
- * The security property, and the reason the page never names its destination: a
- * relay that forwarded to a client-supplied URL would be an open proxy. So the page
- * sends only a `file_id`, and the relay writes ONLY to a presigned URL it minted
- * itself for that id, moments earlier, via its own authenticated API call. There is
- * no client-controlled target — hence nothing to allowlist, and no SSRF surface.
- *
- * Production is untouched: it PUTs direct-to-storage, keeping every byte off the
- * API server.
- */
-/**
- * How long a mint is worth keeping. This is a pruning window, not a correctness gate —
- * storage is the authority on whether a presign is still valid (an expired one is refused
- * there, and the wrapper surfaces that). It only needs to outlive the presign (~10 min) so
- * the relay never 404s a PUT that storage would still have accepted.
- */
-const PRESIGN_TTL_MS = 15 * 60 * 1000;
-export function createUploadRelay(now = Date.now) {
-    const minted = new Map();
-    const prune = (at) => {
-        for (const [id, entry] of minted) {
-            if (at - entry.mintedAt > PRESIGN_TTL_MS)
-                minted.delete(id);
-        }
-    };
-    return {
-        rewriteMint(result) {
-            const mint = result;
-            if (typeof mint?.file_id !== "string" || typeof mint?.upload_url !== "string")
-                return result;
-            const at = now();
-            prune(at);
-            minted.set(mint.file_id, { url: mint.upload_url, mintedAt: at });
-            return { ...mint, upload_url: `/_upload/${encodeURIComponent(mint.file_id)}` };
-        },
-        destinationFor(fileId) {
-            const entry = minted.get(fileId);
-            if (!entry)
-                return null;
-            if (now() - entry.mintedAt > PRESIGN_TTL_MS) {
-                minted.delete(fileId);
-                return null;
-            }
-            return entry.url;
-        },
-        settle(fileId) {
-            minted.delete(fileId);
-        },
-        size: () => minted.size,
-    };
-}

package/dist/dev/upload_relay.test.d.ts

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

package/dist/dev/upload_relay.test.js

@@ -1,76 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { createUploadRelay } from "./upload_relay.js";
-const MINT = {
-    file_id: "fil_abc",
-    file_storage_key: "org/files/fil_abc/photo.jpg",
-    upload_url: "https://production.r2.cloudflarestorage.com/org/files/fil_abc/photo.jpg?X-Amz-Signature=deadbeef",
-};
-describe("upload relay — the page PUTs same-origin", () => {
-    it("hands the page a same-origin URL and keeps everything else it needs to finalize", () => {
-        const relay = createUploadRelay();
-        const seen = relay.rewriteMint(MINT);
-        expect(seen.upload_url).toBe("/_upload/fil_abc");
-        // file_storage_key + file_id still reach the page — `upload_complete` needs both.
-        expect(seen.file_id).toBe("fil_abc");
-        expect(seen.file_storage_key).toBe(MINT.file_storage_key);
-    });
-    it("does not mutate the mint it was handed", () => {
-        const relay = createUploadRelay();
-        relay.rewriteMint(MINT);
-        expect(MINT.upload_url).toContain("r2.cloudflarestorage.com");
-    });
-});
-describe("upload relay — it writes ONLY where it was told to by itself", () => {
-    it("relays to the presigned URL it minted for that id", () => {
-        const relay = createUploadRelay();
-        relay.rewriteMint(MINT);
-        expect(relay.destinationFor("fil_abc")).toBe(MINT.upload_url);
-    });
-    it("refuses an id it never minted — there is no client-supplied destination to honour", () => {
-        const relay = createUploadRelay();
-        expect(relay.destinationFor("fil_never_seen")).toBeNull();
-    });
-    it("refuses a mint that has aged past its presign", () => {
-        let clock = 1_000_000;
-        const relay = createUploadRelay(() => clock);
-        relay.rewriteMint(MINT);
-        clock += 16 * 60 * 1000; // presigns die at ~10 min; the relay holds 15
-        expect(relay.destinationFor("fil_abc")).toBeNull();
-    });
-});
-describe("upload relay — lifecycle", () => {
-    it("forgets a mint once its bytes have landed", () => {
-        const relay = createUploadRelay();
-        relay.rewriteMint(MINT);
-        relay.settle("fil_abc");
-        expect(relay.destinationFor("fil_abc")).toBeNull();
-        expect(relay.size()).toBe(0);
-    });
-    it("keeps the mint on a failed PUT so the page's retry can reuse it", () => {
-        const relay = createUploadRelay();
-        relay.rewriteMint(MINT);
-        // No settle() — the storage PUT 5xx'd and the wrapper page retries.
-        expect(relay.destinationFor("fil_abc")).toBe(MINT.upload_url);
-    });
-    it("prunes dead mints instead of growing forever across a long dev session", () => {
-        let clock = 0;
-        const relay = createUploadRelay(() => clock);
-        relay.rewriteMint({ ...MINT, file_id: "fil_old" });
-        clock += 16 * 60 * 1000;
-        relay.rewriteMint({ ...MINT, file_id: "fil_new" });
-        expect(relay.size()).toBe(1); // the stale one was swept on the next mint
-        expect(relay.destinationFor("fil_new")).toBe(MINT.upload_url);
-    });
-});
-describe("upload relay — a response that carries no mint", () => {
-    it("passes through untouched rather than inventing a relay for it", () => {
-        const relay = createUploadRelay();
-        const odd = { message: "upstream changed shape" };
-        expect(relay.rewriteMint(odd)).toBe(odd);
-        expect(relay.size()).toBe(0);
-    });
-    it("tolerates null without throwing", () => {
-        const relay = createUploadRelay();
-        expect(relay.rewriteMint(null)).toBeNull();
-    });
-});

package/dist/dev/wrapper_page.d.ts

@@ -1,40 +0,0 @@
-/**
- * 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 an iframe with the same
- * sandbox="allow-scripts allow-same-origin allow-downloads" attribute
- * production uses — safe because the Vite iframe is cross-origin to this
- * wrapper (different port), so the app gets its own real origin (and Web
- * Storage) without being able to reach the wrapper. `allow-downloads` lets
- * apps trigger file downloads (generated xlsx / pdf etc.) — Chrome blocks
- * every download path from sandboxed iframes without it. `allow="...; geolocation;
- * web-share"` delegates the host's location permission (geofenced actions read the
- * device position) and grants the Web Share API (apps call `navigator.share({ files })`
- * to push e.g. container photos to the OS share sheet / gallery) — matching
- * production. 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.
- *
- * postMessage is origin-locked both ways — the wrapper passes its origin
- * via `?lotics_host=` and talks only to the Vite origin.
- *
- * 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 }
- *   streaming (op "agentRun"): { id, type: "stream-chunk", chunk } * → { id, type: "stream-end" };
- *     the iframe aborts with { id, type: "abort" }.
- *   urlState (useUrlState): the iframe reads/writes the wrapper's address bar via
- *     urlState.get/set; set writes in place (replaceState), and browser
- *     back/forward broadcast { type: "url-state", params } back to the iframe.
- *     (In-app routing isn't here — the app owns the iframe's own url; see
- *     @lotics/app-sdk/router.)
- */
-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;