import { spawn } from "node:child_process"; import { type Contract, checkHandshake } from "./handshake-conformance.ts"; import contractJson from "./handshake-contract.v1.json"; import { INSTALL_STEP, type NextStep } from "./next-step.ts"; /** The v1 contract, bundled (byte-identical to contract/ashlr-handshake.v1.json; a test enforces it). */ export const HANDSHAKE_CONTRACT = contractJson as unknown as Contract; /** At most this many contract problems are shown per tool, each cut to this length. */ const MAX_PROBLEMS = 3; const MAX_PROBLEM_LEN = 100; /** One Ashlr tool `stack doctor --ecosystem` probes. */ interface EcosystemTool { name: string; command: string; } export const ECOSYSTEM_TOOLS: EcosystemTool[] = [ { name: "phantom", command: "phm" }, { name: "phantom-secrets", command: "phantom" }, { name: "locus", command: "locus" }, { name: "lexicon", command: "lexicon" }, { name: "ashlr-md", command: "mdopener-mcp" }, { name: "ashlr-plugin", command: "ashlr-plugin" }, ]; const PROBE_TIMEOUT_MS = 2000; /** Result of running one probe. `missing` means the binary was not found. */ export type ProbeRun = | { kind: "ran"; code: number | null; stdout: string } | { kind: "missing" } | { kind: "timeout" }; export type ProbeRunner = (command: string, timeoutMs: number) => Promise; export interface EcosystemEntry { name: string; command: string; /** `ok` answered v1; `missing` not installed; `no-handshake` installed but too old or unparseable. */ status: "ok" | "missing" | "no-handshake"; version?: string; capabilities?: string[]; health?: string; detail?: string; /** Only for `ok`: whether the handshake matches the v1 contract. */ contract?: "ok" | "drift"; /** Short contract problems when `contract` is `drift` (at most 3). */ contract_problems?: string[]; } /** * Env for probes: PATH and locale/home basics only, so no token or secret in * this process's environment reaches another tool. */ export function probeEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv { const keep = ["PATH", "HOME", "USER", "LANG", "LC_ALL", "TMPDIR", "SYSTEMROOT", "PATHEXT"]; const out: NodeJS.ProcessEnv = {}; for (const key of keep) if (env[key] !== undefined) out[key] = env[key]; out.NO_COLOR = "1"; return out; } export const defaultProbeRunner: ProbeRunner = (command, timeoutMs) => new Promise((resolve) => { let stdout = ""; let settled = false; const done = (r: ProbeRun) => { if (!settled) { settled = true; resolve(r); } }; let child: ReturnType; try { child = spawn(command, ["--ashlr-handshake", "--json"], { env: probeEnv(), stdio: ["ignore", "pipe", "ignore"], timeout: timeoutMs, killSignal: "SIGKILL", }); } catch { done({ kind: "missing" }); return; } child.stdout?.on("data", (d) => { if (stdout.length < 64_000) stdout += String(d); }); child.on("error", (err: NodeJS.ErrnoException) => done(err.code === "ENOENT" ? { kind: "missing" } : { kind: "ran", code: 1, stdout: "" }), ); child.on("close", (code, signal) => done( signal === "SIGKILL" && code === null ? { kind: "timeout" } : { kind: "ran", code, stdout }, ), ); }); function parseHandshake(tool: EcosystemTool, run: ProbeRun): EcosystemEntry { const base = { name: tool.name, command: tool.command }; if (run.kind === "missing") return { ...base, status: "missing", detail: "not installed" }; if (run.kind === "timeout") return { ...base, status: "no-handshake", detail: "did not answer in time" }; try { const v = JSON.parse(run.stdout.trim()); if (v?.kind !== "ashlr.handshake" || v.schema_version !== 1) throw new Error("shape"); const problems = checkHandshake(v, HANDSHAKE_CONTRACT); return { ...base, status: "ok", contract: problems.length ? "drift" : "ok", ...(problems.length ? { contract_problems: problems .slice(0, MAX_PROBLEMS) .map((p) => p.length > MAX_PROBLEM_LEN ? `${p.slice(0, MAX_PROBLEM_LEN - 3)}...` : p, ), } : {}), version: typeof v.version === "string" ? v.version : undefined, capabilities: Array.isArray(v.capabilities) ? v.capabilities.filter((c: unknown) => typeof c === "string") : [], health: typeof v.health?.status === "string" ? v.health.status : undefined, }; } catch { return { ...base, status: "no-handshake", detail: "installed, but too old to answer --ashlr-handshake", }; } } /** Probes every tool in parallel. Never throws; nothing here is a failure. */ export async function checkEcosystem( runner: ProbeRunner = defaultProbeRunner, tools: EcosystemTool[] = ECOSYSTEM_TOOLS, timeoutMs = PROBE_TIMEOUT_MS, ): Promise { return Promise.all( tools.map(async (tool) => { const run = await runner(tool.command, timeoutMs).catch( (): ProbeRun => ({ kind: "missing" }), ); return parseHandshake(tool, run); }), ); } /** Handshake capability a locus build advertises when `locus doctor --fix` exists. */ export const LOCUS_DOCTOR_FIX_CAPABILITY = "doctor-fix"; /** One explicit action per component; install commands only preview a plan. */ export function ecosystemFix(entry: EcosystemEntry): NextStep | null { if (entry.status === "ok" && entry.contract !== "drift") { return entry.name === "locus" && entry.health !== undefined && entry.health !== "ok" && entry.capabilities?.includes(LOCUS_DOCTOR_FIX_CAPABILITY) ? { summary: "Preview safe repairs for Locus.", command: "locus doctor --fix" } : null; } if (entry.name === "phantom-secrets") return INSTALL_STEP; if (entry.name === "ashlr-plugin") return { summary: "Install or update the plugin for your host: https://github.com/ashlrai/ashlr-plugin#install", command: null, }; return { summary: `Show the install or update plan for ${entry.name}.`, command: `stack doctor --ecosystem --install ${entry.name}`, }; } /** * Suggested next steps for installed tools. Today: `locus doctor --fix` when * locus answered the handshake, reports health other than `ok`, and itself * advertises the `doctor-fix` capability. No version guessing: a locus that * does not advertise the capability gets no suggestion. Healthy: nothing. */ export function ecosystemNextSteps(entries: EcosystemEntry[]): string[] { const steps: string[] = []; for (const e of entries) { if (e.status === "ok" && e.contract === "drift") { steps.push( `upgrade ${e.name}: its \`${e.command} --ashlr-handshake\` does not match the v1 contract (${e.contract_problems?.[0] ?? "see --json"}); see docs/ashlr-handshake.md`, ); } } const locus = entries.find((e) => e.name === "locus"); if ( locus?.status === "ok" && locus.health !== undefined && locus.health !== "ok" && locus.capabilities?.includes(LOCUS_DOCTOR_FIX_CAPABILITY) ) { steps.push( "locus doctor --fix # preview safe repairs (writes nothing); add --apply to make them", ); } return steps; } export function formatEcosystem(entries: EcosystemEntry[]): string[] { const lines = formatEcosystemEntries(entries); const steps = ecosystemNextSteps(entries); if (steps.length) { lines.push("", " Next steps:"); for (const s of steps) lines.push(` ${s}`); } return lines; } function formatEcosystemEntries(entries: EcosystemEntry[]): string[] { return entries.map((e) => { if (e.status === "ok") { const caps = e.capabilities?.length ? ` [${e.capabilities.join(", ")}]` : ""; const health = e.health && e.health !== "ok" ? ` (health: ${e.health})` : ""; if (e.contract === "drift") { const n = e.contract_problems?.length ?? 0; return ` !! ${e.name} ${e.version ?? "?"}${caps}${health} (contract drift: ${n} problem${n === 1 ? "" : "s"})`; } return ` ok ${e.name} ${e.version ?? "?"}${caps}${health}`; } const fix = ecosystemFix(e); const action = fix ? `\n Fix: ${fix.summary}${fix.command ? ` Run \`${fix.command}\`.` : ""}` : ""; return ` -- ${e.name} (${e.command}): ${e.detail}${action}`; }); }