karajan-code 2.5.0 → 2.6.0

package/src/orchestrator/pipeline-context.js

@@ -1,8 +1,25 @@
 /**
  * Shared context object for pipeline execution.
  * Replaces destructured parameter objects across orchestrator functions.
+ *
+ * @typedef {import("../types/config.js").KarajanConfig} KarajanConfig
+ * @typedef {import("../types/session.js").Session} Session
+ * @typedef {import("../types/stage.js").Logger} Logger
+ * @typedef {import("../types/stage.js").Emitter} Emitter
+ * @typedef {import("../types/stage.js").EventBase} EventBase
+ * @typedef {import("../types/config.js").PipelineFlags} PipelineFlags
+ * @typedef {import("../types/stage.js").StageContext} StageContext
  */
 export class PipelineContext {
+  /**
+   * @param {Object} args
+   * @param {KarajanConfig} args.config
+   * @param {Session} args.session
+   * @param {Logger} args.logger
+   * @param {Emitter|null} args.emitter
+   * @param {string} args.task
+   * @param {Object} [args.flags]
+   */
   constructor({ config, session, logger, emitter, task, flags = {} }) {
     this.config = config;
     this.session = session;

package/src/orchestrator/preflight-checks.js

@@ -22,6 +22,14 @@ import {
 } from "../sonar/config-resolver.js";
 import { saveSonarToken } from "../sonar/credentials.js";
 import { withDocLink } from "../utils/doc-links.js";
+import { runChecks as runCheckPipeline } from "../checks/runner.js";
+import { STATUS } from "../checks/types.js";
+import { getNodeChecks } from "../checks/node.js";
+import { getDirSetupChecks } from "../checks/dir-setup.js";
+import { getPortChecks } from "../checks/ports.js";
+import { getTokenChecks } from "../checks/tokens.js";
+import { getMcpHealthChecks } from "../checks/mcp-health.js";
+import { getSkillsChecks } from "../checks/skills.js";
 
 function parseJsonSafe(text) {
   try {
@@ -173,9 +181,14 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
     errors: [],
   };
 
-  // Short-circuit: nothing to check
-  if (!sonarEnabled && !securityEnabled) {
-    logger.info("Preflight: skipped (no sonar, no security)");
+  // Resolve extended preflight opt-in early so the short-circuit below can see it.
+  const extendedDefault = globalThis.__KJ_DEFAULT_PREFLIGHT_EXTENDED ?? true;
+  const extendedEnabled = config?.preflight?.extended ?? extendedDefault;
+
+  // Preserve legacy short-circuit: if nothing at all needs checking, skip
+  // emitting the whole preflight bracket.
+  if (!sonarEnabled && !securityEnabled && !extendedEnabled) {
+    logger.info("Preflight: skipped (no sonar, no security, extended disabled)");
     emitProgress(emitter, makeEvent("preflight:end", { ...eventBase, stage: "preflight" }, {
       message: "Preflight skipped (no checks needed)",
       detail: { ...result, executorType: "local" }
@@ -185,7 +198,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
 
   emitProgress(emitter, makeEvent("preflight:start", { ...eventBase, stage: "preflight" }, {
     message: "Running preflight environment checks",
-    detail: { sonarEnabled, securityEnabled, executorType: "local" }
+    detail: { sonarEnabled, securityEnabled, extendedEnabled, executorType: "local" }
   }));
 
   // --- 1. Docker (only if sonar enabled and not external) ---
@@ -288,6 +301,15 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
     }
   }
 
+  // --- 5. Complementary doctor-style checks (Node version, ports, tokens, MCP
+  //         health, ~/.karajan dirs, openskills). These are auto-remediated
+  //         with yes:true because preflight runs non-interactively inside kj run.
+  //         Opt-out via `config.preflight.extended: false`. Defaults to true
+  //         in production; the test harness (tests/setup.js) defaults it off.
+  if (extendedEnabled) {
+    await runExtendedPreflight({ config, result, emitter, eventBase, logger });
+  }
+
   const hasErrors = result.errors.length > 0;
   const hasWarnings = result.warnings.length > 0;
   const preflightLang = getLang(config);
@@ -303,3 +325,55 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
 
   return result;
 }
+
+/**
+ * Run the doctor-style complementary checks and merge their outcomes into
+ * the existing preflight result shape. Runs with yes:true (non-interactive)
+ * and auto-remediation enabled. FAIL/TIMEOUT are appended to errors (blocking),
+ * WARN are appended to warnings (non-blocking), FIXED status is recorded as a
+ * remediation, and runtime overrides from auto-fixes are merged into
+ * configOverrides.
+ */
+async function runExtendedPreflight({ config, result, emitter, eventBase, logger }) {
+  const checks = [
+    ...getNodeChecks(),
+    ...getDirSetupChecks(),
+    ...getPortChecks(),
+    ...getTokenChecks(config),
+    ...getMcpHealthChecks(),
+    ...getSkillsChecks(),
+  ];
+  let report;
+  try {
+    report = await runCheckPipeline(checks, { config }, { mode: "fix", yes: true, timeoutMs: 3000, logger });
+  } catch (err) {
+    logger.warn(`Preflight: extended checks failed to run (${err.message})`);
+    return;
+  }
+
+  for (const c of report.checks) {
+    result.checks.push({ name: c.name, ok: c.status === STATUS.OK || c.status === STATUS.FIXED || c.status === STATUS.SKIPPED, detail: c.detail });
+    const eventStatus = c.status === STATUS.FAIL || c.status === STATUS.TIMEOUT
+      ? "fail"
+      : c.status === STATUS.WARN
+        ? "warn"
+        : "ok";
+    emitProgress(emitter, makeEvent("preflight:check", { ...eventBase, stage: "preflight" }, {
+      status: eventStatus,
+      message: `${c.label}: ${c.detail}`,
+      detail: { name: c.name, status: c.status, detail: c.detail, fix: c.fix }
+    }));
+    if (c.status === STATUS.FIXED) {
+      result.remediations.push(`${c.label}: ${c.detail}`);
+    } else if (c.status === STATUS.FAIL || c.status === STATUS.TIMEOUT) {
+      result.ok = false;
+      result.errors.push({ check: c.name, message: `${c.label}: ${c.detail}`, fix: c.fix });
+    } else if (c.status === STATUS.WARN) {
+      result.warnings.push(`${c.label}: ${c.detail}`);
+    }
+  }
+
+  if (report.overrides && Object.keys(report.overrides).length > 0) {
+    Object.assign(result.configOverrides, report.overrides);
+  }
+}

package/src/orchestrator/solomon-escalation.js

@@ -156,6 +156,27 @@ export async function invokeSolomon({ config, logger, emitter, eventBase, stage,
     subtask: ruling.result?.subtask?.title || null
   });
 
+  // Record the ruling for the session journal (decisions.md). Lazy-import so
+  // this module stays free of journal-specific deps for callers that don't
+  // need them.
+  try {
+    const { recordSolomonRuling } = await import("../session/journal/decisions-writer.js");
+    recordSolomonRuling(session, {
+      stage: conflict?.stage || stage,
+      trigger: conflict?.reason || conflict?.summary || "solomon invoked",
+      conflict: {
+        task: conflict?.task,
+        reason: conflict?.reason,
+        summary: conflict?.summary,
+        iterationCount: conflict?.iterationCount,
+      },
+      ruling: ruling.result?.ruling || (ruling.ok ? "continue" : "escalate_human"),
+      reasoning: ruling.result?.reasoning || ruling.summary || "",
+      conditions: ruling.result?.conditions || [],
+      alternativeAgent: ruling.result?.alternativeAgent || null,
+    });
+  } catch { /* best-effort, don't break the pipeline on a journal hiccup */ }
+
   if (!ruling.ok) {
     const reason = ruling.result?.escalate_reason || solomonError || ruling.summary;
     return escalateToHuman({

package/src/orchestrator/stages/stage-executor.js

@@ -0,0 +1,155 @@
+/**
+ * StageExecutor — contract for per-stage orchestration logic (KJC-TSK-0315).
+ *
+ * The current orchestrator branches on a flat `pipelineFlags` object inside a
+ * monolithic `runFlow`. This contract is the first step toward replacing those
+ * branches with self-describing stage objects: each stage declares whether it
+ * wants to run (`canRun`), how to run (`execute`), and what to do on failure
+ * (`onFailure`). The orchestrator iterates a registry of stages instead of
+ * owning knowledge of every pipeline flag.
+ *
+ * Scope for this PR: define the contract + a tiny registry. Existing stage
+ * functions (e.g. src/orchestrator/stages/triage-stage.js) continue to be
+ * called directly by flow-runner.js; future refactors can migrate them to
+ * StageExecutor class form incrementally without touching the orchestrator.
+ *
+ * @typedef {Object} StageContext
+ * @property {Object} config
+ * @property {Object} session
+ * @property {Object} logger
+ * @property {Object} emitter
+ * @property {Object} eventBase
+ * @property {Object} pipelineFlags
+ * @property {Object} stageResults
+ * @property {Function} [trackBudget]
+ * @property {Function} [askQuestion]
+ * @property {Object} [brainCtx]
+ * @property {number} [iteration]
+ *
+ * @typedef {Object} StageOutcome
+ * @property {string} status - "ok" | "skipped" | "failed"
+ * @property {*} [result]
+ * @property {string} [detail]
+ */
+
+export class StageExecutor {
+  /**
+   * @param {string} name - unique stage slug (e.g. "triage", "reviewer")
+   */
+  constructor(name) {
+    if (!name || typeof name !== "string") {
+      throw new Error("StageExecutor requires a non-empty name");
+    }
+    this.name = name;
+  }
+
+  /**
+   * Decide whether this stage should run for the current context. Default is
+   * true; subclasses override to gate on pipelineFlags or task type.
+   * @param {StageContext} _ctx
+   * @returns {boolean | Promise<boolean>}
+   */
+  canRun(_ctx) {
+    return true;
+  }
+
+  /**
+   * Run the stage. MUST be overridden. Return a StageOutcome describing what
+   * happened; the runner persists `result` under ctx.stageResults[this.name].
+   * @param {StageContext} _ctx
+   * @returns {Promise<StageOutcome>}
+   */
+  async execute(_ctx) {
+    throw new Error(`StageExecutor(${this.name}).execute() not implemented`);
+  }
+
+  /**
+   * Error hook. Default behaviour rethrows so the orchestrator's global
+   * failure handling kicks in; subclasses can override to recover silently,
+   * return a partial result, or escalate to Solomon before rethrowing.
+   * @param {Error} err
+   * @param {StageContext} _ctx
+   * @returns {Promise<StageOutcome | void>}
+   */
+  // eslint-disable-next-line no-unused-vars
+  async onFailure(err, _ctx) {
+    throw err;
+  }
+}
+
+/**
+ * Registry of StageExecutor instances keyed by stage name. Kept intentionally
+ * small — the orchestrator iterates `list()` in declared order and invokes
+ * `canRun` / `execute` / `onFailure` as needed.
+ */
+export class StageRegistry {
+  constructor() {
+    /** @type {Map<string, StageExecutor>} */
+    this._stages = new Map();
+  }
+
+  /**
+   * @param {StageExecutor} stage
+   */
+  register(stage) {
+    if (!(stage instanceof StageExecutor)) {
+      throw new Error("StageRegistry.register(): argument must be a StageExecutor");
+    }
+    if (this._stages.has(stage.name)) {
+      throw new Error(`StageRegistry: stage "${stage.name}" already registered`);
+    }
+    this._stages.set(stage.name, stage);
+    return this;
+  }
+
+  /**
+   * @param {string} name
+   * @returns {StageExecutor | undefined}
+   */
+  get(name) {
+    return this._stages.get(name);
+  }
+
+  /**
+   * @returns {StageExecutor[]}
+   */
+  list() {
+    return [...this._stages.values()];
+  }
+
+  /**
+   * @param {string} name
+   * @returns {boolean}
+   */
+  has(name) {
+    return this._stages.has(name);
+  }
+
+  get size() {
+    return this._stages.size;
+  }
+}
+
+/**
+ * Run a stage via the contract. Centralizes the canRun/execute/onFailure
+ * dance so future call sites don't reinvent it. Returns null when `canRun`
+ * returns false (stage skipped).
+ *
+ * @param {StageExecutor} stage
+ * @param {StageContext} ctx
+ * @returns {Promise<StageOutcome | null>}
+ */
+export async function runStage(stage, ctx) {
+  if (!(stage instanceof StageExecutor)) {
+    throw new Error("runStage(): first argument must be a StageExecutor");
+  }
+  const shouldRun = await stage.canRun(ctx);
+  if (!shouldRun) return null;
+  try {
+    return await stage.execute(ctx);
+  } catch (err) {
+    const recovered = await stage.onFailure(err, ctx);
+    if (recovered !== undefined) return recovered;
+    throw err;
+  }
+}