@viloforge/vfkb 0.2.1

package/dist/doctor.js

@@ -0,0 +1,479 @@
+// FR-4 (ADR-0030) — `vfkb doctor`: catches the failure modes a consumer trips
+// over before they corrupt a brain — an incompatible/stale engine binding, missing
+// or inconsistent wiring, and the dual-clone drift signal (a brain last stamped by
+// a different engine build). Deterministic; unit-tested (the inner gate per ADR-0023).
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { SCHEMA_VERSION, ENGINE_VERSION, ENGINE_COMMIT } from './version.js';
+import { readManifest } from './manifest.js';
+function readJson(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function projectFromSettings(settings) {
+    const blob = JSON.stringify(settings ?? '');
+    const m = blob.match(/VFKB_PROJECT=([^\s"\\]+)/);
+    return m?.[1];
+}
+function detectPluginWiring(settings, root, pluginsFile) {
+    const registry = pluginsFile ? readJson(pluginsFile) : undefined;
+    // Prefer the install entry for THIS root; fall back to a user-scope entry; never
+    // report another project's install as ours (it would mask the not-installed WARN
+    // and can carry the wrong version).
+    const findInstall = (key) => {
+        const entries = registry?.plugins?.[key];
+        if (!Array.isArray(entries))
+            return undefined;
+        return entries.find((e) => e?.projectPath === root) ?? entries.find((e) => e?.scope === 'user');
+    };
+    const enabled = settings?.enabledPlugins ?? {};
+    for (const [key, on] of Object.entries(enabled)) {
+        if (/^vfkb@/.test(key) && on) {
+            return { key, installed: findInstall(key), registryReadable: registry !== undefined };
+        }
+    }
+    // Registry fallback (user-scope enablement never shows in the project file) — but an
+    // EXPLICIT `false` in the project settings is a deliberate disable and always wins:
+    // a lingering registry entry must not make doctor advise dismantling working
+    // fallback wiring (the #77 failure class, inverted).
+    for (const [key, entries] of Object.entries(registry?.plugins ?? {})) {
+        if (!/^vfkb@/.test(key) || !Array.isArray(entries))
+            continue;
+        if (enabled[key] === false)
+            continue;
+        const forRoot = entries.find((e) => e?.projectPath === root);
+        if (forRoot)
+            return { key, installed: forRoot, registryReadable: true };
+    }
+    return undefined;
+}
+// Claude Code relocates its ENTIRE config dir via CLAUDE_CONFIG_DIR, `plugins/`
+// included. Deriving the registry from $HOME alone makes doctor inspect HOST
+// state even when pointed at a sandbox — observed 2026-07-09, and a prerequisite
+// for any currency check (RFC-024 §1).
+function claudeConfigDir(env) {
+    if (env.CLAUDE_CONFIG_DIR)
+        return env.CLAUDE_CONFIG_DIR;
+    return env.HOME ? join(env.HOME, '.claude') : undefined;
+}
+// Read the clone's checked-out sha WITHOUT shelling git: `ls-remote` must be the
+// only subcommand this module ever issues, so that "the diagnostic does not
+// write" is observable rather than promised.
+function localHeadSha(cloneDir) {
+    const head = readFileMaybe(join(cloneDir, '.git', 'HEAD'));
+    if (!head)
+        return undefined;
+    const ref = head.trim().match(/^ref:\s*(\S+)$/)?.[1];
+    if (!ref)
+        return /^[0-9a-f]{40}$/.test(head.trim()) ? head.trim() : undefined; // detached HEAD
+    const loose = readFileMaybe(join(cloneDir, '.git', ...ref.split('/')));
+    if (loose)
+        return loose.trim();
+    const packed = readFileMaybe(join(cloneDir, '.git', 'packed-refs'));
+    for (const line of packed?.split('\n') ?? []) {
+        const [sha, name] = line.trim().split(/\s+/);
+        if (name === ref)
+            return sha;
+    }
+    return undefined;
+}
+function readFileMaybe(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+// Read-only, short-timeout. `git fetch` is rejected: it writes refs and objects
+// into the user's clone and can contend on the repo lock with a running Claude
+// Code. A diagnostic must not write.
+const realGit = (args, cwd) => execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    timeout: 5000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_SSH_COMMAND: 'ssh -oBatchMode=yes' },
+});
+/**
+ * Plugin currency (RFC-024 §1) — the check that would have caught the 2026-07-09
+ * incident: the plugin was correctly packaged and correctly installed, but the
+ * operator's MARKETPLACE CLONE never advanced, so `plugin update` had nothing
+ * newer to install and nothing said so.
+ *
+ * One axis: compare the clone's checked-out sha to its remote's HEAD via
+ * `git ls-remote` (read-only). Behind → warn, naming the remedy. Offline,
+ * unreachable, no clone, or a directory-source marketplace → skip, NEVER fail.
+ * A detector nobody runs detects nothing, so it is attempted by default with a
+ * short timeout.
+ *
+ * Returns the verdict rather than emitting it, so the install-state line above
+ * can say whether currency was compared instead of asserting it was not.
+ */
+function checkCurrency(plugin, opts, configDir) {
+    const marketplace = plugin.key.split('@')[1];
+    const kmFile = opts.knownMarketplacesFile ?? (configDir ? join(configDir, 'plugins', 'known_marketplaces.json') : undefined);
+    const entry = kmFile ? readJson(kmFile)?.[marketplace] : undefined;
+    const skip = (detail) => ({ status: 'skip', detail });
+    if (!entry)
+        return skip(`no marketplace "${marketplace}" in ${kmFile ?? 'the plugin registry'} — cannot check currency`);
+    // A directory source records the path itself and creates no clone — there is
+    // nothing that can be stale.
+    if (entry.source?.source !== 'github') {
+        return skip(`marketplace "${marketplace}" is a ${entry.source?.source ?? 'unknown'}-source — no clone to compare`);
+    }
+    if (!entry.installLocation || !existsSync(join(entry.installLocation, '.git'))) {
+        return skip(`marketplace clone not found at ${entry.installLocation ?? '(unset installLocation)'}`);
+    }
+    const clone = entry.installLocation;
+    const local = localHeadSha(clone);
+    let remote;
+    try {
+        remote = (opts.git ?? realGit)(['ls-remote', 'origin', 'HEAD'], clone).trim().split(/\s+/)[0];
+    }
+    catch {
+        remote = undefined;
+    }
+    if (!local)
+        return skip(`cannot read the checked-out revision of ${clone}`);
+    // Offline is the common case. Say so plainly: vfkb cannot tell you that you
+    // are running old code, and must not imply health it did not verify.
+    if (!remote || !/^[0-9a-f]{7,40}$/.test(remote)) {
+        return skip(`remote unreachable (offline?) — cannot tell whether ${marketplace} is current`);
+    }
+    if (remote === local) {
+        // Answer the reader's question, but only as far as the check actually goes.
+        //
+        // An earlier version said "you are running the newest published version".
+        // That is axis (b) — installed-vs-offered — which RFC-024 §1 explicitly
+        // GATES and this code never performs. All that is compared here is the
+        // marketplace clone against its remote (axis (a)). In the half-upgraded
+        // `--scope user` state the RFC documents, the clone is level while the
+        // INSTALL lags, and that wording would have told an operator running old
+        // code that they were current. It made the L4's contrast arm clean by being
+        // more confident, not by being more true.
+        //
+        // So: state the clone's currency plainly, and name the limit in the same
+        // breath. The stale branch says "you are running an old copy" because in
+        // that state the clone cannot be ahead of itself; the healthy branch cannot
+        // honestly say the converse about the install.
+        return {
+            status: 'ok',
+            detail: `${marketplace} marketplace clone is CURRENT — level with its remote (${local.slice(0, 7)}), so ` +
+                `\`claude plugin update\` will find nothing newer to install from it. Note: this compares the clone ` +
+                `to its remote; it does not compare your INSTALLED version (${plugin.installed?.version ?? 'unknown'}) ` +
+                `against what the clone offers.`,
+        };
+    }
+    return {
+        status: 'warn',
+        detail: `${marketplace} marketplace clone is STALE — it sits at ${local.slice(0, 7)} but the remote is at ` +
+            `${remote.slice(0, 7)}. You are running an old copy of the plugin, and \`claude plugin update\` ` +
+            `will find nothing newer until the clone advances. Remedy: ` +
+            `\`claude plugin marketplace update ${marketplace}\` then \`claude plugin update ${plugin.key}\`, ` +
+            `then restart Claude Code.`,
+    };
+}
+/**
+ * npm currency (ADR-0058 / RFC-030) — the npm-channel sibling of `checkCurrency`
+ * above. Opt-in ONLY (the CLI calls this solely under `--check-remote`; plain
+ * `runDoctor` never touches it, so plain `doctor` stays fully offline with zero
+ * network calls — verified by the "plain doctor" unit tests and by diffing
+ * `vfkb doctor`'s output against pre-ADR-0058 `main`).
+ *
+ * Axis-(b) wording discipline (the meta-lesson behind this whole ADR): the
+ * healthy line says exactly what was compared — the RUNNING CLI's version
+ * against the npmjs `latest` dist-tag for @viloforge/vfkb — and nothing more.
+ * Never "you are up to date". A unit test pins this with a positive regex (the
+ * comparison claim) and a negative regex (forbidden overclaim phrases).
+ */
+const NPM_PACKAGE_NAME = '@viloforge/vfkb';
+const NPM_REGISTRY_URL = 'https://registry.npmjs.org/@viloforge%2Fvfkb/latest';
+const NPM_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const NPM_CACHE_FILE = 'npm-currency-cache.json';
+function npmCacheFilePath(opts) {
+    return opts.cacheFile ?? join(opts.brainDir, '.signals', NPM_CACHE_FILE);
+}
+// Corrupt or missing cache is treated as absent, silently — never an error
+// surfaced to the user (RFC-030 §2 cache design).
+function readNpmCache(path) {
+    const raw = readJson(path);
+    if (!raw || typeof raw.version !== 'string' || typeof raw.fetchedAt !== 'string')
+        return undefined;
+    if (!Number.isFinite(Date.parse(raw.fetchedAt)))
+        return undefined;
+    return { version: raw.version, fetchedAt: raw.fetchedAt };
+}
+function writeNpmCache(path, entry) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(entry));
+    }
+    catch {
+        // Best-effort — a failed cache write must never fail the check itself.
+    }
+}
+// Small, dependency-free semver-ish comparator: numeric major.minor.patch,
+// with a release ranking above any pre-release of the same core (so 1.0.0 >
+// 1.0.0-beta.1). Sufficient for comparing two npm-published version strings;
+// not a full semver implementation.
+function parseSemverish(v) {
+    const [core, ...preParts] = v.replace(/^v/, '').split('-');
+    const nums = core.split('.').map((n) => parseInt(n, 10));
+    while (nums.length < 3)
+        nums.push(0);
+    return { core: nums.map((n) => (Number.isFinite(n) ? n : 0)), pre: preParts.join('-') };
+}
+function compareVersions(a, b) {
+    const pa = parseSemverish(a);
+    const pb = parseSemverish(b);
+    for (let i = 0; i < 3; i++) {
+        if (pa.core[i] !== pb.core[i])
+            return pa.core[i] - pb.core[i];
+    }
+    if (pa.pre === pb.pre)
+        return 0;
+    if (!pa.pre)
+        return 1; // a is a release, b is a pre-release of the same core
+    if (!pb.pre)
+        return -1;
+    return pa.pre < pb.pre ? -1 : 1;
+}
+// The comparison + wording (shared by the cache-hit and live-fetch paths — the
+// data source suffix is the only thing that differs between them).
+function renderCurrencyVerdict(installed, latest, sourceSuffix) {
+    const cmp = compareVersions(installed, latest);
+    if (cmp === 0) {
+        return {
+            status: 'ok',
+            detail: `installed ${installed} matches the npmjs latest dist-tag (${latest}) ${sourceSuffix}`,
+        };
+    }
+    if (cmp < 0) {
+        return {
+            status: 'warn',
+            detail: `installed ${installed}; npmjs latest dist-tag is ${latest} — a newer version is ` +
+                `published. Remedy: npm i -g ${NPM_PACKAGE_NAME}@latest ${sourceSuffix}`,
+        };
+    }
+    // Ahead: installed > latest — the normal state right after cutting a
+    // release, before/without npm publish, or on a local dev build. Not a
+    // problem, so `ok`, but named plainly rather than folded into the "matches"
+    // wording (that would overclaim a comparison result that isn't equality).
+    return {
+        status: 'ok',
+        detail: `installed ${installed} is newer than the npmjs latest dist-tag (${latest}) — normal ` +
+            `right after a release ${sourceSuffix}`,
+    };
+}
+export async function checkNpmCurrency(opts) {
+    const cachePath = npmCacheFilePath(opts);
+    const now = opts.now ?? Date.now;
+    const nowMs = now();
+    const cached = readNpmCache(cachePath);
+    if (cached) {
+        const ageMs = nowMs - Date.parse(cached.fetchedAt);
+        if (ageMs >= 0 && ageMs < NPM_CACHE_TTL_MS) {
+            const ageH = Math.max(0, Math.floor(ageMs / 3600000));
+            return renderCurrencyVerdict(opts.installedVersion, cached.version, `(cached ${ageH}h)`);
+        }
+    }
+    const fetchImpl = opts.fetch ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? 4000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(NPM_REGISTRY_URL, { signal: controller.signal });
+        if (res.status === 404) {
+            return { status: 'skip', detail: 'skipped (package not on npmjs)' };
+        }
+        if (!res.ok) {
+            return { status: 'skip', detail: 'skipped (registry unreachable)' };
+        }
+        const body = await res.json();
+        const latest = typeof body?.version === 'string' ? body.version : undefined;
+        if (!latest) {
+            return { status: 'skip', detail: 'skipped (registry unreachable)' };
+        }
+        writeNpmCache(cachePath, { version: latest, fetchedAt: new Date(nowMs).toISOString() });
+        return renderCurrencyVerdict(opts.installedVersion, latest, '(live)');
+    }
+    catch {
+        return { status: 'skip', detail: 'skipped (registry unreachable)' };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function runDoctor(opts) {
+    const { root, brainDir, env } = opts;
+    const checks = [];
+    const add = (name, status, detail) => checks.push({ name, status, detail });
+    // 1. Engine identity (info).
+    add('engine', 'ok', `version ${ENGINE_VERSION} · commit ${ENGINE_COMMIT} · schema v${SCHEMA_VERSION}`);
+    // Read the project settings once (used by plugin detection, hooks checks, and
+    // project-consistency below), and detect ADR-0045 plugin wiring up front — it changes
+    // what "healthy" means for the wiring checks AND which advice is safe to give
+    // (`vfkb init` on a plugin-wired repo scaffolds double wiring — issue #77).
+    const settings = readJson(join(root, '.claude', 'settings.json'));
+    const configDir = claudeConfigDir(env);
+    const pluginsFile = opts.pluginsFile ?? (configDir ? join(configDir, 'plugins', 'installed_plugins.json') : undefined);
+    const plugin = detectPluginWiring(settings, root, pluginsFile);
+    // 2. Brain ↔ engine compat (the load-bearing check).
+    const mf = readManifest(brainDir);
+    if (!mf) {
+        add('brain manifest', 'warn', plugin
+            ? `no manifest.json in ${brainDir} — it will be stamped on the next write`
+            : `no manifest.json in ${brainDir} — run \`vfkb init\` (or it will be stamped on next write)`);
+    }
+    else if (typeof mf.schema_version !== 'number') {
+        add('brain manifest', 'warn', 'manifest has no numeric schema_version');
+    }
+    else if (mf.schema_version > SCHEMA_VERSION) {
+        add('brain↔engine compat', 'fail', `brain schema v${mf.schema_version} is NEWER than engine v${SCHEMA_VERSION} — update the engine before using this brain`);
+    }
+    else if (mf.schema_version < SCHEMA_VERSION) {
+        add('brain↔engine compat', 'warn', `brain schema v${mf.schema_version} is older than engine v${SCHEMA_VERSION} — migration may be needed`);
+    }
+    else {
+        add('brain↔engine compat', 'ok', `schema v${mf.schema_version} matches`);
+        // Drift signal: same schema but a different engine build last stamped the brain.
+        if (mf.engine_commit && ENGINE_COMMIT !== 'dev' && mf.engine_commit !== ENGINE_COMMIT) {
+            add('engine drift', 'warn', `brain last stamped by engine ${mf.engine_commit}, running ${ENGINE_COMMIT} — possible dual-clone drift`);
+        }
+    }
+    // 3. $VFKB_BUNDLE_DIR resolves the bundles (the portability indirection, FR-2).
+    // On a plugin-wired repo the plugin vendors its own engine copy (ADR-0045), so an
+    // unset bundle dir is healthy, not a gap.
+    const home = env.VFKB_BUNDLE_DIR || env.VFKB_HOME;
+    if (!home) {
+        if (plugin) {
+            add('$VFKB_BUNDLE_DIR', 'ok', 'unset — not needed here: the plugin vendors the engine (ADR-0045)');
+        }
+        else {
+            add('$VFKB_BUNDLE_DIR', 'warn', 'unset — set it once per machine to the vfkb bundles dir (so the wiring resolves the engine)');
+        }
+    }
+    else if (!existsSync(join(home, 'vfkb.mjs')) || !existsSync(join(home, 'vfkb-mcp.mjs'))) {
+        add('$VFKB_BUNDLE_DIR', 'warn', `set to ${home} but vfkb.mjs / vfkb-mcp.mjs not found there (run \`npm run build:bundles\`)`);
+    }
+    else {
+        add('$VFKB_BUNDLE_DIR', 'ok', home);
+    }
+    // 3b. Deprecated env-var aliases still in use (ADR-0032) — work, but should be renamed.
+    if (env.VFKB_DIR && !env.VFKB_DATA_DIR) {
+        add('env (deprecated)', 'warn', 'VFKB_DIR is a deprecated alias — rename it to VFKB_DATA_DIR');
+    }
+    if (env.VFKB_HOME && !env.VFKB_BUNDLE_DIR) {
+        add('env (deprecated)', 'warn', 'VFKB_HOME is a deprecated alias — rename it to VFKB_BUNDLE_DIR');
+    }
+    // 4. MCP wiring. Plugin-wired repos need no .mcp.json (the plugin bundles the MCP
+    // server); one present ALONGSIDE the plugin is double wiring — advise removal, never
+    // `vfkb init` (issue #77: that advice is what causes the double wiring).
+    const mcp = readJson(join(root, '.mcp.json'));
+    const mcpProject = mcp?.mcpServers?.vfkb?.env?.VFKB_PROJECT;
+    const mcpPresent = Boolean(mcp?.mcpServers?.vfkb);
+    if (plugin && mcpPresent) {
+        add('.mcp.json', 'warn', `vfkb MCP server registered ALONGSIDE the plugin (double wiring) — remove the .mcp.json vfkb entry; the plugin is primary (ADR-0045)`);
+    }
+    else if (plugin) {
+        add('.mcp.json', 'ok', `not needed — MCP server wired via plugin ${plugin.key} (ADR-0045)`);
+    }
+    else if (!mcpPresent) {
+        add('.mcp.json', 'warn', 'no vfkb MCP server registered — run `vfkb init`');
+    }
+    else {
+        add('.mcp.json', 'ok', `vfkb server present (project ${mcpProject ?? '?'})`);
+    }
+    // 5. Hooks wiring (same plugin logic as check 4).
+    const hooks = settings?.hooks ?? {};
+    const expected = ['SessionStart', 'PreToolUse', 'Stop', 'SessionEnd'];
+    const have = expected.filter((e) => JSON.stringify(hooks[e] ?? '').includes('vfkb'));
+    if (plugin && have.length > 0) {
+        add('.claude/settings.json', 'warn', `vfkb hooks present ALONGSIDE the plugin (double wiring) — remove them; the plugin's hooks are primary (ADR-0045)`);
+    }
+    else if (plugin) {
+        add('.claude/settings.json', 'ok', `hooks wired via plugin ${plugin.key} (ADR-0045)`);
+    }
+    else if (have.length === 0) {
+        add('.claude/settings.json', 'warn', 'no vfkb hooks — run `vfkb init`');
+    }
+    else if (have.length < expected.length) {
+        add('.claude/settings.json', 'warn', `only ${have.join(', ')} wired (expected ${expected.join(', ')})`);
+    }
+    else {
+        add('.claude/settings.json', 'ok', `${have.join(', ')} wired`);
+    }
+    // 5a. Hooks must anchor to $CLAUDE_PROJECT_DIR (issue #22 / ADR-0035) — a bare
+    // CWD-relative bootstrap path breaks (MODULE_NOT_FOUND) when the session cd's out
+    // of the repo root, silently disabling the write-gate and the SessionEnd auto-commit.
+    // Skipped on plugin wiring: the plugin owns its hook paths, and any stray fallback
+    // hooks are already flagged for removal above — anchoring advice would be moot.
+    const hooksBlob = JSON.stringify(hooks ?? '');
+    if (!plugin && have.length > 0 && hooksBlob.includes('bootstrap.mjs') && !hooksBlob.includes('CLAUDE_PROJECT_DIR')) {
+        add('hooks anchor', 'warn', 'vfkb hooks use a CWD-relative bootstrap path — they break when the session cd\'s out of the repo root; re-run `vfkb init` to anchor them to $CLAUDE_PROJECT_DIR (issue #22)');
+    }
+    // 5b. The committed bootstrap entry-point (ADR-0031). Fallback wiring only — the
+    // plugin resolves its own engine and needs no committed bootstrap.
+    if (existsSync(join(root, '.vfkb', 'bin', 'bootstrap.mjs'))) {
+        add('bootstrap', 'ok', '.vfkb/bin/bootstrap.mjs present');
+    }
+    else if (!plugin && (mcpPresent || have.length > 0)) {
+        add('bootstrap', 'warn', 'wiring present but .vfkb/bin/bootstrap.mjs is missing — run `vfkb init`');
+    }
+    // 5c/5d. Plugin install state, and whether that installed copy is CURRENT.
+    //
+    // These are computed together because they used to contradict each other. The
+    // install line said "(informational — currency not compared)" while the very
+    // next line compared it. An agent reading the report inferred staleness from
+    // the bare version number plus that hedge, and reported a level clone as "an
+    // older version" — the sole contrast leak in the doctor-staleness L4, sitting
+    // exactly at ADR-0022's error budget. Every individual line was true; the
+    // report as a whole misled. That is a defect in a diagnostic.
+    //
+    // So the currency verdict is computed FIRST, and the install line says
+    // "currency not compared" only when it genuinely was not.
+    const currency = plugin ? checkCurrency(plugin, opts, configDir) : undefined;
+    if (plugin && pluginsFile) {
+        if (plugin.installed?.version) {
+            const compared = currency && currency.status !== 'skip';
+            add('plugin', 'ok', compared
+                ? `${plugin.key} installed, version ${plugin.installed.version} — see \`plugin currency\` below`
+                : `${plugin.key} installed, version ${plugin.installed.version} (currency not compared)`);
+        }
+        else if (plugin.installed) {
+            add('plugin', 'ok', `${plugin.key} installed (version unknown)`);
+        }
+        else if (plugin.registryReadable) {
+            add('plugin', 'warn', `${plugin.key} enabled in settings but not found in the local plugin registry — run \`/plugin install ${plugin.key}\` in Claude Code`);
+        }
+        else {
+            add('plugin', 'warn', `${plugin.key} enabled but the plugin registry at ${pluginsFile} is missing or unreadable — install state unverified`);
+        }
+    }
+    if (currency)
+        add('plugin currency', currency.status, currency.detail);
+    // 6. VFKB_PROJECT consistency across the two wiring files.
+    const settingsProject = projectFromSettings(settings);
+    if (mcpProject && settingsProject && mcpProject !== settingsProject) {
+        add('VFKB_PROJECT', 'fail', `mismatch: .mcp.json says "${mcpProject}", settings says "${settingsProject}"`);
+    }
+    else if (mcpProject || settingsProject) {
+        add('VFKB_PROJECT', 'ok', `${mcpProject ?? settingsProject}`);
+    }
+    return { checks, ok: !checks.some((c) => c.status === 'fail') };
+}
+const ICON = { ok: 'OK  ', warn: 'WARN', fail: 'FAIL', skip: 'SKIP' };
+export function renderDoctor(report) {
+    const lines = report.checks.map((c) => `${ICON[c.status]}  ${c.name} — ${c.detail}`);
+    lines.push('');
+    lines.push(report.ok ? 'doctor: OK (no failures)' : 'doctor: FAIL — fix the FAIL item(s) above');
+    return lines.join('\n');
+}

package/dist/doctor.test.js

@@ -0,0 +1,179 @@
+// FR-4 (ADR-0030) inner gate — `vfkb doctor` catches the failure modes a consumer
+// trips over: incompatible/stale engine binding, missing/inconsistent wiring.
+import { describe, it, expect, beforeEach } from 'vitest';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { initProject } from './init.js';
+import { runDoctor } from './doctor.js';
+import { SCHEMA_VERSION } from './version.js';
+let root;
+let home;
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'vfkb-doctor-'));
+    // a fake $VFKB_BUNDLE_DIR with the two bundle files present
+    home = mkdtempSync(join(tmpdir(), 'vfkb-home-'));
+    writeFileSync(join(home, 'vfkb.mjs'), '');
+    writeFileSync(join(home, 'vfkb-mcp.mjs'), '');
+});
+const doctor = (env) => runDoctor({ root, brainDir: join(root, '.vfkb'), env });
+const status = (r, name) => r.checks.find((c) => c.name === name)?.status;
+describe('vfkb doctor (FR-4)', () => {
+    it('a freshly init-ed repo with $VFKB_BUNDLE_DIR set is healthy (ok)', () => {
+        initProject(root, { project: 'demo' });
+        const r = doctor({ VFKB_BUNDLE_DIR: home });
+        expect(r.ok).toBe(true);
+        expect(status(r, 'brain↔engine compat')).toBe('ok');
+        expect(status(r, '$VFKB_BUNDLE_DIR')).toBe('ok');
+        expect(status(r, '.mcp.json')).toBe('ok');
+        expect(status(r, '.claude/settings.json')).toBe('ok');
+        expect(status(r, 'VFKB_PROJECT')).toBe('ok');
+    });
+    it('warns (not fails) on a bare repo with no wiring and no $VFKB_BUNDLE_DIR', () => {
+        const r = doctor({ VFKB_BUNDLE_DIR: undefined });
+        expect(r.ok).toBe(true); // warnings don't fail
+        expect(status(r, '$VFKB_BUNDLE_DIR')).toBe('warn');
+        expect(status(r, '.mcp.json')).toBe('warn');
+        expect(status(r, 'brain manifest')).toBe('warn');
+    });
+    it('FAILS when the brain schema is newer than the engine (incompatible)', () => {
+        initProject(root, { project: 'demo' });
+        writeFileSync(join(root, '.vfkb', 'manifest.json'), JSON.stringify({ schema_version: SCHEMA_VERSION + 1, engine_version: '9.9.9', engine_commit: 'x' }));
+        const r = doctor({ VFKB_BUNDLE_DIR: home });
+        expect(r.ok).toBe(false);
+        expect(status(r, 'brain↔engine compat')).toBe('fail');
+    });
+    it('FAILS on a VFKB_PROJECT mismatch between .mcp.json and settings', () => {
+        initProject(root, { project: 'demo' });
+        // corrupt .mcp.json to a different project than the settings hooks
+        const mcp = JSON.parse(readFileSync(join(root, '.mcp.json'), 'utf8'));
+        mcp.mcpServers.vfkb.env.VFKB_PROJECT = 'other';
+        writeFileSync(join(root, '.mcp.json'), JSON.stringify(mcp));
+        const r = doctor({ VFKB_BUNDLE_DIR: home });
+        expect(r.ok).toBe(false);
+        expect(status(r, 'VFKB_PROJECT')).toBe('fail');
+    });
+    it('warns when a deprecated env alias (VFKB_DIR / VFKB_HOME) is in use', () => {
+        initProject(root, { project: 'demo' });
+        const r = doctor({ VFKB_BUNDLE_DIR: home, VFKB_DIR: '.vfkb' });
+        expect(status(r, 'env (deprecated)')).toBe('warn');
+        expect(r.ok).toBe(true); // a deprecation is a warning, not a failure
+    });
+    it('warns when $VFKB_BUNDLE_DIR is set but the bundles are missing', () => {
+        initProject(root, { project: 'demo' });
+        const r = doctor({ VFKB_BUNDLE_DIR: mkdtempSync(join(tmpdir(), 'empty-home-')) });
+        expect(status(r, '$VFKB_BUNDLE_DIR')).toBe('warn');
+    });
+    // ADR-0058/RFC-030 — plain `runDoctor` (no --check-remote) never runs the npm
+    // currency check: there is no code path from here to `checkNpmCurrency`, so it
+    // makes zero fetch calls and the report never gains an 'npm currency' line.
+    // The CLI only ever calls checkNpmCurrency under the --check-remote flag.
+    it('never runs the npm currency check on its own — no "npm currency" line, ever', () => {
+        initProject(root, { project: 'demo' });
+        const r = doctor({ VFKB_BUNDLE_DIR: home });
+        expect(r.checks.find((c) => c.name === 'npm currency')).toBeUndefined();
+    });
+});
+// ADR-0045 — plugin-wired repos (issue #77): doctor must recognize the plugin as the
+// primary wiring and stop prescribing `vfkb init` (which would double-wire the repo).
+describe('vfkb doctor — plugin wiring (ADR-0045 / issue #77)', () => {
+    const PLUGIN_KEY = 'vfkb@vfkb';
+    function wirePlugin(extra = {}) {
+        mkdirSync(join(root, '.claude'), { recursive: true });
+        writeFileSync(join(root, '.claude', 'settings.json'), JSON.stringify({ enabledPlugins: { [PLUGIN_KEY]: true }, ...extra }));
+    }
+    function writeRegistry(entries) {
+        const file = join(mkdtempSync(join(tmpdir(), 'vfkb-plugreg-')), 'installed_plugins.json');
+        writeFileSync(file, JSON.stringify({ version: 2, plugins: entries }));
+        return file;
+    }
+    const pluginDoctor = (env, pluginsFile) => runDoctor({ root, brainDir: join(root, '.vfkb'), env, pluginsFile });
+    it('plugin-wired repo: wiring checks are OK, no check prescribes `vfkb init`, bundle dir may be unset', () => {
+        wirePlugin();
+        const file = writeRegistry({ [PLUGIN_KEY]: [{ scope: 'project', projectPath: root, version: '0.2.0' }] });
+        const r = pluginDoctor({}, file);
+        expect(r.ok).toBe(true);
+        expect(status(r, '.mcp.json')).toBe('ok');
+        expect(status(r, '.claude/settings.json')).toBe('ok');
+        expect(status(r, '$VFKB_BUNDLE_DIR')).toBe('ok'); // unset is fine — the plugin vendors the engine
+        expect(status(r, 'plugin')).toBe('ok');
+        for (const c of r.checks)
+            expect(c.detail).not.toContain('vfkb init');
+    });
+    it('reports the installed plugin version as information, without claiming currency', () => {
+        wirePlugin();
+        const file = writeRegistry({ [PLUGIN_KEY]: [{ scope: 'project', projectPath: root, version: '0.2.0' }] });
+        const r = pluginDoctor({}, file);
+        const plugin = r.checks.find((c) => c.name === 'plugin');
+        expect(plugin?.detail).toContain('0.2.0');
+        expect(plugin?.detail).not.toMatch(/up.to.date|latest|current/i);
+    });
+    it('warns when the plugin is enabled but not in the local install registry', () => {
+        wirePlugin();
+        const file = writeRegistry({});
+        const r = pluginDoctor({}, file);
+        expect(status(r, 'plugin')).toBe('warn');
+        expect(r.ok).toBe(true); // warn, never fail — doctor may run on a machine without Claude Code
+    });
+    it('soft-skips the install check when neither HOME nor pluginsFile is available', () => {
+        wirePlugin();
+        const r = pluginDoctor({}); // no HOME in env, no pluginsFile
+        expect(r.checks.find((c) => c.name === 'plugin')).toBeUndefined();
+        expect(status(r, '.mcp.json')).toBe('ok'); // wiring recognition does not depend on the registry
+        expect(r.ok).toBe(true);
+    });
+    it('WARNs on double wiring (plugin + leftover init wiring) and advises removal, not `vfkb init`', () => {
+        initProject(root, { project: 'demo' }); // writes .mcp.json + hooks (the fallback wiring)
+        wirePlugin(); // overwrites settings with plugin config…
+        // …but keep the init hooks too, to simulate a genuinely double-wired settings file
+        const settings = JSON.parse(readFileSync(join(root, '.claude', 'settings.json'), 'utf8'));
+        settings.hooks = { Stop: [{ hooks: [{ type: 'command', command: 'node .vfkb/bin/bootstrap.mjs cli hook stop # vfkb' }] }] };
+        writeFileSync(join(root, '.claude', 'settings.json'), JSON.stringify(settings));
+        const file = writeRegistry({ [PLUGIN_KEY]: [{ scope: 'project', projectPath: root, version: '0.2.0' }] });
+        const r = pluginDoctor({}, file);
+        expect(status(r, '.mcp.json')).toBe('warn'); // stray fallback MCP server alongside the plugin
+        expect(status(r, '.claude/settings.json')).toBe('warn'); // stray fallback hooks alongside the plugin
+        const blob = JSON.stringify(r.checks);
+        expect(blob).toMatch(/double|alongside/i);
+        expect(blob).not.toContain('run `vfkb init`');
+        expect(r.ok).toBe(true); // warn tier
+    });
+    it('detects user-scope enablement via the registry projectPath when settings has no enabledPlugins', () => {
+        // no .claude/settings.json enabledPlugins at all — plugin enabled at user scope
+        const file = writeRegistry({ [PLUGIN_KEY]: [{ scope: 'project', projectPath: root, version: '0.2.0' }] });
+        const r = pluginDoctor({}, file);
+        expect(status(r, '.mcp.json')).toBe('ok');
+        expect(status(r, '.claude/settings.json')).toBe('ok');
+        for (const c of r.checks)
+            expect(c.detail).not.toContain('vfkb init');
+    });
+    it('an explicit enabledPlugins:false disable beats a lingering registry entry — fallback advice stays intact', () => {
+        // The repo deliberately disabled the plugin and runs the init fallback; a stale
+        // registry entry must NOT make doctor advise removing the working hooks.
+        initProject(root, { project: 'demo' });
+        const settings = JSON.parse(readFileSync(join(root, '.claude', 'settings.json'), 'utf8'));
+        settings.enabledPlugins = { [PLUGIN_KEY]: false };
+        writeFileSync(join(root, '.claude', 'settings.json'), JSON.stringify(settings));
+        const file = writeRegistry({ [PLUGIN_KEY]: [{ scope: 'project', projectPath: root, version: '0.2.0' }] });
+        const r = pluginDoctor({ VFKB_BUNDLE_DIR: home }, file);
+        expect(status(r, '.mcp.json')).toBe('ok'); // real init wiring, reported as such
+        expect(status(r, '.claude/settings.json')).toBe('ok');
+        expect(r.checks.find((c) => c.name === 'plugin')).toBeUndefined();
+        expect(JSON.stringify(r.checks)).not.toMatch(/double|alongside|via plugin/i);
+    });
+    it('reports the install entry for THIS root, not another project\'s (and never masks not-installed with a foreign entry)', () => {
+        wirePlugin();
+        const file = writeRegistry({
+            [PLUGIN_KEY]: [
+                { scope: 'project', projectPath: '/somewhere/else', version: '0.1.0' },
+                { scope: 'project', projectPath: root, version: '0.2.0' },
+            ],
+        });
+        const r = pluginDoctor({}, file);
+        expect(r.checks.find((c) => c.name === 'plugin')?.detail).toContain('0.2.0');
+        // only a foreign project's entry exists → the not-installed WARN must NOT be masked
+        const foreignOnly = writeRegistry({ [PLUGIN_KEY]: [{ scope: 'project', projectPath: '/somewhere/else', version: '0.1.0' }] });
+        const r2 = pluginDoctor({}, foreignOnly);
+        expect(status(r2, 'plugin')).toBe('warn');
+    });
+});