karajan-code 2.5.0 → 2.6.1

package/src/checks/ci.js

@@ -0,0 +1,105 @@
+/**
+ * CI infrastructure checks: required workflows, gh CLI, and GitHub secrets.
+ * Only applies when `config.ci.enabled === true`.
+ */
+
+import path from "node:path";
+import { exists } from "../utils/fs.js";
+import { runCommand } from "../utils/process.js";
+import { checkBinary } from "../utils/agent-detect.js";
+import { STRATEGY } from "./types.js";
+
+const REQUIRED_WORKFLOWS = ["kj-ci-gateway.yml", "automerge.yml", "houston-override.yml"];
+
+function ciEnabled(config) {
+  return config.ci?.enabled === true;
+}
+
+function createWorkflowCheck(workflow) {
+  return {
+    name: `ci:workflow:${workflow}`,
+    label: `CI workflow: ${workflow}`,
+    strategy: STRATEGY.MANUAL,
+    applies: ciEnabled,
+    async detect({ config }) {
+      const projectDir = config.projectDir || process.cwd();
+      const wfPath = path.join(projectDir, ".github", "workflows", workflow);
+      const wfExists = await exists(wfPath);
+      return {
+        ok: wfExists,
+        severity: "fail",
+        detail: wfExists ? "Found" : "Not found",
+        fix: wfExists
+          ? undefined
+          : `Run 'kj init --scaffold-ci' or copy from karajan-code/templates/workflows/${workflow}`,
+      };
+    },
+  };
+}
+
+export function createGhCliCheck() {
+  return {
+    name: "ci:gh",
+    label: "CI: gh CLI",
+    strategy: STRATEGY.MANUAL,
+    applies: ciEnabled,
+    async detect() {
+      const gh = await checkBinary("gh");
+      return {
+        ok: gh.ok,
+        severity: "fail",
+        detail: gh.ok ? gh.version : "Not found",
+        fix: gh.ok ? undefined : "Install GitHub CLI: https://cli.github.com/",
+      };
+    },
+  };
+}
+
+export function createGhSecretsCheck() {
+  return {
+    name: "ci:secrets",
+    label: "CI: GitHub secrets",
+    strategy: STRATEGY.MANUAL,
+    applies: ciEnabled,
+    async detect() {
+      try {
+        const { detectRepo } = await import("../ci/repo.js");
+        const repo = await detectRepo();
+        if (!repo) {
+          return { ok: true, severity: "info", detail: "No GitHub repo detected (skipped)" };
+        }
+        const res = await runCommand("gh", ["api", `repos/${repo}/actions/secrets`, "--jq", ".secrets[].name"]);
+        if (res.exitCode !== 0) {
+          return { ok: true, severity: "info", detail: "Cannot query secrets (gh unauthenticated?)" };
+        }
+        const names = new Set(res.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 {
+          ok: secretsOk,
+          severity: "fail",
+          detail: secretsOk ? "KJ_CI_APP_ID + KJ_CI_PRIVATE_KEY found" : `Missing: ${missing}`,
+          fix: secretsOk ? undefined : "Add KJ_CI_APP_ID and KJ_CI_PRIVATE_KEY as GitHub repository secrets",
+        };
+      } catch {
+        return { ok: true, severity: "info", detail: "Cannot check secrets (unexpected error, skipped)" };
+      }
+    },
+  };
+}
+
+/**
+ * Aggregate of CI checks. Each check carries its own `applies` so the runner
+ * marks them SKIPPED when CI is disabled.
+ */
+export function getCiChecks() {
+  const checks = [];
+  for (const wf of REQUIRED_WORKFLOWS) {
+    checks.push(createWorkflowCheck(wf));
+  }
+  checks.push(createGhCliCheck());
+  checks.push(createGhSecretsCheck());
+  return checks;
+}

package/src/checks/config-files.js

@@ -0,0 +1,217 @@
+/**
+ * Config and rule-file checks.
+ *
+ * Covers:
+ *   - kj.config.yml existence (strategy: prompt — offer to run kj init)
+ *   - Review / coder rules discovery (strategy: none, informational)
+ *   - Agent config files: ~/.claude.json, ~/.codex/config.toml,
+ *     ~/.karajan/kj.config.yml (strategy: manual — structural fixes needed)
+ */
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { exists } from "../utils/fs.js";
+import { getConfigPath } from "../config.js";
+import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
+import { withDocLink } from "../utils/doc-links.js";
+import { STRATEGY } from "./types.js";
+
+/**
+ * kj.config.yml presence check.
+ */
+export function createConfigFileCheck() {
+  return {
+    name: "config",
+    label: "Config file",
+    strategy: STRATEGY.PROMPT,
+    describe: "Run 'kj init' to scaffold a default kj.config.yml",
+    async detect() {
+      const configPath = getConfigPath();
+      const configExists = await exists(configPath);
+      return {
+        ok: configExists,
+        severity: "fail",
+        detail: configExists ? configPath : "Not found",
+        fix: configExists ? undefined : withDocLink("Run 'kj init' to create the config file.", "config_missing"),
+      };
+    },
+  };
+}
+
+/**
+ * Review rules (.md) informational check.
+ */
+export function createReviewRulesCheck() {
+  return {
+    name: "review-rules",
+    label: "Reviewer rules (.md)",
+    strategy: STRATEGY.NONE,
+    async detect({ config }) {
+      const projectDir = config.projectDir || process.cwd();
+      const paths = resolveRoleMdPath("reviewer", projectDir);
+      const rules = await loadFirstExisting(paths);
+      return {
+        ok: true,
+        severity: "info",
+        detail: rules ? "Found" : "Not found (will use defaults)",
+      };
+    },
+  };
+}
+
+/**
+ * Coder rules (.md) informational check.
+ */
+export function createCoderRulesCheck() {
+  return {
+    name: "coder-rules",
+    label: "Coder rules (.md)",
+    strategy: STRATEGY.NONE,
+    async detect({ config }) {
+      const projectDir = config.projectDir || process.cwd();
+      const paths = resolveRoleMdPath("coder", projectDir);
+      const rules = await loadFirstExisting(paths);
+      return {
+        ok: true,
+        severity: "info",
+        detail: rules ? "Found" : "Not found (will use defaults)",
+      };
+    },
+  };
+}
+
+/**
+ * Detect duplicate TOML table headers (e.g. [mcp_servers."karajan-mcp"] twice).
+ */
+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;
+}
+
+/**
+ * Claude config (~/.claude.json) validity.
+ */
+export function createClaudeConfigCheck() {
+  return {
+    name: "agent-config:claude",
+    label: "Agent config: claude (~/.claude.json)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const home = os.homedir();
+      const claudeJsonPath = path.join(home, ".claude.json");
+      try {
+        const raw = await fs.readFile(claudeJsonPath, "utf8");
+        JSON.parse(raw);
+        return { ok: true, severity: "info", detail: "Valid JSON" };
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          // Not configured: Claude may not be in use. Informational skip.
+          return { ok: true, severity: "info", detail: "Not present (skipped)" };
+        }
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `Invalid JSON: ${err.message.split("\n")[0]}`,
+          fix: "Fix the JSON syntax in ~/.claude.json. Common issues: trailing commas, missing quotes.",
+        };
+      }
+    },
+  };
+}
+
+/**
+ * Codex config (~/.codex/config.toml) validity.
+ */
+export function createCodexConfigCheck() {
+  return {
+    name: "agent-config:codex",
+    label: "Agent config: codex (~/.codex/config.toml)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const home = os.homedir();
+      const codexTomlPath = path.join(home, ".codex", "config.toml");
+      try {
+        const raw = await fs.readFile(codexTomlPath, "utf8");
+        const duplicates = findDuplicateTomlKeys(raw);
+        if (duplicates.length > 0) {
+          return {
+            ok: false,
+            severity: "warn",
+            detail: `Duplicate TOML keys: ${duplicates.join(", ")}`,
+            fix: `Remove duplicate entries in ~/.codex/config.toml: ${duplicates.join(", ")}`,
+          };
+        }
+        return { ok: true, severity: "info", detail: "Valid TOML (no duplicate keys)" };
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          return { ok: true, severity: "info", detail: "Not present (skipped)" };
+        }
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `Cannot read: ${err.message.split("\n")[0]}`,
+          fix: "Check file permissions on ~/.codex/config.toml",
+        };
+      }
+    },
+  };
+}
+
+/**
+ * KJ config (~/.karajan/kj.config.yml) YAML validity (separate from existence).
+ */
+export function createKjConfigYamlCheck() {
+  return {
+    name: "agent-config:karajan",
+    label: "Agent config: karajan (kj.config.yml)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const kjConfigPath = getConfigPath();
+      try {
+        const raw = await fs.readFile(kjConfigPath, "utf8");
+        const yaml = await import("js-yaml");
+        yaml.default.load(raw);
+        return { ok: true, severity: "info", detail: "Valid YAML" };
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          // Covered by createConfigFileCheck — don't duplicate the failure
+          return { ok: true, severity: "info", detail: "Not present (covered by config check)" };
+        }
+        return {
+          ok: false,
+          severity: "fail",
+          detail: `Invalid YAML: ${err.message.split("\n")[0]}`,
+          fix: `Fix YAML syntax in ${kjConfigPath}. Run 'kj init' to regenerate if needed.`,
+        };
+      }
+    },
+  };
+}
+
+/**
+ * Aggregate: all config-file-related checks.
+ * @returns {import("./types.js").Check[]}
+ */
+export function getConfigFileChecks() {
+  return [
+    createConfigFileCheck(),
+    createReviewRulesCheck(),
+    createCoderRulesCheck(),
+    createClaudeConfigCheck(),
+    createCodexConfigCheck(),
+    createKjConfigYamlCheck(),
+  ];
+}

package/src/checks/dir-setup.js

@@ -0,0 +1,63 @@
+/**
+ * Ensure ~/.karajan/ directory tree exists. Strategy: auto — creating
+ * directories under the user's home is non-invasive.
+ */
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { STRATEGY } from "./types.js";
+
+const REQUIRED_DIRS = [
+  "", // ~/.karajan/
+  "sessions",
+  "skills-cache",
+  "logs",
+];
+
+export function createKarajanDirsCheck() {
+  return {
+    name: "karajan-dirs",
+    label: "~/.karajan directory tree",
+    strategy: STRATEGY.AUTO,
+    describe: "Create missing ~/.karajan subdirectories",
+    async detect() {
+      const home = os.homedir();
+      const root = path.join(home, ".karajan");
+      const missing = [];
+      for (const sub of REQUIRED_DIRS) {
+        const full = sub ? path.join(root, sub) : root;
+        try {
+          const stat = await fs.stat(full);
+          if (!stat.isDirectory()) missing.push(full);
+        } catch {
+          missing.push(full);
+        }
+      }
+      if (missing.length === 0) {
+        return { ok: true, severity: "info", detail: `All ${REQUIRED_DIRS.length} directories present under ${root}` };
+      }
+      return {
+        ok: false,
+        severity: "fail",
+        detail: `Missing: ${missing.map((m) => path.relative(home, m)).join(", ")}`,
+        fix: `mkdir -p ${missing.join(" ")}`,
+        extra: { missing },
+      };
+    },
+    async remediate({ extra }) {
+      const missing = extra?.missing || [];
+      for (const dir of missing) {
+        await fs.mkdir(dir, { recursive: true });
+      }
+      return {
+        fixed: true,
+        detail: `Created ${missing.length} director${missing.length === 1 ? "y" : "ies"} under ~/.karajan`,
+      };
+    },
+  };
+}
+
+export function getDirSetupChecks() {
+  return [createKarajanDirsCheck()];
+}

package/src/checks/mcp-health.js

@@ -0,0 +1,157 @@
+/**
+ * MCP server health checks.
+ *
+ * Karajan integrates with several MCP servers — karajan-mcp (stdio), Serena,
+ * Sonar MCP, Planning Game MCP, etc. This module verifies they respond to
+ * a minimal JSON-RPC `initialize` call within a short deadline.
+ *
+ * For stdio MCPs that Karajan spawns itself (karajan-mcp), a failed ping is
+ * auto-remediable by re-spawning. External MCPs (Serena) are warn-only.
+ */
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { STRATEGY } from "./types.js";
+import { withTimeout, TimeoutError } from "../utils/with-timeout.js";
+import { checkBinary } from "../utils/agent-detect.js";
+
+const PING_TIMEOUT_MS = 3000;
+
+/**
+ * Send a JSON-RPC `initialize` to an MCP server over stdio and wait for
+ * any response. Kills the process immediately after.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {Promise<{ok: boolean, detail: string}>}
+ */
+async function pingMcpStdio(command, args) {
+  const handshake = () =>
+    new Promise((resolve) => {
+      let child;
+      try {
+        child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+      } catch (err) {
+        resolve({ ok: false, detail: `spawn failed: ${err.message}` });
+        return;
+      }
+      let settled = false;
+      const finish = (ok, detail) => {
+        if (settled) return;
+        settled = true;
+        try {
+          child.kill();
+        } catch { /* already exited */ }
+        resolve({ ok, detail });
+      };
+      child.on("error", (err) => finish(false, `process error: ${err.message}`));
+      child.on("exit", (code) => {
+        if (!settled) finish(false, `exited with code ${code} before response`);
+      });
+      child.stdout.on("data", (buf) => {
+        const text = buf.toString();
+        // Any JSON-RPC response line counts as alive.
+        if (text.includes("\"jsonrpc\"") || text.includes("\"result\"") || text.includes("\"error\"")) {
+          finish(true, "Responded to initialize");
+        }
+      });
+      // Send initialize request
+      const req = JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: "2024-11-05",
+          clientInfo: { name: "kj-doctor", version: "1.0.0" },
+          capabilities: {},
+        },
+      });
+      try {
+        child.stdin.write(req + "\n");
+      } catch (err) {
+        finish(false, `stdin write failed: ${err.message}`);
+      }
+    });
+  try {
+    return await withTimeout(handshake(), PING_TIMEOUT_MS, "mcp-ping");
+  } catch (err) {
+    if (err instanceof TimeoutError) {
+      return { ok: false, detail: `No response within ${PING_TIMEOUT_MS}ms` };
+    }
+    return { ok: false, detail: err.message };
+  }
+}
+
+/**
+ * karajan-mcp health — stdio server bundled with this package.
+ * Strategy: auto (we can re-spawn it ourselves).
+ */
+export function createKarajanMcpCheck() {
+  return {
+    name: "mcp:karajan",
+    label: "MCP: karajan-mcp",
+    strategy: STRATEGY.AUTO,
+    describe: "Respawn karajan-mcp stdio process",
+    async detect() {
+      const binPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../bin/karajan-mcp.js");
+      const result = await pingMcpStdio(process.execPath, [binPath]);
+      return {
+        ok: result.ok,
+        severity: result.ok ? "info" : "warn",
+        detail: result.ok ? result.detail : `karajan-mcp did not respond: ${result.detail}`,
+        fix: result.ok ? undefined : "Re-run karajan-mcp via `node bin/karajan-mcp.js`",
+        extra: { binPath },
+      };
+    },
+    async remediate({ extra }) {
+      // Spawn once detached so the MCP client can pick it up for subsequent runs.
+      // This is idempotent: if one instance is already listening, another will
+      // coexist over a different pipe.
+      try {
+        spawn(process.execPath, [extra.binPath], { detached: true, stdio: "ignore" }).unref();
+        return { fixed: true, detail: "Re-spawned karajan-mcp in background" };
+      } catch (err) {
+        return { fixed: false, detail: `Failed to respawn: ${err.message}` };
+      }
+    },
+  };
+}
+
+/**
+ * Serena MCP — external tool the user installs themselves. Warn only when
+ * enabled in config. Strategy: manual (we don't manage its lifecycle).
+ */
+export function createSerenaMcpCheck() {
+  return {
+    name: "mcp:serena",
+    label: "MCP: serena",
+    strategy: STRATEGY.MANUAL,
+    applies: (config) => config?.serena?.enabled === true,
+    async detect() {
+      const bin = await checkBinary("serena");
+      if (!bin.ok) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: "serena binary not on PATH",
+          fix: "Install Serena: uvx --from git+https://github.com/oraios/serena serena",
+        };
+      }
+      const result = await pingMcpStdio("serena", ["start", "--mcp"]);
+      return {
+        ok: result.ok,
+        severity: result.ok ? "info" : "warn",
+        detail: result.ok ? "Serena responded to initialize" : `No response: ${result.detail}`,
+        fix: result.ok ? undefined : "Restart Serena manually and verify connectivity.",
+      };
+    },
+  };
+}
+
+/**
+ * Aggregate of MCP health checks. Only enabled servers run their ping.
+ */
+export function getMcpHealthChecks() {
+  return [createKarajanMcpCheck(), createSerenaMcpCheck()];
+}

package/src/checks/node.js

@@ -0,0 +1,61 @@
+/**
+ * Node.js runtime version check. Requires Node >= 20 (minimum version that
+ * ships structuredClone, Array.prototype.findLast, AbortSignal.timeout, and
+ * stable fetch). Strategy: manual — we cannot auto-upgrade the runtime.
+ */
+
+import { STRATEGY } from "./types.js";
+
+export const MIN_NODE_MAJOR = 20;
+
+/**
+ * Accepts a version string in the form "v20.12.1" or "20.12.1" and returns
+ * an object { major, minor, patch } or null when the shape is invalid.
+ */
+export function parseNodeVersion(versionString) {
+  const str = String(versionString || "").trim();
+  const m = str.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+
+/**
+ * Create the Node version check. Accepts an optional override of the
+ * reported version (useful in tests).
+ *
+ * @param {{ version?: string }} [opts]
+ * @returns {import("./types.js").Check}
+ */
+export function createNodeVersionCheck(opts = {}) {
+  return {
+    name: "node-version",
+    label: "Node.js runtime",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const raw = opts.version ?? process.env.KJ_FORCE_NODE_VERSION ?? process.version;
+      const parsed = parseNodeVersion(raw);
+      if (!parsed) {
+        return {
+          ok: false,
+          severity: "fail",
+          detail: `Unrecognized Node version: ${raw}`,
+          fix: `Install Node ${MIN_NODE_MAJOR}+ from https://nodejs.org/ (current: ${raw}).`,
+        };
+      }
+      if (parsed.major < MIN_NODE_MAJOR) {
+        return {
+          ok: false,
+          severity: "fail",
+          detail: `Node ${raw} detected, requires >=${MIN_NODE_MAJOR}`,
+          fix: `Upgrade Node to ${MIN_NODE_MAJOR}+ (nvm install ${MIN_NODE_MAJOR} && nvm use ${MIN_NODE_MAJOR}, or brew upgrade node).`,
+          extra: { detected: parsed, required: MIN_NODE_MAJOR },
+        };
+      }
+      return { ok: true, severity: "info", detail: `${raw} (>= ${MIN_NODE_MAJOR} required)` };
+    },
+  };
+}
+
+export function getNodeChecks() {
+  return [createNodeVersionCheck()];
+}