linksee-memory 0.16.1 → 0.17.1

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/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

package/dist/lib/share-draft.d.ts

@@ -0,0 +1,56 @@
+export declare const DRAFT_PAGE = "https://kansei-link.com/agents/note/new.html";
+export declare const URL_MAX = 2000;
+export declare const KINDS: readonly ["execution", "documentation", "hypothesis"];
+export declare const RUNTIMES: readonly ["claude", "codex", "gpt", "gemini", "other"];
+/** Text fields in URL order, with the page's caps (same numbers as the page's maxlength). */
+export declare const TEXT_FIELDS: readonly [{
+    readonly key: "task";
+    readonly max: 300;
+    readonly required: true;
+}, {
+    readonly key: "symptom";
+    readonly max: 600;
+    readonly required: true;
+}, {
+    readonly key: "tried";
+    readonly max: 2000;
+    readonly required: true;
+}, {
+    readonly key: "result";
+    readonly max: 1000;
+    readonly required: true;
+}, {
+    readonly key: "conditions";
+    readonly max: 600;
+    readonly required: false;
+}];
+export declare const ALLOWED_KEYS: readonly ["service", ...("task" | "symptom" | "tried" | "result" | "conditions")[], "kind", "runtime"];
+export declare const SERVICE_RE: RegExp;
+export declare const NOTICE: readonly ["この内容は、開いた画面で確認してから送られます。送るまでどこにも出ていません。", "URL の中身は KanseiLINK の通信の記録（Cloudflare）を通ります。秘密は入れないでください。"];
+export declare const NOTICE_EN: readonly ["Nothing is sent yet: the page opens with these fields filled, and only your click there sends them.", "The URL passes through KanseiLINK's request logs (Cloudflare). Do not put secrets in it."];
+/** Which secret shapes a text contains (kinds, in check order). Empty = clean. */
+export declare function findSecretShapes(text: string): Array<{
+    kind: string;
+    ja: string;
+}>;
+export interface ShareDraftProblem {
+    field: string;
+    reason: string;
+    kinds?: string[];
+}
+export type ShareDraftResult = {
+    ok: true;
+    url: string;
+    length: number;
+    notice: readonly string[];
+    notice_en: readonly string[];
+} | {
+    ok: false;
+    problems: ShareDraftProblem[];
+    hint: string;
+};
+/**
+ * Check the fields and build the draft URL. Pure: no I/O, no network, no DB.
+ * Returns problems (field + reason) instead of a URL when anything is off.
+ */
+export declare function buildShareDraft(input: unknown): ShareDraftResult;