karajan-code 2.7.3 → 2.8.0

package/src/config/defaults.js

@@ -0,0 +1,213 @@
+/**
+ * Karajan's default configuration — the baseline every user's config is
+ * merged on top of.
+ *
+ * This is **pure data**. It was extracted from `src/config.js` in TSK-0332
+ * (Oleada 2 of the v2.7.4 audit refactor) so that consumers that only
+ * need the shape (schema tests, display, docs) don't drag the loader's
+ * fs/yaml imports.
+ *
+ * Source of truth is here; `src/config.js` re-exports `DEFAULTS` for
+ * back-compat.
+ */
+
+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 },
+    impeccable: { provider: null, model: null },
+    triage: { provider: null, model: null },
+    discover: { provider: null, model: null },
+    architect: { provider: null, model: null },
+    hu_reviewer: { provider: null, model: null }
+  },
+  pipeline: {
+    planner: { enabled: false },
+    refactorer: { enabled: false },
+    solomon: { enabled: true },
+    researcher: { enabled: false },
+    tester: { enabled: true },
+    security: { enabled: true },
+    impeccable: { enabled: false },
+    triage: { enabled: true },
+    discover: { enabled: false },
+    architect: { enabled: false },
+    hu_reviewer: { enabled: false },
+    brain: { enabled: true },
+    auto_simplify: true
+  },
+  brain: {
+    enabled: true,
+    provider: "claude",
+    bypass_solomon_on_correctness: true,
+    max_consecutive_verification_failures: 2
+  },
+  review_mode: "standard",
+  max_iterations: 5,
+  hu_max_iterations: 3,
+  max_budget_usd: null,
+  review_rules: "./.karajan/review-rules.md",
+  coder_rules: "./.karajan/coder-rules.md",
+  base_branch: "main",
+  coder_options: { model: null, auto_approve: true, fallback_coder: null },
+  reviewer_options: {
+    output_format: "json",
+    require_schema: true,
+    model: null,
+    deterministic: true,
+    retries: 1,
+    fallback_reviewer: null
+  },
+  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: null,
+    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"]
+    }
+  },
+  sonarcloud: {
+    enabled: false,
+    organization: null,
+    token: null,
+    project_key: null,
+    host: "https://sonarcloud.io",
+    scanner: {
+      sources: "src,public,lib",
+      exclusions: "**/node_modules/**,**/dist/**,**/build/**,**/*.min.js",
+      test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**"
+    }
+  },
+  hu_board: {
+    enabled: false,
+    port: 4000,
+    auto_start: false
+  },
+  language: "en",
+  hu_language: "en",
+  policies: {},
+  serena: { enabled: false },
+  planning_game: { enabled: false, project_id: null, codeveloper: null },
+  skills: {
+    mode: "auto",
+    sources: ["addyosmani", "openskills", "local"],
+    addyosmani: {
+      enabled: true,
+      refreshDays: 7,
+      repoUrl: "https://github.com/addyosmani/agent-skills.git"
+    }
+  },
+  ci: { enabled: false, review_event: "kj-review", comment_event: "kj-comment", comment_prefix: true },
+  git: { auto_commit: false, auto_push: false, auto_pr: false, auto_rebase: true, branch_prefix: "feat/" },
+  output: { report_dir: "./.reviews", log_level: "info", quiet: true },
+  budget: {
+    warn_threshold_pct: 80,
+    currency: "usd",
+    exchange_rate_eur: 0.92
+  },
+  model_selection: {
+    enabled: true,
+    tiers: {},
+    role_overrides: {}
+  },
+  session: {
+    max_iteration_minutes: 30,
+    max_total_minutes: 120,
+    max_planner_minutes: 60,
+    checkpoint_interval_minutes: 5,
+    max_agent_silence_minutes: 20,
+    fail_fast_repeats: 2,
+    repeat_detection_threshold: 2,
+    max_sonar_retries: 3,
+    max_reviewer_retries: 3,
+    max_tester_retries: 1,
+    max_security_retries: 1,
+    max_auto_resumes: 2,
+    expiry_days: 30
+  },
+  failFast: {
+    repeatThreshold: 2
+  },
+  webperf: {
+    enabled: true,
+    devtools_mcp: false,
+    thresholds: { lcp: 2500, cls: 0.1, inp: 200 }
+  },
+  telemetry: true,
+  guards: {
+    output: {
+      enabled: true,
+      patterns: [],
+      protected_files: [],
+      on_violation: "block"
+    },
+    perf: {
+      enabled: true,
+      patterns: [],
+      block_on_warning: false,
+      frontend_extensions: []
+    },
+    intent: {
+      enabled: false,
+      patterns: [],
+      confidence_threshold: 0.85
+    }
+  }
+};
+export { DEFAULTS };
+

package/src/config/loader.js

@@ -0,0 +1,137 @@
+/**
+ * Config I/O layer — reads and writes Karajan's YAML config files.
+ *
+ * Extracted from `src/config.js` in TSK-0332 (Oleada 2 of the v2.7.4 audit
+ * refactor). The public API (`loadConfig`, `writeConfig`, `getConfigPath`,
+ * `getProjectConfigPath`, `loadProjectConfig`) stayed exactly the same so
+ * the 28+ files that imported from `src/config.js` didn't have to change.
+ *
+ * Responsibilities:
+ *   - Resolve the global config path under `~/.karajan/kj.config.yml`
+ *     (respecting `KJ_HOME`).
+ *   - Resolve the project config path under `<projectDir>/.karajan/kj.config.yml`.
+ *   - Load + merge global over DEFAULTS, then project over merged.
+ *   - Validate the merged config via the Valibot schema.
+ *   - Record deprecation flags (e.g. `sonarqube.enabled` → ignored since v2.7.4)
+ *     for the orchestrator to surface as warnings at run start.
+ *
+ * Intentionally NOT here: flag overrides (src/config/overrides.js),
+ * role resolution (src/config/role-resolver.js), DEFAULTS (src/config/defaults.js).
+ */
+
+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";
+import { safeParseConfig, formatConfigIssues } from "./schema.js";
+import { DEFAULTS } from "./defaults.js";
+import { resolveTestHarness } from "./test-harness.js";
+
+export 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");
+}
+
+export function getProjectConfigPath(projectDir = process.cwd()) {
+  return path.join(projectDir, ".karajan", "kj.config.yml");
+}
+
+export async function loadProjectConfig(projectDir = process.cwd()) {
+  const projectConfigPath = getProjectConfigPath(projectDir);
+  if (!(await exists(projectConfigPath))) {
+    return null;
+  }
+  const raw = await fs.readFile(projectConfigPath, "utf8");
+  return yaml.load(raw, { json: true }) || {};
+}
+
+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, { json: true }) || {};
+  const pricing = parsed?.budget?.pricing;
+  if (!pricing || typeof pricing !== "object") {
+    return null;
+  }
+
+  return pricing;
+}
+
+export async function loadConfig(projectDir) {
+  const configPath = getConfigPath();
+  const projectPricing = await loadProjectPricingOverrides(projectDir);
+
+  // Load global config
+  let globalConfig = {};
+  const globalExists = await exists(configPath);
+  if (globalExists) {
+    const raw = await fs.readFile(configPath, "utf8");
+    globalConfig = yaml.load(raw, { json: true }) || {};
+  }
+
+  // Load project config (.karajan/kj.config.yml)
+  const projectConfig = await loadProjectConfig(projectDir);
+
+  // Merge: DEFAULTS < global < project
+  let merged = mergeDeep(DEFAULTS, globalConfig);
+  if (projectConfig) {
+    merged = mergeDeep(merged, projectConfig);
+  }
+
+  if (projectPricing) {
+    merged.budget = mergeDeep(merged.budget || {}, { pricing: projectPricing });
+  }
+
+  // KJC-TSK-0318 — schema-validate the merged config so invalid values
+  // (review_mode typos, max_iterations=0, out-of-range ports) surface at
+  // load time with a clear error instead of crashing deep inside the
+  // orchestrator. safeParse + explicit error prefix keeps the message
+  // actionable.
+  const validation = safeParseConfig(merged);
+  if (!validation.success) {
+    throw new Error(`Invalid Karajan config:\n${formatConfigIssues(validation.issues)}`);
+  }
+
+  // Deprecation tracking — `sonarqube.enabled` was a footgun: users would
+  // set it to `false` in their global ~/.karajan/kj.config.yml and then
+  // wonder why Sonar didn't run on a code task. Since v2.7.4 Sonar is
+  // intrinsic to Karajan for code tasks; the field is ignored. We surface
+  // a warning at run start (see emitConfigDeprecations in flow-runner.js)
+  // so users notice and clean up their config. Don't throw — keep
+  // back-compat so existing scripts keep working.
+  const userSetSonarEnabled = (globalConfig?.sonarqube?.enabled !== undefined)
+    || (projectConfig?.sonarqube?.enabled !== undefined);
+  if (userSetSonarEnabled) {
+    merged._deprecated = merged._deprecated || {};
+    merged._deprecated.sonarqubeEnabledKey = true;
+  }
+
+  merged.testHarness = resolveTestHarness(merged.testHarness);
+  return { config: merged, path: configPath, exists: globalExists, hasProjectConfig: !!projectConfig };
+}
+
+export async function writeConfig(configPath, config) {
+  await ensureDir(path.dirname(configPath));
+  await fs.writeFile(configPath, yaml.dump(config, { lineWidth: 120 }), "utf8");
+}
+
+// Declarative mappings for applyRunOverrides to reduce cognitive complexity.
+

package/src/config/overrides.js

@@ -0,0 +1,199 @@
+/**
+ * CLI-flag overrides applied on top of a loaded config.
+ *
+ * `applyRunOverrides(config, flags)` takes the merged config from the
+ * loader plus the CLI flags (also forwarded from MCP tool args) and
+ * produces the final config the orchestrator operates on. Overrides are
+ * declarative where possible (ROLE_PROVIDER_FLAGS, ROLE_MODEL_FLAGS,
+ * PIPELINE_ENABLE_FLAGS, SCALAR_FLAGS, UNDEF_CHECK_FLAGS) and imperative
+ * only where the mapping is not 1:1 (methodology, CI, output mode,
+ * deprecated flags like `--no-sonar`).
+ *
+ * Extracted from `src/config.js` in TSK-0332 (Oleada 2 of the v2.7.4
+ * audit refactor). Public API: `applyRunOverrides`. The apply* helpers
+ * are internal.
+ */
+
+import { mergeDeep } from "./loader.js";
+import { DEFAULTS } from "./defaults.js";
+import { safeParseConfig, formatConfigIssues } from "./schema.js";
+
+const ROLE_PROVIDER_FLAGS = [
+  ["planner", "planner"], ["coder", "coder"], ["reviewer", "reviewer"],
+  ["refactorer", "refactorer"], ["solomon", "solomon"], ["researcher", "researcher"],
+  ["tester", "tester"], ["security", "security"], ["triage", "triage"],
+  ["discover", "discover"], ["architect", "architect"]
+];
+
+// Role model flags: [flagName, roleName] — truthy check, String coercion
+const ROLE_MODEL_FLAGS = [
+  ["plannerModel", "planner"], ["coderModel", "coder"], ["reviewerModel", "reviewer"],
+  ["refactorerModel", "refactorer"], ["solomonModel", "solomon"], ["discoverModel", "discover"],
+  ["architectModel", "architect"]
+];
+
+// Pipeline enable flags: [flagName, pipelineKey] — !== undefined check, Boolean coercion
+const PIPELINE_ENABLE_FLAGS = [
+  ["enablePlanner", "planner"], ["enableRefactorer", "refactorer"],
+  ["enableSolomon", "solomon"], ["enableResearcher", "researcher"],
+  ["enableTester", "tester"], ["enableSecurity", "security"], ["enableImpeccable", "impeccable"],
+  ["enableTriage", "triage"], ["enableDiscover", "discover"],
+  ["enableArchitect", "architect"],
+  ["enableHuReviewer", "hu_reviewer"]
+];
+
+const AUTO_SIMPLIFY_FLAG = "autoSimplify";
+
+// Scalar flags: [flagName, setter] — truthy check.
+// Note: max_iterations was previously here but `0` was silently ignored
+// (truthy check skipped it). It now lives in UNDEF_CHECK_FLAGS so
+// `--max-iterations 0` reaches the schema validator and errors cleanly
+// instead of falling through to the default (KJC-TSK-0318).
+const SCALAR_FLAGS = [
+  ["mode", (out, v) => { out.review_mode = v; }],
+  ["maxIterationMinutes", (out, v) => { out.session.max_iteration_minutes = Number(v); }],
+  ["maxTotalMinutes", (out, v) => { out.session.max_total_minutes = Number(v); }],
+  ["checkpointInterval", (out, v) => { out.session.checkpoint_interval_minutes = Number(v); }],
+  ["baseBranch", (out, v) => { out.base_branch = v; }],
+  ["coderFallback", (out, v) => { out.coder_options.fallback_coder = v; }],
+  ["reviewerFallback", (out, v) => { out.reviewer_options.fallback_reviewer = v; }],
+  ["taskType", (out, v) => { out.taskType = String(v); }],
+  ["branchPrefix", (out, v) => { out.git.branch_prefix = String(v); }]
+];
+
+// Boolean/undefined-check flags: [flagName, setter] — !== undefined check.
+// These preserve falsy values (false, 0) so --no-rebase correctly sets
+// auto_rebase=false and --reviewer-retries 0 correctly disables retries.
+const UNDEF_CHECK_FLAGS = [
+  ["maxIterations", (out, v) => { out.max_iterations = Number(v); }],
+  ["reviewerRetries", (out, v) => { out.reviewer_options.retries = Number(v); }],
+  ["autoCommit", (out, v) => { out.git.auto_commit = Boolean(v); }],
+  ["autoPush", (out, v) => { out.git.auto_push = Boolean(v); }],
+  ["autoPr", (out, v) => { out.git.auto_pr = Boolean(v); }],
+  ["autoRebase", (out, v) => { out.git.auto_rebase = Boolean(v); }],
+  ["enableSerena", (out, v) => { out.serena.enabled = Boolean(v); }]
+];
+
+function applyRoleOverrides(out, flags) {
+  for (const [flag, role] of ROLE_PROVIDER_FLAGS) {
+    if (flags[flag]) out.roles[role].provider = flags[flag];
+  }
+  // coder/reviewer also update top-level aliases
+  if (flags.coder) out.coder = flags.coder;
+  if (flags.reviewer) out.reviewer = flags.reviewer;
+
+  for (const [flag, role] of ROLE_MODEL_FLAGS) {
+    if (flags[flag]) out.roles[role].model = String(flags[flag]);
+  }
+  // reviewerModel also updates reviewer_options
+  if (flags.reviewerModel) out.reviewer_options.model = String(flags.reviewerModel);
+}
+
+function applyPipelineOverrides(out, flags) {
+  for (const [flag, key] of PIPELINE_ENABLE_FLAGS) {
+    if (flags[flag] !== undefined) out.pipeline[key].enabled = Boolean(flags[flag]);
+  }
+  if (flags.enableReviewer !== undefined) {
+    out.pipeline.reviewer = out.pipeline.reviewer || {};
+    out.pipeline.reviewer.enabled = Boolean(flags.enableReviewer);
+  }
+}
+
+function applyScalarAndBooleanOverrides(out, flags) {
+  for (const [flag, setter] of SCALAR_FLAGS) {
+    if (flags[flag]) setter(out, flags[flag]);
+  }
+  for (const [flag, setter] of UNDEF_CHECK_FLAGS) {
+    if (flags[flag] !== undefined) setter(out, flags[flag]);
+  }
+}
+
+function applyMethodologyOverride(out, flags) {
+  if (!flags.methodology) return;
+  const methodology = String(flags.methodology).toLowerCase();
+  out.development.methodology = methodology;
+  out.development.require_test_changes = methodology === "tdd";
+}
+
+function applyCiOverride(out, flags) {
+  out.ci = out.ci || { enabled: false };
+  if (flags.enableCi === undefined) return;
+  out.ci.enabled = Boolean(flags.enableCi);
+  // CI requires git automation (commit + push + PR)
+  if (out.ci.enabled) {
+    out.git.auto_commit = true;
+    out.git.auto_push = true;
+    out.git.auto_pr = true;
+  }
+}
+
+function applyOutputModeOverrides(out, flags) {
+  out.output = out.output || {};
+  // --verbose explicitly overrides quiet
+  if (flags.verbose === true) {
+    out.output.quiet = false;
+  } else if (flags.quiet === true) {
+    out.output.quiet = true;
+  }
+  // quiet defaults to true (set in DEFAULTS)
+}
+
+function applyMiscOverrides(out, flags) {
+  if (flags[AUTO_SIMPLIFY_FLAG] !== undefined) out.pipeline.auto_simplify = Boolean(flags[AUTO_SIMPLIFY_FLAG]);
+  // `--no-sonar` and `sonarqube.enabled: false` are deprecated since v2.7.4.
+  // Sonar is intrinsic to Karajan for code tasks (sw/refactor/add-tests) and
+  // skipped for non-code tasks (audit/doc/infra/analysis/no-code) by policy.
+  // The flag is still accepted to avoid breaking scripts; it now emits a
+  // warning at run start and is otherwise ignored. See preflight-checks.js
+  // and flow-runner.js for the actual gate (resolvedPolicies.sonar).
+  if (flags.noSonar || flags.sonar === false) {
+    out._deprecated = out._deprecated || {};
+    out._deprecated.noSonarFlag = true;
+  }
+  out.sonarcloud = out.sonarcloud || {};
+  if (flags.enableSonarcloud === true) out.sonarcloud.enabled = true;
+  if (flags.noSonarcloud === true || flags.sonarcloud === false) out.sonarcloud.enabled = false;
+
+  out.planning_game = out.planning_game || {};
+  if (flags.pgTask) out.planning_game.enabled = true;
+  if (flags.pgProject) out.planning_game.project_id = flags.pgProject;
+
+  out.model_selection = out.model_selection || { enabled: true, tiers: {}, role_overrides: {} };
+  if (flags.smartModels === true) out.model_selection.enabled = true;
+  if (flags.smartModels === false || flags.noSmartModels === true) out.model_selection.enabled = false;
+}
+
+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 || {});
+  out.serena = out.serena || { enabled: false };
+
+  applyRoleOverrides(out, flags);
+  applyPipelineOverrides(out, flags);
+  applyScalarAndBooleanOverrides(out, flags);
+  applyMethodologyOverride(out, flags);
+  applyCiOverride(out, flags);
+  applyMiscOverrides(out, flags);
+  applyOutputModeOverrides(out, flags);
+
+  // KJC-TSK-0318 — re-run schema validation after overrides so CLI flags
+  // that would produce an invalid config (e.g. --max-iterations 0) fail
+  // fast with the same clear message loadConfig would have produced.
+  const validation = safeParseConfig(out);
+  if (!validation.success) {
+    throw new Error(`Invalid Karajan config after CLI overrides:\n${formatConfigIssues(validation.issues)}`);
+  }
+
+  return out;
+}