@pleri/olam-cli 0.1.201 → 0.1.205

package/dist/lib/health-probes.d.ts

@@ -1,267 +0,0 @@
-/**
- * health-probes.ts — Shared host-health probe module.
- *
- * Phase A1 of olam-operator-onboarding-parity (plan
- * ~/.claude/plans/olam-operator-onboarding-parity.md).
- *
- * The Seam (Decision 3): `olam doctor` + `olam diagnose` both consume
- * these probes. No probe writes to disk; no probe spawns long-running
- * processes; each is independently safe to run in parallel.
- *
- * Probe contract:
- *   - Each returns ProbeResult: { ok: true, message } | { ok: false, message, remedy }
- *   - Each is async; can run in parallel via Promise.all
- *   - Each accepts injectable deps (docker exec / fetch / OLAM_HOME) for testability
- *
- * Cap thresholds (probeKgStorage) mirror packages/cli/src/commands/kg-status.ts:
- *   - 1.5 GB soft-cap → ok:true with "soft-warn" message
- *   - 5.0 GB hard-cap → ok:false with prune remedy
- *
- * Daemon-reachability rule (Risk T5): callers that probe per-image
- * presence MUST call probeDockerDaemon first and fast-fail on its
- * failure. Image probes throw confusing "404 no such image" errors
- * when the daemon is paused mid-check.
- */
-/**
- * ProbeResult — tristate per Phase C / C2:
- *   - PASS: ok:true, no warn flag.
- *   - WARN: ok:true, warn:true — doctor exits 0 but the row renders as
- *     `[WARN]` with the remedy text. Used by probeColimaVersion when
- *     0.10.x is detected (plan Goal verbatim).
- *   - FAIL: ok:false — doctor exits 1, row renders as `[FAIL]`.
- *
- * Pre-C the type was binary (ok:true|false). The new WARN variant is
- * additive: probes that don't surface a warn never set the flag, so the
- * existing 5 probes remain wire-compatible.
- */
-export type ProbeResult = {
-    readonly ok: true;
-    readonly warn?: false;
-    readonly message: string;
-} | {
-    readonly ok: true;
-    readonly warn: true;
-    readonly message: string;
-    readonly remedy: string;
-} | {
-    readonly ok: false;
-    readonly message: string;
-    readonly remedy: string;
-};
-/**
- * Probe: GitHub CLI authenticated via `gh auth status`.
- *
- * k3d uses `gh auth token` to create the GHCR pull secret during olam setup.
- * This probe warns (non-gating) when gh CLI is not authenticated.
- */
-export declare function probeGithubCliAuth(dockerExec?: DockerExec): Promise<ProbeResult>;
-/**
- * Probe: Claude Code installed and accessible via `claude --version`.
- *
- * OLAM requires Claude Code as the primary agent runtime. This probe warns
- * (non-gating) when Claude Code is not found on PATH.
- */
-export declare function probeClaudeCodeInstalled(dockerExec?: DockerExec): Promise<ProbeResult>;
-export declare const COLIMA_010_WARN_TEXT = "Colima 0.10.1's --kubernetes mode is broken upstream. Either switch to OLAM_HOST_CP_ENGINE=docker (recommended) or downgrade Colima to 0.9.x. Track abiosoft/colima issues for fix.";
-export interface DockerExecResult {
-    readonly status: number | null;
-    readonly stdout: string;
-    readonly stderr: string;
-}
-export type DockerExec = (cmd: string, args: ReadonlyArray<string>) => DockerExecResult;
-export type FetchLike = (input: string, init?: {
-    signal?: AbortSignal;
-}) => Promise<Response>;
-/**
- * Verify docker daemon is reachable via `docker info --format`.
- *
- * MUST be called first by callers that probe per-image presence; image
- * probes throw confusing "404 no such image" errors when the daemon is
- * paused mid-check (Risk T5 mitigation).
- */
-export declare function probeDockerDaemon(dockerExec?: DockerExec): Promise<ProbeResult>;
-/**
- * Verify the `docker compose` v2 plugin is installed.
- *
- * Symptom this guards against (B2 / npm-only operator on macOS via Homebrew):
- * `brew install docker` does NOT ship the compose v2 plugin. `docker compose pull …`
- * fails — depending on docker version — with either "is not a docker command"
- * (newer docker) or "unknown shorthand flag" (bare docker mis-parsing the
- * remainder of the compose argv). The cryptic flag error misdirects operators
- * away from the real fix.
- *
- * Returns:
- *   - PASS when `docker compose version` exits 0 with v2.x in stdout.
- *   - FAIL with macOS-aware remedy when docker is present but the plugin isn't.
- *   - FAIL with "install docker" remedy when the docker binary is missing entirely.
- *
- * Detection: relies on stderr / exit status of `docker compose version`. The
- * exact stderr text varies by docker version, so we match a small set of
- * substrings rather than a single regex.
- */
-export declare function probeComposePlugin(dockerExec?: DockerExec): Promise<ProbeResult>;
-/**
- * Verify each ref is present locally via `docker image inspect`.
- *
- * Fast-fail: returns the first missing image; subsequent refs NOT
- * probed. Caller decides ordering of refs.
- */
-export declare function probeImagePresence(refs: ReadonlyArray<string>, dockerExec?: DockerExec): Promise<ProbeResult>;
-/**
- * GET http://127.0.0.1:19000/health with 5s timeout; expect HTTP 200
- * AND a JSON envelope matching the host-cp shape (defends against
- * false-positives from a port-collision with some other 19000-bound
- * process — audit finding HIGH body-shape).
- *
- * Real envelope (per `packages/host-cp/src/server.mjs:665-688`):
- *   { status: 'ok', phase, uptime_seconds: number, cache: {...},
- *     mode: { deployment, world_host }, registry: {...}, auth: {...} }
- *
- * Probe asserts three orthogonal fields (`phase` + `cache` object +
- * `mode.deployment`) that no random web server would carry together.
- * Substring-on-the-token-path was an earlier fragile heuristic; this
- * version pins to actual server contract.
- *
- * Aborts via AbortController on timeout; failure mode is captured in
- * the error path with reason ("timeout" / "ECONNREFUSED" / etc.).
- *
- * Always consumes the response body before returning (avoids undici
- * socket leak when the probe is invoked in a loop).
- */
-export declare function probeHostCpHealth(fetchImpl?: FetchLike): Promise<ProbeResult>;
-export declare function probeAuthVault(olamHomeOverride?: string): Promise<ProbeResult>;
-/**
- * Cumulative KG storage under OLAM_HOME (pristines + overlays).
- * Soft warn at 1.5 GB; hard fail at 5 GB.
- *
- * Layout (mirrors packages/cli/src/commands/kg-status.ts):
- *   - Pristines: ~/.olam/kg/<workspace>/graphify-out/
- *   - Overlays:  ~/.olam/worlds/<world>/<clone>/graphify-out/
- *
- * Cap constants duplicated rather than imported from kg-status.ts to
- * keep this module self-contained (the Seam decision — see plan
- * decision 3). A future PR may extract them to a single source if
- * a third consumer lands.
- */
-export declare function probeKgStorage(olamHomeOverride?: string): Promise<ProbeResult>;
-/**
- * Probe: detect the active container engine via host-cp's `/health`
- * X-Olam-Engine header (Phase A landed the header in #614). When host-cp
- * is unreachable, the probe FAILs with the same remedy as probeHostCpHealth
- * — operators with a stopped host-cp see one canonical fix, not two.
- *
- * Returns the engine name as part of the PASS message. The doctor row
- * label is engine-agnostic (`engine`); the body surfaces the name.
- * No kubectl jargon — for `engine=kubernetes` we say "kubernetes", not
- * "kubectl context k3d-olam" or similar.
- */
-export declare function probeEngine(fetchImpl?: FetchLike): Promise<ProbeResult & {
-    engineName?: 'docker' | 'kubernetes' | string;
-}>;
-/**
- * Probe: Colima version. On macOS / Linux dev hosts using Colima as the
- * Docker daemon, the 0.10.x release line ships a broken
- * `--kubernetes` flag (upstream issue). When detected, surface a WARN
- * with the plan-specced verbatim remediation text.
- *
- * Behaviour matrix:
- *   - `colima` binary not on PATH → PASS (most operators don't run Colima)
- *   - `colima version` returns non-0.10.x → PASS with the detected version
- *   - `colima version` returns 0.10.x      → WARN with verbatim remedy
- *   - `colima version` errors (binary present, daemon issue, etc.) → PASS
- *       with a soft message (don't fail doctor on a tool-specific quirk)
- */
-export declare function probeColimaVersion(dockerExec?: DockerExec): Promise<ProbeResult>;
-/**
- * Probe: K8s API reachable via `kubectl version --output=json --request-timeout=2s`.
- *
- * Replaces probeDockerDaemon at position 1 of the doctor probe array when
- * the active engine is kubernetes (Decision 16 positional contract — the
- * `--json` consumer index stability is load-bearing).
- *
- * No kubectl jargon in the doctor output — this probe's row label stays
- * canonical ("api server") and the message hides the underlying
- * implementation detail.
- */
-export declare function probeK8sApiReachable(exec?: DockerExec): Promise<ProbeResult>;
-/**
- * Probe: required olam images are pullable on the K8s engine.
- *
- * Replaces probeImagePresence at position 2 of the doctor probe array when
- * the active engine is kubernetes (Decision 16 positional contract).
- *
- * Implementation note: on k3d / minikube, image presence is per-node and
- * checked via `kubectl get nodes -o json` + inspecting the `status.images`
- * arrays. We probe the host-cp image (`olam-host-cp:latest`) — the canonical
- * minimum-set. If absent, point the operator at `k3d image import` (or the
- * cluster's equivalent) without exposing kubectl in the remedy.
- */
-export declare function probeK8sImagePresence(refs: ReadonlyArray<string>, exec?: DockerExec): Promise<ProbeResult>;
-/**
- * Injectable cluster-type detector for colima vs k3d remedy differentiation.
- * Returns 'colima' when the active kubectl context is a colima-managed k3s cluster,
- * 'k3d' when it matches a k3d cluster name, or 'unknown' otherwise.
- */
-export type DetectK8sClusterTypeFn = (kubectlContext: string | undefined) => 'colima' | 'k3d' | 'unknown';
-/**
- * Default implementation: checks the provided context name (or reads
- * `kubectl config current-context` when omitted) against well-known prefixes.
- *
- * Heuristic (fail-open → falls back to k3d remedy as safe default):
- *   - context starts with 'colima' → 'colima'
- *   - context starts with 'k3d-'   → 'k3d'
- *   - else                         → 'unknown'
- */
-export declare function defaultDetectK8sClusterType(kubectlContext: string | undefined): 'colima' | 'k3d' | 'unknown';
-/**
- * Probe: detect whether Colima has `kubernetes.enabled: true` in its profile config.
- *
- * Used by `olam setup` Phase 1 (Colima lint, ADR 021).
- *
- * Returns:
- *   - PASS (ok:true, warn:false) when:
- *     - platform is not darwin (Colima is macOS-mostly — skip lint on Linux)
- *     - Colima profile YAML does not exist
- *     - `kubernetes.enabled` is not `true`
- *   - WARN (ok:true, warn:true) when `kubernetes.enabled: true` is found
- *
- * The lint is a WARNING, not a hard fail — the operator may know what they're
- * doing (e.g. intentional --reuse-cluster=colima usage).
- *
- * @param platform - os.platform() result (injectable for tests)
- * @param home - operator's home directory (injectable for tests)
- * @param colimaProfile - Colima profile name (default: $COLIMA_PROFILE or 'default')
- * @param readFileFn - injectable fs.readFileSync for tests
- * @param existsFn - injectable fs.existsSync for tests
- */
-export declare function probeColimaKubernetesEnabled(opts: {
-    platform: string;
-    home: string;
-    colimaProfile?: string;
-    readFileFn?: (p: string, enc: 'utf8') => string;
-    existsFn?: (p: string) => boolean;
-}): ProbeResult;
-/**
- * Probe: `kubectl` binary on PATH.
- *
- * Checks for the binary via `kubectl version --client --output=json`.
- * Does NOT require a live cluster — client-only check. Used by the
- * kubernetes substrate path of `olam setup` Phase 1 system check.
- */
-export declare function probeKubectl(exec?: DockerExec): Promise<ProbeResult>;
-/**
- * Probe: `k3d` binary on PATH (macOS kubernetes substrate).
- *
- * Used by `olam setup --substrate=kubernetes` Phase 1 on macOS to
- * distinguish "k3d missing" (defer to Phase 1.5 install) from
- * "k3d present". Returns ok:false so Phase 1.5 knows to install.
- */
-export declare function probeK3d(exec?: DockerExec): Promise<ProbeResult>;
-/**
- * Build the doctor/upgrade remedy text for a missing docker socket bind-mount.
- * Colima operators need `colima start --kubernetes` with the socket mount flag;
- * k3d operators need `k3d cluster create` with the --volume flag.
- * Issue #713 fix: no longer k3d-only.
- */
-export declare function buildDockerSocketRemedy(clusterType: 'colima' | 'k3d' | 'unknown'): string;
-//# sourceMappingURL=health-probes.d.ts.map

package/dist/lib/health-probes.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"health-probes.d.ts","sourceRoot":"","sources":["../../src/lib/health-probes.ts"],"names":[],"mappings":"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"}