karajan-code 1.2.0

package/src/planning-game/adapter.js

@@ -0,0 +1,105 @@
+/**
+ * Planning Game MCP adapter.
+ * Handles card ID detection, task enrichment, and completion updates.
+ */
+
+const CARD_ID_PATTERN = /[A-Z0-9]{2,5}-(?:TSK|BUG|PCS|PRP|SPR|QA)-\d{4}/;
+
+export function parseCardId(text) {
+  if (!text) return null;
+  const match = String(text).match(CARD_ID_PATTERN);
+  return match ? match[0] : null;
+}
+
+export function buildTaskFromCard(card) {
+  const parts = [`## ${card.cardId}: ${card.title}`];
+
+  if (card.descriptionStructured?.length) {
+    parts.push("", "### User Story");
+    for (const s of card.descriptionStructured) {
+      parts.push(`- **Como** ${s.role}`);
+      parts.push(`  **Quiero** ${s.goal}`);
+      parts.push(`  **Para** ${s.benefit}`);
+    }
+  } else if (card.description) {
+    parts.push("", "### Description", card.description);
+  }
+
+  if (card.acceptanceCriteriaStructured?.length) {
+    parts.push("", "### Acceptance Criteria");
+    for (const ac of card.acceptanceCriteriaStructured) {
+      if (ac.given && ac.when && ac.then) {
+        parts.push(`- **Given** ${ac.given}`);
+        parts.push(`  **When** ${ac.when}`);
+        parts.push(`  **Then** ${ac.then}`);
+      } else if (ac.raw) {
+        parts.push(`- ${ac.raw}`);
+      }
+    }
+  } else if (card.acceptanceCriteria) {
+    parts.push("", "### Acceptance Criteria", card.acceptanceCriteria);
+  }
+
+  if (card.implementationPlan) {
+    const plan = card.implementationPlan;
+    parts.push("", "### Implementation Plan");
+    if (plan.approach) parts.push(`**Approach:** ${plan.approach}`);
+    if (plan.steps?.length) {
+      parts.push("**Steps:**");
+      for (const step of plan.steps) {
+        parts.push(`1. ${step.description}`);
+      }
+    }
+  }
+
+  return parts.join("\n");
+}
+
+export function buildCommitsPayload(gitLog) {
+  if (!gitLog || !gitLog.length) return [];
+  return gitLog.map((entry) => ({
+    hash: entry.hash,
+    message: entry.message,
+    date: entry.date,
+    author: entry.author
+  }));
+}
+
+export function buildCompletionUpdates({ approved, commits, startDate, codeveloper }) {
+  if (!approved) return {};
+
+  const updates = {
+    status: "To Validate",
+    endDate: new Date().toISOString(),
+    developer: "dev_016",
+    commits: commits || []
+  };
+
+  if (startDate) updates.startDate = startDate;
+  if (codeveloper) updates.codeveloper = codeveloper;
+
+  return updates;
+}
+
+export function buildTaskPrompt({ task, card }) {
+  const cardId = parseCardId(task) || card?.cardId || null;
+  const prompt = card ? buildTaskFromCard(card) : task;
+  return { cardId, prompt };
+}
+
+export async function updateCardOnCompletion({
+  client,
+  projectId,
+  cardId,
+  firebaseId,
+  approved,
+  gitLog,
+  startDate,
+  codeveloper
+}) {
+  if (!approved) return null;
+
+  const commits = buildCommitsPayload(gitLog);
+  const updates = buildCompletionUpdates({ approved, commits, startDate, codeveloper });
+  return client.updateCard({ projectId, cardId, firebaseId, updates });
+}

package/src/planning-game/client.js

@@ -0,0 +1,81 @@
+/**
+ * Planning Game MCP client.
+ * Communicates with Planning Game via HTTP API or MCP tool calls.
+ *
+ * When Karajan runs as an MCP server (kj_run), the caller (Claude Code)
+ * is expected to provide card data directly via pgTask/pgProject flags.
+ *
+ * This client provides standalone HTTP access for CLI usage (kj run --pg-task).
+ * Requires planning_game.api_url in config or PG_API_URL env var.
+ */
+
+const DEFAULT_API_URL = "http://localhost:3000/api";
+const DEFAULT_TIMEOUT_MS = 10000;
+
+function getApiUrl() {
+  return process.env.PG_API_URL || DEFAULT_API_URL;
+}
+
+async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...options, signal: controller.signal });
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw new Error(`Planning Game API timeout after ${timeoutMs}ms`);
+    }
+    throw new Error(`Planning Game network error: ${error?.message || "unknown error"}`);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+async function parseJsonResponse(response) {
+  try {
+    return await response.json();
+  } catch (error) {
+    throw new Error(`Planning Game invalid response: ${error?.message || "invalid JSON"}`);
+  }
+}
+
+export async function fetchCard({ projectId, cardId, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards/${encodeURIComponent(cardId)}`;
+  const response = await fetchWithTimeout(url, {}, timeoutMs);
+  if (!response.ok) {
+    throw new Error(`Planning Game API error: ${response.status} ${response.statusText}`);
+  }
+  const data = await parseJsonResponse(response);
+  return data?.card || data;
+}
+
+export async function getCard({ projectId, cardId, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  return fetchCard({ projectId, cardId, timeoutMs });
+}
+
+export async function listCards({ projectId, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards`;
+  const response = await fetchWithTimeout(url, {}, timeoutMs);
+  if (!response.ok) {
+    throw new Error(`Planning Game API error: ${response.status} ${response.statusText}`);
+  }
+  const data = await parseJsonResponse(response);
+  return data?.cards || data;
+}
+
+export async function updateCard({ projectId, cardId, firebaseId, updates, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards/${encodeURIComponent(firebaseId)}`;
+  const response = await fetchWithTimeout(
+    url,
+    {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ updates })
+    },
+    timeoutMs
+  );
+  if (!response.ok) {
+    throw new Error(`Planning Game API error: ${response.status} ${response.statusText}`);
+  }
+  return parseJsonResponse(response);
+}

package/src/prompts/coder.js

@@ -0,0 +1,60 @@
+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.",
+  "Execute the task directly. Do NOT use any MCP tools. Focus only on coding."
+].join(" ");
+
+const SUBAGENT_PREAMBLE_SERENA = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Execute the task directly. Focus only on coding."
+].join(" ");
+
+const SERENA_INSTRUCTIONS = [
+  "## Serena MCP — symbol-level code navigation",
+  "You have access to Serena MCP tools for efficient code navigation.",
+  "Prefer these over reading entire files to save tokens:",
+  "- `find_symbol(name)` — locate a function, class, or variable definition",
+  "- `find_referencing_symbols(name)` — find all code that references a symbol",
+  "- `insert_after_symbol(name, code)` — insert code precisely after a symbol",
+  "Use Serena for understanding existing code structure before making changes.",
+  "Fall back to reading files only when Serena tools are not sufficient."
+].join("\n");
+
+export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false }) {
+  const sections = [
+    serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
+    `Task:\n${task}`,
+    "Implement directly in the repository.",
+    "Keep changes minimal and production-ready."
+  ];
+
+  if (serenaEnabled) {
+    sections.push(SERENA_INSTRUCTIONS);
+  }
+
+  if (coderRules) {
+    sections.push(`Coder rules (MUST follow):\n${coderRules}`);
+  }
+
+  if (methodology === "tdd") {
+    sections.push(
+      [
+        "Default development policy: TDD.",
+        "1) Add or update failing tests first.",
+        "2) Implement minimal code to make tests pass.",
+        "3) Refactor safely while keeping tests green."
+      ].join("\n")
+    );
+  }
+
+  if (sonarSummary) {
+    sections.push(`Sonar summary:\n${sonarSummary}`);
+  }
+
+  if (reviewerFeedback) {
+    sections.push(`Reviewer blocking feedback:\n${reviewerFeedback}`);
+  }
+
+  return sections.join("\n\n");
+}

package/src/prompts/planner.js

@@ -0,0 +1,26 @@
+export function buildPlannerPrompt({ task, context }) {
+  const parts = [
+    "You are an expert software architect. Create an implementation plan for the following task.",
+    "",
+    "## Task",
+    task,
+    ""
+  ];
+
+  if (context) {
+    parts.push("## Context", context, "");
+  }
+
+  parts.push(
+    "## Output format",
+    "Respond with a JSON object containing:",
+    "- `approach`: A concise paragraph describing the overall strategy",
+    "- `steps`: An array of objects, each with `description` (what to do) and `commit` (conventional commit message). Each step should correspond to a single commit.",
+    "- `risks`: An array of strings describing potential risks or challenges",
+    "- `outOfScope`: An array of strings listing what is explicitly NOT included",
+    "",
+    "Respond ONLY with valid JSON, no markdown fences or extra text."
+  );
+
+  return parts.join("\n");
+}

package/src/prompts/reviewer.js

@@ -0,0 +1,45 @@
+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(" ");
+
+const SUBAGENT_PREAMBLE_SERENA = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Focus only on reviewing the code."
+].join(" ");
+
+const SERENA_INSTRUCTIONS = [
+  "## Serena MCP — symbol-level code navigation",
+  "You have access to Serena MCP tools for efficient code review.",
+  "Use these to verify context without reading entire files:",
+  "- `find_symbol(name)` — locate a function, class, or variable definition",
+  "- `find_referencing_symbols(name)` — find all callers/references of a symbol",
+  "Use Serena to check how changed symbols are used across the codebase.",
+  "Fall back to reading files only when Serena tools are not sufficient."
+].join("\n");
+
+export function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false }) {
+  const truncatedDiff = diff.length > 12000 ? `${diff.slice(0, 12000)}\n\n[TRUNCATED]` : diff;
+
+  const sections = [
+    serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
+    `You are a code reviewer in ${mode} mode.`,
+    "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}'
+  ];
+
+  if (serenaEnabled) {
+    sections.push(SERENA_INSTRUCTIONS);
+  }
+
+  sections.push(
+    `Task context:\n${task}`,
+    `Review rules:\n${reviewRules}`,
+    `Git diff:\n${truncatedDiff}`
+  );
+
+  return sections.join("\n\n");
+}

package/src/repeat-detector.js

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+
+const DEFAULT_THRESHOLD = 2;
+
+function normalizeIssueKey(value) {
+  if (value === null || value === undefined) return "";
+  return String(value).trim();
+}
+
+function buildIssueSignature(issues, keySelector) {
+  const counts = new Map();
+  for (const issue of issues || []) {
+    const key = normalizeIssueKey(keySelector(issue));
+    if (!key) continue;
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  if (counts.size === 0) return "";
+  return Array.from(counts.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, count]) => `${key}:${count}`)
+    .join("|");
+}
+
+function hashSignature(signature) {
+  if (!signature) return "";
+  return createHash("sha256").update(signature).digest("hex");
+}
+
+function updateRepeatState(state, signatureHash) {
+  if (!signatureHash) {
+    return { lastHash: null, repeatCount: 0 };
+  }
+  const nextCount = signatureHash === state.lastHash ? state.repeatCount + 1 : 1;
+  return { lastHash: signatureHash, repeatCount: nextCount };
+}
+
+function parseThreshold(value) {
+  const parsed = Number(value);
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  return DEFAULT_THRESHOLD;
+}
+
+export class RepeatDetector {
+  constructor({ threshold = DEFAULT_THRESHOLD } = {}) {
+    this.threshold = parseThreshold(threshold);
+    this.sonar = { lastHash: null, repeatCount: 0 };
+    this.reviewer = { lastHash: null, repeatCount: 0 };
+  }
+
+  addIteration(sonarIssues, reviewerIssues) {
+    const sonarSignature = buildIssueSignature(
+      sonarIssues || [],
+      (issue) => issue?.rule || issue?.message
+    );
+    const reviewerSignature = buildIssueSignature(
+      reviewerIssues || [],
+      (issue) => issue?.description || issue?.content || issue?.id
+    );
+
+    this.sonar = updateRepeatState(this.sonar, hashSignature(sonarSignature));
+    this.reviewer = updateRepeatState(this.reviewer, hashSignature(reviewerSignature));
+  }
+
+  isStalled() {
+    if (this.sonar.repeatCount >= this.threshold) {
+      return { stalled: true, reason: "sonar_repeat" };
+    }
+    if (this.reviewer.repeatCount >= this.threshold) {
+      return { stalled: true, reason: "reviewer_repeat" };
+    }
+    return { stalled: false, reason: "" };
+  }
+
+  getRepeatCounts() {
+    return { sonar: this.sonar.repeatCount, reviewer: this.reviewer.repeatCount };
+  }
+}

package/src/review/diff-generator.js

@@ -0,0 +1,22 @@
+import { runCommand } from "../utils/process.js";
+
+export async function computeBaseRef({ baseBranch = "main", baseRef = null }) {
+  if (baseRef) return baseRef;
+  const mergeBase = await runCommand("git", ["merge-base", "HEAD", `origin/${baseBranch}`]);
+  if (mergeBase.exitCode !== 0) {
+    const fallback = await runCommand("git", ["rev-parse", "HEAD~1"]);
+    if (fallback.exitCode !== 0) {
+      throw new Error("Could not compute diff base reference");
+    }
+    return fallback.stdout.trim();
+  }
+  return mergeBase.stdout.trim();
+}
+
+export async function generateDiff({ baseRef }) {
+  const result = await runCommand("git", ["diff", `${baseRef}`]);
+  if (result.exitCode !== 0) {
+    throw new Error(`git diff failed: ${result.stderr || result.stdout}`);
+  }
+  return result.stdout;
+}

package/src/review/parser.js

@@ -0,0 +1,93 @@
+/**
+ * Review output parsing helpers.
+ * Extracted from orchestrator.js to improve testability and reduce complexity.
+ */
+
+export function parseMaybeJsonString(value) {
+  if (typeof value !== "string") return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    const start = value.indexOf("{");
+    const end = value.lastIndexOf("}");
+    if (start >= 0 && end > start) {
+      const candidate = value.slice(start, end + 1);
+      try {
+        return JSON.parse(candidate);
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+}
+
+export function normalizeReviewPayload(payload) {
+  if (!payload) return null;
+
+  if (payload.approved !== undefined && payload.blocking_issues !== undefined) {
+    return payload;
+  }
+
+  if (Array.isArray(payload)) {
+    for (let i = payload.length - 1; i >= 0; i -= 1) {
+      const item = payload[i];
+      if (item?.approved !== undefined && item?.blocking_issues !== undefined) {
+        return item;
+      }
+
+      const nested = item?.result || item?.message?.content?.[0]?.text;
+      if (typeof nested === "string") {
+        const parsedNested = parseMaybeJsonString(nested);
+        if (parsedNested?.approved !== undefined) return parsedNested;
+      }
+    }
+    return null;
+  }
+
+  if (typeof payload.result === "string") {
+    const parsedResult = parseMaybeJsonString(payload.result);
+    if (parsedResult?.approved !== undefined) return parsedResult;
+    return null;
+  }
+
+  return null;
+}
+
+export function parseJsonOutput(raw) {
+  const cleaned = raw.trim();
+  if (!cleaned) return null;
+  try {
+    const parsed = JSON.parse(cleaned);
+    return normalizeReviewPayload(parsed);
+  } catch {
+    const lines = cleaned
+      .split("\n")
+      .map((x) => x.trim())
+      .filter(Boolean);
+
+    const parsedLines = [];
+    for (const line of lines) {
+      try {
+        parsedLines.push(JSON.parse(line));
+      } catch {
+        continue;
+      }
+    }
+
+    const normalizedLines = normalizeReviewPayload(parsedLines);
+    if (normalizedLines) {
+      return normalizedLines;
+    }
+
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      try {
+        const parsed = JSON.parse(lines[i]);
+        return normalizeReviewPayload(parsed);
+      } catch {
+        continue;
+      }
+    }
+  }
+  return null;
+}

package/src/review/profiles.js

@@ -0,0 +1,66 @@
+/**
+ * Review profile resolver.
+ * Loads mode-specific reviewer instructions with fallback chain:
+ *   1. Project-level / user-level / built-in reviewer-{mode}.md
+ *   2. Project-level / user-level / built-in reviewer.md
+ *   3. Hardcoded default
+ */
+
+import path from "node:path";
+import { loadFirstExisting } from "../roles/base-role.js";
+import { getKarajanHome } from "../utils/paths.js";
+
+const KNOWN_MODES = ["paranoid", "strict", "standard", "relaxed"];
+
+const DEFAULT_RULES = "Focus on critical issues: security vulnerabilities, logic errors, and broken tests.";
+
+function buildCandidates(fileName, projectDir) {
+  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;
+}
+
+export async function resolveReviewProfile({ mode = "standard", projectDir } = {}) {
+  // Known modes: try mode-specific file first, then base reviewer.md
+  if (KNOWN_MODES.includes(mode)) {
+    const modePaths = buildCandidates(`reviewer-${mode}.md`, projectDir);
+    const modeRules = await loadFirstExisting(modePaths);
+    if (modeRules) {
+      return { mode, rules: modeRules };
+    }
+
+    // Fallback to base reviewer.md
+    const basePaths = buildCandidates("reviewer.md", projectDir);
+    const baseRules = await loadFirstExisting(basePaths);
+    if (baseRules) {
+      return { mode, rules: baseRules };
+    }
+
+    return { mode, rules: DEFAULT_RULES };
+  }
+
+  // Custom/unknown modes: only check base reviewer.md
+  const basePaths = buildCandidates("reviewer.md", projectDir);
+  const baseRules = await loadFirstExisting(basePaths);
+  if (baseRules) {
+    return { mode, rules: baseRules };
+  }
+
+  return { mode, rules: DEFAULT_RULES };
+}

package/src/review/schema.js

@@ -0,0 +1,31 @@
+export function validateReviewResult(reviewResult) {
+  if (!reviewResult || typeof reviewResult !== "object") {
+    throw new Error("Reviewer output must be a JSON object");
+  }
+
+  if (typeof reviewResult.approved !== "boolean") {
+    throw new Error("Reviewer output missing boolean field: approved");
+  }
+
+  if (!Array.isArray(reviewResult.blocking_issues)) {
+    throw new Error("Reviewer output missing array field: blocking_issues");
+  }
+
+  if (!Array.isArray(reviewResult.non_blocking_suggestions)) {
+    reviewResult.non_blocking_suggestions = [];
+  }
+
+  if (typeof reviewResult.summary !== "string") {
+    reviewResult.summary = "";
+  }
+
+  if (typeof reviewResult.confidence !== "number") {
+    reviewResult.confidence = 0.5;
+  }
+
+  if (reviewResult.approved && reviewResult.blocking_issues.length > 0) {
+    throw new Error("Invalid reviewer output: approved=true with blocking issues");
+  }
+
+  return reviewResult;
+}

package/src/review/tdd-policy.js

@@ -0,0 +1,57 @@
+function extractChangedFiles(diff) {
+  const files = new Set();
+  const lines = String(diff || "").split("\n");
+  for (const line of lines) {
+    if (!line.startsWith("diff --git ")) continue;
+    const parts = line.split(" ");
+    const b = parts[3] || "";
+    if (b.startsWith("b/")) files.add(b.slice(2));
+  }
+  return [...files];
+}
+
+function isTestFile(file, patterns = []) {
+  const normalized = `/${file}`;
+  return patterns.some((pattern) => normalized.includes(pattern));
+}
+
+function isSourceFile(file, extensions = []) {
+  return extensions.some((ext) => file.endsWith(ext));
+}
+
+export function evaluateTddPolicy(diff, developmentConfig = {}) {
+  const requireTestChanges = developmentConfig.require_test_changes !== false;
+  const patterns = developmentConfig.test_file_patterns || ["/tests/", "/__tests__/", ".test.", ".spec."];
+  const extensions =
+    developmentConfig.source_file_extensions || [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".rb", ".php", ".cs"];
+
+  const files = extractChangedFiles(diff);
+  const sourceFiles = files.filter((f) => isSourceFile(f, extensions) && !isTestFile(f, patterns));
+  const testFiles = files.filter((f) => isTestFile(f, patterns));
+
+  if (!requireTestChanges) {
+    return {
+      ok: true,
+      reason: "test_changes_not_required",
+      sourceFiles,
+      testFiles
+    };
+  }
+
+  if (sourceFiles.length === 0) {
+    return { ok: true, reason: "no_source_changes", sourceFiles, testFiles };
+  }
+
+  if (testFiles.length === 0) {
+    return {
+      ok: false,
+      reason: "source_changes_without_tests",
+      sourceFiles,
+      testFiles,
+      message:
+        "TDD policy violation: source code changed without test changes. Add/adjust tests first, then implementation."
+    };
+  }
+
+  return { ok: true, reason: "tests_present", sourceFiles, testFiles };
+}