@bendyline/docblocks 1.1.2 → 2.1.0

package/src/filesystem/native-provider.ts

@@ -1,384 +0,0 @@
-/**
- * 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);
-}
-
-function toWritableBinary(data: ArrayBuffer | Uint8Array): ArrayBuffer {
-  if (data instanceof ArrayBuffer) return data;
-  const copy = new Uint8Array(data.byteLength);
-  copy.set(data);
-  return copy.buffer;
-}
-
-// ── 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;
-  }
-
-  private async copyDirectory(oldDirPath: string, newDirPath: string): Promise<boolean> {
-    const source = await resolveDir(this.root, oldDirPath);
-    if (!source) return false;
-    await resolveDirCreate(this.root, newDirPath);
-
-    for await (const [name, handle] of source as unknown as AsyncIterable<
-      [string, FileSystemHandle]
-    >) {
-      const oldChild = oldDirPath ? `${oldDirPath}/${name}` : name;
-      const newChild = newDirPath ? `${newDirPath}/${name}` : name;
-      if (handle.kind === 'directory') {
-        await this.copyDirectory(oldChild, newChild);
-      } else {
-        const fileHandle = await source.getFileHandle(name);
-        const file = await fileHandle.getFile();
-        await this.writeBinary(newChild, await file.arrayBuffer());
-      }
-    }
-
-    return true;
-  }
-
-  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);
-    if (op === np) return;
-    if (!op || !np) {
-      throw new Error('Cannot rename the filesystem root');
-    }
-    if (np.startsWith(op + '/')) {
-      throw new Error('Cannot move a directory into itself');
-    }
-
-    // The File System Access API doesn't have a native rename.
-    // Copy → delete.
-    const oldParent = await resolveDir(this.root, parentDir(op));
-    if (!oldParent) return;
-
-    try {
-      const fileHandle = await oldParent.getFileHandle(baseName(op));
-      const file = await fileHandle.getFile();
-      await this.writeBinary(np, await file.arrayBuffer());
-      await this.delete(op);
-      return;
-    } catch {
-      // Not a file; try directory below.
-    }
-
-    const copied = await this.copyDirectory(op, np);
-    if (copied) {
-      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();
-    await writable.write(toWritableBinary(data));
-    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

@@ -1,69 +0,0 @@
-/**
- * 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/host/index.ts

@@ -1,47 +0,0 @@
-/**
- * Host bridge — shared types + runtime access for the Electron desktop
- * host. The renderer calls `getDocBlocksHost()` to reach the preload
- * contextBridge; `isElectronHost()` gates desktop-only UI branches.
- */
-
-export type {
-  DocBlocksHostAPI,
-  DocBlocksHostFsAPI,
-  DocBlocksHostWorkspacesAPI,
-  DocBlocksHostShellAPI,
-  DocBlocksHostFfmpegAPI,
-  DocBlocksHostUpdaterAPI,
-  ElectronWorkspaceInfo,
-  HostEnvironment,
-  MenuCommand,
-  OpenRequest,
-  UpdaterStatus,
-} from './types.js';
-
-import type { DocBlocksHostAPI } from './types.js';
-
-/** True when running inside the Electron desktop shell. */
-export function isElectronHost(): boolean {
-  if (typeof globalThis === 'undefined') return false;
-  const host = (globalThis as { docBlocksHost?: unknown }).docBlocksHost;
-  return (
-    typeof host === 'object' &&
-    host !== null &&
-    typeof (host as { fs?: unknown }).fs === 'object' &&
-    (host as { fs?: unknown }).fs !== null
-  );
-}
-
-/** Return the host API, or throw if not running under Electron. */
-export function getDocBlocksHost(): DocBlocksHostAPI {
-  const host = (globalThis as { docBlocksHost?: DocBlocksHostAPI }).docBlocksHost;
-  if (!host) {
-    throw new Error('docBlocksHost is not available — not running under Electron?');
-  }
-  return host;
-}
-
-/** Return the host API, or null if not running under Electron. */
-export function maybeGetDocBlocksHost(): DocBlocksHostAPI | null {
-  return (globalThis as { docBlocksHost?: DocBlocksHostAPI }).docBlocksHost ?? null;
-}

package/src/host/types.ts

@@ -1,153 +0,0 @@
-/**
- * DocBlocksHostAPI — the contract exposed by the Electron desktop shell
- * to its renderer process via contextBridge.
- *
- * This file is the single source of truth for the host ↔ renderer
- * bridge. The Electron preload script exposes an implementation matching
- * this shape; the React renderer calls it through `window.docBlocksHost`.
- */
-
-import type { FileSystemEntry, FileMeta } from '../filesystem/types.js';
-
-/** Filesystem operations scoped to a registered absolute root path. */
-export interface DocBlocksHostFsAPI {
-  readFile(rootPath: string, path: string): Promise<string | null>;
-  writeFile(rootPath: string, path: string, content: string): Promise<void>;
-  delete(rootPath: string, path: string): Promise<void>;
-  rename(rootPath: string, oldPath: string, newPath: string): Promise<void>;
-  readDirectory(rootPath: string, path: string): Promise<FileSystemEntry[]>;
-  exists(rootPath: string, path: string): Promise<boolean>;
-  createDirectory(rootPath: string, path: string): Promise<void>;
-  stat(rootPath: string, path: string): Promise<FileMeta | null>;
-  readBinary(rootPath: string, path: string): Promise<ArrayBuffer | null>;
-  writeBinary(rootPath: string, path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
-  /**
-   * Subscribe to change notifications for a watched root. Returns an
-   * unsubscribe function. The main process uses chokidar under the hood.
-   */
-  watch(rootPath: string, onChange: (path: string) => void): () => void;
-}
-
-/** Descriptor returned for an Electron-managed workspace (backed by a folder). */
-export interface ElectronWorkspaceInfo {
-  id: string;
-  name: string;
-  rootPath: string;
-}
-
-/** Workspace-management operations exposed to the renderer. */
-export interface DocBlocksHostWorkspacesAPI {
-  /**
-   * Return the default workspace (creating ~/Documents/DocBlocks on first
-   * call, or the user's configured default).
-   */
-  getDefault(): Promise<ElectronWorkspaceInfo>;
-  /**
-   * Open the native folder picker. Returns null if the user cancels.
-   * The selected folder is registered in the main process whitelist.
-   */
-  pickFolder(): Promise<ElectronWorkspaceInfo | null>;
-  /**
-   * Re-register a previously known workspace so its rootPath is trusted
-   * for subsequent fs calls. Called on app startup for persisted
-   * electron-native workspaces before any fs operation.
-   */
-  register(info: ElectronWorkspaceInfo): Promise<void>;
-  /** Remove a workspace from the trusted whitelist. */
-  unregister(id: string): Promise<void>;
-}
-
-/** Shell operations — reveal in Finder/Explorer, open external URLs. */
-export interface DocBlocksHostShellAPI {
-  /** Reveal a file (by absolute path) in the OS file manager. */
-  revealInFolder(absolutePath: string): Promise<void>;
-  /** Open a URL in the default browser. */
-  openExternal(url: string): Promise<void>;
-}
-
-/** System ffmpeg detection and invocation. */
-export interface DocBlocksHostFfmpegAPI {
-  /** True if `ffmpeg` is available on PATH (or bundled). */
-  available(): Promise<boolean>;
-  /** Version string from `ffmpeg -version`, or null if unavailable. */
-  version(): Promise<string | null>;
-  /**
-   * Render a markdown file at the given absolute path to MP4 using the
-   * existing squisq-video CLI pipeline. Returns the absolute path to the
-   * produced MP4 file, or throws on failure.
-   */
-  renderVideo(
-    markdownAbsolutePath: string,
-    options: { fps?: number; quality?: 'draft' | 'normal' | 'high' },
-  ): Promise<string>;
-}
-
-/** Auto-updater control. */
-export interface DocBlocksHostUpdaterAPI {
-  /** Kick off a check; resolves to true if an update is available. */
-  checkForUpdates(): Promise<boolean>;
-  /** Current app version string. */
-  getVersion(): Promise<string>;
-  /**
-   * Quit the app and apply a downloaded update. Should only be called
-   * after an `UpdaterStatus` of kind `'downloaded'` has been observed.
-   */
-  quitAndInstall(): Promise<void>;
-  /**
-   * Subscribe to updater status events. Returns an unsubscribe function.
-   */
-  onStatus(listener: (status: UpdaterStatus) => void): () => void;
-}
-
-export type UpdaterStatus =
-  | { kind: 'checking' }
-  | { kind: 'available'; version: string; releaseNotes?: string; releaseUrl?: string }
-  | { kind: 'not-available' }
-  | { kind: 'downloading'; percent: number }
-  | { kind: 'downloaded'; version: string; releaseNotes?: string; releaseUrl?: string }
-  | { kind: 'error'; message: string };
-
-/** Menu-command events pushed from the main process to the renderer. */
-export type MenuCommand =
-  | 'file:new'
-  | 'file:openFolder'
-  | 'file:revealWorkspace'
-  | 'file:settings'
-  | 'help:about'
-  | 'help:checkForUpdates'
-  | 'help:viewOnGitHub';
-
-/** Deep-link event resolved by the host into a trusted workspace file. */
-export interface OpenRequest {
-  kind: 'workspace-file';
-  workspaceId: string;
-  /** Slash-prefixed path relative to the workspace root. */
-  path: string;
-}
-
-/** Environment metadata provided by the host. */
-export interface HostEnvironment {
-  platform: 'darwin' | 'win32' | 'linux';
-  appVersion: string;
-  isDev: boolean;
-}
-
-/** The full DocBlocks desktop host API. */
-export interface DocBlocksHostAPI {
-  env: HostEnvironment;
-  fs: DocBlocksHostFsAPI;
-  workspaces: DocBlocksHostWorkspacesAPI;
-  shell: DocBlocksHostShellAPI;
-  ffmpeg: DocBlocksHostFfmpegAPI;
-  updater: DocBlocksHostUpdaterAPI;
-  /**
-   * Subscribe to menu commands dispatched by the native menu.
-   * Returns an unsubscribe function.
-   */
-  onMenuCommand(listener: (cmd: MenuCommand) => void): () => void;
-  /**
-   * Subscribe to open-file / open-url requests from the OS.
-   * Returns an unsubscribe function.
-   */
-  onOpenRequest(listener: (request: OpenRequest) => void): () => void;
-}

package/src/index.ts

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

package/src/workspace/index.ts

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