@lotics/cli 0.150.1 → 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",
@@ -71401,6 +71503,24 @@ var subjectSchema = zod_default.discriminatedUnion("type", [
   })
 ]);
 var resourceTypeSchema = zod_default.enum(["table", "table_view", "app", "automation", "skill", "document_template", "instruction", "knowledge_doc"]);
+var accessPrincipalSchema = zod_default.discriminatedUnion("type", [
+  zod_default.object({
+    type: zod_default.literal("member").describe("Principal type: an individual member"),
+    id: zod_default.string().describe("Member ID")
+  }),
+  zod_default.object({
+    type: zod_default.literal("member_group").describe("Principal type: a member group"),
+    id: zod_default.string().describe("Group ID")
+  }),
+  zod_default.object({
+    type: zod_default.literal("organization").describe("Principal type: everyone in the organization"),
+    id: zod_default.string().describe("Organization ID")
+  })
+]);
+var resourceAccessSchema = zod_default.object({
+  resource_id: zod_default.string().describe("ID of the resource these principals can reach"),
+  principals: zod_default.array(accessPrincipalSchema).describe("Members, groups and the organization that have been granted access")
+});
 var resourceRoleBindingSchema = zod_default.object({
   id: zod_default.string().describe("Unique identifier for the role binding"),
   principal: principalSchema.describe(
@@ -71553,12 +71673,14 @@ var documentTemplateSchema = zod_default.object({
   id: zod_default.string().describe("Unique identifier for the document template"),
   workspace_id: zod_default.string().describe("ID of the workspace this template belongs to"),
   name: zod_default.string().describe("Display name of the template"),
+  description: zod_default.string().describe("What the template produces, shown under its name in the library"),
   type: documentTemplateTypeSchema,
   template: zod_default.string().describe("Template content with variable placeholders (e.g., {{customer_name}})"),
   format: zod_default.string().describe("Supported document formats.").optional(),
   orientation: zod_default.enum(["portrait", "landscape"]).describe("Page orientation for PDF generation").optional(),
   variables: zod_default.record(zod_default.string(), zod_default.unknown()).describe("Data to pass to the template."),
   current_version: zod_default.number().describe("Current version number of the template"),
+  owner_member_id: zod_default.string().nullable().optional().describe("Member who created the template, from the IAM registry. Absent on write responses."),
   created_at: zod_default.string().describe("Timestamp when template was created"),
   template_url: zod_default.string().nullable().describe("Signed URL to download the template file (pdf-form/excel only)")
 });
@@ -71866,11 +71988,29 @@ var contractKnowledgeEntrySchema = zod_default.object({
     "Display name \u2014 the runtime routing key an agent resolves the doc by; unique across the contract's knowledge"
   ),
   description: zod_default.string().describe("Doc description (may be empty)"),
-  // Optional so contracts published before folders still parse; absent means
-  // root. A curated corpus is exactly the case where organization is authored
-  // deliberately, so install and upgrade have to carry it — otherwise every
-  // installed corpus lands flat and the customer re-files it by hand.
-  path: zod_default.string().optional().describe("Folder the doc is filed under; omitted means root"),
+  // Optional so contracts published before tagging still parse; absent means
+  // untagged. A curated corpus is exactly the case where classification is
+  // authored deliberately, so install and upgrade have to carry it — otherwise
+  // every installed corpus lands unlabelled and the customer re-tags it by hand.
+  //
+  // ABSENT IS NOT EMPTY, and that distinction is load-bearing on the wire: a
+  // contract that says nothing about tags must leave the customer's own labels
+  // alone, or a routine content upgrade silently strips classification the
+  // workspace added. Every reader below branches on `undefined`, never on length.
+  tags: zod_default.array(zod_default.string()).optional().describe("Labels for the doc; omitted leaves existing labels alone"),
+  /**
+   * LEGACY, read-only, removed in a later release.
+   *
+   * Content packages published while knowledge docs had folders carry a `path`,
+   * and those contracts are stored verbatim in the workspaces that installed
+   * them. Dropping the field would make an installed contract fail to parse and
+   * would discard what the publisher declared, so it is still accepted and
+   * mapped to `tags` on install/upgrade (a path's segments were always labels;
+   * the hierarchy merely insisted on an order for them). Nothing EMITS it any
+   * more — `content_bundle` writes `tags` — so it disappears from a package the
+   * first time it is re-published.
+   */
+  path: zod_default.string().optional().describe("Deprecated: pre-tagging folder. Mapped to tags on install."),
   content_ref: zod_default.string().min(1).describe("Path of the content file within the bundle \u2014 must be `knowledge/<alias>.md`"),
   content_sha256: zod_default.string().describe("sha256 (64-char lowercase hex) of the content bytes \u2014 the modified-detection reference")
 });
@@ -72832,6 +72972,18 @@ function appDirName(name2) {
   const cleaned = name2.replace(/[/\\]+/g, "-").replace(/[<>:"|?*]/g, "").replace(/\s+/g, " ").trim().replace(/^[.\s-]+|[.\s-]+$/g, "");
   return cleaned || "app";
 }
+async function materializeScaffold(targetPath, files) {
+  for (const file2 of files) {
+    const fullPath = path9.join(targetPath, file2.path);
+    fs8.mkdirSync(path9.dirname(fullPath), { recursive: true });
+    fs8.writeFileSync(fullPath, file2.content);
+  }
+  console.error(`Scaffolded ${files.length} files into ${targetPath}`);
+  writeAppDts(targetPath, {});
+  console.error("Installing npm dependencies...");
+  await runNpm(["install"], targetPath);
+  writeAppDtsKitLinks(targetPath);
+}
 async function appCreate(client, args) {
   const targetPath = path9.resolve(args.targetPath ?? appDirName(args.name));
   if (fs8.existsSync(targetPath)) {
@@ -72854,16 +73006,7 @@ async function appCreate(client, args) {
     ui_version: `^${uiLatest}`,
     sdk_version: `^${sdkLatest}`
   });
-  for (const file2 of files) {
-    const fullPath = path9.join(targetPath, file2.path);
-    fs8.mkdirSync(path9.dirname(fullPath), { recursive: true });
-    fs8.writeFileSync(fullPath, file2.content);
-  }
-  console.error(`Scaffolded ${files.length} files into ${targetPath}`);
-  writeAppDts(targetPath, {});
-  console.error("Installing npm dependencies...");
-  await runNpm(["install"], targetPath);
-  writeAppDtsKitLinks(targetPath);
+  await materializeScaffold(targetPath, files);
   console.error("Building initial version...");
   await appDeploy(client, {
     projectDir: targetPath,
@@ -74352,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,
@@ -74389,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;
@@ -102750,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
@@ -103353,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);
   }
@@ -103758,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.1",
+  "version": "0.151.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {