okstra 0.174.0 → 0.176.0

package/src/commands/lifecycle/doctor.mjs

@@ -1,308 +0,0 @@
-import { promises as fs } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { resolvePaths } from "../../lib/paths.mjs";
-import { fileExists, runProcess } from "../../lib/proc.mjs";
-import { runPythonSnippet } from "../../lib/python-helper.mjs";
-import { runtimeIncludesClaudeAssets, validateInstallRuntime } from "./install.mjs";
-import { resolveRuntime } from "../../lib/host-registry-client.mjs";
-
-const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
-const REQUIRED_SKILLS = ["okstra-setup", "okstra-run"];
-
-const USAGE = `okstra doctor — diagnose the installed runtime
-
-Usage:
-  okstra doctor               Run all checks and print a summary
-  okstra doctor --runtime <host-id|alias|all>
-  okstra doctor --phase <phase>
-  okstra doctor --json        Machine-readable result
-Checks:
-  - python3 binary and version (>= 3.10)
-  - okstra_project module importable from $HOME/.okstra/lib/python
-  - okstra_ctl module importable
-  - bash entrypoints present and executable in $HOME/.okstra/bin
-  - agents/ directory exists inside the okstra package
-  - canonical skills present at $HOME/.claude/skills/<name>/SKILL.md
-    (skipped with --runtime codex)
-  - version stamp matches package version
-  - optional phase readiness checks with --phase <phase>
-
-Supported phase readiness checks:
-  - implementation: git worktree support, approved-plan validator, worker agents
-  - final-verification: worktree registry, validators, final-report assets
-  - release-handoff: gh auth, clean git tree, remote, non-base branch
-  - improvement-discovery: required workers and lens whitelist
-`;
-
-export function parseDoctorArgs(args) {
-  const result = {
-    jsonMode: false,
-    phase: null,
-    runtime: "auto",
-  };
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--json") {
-      result.jsonMode = true;
-    } else if (arg === "--runtime" || arg.startsWith("--runtime=")) {
-      const value = arg.startsWith("--runtime=") ? arg.slice("--runtime=".length) : args[i + 1];
-      if (!value || value.startsWith("--")) {
-        throw new Error("--runtime requires a host ID, alias, or all");
-      }
-      result.runtime = validateInstallRuntime(value);
-      if (arg === "--runtime") i++;
-    } else if (arg === "--phase" || arg.startsWith("--phase=")) {
-      const value = arg.startsWith("--phase=") ? arg.slice("--phase=".length) : args[i + 1];
-      if (!value || value.startsWith("--")) {
-        throw new Error("--phase requires a phase name");
-      }
-      result.phase = value;
-      if (arg === "--phase") i++;
-    } else {
-      throw new Error(`unknown argument '${arg}'`);
-    }
-  }
-  return result;
-}
-
-export function requiredSkillNamesForRuntime(resolution) {
-  return runtimeIncludesClaudeAssets(resolution) ? REQUIRED_SKILLS : [];
-}
-
-export function phaseDiagnosticsToChecks(phase, phaseDiagnostics) {
-  const checks = Array.isArray(phaseDiagnostics.checks) ? phaseDiagnostics.checks : [];
-  if (checks.length === 0) {
-    return [
-      {
-        name: `phase ${phase}: diagnostics`,
-        ok: false,
-        detail: phaseDiagnostics.reason || "phase diagnostics returned no checks",
-      },
-    ];
-  }
-  return checks.map((item) => ({
-    name: `phase ${phase}: ${item.name}`,
-    ok: Boolean(item.ok),
-    detail: String(item.detail ?? ""),
-  }));
-}
-
-export function buildPhaseDiagnosticsArgs(phase, paths, resolvedRuntime) {
-  return [
-    phase,
-    process.cwd(),
-    paths.workspace,
-    homedir(),
-    resolvedRuntime || "",
-  ];
-}
-
-async function checkPython3() {
-  const r = await runProcess("python3", ["--version"]);
-  if (r.code !== 0) return { ok: false, detail: `python3 not found: ${r.stderr.trim() || "missing binary"}` };
-  const out = (r.stdout + r.stderr).trim();
-  const m = out.match(/Python\s+(\d+)\.(\d+)/);
-  if (!m) return { ok: false, detail: `unparsable python version: ${out}` };
-  const [, maj, min] = m.map(Number);
-  if (maj < 3 || (maj === 3 && min < 10)) {
-    return { ok: false, detail: `python ${maj}.${min} is too old (need 3.10+)` };
-  }
-  return { ok: true, detail: out };
-}
-
-async function checkPythonImport(moduleName, pythonpath) {
-  const r = await runProcess(
-    "python3",
-    ["-c", `import ${moduleName}; print(${moduleName}.__name__)`],
-    { PYTHONPATH: pythonpath },
-  );
-  if (r.code !== 0) {
-    return { ok: false, detail: `import ${moduleName} failed: ${r.stderr.trim().split("\n").pop()}` };
-  }
-  return { ok: true, detail: `${moduleName} importable` };
-}
-
-async function checkBashEntry(binDir, name) {
-  const p = join(binDir, name);
-  if (!(await fileExists(p))) return { ok: false, detail: `missing ${p}` };
-  try {
-    const st = await fs.stat(p);
-    if (!(st.mode & 0o111)) return { ok: false, detail: `${name} not executable` };
-  } catch (err) {
-    return { ok: false, detail: `stat ${name} failed: ${err.message}` };
-  }
-  return { ok: true, detail: `${name} OK` };
-}
-
-async function dockerAvailabilityWarning() {
-  const r = await runProcess("docker", ["compose", "version"]);
-  if (r.code === 0) return null;
-  return "docker compose not available — `okstra container` needs Docker; all other commands work without it.";
-}
-
-async function check(name, fn) {
-  try {
-    const result = await fn();
-    return { name, ...result };
-  } catch (err) {
-    return { name, ok: false, detail: `unexpected error: ${err.message}` };
-  }
-}
-
-async function loadPhaseDiagnostics(phase, paths, resolvedRuntime) {
-  const script = [
-    "import json, sys",
-    "from okstra_ctl.doctor import phase_diagnostics",
-    "payload = phase_diagnostics(",
-    "    sys.argv[1],",
-    "    cwd=sys.argv[2],",
-    "    workspace_root=sys.argv[3],",
-    "    home=sys.argv[4],",
-    "    host_runtime=sys.argv[5],",
-    ")",
-    "print(json.dumps(payload, ensure_ascii=False))",
-  ].join("\n");
-  // `home` locates the agent install root (`<home>/.claude/agents`), which is
-  // the user home — NOT the okstra home (`paths.home` = ~/.okstra). Agents are
-  // installed under `homedir()/.claude/agents` (see install.mjs), so passing
-  // paths.home made every worker-agent phase check resolve to a path that
-  // never exists and report a false "missing agent".
-  const result = await runPythonSnippet({
-    script,
-    args: buildPhaseDiagnosticsArgs(phase, paths, resolvedRuntime),
-  });
-  if (result.code !== 0 && !result.stdout.trim()) {
-    return {
-      ok: false,
-      usageError: false,
-      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
-      checks: [],
-    };
-  }
-  try {
-    return JSON.parse(result.stdout);
-  } catch (err) {
-    return {
-      ok: false,
-      usageError: false,
-      reason: `could not parse phase diagnostics output: ${err.message}`,
-      checks: [],
-    };
-  }
-}
-
-export async function run(args) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-  let opts;
-  try {
-    opts = parseDoctorArgs(args);
-  } catch (err) {
-    process.stderr.write(`error: ${err.message}\n`);
-    return 2;
-  }
-  const paths = await resolvePaths();
-  const runtimeResolution = await resolveRuntime({
-    requestedRuntime: opts.runtime,
-    command: "doctor",
-    env: process.env,
-    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
-  });
-  // doctor is an environment diagnostic, not a dispatch path. A failed host
-  // auto-detection only means we cannot attribute the optional skill checks to a
-  // runtime, so degrade it to a warning and keep running the host-independent
-  // checks. Dispatch callers of resolveRuntime stay fail-closed by design — this
-  // leniency lives only here. A failed resolution has no install targets, so
-  // skill checks skip; pass --runtime to include them.
-  const resolvedRuntime = runtimeResolution.ok ? runtimeResolution.resolvedRuntime : null;
-
-  // docker is OPTIONAL for okstra (only the container runtime needs it). Like
-  // runtimeResolution, a missing docker must NOT flip allOk → exit 1, so it lives
-  // in its own variable and is rendered as a single [WARN] line, never pushed into
-  // `results`. Absent → string note; present → null.
-  const dockerWarning = await dockerAvailabilityWarning();
-
-  const results = [
-    await check("python3", checkPython3),
-    await check("okstra_project import", () => checkPythonImport("okstra_project", paths.pythonpath)),
-    await check("okstra_ctl import", () => checkPythonImport("okstra_ctl", paths.pythonpath)),
-    await check("agents dir", async () =>
-      (await fileExists(paths.agents))
-        ? { ok: true, detail: paths.agents }
-        : { ok: false, detail: `not found: ${paths.agents}` },
-    ),
-    await check("bin: okstra.sh", () => checkBashEntry(paths.bin, "okstra.sh")),
-    await check("bin: okstra-codex-exec.sh", () => checkBashEntry(paths.bin, "okstra-codex-exec.sh")),
-    await check("bin: okstra-antigravity-exec.sh", () => checkBashEntry(paths.bin, "okstra-antigravity-exec.sh")),
-    await check("bin: okstra-grok-exec.sh", () => checkBashEntry(paths.bin, "okstra-grok-exec.sh")),
-    await check("bin: okstra-kimi-exec.sh", () => checkBashEntry(paths.bin, "okstra-kimi-exec.sh")),
-    await check("bin: okstra-provider-exec.py", () => checkBashEntry(paths.bin, "okstra-provider-exec.py")),
-    await check("bin: okstra-central.sh", () => checkBashEntry(paths.bin, "okstra-central.sh")),
-    ...(await Promise.all(
-      requiredSkillNamesForRuntime(runtimeResolution.ok ? runtimeResolution : null).map((name) =>
-        check(`skill: ${name}`, async () => {
-          const p = join(CLAUDE_SKILLS_DIR, name, "SKILL.md");
-          return (await fileExists(p))
-            ? { ok: true, detail: p }
-            : { ok: false, detail: `not found: ${p}` };
-        }),
-      ),
-    )),
-    await check("version stamp", async () =>
-      paths.version === paths.package
-        ? { ok: true, detail: paths.version }
-        : { ok: false, detail: `stamp=${paths.version || "(none)"} package=${paths.package}` },
-    ),
-  ];
-
-  let phaseDiagnostics = null;
-  if (opts.phase) {
-    phaseDiagnostics = await loadPhaseDiagnostics(
-      opts.phase,
-      paths,
-      resolvedRuntime,
-    );
-    if (phaseDiagnostics.usageError) {
-      process.stderr.write(`error: ${phaseDiagnostics.reason}\n`);
-      return 2;
-    }
-    results.push(...phaseDiagnosticsToChecks(opts.phase, phaseDiagnostics));
-  }
-
-  const allOk = results.every((r) => r.ok);
-
-  if (opts.jsonMode) {
-    process.stdout.write(
-      `${JSON.stringify({
-        ok: allOk,
-        runtimeRequest: opts.runtime,
-        runtime: resolvedRuntime,
-        runtimeResolution,
-        phase: opts.phase,
-        paths,
-        phaseDiagnostics,
-        dockerWarning,
-        checks: results,
-      }, null, 2)}\n`,
-    );
-    return allOk ? 0 : 1;
-  }
-
-  if (!runtimeResolution.ok) {
-    process.stdout.write(
-      `  [WARN] runtime host: ${runtimeResolution.reason} skill checks skipped — pass --runtime <host-id|alias> to include them.\n`,
-    );
-  }
-  if (dockerWarning) {
-    process.stdout.write(`  [WARN] docker: ${dockerWarning}\n`);
-  }
-  for (const r of results) {
-    const mark = r.ok ? "OK  " : "FAIL";
-    process.stdout.write(`  [${mark}] ${r.name}: ${r.detail}\n`);
-  }
-  process.stdout.write(`\nresult: ${allOk ? "OK" : "FAIL"}\n`);
-  return allOk ? 0 : 1;
-}