@tpsdev-ai/flair 0.50.0 → 0.51.1

package/dist/lib/doctor-run.js

@@ -0,0 +1,481 @@
+/**
+ * doctor-run.ts — the enumerable install-health runner (flair#1439).
+ *
+ * `flair doctor` and `flair upgrade` used to keep two definitions of
+ * "healthy". Upgrade's success line (`renderVerifiedSummary`) could only
+ * qualify a ✅ by the facts in its signature — version plus launchd — so
+ * every other doctor check was invisible and rendered green. The previous
+ * fix special-cased one known-unhealthy form (launchd detach). That is a
+ * blacklist: the next unmeasured fact (a Codex SessionStart hook 0.49.0
+ * never wrote) printed the same unqualified success marker.
+ *
+ * This module is the single entry point that runs the named install-health
+ * checks. Adding a check to `DOCTOR_CHECK_IDS` automatically widens what
+ * upgrade claims. Success is asserted POSITIVELY: every catalog id must
+ * have been executed and none may have failed. An `unrun` member is never
+ * treated as a pass — if a reachable state cannot produce "unrun ⇒ no ✅",
+ * the enumeration is decorative and we have rebuilt the same guard.
+ *
+ * Skip (N/A) is not unrun. Linux has no launchd; a machine without Codex
+ * does not owe a Codex hook. Those checks execute and return `skip`.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { checkClaudeMdBootstrap, checkSessionStartHook, effectiveFlairUrl, hookCommandIsSilenced, isFlairHookCommand, partitionKeyIds, planAgentIterations, readClientMcpBlock, } from "../doctor-client.js";
+import { hookInstallHint, hookSettingsPath, installHook, SUPPORTED_HARNESSES, } from "../hook-install.js";
+import { isDetached, renderDetachedWarning, } from "./launchd-management.js";
+/**
+ * The catalog. This is the contract upgrade asserts against.
+ *
+ * A new doctor install-health check is added HERE (id + runner). An id
+ * without a runner is emitted as `unrun` and blocks the success marker —
+ * that is the point, not a fallback.
+ *
+ * Flint's six named client-integration checks plus launchd (the previous
+ * special-case, now a catalog member rather than a side channel).
+ */
+export const DOCTOR_CHECK_IDS = [
+    "mcp-block",
+    "flair-url",
+    "claude-md",
+    "session-start-hook",
+    "verified-read",
+    "keys-prune",
+    "launchd-management",
+];
+const MCP_CLIENT_IDS = ["claude-code", "codex", "gemini", "cursor", "antigravity"];
+function result(id, label, status, extra = {}) {
+    return { id, label, status, ...extra };
+}
+function runMcpBlock(ctx) {
+    const id = "mcp-block";
+    const label = "MCP server block";
+    const mcp = ctx.detectedClientIds.filter((c) => MCP_CLIENT_IDS.includes(c));
+    if (mcp.length === 0) {
+        return result(id, label, "skip", { detail: "no MCP client detected" });
+    }
+    const missing = [];
+    for (const clientId of mcp) {
+        const block = readClientMcpBlock(clientId, ctx.homeDir);
+        if (!block.present)
+            missing.push(`${clientId} (${block.configPath})`);
+    }
+    if (missing.length > 0) {
+        return result(id, label, "fail", {
+            detail: `no Flair MCP server configured: ${missing.join(", ")}`,
+            remedy: "flair doctor --fix",
+        });
+    }
+    return result(id, label, "pass", { detail: `configured for ${mcp.join(", ")}` });
+}
+function runFlairUrl(ctx) {
+    const id = "flair-url";
+    const label = "FLAIR_URL";
+    const mcp = ctx.detectedClientIds.filter((c) => MCP_CLIENT_IDS.includes(c));
+    if (mcp.length === 0) {
+        return result(id, label, "skip", { detail: "no MCP client detected" });
+    }
+    // Presence of a working URL (explicit or client-defaulted) is the check.
+    // Unreachable is a doctor warn, not an install-health failure — the
+    // instance probe already covered liveness on the upgrade path.
+    const present = mcp.filter((clientId) => readClientMcpBlock(clientId, ctx.homeDir).present);
+    if (present.length === 0) {
+        return result(id, label, "skip", { detail: "no MCP block present to take a URL from" });
+    }
+    const urls = present.map((clientId) => {
+        const block = readClientMcpBlock(clientId, ctx.homeDir);
+        const eff = effectiveFlairUrl(block);
+        return `${clientId}=${eff.url}${eff.defaulted ? " (client default)" : ""}`;
+    });
+    return result(id, label, "pass", { detail: urls.join(", ") });
+}
+function runClaudeMd(ctx) {
+    const id = "claude-md";
+    const label = "CLAUDE.md bootstrap";
+    if (!ctx.detectedClientIds.includes("claude-code")) {
+        return result(id, label, "skip", { detail: "Claude Code not detected" });
+    }
+    const check = checkClaudeMdBootstrap(ctx.cwd, ctx.homeDir);
+    if (!check.present) {
+        return result(id, label, "fail", {
+            detail: "bootstrap instruction not found",
+            remedy: "flair doctor --fix",
+        });
+    }
+    return result(id, label, "pass", { detail: check.path ?? undefined });
+}
+function runSessionStartHook(ctx) {
+    const id = "session-start-hook";
+    const label = "SessionStart hook";
+    const harnesses = SUPPORTED_HARNESSES.filter((h) => ctx.detectedClientIds.includes(h));
+    if (harnesses.length === 0) {
+        return result(id, label, "skip", { detail: "no hook-capable client detected" });
+    }
+    const missing = [];
+    const loud = [];
+    for (const harness of harnesses) {
+        const path = hookSettingsPath(ctx.homeDir, harness);
+        const hook = checkSessionStartHook(ctx.homeDir, path);
+        if (!hook.present) {
+            missing.push(harness);
+            continue;
+        }
+        if (hook.command && isFlairHookCommand(hook.command) && !hookCommandIsSilenced(hook.command)) {
+            loud.push(harness);
+        }
+    }
+    if (missing.length > 0) {
+        const harness = missing[0];
+        const path = hookSettingsPath(ctx.homeDir, harness);
+        const detail = missing.length === 1
+            ? `SessionStart hook (${harness}): not found in ${path}`
+            : `SessionStart hook: not found for ${missing.join(", ")} (${missing.map((h) => hookSettingsPath(ctx.homeDir, h)).join("; ")})`;
+        return result(id, label, "fail", {
+            detail,
+            remedy: missing.map((h) => hookInstallHint(h)).join(" ; "),
+            missingHarnesses: missing,
+        });
+    }
+    if (loud.length > 0) {
+        const harness = loud[0];
+        return result(id, label, "fail", {
+            detail: `SessionStart hook (${harness}): a failure would print an error on every session`,
+            remedy: hookInstallHint(harness),
+        });
+    }
+    return result(id, label, "pass", {
+        detail: `wired for ${harnesses.join(", ")}`,
+    });
+}
+function runVerifiedRead(ctx) {
+    const id = "verified-read";
+    const label = "per-agent verified-read";
+    if (ctx.keyAgentIds === undefined) {
+        return result(id, label, "skip", { detail: "no keys enumeration in context" });
+    }
+    const plan = planAgentIterations(ctx.keyAgentIds, ctx.agentFlag);
+    if (plan.length === 0) {
+        return result(id, label, "skip", { detail: "no agents to iterate" });
+    }
+    return result(id, label, "pass", { detail: `iterate ${plan.join(", ")}` });
+}
+function runKeysPrune(ctx) {
+    const id = "keys-prune";
+    const label = "keys prune classification";
+    if (!ctx.keysDir) {
+        return result(id, label, "skip", { detail: "no keys dir in context" });
+    }
+    if (!existsSync(ctx.keysDir)) {
+        return result(id, label, "skip", { detail: "keys dir absent" });
+    }
+    const ids = readdirSync(ctx.keysDir)
+        .filter((f) => f.endsWith(".key"))
+        .map((f) => f.replace(/\.key$/, ""));
+    const { agentKeyIds, nodeKeyIds } = partitionKeyIds(ids, ctx.keysDir);
+    return result(id, label, "pass", {
+        detail: `classified ${agentKeyIds.length} agent / ${nodeKeyIds.length} node key(s)`,
+    });
+}
+function runLaunchdManagement(ctx) {
+    const id = "launchd-management";
+    const label = "launchd management";
+    if (!ctx.launchd) {
+        return result(id, label, "skip", { detail: "launchd not observed" });
+    }
+    const m = ctx.launchd;
+    if (isDetached(m)) {
+        return result(id, label, "fail", {
+            detail: m.detail,
+            remedy: m.remedy?.join(" && "),
+            launchd: m,
+        });
+    }
+    if (m.state === "not-applicable" || m.state === "no-service") {
+        return result(id, label, "skip", { detail: m.detail, launchd: m });
+    }
+    return result(id, label, "pass", { detail: m.detail, launchd: m });
+}
+/** Default implementations. An id in DOCTOR_CHECK_IDS missing from this
+ *  list is emitted as `unrun` — that is a reachable incomplete state. */
+export const DOCTOR_CHECKS = [
+    { id: "mcp-block", label: "MCP server block", run: runMcpBlock },
+    { id: "flair-url", label: "FLAIR_URL", run: runFlairUrl },
+    { id: "claude-md", label: "CLAUDE.md bootstrap", run: runClaudeMd },
+    { id: "session-start-hook", label: "SessionStart hook", run: runSessionStartHook },
+    { id: "verified-read", label: "per-agent verified-read", run: runVerifiedRead },
+    { id: "keys-prune", label: "keys prune classification", run: runKeysPrune },
+    { id: "launchd-management", label: "launchd management", run: runLaunchdManagement },
+];
+/**
+ * Run every catalog id. Missing implementations and thrown runners become
+ * `unrun`, never `pass`.
+ */
+export function runDoctorChecks(ctx, opts = {}) {
+    const catalogIds = opts.catalogIds ?? DOCTOR_CHECK_IDS;
+    const defs = new Map((opts.checks ?? DOCTOR_CHECKS).map((c) => [c.id, c]));
+    const results = [];
+    for (const id of catalogIds) {
+        const stub = opts.stubs?.[id];
+        const def = defs.get(id);
+        if (stub) {
+            try {
+                results.push(normalizeResult(id, def?.label ?? id, stub(ctx)));
+            }
+            catch {
+                results.push(unrunResult(id, def?.label ?? id, "check threw before returning"));
+            }
+            continue;
+        }
+        if (!def) {
+            results.push(unrunResult(id, id, "check was not executed — no runner registered"));
+            continue;
+        }
+        try {
+            results.push(normalizeResult(id, def.label, def.run(ctx)));
+        }
+        catch {
+            results.push(unrunResult(id, def.label, "check threw before returning"));
+        }
+    }
+    return summarizeDoctorRunResults(results, catalogIds);
+}
+function normalizeResult(id, label, r) {
+    return { ...r, id, label: r.label || label };
+}
+function unrunResult(id, label, detail) {
+    return { id, label, status: "unrun", detail };
+}
+/**
+ * Positive assertion over an already-collected result list. Any catalog id
+ * absent from `results` is filled in as `unrun` so a partial list cannot
+ * look complete.
+ */
+export function summarizeDoctorRunResults(results, catalogIds = DOCTOR_CHECK_IDS) {
+    const byId = new Map(results.map((r) => [r.id, r]));
+    const complete = catalogIds.map((id) => byId.get(id) ?? unrunResult(id, id, "check was not executed"));
+    const incomplete = complete.some((r) => r.status === "unrun");
+    const failed = complete.some((r) => r.status === "fail");
+    return {
+        results: complete,
+        healthy: catalogIds.length > 0 && !incomplete && !failed,
+        incomplete,
+    };
+}
+/**
+ * The final status line of a successful `flair upgrade`.
+ *
+ * Success is asserted from the enumerated doctor run — never from "facts I
+ * gathered, minus known-bad cases." The unqualified `✅ verified: healthy`
+ * marker is emitted only when `run.healthy` is true. An unrun member, a
+ * failed member, or an empty catalog all withhold it.
+ */
+export function renderVerifiedSummary(version, run, opts) {
+    // `authenticated` is a probe fact, not a doctor-check special case. The
+    // healthy-unverified upgrade branch could not read /HealthDetail; claiming
+    // "authenticated" there contradicts the next line. Default stays true so
+    // the ok path is unchanged.
+    const authed = opts?.authenticated !== false;
+    const facts = `healthy${authed ? ", authenticated" : ""}${version ? `, running ${version}` : ""}`;
+    if (run.healthy) {
+        return { degraded: false, lines: [`✅ verified: ${facts}`] };
+    }
+    const lines = [];
+    const launchdFail = run.results.find((r) => r.id === "launchd-management" && r.status === "fail");
+    if (launchdFail?.launchd && isDetached(launchdFail.launchd)) {
+        lines.push(...renderDetachedWarning(launchdFail.launchd, `upgrade landed (${facts}) but the instance is NOT running under launchd.`));
+    }
+    else if (run.incomplete) {
+        const unrun = run.results.filter((r) => r.status === "unrun");
+        lines.push(`⚠️  upgrade landed (${facts}) but install checks are incomplete — ${unrun.length} check(s) were not run.`);
+    }
+    else {
+        const failed = run.results.filter((r) => r.status === "fail");
+        lines.push(`⚠️  upgrade landed (${facts}) but doctor found ${failed.length} issue${failed.length === 1 ? "" : "s"}.`);
+    }
+    for (const r of run.results) {
+        if (r.status === "unrun") {
+            lines.push(`   UNRUN: ${r.label} — not yet checked (cannot treat as passing)`);
+        }
+        else if (r.status === "fail" && r.id !== "launchd-management") {
+            lines.push(`   ✗ ${r.detail ?? r.label}`);
+            if (r.remedy)
+                lines.push(`   Fix: ${r.remedy}`);
+        }
+    }
+    return { degraded: true, lines };
+}
+/**
+ * Whether upgrade may write a SessionStart hook. Installing something that
+ * executes at every session start is consent-bearing — the flag is the
+ * documented non-interactive consent; a TTY prompt is the interactive one.
+ * Silence (no flag, no TTY) never writes.
+ */
+export function resolveHookInstallConsent(opts) {
+    if (opts.installHooksFlag)
+        return "install";
+    if (opts.interactive && opts.promptAccepted === undefined)
+        return "prompt";
+    if (opts.interactive && opts.promptAccepted)
+        return "install";
+    if (opts.interactive)
+        return "skip-declined";
+    return "skip-noninteractive";
+}
+/**
+ * Interactive upgrade prompt for missing SessionStart hooks.
+ *
+ * Names EVERY missing harness (and its path) before asking. A yes after
+ * this prompt is consent to write each named hook — not an unnamed extra.
+ * Codex-only rationale is attached only when Codex is in the set.
+ */
+export function missingHookPromptLines(missing, homeDir) {
+    const named = missing.length > 0 ? [...missing] : ["codex"];
+    const preamble = [];
+    for (const h of named) {
+        preamble.push(`SessionStart hook (${h}) is not installed at ${hookSettingsPath(homeDir, h)}.`);
+    }
+    if (named.includes("codex")) {
+        preamble.push("Without the Codex hook, memory never bootstraps (no CLAUDE.md alternative on Codex).");
+    }
+    if (named.length > 1) {
+        preamble.push(`A yes installs the hook for ${named.join(" and ")} — each executes at session start.`);
+    }
+    const question = named.length === 1
+        ? "  Install the flair-session-start hook now? [y/N] "
+        : `  Install the flair-session-start hook for ${named.join(" and ")} now? [y/N] `;
+    return { preamble, question };
+}
+/** Plain-language lines when upgrade will not write the hook. */
+export function missingHookWithoutConsentLines(harness, path) {
+    return [
+        `SessionStart hook (${harness}) is not installed at ${path}.`,
+        "This hook runs at every session start — a consent-bearing write, so upgrade will not install it unprompted.",
+        `Install with: flair upgrade --install-hooks`,
+        `           or: ${hookInstallHint(harness)}`,
+    ];
+}
+/** True when the SessionStart-hook check failed because a hook file is missing. */
+export function sessionStartHookMissing(run) {
+    const hook = run.results.find((r) => r.id === "session-start-hook");
+    return hook?.status === "fail" && (hook.missingHarnesses?.length ?? 0) > 0;
+}
+/**
+ * Inputs for a consented `installHook` after upgrade. Prefers the missing
+ * harness's own MCP block, then env, then the provided fallbacks.
+ */
+export function resolveUpgradeHookInstall(homeDir, harness, fallbacks) {
+    const clientId = harness === "codex" ? "codex" : "claude-code";
+    const block = readClientMcpBlock(clientId, homeDir);
+    const agentId = (typeof process.env.FLAIR_AGENT_ID === "string" && process.env.FLAIR_AGENT_ID) ||
+        block.agentId ||
+        fallbacks.agentId;
+    const flairUrl = (typeof process.env.FLAIR_URL === "string" && process.env.FLAIR_URL) ||
+        block.flairUrl ||
+        fallbacks.flairUrl ||
+        (fallbacks.port ? `http://127.0.0.1:${fallbacks.port}` : "http://127.0.0.1:9926");
+    if (!agentId) {
+        return { error: "no agent id known — pass --agent or set FLAIR_AGENT_ID so the hook can be wired" };
+    }
+    return { agentId, flairUrl };
+}
+/**
+ * How many catalog members block doctor / withhold upgrade's ✅.
+ * `fail` and `unrun` both count — an unrun member is never a pass.
+ */
+export function catalogBlockingCount(run) {
+    return run.results.filter((r) => r.status === "fail" || r.status === "unrun").length;
+}
+/**
+ * Found/fixed delta for `flair doctor --fix`. `found` is the pre-fix
+ * catalog blocking count; `fixed` is how many of those cleared after.
+ */
+export function catalogIssueDelta(before, after) {
+    const found = catalogBlockingCount(before);
+    const remaining = catalogBlockingCount(after);
+    return { found, fixed: Math.max(0, found - remaining) };
+}
+/** Compact catalog lines for doctor's Install health section. */
+export function renderCatalogDoctorLines(run) {
+    return run.results.map((r) => {
+        const icon = r.status === "pass" || r.status === "skip" ? "ok" : r.status === "unrun" ? "warn" : "error";
+        const word = r.status === "skip" ? "n/a" : r.status;
+        const detail = r.detail ? ` — ${r.detail}` : "";
+        return { icon, line: `${r.label}: ${word}${detail}` };
+    });
+}
+/**
+ * Consent → write composition for missing SessionStart hooks after a
+ * catalog run. Silence (no flag, not interactive) never creates a hook
+ * file. `--install-hooks` or an accepted prompt writes every named
+ * missing harness via `installHook` (or `writeHook`).
+ *
+ * This is the path `flair upgrade` actually uses. Testing
+ * `resolveHookInstallConsent` alone would stay green if the caller
+ * always wrote anyway.
+ */
+export function applyUpgradeHookConsent(opts) {
+    const homeDir = opts.homeDir;
+    const empty = {
+        run: opts.run,
+        consent: "skip-declined",
+        missing: [],
+        written: [],
+        writes: [],
+        messages: [],
+    };
+    if (!sessionStartHookMissing(opts.run)) {
+        return { ...empty, consent: "install" };
+    }
+    const missing = opts.run.results.find((r) => r.id === "session-start-hook")?.missingHarnesses ?? [];
+    const consent = resolveHookInstallConsent({
+        installHooksFlag: opts.installHooksFlag,
+        interactive: opts.interactive,
+        promptAccepted: opts.promptAccepted,
+    });
+    const prompt = missingHookPromptLines(missing, homeDir);
+    if (consent === "prompt") {
+        return { ...empty, consent, missing, prompt };
+    }
+    if (consent === "install") {
+        const write = opts.writeHook ?? installHook;
+        const writes = [];
+        const written = [];
+        const messages = [];
+        for (const harness of missing) {
+            const inputs = resolveUpgradeHookInstall(homeDir, harness, {
+                port: opts.port,
+                agentId: opts.agentId,
+                flairUrl: opts.flairUrl,
+            });
+            if ("error" in inputs) {
+                messages.push(inputs.error);
+                writes.push({ harness, ok: false, message: inputs.error });
+                continue;
+            }
+            const installed = write({
+                homeDir,
+                harness,
+                agentId: inputs.agentId,
+                flairUrl: inputs.flairUrl,
+            });
+            writes.push({ harness, ok: installed.ok, message: installed.message });
+            messages.push(installed.message);
+            if (installed.ok)
+                written.push(harness);
+        }
+        return {
+            run: runDoctorChecks(opts.ctx),
+            consent,
+            missing,
+            written,
+            writes,
+            messages,
+        };
+    }
+    const messages = [];
+    if (consent === "skip-noninteractive") {
+        for (const harness of missing) {
+            messages.push(...missingHookWithoutConsentLines(harness, hookSettingsPath(homeDir, harness)));
+        }
+    }
+    return { ...empty, consent, missing, messages };
+}

package/dist/lib/launchd-management.js

@@ -300,29 +300,10 @@ export function renderDetachedWarning(m, headline) {
         lines.push(`   Fix: ${m.remedy.join(" && ")}`);
     return lines;
 }
-/**
- * The final status line of a successful `flair upgrade`, given what the probe
- * found AND what launchd is doing.
- *
- * This is the reported defect reduced to a function, on purpose. The bug was
- * never in the probe — `healthy, authenticated, running <version>` was true —
- * it was that those three facts were rendered as an unqualified ✅ while a
- * fourth, unmeasured fact (the instance had been dropped out of its process
- * manager) was the one that mattered. Deciding it here rather than inline in
- * the command means the decision is testable without performing an upgrade,
- * which on the darwin path nothing else can do: no CI lane runs it.
- *
- * The verified facts are still reported in the degraded case. The upgrade DID
- * land, and hiding that would swap one misleading summary for another; what
- * changes is the marker and the sentence around it.
- */
-export function renderVerifiedSummary(version, m) {
-    const facts = `healthy, authenticated${version ? `, running ${version}` : ""}`;
-    if (!isDetached(m)) {
-        return { degraded: false, lines: [`✅ verified: ${facts}`] };
-    }
-    return {
-        degraded: true,
-        lines: renderDetachedWarning(m, `upgrade landed (${facts}) but the instance is NOT running under launchd.`),
-    };
-}
+// renderVerifiedSummary used to live here and qualify ✅ from version +
+// LaunchdManagement alone (flair#1022). That signature was the ceiling on
+// what it could notice — a blacklist of one known-unhealthy form. The
+// enumerated doctor runner in doctor-run.ts is now the source of the
+// success marker (flair#1439). renderDetachedWarning stays: it is the
+// wording for a detached launchd check, used by the runner and by
+// `flair restart`.