karajan-code 1.2.0

package/src/cli.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { applyRunOverrides, loadConfig, validateConfig } from "./config.js";
+import { createLogger } from "./utils/logger.js";
+import { initCommand } from "./commands/init.js";
+import { configCommand } from "./commands/config.js";
+import { codeCommand } from "./commands/code.js";
+import { reviewCommand } from "./commands/review.js";
+import { scanCommand } from "./commands/scan.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { reportCommand } from "./commands/report.js";
+import { planCommand } from "./commands/plan.js";
+import { runCommandHandler } from "./commands/run.js";
+import { resumeCommand } from "./commands/resume.js";
+import { sonarCommand, sonarOpenCommand } from "./commands/sonar.js";
+import { rolesCommand } from "./commands/roles.js";
+
+async function withConfig(commandName, flags, fn) {
+  const { config } = await loadConfig();
+  const merged = applyRunOverrides(config, flags || {});
+  validateConfig(merged, commandName);
+  const logger = createLogger(merged.output.log_level);
+  await fn({ config: merged, logger, flags });
+}
+
+const program = new Command();
+program.name("kj").description("Karajan Code CLI").version("1.2.0");
+
+program
+  .command("init")
+  .description("Initialize config, review rules and SonarQube")
+  .option("--no-interactive", "Skip wizard, use defaults (for CI/scripts)")
+  .action(async (flags) => {
+    await withConfig("init", flags, async ({ config, logger }) => {
+      await initCommand({ logger, flags });
+    });
+  });
+
+program
+  .command("config")
+  .description("Show current config")
+  .option("--json", "Show as JSON")
+  .option("--edit", "Open config in $EDITOR for editing")
+  .action(async (flags) => {
+    await configCommand(flags);
+  });
+
+program
+  .command("run")
+  .description("Run coder+sonar+reviewer loop")
+  .argument("<task>")
+  .option("--planner <name>")
+  .option("--coder <name>")
+  .option("--reviewer <name>")
+  .option("--refactorer <name>")
+  .option("--planner-model <name>")
+  .option("--coder-model <name>")
+  .option("--reviewer-model <name>")
+  .option("--refactorer-model <name>")
+  .option("--enable-planner")
+  .option("--enable-reviewer")
+  .option("--enable-refactorer")
+  .option("--enable-researcher")
+  .option("--enable-tester")
+  .option("--enable-security")
+  .option("--enable-triage")
+  .option("--enable-serena")
+  .option("--mode <name>")
+  .option("--max-iterations <n>")
+  .option("--max-iteration-minutes <n>")
+  .option("--max-total-minutes <n>")
+  .option("--base-branch <name>")
+  .option("--base-ref <ref>")
+  .option("--reviewer-fallback <name>")
+  .option("--reviewer-retries <n>")
+  .option("--auto-commit")
+  .option("--auto-push")
+  .option("--auto-pr")
+  .option("--branch-prefix <prefix>")
+  .option("--methodology <name>")
+  .option("--no-auto-rebase")
+  .option("--no-sonar")
+  .option("--pg-task <cardId>", "Planning Game card ID (e.g., KJC-TSK-0042)")
+  .option("--pg-project <projectId>", "Planning Game project ID")
+  .option("--dry-run", "Show what would be executed without running anything")
+  .option("--json", "Output JSON only (no styled display)")
+  .action(async (task, flags) => {
+    await withConfig("run", flags, async ({ config, logger }) => {
+      await runCommandHandler({ task, config, logger, flags });
+    });
+  });
+
+program
+  .command("code")
+  .description("Run only coder")
+  .argument("<task>")
+  .option("--coder <name>")
+  .option("--coder-model <name>")
+  .action(async (task, flags) => {
+    await withConfig("code", flags, async ({ config, logger }) => {
+      await codeCommand({ task, config, logger });
+    });
+  });
+
+program
+  .command("review")
+  .description("Run only reviewer")
+  .argument("<task>")
+  .option("--reviewer <name>")
+  .option("--reviewer-model <name>")
+  .option("--base-ref <ref>")
+  .action(async (task, flags) => {
+    await withConfig("review", flags, async ({ config, logger }) => {
+      await reviewCommand({ task, config, logger, baseRef: flags.baseRef });
+    });
+  });
+
+program
+  .command("scan")
+  .description("Run SonarQube scan")
+  .action(async () => {
+    await withConfig("scan", {}, scanCommand);
+  });
+
+program
+  .command("doctor")
+  .description("Check environment requirements")
+  .action(async () => {
+    await withConfig("doctor", {}, doctorCommand);
+  });
+
+program
+  .command("report")
+  .description("Show latest session report")
+  .option("--list", "List session ids")
+  .option("--session-id <id>", "Show report for a specific session ID")
+  .option("--format <type>", "Output format: text|json", "text")
+  .option("--trace", "Show chronological trace of all pipeline stages")
+  .option("--currency <code>", "Display costs in currency: usd|eur", "usd")
+  .action(async (flags) => {
+    await reportCommand(flags);
+  });
+
+program
+  .command("roles [subcommand] [role]")
+  .description("List pipeline roles or show role template instructions")
+  .action(async (subcommand, role) => {
+    await withConfig("roles", {}, async ({ config }) => {
+      await rolesCommand({ config, subcommand: subcommand || "list", roleName: role });
+    });
+  });
+
+program
+  .command("plan")
+  .description("Generate implementation plan")
+  .argument("<task>")
+  .option("--planner <name>")
+  .option("--planner-model <name>")
+  .option("--context <text>", "Additional context for the planner")
+  .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 });
+    });
+  });
+
+program
+  .command("resume")
+  .description("Resume a paused session")
+  .argument("<sessionId>")
+  .option("--answer <text>", "Answer to the question that caused the pause")
+  .option("--json", "Output JSON only")
+  .action(async (sessionId, flags) => {
+    await withConfig("resume", flags, async ({ config, logger }) => {
+      await resumeCommand({ sessionId, answer: flags.answer, config, logger, flags });
+    });
+  });
+
+const sonar = program.command("sonar").description("Manage SonarQube container");
+sonar.command("status").action(async () => sonarCommand({ action: "status" }));
+sonar.command("start").action(async () => sonarCommand({ action: "start" }));
+sonar.command("stop").action(async () => sonarCommand({ action: "stop" }));
+sonar.command("logs").action(async () => sonarCommand({ action: "logs" }));
+sonar
+  .command("open")
+  .description("Open SonarQube dashboard in the browser")
+  .action(async () => {
+    const { config } = await loadConfig();
+    const result = await sonarOpenCommand({ config });
+    if (!result.ok) {
+      console.error(result.error);
+      process.exit(1);
+    }
+    console.log(`Opened ${result.url}`);
+  });
+
+program.parseAsync().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/src/commands/code.js

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { buildCoderPrompt } from "../prompts/coder.js";
+import { resolveRole } from "../config.js";
+
+export async function codeCommand({ task, config, logger }) {
+  const coderRole = resolveRole(config, "coder");
+  await assertAgentsAvailable([coderRole.provider]);
+  logger.info(`Coder (${coderRole.provider}) starting...`);
+  const coder = createAgent(coderRole.provider, config, logger);
+  let coderRules = null;
+  if (config.coder_rules) {
+    try {
+      coderRules = await fs.readFile(config.coder_rules, "utf8");
+    } catch { /* no coder rules file, that's ok */ }
+  }
+  const prompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
+  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+  const result = await coder.runTask({ prompt, onOutput, role: "coder" });
+  if (!result.ok) {
+    if (result.error) logger.error(result.error);
+    throw new Error(result.error || result.output || `Coder failed (exit ${result.exitCode})`);
+  }
+  if (result.output) {
+    console.log(result.output);
+  }
+  if (result.error) {
+    logger.warn(result.error);
+  }
+  logger.info(`Coder completed (exit ${result.exitCode})`);
+}

package/src/commands/config.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import yaml from "js-yaml";
+import { loadConfig, validateConfig, getConfigPath, writeConfig } from "../config.js";
+import { ensureDir } from "../utils/fs.js";
+import path from "node:path";
+
+function resolveEditor() {
+  const raw = process.env.VISUAL || process.env.EDITOR || "vi";
+  const parts = raw.split(/\s+/);
+  return { cmd: parts[0], args: parts.slice(1) };
+}
+
+export async function editConfigOnce(configPath) {
+  const { cmd, args } = resolveEditor();
+  const result = spawnSync(cmd, [...args, configPath], { stdio: "inherit" });
+
+  if (result.status !== 0) {
+    return { ok: false, error: `Editor exited with code ${result.status}` };
+  }
+
+  let raw;
+  try {
+    raw = await fs.readFile(configPath, "utf8");
+  } catch (err) {
+    return { ok: false, error: `Could not read config: ${err.message}` };
+  }
+
+  let parsed;
+  try {
+    parsed = yaml.load(raw);
+  } catch (err) {
+    return { ok: false, error: `Invalid YAML: ${err.message}` };
+  }
+
+  try {
+    validateConfig(parsed || {});
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+
+  return { ok: true, config: parsed };
+}
+
+export async function configCommand({ json = false, edit = false }) {
+  if (edit) {
+    const configPath = getConfigPath();
+    await ensureDir(path.dirname(configPath));
+    const { exists: configExists } = await loadConfig();
+    if (!configExists) {
+      const { config: defaults } = await loadConfig();
+      await writeConfig(configPath, defaults);
+    }
+
+    const result = await editConfigOnce(configPath);
+    if (result.ok) {
+      console.log("Configuration saved and validated.");
+    } else {
+      console.error(`Validation error: ${result.error}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  const { config, path: cfgPath, exists } = await loadConfig();
+  if (json) {
+    console.log(JSON.stringify({ path: cfgPath, exists, config }, null, 2));
+    return;
+  }
+
+  console.log(`Config path: ${cfgPath}`);
+  console.log(`Exists: ${exists}`);
+  console.log(JSON.stringify(config, null, 2));
+}

package/src/commands/doctor.js

@@ -0,0 +1,155 @@
+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";
+
+export async function runChecks({ config }) {
+  const checks = [];
+
+  // 1. Config file
+  const configPath = getConfigPath();
+  const configExists = await exists(configPath);
+  checks.push({
+    name: "config",
+    label: "Config file",
+    ok: configExists,
+    detail: configExists ? configPath : "Not found",
+    fix: configExists ? null : "Run 'kj init' to create the config file."
+  });
+
+  // 2. Git repository
+  let gitOk = false;
+  try {
+    gitOk = await ensureGitRepo();
+  } catch {
+    gitOk = false;
+  }
+  checks.push({
+    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."
+  });
+
+  // 3. Docker
+  const docker = await checkBinary("docker", "--version");
+  checks.push({
+    name: "docker",
+    label: "Docker",
+    ok: docker.ok,
+    detail: docker.ok ? docker.version : "Not found",
+    fix: docker.ok ? null : "Install Docker: https://docs.docker.com/get-docker/"
+  });
+
+  // 4. SonarQube reachability
+  const sonarHost = config.sonarqube?.host || "http://localhost:9000";
+  let sonarOk = false;
+  if (config.sonarqube?.enabled !== false) {
+    try {
+      sonarOk = await isSonarReachable(sonarHost);
+    } catch {
+      sonarOk = false;
+    }
+  }
+  checks.push({
+    name: "sonarqube",
+    label: "SonarQube",
+    ok: sonarOk || config.sonarqube?.enabled === false,
+    detail: config.sonarqube?.enabled === false
+      ? "Disabled in config"
+      : sonarOk
+        ? `Reachable at ${sonarHost}`
+        : `Not reachable at ${sonarHost}`,
+    fix: sonarOk || config.sonarqube?.enabled === false
+      ? null
+      : "Run 'kj sonar start' or 'docker start karajan-sonarqube'. Use --no-sonar to skip."
+  });
+
+  // 5. Agent CLIs
+  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 : `Install: ${agent.install}`
+    });
+  }
+
+  // 6. Core binaries
+  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.`
+    });
+  }
+
+  // 7. Serena MCP
+  if (config.serena?.enabled) {
+    let serenaOk = false;
+    try {
+      const serenaCheck = await runCommand("serena", ["--version"]);
+      serenaOk = serenaCheck.exitCode === 0;
+    } catch {
+      serenaOk = false;
+    }
+    checks.push({
+      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"
+    });
+  }
+
+  // 8. Review rules / Coder rules
+  const projectDir = config.projectDir || process.cwd();
+  const reviewRules = await loadFirstExisting(resolveRoleMdPath("reviewer", projectDir));
+  const coderRules = await loadFirstExisting(resolveRoleMdPath("coder", projectDir));
+  checks.push({
+    name: "review-rules",
+    label: "Reviewer rules (.md)",
+    ok: Boolean(reviewRules),
+    detail: reviewRules ? "Found" : "Not found (will use defaults)",
+    fix: null
+  });
+  checks.push({
+    name: "coder-rules",
+    label: "Coder rules (.md)",
+    ok: Boolean(coderRules),
+    detail: coderRules ? "Found" : "Not found (will use defaults)",
+    fix: null
+  });
+
+  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) {
+      console.log(`     -> ${check.fix}`);
+    }
+  }
+
+  const failures = checks.filter((c) => !c.ok && c.fix);
+  if (failures.length === 0) {
+    console.log("\nAll checks passed.");
+  } else {
+    console.log(`\n${failures.length} issue(s) found.`);
+  }
+
+  return checks;
+}

package/src/commands/init.js

@@ -0,0 +1,181 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { getConfigPath, loadConfig, writeConfig } from "../config.js";
+import { sonarUp, checkVmMaxMapCount } from "../sonar/manager.js";
+import { exists, ensureDir } from "../utils/fs.js";
+import { getKarajanHome } from "../utils/paths.js";
+import { detectAvailableAgents } from "../utils/agent-detect.js";
+import { createWizard, isTTY } from "../utils/wizard.js";
+
+async function runWizard(config, logger) {
+  const agents = await detectAvailableAgents();
+  const available = agents.filter((a) => a.available);
+  const unavailable = agents.filter((a) => !a.available);
+
+  logger.info("\n=== Karajan Code Setup Wizard ===\n");
+
+  if (available.length === 0) {
+    logger.warn("No AI agents detected. Install at least one:");
+    for (const agent of unavailable) {
+      logger.warn(`  ${agent.name}: ${agent.install}`);
+    }
+    logger.info("\nGenerating config with defaults (claude). You can change it later in kj.config.yml.\n");
+    return config;
+  }
+
+  logger.info("Detected agents:");
+  for (const agent of available) {
+    logger.info(`  OK   ${agent.name} (${agent.version})`);
+  }
+  for (const agent of unavailable) {
+    logger.info(`  MISS ${agent.name}`);
+  }
+  logger.info("");
+
+  if (available.length === 1) {
+    const only = available[0].name;
+    logger.info(`Only one agent available: ${only}. Using it for all roles.\n`);
+    config.coder = only;
+    config.reviewer = only;
+    config.roles.coder.provider = only;
+    config.roles.reviewer.provider = only;
+    return config;
+  }
+
+  const wizard = createWizard();
+  try {
+    const agentOptions = available.map((a) => ({
+      label: `${a.name} (${a.version})`,
+      value: a.name,
+      available: true
+    }));
+
+    const coder = await wizard.select("Select default CODER agent:", agentOptions);
+    config.coder = coder;
+    config.roles.coder.provider = coder;
+    logger.info(`  -> Coder: ${coder}`);
+
+    const reviewer = await wizard.select("Select default REVIEWER agent:", agentOptions);
+    config.reviewer = reviewer;
+    config.roles.reviewer.provider = reviewer;
+    logger.info(`  -> Reviewer: ${reviewer}`);
+
+    const enableTriage = await wizard.confirm("Enable triage (auto-classify task complexity)?", false);
+    config.pipeline.triage = config.pipeline.triage || {};
+    config.pipeline.triage.enabled = enableTriage;
+    logger.info(`  -> Triage: ${enableTriage ? "enabled" : "disabled"}`);
+
+    const enableSonar = await wizard.confirm("Enable SonarQube analysis?", true);
+    config.sonarqube.enabled = enableSonar;
+    logger.info(`  -> SonarQube: ${enableSonar ? "enabled" : "disabled"}`);
+
+    const methodology = await wizard.select("Development methodology:", [
+      { label: "TDD (test-driven development)", value: "tdd", available: true },
+      { label: "Standard (no TDD enforcement)", value: "standard", available: true }
+    ]);
+    config.development.methodology = methodology;
+    config.development.require_test_changes = methodology === "tdd";
+    logger.info(`  -> Methodology: ${methodology}`);
+
+    logger.info("");
+  } finally {
+    wizard.close();
+  }
+
+  return config;
+}
+
+export async function initCommand({ logger, flags = {} }) {
+  const karajanHome = getKarajanHome();
+  await ensureDir(karajanHome);
+  logger.info(`Ensured ${karajanHome} exists`);
+
+  const configPath = getConfigPath();
+  const reviewRulesPath = path.resolve(process.cwd(), "review-rules.md");
+  const coderRulesPath = path.resolve(process.cwd(), "coder-rules.md");
+
+  const { config, exists: configExists } = await loadConfig();
+  const interactive = flags.noInteractive !== true && isTTY();
+
+  if (configExists && interactive) {
+    const wizard = createWizard();
+    try {
+      const reconfigure = await wizard.confirm("Config already exists. Reconfigure?", false);
+      if (reconfigure) {
+        const updated = await runWizard(config, logger);
+        await writeConfig(configPath, updated);
+        logger.info(`Updated ${configPath}`);
+      } else {
+        logger.info("Keeping existing config.");
+      }
+    } finally {
+      wizard.close();
+    }
+  } else if (!configExists && interactive) {
+    const updated = await runWizard(config, logger);
+    await writeConfig(configPath, updated);
+    logger.info(`Created ${configPath}`);
+  } else if (!configExists) {
+    await writeConfig(configPath, config);
+    logger.info(`Created ${configPath}`);
+  }
+
+  if (!(await exists(reviewRulesPath))) {
+    await fs.writeFile(
+      reviewRulesPath,
+      "# Review Rules\n\n- Focus on security, correctness, and test coverage.\n",
+      "utf8"
+    );
+    logger.info("Created review-rules.md");
+  }
+
+  if (!(await exists(coderRulesPath))) {
+    const templatePath = path.resolve(import.meta.dirname, "../../templates/coder-rules.md");
+    let content;
+    try {
+      content = await fs.readFile(templatePath, "utf8");
+    } catch {
+      content = [
+        "# Coder Rules",
+        "",
+        "## File modification safety",
+        "",
+        "- NEVER overwrite existing files entirely. Always make targeted, minimal edits.",
+        "- After each edit, verify with `git diff` that ONLY the intended lines changed.",
+        "- Do not modify code unrelated to the task.",
+        ""
+      ].join("\n");
+    }
+    await fs.writeFile(coderRulesPath, content, "utf8");
+    logger.info("Created coder-rules.md");
+  }
+
+  if (config.sonarqube?.enabled !== false) {
+    const vmCheck = await checkVmMaxMapCount(os.platform());
+    if (!vmCheck.ok) {
+      logger.warn(`vm.max_map_count check failed: ${vmCheck.reason}`);
+      if (vmCheck.fix) {
+        logger.warn(`Fix: ${vmCheck.fix}`);
+      }
+    }
+
+    const sonar = await sonarUp();
+    if (sonar.exitCode !== 0) {
+      throw new Error(`Failed to start SonarQube: ${sonar.stderr || sonar.stdout}`);
+    }
+
+    logger.info("SonarQube container started");
+
+    logger.info("");
+    logger.info("To configure the SonarQube token:");
+    logger.info("  1. Open http://localhost:9000");
+    logger.info("  2. Log in (default credentials: admin / admin)");
+    logger.info("  3. Go to: My Account > Security > Generate Token");
+    logger.info("  4. Name: karajan-cli, Type: Global Analysis Token");
+    logger.info("  5. Set the token in ~/.karajan/kj.config.yml under sonarqube.token");
+    logger.info('     or export KJ_SONAR_TOKEN="<your-token>"');
+  } else {
+    logger.info("SonarQube disabled — skipping container setup.");
+  }
+}