@indigoai-us/hq-cli 5.98.3 → 5.99.1

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

@@ -0,0 +1,244 @@
+/**
+ * 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 type { DoctorStatus } from "./types.js";
+/** Every platform the doctor can report, including the `unknown` fallback. */
+export declare const PLATFORMS: readonly ["claude-code-cli", "claude-code-app", "claude-code-sdk", "codex", "grok", "unknown"];
+/** A detected host platform. Closed union derived from {@link PLATFORMS}. */
+export type Platform = (typeof PLATFORMS)[number];
+/**
+ * The platforms a signal can positively point at. `unknown` is never the target
+ * of a signal — it is the verdict when no platform is positively established.
+ */
+export type DetectablePlatform = Exclude<Platform, "unknown">;
+/**
+ * How dispositive a signal is:
+ *   - `strong`: on its own, identifies a specific platform (e.g.
+ *     `CLAUDE_CODE_ENTRYPOINT=cli`, a Codex runtime env var, a `codex` ancestor).
+ *   - `weak`: corroborating but not variant-specific (e.g. `CLAUDECODE=1`, which
+ *     is shared by the CLI, app, and SDK).
+ */
+export type SignalStrength = "strong" | "weak";
+/** One observed signal and the platform it points at. */
+export interface PlatformEvidence {
+    /** Stable machine key for the signal, e.g. `env.CLAUDE_CODE_ENTRYPOINT`. */
+    key: string;
+    /** Human-readable detail, e.g. `CLAUDE_CODE_ENTRYPOINT=cli`. Never a secret. */
+    detail: string;
+    /** The platform this signal supports. */
+    points: DetectablePlatform;
+    /** How dispositive the signal is. */
+    strength: SignalStrength;
+}
+/** The result of a detection: the verdict plus the evidence behind it. */
+export interface PlatformDetection {
+    /** The resolved platform, or `unknown` when none could be established. */
+    platform: Platform;
+    /** Every signal observed, in collection order — the report shows its work. */
+    evidence: PlatformEvidence[];
+    /** The evidence keys that determined the verdict; empty when `unknown`. */
+    decidedBy: string[];
+    /** One-line, plain-language explanation of why this verdict was reached. */
+    reason: string;
+}
+/** One ancestor process in the chain from this process up toward init. */
+export interface AncestorProcess {
+    /** Process id. */
+    pid: number;
+    /** Executable command (path or name) as reported by `ps`. */
+    command: string;
+}
+/** Reads this process's ancestor chain, nearest parent first. Injectable. */
+export type AncestryReader = () => AncestorProcess[];
+/** Options for {@link detectPlatform}. All are injectable so runs are testable. */
+export interface DetectPlatformOptions {
+    /** Environment to read. Default: `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Ancestor-process reader. Default: {@link readProcessAncestry}. */
+    ancestry?: AncestryReader;
+}
+/**
+ * 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 declare function entrypointEvidence(env: NodeJS.ProcessEnv): PlatformEvidence | null;
+/**
+ * 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 declare function claudeCodeFlagEvidence(env: NodeJS.ProcessEnv): PlatformEvidence | null;
+/**
+ * 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 declare function bundleIdEvidence(env: NodeJS.ProcessEnv): PlatformEvidence | null;
+/**
+ * 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 declare const CODEX_ENV_VARS: readonly ["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 declare function codexEnvEvidence(env: NodeJS.ProcessEnv): PlatformEvidence[];
+/**
+ * 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 declare const GROK_ENV_VARS: readonly ["GROK_SESSION_ID", "GROK_WORKSPACE_ROOT"];
+/** Every Grok environment signal present in `env`, one entry per variable. */
+export declare function grokEnvEvidence(env: NodeJS.ProcessEnv): PlatformEvidence[];
+/**
+ * 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 declare function ancestryEvidence(ancestors: AncestorProcess[]): PlatformEvidence[];
+/** The one command this module ever launches to read process ancestry. */
+export declare const PS_COMMAND = "ps";
+/** `ps` arguments: every process as `pid ppid comm`, header-suppressed. */
+export declare const PS_ARGS: readonly ["-Ao", "pid=,ppid=,comm="];
+/**
+ * Low-level process-table provider: runs a command and returns its stdout, or
+ * `null` on failure. This is the single seam through which any process is
+ * spawned, so a test can both feed a synthetic table and assert that the only
+ * command ever requested is `ps` — never an agent binary.
+ */
+export type ProcessSpawner = (command: string, args: readonly string[]) => string | null;
+/** Options for {@link readProcessAncestry}. */
+export interface ReadAncestryOptions {
+    /** Process to start from. Default: `process.pid`. */
+    pid?: number;
+    /** Maximum ancestors to walk. Default: {@link DEFAULT_MAX_HOPS}. */
+    maxHops?: number;
+    /** Process-table provider. Default: {@link defaultPsSpawner} (runs `ps`). */
+    spawner?: ProcessSpawner;
+}
+/**
+ * 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 declare function readProcessAncestry(options?: ReadAncestryOptions): AncestorProcess[];
+/**
+ * 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 declare function collectEnvEvidence(env: NodeJS.ProcessEnv): PlatformEvidence[];
+/**
+ * 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 declare function collectPlatformEvidence(env: NodeJS.ProcessEnv, ancestors: AncestorProcess[]): PlatformEvidence[];
+/**
+ * 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 declare function detectPlatform(options?: DetectPlatformOptions): PlatformDetection;
+/** A human-readable label for a platform, for text and report output. */
+export declare function platformLabel(platform: Platform): string;
+/**
+ * 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 declare function hostSpecificChecksTrustworthy(platform: Platform): boolean;
+/**
+ * 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 declare function unknownPlatformCheckStatus(): DoctorStatus;
+/**
+ * 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 declare function formatPlatformLines(detection: PlatformDetection): string[];
+//# sourceMappingURL=platform.d.ts.map