karajan-code 2.5.0 → 2.6.1

package/src/commands/doctor.js

@@ -1,393 +1,161 @@
-import { readFileSync } from "node:fs";
-import fs from "node:fs/promises";
-import { fileURLToPath } from "node:url";
-import os from "node:os";
-import path from "node:path";
-import { runCommand } from "../utils/process.js";
-import { exists } from "../utils/fs.js";
-import { getConfigPath } from "../config.js";
-import { isSonarReachable } from "../sonar/manager.js";
-import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
-import { ensureGitRepo } from "../utils/git.js";
-import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
-import { getInstallCommand } from "../utils/os-detect.js";
-import { withDocLink } from "../utils/doc-links.js";
-
-
-function getPackageVersion() {
-  const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
-  return JSON.parse(readFileSync(pkgPath, "utf8")).version;
-}
-
-function checkKarajanVersion() {
-  const version = getPackageVersion();
-  return {
-    name: "karajan",
-    label: "Karajan Code",
-    ok: true,
-    detail: `v${version}`,
-    fix: null
-  };
-}
-
-async function checkConfigFile() {
-  const configPath = getConfigPath();
-  const configExists = await exists(configPath);
-  return {
-    name: "config",
-    label: "Config file",
-    ok: configExists,
-    detail: configExists ? configPath : "Not found",
-    fix: configExists ? null : withDocLink("Run 'kj init' to create the config file.", "config_missing")
-  };
-}
-
-async function checkGitRepo() {
-  let gitOk = false;
-  try {
-    gitOk = await ensureGitRepo();
-  } catch { /* git check failed */
-    gitOk = false;
-  }
-  return {
-    name: "git",
-    label: "Git repository",
-    ok: gitOk,
-    detail: gitOk ? "Inside a git repository" : "Not a git repository",
-    fix: gitOk ? null : "Run 'git init' or navigate to a git-managed project."
-  };
-}
+/**
+ * `kj doctor` command. Runs the unified check runner and prints a
+ * human-readable report by default. Supports flags:
+ *
+ *   --check-only   : only detect, do not apply fixes
+ *   --yes / -y     : auto-confirm prompts for invasive remediations (CI mode)
+ *   --json         : emit machine-readable JSON to stdout
+ *   --verbose      : include fix hints and timing per check
+ *
+ * Exit code is 1 whenever any check ends with FAIL (including remediation
+ * failures). WARN, OK, FIXED, SKIPPED and TIMEOUT do not fail the command.
+ */
 
-async function checkDocker() {
-  const docker = await checkBinary("docker", "--version");
-  return {
-    name: "docker",
-    label: "Docker",
-    ok: docker.ok,
-    detail: docker.ok ? docker.version : "Not found",
-    fix: docker.ok ? null : withDocLink("Install Docker: https://docs.docker.com/get-docker/", "sonar_docker")
-  };
-}
+import readline from "node:readline";
+import { runChecks as runCheckPipeline, toLegacyShape } from "../checks/runner.js";
+import { STATUS } from "../checks/types.js";
+import { getSystemChecks } from "../checks/system.js";
+import { getConfigFileChecks } from "../checks/config-files.js";
+import { getBinaryChecks } from "../checks/binaries.js";
+import { getSonarChecks } from "../checks/sonar.js";
+import { getCiChecks } from "../checks/ci.js";
+import { getRtkChecks } from "../checks/rtk.js";
+import { getNodeChecks } from "../checks/node.js";
+import { getPortChecks } from "../checks/ports.js";
+import { getTokenChecks } from "../checks/tokens.js";
+import { getMcpHealthChecks } from "../checks/mcp-health.js";
+import { getSkillsChecks } from "../checks/skills.js";
+import { getDirSetupChecks } from "../checks/dir-setup.js";
 
-function sonarDetail(config, sonarOk, sonarHost) {
-  if (config.sonarqube?.enabled === false) return "Disabled in config";
-  if (sonarOk) return `Reachable at ${sonarHost}`;
-  return `Not reachable at ${sonarHost}`;
+/**
+ * Build the list of Check objects applicable to the current config.
+ * @param {Object} config
+ * @returns {import("../checks/types.js").Check[]}
+ */
+function buildChecks(config) {
+  return [
+    ...getSystemChecks(),
+    ...getNodeChecks(),
+    ...getDirSetupChecks(),
+    ...getConfigFileChecks(),
+    ...getBinaryChecks(),
+    ...getSonarChecks(),
+    ...getPortChecks(),
+    ...getTokenChecks(config),
+    ...getMcpHealthChecks(),
+    ...getSkillsChecks(),
+    ...getCiChecks(),
+    ...getRtkChecks(),
+  ];
 }
 
-async function checkSonarQube(config) {
-  const sonarHost = config.sonarqube?.host || "http://localhost:9000";
-  let sonarOk = false;
-  if (config.sonarqube?.enabled !== false) {
-    try {
-      sonarOk = await isSonarReachable(sonarHost);
-    } catch { /* sonar check failed */
-      sonarOk = false;
+/**
+ * Interactive terminal confirmation. Returns false when stdin is not a TTY
+ * so non-interactive contexts don't hang forever.
+ *
+ * @param {string} describe
+ * @returns {Promise<boolean>}
+ */
+function confirmViaTty(describe) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) {
+      resolve(false);
+      return;
     }
-  }
-  const isOkOrDisabled = sonarOk || config.sonarqube?.enabled === false;
-  return {
-    name: "sonarqube",
-    label: "SonarQube",
-    ok: isOkOrDisabled,
-    detail: sonarDetail(config, sonarOk, sonarHost),
-    fix: isOkOrDisabled
-      ? null
-      : withDocLink("Run 'kj sonar start' or 'docker start karajan-sonarqube'. Use --no-sonar to skip.", "sonar_docker")
-  };
-}
-
-async function checkAgentCLIs() {
-  const checks = [];
-  for (const agent of KNOWN_AGENTS) {
-    const result = await checkBinary(agent.name);
-    checks.push({
-      name: `agent:${agent.name}`,
-      label: `Agent: ${agent.name}`,
-      ok: result.ok,
-      detail: result.ok ? `${result.version} (${result.path})` : "Not found",
-      fix: result.ok ? null : withDocLink(`Install: ${agent.install}`, "agent_not_found")
-    });
-  }
-  return checks;
-}
-
-async function checkCoreBinaries() {
-  const checks = [];
-  for (const bin of ["node", "npm", "git"]) {
-    const result = await checkBinary(bin);
-    checks.push({
-      name: bin,
-      label: bin,
-      ok: result.ok,
-      detail: result.ok ? result.version : "Not found",
-      fix: result.ok ? null : `Install ${bin} from its official website.`
-    });
-  }
-  return checks;
-}
-
-async function checkSerena() {
-  let serenaOk = false;
-  try {
-    const serenaCheck = await runCommand("serena", ["--version"]);
-    serenaOk = serenaCheck.exitCode === 0;
-  } catch { /* serena not installed */
-    serenaOk = false;
-  }
-  return {
-    name: "serena",
-    label: "Serena MCP",
-    ok: serenaOk,
-    detail: serenaOk ? "Available" : "Not found (prompts will still include Serena instructions)",
-    fix: serenaOk ? null : "Install Serena: uvx --from git+https://github.com/oraios/serena serena --help"
-  };
-}
-
-async function checkCiWorkflows(projectDir) {
-  const checks = [];
-  const workflowDir = path.join(projectDir, ".github", "workflows");
-  const requiredWorkflows = ["kj-ci-gateway.yml", "automerge.yml", "houston-override.yml"];
-  for (const wf of requiredWorkflows) {
-    const wfPath = path.join(workflowDir, wf);
-    const wfExists = await exists(wfPath);
-    checks.push({
-      name: `ci:workflow:${wf}`,
-      label: `CI workflow: ${wf}`,
-      ok: wfExists,
-      detail: wfExists ? "Found" : "Not found",
-      fix: wfExists ? null : `Run 'kj init --scaffold-ci' or copy from karajan-code/templates/workflows/${wf}`
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`? ${describe} [y/N] `, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
     });
-  }
-  return checks;
-}
-
-async function checkCiSecrets() {
-  try {
-    const { detectRepo } = await import("../ci/repo.js");
-    const repo = await detectRepo();
-    if (!repo) return null;
-
-    const secretsRes = await runCommand("gh", ["api", `repos/${repo}/actions/secrets`, "--jq", ".secrets[].name"]);
-    if (secretsRes.exitCode !== 0) return null;
-
-    const names = new Set(secretsRes.stdout.split("\n").map((s) => s.trim()));
-    const hasAppId = names.has("KJ_CI_APP_ID");
-    const hasKey = names.has("KJ_CI_PRIVATE_KEY");
-    const secretsOk = hasAppId && hasKey;
-    const missing = [!hasAppId && "KJ_CI_APP_ID", !hasKey && "KJ_CI_PRIVATE_KEY"].filter(Boolean).join(" ");
-    return {
-      name: "ci:secrets",
-      label: "CI: GitHub secrets",
-      ok: secretsOk,
-      detail: secretsOk ? "KJ_CI_APP_ID + KJ_CI_PRIVATE_KEY found" : `Missing: ${missing}`,
-      fix: secretsOk ? null : "Add KJ_CI_APP_ID and KJ_CI_PRIVATE_KEY as GitHub repository secrets"
-    };
-  } catch { /* GitHub API error */
-    return null;
-  }
-}
-
-async function checkCiInfra(config) {
-  const checks = [];
-  const projectDir = config.projectDir || process.cwd();
-
-  checks.push(...await checkCiWorkflows(projectDir));
-
-  const ghCheck = await checkBinary("gh");
-  checks.push({
-    name: "ci:gh",
-    label: "CI: gh CLI",
-    ok: ghCheck.ok,
-    detail: ghCheck.ok ? ghCheck.version : "Not found",
-    fix: ghCheck.ok ? null : "Install GitHub CLI: https://cli.github.com/"
   });
-
-  const secretsCheck = await checkCiSecrets();
-  if (secretsCheck) checks.push(secretsCheck);
-
-  return checks;
 }
 
-async function checkRtk() {
-  const installCmd = getInstallCommand("rtk");
-  try {
-    const res = await runCommand("rtk", ["--version"]);
-    if (res.exitCode === 0) {
-      return { name: "rtk", label: "RTK (Rust Token Killer)", ok: true, detail: `${res.stdout.trim()} — token savings active`, fix: null };
-    }
-  } catch { /* not installed */ }
-  return {
-    name: "rtk",
-    label: "RTK (Rust Token Killer)",
-    ok: false,
-    detail: "Not found — 60-90% token savings available",
-    fix: withDocLink(`Install: ${installCmd}`, "rtk_install")
-  };
-}
-
-async function checkRuleFiles(config) {
-  const projectDir = config.projectDir || process.cwd();
-  const reviewRules = await loadFirstExisting(resolveRoleMdPath("reviewer", projectDir));
-  const coderRules = await loadFirstExisting(resolveRoleMdPath("coder", projectDir));
-  return [
-    {
-      name: "review-rules",
-      label: "Reviewer rules (.md)",
-      ok: Boolean(reviewRules),
-      detail: reviewRules ? "Found" : "Not found (will use defaults)",
-      fix: null
-    },
-    {
-      name: "coder-rules",
-      label: "Coder rules (.md)",
-      ok: Boolean(coderRules),
-      detail: coderRules ? "Found" : "Not found (will use defaults)",
-      fix: null
-    }
-  ];
+/**
+ * Run the full doctor pipeline without CLI formatting. Consumers that need
+ * the raw report (preflight, status command) should use this.
+ *
+ * @param {{ config: Object, checkOnly?: boolean, yes?: boolean, onConfirm?: Function, logger?: Object }} args
+ * @returns {Promise<import("../checks/types.js").RunReport>}
+ */
+export async function runDoctor({ config, checkOnly = false, yes = false, onConfirm, logger }) {
+  const checks = buildChecks(config);
+  return runCheckPipeline(checks, { config }, {
+    mode: checkOnly ? "check-only" : "fix",
+    yes,
+    onConfirm: onConfirm ?? confirmViaTty,
+    logger,
+  });
 }
 
 /**
- * Detect duplicate TOML table headers (e.g. [mcp_servers."karajan-mcp"] appearing twice).
- * Full TOML parsing would require a dependency — this catches the most common config error.
+ * Legacy shape (backwards-compat for callers that still expect
+ * {name,label,ok,detail,fix}). Kept public because tests and the CI gate
+ * still rely on it.
+ *
+ * @param {{ config: Object }} args
  */
-function findDuplicateTomlKeys(content) {
-  const tableHeaders = [];
-  const duplicates = [];
-  for (const line of content.split("\n")) {
-    const match = line.match(/^\s*\[([^\]]+)\]\s*$/);
-    if (match) {
-      const key = match[1].trim();
-      if (tableHeaders.includes(key)) {
-        duplicates.push(key);
-      } else {
-        tableHeaders.push(key);
-      }
-    }
-  }
-  return duplicates;
+export async function runChecks({ config }) {
+  const report = await runDoctor({ config });
+  return toLegacyShape(report);
 }
 
-async function checkAgentConfigs() {
-  const checks = [];
-  const home = os.homedir();
-
-  // Claude: ~/.claude.json
-  const claudeJsonPath = path.join(home, ".claude.json");
-  try {
-    const raw = await fs.readFile(claudeJsonPath, "utf8");
-    JSON.parse(raw);
-    checks.push({ name: "agent-config:claude", label: "Agent config: claude (~/.claude.json)", ok: true, detail: "Valid JSON", fix: null });
-  } catch (err) {
-    if (err.code === "ENOENT") {
-      // File doesn't exist — not an error, Claude may not be configured
-    } else {
-      checks.push({
-        name: "agent-config:claude",
-        label: "Agent config: claude (~/.claude.json)",
-        ok: false,
-        detail: `Invalid JSON: ${err.message.split("\n")[0]}`,
-        fix: "Fix the JSON syntax in ~/.claude.json. Common issues: trailing commas, missing quotes."
-      });
-    }
-  }
-
-  // Codex: ~/.codex/config.toml
-  const codexTomlPath = path.join(home, ".codex", "config.toml");
-  try {
-    const raw = await fs.readFile(codexTomlPath, "utf8");
-    const duplicates = findDuplicateTomlKeys(raw);
-    if (duplicates.length > 0) {
-      checks.push({
-        name: "agent-config:codex",
-        label: "Agent config: codex (~/.codex/config.toml)",
-        ok: false,
-        detail: `Duplicate TOML keys: ${duplicates.join(", ")}`,
-        fix: `Remove duplicate entries in ~/.codex/config.toml: ${duplicates.join(", ")}`
-      });
-    } else {
-      checks.push({ name: "agent-config:codex", label: "Agent config: codex (~/.codex/config.toml)", ok: true, detail: "Valid TOML (no duplicate keys)", fix: null });
-    }
-  } catch (err) {
-    if (err.code !== "ENOENT") {
-      checks.push({
-        name: "agent-config:codex",
-        label: "Agent config: codex (~/.codex/config.toml)",
-        ok: false,
-        detail: `Cannot read: ${err.message.split("\n")[0]}`,
-        fix: "Check file permissions on ~/.codex/config.toml"
-      });
-    }
-  }
+/**
+ * `kj doctor` CLI entrypoint. Returns the exit code (0 OK, 1 when FAIL).
+ *
+ * @param {{ config: Object, checkOnly?: boolean, yes?: boolean, json?: boolean, verbose?: boolean }} args
+ * @returns {Promise<number>}
+ */
+export async function doctorCommand({ config, checkOnly = false, yes = false, json = false, verbose = false }) {
+  const report = await runDoctor({ config, checkOnly, yes });
 
-  // KJ config: ~/.karajan/kj.config.yml (validate YAML)
-  const kjConfigPath = getConfigPath();
-  try {
-    const raw = await fs.readFile(kjConfigPath, "utf8");
-    const yaml = await import("js-yaml");
-    yaml.default.load(raw);
-    checks.push({ name: "agent-config:karajan", label: "Agent config: karajan (kj.config.yml)", ok: true, detail: "Valid YAML", fix: null });
-  } catch (err) {
-    if (err.code !== "ENOENT") {
-      checks.push({
-        name: "agent-config:karajan",
-        label: "Agent config: karajan (kj.config.yml)",
-        ok: false,
-        detail: `Invalid YAML: ${err.message.split("\n")[0]}`,
-        fix: `Fix YAML syntax in ${kjConfigPath}. Run 'kj init' to regenerate if needed.`
-      });
-    }
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printHuman(report, { verbose });
   }
 
-  return checks;
+  return hasBlockingFailure(report) ? 1 : 0;
 }
 
-export async function runChecks({ config }) {
-  const checks = [];
-
-  checks.push(
-    checkKarajanVersion(),
-    await checkConfigFile(),
-    await checkGitRepo(),
-    await checkDocker(),
-    await checkSonarQube(config),
-    ...await checkAgentCLIs(),
-    ...await checkCoreBinaries()
-  );
-
-  if (config.serena?.enabled) {
-    checks.push(await checkSerena());
-  }
+function hasBlockingFailure(report) {
+  return report.checks.some((c) => c.status === STATUS.FAIL || c.status === STATUS.TIMEOUT);
+}
 
-  if (config.ci?.enabled) {
-    checks.push(...await checkCiInfra(config));
+function statusIcon(status) {
+  switch (status) {
+    case STATUS.OK: return "OK   ";
+    case STATUS.FIXED: return "FIXED";
+    case STATUS.WARN: return "WARN ";
+    case STATUS.FAIL: return "FAIL ";
+    case STATUS.SKIPPED: return "SKIP ";
+    case STATUS.TIMEOUT: return "TIME ";
+    default: return "?    ";
   }
-
-  checks.push(...await checkAgentConfigs());
-  checks.push(...await checkRuleFiles(config));
-  checks.push(await checkRtk());
-
-  return checks;
 }
 
-export async function doctorCommand({ config }) {
-  const checks = await runChecks({ config });
-
-  for (const check of checks) {
-    const icon = check.ok ? "OK  " : "MISS";
-    console.log(`${icon} ${check.label}: ${check.detail}`);
-    if (check.fix) {
+function printHuman(report, { verbose }) {
+  for (const check of report.checks) {
+    console.log(`${statusIcon(check.status)} ${check.label}: ${check.detail}`);
+    if (check.fix && (check.status === STATUS.FAIL || check.status === STATUS.WARN || verbose)) {
       console.log(`     -> ${check.fix}`);
     }
+    if (verbose) {
+      console.log(`     (${check.runMs}ms, strategy=${check.strategy})`);
+    }
   }
 
-  const failures = checks.filter((c) => !c.ok && c.fix);
-  if (failures.length === 0) {
-    console.log("\nAll checks passed.");
+  const s = report.summary;
+  const total = s.ok + s.fixed + s.warn + s.fail + s.skipped + s.timeout;
+  console.log();
+  if (s.fail === 0 && s.timeout === 0) {
+    const label = s.fixed > 0 ? `All checks passed (${s.fixed} auto-fixed)` : "All checks passed.";
+    console.log(label);
   } else {
-    console.log(`\n${failures.length} issue(s) found.`);
+    console.log(
+      `${s.fail + s.timeout} issue(s) found, ${s.fixed} auto-fixed, ${s.warn} warnings, ${s.skipped} skipped out of ${total}.`
+    );
+  }
+  if (Object.keys(report.overrides).length > 0) {
+    console.log(`Runtime overrides applied: ${JSON.stringify(report.overrides)}`);
   }
-
-  return checks;
 }

package/src/commands/resume.js

@@ -2,7 +2,7 @@ import { EventEmitter } from "node:events";
 import readline from "node:readline";
 import { resumeFlow } from "../orchestrator.js";
 import { createActivityLog } from "../activity-log.js";
-import { printEvent } from "../utils/display.js";
+import { printEvent } from "../utils/display/event-handlers.js";
 
 function createCliAskQuestion() {
   return async (question, context) => {

package/src/commands/run.js

@@ -3,7 +3,8 @@ import readline from "node:readline";
 import { runFlow } from "../orchestrator.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { createActivityLog } from "../activity-log.js";
-import { printHeader, printEvent } from "../utils/display.js";
+import { printHeader } from "../utils/display/header.js";
+import { printEvent } from "../utils/display/event-handlers.js";
 import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 

package/src/commands/skills.js

@@ -0,0 +1,49 @@
+/**
+ * `kj skills` — manage the local OpenSkills cache.
+ *
+ * Subcommands:
+ *   - list         : print cached skills with their age and freshness.
+ *   - clear-cache  : delete all cached metadata (forces re-install on next session).
+ */
+
+import { listCached, clearCache, getCacheRoot, DEFAULT_TTL_MS } from "../skills/skills-cache.js";
+
+function humanAge(cachedAt) {
+  const ms = Date.now() - Date.parse(cachedAt);
+  if (!Number.isFinite(ms) || ms < 0) return "unknown";
+  const days = ms / (24 * 60 * 60 * 1000);
+  if (days < 1) return `${Math.max(1, Math.round(ms / (60 * 60 * 1000)))}h ago`;
+  return `${days.toFixed(1)}d ago`;
+}
+
+export async function skillsCommand({ action = "list" } = {}) {
+  switch (action) {
+    case "list":
+      return listAction();
+    case "clear-cache":
+      return clearAction();
+    default:
+      console.error(`Unknown action: ${action}. Use: list | clear-cache`);
+      return 1;
+  }
+}
+
+async function listAction() {
+  const cache = await listCached();
+  if (cache.length === 0) {
+    console.log(`No cached skills at ${getCacheRoot()}`);
+    return 0;
+  }
+  console.log(`Cached skills (TTL ${Math.round(DEFAULT_TTL_MS / 86400000)}d) at ${getCacheRoot()}:\n`);
+  for (const entry of cache) {
+    const flag = entry.fresh ? "FRESH" : "STALE";
+    console.log(`  ${flag}  ${entry.name}  (${humanAge(entry.cachedAt)})`);
+  }
+  return 0;
+}
+
+async function clearAction() {
+  const { removed } = await clearCache();
+  console.log(`Cleared ${removed} cached skill${removed === 1 ? "" : "s"} from ${getCacheRoot()}`);
+  return 0;
+}