@fgv/ts-http-storage 5.1.0-5 → 5.1.0-50

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erik Fortune
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/ts-http-storage.d.ts

@@ -23,7 +23,7 @@ export declare class FsStorageProvider implements IHttpStorageProvider {
     constructor(rootPath: string);
     getItem(itemPath: string): Promise<Result<IStorageTreeItem>>;
     getChildren(itemPath: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>>;
-    getFile(itemPath: string): Promise<Result<IStorageFileResponse>>;
+    getFile(itemPath: string, encoding?: StorageContentEncoding): Promise<Result<IStorageFileResponse>>;
     saveFile(itemPath: string, contents: string, contentType?: string): Promise<Result<IStorageFileResponse>>;
     deleteFile(itemPath: string): Promise<Result<boolean>>;
     createDirectory(itemPath: string): Promise<Result<IStorageTreeItem>>;
@@ -51,7 +51,7 @@ export declare class HttpStorageService {
     constructor(providers: IHttpStorageProviderFactory);
     getItem(request: IStoragePathRequest): Promise<Result<IStorageTreeItem>>;
     getChildren(request: IStoragePathRequest): Promise<Result<IStorageTreeChildrenResponse>>;
-    getFile(request: IStoragePathRequest): Promise<Result<IStorageFileResponse>>;
+    getFile(request: IStorageReadFileRequest): Promise<Result<IStorageFileResponse>>;
     saveFile(request: IStorageWriteFileRequest): Promise<Result<IStorageFileResponse>>;
     deleteFile(request: IStoragePathRequest): Promise<Result<boolean>>;
     createDirectory(request: IStoragePathRequest): Promise<Result<IStorageTreeItem>>;
@@ -84,7 +84,15 @@ export declare interface IFsStorageProviderFactoryOptions {
 export declare interface IHttpStorageProvider {
     getItem(path: string): Promise<Result<IStorageTreeItem>>;
     getChildren(path: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>>;
-    getFile(path: string): Promise<Result<IStorageFileResponse>>;
+    /**
+     * Reads a file.
+     * @param path - Path of the file to read.
+     * @param encoding - Preferred wire encoding for the returned `contents`. A
+     * provider that does not implement the requested encoding MUST answer in
+     * `'utf8'` and report that on the response, rather than failing — the field is
+     * a preference and the response is the authority.
+     */
+    getFile(path: string, encoding?: StorageContentEncoding): Promise<Result<IStorageFileResponse>>;
     saveFile(path: string, contents: string, contentType?: string): Promise<Result<IStorageFileResponse>>;
     deleteFile(path: string): Promise<Result<boolean>>;
     createDirectory(path: string): Promise<Result<IStorageTreeItem>>;
@@ -107,6 +115,19 @@ export declare interface IStorageFileResponse {
     readonly path: string;
     readonly contents: string;
     readonly contentType?: string;
+    /**
+     * How `contents` is encoded. Absent means `'utf8'`.
+     *
+     * @remarks
+     * **This field describes what the server actually produced, not what the
+     * client asked for**, and a client must branch on it rather than on its own
+     * request. A provider that does not implement `'base64'` ignores the request
+     * and answers with UTF-8 text; a client that base64-decoded on the strength of
+     * having *asked* would corrupt every such response. Trusting the field instead
+     * makes an older or simpler provider degrade to today's behavior rather than
+     * to garbage.
+     */
+    readonly encoding?: StorageContentEncoding;
 }
 
 /**
@@ -118,6 +139,27 @@ export declare interface IStoragePathRequest {
     readonly namespace?: StorageNamespace;
 }
 
+/**
+ * Request for reading a file, with an optional preferred content encoding.
+ *
+ * @remarks
+ * `encoding` is a *preference*, not a demand: a provider that cannot honour it
+ * answers in `'utf8'` and says so on {@link IStorageFileResponse.encoding}. The
+ * response is the authority.
+ * @public
+ */
+export declare interface IStorageReadFileRequest extends IStoragePathRequest {
+    /**
+     * Preferred wire encoding for the response's `contents`. Absent means `'utf8'`.
+     *
+     * @remarks
+     * A preference, not a demand — see {@link IStorageFileResponse.encoding}, which
+     * reports what the server actually produced and is the field a client must
+     * branch on.
+     */
+    readonly encoding?: StorageContentEncoding;
+}
+
 /**
  * Request for sync operation.
  * @public
@@ -174,6 +216,29 @@ export declare function normalizeRequestPath(requestPath: string): string;
  */
 export declare function sanitizeNamespace(namespace?: string): Result<string>;
 
+/**
+ * How a file's bytes are represented in the `contents` field on the wire.
+ *
+ * @remarks
+ * - `'utf8'` — `contents` is the file decoded as UTF-8 text. This is the
+ *   historical (and default) representation, and it is **lossy**: the decode is
+ *   the lenient WHATWG one, so any byte sequence that is not valid UTF-8 has
+ *   already been replaced by U+FFFD by the time it reaches the wire, and the
+ *   substitution is not recoverable downstream.
+ * - `'base64'` — `contents` is the file's bytes, base64-encoded. Byte-faithful
+ *   and therefore the only representation over which a consumer can decide
+ *   whether the stored bytes were valid UTF-8, or read genuinely binary content.
+ *   Costs roughly 33% more payload.
+ * @public
+ */
+export declare type StorageContentEncoding = 'utf8' | 'base64';
+
+/**
+ * Converter for the wire content encoding.
+ * @public
+ */
+export declare const storageContentEncoding: Converter<StorageContentEncoding>;
+
 /**
  * Converter for file responses.
  * @public
@@ -198,6 +263,12 @@ export declare type StorageNamespace = string;
  */
 export declare const storagePathRequest: Converter<IStoragePathRequest>;
 
+/**
+ * Converter for read-file requests.
+ * @public
+ */
+export declare const storageReadFileRequest: Converter<IStorageReadFileRequest>;
+
 /**
  * Converter for sync requests.
  * @public

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.57.7"
+      "packageVersion": "7.58.9"
     }
   ]
 }

package/eslint.config.js

@@ -0,0 +1,16 @@
+// ESLint 9 flat config
+const nodeProfile = require('@rushstack/eslint-config/flat/profile/node');
+const packletsPlugin = require('@rushstack/eslint-config/flat/mixins/packlets');
+const tsdocPlugin = require('@rushstack/eslint-config/flat/mixins/tsdoc');
+
+module.exports = [
+  ...nodeProfile,
+  packletsPlugin,
+  ...tsdocPlugin,
+  {
+    // Override specific rules if needed
+    rules: {
+      '@rushstack/packlets/mechanics': 'warn'
+    }
+  }
+];

package/lib/packlets/storage/converters.d.ts

@@ -1,5 +1,5 @@
 import { type Converter } from '@fgv/ts-utils';
-import type { IStorageFileResponse, IStoragePathRequest, IStorageSyncRequest, IStorageTreeChildrenResponse, IStorageTreeItem, IStorageWriteFileRequest } from './model';
+import type { IStorageFileResponse, IStoragePathRequest, IStorageReadFileRequest, IStorageSyncRequest, IStorageTreeChildrenResponse, IStorageTreeItem, IStorageWriteFileRequest, StorageContentEncoding } from './model';
 /**
  * Converter for {@link IStorageTreeItem}.
  * @public
@@ -10,6 +10,16 @@ export declare const storageTreeItem: Converter<IStorageTreeItem>;
  * @public
  */
 export declare const storagePathRequest: Converter<IStoragePathRequest>;
+/**
+ * Converter for the wire content encoding.
+ * @public
+ */
+export declare const storageContentEncoding: Converter<StorageContentEncoding>;
+/**
+ * Converter for read-file requests.
+ * @public
+ */
+export declare const storageReadFileRequest: Converter<IStorageReadFileRequest>;
 /**
  * Converter for write-file requests.
  * @public

package/lib/packlets/storage/converters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../../../src/packlets/storage/converters.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,KAAK,SAAS,EAAc,MAAM,eAAe,CAAC;AAE3D,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,4BAA4B,EAC5B,gBAAgB,EAChB,wBAAwB,EAEzB,MAAM,SAAS,CAAC;AAOjB;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,CAAC,gBAAgB,CAItD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,CAAC,mBAAmB,CAI1D,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,CAAC,wBAAwB,CAMpE,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,CAAC,mBAAmB,CAG1D,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,CAAC,oBAAoB,CAK5D,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,CAAC,4BAA4B,CAI5E,CAAC"}
+{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../../../src/packlets/storage/converters.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,KAAK,SAAS,EAAc,MAAM,eAAe,CAAC;AAE3D,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,4BAA4B,EAC5B,gBAAgB,EAChB,wBAAwB,EACxB,sBAAsB,EAEvB,MAAM,SAAS,CAAC;AAOjB;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,CAAC,gBAAgB,CAItD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,CAAC,mBAAmB,CAI1D,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,CAAC,sBAAsB,CACG,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,CAAC,uBAAuB,CAKlE,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,CAAC,wBAAwB,CAMpE,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,CAAC,mBAAmB,CAG1D,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,CAAC,oBAAoB,CAM5D,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,CAAC,4BAA4B,CAI5E,CAAC"}

package/lib/packlets/storage/converters.js

@@ -21,7 +21,7 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.storageTreeChildrenResponse = exports.storageFileResponse = exports.storageSyncRequest = exports.storageWriteFileRequest = exports.storagePathRequest = exports.storageTreeItem = void 0;
+exports.storageTreeChildrenResponse = exports.storageFileResponse = exports.storageSyncRequest = exports.storageWriteFileRequest = exports.storageReadFileRequest = exports.storageContentEncoding = exports.storagePathRequest = exports.storageTreeItem = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const storageItemType = ts_utils_1.Converters.enumeratedValue([
     'file',
@@ -44,6 +44,20 @@ exports.storagePathRequest = ts_utils_1.Converters.strictObject({
     path: ts_utils_1.Converters.string,
     namespace: ts_utils_1.Converters.string.optional()
 });
+/**
+ * Converter for the wire content encoding.
+ * @public
+ */
+exports.storageContentEncoding = ts_utils_1.Converters.enumeratedValue(['utf8', 'base64']);
+/**
+ * Converter for read-file requests.
+ * @public
+ */
+exports.storageReadFileRequest = ts_utils_1.Converters.strictObject({
+    path: ts_utils_1.Converters.string,
+    namespace: ts_utils_1.Converters.string.optional(),
+    encoding: exports.storageContentEncoding.optional()
+});
 /**
  * Converter for write-file requests.
  * @public
@@ -68,7 +82,8 @@ exports.storageSyncRequest = ts_utils_1.Converters.strictObject({
 exports.storageFileResponse = ts_utils_1.Converters.strictObject({
     path: ts_utils_1.Converters.string,
     contents: ts_utils_1.Converters.string,
-    contentType: ts_utils_1.Converters.string.optional()
+    contentType: ts_utils_1.Converters.string.optional(),
+    encoding: exports.storageContentEncoding.optional()
 });
 /**
  * Converter for children list responses.

package/lib/packlets/storage/converters.js.map

@@ -1 +1 @@
-{"version":3,"file":"converters.js","sourceRoot":"","sources":["../../../src/packlets/storage/converters.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,4CAA2D;AAY3D,MAAM,eAAe,GAA+B,qBAAU,CAAC,eAAe,CAAkB;IAC9F,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAEH;;;GAGG;AACU,QAAA,eAAe,GAAgC,qBAAU,CAAC,YAAY,CAAmB;IACpG,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,IAAI,EAAE,eAAe;CACtB,CAAC,CAAC;AAEH;;;GAGG;AACU,QAAA,kBAAkB,GAC7B,qBAAU,CAAC,YAAY,CAAsB;IAC3C,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,SAAS,EAAE,qBAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEL;;;GAGG;AACU,QAAA,uBAAuB,GAClC,qBAAU,CAAC,YAAY,CAA2B;IAChD,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,QAAQ,EAAE,qBAAU,CAAC,MAAM;IAC3B,WAAW,EAAE,qBAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;IACzC,SAAS,EAAE,qBAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEL;;;GAGG;AACU,QAAA,kBAAkB,GAC7B,qBAAU,CAAC,YAAY,CAAsB;IAC3C,SAAS,EAAE,qBAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEL;;;GAGG;AACU,QAAA,mBAAmB,GAC9B,qBAAU,CAAC,YAAY,CAAuB;IAC5C,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,QAAQ,EAAE,qBAAU,CAAC,MAAM;IAC3B,WAAW,EAAE,qBAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC;AAEL;;;GAGG;AACU,QAAA,2BAA2B,GACtC,qBAAU,CAAC,YAAY,CAA+B;IACpD,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,QAAQ,EAAE,qBAAU,CAAC,OAAO,CAAC,uBAAe,CAAC;CAC9C,CAAC,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { type Converter, Converters } from '@fgv/ts-utils';\n\nimport type {\n  IStorageFileResponse,\n  IStoragePathRequest,\n  IStorageSyncRequest,\n  IStorageTreeChildrenResponse,\n  IStorageTreeItem,\n  IStorageWriteFileRequest,\n  StorageItemType\n} from './model';\n\nconst storageItemType: Converter<StorageItemType> = Converters.enumeratedValue<StorageItemType>([\n  'file',\n  'directory'\n]);\n\n/**\n * Converter for {@link IStorageTreeItem}.\n * @public\n */\nexport const storageTreeItem: Converter<IStorageTreeItem> = Converters.strictObject<IStorageTreeItem>({\n  path: Converters.string,\n  name: Converters.string,\n  type: storageItemType\n});\n\n/**\n * Converter for path-based requests.\n * @public\n */\nexport const storagePathRequest: Converter<IStoragePathRequest> =\n  Converters.strictObject<IStoragePathRequest>({\n    path: Converters.string,\n    namespace: Converters.string.optional()\n  });\n\n/**\n * Converter for write-file requests.\n * @public\n */\nexport const storageWriteFileRequest: Converter<IStorageWriteFileRequest> =\n  Converters.strictObject<IStorageWriteFileRequest>({\n    path: Converters.string,\n    contents: Converters.string,\n    contentType: Converters.string.optional(),\n    namespace: Converters.string.optional()\n  });\n\n/**\n * Converter for sync requests.\n * @public\n */\nexport const storageSyncRequest: Converter<IStorageSyncRequest> =\n  Converters.strictObject<IStorageSyncRequest>({\n    namespace: Converters.string.optional()\n  });\n\n/**\n * Converter for file responses.\n * @public\n */\nexport const storageFileResponse: Converter<IStorageFileResponse> =\n  Converters.strictObject<IStorageFileResponse>({\n    path: Converters.string,\n    contents: Converters.string,\n    contentType: Converters.string.optional()\n  });\n\n/**\n * Converter for children list responses.\n * @public\n */\nexport const storageTreeChildrenResponse: Converter<IStorageTreeChildrenResponse> =\n  Converters.strictObject<IStorageTreeChildrenResponse>({\n    path: Converters.string,\n    children: Converters.arrayOf(storageTreeItem)\n  });\n"]}
+{"version":3,"file":"converters.js","sourceRoot":"","sources":["../../../src/packlets/storage/converters.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,4CAA2D;AAc3D,MAAM,eAAe,GAA+B,qBAAU,CAAC,eAAe,CAAkB;IAC9F,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAEH;;;GAGG;AACU,QAAA,eAAe,GAAgC,qBAAU,CAAC,YAAY,CAAmB;IACpG,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,IAAI,EAAE,eAAe;CACtB,CAAC,CAAC;AAEH;;;GAGG;AACU,QAAA,kBAAkB,GAC7B,qBAAU,CAAC,YAAY,CAAsB;IAC3C,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,SAAS,EAAE,qBAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEL;;;GAGG;AACU,QAAA,sBAAsB,GACjC,qBAAU,CAAC,eAAe,CAAyB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEzE;;;GAGG;AACU,QAAA,sBAAsB,GACjC,qBAAU,CAAC,YAAY,CAA0B;IAC/C,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,SAAS,EAAE,qBAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;IACvC,QAAQ,EAAE,8BAAsB,CAAC,QAAQ,EAAE;CAC5C,CAAC,CAAC;AAEL;;;GAGG;AACU,QAAA,uBAAuB,GAClC,qBAAU,CAAC,YAAY,CAA2B;IAChD,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,QAAQ,EAAE,qBAAU,CAAC,MAAM;IAC3B,WAAW,EAAE,qBAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;IACzC,SAAS,EAAE,qBAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEL;;;GAGG;AACU,QAAA,kBAAkB,GAC7B,qBAAU,CAAC,YAAY,CAAsB;IAC3C,SAAS,EAAE,qBAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEL;;;GAGG;AACU,QAAA,mBAAmB,GAC9B,qBAAU,CAAC,YAAY,CAAuB;IAC5C,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,QAAQ,EAAE,qBAAU,CAAC,MAAM;IAC3B,WAAW,EAAE,qBAAU,CAAC,MAAM,CAAC,QAAQ,EAAE;IACzC,QAAQ,EAAE,8BAAsB,CAAC,QAAQ,EAAE;CAC5C,CAAC,CAAC;AAEL;;;GAGG;AACU,QAAA,2BAA2B,GACtC,qBAAU,CAAC,YAAY,CAA+B;IACpD,IAAI,EAAE,qBAAU,CAAC,MAAM;IACvB,QAAQ,EAAE,qBAAU,CAAC,OAAO,CAAC,uBAAe,CAAC;CAC9C,CAAC,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { type Converter, Converters } from '@fgv/ts-utils';\n\nimport type {\n  IStorageFileResponse,\n  IStoragePathRequest,\n  IStorageReadFileRequest,\n  IStorageSyncRequest,\n  IStorageTreeChildrenResponse,\n  IStorageTreeItem,\n  IStorageWriteFileRequest,\n  StorageContentEncoding,\n  StorageItemType\n} from './model';\n\nconst storageItemType: Converter<StorageItemType> = Converters.enumeratedValue<StorageItemType>([\n  'file',\n  'directory'\n]);\n\n/**\n * Converter for {@link IStorageTreeItem}.\n * @public\n */\nexport const storageTreeItem: Converter<IStorageTreeItem> = Converters.strictObject<IStorageTreeItem>({\n  path: Converters.string,\n  name: Converters.string,\n  type: storageItemType\n});\n\n/**\n * Converter for path-based requests.\n * @public\n */\nexport const storagePathRequest: Converter<IStoragePathRequest> =\n  Converters.strictObject<IStoragePathRequest>({\n    path: Converters.string,\n    namespace: Converters.string.optional()\n  });\n\n/**\n * Converter for the wire content encoding.\n * @public\n */\nexport const storageContentEncoding: Converter<StorageContentEncoding> =\n  Converters.enumeratedValue<StorageContentEncoding>(['utf8', 'base64']);\n\n/**\n * Converter for read-file requests.\n * @public\n */\nexport const storageReadFileRequest: Converter<IStorageReadFileRequest> =\n  Converters.strictObject<IStorageReadFileRequest>({\n    path: Converters.string,\n    namespace: Converters.string.optional(),\n    encoding: storageContentEncoding.optional()\n  });\n\n/**\n * Converter for write-file requests.\n * @public\n */\nexport const storageWriteFileRequest: Converter<IStorageWriteFileRequest> =\n  Converters.strictObject<IStorageWriteFileRequest>({\n    path: Converters.string,\n    contents: Converters.string,\n    contentType: Converters.string.optional(),\n    namespace: Converters.string.optional()\n  });\n\n/**\n * Converter for sync requests.\n * @public\n */\nexport const storageSyncRequest: Converter<IStorageSyncRequest> =\n  Converters.strictObject<IStorageSyncRequest>({\n    namespace: Converters.string.optional()\n  });\n\n/**\n * Converter for file responses.\n * @public\n */\nexport const storageFileResponse: Converter<IStorageFileResponse> =\n  Converters.strictObject<IStorageFileResponse>({\n    path: Converters.string,\n    contents: Converters.string,\n    contentType: Converters.string.optional(),\n    encoding: storageContentEncoding.optional()\n  });\n\n/**\n * Converter for children list responses.\n * @public\n */\nexport const storageTreeChildrenResponse: Converter<IStorageTreeChildrenResponse> =\n  Converters.strictObject<IStorageTreeChildrenResponse>({\n    path: Converters.string,\n    children: Converters.arrayOf(storageTreeItem)\n  });\n"]}

package/lib/packlets/storage/fsProvider.d.ts

@@ -1,5 +1,5 @@
 import { type Result } from '@fgv/ts-utils';
-import type { IHttpStorageProvider, IStorageFileResponse, IStorageSyncResponse, IStorageTreeItem } from './model';
+import type { IHttpStorageProvider, IStorageFileResponse, IStorageSyncResponse, IStorageTreeItem, StorageContentEncoding } from './model';
 import type { IHttpStorageProviderFactory } from './provider';
 /**
  * Options for creating filesystem-backed storage providers.
@@ -17,7 +17,7 @@ export declare class FsStorageProvider implements IHttpStorageProvider {
     constructor(rootPath: string);
     getItem(itemPath: string): Promise<Result<IStorageTreeItem>>;
     getChildren(itemPath: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>>;
-    getFile(itemPath: string): Promise<Result<IStorageFileResponse>>;
+    getFile(itemPath: string, encoding?: StorageContentEncoding): Promise<Result<IStorageFileResponse>>;
     saveFile(itemPath: string, contents: string, contentType?: string): Promise<Result<IStorageFileResponse>>;
     deleteFile(itemPath: string): Promise<Result<boolean>>;
     createDirectory(itemPath: string): Promise<Result<IStorageTreeItem>>;

package/lib/packlets/storage/fsProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fsProvider.d.ts","sourceRoot":"","sources":["../../../src/packlets/storage/fsProvider.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAuB,KAAK,MAAM,EAAW,MAAM,eAAe,CAAC;AAE1E,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAEjB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAMD;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,oBAAoB;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEhB,QAAQ,EAAE,MAAM;IAItB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAa5D,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAa/E,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAoBhE,QAAQ,CACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAmB3B,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAiBtD,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAapE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAI1D,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,WAAW;CASpB;AAuBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAMhE;AAED;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,2BAA2B;IAC1E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEhB,OAAO,EAAE,gCAAgC;IAIrD,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,oBAAoB,CAAC;CAmBtE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CASpE"}
+{"version":3,"file":"fsProvider.d.ts","sourceRoot":"","sources":["../../../src/packlets/storage/fsProvider.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAuB,KAAK,MAAM,EAAW,MAAM,eAAe,CAAC;AAE1E,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EAEvB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAMD;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,oBAAoB;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEhB,QAAQ,EAAE,MAAM;IAItB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAa5D,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAa/E,OAAO,CAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,sBAAsB,GAChC,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAoC3B,QAAQ,CACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAmB3B,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAiBtD,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAapE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAI1D,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,WAAW;CASpB;AAuBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAMhE;AAED;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,2BAA2B;IAC1E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEhB,OAAO,EAAE,gCAAgC;IAIrD,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,oBAAoB,CAAC;CAmBtE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CASpE"}

package/lib/packlets/storage/fsProvider.js

@@ -98,7 +98,7 @@ class FsStorageProvider {
             return (0, ts_utils_1.fail)(`${itemPath}: ${_toMessage(err)}`);
         }
     }
-    async getFile(itemPath) {
+    async getFile(itemPath, encoding) {
         const resolved = this._resolveAbsolutePath(itemPath);
         if (resolved.isFailure()) {
             return (0, ts_utils_1.fail)(resolved.message);
@@ -108,6 +108,22 @@ class FsStorageProvider {
             if (!stats.isFile()) {
                 return (0, ts_utils_1.fail)(`${itemPath}: not a file`);
             }
+            // Byte-faithful only when asked. On the base64 branch `readFile` is called
+            // with no encoding argument, so it yields the raw bytes and base64 carries
+            // them intact. The default branch below still decodes as UTF-8 — lossy, but
+            // it is what every existing caller already receives.
+            if (encoding === 'base64') {
+                const bytes = await fsp.readFile(resolved.value);
+                return (0, ts_utils_1.succeed)({
+                    path: normalizeRequestPath(itemPath),
+                    contents: bytes.toString('base64'),
+                    encoding: 'base64'
+                });
+            }
+            // Deliberately no `encoding` field on the default path: absent means `'utf8'`,
+            // so an existing deployment's responses stay byte-identical. It also leaves a
+            // usable signal — a client that asked for base64 and got no field back knows
+            // the request was not honoured, rather than having to guess.
             const contents = await fsp.readFile(resolved.value, 'utf8');
             return (0, ts_utils_1.succeed)({
                 path: normalizeRequestPath(itemPath),

package/lib/packlets/storage/fsProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"fsProvider.js","sourceRoot":"","sources":["../../../src/packlets/storage/fsProvider.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport * as fs from 'fs';\nimport * as fsp from 'fs/promises';\nimport * as path from 'path';\n\nimport { captureResult, fail, type Result, succeed } from '@fgv/ts-utils';\n\nimport type {\n  IHttpStorageProvider,\n  IStorageFileResponse,\n  IStorageSyncResponse,\n  IStorageTreeItem,\n  StorageItemType\n} from './model';\nimport type { IHttpStorageProviderFactory } from './provider';\n\n/**\n * Options for creating filesystem-backed storage providers.\n * @public\n */\nexport interface IFsStorageProviderFactoryOptions {\n  readonly rootPath: string;\n}\n\nfunction toItemType(stats: fs.Stats): StorageItemType {\n  return stats.isDirectory() ? 'directory' : 'file';\n}\n\n/**\n * Filesystem-backed implementation of {@link IHttpStorageProvider}.\n * @public\n */\nexport class FsStorageProvider implements IHttpStorageProvider {\n  private readonly _rootPath: string;\n\n  public constructor(rootPath: string) {\n    this._rootPath = rootPath;\n  }\n\n  public async getItem(itemPath: string): Promise<Result<IStorageTreeItem>> {\n    const resolved = this._resolveAbsolutePath(itemPath);\n    if (resolved.isFailure()) {\n      return fail(resolved.message);\n    }\n    try {\n      const stats = await fsp.stat(resolved.value);\n      return succeed(this._toTreeItem(itemPath, toItemType(stats)));\n    } catch (err: unknown) {\n      return fail(`${itemPath}: ${_toMessage(err)}`);\n    }\n  }\n\n  public async getChildren(itemPath: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>> {\n    const resolved = this._resolveAbsolutePath(itemPath);\n    if (resolved.isFailure()) {\n      return fail(resolved.message);\n    }\n    try {\n      const entries = await fsp.readdir(resolved.value, { withFileTypes: true });\n      return _mapEntries(entries, itemPath);\n    } catch (err: unknown) {\n      return fail(`${itemPath}: ${_toMessage(err)}`);\n    }\n  }\n\n  public async getFile(itemPath: string): Promise<Result<IStorageFileResponse>> {\n    const resolved = this._resolveAbsolutePath(itemPath);\n    if (resolved.isFailure()) {\n      return fail(resolved.message);\n    }\n    try {\n      const stats = await fsp.stat(resolved.value);\n      if (!stats.isFile()) {\n        return fail(`${itemPath}: not a file`);\n      }\n      const contents = await fsp.readFile(resolved.value, 'utf8');\n      return succeed({\n        path: normalizeRequestPath(itemPath),\n        contents\n      });\n    } catch (err: unknown) {\n      return fail(`${itemPath}: ${_toMessage(err)}`);\n    }\n  }\n\n  public async saveFile(\n    itemPath: string,\n    contents: string,\n    contentType?: string\n  ): Promise<Result<IStorageFileResponse>> {\n    const resolved = this._resolveAbsolutePath(itemPath);\n    if (resolved.isFailure()) {\n      return fail(resolved.message);\n    }\n    try {\n      const parentDir = path.dirname(resolved.value);\n      await fsp.mkdir(parentDir, { recursive: true });\n      await fsp.writeFile(resolved.value, contents, 'utf8');\n      return succeed({\n        path: normalizeRequestPath(itemPath),\n        contents,\n        contentType\n      });\n    } catch (err: unknown) {\n      return fail(`${itemPath}: ${_toMessage(err)}`);\n    }\n  }\n\n  public async deleteFile(itemPath: string): Promise<Result<boolean>> {\n    const resolved = this._resolveAbsolutePath(itemPath);\n    if (resolved.isFailure()) {\n      return fail(resolved.message);\n    }\n    try {\n      const stats = await fsp.stat(resolved.value);\n      if (!stats.isFile()) {\n        return fail(`${itemPath}: not a file`);\n      }\n      await fsp.unlink(resolved.value);\n      return succeed(true);\n    } catch (err: unknown) {\n      return fail(`${itemPath}: ${_toMessage(err)}`);\n    }\n  }\n\n  public async createDirectory(itemPath: string): Promise<Result<IStorageTreeItem>> {\n    const resolved = this._resolveAbsolutePath(itemPath);\n    if (resolved.isFailure()) {\n      return fail(resolved.message);\n    }\n    try {\n      await fsp.mkdir(resolved.value, { recursive: true });\n      return succeed(this._toTreeItem(itemPath, 'directory'));\n    } catch (err: unknown) {\n      return fail(`${itemPath}: ${_toMessage(err)}`);\n    }\n  }\n\n  public async sync(): Promise<Result<IStorageSyncResponse>> {\n    return succeed({ synced: 0 });\n  }\n\n  private _resolveAbsolutePath(requestPath: string): Result<string> {\n    const normalized = normalizeRequestPath(requestPath);\n    const candidate = path.resolve(this._rootPath, `.${normalized}`);\n    const relative = path.relative(this._rootPath, candidate);\n    if (relative.startsWith('..') || path.isAbsolute(relative)) {\n      return fail(`${requestPath}: path is outside storage root`);\n    }\n    return succeed(candidate);\n  }\n\n  private _toTreeItem(itemPath: string, type: StorageItemType): IStorageTreeItem {\n    const normalizedPath = normalizeRequestPath(itemPath);\n    const name = normalizedPath === '/' ? '/' : path.posix.basename(normalizedPath);\n    return {\n      path: normalizedPath,\n      name,\n      type\n    };\n  }\n}\n\nfunction _mapEntries(\n  entries: ReadonlyArray<fs.Dirent>,\n  parentPath: string\n): Result<ReadonlyArray<IStorageTreeItem>> {\n  const normalizedParent = normalizeRequestPath(parentPath);\n  const items: IStorageTreeItem[] = entries.map((entry) => {\n    const isDirectory = entry.isDirectory();\n    const childPath = normalizedParent === '/' ? `/${entry.name}` : `${normalizedParent}/${entry.name}`;\n    return {\n      path: childPath,\n      name: entry.name,\n      type: isDirectory ? 'directory' : 'file'\n    };\n  });\n  return succeed(items);\n}\n\nfunction _toMessage(err: unknown): string {\n  return err instanceof Error ? err.message : String(err);\n}\n\n/**\n * Normalizes a request path to a consistent POSIX format.\n * @public\n */\nexport function normalizeRequestPath(requestPath: string): string {\n  if (requestPath.length === 0) {\n    return '/';\n  }\n  const normalized = path.posix.normalize(requestPath.startsWith('/') ? requestPath : `/${requestPath}`);\n  return normalized.startsWith('/') ? normalized : `/${normalized}`;\n}\n\n/**\n * Namespace-aware provider factory backed by filesystem directories.\n * @public\n */\nexport class FsStorageProviderFactory implements IHttpStorageProviderFactory {\n  private readonly _rootPath: string;\n\n  public constructor(options: IFsStorageProviderFactoryOptions) {\n    this._rootPath = path.resolve(options.rootPath);\n  }\n\n  public forNamespace(namespace?: string): Result<IHttpStorageProvider> {\n    const safeNamespace = sanitizeNamespace(namespace);\n    if (safeNamespace.isFailure()) {\n      return fail(safeNamespace.message);\n    }\n\n    const namespaceRoot = path.resolve(this._rootPath, safeNamespace.value);\n    const relative = path.relative(this._rootPath, namespaceRoot);\n    if (relative.startsWith('..') || path.isAbsolute(relative)) {\n      return fail(`namespace '${safeNamespace.value}' is outside root`);\n    }\n\n    const ensureResult = captureResult(() => fs.mkdirSync(namespaceRoot, { recursive: true }));\n    if (ensureResult.isFailure()) {\n      return fail(`namespace '${safeNamespace.value}': ${ensureResult.message}`);\n    }\n\n    return succeed(new FsStorageProvider(namespaceRoot));\n  }\n}\n\n/**\n * Sanitize namespace path segment.\n * @public\n */\nexport function sanitizeNamespace(namespace?: string): Result<string> {\n  if (!namespace || namespace.trim().length === 0) {\n    return succeed('default');\n  }\n  const trimmed = namespace.trim();\n  if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) {\n    return fail(`namespace '${namespace}': only [a-zA-Z0-9._-] allowed`);\n  }\n  return succeed(trimmed);\n}\n"]}
+{"version":3,"file":"fsProvider.js","sourceRoot":"","sources":["../../../src/packlets/storage/fsProvider.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport * as fs from 'fs';\nimport * as fsp from 'fs/promises';\nimport * as path from 'path';\n\nimport { captureResult, fail, type Result, succeed } from '@fgv/ts-utils';\n\nimport type {\n  IHttpStorageProvider,\n  IStorageFileResponse,\n  IStorageSyncResponse,\n  IStorageTreeItem,\n  StorageContentEncoding,\n  StorageItemType\n} from './model';\nimport type { IHttpStorageProviderFactory } from './provider';\n\n/**\n * Options for creating filesystem-backed storage providers.\n * @public\n */\nexport interface IFsStorageProviderFactoryOptions {\n  readonly rootPath: string;\n}\n\nfunction toItemType(stats: fs.Stats): StorageItemType {\n  return stats.isDirectory() ? 'directory' : 'file';\n}\n\n/**\n * Filesystem-backed implementation of {@link IHttpStorageProvider}.\n * @public\n */\nexport class FsStorageProvider implements IHttpStorageProvider {\n  private readonly _rootPath: string;\n\n  public constructor(rootPath: string) {\n    this._rootPath = rootPath;\n  }\n\n  public async getItem(itemPath: string): Promise<Result<IStorageTreeItem>> {\n    const resolved = this._resolveAbsolutePath(itemPath);\n    if (resolved.isFailure()) {\n      return fail(resolved.message);\n    }\n    try {\n      const stats = await fsp.stat(resolved.value);\n      return succeed(this._toTreeItem(itemPath, toItemType(stats)));\n    } catch (err: unknown) {\n      return fail(`${itemPath}: ${_toMessage(err)}`);\n    }\n  }\n\n  public async getChildren(itemPath: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>> {\n    const resolved = this._resolveAbsolutePath(itemPath);\n    if (resolved.isFailure()) {\n      return fail(resolved.message);\n    }\n    try {\n      const entries = await fsp.readdir(resolved.value, { withFileTypes: true });\n      return _mapEntries(entries, itemPath);\n    } catch (err: unknown) {\n      return fail(`${itemPath}: ${_toMessage(err)}`);\n    }\n  }\n\n  public async getFile(\n    itemPath: string,\n    encoding?: StorageContentEncoding\n  ): Promise<Result<IStorageFileResponse>> {\n    const resolved = this._resolveAbsolutePath(itemPath);\n    if (resolved.isFailure()) {\n      return fail(resolved.message);\n    }\n    try {\n      const stats = await fsp.stat(resolved.value);\n      if (!stats.isFile()) {\n        return fail(`${itemPath}: not a file`);\n      }\n      // Byte-faithful only when asked. On the base64 branch `readFile` is called\n      // with no encoding argument, so it yields the raw bytes and base64 carries\n      // them intact. The default branch below still decodes as UTF-8 — lossy, but\n      // it is what every existing caller already receives.\n      if (encoding === 'base64') {\n        const bytes = await fsp.readFile(resolved.value);\n        return succeed({\n          path: normalizeRequestPath(itemPath),\n          contents: bytes.toString('base64'),\n          encoding: 'base64'\n        });\n      }\n      // Deliberately no `encoding` field on the default path: absent means `'utf8'`,\n      // so an existing deployment's responses stay byte-identical. It also leaves a\n      // usable signal — a client that asked for base64 and got no field back knows\n      // the request was not honoured, rather than having to guess.\n      const contents = await fsp.readFile(resolved.value, 'utf8');\n      return succeed({\n        path: normalizeRequestPath(itemPath),\n        contents\n      });\n    } catch (err: unknown) {\n      return fail(`${itemPath}: ${_toMessage(err)}`);\n    }\n  }\n\n  public async saveFile(\n    itemPath: string,\n    contents: string,\n    contentType?: string\n  ): Promise<Result<IStorageFileResponse>> {\n    const resolved = this._resolveAbsolutePath(itemPath);\n    if (resolved.isFailure()) {\n      return fail(resolved.message);\n    }\n    try {\n      const parentDir = path.dirname(resolved.value);\n      await fsp.mkdir(parentDir, { recursive: true });\n      await fsp.writeFile(resolved.value, contents, 'utf8');\n      return succeed({\n        path: normalizeRequestPath(itemPath),\n        contents,\n        contentType\n      });\n    } catch (err: unknown) {\n      return fail(`${itemPath}: ${_toMessage(err)}`);\n    }\n  }\n\n  public async deleteFile(itemPath: string): Promise<Result<boolean>> {\n    const resolved = this._resolveAbsolutePath(itemPath);\n    if (resolved.isFailure()) {\n      return fail(resolved.message);\n    }\n    try {\n      const stats = await fsp.stat(resolved.value);\n      if (!stats.isFile()) {\n        return fail(`${itemPath}: not a file`);\n      }\n      await fsp.unlink(resolved.value);\n      return succeed(true);\n    } catch (err: unknown) {\n      return fail(`${itemPath}: ${_toMessage(err)}`);\n    }\n  }\n\n  public async createDirectory(itemPath: string): Promise<Result<IStorageTreeItem>> {\n    const resolved = this._resolveAbsolutePath(itemPath);\n    if (resolved.isFailure()) {\n      return fail(resolved.message);\n    }\n    try {\n      await fsp.mkdir(resolved.value, { recursive: true });\n      return succeed(this._toTreeItem(itemPath, 'directory'));\n    } catch (err: unknown) {\n      return fail(`${itemPath}: ${_toMessage(err)}`);\n    }\n  }\n\n  public async sync(): Promise<Result<IStorageSyncResponse>> {\n    return succeed({ synced: 0 });\n  }\n\n  private _resolveAbsolutePath(requestPath: string): Result<string> {\n    const normalized = normalizeRequestPath(requestPath);\n    const candidate = path.resolve(this._rootPath, `.${normalized}`);\n    const relative = path.relative(this._rootPath, candidate);\n    if (relative.startsWith('..') || path.isAbsolute(relative)) {\n      return fail(`${requestPath}: path is outside storage root`);\n    }\n    return succeed(candidate);\n  }\n\n  private _toTreeItem(itemPath: string, type: StorageItemType): IStorageTreeItem {\n    const normalizedPath = normalizeRequestPath(itemPath);\n    const name = normalizedPath === '/' ? '/' : path.posix.basename(normalizedPath);\n    return {\n      path: normalizedPath,\n      name,\n      type\n    };\n  }\n}\n\nfunction _mapEntries(\n  entries: ReadonlyArray<fs.Dirent>,\n  parentPath: string\n): Result<ReadonlyArray<IStorageTreeItem>> {\n  const normalizedParent = normalizeRequestPath(parentPath);\n  const items: IStorageTreeItem[] = entries.map((entry) => {\n    const isDirectory = entry.isDirectory();\n    const childPath = normalizedParent === '/' ? `/${entry.name}` : `${normalizedParent}/${entry.name}`;\n    return {\n      path: childPath,\n      name: entry.name,\n      type: isDirectory ? 'directory' : 'file'\n    };\n  });\n  return succeed(items);\n}\n\nfunction _toMessage(err: unknown): string {\n  return err instanceof Error ? err.message : String(err);\n}\n\n/**\n * Normalizes a request path to a consistent POSIX format.\n * @public\n */\nexport function normalizeRequestPath(requestPath: string): string {\n  if (requestPath.length === 0) {\n    return '/';\n  }\n  const normalized = path.posix.normalize(requestPath.startsWith('/') ? requestPath : `/${requestPath}`);\n  return normalized.startsWith('/') ? normalized : `/${normalized}`;\n}\n\n/**\n * Namespace-aware provider factory backed by filesystem directories.\n * @public\n */\nexport class FsStorageProviderFactory implements IHttpStorageProviderFactory {\n  private readonly _rootPath: string;\n\n  public constructor(options: IFsStorageProviderFactoryOptions) {\n    this._rootPath = path.resolve(options.rootPath);\n  }\n\n  public forNamespace(namespace?: string): Result<IHttpStorageProvider> {\n    const safeNamespace = sanitizeNamespace(namespace);\n    if (safeNamespace.isFailure()) {\n      return fail(safeNamespace.message);\n    }\n\n    const namespaceRoot = path.resolve(this._rootPath, safeNamespace.value);\n    const relative = path.relative(this._rootPath, namespaceRoot);\n    if (relative.startsWith('..') || path.isAbsolute(relative)) {\n      return fail(`namespace '${safeNamespace.value}' is outside root`);\n    }\n\n    const ensureResult = captureResult(() => fs.mkdirSync(namespaceRoot, { recursive: true }));\n    if (ensureResult.isFailure()) {\n      return fail(`namespace '${safeNamespace.value}': ${ensureResult.message}`);\n    }\n\n    return succeed(new FsStorageProvider(namespaceRoot));\n  }\n}\n\n/**\n * Sanitize namespace path segment.\n * @public\n */\nexport function sanitizeNamespace(namespace?: string): Result<string> {\n  if (!namespace || namespace.trim().length === 0) {\n    return succeed('default');\n  }\n  const trimmed = namespace.trim();\n  if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) {\n    return fail(`namespace '${namespace}': only [a-zA-Z0-9._-] allowed`);\n  }\n  return succeed(trimmed);\n}\n"]}

package/lib/packlets/storage/model.d.ts

@@ -9,6 +9,22 @@ export type StorageNamespace = string;
  * @public
  */
 export type StorageItemType = 'file' | 'directory';
+/**
+ * How a file's bytes are represented in the `contents` field on the wire.
+ *
+ * @remarks
+ * - `'utf8'` — `contents` is the file decoded as UTF-8 text. This is the
+ *   historical (and default) representation, and it is **lossy**: the decode is
+ *   the lenient WHATWG one, so any byte sequence that is not valid UTF-8 has
+ *   already been replaced by U+FFFD by the time it reaches the wire, and the
+ *   substitution is not recoverable downstream.
+ * - `'base64'` — `contents` is the file's bytes, base64-encoded. Byte-faithful
+ *   and therefore the only representation over which a consumer can decide
+ *   whether the stored bytes were valid UTF-8, or read genuinely binary content.
+ *   Costs roughly 33% more payload.
+ * @public
+ */
+export type StorageContentEncoding = 'utf8' | 'base64';
 /**
  * Storage tree item metadata.
  * @public
@@ -34,6 +50,19 @@ export interface IStorageFileResponse {
     readonly path: string;
     readonly contents: string;
     readonly contentType?: string;
+    /**
+     * How `contents` is encoded. Absent means `'utf8'`.
+     *
+     * @remarks
+     * **This field describes what the server actually produced, not what the
+     * client asked for**, and a client must branch on it rather than on its own
+     * request. A provider that does not implement `'base64'` ignores the request
+     * and answers with UTF-8 text; a client that base64-decoded on the strength of
+     * having *asked* would corrupt every such response. Trusting the field instead
+     * makes an older or simpler provider degrade to today's behavior rather than
+     * to garbage.
+     */
+    readonly encoding?: StorageContentEncoding;
 }
 /**
  * Request for path-based operations.
@@ -43,6 +72,26 @@ export interface IStoragePathRequest {
     readonly path: string;
     readonly namespace?: StorageNamespace;
 }
+/**
+ * Request for reading a file, with an optional preferred content encoding.
+ *
+ * @remarks
+ * `encoding` is a *preference*, not a demand: a provider that cannot honour it
+ * answers in `'utf8'` and says so on {@link IStorageFileResponse.encoding}. The
+ * response is the authority.
+ * @public
+ */
+export interface IStorageReadFileRequest extends IStoragePathRequest {
+    /**
+     * Preferred wire encoding for the response's `contents`. Absent means `'utf8'`.
+     *
+     * @remarks
+     * A preference, not a demand — see {@link IStorageFileResponse.encoding}, which
+     * reports what the server actually produced and is the field a client must
+     * branch on.
+     */
+    readonly encoding?: StorageContentEncoding;
+}
 /**
  * Request for writing file contents.
  * @public
@@ -73,7 +122,15 @@ export interface IStorageSyncResponse {
 export interface IHttpStorageProvider {
     getItem(path: string): Promise<Result<IStorageTreeItem>>;
     getChildren(path: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>>;
-    getFile(path: string): Promise<Result<IStorageFileResponse>>;
+    /**
+     * Reads a file.
+     * @param path - Path of the file to read.
+     * @param encoding - Preferred wire encoding for the returned `contents`. A
+     * provider that does not implement the requested encoding MUST answer in
+     * `'utf8'` and report that on the response, rather than failing — the field is
+     * a preference and the response is the authority.
+     */
+    getFile(path: string, encoding?: StorageContentEncoding): Promise<Result<IStorageFileResponse>>;
     saveFile(path: string, contents: string, contentType?: string): Promise<Result<IStorageFileResponse>>;
     deleteFile(path: string): Promise<Result<boolean>>;
     createDirectory(path: string): Promise<Result<IStorageTreeItem>>;

package/lib/packlets/storage/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/packlets/storage/model.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEtC;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,WAAW,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;CACpD;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACzD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC5E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC;IACtG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IACnD,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACjE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC;CAC/C"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/packlets/storage/model.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEtC;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,WAAW,CAAC;AAEnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;CACpD;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CAC5C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CAC5C;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACzD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC5E;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAChG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC;IACtG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IACnD,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACjE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC;CAC/C"}

package/lib/packlets/storage/model.js.map

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/packlets/storage/model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport type { Result } from '@fgv/ts-utils';\n\n/**\n * Namespace identifier for scoped storage.\n * @public\n */\nexport type StorageNamespace = string;\n\n/**\n * Storage item type.\n * @public\n */\nexport type StorageItemType = 'file' | 'directory';\n\n/**\n * Storage tree item metadata.\n * @public\n */\nexport interface IStorageTreeItem {\n  readonly path: string;\n  readonly name: string;\n  readonly type: StorageItemType;\n}\n\n/**\n * Response for listing children.\n * @public\n */\nexport interface IStorageTreeChildrenResponse {\n  readonly path: string;\n  readonly children: ReadonlyArray<IStorageTreeItem>;\n}\n\n/**\n * Response for reading a file.\n * @public\n */\nexport interface IStorageFileResponse {\n  readonly path: string;\n  readonly contents: string;\n  readonly contentType?: string;\n}\n\n/**\n * Request for path-based operations.\n * @public\n */\nexport interface IStoragePathRequest {\n  readonly path: string;\n  readonly namespace?: StorageNamespace;\n}\n\n/**\n * Request for writing file contents.\n * @public\n */\nexport interface IStorageWriteFileRequest extends IStoragePathRequest {\n  readonly contents: string;\n  readonly contentType?: string;\n}\n\n/**\n * Request for sync operation.\n * @public\n */\nexport interface IStorageSyncRequest {\n  readonly namespace?: StorageNamespace;\n}\n\n/**\n * Sync response metadata.\n * @public\n */\nexport interface IStorageSyncResponse {\n  readonly synced: number;\n}\n\n/**\n * Provider contract for storage backends.\n * All methods are async to support both filesystem and database backends.\n * @public\n */\nexport interface IHttpStorageProvider {\n  getItem(path: string): Promise<Result<IStorageTreeItem>>;\n  getChildren(path: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>>;\n  getFile(path: string): Promise<Result<IStorageFileResponse>>;\n  saveFile(path: string, contents: string, contentType?: string): Promise<Result<IStorageFileResponse>>;\n  deleteFile(path: string): Promise<Result<boolean>>;\n  createDirectory(path: string): Promise<Result<IStorageTreeItem>>;\n  sync(): Promise<Result<IStorageSyncResponse>>;\n}\n"]}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/packlets/storage/model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport type { Result } from '@fgv/ts-utils';\n\n/**\n * Namespace identifier for scoped storage.\n * @public\n */\nexport type StorageNamespace = string;\n\n/**\n * Storage item type.\n * @public\n */\nexport type StorageItemType = 'file' | 'directory';\n\n/**\n * How a file's bytes are represented in the `contents` field on the wire.\n *\n * @remarks\n * - `'utf8'` — `contents` is the file decoded as UTF-8 text. This is the\n *   historical (and default) representation, and it is **lossy**: the decode is\n *   the lenient WHATWG one, so any byte sequence that is not valid UTF-8 has\n *   already been replaced by U+FFFD by the time it reaches the wire, and the\n *   substitution is not recoverable downstream.\n * - `'base64'` — `contents` is the file's bytes, base64-encoded. Byte-faithful\n *   and therefore the only representation over which a consumer can decide\n *   whether the stored bytes were valid UTF-8, or read genuinely binary content.\n *   Costs roughly 33% more payload.\n * @public\n */\nexport type StorageContentEncoding = 'utf8' | 'base64';\n\n/**\n * Storage tree item metadata.\n * @public\n */\nexport interface IStorageTreeItem {\n  readonly path: string;\n  readonly name: string;\n  readonly type: StorageItemType;\n}\n\n/**\n * Response for listing children.\n * @public\n */\nexport interface IStorageTreeChildrenResponse {\n  readonly path: string;\n  readonly children: ReadonlyArray<IStorageTreeItem>;\n}\n\n/**\n * Response for reading a file.\n * @public\n */\nexport interface IStorageFileResponse {\n  readonly path: string;\n  readonly contents: string;\n  readonly contentType?: string;\n\n  /**\n   * How `contents` is encoded. Absent means `'utf8'`.\n   *\n   * @remarks\n   * **This field describes what the server actually produced, not what the\n   * client asked for**, and a client must branch on it rather than on its own\n   * request. A provider that does not implement `'base64'` ignores the request\n   * and answers with UTF-8 text; a client that base64-decoded on the strength of\n   * having *asked* would corrupt every such response. Trusting the field instead\n   * makes an older or simpler provider degrade to today's behavior rather than\n   * to garbage.\n   */\n  readonly encoding?: StorageContentEncoding;\n}\n\n/**\n * Request for path-based operations.\n * @public\n */\nexport interface IStoragePathRequest {\n  readonly path: string;\n  readonly namespace?: StorageNamespace;\n}\n\n/**\n * Request for reading a file, with an optional preferred content encoding.\n *\n * @remarks\n * `encoding` is a *preference*, not a demand: a provider that cannot honour it\n * answers in `'utf8'` and says so on {@link IStorageFileResponse.encoding}. The\n * response is the authority.\n * @public\n */\nexport interface IStorageReadFileRequest extends IStoragePathRequest {\n  /**\n   * Preferred wire encoding for the response's `contents`. Absent means `'utf8'`.\n   *\n   * @remarks\n   * A preference, not a demand — see {@link IStorageFileResponse.encoding}, which\n   * reports what the server actually produced and is the field a client must\n   * branch on.\n   */\n  readonly encoding?: StorageContentEncoding;\n}\n\n/**\n * Request for writing file contents.\n * @public\n */\nexport interface IStorageWriteFileRequest extends IStoragePathRequest {\n  readonly contents: string;\n  readonly contentType?: string;\n}\n\n/**\n * Request for sync operation.\n * @public\n */\nexport interface IStorageSyncRequest {\n  readonly namespace?: StorageNamespace;\n}\n\n/**\n * Sync response metadata.\n * @public\n */\nexport interface IStorageSyncResponse {\n  readonly synced: number;\n}\n\n/**\n * Provider contract for storage backends.\n * All methods are async to support both filesystem and database backends.\n * @public\n */\nexport interface IHttpStorageProvider {\n  getItem(path: string): Promise<Result<IStorageTreeItem>>;\n  getChildren(path: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>>;\n  /**\n   * Reads a file.\n   * @param path - Path of the file to read.\n   * @param encoding - Preferred wire encoding for the returned `contents`. A\n   * provider that does not implement the requested encoding MUST answer in\n   * `'utf8'` and report that on the response, rather than failing — the field is\n   * a preference and the response is the authority.\n   */\n  getFile(path: string, encoding?: StorageContentEncoding): Promise<Result<IStorageFileResponse>>;\n  saveFile(path: string, contents: string, contentType?: string): Promise<Result<IStorageFileResponse>>;\n  deleteFile(path: string): Promise<Result<boolean>>;\n  createDirectory(path: string): Promise<Result<IStorageTreeItem>>;\n  sync(): Promise<Result<IStorageSyncResponse>>;\n}\n"]}

package/lib/packlets/storage/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/packlets/storage/routes.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAY7C,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,EAAE,2BAA2B,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;CACnC;AAaD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,CAwJ9E"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/packlets/storage/routes.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAa7C,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,EAAE,2BAA2B,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;CACnC;AAaD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,CA8J9E"}

package/lib/packlets/storage/routes.js

@@ -80,7 +80,8 @@ function createStorageRoutes(options) {
         return c.json(converted.value);
     });
     routes.get('/file', async (c) => {
-        const parsed = converters_1.storagePathRequest.convert(parsePathQuery(c.req.query('path'), c.req.query('namespace')));
+        const requestedEncoding = c.req.query('encoding');
+        const parsed = converters_1.storageReadFileRequest.convert(Object.assign(Object.assign({}, parsePathQuery(c.req.query('path'), c.req.query('namespace'))), (requestedEncoding !== undefined ? { encoding: requestedEncoding } : {})));
         if (parsed.isFailure()) {
             return c.json({ error: `invalid request: ${parsed.message}` }, 400);
         }