@bendyline/docblocks 1.1.2 → 2.0.0

package/src/document/types.ts

@@ -0,0 +1,116 @@
+/**
+ * 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

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,135 @@
+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;
+}