@lotics/cli 0.150.2 → 0.151.0

package/dist/src/cli.js

@@ -45132,14 +45132,27 @@ var LoticsClient = class {
     );
   }
   async uploadFiles(filePaths, options) {
-    const formData = new FormData();
+    const items = [];
     for (let i2 = 0; i2 < filePaths.length; i2++) {
       const absolutePath = path2.resolve(filePaths[i2]);
-      const buffer = await fs2.promises.readFile(absolutePath);
-      const filename = options?.filenames?.[i2] ?? path2.basename(absolutePath);
-      const mimeType = getMimeType(filename);
-      const blob = new Blob([buffer], { type: mimeType });
-      formData.append("file", blob, filename);
+      items.push({
+        bytes: await fs2.promises.readFile(absolutePath),
+        filename: options?.filenames?.[i2] ?? path2.basename(absolutePath)
+      });
+    }
+    return this.uploadFileBytes(items);
+  }
+  /**
+   * Store files from bytes the caller already holds — the path for a caller that
+   * never had them on disk (an email attachment decoded in memory, a generated
+   * document, a fetched URL). `uploadFiles` is this with a read in front, so
+   * both routes hit one endpoint and one mime-derivation rule.
+   */
+  async uploadFileBytes(items) {
+    const formData = new FormData();
+    for (const item of items) {
+      const mimeType = item.mimeType ?? getMimeType(item.filename);
+      formData.append("file", new Blob([item.bytes], { type: mimeType }), item.filename);
     }
     const url2 = `${this.baseUrl}/v1/files`;
     const response = await fetch(url2, {
@@ -45152,6 +45165,92 @@ var LoticsClient = class {
   }
 };
 
+// src/upload_source.ts
+var MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
+var URL_FETCH_TIMEOUT_MS = 3e4;
+async function readStdinBytes(limit) {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of process.stdin) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    total += buf.byteLength;
+    if (total > limit) return { tooLarge: true };
+    chunks.push(buf);
+  }
+  return Buffer.concat(chunks);
+}
+function decodeBase64Strict(input) {
+  const text = Buffer.from(input).toString("utf8").trim();
+  const canonical = text.replace(/\s+/g, "").replace(/=+$/, "");
+  if (canonical.length > 0 && !/^[A-Za-z0-9+/]+$/.test(canonical)) return null;
+  const decoded = Buffer.from(text, "base64");
+  if (decoded.toString("base64").replace(/=+$/, "") !== canonical) return null;
+  return decoded;
+}
+function filenameFromResponse(headers, url2) {
+  const disposition = headers.get("content-disposition");
+  const encoded = disposition?.match(/filename\*=\s*(?:UTF-8'')?"?([^";]+)"?/i);
+  const plain = disposition?.match(/filename=\s*"?([^";]+)"?/i);
+  const raw = encoded?.[1] ?? plain?.[1];
+  if (raw) return decodeURIComponent(raw.trim());
+  const last3 = new URL(url2).pathname.split("/").filter(Boolean).pop();
+  return last3 && last3.includes(".") ? decodeURIComponent(last3) : void 0;
+}
+async function resolveUploadSource(sourceFlag, flags) {
+  let bytes;
+  let filename = flags.as;
+  if (flags.url !== void 0) {
+    const controller = new AbortController();
+    const timer2 = setTimeout(() => controller.abort(), URL_FETCH_TIMEOUT_MS);
+    let response;
+    try {
+      response = await fetch(flags.url, { signal: controller.signal });
+    } catch (e) {
+      const reason = controller.signal.aborted ? `no response within ${URL_FETCH_TIMEOUT_MS}ms` : e instanceof Error ? e.message : String(e);
+      return { error: `Fetch failed for ${flags.url}: ${reason}` };
+    } finally {
+      clearTimeout(timer2);
+    }
+    if (!response.ok) {
+      return { error: `Fetch failed: ${response.status} ${response.statusText} for ${flags.url}` };
+    }
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_UPLOAD_BYTES) {
+      return { error: `That URL returns ${declared} bytes; the upload limit is ${MAX_UPLOAD_BYTES}.` };
+    }
+    bytes = new Uint8Array(await response.arrayBuffer());
+    filename ??= filenameFromResponse(response.headers, flags.url);
+  } else {
+    const read = await readStdinBytes(MAX_UPLOAD_BYTES);
+    if ("tooLarge" in read) {
+      return { error: `stdin exceeded the ${MAX_UPLOAD_BYTES}-byte upload limit.` };
+    }
+    if (read.byteLength === 0) {
+      return { error: `${sourceFlag} was given but stdin was empty \u2014 pipe the bytes in.` };
+    }
+    if (flags.base64) {
+      const decoded = decodeBase64Strict(read);
+      if (decoded === null) {
+        return {
+          error: "--base64 input is not valid base64: it contains characters outside the standard alphabet (base64url is not accepted) or is truncated."
+        };
+      }
+      bytes = decoded;
+    } else {
+      bytes = read;
+    }
+  }
+  if (bytes.byteLength > MAX_UPLOAD_BYTES) {
+    return { error: `That is ${bytes.byteLength} bytes; the upload limit is ${MAX_UPLOAD_BYTES}.` };
+  }
+  if (filename === void 0) {
+    return {
+      error: "--as <name> is required: no filename could be derived from the source, and the mime type comes from it."
+    };
+  }
+  return { bytes, filename };
+}
+
 // src/telemetry.ts
 import crypto from "node:crypto";
 import fs3 from "node:fs";
@@ -45928,6 +46027,9 @@ var COMMANDS = [
     aliases: ["upload", "download", "preview"],
     help: [
       "  lotics file upload <file|dir...>     Upload files (alias: lotics upload)",
+      "  lotics file upload --stdin --as <name>",
+      "                                       Upload bytes you already hold, piped on stdin",
+      "                                       (--base64 for base64; --url <url> to fetch first)",
       "  lotics file download <file_id>       Download a file by ID (alias: lotics download)",
       "  lotics file download record <record_id> <field_key>",
       "                                       Download all files on a record file field",
@@ -74393,6 +74495,9 @@ function parseArgs(argv) {
   const flags = {
     json: false,
     force: false,
+    stdin: false,
+    base64: false,
+    url: void 0,
     fromVersion: void 0,
     timeout: void 0,
     output: void 0,
@@ -74430,6 +74535,15 @@ function parseArgs(argv) {
       case "--force":
         flags.force = true;
         break;
+      case "--stdin":
+        flags.stdin = true;
+        break;
+      case "--base64":
+        flags.base64 = true;
+        break;
+      case "--url":
+        flags.url = argv[++i2];
+        break;
       case "--from-version":
         flags.fromVersion = argv[++i2];
         break;
@@ -102791,7 +102905,10 @@ FLAGS
   --json             Full JSON output (default is human-readable text)
   --timeout <ms>     Timeout for tool execution (default: 60000)
   -o <path>          Output dir for downloads
-  --as <name>        Override upload filename
+  --as <name>        Override upload filename (required with --stdin/--base64)
+  --stdin            Upload raw bytes piped on stdin instead of a path
+  --base64           Upload base64 piped on stdin (decoded strictly)
+  --url <url>        Fetch a URL and upload what it returns
   --api-key <key>    One-off API key (overrides saved config + env)
   --workspace <id>   One-off workspace override (alias: -w)
   --view-as <id>     Admin "View as": run every request as this member, so
@@ -103394,8 +103511,12 @@ async function main() {
     console.error('Run "lotics tools" to see available tools.');
     process.exit(1);
   }
-  if (command === "upload" && !subcommand) {
-    console.error("Usage: lotics upload <file|dir...> [--as <name>]");
+  if (command === "upload" && !subcommand && !flags.stdin && !flags.base64 && !flags.url) {
+    console.error("Usage:");
+    console.error("  lotics upload <file|dir...> [--as <name>]");
+    console.error("  lotics upload --stdin --as <name>     Raw bytes on stdin");
+    console.error("  lotics upload --base64 --as <name>    Base64 on stdin");
+    console.error("  lotics upload --url <url> [--as <name>]");
     console.error("Uploads files and returns their file_ids. Directories expand to their immediate files.");
     process.exit(1);
   }
@@ -103799,19 +103920,39 @@ ${JSON.stringify(info.input_schema, null, 2)}`);
     return;
   }
   if (command === "upload") {
-    const rawPaths = [subcommand, ...toolArgs ? [toolArgs] : [], ...restArgs];
-    const filePaths = resolveUploadPaths(rawPaths);
-    if (filePaths.length === 0) {
-      console.error("No files found in the specified paths.");
+    const sources = [flags.stdin && "--stdin", flags.base64 && "--base64", flags.url && "--url"].filter(Boolean);
+    if (sources.length > 1) {
+      console.error(`Pick one source: ${sources.join(", ")} were all given.`);
       process.exit(1);
     }
-    if (flags.as && filePaths.length > 1) {
-      console.error("Cannot use --as with multiple files.");
-      process.exit(1);
+    let upload;
+    if (sources.length === 1) {
+      const positional = [subcommand, toolArgs, ...restArgs].filter((v) => v !== void 0);
+      if (positional.length > 0) {
+        console.error(`${sources[0]} reads the bytes itself \u2014 drop the path argument (${positional.join(", ")}).`);
+        process.exit(1);
+      }
+      const resolved = await resolveUploadSource(String(sources[0]), flags);
+      if ("error" in resolved) {
+        console.error(resolved.error);
+        process.exit(1);
+      }
+      upload = await client.uploadFileBytes([resolved]);
+    } else {
+      const rawPaths = [subcommand, ...toolArgs ? [toolArgs] : [], ...restArgs];
+      const filePaths = resolveUploadPaths(rawPaths);
+      if (filePaths.length === 0) {
+        console.error("No files found in the specified paths.");
+        process.exit(1);
+      }
+      if (flags.as && filePaths.length > 1) {
+        console.error("Cannot use --as with multiple files.");
+        process.exit(1);
+      }
+      upload = await client.uploadFiles(filePaths, {
+        filenames: flags.as ? [flags.as] : void 0
+      });
     }
-    const upload = await client.uploadFiles(filePaths, {
-      filenames: flags.as ? [flags.as] : void 0
-    });
     if (upload.files.length === 0 && upload.errors.length > 0) {
       console.error(`Upload failed: ${upload.errors.map((e) => `${e.filename}: ${e.error}`).join(", ")}`);
       process.exit(1);

package/dist/src/client.d.ts

@@ -1112,4 +1112,15 @@ export declare class LoticsClient {
     uploadFiles(filePaths: string[], options?: {
         filenames?: string[];
     }): Promise<FileUploadResult>;
+    /**
+     * Store files from bytes the caller already holds — the path for a caller that
+     * never had them on disk (an email attachment decoded in memory, a generated
+     * document, a fetched URL). `uploadFiles` is this with a read in front, so
+     * both routes hit one endpoint and one mime-derivation rule.
+     */
+    uploadFileBytes(items: {
+        bytes: Uint8Array<ArrayBuffer>;
+        filename: string;
+        mimeType?: string;
+    }[]): Promise<FileUploadResult>;
 }

package/dist/src/client.js

@@ -846,14 +846,40 @@ export class LoticsClient {
         }));
     }
     async uploadFiles(filePaths, options) {
-        const formData = new FormData();
+        // Sequential, not `Promise.all`: `lotics upload <dir>` expands a directory to
+        // every file in it, and reading them all at once opens one handle per file —
+        // EMFILE on a large directory. The upload itself is a single request either
+        // way, so concurrency here buys nothing.
+        const items = [];
         for (let i = 0; i < filePaths.length; i++) {
             const absolutePath = path.resolve(filePaths[i]);
-            const buffer = await fs.promises.readFile(absolutePath);
-            const filename = options?.filenames?.[i] ?? path.basename(absolutePath);
-            const mimeType = getMimeType(filename);
-            const blob = new Blob([buffer], { type: mimeType });
-            formData.append("file", blob, filename);
+            items.push({
+                bytes: await fs.promises.readFile(absolutePath),
+                filename: options?.filenames?.[i] ?? path.basename(absolutePath),
+            });
+        }
+        return this.uploadFileBytes(items);
+    }
+    /**
+     * Store files from bytes the caller already holds — the path for a caller that
+     * never had them on disk (an email attachment decoded in memory, a generated
+     * document, a fetched URL). `uploadFiles` is this with a read in front, so
+     * both routes hit one endpoint and one mime-derivation rule.
+     */
+    async uploadFileBytes(
+    // `Uint8Array<ArrayBuffer>`, not a bare `Uint8Array`: `Blob` takes a
+    // `BufferSource`, which excludes a `SharedArrayBuffer`-backed view. Every
+    // real source here (`readFile`, `Buffer.concat`, `response.arrayBuffer()`)
+    // is already ArrayBuffer-backed, so the narrower type states the
+    // requirement rather than casting it away at the call site.
+    items) {
+        const formData = new FormData();
+        for (const item of items) {
+            const mimeType = item.mimeType ?? getMimeType(item.filename);
+            // `Blob` copies a BufferSource by the VIEW's offset+length, so passing a
+            // pooled `Buffer` from `readFile` straight in is correct — no defensive
+            // re-copy, which would double peak memory on every upload.
+            formData.append("file", new Blob([item.bytes], { type: mimeType }), item.filename);
         }
         const url = `${this.baseUrl}/v1/files`;
         const response = await fetch(url, {

package/docs/cli_reference.md

@@ -22,7 +22,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics tools <name>` | Full description + JSON Schema for one tool |
 | `lotics run <tool> '<json>'` | Execute a tool (text output via toModelOutput). Args may also come from a file (`lotics run <tool> @args.json`) or piped stdin (`cat args.json \| lotics run <tool>`) — both bypass the OS `ARG_MAX` limit for large payloads (a knowledge-doc `content`, a bulk update). A leading `@` on the args is unambiguously a file path (JSON args start with `{`). |
 | `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |
-| `lotics upload <file\|dir...>` | Upload files/directories via multipart POST to /v1/files |
+| `lotics upload <file\|dir...>` · `--stdin` · `--base64` · `--url <url>` | Upload files/directories via multipart POST to /v1/files. A directory expands to its immediate files; `--as <name>` renames a single upload. **Three alternative byte sources, for a caller that never had the bytes on disk** — an attachment decoded in memory, a generated document, a signed download link — each mutually exclusive with the others and with a path argument: `--stdin` takes raw bytes on stdin, `--base64` takes base64 on stdin (the shape attachments arrive in), `--url <url>` fetches the URL first. `--stdin`/`--base64` REQUIRE `--as`, because stdin carries no filename and the mime type is derived from it; `--url` falls back to `Content-Disposition` then the URL's last path segment. `--base64` decodes STRICTLY — `Buffer.from(s, "base64")` silently skips invalid characters and truncates on bad padding, so a corrupted pipe would otherwise store a short file that only fails when a human opens it. The `--url` fetch happens in the CLI, not the server: the URL comes from the operator running the command, so routing it through the backend would add an SSRF surface to buy what `curl` already does. |
 | `lotics file download <file_id> [-o <dir>]` | (alias `lotics download`) Download a stored file: `GET /v1/files/{id}/signed_url` → fetch the presigned URL, saving under the stored filename (from the response's `Content-Disposition`) into `-o` (a **DIRECTORY** — note this is distinct from `lotics file preview`'s `-o`, which is a FILE path), else cwd. `lotics file download record <record_id> <field_key>` pulls every file on a record's file field. |
 | `lotics knowledge list` | List knowledge docs via the `list_knowledge` tool — a table of id, name, description (`--json` for the raw results array). |
 | `lotics knowledge create --name <n> [--description <d>] (--from <file.md> \| --content <str>)` | Read the body client-side (a file XOR an inline string — exactly one required), then call `create_knowledge` with `{ name, description, content }` (description defaults to `""`). Prints the new id to stdout. Large files ride the POST body fine. |

package/package.json

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