karajan-code 1.2.0

package/src/commands/plan.js

@@ -0,0 +1,67 @@
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { resolveRole } from "../config.js";
+import { buildPlannerPrompt } from "../prompts/planner.js";
+import { parseMaybeJsonString } from "../review/parser.js";
+
+function formatPlan(plan) {
+  const lines = [];
+
+  if (plan.approach) {
+    lines.push("## Approach", plan.approach, "");
+  }
+
+  if (plan.steps?.length) {
+    lines.push("## Steps");
+    for (let i = 0; i < plan.steps.length; i++) {
+      const step = plan.steps[i];
+      const commit = step.commit ? ` → \`${step.commit}\`` : "";
+      lines.push(`${i + 1}. ${step.description}${commit}`);
+    }
+    lines.push("");
+  }
+
+  if (plan.risks?.length) {
+    lines.push("## Risks");
+    for (const risk of plan.risks) {
+      lines.push(`- ${risk}`);
+    }
+    lines.push("");
+  }
+
+  if (plan.outOfScope?.length) {
+    lines.push("## Out of scope");
+    for (const item of plan.outOfScope) {
+      lines.push(`- ${item}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+export async function planCommand({ task, config, logger, json, context }) {
+  const plannerRole = resolveRole(config, "planner");
+  await assertAgentsAvailable([plannerRole.provider]);
+
+  const planner = createAgent(plannerRole.provider, config, logger);
+  const prompt = buildPlannerPrompt({ task, context });
+  const result = await planner.runTask({ prompt, role: "planner" });
+
+  if (!result.ok) {
+    throw new Error(result.error || result.output || "Planner failed");
+  }
+
+  const parsed = parseMaybeJsonString(result.output);
+
+  if (json) {
+    console.log(JSON.stringify(parsed || result.output, null, 2));
+    return;
+  }
+
+  if (parsed && parsed.approach) {
+    console.log(formatPlan(parsed));
+  } else {
+    console.log(result.output);
+  }
+}

package/src/commands/report.js

@@ -0,0 +1,340 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { exists } from "../utils/fs.js";
+import { getSessionRoot } from "../utils/paths.js";
+import { loadConfig } from "../config.js";
+
+function parseBudgetFromActivityLog(logText) {
+  if (!logText) {
+    return { consumed_usd: null, limit_usd: null };
+  }
+
+  const regex = /Budget:\s*\$([0-9]+(?:\.[0-9]+)?)\s*\/\s*\$([0-9]+(?:\.[0-9]+)?)/g;
+  let match;
+  let last = null;
+  while ((match = regex.exec(logText)) !== null) {
+    last = match;
+  }
+
+  if (!last) {
+    return { consumed_usd: null, limit_usd: null };
+  }
+
+  return {
+    consumed_usd: Number(last[1]),
+    limit_usd: Number(last[2])
+  };
+}
+
+function summarizeIterations(checkpoints = []) {
+  const byIteration = new Map();
+  for (const checkpoint of checkpoints) {
+    const iteration = Number(checkpoint?.iteration);
+    if (!Number.isFinite(iteration) || iteration <= 0) continue;
+
+    if (!byIteration.has(iteration)) {
+      byIteration.set(iteration, {
+        iteration,
+        coder_runs: 0,
+        reviewer_attempts: 0,
+        reviewer_approved: null
+      });
+    }
+
+    const item = byIteration.get(iteration);
+    if (checkpoint.stage === "coder") {
+      item.coder_runs += 1;
+    } else if (checkpoint.stage === "reviewer-attempt") {
+      item.reviewer_attempts += 1;
+    } else if (checkpoint.stage === "reviewer") {
+      item.reviewer_approved = Boolean(checkpoint.approved);
+    }
+  }
+
+  return [...byIteration.values()].sort((a, b) => a.iteration - b.iteration);
+}
+
+function summarizePlan(checkpoints = []) {
+  const stages = checkpoints
+    .map((checkpoint) => checkpoint.stage)
+    .filter((stage) => typeof stage === "string" && stage.length > 0);
+
+  const uniqueOrdered = [];
+  for (const stage of stages) {
+    if (uniqueOrdered[uniqueOrdered.length - 1] !== stage) {
+      uniqueOrdered.push(stage);
+    }
+  }
+
+  return uniqueOrdered;
+}
+
+function summarizeSonar(checkpoints = []) {
+  const sonarPoints = checkpoints
+    .filter((checkpoint) => checkpoint.stage === "sonar" && typeof checkpoint.open_issues === "number")
+    .map((checkpoint) => checkpoint.open_issues);
+
+  if (sonarPoints.length === 0) {
+    return { initial: null, final: null, resolved: 0 };
+  }
+
+  const initial = sonarPoints[0];
+  const final = sonarPoints[sonarPoints.length - 1];
+  return {
+    initial,
+    final,
+    resolved: Math.max(initial - final, 0)
+  };
+}
+
+function summarizeCommits(session, checkpoints = []) {
+  const idsFromSession = Array.isArray(session?.git?.commits)
+    ? session.git.commits.filter((item) => typeof item === "string" && item.length > 0)
+    : [];
+
+  const idsFromCheckpoints = checkpoints
+    .filter((checkpoint) => checkpoint.stage === "git-commit" && checkpoint.committed && checkpoint.commit)
+    .map((checkpoint) => checkpoint.commit)
+    .filter((item) => typeof item === "string" && item.length > 0);
+
+  const ids = [...new Set([...idsFromSession, ...idsFromCheckpoints])];
+  if (ids.length > 0) {
+    return { count: ids.length, ids };
+  }
+
+  const committedCount = checkpoints.filter(
+    (checkpoint) => checkpoint.stage === "git-commit" && checkpoint.committed
+  ).length;
+
+  return { count: committedCount, ids: [] };
+}
+
+async function readActivityLog(sessionDir) {
+  const file = path.join(sessionDir, "activity.log");
+  if (!(await exists(file))) {
+    return "";
+  }
+
+  return fs.readFile(file, "utf8");
+}
+
+async function buildReport(dir, sessionId) {
+  const sessionDir = path.join(dir, sessionId);
+  const sessionFile = path.join(sessionDir, "session.json");
+  if (!(await exists(sessionFile))) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+  const content = await fs.readFile(sessionFile, "utf8");
+  const session = JSON.parse(content);
+  const checkpoints = Array.isArray(session.checkpoints) ? session.checkpoints : [];
+  const activityLog = await readActivityLog(sessionDir);
+
+  const sonar = summarizeSonar(checkpoints);
+  const budget = parseBudgetFromActivityLog(activityLog);
+  const commits = summarizeCommits(session, checkpoints);
+
+  const budgetTrace = Array.isArray(session.budget?.trace) ? session.budget.trace : [];
+
+  return {
+    session_id: session.id,
+    task_description: session.task || "",
+    plan_executed: summarizePlan(checkpoints),
+    iterations: summarizeIterations(checkpoints),
+    sonar_issues_resolved: {
+      initial_open_issues: sonar.initial,
+      final_open_issues: sonar.final,
+      resolved: sonar.resolved
+    },
+    budget_consumed: budget,
+    budget_trace: budgetTrace,
+    commits_generated: commits,
+    status: session.status || "unknown"
+  };
+}
+
+function printTextReport(report) {
+  const budgetText =
+    typeof report.budget_consumed?.consumed_usd === "number"
+      ? `$${report.budget_consumed.consumed_usd.toFixed(2)}${
+          typeof report.budget_consumed?.limit_usd === "number"
+            ? ` / $${report.budget_consumed.limit_usd.toFixed(2)}`
+            : ""
+        }`
+      : "N/A";
+
+  const planText = report.plan_executed.length > 0 ? report.plan_executed.join(" -> ") : "N/A";
+  const iterationText =
+    report.iterations.length > 0
+      ? report.iterations
+          .map(
+            (item) =>
+              `#${item.iteration} coder=${item.coder_runs} reviewer_attempts=${item.reviewer_attempts} approved=${item.reviewer_approved}`
+          )
+          .join("\n")
+      : "N/A";
+  const commitsText =
+    report.commits_generated.ids.length > 0
+      ? `${report.commits_generated.count} (${report.commits_generated.ids.join(", ")})`
+      : String(report.commits_generated.count);
+
+  console.log(`Session: ${report.session_id}`);
+  console.log(`Status: ${report.status}`);
+  console.log("Task Description:");
+  console.log(report.task_description || "N/A");
+  console.log("Plan Executed:");
+  console.log(planText);
+  console.log("Iterations (Coder/Reviewer):");
+  console.log(iterationText);
+  console.log("Sonar Issues Resolved:");
+  console.log(
+    `initial=${report.sonar_issues_resolved.initial_open_issues ?? "N/A"} final=${report.sonar_issues_resolved.final_open_issues ?? "N/A"} resolved=${report.sonar_issues_resolved.resolved}`
+  );
+  console.log("Budget Consumed:");
+  console.log(budgetText);
+  console.log("Commits Generated:");
+  console.log(commitsText);
+}
+
+function formatDuration(ms) {
+  if (ms === null || ms === undefined) return "-";
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainSeconds = (seconds % 60).toFixed(0);
+  return `${minutes}m${remainSeconds}s`;
+}
+
+function padRight(str, len) {
+  const s = String(str);
+  return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function padLeft(str, len) {
+  const s = String(str);
+  return s.length >= len ? s : " ".repeat(len - s.length) + s;
+}
+
+function convertCost(costUsd, currency, exchangeRate) {
+  if (currency === "eur") return costUsd * exchangeRate;
+  return costUsd;
+}
+
+function formatCost(cost, currency) {
+  const symbol = currency === "eur" ? "\u20AC" : "$";
+  return `${symbol}${cost.toFixed(4)}`;
+}
+
+function printTraceTable(trace, { currency = "usd", exchangeRate = 0.92 } = {}) {
+  if (!trace || trace.length === 0) {
+    console.log("No trace data available.");
+    return;
+  }
+
+  const currencyLabel = currency.toUpperCase();
+
+  const headers = ["#", "Stage", "Provider", "Duration", "Tokens In", "Tokens Out", `Cost ${currencyLabel}`];
+  const rows = trace.map((entry) => {
+    const cost = convertCost(entry.cost_usd, currency, exchangeRate);
+    return [
+      String(entry.index ?? "-"),
+      entry.role,
+      entry.provider || "-",
+      formatDuration(entry.duration_ms),
+      String(entry.tokens_in),
+      String(entry.tokens_out),
+      formatCost(cost, currency)
+    ];
+  });
+
+  const totals = trace.reduce(
+    (acc, entry) => {
+      acc.tokens_in += entry.tokens_in;
+      acc.tokens_out += entry.tokens_out;
+      acc.cost += entry.cost_usd;
+      acc.duration += entry.duration_ms ?? 0;
+      return acc;
+    },
+    { tokens_in: 0, tokens_out: 0, cost: 0, duration: 0 }
+  );
+
+  const totalRow = [
+    "",
+    "TOTAL",
+    "",
+    formatDuration(totals.duration),
+    String(totals.tokens_in),
+    String(totals.tokens_out),
+    formatCost(convertCost(totals.cost, currency, exchangeRate), currency)
+  ];
+
+  const allRows = [headers, ...rows, totalRow];
+  const colWidths = headers.map((_, colIdx) =>
+    Math.max(...allRows.map((row) => String(row[colIdx]).length))
+  );
+
+  const rightAligned = new Set([0, 3, 4, 5, 6]);
+  function formatRow(row) {
+    return row
+      .map((cell, idx) =>
+        rightAligned.has(idx)
+          ? padLeft(cell, colWidths[idx])
+          : padRight(cell, colWidths[idx])
+      )
+      .join("  ");
+  }
+
+  console.log(formatRow(headers));
+  console.log(colWidths.map((w) => "-".repeat(w)).join("  "));
+  for (const row of rows) {
+    console.log(formatRow(row));
+  }
+  console.log(colWidths.map((w) => "-".repeat(w)).join("  "));
+  console.log(formatRow(totalRow));
+}
+
+export async function reportCommand({ list = false, sessionId = null, format = "text", trace = false, currency = "usd" }) {
+  const dir = getSessionRoot();
+  if (!(await exists(dir))) {
+    console.log("No reports yet");
+    return;
+  }
+
+  const entries = await fs.readdir(dir);
+  if (list) {
+    for (const item of entries) console.log(item);
+    return;
+  }
+
+  const ids = [...entries].sort();
+  const selectedSessionId = sessionId || ids.at(-1);
+  if (!selectedSessionId) {
+    console.log("No reports yet");
+    return;
+  }
+  if (sessionId && !ids.includes(sessionId)) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+
+  const report = await buildReport(dir, selectedSessionId);
+  if (format === "json") {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  if (trace) {
+    const { config } = await loadConfig();
+    const cur = currency?.toLowerCase() || config?.budget?.currency || "usd";
+    const rate = config?.budget?.exchange_rate_eur ?? 0.92;
+    console.log(`Session: ${report.session_id}`);
+    console.log(`Status: ${report.status}`);
+    console.log(`Task: ${report.task_description || "N/A"}`);
+    console.log("");
+    printTraceTable(report.budget_trace, { currency: cur, exchangeRate: rate });
+    return;
+  }
+
+  printTextReport(report);
+}
+
+export { formatDuration, convertCost, formatCost, printTraceTable, buildReport };

package/src/commands/resume.js

@@ -0,0 +1,39 @@
+import { EventEmitter } from "node:events";
+import { resumeFlow } from "../orchestrator.js";
+import { createActivityLog } from "../activity-log.js";
+import { printEvent } from "../utils/display.js";
+
+export async function resumeCommand({ sessionId, answer, config, logger, flags }) {
+  const jsonMode = flags?.json;
+
+  const emitter = new EventEmitter();
+  let activityLog = null;
+
+  emitter.on("progress", (event) => {
+    if (!activityLog && event.sessionId) {
+      activityLog = createActivityLog(event.sessionId);
+      logger.onLog((entry) => activityLog.write(entry));
+    }
+
+    if (activityLog) {
+      activityLog.writeEvent(event);
+    }
+
+    if (!jsonMode) {
+      printEvent(event);
+    }
+  });
+
+  const result = await resumeFlow({
+    sessionId,
+    answer: answer || null,
+    config,
+    logger,
+    flags: flags || {},
+    emitter
+  });
+
+  if (jsonMode || !answer) {
+    console.log(JSON.stringify(result, null, 2));
+  }
+}

package/src/commands/review.js

@@ -0,0 +1,26 @@
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { computeBaseRef, generateDiff } from "../review/diff-generator.js";
+import { buildReviewerPrompt } from "../prompts/reviewer.js";
+import { resolveRole } from "../config.js";
+import { resolveReviewProfile } from "../review/profiles.js";
+
+export async function reviewCommand({ task, config, logger, baseRef }) {
+  const reviewerRole = resolveRole(config, "reviewer");
+  await assertAgentsAvailable([reviewerRole.provider, config.reviewer_options?.fallback_reviewer]);
+  logger.info(`Reviewer (${reviewerRole.provider}) starting...`);
+  const reviewer = createAgent(reviewerRole.provider, config, logger);
+  const resolvedBase = await computeBaseRef({ baseBranch: config.base_branch, baseRef });
+  const diff = await generateDiff({ baseRef: resolvedBase });
+  const { rules } = await resolveReviewProfile({ mode: config.review_mode, projectDir: process.cwd() });
+
+  const prompt = buildReviewerPrompt({ task, diff, reviewRules: rules, mode: config.review_mode });
+  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+  const result = await reviewer.reviewTask({ prompt, onOutput, role: "reviewer" });
+  if (!result.ok) {
+    if (result.error) logger.error(result.error);
+    throw new Error(result.error || result.output || `Reviewer failed (exit ${result.exitCode})`);
+  }
+  console.log(result.output);
+  logger.info(`Reviewer completed (exit ${result.exitCode})`);
+}

package/src/commands/roles.js

@@ -0,0 +1,117 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
+import { resolveRole } from "../config.js";
+import { exists } from "../utils/fs.js";
+
+const PIPELINE_ROLES = [
+  { name: "triage", description: "Classifies task complexity and activates pipeline roles" },
+  { name: "researcher", description: "Investigates codebase before planning" },
+  { name: "planner", description: "Generates implementation plans" },
+  { name: "coder", description: "Writes code and tests (TDD)" },
+  { name: "refactorer", description: "Improves code clarity without changing behavior" },
+  { name: "sonar", description: "SonarQube static analysis" },
+  { name: "reviewer", description: "Code review with configurable strictness" },
+  { name: "tester", description: "Test quality gate and coverage checks" },
+  { name: "security", description: "OWASP security audit" },
+  { name: "solomon", description: "Conflict resolver between agents" },
+  { name: "commiter", description: "Git commit, push, and PR automation" }
+];
+
+const REVIEW_VARIANTS = ["reviewer-strict", "reviewer-relaxed", "reviewer-paranoid"];
+
+function isRoleEnabled(config, roleName) {
+  if (roleName === "coder" || roleName === "commiter" || roleName === "sonar") {
+    if (roleName === "sonar") return Boolean(config?.sonarqube?.enabled);
+    return true;
+  }
+  if (roleName === "reviewer") return config?.pipeline?.reviewer?.enabled !== false;
+  return Boolean(config?.pipeline?.[roleName]?.enabled);
+}
+
+export function listRoles(config) {
+  return PIPELINE_ROLES.map((role) => {
+    const resolved = resolveRole(config, role.name);
+    return {
+      name: role.name,
+      description: role.description,
+      provider: resolved.provider || "-",
+      model: resolved.model || "-",
+      enabled: isRoleEnabled(config, role.name)
+    };
+  });
+}
+
+export async function showRole(roleName, config) {
+  const projectDir = config?.projectDir || process.cwd();
+  const candidates = resolveRoleMdPath(roleName, projectDir);
+
+  const customPath = candidates[0];
+  const hasCustom = await exists(customPath);
+
+  const content = await loadFirstExisting(candidates);
+  if (!content) {
+    return { found: false, roleName, content: null, source: null, customPath: null };
+  }
+
+  let source = "built-in";
+  if (hasCustom) {
+    source = "custom";
+  } else if (candidates.length > 2) {
+    try {
+      await fs.readFile(candidates[1], "utf8");
+      source = "user";
+    } catch {
+      source = "built-in";
+    }
+  }
+
+  return {
+    found: true,
+    roleName,
+    content,
+    source,
+    customPath: hasCustom ? customPath : null
+  };
+}
+
+function printRoleList(roles) {
+  const nameWidth = Math.max(...roles.map((r) => r.name.length), 4);
+  const provWidth = Math.max(...roles.map((r) => r.provider.length), 8);
+
+  const header = `${"Role".padEnd(nameWidth)}  ${"Provider".padEnd(provWidth)}  Enabled  Description`;
+  console.log(header);
+  console.log("-".repeat(header.length));
+
+  for (const role of roles) {
+    const enabled = role.enabled ? "yes" : "no ";
+    console.log(
+      `${role.name.padEnd(nameWidth)}  ${role.provider.padEnd(provWidth)}  ${enabled.padEnd(7)}  ${role.description}`
+    );
+  }
+}
+
+export async function rolesCommand({ config, subcommand, roleName }) {
+  if (subcommand === "show" && roleName) {
+    const result = await showRole(roleName, config);
+    if (!result.found) {
+      console.log(`Role "${roleName}" not found.`);
+      console.log(`Available roles: ${PIPELINE_ROLES.map((r) => r.name).join(", ")}`);
+      console.log(`Review variants: ${REVIEW_VARIANTS.join(", ")}`);
+      return result;
+    }
+    if (result.source === "custom") {
+      console.log(`[custom override: ${result.customPath}]\n`);
+    }
+    console.log(result.content);
+    return result;
+  }
+
+  const roles = listRoles(config);
+  printRoleList(roles);
+  console.log(`\nReview variants: ${REVIEW_VARIANTS.join(", ")}`);
+  console.log('\nUse "kj roles show <role>" to view template instructions.');
+  return roles;
+}
+
+export { PIPELINE_ROLES, REVIEW_VARIANTS };

package/src/commands/run.js

@@ -0,0 +1,91 @@
+import { EventEmitter } from "node:events";
+import { runFlow } from "../orchestrator.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { createActivityLog } from "../activity-log.js";
+import { printHeader, printEvent } from "../utils/display.js";
+import { resolveRole } from "../config.js";
+import { parseCardId, buildTaskFromCard, buildCompletionUpdates } from "../planning-game/adapter.js";
+
+export async function runCommandHandler({ task, config, logger, flags }) {
+  const requiredProviders = [
+    resolveRole(config, "coder").provider,
+    config.reviewer_options?.fallback_reviewer
+  ];
+  if (config.pipeline?.reviewer?.enabled !== false) {
+    requiredProviders.push(resolveRole(config, "reviewer").provider);
+  }
+  if (config.pipeline?.triage?.enabled) requiredProviders.push(resolveRole(config, "triage").provider);
+  if (config.pipeline?.planner?.enabled) requiredProviders.push(resolveRole(config, "planner").provider);
+  if (config.pipeline?.refactorer?.enabled) requiredProviders.push(resolveRole(config, "refactorer").provider);
+  if (config.pipeline?.researcher?.enabled) requiredProviders.push(resolveRole(config, "researcher").provider);
+  if (config.pipeline?.tester?.enabled) requiredProviders.push(resolveRole(config, "tester").provider);
+  if (config.pipeline?.security?.enabled) requiredProviders.push(resolveRole(config, "security").provider);
+  await assertAgentsAvailable(requiredProviders);
+
+  // --- Planning Game: resolve card context ---
+  const pgCardId = flags?.pgTask || parseCardId(task);
+  const pgProject = flags?.pgProject || config.planning_game?.project_id || null;
+  let pgCard = null;
+  let enrichedTask = task;
+
+  if (pgCardId && pgProject && config.planning_game?.enabled !== false) {
+    try {
+      const { fetchCard, updateCard } = await import("../planning-game/client.js");
+      pgCard = await fetchCard({ projectId: pgProject, cardId: pgCardId });
+      if (pgCard) {
+        enrichedTask = buildTaskFromCard(pgCard);
+        logger.info(`Planning Game: loaded card ${pgCardId} from project ${pgProject}`);
+      }
+    } catch (err) {
+      logger.warn(`Planning Game: could not load card ${pgCardId}: ${err.message}`);
+    }
+  }
+
+  const jsonMode = flags?.json;
+
+  const emitter = new EventEmitter();
+  let activityLog = null;
+
+  emitter.on("progress", (event) => {
+    if (!activityLog && event.sessionId) {
+      activityLog = createActivityLog(event.sessionId);
+      logger.onLog((entry) => activityLog.write(entry));
+    }
+
+    if (activityLog) {
+      activityLog.writeEvent(event);
+    }
+
+    if (!jsonMode) {
+      printEvent(event);
+    }
+  });
+
+  if (!jsonMode) {
+    printHeader({ task: enrichedTask, config });
+  }
+
+  const startDate = new Date().toISOString();
+  const result = await runFlow({ task: enrichedTask, config, logger, flags, emitter });
+
+  // --- Planning Game: update card on completion ---
+  if (pgCard && pgProject && result?.approved) {
+    try {
+      const { updateCard } = await import("../planning-game/client.js");
+      const updates = buildCompletionUpdates({
+        approved: true,
+        commits: result.git?.commits || [],
+        startDate,
+        codeveloper: config.planning_game?.codeveloper || null
+      });
+      await updateCard({ projectId: pgProject, cardId: pgCardId, firebaseId: pgCard.firebaseId, updates });
+      logger.info(`Planning Game: updated ${pgCardId} to "${updates.status}"`);
+    } catch (err) {
+      logger.warn(`Planning Game: could not update card ${pgCardId}: ${err.message}`);
+    }
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify(result, null, 2));
+  }
+}

package/src/commands/scan.js

@@ -0,0 +1,18 @@
+import { getOpenIssues, getQualityGateStatus } from "../sonar/api.js";
+import { runSonarScan } from "../sonar/scanner.js";
+import { summarizeIssues } from "../sonar/enforcer.js";
+
+export async function scanCommand({ config }) {
+  const scan = await runSonarScan(config);
+  if (!scan.ok) {
+    throw new Error(`Sonar scan failed: ${scan.stderr || scan.stdout}`);
+  }
+
+  const gate = await getQualityGateStatus(config, scan.projectKey);
+  const issues = await getOpenIssues(config, scan.projectKey);
+
+  console.log(`Project key: ${scan.projectKey}`);
+  console.log(`Quality Gate: ${gate.status}`);
+  console.log(`Open issues: ${issues.total}`);
+  console.log(`By severity: ${summarizeIssues(issues.issues) || "none"}`);
+}