@mycompbox/compbox-cli 1.13.0

package/commands/doctor.d.ts

@@ -0,0 +1,136 @@
+/**
+ * `compbox doctor` — verify the local setup end-to-end.
+ *
+ * Runs a series of independent checks, each printed with a clear
+ * PASS / FAIL / SKIP and a concrete remediation on failure:
+ *   1. Local config present (central URL + token).
+ *   2. Central API reachable over the network.
+ *   3. Token authenticates (GET /auth/me returns an identity).
+ *   4. Attribution: a user-scoped write resolves to the expected user id.
+ *   5. Machine paired — the stored machine token resolves against central
+ *      (reported present/valid; the token value is NEVER printed).
+ *   6. MCP config written at the expected path (verifies the WRITTEN config
+ *      file, not a locally installed MCP binary — the server auto-installs via
+ *      `npx` on first use).
+ *   6.5 Central target — which central the MCP writes to (its API_BASE_URL).
+ *      WARN-level (never fails): warns when it is a local/loopback endpoint or
+ *      differs from the logged-in central, so work is never silently pointed at
+ *      localhost instead of the cloud. The API token is never printed.
+ *   6.7 MCP launch target — the written entry must actually be launchable
+ *      (ENG-141): `node` entries must point at a bundle that exists on disk
+ *      and answers a short startup probe (hard 5s timeout so doctor can never
+ *      hang — WARN on timeout); `npx` entries resolve from registry.npmjs.org
+ *      on first use, so there is nothing local to verify.
+ *   7. AI mode configured (keychain key present, or subscription acknowledged).
+ *   8. macOS only — the Homebrew-managed service is running (best-effort; skips
+ *      gracefully when `brew` is not on PATH).
+ *   9. pxpipe token proxy — reachable when enabled (SKIP when disabled). Agents
+ *      fall back to direct calls if it is down, so this never hard-fails setup.
+ *
+ * Exits non-zero if any non-skipped check fails so it is usable in scripts.
+ */
+import { Command } from 'commander';
+import type { CompboxConfig } from '../utils/config-store.js';
+import type { AgentRuntimeProbe } from '../utils/claude-runtime.js';
+import type { McpConfigStatus } from '../utils/mcp-config-writer.js';
+export interface CheckResult {
+    name: string;
+    passed: boolean;
+    detail: string;
+    /** Skipped checks are informational and never count as a failure. */
+    skipped?: boolean;
+    /**
+     * WARN-level checks surface a concern (e.g. writing to a localhost central)
+     * without failing the run. Like skipped checks, they never count as a failure
+     * or affect the exit code — they exist to keep the user informed.
+     */
+    warning?: boolean;
+}
+/**
+ * Compare two central URLs for equivalence so trivial formatting differences
+ * don't trip the central-target mismatch warning. Normalizes via WHATWG
+ * `new URL(u).href` (lowercases scheme/host, drops default ports such as
+ * `:443` for https and `:80` for http), falling back to plain string
+ * normalization for values that don't parse as URLs, then ignores trailing
+ * slashes.
+ *
+ * Intentionally NOT tolerant of http↔https or path differences (e.g. an
+ * `/api` suffix): those point at genuinely different targets, so they should
+ * still trigger the mismatch WARN.
+ */
+export declare function sameCentralUrl(a: string, b: string): boolean;
+/**
+ * Check 6.5: Central target — which central the MCP actually writes to.
+ * Uses the read-only API_BASE_URL from the written MCP entry (never the
+ * token). WARN-level only: localhost is valid in dev, so we surface — never
+ * block. Warns when the MCP writes to a local/loopback endpoint, OR when it
+ * targets a different central than the one this machine logged into.
+ * Extracted (and exported) so the WARN semantics are unit-testable.
+ */
+export declare function centralTargetCheck(mcpStatus: Pick<McpConfigStatus, 'entryPresent' | 'apiBaseUrl'>, loggedInUrl: string | undefined): CheckResult;
+/**
+ * Count hard failures: skipped checks are informational and WARN-level checks
+ * (e.g. a localhost central target) never fail the run or affect the exit
+ * code. Extracted (and exported) so this exclusion is unit-testable.
+ */
+export declare function countFailures(results: CheckResult[]): number;
+/**
+ * Hard upper bound for the launch-target startup probe. The probe must never
+ * hang `doctor`: after this many milliseconds the child is killed and the
+ * check reports WARN (not FAIL — a slow machine is not a broken setup).
+ */
+export declare const LAUNCH_PROBE_TIMEOUT_MS = 5000;
+/** Outcome of spawning the configured launch target (see probeLaunchTarget). */
+export interface LaunchProbeResult {
+    status: 'answered' | 'timeout' | 'error';
+    /** Populated for `error`: why the target failed to start. */
+    detail?: string;
+}
+export type LaunchProbe = (command: string, args: string[]) => Promise<LaunchProbeResult>;
+/**
+ * Spawn the configured MCP launch target and wait for its startup banner.
+ * The server logs `… started (stdio transport)` to stderr once the stdio
+ * transport is connected, so ANY output on stderr/stdout counts as an answer
+ * — the probe cares that the process starts, not what it says. Runs with a
+ * dummy API_TOKEN (env validation happens before the banner) pointing at an
+ * unroutable loopback port so the probe can never write to a real central.
+ * The child is always killed, and `timeoutMs` (default
+ * LAUNCH_PROBE_TIMEOUT_MS) guarantees the probe cannot hang.
+ */
+export declare function probeLaunchTarget(command: string, args: string[], timeoutMs?: number): Promise<LaunchProbeResult>;
+/**
+ * Check 6.7: MCP launch target — the entry `configure` wrote must actually be
+ * launchable (ENG-141). Semantics:
+ *   - `node <bundle>`: FAIL when the bundle file is missing (broken install)
+ *     or crashes on startup; WARN when it exists but does not answer within
+ *     LAUNCH_PROBE_TIMEOUT_MS; PASS when it answers the startup probe.
+ *   - `npx …`: nothing installed locally to verify — PASS with a note that
+ *     the package resolves from registry.npmjs.org on first use.
+ *   - No entry / no command / custom override command: SKIP (informational).
+ * Extracted (and exported) with injectable fs/spawn deps so every branch is
+ * unit-testable without touching the real filesystem or spawning processes.
+ */
+export declare function launchTargetCheck(mcpStatus: Pick<McpConfigStatus, 'entryPresent' | 'command' | 'args'>, deps?: {
+    fileExists?: (path: string) => boolean;
+    probe?: LaunchProbe;
+}): Promise<CheckResult>;
+/** A zero-arg agent-runtime probe (matches probeAgentRuntime's default call). */
+export type AgentRuntimeProbeFn = () => Promise<AgentRuntimeProbe>;
+/**
+ * Check 7.5: Agent runtime (claude CLI) — only meaningful in
+ * `claude-subscription` mode, where the `compbox run` daemon must be able to
+ * spawn the local `claude` binary (ENG-135). Semantics:
+ *   - api-key mode (or unset): SKIP — no `claude` needed, so this never
+ *     affects the exit code.
+ *   - claude-subscription + probe `ok`: PASS, echoing the version.
+ *   - claude-subscription + probe `not-found`/`error`: FAIL with a remediation
+ *     that lists the searched install locations (WELL_KNOWN_DIRS /
+ *     claudeNotFoundMessage), the install link, and a note to re-run doctor.
+ * The probe is injectable (defaults to ENG-135 probeAgentRuntime) so every
+ * branch is unit-testable without spawning a real `claude`.
+ */
+export declare function agentRuntimeCheck(config: Pick<CompboxConfig, 'aiMode'>, deps?: {
+    probe?: AgentRuntimeProbeFn;
+}): Promise<CheckResult>;
+export declare const doctorCommand: Command;
+//# sourceMappingURL=doctor.d.ts.map

package/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAM9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAWpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAQrE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAY5D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,IAAI,CAAC,eAAe,EAAE,cAAc,GAAG,YAAY,CAAC,EAC/D,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,WAAW,CA0Cb;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC;IACzC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,WAAW,GAAG,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEhC;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,GAAE,MAAgC,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CA8C5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,IAAI,CAAC,eAAe,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC,EACrE,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAO,GACzE,OAAO,CAAC,WAAW,CAAC,CAwEtB;AAwED,iFAAiF;AACjF,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,EACrC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAAO,GACzC,OAAO,CAAC,WAAW,CAAC,CAwCtB;AAED,eAAO,MAAM,aAAa,SAsOtB,CAAC"}