@bendyline/docblocks 2.0.0 → 2.1.0

package/src/workspace/index.ts

@@ -1,17 +0,0 @@
-export type { WorkspaceDescriptor, TransientOrigin } from './types.js';
-
-export {
-  listWorkspaces,
-  getWorkspace,
-  saveWorkspace,
-  removeWorkspace,
-  touchWorkspace,
-  ensureDefaultWorkspace,
-  registerTransientWorkspace,
-  getTransientWorkspace,
-  unregisterTransientWorkspace,
-} from './workspace-manager.js';
-export {
-  reconcileElectronWorkspaceDescriptors,
-  type ElectronWorkspaceReconciliation,
-} from './reconcile-electron.js';

package/src/workspace/reconcile-electron.ts

@@ -1,65 +0,0 @@
-import type { ElectronWorkspaceInfo, HostEnvironment } from '../host/types.js';
-import type { WorkspaceDescriptor } from './types.js';
-
-export interface ElectronWorkspaceReconciliation {
-  /** Obsolete renderer descriptors to remove before attempting restoration. */
-  readonly removeIds: readonly string[];
-  /** Canonical main-authorized descriptors to insert or replace. */
-  readonly upsert: readonly WorkspaceDescriptor[];
-  /** Safe navigation migration for a local descriptor matched by root. */
-  readonly idRemap: Readonly<Record<string, string>>;
-}
-
-function comparableRoot(rootPath: string, platform: HostEnvironment['platform']): string {
-  const normalized = rootPath.replace(/\\/gu, '/').replace(/\/+$/gu, '');
-  return platform === 'win32' ? normalized.toLowerCase() : normalized;
-}
-
-/**
- * Reconcile renderer IndexedDB metadata with the main process authority list.
- * `hostWorkspaces` is authoritative: local Electron descriptors absent from
- * it cannot be opened safely and are removed. Root-path matching carries user
- * metadata across an id migration without treating that display path as
- * authority.
- */
-export function reconcileElectronWorkspaceDescriptors(
-  local: readonly WorkspaceDescriptor[],
-  hostWorkspaces: readonly ElectronWorkspaceInfo[],
-  platform: HostEnvironment['platform'],
-  now: string,
-): ElectronWorkspaceReconciliation {
-  const electron = local.filter((workspace) => workspace.type === 'electron-native');
-  const matchedLocalIds = new Set<string>();
-  const idRemap: Record<string, string> = {};
-  const upsert = hostWorkspaces.map((hostWorkspace): WorkspaceDescriptor => {
-    const root = comparableRoot(hostWorkspace.rootPath, platform);
-    const candidates = electron.filter(
-      (workspace) => workspace.rootPath && comparableRoot(workspace.rootPath, platform) === root,
-    );
-    const matching = candidates.sort((left, right) =>
-      right.lastOpened.localeCompare(left.lastOpened),
-    )[0];
-    if (matching) {
-      matchedLocalIds.add(matching.id);
-      if (matching.id !== hostWorkspace.id) idRemap[matching.id] = hostWorkspace.id;
-    }
-    return {
-      id: hostWorkspace.id,
-      name: matching?.name ?? hostWorkspace.name,
-      type: 'electron-native',
-      rootPath: hostWorkspace.rootPath,
-      lastOpened: matching?.lastOpened ?? now,
-      ...(matching?.versioningOverride ? { versioningOverride: matching.versioningOverride } : {}),
-    };
-  });
-  const canonicalIds = new Set(hostWorkspaces.map((workspace) => workspace.id));
-  const removeIds = electron
-    .filter(
-      (workspace) =>
-        !canonicalIds.has(workspace.id) ||
-        (matchedLocalIds.has(workspace.id) &&
-          !upsert.some((candidate) => candidate.id === workspace.id)),
-    )
-    .map((workspace) => workspace.id);
-  return { removeIds, upsert, idRemap };
-}

package/src/workspace/types.ts

@@ -1,67 +0,0 @@
-/**
- * Origin of a transient workspace — records where its contents came from and
- * how to save them back. Set only on `type: 'transient'` workspaces.
- * - 'loose-file' — a single markdown file opened from the OS (Electron);
- *   edits write back through an owner-scoped `resourceId` grant.
- * - 'dbk' — a `.dbk`/zip bundle unpacked into memory (Electron); edits are
- *   re-zipped and written back through an owner-scoped resource grant.
- * - 'web-file' — a single markdown file launched into the installed web app
- *   (File Handling API); edits write back through `handle`.
- * - 'web-dbk' — a `.dbk`/zip bundle launched into the installed web app;
- *   edits are re-zipped and written back through `handle`.
- *
- * The web variants hold a live `FileSystemFileHandle`. That is safe because
- * transient descriptors are never persisted — they live only in the
- * in-memory registry (see workspace-manager) for the current page session.
- */
-export type TransientOrigin =
-  | { kind: 'loose-file'; resourceId: string }
-  | {
-      kind: 'dbk';
-      resourceId: string;
-      /** SHA-256 of the last bundle version acknowledged by the host. */
-      version: string | null;
-    }
-  | { kind: 'web-file'; handle: FileSystemFileHandle; name: string }
-  | {
-      kind: 'web-dbk';
-      handle: FileSystemFileHandle;
-      name: string;
-      /** SHA-256 of the last bundle version observed on disk. */
-      version: string | null;
-    };
-
-/**
- * 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;
-  /**
-   * Provider kind:
-   * - 'indexeddb' — browser-local storage (web only)
-   * - 'native' — File System Access API (web Chrome/Edge only)
-   * - 'electron-native' — Electron main-process native filesystem
-   * - 'transient' — session-only, in-memory (a loose file or `.dbk` opened
-   *   from the OS). Never persisted; its provider lives in an in-memory
-   *   registry (see workspace-manager) and it saves back to `origin`.
-   */
-  type: 'indexeddb' | 'native' | 'electron-native' | 'transient';
-  /** ISO timestamp of last access. */
-  lastOpened: string;
-  /** Absolute filesystem path for 'electron-native' workspaces. */
-  rootPath?: string;
-  /** For 'transient' workspaces: where the contents came from / save back to. */
-  origin?: TransientOrigin;
-  /**
-   * Per-workspace override for the global versioning preference. When
-   * `'inherit'` (or absent), the global preference applies. `'on'` /
-   * `'off'` force the corresponding behavior regardless of the global
-   * setting. See `resolveVersioningEnabled` in the preferences module.
-   */
-  versioningOverride?: 'inherit' | 'on' | 'off';
-}

package/src/workspace/workspace-manager.ts

@@ -1,151 +0,0 @@
-/**
- * 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 { getFileSystemProviderV2, type FileSystemProvider } from '../filesystem/types.js';
-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,
-});
-
-/**
- * Session-only transient workspaces (a loose file or `.dbk` opened from the
- * OS). Kept purely in memory — never written to the persisted list — with
- * their pre-built provider registered alongside the descriptor. Lost on
- * reload, which is the intended "transient for the app session" behaviour.
- */
-interface TransientEntry {
-  descriptor: WorkspaceDescriptor;
-  provider: FileSystemProvider;
-}
-const transientWorkspaces = new Map<string, TransientEntry>();
-
-/** Register a transient workspace and its (already-built) provider. */
-export function registerTransientWorkspace(
-  descriptor: WorkspaceDescriptor,
-  provider: FileSystemProvider,
-): void {
-  const previous = transientWorkspaces.get(descriptor.id);
-  if (previous && previous.provider !== provider) {
-    void getFileSystemProviderV2(previous.provider)?.dispose();
-  }
-  transientWorkspaces.set(descriptor.id, { descriptor, provider });
-}
-
-/** Look up a transient workspace (descriptor + provider) by id, if any. */
-export function getTransientWorkspace(
-  id: string,
-): { descriptor: WorkspaceDescriptor; provider: FileSystemProvider } | null {
-  return transientWorkspaces.get(id) ?? null;
-}
-
-/** Forget a transient workspace (e.g. when it is closed). */
-export async function unregisterTransientWorkspace(id: string): Promise<void> {
-  const entry = transientWorkspaces.get(id);
-  if (!entry) return;
-  transientWorkspaces.delete(id);
-  await getFileSystemProviderV2(entry.provider)?.dispose();
-}
-
-/** The persisted (on-disk) workspace list only — excludes transient ones. */
-async function listPersisted(): Promise<WorkspaceDescriptor[]> {
-  const list = await store.get<WorkspaceDescriptor[]>(LIST_KEY);
-  return list ?? [];
-}
-
-/**
- * Get all known workspace descriptors — persisted plus any session-only
- * transient ones (so they show in the picker and resolve for the session).
- */
-export async function listWorkspaces(): Promise<WorkspaceDescriptor[]> {
-  const persisted = await listPersisted();
-  const transient = [...transientWorkspaces.values()].map((t) => t.descriptor);
-  return [...persisted, ...transient];
-}
-
-/**
- * Get a specific workspace descriptor by id (transient or persisted).
- */
-export async function getWorkspace(id: string): Promise<WorkspaceDescriptor | null> {
-  const transient = transientWorkspaces.get(id);
-  if (transient) return transient.descriptor;
-  const list = await listPersisted();
-  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. Transient workspaces are never persisted.
- */
-export async function saveWorkspace(workspace: WorkspaceDescriptor): Promise<void> {
-  if (workspace.type === 'transient') return;
-  const list = await listPersisted();
-  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 (transient or persisted).
- */
-export async function removeWorkspace(id: string): Promise<void> {
-  if (transientWorkspaces.has(id)) {
-    await unregisterTransientWorkspace(id);
-    return;
-  }
-  const list = await listPersisted();
-  const filtered = list.filter((w) => w.id !== id);
-  await store.set(LIST_KEY, filtered);
-}
-
-/**
- * Touch the lastOpened timestamp on a workspace. For transient workspaces this
- * updates the in-memory descriptor only (nothing is persisted).
- */
-export async function touchWorkspace(id: string): Promise<void> {
-  const transient = transientWorkspaces.get(id);
-  if (transient) {
-    transient.descriptor.lastOpened = new Date().toISOString();
-    return;
-  }
-  const list = await listPersisted();
-  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;
-}