@chrischall/mcp-utils 0.3.0 → 0.4.0

package/README.md

@@ -27,7 +27,7 @@ import light:
 
 | Import | Contents |
 | --- | --- |
-| `@chrischall/mcp-utils` | core barrel: `server` + `response` + `errors` + `config` + `http` + `zod` + `auth` |
+| `@chrischall/mcp-utils` | core barrel: `server` + `response` + `errors` + `config` + `fs` + `http` + `zod` + `auth` |
 | `@chrischall/mcp-utils/session` | session registry, session store, token manager |
 | `@chrischall/mcp-utils/fetchproxy` | fetchproxy transport adapter, bot-wall / retry / concurrency helpers |
 | `@chrischall/mcp-utils/html` | opt-in HTML scraping helpers (needs `node-html-parser`) |
@@ -115,6 +115,26 @@ const home = expandPath('~/.config/my-mcp');
 `loadDotenvSafely` is a no-throw `.env` loader (returns `false` instead of
 failing when the file is absent).
 
+### `fs` — streaming file helpers (uploads)
+
+`fileBlob`, `readFileHead`.
+
+```ts
+import { fileBlob, readFileHead } from '@chrischall/mcp-utils';
+
+// A file-backed Blob: fetch streams it from disk, never buffered in memory.
+const blob = await fileBlob(path, { type: 'image/jpeg', maxBytes: 20_000_000, label: 'Image' });
+const form = new FormData();
+form.append('file', blob, 'photo.jpg');
+
+// Sniff a header (image dimensions, magic bytes) without reading the whole file.
+const head = await readFileHead(path, 65_536);
+```
+
+Use `fileBlob` in place of `new Blob([readFileSync(path)])` for `FormData` uploads
+— `fs.openAsBlob` backs the Blob with the file on disk, so a 20 MB upload uses
+constant memory instead of a 20 MB Buffer.
+
 ### `http` — bearer API-client kit
 
 `createApiClient` plus building blocks: `buildQueryString`, `buildOptionalBody`,

package/dist/fs/index.d.ts

@@ -0,0 +1,25 @@
+/** Options for {@link fileBlob}. */
+export interface FileBlobOptions {
+    /** MIME type stamped on the Blob (becomes the multipart part's Content-Type). */
+    type?: string;
+    /** Reject (before any upload) when the file is larger than this many bytes. */
+    maxBytes?: number;
+    /** Friendly name for the size-limit error message (e.g. "Image"). */
+    label?: string;
+}
+/**
+ * A **file-backed** `Blob` for streaming multipart uploads. Backed by the file
+ * on disk via `fs.openAsBlob`, so the bytes are NOT read into memory — `fetch`
+ * streams them from disk as it sends the request body. Use in place of
+ * `new Blob([readFileSync(path)])` when building `FormData` for an upload.
+ *
+ * @throws if the file can't be opened, or (when `maxBytes` is set) is too large.
+ */
+export declare function fileBlob(path: string, opts?: FileBlobOptions): Promise<Blob>;
+/**
+ * Read the first `bytes` of a file (for magic-byte / header sniffing — image
+ * dimensions, file-type detection) WITHOUT loading the whole file. Returns only
+ * as many bytes as were actually read (a short file yields a short buffer).
+ */
+export declare function readFileHead(path: string, bytes: number): Promise<Buffer>;
+//# sourceMappingURL=index.d.ts.map

package/dist/fs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fs/index.ts"],"names":[],"mappings":"AAcA,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAatF;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB/E"}

package/dist/fs/index.js

@@ -0,0 +1,58 @@
+// ────────────────────────────────────────────────────────────────────────────
+// Filesystem helpers for multipart uploads — stream files from disk instead of
+// buffering them in memory.
+//
+// The fleet's upload tools (ofw attachments, evite photos, skylight avatars)
+// repeated `new Blob([readFileSync(path)])` → which loads the WHOLE file into a
+// Node Buffer before the request even starts. `fileBlob()` returns a Blob backed
+// by the file on disk (`fs.openAsBlob`), so `fetch` streams the bytes straight
+// off disk as it sends the multipart body — constant memory regardless of size.
+// ────────────────────────────────────────────────────────────────────────────
+import { openAsBlob } from 'node:fs';
+import { open } from 'node:fs/promises';
+/**
+ * A **file-backed** `Blob` for streaming multipart uploads. Backed by the file
+ * on disk via `fs.openAsBlob`, so the bytes are NOT read into memory — `fetch`
+ * streams them from disk as it sends the request body. Use in place of
+ * `new Blob([readFileSync(path)])` when building `FormData` for an upload.
+ *
+ * @throws if the file can't be opened, or (when `maxBytes` is set) is too large.
+ */
+export async function fileBlob(path, opts = {}) {
+    let blob;
+    try {
+        blob = await openAsBlob(path, opts.type !== undefined ? { type: opts.type } : undefined);
+    }
+    catch {
+        throw new Error(`Cannot read file for upload: ${path}`);
+    }
+    if (opts.maxBytes !== undefined && blob.size > opts.maxBytes) {
+        throw new Error(`${opts.label ?? 'File'} is ${blob.size} bytes, over the ${opts.maxBytes}-byte limit: ${path}`);
+    }
+    return blob;
+}
+/**
+ * Read the first `bytes` of a file (for magic-byte / header sniffing — image
+ * dimensions, file-type detection) WITHOUT loading the whole file. Returns only
+ * as many bytes as were actually read (a short file yields a short buffer).
+ */
+export async function readFileHead(path, bytes) {
+    // Wrap the open like `fileBlob` does, so a missing file yields the same clean,
+    // non-leaking message instead of a raw Node ENOENT (path + stack).
+    let fh;
+    try {
+        fh = await open(path, 'r');
+    }
+    catch {
+        throw new Error(`Cannot read file: ${path}`);
+    }
+    try {
+        const buf = Buffer.alloc(bytes);
+        const { bytesRead } = await fh.read(buf, 0, bytes, 0);
+        return buf.subarray(0, bytesRead);
+    }
+    finally {
+        await fh.close();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/fs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/fs/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,+EAA+E;AAC/E,4BAA4B;AAC5B,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,iFAAiF;AACjF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAE/E,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAmB,MAAM,kBAAkB,CAAC;AAYzD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY,EAAE,OAAwB,EAAE;IACrE,IAAI,IAAU,CAAC;IACf,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC3F,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,CAAC,KAAK,IAAI,MAAM,OAAO,IAAI,CAAC,IAAI,oBAAoB,IAAI,CAAC,QAAQ,gBAAgB,IAAI,EAAE,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY,EAAE,KAAa;IAC5D,+EAA+E;IAC/E,mEAAmE;IACnE,IAAI,EAAc,CAAC;IACnB,IAAI,CAAC;QACH,EAAE,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QACtD,OAAO,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACpC,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -17,6 +17,7 @@ export * from './server/index.js';
 export * from './response/index.js';
 export * from './errors/index.js';
 export * from './config/index.js';
+export * from './fs/index.js';
 export * from './http/index.js';
 export * from './zod/index.js';
 export * from './auth/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -17,6 +17,7 @@ export * from './server/index.js';
 export * from './response/index.js';
 export * from './errors/index.js';
 export * from './config/index.js';
+export * from './fs/index.js';
 export * from './http/index.js';
 export * from './zod/index.js';
 export * from './auth/index.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/mcp-utils",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared scaffolding for the chrischall MCP fleet — server bootstrap, tool-result formatting, helpful errors, hardened env/config, a bearer API-client kit, zod atoms, session registries, a fetchproxy transport adapter, auth resolver skeletons, an in-memory test harness, and opt-in HTML helpers. The generic MCP glue hoisted out of ~19 sibling servers.",
   "type": "module",
   "license": "MIT",