karajan-code 1.54.0 → 1.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.54.0",
+  "version": "1.55.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/bootstrap.js

@@ -22,6 +22,7 @@ import { checkBinary } from "./utils/agent-detect.js";
 import { exists } from "./utils/fs.js";
 import { getConfigPath, resolveRole } from "./config.js";
 import { isSonarReachable, sonarUp } from "./sonar/manager.js";
+import { withDocLink } from "./utils/doc-links.js";
 
 const BOOTSTRAP_VERSION = 1;
 const BOOTSTRAP_TTL_HOURS = 24;
@@ -185,14 +186,14 @@ function formatBootstrapFailure(failures) {
   const lines = failures.map(f =>
     `  FAIL  ${f.name}: ${f.detail}\n        Fix: ${f.fix}`
   );
-  return [
+  return withDocLink([
     "BOOTSTRAP FAILED — Environment not ready for Karajan Code.\n",
     "The following prerequisite(s) are not met:\n",
     ...lines,
     "",
     "Run 'kj_doctor' for a complete environment diagnostic.",
     "Do NOT work around these issues — fix them properly."
-  ].join("\n");
+  ].join("\n"), "bootstrap_failed");
 }
 
 // ── Public API ───────────────────────────────────────────────────────

package/src/cli.js

@@ -24,6 +24,7 @@ import { researcherCommand } from "./commands/researcher.js";
 import { architectCommand } from "./commands/architect.js";
 import { auditCommand } from "./commands/audit.js";
 import { boardCommand } from "./commands/board.js";
+import { undoCommand } from "./commands/undo.js";
 
 import { printUpdateNotice } from "./utils/update-check.js";
 
@@ -324,6 +325,17 @@ program
     });
   });
 
+program
+  .command("undo")
+  .description("Revert last pipeline run")
+  .option("--hard", "Discard all changes (default: soft reset, keeps changes staged)")
+  .action(async (flags) => {
+    await withConfig("undo", flags, async ({ logger }) => {
+      const result = await undoCommand({ hard: !!flags.hard, logger });
+      if (!result.ok) process.exit(1);
+    });
+  });
+
 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" }));

package/src/commands/doctor.js

@@ -11,6 +11,7 @@ import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
 import { ensureGitRepo } from "../utils/git.js";
 import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
 import { getInstallCommand } from "../utils/os-detect.js";
+import { withDocLink } from "../utils/doc-links.js";
 
 function getPackageVersion() {
   const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
@@ -36,7 +37,7 @@ async function checkConfigFile() {
     label: "Config file",
     ok: configExists,
     detail: configExists ? configPath : "Not found",
-    fix: configExists ? null : "Run 'kj init' to create the config file."
+    fix: configExists ? null : withDocLink("Run 'kj init' to create the config file.", "config_missing")
   };
 }
 
@@ -63,7 +64,7 @@ async function checkDocker() {
     label: "Docker",
     ok: docker.ok,
     detail: docker.ok ? docker.version : "Not found",
-    fix: docker.ok ? null : "Install Docker: https://docs.docker.com/get-docker/"
+    fix: docker.ok ? null : withDocLink("Install Docker: https://docs.docker.com/get-docker/", "sonar_docker")
   };
 }
 
@@ -91,7 +92,7 @@ async function checkSonarQube(config) {
     detail: sonarDetail(config, sonarOk, sonarHost),
     fix: isOkOrDisabled
       ? null
-      : "Run 'kj sonar start' or 'docker start karajan-sonarqube'. Use --no-sonar to skip."
+      : withDocLink("Run 'kj sonar start' or 'docker start karajan-sonarqube'. Use --no-sonar to skip.", "sonar_docker")
   };
 }
 
@@ -104,7 +105,7 @@ async function checkAgentCLIs() {
       label: `Agent: ${agent.name}`,
       ok: result.ok,
       detail: result.ok ? `${result.version} (${result.path})` : "Not found",
-      fix: result.ok ? null : `Install: ${agent.install}`
+      fix: result.ok ? null : withDocLink(`Install: ${agent.install}`, "agent_not_found")
     });
   }
   return checks;
@@ -220,7 +221,7 @@ async function checkRtk() {
     label: "RTK (Rust Token Killer)",
     ok: false,
     detail: "Not found — 60-90% token savings available",
-    fix: `Install: ${installCmd}`
+    fix: withDocLink(`Install: ${installCmd}`, "rtk_install")
   };
 }
 

package/src/commands/undo.js

@@ -0,0 +1,62 @@
+import { loadMostRecentSession } from "../session-store.js";
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Revert the last pipeline run by resetting to the pre-pipeline commit.
+ * Default: soft reset (keeps changes staged). With --hard: discards all changes.
+ */
+export async function undoCommand({ hard = false, logger } = {}) {
+  const session = await loadMostRecentSession();
+  if (!session) {
+    const msg = "No session to undo. No sessions found in the sessions directory.";
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  const sha = session.session_start_sha;
+  if (!sha) {
+    const msg = `Session ${session.id} has no session_start_sha. Cannot determine the pre-pipeline commit.`;
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  // Verify the SHA exists in git history
+  const verifyRes = await runCommand("git", ["cat-file", "-t", sha]);
+  if (verifyRes.exitCode !== 0 || verifyRes.stdout.trim() !== "commit") {
+    const msg = `Commit ${sha} not found in git history. It may have been garbage-collected or belong to a different repository.`;
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  // Check there are commits after the SHA (HEAD is ahead)
+  const logRes = await runCommand("git", ["log", "--oneline", `${sha}..HEAD`]);
+  if (logRes.exitCode !== 0 || !logRes.stdout.trim()) {
+    const msg = `No commits to undo. HEAD is already at or before ${sha.slice(0, 8)}.`;
+    if (logger) logger.warn(msg);
+    return { ok: false, error: msg };
+  }
+
+  const mode = hard ? "--hard" : "--soft";
+  const resetRes = await runCommand("git", ["reset", mode, sha]);
+  if (resetRes.exitCode !== 0) {
+    const msg = `git reset ${mode} ${sha} failed: ${resetRes.stderr || resetRes.stdout}`;
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  const shortSha = sha.slice(0, 8);
+  const message = hard
+    ? `Reverted to pre-pipeline state (commit ${shortSha}). All changes discarded.`
+    : `Reverted to pre-pipeline state (commit ${shortSha}). Changes are staged. Use \`git diff --cached\` to review.`;
+
+  if (logger) logger.info(message);
+  console.log(message);
+
+  return {
+    ok: true,
+    message,
+    sessionId: session.id,
+    sha,
+    mode: hard ? "hard" : "soft"
+  };
+}

package/src/mcp/handlers/management-handlers.js

@@ -163,6 +163,18 @@ export async function handleBoard(a) {
   }
 }
 
+export async function handleUndo(a, server) {
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const origCwd = process.cwd();
+  try {
+    process.chdir(projectDir);
+    const { undoCommand } = await import("../../commands/undo.js");
+    return undoCommand({ hard: !!a.hard });
+  } finally {
+    process.chdir(origCwd);
+  }
+}
+
 export async function buildPreflightRequiredResponse(toolName) {
   const { config } = await loadConfig();
   const { listAgents } = await import("../../commands/agents.js");

package/src/mcp/server-handlers.js

@@ -10,11 +10,12 @@ import { loadConfig, applyRunOverrides, validateConfig } from "../config.js";
 import { currentBranch } from "../utils/git.js";
 import { buildProgressNotifier } from "./progress.js";
 import { compressResponse, compactStringify } from "./response-compressor.js";
+import { withDocLink } from "../utils/doc-links.js";
 
 // ── Sub-module re-exports ────────────────────────────────────────────
 export { handleRunDirect, handleResumeDirect, validateResumeAnswer, handleRun, handleResume } from "./handlers/run-handler.js";
 export { handlePlanDirect, handleCodeDirect, handleReviewDirect, handleDiscoverDirect, handleTriageDirect, handleResearcherDirect, handleAuditDirect, handleArchitectDirect, handleCode, handleReview, handlePlan, handleDiscover, handleTriage, handleResearcher, handleArchitect, handleAudit } from "./handlers/direct-handlers.js";
-export { handleStatus, handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
+export { handleStatus, handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, handleUndo, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
 export { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
 
 // ── Shared helpers (used by sub-modules and external consumers) ──────
@@ -82,22 +83,22 @@ const ERROR_CLASSIFIERS = [
   {
     test: (lower) => lower.includes("sonar") && (lower.includes("connect") || lower.includes("econnrefused") || lower.includes("not available") || lower.includes("not running")),
     category: "sonar_unavailable",
-    suggestion: "SonarQube is not reachable. Try: kj_init to set up SonarQube, or run 'docker start sonarqube' if already installed. Use --no-sonar to skip SonarQube."
+    suggestion: withDocLink("SonarQube is not reachable. Try: kj_init to set up SonarQube, or run 'docker start sonarqube' if already installed. Use --no-sonar to skip SonarQube.", "sonar_docker")
   },
   {
     test: (lower) => lower.includes("401") || lower.includes("unauthorized") || lower.includes("invalid token"),
     category: "auth_error",
-    suggestion: "Authentication failed. Regenerate the SonarQube token and update it via kj_init or in ~/.karajan/kj.config.yml under sonarqube.token."
+    suggestion: withDocLink("Authentication failed. Regenerate the SonarQube token and update it via kj_init or in ~/.karajan/kj.config.yml under sonarqube.token.", "sonar_token")
   },
   {
     test: (lower) => lower.includes("config") && (lower.includes("missing") || lower.includes("not found") || lower.includes("invalid")),
     category: "config_error",
-    suggestion: "Configuration issue detected. Run kj_doctor to diagnose, or kj_init to create a fresh config."
+    suggestion: withDocLink("Configuration issue detected. Run kj_doctor to diagnose, or kj_init to create a fresh config.", "config_missing")
   },
   {
     test: (lower) => lower.includes("missing provider") || lower.includes("not found") && (lower.includes("claude") || lower.includes("codex") || lower.includes("gemini") || lower.includes("aider")),
     category: "agent_missing",
-    suggestion: "Required agent CLI not found. Run kj_doctor to check which agents are installed and get installation instructions."
+    suggestion: withDocLink("Required agent CLI not found. Run kj_doctor to check which agents are installed and get installation instructions.", "agent_not_found")
   },
   {
     test: (lower) => lower.includes("timed out") || lower.includes("timeout"),
@@ -107,7 +108,7 @@ const ERROR_CLASSIFIERS = [
   {
     test: (lower) => lower.includes("you are on the base branch"),
     category: "branch_error",
-    suggestion: "Create a feature branch before running Karajan. Use 'git checkout -b feat/<task-description>' and then retry. Do NOT run kj_code directly on the base branch."
+    suggestion: withDocLink("Create a feature branch before running Karajan. Use 'git checkout -b feat/<task-description>' and then retry. Do NOT run kj_code directly on the base branch.", "branch_error")
   },
   {
     test: (lower) => lower.includes("not a git repository"),
@@ -117,7 +118,7 @@ const ERROR_CLASSIFIERS = [
   {
     test: (lower) => lower.includes("bootstrap failed"),
     category: "bootstrap_error",
-    suggestion: "Environment prerequisites not met. Run kj_doctor for diagnostics, then fix the issues listed. Do NOT work around these — fix them properly."
+    suggestion: withDocLink("Environment prerequisites not met. Run kj_doctor for diagnostics, then fix the issues listed. Do NOT work around these — fix them properly.", "bootstrap_failed")
   }
 ];
 
@@ -218,7 +219,7 @@ import {
 import {
   handleStatus, handleAgents, handlePreflight, handleRoles,
   handleReport, handleInit, handleDoctor, handleConfig,
-  handleScan, handleBoard
+  handleScan, handleBoard, handleUndo
 } from "./handlers/management-handlers.js";
 import { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
 
@@ -245,7 +246,8 @@ const toolHandlers = {
   kj_board:       (a) => handleBoard(a),
   kj_hu:          (a, server) => handleHu(a, server),
   kj_suggest:     (a) => handleSuggest(a),
-  kj_skills:      (a) => handleSkills(a)
+  kj_skills:      (a) => handleSkills(a),
+  kj_undo:        (a, server) => handleUndo(a, server)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/tools.js

@@ -364,5 +364,16 @@ export const tools = [
       },
       required: ["action"]
     }
+  },
+  {
+    name: "kj_undo",
+    description: "Revert the last pipeline run by resetting to the pre-pipeline commit. Default: soft reset (keeps changes staged). Use hard=true to discard all changes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        hard: { type: "boolean", description: "If true, discard all changes (git reset --hard). Default: false (soft reset, keeps changes staged)." },
+        projectDir: { type: "string", description: "Absolute path to the project directory" }
+      }
+    }
   }
 ];

package/src/orchestrator/preflight-checks.js

@@ -19,6 +19,7 @@ import {
   resolveSonarToken,
   resolveSonarCredentials,
 } from "../sonar/config-resolver.js";
+import { withDocLink } from "../utils/doc-links.js";
 
 function parseJsonSafe(text) {
   try {
@@ -188,7 +189,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       result.errors.push({
         check: "docker",
         message: "Docker not available but SonarQube is enabled.",
-        fix: "Start Docker, or disable SonarQube: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar."
+        fix: withDocLink("Start Docker, or disable SonarQube: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar.", "sonar_docker")
       });
       logger.error("Preflight: Docker not found — SonarQube requires Docker");
 
@@ -222,7 +223,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       result.errors.push({
         check: "sonar-reachable",
         message: `SonarQube not reachable at ${sonarHost}.`,
-        fix: "Start SonarQube: 'docker start karajan-sonarqube', or disable it: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar."
+        fix: withDocLink("Start SonarQube: 'docker start karajan-sonarqube', or disable it: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar.", "sonar_docker")
       });
       logger.error("Preflight: SonarQube not reachable after remediation attempt");
     }
@@ -248,7 +249,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       result.errors.push({
         check: "sonar-auth",
         message: "SonarQube is running but no authentication token is configured.",
-        fix: "Fix: run 'kj init' to configure it, or set KJ_SONAR_TOKEN env var, or add sonarqube.token to ~/.karajan/kj.config.yml."
+        fix: withDocLink("Fix: run 'kj init' to configure it, or set KJ_SONAR_TOKEN env var, or add sonarqube.token to ~/.karajan/kj.config.yml.", "sonar_token")
       });
       logger.error("Preflight: Sonar auth failed");
     }

package/src/utils/doc-links.js

@@ -0,0 +1,27 @@
+/**
+ * Documentation links for error messages.
+ *
+ * Maps error types to their relevant documentation page so that
+ * every actionable error includes a "See: <url>" pointer.
+ */
+
+const BASE_URL = "https://karajancode.com/docs";
+
+const ERROR_DOCS = {
+  sonar_token: `${BASE_URL}/guides/configuration/#sonarqube`,
+  sonar_docker: `${BASE_URL}/getting-started/installation/#docker`,
+  agent_not_found: `${BASE_URL}/getting-started/installation/#agents`,
+  bootstrap_failed: `${BASE_URL}/guides/troubleshooting/`,
+  config_missing: `${BASE_URL}/getting-started/quick-start/`,
+  branch_error: `${BASE_URL}/guides/pipeline/#git-workflow`,
+  rtk_install: `${BASE_URL}/guides/configuration/#rtk`,
+};
+
+export function docLink(errorType) {
+  return ERROR_DOCS[errorType] || `${BASE_URL}/guides/troubleshooting/`;
+}
+
+export function withDocLink(message, errorType) {
+  const link = docLink(errorType);
+  return `${message}\n  See: ${link}`;
+}