@lannguyensi/harness 0.41.0 → 0.42.0

package/dist/io/claude-mcp.d.ts

@@ -0,0 +1,258 @@
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export interface ClaudeMcpExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    /** True iff the failure was a spawn-time ENOENT (the `claude` binary is not resolvable on PATH). */
+    enoent: boolean;
+    /** True iff the call was killed after exceeding the timeout. */
+    timedOut: boolean;
+}
+export interface ClaudeMcpExec {
+    (args: string[], timeoutMs: number): Promise<ClaudeMcpExecResult>;
+}
+export interface ClaudeMcpCallOptions {
+    /** Override the `claude` spawn. Tests inject a fake; default is the real CLI. */
+    exec?: ClaudeMcpExec;
+    /** Per-call timeout in ms. Default {@link DEFAULT_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/** Claude Code's `mcpServers` entry shape: command + optional args/env (matches SettingsMcpServer in generate-settings.ts). */
+export interface ClaudeMcpServerSpec {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+export type AddJsonStatus = "added" | "already-exists" | "invalid-config" | "cli-missing" | "timeout" | "error";
+export interface AddJsonResult {
+    status: AddJsonStatus;
+    message: string;
+    code: number;
+}
+/**
+ * Wrap a value as a single POSIX shell single-quoted token, escaping any
+ * embedded single quote as `'\''`. Used to build the copy-pasteable
+ * `claude mcp add-json ... <json>` fallback commands harness prints when the
+ * CLI is missing or a server is unregistered, so the operator can paste them
+ * verbatim even when a value (e.g. a home path containing an apostrophe, as
+ * projected into grounding-mcp's EVIDENCE_LEDGER_DB) has a single quote.
+ * Harness never executes these strings itself.
+ */
+export declare function posixSingleQuote(value: string): string;
+export declare function addJsonMcpServer(name: string, spec: ClaudeMcpServerSpec, opts?: ClaudeMcpCallOptions): Promise<AddJsonResult>;
+export type RemoveStatus = "removed" | "not-found" | "cli-missing" | "timeout" | "error";
+export interface RemoveResult {
+    status: RemoveStatus;
+    message: string;
+    code: number;
+}
+export declare function removeMcpServer(name: string, opts?: ClaudeMcpCallOptions): Promise<RemoveResult>;
+/**
+ * One `claude mcp remove --scope user <name>` line per name, sorted.
+ * Sibling of `manualAddJsonLines` in `cli/init/interactive.ts` — the
+ * copy-pasteable fallback GC (task 363a6de0) prints when it can't reach
+ * the `claude` CLI (or hits some other non-"removed"/"not-found" outcome)
+ * to deregister a stale, harness-owned server itself. Uses
+ * {@link posixSingleQuote} on the name for the same reason
+ * `manualAddJsonLines` quotes its JSON payload: a server name is an
+ * ordinary token today, but quoting it costs nothing and keeps the line
+ * safe to paste verbatim regardless. Harness never executes these strings
+ * itself.
+ */
+export declare function manualRemoveLines(names: readonly string[]): string[];
+export type GetStatus = "found" | "not-found" | "cli-missing" | "timeout";
+export interface GetResult {
+    status: GetStatus;
+    raw: string;
+    code: number;
+}
+export declare function getMcpServer(name: string, opts?: ClaudeMcpCallOptions): Promise<GetResult>;
+export type ClaudeMcpConnectionStatus = "connected" | "failed" | "needs-authentication" | "unknown";
+export interface ClaudeMcpListEntry {
+    name: string;
+    command: string;
+    args: string[];
+    status: ClaudeMcpConnectionStatus;
+    statusText: string;
+}
+/**
+ * Parse `claude mcp list` stdout. Lines that don't match the expected
+ * shape (blank lines, any future banner/preamble) are skipped rather
+ * than throwing — the exit code alone tells us the command succeeded.
+ *
+ * Caveat (same one `buildMcpServers` in generate-settings.ts documents
+ * for the inverse direction): splitting the command+args segment on
+ * whitespace mis-splits a command path with embedded spaces. Foreign
+ * entries whose "command" is a URL (e.g. `claude.ai Gmail: https://... -
+ * ! Needs authentication`) still parse correctly since URLs have no
+ * embedded whitespace.
+ */
+export declare function parseClaudeMcpListOutput(stdout: string): ClaudeMcpListEntry[];
+export type ListStatus = "ok" | "cli-missing" | "timeout" | "error";
+export interface ListResult {
+    status: ListStatus;
+    servers: ClaudeMcpListEntry[];
+    message?: string;
+}
+export declare function listMcpServers(opts?: ClaudeMcpCallOptions): Promise<ListResult>;
+export interface ResolveRegistryPathOptions {
+    /** Override for Claude Code's own config home. Defaults to `path.join(os.homedir(), ".claude")`. */
+    homeDir?: string;
+    /** Override for process.env (CLAUDE_CONFIG_DIR lookup). Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve the path to the user-scope registry file the `claude` CLI
+ * itself reads/writes — the same precedence the CLI applies: an explicit
+ * `CLAUDE_CONFIG_DIR` wins (`$CLAUDE_CONFIG_DIR/.claude.json`); otherwise
+ * it's `~/.claude.json`, derived here as `path.join(path.dirname(homeDir),
+ * ".claude.json")` to match the existing resolution in
+ * `src/cli/uninstall/index.ts` (`probeProjectLocalClaudeJson`).
+ */
+export declare function resolveClaudeUserRegistryPath(opts?: ResolveRegistryPathOptions): string;
+export interface RegistryReadResult {
+    servers: Record<string, unknown>;
+    error: string | null;
+}
+/**
+ * Read strictly the top-level `mcpServers` key of the registry file. Never
+ * reads/interprets `projects.<path>.mcpServers` — that's project-local
+ * Claude Code state, out of scope here (see `probeProjectLocalClaudeJson`
+ * in uninstall for the existing, separate, read-only handling of it).
+ *
+ * Exported (task 83d8d03a) as the single allowed primitive for reading the
+ * effective Claude Code user-scope MCP registration from outside this
+ * module — `adopt` (MCP-drift comparison) and `detect` (team/full
+ * recognition) both call this directly instead of duplicating a registry
+ * reader or spawning `claude mcp list`. Read-only; never writes.
+ */
+export declare function readTopLevelMcpServers(registryPath: string): RegistryReadResult;
+export type EnsureAction = "noop" | "add" | "replace" | "skipped";
+export interface EnsureServerResult {
+    name: string;
+    action: EnsureAction;
+    /** Present when action === "replace". */
+    remove?: RemoveResult;
+    /** Present when action === "add" or a "replace" whose remove step succeeded. */
+    add?: AddJsonResult;
+    /** Present when action === "skipped": the registry file could not be read safely, so drift cannot be determined. */
+    reason?: string;
+}
+export interface EnsureMcpServersGcOptions {
+    /**
+     * Names this harness install is allowed to garbage-collect from the
+     * registry (task 363a6de0, D-107 ownership union: the current
+     * manifest's `tools.mcp[]` names, union the `.last-apply` manifest
+     * snapshot's `tools.mcp[]` names — the snapshot as of BEFORE the
+     * caller's own apply ran, so a combined edit that both drops an entry
+     * and re-stamps `.last-apply` doesn't erase the provenance). Building
+     * this set is entirely the caller's responsibility — see `wireClaudeMcp`
+     * in `cli/init/interactive.ts` for the reference construction.
+     * Deliberately NOT included: the uninstall module's
+     * `DEFAULT_OWNED_MCP_SERVERS` (D-107 supersedes the original D-103,
+     * reviewer HIGH finding) — a server sharing one of those default names
+     * that the operator registered themselves, outside/before any harness
+     * manifest, must never be GC'd just because it's absent from `desired`.
+     * A registry entry outside this set is NEVER touched by GC, no matter
+     * how it drifts from `desired`.
+     */
+    ownedNames: string[];
+}
+export type GcAction = "removed" | "skipped";
+export interface GcServerResult {
+    name: string;
+    action: GcAction;
+    /** The underlying `claude mcp remove` outcome. */
+    remove: RemoveResult;
+    /**
+     * Present when action === "skipped": `remove.status` was something
+     * other than "removed"/"not-found" (cli-missing, timeout, or a genuine
+     * error) — restated here as a human-readable reason so callers don't
+     * have to re-derive it from `remove`.
+     */
+    reason?: string;
+}
+export interface GcResult {
+    /**
+     * One entry per GC candidate: an owned name (per `opts.gc.ownedNames`)
+     * that is present in the registry and absent from `desired`. Empty when
+     * there were no candidates, or when `registryReadError` is set.
+     */
+    results: GcServerResult[];
+    /**
+     * Present when the registry could not be read safely — the same
+     * condition the main loop reports per-name via `skipped`/`reason`. No
+     * GC candidate could be determined, so no removal was attempted for any
+     * owned name; `results` stays empty rather than guessing.
+     */
+    registryReadError?: string;
+}
+export interface EnsureMcpServersOptions {
+    /** Desired state: server name -> spec. */
+    desired: Record<string, ClaudeMcpServerSpec>;
+    exec?: ClaudeMcpExec;
+    timeoutMs?: number;
+    /** Explicit override for the registry file read for drift comparison. Takes precedence over homeDir/env. */
+    registryPath?: string;
+    /** Base for the default registry path when `registryPath` is not given. */
+    homeDir?: string;
+    /** Override for process.env (CLAUDE_CONFIG_DIR lookup) when `registryPath` is not given. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Opt-in garbage collection (task 363a6de0): after reconciling
+     * `desired`, additionally `claude mcp remove` any name in
+     * `gc.ownedNames` that's registered but no longer in `desired` (i.e.
+     * removed or disabled in the manifest since it was last registered).
+     * Omitted entirely: behavior is exactly the pre-GC contract — every
+     * registry entry outside `desired` is left untouched, and
+     * `EnsureMcpServersResult.gc` stays undefined.
+     */
+    gc?: EnsureMcpServersGcOptions;
+}
+export interface EnsureMcpServersResult {
+    registryPath: string;
+    results: EnsureServerResult[];
+    /** Present iff `opts.gc` was given. */
+    gc?: GcResult;
+}
+/**
+ * Reconcile `desired` against the live user-scope registry:
+ *   - name absent from the registry           → `add-json`
+ *   - name present, spec identical             → no-op, NO exec call at all
+ *   - name present, spec differs (drift)        → `remove` then `add-json`
+ * The registry is only ever read (for the comparison); every write goes
+ * through the CLI wrapper. If the registry file can't be read safely
+ * (malformed JSON, `mcpServers` not an object, non-ENOENT read error),
+ * every desired server is reported `skipped` with a reason instead of
+ * guessing — a missing file (ENOENT, i.e. no registry yet) is NOT an
+ * error and is treated as an empty registry.
+ *
+ * `opts.gc` (task 363a6de0) opts into a second pass over the SAME
+ * registry snapshot: every name in `opts.gc.ownedNames` that is currently
+ * registered but absent from `desired` gets `claude mcp remove`d — this is
+ * how a manifest edit that deletes or disables a `tools.mcp[]` entry
+ * propagates into a deregistration on the next ensure run. A name that's
+ * owned but ALSO still in `desired` (e.g. an operator hand-registered a
+ * drifted copy of a still-active entry) is never a GC candidate — the
+ * `desired` membership check excludes it before ownership is even
+ * considered, so it's protected automatically, not via special-cased
+ * content comparison. Without `opts.gc`, behavior is exactly the pre-GC
+ * contract: every registry entry outside `desired` is left alone. If the
+ * registry couldn't be read safely, GC is skipped too, mirroring the main
+ * loop (`gc.registryReadError` set, `gc.results` empty) — same "never
+ * guess" rule.
+ */
+export declare function ensureMcpServers(opts: EnsureMcpServersOptions): Promise<EnsureMcpServersResult>;
+export interface StripOwnedMcpServersResult {
+    settings: Record<string, unknown>;
+    /** Names actually removed (subset of ownedNames that were present), sorted. */
+    removedNames: string[];
+}
+/**
+ * Remove exactly the given owned names from `settings.mcpServers`,
+ * preserve every foreign entry, drop the `mcpServers` key entirely when
+ * it becomes empty, and leave every other top-level key byte-identical
+ * (same values, same insertion order). Pure — no file I/O; callers own
+ * reading/writing settings.json.
+ */
+export declare function stripOwnedMcpServers(settings: Record<string, unknown>, ownedNames: readonly string[]): StripOwnedMcpServersResult;