@lotics/cli 0.51.0 → 0.51.1

package/dist/app_commands.d.ts

@@ -63,6 +63,17 @@ export declare function stampPulledManifest(projectDir: string, args: {
     queries: Record<string, AppQueryDeclaration>;
     agents: Record<string, AppAgentDeclaration>;
 }): void;
+/**
+ * A filesystem-safe SINGLE directory segment from an app's free-form display
+ * name, for the default create/pull target. App names may contain "/" (and
+ * other path-hostile characters); used verbatim as a directory, a name like
+ * "Nhập/Xuất Cont" splits into NESTED folders ("Nhập" → "Xuất Cont") — and a
+ * deploy then packages that nested copy into the source archive, so each later
+ * pull re-extracts and compounds it. Neutralize path separators + reserved
+ * characters to one segment, keeping spaces and unicode so the folder stays
+ * recognizable. An explicit `targetPath` still overrides this entirely.
+ */
+export declare function appDirName(name: string): string;
 /**
  * `lotics app create <name> [path]`
  *

package/dist/app_commands.js

@@ -149,6 +149,25 @@ async function downloadToFile(url, destPath) {
     const buffer = Buffer.from(await response.arrayBuffer());
     fs.writeFileSync(destPath, buffer);
 }
+/**
+ * A filesystem-safe SINGLE directory segment from an app's free-form display
+ * name, for the default create/pull target. App names may contain "/" (and
+ * other path-hostile characters); used verbatim as a directory, a name like
+ * "Nhập/Xuất Cont" splits into NESTED folders ("Nhập" → "Xuất Cont") — and a
+ * deploy then packages that nested copy into the source archive, so each later
+ * pull re-extracts and compounds it. Neutralize path separators + reserved
+ * characters to one segment, keeping spaces and unicode so the folder stays
+ * recognizable. An explicit `targetPath` still overrides this entirely.
+ */
+export function appDirName(name) {
+    const cleaned = name
+        .replace(/[/\\]+/g, "-") // path separators — the core bug
+        .replace(/[<>:"|?*]/g, "") // other filesystem-reserved characters
+        .replace(/\s+/g, " ") // collapse whitespace runs
+        .trim()
+        .replace(/^[.\s-]+|[.\s-]+$/g, ""); // no leading/trailing dot/space/dash → never "."/".."/hidden/blank
+    return cleaned || "app";
+}
 /**
  * `lotics app create <name> [path]`
  *
@@ -164,7 +183,7 @@ async function downloadToFile(url, destPath) {
  * with CLI releases. (Server-side build is the v2 path.)
  */
 export async function appCreate(client, args) {
-    const targetPath = path.resolve(args.targetPath ?? args.name);
+    const targetPath = path.resolve(args.targetPath ?? appDirName(args.name));
     if (fs.existsSync(targetPath)) {
         const entries = fs.readdirSync(targetPath);
         if (entries.length > 0) {
@@ -259,7 +278,7 @@ export async function appPull(client, args) {
     }
     const version = await client.getAppVersion(app.id, app.current_version_id);
     const sourceUrl = await client.getAppVersionSourceUrl(app.id, version.id);
-    const targetPath = path.resolve(args.targetPath ?? app.name);
+    const targetPath = path.resolve(args.targetPath ?? appDirName(app.name));
     fs.mkdirSync(targetPath, { recursive: true });
     // Download to a temp file because `tar -xz` reads from a real path.
     const tmpFile = path.join(tmpdir(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);

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, undeclaredCapabilities } from "./app_commands.js";
+import { stampPulledManifest, undeclaredCapabilities, appDirName } 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
@@ -135,3 +135,25 @@ describe("undeclaredCapabilities", () => {
         expect(undeclaredCapabilities(`await deleteComment(id);`, {})).toEqual(["comments"]);
     });
 });
+describe("appDirName", () => {
+    it("collapses a slash in the name to a single segment (the create/pull nesting bug)", () => {
+        // A "/" in the name used to split the create/pull target into nested folders
+        // ("Nhập" → "Xuất Cont") and compound on each pull.
+        expect(appDirName("Nhập/Xuất Cont")).toBe("Nhập-Xuất Cont");
+        expect(appDirName("a/b/c")).toBe("a-b-c");
+        expect(appDirName("a\\b")).toBe("a-b");
+    });
+    it("leaves an ordinary name untouched (no regression for the common case)", () => {
+        expect(appDirName("Sales Tracker")).toBe("Sales Tracker");
+        expect(appDirName("crm")).toBe("crm");
+    });
+    it("strips reserved characters and collapses whitespace", () => {
+        expect(appDirName('Report: "Q1" <draft>')).toBe("Report Q1 draft");
+    });
+    it("never yields a traversal, hidden, or empty directory", () => {
+        expect(appDirName("../etc")).toBe("etc"); // "/"→"-", then leading dot/dash run stripped
+        expect(appDirName(".hidden")).toBe("hidden");
+        expect(appDirName("   ")).toBe("app");
+        expect(appDirName("///")).toBe("app"); // separators → "-", a dir of only "-" falls back
+    });
+});

package/dist/client.d.ts

@@ -216,6 +216,16 @@ export declare class LoticsClient {
      * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
      */
     appWorkflow(app_id: string, alias: string, inputs: unknown): Promise<unknown>;
+    /**
+     * Open a streaming agent run and return the RAW streamed `Response` (the
+     * caller reads `res.body`). Unlike `request`, this does not buffer/parse the
+     * body — it's the SSE stream the `lotics app dev` harness proxies to the
+     * iframe. Mirrors POST /v1/apps/{app_id}/agents/{alias}/runs.
+     */
+    appAgentRunStream(app_id: string, alias: string, body: {
+        session_id: string;
+        input: Record<string, unknown>;
+    }, signal?: AbortSignal): Promise<Response>;
     /**
      * Mint a presigned URL for uploading a file into an app. Mirrors
      * POST /v1/apps/{app_id}/files/upload-url.

package/dist/client.js

@@ -202,6 +202,23 @@ export class LoticsClient {
     async appWorkflow(app_id, alias, inputs) {
         return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/execute`, { inputs });
     }
+    /**
+     * Open a streaming agent run and return the RAW streamed `Response` (the
+     * caller reads `res.body`). Unlike `request`, this does not buffer/parse the
+     * body — it's the SSE stream the `lotics app dev` harness proxies to the
+     * iframe. Mirrors POST /v1/apps/{app_id}/agents/{alias}/runs.
+     */
+    async appAgentRunStream(app_id, alias, body, signal) {
+        const res = await fetch(`${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agents/${encodeURIComponent(alias)}/runs`, {
+            method: "POST",
+            headers: { ...this.buildHeaders(), "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal,
+        });
+        if (!res.ok)
+            await this.throwResponseError(res);
+        return res;
+    }
     /**
      * Mint a presigned URL for uploading a file into an app. Mirrors
      * POST /v1/apps/{app_id}/files/upload-url.

package/dist/dev/server.js

@@ -116,6 +116,57 @@ export async function startDevServer(args) {
             }
             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;
+        }
         res.writeHead(404, { "Content-Type": "text/plain" });
         res.end("Not Found");
     });

package/dist/dev/wrapper_page.d.ts

@@ -20,6 +20,8 @@
  * 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" }.
  */
 export interface WrapperPageArgs {
     app_name: string;

package/dist/dev/wrapper_page.js

@@ -20,6 +20,8 @@
  * 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" }.
  */
 export function buildWrapperPage(args) {
     const { app_name, app_id, workspace_id, vite_url, api_url } = args;
@@ -161,10 +163,61 @@ export function buildWrapperPage(args) {
         return undefined;
       }
 
+      // Streaming agent runs (op "agentRun"): the response is a stream, so it
+      // can't use rpc()'s single JSON round-trip. POST /_agent_run, read the SSE
+      // body, and forward chunks to the iframe as the SDK's bridged streaming
+      // protocol expects (stream-chunk* -> stream-end). Mirrors the production
+      // host in frontend/features/app_ui/app_iframe_host.tsx.
+      const streamingRuns = {};
+      async function handleAgentRun(id, payload) {
+        const controller = new AbortController();
+        streamingRuns[id] = controller;
+        try {
+          const res = await fetch("/_agent_run", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ app_id: APP_ID, op: "agentRun", payload: payload }),
+            signal: controller.signal,
+          });
+          if (!res.ok || !res.body) {
+            let detail = await res.text().catch(function () { return ""; });
+            try { detail = JSON.parse(detail).message || detail; } catch (_) {}
+            throw new Error(detail || ("HTTP " + res.status));
+          }
+          const reader = res.body.getReader();
+          const decoder = new TextDecoder();
+          for (;;) {
+            const r = await reader.read();
+            if (r.done) break;
+            iframe.contentWindow.postMessage(
+              { id: id, type: "stream-chunk", chunk: decoder.decode(r.value, { stream: true }) },
+              VITE_ORIGIN
+            );
+          }
+          const tail = decoder.decode();
+          if (tail) iframe.contentWindow.postMessage({ id: id, type: "stream-chunk", chunk: tail }, VITE_ORIGIN);
+          iframe.contentWindow.postMessage({ id: id, type: "stream-end" }, VITE_ORIGIN);
+        } catch (err) {
+          if (controller.signal.aborted) return;
+          const message = err && err.message ? err.message : String(err);
+          iframe.contentWindow.postMessage({ id: id, type: "error", message: message }, VITE_ORIGIN);
+        } finally {
+          delete streamingRuns[id];
+        }
+      }
+
       window.addEventListener("message", async function (event) {
         if (event.source !== iframe.contentWindow || event.origin !== VITE_ORIGIN) return;
         const msg = event.data;
-        if (!msg || typeof msg.id !== "number" || typeof msg.op !== "string") return;
+        if (!msg || typeof msg.id !== "number") return;
+        // Abort an in-flight streaming run (control message, carries no op).
+        if (msg.type === "abort") {
+          if (streamingRuns[msg.id]) { streamingRuns[msg.id].abort(); delete streamingRuns[msg.id]; }
+          return;
+        }
+        if (typeof msg.op !== "string") return;
+        // Streaming agent run — many messages back, not a single result.
+        if (msg.op === "agentRun") { handleAgentRun(msg.id, msg.payload); return; }
         const startedAt = performance.now();
         try {
           const data = msg.op === "upload"

package/dist/src/cli.js

@@ -29791,6 +29791,25 @@ var LoticsClient = class {
       { inputs }
     );
   }
+  /**
+   * Open a streaming agent run and return the RAW streamed `Response` (the
+   * caller reads `res.body`). Unlike `request`, this does not buffer/parse the
+   * body — it's the SSE stream the `lotics app dev` harness proxies to the
+   * iframe. Mirrors POST /v1/apps/{app_id}/agents/{alias}/runs.
+   */
+  async appAgentRunStream(app_id, alias, body, signal) {
+    const res = await fetch(
+      `${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agents/${encodeURIComponent(alias)}/runs`,
+      {
+        method: "POST",
+        headers: { ...this.buildHeaders(), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal
+      }
+    );
+    if (!res.ok) await this.throwResponseError(res);
+    return res;
+  }
   /**
    * Mint a presigned URL for uploading a file into an app. Mirrors
    * POST /v1/apps/{app_id}/files/upload-url.
@@ -30304,7 +30323,12 @@ function buildStarterTemplate(args) {
           // Restrict tsc to the project's own sources. tsgo follows
           // transitive imports into node_modules — strict rules
           // (noUnusedLocals etc.) would fire on @lotics/ui's source.
-          include: ["src", ".lotics"],
+          // `.lotics/**/*` (not bare `.lotics`): TypeScript's include glob walk
+          // SKIPS dot-directories, so a bare `.lotics` silently loads zero of the
+          // generated `.d.ts` augmentations and typed useWorkflow/useQuery/useAgentRun
+          // fall to `unknown`. The explicit glob makes the dot-dir the non-wildcard
+          // base, which IS read. (GAP-38.)
+          include: ["src", ".lotics/**/*"],
           exclude: ["node_modules"]
         },
         null,
@@ -31023,10 +31047,61 @@ function buildWrapperPage(args) {
         return undefined;
       }
 
+      // Streaming agent runs (op "agentRun"): the response is a stream, so it
+      // can't use rpc()'s single JSON round-trip. POST /_agent_run, read the SSE
+      // body, and forward chunks to the iframe as the SDK's bridged streaming
+      // protocol expects (stream-chunk* -> stream-end). Mirrors the production
+      // host in frontend/features/app_ui/app_iframe_host.tsx.
+      const streamingRuns = {};
+      async function handleAgentRun(id, payload) {
+        const controller = new AbortController();
+        streamingRuns[id] = controller;
+        try {
+          const res = await fetch("/_agent_run", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ app_id: APP_ID, op: "agentRun", payload: payload }),
+            signal: controller.signal,
+          });
+          if (!res.ok || !res.body) {
+            let detail = await res.text().catch(function () { return ""; });
+            try { detail = JSON.parse(detail).message || detail; } catch (_) {}
+            throw new Error(detail || ("HTTP " + res.status));
+          }
+          const reader = res.body.getReader();
+          const decoder = new TextDecoder();
+          for (;;) {
+            const r = await reader.read();
+            if (r.done) break;
+            iframe.contentWindow.postMessage(
+              { id: id, type: "stream-chunk", chunk: decoder.decode(r.value, { stream: true }) },
+              VITE_ORIGIN
+            );
+          }
+          const tail = decoder.decode();
+          if (tail) iframe.contentWindow.postMessage({ id: id, type: "stream-chunk", chunk: tail }, VITE_ORIGIN);
+          iframe.contentWindow.postMessage({ id: id, type: "stream-end" }, VITE_ORIGIN);
+        } catch (err) {
+          if (controller.signal.aborted) return;
+          const message = err && err.message ? err.message : String(err);
+          iframe.contentWindow.postMessage({ id: id, type: "error", message: message }, VITE_ORIGIN);
+        } finally {
+          delete streamingRuns[id];
+        }
+      }
+
       window.addEventListener("message", async function (event) {
         if (event.source !== iframe.contentWindow || event.origin !== VITE_ORIGIN) return;
         const msg = event.data;
-        if (!msg || typeof msg.id !== "number" || typeof msg.op !== "string") return;
+        if (!msg || typeof msg.id !== "number") return;
+        // Abort an in-flight streaming run (control message, carries no op).
+        if (msg.type === "abort") {
+          if (streamingRuns[msg.id]) { streamingRuns[msg.id].abort(); delete streamingRuns[msg.id]; }
+          return;
+        }
+        if (typeof msg.op !== "string") return;
+        // Streaming agent run \u2014 many messages back, not a single result.
+        if (msg.op === "agentRun") { handleAgentRun(msg.id, msg.payload); return; }
         const startedAt = performance.now();
         try {
           const data = msg.op === "upload"
@@ -31142,6 +31217,49 @@ async function startDevServer(args) {
       }
       return;
     }
+    if (req.method === "POST" && url === "/_agent_run") {
+      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 (err2) {
+        if (ac.signal.aborted) {
+          res.end();
+          return;
+        }
+        const message = err2 instanceof Error ? err2.message : String(err2);
+        process.stderr.write(`[agent_run] ERROR ${message}
+`);
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ message }));
+        } else {
+          res.end();
+        }
+      }
+      return;
+    }
     res.writeHead(404, { "Content-Type": "text/plain" });
     res.end("Not Found");
   });
@@ -31559,8 +31677,12 @@ async function downloadToFile(url, destPath) {
   const buffer = Buffer.from(await response.arrayBuffer());
   fs3.writeFileSync(destPath, buffer);
 }
+function appDirName(name) {
+  const cleaned = name.replace(/[/\\]+/g, "-").replace(/[<>:"|?*]/g, "").replace(/\s+/g, " ").trim().replace(/^[.\s-]+|[.\s-]+$/g, "");
+  return cleaned || "app";
+}
 async function appCreate(client, args) {
-  const targetPath = path4.resolve(args.targetPath ?? args.name);
+  const targetPath = path4.resolve(args.targetPath ?? appDirName(args.name));
   if (fs3.existsSync(targetPath)) {
     const entries = fs3.readdirSync(targetPath);
     if (entries.length > 0) {
@@ -31621,7 +31743,7 @@ async function appPull(client, args) {
   }
   const version = await client.getAppVersion(app.id, app.current_version_id);
   const sourceUrl = await client.getAppVersionSourceUrl(app.id, version.id);
-  const targetPath = path4.resolve(args.targetPath ?? app.name);
+  const targetPath = path4.resolve(args.targetPath ?? appDirName(app.name));
   fs3.mkdirSync(targetPath, { recursive: true });
   const tmpFile = path4.join(tmpdir(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);
   console.error(`Downloading source archive...`);
@@ -38305,6 +38427,12 @@ function emptyStyleResolver() {
 var xmlParser3 = new XMLParser({
   ignoreAttributes: false,
   attributeNamePrefix: "@_",
+  // Shared-string and workbook text is textual BY DEFINITION (tax IDs, phone
+  // numbers, account codes, sheet/defined names). fast-xml-parser's default tag
+  // coercion would parse `<t>0312345678</t>` as the number 312345678 — silently
+  // dropping the leading zero before we can read it. Cell `<v>` numerics are
+  // parsed deliberately (parseFloat) in ooxml_sheet.ts, so this never affects them.
+  parseTagValue: false,
   trimValues: false,
   processEntities: false,
   isArray: (tagName) => tagName === "sheet" || tagName === "si" || tagName === "r" || tagName === "Relationship" || tagName === "definedName"

package/dist/starter_template.js

@@ -126,7 +126,12 @@ export function buildStarterTemplate(args) {
                 // Restrict tsc to the project's own sources. tsgo follows
                 // transitive imports into node_modules — strict rules
                 // (noUnusedLocals etc.) would fire on @lotics/ui's source.
-                include: ["src", ".lotics"],
+                // `.lotics/**/*` (not bare `.lotics`): TypeScript's include glob walk
+                // SKIPS dot-directories, so a bare `.lotics` silently loads zero of the
+                // generated `.d.ts` augmentations and typed useWorkflow/useQuery/useAgentRun
+                // fall to `unknown`. The explicit glob makes the dot-dir the non-wildcard
+                // base, which IS read. (GAP-38.)
+                include: ["src", ".lotics/**/*"],
                 exclude: ["node_modules"],
             }, null, 2) + "\n",
         },

package/package.json

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