karajan-code 2.4.1 → 2.6.0

package/src/checks/skills.js

@@ -0,0 +1,49 @@
+/**
+ * OpenSkills CLI availability check. Only runs when skills are enabled.
+ * Strategy: prompt — we can offer to run `npm install -g openskills`,
+ * but global installs are invasive enough that they need user consent.
+ */
+
+import { isOpenSkillsAvailable } from "../skills/openskills-client.js";
+import { runCommand } from "../utils/process.js";
+import { STRATEGY } from "./types.js";
+
+export function skillsEnabled(config) {
+  return config?.skills?.enabled !== false;
+}
+
+export function createOpenSkillsCheck() {
+  return {
+    name: "openskills",
+    label: "OpenSkills CLI",
+    strategy: STRATEGY.PROMPT,
+    applies: skillsEnabled,
+    describe: "Install OpenSkills globally: npm install -g openskills",
+    async detect() {
+      const available = await isOpenSkillsAvailable();
+      if (available) {
+        return { ok: true, severity: "info", detail: "Available via `npx openskills`" };
+      }
+      return {
+        ok: false,
+        severity: "warn", // skills enabled but missing → degrade gracefully
+        detail: "`npx openskills` not available — skill injection will be skipped",
+        fix: "Install OpenSkills: npm install -g openskills",
+      };
+    },
+    async remediate() {
+      const res = await runCommand("npm", ["install", "-g", "openskills"], { timeout: 60000 });
+      if (res.exitCode === 0) {
+        return { fixed: true, detail: "Installed openskills globally via npm" };
+      }
+      return {
+        fixed: false,
+        detail: `npm install -g openskills failed (exit ${res.exitCode}): ${res.stderr.split("\n")[0]}`,
+      };
+    },
+  };
+}
+
+export function getSkillsChecks() {
+  return [createOpenSkillsCheck()];
+}

package/src/checks/sonar.js

@@ -0,0 +1,67 @@
+/**
+ * SonarQube reachability + auth checks.
+ *
+ * Auto-remediation strategy (preserving existing behavior from
+ * preflight-checks.js): if Sonar is not reachable, try `sonarUp()` which
+ * starts the Docker container, then poll for readiness. If auth fails but
+ * admin credentials exist, generate a fresh token and persist it.
+ */
+
+import { isSonarReachable } from "../sonar/manager.js";
+import { STRATEGY } from "./types.js";
+import { withDocLink } from "../utils/doc-links.js";
+
+/**
+ * Whether Sonar is enabled in the active config.
+ */
+function sonarEnabled(config) {
+  return config.sonarqube?.enabled !== false;
+}
+
+function sonarHost(config) {
+  return config.sonarqube?.host || "http://localhost:9000";
+}
+
+/**
+ * Informative check: Sonar enabled/disabled status.
+ * Produces an OK result with disabled description when Sonar is off.
+ */
+export function createSonarStatusCheck() {
+  return {
+    name: "sonarqube",
+    label: "SonarQube",
+    strategy: STRATEGY.NONE,
+    async detect({ config }) {
+      const host = sonarHost(config);
+      if (!sonarEnabled(config)) {
+        return { ok: true, severity: "info", detail: "Disabled in config" };
+      }
+      let reachable = false;
+      try {
+        reachable = await isSonarReachable(host);
+      } catch {
+        reachable = false;
+      }
+      return {
+        ok: reachable,
+        severity: "fail",
+        detail: reachable ? `Reachable at ${host}` : `Not reachable at ${host}`,
+        fix: reachable
+          ? undefined
+          : withDocLink(
+              "Run 'kj sonar start' or 'docker start karajan-sonarqube'. Use --no-sonar to skip.",
+              "sonar_docker"
+            ),
+        extra: { host, reachable },
+      };
+    },
+  };
+}
+
+/**
+ * All Sonar-related checks. Keeps just the status check for commit 1;
+ * auth + auto-remediation are layered in commit 3.
+ */
+export function getSonarChecks() {
+  return [createSonarStatusCheck()];
+}

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;
+}
+
+export function createKarajanVersionCheck() {
+  return {
+    name: "karajan",
+    label: "Karajan Code",
+    strategy: STRATEGY.NONE,
+    async detect() {
+      const version = getPackageVersion();
+      return { ok: true, severity: "info", detail: `v${version}` };
+    },
+  };
+}
+
+export function createGitRepoCheck() {
+  return {
+    name: "git",
+    label: "Git repository",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      let gitOk = false;
+      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,96 @@
+/**
+ * API token availability checks.
+ *
+ * Provider tokens (ANTHROPIC_API_KEY / OPENAI_API_KEY / ...) are LAZY:
+ * we only check them for providers that are actually used by at least one
+ * active role in the current config.
+ *
+ * Strategy:
+ *   - Required providers with no key → FAIL, strategy manual (we can't
+ *     fetch an API key for the user). Fix hint includes the how-to URL.
+ *   - Optional providers (opencode, aider) without key → WARN.
+ *   - GH_TOKEN is checked when git.auto_pr=true, strategy prompt (we can
+ *     launch `gh auth login` with user approval).
+ */
+
+import { checkBinary } from "../utils/agent-detect.js";
+import { getRequiredProviderEnvs, hasEnvVar } from "../utils/provider-env.js";
+import { STRATEGY } from "./types.js";
+
+/**
+ * A single provider env check. One is created per active provider.
+ */
+function createProviderTokenCheck(entry) {
+  return {
+    name: `token:${entry.provider}`,
+    label: `API token: ${entry.provider}`,
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const ok = hasEnvVar(entry);
+      if (ok) {
+        return { ok: true, severity: "info", detail: `${entry.envVars[0]} is set` };
+      }
+      return {
+        ok: false,
+        severity: entry.optional ? "warn" : "fail",
+        detail: `${entry.envVars.join(" / ")} not set`,
+        fix: `Get an API key at ${entry.howToGetUrl} and export ${entry.envVars[0]}=...`,
+        extra: { provider: entry.provider, envVars: entry.envVars, howToGetUrl: entry.howToGetUrl },
+      };
+    },
+  };
+}
+
+/**
+ * GH token check + auto-remediation via `gh auth login` when it's installed.
+ */
+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",
+    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 },
+        };
+      }
+      return {
+        ok: false,
+        severity: "fail",
+        detail: "No GH_TOKEN/GITHUB_TOKEN; `gh` is installed but auth status unknown",
+        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 token checks for the active config. Each active provider
+ * gets one, plus conditional GH token when auto_pr is on.
+ *
+ * @param {Object} config
+ * @returns {import("./types.js").Check[]}
+ */
+export function getTokenChecks(config) {
+  const required = getRequiredProviderEnvs(config);
+  const checks = required.map(createProviderTokenCheck);
+  checks.push(createGhTokenCheck());
+  return checks;
+}

package/src/checks/types.js

@@ -0,0 +1,105 @@
+/**
+ * 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} 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.
+ */
+
+/**
+ * @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",
+});
+
+export const SEVERITY = Object.freeze({
+  FAIL: "fail",
+  WARN: "warn",
+  INFO: "info",
+});
+
+/**
+ * Whether the final status blocks the pipeline (for preflight).
+ */
+export function isBlocking(status) {
+  return status === STATUS.FAIL || status === STATUS.TIMEOUT;
+}

package/src/cli.js

@@ -128,6 +128,10 @@ program
   .option("--no-smart-models", "Disable smart model selection")
   .option("--design", "Activate design refactoring mode (impeccable role applies design changes)")
   .option("--domain <text-or-path>", "Domain knowledge: inline text or path to .md file")
+  .option("--skills-mode <mode>", "Skill detection mode: auto|regex|semantic|none (default: auto)")
+  .option("--brain <mode>", "Brain decisor: on|off (default: on). When off, only legacy flags drive routing.")
+  .option("--skip-role <role...>", "Force one or more roles OFF regardless of triage (e.g. --skip-role tester security)")
+  .option("--force-role <role...>", "Force one or more roles ON regardless of triage")
   .option("--dry-run", "Show what would be executed without running anything")
   .option("--json", "Output JSON only (no styled display)")
   .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")
@@ -172,9 +176,22 @@ program
 
 program
   .command("doctor")
-  .description("Check environment requirements")
-  .action(async () => {
-    await withConfig("doctor", {}, doctorCommand);
+  .description("Check environment requirements and auto-remediate when possible")
+  .option("--check-only", "Detect issues without applying fixes")
+  .option("-y, --yes", "Auto-confirm prompts for invasive remediations (CI mode)")
+  .option("--json", "Emit machine-readable JSON instead of human output")
+  .option("--verbose", "Include fix hints and timing for every check")
+  .action(async (flags) => {
+    const exitCode = await withConfig("doctor", {}, (ctx) =>
+      doctorCommand({
+        ...ctx,
+        checkOnly: !!flags.checkOnly,
+        yes: !!flags.yes,
+        json: !!flags.json,
+        verbose: !!flags.verbose,
+      })
+    );
+    if (Number.isInteger(exitCode)) process.exit(exitCode);
   });
 
 program
@@ -198,6 +215,15 @@ program
     await reportCommand(flags);
   });
 
+program
+  .command("skills [action]")
+  .description("Manage the local OpenSkills cache (actions: list | clear-cache)")
+  .action(async (action) => {
+    const { skillsCommand } = await import("./commands/skills.js");
+    const exitCode = await skillsCommand({ action: action || "list" });
+    if (Number.isInteger(exitCode)) process.exit(exitCode);
+  });
+
 program
   .command("roles [subcommand] [role]")
   .description("List pipeline roles or show role template instructions")
@@ -217,9 +243,11 @@ program
     });
   });
 
-program
-  .command("plan")
-  .description("Generate implementation plan")
+const plan = program.command("plan").description("Plan management (generate, review, approve, execute)");
+
+plan
+  .command("generate", { isDefault: true })
+  .description("Generate implementation plan with HUs")
   .argument("<task>")
   .option("--planner <name>")
   .option("--planner-model <name>")
@@ -227,10 +255,65 @@ program
   .option("--json", "Output raw JSON plan")
   .action(async (task, flags) => {
     await withConfig("plan", flags, async ({ config, logger }) => {
-      await planCommand({ task, config, logger, json: flags.json, context: flags.context });
+      const { planGenerateCommand } = await import("./commands/plan.js");
+      await planGenerateCommand({ task, config, logger, json: flags.json, context: flags.context });
+    });
+  });
+
+plan.command("list").description("List all plans").action(async (flags) => {
+  await withConfig("plan", flags, async ({ config }) => {
+    const { planListCommand } = await import("./commands/plan.js");
+    await planListCommand({ config });
+  });
+});
+
+plan.command("show").description("Show plan details + HUs").argument("<planId>").action(async (planId, flags) => {
+  await withConfig("plan", flags, async ({ config }) => {
+    const { planShowCommand } = await import("./commands/plan.js");
+    await planShowCommand({ config, planId });
+  });
+});
+
+plan.command("ready").description("Approve plan — certify all HUs").argument("<planId>").action(async (planId, flags) => {
+  await withConfig("plan", flags, async ({ config }) => {
+    const { planReadyCommand } = await import("./commands/plan.js");
+    await planReadyCommand({ config, planId });
+  });
+});
+
+plan.command("validate").description("Validate plan structure").argument("<planId>").action(async (planId, flags) => {
+  await withConfig("plan", flags, async ({ config }) => {
+    const { planValidateCommand } = await import("./commands/plan.js");
+    await planValidateCommand({ config, planId });
+  });
+});
+
+plan.command("delete").description("Delete a plan").argument("<planId>").action(async (planId, flags) => {
+  await withConfig("plan", flags, async ({ config }) => {
+    const { planDeleteCommand } = await import("./commands/plan.js");
+    await planDeleteCommand({ config, planId });
+  });
+});
+
+plan.command("add-hu").description("Add HU to plan").argument("<planId>")
+  .option("--title <text>", "HU title")
+  .option("--type <type>", "Task type: sw|infra|doc|add-tests|refactor|nocode", "sw")
+  .option("--deps <ids>", "Comma-separated HU IDs this depends on")
+  .option("--scope <text>", "Scope description")
+  .action(async (planId, flags) => {
+    await withConfig("plan", flags, async ({ config }) => {
+      const { planAddHuCommand } = await import("./commands/plan.js");
+      await planAddHuCommand({ config, planId, title: flags.title, type: flags.type, deps: flags.deps, scope: flags.scope });
     });
   });
 
+plan.command("remove-hu").description("Remove HU from plan").argument("<planId>").argument("<huId>").action(async (planId, huId, flags) => {
+  await withConfig("plan", flags, async ({ config }) => {
+    const { planRemoveHuCommand } = await import("./commands/plan.js");
+    await planRemoveHuCommand({ config, planId, huId });
+  });
+});
+
 program
   .command("discover")
   .description("Analyze task for gaps, ambiguities and missing info")

package/src/commands/board.js

@@ -115,6 +115,29 @@ export async function boardStatus(port = 4000) {
   };
 }
 
+/**
+ * Render a highlighted cyan box with the HU Board URL + optional project name.
+ * Centralizes the banner used by both the init-time auto-start (flow-runner.js)
+ * and the post-planner auto-HU generation safety net so they stay in sync.
+ *
+ * @param {Object} params
+ * @param {string} params.url           - "http://localhost:4000"
+ * @param {string} params.status        - "started" | "already running"
+ * @param {string} [params.projectName] - optional project label
+ * @returns {string} ANSI-escaped box ready for console.log
+ */
+export function renderBoardBanner({ url, status, projectName }) {
+  const title = projectName ? `  Project: \u001b[1m${projectName}\u001b[0m` : null;
+  const lines = [
+    "",
+    "\u001b[36m\u256d\u2500 HU Board \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e",
+    `\u001b[36m\u2502\u001b[0m  \u001b[1m${status}\u001b[0m  \u001b[4m${url}\u001b[0m`,
+  ];
+  if (title) lines.push(`\u001b[36m\u2502\u001b[0m${title}`);
+  lines.push("\u001b[36m\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\u001b[0m", "");
+  return lines.join("\n");
+}
+
 export async function boardCommand({ action = "start", port = 4000, logger }) {
   switch (action) {
     case "start": {