@bendyline/docblocks 1.1.2 → 2.0.0

package/src/workspace/index.ts

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

package/src/workspace/reconcile-electron.ts

@@ -0,0 +1,65 @@
+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,3 +1,36 @@
+/**
+ * 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).
@@ -13,12 +46,17 @@ export interface WorkspaceDescriptor {
    * - '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';
+  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'` /

package/src/workspace/workspace-manager.ts

@@ -7,6 +7,7 @@
  */
 
 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';
@@ -20,27 +21,77 @@ const store = new LocalForageAdapter({
 });
 
 /**
- * Get the list of all known workspace descriptors.
+ * 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.
  */
-export async function listWorkspaces(): Promise<WorkspaceDescriptor[]> {
+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 a specific workspace descriptor by id.
+ * 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 list = await listWorkspaces();
+  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.
+ * already exists, it is replaced. Transient workspaces are never persisted.
  */
 export async function saveWorkspace(workspace: WorkspaceDescriptor): Promise<void> {
-  const list = await listWorkspaces();
+  if (workspace.type === 'transient') return;
+  const list = await listPersisted();
   const idx = list.findIndex((w) => w.id === workspace.id);
   if (idx >= 0) {
     list[idx] = workspace;
@@ -51,19 +102,29 @@ export async function saveWorkspace(workspace: WorkspaceDescriptor): Promise<voi
 }
 
 /**
- * Remove a workspace descriptor by id.
+ * Remove a workspace descriptor by id (transient or persisted).
  */
 export async function removeWorkspace(id: string): Promise<void> {
-  const list = await listWorkspaces();
+  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.
+ * 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 list = await listWorkspaces();
+  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();

package/dist/chunk-GUNM43XZ.js

@@ -1,63 +0,0 @@
-// src/workspace/workspace-manager.ts
-import { LocalForageAdapter } from "@bendyline/squisq/storage";
-var DB_NAME = "docblocks-workspaces";
-var STORE_NAME = "workspaces";
-var LIST_KEY = "workspace-list";
-var DEFAULT_WORKSPACE_ID = "default";
-var store = new LocalForageAdapter({
-  name: DB_NAME,
-  storeName: STORE_NAME
-});
-async function listWorkspaces() {
-  const list = await store.get(LIST_KEY);
-  return list ?? [];
-}
-async function getWorkspace(id) {
-  const list = await listWorkspaces();
-  return list.find((w) => w.id === id) ?? null;
-}
-async function saveWorkspace(workspace) {
-  const list = await listWorkspaces();
-  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);
-}
-async function removeWorkspace(id) {
-  const list = await listWorkspaces();
-  const filtered = list.filter((w) => w.id !== id);
-  await store.set(LIST_KEY, filtered);
-}
-async function touchWorkspace(id) {
-  const list = await listWorkspaces();
-  const workspace = list.find((w) => w.id === id);
-  if (workspace) {
-    workspace.lastOpened = (/* @__PURE__ */ new Date()).toISOString();
-    await store.set(LIST_KEY, list);
-  }
-}
-async function ensureDefaultWorkspace() {
-  const existing = await getWorkspace(DEFAULT_WORKSPACE_ID);
-  if (existing) return existing;
-  const descriptor = {
-    id: DEFAULT_WORKSPACE_ID,
-    name: "My Documents",
-    type: "indexeddb",
-    lastOpened: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  await saveWorkspace(descriptor);
-  return descriptor;
-}
-
-export {
-  listWorkspaces,
-  getWorkspace,
-  saveWorkspace,
-  removeWorkspace,
-  touchWorkspace,
-  ensureDefaultWorkspace
-};
-//# sourceMappingURL=chunk-GUNM43XZ.js.map

package/dist/chunk-GUNM43XZ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/workspace/workspace-manager.ts"],"sourcesContent":["/**\n * WorkspaceManager — manages the list of known workspaces in IndexedDB\n * and provides helpers for creating / switching / removing them.\n *\n * The actual FileSystemProvider instances are created by the caller\n * (since native providers need a DirectoryHandle from user interaction).\n */\n\nimport { LocalForageAdapter } from '@bendyline/squisq/storage';\nimport type { WorkspaceDescriptor } from './types.js';\n\nconst DB_NAME = 'docblocks-workspaces';\nconst STORE_NAME = 'workspaces';\nconst LIST_KEY = 'workspace-list';\nconst DEFAULT_WORKSPACE_ID = 'default';\n\nconst store = new LocalForageAdapter({\n  name: DB_NAME,\n  storeName: STORE_NAME,\n});\n\n/**\n * Get the list of all known workspace descriptors.\n */\nexport async function listWorkspaces(): Promise<WorkspaceDescriptor[]> {\n  const list = await store.get<WorkspaceDescriptor[]>(LIST_KEY);\n  return list ?? [];\n}\n\n/**\n * Get a specific workspace descriptor by id.\n */\nexport async function getWorkspace(id: string): Promise<WorkspaceDescriptor | null> {\n  const list = await listWorkspaces();\n  return list.find((w) => w.id === id) ?? null;\n}\n\n/**\n * Add or update a workspace descriptor. If a workspace with the same id\n * already exists, it is replaced.\n */\nexport async function saveWorkspace(workspace: WorkspaceDescriptor): Promise<void> {\n  const list = await listWorkspaces();\n  const idx = list.findIndex((w) => w.id === workspace.id);\n  if (idx >= 0) {\n    list[idx] = workspace;\n  } else {\n    list.push(workspace);\n  }\n  await store.set(LIST_KEY, list);\n}\n\n/**\n * Remove a workspace descriptor by id.\n */\nexport async function removeWorkspace(id: string): Promise<void> {\n  const list = await listWorkspaces();\n  const filtered = list.filter((w) => w.id !== id);\n  await store.set(LIST_KEY, filtered);\n}\n\n/**\n * Touch the lastOpened timestamp on a workspace.\n */\nexport async function touchWorkspace(id: string): Promise<void> {\n  const list = await listWorkspaces();\n  const workspace = list.find((w) => w.id === id);\n  if (workspace) {\n    workspace.lastOpened = new Date().toISOString();\n    await store.set(LIST_KEY, list);\n  }\n}\n\n/**\n * Ensure a default IndexedDB workspace exists. Called on app startup.\n * Returns the descriptor.\n */\nexport async function ensureDefaultWorkspace(): Promise<WorkspaceDescriptor> {\n  const existing = await getWorkspace(DEFAULT_WORKSPACE_ID);\n  if (existing) return existing;\n\n  const descriptor: WorkspaceDescriptor = {\n    id: DEFAULT_WORKSPACE_ID,\n    name: 'My Documents',\n    type: 'indexeddb',\n    lastOpened: new Date().toISOString(),\n  };\n  await saveWorkspace(descriptor);\n  return descriptor;\n}\n"],"mappings":";AAQA,SAAS,0BAA0B;AAGnC,IAAM,UAAU;AAChB,IAAM,aAAa;AACnB,IAAM,WAAW;AACjB,IAAM,uBAAuB;AAE7B,IAAM,QAAQ,IAAI,mBAAmB;AAAA,EACnC,MAAM;AAAA,EACN,WAAW;AACb,CAAC;AAKD,eAAsB,iBAAiD;AACrE,QAAM,OAAO,MAAM,MAAM,IAA2B,QAAQ;AAC5D,SAAO,QAAQ,CAAC;AAClB;AAKA,eAAsB,aAAa,IAAiD;AAClF,QAAM,OAAO,MAAM,eAAe;AAClC,SAAO,KAAK,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK;AAC1C;AAMA,eAAsB,cAAc,WAA+C;AACjF,QAAM,OAAO,MAAM,eAAe;AAClC,QAAM,MAAM,KAAK,UAAU,CAAC,MAAM,EAAE,OAAO,UAAU,EAAE;AACvD,MAAI,OAAO,GAAG;AACZ,SAAK,GAAG,IAAI;AAAA,EACd,OAAO;AACL,SAAK,KAAK,SAAS;AAAA,EACrB;AACA,QAAM,MAAM,IAAI,UAAU,IAAI;AAChC;AAKA,eAAsB,gBAAgB,IAA2B;AAC/D,QAAM,OAAO,MAAM,eAAe;AAClC,QAAM,WAAW,KAAK,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE;AAC/C,QAAM,MAAM,IAAI,UAAU,QAAQ;AACpC;AAKA,eAAsB,eAAe,IAA2B;AAC9D,QAAM,OAAO,MAAM,eAAe;AAClC,QAAM,YAAY,KAAK,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE;AAC9C,MAAI,WAAW;AACb,cAAU,cAAa,oBAAI,KAAK,GAAE,YAAY;AAC9C,UAAM,MAAM,IAAI,UAAU,IAAI;AAAA,EAChC;AACF;AAMA,eAAsB,yBAAuD;AAC3E,QAAM,WAAW,MAAM,aAAa,oBAAoB;AACxD,MAAI,SAAU,QAAO;AAErB,QAAM,aAAkC;AAAA,IACtC,IAAI;AAAA,IACJ,MAAM;AAAA,IACN,MAAM;AAAA,IACN,aAAY,oBAAI,KAAK,GAAE,YAAY;AAAA,EACrC;AACA,QAAM,cAAc,UAAU;AAC9B,SAAO;AACT;","names":[]}