@karajan-family/code 4.21.0

package/src/checks/system.js

@@ -0,0 +1,53 @@
+/**
+ * Miscellaneous system-level checks: Karajan version, git repo presence.
+ * Kept in a dedicated module so they're easy to find and extend.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { ensureGitRepo } from "../utils/git.js";
+import { STRATEGY } from "./types.js";
+
+function getPackageVersion() {
+  const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
+  return JSON.parse(readFileSync(pkgPath, "utf8")).version;
+}
+
+function createKarajanVersionCheck() {
+  return {
+    name: "karajan",
+    label: "Karajan Code",
+    strategy: STRATEGY.NONE,
+    async detect() {
+      const version = getPackageVersion();
+      return { ok: true, severity: "info", detail: `v${version}` };
+    },
+  };
+}
+
+function createGitRepoCheck() {
+  return {
+    name: "git",
+    label: "Git repository",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      let gitOk;
+      try {
+        gitOk = await ensureGitRepo();
+      } catch {
+        gitOk = false;
+      }
+      return {
+        ok: gitOk,
+        severity: "fail",
+        detail: gitOk ? "Inside a git repository" : "Not a git repository",
+        fix: gitOk ? undefined : "Run 'git init' or navigate to a git-managed project.",
+      };
+    },
+  };
+}
+
+export function getSystemChecks() {
+  return [createKarajanVersionCheck(), createGitRepoCheck()];
+}

package/src/checks/tokens.js

@@ -0,0 +1,172 @@
+/**
+ * Provider CLI availability checks (preflight).
+ *
+ * IMPORTANT — Karajan does NOT call provider APIs directly. There is no
+ * `@anthropic-ai/sdk`, no `openai`, no `@google/generative-ai` in
+ * package.json. Every active role spawns its agent CLI as a subprocess
+ * (`claude`, `codex`, `gemini`, `opencode`, `aider`). The CLI handles its
+ * own auth, typically via OAuth + on-disk token (Claude Code, Codex CLI,
+ * Gemini CLI). The user does NOT need to set ANTHROPIC_API_KEY etc. for
+ * Karajan to work.
+ *
+ * Pre-v2.7.4 this module checked for ANTHROPIC_API_KEY / OPENAI_API_KEY /
+ * GEMINI_API_KEY env vars and FAILed preflight when missing — a false
+ * positive that blocked every user running Karajan as an MCP child of
+ * Claude Code (where `apiKeySource: "none"` is the norm). Replaced with a
+ * CLI-availability check that mirrors what the orchestrator actually does.
+ *
+ * GH_TOKEN is still checked when `git.auto_pr=true`, because that flow uses
+ * `git push` directly with the env var.
+ */
+
+import { checkBinary } from "../utils/agent-detect.js";
+import { getRequiredProviderEnvs, normalizeProvider } from "../utils/provider-env.js";
+import { runCommand } from "../utils/process.js";
+import { STRATEGY } from "./types.js";
+
+/**
+ * Map canonical provider name → the CLI binary Karajan actually spawns.
+ * Keep in sync with src/agents/index.js.
+ */
+const PROVIDER_TO_CLI = Object.freeze({
+  anthropic: "claude",
+  openai: "codex",
+  google: "gemini",
+  opencode: "opencode",
+  aider: "aider",
+});
+
+/**
+ * Build a CLI-availability check for one provider.
+ *
+ * The check runs `<cli> --version`. If the binary is on PATH and exits 0,
+ * preflight passes — Karajan can spawn it. If the CLI is missing, preflight
+ * fails with the install URL we already track in PROVIDER_ENV.
+ *
+ * Note: we do NOT verify that the CLI is *authenticated*. Doing so would
+ * require provider-specific introspection (`claude doctor`, `codex login
+ * status`, ...), each with its own quirks and exit codes. If the CLI is
+ * present but not logged in, the agent will fail at the first request with
+ * a clear error — and the orchestrator surfaces that error already.
+ */
+function createProviderCliCheck(entry) {
+  const cli = PROVIDER_TO_CLI[entry.provider];
+  return {
+    name: `cli:${entry.provider}`,
+    label: `${entry.provider} CLI (${cli})`,
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      if (!cli) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `Unknown CLI for provider ${entry.provider}`,
+          extra: { provider: entry.provider },
+        };
+      }
+      const result = await checkBinary(cli);
+      if (result.ok) {
+        return {
+          ok: true,
+          severity: "info",
+          detail: `${cli} on PATH (${result.version || "version unknown"})`,
+          extra: { provider: entry.provider, cli, version: result.version, path: result.path },
+        };
+      }
+      return {
+        ok: false,
+        severity: entry.optional ? "warn" : "fail",
+        detail: `${cli} not found on PATH`,
+        fix: `Install the ${cli} CLI: see ${entry.howToGetUrl}`,
+        extra: { provider: entry.provider, cli, howToGetUrl: entry.howToGetUrl },
+      };
+    },
+  };
+}
+
+/**
+ * GH token check + auto-remediation via `gh auth login` when it's installed.
+ * Kept from the previous version: this one IS legitimate because Karajan
+ * uses `gh` (or raw `git push`) directly when auto_pr is on.
+ */
+function createGhTokenCheck() {
+  return {
+    name: "token:gh",
+    label: "GitHub token (for auto_pr)",
+    strategy: STRATEGY.PROMPT,
+    applies: (config) => config?.git?.auto_pr === true,
+    describe: "Run 'gh auth login' to authenticate with GitHub",
+    // KJC-BUG-0049: auto_pr es feature opcional. Si falta el token, no abortar
+    // el run — desactivar auto_pr y auto_push (sin push no hay PR posible) y
+    // continuar. El usuario verá WARN y el commit local sigue funcionando.
+    degradable: {
+      disables: ["git.auto_pr", "git.auto_push"],
+      warn: "auto_pr y auto_push DESACTIVADOS para este run (commit local sí funciona). Ejecuta `gh auth login` para reactivar.",
+    },
+    async detect() {
+      const envOk = !!process.env.GH_TOKEN || !!process.env.GITHUB_TOKEN;
+      if (envOk) {
+        return { ok: true, severity: "info", detail: "GH_TOKEN or GITHUB_TOKEN is set" };
+      }
+      // If `gh` is installed and authenticated, it manages its own token.
+      const gh = await checkBinary("gh");
+      if (!gh.ok) {
+        return {
+          ok: false,
+          severity: "fail",
+          detail: "No GH_TOKEN/GITHUB_TOKEN and `gh` CLI not installed",
+          fix: "Install GitHub CLI (https://cli.github.com) or export GH_TOKEN=...",
+          extra: { hasGh: false },
+        };
+      }
+      // KJC-BUG-0049 — el check anterior asumía que un usuario sin env var no
+      // tiene auth válida y abortaba el run. Pero `gh` puede estar autenticado
+      // por keyring/OAuth (caso default tras `gh auth login --web`) y operar
+      // sin env var. Si `gh auth status` devuelve exit 0 (logged in), el flujo
+      // de `auto_pr` funciona — Karajan ya no necesita `GH_TOKEN` en env.
+      try {
+        const auth = await runCommand("gh", ["auth", "status"], { reject: false });
+        if (auth.exitCode === 0) {
+          return {
+            ok: true,
+            severity: "info",
+            detail: "`gh` authenticated via keyring/OAuth (no env var needed)",
+          };
+        }
+      } catch { /* fall through to FAIL */ }
+      return {
+        ok: false,
+        severity: "fail",
+        detail: "No GH_TOKEN/GITHUB_TOKEN and `gh auth status` reports not logged in",
+        fix: "Run 'gh auth login' or export GH_TOKEN=...",
+        extra: { hasGh: true },
+      };
+    },
+    // remediate() intentionally omitted: launching `gh auth login` requires an
+    // interactive terminal session. The runner's prompt strategy will point
+    // the user to the command and exit with FAIL in non-TTY contexts.
+  };
+}
+
+/**
+ * Build the list of CLI/token checks for the active config.
+ * - One CLI availability check per active provider (claude / codex / gemini / ...).
+ * - One GH token check, conditional on git.auto_pr.
+ *
+ * Function name kept as `getTokenChecks` for backward compat with
+ * preflight-checks.js, even though the bulk of the checks no longer touch
+ * tokens at all. Tracked: rename to `getProviderChecks` in a follow-up
+ * once consumers are updated.
+ *
+ * @param {Object} config
+ * @returns {import("./types.js").Check[]}
+ */
+export function getTokenChecks(config) {
+  const required = getRequiredProviderEnvs(config);
+  const checks = required.map(createProviderCliCheck);
+  checks.push(createGhTokenCheck());
+  return checks;
+}
+
+// Re-export for tests that need to introspect the mapping.
+export { normalizeProvider };

package/src/checks/types.js

@@ -0,0 +1,103 @@
+/**
+ * Shared check schema for doctor/preflight subsystem.
+ *
+ * A Check describes an environment requirement (binary present, port free,
+ * token configured, MCP reachable...). Each check can optionally remediate
+ * itself when it fails, using one of 4 strategies:
+ *
+ *   - "auto"   → fix without asking. Use for non-invasive, reversible changes
+ *                (in-memory runtime overrides, starting existing services,
+ *                creating files under ~/.karajan/, etc.)
+ *   - "prompt" → ask user before fixing. Use for invasive changes that touch
+ *                the user's system outside Karajan's scope (global npm install,
+ *                writing kj.config.yml, `gh auth login`, etc.)
+ *   - "manual" → cannot auto-fix, only report a hint (Node runtime upgrade,
+ *                missing Docker, missing API key with no admin creds)
+ *   - "none"   → informational check, always OK (Karajan version, feature
+ *                disabled by config)
+ */
+
+/**
+ * @typedef {Object} CheckResult
+ * @property {boolean} ok                        - true if check passes
+ * @property {"fail"|"warn"|"info"} [severity]   - relevant when !ok; default "fail"
+ * @property {string} detail                     - human-readable status
+ * @property {string} [fix]                      - remediation hint shown when manual or user declines
+ * @property {Object} [extra]                    - structured data consumed by remediate (e.g. occupant PID, host, roles)
+ */
+
+/**
+ * @typedef {Object} RemediationContext
+ * @property {Object} config                     - resolved Karajan config
+ * @property {AbortSignal} [signal]              - cancellation
+ * @property {Object} extra                      - check's CheckResult.extra
+ * @property {Object} logger                     - logger instance
+ */
+
+/**
+ * @typedef {Object} RemediationResult
+ * @property {boolean} fixed                     - true if remediation succeeded
+ * @property {string} detail                     - what was done, human-readable
+ * @property {Object} [changes]                  - runtime config overrides to merge into the active session
+ */
+
+/**
+ * @typedef {Object} DegradableSpec
+ * @property {string[]} disables        - dot-paths del config a desactivar si el check falla (e.g. ["git.auto_pr", "git.auto_push"])
+ * @property {string} warn              - mensaje WARN que se muestra al usuario explicando qué se desactivó y por qué
+ */
+
+/**
+ * @typedef {Object} Check
+ * @property {string} name                       - slug, unique across all checks (e.g. "node-version")
+ * @property {string} label                      - human label (e.g. "Node.js runtime")
+ * @property {"auto"|"prompt"|"manual"|"none"} strategy
+ * @property {(ctx: { config: Object }) => Promise<CheckResult>} detect
+ * @property {(ctx: RemediationContext) => Promise<RemediationResult>} [remediate]
+ * @property {string} [describe]                 - shown to user when strategy is "prompt"
+ * @property {(config: Object) => boolean} [applies]  - if false, check is SKIPPED (lazy evaluation). Default: always applies.
+ * @property {DegradableSpec} [degradable]       - KJC-BUG-0049: si está definido y el check falla, en lugar de abortar
+ *                                                  el preflight, se desactivan los flags listados en `disables` y se emite
+ *                                                  WARN con `warn`. Útil para features opcionales (auto_pr, auto_push,
+ *                                                  sonar advisory, etc.) que no son blockers absolutos.
+ */
+
+/**
+ * @typedef {Object} CheckReport
+ * @property {string} name
+ * @property {string} label
+ * @property {"OK"|"FIXED"|"WARN"|"FAIL"|"SKIPPED"|"TIMEOUT"} status
+ * @property {"auto"|"prompt"|"manual"|"none"} strategy
+ * @property {string} detail                     - detect detail or remediate detail when FIXED
+ * @property {string} [fix]                      - remediation hint for FAIL/WARN
+ * @property {number} runMs                      - total time (detect + remediate + re-verify)
+ * @property {boolean} [cached]                  - future: served from cache
+ */
+
+/**
+ * @typedef {Object} RunReport
+ * @property {CheckReport[]} checks
+ * @property {Object} overrides                  - merged runtime overrides from auto-remediations
+ * @property {number} totalMs
+ * @property {{ ok: number, fixed: number, warn: number, fail: number, skipped: number, timeout: number }} summary
+ */
+
+/**
+ * Status constants.
+ */
+export const STATUS = Object.freeze({
+  OK: "OK",
+  FIXED: "FIXED",
+  WARN: "WARN",
+  FAIL: "FAIL",
+  SKIPPED: "SKIPPED",
+  TIMEOUT: "TIMEOUT",
+});
+
+export const STRATEGY = Object.freeze({
+  AUTO: "auto",
+  PROMPT: "prompt",
+  MANUAL: "manual",
+  NONE: "none",
+});
+

package/src/ci/dispatch.js

@@ -0,0 +1,99 @@
+/**
+ * Karajan CI dispatch client — sends repository_dispatch events via gh CLI
+ * so the Karajan CI Gateway can publish comments and reviews on PRs.
+ *
+ * Event types are configurable via ci config:
+ *   - comment_event (default: "kj-comment")
+ *   - review_event  (default: "kj-review")
+ *
+ * Only active when ci.enabled: true.
+ */
+
+import { runCommand } from "../utils/process.js";
+
+export const VALID_AGENTS = [
+  "Coder",
+  "Reviewer",
+  "Solomon",
+  "Sonar",
+  "Tester",
+  "Security",
+  "Planner"
+];
+
+const VALID_REVIEW_EVENTS = ["APPROVE", "REQUEST_CHANGES"];
+
+function validateCommon({ repo, prNumber }) {
+  if (!repo) throw new Error("repo is required (e.g. 'owner/repo')");
+  if (!prNumber) throw new Error("prNumber is required (positive integer)");
+}
+
+function validateAgent(agent) {
+  if (!VALID_AGENTS.includes(agent)) {
+    throw new Error(
+      `Invalid agent "${agent}". Must be one of: ${VALID_AGENTS.join(", ")}`
+    );
+  }
+}
+
+async function sendDispatch(repo, payload) {
+  const res = await runCommand(
+    "gh",
+    ["api", `repos/${repo}/dispatches`, "--method", "POST", "--input", "-"],
+    { input: JSON.stringify(payload) }
+  );
+
+  if (res.exitCode === 127) {
+    throw new Error(
+      "gh CLI not found. Install GitHub CLI: https://cli.github.com/"
+    );
+  }
+
+  if (res.exitCode !== 0) {
+    throw new Error(
+      `Dispatch failed (exit ${res.exitCode}): ${res.stderr || res.stdout}`
+    );
+  }
+}
+
+/**
+ * Send a comment event so the gateway posts a PR comment.
+ * @param {object} opts
+ * @param {object} [opts.ciConfig] - ci config section (optional)
+ */
+export async function dispatchComment({ repo, prNumber, agent, body, ciConfig }) {
+  validateCommon({ repo, prNumber });
+  validateAgent(agent);
+  if (!body) throw new Error("body is required (comment text)");
+
+  const prefix = ciConfig?.comment_prefix === false ? "" : `[${agent}] `;
+  const eventType = ciConfig?.comment_event || "kj-comment";
+
+  await sendDispatch(repo, {
+    event_type: eventType,
+    client_payload: { pr_number: prNumber, agent, body: `${prefix}${body}` }
+  });
+}
+
+/**
+ * Send a review event so the gateway submits a formal PR review.
+ * @param {object} opts
+ * @param {object} [opts.ciConfig] - ci config section (optional)
+ */
+export async function dispatchReview({ repo, prNumber, event, body, agent, ciConfig }) {
+  validateCommon({ repo, prNumber });
+  validateAgent(agent);
+  if (!VALID_REVIEW_EVENTS.includes(event)) {
+    throw new Error(
+      `event must be one of: ${VALID_REVIEW_EVENTS.join(", ")} (got "${event}")`
+    );
+  }
+  if (!body) throw new Error("body is required (review text)");
+
+  const eventType = ciConfig?.review_event || "kj-review";
+
+  await sendDispatch(repo, {
+    event_type: eventType,
+    client_payload: { pr_number: prNumber, event, body, agent }
+  });
+}

package/src/ci/index.js

@@ -0,0 +1,3 @@
+export { dispatchComment, dispatchReview, VALID_AGENTS } from "./dispatch.js";
+export { detectRepo, detectPrNumber } from "./repo.js";
+export { getPrDiff } from "./pr-diff.js";

package/src/ci/pr-diff.js

@@ -0,0 +1,26 @@
+/**
+ * Read PR diff via gh CLI for Karajan CI flow.
+ * The reviewer reads the PR diff instead of local git diff.
+ */
+
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Get the diff of a PR via `gh pr diff <number>`.
+ * Returns the diff string or throws on failure.
+ */
+export async function getPrDiff(prNumber) {
+  if (!prNumber) throw new Error("prNumber is required");
+
+  const res = await runCommand("gh", [
+    "pr",
+    "diff",
+    String(prNumber)
+  ]);
+
+  if (res.exitCode !== 0) {
+    throw new Error(`gh pr diff ${prNumber} failed: ${res.stderr || res.stdout}`);
+  }
+
+  return res.stdout;
+}

package/src/ci/repo.js

@@ -0,0 +1,45 @@
+/**
+ * Detect GitHub repo and PR number from local git context.
+ */
+
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Detect owner/repo from the git remote URL (origin).
+ * Supports HTTPS, SSH, and custom SSH aliases (e.g. github.com-user).
+ * Returns null if not a GitHub repo or not a git repo.
+ */
+export async function detectRepo() {
+  const res = await runCommand("git", [
+    "remote",
+    "get-url",
+    "origin"
+  ]);
+  if (res.exitCode !== 0) return null;
+
+  const url = res.stdout.trim();
+  // SSH: git@github.com:owner/repo.git  or  git@github.com-alias:owner/repo.git
+  const sshMatch = /github\.com[^:]*:([^/]+\/[^/]+?)(?:\.git)?$/.exec(url);
+  if (sshMatch) return sshMatch[1];
+
+  // HTTPS: https://github.com/owner/repo.git
+  const httpsMatch = /github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/.exec(url);
+  if (httpsMatch) return httpsMatch[1];
+
+  return null;
+}
+
+/**
+ * Detect the PR number for a given branch using gh CLI.
+ * Returns null if no PR exists for the branch.
+ */
+export async function detectPrNumber(branch) {
+  const args = ["pr", "view"];
+  if (branch) args.push(branch);
+  args.push("--json", "number", "--jq", ".number");
+  const res = await runCommand("gh", args);
+  if (res.exitCode !== 0) return null;
+
+  const num = Number.parseInt(res.stdout.trim(), 10);
+  return Number.isFinite(num) ? num : null;
+}

package/src/cli/_shared.js

@@ -0,0 +1,30 @@
+import { applyRunOverrides, loadConfig, validateConfig } from "../config.js";
+import { createLogger } from "../utils/logger.js";
+
+/**
+ * Wraps a CLI action so it loads + validates config, builds the logger,
+ * and fires the anonymous cli_command telemetry event before invoking
+ * the real command body. Shared across every register-*.js module so
+ * each one doesn't need to re-import the config plumbing.
+ *
+ * @param {string} pkgVersion       Current kj version (used for telemetry).
+ * @param {string} commandName      The CLI command name being executed.
+ * @param {object} flags            Flags parsed by Commander.
+ * @param {(ctx: { config: object, logger: object, flags: object }) => Promise<any>} fn
+ *                                  Body of the command — receives the merged config + logger.
+ */
+export async function withConfig(pkgVersion, commandName, flags, fn) {
+  const { config } = await loadConfig();
+  const merged = applyRunOverrides(config, flags || {});
+  validateConfig(merged, commandName);
+  const logger = createLogger(merged.output.log_level);
+
+  // Telemetry: anonymous cli_command event (non-blocking).
+  import("../utils/telemetry.js")
+    .then(({ sendTelemetryEvent }) =>
+      sendTelemetryEvent("cli_command", { command: commandName, version: pkgVersion }, merged)
+    )
+    .catch(() => {});
+
+  return fn({ config: merged, logger, flags });
+}

package/src/cli/advanced-commands.js

@@ -0,0 +1,61 @@
+// KJC-TSK-0582: the flat `kj --help` list had grown to 37 commands, which
+// drowns the handful a newcomer actually needs. This module is the single
+// source of truth for which commands are "core" (always shown in `kj --help`)
+// vs "advanced/specialized" (grouped under `kj advanced`). Nothing is hidden
+// or unregistered — every command stays top-level and invokable for
+// back-compat; this only changes what the help listing surfaces by default.
+
+/** The few commands a newcomer needs. Shown in `kj --help`. */
+export const CORE_COMMANDS = [
+  "start",
+  "init",
+  "run",
+  "plan",
+  "status",
+  "doctor",
+  "harden",
+  "config",
+  "update",
+];
+
+/** Navigation/built-ins that are neither core-basics nor advanced. */
+export const META_COMMANDS = ["advanced", "help"];
+
+/**
+ * Advanced commands grouped by area, in display order. Every advanced
+ * command MUST live in exactly one group — the parity test fails otherwise,
+ * so a newly-registered command can never silently vanish from `kj advanced`.
+ */
+export const ADVANCED_GROUPS = [
+  { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "solomon", "agent", "scan", "tournament"] },
+  { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
+  { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
+  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy"] },
+  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel", "identity"] },
+  { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
+  { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },
+];
+
+/** Flat set of every advanced command name (for fast lookup / filtering). */
+export const ADVANCED_COMMANDS = ADVANCED_GROUPS.flatMap((g) => g.commands);
+
+const ADVANCED_SET = new Set(ADVANCED_COMMANDS);
+const CORE_SET = new Set(CORE_COMMANDS);
+const META_SET = new Set(META_COMMANDS);
+
+/**
+ * Classify a command name. Returns "core" | "advanced" | "meta" | "unknown".
+ * "unknown" means the command is registered but not yet placed in this file —
+ * the parity test treats that as a failure so the listing never drifts.
+ */
+export function classifyCommand(name) {
+  if (CORE_SET.has(name)) return "core";
+  if (ADVANCED_SET.has(name)) return "advanced";
+  if (META_SET.has(name)) return "meta";
+  return "unknown";
+}
+
+/** True when the command should be hidden from the flat `kj --help` list. */
+export function isAdvancedCommand(name) {
+  return ADVANCED_SET.has(name);
+}