karajan-code 1.2.3 → 1.3.0

package/package.json

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

package/src/config.js

@@ -114,10 +114,18 @@ const DEFAULTS = {
     max_sonar_retries: 3,
     max_reviewer_retries: 3,
     max_tester_retries: 1,
-    max_security_retries: 1
+    max_security_retries: 1,
+    expiry_days: 30
   },
   failFast: {
     repeatThreshold: 2
+  },
+  retry: {
+    max_attempts: 3,
+    initial_backoff_ms: 1000,
+    max_backoff_ms: 30000,
+    backoff_multiplier: 2,
+    jitter_factor: 0.1
   }
 };
 

package/src/planning-game/client.js

@@ -9,6 +9,8 @@
  * Requires planning_game.api_url in config or PG_API_URL env var.
  */
 
+import { withRetry, isTransientError } from "../utils/retry.js";
+
 const DEFAULT_API_URL = "http://localhost:3000/api";
 const DEFAULT_TIMEOUT_MS = 10000;
 
@@ -20,10 +22,20 @@ async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_M
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    return await fetch(url, { ...options, signal: controller.signal });
+    const response = await fetch(url, { ...options, signal: controller.signal });
+    if (!response.ok) {
+      const err = new Error(`Planning Game API error: ${response.status} ${response.statusText}`);
+      err.httpStatus = response.status;
+      err.retryAfter = response.headers?.get?.("retry-after") || null;
+      throw err;
+    }
+    return response;
   } catch (error) {
+    if (error?.httpStatus) throw error;
     if (error?.name === "AbortError") {
-      throw new Error(`Planning Game API timeout after ${timeoutMs}ms`);
+      const err = new Error(`Planning Game API timeout after ${timeoutMs}ms`);
+      err.httpStatus = 408;
+      throw err;
     }
     throw new Error(`Planning Game network error: ${error?.message || "unknown error"}`);
   } finally {
@@ -31,6 +43,13 @@ async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_M
   }
 }
 
+async function fetchWithRetry(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_MS, retryOpts = {}) {
+  return withRetry(
+    () => fetchWithTimeout(url, options, timeoutMs),
+    { maxAttempts: 3, initialBackoffMs: 1000, ...retryOpts }
+  );
+}
+
 async function parseJsonResponse(response) {
   try {
     return await response.json();
@@ -41,10 +60,7 @@ async function parseJsonResponse(response) {
 
 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 response = await fetchWithRetry(url, {}, timeoutMs);
   const data = await parseJsonResponse(response);
   return data?.card || data;
 }
@@ -55,27 +71,21 @@ export async function getCard({ projectId, cardId, timeoutMs = DEFAULT_TIMEOUT_M
 
 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 response = await fetchWithRetry(url, {}, timeoutMs);
   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(
+  const response = await fetchWithRetry(
     url,
     {
-    method: "PATCH",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ updates })
+      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/plugins/loader.js

@@ -0,0 +1,67 @@
+/**
+ * Plugin loader: discovers and loads plugins from .karajan/plugins/ directories.
+ *
+ * Plugins are JS files that export a `register(api)` function.
+ * The `api` object provides: registerAgent, registerModel.
+ *
+ * Discovery order (all are loaded, not first-wins):
+ *   1. <project>/.karajan/plugins/*.js
+ *   2. ~/.karajan/plugins/*.js
+ */
+
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { getKarajanHome } from "../utils/paths.js";
+import { registerAgent } from "../agents/index.js";
+
+async function listPluginFiles(dir) {
+  try {
+    const { readdir } = await import("node:fs/promises");
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isFile() && e.name.endsWith(".js"))
+      .map((e) => path.join(dir, e.name));
+  } catch {
+    return [];
+  }
+}
+
+async function loadPlugin(filePath, api, logger) {
+  try {
+    const mod = await import(pathToFileURL(filePath).href);
+    const registerFn = mod.register || mod.default?.register;
+    if (typeof registerFn !== "function") {
+      logger?.warn?.(`Plugin ${filePath}: no register() export found, skipping`);
+      return null;
+    }
+    const meta = registerFn(api);
+    const name = meta?.name || path.basename(filePath, ".js");
+    logger?.debug?.(`Plugin loaded: ${name} (${filePath})`);
+    return { name, path: filePath, meta };
+  } catch (error) {
+    logger?.warn?.(`Plugin ${filePath} failed to load: ${error.message}`);
+    return null;
+  }
+}
+
+export async function loadPlugins({ projectDir, logger } = {}) {
+  const dirs = [];
+
+  if (projectDir) {
+    dirs.push(path.join(projectDir, ".karajan", "plugins"));
+  }
+  dirs.push(path.join(getKarajanHome(), "plugins"));
+
+  const api = { registerAgent };
+
+  const loaded = [];
+  for (const dir of dirs) {
+    const files = await listPluginFiles(dir);
+    for (const file of files) {
+      const result = await loadPlugin(file, api, logger);
+      if (result) loaded.push(result);
+    }
+  }
+
+  return loaded;
+}

package/src/session-cleanup.js

@@ -0,0 +1,63 @@
+/**
+ * Automatic cleanup of expired sessions.
+ * Removes session directories older than session.expiry_days (default: 30).
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getSessionRoot } from "./utils/paths.js";
+
+const DEFAULT_EXPIRY_DAYS = 30;
+
+export async function cleanupExpiredSessions({ config, logger } = {}) {
+  const expiryDays = config?.session?.expiry_days ?? DEFAULT_EXPIRY_DAYS;
+  if (expiryDays <= 0) return { removed: 0, errors: [] };
+
+  const sessionRoot = getSessionRoot();
+  const cutoff = Date.now() - expiryDays * 24 * 60 * 60 * 1000;
+
+  let entries;
+  try {
+    entries = await fs.readdir(sessionRoot, { withFileTypes: true });
+  } catch {
+    return { removed: 0, errors: [] };
+  }
+
+  const dirs = entries.filter((e) => e.isDirectory() && e.name.startsWith("s_"));
+  const removed = [];
+  const errors = [];
+
+  for (const dir of dirs) {
+    const sessionDir = path.join(sessionRoot, dir.name);
+    const sessionFile = path.join(sessionDir, "session.json");
+
+    try {
+      const raw = await fs.readFile(sessionFile, "utf8");
+      const session = JSON.parse(raw);
+      const updatedAt = new Date(session.updated_at || session.created_at).getTime();
+
+      if (updatedAt < cutoff) {
+        await fs.rm(sessionDir, { recursive: true, force: true });
+        removed.push(dir.name);
+        logger?.debug?.(`Session expired and removed: ${dir.name}`);
+      }
+    } catch (error) {
+      const stat = await fs.stat(sessionDir).catch(() => null);
+      if (stat && stat.mtimeMs < cutoff) {
+        try {
+          await fs.rm(sessionDir, { recursive: true, force: true });
+          removed.push(dir.name);
+          logger?.debug?.(`Orphan session dir removed: ${dir.name}`);
+        } catch (rmErr) {
+          errors.push({ session: dir.name, error: rmErr.message });
+        }
+      }
+    }
+  }
+
+  if (removed.length > 0) {
+    logger?.info?.(`Cleaned up ${removed.length} expired session(s)`);
+  }
+
+  return { removed: removed.length, errors };
+}

package/src/sonar/api.js

@@ -1,4 +1,5 @@
 import { runCommand } from "../utils/process.js";
+import { withRetry } from "../utils/retry.js";
 import { resolveSonarProjectKey } from "./project-key.js";
 
 export class SonarApiError extends Error {
@@ -22,16 +23,18 @@ function parseHttpResponse(stdout) {
   return { httpCode, body };
 }
 
-async function sonarFetch(config, urlPath) {
+async function sonarFetchOnce(config, urlPath) {
   const token = tokenFromConfig(config);
   const url = `${config.sonarqube.host}${urlPath}`;
   const res = await runCommand("curl", ["-s", "-w", "\n%{http_code}", "-u", `${token}:`, url]);
 
   if (res.exitCode !== 0) {
-    throw new SonarApiError(
+    const err = new SonarApiError(
       `SonarQube is not reachable at ${config.sonarqube.host}. Check that SonarQube is running ('kj sonar start').`,
       { url, hint: "Run 'kj sonar start' or verify Docker is running." }
     );
+    err.httpStatus = 503;
+    throw err;
   }
 
   const { httpCode, body } = parseHttpResponse(res.stdout);
@@ -44,15 +47,25 @@ async function sonarFetch(config, urlPath) {
   }
 
   if (httpCode >= 400) {
-    throw new SonarApiError(
+    const err = new SonarApiError(
       `SonarQube API returned HTTP ${httpCode} for ${url}.`,
       { url, httpStatus: httpCode }
     );
+    err.httpStatus = httpCode;
+    throw err;
   }
 
   return body;
 }
 
+async function sonarFetch(config, urlPath) {
+  const maxAttempts = config.sonarqube?.max_scan_retries ?? 3;
+  return withRetry(
+    () => sonarFetchOnce(config, urlPath),
+    { maxAttempts, initialBackoffMs: 2000, maxBackoffMs: 15000 }
+  );
+}
+
 export async function getQualityGateStatus(config, projectKey = null) {
   const effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey });
   const body = await sonarFetch(config, `/api/qualitygates/project_status?projectKey=${effectiveProjectKey}`);

package/src/utils/retry.js

@@ -0,0 +1,88 @@
+/**
+ * Generic retry utility with exponential backoff and jitter.
+ * Handles transient errors (429, 502, 503, timeouts) automatically.
+ */
+
+const TRANSIENT_HTTP_CODES = new Set([408, 429, 500, 502, 503, 504]);
+
+const TRANSIENT_ERROR_PATTERNS = [
+  "ETIMEDOUT", "ECONNREFUSED", "ECONNRESET", "EPIPE",
+  "ENETUNREACH", "EAI_AGAIN", "EHOSTUNREACH",
+  "socket hang up", "network error", "fetch failed"
+];
+
+const DEFAULT_OPTIONS = {
+  maxAttempts: 3,
+  initialBackoffMs: 1000,
+  maxBackoffMs: 30000,
+  backoffMultiplier: 2,
+  jitterFactor: 0.1,
+  onRetry: null
+};
+
+export function isTransientError(error) {
+  if (!error) return false;
+
+  if (error.httpStatus && TRANSIENT_HTTP_CODES.has(error.httpStatus)) return true;
+  if (error.status && TRANSIENT_HTTP_CODES.has(error.status)) return true;
+
+  const msg = (error.message || String(error)).toLowerCase();
+  return TRANSIENT_ERROR_PATTERNS.some((p) => msg.includes(p.toLowerCase()));
+}
+
+export function parseRetryAfter(headerValue) {
+  if (!headerValue) return null;
+  const seconds = Number(headerValue);
+  if (!Number.isNaN(seconds) && seconds > 0) return seconds * 1000;
+
+  const date = Date.parse(headerValue);
+  if (!Number.isNaN(date)) {
+    const delayMs = date - Date.now();
+    return delayMs > 0 ? delayMs : null;
+  }
+  return null;
+}
+
+export function calculateBackoff(attempt, options = {}) {
+  const { initialBackoffMs = 1000, maxBackoffMs = 30000, backoffMultiplier = 2, jitterFactor = 0.1 } = options;
+
+  const base = initialBackoffMs * Math.pow(backoffMultiplier, attempt);
+  const capped = Math.min(base, maxBackoffMs);
+  const jitter = capped * jitterFactor * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(capped + jitter));
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function withRetry(fn, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError;
+
+  for (let attempt = 0; attempt < opts.maxAttempts; attempt++) {
+    try {
+      return await fn(attempt);
+    } catch (error) {
+      lastError = error;
+
+      if (attempt >= opts.maxAttempts - 1) break;
+      if (!isTransientError(error)) break;
+
+      let delayMs = calculateBackoff(attempt, opts);
+
+      const retryAfterMs = parseRetryAfter(error.retryAfter || error.headers?.get?.("retry-after"));
+      if (retryAfterMs) {
+        delayMs = Math.min(retryAfterMs, opts.maxBackoffMs);
+      }
+
+      if (opts.onRetry) {
+        opts.onRetry({ attempt, error, delayMs, maxAttempts: opts.maxAttempts });
+      }
+
+      await sleep(delayMs);
+    }
+  }
+
+  throw lastError;
+}