linksee-memory 0.17.1 → 0.17.2

package/dist/db/migrate.js

@@ -11,34 +11,63 @@ const DB_PATH = join(DEFAULT_DB_DIR, 'memory.db');
 export function getDbPath() {
     return DB_PATH;
 }
+/** This package's version (dist/db/migrate.js → ../../package.json), for exact-version guidance. */
+export function packageVersion() {
+    try {
+        const pkg = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+        return String(JSON.parse(readFileSync(pkg, 'utf8')).version || '');
+    }
+    catch {
+        return '';
+    }
+}
 /**
- * Decide, WITHOUT a writable connection, whether this file may be opened for writing at all.
- * (0.17.1, Codex re-review of #15.) A writable connection that is the last one to close
- * checkpoints a leftover WAL into memory.db and deletes it, and rolls back a hot journal — both
- * are writes to a file we are about to refuse. So the schema is read through a read-only
- * connection first (SQLITE_OPEN_READONLY: no checkpoint, no rollback, memory.db and -wal untouched).
- *   • schema 1–5                 → LegacySchemaError
- *   • a hot rollback journal     → HotJournalError (it cannot be read without rolling back)
- *   • not a DB                   → return; the normal open's corruption path moves it aside
- *   • native addon failed        → rethrown as is
- *   • anything else (busy, locked, unreadable) → PrecheckError: could not check, so no writing
- * When the file is refused, the -wal/-shm that the read-only open itself created are removed
- * again, so the folder is left as it was.
+ * The command that migrates / recovers this file. Pinned to this exact version: an unpinned
+ * `npx linksee-memory` could resolve to a cached older version, and versions before 0.17.2 have
+ * no `migrate` subcommand — they would start the MCP server instead (L-1-130).
  */
-function precheckBeforeWrite(path) {
+export function migrateCommand() {
+    const v = packageVersion();
+    // Never fall back to an unpinned command (Codex review of #19): if this version cannot be read,
+    // name the first version that has `migrate`, as a fixed string.
+    return /^\d+\.\d+\.\d+/.test(v) ? `npx -y linksee-memory@${v} migrate` : `npx -y linksee-memory@${MIGRATE_SINCE} migrate`;
+}
+/** First version with the `migrate` subcommand. */
+export const MIGRATE_SINCE = '0.17.2';
+/**
+ * Read the schema through a read-only connection (no checkpoint, no rollback). Returns what it
+ * found plus `tidy`, which removes the -wal/-shm that the read-only open itself added.
+ * Throws the native load error as is, and PrecheckError when the file could not be checked at all.
+ */
+export function probeReadonly(path) {
     if (!existsSync(path))
-        return; // new DB: nothing to protect, create it
+        return { probe: { kind: 'missing' }, tidy: () => { } };
     const had = { wal: existsSync(path + '-wal'), shm: existsSync(path + '-shm') };
+    const walStat = had.wal ? statSync(path + '-wal') : null;
     // Remove only what the read-only open itself added: a -wal that was absent and is still empty,
     // and a -shm that was absent (e.g. a leftover -wal with no -shm — the reader builds one).
-    // Known limit (0.17.2): if another process opens the file in the same instant, the -shm deleted
-    // here may already be in use by it. The tests check a single process only, not concurrency.
+    // 0.17.2 (Codex fifth review of #15, P2): another process may open the file in the same instant
+    // and start using the -shm. Two guards: (1) if the -wal changed while we looked (size or mtime),
+    // someone else is active → leave both; (2) the -shm is renamed aside first — on Windows a file
+    // another process has open cannot be renamed, so an in-use -shm stays. On POSIX an open -shm can
+    // still be renamed, so a writer that starts in the exact window remains a known limit.
     const tidy = () => {
         try {
-            if (!had.wal && existsSync(path + '-wal') && statSync(path + '-wal').size === 0)
+            if (had.wal) {
+                const now = existsSync(path + '-wal') ? statSync(path + '-wal') : null;
+                if (!now || !walStat || now.size !== walStat.size || now.mtimeMs !== walStat.mtimeMs)
+                    return;
+            }
+            else if (existsSync(path + '-wal')) {
+                if (statSync(path + '-wal').size !== 0)
+                    return; // someone wrote to it: not ours
                 unlinkSync(path + '-wal');
-            if (!had.shm && existsSync(path + '-shm'))
-                unlinkSync(path + '-shm');
+            }
+            if (!had.shm && existsSync(path + '-shm')) {
+                const aside = `${path}-shm.tidy-${process.pid}`;
+                renameSync(path + '-shm', aside);
+                unlinkSync(aside);
+            }
         }
         catch { /* leave them; memory.db itself is untouched either way */ }
     };
@@ -56,24 +85,46 @@ function precheckBeforeWrite(path) {
         const code = e?.code ?? '';
         const msg = e?.message ?? String(e);
         // The file vanished between the check and the open: a new DB, as above.
-        if (!existsSync(path) && (code === 'SQLITE_CANTOPEN' || code === 'ENOENT' || /unable to open|does not exist/i.test(msg)))
-            return;
+        if (!existsSync(path) && (code === 'SQLITE_CANTOPEN' || code === 'ENOENT' || /unable to open|does not exist/i.test(msg))) {
+            return { probe: { kind: 'missing' }, tidy: () => { } };
+        }
         // The native addon itself failed: let it surface as such (the hooks turn it into one line).
         if (isNativeLoadError(e))
             throw e;
-        // Not a database at all: the normal open's corruption path moves it aside (nothing lost).
-        if (code === 'SQLITE_NOTADB' || code === 'SQLITE_CORRUPT' || /not a database|malformed|disk image/i.test(msg))
-            return;
+        // Not a database at all.
+        if (code === 'SQLITE_NOTADB' || code === 'SQLITE_CORRUPT' || /not a database|malformed|disk image/i.test(msg)) {
+            return { probe: { kind: 'notadb' }, tidy };
+        }
         tidy();
         if (code === 'SQLITE_READONLY_ROLLBACK')
-            throw new HotJournalError(path);
+            return { probe: { kind: 'hot' }, tidy: () => { } };
         // Anything else (SQLITE_BUSY, locked, permission, I/O): we could not check it, so we do not
         // write to it either — fail closed (0.17.1, Codex third review of #15).
         throw new PrecheckError(path, code || msg.split('\n')[0]);
     }
-    if (v > 0 && v < MIN_SUPPORTED_SCHEMA) {
+    return { probe: { kind: 'version', version: v }, tidy };
+}
+/**
+ * Decide, WITHOUT a writable connection, whether this file may be opened for writing at all.
+ * (0.17.1, Codex re-review of #15.) A writable connection that is the last one to close
+ * checkpoints a leftover WAL into memory.db and deletes it, and rolls back a hot journal — both
+ * are writes to a file we are about to refuse. So the schema is read through a read-only
+ * connection first (SQLITE_OPEN_READONLY: no checkpoint, no rollback, memory.db and -wal untouched).
+ *   • schema 1–5                 → LegacySchemaError
+ *   • a hot rollback journal     → HotJournalError (it cannot be read without rolling back)
+ *   • not a DB                   → return; the normal open's corruption path moves it aside
+ *   • native addon failed        → rethrown as is
+ *   • anything else (busy, locked, unreadable) → PrecheckError: could not check, so no writing
+ * When the file is refused, the -wal/-shm that the read-only open itself created are removed
+ * again, so the folder is left as it was.
+ */
+function precheckBeforeWrite(path) {
+    const { probe, tidy } = probeReadonly(path);
+    if (probe.kind === 'hot')
+        throw new HotJournalError(path);
+    if (probe.kind === 'version' && probe.version > 0 && probe.version < MIN_SUPPORTED_SCHEMA) {
         tidy();
-        throw new LegacySchemaError(v, path);
+        throw new LegacySchemaError(probe.version, path);
     }
 }
 function openAt(path) {
@@ -139,7 +190,7 @@ export class DbRefusedError extends Error {
  * No old version is recommended as a stepping stone: 0.8.0–0.17.0 stop on `no such table:
  * drift_anchors` after partly altering the file, and 0.7.2 has no subcommands — `npx
  * linksee-memory@0.7.2 <anything>` starts its MCP server, whose start-up consolidate can delete
- * original rows (Codex review of PR #15). A migration command for these files is 0.17.2 work.
+ * original rows (Codex review of PR #15). 0.17.2: `linksee-memory migrate` (src/bin/migrate-legacy.ts).
  */
 export class LegacySchemaError extends DbRefusedError {
     schemaVersion;
@@ -153,7 +204,9 @@ export class LegacySchemaError extends DbRefusedError {
 \n` +
             `  3. Do not open this file with another linksee-memory version in the meantime — older versions can delete or half-migrate rows.
 \n` +
-            `A migration command for this schema is planned for 0.17.2. To start fresh instead, point LINKSEE_MEMORY_DIR at an empty folder.`);
+            `  4. Migrate it (it backs the file up first; --dry only reports): ${migrateCommand()} --dry, then the same without --dry.
+\n` +
+            `To start fresh instead, point LINKSEE_MEMORY_DIR at an empty folder.`);
         this.name = 'LegacySchemaError';
         this.schemaVersion = schemaVersion;
     }
@@ -175,8 +228,8 @@ export class HotJournalError extends DbRefusedError {
         super(`[linksee-memory] ${dbPath} has an unfinished write from an interrupted process (memory.db-journal), ` +
             `so it cannot be checked without changing it. Stopped before writing anything.
 \n` +
-            `  Back up the folder that holds memory.db (all memory.db* files) before anything else opens it. ` +
-            `A recovery command is planned for 0.17.2.`);
+            `  Back up the folder that holds memory.db (all memory.db* files) before anything else opens it, ` +
+            `then run: ${migrateCommand()} (it copies the files first, then lets SQLite roll the unfinished write back).`);
         this.name = 'HotJournalError';
     }
 }
@@ -188,7 +241,8 @@ export function readSchemaVersion(db) {
     const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
     return row ? Number(row.value) || 0 : 0;
 }
-export function runMigrations(db) {
+export function runMigrations(db, opts = {}) {
+    const step = (name) => opts.onStep?.(name, db);
     const __filename = fileURLToPath(import.meta.url);
     const schemaPath = join(dirname(__filename), 'schema.sql');
     const sql = readFileSync(schemaPath, 'utf8');
@@ -198,14 +252,16 @@ export function runMigrations(db) {
     // 0.17.1 (L-1-106 / audit F3): refuse schema 1–5 BEFORE any write. Their path through here
     // (v5 → v6 generated columns, then the v5 entity merge running after the version has already
     // been bumped to 16, with no transaction around it) can leave a half-migrated file. A safe,
-    // tested migration is 0.17.2 work. openDb() already refused these before any write; this is
-    // the second line for callers that hand in their own connection.
-    if (currentVersion > 0 && currentVersion < MIN_SUPPORTED_SCHEMA) {
+    // tested path is the `migrate` command (0.17.2): it backs up, sets allowLegacy and runs all of
+    // this inside one transaction. openDb() already refused these before any write; this is the
+    // second line for callers that hand in their own connection.
+    if (currentVersion > 0 && currentVersion < MIN_SUPPORTED_SCHEMA && !opts.allowLegacy) {
         throw new LegacySchemaError(currentVersion, getDbPath());
     }
     // v3 → v4: rebuild memories_fts with trigram tokenizer for JP/CJK support.
     // Only runs when upgrading an existing DB from schema v1-3.
     if (currentVersion > 0 && currentVersion < 4) {
+        step('v3-v4');
         db.exec(`
       DROP TRIGGER IF EXISTS trg_memories_fts_ai;
       DROP TRIGGER IF EXISTS trg_memories_fts_ad;
@@ -216,6 +272,7 @@ export function runMigrations(db) {
     // v4 → v5: add normalized_name column BEFORE schema.sql runs,
     // so the CREATE INDEX IF NOT EXISTS on (kind, normalized_name) succeeds.
     if (currentVersion > 0 && currentVersion < 5) {
+        step('v4-v5');
         const cols = db.prepare("PRAGMA table_info(entities)").all();
         if (!cols.some(c => c.name === 'normalized_name')) {
             db.exec('ALTER TABLE entities ADD COLUMN normalized_name TEXT');
@@ -229,6 +286,7 @@ export function runMigrations(db) {
     // NOTE: VIRTUAL generated columns are hidden from PRAGMA table_info.
     // Use PRAGMA table_xinfo (hidden=2 = VIRTUAL generated column) to detect them.
     if (currentVersion > 0 && currentVersion < 6) {
+        step('v5-v6');
         const xcols = db.prepare("PRAGMA table_xinfo(memories)").all();
         const hasAltitude = xcols.some(c => c.name === 'altitude' && c.hidden === 2);
         if (hasAltitude) {
@@ -249,6 +307,7 @@ export function runMigrations(db) {
     // thread_id groups related memories (session-level or decision chains).
     // memory_edges creates directed relationships between individual memories.
     if (currentVersion > 0 && currentVersion < 7) {
+        step('v6-v7');
         const cols = db.prepare("PRAGMA table_info(memories)").all();
         if (!cols.some(c => c.name === 'thread_id')) {
             db.exec('ALTER TABLE memories ADD COLUMN thread_id TEXT');
@@ -270,6 +329,7 @@ export function runMigrations(db) {
     // with all of these columns.
     const hasDriftAnchors = !!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='drift_anchors'").get();
     if (currentVersion > 0 && currentVersion < 9 && hasDriftAnchors) {
+        step('v8-v9');
         const have = new Set(db.prepare('PRAGMA table_info(drift_anchors)').all().map((c) => c.name));
         const addCol = (name, ddl) => {
             if (!have.has(name))
@@ -292,6 +352,7 @@ export function runMigrations(db) {
     // without them). Only ALTER if map_nodes already exists; a v10→v12 jump creates
     // it fresh (with the columns) via db.exec(sql) below.
     if (currentVersion > 0 && currentVersion < 12) {
+        step('v11-v12');
         const hasMapNodes = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='map_nodes'").get();
         if (hasMapNodes) {
             const have = new Set(db.prepare('PRAGMA table_info(map_nodes)').all().map((c) => c.name));
@@ -305,6 +366,7 @@ export function runMigrations(db) {
     }
     // v12 → v13: edge strength + accounted-for expiry (anti-noise / anti-graveyard).
     if (currentVersion > 0 && currentVersion < 13) {
+        step('v12-v13');
         const has = (table, col) => db.prepare(`PRAGMA table_info(${table})`).all().some((c) => c.name === col);
         if (db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='map_edges'").get()) {
             if (!has('map_edges', 'strength'))
@@ -322,8 +384,10 @@ export function runMigrations(db) {
     // node or a `readme→docs-site` edge. SQLite can't alter a PK/UNIQUE, so drop + recreate;
     // safe because importMap rebuilds both from map.yaml on every run.
     if (currentVersion > 0 && currentVersion < 14) {
+        step('v13-v14');
         db.exec('DROP TABLE IF EXISTS map_nodes; DROP TABLE IF EXISTS map_edges;');
     }
+    step('schema.sql');
     db.exec(sql);
     if (currentVersion > 0 && currentVersion < 4) {
         db.exec(`INSERT INTO memories_fts(rowid, content) SELECT id, content FROM memories;`);
@@ -345,13 +409,14 @@ export function runMigrations(db) {
     // v4 → v5: entity name normalization for dedup prevention.
     // Adds normalized_name column + backfills from existing entity names.
     if (currentVersion > 0 && currentVersion < 5) {
-        migrateV5EntityNormalization(db);
+        step('v5-backfill');
+        migrateV5EntityNormalization(db, opts.mergeDuplicateEntities !== false);
     }
 }
 /**
  * v5 migration: add normalized_name column and backfill + merge duplicates.
  */
-function migrateV5EntityNormalization(db) {
+function migrateV5EntityNormalization(db, merge) {
     // Column + index already added before db.exec(sql) above.
     // Now backfill normalized_name for all entities.
     const entities = db.prepare('SELECT id, name FROM entities').all();
@@ -369,6 +434,10 @@ function migrateV5EntityNormalization(db) {
     GROUP BY kind, normalized_name
     HAVING COUNT(*) > 1
   `).all();
+    if (dupes.length > 0 && !merge) {
+        console.log(`[linksee-memory] v5 migration: ${dupes.length} duplicate entity clusters left as they are (not merged)`);
+        return;
+    }
     if (dupes.length > 0) {
         console.log(`[linksee-memory] v5 migration: merging ${dupes.length} duplicate entity clusters`);
         db.transaction(() => {

package/dist/lib/hook-runtime.js

@@ -11,7 +11,8 @@
 // a git clone is already stable and is used where it is.
 //
 // Codex review of #15: copying npx's node_modules tree was replaced by this install — a real
-// install has no links back into the cache, its size is known, and old versions are removed.
+// install has no links back into the cache and its size is known. Old versions are never removed
+// here; `linksee-memory runtime prune` (src/bin/runtime.ts, 0.17.2) removes unreferenced ones.
 //   • the new runtime must load better-sqlite3 before anything else happens;
 //   • older runtime/<version> folders are NOT deleted (0.17.1); setup says where they are;
 //   • on any failure the existing runtime is left as it was and the hooks keep the npx form.
@@ -143,12 +144,16 @@ export function resolveHookRuntime(o) {
     const spec = o.spec ?? `linksee-memory@${o.version}`;
     const staging = join(base, `.tmp-${o.version}-${process.pid}`);
     const stagingRoot = join(staging, 'node_modules', 'linksee-memory');
-    const fail = (why) => {
+    // `previousAt`: the same-version swap moved the old runtime aside and could not put it back —
+    // then "left as it was" would be false, so the note says where it is instead (Codex 5th review, P2).
+    const fail = (why, previousAt) => {
         try {
             rmSync(staging, { recursive: true, force: true });
         }
         catch { /* ignore */ }
-        return npx(`${why}; kept the npx form, existing runtime left as it was`);
+        return npx(previousAt
+            ? `${why}; kept the npx form. The previous runtime could not be moved back: it is at ${previousAt} — rename it to ${dest} to restore it`
+            : `${why}; kept the npx form, existing runtime left as it was`);
     };
     try {
         rmSync(staging, { recursive: true, force: true });
@@ -183,7 +188,7 @@ export function resolveHookRuntime(o) {
             catch { /* reported below */ }
         }
         const restored = !movedAside || existsSync(dest);
-        return fail(`could not move the runtime into ${dest} (${e?.message ?? e})${restored ? '' : `; the previous one is at ${aside}`}`);
+        return fail(`could not move the runtime into ${dest} (${e?.message ?? e})`, restored ? undefined : aside);
     }
     if (movedAside) {
         try {

package/dist/lib/test-faults.d.ts

@@ -0,0 +1,3 @@
+import { type RmOptions } from 'node:fs';
+export declare function renameGuarded(from: string, to: string): void;
+export declare function rmGuarded(path: string, opts: RmOptions): void;

package/dist/lib/test-faults.js

@@ -0,0 +1,30 @@
+// test-faults — explicit failure injection for the rename / remove steps of `migrate` and
+// `runtime prune` (0.17.2, Codex second review of #19). Windows file locking cannot be relied on
+// to make these fail in a test (libuv opens files with FILE_SHARE_DELETE), and CI runs on Linux.
+//
+//   LINKSEE_TEST_FAIL_RENAME=2,3   the 2nd and 3rd guarded rename in this process throw
+//   LINKSEE_TEST_FAIL_RM=1         the 1st guarded recursive remove throws
+//
+// Unset (the normal case) these are plain renameSync / rmSync.
+import { renameSync, rmSync } from 'node:fs';
+const counters = {};
+function inject(kind) {
+    const spec = process.env[`LINKSEE_TEST_FAIL_${kind}`];
+    if (!spec)
+        return;
+    counters[kind] = (counters[kind] ?? 0) + 1;
+    if (spec.split(',').map((s) => Number(s.trim())).includes(counters[kind])) {
+        const e = new Error(`injected ${kind.toLowerCase()} failure #${counters[kind]}`);
+        e.code = 'EINJECTED';
+        throw e;
+    }
+}
+export function renameGuarded(from, to) {
+    inject('RENAME');
+    renameSync(from, to);
+}
+export function rmGuarded(path, opts) {
+    inject('RM');
+    rmSync(path, opts);
+}
+//# sourceMappingURL=test-faults.js.map

package/dist/mcp/server.js

@@ -64,6 +64,8 @@ const SUBCOMMANDS = {
     detect: 'detect-drift.js',
     export: 'export-report.js',
     'share-draft': 'share-draft.js',
+    migrate: 'migrate-legacy.js', // 0.17.2: schema 1–5 → current, without starting the server
+    runtime: 'runtime.js', // 0.17.2: runtime list | prune
 };
 const subcommand = process.argv[2];
 if (subcommand && Object.prototype.hasOwnProperty.call(SUBCOMMANDS, subcommand)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linksee-memory",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "mcpName": "io.github.michielinksee/linksee-memory",
   "description": "Hand a project over — to your next session, to Cursor/Codex/Gemini, to your successor — with the reasons attached. Local-first memory MCP for coding agents: decisions re-injected before the agent acts, drift detection across every project you run. One SQLite file, nothing leaves your machine.",
   "type": "module",