@vrtmrz/livesync-commonlib 0.3.0 → 0.3.1

package/dist/platform/browser/storage.d.ts

@@ -1,5 +1,6 @@
 import type { UXDataWriteOptions, UXStat } from "../../common/types.js";
 import type { IStorageAdapter } from "../../serviceModules/adapters/IStorageAdapter.js";
+import type { DirectoryEntry, StoragePath } from "../pathTypes.js";
 export type FileSystemAccessStorageStat = UXStat;
 export interface CreateFileSystemAccessStorageOptions {
     /** A directory handle already selected and authorised by the host application. */
@@ -12,10 +13,32 @@ export declare class FileSystemAccessStorageAdapter implements IStorageAdapter<F
     private resolvePath;
     private getFileHandle;
     private getDirectoryHandle;
+    private getStrictDirectoryHandle;
+    private getStrictFileHandle;
+    private requireStrictFileHandle;
+    private getStrictWritableFileHandle;
     private resolveWritablePath;
     exists(path: string): Promise<boolean>;
     trystat(path: string): Promise<FileSystemAccessStorageStat | null>;
     stat(path: string): Promise<FileSystemAccessStorageStat | null>;
+    /** Enumerate one directory without converting permission or type errors into absence. */
+    readDirectory(path: StoragePath): Promise<readonly DirectoryEntry[] | null>;
+    /** Stat a path using its exact physical spelling and preserve non-missing errors. */
+    statResolved(path: StoragePath): Promise<FileSystemAccessStorageStat | null>;
+    /** Read an exact resolved file path while preserving missing, type, and permission errors. */
+    readResolved(path: StoragePath): Promise<string>;
+    /** Read an exact resolved file path as bytes while preserving host errors. */
+    readBinaryResolved(path: StoragePath): Promise<ArrayBuffer>;
+    /** Write an exact resolved file path, creating missing parent directories. */
+    writeResolved(path: StoragePath, data: string, _options?: UXDataWriteOptions): Promise<void>;
+    /** Write bytes to an exact resolved file path, creating missing parent directories. */
+    writeBinaryResolved(path: StoragePath, data: ArrayBuffer, _options?: UXDataWriteOptions): Promise<void>;
+    /** Append through strict reads and writes so denied reads cannot become truncating writes. */
+    appendResolved(path: StoragePath, data: string, options?: UXDataWriteOptions): Promise<void>;
+    /** Remove an exact resolved path, retaining the adapter's no-op behaviour when it is absent. */
+    removeResolved(path: StoragePath): Promise<void>;
+    /** Create an exact resolved directory path without hiding browser errors. */
+    mkdirResolved(path: StoragePath): Promise<void>;
     mkdir(path: string): Promise<void>;
     remove(path: string): Promise<void>;
     read(path: string): Promise<string>;

package/dist/platform/browser/storage.js

@@ -40,6 +40,47 @@ class FileSystemAccessStorageAdapter {
       return null;
     }
   }
+  async getStrictDirectoryHandle(path) {
+    validateStoragePath(path);
+    let currentHandle = this.rootHandle;
+    for (const part of path.split("/").filter((segment) => segment !== "")) {
+      try {
+        currentHandle = await currentHandle.getDirectoryHandle(part);
+      } catch (error) {
+        if (isNamedError(error, "NotFoundError")) return null;
+        throw error;
+      }
+    }
+    return currentHandle;
+  }
+  async getStrictFileHandle(path) {
+    validateStoragePath(path, false);
+    const parts = path.split("/").filter((part) => part !== "");
+    const name = parts.pop();
+    const dirHandle = await this.getStrictDirectoryHandle(parts.join("/"));
+    if (!dirHandle) return null;
+    try {
+      return await dirHandle.getFileHandle(name);
+    } catch (error) {
+      if (isNamedError(error, "NotFoundError")) return null;
+      throw error;
+    }
+  }
+  async requireStrictFileHandle(path) {
+    const handle = await this.getStrictFileHandle(path);
+    if (!handle) throw new Error(`File not found: ${path}`);
+    return handle;
+  }
+  async getStrictWritableFileHandle(path) {
+    validateStoragePath(path, false);
+    const parts = path.split("/").filter((part) => part !== "");
+    const name = parts.pop();
+    const parentPath = parts.join("/");
+    await this.mkdir(parentPath);
+    const dirHandle = await this.getStrictDirectoryHandle(parentPath);
+    if (!dirHandle) throw new Error(`Invalid path: ${path}`);
+    return await dirHandle.getFileHandle(name, { create: true });
+  }
   async resolveWritablePath(path) {
     validateStoragePath(path, false);
     const parts = path.split("/").filter((part) => part !== "");
@@ -71,6 +112,100 @@ class FileSystemAccessStorageAdapter {
   async stat(path) {
     return await this.trystat(path);
   }
+  /** Enumerate one directory without converting permission or type errors into absence. */
+  async readDirectory(path) {
+    const dirHandle = await this.getStrictDirectoryHandle(path);
+    if (!dirHandle) return null;
+    const entries = [];
+    for await (const [name, entry] of dirHandle.entries()) {
+      if (entry.kind === "directory" || entry.kind === "file") {
+        entries.push({ name, kind: entry.kind });
+      }
+    }
+    return entries;
+  }
+  /** Stat a path using its exact physical spelling and preserve non-missing errors. */
+  async statResolved(path) {
+    validateStoragePath(path);
+    if (path === "") {
+      const now = Date.now();
+      return { size: 0, mtime: now, ctime: now, type: "folder" };
+    }
+    const parts = path.split("/");
+    const name = parts.pop();
+    const parentHandle = await this.getStrictDirectoryHandle(parts.join("/"));
+    if (!parentHandle) return null;
+    let fileHandle;
+    try {
+      fileHandle = await parentHandle.getFileHandle(name);
+    } catch (error) {
+      if (isNamedError(error, "NotFoundError")) return null;
+      if (!isNamedError(error, "TypeMismatchError")) throw error;
+      try {
+        await parentHandle.getDirectoryHandle(name);
+      } catch (directoryError) {
+        if (isNamedError(directoryError, "NotFoundError")) return null;
+        throw directoryError;
+      }
+      const now = Date.now();
+      return { size: 0, mtime: now, ctime: now, type: "folder" };
+    }
+    const file = await fileHandle.getFile();
+    return {
+      size: file.size,
+      mtime: file.lastModified,
+      ctime: file.lastModified,
+      type: "file"
+    };
+  }
+  /** Read an exact resolved file path while preserving missing, type, and permission errors. */
+  async readResolved(path) {
+    const handle = await this.requireStrictFileHandle(path);
+    return await (await handle.getFile()).text();
+  }
+  /** Read an exact resolved file path as bytes while preserving host errors. */
+  async readBinaryResolved(path) {
+    const handle = await this.requireStrictFileHandle(path);
+    return await (await handle.getFile()).arrayBuffer();
+  }
+  /** Write an exact resolved file path, creating missing parent directories. */
+  async writeResolved(path, data, _options) {
+    const handle = await this.getStrictWritableFileHandle(path);
+    const writable = await handle.createWritable();
+    await writable.write(data);
+    await writable.close();
+  }
+  /** Write bytes to an exact resolved file path, creating missing parent directories. */
+  async writeBinaryResolved(path, data, _options) {
+    const handle = await this.getStrictWritableFileHandle(path);
+    const writable = await handle.createWritable();
+    await writable.write(data);
+    await writable.close();
+  }
+  /** Append through strict reads and writes so denied reads cannot become truncating writes. */
+  async appendResolved(path, data, options) {
+    const handle = await this.getStrictFileHandle(path);
+    const existing = handle ? await (await handle.getFile()).text() : "";
+    await this.writeResolved(path, existing + data, options);
+  }
+  /** Remove an exact resolved path, retaining the adapter's no-op behaviour when it is absent. */
+  async removeResolved(path) {
+    validateStoragePath(path, false);
+    const parts = path.split("/").filter((part) => part !== "");
+    const name = parts.pop();
+    const dirHandle = await this.getStrictDirectoryHandle(parts.join("/"));
+    if (!dirHandle) return;
+    try {
+      await dirHandle.removeEntry(name, { recursive: true });
+    } catch (error) {
+      if (isNamedError(error, "NotFoundError")) return;
+      throw error;
+    }
+  }
+  /** Create an exact resolved directory path without hiding browser errors. */
+  async mkdirResolved(path) {
+    await this.mkdir(path);
+  }
   async mkdir(path) {
     validateStoragePath(path);
     let currentHandle = this.rootHandle;
@@ -131,6 +266,9 @@ function createFileSystemAccessStorage({
 }) {
   return new FileSystemAccessStorageAdapter(rootHandle);
 }
+function isNamedError(error, name) {
+  return typeof error === "object" && error !== null && "name" in error && error.name === name;
+}
 import { validateStoragePath as validateStoragePath2 } from "../storagePath.js";
 export {
   FileSystemAccessStorageAdapter,

package/dist/platform/node/UnicodeResolvingNodeStorageAdapter.d.ts

@@ -0,0 +1,79 @@
+import type { FilePath, StoragePath } from "../pathTypes.js";
+import { NodeStorageAdapter } from "./storage.js";
+/**
+ * Resolve NFC-equivalent logical paths against current Node directory names.
+ *
+ * @remarks
+ * Each operation snapshots Unicode and case settings. Version `0` delegates to
+ * the existing adapter; version `1` resolves names and rejects observed aliases
+ * before I/O. Physical spelling and the host adapter's mutation semantics remain
+ * unchanged. Resolution does not reserve paths against concurrent changes.
+ */
+export declare class UnicodeResolvingNodeStorageAdapter extends NodeStorageAdapter {
+    private readonly getPathNormalizationVersion;
+    private readonly isCaseInsensitive;
+    /**
+     * Bind a host-owned root and callbacks for each operation's comparison settings.
+     *
+     * @param rootPath - Host-selected storage directory.
+     * @param getPathNormalizationVersion - Supplies `0` or `1`; defaults to Legacy `0`.
+     * @param isCaseInsensitive - Whether comparisons ignore case; defaults to false.
+     */
+    constructor(rootPath: string, getPathNormalizationVersion?: () => number, isCaseInsensitive?: () => boolean);
+    /** Whether the current settings select NFC path resolution. */
+    get isUnicodePathNormalizationEnabled(): boolean;
+    /** Read metadata for an entry already resolved or obtained from a storage listing. */
+    statExact(path: StoragePath): Promise<import("../../common/types.js").UXStat>;
+    /** Inspect a physical directory once before descending into its enumerated entries. */
+    listExact(path: StoragePath): Promise<{
+        files: StoragePath[];
+        folders: StoragePath[];
+    }>;
+    /**
+     * Resolve a logical path under one snapshot of the current settings.
+     *
+     * @param path - Original root-relative file path.
+     * @param caseInsensitive - Override this lookup's case rule without changing settings.
+     * @param allowMissing - Keep a missing write suffix when true; defaults to true.
+     * @returns The physical target, or `null` for an absent path when `allowMissing`
+     * is false in NFC mode. Legacy mode returns the validated original path.
+     * @throws Propagates NFC ambiguity and reader failures, and rejects invalid input.
+     */
+    resolveLogicalPath(path: FilePath, caseInsensitive?: boolean, allowMissing?: boolean): Promise<StoragePath | null>;
+    /** Check whether the logical path exists under the current Unicode policy. */
+    exists(path: string, caseInsensitive?: boolean): Promise<boolean>;
+    /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+    trystat(path: string, caseInsensitive?: boolean): Promise<import("../../common/types.js").UXStat>;
+    /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+    stat(path: string, caseInsensitive?: boolean): Promise<import("../../common/types.js").UXStat>;
+    /** Create a directory at the resolved write target. */
+    mkdir(path: string, caseInsensitive?: boolean): Promise<void>;
+    /** Remove the entry at its resolved physical path. */
+    remove(path: string, caseInsensitive?: boolean): Promise<void>;
+    /** Read text from the resolved physical file. */
+    read(path: string, caseInsensitive?: boolean): Promise<string>;
+    /** Read bytes from the resolved physical file. */
+    readBinary(path: string, caseInsensitive?: boolean): Promise<ArrayBuffer>;
+    /** Write text at the resolved target while retaining existing physical spelling. */
+    write(path: string, data: string, options?: Parameters<NodeStorageAdapter["write"]>[2], caseInsensitive?: boolean): Promise<void>;
+    /** Write bytes at the resolved target while retaining existing physical spelling. */
+    writeBinary(path: string, data: ArrayBuffer, options?: Parameters<NodeStorageAdapter["writeBinary"]>[2], caseInsensitive?: boolean): Promise<void>;
+    /** Append text at the resolved target using the host adapter semantics. */
+    append(path: string, data: string, options?: Parameters<NodeStorageAdapter["append"]>[2], caseInsensitive?: boolean): Promise<void>;
+    /** Resolve and perform an explicit rename, including a requested leaf spelling change. */
+    rename(sourcePath: string, targetPath: string, caseInsensitive?: boolean): Promise<void>;
+    /** List logical directory contents, checking equivalent child names in NFC mode. */
+    list(basePath: string, caseInsensitive?: boolean): Promise<{
+        files: string[];
+        folders: string[];
+    }>;
+    private statWithSettings;
+    private requireExistingPath;
+    private preflightRequestedPath;
+    private listPhysicalDirectory;
+    private createResolver;
+    private getSettings;
+    private getPathNormalizationVersionSnapshot;
+    private asStoragePath;
+    private missingPathError;
+}

package/dist/platform/node/UnicodeResolvingNodeStorageAdapter.js

@@ -0,0 +1,218 @@
+import { getPathNormalizationVersion as getSupportedPathNormalizationVersion } from "../../common/pathNormalization.js";
+import { createStoragePathResolver } from "../storagePathResolution.js";
+import { parseFilePath } from "../pathComparison.js";
+import { NodeStorageAdapter } from "./storage.js";
+class UnicodeResolvingNodeStorageAdapter extends NodeStorageAdapter {
+  /**
+   * Bind a host-owned root and callbacks for each operation's comparison settings.
+   *
+   * @param rootPath - Host-selected storage directory.
+   * @param getPathNormalizationVersion - Supplies `0` or `1`; defaults to Legacy `0`.
+   * @param isCaseInsensitive - Whether comparisons ignore case; defaults to false.
+   */
+  constructor(rootPath, getPathNormalizationVersion = () => 0, isCaseInsensitive = () => false) {
+    super(rootPath);
+    this.getPathNormalizationVersion = getPathNormalizationVersion;
+    this.isCaseInsensitive = isCaseInsensitive;
+  }
+  getPathNormalizationVersion;
+  isCaseInsensitive;
+  /** Whether the current settings select NFC path resolution. */
+  get isUnicodePathNormalizationEnabled() {
+    return this.getPathNormalizationVersionSnapshot() === 1;
+  }
+  /** Read metadata for an entry already resolved or obtained from a storage listing. */
+  async statExact(path) {
+    const settings = this.getSettings();
+    if (settings.pathNormalizationVersion === 0) return await super.trystat(path);
+    return await super.statResolved(this.asStoragePath(path));
+  }
+  /** Inspect a physical directory once before descending into its enumerated entries. */
+  async listExact(path) {
+    const settings = this.getSettings();
+    if (settings.pathNormalizationVersion === 0) {
+      const entries = await super.list(path);
+      return {
+        files: entries.files.map((entry) => this.asStoragePath(entry)),
+        folders: entries.folders.map((entry) => this.asStoragePath(entry))
+      };
+    }
+    return await this.listPhysicalDirectory(this.asStoragePath(path), settings);
+  }
+  /**
+   * Resolve a logical path under one snapshot of the current settings.
+   *
+   * @param path - Original root-relative file path.
+   * @param caseInsensitive - Override this lookup's case rule without changing settings.
+   * @param allowMissing - Keep a missing write suffix when true; defaults to true.
+   * @returns The physical target, or `null` for an absent path when `allowMissing`
+   * is false in NFC mode. Legacy mode returns the validated original path.
+   * @throws Propagates NFC ambiguity and reader failures, and rejects invalid input.
+   */
+  async resolveLogicalPath(path, caseInsensitive, allowMissing = true) {
+    const settings = this.getSettings(caseInsensitive);
+    const filePath = parseFilePath(path);
+    if (settings.pathNormalizationVersion === 0) return filePath;
+    await this.preflightRequestedPath(filePath);
+    const resolver = this.createResolver(settings);
+    return allowMissing ? await resolver.resolveForWrite(filePath) : await resolver.resolveExisting(filePath);
+  }
+  /** Check whether the logical path exists under the current Unicode policy. */
+  async exists(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.exists(path);
+    await this.preflightRequestedPath(path);
+    const resolver = this.createResolver(settings);
+    const resolvedPath = await resolver.resolveExisting(parseFilePath(path));
+    if (resolvedPath === null) return false;
+    return await super.statResolved(resolvedPath) !== null;
+  }
+  /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+  async trystat(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    return await this.statWithSettings(path, settings);
+  }
+  /** Read logical-path metadata, retaining Legacy adapter behaviour in version `0`. */
+  async stat(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    return await this.statWithSettings(path, settings);
+  }
+  /** Create a directory at the resolved write target. */
+  async mkdir(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.mkdir(path);
+    await this.preflightRequestedPath(path);
+    const resolvedPath = await this.createResolver(settings).resolveForWrite(parseFilePath(path));
+    await super.mkdirResolved(resolvedPath);
+  }
+  /** Remove the entry at its resolved physical path. */
+  async remove(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.remove(path);
+    const resolvedPath = await this.requireExistingPath(path, this.createResolver(settings));
+    await super.removeResolved(resolvedPath);
+  }
+  /** Read text from the resolved physical file. */
+  async read(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.read(path);
+    const resolvedPath = await this.requireExistingPath(path, this.createResolver(settings));
+    return await super.readResolved(resolvedPath);
+  }
+  /** Read bytes from the resolved physical file. */
+  async readBinary(path, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.readBinary(path);
+    const resolvedPath = await this.requireExistingPath(path, this.createResolver(settings));
+    return await super.readBinaryResolved(resolvedPath);
+  }
+  /** Write text at the resolved target while retaining existing physical spelling. */
+  async write(path, data, options, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.write(path, data, options);
+    await this.preflightRequestedPath(path);
+    const resolvedPath = await this.createResolver(settings).resolveForWrite(parseFilePath(path));
+    await super.writeResolved(resolvedPath, data, options);
+  }
+  /** Write bytes at the resolved target while retaining existing physical spelling. */
+  async writeBinary(path, data, options, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.writeBinary(path, data, options);
+    await this.preflightRequestedPath(path);
+    const resolvedPath = await this.createResolver(settings).resolveForWrite(parseFilePath(path));
+    await super.writeBinaryResolved(resolvedPath, data, options);
+  }
+  /** Append text at the resolved target using the host adapter semantics. */
+  async append(path, data, options, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.append(path, data, options);
+    await this.preflightRequestedPath(path);
+    const resolvedPath = await this.createResolver(settings).resolveForWrite(parseFilePath(path));
+    await super.appendResolved(resolvedPath, data, options);
+  }
+  /** Resolve and perform an explicit rename, including a requested leaf spelling change. */
+  async rename(sourcePath, targetPath, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.rename(sourcePath, targetPath);
+    await this.preflightRequestedPath(sourcePath, false);
+    await this.preflightRequestedPath(targetPath, false);
+    const resolver = this.createResolver(settings);
+    const resolved = await resolver.resolveRename(parseFilePath(sourcePath), parseFilePath(targetPath));
+    if (resolved === null) throw this.missingPathError(sourcePath);
+    await super.renameResolved(resolved.source, resolved.target);
+  }
+  /** List logical directory contents, checking equivalent child names in NFC mode. */
+  async list(basePath, caseInsensitive) {
+    const settings = this.getSettings(caseInsensitive);
+    if (settings.pathNormalizationVersion === 0) return await super.list(basePath);
+    await this.preflightRequestedPath(basePath);
+    const resolver = this.createResolver(settings);
+    const resolvedPath = await resolver.resolveExisting(parseFilePath(basePath));
+    if (resolvedPath === null) return { files: [], folders: [] };
+    return await this.listPhysicalDirectory(resolvedPath, settings, resolver);
+  }
+  async statWithSettings(path, settings) {
+    if (settings.pathNormalizationVersion === 0) return await super.trystat(path);
+    await this.preflightRequestedPath(path);
+    const resolvedPath = await this.createResolver(settings).resolveExisting(parseFilePath(path));
+    if (resolvedPath === null) return null;
+    return await super.statResolved(resolvedPath);
+  }
+  async requireExistingPath(path, resolver) {
+    await this.preflightRequestedPath(path);
+    const resolvedPath = await resolver.resolveExisting(parseFilePath(path));
+    if (resolvedPath === null) throw this.missingPathError(path);
+    return resolvedPath;
+  }
+  async preflightRequestedPath(path, allowRoot = true) {
+    try {
+      await this.resolvePath(path, allowRoot);
+    } catch (error) {
+      if (error.code === "ENOTDIR") return;
+      throw error;
+    }
+  }
+  async listPhysicalDirectory(path, settings, resolver = this.createResolver(settings)) {
+    const entries = await resolver.listResolvedDirectory(path);
+    const files = [];
+    const folders = [];
+    for (const entry of entries ?? []) {
+      if (entry.kind === "directory") folders.push(entry.path);
+      else files.push(entry.path);
+    }
+    return { files, folders };
+  }
+  createResolver(settings) {
+    return createStoragePathResolver({
+      readDirectory: async (path) => await super.readDirectory(path),
+      policy: {
+        pathNormalizationVersion: 1,
+        handleFilenameCaseSensitive: !settings.caseInsensitive
+      }
+    });
+  }
+  getSettings(caseInsensitive) {
+    const pathNormalizationVersion = this.getPathNormalizationVersionSnapshot();
+    return {
+      pathNormalizationVersion,
+      caseInsensitive: caseInsensitive ?? this.isCaseInsensitive()
+    };
+  }
+  getPathNormalizationVersionSnapshot() {
+    return getSupportedPathNormalizationVersion({
+      pathNormalizationVersion: this.getPathNormalizationVersion()
+    });
+  }
+  asStoragePath(path) {
+    return parseFilePath(path);
+  }
+  missingPathError(path) {
+    const error = new Error("ENOENT: no such file or directory, " + path);
+    error.code = "ENOENT";
+    error.path = path;
+    return error;
+  }
+}
+export {
+  UnicodeResolvingNodeStorageAdapter
+};

package/dist/platform/node/index.d.ts

@@ -20,5 +20,6 @@ export declare const readline: typeof nodeReadlinePromises;
 export declare const builtinModules: readonly string[];
 /** Returns whether a module specifier refers to a Node built-in. */
 export declare const isBuiltin: typeof nodeIsBuiltin;
+export { UnicodeResolvingNodeStorageAdapter } from "./UnicodeResolvingNodeStorageAdapter.js";
 export { NodeStorageAdapter, createNodeStorage, getNodeFileCreationTime, validateStoragePath, type CreateNodeStorageOptions, type NodeStorageStat, } from "./storage.js";
 export { createNodeStandardIo, type CreateNodeStandardIoOptions, type NodeStandardInput, type NodeStandardOutput, } from "./standardIo.js";

package/dist/platform/node/index.js

@@ -12,6 +12,7 @@ const os = nodeOs;
 const readline = nodeReadlinePromises;
 const builtinModules = nodeBuiltinModules;
 const isBuiltin = nodeIsBuiltin;
+import { UnicodeResolvingNodeStorageAdapter } from "./UnicodeResolvingNodeStorageAdapter.js";
 import {
   NodeStorageAdapter,
   createNodeStorage,
@@ -23,6 +24,7 @@ import {
 } from "./standardIo.js";
 export {
   NodeStorageAdapter,
+  UnicodeResolvingNodeStorageAdapter,
   builtinModules,
   createNodeStandardIo,
   createNodeStorage,

package/dist/platform/node/storage.d.ts

@@ -1,6 +1,7 @@
 import type { Stats } from "node:fs";
 import type { UXDataWriteOptions, UXStat } from "../../common/types.js";
 import type { IStorageAdapter } from "../../serviceModules/adapters/IStorageAdapter.js";
+import type { DirectoryEntry, StoragePath } from "../pathTypes.js";
 export type NodeStorageStat = UXStat;
 /** Read creation time in integer milliseconds, using change time when birth time is unavailable. */
 export declare function getNodeFileCreationTime(stat: Pick<Stats, "birthtimeMs" | "ctimeMs">): number;
@@ -17,20 +18,48 @@ export interface CreateNodeStorageOptions {
 export declare class NodeStorageAdapter implements IStorageAdapter<NodeStorageStat> {
     private readonly rootPath;
     constructor(rootPath: string);
-    private resolvePath;
+    protected resolvePath(path: string, allowRoot?: boolean): Promise<string>;
     private assertNoSymbolicLinks;
     exists(path: string): Promise<boolean>;
     trystat(path: string): Promise<NodeStorageStat | null>;
+    /** Read metadata for an exact physical path, returning null only when it is absent. */
+    statResolved(path: StoragePath): Promise<NodeStorageStat | null>;
+    /** Enumerate immediate physical children, returning null only when the directory is absent. */
+    readDirectory(path: StoragePath): Promise<readonly DirectoryEntry[] | null>;
     stat(path: string): Promise<NodeStorageStat | null>;
     mkdir(path: string): Promise<void>;
+    /** Create an exact resolved directory path. */
+    mkdirResolved(path: StoragePath): Promise<void>;
+    private mkdirPath;
     remove(path: string): Promise<void>;
+    /** Remove an exact resolved file or directory path. */
+    removeResolved(path: StoragePath): Promise<void>;
+    private removePath;
     read(path: string): Promise<string>;
+    /** Read a file by its exact resolved physical path. */
+    readResolved(path: StoragePath): Promise<string>;
+    private readPath;
     readBinary(path: string): Promise<ArrayBuffer>;
+    /** Read bytes by their exact resolved physical path. */
+    readBinaryResolved(path: StoragePath): Promise<ArrayBuffer>;
+    private readBinaryPath;
     write(path: string, data: string, options?: UXDataWriteOptions): Promise<void>;
+    /** Write text to an exact resolved physical path. */
+    writeResolved(path: StoragePath, data: string, options?: UXDataWriteOptions): Promise<void>;
+    private writePath;
     writeBinary(path: string, data: ArrayBuffer, options?: UXDataWriteOptions): Promise<void>;
+    /** Write bytes to an exact resolved physical path. */
+    writeBinaryResolved(path: StoragePath, data: ArrayBuffer, options?: UXDataWriteOptions): Promise<void>;
+    private writeBinaryPath;
     append(path: string, data: string, options?: UXDataWriteOptions): Promise<void>;
+    /** Append text to an exact resolved physical path. */
+    appendResolved(path: StoragePath, data: string, options?: UXDataWriteOptions): Promise<void>;
+    private appendPath;
     /** Atomically rename or move an entry without leaving the injected root. */
     rename(sourcePath: string, targetPath: string): Promise<void>;
+    /** Rename or move exact resolved physical paths without leaving the injected root. */
+    renameResolved(sourcePath: StoragePath, targetPath: StoragePath): Promise<void>;
+    private renamePath;
     list(basePath: string): Promise<{
         files: string[];
         folders: string[];