linksee-memory 0.17.0 → 0.17.1

package/dist/lib/guard-wiring.js

@@ -10,17 +10,119 @@
 export const GUARD_EVENTS = ['SessionStart', 'PreToolUse'];
 /** The bin every wiring form resolves to; used as the idempotency key. */
 export const GUARD_BIN = 'linksee-memory-guard';
+/** The npx form setup wrote before 0.17.1. Still the fallback when no stable install exists. */
 export const GUARD_COMMAND = 'npx -y linksee-memory guard';
-export const GUARD_HOOKS = {
-    SessionStart: {
-        matcher: 'startup|resume|compact',
-        hooks: [{ type: 'command', command: GUARD_COMMAND, timeout: 15 }],
-    },
-    PreToolUse: {
-        matcher: 'Edit|Write|Bash',
-        hooks: [{ type: 'command', command: GUARD_COMMAND, timeout: 8 }],
-    },
+export const SYNC_COMMAND = 'npx -y linksee-memory sync';
+export const NPX_HOOK_COMMANDS = { guard: GUARD_COMMAND, sync: SYNC_COMMAND };
+/**
+ * Marker setup appends to every direct-node hook it writes. It is an ordinary trailing argument
+ * (the hook scripts ignore argv), so it survives cmd.exe and sh alike — a `#` comment would not
+ * (cmd.exe has no inline comments). Only a command carrying it is treated as setup-owned.
+ */
+export const MANAGED_MARKER = '--linksee-managed';
+/**
+ * Direct `node` form (0.17.1, L-1-106 / audit F11): `npx -y` costs 6–9 s per call on a warm
+ * cache (npm start-up + a registry check), against an 8 s PreToolUse timeout — so the guard
+ * could time out and silently not fire. `"<node>" "<root>/dist/bin/<bin>.js" --linksee-managed`
+ * starts in well under a second.
+ *
+ * Shells: Claude Code runs a hook command through cmd.exe on Windows and through sh on POSIX
+ * (PowerShell is not used for hooks — assumed here; under PowerShell this form would need `&`).
+ * Double quotes protect spaces in both. They do NOT neutralise `$` or backticks (sh) or `%`
+ * (cmd.exe), and a path containing `"` cannot be quoted at all — see `shellSafePath`; setup falls
+ * back to the npx form for such paths instead of writing a command that might expand.
+ */
+export function nodeHookCommands(nodePath, packageRoot) {
+    const fwd = (p) => p.replace(/\\/g, '/');
+    const bin = (file) => `"${fwd(nodePath)}" "${fwd(packageRoot).replace(/\/$/, '')}/dist/bin/${file}" ${MANAGED_MARKER}`;
+    return { guard: bin('guard-hook.js'), sync: bin('sync-session.js') };
+}
+/** Can this path go inside double quotes in both cmd.exe and sh without being expanded? */
+export function shellSafePath(p) {
+    return !/["$`%!\r\n]/.test(p);
+}
+/** Exactly the npx strings setup wrote up to 0.17.0. */
+const LEGACY_NPX = {
+    guard: 'npx -y linksee-memory guard',
+    sync: 'npx -y linksee-memory sync',
 };
+/** The form setup itself writes from 0.17.1 on — quoted node, quoted script, the marker. */
+const MANAGED_NODE_FORM = /^"[^"]+" "[^"]+\/dist\/bin\/(guard-hook|sync-session)\.js" --linksee-managed$/;
+/**
+ * Is this command one setup wrote — (a) the exact 0.17.0-and-earlier npx string, or (b) the
+ * 0.17.1+ direct form carrying MANAGED_MARKER? Anything else (wrappers, unquoted paths, extra
+ * flags, someone else's script) is not ours to change.
+ */
+export function setupWrittenKind(command) {
+    if (typeof command !== 'string')
+        return null;
+    const c = command.trim();
+    for (const kind of ['guard', 'sync'])
+        if (LEGACY_NPX[kind] === c)
+            return kind;
+    const m = MANAGED_NODE_FORM.exec(c);
+    if (m)
+        return m[1] === 'guard-hook' ? 'guard' : 'sync';
+    return null;
+}
+function eachCommandHook(settings, fn) {
+    for (const entries of Object.values(settings.hooks ?? {})) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries)
+            for (const h of entry?.hooks ?? [])
+                if (h && h.type === 'command')
+                    fn(h);
+    }
+}
+/**
+ * Point the setup-written hooks of the given kinds at `commands`. Exec-form hooks (`args`), other
+ * tools' hooks and hand-edited commands are never touched. Only `command` changes — matcher,
+ * timeout and any other field stay. Mutates `settings`; returns the replaced commands.
+ */
+export function rewireLegacyHooks(settings, commands, kinds = ['guard', 'sync']) {
+    const replaced = [];
+    eachCommandHook(settings, (h) => {
+        if (Array.isArray(h.args) && h.args.length)
+            return;
+        const kind = setupWrittenKind(h.command);
+        if (!kind || !kinds.includes(kind) || h.command === commands[kind])
+            return;
+        replaced.push(h.command);
+        h.command = commands[kind];
+    });
+    return { replaced };
+}
+/**
+ * Hooks that look like ours (they run the guard or the sync script) but were not written by setup —
+ * hand-wired paths, wrappers, exec form. setup leaves them alone and lists them so the user knows.
+ */
+export function unmanagedLinkseeHooks(settings) {
+    const out = [];
+    eachCommandHook(settings, (h) => {
+        const hay = [h.command, ...(h.args ?? [])].filter((x) => typeof x === 'string').join(' ');
+        const looksOurs = /guard-hook|sync-session/.test(hay) || (/linksee-memory/.test(hay) && /\b(guard|sync)\b/.test(hay));
+        if (!looksOurs)
+            return;
+        if ((!h.args || !h.args.length) && setupWrittenKind(h.command))
+            return;
+        out.push(hay);
+    });
+    return out;
+}
+export function guardHooks(command = GUARD_COMMAND) {
+    return {
+        SessionStart: {
+            matcher: 'startup|resume|compact',
+            hooks: [{ type: 'command', command, timeout: 15 }],
+        },
+        PreToolUse: {
+            matcher: 'Edit|Write|Bash',
+            hooks: [{ type: 'command', command, timeout: 8 }],
+        },
+    };
+}
+export const GUARD_HOOKS = guardHooks();
 /** Everything a hook entry could carry an identifier in: `command`, or `args` for the exec form. */
 function hookHaystack(h) {
     return [h?.command, ...(h?.args ?? [])].filter((x) => typeof x === 'string').join(' ');
@@ -69,14 +171,15 @@ export function guardFullyWired(settings) {
  * Add the guard to any event it does not already own. Mutates and returns `settings`, plus the
  * events that were actually added (empty when it was already wired).
  */
-export function wireGuard(settings) {
+export function wireGuard(settings, command = GUARD_COMMAND) {
     const hooks = (settings.hooks ??= {});
     const added = [];
+    const wanted = guardHooks(command);
     for (const ev of GUARD_EVENTS) {
         if (!Array.isArray(hooks[ev]))
             hooks[ev] = [];
         if (!guardWiredFor(settings, ev)) {
-            hooks[ev].push(GUARD_HOOKS[ev]);
+            hooks[ev].push(wanted[ev]);
             added.push(ev);
         }
     }

package/dist/lib/hook-runtime.d.ts

@@ -0,0 +1,41 @@
+import { type HookCommands } from './guard-wiring.js';
+export type HookRuntime = {
+    commands: HookCommands;
+    /** 'direct' = this install is stable; 'pinned' = installed under runtime/; 'npx' = fallback. */
+    mode: 'direct' | 'pinned' | 'npx';
+    root?: string;
+    note?: string;
+    /** runtime/ folder and the version kept there, when pinned (setup reports where runtimes live). */
+    runtimeBase?: string;
+    version?: string;
+    /** Size of the pinned runtime in bytes, when one is in use. */
+    bytes?: number;
+};
+/** Is this package root inside a cache that npm / pnpm / bun may rebuild or delete? */
+export declare function isEphemeralRoot(packageRoot: string): boolean;
+/** Can a node process load the native dependency from this root? (the part most likely to break) */
+export declare function verifyRoot(root: string, nodePath: string): boolean;
+/** Locate npm's CLI script so it can be run with this node, without a shell. */
+export declare function findNpmCli(nodePath: string, env?: NodeJS.ProcessEnv): string | null;
+export type Installer = (spec: string, prefix: string, nodePath: string) => {
+    ok: boolean;
+    detail?: string;
+};
+/** `npm install --prefix <prefix> --no-save --omit=dev <spec>` with this node, no shell. */
+export declare const npmInstall: Installer;
+export declare function dirBytes(dir: string): number;
+export declare function formatBytes(n: number): string;
+export type ResolveOpts = {
+    packageRoot: string;
+    nodePath: string;
+    memoryDir: string;
+    version: string;
+    /** What to install; defaults to linksee-memory@<version>. */
+    spec?: string;
+    dryRun?: boolean;
+    /** Injected in tests; default = real child-process load check. */
+    verify?: (root: string, nodePath: string) => boolean;
+    /** Injected in tests; default = npm install with this node. */
+    install?: Installer;
+};
+export declare function resolveHookRuntime(o: ResolveOpts): HookRuntime;

package/dist/lib/hook-runtime.js

@@ -0,0 +1,197 @@
+// hook-runtime — decide what command setup writes into the Claude Code hooks.
+//
+// 0.17.1 (L-1-106 / audit F11): hooks call `node <abs>/dist/bin/<bin>.js` directly instead of
+// `npx -y linksee-memory <sub>` (6–9 s per call, against an 8 s PreToolUse timeout).
+//
+// The catch is WHERE that dist lives. `npx -y linksee-memory setup` runs out of npm's npx cache,
+// which npm may rebuild or wipe at any time. So when setup runs from such a temporary place, it
+// installs this exact version once into <memory dir>/runtime/<version>/ with
+//   npm install --prefix <memory dir>/runtime/<version> --no-save --omit=dev linksee-memory@<version>
+// (the only network call, and only during setup) and points the hooks there. A global install or
+// 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.
+//   • 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.
+// The node path written is process.execPath at setup time. If Node is later upgraded to another
+// major, the guard hook catches the driver load failure, says "re-run setup" on stderr and exits 0.
+import { existsSync, readFileSync, readdirSync, renameSync, rmSync, mkdirSync, realpathSync, lstatSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { NPX_HOOK_COMMANDS, nodeHookCommands, shellSafePath } from './guard-wiring.js';
+function norm(p) {
+    let r = resolve(p);
+    try {
+        r = realpathSync(r);
+    }
+    catch { /* keep resolved */ }
+    return process.platform === 'win32' ? r.toLowerCase() : r;
+}
+/** Is this package root inside a cache that npm / pnpm / bun may rebuild or delete? */
+export function isEphemeralRoot(packageRoot) {
+    const p = norm(packageRoot);
+    const parts = p.split(/[\\/]+/);
+    if (parts.includes('_npx') || parts.includes('dlx') || parts.some((s) => s.startsWith('bunx-')))
+        return true;
+    const t = norm(tmpdir());
+    return p === t || p.startsWith(t + sep) || p.startsWith(t + '/');
+}
+/** Can a node process load the native dependency from this root? (the part most likely to break) */
+export function verifyRoot(root, nodePath) {
+    const pkg = join(root, 'package.json');
+    if (!existsSync(join(root, 'dist', 'bin', 'guard-hook.js')) || !existsSync(pkg))
+        return false;
+    const r = spawnSync(nodePath, ['-e', `const r=require('node:module').createRequire(${JSON.stringify(pkg)});const D=r('better-sqlite3');new D(':memory:').close()`], { encoding: 'utf8', timeout: 30000 });
+    return r.status === 0;
+}
+/** Locate npm's CLI script so it can be run with this node, without a shell. */
+export function findNpmCli(nodePath, env = process.env) {
+    const cands = [];
+    const ep = env.npm_execpath;
+    if (ep) {
+        if (/npm-cli\.js$/.test(ep))
+            cands.push(ep);
+        if (/npx-cli\.js$/.test(ep))
+            cands.push(join(dirname(ep), 'npm-cli.js'));
+    }
+    const nodeDir = dirname(nodePath);
+    cands.push(join(nodeDir, 'node_modules', 'npm', 'bin', 'npm-cli.js')); // Windows installer
+    cands.push(join(nodeDir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js')); // POSIX layout
+    return cands.find((c) => existsSync(c)) ?? null;
+}
+/** `npm install --prefix <prefix> --no-save --omit=dev <spec>` with this node, no shell. */
+export const npmInstall = (spec, prefix, nodePath) => {
+    const cli = findNpmCli(nodePath);
+    if (!cli)
+        return { ok: false, detail: 'npm not found next to this node' };
+    const r = spawnSync(nodePath, [cli, 'install', '--prefix', prefix, '--no-save', '--omit=dev', '--no-audit', '--no-fund', '--loglevel=error', spec], { encoding: 'utf8', timeout: 300000, stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.status === 0)
+        return { ok: true };
+    return { ok: false, detail: (r.stderr || r.error?.message || `exit ${r.status}`).trim().split('\n').slice(-2).join(' ') };
+};
+export function dirBytes(dir) {
+    let total = 0;
+    const walk = (d) => {
+        let names = [];
+        try {
+            names = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const p = join(d, n);
+            let st;
+            try {
+                st = lstatSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (st.isSymbolicLink())
+                continue;
+            if (st.isDirectory())
+                walk(p);
+            else
+                total += st.size;
+        }
+    };
+    walk(dir);
+    return total;
+}
+export function formatBytes(n) {
+    return n >= 1024 * 1024 ? `${(n / 1024 / 1024).toFixed(0)} MB` : `${Math.max(1, Math.round(n / 1024))} KB`;
+}
+export function resolveHookRuntime(o) {
+    const verify = o.verify ?? verifyRoot;
+    const install = o.install ?? npmInstall;
+    const npx = (note) => ({ commands: NPX_HOOK_COMMANDS, mode: 'npx', note });
+    if (!shellSafePath(o.nodePath))
+        return npx(`the node path contains a character a hook command cannot quote safely (${o.nodePath})`);
+    if (!isEphemeralRoot(o.packageRoot)) {
+        if (!shellSafePath(o.packageRoot))
+            return npx(`the package path contains a character a hook command cannot quote safely (${o.packageRoot})`);
+        return { commands: nodeHookCommands(o.nodePath, o.packageRoot), mode: 'direct', root: o.packageRoot };
+    }
+    const base = join(o.memoryDir, 'runtime');
+    const dest = join(base, o.version);
+    const destRoot = join(dest, 'node_modules', 'linksee-memory');
+    if (!shellSafePath(destRoot))
+        return npx(`the memory folder path contains a character a hook command cannot quote safely (${destRoot})`);
+    const pinned = (note) => {
+        const bytes = dirBytes(dest);
+        return { commands: nodeHookCommands(o.nodePath, destRoot), mode: 'pinned', root: destRoot, runtimeBase: base, version: o.version, bytes, note: `${note}; ${formatBytes(bytes)}` };
+    };
+    const versionAt = (root) => {
+        try {
+            return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
+        }
+        catch {
+            return null;
+        }
+    };
+    // Already installed and loadable → reuse, no network.
+    if (versionAt(destRoot) === o.version && verify(destRoot, o.nodePath)) {
+        return pinned(`using the pinned runtime at ${dest}`);
+    }
+    if (o.dryRun) {
+        return { commands: nodeHookCommands(o.nodePath, destRoot), mode: 'pinned', root: destRoot, note: `[dry-run] would run npm install into ${dest}` };
+    }
+    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) => {
+        try {
+            rmSync(staging, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+        return npx(`${why}; kept the npx form, existing runtime left as it was`);
+    };
+    try {
+        rmSync(staging, { recursive: true, force: true });
+        mkdirSync(staging, { recursive: true });
+    }
+    catch (e) {
+        return fail(`could not create ${staging} (${e?.message ?? e})`);
+    }
+    const res = install(spec, staging, o.nodePath);
+    if (!res.ok)
+        return fail(`npm install ${spec} failed (${res.detail ?? 'unknown error'})`);
+    if (versionAt(stagingRoot) !== o.version)
+        return fail(`npm installed ${versionAt(stagingRoot) ?? 'nothing'} instead of ${o.version}`);
+    if (!verify(stagingRoot, o.nodePath))
+        return fail(`the installed runtime could not load better-sqlite3`);
+    // Same-version replacement must be undoable: move the old folder aside, move the new one in,
+    // and only then delete the old one. If the second move fails, put the old one back.
+    const aside = `${dest}.old-${process.pid}`;
+    let movedAside = false;
+    try {
+        if (existsSync(dest)) {
+            renameSync(dest, aside);
+            movedAside = true;
+        }
+        renameSync(staging, dest);
+    }
+    catch (e) {
+        if (movedAside) {
+            try {
+                renameSync(aside, dest);
+            }
+            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}`}`);
+    }
+    if (movedAside) {
+        try {
+            rmSync(aside, { recursive: true, force: true });
+        }
+        catch { /* harmless leftover */ }
+    }
+    // Older versions are never removed automatically (see above).
+    return pinned(`installed ${spec} into ${dest}`);
+}
+//# sourceMappingURL=hook-runtime.js.map

package/dist/lib/map-import.js

@@ -71,13 +71,13 @@ export function importMap(db, map) {
     const anchorExists = db.prepare('SELECT 1 FROM drift_anchors WHERE id = ?');
     let linked = 0;
     const tx = db.transaction(() => {
-        db.prepare(`
-      INSERT INTO map_projects (project, job, audience, product_status, template, stages, related_projects, updated_at)
-      VALUES (@project, @job, @audience, @product_status, @template, @stages, @related_projects, unixepoch())
-      ON CONFLICT(project) DO UPDATE SET
-        job=excluded.job, audience=excluded.audience, product_status=excluded.product_status,
-        template=excluded.template, stages=excluded.stages, related_projects=excluded.related_projects,
-        updated_at=unixepoch()
+        db.prepare(`
+      INSERT INTO map_projects (project, job, audience, product_status, template, stages, related_projects, updated_at)
+      VALUES (@project, @job, @audience, @product_status, @template, @stages, @related_projects, unixepoch())
+      ON CONFLICT(project) DO UPDATE SET
+        job=excluded.job, audience=excluded.audience, product_status=excluded.product_status,
+        template=excluded.template, stages=excluded.stages, related_projects=excluded.related_projects,
+        updated_at=unixepoch()
     `).run({
             project: map.project,
             job: map.job ?? null,
@@ -89,13 +89,13 @@ export function importMap(db, map) {
         });
         db.prepare('DELETE FROM map_edges WHERE project = ?').run(map.project);
         db.prepare('DELETE FROM map_nodes WHERE project = ?').run(map.project);
-        const insNode = db.prepare(`
-      INSERT INTO map_nodes
-        (id, project, layer, stage, statement, status, facets, role, note, due,
-         paused_reason, related_project, spinout_candidate, anchor_id, review_by, revival_condition, reality, extra, updated_at)
-      VALUES
-        (@id, @project, @layer, @stage, @statement, @status, @facets, @role, @note, @due,
-         @paused_reason, @related_project, @spinout_candidate, @anchor_id, @review_by, @revival_condition, @reality, @extra, unixepoch())
+        const insNode = db.prepare(`
+      INSERT INTO map_nodes
+        (id, project, layer, stage, statement, status, facets, role, note, due,
+         paused_reason, related_project, spinout_candidate, anchor_id, review_by, revival_condition, reality, extra, updated_at)
+      VALUES
+        (@id, @project, @layer, @stage, @statement, @status, @facets, @role, @note, @due,
+         @paused_reason, @related_project, @spinout_candidate, @anchor_id, @review_by, @revival_condition, @reality, @extra, unixepoch())
     `);
         for (const n of map.nodes) {
             if (!n.id)
@@ -134,9 +134,9 @@ export function importMap(db, map) {
                 extra: JSON.stringify(extra),
             });
         }
-        const insEdge = db.prepare(`
-      INSERT OR IGNORE INTO map_edges (project, from_id, to_id, type, strength, note)
-      VALUES (?, ?, ?, ?, ?, ?)
+        const insEdge = db.prepare(`
+      INSERT OR IGNORE INTO map_edges (project, from_id, to_id, type, strength, note)
+      VALUES (?, ?, ?, ?, ?, ?)
     `);
         for (const e of map.edges)
             insEdge.run(map.project, e.from, e.to, e.type, e.strength ?? null, e.note ?? null);

package/dist/lib/native-hint.d.ts

@@ -0,0 +1,5 @@
+export declare const NATIVE_HINT = "linksee-memory: native module failed to load (Node changed?). Re-run: npx -y linksee-memory setup";
+/** Does this error (or child-process stderr) look like the native addon failing to load? */
+export declare function isNativeLoadError(e: unknown): boolean;
+/** Append one line to <memory dir>/hook.log; never throws. */
+export declare function hookLog(msg: string): void;

package/dist/lib/native-hint.js

@@ -0,0 +1,42 @@
+// native-hint — tell the user, in one line, when the SQLite native addon cannot load.
+//
+// 0.17.1 (Codex re-review of #15): hooks call `node <runtime>/dist/bin/*.js` with the node that ran
+// setup. After a Node major upgrade the pinned better-sqlite3 addon no longer matches the ABI. That
+// failure happens at `new Database()` (better-sqlite3 loads the .node lazily), not at import — so
+// the hooks catch it around opening the DB. They still fail open (exit 0), but say why once on
+// stderr; any other failure stays silent and goes to hook.log only.
+//
+// Must not import better-sqlite3 (it is used exactly when that import is the problem).
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+export const NATIVE_HINT = 'linksee-memory: native module failed to load (Node changed?). Re-run: npx -y linksee-memory setup';
+const NATIVE_PATTERNS = [
+    /NODE_MODULE_VERSION/,
+    /was compiled against a different Node\.js version/i,
+    /Could not locate the bindings file/i,
+    /ERR_DLOPEN_FAILED/,
+    /not a valid Win32 application/i,
+    /invalid ELF header/i,
+    /wrong ELF class/i,
+    /mach-o, but wrong architecture|not a mach-o file/i,
+    /better_sqlite3\.node/,
+    /Cannot find (module|package) 'better-sqlite3'/,
+];
+/** Does this error (or child-process stderr) look like the native addon failing to load? */
+export function isNativeLoadError(e) {
+    const text = typeof e === 'string'
+        ? e
+        : [e?.code, e?.message, e?.stack].filter(Boolean).join('\n');
+    return NATIVE_PATTERNS.some((re) => re.test(text));
+}
+/** Append one line to <memory dir>/hook.log; never throws. */
+export function hookLog(msg) {
+    try {
+        const dir = process.env.LINKSEE_MEMORY_DIR ?? join(homedir(), '.linksee-memory');
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(join(dir, 'hook.log'), `[${new Date().toISOString()}] ${msg}\n`);
+    }
+    catch { /* never throw from log */ }
+}
+//# sourceMappingURL=native-hint.js.map

package/dist/lib/settings-file.d.ts

@@ -0,0 +1,23 @@
+export type SettingsRead = {
+    ok: true;
+    exists: boolean;
+    settings: Record<string, unknown>;
+    raw: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function stripBom(raw: string): string;
+/** Read a settings file. A missing file is `{}`; an unreadable or non-object file is a refusal. */
+export declare function readSettingsFile(path: string): SettingsRead;
+export declare function backupTimestamp(d?: Date): string;
+/** `backup` is set only on the write that created it. */
+export type SettingsWrite = {
+    written: boolean;
+    backup?: string;
+};
+/**
+ * Write `settings` to `path` if (and only if) it differs from what is on disk.
+ * Leaves `<path>.bak-<timestamp>` before the first write of this process; writes atomically.
+ */
+export declare function writeSettingsFile(path: string, settings: Record<string, unknown>): SettingsWrite;

package/dist/lib/settings-file.js

@@ -0,0 +1,137 @@
+// settings-file — read and write ~/.claude/settings.json without ever losing what was there.
+//
+// Why (L-1-106 / audit F4, 2026-11-04): setup's Stop-hook step parsed the file, and on a parse
+// failure carried on with `{}` and wrote it back — wiping every other hook and setting the user
+// had. A UTF-8 BOM (Notepad's default on Windows) was enough to trigger it. The guard step
+// already refused to touch a file it could not parse; this module gives both steps one set of
+// rules:
+//
+//   • strip a leading BOM before parsing
+//   • if the file exists but does not parse to an object, refuse — never write
+//   • before the first write of a run, leave one `settings.json.bak-<timestamp>` copy
+//   • write to a temp file in the same folder, then rename (no half-written settings.json)
+//   • write nothing when nothing changed (a second setup run is a no-op)
+import { existsSync, readFileSync, writeFileSync, renameSync, copyFileSync, mkdirSync, unlinkSync, statSync, chmodSync, lstatSync, realpathSync } from 'node:fs';
+import { dirname } from 'node:path';
+export function stripBom(raw) {
+    return raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+}
+/** Read a settings file. A missing file is `{}`; an unreadable or non-object file is a refusal. */
+export function readSettingsFile(path) {
+    if (!existsSync(path)) {
+        let dangling = false;
+        try {
+            dangling = lstatSync(path).isSymbolicLink();
+        }
+        catch { /* really absent */ }
+        if (dangling)
+            return { ok: false, reason: 'symbolic link whose target does not exist' };
+        return { ok: true, exists: false, settings: {}, raw: '' };
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        return { ok: false, reason: `could not read: ${e?.message ?? e}` };
+    }
+    const body = stripBom(raw);
+    if (body.trim() === '')
+        return { ok: true, exists: true, settings: {}, raw };
+    try {
+        const parsed = JSON.parse(body);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return { ok: false, reason: 'top level is not a JSON object' };
+        }
+        return { ok: true, exists: true, settings: parsed, raw };
+    }
+    catch (e) {
+        return { ok: false, reason: `invalid JSON: ${e?.message ?? e}` };
+    }
+}
+/**
+ * Paths this process already backed up (value = the .bak path) or created (value = ''), so one
+ * setup run leaves at most one .bak per file — and none for a file the run itself created.
+ */
+const backedUp = new Map();
+export function backupTimestamp(d = new Date()) {
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+/**
+ * Write `settings` to `path` if (and only if) it differs from what is on disk.
+ * Leaves `<path>.bak-<timestamp>` before the first write of this process; writes atomically.
+ */
+export function writeSettingsFile(path, settings) {
+    const next = JSON.stringify(settings, null, 2);
+    let current = null;
+    if (existsSync(path)) {
+        current = readFileSync(path, 'utf8');
+        // Compare structurally so formatting or a BOM alone never triggers a rewrite.
+        try {
+            if (JSON.stringify(JSON.parse(stripBom(current)), null, 2) === next)
+                return { written: false };
+        }
+        catch {
+            // The caller should have refused an unparseable file; refuse here too rather than clobber it.
+            throw new Error(`refusing to overwrite unparseable ${path}`);
+        }
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    let backup = backedUp.get(path);
+    let created = false;
+    if (backup === undefined) {
+        created = true;
+        if (current !== null) {
+            backup = `${path}.bak-${backupTimestamp()}`;
+            copyFileSync(path, backup);
+        }
+        else {
+            backup = '';
+        }
+        backedUp.set(path, backup);
+    }
+    // If settings.json is a symlink (dotfiles repos), replace the file it points to, not the link.
+    let target = path;
+    let isLink = false;
+    try {
+        isLink = lstatSync(path).isSymbolicLink();
+    }
+    catch { /* no file, no link */ }
+    if (isLink) {
+        // A dangling link (target missing) is refused: replacing it would silently turn the user's
+        // link into a plain file, and following it would create a file somewhere they did not expect.
+        try {
+            target = realpathSync(path);
+        }
+        catch {
+            throw new Error(`refusing to write ${path}: it is a symbolic link whose target does not exist`);
+        }
+    }
+    // Keep the original permission bits (e.g. 600) — a fresh temp file gets the umask default.
+    // On Windows chmod only toggles read-only, so this is effectively a no-op there.
+    let mode;
+    try {
+        mode = statSync(target).mode & 0o7777;
+    }
+    catch { /* new file */ }
+    const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        // Create the temp file with the original mode from the start (umask may widen it, so chmod too).
+        writeFileSync(tmp, next, mode !== undefined ? { encoding: 'utf8', mode } : 'utf8');
+        if (mode !== undefined)
+            chmodSync(tmp, mode);
+        renameSync(tmp, target);
+    }
+    catch (e) {
+        try {
+            if (existsSync(tmp))
+                unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+        throw e;
+    }
+    // Report the backup only on the write that made it, so callers print it once.
+    return { written: true, backup: created && backup ? backup : undefined };
+}
+//# sourceMappingURL=settings-file.js.map