linksee-memory 0.17.1 → 0.18.0

package/dist/bin/runtime.js

@@ -0,0 +1,381 @@
+#!/usr/bin/env node
+// linksee-memory runtime list | prune [--yes --scope-confirmed] [--settings <file>]…   (0.17.2, L-1-148)
+//
+// setup (run through npx) installs each version under <memory dir>/runtime/<version>/ (about
+// 35 MB each) and never deletes older ones. This command lists them and deletes, only when asked
+// twice over (--yes AND --scope-confirmed), the versions nothing is confirmed to reference.
+//
+// Where a reference can be:
+//   user:    ~/.claude/settings.json, ~/.claude/settings.local.json, ~/.claude.json, ~/.codex/config.toml
+//   project: <cwd>/.claude/settings.json, <cwd>/.claude/settings.local.json
+//   extra:   every --settings <file>
+// Project settings of OTHER repos (where `setup --project` was run) cannot be found from here.
+// So --yes alone deletes nothing: --scope-confirmed says "I checked the other repos' .claude/
+// settings*.json, or passed them all with --settings" (Codex review of #19).
+//
+// How a file is read (Codex review of #19: no raw-text grep as the only test):
+//   • JSON: parsed; every string (keys and values, at any depth) is checked for runtime/<version>
+//     after normalizing \ → /. Parse failure → could not confirm.
+//   • TOML (~/.codex/config.toml): a deliberately small line reader (Codex second review of #19:
+//     do not be clever). The ONLY lines it accepts are: blank, `# comment`, a `[table]` /
+//     `[[array]]` header of bare keys, and `bare.key = <value>` where the value is one string
+//     ("…" with escapes decoded, or '…'), a one-line array of such strings, a number, or
+//     true/false. Anything else - a quoted key, an inline table, a multi-line array or string, a
+//     date, an unknown form - makes the whole file "could not confirm". Every string it read
+//     (whatever the key) is checked for a runtime path.
+//   • In both, the raw text is ALSO searched (a match there only keeps a version, never deletes one).
+// A default file that does not exist (ENOENT) references nothing. Anything else that cannot be
+// confirmed → nothing is deleted, the reason is printed, exit 1.
+// Never touched: .tmp-* (an install in progress), *.old-* (kept from a failed same-version swap),
+// any name that is not a version, and the version this command runs from.
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dirBytes, formatBytes } from '../lib/hook-runtime.js';
+import { renameGuarded, rmGuarded } from '../lib/test-faults.js';
+const VERSION_DIR = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]+)?$/;
+export function defaultSources(home, cwd) {
+    return [
+        join(home, '.claude', 'settings.json'),
+        join(home, '.claude', 'settings.local.json'),
+        join(home, '.claude.json'),
+        join(home, '.codex', 'config.toml'),
+        join(cwd, '.claude', 'settings.json'),
+        join(cwd, '.claude', 'settings.local.json'),
+    ].map((path) => ({ path, explicit: false }));
+}
+export const normPath = (t) => {
+    const s = t.replace(/\\+/g, '/');
+    return process.platform === 'win32' ? s.toLowerCase() : s;
+};
+function jsonStrings(v, out) {
+    if (typeof v === 'string')
+        out.push(v);
+    else if (Array.isArray(v))
+        for (const x of v)
+            jsonStrings(x, out);
+    else if (v && typeof v === 'object')
+        for (const [k, x] of Object.entries(v)) {
+            out.push(k);
+            jsonStrings(x, out);
+        }
+}
+/** Parse one TOML string token at s[i]; returns [value, nextIndex] or null. */
+function tomlString(s, i) {
+    if (s[i] === "'") {
+        if (s.startsWith("'''", i))
+            return null; // multi-line literal: not handled → unconfirmable
+        const j = s.indexOf("'", i + 1);
+        return j < 0 ? null : [s.slice(i + 1, j), j + 1];
+    }
+    if (s[i] !== '"' || s.startsWith('"""', i))
+        return null;
+    let out = '';
+    let j = i + 1;
+    while (j < s.length) {
+        const c = s[j];
+        if (c === '"')
+            return [out, j + 1];
+        if (c === '\\') {
+            const n = s[j + 1];
+            const map = { '"': '"', '\\': '\\', '/': '/', b: '\b', t: '\t', n: '\n', f: '\f', r: '\r' };
+            if (n in map) {
+                out += map[n];
+                j += 2;
+                continue;
+            }
+            if (n === 'u' || n === 'U') {
+                const len = n === 'u' ? 4 : 8;
+                const hex = s.slice(j + 2, j + 2 + len);
+                if (!/^[0-9a-fA-F]+$/.test(hex) || hex.length !== len)
+                    return null;
+                out += String.fromCodePoint(parseInt(hex, 16));
+                j += 2 + len;
+                continue;
+            }
+            return null;
+        }
+        out += c;
+        j++;
+    }
+    return null;
+}
+const BARE = '[A-Za-z0-9_-]+(?:\\s*\\.\\s*[A-Za-z0-9_-]+)*';
+const TOML_HEADER = new RegExp(`^\\[\\[?\\s*${BARE}\\s*\\]\\]?\\s*(#.*)?$`);
+const TOML_KV = new RegExp(`^(${BARE})\\s*=\\s*(.*)$`);
+const TOML_SCALAR = /^(?:true|false|[+-]?(?:0|[1-9](?:_?\d)*)(?:\.\d(?:_?\d)*)?(?:[eE][+-]?\d+)?)/;
+/**
+ * Strict, small TOML line reader. Returns every string value it read, or an error naming the first
+ * line it does not accept (then the caller treats the file as "could not confirm").
+ */
+export function tomlStrings(text) {
+    const strings = [];
+    const lines = text.replace(/^\uFEFF/, '').split(/\r?\n/);
+    for (let n = 0; n < lines.length; n++) {
+        const line = lines[n].trim();
+        const bad = (why) => ({ strings, error: `line ${n + 1}: ${why}` });
+        if (line === '' || line.startsWith('#'))
+            continue;
+        if (line.startsWith('[')) {
+            if (TOML_HEADER.test(line))
+                continue;
+            return bad('not a [table] header of bare keys');
+        }
+        const m = line.match(TOML_KV);
+        if (!m)
+            return bad('not `bare_key = value` (quoted keys are not read)');
+        const rest = m[2];
+        let i = 0;
+        const skip = () => { while (i < rest.length && (rest[i] === ' ' || rest[i] === '\t'))
+            i++; };
+        const endOk = () => { skip(); return i >= rest.length || rest[i] === '#'; };
+        if (rest[0] === '"' || rest[0] === "'") {
+            const t = tomlString(rest, 0);
+            if (!t)
+                return bad('a string it cannot read (multi-line or unterminated)');
+            strings.push(t[0]);
+            i = t[1];
+        }
+        else if (rest[0] === '[') {
+            i = 1;
+            skip();
+            while (rest[i] !== ']') {
+                const t = tomlString(rest, i);
+                if (!t)
+                    return bad('an array that is not one line of strings');
+                strings.push(t[0]);
+                i = t[1];
+                skip();
+                if (rest[i] === ',') {
+                    i++;
+                    skip();
+                    continue;
+                }
+                if (rest[i] !== ']')
+                    return bad('an array that is not one line of strings');
+            }
+            i++;
+        }
+        else {
+            const sm = rest.match(TOML_SCALAR);
+            if (!sm)
+                return bad('a value type it does not read (inline table, date, ...)');
+            i = sm[0].length;
+        }
+        if (!endOk())
+            return bad('unexpected text after the value');
+    }
+    return { strings };
+}
+/** Read every source into normalized strings, or say why it could not be confirmed. */
+export function readSources(sources) {
+    const texts = [];
+    const problems = [];
+    for (const s of sources) {
+        let raw;
+        try {
+            raw = readFileSync(s.path, 'utf8');
+        }
+        catch (e) {
+            const code = e?.code;
+            if (code === 'ENOENT' && !s.explicit)
+                continue; // absent → references nothing
+            problems.push(`${s.path}: ${code === 'ENOENT' ? 'not found (passed with --settings)' : `could not read (${code ?? e?.message})`}`);
+            continue;
+        }
+        const strings = [raw];
+        if (/\.toml$/i.test(s.path)) {
+            const t = tomlStrings(raw);
+            if (t.error) {
+                problems.push(`${s.path}: could not read as TOML (${t.error})`);
+                continue;
+            }
+            strings.push(...t.strings);
+        }
+        else {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw.replace(/^/, ''));
+            }
+            catch (e) {
+                problems.push(`${s.path}: not valid JSON (${e?.message?.split('\n')[0]})`);
+                continue;
+            }
+            jsonStrings(parsed, strings);
+        }
+        texts.push({ path: s.path, strings: strings.map(normPath) });
+    }
+    return { texts, problems };
+}
+export function listRuntimes(memoryDir) {
+    const base = join(memoryDir, 'runtime');
+    if (!existsSync(base))
+        return { base, versions: [], others: [] };
+    let names;
+    try {
+        names = readdirSync(base);
+    }
+    catch (e) {
+        return { base, versions: [], others: [], error: e?.message };
+    }
+    const versions = [];
+    const others = [];
+    for (const n of names.sort()) {
+        let dir = false;
+        try {
+            dir = statSync(join(base, n)).isDirectory();
+        }
+        catch { /* treat as other */ }
+        (dir && VERSION_DIR.test(n) ? versions : others).push(n);
+    }
+    return { base, versions, others };
+}
+export function pruneRuntimes(o) {
+    const log = o.log ?? ((l) => console.log(l));
+    const { base, versions, others, error } = listRuntimes(o.memoryDir);
+    if (error) {
+        log(`Could not list ${base}: ${error}. Nothing deleted.`);
+        return { code: 1, entries: [], problems: [error] };
+    }
+    if (versions.length === 0) {
+        log(`No runtime versions under ${base}.`);
+        for (const n of others)
+            log(`  (left alone) ${n}`);
+        return { code: 0, entries: [], problems: [] };
+    }
+    const { texts, problems } = readSources(o.sources);
+    const self = o.selfRoot ? normPath(safeReal(o.selfRoot)) : '';
+    const entries = versions.map((v) => {
+        const dir = join(base, v);
+        const needle = `runtime/${normPath(v)}`;
+        const hit = (s) => s.includes(needle + '/') || s.endsWith(needle) || s.includes(needle + '"') || s.includes(needle + "'");
+        const referencedBy = texts.filter((t) => t.strings.some(hit)).map((t) => t.path);
+        const e = { version: v, dir, bytes: dirBytes(dir), referencedBy, decision: 'delete' };
+        const dirNorm = normPath(safeReal(dir)) + '/';
+        if (self && (self + '/').startsWith(dirNorm)) {
+            e.decision = 'keep-running';
+            e.reason = 'this command is running from it';
+        }
+        else if (referencedBy.length) {
+            e.decision = 'keep-referenced';
+            e.reason = `referenced by ${referencedBy.join(', ')}`;
+        }
+        else if (problems.length) {
+            e.decision = 'keep-unconfirmed';
+            e.reason = 'could not confirm that nothing references it (see below)';
+        }
+        return e;
+    });
+    const willDelete = o.yes && !!o.scopeConfirmed && problems.length === 0;
+    log(`Runtimes under ${base}:`);
+    for (const e of entries) {
+        const what = e.decision === 'delete'
+            ? (willDelete ? 'delete' : 'no reference found (deletable with --yes --scope-confirmed)')
+            : `keep — ${e.reason}`;
+        log(`  ${e.version.padEnd(10)} ${formatBytes(e.bytes).padStart(7)}  ${what}`);
+    }
+    for (const n of others)
+        log(`  (left alone) ${n}`);
+    if (problems.length) {
+        log(`Could not confirm references, so nothing is deleted:`);
+        for (const p of problems)
+            log(`  • ${p}`);
+    }
+    log(`Checked: ${o.sources.map((s) => s.path).join(', ')}.`);
+    log(`Not checked: project settings of other repos. If you ran \`setup --project\` elsewhere, pass each repo's .claude/settings.json (and settings.local.json) with --settings.`);
+    let code = problems.length ? 1 : 0;
+    if (o.yes && !o.scopeConfirmed) {
+        log(`Nothing deleted: add --scope-confirmed once you have checked (or passed with --settings) the .claude/settings*.json of every other repo where you ran setup --project.`);
+        return { code: 1, entries, problems };
+    }
+    if (willDelete) {
+        for (const e of entries.filter((x) => x.decision === 'delete')) {
+            // Rename first so the version disappears at once (no half-deleted runtime under its own
+            // name), then remove the renamed folder.
+            const aside = join(base, `.pruning-${e.version}-${process.pid}`);
+            try {
+                renameGuarded(e.dir, aside);
+            }
+            catch (err) {
+                e.decision = 'delete-failed';
+                e.reason = err?.message;
+                code = 1;
+                log(`  could not delete ${e.version} (${e.reason}); left as it was`);
+                continue;
+            }
+            try {
+                rmGuarded(aside, { recursive: true, force: true });
+                if (existsSync(aside))
+                    throw new Error('folder still there');
+            }
+            catch (err) {
+                e.decision = 'delete-failed';
+                e.reason = `moved to ${aside} but not fully removed (${err?.message})`;
+                code = 1;
+                log(`  ${e.version}: ${e.reason}; delete that folder by hand`);
+                continue;
+            }
+            e.decision = 'deleted';
+            log(`  deleted ${e.version} (${formatBytes(e.bytes)})`);
+        }
+    }
+    return { code, entries, problems };
+}
+function safeReal(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+function usage() {
+    return `Usage: npx -y linksee-memory runtime list [--settings <file>]...
+       npx -y linksee-memory runtime prune [--yes --scope-confirmed] [--settings <file>]...
+
+Lists <memory dir>/runtime/<version> (installed by setup when run through npx) with sizes and
+what references each one. prune deletes only versions no settings file references, and only with
+both --yes and --scope-confirmed (= you checked, or passed with --settings, the .claude/settings*.json
+of every other repo where you ran setup --project). If any settings file cannot be read or parsed,
+nothing is deleted.`;
+}
+function main(argv) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === '--help' || cmd === '-h' || (cmd !== 'list' && cmd !== 'prune')) {
+        console.log(usage());
+        return cmd && cmd !== '--help' && cmd !== '-h' ? 1 : 0;
+    }
+    const extra = [];
+    let yes = false;
+    let scopeConfirmed = false;
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === '--yes' && cmd === 'prune')
+            yes = true;
+        else if (rest[i] === '--scope-confirmed' && cmd === 'prune')
+            scopeConfirmed = true;
+        else if (rest[i] === '--settings' && rest[i + 1])
+            extra.push({ path: resolve(rest[++i]), explicit: true });
+        else {
+            console.error(`Unknown argument: ${rest[i]}\n\n${usage()}`);
+            return 1;
+        }
+    }
+    const home = homedir();
+    const memoryDir = process.env.LINKSEE_MEMORY_DIR ?? join(home, '.linksee-memory');
+    const selfRoot = join(fileURLToPath(import.meta.url), '..', '..', '..');
+    return pruneRuntimes({ memoryDir, sources: [...defaultSources(home, process.cwd()), ...extra], yes, scopeConfirmed, selfRoot }).code;
+}
+const isMain = (() => {
+    try {
+        const a = process.argv[1] ? realpathSync(process.argv[1]) : '';
+        const b = realpathSync(fileURLToPath(import.meta.url));
+        return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+    }
+    catch {
+        return false;
+    }
+})();
+if (isMain)
+    process.exit(main(process.argv.slice(2)));
+//# sourceMappingURL=runtime.js.map

package/dist/bin/setup.js

@@ -457,7 +457,7 @@ console.log('');
 // removing one a hook still uses). Say what they cost and how to remove old ones by hand.
 if (runtime.mode === 'pinned' && runtime.runtimeBase && !dryRun) {
     console.log(`  ${DIM}• Hooks run from ${runtime.runtimeBase}${sep}<version> (${runtime.bytes !== undefined ? formatBytes(runtime.bytes) : 'about 35 MB'} each). Older versions are not removed automatically;${RESET}`);
-    console.log(`  ${DIM}  0.17.2 adds \`linksee-memory runtime prune\`. Until then you can delete old ones by hand: ${runtime.runtimeBase}${RESET}`);
+    console.log(`  ${DIM}  List them and remove the ones no settings file uses: npx -y linksee-memory runtime prune (see its output before adding --yes --scope-confirmed)${RESET}`);
     console.log('');
 }
 handWiredNotice(SETTINGS_PATH);

package/dist/bin/sync-session.js

@@ -77,7 +77,7 @@ async function main() {
         log(`transcript missing: ${transcriptPath}`);
         process.exit(0);
     }
-    const r = spawnSync(process.execPath, [importerPath, '--session-file', transcriptPath], {
+    const r = spawnSync(process.execPath, [importerPath, '--session-file', transcriptPath, '--via', 'stop-hook'], {
         encoding: 'utf8',
         timeout: 30000,
     });

package/dist/db/migrate.d.ts

@@ -1,5 +1,48 @@
 import Database from 'better-sqlite3';
 export declare function getDbPath(): string;
+/** This package's version (dist/db/migrate.js → ../../package.json), for exact-version guidance. */
+export declare function packageVersion(): string;
+/**
+ * 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).
+ */
+export declare function migrateCommand(): string;
+/** First version with the `migrate` subcommand. */
+export declare const MIGRATE_SINCE = "0.17.2";
+/**
+ * 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.
+ */
+export type ReadonlyProbe = {
+    kind: 'missing';
+} | {
+    kind: 'notadb';
+} | {
+    kind: 'hot';
+} | {
+    kind: 'version';
+    version: number;
+};
+/**
+ * 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 declare function probeReadonly(path: string): {
+    probe: ReadonlyProbe;
+    tidy: () => void;
+};
 export declare function openDb(): Database.Database;
 /** Oldest schema this version migrates in place. Older files are refused before any write. */
 export declare const MIN_SUPPORTED_SCHEMA = 6;
@@ -14,7 +57,7 @@ export declare 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 declare class LegacySchemaError extends DbRefusedError {
     readonly schemaVersion: number;
@@ -31,4 +74,12 @@ export declare class HotJournalError extends DbRefusedError {
 }
 /** Read meta.schema_version without writing (0 when the table or row is absent). */
 export declare function readSchemaVersion(db: Database.Database): number;
-export declare function runMigrations(db: Database.Database): void;
+export type MigrateOptions = {
+    /** Migrate schema 1–5 too. Only the `migrate` command sets this (inside its own transaction). */
+    allowLegacy?: boolean;
+    /** v4→v5 dedupe merges duplicate entities (deletes rows). Default true; `migrate` passes false. */
+    mergeDuplicateEntities?: boolean;
+    /** Called before each step (tests inject a failure here). */
+    onStep?: (step: string, db: Database.Database) => void;
+};
+export declare function runMigrations(db: Database.Database, opts?: MigrateOptions): void;