@karajan-family/code 4.21.0

package/src/checks/ai-surface.js

@@ -0,0 +1,79 @@
+/**
+ * ai-surface — MCP inventory with drift detection (KJC-TSK-0694).
+ *
+ * Every new tool an agent gains is one more access. An inventory nobody
+ * reconciles is "the feeling of control without the control", so kj check
+ * flags what APPEARED since the last run and asks the user to own it.
+ * A nudge, never a gate. ~/.claude.json is scoped to its global block plus
+ * THIS project's entry — other projects' MCPs are not reachable here.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const sources = (projectDir, home) => [
+  { file: path.join(projectDir, ".mcp.json"), format: "json" },
+  { file: path.join(home, ".claude.json"), format: "json" },
+  { file: path.join(home, ".codex", "config.toml"), format: "toml" },
+  { file: path.join(home, ".gemini", "settings.json"), format: "json" },
+];
+
+function jsonServerNames(text, projectDir) {
+  try {
+    const parsed = JSON.parse(text);
+    const names = new Set(Object.keys(parsed.mcpServers || {}));
+    for (const name of Object.keys(parsed.projects?.[projectDir]?.mcpServers || {})) names.add(name);
+    return names;
+  } catch {
+    return new Set();
+  }
+}
+
+const tomlServerNames = (text) =>
+  new Set([...text.matchAll(/^\s*\[mcp_servers\.["']?([^\]"']+)["']?\]/gm)].map((m) => m[1]));
+
+/** Sorted `name (config-file)` entries for every MCP reachable in this project. */
+export function collectAiSurface({ projectDir = process.cwd(), home = os.homedir() } = {}) {
+  const surface = new Set();
+  for (const { file, format } of sources(projectDir, home)) {
+    if (!existsSync(file)) continue;
+    let text;
+    try { text = readFileSync(file, "utf8"); } catch { continue; }
+    const names = format === "toml" ? tomlServerNames(text) : jsonServerNames(text, projectDir);
+    for (const name of names) surface.add(`${name} (${path.basename(file)})`);
+  }
+  return [...surface].sort();
+}
+
+/**
+ * Diff the current surface against the last-seen snapshot and persist the
+ * new state. First run records the baseline silently.
+ */
+export function checkAiSurface({ projectDir = process.cwd(), home = os.homedir(), statePath = path.join(os.homedir(), ".karajan", "ai-surface.json"), extraSurface = [] } = {}) {
+  // KJC-TSK-0728: extraSurface carries entries the (async) caller collected
+  // outside config files — e.g. observed agent CLIs as "grok (cli)" — so
+  // they ride the same snapshot and the same "NEW since last check" drift.
+  const surface = [...new Set([...collectAiSurface({ projectDir, home }), ...extraSurface])].sort();
+  let state = {};
+  try { state = JSON.parse(readFileSync(statePath, "utf8")); } catch { /* first run or corrupt → baseline */ }
+  const prev = Array.isArray(state[projectDir]) ? state[projectDir] : null;
+  const added = prev ? surface.filter((e) => !prev.includes(e)) : [];
+  const removed = prev ? prev.filter((e) => !surface.includes(e)) : [];
+  state[projectDir] = surface;
+  try {
+    mkdirSync(path.dirname(statePath), { recursive: true });
+    writeFileSync(statePath, JSON.stringify(state, null, 2));
+  } catch { /* read-only FS — inventory still reports, just cannot remember */ }
+  return { surface, added, removed, first: !prev };
+}
+
+/** One line for kj check output. */
+export function formatAiSurface({ surface, added, removed, first }) {
+  const head = `ai surface: ${surface.length} MCP(s)`;
+  if (first) return `${head} — baseline recorded`;
+  const parts = [head];
+  if (added.length) parts.push(`NEW since last check: ${added.join(", ")} — approved by you?`);
+  if (removed.length) parts.push(`gone: ${removed.join(", ")}`);
+  return parts.join(" · ");
+}

package/src/checks/ai-trash.js

@@ -0,0 +1,34 @@
+/**
+ * ai-trash safety net availability check (KJC-TSK-0391).
+ * Surfaces a WARN in `kj doctor` when the `kj-trash` binary is missing,
+ * since the PreToolUse hook cannot snapshot destructive ops without it.
+ * The remediation is `kj-trash install --claude-code` once the binary is
+ * on PATH (the workspace ships it with karajan-code).
+ */
+
+import { detectAiTrash } from "../utils/ai-trash.js";
+import { STRATEGY } from "./types.js";
+
+function createAiTrashCheck() {
+  return {
+    name: "ai-trash",
+    label: "ai-trash safety net",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const res = await detectAiTrash();
+      if (res.available) {
+        return { ok: true, severity: "info", detail: "kj-trash present — preventive safety net active" };
+      }
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "kj-trash not found — destructive ops unprotected",
+        fix: "Install karajan-code globally (npm i -g karajan-code) so kj-trash is on PATH, then run `kj-trash install --claude-code`",
+      };
+    },
+  };
+}
+
+export function getAiTrashChecks() {
+  return [createAiTrashCheck()];
+}

package/src/checks/binaries.js

@@ -0,0 +1,207 @@
+/**
+ * Binary / CLI availability checks.
+ *
+ * Covers:
+ *   - Agent CLIs (claude, codex, gemini, aider, opencode)
+ *   - Core binaries (node, npm, git)
+ *   - Docker
+ *   - Serena MCP (optional)
+ *
+ * All binary checks use `strategy: "manual"` because auto-installing binaries
+ * is invasive and platform-specific. Exception: Serena is `"prompt"` (we know
+ * the install command and can offer to run it).
+ */
+
+import { checkBinary, KNOWN_AGENTS, detectObservedAgents } from "../utils/agent-detect.js";
+import { runCommand } from "../utils/process.js";
+import { withDocLink } from "../utils/doc-links.js";
+import { getInstallHint, appliesToStack } from "../utils/install-hints.js";
+import { STRATEGY } from "./types.js";
+
+/**
+ * Check the presence of a named agent CLI (claude/codex/gemini/aider).
+ */
+function createAgentCheck(agent) {
+  return {
+    name: `agent:${agent.name}`,
+    label: `Agent: ${agent.name}`,
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const result = await checkBinary(agent.name);
+      return {
+        ok: result.ok,
+        severity: "warn", // missing one agent CLI shouldn't block — user may not use it
+        detail: result.ok ? `${result.version} (${result.path})` : "Not found",
+        fix: result.ok ? undefined : withDocLink(`Install: ${agent.install}`, "agent_not_found"),
+      };
+    },
+  };
+}
+
+/**
+ * KJC-TSK-0728 — ONE aggregate line for the observation census (agent CLIs
+ * kj sees but does not drive). Only FOUND CLIs are listed; the missing ones
+ * make no noise, and the check never fails. `detector` is injectable for
+ * tests.
+ */
+export function createObservedAgentsCheck({ detector = detectObservedAgents } = {}) {
+  return {
+    name: "agents:observed",
+    label: "Agent CLIs observed (not driven)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      let found = [];
+      try {
+        found = (await detector()).filter((a) => a.available);
+      } catch { /* census is best-effort */ }
+      return {
+        ok: true,
+        severity: "info",
+        detail: found.length
+          ? found.map((a) => `${a.name} (${(a.version || "").split(" ").at(-1) || "?"})`).join(", ")
+          : "none detected",
+      };
+    },
+  };
+}
+
+/**
+ * Check the presence of a core binary (node, npm, git).
+ */
+function createCoreBinaryCheck(bin) {
+  return {
+    name: bin,
+    label: bin,
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const result = await checkBinary(bin);
+      return {
+        ok: result.ok,
+        severity: "fail",
+        detail: result.ok ? result.version : "Not found",
+        fix: result.ok ? undefined : `Install ${bin} from its official website.`,
+      };
+    },
+  };
+}
+
+/**
+ * Docker check. Manual strategy (platform-dependent install).
+ */
+function createDockerCheck() {
+  return {
+    name: "docker",
+    label: "Docker",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const docker = await checkBinary("docker", "--version");
+      return {
+        ok: docker.ok,
+        severity: "warn", // only required if Sonar enabled; soft-fail here
+        detail: docker.ok ? docker.version : "Not found",
+        fix: docker.ok ? undefined : withDocLink("Install Docker: https://docs.docker.com/get-docker/", "sonar_docker"),
+      };
+    },
+  };
+}
+
+/**
+ * Serena MCP (optional). Prompt strategy: we know how to install it.
+ */
+function createSerenaCheck() {
+  return {
+    name: "serena",
+    label: "Serena MCP",
+    strategy: STRATEGY.MANUAL,
+    applies: (config) => config.serena?.enabled === true,
+    describe: "Install Serena via: uvx --from git+https://github.com/oraios/serena serena",
+    async detect() {
+      let ok;
+      try {
+        const res = await runCommand("serena", ["--version"]);
+        ok = res.exitCode === 0;
+      } catch {
+        ok = false;
+      }
+      return {
+        ok,
+        severity: "warn",
+        detail: ok ? "Available" : "Not found (prompts will still include Serena instructions)",
+        fix: ok ? undefined : "Install Serena: uvx --from git+https://github.com/oraios/serena serena --help",
+      };
+    },
+  };
+}
+
+/**
+ * Audit-side external tool (semgrep, osv-scanner, lighthouse) check.
+ *
+ * These are not blockers: `kj audit` and `kj webperf` degrade to
+ * available:false when missing. We surface them in `kj doctor` so the
+ * user can see at a glance which audit dimensions are active, and we
+ * point to `kj install-tools` for one-line remediation.
+ *
+ * `lighthouse` is stack-gated: only flagged when the project is
+ * frontend / fullstack. On backend-only projects the check is a no-op
+ * (returns ok:true with detail "n/a") to keep doctor output focused.
+ */
+function createAuditToolCheck(tool, { gatedByStack = false, label }) {
+  return {
+    name: `audit-tool:${tool}`,
+    label,
+    strategy: STRATEGY.MANUAL,
+    async detect({ config } = {}) {
+      if (gatedByStack) {
+        // Stack detection is best-effort — failing here just means we
+        // treat the project as backend-only (skip the check). Keeps the
+        // doctor pipeline resilient to weird repos.
+        let stack = null;
+        try {
+          const { detectProjectStack } = await import("../utils/stack-detect.js");
+          stack = await detectProjectStack(config?.projectDir || process.cwd());
+        } catch { /* ignore */ }
+        if (!appliesToStack(tool, stack)) {
+          return { ok: true, severity: "info", detail: "n/a (no frontend stack detected)" };
+        }
+      }
+      const result = await checkBinary(tool);
+      if (result.ok) {
+        return { ok: true, severity: "info", detail: result.version || "available" };
+      }
+      const hint = await getInstallHint(tool);
+      const fixLine = hint.command
+        ? `Run \`kj install-tools --only ${tool}\` or: ${hint.command}`
+        : `Run \`kj install-tools --only ${tool}\` or see ${hint.manualUrl}`;
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "Not found — `kj audit` dimension will degrade",
+        fix: fixLine,
+        extra: { tool, suggested: hint.command, manager: hint.manager, manualUrl: hint.manualUrl },
+      };
+    },
+  };
+}
+
+/**
+ * Aggregate: all binary-related checks for the current config.
+ * @returns {import("./types.js").Check[]}
+ */
+export function getBinaryChecks() {
+  const checks = [];
+  for (const agent of KNOWN_AGENTS) {
+    checks.push(createAgentCheck(agent));
+  }
+  checks.push(createObservedAgentsCheck());
+  for (const bin of ["node", "npm", "git"]) {
+    checks.push(createCoreBinaryCheck(bin));
+  }
+  checks.push(createDockerCheck());
+  checks.push(createSerenaCheck());
+  // KJC-TSK v2.18 — surface audit-side tools in doctor so the user knows
+  // which dimensions will work. lighthouse is gated to frontend stacks.
+  checks.push(createAuditToolCheck("semgrep", { label: "Semgrep (audit/security)" }));
+  checks.push(createAuditToolCheck("osv-scanner", { label: "OSV-Scanner (audit/security)" }));
+  checks.push(createAuditToolCheck("lighthouse", { label: "Lighthouse (webperf)", gatedByStack: true }));
+  return checks;
+}

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}`,
+      };
+    },
+  };
+}
+
+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/",
+      };
+    },
+  };
+}
+
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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).
+ */
+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(),
+  ];
+}