@mnemosyne_os/affine-reader 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024–2030 Tony Trochet — Mnemosyne OS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,42 @@
+# Third-party code vendored in this package
+
+## AFFiNE — `src/vendor/affine/`
+
+Copyright (c) 2022-present TOEVERYTHING PTE. LTD. and its affiliates.
+Licensed under the **MIT License**.
+
+| | |
+|---|---|
+| Upstream | https://github.com/toeverything/AFFiNE |
+| Path | `packages/common/reader/src/doc-parser/` |
+| Fetched | 2026-09-06, from the repository's default branch |
+| Last upstream commit touching that path | `0c7b20dc18759dc63adbd93df491eba556baa6fe` (2026-08-10) |
+
+AFFiNE's repository is under a **mixed** licence: `packages/backend` and
+`packages/common/native` carry a separate one, and everything else — including
+`packages/common/reader` — is MIT. The vendored files come only from the MIT part.
+
+The upstream package (`@affine/reader`) is marked `private: true` and is not
+published to npm, which is why the source is vendored rather than depended upon.
+
+### What was changed
+
+Two lines, both **type-only** and therefore erased at compilation, so runtime
+behaviour is byte-for-byte the upstream one:
+
+| File | Before | After |
+|---|---|---|
+| `parser.ts` | `import type { ColumnDataType } from '@blocksuite/affine/model'` | `from './blocksuite-types'` |
+| `types.ts` | `import { type CellDataType } from '@blocksuite/affine/model'` | `from './blocksuite-types'` |
+
+`src/vendor/affine/blocksuite-types.ts` is ours, not AFFiNE's. It declares the two
+shapes locally so this package does not need `@blocksuite/affine` (MPL-2.0) on its
+resolution path merely to typecheck. Every changed line is marked
+`// MODIFIED (Mnemosyne OS)` in place.
+
+Nothing else was edited. `delta-to-md/` is byte-identical to upstream.
+
+## Not vendored
+
+**BlockSuite** (MPL-2.0) is not included, not linked, and not required at runtime.
+Rendering a document needs only `yjs` (MIT) and the files above.

package/README.md

@@ -0,0 +1,89 @@
+# @mnemosyne_os/affine-reader
+
+Read a local [AFFiNE](https://github.com/toeverything/AFFiNE) workspace and render its
+documents to Markdown — without running AFFiNE, without BlockSuite, without a server.
+
+**Read-only, in every direction.** Two processes writing one CRDT corrupt it, so this
+package copies the database before it reads and never writes back.
+
+## Install
+
+```bash
+npm install @mnemosyne_os/affine-reader
+```
+
+Runtime dependency: `yjs`. That is the whole list.
+
+## Use
+
+```ts
+import {
+  affineDataDir,
+  exportWorkspace,
+  findWorkspaces,
+  openNodeSqlite,
+  stageDatabase,
+} from '@mnemosyne_os/affine-reader';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+for (const ref of findWorkspaces()) {
+  const staged = stageDatabase(ref.dbPath, mkdtempSync(join(tmpdir(), 'affine-')));
+  const db = openNodeSqlite(staged.path);
+  try {
+    const result = exportWorkspace(db, `./out/${ref.id}`);
+    console.log(result.files, result.skipped);
+  } finally {
+    db.close();
+    staged.dispose();
+  }
+}
+```
+
+`findWorkspaces()` returning `[]` and `affineDataDir()` returning `null` are **different
+answers** — nothing to read versus AFFiNE not installed. Both are reported.
+
+### Bring your own SQLite
+
+`openNodeSqlite` uses Node's built-in `node:sqlite`, which needs **Node ≥ 22.5**.
+Electron 31 ships Node 20 and has none, so a host passes its own adapter:
+
+```ts
+import Database from 'better-sqlite3';
+import { readWorkspace } from '@mnemosyne_os/affine-reader';
+
+const raw = new Database(stagedPath);
+readWorkspace({ prepare: (sql) => raw.prepare(sql), close: () => raw.close() });
+```
+
+## What it reads
+
+| | |
+|---|---|
+| Location | `<app-data>/AFFiNE/<workspaces\|userspaces>/<peer>/<id>/storage.db` |
+| Schema | nbstore `v2` (`snapshots` + `updates` + `blobs`), and the legacy `v1` shape |
+| Content | Yjs history replayed into a document, rendered by AFFiNE's own MIT parser |
+
+Headings, lists, checkboxes, bold/italic, links, code, tables, database views, LaTeX and
+images all survive the trip. Images come out as blob files with links that point at them.
+
+## Two things that will bite you
+
+**The content may live in the `-wal`, not in `storage.db`.** Measured on one running
+0.27.4 install: at 14:28 `storage.db` was 4 KB next to a 1.8 MB `-wal`; at 14:46, same
+app still running, the journal had been checkpointed away and `storage.db` was 1.14 MB
+with no sidecar at all. A reader that copies only `storage.db` sees an **empty
+workspace** in the first state and cannot tell. `stageDatabase()` copies the sidecars
+when they exist and reports which ones it took.
+
+**A snapshot alone is stale.** A document typed one minute earlier decoded to **2
+characters** from its snapshot row and **323** once its 16 `updates` rows were replayed.
+Long-settled documents give the same answer either way — so a test written on those
+passes while the reader loses everything the user just wrote. Every load here replays
+the updates.
+
+## Licence
+
+MIT. Includes MIT-licensed source vendored from AFFiNE — see [NOTICE.md](./NOTICE.md).
+BlockSuite (MPL-2.0) is **not** included and is not required at runtime.

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * affine-export — write every local AFFiNE workspace out as Markdown.
+ *
+ *   npx @mnemosyne_os/affine-reader ./out
+ *
+ * Read-only: the database is copied (with its journal, where the content may
+ * actually live) before a byte is read, and nothing is ever written back into
+ * AFFiNE's directory.
+ *
+ * ⚠️ Needs Node >= 22.5 for `node:sqlite`. It says so rather than failing with
+ * an opaque module error.
+ */
+export declare function runCli(argv?: string[]): number;

package/dist/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * affine-export — write every local AFFiNE workspace out as Markdown.
+ *
+ *   npx @mnemosyne_os/affine-reader ./out
+ *
+ * Read-only: the database is copied (with its journal, where the content may
+ * actually live) before a byte is read, and nothing is ever written back into
+ * AFFiNE's directory.
+ *
+ * ⚠️ Needs Node >= 22.5 for `node:sqlite`. It says so rather than failing with
+ * an opaque module error.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCli = runCli;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const exportMarkdown_1 = require("./exportMarkdown");
+const locate_1 = require("./locate");
+const nodeSqlite_1 = require("./nodeSqlite");
+const stage_1 = require("./stage");
+function runCli(argv = process.argv.slice(2)) {
+    const outDir = argv[0];
+    if (!outDir || outDir === '--help' || outDir === '-h') {
+        console.log('usage: affine-export <outDir>');
+        console.log('  Writes one Markdown file per AFFiNE document, plus its images.');
+        return outDir ? 0 : 2;
+    }
+    if (!(0, nodeSqlite_1.hasNodeSqlite)()) {
+        console.error(`This tool needs Node >= 22.5 (for node:sqlite); this is ${process.version}.`);
+        return 1;
+    }
+    const dataDir = (0, locate_1.affineDataDir)();
+    const workspaces = (0, locate_1.findWorkspaces)();
+    if (workspaces.length === 0) {
+        // 🎭 Two different answers, and the person needs to know which one they got.
+        console.error(dataDir
+            ? `AFFiNE is installed (${dataDir}) but holds no workspace.`
+            : 'AFFiNE does not appear to be installed for this user.');
+        return 1;
+    }
+    let failures = 0;
+    for (const ref of workspaces) {
+        const staged = (0, stage_1.stageDatabase)(ref.dbPath, (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'affine-read-')));
+        try {
+            const db = (0, nodeSqlite_1.openNodeSqlite)(staged.path);
+            try {
+                const result = (0, exportMarkdown_1.exportWorkspace)(db, (0, node_path_1.join)(outDir, (0, exportMarkdown_1.workspaceFolderName)(ref)));
+                console.log(`\n${ref.kind} ${ref.id} — peer ${ref.peer}, schema ${result.schema}, ` +
+                    `journal ${staged.sidecars.join('+') || 'none'}`);
+                for (const doc of result.docs)
+                    console.log(`  ${String(doc.markdown.length).padStart(7)} chars  ` +
+                        `${doc.hadSnapshot ? 'snapshot' : 'no snapshot'}+${doc.updatesReplayed}  ` +
+                        `${doc.title || '(untitled)'}`);
+                // Never hidden: a document left out and a document that does not exist
+                // look identical in a count.
+                for (const skip of result.skipped) {
+                    failures++;
+                    console.log(`  SKIPPED ${skip.id} — ${skip.reason}`);
+                }
+                console.log(`  → ${result.files.length} file(s), ${result.blobsWritten} image(s)` +
+                    (result.trashed ? `, ${result.trashed} left in AFFiNE's trash` : ''));
+            }
+            finally {
+                db.close();
+            }
+        }
+        finally {
+            staged.dispose();
+        }
+    }
+    return failures > 0 ? 1 : 0;
+}
+// `require.main === module` rather than a bare call: importing this file from a
+// test must not run the tool against the developer's own AFFiNE install.
+if (require.main === module)
+    process.exit(runCli());

package/dist/exportMarkdown.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Writing a workspace out as Markdown + blob files, ready for a watched folder.
+ */
+import type { ReadOptions, SqliteDatabase, WorkspaceContent } from './types';
+export interface ExportResult extends WorkspaceContent {
+    outDir: string;
+    files: {
+        docId: string;
+        path: string;
+    }[];
+    blobsWritten: number;
+}
+export interface ExportOptions extends ReadOptions {
+    /** Also write the blob bytes next to the docs. Default true. */
+    writeBlobs?: boolean;
+}
+/** Filesystem-safe stem. Accents are folded, never dropped into an empty name. */
+export declare function slugify(input: string, fallback: string): string;
+/**
+ * A file name that is stable across runs and unique within a workspace.
+ *
+ * The doc id is part of the name on purpose: a watched folder is re-exported over
+ * and over, and keying the file on the TITLE would leave an orphan copy behind
+ * every time someone renames a doc — the folder would slowly fill with duplicates
+ * of the same document under its old names.
+ */
+export declare function fileNameFor(title: string, docId: string): string;
+/**
+ * The folder one workspace is exported into, relative to the destination.
+ *
+ * 🚨 The peer is part of the name, not decoration. A workspace synced from a
+ * server and a local one can carry the SAME id, and a name built from the id
+ * alone makes the second export silently overwrite the first. Both callers —
+ * the CLI and the app's IPC handler — go through this one function, so the two
+ * doors cannot resolve the same workspace to two different directories.
+ */
+export declare function workspaceFolderName(ref: {
+    id: string;
+    peer: string;
+}): string;
+/**
+ * Read `db` and write one Markdown file per doc into `outDir`.
+ *
+ * The caller owns `outDir`. Nothing is ever written back into AFFiNE's directory.
+ */
+export declare function exportWorkspace(db: SqliteDatabase, outDir: string, options?: ExportOptions): ExportResult;

package/dist/exportMarkdown.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Writing a workspace out as Markdown + blob files, ready for a watched folder.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.slugify = slugify;
+exports.fileNameFor = fileNameFor;
+exports.workspaceFolderName = workspaceFolderName;
+exports.exportWorkspace = exportWorkspace;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const read_1 = require("./read");
+/** Filesystem-safe stem. Accents are folded, never dropped into an empty name. */
+function slugify(input, fallback) {
+    const cleaned = input
+        .normalize('NFD')
+        .replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+    return cleaned || fallback;
+}
+/**
+ * A file name that is stable across runs and unique within a workspace.
+ *
+ * The doc id is part of the name on purpose: a watched folder is re-exported over
+ * and over, and keying the file on the TITLE would leave an orphan copy behind
+ * every time someone renames a doc — the folder would slowly fill with duplicates
+ * of the same document under its old names.
+ */
+function fileNameFor(title, docId) {
+    return `${slugify(title, 'doc')}--${slugify(docId, 'id')}.md`;
+}
+/**
+ * The folder one workspace is exported into, relative to the destination.
+ *
+ * 🚨 The peer is part of the name, not decoration. A workspace synced from a
+ * server and a local one can carry the SAME id, and a name built from the id
+ * alone makes the second export silently overwrite the first. Both callers —
+ * the CLI and the app's IPC handler — go through this one function, so the two
+ * doors cannot resolve the same workspace to two different directories.
+ */
+function workspaceFolderName(ref) {
+    return `affine-${slugify(ref.peer, 'peer')}-${slugify(ref.id, 'id')}`;
+}
+function blobFileName(key, mime) {
+    const ext = (mime.split('/')[1] ?? 'bin').replace('+xml', '').replace(/[^a-z0-9]/gi, '');
+    return `${slugify(key, 'blob')}.${ext || 'bin'}`;
+}
+function frontMatter(fields) {
+    const lines = Object.entries(fields).map(([key, value]) => typeof value === 'string' ? `${key}: ${JSON.stringify(value)}` : `${key}: ${value}`);
+    return ['---', ...lines, '---', ''].join('\n');
+}
+/**
+ * Read `db` and write one Markdown file per doc into `outDir`.
+ *
+ * The caller owns `outDir`. Nothing is ever written back into AFFiNE's directory.
+ */
+function exportWorkspace(db, outDir, options = {}) {
+    (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    // Blob file names are decided BEFORE the docs are rendered, so an image link and
+    // the file it points at come from the SAME map. Computing them separately is how
+    // an export ends up with links that look right and resolve to nothing.
+    const schema = (0, read_1.detectSchema)(db);
+    const blobNames = new Map();
+    for (const blob of (0, read_1.readBlobIndex)(db, schema))
+        blobNames.set(blob.key, blobFileName(blob.key, blob.mime));
+    const rendered = (0, read_1.readWorkspace)(db, {
+        ...options,
+        blobUrl: (key) => {
+            const name = blobNames.get(key);
+            return name ? `blobs/${name}` : (options.blobUrl?.(key) ?? null);
+        },
+    });
+    let blobsWritten = 0;
+    if (options.writeBlobs !== false && rendered.blobs.length > 0) {
+        const blobDir = (0, node_path_1.join)(outDir, 'blobs');
+        (0, node_fs_1.mkdirSync)(blobDir, { recursive: true });
+        (0, read_1.forEachBlob)(db, rendered.schema, (blob) => {
+            const name = blobNames.get(blob.key) ?? blobFileName(blob.key, blob.mime);
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(blobDir, name), blob.data);
+            blobsWritten++;
+        });
+    }
+    const files = [];
+    for (const doc of rendered.docs) {
+        const path = (0, node_path_1.join)(outDir, fileNameFor(doc.title, doc.id));
+        // 🪤 No timestamp here, deliberately. A `read_at` written on every export
+        // changes the bytes of every file on every run, so a watched folder would
+        // see the whole workspace as modified and re-ingest (and re-embed) all of
+        // it each time — churn and cost for documents nobody touched. What changed
+        // belongs in the log and the result, not in content that is hashed.
+        const body = frontMatter({
+            source: 'affine',
+            workspace: rendered.workspaceId,
+            doc_id: doc.id,
+            title: doc.title,
+        });
+        const heading = doc.title ? `# ${doc.title}\n\n` : '';
+        (0, node_fs_1.writeFileSync)(path, `${body}${heading}${doc.markdown}`, 'utf8');
+        files.push({ docId: doc.id, path });
+    }
+    return { ...rendered, outDir, files, blobsWritten };
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @mnemosyne_os/affine-reader — read a local AFFiNE workspace, without AFFiNE.
+ *
+ * Reads the SQLite database AFFiNE keeps on disk, replays its Yjs history and
+ * renders each document to Markdown using AFFiNE's own MIT parser (vendored, see
+ * NOTICE.md). No BlockSuite at runtime, no native module, no server.
+ *
+ * ⛔ READ ONLY, in every direction. Two processes writing one CRDT corrupt it.
+ */
+export { affineDataDir, findWorkspaces } from './locate';
+export { SIDECAR_SUFFIXES, stageDatabase } from './stage';
+export type { StagedDatabase } from './stage';
+export { detectSchema, forEachBlob, loadDoc, readBlobIndex, readDocIndex, readWorkspace, readWorkspaceId, } from './read';
+export { exportWorkspace, fileNameFor, slugify, workspaceFolderName } from './exportMarkdown';
+export type { ExportOptions, ExportResult } from './exportMarkdown';
+export { hasNodeSqlite, openNodeSqlite } from './nodeSqlite';
+export type { AffineDoc, AffineSchema, BlobRef, ReadOptions, SkippedDoc, SqliteDatabase, SqliteOpener, SqliteStatement, WorkspaceContent, WorkspaceRef, } from './types';

package/dist/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * @mnemosyne_os/affine-reader — read a local AFFiNE workspace, without AFFiNE.
+ *
+ * Reads the SQLite database AFFiNE keeps on disk, replays its Yjs history and
+ * renders each document to Markdown using AFFiNE's own MIT parser (vendored, see
+ * NOTICE.md). No BlockSuite at runtime, no native module, no server.
+ *
+ * ⛔ READ ONLY, in every direction. Two processes writing one CRDT corrupt it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openNodeSqlite = exports.hasNodeSqlite = exports.workspaceFolderName = exports.slugify = exports.fileNameFor = exports.exportWorkspace = exports.readWorkspaceId = exports.readWorkspace = exports.readDocIndex = exports.readBlobIndex = exports.loadDoc = exports.forEachBlob = exports.detectSchema = exports.stageDatabase = exports.SIDECAR_SUFFIXES = exports.findWorkspaces = exports.affineDataDir = void 0;
+var locate_1 = require("./locate");
+Object.defineProperty(exports, "affineDataDir", { enumerable: true, get: function () { return locate_1.affineDataDir; } });
+Object.defineProperty(exports, "findWorkspaces", { enumerable: true, get: function () { return locate_1.findWorkspaces; } });
+var stage_1 = require("./stage");
+Object.defineProperty(exports, "SIDECAR_SUFFIXES", { enumerable: true, get: function () { return stage_1.SIDECAR_SUFFIXES; } });
+Object.defineProperty(exports, "stageDatabase", { enumerable: true, get: function () { return stage_1.stageDatabase; } });
+var read_1 = require("./read");
+Object.defineProperty(exports, "detectSchema", { enumerable: true, get: function () { return read_1.detectSchema; } });
+Object.defineProperty(exports, "forEachBlob", { enumerable: true, get: function () { return read_1.forEachBlob; } });
+Object.defineProperty(exports, "loadDoc", { enumerable: true, get: function () { return read_1.loadDoc; } });
+Object.defineProperty(exports, "readBlobIndex", { enumerable: true, get: function () { return read_1.readBlobIndex; } });
+Object.defineProperty(exports, "readDocIndex", { enumerable: true, get: function () { return read_1.readDocIndex; } });
+Object.defineProperty(exports, "readWorkspace", { enumerable: true, get: function () { return read_1.readWorkspace; } });
+Object.defineProperty(exports, "readWorkspaceId", { enumerable: true, get: function () { return read_1.readWorkspaceId; } });
+var exportMarkdown_1 = require("./exportMarkdown");
+Object.defineProperty(exports, "exportWorkspace", { enumerable: true, get: function () { return exportMarkdown_1.exportWorkspace; } });
+Object.defineProperty(exports, "fileNameFor", { enumerable: true, get: function () { return exportMarkdown_1.fileNameFor; } });
+Object.defineProperty(exports, "slugify", { enumerable: true, get: function () { return exportMarkdown_1.slugify; } });
+Object.defineProperty(exports, "workspaceFolderName", { enumerable: true, get: function () { return exportMarkdown_1.workspaceFolderName; } });
+var nodeSqlite_1 = require("./nodeSqlite");
+Object.defineProperty(exports, "hasNodeSqlite", { enumerable: true, get: function () { return nodeSqlite_1.hasNodeSqlite; } });
+Object.defineProperty(exports, "openNodeSqlite", { enumerable: true, get: function () { return nodeSqlite_1.openNodeSqlite; } });

package/dist/locate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Finding AFFiNE workspaces on disk.
+ *
+ * Layout, from AFFiNE's own comment in
+ * `packages/frontend/apps/electron/src/helper/dialog/dialog.ts`, verified against a
+ * real 0.27.4 install on Windows 2026-09-06:
+ *
+ *   <app-data>/AFFiNE/<workspaces|userspaces>/<peer>/<workspace-id>/storage.db   (v2)
+ *   <app-data>/AFFiNE/<workspaces|userspaces>/<workspace-id>/storage.db          (v1, legacy)
+ *
+ * ⚠️ The v1 branch is written from their source, NOT measured — no v1 install was
+ * available. `layout` says which one a ref came from so a caller can tell them apart.
+ */
+import type { WorkspaceRef } from './types';
+/** Root of AFFiNE's application data, or null when the app was never installed here. */
+export declare function affineDataDir(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string | null;
+/**
+ * Every workspace reachable on this machine. Never throws for a missing AFFiNE —
+ * an empty list means "nothing found", and `affineDataDir()` says whether AFFiNE
+ * is installed at all. The two are different answers and callers need both.
+ */
+export declare function findWorkspaces(opts?: {
+    dataDir?: string | null;
+}): WorkspaceRef[];

package/dist/locate.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Finding AFFiNE workspaces on disk.
+ *
+ * Layout, from AFFiNE's own comment in
+ * `packages/frontend/apps/electron/src/helper/dialog/dialog.ts`, verified against a
+ * real 0.27.4 install on Windows 2026-09-06:
+ *
+ *   <app-data>/AFFiNE/<workspaces|userspaces>/<peer>/<workspace-id>/storage.db   (v2)
+ *   <app-data>/AFFiNE/<workspaces|userspaces>/<workspace-id>/storage.db          (v1, legacy)
+ *
+ * ⚠️ The v1 branch is written from their source, NOT measured — no v1 install was
+ * available. `layout` says which one a ref came from so a caller can tell them apart.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.affineDataDir = affineDataDir;
+exports.findWorkspaces = findWorkspaces;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const SPACE_DIRS = ['workspaces', 'userspaces'];
+/** Root of AFFiNE's application data, or null when the app was never installed here. */
+function affineDataDir(env = process.env, platform = process.platform) {
+    const home = env.HOME ?? env.USERPROFILE ?? '';
+    const base = platform === 'win32'
+        ? env.APPDATA
+        : platform === 'darwin'
+            ? home && (0, node_path_1.join)(home, 'Library', 'Application Support')
+            : (env.XDG_CONFIG_HOME ?? (home && (0, node_path_1.join)(home, '.config')));
+    if (!base)
+        return null;
+    const dir = (0, node_path_1.join)(base, 'AFFiNE');
+    return (0, node_fs_1.existsSync)(dir) ? dir : null;
+}
+function isDir(path) {
+    try {
+        return (0, node_fs_1.statSync)(path).isDirectory();
+    }
+    catch {
+        // A racing uninstall, or a permission we do not have. Not a directory we can
+        // walk, which is all the caller needs — and the failure is not swallowed for
+        // any decision: an unreadable entry simply yields no workspace.
+        return false;
+    }
+}
+/**
+ * Every workspace reachable on this machine. Never throws for a missing AFFiNE —
+ * an empty list means "nothing found", and `affineDataDir()` says whether AFFiNE
+ * is installed at all. The two are different answers and callers need both.
+ */
+function findWorkspaces(opts = {}) {
+    const dataDir = opts.dataDir === undefined ? affineDataDir() : opts.dataDir;
+    if (!dataDir || !isDir(dataDir))
+        return [];
+    const found = [];
+    for (const kindDir of SPACE_DIRS) {
+        const kind = kindDir === 'workspaces' ? 'workspace' : 'userspace';
+        const root = (0, node_path_1.join)(dataDir, kindDir);
+        if (!isDir(root))
+            continue;
+        for (const entry of safeReaddir(root)) {
+            const entryPath = (0, node_path_1.join)(root, entry);
+            if (!isDir(entryPath))
+                continue;
+            // v1 put storage.db directly under the workspace id; v2 inserted a <peer> level.
+            const v1Db = (0, node_path_1.join)(entryPath, 'storage.db');
+            if ((0, node_fs_1.existsSync)(v1Db)) {
+                found.push({ id: entry, peer: 'local', kind, dbPath: v1Db, layout: 'v1' });
+                continue;
+            }
+            for (const workspaceId of safeReaddir(entryPath)) {
+                const dbPath = (0, node_path_1.join)(entryPath, workspaceId, 'storage.db');
+                if ((0, node_fs_1.existsSync)(dbPath))
+                    found.push({ id: workspaceId, peer: entry, kind, dbPath, layout: 'v2' });
+            }
+        }
+    }
+    return found;
+}
+function safeReaddir(path) {
+    try {
+        return (0, node_fs_1.readdirSync)(path);
+    }
+    catch (error) {
+        // ⚠️ An unreadable directory is NOT an empty one, and the caller cannot tell
+        // the two apart from a list. It is at least said out loud rather than
+        // skipped in silence (rule 7) — a permission error here surfaces to whoever
+        // reads the log as "we could not look", not as "there is nothing there".
+        console.warn(`[affine-reader] could not read ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}

package/dist/nodeSqlite.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A read-only SQLite adapter backed by Node's built-in `node:sqlite`.
+ *
+ * ⚠️ `node:sqlite` landed in Node 22.5. Electron 31 ships Node 20, so the app CANNOT
+ * use this one — it passes an adapter over its own better-sqlite3. This exists for
+ * scripts and tests, and it says so when the runtime cannot provide it instead of
+ * failing with an opaque module error.
+ */
+import type { SqliteOpener } from './types';
+/** True when this runtime can provide `node:sqlite`. */
+export declare function hasNodeSqlite(): boolean;
+/**
+ * Opens a STAGED COPY. Never point this at a live AFFiNE file.
+ *
+ * 🪤 Deliberately NOT opened with `readOnly: true`: recovering a WAL needs to touch
+ * the -shm, and a read-only handle on a database with a journal fails instead of
+ * reading it. Safety here comes from `stageDatabase()` — the file is our own copy —
+ * not from a flag that would break the very case the copy exists for.
+ */
+export declare const openNodeSqlite: SqliteOpener;

package/dist/nodeSqlite.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * A read-only SQLite adapter backed by Node's built-in `node:sqlite`.
+ *
+ * ⚠️ `node:sqlite` landed in Node 22.5. Electron 31 ships Node 20, so the app CANNOT
+ * use this one — it passes an adapter over its own better-sqlite3. This exists for
+ * scripts and tests, and it says so when the runtime cannot provide it instead of
+ * failing with an opaque module error.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openNodeSqlite = void 0;
+exports.hasNodeSqlite = hasNodeSqlite;
+const node_module_1 = require("node:module");
+/** True when this runtime can provide `node:sqlite`. */
+function hasNodeSqlite() {
+    try {
+        (0, node_module_1.createRequire)(__filename)('node:sqlite');
+        return true;
+    }
+    catch {
+        // Not an error to report: on Node 20 / Electron this is simply the answer,
+        // and the caller is expected to bring its own adapter.
+        return false;
+    }
+}
+/**
+ * Opens a STAGED COPY. Never point this at a live AFFiNE file.
+ *
+ * 🪤 Deliberately NOT opened with `readOnly: true`: recovering a WAL needs to touch
+ * the -shm, and a read-only handle on a database with a journal fails instead of
+ * reading it. Safety here comes from `stageDatabase()` — the file is our own copy —
+ * not from a flag that would break the very case the copy exists for.
+ */
+const openNodeSqlite = (path) => {
+    let mod;
+    try {
+        mod = (0, node_module_1.createRequire)(__filename)('node:sqlite');
+    }
+    catch (error) {
+        throw new Error('node:sqlite is unavailable in this runtime (it needs Node >= 22.5; Electron 31 ships Node 20). ' +
+            'Pass your own SqliteOpener instead. Cause: ' +
+            (error instanceof Error ? error.message : String(error)));
+    }
+    const db = new mod.DatabaseSync(path);
+    return {
+        prepare: (sql) => db.prepare(sql),
+        close: () => db.close(),
+    };
+};
+exports.openNodeSqlite = openNodeSqlite;