@indigoai-us/hq-cli 5.98.2 → 5.99.0

package/dist/lib/doctor/platform.js

@@ -0,0 +1,490 @@
+/**
+ * Host platform detection for `hq doctor`.
+ *
+ * The doctor runs live checks against the agent runtime it is embedded in, so it
+ * has to know which host launched it. This module answers that question and,
+ * crucially, records the *evidence* behind every verdict so the report can show
+ * its work rather than assert a bare label.
+ *
+ * ## Why this is the project's highest-risk piece
+ *
+ * `personal-context.md` and `core/docs/hq/HOOKS-NOT-FIRING.md` document that the
+ * Claude Code **app** and **SDK** runtimes do not dispatch command hooks at all,
+ * even when `.claude/settings.json` is present and correct. The terminal **CLI**
+ * does dispatch them. So the single most important distinction this module can
+ * get wrong is calling an app/SDK host a CLI host: that would let a runtime with
+ * *zero* live hook enforcement report PASS on hook checks — the exact false
+ * confidence the whole tool exists to prevent.
+ *
+ * The design therefore treats `claude-code-cli` as the verdict that requires the
+ * strongest, most specific positive evidence, and treats ambiguity as `unknown`
+ * rather than guessing:
+ *
+ *   - `claude-code-cli` is asserted only on a positive CLI signal
+ *     (`CLAUDE_CODE_ENTRYPOINT=cli`) with no competing strong signal.
+ *   - `CLAUDECODE=1` alone is *weak*: the CLI, app, and SDK all set it, so on its
+ *     own it proves only "some Claude Code host", never which one. Weak-only
+ *     evidence resolves to `unknown`, never to CLI.
+ *   - Conflicting strong signals (e.g. `entrypoint=cli` while a Claude desktop
+ *     bundle id is also present) resolve to `unknown`, because a host that looks
+ *     like two things at once cannot be trusted to be the safe one.
+ *   - `unknown` is a first-class, safe outcome: the doctor still runs every
+ *     platform-independent check and marks host-specific checks UNKNOWN (see
+ *     {@link hostSpecificChecksTrustworthy}) rather than PASS.
+ *
+ * Residual limitation, stated honestly: if a non-dispatching host set
+ * `CLAUDE_CODE_ENTRYPOINT=cli` and left behind no other distinguishing signal,
+ * this module would report `claude-code-cli`. That gap is closed downstream by
+ * the runtime probe (US-006), which reads the policy-trigger ledger to confirm
+ * hooks *actually fired*, independent of the label here. Platform detection is a
+ * strong hint; the ledger is the proof.
+ *
+ * ## Signals, not a single variable
+ *
+ * Detection combines environment signals with process ancestry, mirroring the
+ * canonical shell detector `core/scripts/lib/detect-codex.sh`. Every signal is
+ * collected by its own small, individually testable function; {@link
+ * detectPlatform} composes them and applies the resolution rules above.
+ *
+ * The whole path is cheap (env reads plus at most one `ps` snapshot) and never
+ * launches an agent binary, satisfying the startup-latency budget.
+ */
+import * as childProcess from "node:child_process";
+/** Every platform the doctor can report, including the `unknown` fallback. */
+export const PLATFORMS = [
+    "claude-code-cli",
+    "claude-code-app",
+    "claude-code-sdk",
+    "codex",
+    "grok",
+    "unknown",
+];
+// --- environment signal collectors --------------------------------------------
+//
+// Each collector is exported and takes an explicit environment so a single
+// signal can be exercised in isolation with a stubbed environment.
+/**
+ * The `CLAUDE_CODE_ENTRYPOINT` signal — the one variable that distinguishes the
+ * Claude Code CLI from the SDK. `cli` ⇒ CLI; anything starting `sdk` (e.g.
+ * `sdk-ts`, `sdk-py`, `sdk-cli`) ⇒ SDK. Any other non-empty value is a Claude
+ * Code host of a variant we do not map, recorded as a *weak* Claude-app-leaning
+ * hint that on its own resolves to `unknown` rather than a CLI false positive.
+ */
+export function entrypointEvidence(env) {
+    const raw = env.CLAUDE_CODE_ENTRYPOINT;
+    if (!raw)
+        return null;
+    const value = raw.trim();
+    if (value === "")
+        return null;
+    const key = "env.CLAUDE_CODE_ENTRYPOINT";
+    const detail = `CLAUDE_CODE_ENTRYPOINT=${value}`;
+    if (value === "cli") {
+        return { key, detail, points: "claude-code-cli", strength: "strong" };
+    }
+    if (/^sdk/i.test(value)) {
+        return { key, detail, points: "claude-code-sdk", strength: "strong" };
+    }
+    // A recognized Claude Code host of an unmapped variant. Deliberately weak and
+    // pointed at the app: we will not let it masquerade as the CLI, and if it is
+    // the only evidence the verdict falls to `unknown`.
+    return { key, detail, points: "claude-code-app", strength: "weak" };
+}
+/**
+ * The `CLAUDECODE=1` signal. Set by the CLI, app, and SDK alike, so it proves
+ * only that some Claude Code host is present — never which one. Always weak, and
+ * pointed at the app so it can never, on its own, promote a run to CLI.
+ */
+export function claudeCodeFlagEvidence(env) {
+    const raw = env.CLAUDECODE;
+    if (!raw || raw.trim() === "" || raw.trim() === "0")
+        return null;
+    return {
+        key: "env.CLAUDECODE",
+        detail: `CLAUDECODE=${raw.trim()}`,
+        points: "claude-code-app",
+        strength: "weak",
+    };
+}
+/**
+ * The macOS `__CFBundleIdentifier` signal — the bundle of the app that launched
+ * this process, set when a GUI application spawns it. Mirrors the Codex check in
+ * `detect-codex.sh`. A terminal emulator sets its own bundle id (e.g.
+ * `com.googlecode.iterm2`), so this fires only under a real desktop host.
+ */
+export function bundleIdEvidence(env) {
+    const raw = env.__CFBundleIdentifier;
+    if (!raw)
+        return null;
+    const id = raw.trim();
+    if (id === "")
+        return null;
+    const key = "env.__CFBundleIdentifier";
+    const detail = `__CFBundleIdentifier=${id}`;
+    if (id === "com.openai.codex") {
+        return { key, detail, points: "codex", strength: "strong" };
+    }
+    if (/grok|(?:^|\.)x\.ai(?:\.|$)|com\.xai/i.test(id)) {
+        return { key, detail, points: "grok", strength: "strong" };
+    }
+    if (looksLikeClaudeDesktopBundle(id)) {
+        return { key, detail, points: "claude-code-app", strength: "strong" };
+    }
+    return null;
+}
+/**
+ * A Claude *desktop app* bundle id — an Anthropic-owned bundle that names Claude.
+ * Kept deliberately narrow so a terminal or unrelated app never matches: the
+ * bundle must be under an Anthropic/Claude namespace, not merely mention the
+ * word.
+ */
+function looksLikeClaudeDesktopBundle(id) {
+    const lower = id.toLowerCase();
+    const anthropicClaude = lower.startsWith("com.anthropic.") && lower.includes("claude");
+    const claudeDesktop = lower.includes("claude") && lower.includes("desktop");
+    return anthropicClaude || claudeDesktop;
+}
+/**
+ * Codex runtime environment variables, kept in parity with the canonical shell
+ * detector `core/scripts/lib/detect-codex.sh`. Presence of any is a strong Codex
+ * signal. One evidence entry is produced per variable found so a single Codex
+ * signal can be tested in isolation.
+ */
+export const CODEX_ENV_VARS = [
+    "CODEX_SANDBOX",
+    "CODEX_SESSION_ID",
+    "CODEX_EXECUTION_ID",
+    "CODEX_AGENT_ID",
+    "CODEX_THREAD_ID",
+    "CODEX_SHELL",
+    "CODEX_CI",
+    "CODEX_INTERNAL_ORIGINATOR_OVERRIDE",
+    "OPENAI_CODEX",
+];
+/** Every Codex environment signal present in `env`, one entry per variable. */
+export function codexEnvEvidence(env) {
+    const found = [];
+    for (const name of CODEX_ENV_VARS) {
+        const raw = env[name];
+        if (raw === undefined || raw.trim() === "")
+            continue;
+        found.push({
+            key: `env.${name}`,
+            detail: `${name} is set`,
+            points: "codex",
+            strength: "strong",
+        });
+    }
+    return found;
+}
+/**
+ * Grok runtime environment variables. Restricted to variables the Grok host
+ * exports into the session (a session id, its workspace root) — HQ's own Grok
+ * *launcher* variables (`GROK_BIN`, `GROK_CONFIG`, `XAI_API_KEY`, …) are
+ * excluded on purpose: those can be set inside a Claude or Codex session that is
+ * merely preparing to launch Grok, and treating them as "we are running under
+ * Grok" would be a false positive.
+ */
+export const GROK_ENV_VARS = ["GROK_SESSION_ID", "GROK_WORKSPACE_ROOT"];
+/** Every Grok environment signal present in `env`, one entry per variable. */
+export function grokEnvEvidence(env) {
+    const found = [];
+    for (const name of GROK_ENV_VARS) {
+        const raw = env[name];
+        if (raw === undefined || raw.trim() === "")
+            continue;
+        found.push({
+            key: `env.${name}`,
+            detail: `${name} is set`,
+            points: "grok",
+            strength: "strong",
+        });
+    }
+    return found;
+}
+// --- process ancestry signal --------------------------------------------------
+/**
+ * Match an ancestor process's command against a platform's known binary names.
+ * `codex`/`codex-*`/`Codex*` ⇒ Codex, `grok`/`grok-*`/`Grok*` ⇒ Grok — the same
+ * name families `detect-codex.sh` walks for. A Codex/Grok ancestor is a strong
+ * signal because those runtimes launch a distinctly-named binary.
+ *
+ * The Claude CLI is a Node application whose process is frequently reported as
+ * `node`, so a Claude ancestor cannot be matched reliably by name; Claude relies
+ * on its environment signals instead, and this function does not guess it.
+ */
+export function ancestryEvidence(ancestors) {
+    const found = [];
+    for (const ancestor of ancestors) {
+        const platform = classifyAncestorCommand(ancestor.command);
+        if (!platform)
+            continue;
+        found.push({
+            key: "proc.ancestor",
+            detail: `ancestor process ${basename(ancestor.command)} (pid ${ancestor.pid})`,
+            points: platform,
+            strength: "strong",
+        });
+    }
+    return found;
+}
+function classifyAncestorCommand(command) {
+    const exe = basename(command);
+    if (/^codex(-.*)?$/i.test(exe))
+        return "codex";
+    if (/^grok(-.*)?$/i.test(exe))
+        return "grok";
+    return null;
+}
+function basename(command) {
+    const trimmed = command.trim();
+    // `ps` may report a full path and/or trailing arguments; take the first token
+    // then its path basename.
+    const firstToken = trimmed.split(/\s+/)[0] ?? trimmed;
+    const parts = firstToken.split("/");
+    return parts[parts.length - 1] || firstToken;
+}
+/** Default hop bound when walking the ancestor chain. */
+const DEFAULT_MAX_HOPS = 20;
+/** Wall-clock bound for the single `ps` snapshot, keeping startup fast. */
+const PS_TIMEOUT_MS = 250;
+/** The one command this module ever launches to read process ancestry. */
+export const PS_COMMAND = "ps";
+/** `ps` arguments: every process as `pid ppid comm`, header-suppressed. */
+export const PS_ARGS = ["-Ao", "pid=,ppid=,comm="];
+/**
+ * Read this process's ancestor chain (nearest parent first) by taking one `ps`
+ * snapshot of the process table and walking parent pointers upward. A single
+ * spawn — never per-hop — keeps the cost to a few milliseconds, and it launches
+ * only `ps`, never an agent binary. Fails closed (returns `[]`) if `ps` is
+ * unavailable or its output cannot be parsed, so detection degrades to
+ * environment signals rather than throwing.
+ */
+export function readProcessAncestry(options = {}) {
+    const startPid = options.pid ?? process.pid;
+    const maxHops = options.maxHops ?? DEFAULT_MAX_HOPS;
+    const spawner = options.spawner ?? defaultPsSpawner;
+    const out = spawner(PS_COMMAND, PS_ARGS);
+    if (!out)
+        return [];
+    const table = parseProcessTable(out);
+    const ancestors = [];
+    const seen = new Set();
+    let current = table.get(startPid);
+    let hops = 0;
+    while (current && hops < maxHops) {
+        const parentPid = current.ppid;
+        if (parentPid <= 1 || seen.has(parentPid))
+            break;
+        seen.add(parentPid);
+        const parent = table.get(parentPid);
+        if (!parent)
+            break;
+        ancestors.push({ pid: parentPid, command: parent.command });
+        current = parent;
+        hops += 1;
+    }
+    return ancestors;
+}
+function parseProcessTable(psOutput) {
+    const table = new Map();
+    for (const line of psOutput.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "")
+            continue;
+        // `pid ppid comm...` — comm may contain spaces (a full path), so split only
+        // the first two numeric columns off and keep the remainder as the command.
+        const match = /^(\d+)\s+(\d+)\s+(.*)$/.exec(trimmed);
+        if (!match)
+            continue;
+        const pid = Number.parseInt(match[1], 10);
+        const ppid = Number.parseInt(match[2], 10);
+        if (Number.isNaN(pid) || Number.isNaN(ppid))
+            continue;
+        table.set(pid, { ppid, command: match[3] });
+    }
+    return table;
+}
+/** The default spawner. The only place this module launches a process. */
+function defaultPsSpawner(command, args) {
+    try {
+        const result = childProcess.spawnSync(command, [...args], {
+            encoding: "utf8",
+            timeout: PS_TIMEOUT_MS,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        if (result.error ||
+            result.status !== 0 ||
+            typeof result.stdout !== "string") {
+            return null;
+        }
+        return result.stdout;
+    }
+    catch {
+        return null;
+    }
+}
+// --- composition and resolution -----------------------------------------------
+/**
+ * Collect the environment signals, in a stable order: entrypoint, the Claude
+ * flag, bundle id, Codex vars, then Grok vars. Process ancestry is collected
+ * separately (and lazily) by {@link detectPlatform}.
+ */
+export function collectEnvEvidence(env) {
+    const evidence = [];
+    const entrypoint = entrypointEvidence(env);
+    if (entrypoint)
+        evidence.push(entrypoint);
+    const flag = claudeCodeFlagEvidence(env);
+    if (flag)
+        evidence.push(flag);
+    const bundle = bundleIdEvidence(env);
+    if (bundle)
+        evidence.push(bundle);
+    evidence.push(...codexEnvEvidence(env));
+    evidence.push(...grokEnvEvidence(env));
+    return evidence;
+}
+/**
+ * Collect every signal from an environment and an explicit ancestor chain, in a
+ * stable order: environment signals first, then process ancestry. Exposed for
+ * callers that already hold an ancestor chain and want the full combined view.
+ */
+export function collectPlatformEvidence(env, ancestors) {
+    return [...collectEnvEvidence(env), ...ancestryEvidence(ancestors)];
+}
+/** The distinct platforms with a `strong` signal in an evidence list. */
+function strongPlatformsOf(evidence) {
+    return new Set(evidence.filter((e) => e.strength === "strong").map((e) => e.points));
+}
+/**
+ * Detect the host platform from environment signals and process ancestry, and
+ * return the verdict together with the evidence that produced it.
+ *
+ * Resolution rules (see the module header for the safety rationale):
+ *   1. If exactly one platform has strong evidence, that platform wins.
+ *   2. If more than one platform has strong evidence, the verdict is `unknown`
+ *      (a host that looks like two things cannot be trusted to be the safe one).
+ *   3. With no strong evidence, weak signals never establish a platform — the
+ *      verdict is `unknown`, which keeps a bare `CLAUDECODE=1` from being read
+ *      as the CLI.
+ *
+ * Process ancestry is consulted **lazily**: when the environment already yields
+ * exactly one strong platform, or a genuine strong conflict, the ancestor chain
+ * cannot safely change the answer, so it is not read at all. This makes the
+ * common case (a dispositive env signal) spawn no process whatsoever, and limits
+ * the one `ps` snapshot to the cases where env signals are silent and ancestry
+ * is the only remaining evidence.
+ */
+export function detectPlatform(options = {}) {
+    const env = options.env ?? process.env;
+    const readAncestry = options.ancestry ?? readProcessAncestry;
+    const envEvidence = collectEnvEvidence(env);
+    const envStrong = strongPlatformsOf(envEvidence);
+    // A single strong env signal, or a genuine env conflict, is already decisive;
+    // reading process ancestry cannot safely override it, so skip the ps spawn.
+    if (envStrong.size >= 1) {
+        return resolveVerdict(envEvidence);
+    }
+    // Env signals are silent or only weak — consult process ancestry for a
+    // stronger signal (e.g. a `codex`/`grok` binary in the parent chain).
+    const ancestors = readAncestry();
+    const evidence = [...envEvidence, ...ancestryEvidence(ancestors)];
+    return resolveVerdict(evidence);
+}
+/** Apply the resolution rules to a fully-collected evidence list. */
+function resolveVerdict(evidence) {
+    const strong = evidence.filter((e) => e.strength === "strong");
+    const strongPlatforms = new Set(strong.map((e) => e.points));
+    if (strongPlatforms.size === 1) {
+        const [platform] = [...strongPlatforms];
+        const decidedBy = strong.map((e) => e.key);
+        return {
+            platform,
+            evidence,
+            decidedBy,
+            reason: `Resolved to ${platformLabel(platform)} from ${describeKeys(decidedBy)}.`,
+        };
+    }
+    if (strongPlatforms.size > 1) {
+        const names = [...strongPlatforms].map(platformLabel).join(", ");
+        return {
+            platform: "unknown",
+            evidence,
+            decidedBy: [],
+            reason: `Conflicting strong signals for ${names}; cannot safely pick one, so reporting unknown.`,
+        };
+    }
+    if (evidence.length > 0) {
+        return {
+            platform: "unknown",
+            evidence,
+            decidedBy: [],
+            reason: "Only weak or ambiguous signals were found (e.g. CLAUDECODE is shared by the CLI, app, and SDK), so the specific host cannot be established; reporting unknown rather than a possibly-false verdict.",
+        };
+    }
+    return {
+        platform: "unknown",
+        evidence,
+        decidedBy: [],
+        reason: "No recognizable platform signals were found in the environment or process ancestry.",
+    };
+}
+// --- consumer-facing helpers --------------------------------------------------
+const PLATFORM_LABELS = {
+    "claude-code-cli": "Claude Code (CLI)",
+    "claude-code-app": "Claude Code (app)",
+    "claude-code-sdk": "Claude Code (SDK)",
+    codex: "Codex",
+    grok: "Grok",
+    unknown: "unknown",
+};
+/** A human-readable label for a platform, for text and report output. */
+export function platformLabel(platform) {
+    return PLATFORM_LABELS[platform];
+}
+/**
+ * Whether host-specific *live* checks can be trusted to report PASS on this
+ * platform. False for `unknown`: a check that verifies live behavior on the
+ * detected host has no trustworthy host to verify against when the host is
+ * unknown, and must report UNKNOWN instead of PASS. This is the single source of
+ * truth the runtime tier (US-006) keys its UNKNOWN-not-PASS behavior off.
+ */
+export function hostSpecificChecksTrustworthy(platform) {
+    return platform !== "unknown";
+}
+/**
+ * The status a host-specific check must use when the platform is unknown —
+ * always {@link DoctorStatus} `UNKNOWN`, never PASS. Exposed so consumers share
+ * one honest answer rather than each re-deriving it.
+ */
+export function unknownPlatformCheckStatus() {
+    return "UNKNOWN";
+}
+/**
+ * Render a detection as plain text lines for the default report: the labelled
+ * verdict, the reason, and each piece of evidence. US-015 owns the surrounding
+ * layout, colour, and `--json`; this is a self-contained, colour-free block it
+ * can drop in.
+ */
+export function formatPlatformLines(detection) {
+    const lines = [`Platform: ${platformLabel(detection.platform)}`];
+    lines.push(`  ${detection.reason}`);
+    if (detection.evidence.length === 0) {
+        lines.push("  Evidence: none");
+        return lines;
+    }
+    lines.push("  Evidence:");
+    for (const item of detection.evidence) {
+        const decided = detection.decidedBy.includes(item.key) ? " (decisive)" : "";
+        lines.push(`    - [${item.strength}] ${item.detail} → ${platformLabel(item.points)}${decided}`);
+    }
+    return lines;
+}
+function describeKeys(keys) {
+    if (keys.length === 0)
+        return "no signals";
+    const unique = [...new Set(keys)];
+    return unique.join(", ");
+}
+//# sourceMappingURL=platform.js.map

package/dist/lib/doctor/registry.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The doctor engine — an ordered set of check families — and the first family
+ * (hooks).
+ *
+ * The engine is deliberately ignorant of any specific family: `register`
+ * accepts any object implementing {@link CheckFamily}, and `run` iterates them
+ * generically. A new family (vault, sync, MCP, secrets, qmd freshness, …) is
+ * added by registering it — never by editing this class — which is exactly the
+ * property US-002 requires and later stories rely on.
+ *
+ * The hooks family here is intentionally a skeleton: it establishes the family
+ * so the wiring/parity/runtime checks (US-004+) have somewhere to live, and
+ * reports only the presence and validity of `.claude/settings.json`. Those
+ * later stories add per-item results to this family without touching the engine.
+ */
+import type { CheckContext, CheckFamily, FamilyRun } from "./types.js";
+/**
+ * An ordered, id-keyed set of check families. Registration order is preserved
+ * (Map iteration order), and re-registering an id replaces the family in place
+ * rather than appending a duplicate.
+ */
+export declare class DoctorRegistry {
+    private readonly familiesById;
+    /** Register a family. Re-registering the same id replaces it, keeping order. */
+    register(family: CheckFamily): void;
+    /** The registered families, in registration order. */
+    families(): CheckFamily[];
+    /** Whether a family with this id is registered. */
+    has(id: string): boolean;
+    /** Run every family in order and collect grouped results. */
+    run(context: CheckContext): Promise<FamilyRun[]>;
+}
+/** The id of the hooks family — the first, and for now only, check family. */
+export declare const HOOKS_FAMILY_ID = "hooks";
+/**
+ * The hooks check family. US-002 shipped the skeleton (Claude settings presence
+ * and validity). US-005 adds the Codex and Grok wiring/parity tiers, which run
+ * for every platform regardless of host. US-004+ extend the Claude tier with the
+ * full settings/registration wiring checks. Each tier appends its own results;
+ * the engine (DoctorRegistry) is untouched.
+ */
+export declare const hooksFamily: CheckFamily;
+/**
+ * Build a registry pre-loaded with the default families. Hooks is the first
+ * family; later families are registered here as they are implemented, each
+ * one line, with no engine change.
+ */
+export declare function createDefaultRegistry(): DoctorRegistry;
+//# sourceMappingURL=registry.d.ts.map