@fgv/ts-web-extras 5.0.2 → 5.1.0-1

package/lib/packlets/file-tree/fileSystemAccessTreeAccessors.js

@@ -0,0 +1,418 @@
+"use strict";
+/*
+ * 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.
+ */
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileSystemAccessTreeAccessors = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_json_base_1 = require("@fgv/ts-json-base");
+/**
+ * Implementation of `FileTree.IPersistentFileTreeAccessors` that uses the File System Access API
+ * to provide persistent file editing in browsers.
+ * @public
+ */
+class FileSystemAccessTreeAccessors extends ts_json_base_1.FileTree.InMemoryTreeAccessors {
+    /**
+     * Protected constructor for FileSystemAccessTreeAccessors.
+     * @param files - An array of in-memory files to include in the tree.
+     * @param rootDir - The root directory handle.
+     * @param handles - Map of file paths to their handles.
+     * @param params - Optional params for the tree.
+     * @param hasWritePermission - Whether write permission was granted.
+     */
+    constructor(files, rootDir, handles, params, hasWritePermission) {
+        var _a, _b;
+        super(files, params);
+        this._rootDir = rootDir;
+        this._handles = handles;
+        this._dirtyFiles = new Set();
+        this._pendingDeletions = new Set();
+        /* c8 ignore next 3 - intermittent branch coverage: ?? fallback branches in constructor */
+        this._autoSync = (_a = params === null || params === void 0 ? void 0 : params.autoSync) !== null && _a !== void 0 ? _a : false;
+        this._hasWritePermission = hasWritePermission;
+        this._logger = (_b = params === null || params === void 0 ? void 0 : params.logger) !== null && _b !== void 0 ? _b : new ts_utils_1.Logging.LogReporter();
+    }
+    async _runAutoSyncTask(path, operation, action) {
+        try {
+            const result = await action();
+            if (result.isFailure()) {
+                this._logger.error(`Auto-${operation} failed for ${path}: ${result.message}`);
+            }
+        }
+        catch (err) {
+            this._logger.error(`Auto-${operation} threw for ${path}: ${String(err)}`);
+        }
+    }
+    /**
+     * Creates a new FileSystemAccessTreeAccessors instance from a directory handle.
+     * @param dirHandle - The FileSystemDirectoryHandle to load files from.
+     * @param params - Optional parameters including autoSync and permission settings.
+     * @returns Promise resolving to a FileSystemAccessTreeAccessors instance.
+     * @public
+     */
+    static async fromDirectoryHandle(dirHandle, params) {
+        var _a, _b;
+        try {
+            // Check write permission
+            const hasWritePermission = await this._checkWritePermission(dirHandle);
+            /* c8 ignore next 3 - coverage intermittently missed in full suite */
+            if (!hasWritePermission && ((_a = params === null || params === void 0 ? void 0 : params.requireWritePermission) !== null && _a !== void 0 ? _a : true)) {
+                return (0, ts_utils_1.fail)('Write permission required but not granted');
+            }
+            // Load all files from the directory (always use '/' as base, prefix is handled by parent)
+            const { files, handles } = await this._loadDirectory(dirHandle, '/', params);
+            // Enable tree mutability when write permission is granted and caller didn't explicitly set mutable
+            const effectiveParams = Object.assign(Object.assign({}, params), { mutable: (_b = params === null || params === void 0 ? void 0 : params.mutable) !== null && _b !== void 0 ? _b : (hasWritePermission ? true : false) });
+            return (0, ts_utils_1.succeed)(new FileSystemAccessTreeAccessors(files, dirHandle, handles, effectiveParams, hasWritePermission));
+            /* c8 ignore next 4 - defensive: outer catch for unexpected errors */
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return (0, ts_utils_1.fail)(`Failed to create FileSystemAccessTreeAccessors: ${message}`);
+        }
+    }
+    /**
+     * Creates a new FileSystemAccessTreeAccessors instance from a single file handle.
+     *
+     * The resulting tree contains exactly one file at `/<filename>`.
+     * `syncToDisk()` writes changes back to the original file via the File System Access API.
+     * New file creation is not supported on this tree (no parent directory handle).
+     *
+     * @param fileHandle - The FileSystemFileHandle to load.
+     * @param params - Optional parameters including autoSync and permission settings.
+     * @returns Promise resolving to a FileSystemAccessTreeAccessors instance.
+     * @public
+     */
+    static async fromFileHandle(fileHandle, params) {
+        var _a, _b, _c;
+        try {
+            const hasWritePermission = await this._checkFileWritePermission(fileHandle);
+            /* c8 ignore next 1 - intermittent branch coverage: ?? true fallback */
+            if (!hasWritePermission && ((_a = params === null || params === void 0 ? void 0 : params.requireWritePermission) !== null && _a !== void 0 ? _a : true)) {
+                return (0, ts_utils_1.fail)('Write permission required but not granted');
+            }
+            const file = await fileHandle.getFile();
+            const contents = await file.text();
+            const path = (_b = params === null || params === void 0 ? void 0 : params.filePath) !== null && _b !== void 0 ? _b : `/${fileHandle.name}`;
+            /* c8 ignore next 3 - intermittent branch coverage: ternary for inferContentType */
+            const contentType = (params === null || params === void 0 ? void 0 : params.inferContentType)
+                ? params.inferContentType(path, file.type).orDefault()
+                : undefined;
+            const files = [{ path, contents, contentType }];
+            const handles = new Map([[path, fileHandle]]);
+            const dummyRoot = {};
+            const effectiveParams = Object.assign(Object.assign({}, params), { 
+                /* c8 ignore next 1 - intermittent branch coverage: ?? false fallback */
+                mutable: hasWritePermission ? true : (_c = params === null || params === void 0 ? void 0 : params.mutable) !== null && _c !== void 0 ? _c : false });
+            return (0, ts_utils_1.succeed)(new FileSystemAccessTreeAccessors(files, dummyRoot, handles, effectiveParams, hasWritePermission));
+        }
+        catch (error) {
+            /* c8 ignore next 1 - intermittent branch coverage: error instanceof Error false branch */
+            const message = error instanceof Error ? error.message : String(error);
+            return (0, ts_utils_1.fail)(`Failed to create FileSystemAccessTreeAccessors from file: ${message}`);
+        }
+    }
+    /**
+     * Check if the directory handle has write permission.
+     * @param handle - The directory handle to check.
+     * @returns Promise resolving to true if write permission is granted.
+     * @internal
+     */
+    static async _checkWritePermission(handle) {
+        try {
+            const permission = await handle.queryPermission({ mode: 'readwrite' });
+            if (permission === 'granted') {
+                return true;
+            }
+            if (permission === 'prompt') {
+                const requested = await handle.requestPermission({ mode: 'readwrite' });
+                return requested === 'granted';
+            }
+            return false;
+        }
+        catch (error) {
+            // Permission API might not be available or might throw
+            return false;
+        }
+    }
+    /**
+     * Check if the file handle has write permission.
+     * @param handle - The file handle to check.
+     * @returns Promise resolving to true if write permission is granted.
+     * @internal
+     */
+    static async _checkFileWritePermission(handle) {
+        try {
+            const permission = await handle.queryPermission({ mode: 'readwrite' });
+            if (permission === 'granted') {
+                return true;
+            }
+            if (permission === 'prompt') {
+                const requested = await handle.requestPermission({ mode: 'readwrite' });
+                return requested === 'granted';
+            }
+            return false;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * Load all files from a directory handle recursively.
+     * @param dirHandle - The directory handle to load from.
+     * @param basePath - The base path for files.
+     * @param params - Optional parameters.
+     * @returns Promise resolving to files and handles.
+     * @internal
+     */
+    static async _loadDirectory(dirHandle, basePath, params) {
+        var _a, e_1, _b, _c;
+        const files = [];
+        const handles = new Map();
+        try {
+            for (var _d = true, _e = __asyncValues(dirHandle.entries()), _f; _f = await _e.next(), _a = _f.done, !_a; _d = true) {
+                _c = _f.value;
+                _d = false;
+                const [name, handle] = _c;
+                if (handle.kind === 'file') {
+                    const fileHandle = handle;
+                    const file = await fileHandle.getFile();
+                    const contents = await file.text();
+                    const path = this._joinPath(basePath, name);
+                    /* c8 ignore next 2 - coverage intermittently missed in full suite */
+                    const contentType = (params === null || params === void 0 ? void 0 : params.inferContentType)
+                        ? params.inferContentType(path, file.type).orDefault()
+                        : undefined;
+                    files.push({ path, contents, contentType });
+                    handles.set(path, fileHandle);
+                }
+                else if (handle.kind === 'directory') {
+                    const subDirHandle = handle;
+                    const subPath = this._joinPath(basePath, name);
+                    const subResult = await this._loadDirectory(subDirHandle, subPath, params);
+                    files.push(...subResult.files);
+                    for (const [path, fileHandle] of subResult.handles) {
+                        handles.set(path, fileHandle);
+                    }
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (!_d && !_a && (_b = _e.return)) await _b.call(_e);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        return { files, handles };
+    }
+    /**
+     * Join path segments.
+     * @param base - The base path.
+     * @param name - The name to append.
+     * @returns The joined path.
+     * @internal
+     */
+    static _joinPath(base, name) {
+        const normalized = base.endsWith('/') ? base.slice(0, -1) : base;
+        return `${normalized}/${name}`;
+    }
+    /**
+     * Implements `FileTree.IPersistentFileTreeAccessors.syncToDisk`
+     */
+    async syncToDisk() {
+        if (!this._hasWritePermission) {
+            return (0, ts_utils_1.fail)('Write permission not granted - cannot sync to disk');
+        }
+        const errors = [];
+        // Process pending deletions from disk
+        for (const path of this._pendingDeletions) {
+            const deleteResult = await this._deleteFileFromDisk(path);
+            if (deleteResult.isFailure()) {
+                errors.push(`delete ${path}: ${deleteResult.message}`);
+            }
+        }
+        for (const path of this._dirtyFiles) {
+            const syncResult = await this._syncFile(path);
+            if (syncResult.isFailure()) {
+                errors.push(`${path}: ${syncResult.message}`);
+            }
+        }
+        if (errors.length > 0) {
+            return (0, ts_utils_1.fail)(`Failed to sync ${errors.length} file(s):\n${errors.join('\n')}`);
+        }
+        this._pendingDeletions.clear();
+        this._dirtyFiles.clear();
+        return (0, ts_utils_1.succeed)(undefined);
+    }
+    /**
+     * Implements `FileTree.IPersistentFileTreeAccessors.isDirty`
+     */
+    isDirty() {
+        return this._dirtyFiles.size > 0 || this._pendingDeletions.size > 0;
+    }
+    /**
+     * Implements `FileTree.IPersistentFileTreeAccessors.getDirtyPaths`
+     */
+    getDirtyPaths() {
+        return [...Array.from(this._dirtyFiles), ...Array.from(this._pendingDeletions)];
+    }
+    /**
+     * Override deleteFile to track pending deletions for syncToDisk.
+     */
+    deleteFile(path) {
+        const result = super.deleteFile(path);
+        if (result.isSuccess()) {
+            this._dirtyFiles.delete(path);
+            this._handles.delete(path);
+            if (this._hasWritePermission) {
+                this._pendingDeletions.add(path);
+                if (this._autoSync) {
+                    void this._runAutoSyncTask(path, 'delete', () => this._deleteFileFromDisk(path));
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Implements `FileTree.IMutableFileTreeAccessors.saveFileContents`
+     */
+    saveFileContents(path, contents) {
+        // Call parent to update in-memory state
+        const result = super.saveFileContents(path, contents);
+        if (result.isSuccess() && this._hasWritePermission) {
+            this._dirtyFiles.add(path);
+            // Auto-sync if enabled
+            if (this._autoSync) {
+                // Fire and log-on-failure; don't block the save path.
+                void this._runAutoSyncTask(path, 'save', () => this._syncFile(path));
+            }
+        }
+        return result;
+    }
+    /**
+     * Implements `FileTree.IMutableFileTreeAccessors.fileIsMutable`
+     */
+    fileIsMutable(path) {
+        const baseResult = super.fileIsMutable(path);
+        if (baseResult.isSuccess() && baseResult.detail === 'transient' && this._hasWritePermission) {
+            // Upgrade to 'persistent' if we have write permission
+            return (0, ts_utils_1.succeedWithDetail)(true, 'persistent');
+        }
+        return baseResult;
+    }
+    /**
+     * Sync a single file to disk.
+     * @param path - The path of the file to sync.
+     * @returns Promise resolving to success or failure.
+     * @internal
+     */
+    async _syncFile(path) {
+        const handle = this._handles.get(path);
+        if (!handle) {
+            return this._createAndWriteFile(path);
+        }
+        const contents = this.getFileContents(path);
+        if (contents.isFailure()) {
+            return (0, ts_utils_1.fail)(contents.message);
+        }
+        try {
+            const writable = await handle.createWritable();
+            await writable.write(contents.value);
+            await writable.close();
+            return (0, ts_utils_1.succeed)(undefined);
+            /* c8 ignore next 4 - coverage intermittently missed in full suite */
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return (0, ts_utils_1.fail)(`Failed to write file: ${message}`);
+        }
+    }
+    /**
+     * Delete a file from disk using the File System Access API.
+     * @param path - The path of the file to delete.
+     * @returns Promise resolving to success or failure.
+     * @internal
+     */
+    async _deleteFileFromDisk(path) {
+        try {
+            const absolutePath = this.resolveAbsolutePath(path);
+            const parts = absolutePath.split('/').filter((p) => p.length > 0);
+            const filename = parts.pop();
+            /* c8 ignore next 3 - defensive: invalid path */
+            if (!filename) {
+                return (0, ts_utils_1.fail)(`Invalid file path: ${path}`);
+            }
+            // Navigate to the parent directory
+            let currentDir = this._rootDir;
+            for (const part of parts) {
+                currentDir = await currentDir.getDirectoryHandle(part);
+            }
+            await currentDir.removeEntry(filename);
+            return (0, ts_utils_1.succeed)(undefined);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return (0, ts_utils_1.fail)(`Failed to delete file ${path}: ${message}`);
+        }
+    }
+    /**
+     * Create a new file and write its contents.
+     * @param path - The path of the file to create.
+     * @returns Promise resolving to success or failure.
+     * @internal
+     */
+    async _createAndWriteFile(path) {
+        try {
+            // Parse path to get directory and filename
+            const absolutePath = this.resolveAbsolutePath(path);
+            const parts = absolutePath.split('/').filter((p) => p.length > 0);
+            const filename = parts.pop();
+            /* c8 ignore next 3 - coverage intermittently missed in full suite */
+            if (!filename) {
+                return (0, ts_utils_1.fail)(`Invalid file path: ${path}`);
+            }
+            // Navigate/create directory structure
+            let currentDir = this._rootDir;
+            for (const part of parts) {
+                currentDir = await currentDir.getDirectoryHandle(part, { create: true });
+            }
+            // Create file and write contents
+            const fileHandle = await currentDir.getFileHandle(filename, { create: true });
+            this._handles.set(path, fileHandle);
+            return this._syncFile(path);
+            /* c8 ignore next 4 - coverage intermittently missed in full suite */
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return (0, ts_utils_1.fail)(`Failed to create file ${path}: ${message}`);
+        }
+    }
+}
+exports.FileSystemAccessTreeAccessors = FileSystemAccessTreeAccessors;
+//# sourceMappingURL=fileSystemAccessTreeAccessors.js.map

package/lib/packlets/file-tree/fileSystemAccessTreeAccessors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileSystemAccessTreeAccessors.js","sourceRoot":"","sources":["../../../src/packlets/file-tree/fileSystemAccessTreeAccessors.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 {\n  Result,\n  succeed,\n  fail,\n  captureResult,\n  DetailedResult,\n  succeedWithDetail,\n  Logging\n} from '@fgv/ts-utils';\nimport { FileTree } from '@fgv/ts-json-base';\nimport { FileSystemDirectoryHandle, FileSystemFileHandle } from '../file-api-types';\n\n/**\n * Options for creating persistent file trees.\n * @public\n */\nexport interface IFileSystemAccessTreeParams<TCT extends string = string>\n  extends FileTree.IFileTreeInitParams<TCT> {\n  /**\n   * Automatically sync changes to disk immediately after each save.\n   * If false, changes are batched and written on explicit syncToDisk() call.\n   * @defaultValue false\n   */\n  autoSync?: boolean;\n\n  /**\n   * Require write permission on the directory handle.\n   * If true, fails if write permission cannot be obtained.\n   * If false, falls back to read-only mode.\n   * @defaultValue true\n   */\n  requireWritePermission?: boolean;\n\n  /**\n   * Override the path at which the file is stored in the tree (for fromFileHandle).\n   * Must be an absolute path (e.g., '/data/confections/common.yaml').\n   * If omitted, defaults to `/<filename>`.\n   */\n  filePath?: string;\n\n  /** Optional logger for auto-sync and persistence failures. */\n  logger?: Logging.LogReporter<unknown>;\n}\n\n/**\n * Implementation of `FileTree.IPersistentFileTreeAccessors` that uses the File System Access API\n * to provide persistent file editing in browsers.\n * @public\n */\nexport class FileSystemAccessTreeAccessors<TCT extends string = string>\n  extends FileTree.InMemoryTreeAccessors<TCT>\n  implements FileTree.IPersistentFileTreeAccessors<TCT>\n{\n  private readonly _handles: Map<string, FileSystemFileHandle>;\n  private readonly _rootDir: FileSystemDirectoryHandle;\n  private readonly _dirtyFiles: Set<string>;\n  private readonly _pendingDeletions: Set<string>;\n  private readonly _autoSync: boolean;\n  private readonly _hasWritePermission: boolean;\n  private readonly _logger: Logging.LogReporter<unknown>;\n\n  /**\n   * Protected constructor for FileSystemAccessTreeAccessors.\n   * @param files - An array of in-memory files to include in the tree.\n   * @param rootDir - The root directory handle.\n   * @param handles - Map of file paths to their handles.\n   * @param params - Optional params for the tree.\n   * @param hasWritePermission - Whether write permission was granted.\n   */\n  protected constructor(\n    files: FileTree.IInMemoryFile<TCT>[],\n    rootDir: FileSystemDirectoryHandle,\n    handles: Map<string, FileSystemFileHandle>,\n    params: IFileSystemAccessTreeParams<TCT> | undefined,\n    hasWritePermission: boolean\n  ) {\n    super(files, params);\n    this._rootDir = rootDir;\n    this._handles = handles;\n    this._dirtyFiles = new Set();\n    this._pendingDeletions = new Set();\n    /* c8 ignore next 3 - intermittent branch coverage: ?? fallback branches in constructor */\n    this._autoSync = params?.autoSync ?? false;\n    this._hasWritePermission = hasWritePermission;\n    this._logger = params?.logger ?? new Logging.LogReporter<unknown>();\n  }\n\n  private async _runAutoSyncTask(\n    path: string,\n    operation: 'save' | 'delete',\n    action: () => Promise<Result<void>>\n  ): Promise<void> {\n    try {\n      const result = await action();\n      if (result.isFailure()) {\n        this._logger.error(`Auto-${operation} failed for ${path}: ${result.message}`);\n      }\n    } catch (err) {\n      this._logger.error(`Auto-${operation} threw for ${path}: ${String(err)}`);\n    }\n  }\n\n  /**\n   * Creates a new FileSystemAccessTreeAccessors instance from a directory handle.\n   * @param dirHandle - The FileSystemDirectoryHandle to load files from.\n   * @param params - Optional parameters including autoSync and permission settings.\n   * @returns Promise resolving to a FileSystemAccessTreeAccessors instance.\n   * @public\n   */\n  public static async fromDirectoryHandle<TCT extends string = string>(\n    dirHandle: FileSystemDirectoryHandle,\n    params?: IFileSystemAccessTreeParams<TCT>\n  ): Promise<Result<FileSystemAccessTreeAccessors<TCT>>> {\n    try {\n      // Check write permission\n      const hasWritePermission = await this._checkWritePermission(dirHandle);\n\n      /* c8 ignore next 3 - coverage intermittently missed in full suite */\n      if (!hasWritePermission && (params?.requireWritePermission ?? true)) {\n        return fail('Write permission required but not granted');\n      }\n\n      // Load all files from the directory (always use '/' as base, prefix is handled by parent)\n      const { files, handles } = await this._loadDirectory<TCT>(dirHandle, '/', params);\n\n      // Enable tree mutability when write permission is granted and caller didn't explicitly set mutable\n      const effectiveParams: IFileSystemAccessTreeParams<TCT> = {\n        ...params,\n        mutable: params?.mutable ?? (hasWritePermission ? true : false)\n      };\n\n      return succeed(\n        new FileSystemAccessTreeAccessors<TCT>(files, dirHandle, handles, effectiveParams, hasWritePermission)\n      );\n      /* c8 ignore next 4 - defensive: outer catch for unexpected errors */\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error);\n      return fail(`Failed to create FileSystemAccessTreeAccessors: ${message}`);\n    }\n  }\n\n  /**\n   * Creates a new FileSystemAccessTreeAccessors instance from a single file handle.\n   *\n   * The resulting tree contains exactly one file at `/<filename>`.\n   * `syncToDisk()` writes changes back to the original file via the File System Access API.\n   * New file creation is not supported on this tree (no parent directory handle).\n   *\n   * @param fileHandle - The FileSystemFileHandle to load.\n   * @param params - Optional parameters including autoSync and permission settings.\n   * @returns Promise resolving to a FileSystemAccessTreeAccessors instance.\n   * @public\n   */\n  public static async fromFileHandle<TCT extends string = string>(\n    fileHandle: FileSystemFileHandle,\n    params?: IFileSystemAccessTreeParams<TCT>\n  ): Promise<Result<FileSystemAccessTreeAccessors<TCT>>> {\n    try {\n      const hasWritePermission = await this._checkFileWritePermission(fileHandle);\n\n      /* c8 ignore next 1 - intermittent branch coverage: ?? true fallback */\n      if (!hasWritePermission && (params?.requireWritePermission ?? true)) {\n        return fail('Write permission required but not granted');\n      }\n\n      const file = await fileHandle.getFile();\n      const contents = await file.text();\n      const path = params?.filePath ?? `/${fileHandle.name}`;\n      /* c8 ignore next 3 - intermittent branch coverage: ternary for inferContentType */\n      const contentType = params?.inferContentType\n        ? params.inferContentType(path, file.type).orDefault()\n        : undefined;\n\n      const files: FileTree.IInMemoryFile<TCT>[] = [{ path, contents, contentType }];\n      const handles = new Map<string, FileSystemFileHandle>([[path, fileHandle]]);\n\n      const dummyRoot = {} as FileSystemDirectoryHandle;\n      const effectiveParams: IFileSystemAccessTreeParams<TCT> = {\n        ...params,\n        /* c8 ignore next 1 - intermittent branch coverage: ?? false fallback */\n        mutable: hasWritePermission ? true : params?.mutable ?? false\n      };\n\n      return succeed(\n        new FileSystemAccessTreeAccessors<TCT>(files, dummyRoot, handles, effectiveParams, hasWritePermission)\n      );\n    } catch (error) {\n      /* c8 ignore next 1 - intermittent branch coverage: error instanceof Error false branch */\n      const message = error instanceof Error ? error.message : String(error);\n      return fail(`Failed to create FileSystemAccessTreeAccessors from file: ${message}`);\n    }\n  }\n\n  /**\n   * Check if the directory handle has write permission.\n   * @param handle - The directory handle to check.\n   * @returns Promise resolving to true if write permission is granted.\n   * @internal\n   */\n  private static async _checkWritePermission(handle: FileSystemDirectoryHandle): Promise<boolean> {\n    try {\n      const permission = await handle.queryPermission({ mode: 'readwrite' });\n\n      if (permission === 'granted') {\n        return true;\n      }\n\n      if (permission === 'prompt') {\n        const requested = await handle.requestPermission({ mode: 'readwrite' });\n        return requested === 'granted';\n      }\n\n      return false;\n    } catch (error) {\n      // Permission API might not be available or might throw\n      return false;\n    }\n  }\n\n  /**\n   * Check if the file handle has write permission.\n   * @param handle - The file handle to check.\n   * @returns Promise resolving to true if write permission is granted.\n   * @internal\n   */\n  private static async _checkFileWritePermission(handle: FileSystemFileHandle): Promise<boolean> {\n    try {\n      const permission = await handle.queryPermission({ mode: 'readwrite' });\n\n      if (permission === 'granted') {\n        return true;\n      }\n\n      if (permission === 'prompt') {\n        const requested = await handle.requestPermission({ mode: 'readwrite' });\n        return requested === 'granted';\n      }\n\n      return false;\n    } catch (error) {\n      return false;\n    }\n  }\n\n  /**\n   * Load all files from a directory handle recursively.\n   * @param dirHandle - The directory handle to load from.\n   * @param basePath - The base path for files.\n   * @param params - Optional parameters.\n   * @returns Promise resolving to files and handles.\n   * @internal\n   */\n  private static async _loadDirectory<TCT extends string = string>(\n    dirHandle: FileSystemDirectoryHandle,\n    basePath: string,\n    params?: IFileSystemAccessTreeParams<TCT>\n  ): Promise<{ files: FileTree.IInMemoryFile<TCT>[]; handles: Map<string, FileSystemFileHandle> }> {\n    const files: FileTree.IInMemoryFile<TCT>[] = [];\n    const handles = new Map<string, FileSystemFileHandle>();\n\n    for await (const [name, handle] of dirHandle.entries()) {\n      if (handle.kind === 'file') {\n        const fileHandle = handle as FileSystemFileHandle;\n        const file = await fileHandle.getFile();\n        const contents = await file.text();\n        const path = this._joinPath(basePath, name);\n        /* c8 ignore next 2 - coverage intermittently missed in full suite */\n        const contentType = params?.inferContentType\n          ? params.inferContentType(path, file.type).orDefault()\n          : undefined;\n\n        files.push({ path, contents, contentType });\n        handles.set(path, fileHandle);\n      } else if (handle.kind === 'directory') {\n        const subDirHandle = handle as FileSystemDirectoryHandle;\n        const subPath = this._joinPath(basePath, name);\n        const subResult = await this._loadDirectory<TCT>(subDirHandle, subPath, params);\n        files.push(...subResult.files);\n        for (const [path, fileHandle] of subResult.handles) {\n          handles.set(path, fileHandle);\n        }\n      }\n    }\n\n    return { files, handles };\n  }\n\n  /**\n   * Join path segments.\n   * @param base - The base path.\n   * @param name - The name to append.\n   * @returns The joined path.\n   * @internal\n   */\n  private static _joinPath(base: string, name: string): string {\n    const normalized = base.endsWith('/') ? base.slice(0, -1) : base;\n    return `${normalized}/${name}`;\n  }\n\n  /**\n   * Implements `FileTree.IPersistentFileTreeAccessors.syncToDisk`\n   */\n  public async syncToDisk(): Promise<Result<void>> {\n    if (!this._hasWritePermission) {\n      return fail('Write permission not granted - cannot sync to disk');\n    }\n\n    const errors: string[] = [];\n\n    // Process pending deletions from disk\n    for (const path of this._pendingDeletions) {\n      const deleteResult = await this._deleteFileFromDisk(path);\n      if (deleteResult.isFailure()) {\n        errors.push(`delete ${path}: ${deleteResult.message}`);\n      }\n    }\n\n    for (const path of this._dirtyFiles) {\n      const syncResult = await this._syncFile(path);\n      if (syncResult.isFailure()) {\n        errors.push(`${path}: ${syncResult.message}`);\n      }\n    }\n\n    if (errors.length > 0) {\n      return fail(`Failed to sync ${errors.length} file(s):\\n${errors.join('\\n')}`);\n    }\n\n    this._pendingDeletions.clear();\n    this._dirtyFiles.clear();\n    return succeed(undefined);\n  }\n\n  /**\n   * Implements `FileTree.IPersistentFileTreeAccessors.isDirty`\n   */\n  public isDirty(): boolean {\n    return this._dirtyFiles.size > 0 || this._pendingDeletions.size > 0;\n  }\n\n  /**\n   * Implements `FileTree.IPersistentFileTreeAccessors.getDirtyPaths`\n   */\n  public getDirtyPaths(): string[] {\n    return [...Array.from(this._dirtyFiles), ...Array.from(this._pendingDeletions)];\n  }\n\n  /**\n   * Override deleteFile to track pending deletions for syncToDisk.\n   */\n  public deleteFile(path: string): Result<boolean> {\n    const result = super.deleteFile(path);\n    if (result.isSuccess()) {\n      this._dirtyFiles.delete(path);\n      this._handles.delete(path);\n\n      if (this._hasWritePermission) {\n        this._pendingDeletions.add(path);\n\n        if (this._autoSync) {\n          void this._runAutoSyncTask(path, 'delete', () => this._deleteFileFromDisk(path));\n        }\n      }\n    }\n    return result;\n  }\n\n  /**\n   * Implements `FileTree.IMutableFileTreeAccessors.saveFileContents`\n   */\n  public saveFileContents(path: string, contents: string): Result<string> {\n    // Call parent to update in-memory state\n    const result = super.saveFileContents(path, contents);\n\n    if (result.isSuccess() && this._hasWritePermission) {\n      this._dirtyFiles.add(path);\n\n      // Auto-sync if enabled\n      if (this._autoSync) {\n        // Fire and log-on-failure; don't block the save path.\n        void this._runAutoSyncTask(path, 'save', () => this._syncFile(path));\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Implements `FileTree.IMutableFileTreeAccessors.fileIsMutable`\n   */\n  public fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail> {\n    const baseResult = super.fileIsMutable(path);\n\n    if (baseResult.isSuccess() && baseResult.detail === 'transient' && this._hasWritePermission) {\n      // Upgrade to 'persistent' if we have write permission\n      return succeedWithDetail(true, 'persistent');\n    }\n\n    return baseResult;\n  }\n\n  /**\n   * Sync a single file to disk.\n   * @param path - The path of the file to sync.\n   * @returns Promise resolving to success or failure.\n   * @internal\n   */\n  private async _syncFile(path: string): Promise<Result<void>> {\n    const handle = this._handles.get(path);\n    if (!handle) {\n      return this._createAndWriteFile(path);\n    }\n\n    const contents = this.getFileContents(path);\n    if (contents.isFailure()) {\n      return fail(contents.message);\n    }\n\n    try {\n      const writable = await handle.createWritable();\n      await writable.write(contents.value);\n      await writable.close();\n      return succeed(undefined);\n      /* c8 ignore next 4 - coverage intermittently missed in full suite */\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error);\n      return fail(`Failed to write file: ${message}`);\n    }\n  }\n\n  /**\n   * Delete a file from disk using the File System Access API.\n   * @param path - The path of the file to delete.\n   * @returns Promise resolving to success or failure.\n   * @internal\n   */\n  private async _deleteFileFromDisk(path: string): Promise<Result<void>> {\n    try {\n      const absolutePath = this.resolveAbsolutePath(path);\n      const parts = absolutePath.split('/').filter((p) => p.length > 0);\n      const filename = parts.pop();\n\n      /* c8 ignore next 3 - defensive: invalid path */\n      if (!filename) {\n        return fail(`Invalid file path: ${path}`);\n      }\n\n      // Navigate to the parent directory\n      let currentDir = this._rootDir;\n      for (const part of parts) {\n        currentDir = await currentDir.getDirectoryHandle(part);\n      }\n\n      await currentDir.removeEntry(filename);\n      return succeed(undefined);\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error);\n      return fail(`Failed to delete file ${path}: ${message}`);\n    }\n  }\n\n  /**\n   * Create a new file and write its contents.\n   * @param path - The path of the file to create.\n   * @returns Promise resolving to success or failure.\n   * @internal\n   */\n  private async _createAndWriteFile(path: string): Promise<Result<void>> {\n    try {\n      // Parse path to get directory and filename\n      const absolutePath = this.resolveAbsolutePath(path);\n      const parts = absolutePath.split('/').filter((p) => p.length > 0);\n      const filename = parts.pop();\n\n      /* c8 ignore next 3 - coverage intermittently missed in full suite */\n      if (!filename) {\n        return fail(`Invalid file path: ${path}`);\n      }\n\n      // Navigate/create directory structure\n      let currentDir = this._rootDir;\n      for (const part of parts) {\n        currentDir = await currentDir.getDirectoryHandle(part, { create: true });\n      }\n\n      // Create file and write contents\n      const fileHandle = await currentDir.getFileHandle(filename, { create: true });\n      this._handles.set(path, fileHandle);\n\n      return this._syncFile(path);\n      /* c8 ignore next 4 - coverage intermittently missed in full suite */\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error);\n      return fail(`Failed to create file ${path}: ${message}`);\n    }\n  }\n}\n"]}

package/lib/packlets/file-tree/httpTreeAccessors.d.ts

@@ -0,0 +1,88 @@
+import { DetailedResult, type Result, Logging } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+/**
+ * Configuration for creating HTTP-backed tree accessors.
+ * @public
+ */
+export interface IHttpTreeParams<TCT extends string = string> extends FileTree.IFileTreeInitParams<TCT> {
+    readonly baseUrl: string;
+    readonly namespace?: string;
+    readonly autoSync?: boolean;
+    readonly fetchImpl?: typeof fetch;
+    readonly userId?: string;
+    readonly logger?: Logging.LogReporter<unknown>;
+}
+/**
+ * HTTP-backed file tree accessors that cache data in memory and persist via REST API.
+ * @public
+ */
+export declare class HttpTreeAccessors<TCT extends string = string> extends FileTree.InMemoryTreeAccessors<TCT> implements FileTree.IPersistentFileTreeAccessors<TCT> {
+    private readonly _baseUrl;
+    private readonly _namespace;
+    private readonly _fetchImpl;
+    private readonly _dirtyFiles;
+    private readonly _pendingDeletions;
+    private readonly _autoSync;
+    private readonly _userId;
+    private readonly _logger;
+    private constructor();
+    private _runAutoSyncTask;
+    /**
+     * Creates a new HttpTreeAccessors instance from an HTTP backend.
+     * @param params - Configuration parameters for the HTTP tree accessors.
+     * @returns A promise that resolves to a result containing the new HttpTreeAccessors instance or an error message.
+     */
+    static fromHttp<TCT extends string = string>(params: IHttpTreeParams<TCT>): Promise<Result<HttpTreeAccessors<TCT>>>;
+    /**
+     * Synchronizes all dirty files to the HTTP backend.
+     * @returns A promise that resolves to a result indicating success or failure.
+     */
+    syncToDisk(): Promise<Result<void>>;
+    /**
+     * Checks if there are any dirty files that need synchronization.
+     * @returns True if there are dirty files, false otherwise.
+     */
+    isDirty(): boolean;
+    /**
+     * Gets the list of paths for all dirty files.
+     * @returns An array of file paths that have been modified but not yet synchronized.
+     */
+    getDirtyPaths(): string[];
+    deleteFile(path: string): Result<boolean>;
+    /**
+     * Saves file contents and marks the file as dirty for synchronization.
+     * @param path - The path to the file.
+     * @param contents - The new contents of the file.
+     * @returns A result indicating success or failure.
+     */
+    saveFileContents(path: string, contents: string): Result<string>;
+    /**
+     * Checks if a file is mutable (can be modified).
+     * @param path - The path to the file.
+     * @returns A detailed result indicating if the file is mutable and the reason.
+     */
+    fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail>;
+    /**
+     * Makes an HTTP request to the specified resource path.
+     * @param resourcePath - The path to the resource.
+     * @param init - Optional request initialization options.
+     * @returns A promise that resolves to a result containing the response data or an error message.
+     */
+    private _request;
+    /**
+     * Loads files from the HTTP backend for the specified directory path.
+     * @param params - Configuration parameters for the HTTP tree accessors.
+     * @param directoryPath - The path to the directory to load files from.
+     * @returns A promise that resolves to a result containing the loaded files or an error message.
+     */
+    private static _loadFiles;
+    /**
+     * Makes an HTTP request with query parameters to the specified resource path.
+     * @param params - Configuration parameters for the HTTP tree accessors.
+     * @param resourcePath - The path to the resource.
+     * @param query - Query parameters to include in the request.
+     * @returns A promise that resolves to a result containing the response data or an error message.
+     */
+    private static _requestWithParams;
+}
+//# sourceMappingURL=httpTreeAccessors.d.ts.map

package/lib/packlets/file-tree/httpTreeAccessors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpTreeAccessors.d.ts","sourceRoot":"","sources":["../../../src/packlets/file-tree/httpTreeAccessors.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,cAAc,EAAQ,KAAK,MAAM,EAA8B,OAAO,EAAE,MAAM,eAAe,CAAC;AACvG,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AA4B7C;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,QAAQ,CAAC,mBAAmB,CAAC,GAAG,CAAC;IACrG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;CAChD;AAED;;;GAGG;AACH,qBAAa,iBAAiB,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,CACxD,SAAQ,QAAQ,CAAC,qBAAqB,CAAC,GAAG,CAC1C,YAAW,QAAQ,CAAC,4BAA4B,CAAC,GAAG,CAAC;IAErD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0B;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IAEvD,OAAO;YAUO,gBAAgB;IAW9B;;;;OAIG;WACiB,QAAQ,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,EACtD,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,GAC3B,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;IAQ1C;;;OAGG;IACU,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IA2DhD;;;OAGG;IACI,OAAO,IAAI,OAAO;IAIzB;;;OAGG;IACI,aAAa,IAAI,MAAM,EAAE;IAIzB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;IAiBhD;;;;;OAKG;IACI,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAgBvE;;;;OAIG;IACI,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC;IAQhF;;;;;OAKG;YACW,QAAQ;IA4BtB;;;;;OAKG;mBACkB,UAAU;IA8C/B;;;;;;OAMG;mBACkB,kBAAkB;CAuCxC"}