@bendyline/docblocks 0.1.0

package/src/filesystem/native-provider.ts

@@ -0,0 +1,348 @@
+/**
+ * NativeFileSystemProvider — wraps the File System Access API
+ * (window.showDirectoryPicker / FileSystemDirectoryHandle).
+ *
+ * Progressive enhancement: only available in browsers that support
+ * the API (Chrome, Edge). Feature-detect with `isNativeFileSystemSupported()`.
+ */
+
+import type { FileSystemProvider, FileSystemEntry, FileMeta } from './types.js';
+
+// ── Feature detection ──────────────────────────────────────────────
+
+export function isNativeFileSystemSupported(): boolean {
+  return typeof globalThis !== 'undefined' && 'showDirectoryPicker' in globalThis;
+}
+
+// ── Handle persistence (IndexedDB, structured clone) ───────────────
+
+const HANDLE_DB_NAME = 'docblocks-handles';
+const HANDLE_STORE_NAME = 'directory-handles';
+
+function openHandleDB(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(HANDLE_DB_NAME, 1);
+    req.onupgradeneeded = () => {
+      req.result.createObjectStore(HANDLE_STORE_NAME);
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+/** Persist a FileSystemDirectoryHandle so it survives page reloads. */
+export async function storeDirectoryHandle(
+  workspaceId: string,
+  handle: FileSystemDirectoryHandle,
+): Promise<void> {
+  const db = await openHandleDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(HANDLE_STORE_NAME, 'readwrite');
+    tx.objectStore(HANDLE_STORE_NAME).put(handle, workspaceId);
+    tx.oncomplete = () => {
+      db.close();
+      resolve();
+    };
+    tx.onerror = () => {
+      db.close();
+      reject(tx.error);
+    };
+  });
+}
+
+/** Retrieve a previously stored handle. Returns null if not found. */
+export async function loadDirectoryHandle(
+  workspaceId: string,
+): Promise<FileSystemDirectoryHandle | null> {
+  const db = await openHandleDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(HANDLE_STORE_NAME, 'readonly');
+    const req = tx.objectStore(HANDLE_STORE_NAME).get(workspaceId);
+    req.onsuccess = () => {
+      db.close();
+      resolve(req.result ?? null);
+    };
+    req.onerror = () => {
+      db.close();
+      reject(req.error);
+    };
+  });
+}
+
+/** Remove a stored handle (e.g. when deleting a workspace). */
+export async function removeDirectoryHandle(workspaceId: string): Promise<void> {
+  const db = await openHandleDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(HANDLE_STORE_NAME, 'readwrite');
+    tx.objectStore(HANDLE_STORE_NAME).delete(workspaceId);
+    tx.oncomplete = () => {
+      db.close();
+      resolve();
+    };
+    tx.onerror = () => {
+      db.close();
+      reject(tx.error);
+    };
+  });
+}
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+function normalisePath(p: string): string {
+  return p.replace(/\\/g, '/').replace(/\/+/g, '/').replace(/^\//, '').replace(/\/$/, '');
+}
+
+/**
+ * Walk a chain of path segments to reach a FileSystemDirectoryHandle.
+ * Returns null if any segment is missing.
+ */
+async function resolveDir(
+  root: FileSystemDirectoryHandle,
+  dirPath: string,
+): Promise<FileSystemDirectoryHandle | null> {
+  if (!dirPath) return root;
+  const parts = dirPath.split('/');
+  let current = root;
+  for (const part of parts) {
+    try {
+      current = await current.getDirectoryHandle(part);
+    } catch {
+      return null;
+    }
+  }
+  return current;
+}
+
+/**
+ * Walk path segments, creating directories as needed.
+ */
+async function resolveDirCreate(
+  root: FileSystemDirectoryHandle,
+  dirPath: string,
+): Promise<FileSystemDirectoryHandle> {
+  if (!dirPath) return root;
+  const parts = dirPath.split('/');
+  let current = root;
+  for (const part of parts) {
+    current = await current.getDirectoryHandle(part, { create: true });
+  }
+  return current;
+}
+
+function parentDir(p: string): string {
+  const idx = p.lastIndexOf('/');
+  return idx === -1 ? '' : p.slice(0, idx);
+}
+
+function baseName(p: string): string {
+  const idx = p.lastIndexOf('/');
+  return idx === -1 ? p : p.slice(idx + 1);
+}
+
+// ── Implementation ─────────────────────────────────────────────────
+
+export class NativeFileSystemProvider implements FileSystemProvider {
+  readonly id: string;
+  readonly label: string;
+
+  private root: FileSystemDirectoryHandle;
+
+  constructor(id: string, root: FileSystemDirectoryHandle) {
+    this.id = id;
+    this.label = root.name;
+    this.root = root;
+  }
+
+  async readFile(path: string): Promise<string | null> {
+    const p = normalisePath(path);
+    const dir = await resolveDir(this.root, parentDir(p));
+    if (!dir) return null;
+    try {
+      const fileHandle = await dir.getFileHandle(baseName(p));
+      const file = await fileHandle.getFile();
+      return file.text();
+    } catch {
+      return null;
+    }
+  }
+
+  async writeFile(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();
+  }
+
+  async delete(path: string): Promise<void> {
+    const p = normalisePath(path);
+    const parent = parentDir(p);
+    const name = baseName(p);
+    const dir = await resolveDir(this.root, parent);
+    if (!dir) return;
+    await dir.removeEntry(name, { recursive: true });
+  }
+
+  async rename(oldPath: string, newPath: string): Promise<void> {
+    const op = normalisePath(oldPath);
+    const np = normalisePath(newPath);
+
+    // The File System Access API doesn't have a native rename.
+    // Read → write → delete.
+    const content = await this.readFile(op);
+    if (content !== null) {
+      await this.writeFile(np, content);
+      await this.delete(op);
+      return;
+    }
+
+    // Try binary
+    const binary = await this.readBinary(op);
+    if (binary !== null) {
+      await this.writeBinary(np, binary);
+      await this.delete(op);
+    }
+  }
+
+  async readDirectory(path: string): Promise<FileSystemEntry[]> {
+    const p = normalisePath(path);
+    const dir = await resolveDir(this.root, p);
+    if (!dir) return [];
+
+    const entries: FileSystemEntry[] = [];
+    for await (const [name, handle] of dir as unknown as AsyncIterable<
+      [string, FileSystemHandle]
+    >) {
+      const entryPath = p ? `${p}/${name}` : name;
+      if (handle.kind === 'directory') {
+        entries.push({ kind: 'directory', name, path: entryPath });
+      } else {
+        entries.push({ kind: 'file', name, path: entryPath });
+      }
+    }
+
+    // Sort: directories first, then alphabetical
+    entries.sort((a, b) => {
+      if (a.kind !== b.kind) return a.kind === 'directory' ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
+
+    return entries;
+  }
+
+  async exists(path: string): Promise<boolean> {
+    const p = normalisePath(path);
+    const parent = parentDir(p);
+    const name = baseName(p);
+    const dir = await resolveDir(this.root, parent);
+    if (!dir) return false;
+
+    try {
+      await dir.getFileHandle(name);
+      return true;
+    } catch {
+      try {
+        await dir.getDirectoryHandle(name);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  }
+
+  async createDirectory(path: string): Promise<void> {
+    const p = normalisePath(path);
+    await resolveDirCreate(this.root, p);
+  }
+
+  async stat(path: string): Promise<FileMeta | null> {
+    const p = normalisePath(path);
+    const dir = await resolveDir(this.root, parentDir(p));
+    if (!dir) return null;
+
+    try {
+      const fileHandle = await dir.getFileHandle(baseName(p));
+      const file = await fileHandle.getFile();
+      return {
+        name: file.name,
+        path: p,
+        size: file.size,
+        lastModified: new Date(file.lastModified).toISOString(),
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  async readBinary(path: string): Promise<ArrayBuffer | null> {
+    const p = normalisePath(path);
+    const dir = await resolveDir(this.root, parentDir(p));
+    if (!dir) return null;
+    try {
+      const fileHandle = await dir.getFileHandle(baseName(p));
+      const file = await fileHandle.getFile();
+      return file.arrayBuffer();
+    } catch {
+      return null;
+    }
+  }
+
+  async writeBinary(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();
+  }
+}
+
+/**
+ * Prompt the user to pick a local folder and return a NativeFileSystemProvider.
+ * The directory handle is persisted in IndexedDB so it can be restored later.
+ * Throws if the user cancels or the API is unsupported.
+ */
+export async function openNativeFolder(): Promise<NativeFileSystemProvider> {
+  if (!isNativeFileSystemSupported()) {
+    throw new Error('File System Access API is not supported in this browser');
+  }
+
+  const handle = await (
+    globalThis as unknown as { showDirectoryPicker: () => Promise<FileSystemDirectoryHandle> }
+  ).showDirectoryPicker();
+  const id = `native-${handle.name}-${Date.now()}`;
+  await storeDirectoryHandle(id, handle);
+  return new NativeFileSystemProvider(id, handle);
+}
+
+/**
+ * Restore a previously opened native folder from a persisted handle.
+ * Re-requests read/write permission (browser will show a prompt).
+ * Returns null if the handle is not found or permission is denied.
+ */
+export async function restoreNativeFolder(
+  workspaceId: string,
+): Promise<NativeFileSystemProvider | null> {
+  const handle = await loadDirectoryHandle(workspaceId);
+  if (!handle) return null;
+
+  // Verify/request permission
+  const opts = { mode: 'readwrite' as const };
+  const h = handle as FileSystemDirectoryHandle & {
+    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);
+  }
+
+  return null;
+}

package/src/filesystem/types.ts

@@ -0,0 +1,69 @@
+/**
+ * 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).
+ */
+
+// ── Entry types ────────────────────────────────────────────────────
+
+export interface FileEntry {
+  kind: 'file';
+  name: string;
+  path: string;
+}
+
+export interface FolderEntry {
+  kind: 'directory';
+  name: string;
+  path: string;
+}
+
+export type FileSystemEntry = FileEntry | FolderEntry;
+
+export interface FileMeta {
+  name: string;
+  path: string;
+  size: number;
+  lastModified: string;
+}
+
+// ── Provider interface ─────────────────────────────────────────────
+
+export interface FileSystemProvider {
+  /** Unique identifier for this provider instance. */
+  readonly id: string;
+
+  /** Human-readable label (e.g., folder name or "Browser Storage"). */
+  readonly label: string;
+
+  /** 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. */
+  delete(path: string): Promise<void>;
+
+  /** Rename or move an entry. */
+  rename(oldPath: string, newPath: string): Promise<void>;
+
+  /** List immediate children of a directory. */
+  readDirectory(path: string): Promise<FileSystemEntry[]>;
+
+  /** Check whether a path exists. */
+  exists(path: string): Promise<boolean>;
+
+  /** Create a directory (and parents if needed). */
+  createDirectory(path: string): Promise<void>;
+
+  /** Get metadata for a file. Returns null if not found. */
+  stat(path: string): Promise<FileMeta | null>;
+
+  /** Read raw binary content. Returns null if not found. */
+  readBinary(path: string): Promise<ArrayBuffer | null>;
+
+  /** Write raw binary content. */
+  writeBinary(path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @bendyline/docblocks — Core package
+ *
+ * Re-exports filesystem and workspace modules for convenience.
+ */
+
+export * from './filesystem/index.js';
+export * from './workspace/index.js';

package/src/workspace/index.ts

@@ -0,0 +1,10 @@
+export type { WorkspaceDescriptor } from './types.js';
+
+export {
+  listWorkspaces,
+  getWorkspace,
+  saveWorkspace,
+  removeWorkspace,
+  touchWorkspace,
+  ensureDefaultWorkspace,
+} from './workspace-manager.js';

package/src/workspace/types.ts

@@ -0,0 +1,15 @@
+/**
+ * Workspace — a named binding to a FileSystemProvider, representing
+ * the user's current working context (a folder of markdown files).
+ */
+
+export interface WorkspaceDescriptor {
+  /** Unique stable identifier (persisted in IndexedDB). */
+  id: string;
+  /** User-visible label. */
+  name: string;
+  /** 'indexeddb' for browser-local storage, 'native' for File System Access API. */
+  type: 'indexeddb' | 'native';
+  /** ISO timestamp of last access. */
+  lastOpened: string;
+}

package/src/workspace/workspace-manager.ts

@@ -0,0 +1,90 @@
+/**
+ * WorkspaceManager — manages the list of known workspaces in IndexedDB
+ * and provides helpers for creating / switching / removing them.
+ *
+ * The actual FileSystemProvider instances are created by the caller
+ * (since native providers need a DirectoryHandle from user interaction).
+ */
+
+import { LocalForageAdapter } from '@bendyline/squisq/storage';
+import type { WorkspaceDescriptor } from './types.js';
+
+const DB_NAME = 'docblocks-workspaces';
+const STORE_NAME = 'workspaces';
+const LIST_KEY = 'workspace-list';
+const DEFAULT_WORKSPACE_ID = 'default';
+
+const store = new LocalForageAdapter({
+  name: DB_NAME,
+  storeName: STORE_NAME,
+});
+
+/**
+ * Get the list of all known workspace descriptors.
+ */
+export async function listWorkspaces(): Promise<WorkspaceDescriptor[]> {
+  const list = await store.get<WorkspaceDescriptor[]>(LIST_KEY);
+  return list ?? [];
+}
+
+/**
+ * Get a specific workspace descriptor by id.
+ */
+export async function getWorkspace(id: string): Promise<WorkspaceDescriptor | null> {
+  const list = await listWorkspaces();
+  return list.find((w) => w.id === id) ?? null;
+}
+
+/**
+ * Add or update a workspace descriptor. If a workspace with the same id
+ * already exists, it is replaced.
+ */
+export async function saveWorkspace(workspace: WorkspaceDescriptor): Promise<void> {
+  const list = await listWorkspaces();
+  const idx = list.findIndex((w) => w.id === workspace.id);
+  if (idx >= 0) {
+    list[idx] = workspace;
+  } else {
+    list.push(workspace);
+  }
+  await store.set(LIST_KEY, list);
+}
+
+/**
+ * Remove a workspace descriptor by id.
+ */
+export async function removeWorkspace(id: string): Promise<void> {
+  const list = await listWorkspaces();
+  const filtered = list.filter((w) => w.id !== id);
+  await store.set(LIST_KEY, filtered);
+}
+
+/**
+ * Touch the lastOpened timestamp on a workspace.
+ */
+export async function touchWorkspace(id: string): Promise<void> {
+  const list = await listWorkspaces();
+  const workspace = list.find((w) => w.id === id);
+  if (workspace) {
+    workspace.lastOpened = new Date().toISOString();
+    await store.set(LIST_KEY, list);
+  }
+}
+
+/**
+ * Ensure a default IndexedDB workspace exists. Called on app startup.
+ * Returns the descriptor.
+ */
+export async function ensureDefaultWorkspace(): Promise<WorkspaceDescriptor> {
+  const existing = await getWorkspace(DEFAULT_WORKSPACE_ID);
+  if (existing) return existing;
+
+  const descriptor: WorkspaceDescriptor = {
+    id: DEFAULT_WORKSPACE_ID,
+    name: 'My Documents',
+    type: 'indexeddb',
+    lastOpened: new Date().toISOString(),
+  };
+  await saveWorkspace(descriptor);
+  return descriptor;
+}