karajan-code 2.7.4 → 2.8.0

package/src/cli/register-pipeline.js

@@ -0,0 +1,212 @@
+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 { runCommandHandler } from "../commands/run.js";
+import { statusCommand } from "../commands/status.js";
+import { loadPlan } from "../plan/plan-store.js";
+import { withConfig } from "./_shared.js";
+
+/**
+ * Register the "core pipeline" commands: everything the user runs day-to-day
+ * to drive the agent loop or inspect its output. Kept together so the
+ * shape of the run/code/review trio (and the scan/report/doctor helpers
+ * that frame them) lives in one file.
+ */
+export function registerPipeline(program, { pkgVersion }) {
+  program
+    .command("init")
+    .description("Initialize config, review rules and SonarQube")
+    .option("--no-interactive", "Skip wizard, use defaults (for CI/scripts)")
+    .option("--scaffold-ci", "Scaffold Karajan CI Gateway workflow files")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "init", flags, async ({ config: _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]", "Task description (or use --task-file to read from a .md file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md). Alternative to the positional task argument.")
+    .option("-y, --yes", "Skip the cwd confirmation prompt (CI / scripted runs).")
+    .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-impeccable")
+    .option("--enable-triage")
+    .option("--enable-discover")
+    .option("--enable-architect")
+    .option("--plan <planId>", "Plan ID from kj plan. Loads persisted plan context and skips researcher/architect/planner.")
+    // PR4: launch a single HU (or comma-separated list) instead of the
+    // entire plan. The board uses this for the per-HU ▶ button so the
+    // user can re-run only a failed HU without restarting the whole
+    // plan. Requires --plan to also be set.
+    .option("--hu <huIds>", "Comma-separated HU IDs to run. When set, the plan's other HUs are skipped. Requires --plan.")
+    .option("--enable-hu-reviewer")
+    .option("--hu-file <path>", "YAML file with HU stories to certify before coding")
+    .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("--coder-fallback <name>")
+    .option("--reviewer-fallback <name>")
+    .option("--reviewer-retries <n>")
+    .option("--auto-commit")
+    .option("--auto-push")
+    .option("--auto-pr")
+    .option("--enable-ci", "Enable Karajan CI (early PR + dispatch comments/reviews)")
+    .option("--branch-prefix <prefix>")
+    .option("--task-type <type>", "Explicit task type: sw, infra, doc, add-tests, refactor")
+    .option("--methodology <name>")
+    .option("--no-auto-rebase")
+    .option("--no-sonar")
+    .option("--enable-sonarcloud", "Enable SonarCloud scan (complementary to SonarQube)")
+    .option("--no-sonarcloud")
+    .option("--checkpoint-interval <n>", "Minutes between interactive checkpoints (default: 5)")
+    .option("--pg-task <cardId>", "Planning Game card ID (e.g., KJC-TSK-0042)")
+    .option("--pg-project <projectId>", "Planning Game project ID")
+    .option("--auto-simplify", "Auto-simplify pipeline for simple tasks (disable reviewer/tester)")
+    .option("--no-auto-simplify", "Force full pipeline regardless of triage level")
+    .option("--smart-models", "Enable smart model selection based on triage complexity")
+    .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)")
+    .option("-v, --verbose", "Show full agent output (stream-json, raw lines)")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "run", flags, async ({ config, logger }) => {
+        // If `--plan <id>` was passed and the user didn't provide a task
+        // argument or --task-file, fall back to the task embedded in the
+        // plan JSON. The whole point of `kj plan generate` is that the
+        // task is captured once and re-used; forcing the user to repeat
+        // --task-file on every run is friction with no upside.
+        let effectiveTask = task;
+        if (!task && !flags.taskFile && flags.plan) {
+          // config.projectDir is only populated post-init; before runFlow
+          // it can still be undefined. Plans are stored under cwd, so
+          // that's the correct fallback for the lookup.
+          const projectDir = config.projectDir || process.cwd();
+          const plan = await loadPlan(projectDir, flags.plan);
+          if (plan?.task && String(plan.task).trim()) {
+            effectiveTask = plan.task;
+          }
+        }
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task: effectiveTask, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await runCommandHandler({ task: resolvedTask, config, logger, flags });
+      });
+    });
+
+  program
+    .command("code")
+    .description("Run only coder")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--coder <name>")
+    .option("--coder-model <name>")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "code", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await codeCommand({ task: resolvedTask, config, logger });
+      });
+    });
+
+  program
+    .command("review")
+    .description("Run only reviewer")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--reviewer <name>")
+    .option("--reviewer-model <name>")
+    .option("--base-ref <ref>")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "review", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await reviewCommand({ task: resolvedTask, config, logger, baseRef: flags.baseRef });
+      });
+    });
+
+  program
+    .command("scan")
+    .description("Run SonarQube scan")
+    .action(async () => {
+      await withConfig(pkgVersion, "scan", {}, scanCommand);
+    });
+
+  program
+    .command("doctor")
+    .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(pkgVersion, "doctor", {}, (ctx) =>
+        doctorCommand({
+          ...ctx,
+          checkOnly: !!flags.checkOnly,
+          yes: !!flags.yes,
+          json: !!flags.json,
+          verbose: !!flags.verbose,
+        })
+      );
+      if (Number.isInteger(exitCode)) process.exit(exitCode);
+    });
+
+  program
+    .command("status")
+    .description("Show pipeline dashboard with HU progress")
+    .option("-n, --lines <n>", "Max log lines to read", "50")
+    .action(async (flags) => {
+      await statusCommand({ lines: Number(flags.lines) });
+    });
+
+  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")
+    .option("--pg-task <cardId>", "Filter reports by Planning Game card ID")
+    .action(async (flags) => {
+      await reportCommand(flags);
+    });
+}

package/src/cli/register-plan.js

@@ -0,0 +1,152 @@
+import {
+  planGenerateCommand,
+  planListCommand,
+  planShowCommand,
+  planReadyCommand,
+  planValidateCommand,
+  planDeleteCommand,
+  planAddHuCommand,
+  planRemoveHuCommand,
+} from "../commands/plan.js";
+import { parseCanvasMarkdown } from "../canvas/parse-md.js";
+import { validateCanvas } from "../canvas/validate.js";
+import { canvasToTask } from "../canvas/to-flat.js";
+import { withConfig } from "./_shared.js";
+
+/**
+ * Register the `plan` parent command and every sub-command that lives
+ * under it (generate / list / show / ready / validate / delete /
+ * add-hu / remove-hu). Centralising plan management here keeps the
+ * REASONS Canvas auto-detection logic in one file alongside the
+ * planner entrypoint.
+ */
+export function registerPlan(program, { pkgVersion }) {
+  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]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--planner <name>")
+    .option("--planner-model <name>")
+    .option("--context <text>", "Additional context for the planner")
+    .option("--json", "Output raw JSON plan")
+    // Tests-first quality knobs (v2.7.5). Default is "thorough":
+    // when the planner skips acceptance_tests on some HUs, run a
+    // focused synthesizer pass to fill them in. Disable with these
+    // flags only if you explicitly want a fast / sketch plan.
+    .option("--no-tests-synth", "Skip the tests-synthesizer pass that fills in missing acceptance_tests")
+    .option("--no-plan-review", "Skip the high-level plan reviewer pass (gaps / deps / overlap / order)")
+    .option("--quick", "Sketch mode — skip every quality pass after the initial planner call")
+    .option("-y, --yes", "Skip the project-name prompt (use the auto-derived default).")
+    .option("--no-interactive", "Force non-interactive mode (no prompts, use defaults).")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "plan", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+
+        // REASONS Canvas auto-detection: a SPEC that contains
+        // `## REASONS:Section` headings is treated as a structured
+        // Canvas — parsed + validated BEFORE the planner runs. This
+        // catches broken acceptance tests (jq syntax, bash parse,
+        // gherkin missing Given/Then, the 2026-04-29 as-binding
+        // misuse class) at plan-time, without spending LLM dollars.
+        //
+        // Detection by file CONTENTS, not by CLI flag — the Canvas
+        // format is the signal. Flat SPECs without REASONS sections
+        // continue through the legacy path unchanged (back-compat).
+        if (typeof resolvedTask === "string" && /^##\s+REASONS:/m.test(resolvedTask)) {
+          let parsed;
+          try {
+            parsed = parseCanvasMarkdown(resolvedTask);
+          } catch (err) {
+            throw new Error(`Canvas parse error: ${err.message}`, { cause: err });
+          }
+          const validation = validateCanvas(parsed);
+          if (!validation.valid) {
+            const lines = ["Canvas validation failed."];
+            if (validation.schemaIssues) {
+              lines.push("Schema issues:");
+              for (const issue of validation.schemaIssues) {
+                lines.push(`  - ${issue.path?.map((p) => p.key).join(".") || "(root)"}: ${issue.message}`);
+              }
+            }
+            if (validation.testIssues) {
+              lines.push("Acceptance test issues:");
+              for (const issue of validation.testIssues) {
+                lines.push(`  - Operation #${issue.operationIndex + 1} "${issue.operationTitle}", test #${issue.testIndex + 1} (${issue.type}, ${issue.kind}):`);
+                lines.push(`      ${issue.content}`);
+                lines.push(`      → ${issue.error}`);
+              }
+            }
+            throw new Error(lines.join("\n"));
+          }
+          // Pass the Canvas-derived flat task to the existing planner.
+          // Norms + Safeguards ride along under explicit headings the
+          // coder prompt can grep for.
+          const taskFromCanvas = canvasToTask(validation.canvas);
+          await planGenerateCommand({ task: taskFromCanvas, config, logger, flags });
+          return;
+        }
+        await planGenerateCommand({
+          task: resolvedTask, config, logger, json: flags.json, context: flags.context,
+          flags: {
+            noTestsSynth: flags.testsSynth === false,
+            noPlanReview: flags.planReview === false,
+            quick: Boolean(flags.quick),
+            yes: Boolean(flags.yes),
+            interactive: flags.interactive,
+          },
+        });
+      });
+    });
+
+  plan.command("list").description("List all plans").action(async (flags) => {
+    await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+      // TSK-0340: was `await import(...)` — now served by the top-level static import.
+      await planListCommand({ config });
+    });
+  });
+
+  plan.command("show").description("Show plan details + HUs").argument("<planId>").action(async (planId, flags) => {
+    await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+      await planShowCommand({ config, planId });
+    });
+  });
+
+  plan.command("ready").description("Approve plan — certify all HUs").argument("<planId>").action(async (planId, flags) => {
+    await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+      await planReadyCommand({ config, planId });
+    });
+  });
+
+  plan.command("validate").description("Validate plan structure").argument("<planId>").action(async (planId, flags) => {
+    await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+      await planValidateCommand({ config, planId });
+    });
+  });
+
+  plan.command("delete").description("Delete a plan").argument("<planId>").action(async (planId, flags) => {
+    await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+      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(pkgVersion, "plan", flags, async ({ config }) => {
+        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(pkgVersion, "plan", flags, async ({ config }) => {
+      await planRemoveHuCommand({ config, planId, huId });
+    });
+  });
+}

package/src/cli/register-roles-skills.js

@@ -0,0 +1,38 @@
+import { rolesCommand } from "../commands/roles.js";
+import { agentsCommand } from "../commands/agents.js";
+import { withConfig } from "./_shared.js";
+
+/**
+ * Register the meta-configuration commands the user reaches for when
+ * setting up the pipeline itself: which skills to load, which roles
+ * are wired in, which provider is mapped to each agent slot.
+ */
+export function registerRolesSkills(program, { pkgVersion }) {
+  program
+    .command("skills [action]")
+    .description("Manage the skill cache (actions: list | clear-cache | sync-addyosmani | list-addyosmani)")
+    .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")
+    .action(async (subcommand, role) => {
+      await withConfig(pkgVersion, "roles", {}, async ({ config }) => {
+        await rolesCommand({ config, subcommand: subcommand || "list", roleName: role });
+      });
+    });
+
+  program
+    .command("agents [subcommand] [role] [provider]")
+    .description("List or change AI agent assignments per role (e.g. kj agents set coder gemini)")
+    .option("--global", "Persist change to kj.config.yml (default for CLI)")
+    .action(async (subcommand, role, provider, flags) => {
+      await withConfig(pkgVersion, "agents", {}, async ({ config }) => {
+        await agentsCommand({ config, subcommand: subcommand || "list", role, provider, global: flags.global });
+      });
+    });
+}

package/src/cli/register-sonar.js

@@ -0,0 +1,28 @@
+import { sonarCommand, sonarOpenCommand } from "../commands/sonar.js";
+import { loadConfig } from "../config.js";
+
+/**
+ * Register the `sonar` parent command and its sub-actions
+ * (status / start / stop / logs / open). Kept in its own module
+ * because every sub-command shares the same one-liner shape and
+ * the only one that needs config is `open`.
+ */
+export function registerSonar(program) {
+  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}`);
+    });
+}