@bendyline/docblocks 2.0.0 → 2.1.1

package/src/filesystem/electron-provider.ts

@@ -1,99 +0,0 @@
-/**
- * ElectronFileSystemProvider — implements FileSystemProvider by delegating
- * to the Electron desktop host's fs IPC bridge. Every operation is scoped
- * to an opaque workspace id that the main process resolves against its
- * registered workspace authority.
- *
- * This file has no Electron dependency — it is a pure IPC client that
- * relies on the `docBlocksHost` global installed by the preload script.
- */
-
-import type { FileCommitResult, FileSystemProvider, FileSystemEntry, FileMeta } from './types.js';
-import { maybeGetDocBlocksHost } from '../host/index.js';
-import type { DocBlocksHostFsAPI } from '../host/types.js';
-import { ElectronFileSystemProviderV2 } from './electron-provider-v2.js';
-
-export { isElectronHost } from '../host/index.js';
-
-function getHostFs(): DocBlocksHostFsAPI {
-  const host = maybeGetDocBlocksHost();
-  if (!host) {
-    throw new Error(
-      'ElectronFileSystemProvider: docBlocksHost is not available — not running under Electron?',
-    );
-  }
-  return host.fs;
-}
-
-export class ElectronFileSystemProvider implements FileSystemProvider {
-  readonly id: string;
-  readonly label: string;
-  readonly v2: ElectronFileSystemProviderV2;
-
-  private readonly rootPath: string;
-
-  constructor(id: string, label: string, rootPath: string) {
-    this.id = id;
-    this.label = label;
-    this.rootPath = rootPath;
-    this.v2 = new ElectronFileSystemProviderV2(id, label, rootPath);
-  }
-
-  /** Absolute path this provider is rooted at. */
-  getRootPath(): string {
-    return this.rootPath;
-  }
-
-  readFile(path: string): Promise<string | null> {
-    return getHostFs().readFile(this.id, path);
-  }
-
-  writeFile(path: string, content: string): Promise<void> {
-    return getHostFs().writeFile(this.id, path, content);
-  }
-
-  commitFile(
-    path: string,
-    content: string,
-    expectedContent: string | null,
-  ): Promise<FileCommitResult> {
-    return getHostFs().commitFile(this.id, path, content, expectedContent);
-  }
-
-  delete(path: string): Promise<void> {
-    return getHostFs().delete(this.id, path);
-  }
-
-  rename(oldPath: string, newPath: string): Promise<void> {
-    return getHostFs().rename(this.id, oldPath, newPath);
-  }
-
-  readDirectory(path: string): Promise<FileSystemEntry[]> {
-    return getHostFs().readDirectory(this.id, path);
-  }
-
-  exists(path: string): Promise<boolean> {
-    return getHostFs().exists(this.id, path);
-  }
-
-  createDirectory(path: string): Promise<void> {
-    return getHostFs().createDirectory(this.id, path);
-  }
-
-  stat(path: string): Promise<FileMeta | null> {
-    return getHostFs().stat(this.id, path);
-  }
-
-  readBinary(path: string): Promise<ArrayBuffer | null> {
-    return getHostFs().readBinary(this.id, path);
-  }
-
-  writeBinary(path: string, data: ArrayBuffer | Uint8Array): Promise<void> {
-    return getHostFs().writeBinary(this.id, path, data);
-  }
-
-  /** Subscribe to external change notifications under this root. */
-  watch(onChange: (changedPath: string) => void): () => void {
-    return getHostFs().watch(this.id, onChange);
-  }
-}

package/src/filesystem/electron.ts

@@ -1,3 +0,0 @@
-/** Electron renderer filesystem provider entry point. */
-export { ElectronFileSystemProvider, isElectronHost } from './electron-provider.js';
-export { ElectronFileSystemProviderV2 } from './electron-provider-v2.js';

package/src/filesystem/file-media-provider.ts

@@ -1,103 +0,0 @@
-/**
- * createFileMediaProvider — per-file media storage following the pandoc /
- * Word convention: a markdown file `notes.md` gets a sibling folder
- * `notes_files/` that holds its images, audio, and video.
- *
- * Given:
- *   • `container` — a ContentContainer scoped to the markdown file's
- *     parent directory (so `readFile('notes_files/image.png')` maps to the
- *     parent-relative path)
- *   • `markdownBasename` — e.g. `"notes.md"`
- *
- * Returns a MediaProvider that:
- *   • Writes new media under `{basename}_files/{name}` in the parent dir
- *   • Returns the folder-qualified path (`notes_files/image.png`) from
- *     addMedia so the markdown stays portable outside DocBlocks
- *   • Resolves both bare (`image.png`) and folder-qualified
- *     (`notes_files/image.png`) references — so legacy markdown and
- *     exports from other tools both work
- */
-
-import type { MediaProvider, MediaEntry } from '@bendyline/squisq/schemas';
-import type { ContentContainer } from '@bendyline/squisq/storage';
-
-function stripExt(name: string): string {
-  return name.replace(/\.[^.]+$/, '');
-}
-
-export function createFileMediaProvider(
-  container: ContentContainer,
-  markdownBasename: string,
-): MediaProvider {
-  const folder = stripExt(markdownBasename) + '_files';
-  const prefix = folder + '/';
-  const blobUrlCache = new Map<string, string>();
-
-  function toKey(ref: string): string {
-    const clean = ref.replace(/^\/+/, '');
-    return clean.startsWith(prefix) ? clean : prefix + clean;
-  }
-
-  return {
-    async resolveUrl(ref: string): Promise<string> {
-      const key = toKey(ref);
-      const cached = blobUrlCache.get(key);
-      if (cached) return cached;
-
-      const data = await container.readFile(key);
-      if (!data) return ref;
-
-      const entries = await container.listFiles();
-      const entry = entries.find((e) => e.path === key);
-      const mimeType = entry?.mimeType ?? 'application/octet-stream';
-
-      const url = URL.createObjectURL(new Blob([data], { type: mimeType }));
-      blobUrlCache.set(key, url);
-      return url;
-    },
-
-    async listMedia(): Promise<MediaEntry[]> {
-      const entries = await container.listFiles(prefix);
-      return entries
-        .filter((e) => !e.path.toLowerCase().endsWith('.md'))
-        .map((e) => ({
-          name: e.path,
-          mimeType: e.mimeType,
-          size: e.size,
-        }));
-    },
-
-    async addMedia(
-      name: string,
-      data: ArrayBuffer | Blob | Uint8Array,
-      mimeType: string,
-    ): Promise<string> {
-      const key = toKey(name);
-      const cached = blobUrlCache.get(key);
-      if (cached) {
-        URL.revokeObjectURL(cached);
-        blobUrlCache.delete(key);
-      }
-      const buffer = data instanceof Blob ? new Uint8Array(await data.arrayBuffer()) : data;
-      await container.writeFile(key, buffer, mimeType);
-      return key;
-    },
-
-    async removeMedia(ref: string): Promise<void> {
-      const key = toKey(ref);
-      const cached = blobUrlCache.get(key);
-      if (cached) {
-        URL.revokeObjectURL(cached);
-        blobUrlCache.delete(key);
-      }
-      await container.removeFile(key);
-    },
-
-    dispose(): void {
-      for (const url of blobUrlCache.values()) {
-        URL.revokeObjectURL(url);
-      }
-      blobUrlCache.clear();
-    },
-  };
-}

package/src/filesystem/filesystem-content-container.ts

@@ -1,164 +0,0 @@
-/**
- * FileSystemContentContainer — a ContentContainer backed by any
- * FileSystemProvider, scoped to a sub-path (e.g., ".docblocks/media/").
- *
- * Used by the Electron desktop app so media lives inside the workspace
- * folder (visible as regular files) rather than in a separate IndexedDB
- * origin that only the app can see.
- */
-
-import type { ContentContainer, ContentEntry } from '@bendyline/squisq/storage';
-import { findDocumentPath } from '@bendyline/squisq/storage';
-import { FsError } from './fs-error.js';
-import { getFileSystemProviderV2, type FileSystemProvider } from './types.js';
-import { parseWorkspacePath, workspacePathContains, workspacePathJoin } from './workspace-path.js';
-
-const EXTENSION_MIME_MAP: Record<string, string> = {
-  '.md': 'text/markdown',
-  '.txt': 'text/plain',
-  '.json': 'application/json',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.png': 'image/png',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-  '.webp': 'image/webp',
-  '.avif': 'image/avif',
-  '.mp4': 'video/mp4',
-  '.webm': 'video/webm',
-  '.mp3': 'audio/mpeg',
-  '.wav': 'audio/wav',
-  '.ogg': 'audio/ogg',
-};
-
-function guessMimeType(path: string): string {
-  const dot = path.lastIndexOf('.');
-  if (dot === -1) return 'application/octet-stream';
-  const ext = path.slice(dot).toLowerCase();
-  return EXTENSION_MIME_MAP[ext] ?? 'application/octet-stream';
-}
-
-function joinPrefix(prefix: string, p: string): string {
-  return workspacePathJoin(parseWorkspacePath(prefix), p);
-}
-
-export class FileSystemContentContainer implements ContentContainer {
-  private readonly prefix: string;
-
-  constructor(
-    private readonly provider: FileSystemProvider,
-    prefix = '.docblocks/media',
-  ) {
-    this.prefix = parseWorkspacePath(prefix);
-  }
-
-  async readFile(path: string): Promise<ArrayBuffer | null> {
-    const full = joinPrefix(this.prefix, path);
-    const providerV2 = getFileSystemProviderV2(this.provider);
-    if (providerV2) return (await providerV2.readFile(parseWorkspacePath(full)))?.data ?? null;
-    const binary = await this.provider.readBinary(full);
-    if (binary) return binary;
-    // IndexedDB-backed workspaces store text via `writeFile(string)` and
-    // binary via `writeBinary(ArrayBuffer)` under separate keys, so a
-    // markdown file written through the text API is invisible to
-    // `readBinary`. Fall back to text-then-UTF-8 so consumers like the
-    // recursive HTML export can resolve sibling `.md` links uniformly
-    // across browser and native workspaces.
-    const text = await this.provider.readFile(full);
-    if (text === null) return null;
-    return new TextEncoder().encode(text).buffer as ArrayBuffer;
-  }
-
-  async writeFile(path: string, data: ArrayBuffer | Uint8Array, _mimeType?: string): Promise<void> {
-    const full = joinPrefix(this.prefix, path);
-    const providerV2 = getFileSystemProviderV2(this.provider);
-    if (providerV2) {
-      await providerV2.writeFile(parseWorkspacePath(full), data, {
-        mode: 'upsert',
-        createParents: true,
-      });
-      return;
-    }
-    await this.provider.writeBinary(full, data);
-  }
-
-  async removeFile(path: string): Promise<void> {
-    const full = joinPrefix(this.prefix, path);
-    const providerV2 = getFileSystemProviderV2(this.provider);
-    if (providerV2) {
-      await providerV2.remove(parseWorkspacePath(full), { missing: 'ignore' });
-      return;
-    }
-    await this.provider.delete(full);
-  }
-
-  async listFiles(prefix?: string): Promise<ContentEntry[]> {
-    const entries: ContentEntry[] = [];
-    const providerV2 = getFileSystemProviderV2(this.provider);
-    const root = parseWorkspacePath(this.prefix);
-    type ListedEntry = {
-      readonly kind: 'file' | 'directory';
-      readonly path: string;
-      readonly size?: number | null;
-    };
-    const walk = async (dir: string) => {
-      let children: readonly ListedEntry[];
-      try {
-        children = providerV2
-          ? await providerV2.readDirectory(parseWorkspacePath(dir))
-          : await this.provider.readDirectory(dir);
-      } catch (error: unknown) {
-        // An absent container root means an empty container. Every other
-        // storage fault (including a subtree disappearing mid-snapshot)
-        // remains observable to backup/export callers.
-        if (dir === root && error instanceof FsError && error.code === 'not-found') return;
-        throw error;
-      }
-      for (const child of children) {
-        if (child.kind === 'directory') {
-          await walk(child.path);
-        } else {
-          const childPath = parseWorkspacePath(child.path);
-          const prefixPath = parseWorkspacePath(this.prefix);
-          if (!workspacePathContains(prefixPath, childPath)) continue;
-          const rel = childPath === prefixPath ? '' : childPath.slice(prefixPath.length + 1);
-          if (prefix && !rel.startsWith(prefix)) continue;
-          const size = child.size ?? (await this.provider.stat(child.path))?.size ?? 0;
-          entries.push({
-            path: rel,
-            mimeType: guessMimeType(rel),
-            size,
-          });
-        }
-      }
-    };
-    await walk(root);
-    return entries;
-  }
-
-  async exists(path: string): Promise<boolean> {
-    const full = joinPrefix(this.prefix, path);
-    const providerV2 = getFileSystemProviderV2(this.provider);
-    return providerV2
-      ? (await providerV2.stat(parseWorkspacePath(full))) !== null
-      : this.provider.exists(full);
-  }
-
-  async getDocumentPath(): Promise<string | null> {
-    return findDocumentPath(await this.listFiles());
-  }
-
-  async readDocument(): Promise<string | null> {
-    const docPath = await this.getDocumentPath();
-    if (!docPath) return null;
-    const data = await this.readFile(docPath);
-    if (!data) return null;
-    return new TextDecoder().decode(data);
-  }
-
-  async writeDocument(markdown: string, filename?: string): Promise<void> {
-    const name = filename ?? 'index.md';
-    const data = new TextEncoder().encode(markdown);
-    await this.writeFile(name, data, 'text/markdown');
-  }
-}

package/src/filesystem/fs-error.ts

@@ -1,234 +0,0 @@
-/** Stable error codes shared by every filesystem transport and backend. */
-export type FsErrorCode =
-  | 'invalid-path'
-  | 'path-escape'
-  | 'not-found'
-  | 'already-exists'
-  | 'type-mismatch'
-  | 'not-empty'
-  | 'permission-denied'
-  | 'conflict'
-  | 'quota-exceeded'
-  | 'not-supported'
-  | 'busy'
-  | 'disposed'
-  | 'closed'
-  | 'aborted'
-  | 'io';
-
-export type FsOperation =
-  | 'parse-path'
-  | 'read'
-  | 'stat'
-  | 'list'
-  | 'write'
-  | 'create-directory'
-  | 'remove'
-  | 'move'
-  | 'snapshot'
-  | 'watch'
-  | 'dispose';
-
-/** Plain-data form safe to send over IPC, postMessage, or JSON. */
-export interface SerializedFsError {
-  readonly name: 'FsError';
-  readonly code: FsErrorCode;
-  readonly message: string;
-  readonly operation: FsOperation | null;
-  readonly path: string | null;
-  readonly destinationPath: string | null;
-  readonly retryable: boolean;
-}
-
-export interface FsErrorContext {
-  readonly operation?: FsOperation;
-  readonly path?: string;
-  readonly destinationPath?: string;
-  readonly retryable?: boolean;
-  readonly defaultCode?: FsErrorCode;
-}
-
-const FS_ERROR_CODES: ReadonlySet<string> = new Set<FsErrorCode>([
-  'invalid-path',
-  'path-escape',
-  'not-found',
-  'already-exists',
-  'type-mismatch',
-  'not-empty',
-  'permission-denied',
-  'conflict',
-  'quota-exceeded',
-  'not-supported',
-  'busy',
-  'disposed',
-  'closed',
-  'aborted',
-  'io',
-]);
-
-const FS_OPERATIONS: ReadonlySet<string> = new Set<FsOperation>([
-  'parse-path',
-  'read',
-  'stat',
-  'list',
-  'write',
-  'create-directory',
-  'remove',
-  'move',
-  'snapshot',
-  'watch',
-  'dispose',
-]);
-
-/** Error with a stable code and a deliberately serializable public shape. */
-export class FsError extends Error {
-  public readonly code: FsErrorCode;
-  public readonly operation: FsOperation | null;
-  public readonly path: string | null;
-  public readonly destinationPath: string | null;
-  public readonly retryable: boolean;
-
-  public constructor(code: FsErrorCode, message: string, context: FsErrorContext = {}) {
-    super(message);
-    this.name = 'FsError';
-    this.code = code;
-    this.operation = context.operation ?? null;
-    this.path = context.path ?? null;
-    this.destinationPath = context.destinationPath ?? null;
-    this.retryable = context.retryable ?? (code === 'io' || code === 'aborted' || code === 'busy');
-  }
-
-  public toJSON(): SerializedFsError {
-    return {
-      name: 'FsError',
-      code: this.code,
-      message: this.message,
-      operation: this.operation,
-      path: this.path,
-      destinationPath: this.destinationPath,
-      retryable: this.retryable,
-    };
-  }
-}
-
-export function mapDomExceptionToFsErrorCode(name: string): FsErrorCode {
-  switch (name) {
-    case 'NotFoundError':
-      return 'not-found';
-    case 'ConstraintError':
-      return 'already-exists';
-    case 'TypeMismatchError':
-      return 'type-mismatch';
-    case 'InvalidModificationError':
-      return 'not-empty';
-    case 'NotAllowedError':
-    case 'SecurityError':
-    case 'NoModificationAllowedError':
-      return 'permission-denied';
-    case 'QuotaExceededError':
-      return 'quota-exceeded';
-    case 'NotSupportedError':
-      return 'not-supported';
-    case 'InvalidStateError':
-      return 'disposed';
-    case 'AbortError':
-      return 'aborted';
-    default:
-      return 'io';
-  }
-}
-
-export function mapNodeErrorCodeToFsErrorCode(code: string): FsErrorCode {
-  switch (code) {
-    case 'ENOENT':
-      return 'not-found';
-    case 'ENOTDIR':
-      return 'type-mismatch';
-    case 'EEXIST':
-      return 'already-exists';
-    case 'EISDIR':
-      return 'type-mismatch';
-    case 'ENOTEMPTY':
-      return 'not-empty';
-    case 'EACCES':
-    case 'EPERM':
-      return 'permission-denied';
-    case 'ENOSPC':
-    case 'EDQUOT':
-      return 'quota-exceeded';
-    case 'EBUSY':
-      return 'busy';
-    case 'EXDEV':
-    case 'ENOTSUP':
-    case 'EOPNOTSUPP':
-      return 'not-supported';
-    default:
-      return 'io';
-  }
-}
-
-export function isSerializedFsError(value: unknown): value is SerializedFsError {
-  if (!value || typeof value !== 'object') return false;
-  const candidate = value as Partial<Record<keyof SerializedFsError, unknown>>;
-  return (
-    candidate.name === 'FsError' &&
-    typeof candidate.code === 'string' &&
-    FS_ERROR_CODES.has(candidate.code) &&
-    typeof candidate.message === 'string' &&
-    (candidate.operation === null ||
-      (typeof candidate.operation === 'string' && FS_OPERATIONS.has(candidate.operation))) &&
-    (candidate.path === null || typeof candidate.path === 'string') &&
-    (candidate.destinationPath === null || typeof candidate.destinationPath === 'string') &&
-    typeof candidate.retryable === 'boolean'
-  );
-}
-
-export function deserializeFsError(value: SerializedFsError): FsError {
-  return new FsError(value.code, value.message, {
-    operation: value.operation ?? undefined,
-    path: value.path ?? undefined,
-    destinationPath: value.destinationPath ?? undefined,
-    retryable: value.retryable,
-  });
-}
-
-export function fsErrorFromUnknown(error: unknown, context: FsErrorContext = {}): FsError {
-  if (error instanceof FsError) return error;
-  if (isSerializedFsError(error)) return deserializeFsError(error);
-
-  const name = getErrorStringField(error, 'name');
-  const nodeCode = getErrorStringField(error, 'code');
-  const message = getErrorStringField(error, 'message') ?? String(error);
-  const code =
-    context.defaultCode ??
-    (nodeCode
-      ? mapNodeErrorCodeToFsErrorCode(nodeCode)
-      : name
-        ? mapDomExceptionToFsErrorCode(name)
-        : 'io');
-  return new FsError(code, message, context);
-}
-
-export function serializeFsError(error: unknown, context: FsErrorContext = {}): SerializedFsError {
-  return fsErrorFromUnknown(error, context).toJSON();
-}
-
-/**
- * True when a storage backend rejected an operation because the origin or
- * device is out of space. Covers typed `FsError`s (`'quota-exceeded'`, from
- * DOMException `QuotaExceededError` or Node `ENOSPC`/`EDQUOT`), serialized
- * transport copies, and raw DOMExceptions from backends that do not wrap
- * their errors (e.g. the File System Access API) — including cross-realm
- * instances where `instanceof DOMException` would fail.
- */
-export function isQuotaExceededError(error: unknown): boolean {
-  if (error instanceof FsError) return error.code === 'quota-exceeded';
-  if (isSerializedFsError(error)) return error.code === 'quota-exceeded';
-  return getErrorStringField(error, 'name') === 'QuotaExceededError';
-}
-
-function getErrorStringField(error: unknown, key: 'name' | 'message' | 'code'): string | null {
-  if (!error || typeof error !== 'object') return null;
-  const value = (error as Record<string, unknown>)[key];
-  return typeof value === 'string' ? value : null;
-}