karajan-code 1.2.0

package/src/roles/base-role.js

@@ -0,0 +1,127 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getKarajanHome } from "../utils/paths.js";
+
+const ROLE_EVENTS = {
+  START: "role:start",
+  END: "role:end",
+  ERROR: "role:error"
+};
+
+function resolveRoleMdPath(roleName, projectDir) {
+  const fileName = `${roleName}.md`;
+  const candidates = [];
+
+  if (projectDir) {
+    candidates.push(path.join(projectDir, ".karajan", "roles", fileName));
+  }
+
+  candidates.push(path.join(getKarajanHome(), "roles", fileName));
+
+  const builtIn = path.resolve(
+    path.dirname(new URL(import.meta.url).pathname),
+    "..",
+    "..",
+    "templates",
+    "roles",
+    fileName
+  );
+  candidates.push(builtIn);
+
+  return candidates;
+}
+
+async function loadFirstExisting(paths) {
+  for (const p of paths) {
+    try {
+      return await fs.readFile(p, "utf8");
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+export class BaseRole {
+  constructor({ name, config, logger, emitter = null }) {
+    if (!name) throw new Error("Role name is required");
+    this.name = name;
+    this.config = config || {};
+    this.logger = logger;
+    this.emitter = emitter;
+    this.instructions = null;
+    this._initialized = false;
+    this._startTime = null;
+    this._output = null;
+  }
+
+  async init(context = {}) {
+    this.context = context;
+    const projectDir = this.config.projectDir || process.cwd();
+    const paths = resolveRoleMdPath(this.name, projectDir);
+    this.instructions = await loadFirstExisting(paths);
+    this._initialized = true;
+  }
+
+  async execute(_input) {
+    throw new Error(`${this.name}: execute() not implemented`);
+  }
+
+  report() {
+    return {
+      role: this.name,
+      ok: this._output?.ok ?? false,
+      result: this._output?.result ?? null,
+      summary: this._output?.summary ?? "",
+      timestamp: new Date().toISOString()
+    };
+  }
+
+  validate(output) {
+    if (!output) return { valid: false, reason: "Output is null or undefined" };
+    if (typeof output.ok !== "boolean") return { valid: false, reason: "Output.ok must be a boolean" };
+    return { valid: true, reason: "" };
+  }
+
+  async run(input) {
+    this._ensureInitialized();
+    this._startTime = Date.now();
+    this._emitEvent(ROLE_EVENTS.START, { input });
+
+    try {
+      const output = await this.execute(input);
+      this._output = output;
+
+      const validation = this.validate(output);
+      if (!validation.valid) {
+        throw new Error(`${this.name} output validation failed: ${validation.reason}`);
+      }
+
+      this._emitEvent(ROLE_EVENTS.END, { output: this.report() });
+      return output;
+    } catch (error) {
+      this._emitEvent(ROLE_EVENTS.ERROR, { error: error.message });
+      throw error;
+    }
+  }
+
+  _ensureInitialized() {
+    if (!this._initialized) {
+      throw new Error(`${this.name}: init() must be called before run()`);
+    }
+  }
+
+  _emitEvent(type, detail = {}) {
+    if (!this.emitter) return;
+    this.emitter.emit(type, {
+      role: this.name,
+      iteration: this.context?.iteration ?? 0,
+      sessionId: this.context?.sessionId ?? null,
+      elapsed: this._startTime ? Date.now() - this._startTime : 0,
+      timestamp: new Date().toISOString(),
+      ...detail
+    });
+  }
+}
+
+export { ROLE_EVENTS, resolveRoleMdPath, loadFirstExisting };

package/src/roles/coder-role.js

@@ -0,0 +1,60 @@
+import { BaseRole } from "./base-role.js";
+import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { buildCoderPrompt } from "../prompts/coder.js";
+
+function resolveProvider(config) {
+  return (
+    config?.roles?.coder?.provider ||
+    config?.coder ||
+    "claude"
+  );
+}
+
+export class CoderRole extends BaseRole {
+  constructor({ config, logger, emitter = null, createAgentFn = null }) {
+    super({ name: "coder", config, logger, emitter });
+    this._createAgent = createAgentFn || defaultCreateAgent;
+  }
+
+  async execute(input) {
+    const { task, reviewerFeedback, sonarSummary, onOutput } = typeof input === "string"
+      ? { task: input, reviewerFeedback: null, sonarSummary: null, onOutput: null }
+      : input || {};
+
+    const provider = resolveProvider(this.config);
+    const agent = this._createAgent(provider, this.config, this.logger);
+
+    const prompt = buildCoderPrompt({
+      task: task || this.context?.task || "",
+      reviewerFeedback: reviewerFeedback || null,
+      sonarSummary: sonarSummary || null,
+      coderRules: this.instructions,
+      methodology: this.config?.development?.methodology || "tdd"
+    });
+
+    const coderArgs = { prompt, role: "coder" };
+    if (onOutput) coderArgs.onOutput = onOutput;
+
+    const result = await agent.runTask(coderArgs);
+
+    if (!result.ok) {
+      return {
+        ok: false,
+        result: {
+          error: result.error || result.output || "Coder failed",
+          provider
+        },
+        summary: `Coder failed: ${result.error || result.output || "unknown error"}`
+      };
+    }
+
+    return {
+      ok: true,
+      result: {
+        output: result.output || "",
+        provider
+      },
+      summary: "Coder completed"
+    };
+  }
+}

package/src/roles/commiter-role.js

@@ -0,0 +1,94 @@
+import { BaseRole } from "./base-role.js";
+import {
+  ensureGitRepo,
+  currentBranch,
+  fetchBase,
+  ensureBranchUpToDateWithBase,
+  hasChanges,
+  commitAll,
+  pushBranch,
+  createPullRequest,
+  revParse
+} from "../utils/git.js";
+
+function buildCommitMessage(task) {
+  const clean = String(task || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  const prefix = "feat: ";
+  const maxBody = 72 - prefix.length;
+  return `${prefix}${clean.slice(0, maxBody) || "update"}`;
+}
+
+function buildPrTitle(task) {
+  const clean = String(task || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return clean.slice(0, 70) || "Karajan update";
+}
+
+export class CommiterRole extends BaseRole {
+  constructor({ config, logger, emitter = null }) {
+    super({ name: "commiter", config, logger, emitter });
+  }
+
+  async execute(input) {
+    const { task, commitMessage, push = false, createPr = false } = input || {};
+
+    const isRepo = await ensureGitRepo();
+    if (!isRepo) {
+      return {
+        ok: false,
+        result: { error: "Current directory is not a git repository" },
+        summary: "Commiter failed: not a git repo"
+      };
+    }
+
+    const branch = await currentBranch();
+    const changes = await hasChanges();
+
+    if (!changes) {
+      return {
+        ok: true,
+        result: { branch, committed: false, commitHash: null, prUrl: null },
+        summary: "No changes to commit"
+      };
+    }
+
+    const msg = commitMessage || buildCommitMessage(task);
+    await commitAll(msg);
+    const commitHash = await revParse("HEAD");
+
+    if (push) {
+      const baseBranch = this.config.base_branch || "main";
+      await fetchBase(baseBranch);
+      await ensureBranchUpToDateWithBase({
+        branch,
+        baseBranch,
+        autoRebase: true
+      });
+      await pushBranch(branch);
+    }
+
+    let prUrl = null;
+    if (push && createPr) {
+      const baseBranch = this.config.base_branch || "main";
+      prUrl = await createPullRequest({
+        baseBranch,
+        branch,
+        title: buildPrTitle(task),
+        body: `Task: ${task || "N/A"}`
+      });
+    }
+
+    const parts = [`Committed on ${branch}`];
+    if (push) parts.push("pushed");
+    if (prUrl) parts.push(`PR: ${prUrl}`);
+
+    return {
+      ok: true,
+      result: { branch, committed: true, commitHash, prUrl },
+      summary: parts.join(", ")
+    };
+  }
+}

package/src/roles/index.js

@@ -0,0 +1,12 @@
+export { BaseRole, ROLE_EVENTS, resolveRoleMdPath, loadFirstExisting } from "./base-role.js";
+export { PlannerRole } from "./planner-role.js";
+export { ReviewerRole } from "./reviewer-role.js";
+export { RefactorerRole } from "./refactorer-role.js";
+export { CommiterRole } from "./commiter-role.js";
+export { CoderRole } from "./coder-role.js";
+export { SonarRole } from "./sonar-role.js";
+export { ResearcherRole } from "./researcher-role.js";
+export { TriageRole } from "./triage-role.js";
+export { TesterRole } from "./tester-role.js";
+export { SecurityRole } from "./security-role.js";
+export { SolomonRole } from "./solomon-role.js";

package/src/roles/planner-role.js

@@ -0,0 +1,81 @@
+import { BaseRole } from "./base-role.js";
+import { createAgent as defaultCreateAgent } from "../agents/index.js";
+
+function resolveProvider(config) {
+  return (
+    config?.roles?.planner?.provider ||
+    config?.roles?.coder?.provider ||
+    "claude"
+  );
+}
+
+function buildPrompt({ task, instructions, research }) {
+  const sections = [];
+
+  if (instructions) {
+    sections.push(instructions);
+    sections.push("");
+  }
+
+  sections.push("Create an implementation plan for this task.");
+  sections.push("Return concise numbered steps focused on execution order and risk.");
+  sections.push("");
+
+  if (research) {
+    sections.push("## Research findings");
+    if (research.affected_files?.length) {
+      sections.push(`Affected files: ${research.affected_files.join(", ")}`);
+    }
+    if (research.patterns?.length) {
+      sections.push(`Patterns: ${research.patterns.join(", ")}`);
+    }
+    if (research.constraints?.length) {
+      sections.push(`Constraints: ${research.constraints.join(", ")}`);
+    }
+    if (research.risks?.length) {
+      sections.push(`Risks: ${research.risks.join(", ")}`);
+    }
+    if (research.prior_decisions?.length) {
+      sections.push(`Prior decisions: ${research.prior_decisions.join(", ")}`);
+    }
+    sections.push("");
+  }
+
+  sections.push("## Task");
+  sections.push(task);
+
+  return sections.join("\n");
+}
+
+export class PlannerRole extends BaseRole {
+  constructor({ config, logger, emitter = null, createAgentFn = null }) {
+    super({ name: "planner", config, logger, emitter });
+    this._createAgent = createAgentFn || defaultCreateAgent;
+  }
+
+  async execute(input) {
+    const task = input || this.context?.task || "";
+    const research = this.context?.research || null;
+    const provider = resolveProvider(this.config);
+
+    const agent = this._createAgent(provider, this.config, this.logger);
+    const prompt = buildPrompt({ task, instructions: this.instructions, research });
+
+    const result = await agent.runTask({ prompt, role: "planner" });
+
+    if (!result.ok) {
+      return {
+        ok: false,
+        result: { error: result.error || result.output || "Planner agent failed", plan: null },
+        summary: `Planner failed: ${result.error || "unknown error"}`
+      };
+    }
+
+    const plan = result.output?.trim() || "";
+    return {
+      ok: true,
+      result: { plan, provider },
+      summary: plan ? `Plan generated (${plan.split("\n").length} lines)` : "Empty plan generated"
+    };
+  }
+}

package/src/roles/refactorer-role.js

@@ -0,0 +1,66 @@
+import { BaseRole } from "./base-role.js";
+import { createAgent as defaultCreateAgent } from "../agents/index.js";
+
+function resolveProvider(config) {
+  return (
+    config?.roles?.refactorer?.provider ||
+    config?.roles?.coder?.provider ||
+    "claude"
+  );
+}
+
+function buildPrompt({ task, instructions }) {
+  const sections = [];
+
+  if (instructions) {
+    sections.push(instructions);
+    sections.push("");
+  }
+
+  sections.push("Refactor the current changes for clarity and maintainability without changing behavior.");
+  sections.push("Do not expand scope and keep tests green.");
+  sections.push("");
+  sections.push("## Task context");
+  sections.push(task);
+
+  return sections.join("\n");
+}
+
+export class RefactorerRole extends BaseRole {
+  constructor({ config, logger, emitter = null, createAgentFn = null }) {
+    super({ name: "refactorer", config, logger, emitter });
+    this._createAgent = createAgentFn || defaultCreateAgent;
+  }
+
+  async execute(input) {
+    const task = typeof input === "string"
+      ? input
+      : input?.task || this.context?.task || "";
+
+    const provider = resolveProvider(this.config);
+    const agent = this._createAgent(provider, this.config, this.logger);
+
+    const prompt = buildPrompt({ task, instructions: this.instructions });
+    const result = await agent.runTask({ prompt, role: "refactorer" });
+
+    if (!result.ok) {
+      return {
+        ok: false,
+        result: {
+          error: result.error || result.output || "Refactorer failed",
+          provider
+        },
+        summary: `Refactorer failed: ${result.error || "unknown error"}`
+      };
+    }
+
+    return {
+      ok: true,
+      result: {
+        output: result.output?.trim() || "",
+        provider
+      },
+      summary: "Refactoring applied"
+    };
+  }
+}

package/src/roles/researcher-role.js

@@ -0,0 +1,134 @@
+import { BaseRole } from "./base-role.js";
+import { createAgent as defaultCreateAgent } from "../agents/index.js";
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on researching the codebase."
+].join(" ");
+
+function resolveProvider(config) {
+  return (
+    config?.roles?.researcher?.provider ||
+    config?.roles?.coder?.provider ||
+    "claude"
+  );
+}
+
+function buildPrompt({ task, instructions }) {
+  const sections = [SUBAGENT_PREAMBLE];
+
+  if (instructions) {
+    sections.push(instructions);
+  }
+
+  sections.push(
+    "Investigate the codebase for the following task.",
+    "Identify affected files, patterns, constraints, prior decisions, risks, and test coverage.",
+    "Return a single valid JSON object with your findings and nothing else.",
+    'JSON schema: {"affected_files":[string],"patterns":[string],"constraints":[string],"prior_decisions":[string],"risks":[string],"test_coverage":string}'
+  );
+
+  sections.push(`## Task\n${task}`);
+
+  return sections.join("\n\n");
+}
+
+function parseResearchOutput(raw) {
+  const text = raw?.trim() || "";
+  const jsonMatch = text.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) return null;
+  return JSON.parse(jsonMatch[0]);
+}
+
+function buildSummary(parsed) {
+  const files = parsed.affected_files?.length || 0;
+  const risks = parsed.risks?.length || 0;
+  const patterns = parsed.patterns?.length || 0;
+  const parts = [];
+  if (files) parts.push(`${files} file${files !== 1 ? "s" : ""}`);
+  if (risks) parts.push(`${risks} risk${risks !== 1 ? "s" : ""}`);
+  if (patterns) parts.push(`${patterns} pattern${patterns !== 1 ? "s" : ""}`);
+  return parts.length
+    ? `Research complete: ${parts.join(", ")} identified`
+    : "Research complete";
+}
+
+export class ResearcherRole extends BaseRole {
+  constructor({ config, logger, emitter = null, createAgentFn = null }) {
+    super({ name: "researcher", config, logger, emitter });
+    this._createAgent = createAgentFn || defaultCreateAgent;
+  }
+
+  async execute(input) {
+    const task = typeof input === "string"
+      ? input
+      : input?.task || this.context?.task || "";
+
+    const provider = resolveProvider(this.config);
+    const agent = this._createAgent(provider, this.config, this.logger);
+
+    const prompt = buildPrompt({ task, instructions: this.instructions });
+    const result = await agent.runTask({ prompt, role: "researcher" });
+
+    if (!result.ok) {
+      return {
+        ok: false,
+        result: {
+          error: result.error || result.output || "Researcher failed",
+          provider
+        },
+        summary: `Researcher failed: ${result.error || "unknown error"}`
+      };
+    }
+
+    try {
+      const parsed = parseResearchOutput(result.output);
+      if (!parsed) {
+        return {
+          ok: true,
+          result: {
+            affected_files: [],
+            patterns: [],
+            constraints: [],
+            prior_decisions: [],
+            risks: [],
+            test_coverage: "",
+            raw: result.output,
+            provider
+          },
+          summary: "Research complete (unstructured output)"
+        };
+      }
+
+      return {
+        ok: true,
+        result: {
+          affected_files: parsed.affected_files || [],
+          patterns: parsed.patterns || [],
+          constraints: parsed.constraints || [],
+          prior_decisions: parsed.prior_decisions || [],
+          risks: parsed.risks || [],
+          test_coverage: parsed.test_coverage || "",
+          provider
+        },
+        summary: buildSummary(parsed)
+      };
+    } catch {
+      return {
+        ok: true,
+        result: {
+          affected_files: [],
+          patterns: [],
+          constraints: [],
+          prior_decisions: [],
+          risks: [],
+          test_coverage: "",
+          raw: result.output,
+          provider
+        },
+        summary: "Research complete (unstructured output)"
+      };
+    }
+  }
+}

package/src/roles/reviewer-role.js

@@ -0,0 +1,132 @@
+import { BaseRole } from "./base-role.js";
+import { createAgent as defaultCreateAgent } from "../agents/index.js";
+
+const MAX_DIFF_LENGTH = 12000;
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on reviewing the code."
+].join(" ");
+
+function resolveProvider(config) {
+  return (
+    config?.roles?.reviewer?.provider ||
+    config?.roles?.coder?.provider ||
+    "claude"
+  );
+}
+
+function truncateDiff(diff) {
+  if (!diff) return "";
+  return diff.length > MAX_DIFF_LENGTH
+    ? `${diff.slice(0, MAX_DIFF_LENGTH)}\n\n[TRUNCATED]`
+    : diff;
+}
+
+function buildPrompt({ task, diff, reviewRules, reviewMode, instructions }) {
+  const sections = [];
+
+  sections.push(SUBAGENT_PREAMBLE);
+
+  if (instructions) {
+    sections.push(instructions);
+  }
+
+  sections.push(`You are a code reviewer in ${reviewMode || "standard"} mode.`);
+  sections.push(
+    "Return only one valid JSON object and nothing else.",
+    'JSON schema:',
+    '{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}'
+  );
+
+  sections.push(`Task context:\n${task}`);
+
+  if (reviewRules) {
+    sections.push(`Review rules:\n${reviewRules}`);
+  }
+
+  sections.push(`Git diff:\n${truncateDiff(diff)}`);
+
+  return sections.join("\n\n");
+}
+
+function parseReviewOutput(raw) {
+  const text = raw?.trim() || "";
+  const jsonMatch = text.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) {
+    throw new Error(`Failed to parse reviewer output: no JSON found`);
+  }
+  return JSON.parse(jsonMatch[0]);
+}
+
+export class ReviewerRole extends BaseRole {
+  constructor({ config, logger, emitter = null, createAgentFn = null }) {
+    super({ name: "reviewer", config, logger, emitter });
+    this._createAgent = createAgentFn || defaultCreateAgent;
+  }
+
+  async execute(input) {
+    const { task, diff, reviewRules, onOutput } = typeof input === "string"
+      ? { task: input, diff: "", reviewRules: null, onOutput: null }
+      : input;
+
+    const provider = resolveProvider(this.config);
+    const agent = this._createAgent(provider, this.config, this.logger);
+
+    const prompt = buildPrompt({
+      task: task || this.context?.task || "",
+      diff: diff || "",
+      reviewRules: reviewRules || null,
+      reviewMode: this.config?.review_mode || "standard",
+      instructions: this.instructions
+    });
+
+    const reviewArgs = { prompt, role: "reviewer" };
+    if (onOutput) reviewArgs.onOutput = onOutput;
+
+    const result = await agent.reviewTask(reviewArgs);
+
+    if (!result.ok) {
+      return {
+        ok: false,
+        result: {
+          error: result.error || result.output || "Reviewer agent failed",
+          approved: false,
+          blocking_issues: []
+        },
+        summary: `Reviewer failed: ${result.error || "unknown error"}`
+      };
+    }
+
+    try {
+      const parsed = parseReviewOutput(result.output);
+      const approved = Boolean(parsed.approved);
+      const blockingIssues = parsed.blocking_issues || [];
+
+      return {
+        ok: true,
+        result: {
+          approved,
+          blocking_issues: blockingIssues,
+          non_blocking_suggestions: parsed.non_blocking_suggestions || [],
+          confidence: parsed.confidence ?? null,
+          raw_summary: parsed.summary || ""
+        },
+        summary: approved
+          ? `Approved: ${parsed.summary || "no issues found"}`
+          : `Rejected: ${blockingIssues.length} blocking issue(s) — ${parsed.summary || ""}`
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        result: {
+          error: `Failed to parse reviewer output: ${err.message}`,
+          approved: false,
+          blocking_issues: []
+        },
+        summary: `Reviewer output parse error: ${err.message}`
+      };
+    }
+  }
+}