karajan-code 1.2.0

package/src/commands/sonar.js

@@ -0,0 +1,53 @@
+import os from "node:os";
+import { sonarDown, sonarLogs, sonarStatus, sonarUp, isSonarReachable } from "../sonar/manager.js";
+import { resolveSonarProjectKey } from "../sonar/project-key.js";
+import { runCommand } from "../utils/process.js";
+
+function openBrowserCmd() {
+  const platform = os.platform();
+  if (platform === "darwin") return "open";
+  if (platform === "win32") return "start";
+  return "xdg-open";
+}
+
+export async function sonarOpenCommand({ config }) {
+  const host = config?.sonarqube?.host || "http://localhost:9000";
+
+  if (!(await isSonarReachable(host))) {
+    return { ok: false, error: `SonarQube is not reachable at ${host}. Run 'kj sonar start' first.` };
+  }
+
+  let projectKey;
+  try {
+    projectKey = await resolveSonarProjectKey(config);
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+
+  const url = `${host}/dashboard?id=${projectKey}`;
+  await runCommand(openBrowserCmd(), [url]);
+  return { ok: true, url };
+}
+
+export async function sonarCommand({ action }) {
+  if (action === "start") {
+    const res = await sonarUp();
+    console.log(res.stdout || res.stderr);
+    return;
+  }
+
+  if (action === "stop") {
+    const res = await sonarDown();
+    console.log(res.stdout || res.stderr);
+    return;
+  }
+
+  if (action === "logs") {
+    const res = await sonarLogs();
+    console.log(res.stdout || res.stderr);
+    return;
+  }
+
+  const res = await sonarStatus();
+  console.log(res.stdout || "stopped");
+}

package/src/config.js

@@ -0,0 +1,322 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { ensureDir, exists } from "./utils/fs.js";
+import { getKarajanHome } from "./utils/paths.js";
+
+const DEFAULTS = {
+  coder: "claude",
+  reviewer: "codex",
+  roles: {
+    planner: { provider: null, model: null },
+    coder: { provider: null, model: null },
+    reviewer: { provider: null, model: null },
+    refactorer: { provider: null, model: null },
+    solomon: { provider: null, model: null },
+    researcher: { provider: null, model: null },
+    tester: { provider: null, model: null },
+    security: { provider: null, model: null },
+    triage: { provider: null, model: null }
+  },
+  pipeline: {
+    planner: { enabled: false },
+    refactorer: { enabled: false },
+    solomon: { enabled: false },
+    researcher: { enabled: false },
+    tester: { enabled: false },
+    security: { enabled: false },
+    triage: { enabled: false }
+  },
+  review_mode: "standard",
+  max_iterations: 5,
+  max_budget_usd: null,
+  review_rules: "./review-rules.md",
+  coder_rules: "./coder-rules.md",
+  base_branch: "main",
+  coder_options: { model: null, auto_approve: true },
+  reviewer_options: {
+    output_format: "json",
+    require_schema: true,
+    model: null,
+    deterministic: true,
+    retries: 1,
+    fallback_reviewer: "codex"
+  },
+  development: {
+    methodology: "tdd",
+    require_test_changes: true,
+    test_file_patterns: ["/tests/", "/__tests__/", ".test.", ".spec."],
+    source_file_extensions: [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".rb", ".php", ".cs"]
+  },
+  sonarqube: {
+    enabled: true,
+    host: "http://localhost:9000",
+    external: false,
+    container_name: "karajan-sonarqube",
+    network: "karajan_sonar_net",
+    volumes: {
+      data: "karajan_sonar_data",
+      logs: "karajan_sonar_logs",
+      extensions: "karajan_sonar_extensions"
+    },
+    timeouts: {
+      healthcheck_seconds: 5,
+      compose_up_ms: 300000,
+      compose_control_ms: 120000,
+      logs_ms: 30000,
+      scanner_ms: 900000
+    },
+    token: null,
+    project_key: null,
+    admin_user: "admin",
+    admin_password: null,
+    coverage: {
+      enabled: false,
+      command: null,
+      timeout_ms: 300000,
+      block_on_failure: true,
+      lcov_report_path: null
+    },
+    quality_gate: true,
+    enforcement_profile: "pragmatic",
+    gate_block_on: [
+      "new_reliability_rating=E",
+      "new_security_rating=E",
+      "new_maintainability_rating=E",
+      "new_coverage<80",
+      "new_duplicated_lines_density>5"
+    ],
+    fail_on: ["BLOCKER", "CRITICAL"],
+    ignore_on: ["INFO"],
+    max_scan_retries: 3,
+    scanner: {
+      sources: "src,public,lib",
+      exclusions: "**/node_modules/**,**/fake-apps/**,**/scripts/**,**/playground/**,**/dist/**,**/build/**,**/*.min.js",
+      test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**",
+      coverage_exclusions: "**/tests/**,**/__tests__/**,**/*.test.js,**/*.spec.js",
+      disabled_rules: ["javascript:S1116", "javascript:S3776"]
+    }
+  },
+  serena: { enabled: false },
+  planning_game: { enabled: false, project_id: null, codeveloper: null },
+  git: { auto_commit: false, auto_push: false, auto_pr: false, auto_rebase: true, branch_prefix: "feat/" },
+  output: { report_dir: "./.reviews", log_level: "info" },
+  budget: {
+    warn_threshold_pct: 80,
+    currency: "usd",
+    exchange_rate_eur: 0.92
+  },
+  session: {
+    max_iteration_minutes: 15,
+    max_total_minutes: 120,
+    fail_fast_repeats: 2,
+    repeat_detection_threshold: 2,
+    max_sonar_retries: 3,
+    max_reviewer_retries: 3,
+    max_tester_retries: 1,
+    max_security_retries: 1
+  },
+  failFast: {
+    repeatThreshold: 2
+  }
+};
+
+function mergeDeep(base, override) {
+  const output = { ...base };
+  for (const [key, value] of Object.entries(override || {})) {
+    if (Array.isArray(value)) {
+      output[key] = value;
+    } else if (value && typeof value === "object") {
+      output[key] = mergeDeep(base[key] || {}, value);
+    } else {
+      output[key] = value;
+    }
+  }
+  return output;
+}
+
+export function getConfigPath() {
+  return path.join(getKarajanHome(), "kj.config.yml");
+}
+
+async function loadProjectPricingOverrides(projectDir = process.cwd()) {
+  const projectConfigPath = path.join(projectDir, ".karajan.yml");
+  if (!(await exists(projectConfigPath))) {
+    return null;
+  }
+
+  const raw = await fs.readFile(projectConfigPath, "utf8");
+  const parsed = yaml.load(raw) || {};
+  const pricing = parsed?.budget?.pricing;
+  if (!pricing || typeof pricing !== "object") {
+    return null;
+  }
+
+  return pricing;
+}
+
+export async function loadConfig() {
+  const configPath = getConfigPath();
+  const projectPricing = await loadProjectPricingOverrides();
+  if (!(await exists(configPath))) {
+    const baseDefaults = mergeDeep(DEFAULTS, {});
+    if (projectPricing) {
+      baseDefaults.budget = mergeDeep(baseDefaults.budget || {}, { pricing: projectPricing });
+    }
+    return { config: baseDefaults, path: configPath, exists: false };
+  }
+
+  const raw = await fs.readFile(configPath, "utf8");
+  const parsed = yaml.load(raw) || {};
+  const merged = mergeDeep(DEFAULTS, parsed);
+  if (projectPricing) {
+    merged.budget = mergeDeep(merged.budget || {}, { pricing: projectPricing });
+  }
+  return { config: merged, path: configPath, exists: true };
+}
+
+export async function writeConfig(configPath, config) {
+  await ensureDir(path.dirname(configPath));
+  await fs.writeFile(configPath, yaml.dump(config, { lineWidth: 120 }), "utf8");
+}
+
+export function applyRunOverrides(config, flags) {
+  const out = mergeDeep(config, {});
+  out.coder_options = out.coder_options || {};
+  out.reviewer_options = out.reviewer_options || {};
+  out.session = out.session || {};
+  out.git = out.git || {};
+  out.development = out.development || {};
+  out.sonarqube = out.sonarqube || {};
+  if (out.max_budget_usd === undefined || out.max_budget_usd === null) {
+    out.max_budget_usd = out.session.max_budget_usd ?? null;
+  }
+  out.budget = mergeDeep(DEFAULTS.budget, out.budget || {});
+  out.roles = mergeDeep(DEFAULTS.roles, out.roles || {});
+  out.pipeline = mergeDeep(DEFAULTS.pipeline, out.pipeline || {});
+
+  if (flags.planner) out.roles.planner.provider = flags.planner;
+  if (flags.coder) out.coder = flags.coder;
+  if (flags.coder) out.roles.coder.provider = flags.coder;
+  if (flags.reviewer) out.reviewer = flags.reviewer;
+  if (flags.reviewer) out.roles.reviewer.provider = flags.reviewer;
+  if (flags.refactorer) out.roles.refactorer.provider = flags.refactorer;
+  if (flags.solomon) out.roles.solomon.provider = flags.solomon;
+  if (flags.researcher) out.roles.researcher.provider = flags.researcher;
+  if (flags.tester) out.roles.tester.provider = flags.tester;
+  if (flags.security) out.roles.security.provider = flags.security;
+  if (flags.triage) out.roles.triage.provider = flags.triage;
+  if (flags.plannerModel) out.roles.planner.model = String(flags.plannerModel);
+  if (flags.coderModel) {
+    out.roles.coder.model = String(flags.coderModel);
+  }
+  if (flags.reviewerModel) {
+    out.roles.reviewer.model = String(flags.reviewerModel);
+    out.reviewer_options.model = String(flags.reviewerModel);
+  }
+  if (flags.refactorerModel) out.roles.refactorer.model = String(flags.refactorerModel);
+  if (flags.solomonModel) out.roles.solomon.model = String(flags.solomonModel);
+  if (flags.enablePlanner !== undefined) out.pipeline.planner.enabled = Boolean(flags.enablePlanner);
+  if (flags.enableRefactorer !== undefined) out.pipeline.refactorer.enabled = Boolean(flags.enableRefactorer);
+  if (flags.enableSolomon !== undefined) out.pipeline.solomon.enabled = Boolean(flags.enableSolomon);
+  if (flags.enableResearcher !== undefined) out.pipeline.researcher.enabled = Boolean(flags.enableResearcher);
+  if (flags.enableTester !== undefined) out.pipeline.tester.enabled = Boolean(flags.enableTester);
+  if (flags.enableSecurity !== undefined) out.pipeline.security.enabled = Boolean(flags.enableSecurity);
+  if (flags.enableReviewer !== undefined) {
+    out.pipeline.reviewer = out.pipeline.reviewer || {};
+    out.pipeline.reviewer.enabled = Boolean(flags.enableReviewer);
+  }
+  if (flags.enableTriage !== undefined) out.pipeline.triage.enabled = Boolean(flags.enableTriage);
+  if (flags.mode) out.review_mode = flags.mode;
+  if (flags.maxIterations) out.max_iterations = Number(flags.maxIterations);
+  if (flags.maxIterationMinutes) out.session.max_iteration_minutes = Number(flags.maxIterationMinutes);
+  if (flags.maxTotalMinutes) out.session.max_total_minutes = Number(flags.maxTotalMinutes);
+  if (flags.baseBranch) out.base_branch = flags.baseBranch;
+  if (flags.reviewerFallback) out.reviewer_options.fallback_reviewer = flags.reviewerFallback;
+  if (flags.reviewerRetries !== undefined) out.reviewer_options.retries = Number(flags.reviewerRetries);
+  if (flags.autoCommit !== undefined) out.git.auto_commit = Boolean(flags.autoCommit);
+  if (flags.autoPush !== undefined) out.git.auto_push = Boolean(flags.autoPush);
+  if (flags.autoPr !== undefined) out.git.auto_pr = Boolean(flags.autoPr);
+  if (flags.autoRebase !== undefined) out.git.auto_rebase = Boolean(flags.autoRebase);
+  if (flags.branchPrefix) out.git.branch_prefix = String(flags.branchPrefix);
+  if (flags.methodology) {
+    const methodology = String(flags.methodology).toLowerCase();
+    out.development = out.development || {};
+    out.development.methodology = methodology;
+    out.development.require_test_changes = methodology === "tdd";
+  }
+  if (flags.noSonar || flags.sonar === false) out.sonarqube.enabled = false;
+  out.serena = out.serena || { enabled: false };
+  if (flags.enableSerena !== undefined) out.serena.enabled = Boolean(flags.enableSerena);
+  out.planning_game = out.planning_game || {};
+  if (flags.pgTask) out.planning_game.enabled = true;
+  if (flags.pgProject) out.planning_game.project_id = flags.pgProject;
+  return out;
+}
+
+export function resolveRole(config, role) {
+  const roles = config?.roles || {};
+  const roleConfig = roles[role] || {};
+  const legacyCoder = config?.coder || null;
+  const legacyReviewer = config?.reviewer || null;
+
+  let provider = roleConfig.provider ?? null;
+  if (!provider && role === "coder") provider = legacyCoder;
+  if (!provider && role === "reviewer") provider = legacyReviewer;
+  if (!provider && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "triage")) {
+    provider = roles.coder?.provider || legacyCoder;
+  }
+
+  let model = roleConfig.model ?? null;
+  if (!model && role === "coder") model = config?.coder_options?.model ?? null;
+  if (!model && role === "reviewer") model = config?.reviewer_options?.model ?? null;
+  if (!model && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "triage")) {
+    model = config?.coder_options?.model ?? null;
+  }
+
+  return { provider, model };
+}
+
+function requiredRolesFor(commandName, config) {
+  if (commandName === "run") {
+    const required = ["coder"];
+    if (config?.pipeline?.reviewer?.enabled !== false) required.push("reviewer");
+    if (config?.pipeline?.triage?.enabled) required.push("triage");
+    if (config?.pipeline?.planner?.enabled) required.push("planner");
+    if (config?.pipeline?.refactorer?.enabled) required.push("refactorer");
+    if (config?.pipeline?.researcher?.enabled) required.push("researcher");
+    if (config?.pipeline?.tester?.enabled) required.push("tester");
+    if (config?.pipeline?.security?.enabled) required.push("security");
+    return required;
+  }
+  if (commandName === "plan") return ["planner"];
+  if (commandName === "code") return ["coder"];
+  if (commandName === "review") return ["reviewer"];
+  return [];
+}
+
+export function validateConfig(config, commandName = "run") {
+  const errors = [];
+  if (!["paranoid", "strict", "standard", "relaxed", "custom"].includes(config.review_mode)) {
+    errors.push(`Invalid review_mode: ${config.review_mode}`);
+  }
+  if (!["tdd", "standard"].includes(config.development?.methodology)) {
+    errors.push(`Invalid development.methodology: ${config.development?.methodology}`);
+  }
+
+  const requiredRoles = requiredRolesFor(commandName, config);
+  for (const role of requiredRoles) {
+    const { provider } = resolveRole(config, role);
+    if (!provider) {
+      errors.push(
+        `Missing provider for required role '${role}'. Set 'roles.${role}.provider' or pass '--${role} <name>'`
+      );
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+
+  return config;
+}

package/src/git/automation.js

@@ -0,0 +1,100 @@
+/**
+ * Git automation helpers for the pipeline.
+ * Extracted from orchestrator.js for testability and reuse.
+ */
+
+import { addCheckpoint } from "../session-store.js";
+import {
+  ensureGitRepo,
+  currentBranch,
+  fetchBase,
+  syncBaseBranch,
+  ensureBranchUpToDateWithBase,
+  createBranch,
+  buildBranchName,
+  commitAll,
+  pushBranch,
+  createPullRequest
+} from "../utils/git.js";
+
+export function commitMessageFromTask(task) {
+  const clean = String(task || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return `feat: ${clean.slice(0, 72) || "karajan update"}`;
+}
+
+export async function prepareGitAutomation({ config, task, logger, session }) {
+  const enabled = config.git.auto_commit || config.git.auto_push || config.git.auto_pr;
+  if (!enabled) return { enabled: false };
+
+  if (!(await ensureGitRepo())) {
+    throw new Error("Git automation requested but current directory is not a git repository");
+  }
+
+  const baseBranch = config.base_branch;
+  const autoRebase = config.git.auto_rebase !== false;
+  await fetchBase(baseBranch);
+
+  let branch = await currentBranch();
+  if (branch === baseBranch) {
+    await syncBaseBranch({ baseBranch, autoRebase });
+    const created = buildBranchName(config.git.branch_prefix || "feat/", task);
+    await createBranch(created);
+    branch = created;
+    logger.info(`Created working branch: ${branch}`);
+    await addCheckpoint(session, { stage: "git-prep", branch, created: true });
+  } else {
+    await ensureBranchUpToDateWithBase({ branch, baseBranch, autoRebase });
+    await addCheckpoint(session, { stage: "git-prep", branch, created: false });
+  }
+
+  return { enabled: true, branch, baseBranch, autoRebase };
+}
+
+export async function finalizeGitAutomation({ config, gitCtx, task, logger, session }) {
+  if (!gitCtx?.enabled) return { git: "disabled", commits: [] };
+
+  const commitMsg = config.git.commit_message || commitMessageFromTask(task);
+  let committed = false;
+  const commits = [];
+  if (config.git.auto_commit) {
+    const commitResult = await commitAll(commitMsg);
+    committed = commitResult.committed;
+    if (commitResult.commit) {
+      commits.push(commitResult.commit);
+    }
+    await addCheckpoint(session, { stage: "git-commit", committed });
+    logger.info(committed ? "Committed changes" : "No changes to commit");
+  }
+
+  if (config.git.auto_push || config.git.auto_pr) {
+    await fetchBase(gitCtx.baseBranch);
+    await ensureBranchUpToDateWithBase({
+      branch: gitCtx.branch,
+      baseBranch: gitCtx.baseBranch,
+      autoRebase: gitCtx.autoRebase
+    });
+    await addCheckpoint(session, { stage: "git-rebase-check", branch: gitCtx.branch });
+  }
+
+  if (config.git.auto_push || config.git.auto_pr) {
+    await pushBranch(gitCtx.branch);
+    await addCheckpoint(session, { stage: "git-push", branch: gitCtx.branch });
+    logger.info(`Pushed branch: ${gitCtx.branch}`);
+  }
+
+  let prUrl = null;
+  if (config.git.auto_pr) {
+    prUrl = await createPullRequest({
+      baseBranch: gitCtx.baseBranch,
+      branch: gitCtx.branch,
+      title: commitMessageFromTask(task),
+      body: "Created by Karajan Code."
+    });
+    await addCheckpoint(session, { stage: "git-pr", branch: gitCtx.branch, pr: prUrl });
+    logger.info("Pull request created");
+  }
+
+  return { committed, branch: gitCtx.branch, prUrl, pr: prUrl, commits };
+}

package/src/mcp/progress.js

@@ -0,0 +1,69 @@
+/**
+ * MCP progress notification helpers.
+ * Extracted from server.js for testability and reuse.
+ */
+
+export const PROGRESS_STAGES = [
+  "session:start",
+  "iteration:start",
+  "planner:start",
+  "planner:end",
+  "coder:start",
+  "coder:end",
+  "refactorer:start",
+  "refactorer:end",
+  "tdd:result",
+  "sonar:start",
+  "sonar:end",
+  "reviewer:start",
+  "reviewer:end",
+  "iteration:end",
+  "solomon:escalate",
+  "question",
+  "session:end",
+  "dry-run:summary"
+];
+
+export function buildProgressHandler(server) {
+  return (event) => {
+    try {
+      server.sendLoggingMessage({
+        level: event.type === "agent:output" ? "debug" : event.status === "fail" ? "error" : "info",
+        logger: "karajan",
+        data: event
+      });
+    } catch {
+      // best-effort: if logging fails, continue
+    }
+  };
+}
+
+export function buildProgressNotifier(extra) {
+  const progressToken = extra?._meta?.progressToken;
+  if (progressToken === undefined) return null;
+
+  const total = PROGRESS_STAGES.length;
+  return (event) => {
+    const idx = PROGRESS_STAGES.indexOf(event.type);
+    if (idx < 0) return;
+
+    const iteration = event.iteration || event.detail?.iteration;
+    const message = iteration
+      ? `[${event.iteration}] ${event.message || event.type}`
+      : event.message || event.type;
+
+    try {
+      extra.sendNotification({
+        method: "notifications/progress",
+        params: {
+          progressToken,
+          progress: idx + 1,
+          total,
+          message
+        }
+      });
+    } catch {
+      // best-effort
+    }
+  };
+}

package/src/mcp/run-kj.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execa } from "execa";
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const CLI_PATH = path.resolve(MODULE_DIR, "..", "cli.js");
+
+function normalizeBoolFlag(value, flagName, args) {
+  if (value === true) args.push(flagName);
+}
+
+function addOptionalValue(args, flag, value) {
+  if (value !== undefined && value !== null && value !== "") {
+    args.push(flag, String(value));
+  }
+}
+
+export async function runKjCommand({ command, commandArgs = [], options = {}, env = {} }) {
+  const args = [CLI_PATH, command, ...commandArgs];
+
+  addOptionalValue(args, "--coder", options.coder);
+  addOptionalValue(args, "--reviewer", options.reviewer);
+  addOptionalValue(args, "--planner", options.planner);
+  addOptionalValue(args, "--refactorer", options.refactorer);
+  addOptionalValue(args, "--planner-model", options.plannerModel);
+  addOptionalValue(args, "--coder-model", options.coderModel);
+  addOptionalValue(args, "--reviewer-model", options.reviewerModel);
+  addOptionalValue(args, "--refactorer-model", options.refactorerModel);
+  addOptionalValue(args, "--reviewer-fallback", options.reviewerFallback);
+  addOptionalValue(args, "--reviewer-retries", options.reviewerRetries);
+  addOptionalValue(args, "--mode", options.mode);
+  addOptionalValue(args, "--max-iterations", options.maxIterations);
+  addOptionalValue(args, "--max-iteration-minutes", options.maxIterationMinutes);
+  addOptionalValue(args, "--max-total-minutes", options.maxTotalMinutes);
+  addOptionalValue(args, "--base-branch", options.baseBranch);
+  addOptionalValue(args, "--base-ref", options.baseRef);
+  addOptionalValue(args, "--branch-prefix", options.branchPrefix);
+  addOptionalValue(args, "--methodology", options.methodology);
+  normalizeBoolFlag(options.enablePlanner, "--enable-planner", args);
+  normalizeBoolFlag(options.enableReviewer, "--enable-reviewer", args);
+  normalizeBoolFlag(options.enableRefactorer, "--enable-refactorer", args);
+  normalizeBoolFlag(options.enableResearcher, "--enable-researcher", args);
+  normalizeBoolFlag(options.enableTester, "--enable-tester", args);
+  normalizeBoolFlag(options.enableSecurity, "--enable-security", args);
+  normalizeBoolFlag(options.enableTriage, "--enable-triage", args);
+  normalizeBoolFlag(options.enableSerena, "--enable-serena", args);
+  normalizeBoolFlag(options.autoCommit, "--auto-commit", args);
+  normalizeBoolFlag(options.autoPush, "--auto-push", args);
+  normalizeBoolFlag(options.autoPr, "--auto-pr", args);
+  if (options.autoRebase === false) args.push("--no-auto-rebase");
+  normalizeBoolFlag(options.noSonar, "--no-sonar", args);
+  addOptionalValue(args, "--pg-task", options.pgTask);
+  addOptionalValue(args, "--pg-project", options.pgProject);
+
+  const runEnv = {
+    ...process.env,
+    ...env
+  };
+
+  if (options.kjHome) {
+    runEnv.KJ_HOME = options.kjHome;
+  }
+
+  if (options.sonarToken) {
+    runEnv.KJ_SONAR_TOKEN = options.sonarToken;
+  }
+
+  const result = await execa("node", args, {
+    env: runEnv,
+    reject: false,
+    timeout: options.timeoutMs ? Number(options.timeoutMs) : undefined
+  });
+
+  const ok = result.exitCode === 0;
+  const payload = {
+    ok,
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr
+  };
+
+  if (!ok && result.stderr) {
+    payload.errorSummary = result.stderr.split("\n").filter(Boolean).slice(-3).join(" | ");
+  }
+
+  return payload;
+}