@lannguyensi/harness 0.64.0 → 1.0.0

package/dist/cli/session-start/toolchain-parity.d.ts

@@ -1,267 +0,0 @@
-import { type LedgerWriteFn } from "../../runtime/ledger-writer.js";
-import { type SessionSource, type SessionStartCwdOptions } from "./shared-options.js";
-/**
- * Profile names land in a filename; strip anything not filename-safe.
- * Exported (task 13919613) so `harness doctor`'s toolchain-parity section
- * can resolve the SAME own-profile filename this producer would, without
- * re-implementing the sanitization rule. Pure export, no behaviour change
- * to any call site in this module.
- */
-export declare function sanitizeProfileName(value: string): string;
-/**
- * The toolchain snapshot v1 content (task brief §"Snapshot-Inhalt v1").
- * Every collected field is optional: a collection failure (spawn missing/
- * timed out, file unreadable) degrades to the matching `*Error` field
- * instead of ever throwing — see collectLocalSnapshot below. The harness
- * package's own version is deliberately NOT a separate field: it is just
- * one more entry in `npmGlobals` (key `@lannguyensi/harness`), which the
- * generic npm-package-version comparison in compareToPeer already covers.
- */
-export interface ToolchainSnapshot {
-    schemaVersion: 1;
-    /** This machine's configured/derived profile name. */
-    profile: string;
-    /** ISO timestamp of when this snapshot was collected. */
-    timestamp: string;
-    /** `node --version` output (e.g. "v22.1.0"), PATH-resolved — see collectNodeVersion. */
-    node?: string;
-    nodeError?: string;
-    /** `npm ls -g --depth=0 --json` dependencies, name -> version. */
-    npmGlobals: Record<string, string>;
-    npmGlobalsError?: string;
-    /** `<workspaceRoot>/.ai/workflow/manifest.json`'s `version` field. */
-    owKitVersion?: string;
-    owKitError?: string;
-    /** MCP server names registered with the `claude` CLI (file-read, no spawn). */
-    mcpServers: string[];
-    mcpServersError?: string;
-}
-/**
- * Parse a stored snapshot JSON. Rejects (`ok:false`) only on the shapes
- * that make comparison meaningless — not valid JSON, not an object,
- * missing/invalid `profile` or `timestamp`. Every other field degrades
- * leniently (missing/malformed -> empty/absent) rather than rejecting the
- * whole file, since a peer snapshot written by a future schema version
- * should still compare on the fields this version understands.
- */
-export declare function parseSnapshotJson(raw: string): {
-    ok: true;
-    snapshot: ToolchainSnapshot;
-} | {
-    ok: false;
-    reason: string;
-};
-export type CollectNodeVersionResult = {
-    ok: true;
-    version: string;
-} | {
-    ok: false;
-    reason: string;
-};
-export type CollectNpmGlobalsResult = {
-    ok: true;
-    packages: Record<string, string>;
-} | {
-    ok: false;
-    reason: string;
-};
-/**
- * Hermetic guard (mirrors `realNpmExec` in src/cli/doctor/npm-bin-path.ts):
- * asserts BEFORE touching `child_process` that we are not running under
- * vitest without a test having injected `runNodeVersion`. This function has
- * no try/catch around the assertion, and its only caller,
- * `collectLocalSnapshot`, calls it (via the `runNodeVersion` param, defaulted
- * to this function in `runSessionStartToolchainParity`) with no surrounding
- * try/catch either — see src/runtime/hermetic-spawn-guard.ts for why that
- * matters (a thrown `HermeticSpawnViolationError` must propagate, not be
- * folded into an ordinary "collection failed" outcome).
- *
- * PATH-resolved deliberately: `execFile("node", ...)` does a PATH lookup for
- * the literal string "node", NOT `process.execPath` — the entire point of
- * this collector is capturing the PATH state of the *shell* the session
- * runs in (the PATH-shim incident this task follows up on was exactly a
- * PATH pointing at the wrong node), which `process.version` (the node
- * running THIS harness process) would silently paper over.
- *
- * Exported (task 13919613) so `harness doctor`'s toolchain-parity section
- * can default its own `runNodeVersion` injection knob to the SAME real
- * collector this producer uses — the whole point of the reuse is that
- * doctor never re-implements this spawn/parse logic. No behaviour change:
- * this is the exact function every existing call site already used.
- */
-export declare function realNodeVersionSpawn(timeoutMs: number): Promise<CollectNodeVersionResult>;
-/**
- * Hermetic guard, same shape/rationale as {@link realNodeVersionSpawn} —
- * see that function's doc. Tolerant of a non-zero exit the same way
- * `spawnPreflight` (session-start/index.ts) is tolerant of `preflight run`'s
- * exit code: `npm ls -g` can exit non-zero on an unrelated extraneous/
- * invalid global entry while still emitting a perfectly parseable
- * `dependencies` JSON block, so a parseable stdout wins over the exit code.
- *
- * Exported (task 13919613) for the same reuse reason as
- * {@link realNodeVersionSpawn} — `harness doctor`'s toolchain-parity
- * section defaults to this real collector rather than duplicating it.
- */
-export declare function realNpmGlobalsSpawn(timeoutMs: number): Promise<CollectNpmGlobalsResult>;
-/**
- * Read `<workspaceRoot>/.ai/workflow/manifest.json`'s `version` field
- * (the orchestrator-workflow kit's own version marker). A missing file is
- * the expected common case (most repos are not OW-kit-managed) and is
- * NOT an error — it degrades silently to `{}`. Malformed JSON or a
- * non-string `version` field on a manifest that DOES exist is noteworthy
- * (something is there but broken), so that degrades to `{ error }`.
- *
- * Exported (task 13919613) for the same reuse reason as
- * {@link realNodeVersionSpawn}.
- */
-export declare function realReadOwKitVersion(workspaceRoot: string): {
-    version?: string;
-    error?: string;
-};
-/**
- * MCP server names from Claude Code's user-scope registry — a pure FILE
- * READ (never a spawn), reusing the exact primitive `harness doctor`'s
- * claude-mcp check ultimately compares against
- * (`resolveClaudeUserRegistryPath` + `readTopLevelMcpServers` in
- * src/io/claude-mcp.ts — the same functions `adopt`/`detect` use for the
- * same "read the effective registration from outside io/claude-mcp.ts"
- * purpose). Deliberately NOT `claude mcp list` (a spawn): the brief calls
- * for a file-read source for the NAMES here, and this is it.
- *
- * Exported (task 13919613) for the same reuse reason as
- * {@link realNodeVersionSpawn}.
- */
-export declare function realReadMcpServerNames(): {
-    names: string[];
-    error?: string;
-};
-/**
- * Exported (task 13919613) so `harness doctor`'s toolchain-parity section
- * can call {@link collectLocalSnapshot} directly instead of duplicating
- * its orchestration of the four collectors.
- */
-export interface CollectLocalSnapshotOptions {
-    profile: string;
-    now: Date;
-    workspaceRoot: string;
-    nodeTimeoutMs: number;
-    npmTimeoutMs: number;
-    runNodeVersion: (timeoutMs: number) => Promise<CollectNodeVersionResult>;
-    runNpmGlobals: (timeoutMs: number) => Promise<CollectNpmGlobalsResult>;
-    readOwKitVersion: (workspaceRoot: string) => {
-        version?: string;
-        error?: string;
-    };
-    readMcpServerNames: () => {
-        names: string[];
-        error?: string;
-    };
-}
-/**
- * Collect the local, LIVE toolchain snapshot. Never throws (every
- * collector above degrades to `{ok:false,reason}` / `{error}` instead of
- * rejecting/throwing) — a collection failure is reported both inline on
- * the returned snapshot (the matching `*Error` field) AND as a `notes`
- * line for the caller to log, but never stops the other collectors from
- * running. node/npm run in PARALLEL (see the timeout constants' comment
- * above for why).
- *
- * Exported (task 13919613): `harness doctor`'s toolchain-parity section
- * imports this directly as its Collector core — see that module's header
- * for the reuse rationale. No behaviour change to this function or any
- * existing call site.
- */
-export declare function collectLocalSnapshot(opts: CollectLocalSnapshotOptions): Promise<{
-    snapshot: ToolchainSnapshot;
-    notes: string[];
-}>;
-export type DriftKind = "node" | "ow_kit" | "npm_package_version" | "npm_package_missing_local" | "npm_package_missing_peer" | "mcp_missing_local" | "mcp_missing_peer";
-export interface DriftItem {
-    kind: DriftKind;
-    message: string;
-}
-export interface PeerComparison {
-    peerProfile: string;
-    /** Snapshot age in ms, derived from the peer's own `timestamp` field. */
-    ageMs: number;
-    drift: DriftItem[];
-}
-/** `"just now"` / `"<n>m"` / `"<n>h"` / `"<n>d"` — coarse, human-scannable. */
-export declare function formatSnapshotAge(ageMs: number): string;
-/**
- * Compare the local LIVE snapshot against one peer's stored snapshot.
- * Node / OW-Kit drift only fires when BOTH sides collected that field
- * successfully (an unavailable field reads as "unknown", not "match" or
- * "drift"). The npm-globals and MCP-name comparisons additionally gate on
- * the WHOLE field having collected without error on both sides — an
- * `npmGlobalsError`/`mcpServersError` on either side means that side's map
- * is "unknown", not "empty", and treating it as empty would fabricate a
- * wall of "missing on N packages" drift instead of the real gap (which the
- * caller's own note()s already surface separately, from collectLocalSnapshot's
- * `notes` and the peer-unreadable path).
- */
-export declare function compareToPeer(local: ToolchainSnapshot, peer: ToolchainSnapshot, now: Date): PeerComparison;
-export interface SessionStartToolchainParityOptions extends SessionStartCwdOptions {
-    /** Override "now" for deterministic snapshot-age tests. */
-    now?: Date;
-    /** Inject the ledger writer (tests). */
-    writeLedger?: LedgerWriteFn;
-    /** `node --version` subprocess timeout in ms. */
-    nodeTimeoutMs?: number;
-    /** `npm ls -g --depth=0 --json` subprocess timeout in ms. */
-    npmTimeoutMs?: number;
-    /** Inject the `node --version` collector (tests) — see realNodeVersionSpawn's doc. */
-    runNodeVersion?: (timeoutMs: number) => Promise<CollectNodeVersionResult>;
-    /** Inject the `npm ls -g` collector (tests) — see realNpmGlobalsSpawn's doc. */
-    runNpmGlobals?: (timeoutMs: number) => Promise<CollectNpmGlobalsResult>;
-    /** Inject the OW-Kit-version file reader (tests). */
-    readOwKitVersion?: (workspaceRoot: string) => {
-        version?: string;
-        error?: string;
-    };
-    /** Inject the MCP-server-names file reader (tests). */
-    readMcpServerNames?: () => {
-        names: string[];
-        error?: string;
-    };
-}
-export interface SessionStartToolchainParityResult {
-    /** Always 0 — a SessionStart hook must never break the session loop. */
-    exitCode: number;
-    /** Whether the `toolchain-parity:` ledger fact was written. */
-    wrote: boolean;
-    /** Resolved own profile name. */
-    profile: string;
-    /** Number of peer snapshots actually compared (readable + parseable). */
-    peersCompared: number;
-    /** Total drift items found across every compared peer. */
-    driftCount: number;
-    /**
-     * Peer files present in the machine-state directory that failed to parse
-     * as valid JSON (readable but not JSON, or JSON that fails the minimal
-     * `profile`/`timestamp` shape check) and were therefore excluded from
-     * `driftCount`/`peersCompared`. A non-zero count here means `driftCount`
-     * reflects a PARTIAL comparison, not a full one — see the
-     * `:unparseable-peer:<n>` ledger-content suffix this drives.
-     *
-     * The contrapositive does NOT hold: peers whose file could not be READ
-     * at all (EACCES, EISDIR, ...) are skipped by the unreadable branch and
-     * are not counted here, so the absence of the suffix does not prove a
-     * complete comparison. That branch is scoped to the follow-up hardening
-     * round (task c1b5ade5).
-     */
-    unparseablePeerCount: number;
-    /** Resolved session id. */
-    sessionId: string;
-    sessionSource: SessionSource;
-    /** Human-readable explanation of a non-write outcome, for diagnostics. */
-    reason?: string;
-}
-/**
- * Exported (task 13919613) so `harness doctor`'s toolchain-parity section
- * resolves the SAME default machine-state directory this producer writes
- * to when `toolchain_parity.machine_state_dir` is omitted from the
- * manifest — reusing the constant instead of re-deriving it.
- */
-export declare function defaultMachineStateDir(): string;
-export declare function runSessionStartToolchainParity(opts?: SessionStartToolchainParityOptions): Promise<SessionStartToolchainParityResult>;