@bendyline/docblocks 1.1.1 → 2.0.0

package/src/filesystem/native-provider.ts

@@ -6,12 +6,18 @@
  * the API (Chrome, Edge). Feature-detect with `isNativeFileSystemSupported()`.
  */
 
-import type { FileSystemProvider, FileSystemEntry, FileMeta } from './types.js';
+import type { FileCommitResult, FileSystemProvider, FileSystemEntry, FileMeta } from './types.js';
+import { withFileCommitLock } from './commit-lock.js';
+import { NativeFileSystemProviderV2 } from './native-provider-v2.js';
+import { parseWorkspacePath } from './workspace-path.js';
 
 // ── Feature detection ──────────────────────────────────────────────
 
 export function isNativeFileSystemSupported(): boolean {
-  return typeof globalThis !== 'undefined' && 'showDirectoryPicker' in globalThis;
+  return (
+    typeof globalThis !== 'undefined' &&
+    typeof (globalThis as { showDirectoryPicker?: unknown }).showDirectoryPicker === 'function'
+  );
 }
 
 // ── Handle persistence (IndexedDB, structured clone) ───────────────
@@ -89,7 +95,33 @@ export async function removeDirectoryHandle(workspaceId: string): Promise<void>
 // ── Helpers ────────────────────────────────────────────────────────
 
 function normalisePath(p: string): string {
-  return p.replace(/\\/g, '/').replace(/\/+/g, '/').replace(/^\//, '').replace(/\/$/, '');
+  return parseWorkspacePath(p);
+}
+
+function errorName(error: unknown): string | undefined {
+  return typeof error === 'object' && error !== null && 'name' in error
+    ? String((error as { name?: unknown }).name)
+    : undefined;
+}
+
+function isMissingEntryError(error: unknown): boolean {
+  const name = errorName(error);
+  return name === 'NotFoundError' || name === 'TypeMismatchError';
+}
+
+function isPermissionError(error: unknown): boolean {
+  const name = errorName(error);
+  return name === 'NotAllowedError' || name === 'SecurityError';
+}
+
+class NativeMoveRecoveryError extends Error {
+  readonly causes: readonly unknown[];
+
+  constructor(message: string, causes: readonly unknown[]) {
+    super(message);
+    this.name = 'NativeMoveRecoveryError';
+    this.causes = causes;
+  }
 }
 
 /**
@@ -106,8 +138,9 @@ async function resolveDir(
   for (const part of parts) {
     try {
       current = await current.getDirectoryHandle(part);
-    } catch {
-      return null;
+    } catch (error: unknown) {
+      if (isMissingEntryError(error)) return null;
+      throw error;
     }
   }
   return current;
@@ -139,11 +172,32 @@ function baseName(p: string): string {
   return idx === -1 ? p : p.slice(idx + 1);
 }
 
+function toWritableBinary(data: ArrayBuffer | Uint8Array): ArrayBuffer {
+  if (data instanceof ArrayBuffer) return data;
+  const copy = new Uint8Array(data.byteLength);
+  copy.set(data);
+  return copy.buffer;
+}
+
+async function writeAndClose(
+  writable: FileSystemWritableFileStream,
+  data: string | ArrayBuffer,
+): Promise<void> {
+  try {
+    await writable.write(data);
+    await writable.close();
+  } catch (error: unknown) {
+    await writable.abort(error).catch(() => undefined);
+    throw error;
+  }
+}
+
 // ── Implementation ─────────────────────────────────────────────────
 
 export class NativeFileSystemProvider implements FileSystemProvider {
   readonly id: string;
   readonly label: string;
+  readonly v2: NativeFileSystemProviderV2;
 
   private root: FileSystemDirectoryHandle;
 
@@ -151,11 +205,17 @@ export class NativeFileSystemProvider implements FileSystemProvider {
     this.id = id;
     this.label = root.name;
     this.root = root;
+    this.v2 = new NativeFileSystemProviderV2(id, root);
+  }
+
+  private withMutationLock<T>(operation: () => Promise<T>): Promise<T> {
+    return withFileCommitLock(`native:${this.id}:workspace`, operation);
   }
 
-  private async copyDirectory(oldDirPath: string, newDirPath: string): Promise<boolean> {
+  private async copyDirectory(oldDirPath: string, newDirPath: string): Promise<void> {
     const source = await resolveDir(this.root, oldDirPath);
-    if (!source) return false;
+    if (!source)
+      throw new DOMException(`Source directory does not exist: ${oldDirPath}`, 'NotFoundError');
     await resolveDirCreate(this.root, newDirPath);
 
     for await (const [name, handle] of source as unknown as AsyncIterable<
@@ -168,11 +228,9 @@ export class NativeFileSystemProvider implements FileSystemProvider {
       } else {
         const fileHandle = await source.getFileHandle(name);
         const file = await fileHandle.getFile();
-        await this.writeBinary(newChild, await file.arrayBuffer());
+        await this.writeBinaryUnlocked(newChild, await file.arrayBuffer());
       }
     }
-
-    return true;
   }
 
   async readFile(path: string): Promise<string | null> {
@@ -183,30 +241,70 @@ export class NativeFileSystemProvider implements FileSystemProvider {
       const fileHandle = await dir.getFileHandle(baseName(p));
       const file = await fileHandle.getFile();
       return file.text();
-    } catch {
-      return null;
+    } catch (error: unknown) {
+      if (isMissingEntryError(error)) return null;
+      throw error;
     }
   }
 
   async writeFile(path: string, content: string): Promise<void> {
+    return this.withMutationLock(() => this.writeFileUnlocked(path, content));
+  }
+
+  private async writeFileUnlocked(path: string, content: string): Promise<void> {
     const p = normalisePath(path);
     const dir = await resolveDirCreate(this.root, parentDir(p));
     const fileHandle = await dir.getFileHandle(baseName(p), { create: true });
     const writable = await fileHandle.createWritable();
-    await writable.write(content);
-    await writable.close();
+    await writeAndClose(writable, content);
+  }
+
+  async commitFile(
+    path: string,
+    content: string,
+    expectedContent: string | null,
+  ): Promise<FileCommitResult> {
+    const p = normalisePath(path);
+    return this.withMutationLock(async () => {
+      const current = await this.readFile(p);
+      if (current !== expectedContent && current !== content) {
+        const meta = await this.stat(p);
+        return {
+          status: 'conflict',
+          content: current,
+          version: meta?.lastModified ?? null,
+        };
+      }
+      await this.writeFileUnlocked(p, content);
+      const meta = await this.stat(p);
+      return { status: 'committed', version: meta?.lastModified ?? null };
+    });
   }
 
   async delete(path: string): Promise<void> {
+    return this.withMutationLock(() => this.deleteUnlocked(path));
+  }
+
+  private async deleteUnlocked(path: string): Promise<void> {
     const p = normalisePath(path);
+    if (!p) throw new Error('Cannot delete the filesystem root');
     const parent = parentDir(p);
     const name = baseName(p);
     const dir = await resolveDir(this.root, parent);
     if (!dir) return;
-    await dir.removeEntry(name, { recursive: true });
+    try {
+      await dir.removeEntry(name, { recursive: true });
+    } catch (error: unknown) {
+      if (isMissingEntryError(error)) return;
+      throw error;
+    }
   }
 
   async rename(oldPath: string, newPath: string): Promise<void> {
+    return this.withMutationLock(() => this.renameUnlocked(oldPath, newPath));
+  }
+
+  private async renameUnlocked(oldPath: string, newPath: string): Promise<void> {
     const op = normalisePath(oldPath);
     const np = normalisePath(newPath);
     if (op === np) return;
@@ -216,25 +314,72 @@ export class NativeFileSystemProvider implements FileSystemProvider {
     if (np.startsWith(op + '/')) {
       throw new Error('Cannot move a directory into itself');
     }
+    if (!(await this.exists(op))) {
+      throw new Error(`Source does not exist: ${oldPath}`);
+    }
+    if (await this.exists(np)) {
+      throw new Error(`Destination exists: ${newPath}`);
+    }
 
     // The File System Access API doesn't have a native rename.
     // Copy → delete.
     const oldParent = await resolveDir(this.root, parentDir(op));
-    if (!oldParent) return;
+    if (!oldParent) {
+      throw new DOMException(`Source does not exist: ${oldPath}`, 'NotFoundError');
+    }
 
+    let fileHandle: FileSystemFileHandle | null = null;
     try {
-      const fileHandle = await oldParent.getFileHandle(baseName(op));
+      fileHandle = await oldParent.getFileHandle(baseName(op));
+    } catch (error: unknown) {
+      if (!isMissingEntryError(error)) throw error;
+    }
+
+    if (fileHandle) {
       const file = await fileHandle.getFile();
-      await this.writeBinary(np, await file.arrayBuffer());
-      await this.delete(op);
+      await this.writeBinaryUnlocked(np, await file.arrayBuffer());
+      try {
+        await this.deleteUnlocked(op);
+      } catch (error: unknown) {
+        try {
+          await this.deleteUnlocked(np);
+        } catch (rollbackError: unknown) {
+          throw new NativeMoveRecoveryError(
+            `Move partially completed and rollback failed: ${oldPath} -> ${newPath}`,
+            [error, rollbackError],
+          );
+        }
+        throw error;
+      }
       return;
-    } catch {
-      // Not a file; try directory below.
     }
 
-    const copied = await this.copyDirectory(op, np);
-    if (copied) {
-      await this.delete(op);
+    try {
+      await this.copyDirectory(op, np);
+    } catch (error: unknown) {
+      try {
+        await this.deleteUnlocked(np);
+      } catch (rollbackError: unknown) {
+        throw new NativeMoveRecoveryError(
+          `Move failed and destination cleanup failed: ${oldPath} -> ${newPath}`,
+          [error, rollbackError],
+        );
+      }
+      throw error;
+    }
+
+    try {
+      await this.deleteUnlocked(op);
+    } catch (error: unknown) {
+      try {
+        await this.deleteUnlocked(np);
+      } catch (rollbackError: unknown) {
+        throw new NativeMoveRecoveryError(
+          `Move partially completed and rollback failed: ${oldPath} -> ${newPath}`,
+          [error, rollbackError],
+        );
+      }
+      throw error;
     }
   }
 
@@ -274,19 +419,23 @@ export class NativeFileSystemProvider implements FileSystemProvider {
     try {
       await dir.getFileHandle(name);
       return true;
-    } catch {
+    } catch (fileError: unknown) {
+      if (!isMissingEntryError(fileError)) throw fileError;
       try {
         await dir.getDirectoryHandle(name);
         return true;
-      } catch {
+      } catch (directoryError: unknown) {
+        if (!isMissingEntryError(directoryError)) throw directoryError;
         return false;
       }
     }
   }
 
   async createDirectory(path: string): Promise<void> {
-    const p = normalisePath(path);
-    await resolveDirCreate(this.root, p);
+    return this.withMutationLock(async () => {
+      const p = normalisePath(path);
+      await resolveDirCreate(this.root, p);
+    });
   }
 
   async stat(path: string): Promise<FileMeta | null> {
@@ -303,8 +452,9 @@ export class NativeFileSystemProvider implements FileSystemProvider {
         size: file.size,
         lastModified: new Date(file.lastModified).toISOString(),
       };
-    } catch {
-      return null;
+    } catch (error: unknown) {
+      if (isMissingEntryError(error)) return null;
+      throw error;
     }
   }
 
@@ -316,22 +466,22 @@ export class NativeFileSystemProvider implements FileSystemProvider {
       const fileHandle = await dir.getFileHandle(baseName(p));
       const file = await fileHandle.getFile();
       return file.arrayBuffer();
-    } catch {
-      return null;
+    } catch (error: unknown) {
+      if (isMissingEntryError(error)) return null;
+      throw error;
     }
   }
 
   async writeBinary(path: string, data: ArrayBuffer | Uint8Array): Promise<void> {
+    return this.withMutationLock(() => this.writeBinaryUnlocked(path, data));
+  }
+
+  private async writeBinaryUnlocked(path: string, data: ArrayBuffer | Uint8Array): Promise<void> {
     const p = normalisePath(path);
     const dir = await resolveDirCreate(this.root, parentDir(p));
     const fileHandle = await dir.getFileHandle(baseName(p), { create: true });
     const writable = await fileHandle.createWritable();
-    if (data instanceof ArrayBuffer) {
-      await writable.write(data);
-    } else {
-      await writable.write(data.buffer as ArrayBuffer);
-    }
-    await writable.close();
+    await writeAndClose(writable, toWritableBinary(data));
   }
 }
 
@@ -346,8 +496,10 @@ export async function openNativeFolder(): Promise<NativeFileSystemProvider> {
   }
 
   const handle = await (
-    globalThis as unknown as { showDirectoryPicker: () => Promise<FileSystemDirectoryHandle> }
-  ).showDirectoryPicker();
+    globalThis as unknown as {
+      showDirectoryPicker: (options: { mode: 'readwrite' }) => Promise<FileSystemDirectoryHandle>;
+    }
+  ).showDirectoryPicker({ mode: 'readwrite' });
   const id = `native-${handle.name}-${Date.now()}`;
   await storeDirectoryHandle(id, handle);
   return new NativeFileSystemProvider(id, handle);
@@ -370,11 +522,15 @@ export async function restoreNativeFolder(
     queryPermission(desc: { mode: string }): Promise<string>;
     requestPermission(desc: { mode: string }): Promise<string>;
   };
-  if ((await h.queryPermission(opts)) === 'granted') {
-    return new NativeFileSystemProvider(workspaceId, handle);
-  }
-  if ((await h.requestPermission(opts)) === 'granted') {
-    return new NativeFileSystemProvider(workspaceId, handle);
+  try {
+    if ((await h.queryPermission(opts)) === 'granted') {
+      return new NativeFileSystemProvider(workspaceId, handle);
+    }
+    if ((await h.requestPermission(opts)) === 'granted') {
+      return new NativeFileSystemProvider(workspaceId, handle);
+    }
+  } catch (error: unknown) {
+    if (!isPermissionError(error)) throw error;
   }
 
   return null;

package/src/filesystem/native.ts

@@ -0,0 +1,16 @@
+/** Browser File System Access API provider entry point. */
+export {
+  NativeFileSystemProvider,
+  isNativeFileSystemSupported,
+  openNativeFolder,
+  restoreNativeFolder,
+  storeDirectoryHandle,
+  loadDirectoryHandle,
+  removeDirectoryHandle,
+} from './native-provider.js';
+export {
+  NativeFileSystemProviderV2,
+  NativeFileSystemMoveRecoveryError,
+  type NativeFileSystemMovePathState,
+  type NativeFileSystemMoveRecoveryState,
+} from './native-provider-v2.js';

package/src/filesystem/types.ts

@@ -1,12 +1,15 @@
 /**
  * FileSystemProvider — abstract interface for a virtual filesystem.
  *
- * Implementations back onto IndexedDB (for browser-local storage) or
- * the File System Access API (for native folder access).
+ * Legacy text-oriented facade retained while consumers migrate to
+ * FileSystemProviderV2. New persistence code must use the provider's `v2`
+ * contract so paths, errors, operation modes, and capabilities are explicit.
  */
 
 // ── Entry types ────────────────────────────────────────────────────
 
+import type { FileSystemProviderV2 } from './v2.js';
+
 export interface FileEntry {
   kind: 'file';
   name: string;
@@ -28,8 +31,17 @@ export interface FileMeta {
   lastModified: string;
 }
 
+export type FileCommitResult =
+  | { status: 'committed'; version: string | null }
+  | { status: 'conflict'; content: string | null; version: string | null };
+
 // ── Provider interface ─────────────────────────────────────────────
 
+/**
+ * @deprecated Compatibility facade for external providers and older callers.
+ * Implement new backends with `FileSystemProviderV2`; built-in facades expose
+ * their authoritative implementation through `v2`.
+ */
 export interface FileSystemProvider {
   /** Unique identifier for this provider instance. */
   readonly id: string;
@@ -37,16 +49,33 @@ export interface FileSystemProvider {
   /** Human-readable label (e.g., folder name or "Browser Storage"). */
   readonly label: string;
 
+  /** Optional correctness-first implementation exposed during the v1-to-v2 migration. */
+  readonly v2?: FileSystemProviderV2;
+
   /** Read the text content of a file. Returns null if the file doesn't exist. */
   readFile(path: string): Promise<string | null>;
 
   /** Write text content to a file, creating it (and parent dirs) if needed. */
   writeFile(path: string, content: string): Promise<void>;
 
-  /** Delete a file or empty directory. */
+  /**
+   * Conditionally replace a text file when it still matches the caller's
+   * persisted baseline. Production providers implement this at their
+   * strongest available serialization boundary.
+   */
+  commitFile?(
+    path: string,
+    content: string,
+    expectedContent: string | null,
+  ): Promise<FileCommitResult>;
+
+  /**
+   * Legacy recursive removal of a file or directory subtree. Workspace root
+   * deletion is forbidden. Prefer v2 `remove({ recursive })`.
+   */
   delete(path: string): Promise<void>;
 
-  /** Rename or move an entry. */
+  /** Rename or move an entry. Rejects missing sources and existing destinations. */
   rename(oldPath: string, newPath: string): Promise<void>;
 
   /** List immediate children of a directory. */
@@ -67,3 +96,19 @@ export interface FileSystemProvider {
   /** Write raw binary content. */
   writeBinary(path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
 }
+
+export type FileSystemProviderWithV2 = FileSystemProvider & {
+  readonly v2: FileSystemProviderV2;
+};
+
+/** Discover a provider-owned v2 implementation without coupling consumers to a concrete class. */
+export function hasFileSystemProviderV2(
+  provider: FileSystemProvider,
+): provider is FileSystemProviderWithV2 {
+  return provider.v2 !== undefined && provider.v2 !== null;
+}
+
+/** Return the provider-owned v2 implementation when migration support is available. */
+export function getFileSystemProviderV2(provider: FileSystemProvider): FileSystemProviderV2 | null {
+  return provider.v2 ?? null;
+}