@bendyline/docblocks 2.0.0 → 2.1.0

package/src/document/types.ts

@@ -1,116 +0,0 @@
-/**
- * Framework-neutral document persistence contracts.
- *
- * A DocumentSession owns one logical document at a time. Storage-specific
- * adapters implement DocumentCommitTarget; the session owns revisions,
- * serialization, lifecycle transitions, and conflict state.
- */
-
-import type { DocumentRecoveryJournal } from './recovery-journal.js';
-
-export type DocumentSaveReason =
-  | 'autosave'
-  | 'manual'
-  | 'transition'
-  | 'close'
-  | 'backup'
-  | 'conflict';
-
-export type DocumentExternalVersion = string | number | null;
-
-export interface DocumentCommitRequest {
-  /** Stable key for the target this commit was created for. */
-  targetKey: string;
-  /** Latest complete document snapshot to persist. */
-  content: string;
-  /** Monotonic session revision represented by content. */
-  revision: number;
-  /** Most recent revision acknowledged by this target. */
-  persistedRevision: number;
-  /** Content last acknowledged by the target, or null if it did not exist. */
-  persistedContent: string | null;
-  reason: DocumentSaveReason;
-}
-
-export interface DocumentCommitResult {
-  /** Optional backend version (mtime, TextDocument.version, etag, and so on). */
-  version?: DocumentExternalVersion;
-}
-
-export interface DocumentCommitTarget {
-  readonly key: string;
-  commit(request: DocumentCommitRequest): Promise<DocumentCommitResult | void>;
-}
-
-export type DocumentSessionStatus =
-  | 'idle'
-  | 'saved'
-  | 'dirty'
-  | 'saving'
-  | 'error'
-  | 'conflict'
-  | 'closed';
-
-export type DocumentSessionLifecycle = 'open' | 'transitioning' | 'closing' | 'closed';
-
-export interface DocumentExternalSnapshot {
-  /** Target key captured before the external read began. */
-  targetKey: string;
-  /** Monotonic observation number assigned by the target watcher. */
-  sequence?: number;
-  /** Null represents an externally deleted document. */
-  content: string | null;
-  version?: DocumentExternalVersion;
-}
-
-export interface DocumentSessionConflict {
-  targetKey: string;
-  localContent: string;
-  localRevision: number;
-  externalContent: string | null;
-  externalVersion: DocumentExternalVersion;
-}
-
-export interface DocumentSessionSnapshot {
-  targetKey: string | null;
-  content: string;
-  revision: number;
-  persistedRevision: number;
-  persistedContent: string | null;
-  savingRevision: number | null;
-  generation: number;
-  status: DocumentSessionStatus;
-  lifecycle: DocumentSessionLifecycle;
-  frozen: boolean;
-  error: Error | null;
-  conflict: DocumentSessionConflict | null;
-}
-
-export interface DocumentSessionOptions {
-  autoSaveDelayMs?: number;
-  /** Whether edits schedule automatic persistence. Manual and lifecycle flushes remain available. */
-  autoSaveEnabled?: boolean;
-  /**
-   * Bounded delays used after an automatic save fails. Each entry permits
-   * one retry; exhausting the list leaves the session in error state until
-   * the user edits again or explicitly flushes it. Conflicts never retry.
-   */
-  autoSaveRetryDelaysMs?: readonly number[];
-  /** Optional synchronous crash-recovery journal owned by this session. */
-  recoveryJournal?: DocumentRecoveryJournal | null;
-}
-
-/** Scope captured by an editor instance when it mounts. */
-export interface DocumentSessionEditScope {
-  targetKey: string;
-  generation: number;
-}
-
-/** Result produced while a session transition is frozen. */
-export interface DocumentSessionTransition {
-  target: DocumentCommitTarget | null;
-  content: string;
-}
-
-export type DocumentExternalChangeResult = 'applied' | 'conflict' | 'ignored';
-export type DocumentConflictStrategy = 'use-local' | 'use-external';

package/src/filesystem/commit-lock.ts

@@ -1,29 +0,0 @@
-type LockNavigator = Navigator & {
-  locks?: {
-    request<T>(name: string, callback: () => Promise<T>): Promise<T>;
-  };
-};
-
-const localTails = new Map<string, Promise<void>>();
-
-/** Serialize conditional commits across providers and, when available, tabs. */
-export async function withFileCommitLock<T>(key: string, operation: () => Promise<T>): Promise<T> {
-  const lockManager =
-    typeof navigator === 'undefined' ? undefined : (navigator as LockNavigator).locks;
-  if (lockManager) {
-    return lockManager.request(`docblocks:${key}`, operation);
-  }
-
-  const previous = localTails.get(key) ?? Promise.resolve();
-  const run = previous.then(operation, operation);
-  const tail = run.then(
-    () => undefined,
-    () => undefined,
-  );
-  localTails.set(key, tail);
-  try {
-    return await run;
-  } finally {
-    if (localTails.get(key) === tail) localTails.delete(key);
-  }
-}

package/src/filesystem/dbk-workspace.ts

@@ -1,135 +0,0 @@
-import type { ContentContainer } from '@bendyline/squisq/storage';
-import { documentCompanionPath } from './move-entry.js';
-import type {
-  MemoryFileSystemProvider,
-  MemoryFileSystemSnapshot,
-  MemoryFileSystemSnapshotFile,
-} from './memory-provider.js';
-
-export type DbkWorkspaceAssetLayout = 'auto' | 'preserve' | 'companion';
-
-export interface DbkWorkspaceSnapshotOptions {
-  /** Provider-relative path of the transient workspace's active markdown file. */
-  targetDocumentPath: string;
-  /**
-   * `preserve` treats the DBK as a serialized workspace tree. `companion`
-   * rebases non-document files beneath `<document>_files/`. `auto` preserves
-   * a DBK whose primary path already matches the target, otherwise rebasing
-   * imported media into the companion directory.
-   */
-  assetLayout?: DbkWorkspaceAssetLayout;
-}
-
-export interface DbkWorkspaceSnapshot extends MemoryFileSystemSnapshot {
-  readonly sourceDocumentPath: string;
-  readonly targetDocumentPath: string;
-  readonly documentContent: string;
-  readonly assetLayout: Exclude<DbkWorkspaceAssetLayout, 'auto'>;
-}
-
-function normaliseRelativePath(path: string, label: string): string {
-  if (path.includes('\\') || path.includes('\0')) {
-    throw new Error(`DBK ${label} must use a safe forward-slash path: ${path}`);
-  }
-  const normalized = path.replace(/^\/+|\/+$/g, '').replace(/\/+/g, '/');
-  const segments = normalized ? normalized.split('/') : [];
-  if (segments.length === 0 || segments.some((segment) => segment === '.' || segment === '..')) {
-    throw new Error(`DBK ${label} must not be empty or traverse directories: ${path}`);
-  }
-  return segments.join('/');
-}
-
-function joinPath(parent: string, child: string): string {
-  return `${parent.replace(/\/+$/g, '')}/${child.replace(/^\/+/, '')}`;
-}
-
-/**
- * Fully materialize and validate a DBK container before touching its target
- * provider. A missing or unreadable entry fails the snapshot as a whole.
- */
-export async function createDbkWorkspaceSnapshot(
-  source: ContentContainer,
-  options: DbkWorkspaceSnapshotOptions,
-): Promise<DbkWorkspaceSnapshot> {
-  const targetDocumentPath = normaliseRelativePath(
-    options.targetDocumentPath,
-    'target document path',
-  );
-  const discoveredDocumentPath = await source.getDocumentPath();
-  if (!discoveredDocumentPath)
-    throw new Error('The external DBK has no primary markdown document.');
-  const sourceDocumentPath = normaliseRelativePath(discoveredDocumentPath, 'primary document path');
-  const requestedLayout = options.assetLayout ?? 'auto';
-  const assetLayout: Exclude<DbkWorkspaceAssetLayout, 'auto'> =
-    requestedLayout === 'auto'
-      ? sourceDocumentPath === targetDocumentPath
-        ? 'preserve'
-        : 'companion'
-      : requestedLayout;
-  const companionPath = normaliseRelativePath(
-    documentCompanionPath(targetDocumentPath),
-    'companion directory path',
-  );
-
-  const listed = await source.listFiles();
-  const entries = [...listed].sort((a, b) => a.path.localeCompare(b.path));
-  const seenSourcePaths = new Set<string>();
-  const files: MemoryFileSystemSnapshotFile[] = [];
-  let documentContent: string | null = null;
-
-  for (const entry of entries) {
-    const sourcePath = normaliseRelativePath(entry.path, 'entry path');
-    if (seenSourcePaths.has(sourcePath)) {
-      throw new Error(`The external DBK contains duplicate paths: ${sourcePath}`);
-    }
-    seenSourcePaths.add(sourcePath);
-
-    const data = await source.readFile(entry.path);
-    if (data === null) {
-      throw new Error(`The external DBK changed while reading: ${sourcePath}`);
-    }
-    if (sourcePath === sourceDocumentPath) {
-      documentContent = new TextDecoder().decode(data);
-      files.push({ kind: 'text', path: targetDocumentPath, content: documentContent });
-      continue;
-    }
-
-    const targetPath =
-      assetLayout === 'preserve' ? sourcePath : joinPath(companionPath, sourcePath);
-    if (/\.(?:md|mdx|txt)$/i.test(sourcePath)) {
-      files.push({ kind: 'text', path: targetPath, content: new TextDecoder().decode(data) });
-    } else {
-      files.push({ kind: 'binary', path: targetPath, data });
-    }
-  }
-
-  if (documentContent === null) {
-    throw new Error(`The external DBK did not include its primary document: ${sourceDocumentPath}`);
-  }
-
-  return {
-    sourceDocumentPath,
-    targetDocumentPath,
-    documentContent,
-    assetLayout,
-    files,
-  };
-}
-
-/**
- * Replace a transient DBK workspace as one logical operation.
- *
- * Container reads and validation happen before provider mutation. The memory
- * provider then stages and swaps the full tree synchronously, which removes
- * stale files and guarantees the old tree survives any failed replacement.
- */
-export async function replaceMemoryWorkspaceFromDbk(
-  provider: MemoryFileSystemProvider,
-  source: ContentContainer,
-  options: DbkWorkspaceSnapshotOptions,
-): Promise<DbkWorkspaceSnapshot> {
-  const expectedTreeVersion = provider.treeVersion;
-  const snapshot = await createDbkWorkspaceSnapshot(source, options);
-  provider.replaceContents(snapshot, expectedTreeVersion);
-  return snapshot;
-}