karajan-code 1.2.0

package/src/utils/logger.js

@@ -0,0 +1,86 @@
+import { EventEmitter } from "node:events";
+
+const LEVELS = ["debug", "info", "warn", "error"];
+
+const ANSI = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  gray: "\x1b[90m"
+};
+
+const LEVEL_COLORS = {
+  debug: ANSI.gray,
+  info: ANSI.cyan,
+  warn: ANSI.yellow,
+  error: ANSI.red
+};
+
+function timestamp() {
+  return new Date().toISOString().slice(11, 23);
+}
+
+function formatContext(ctx) {
+  const parts = [];
+  if (ctx.iteration !== undefined) parts.push(`iter=${ctx.iteration}`);
+  if (ctx.stage) parts.push(`stage=${ctx.stage}`);
+  return parts.length ? `[${parts.join(" ")}] ` : "";
+}
+
+export function createLogger(level = "info", mode = "cli") {
+  const min = LEVELS.indexOf(level);
+  const minIdx = min === -1 ? 1 : min;
+  const emitter = new EventEmitter();
+  let context = {};
+
+  function canLog(target) {
+    return LEVELS.indexOf(target) >= minIdx;
+  }
+
+  function emit(lvl, args) {
+    const entry = {
+      level: lvl,
+      timestamp: new Date().toISOString(),
+      context: { ...context },
+      message: args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ")
+    };
+    emitter.emit("log", entry);
+  }
+
+  function log(lvl, ...args) {
+    if (!canLog(lvl)) return;
+    emit(lvl, args);
+    if (mode === "silent") return;
+    if (mode === "mcp") return;
+    const color = LEVEL_COLORS[lvl] || "";
+    const ts = `${ANSI.dim}${timestamp()}${ANSI.reset}`;
+    const prefix = `${color}[${lvl}]${ANSI.reset}`;
+    const ctx = formatContext(context);
+    const stream = lvl === "error" ? console.error : lvl === "warn" ? console.warn : console.log;
+    stream(`${ts} ${prefix} ${ctx}${args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ")}`);
+  }
+
+  return {
+    debug: (...args) => log("debug", ...args),
+    info: (...args) => log("info", ...args),
+    warn: (...args) => log("warn", ...args),
+    error: (...args) => log("error", ...args),
+    setContext(ctx) {
+      context = { ...context, ...ctx };
+    },
+    resetContext() {
+      context = {};
+    },
+    onLog(callback) {
+      emitter.on("log", callback);
+    },
+    offLog(callback) {
+      emitter.off("log", callback);
+    },
+    get mode() {
+      return mode;
+    }
+  };
+}

package/src/utils/paths.js

@@ -0,0 +1,18 @@
+import os from "node:os";
+import path from "node:path";
+
+export function getKarajanHome() {
+  if (process.env.KJ_HOME) {
+    return path.resolve(process.env.KJ_HOME);
+  }
+
+  return path.join(os.homedir(), ".karajan");
+}
+
+export function getSessionRoot() {
+  return path.join(getKarajanHome(), "sessions");
+}
+
+export function getSonarComposePath() {
+  return path.join(getKarajanHome(), "docker-compose.sonar.yml");
+}

package/src/utils/pricing.js

@@ -0,0 +1,28 @@
+export const DEFAULT_MODEL_PRICING = {
+  "claude": { input_per_million: 3, output_per_million: 15 },
+  "claude/sonnet": { input_per_million: 3, output_per_million: 15 },
+  "claude/opus": { input_per_million: 15, output_per_million: 75 },
+  "claude/haiku": { input_per_million: 0.25, output_per_million: 1.25 },
+  "codex": { input_per_million: 1.5, output_per_million: 4 },
+  "codex/o4-mini": { input_per_million: 1.5, output_per_million: 4 },
+  "codex/o3": { input_per_million: 10, output_per_million: 40 },
+  "gemini": { input_per_million: 1.25, output_per_million: 5 },
+  "gemini/pro": { input_per_million: 1.25, output_per_million: 5 },
+  "gemini/flash": { input_per_million: 0.075, output_per_million: 0.3 },
+  "aider": { input_per_million: 3, output_per_million: 15 }
+};
+
+export function calculateUsageCostUsd({ model, tokens_in, tokens_out, pricing }) {
+  const table = pricing || DEFAULT_MODEL_PRICING;
+  const entry = table[model] || null;
+  if (!entry) return 0;
+
+  const inputCost = (tokens_in * entry.input_per_million) / 1_000_000;
+  const outputCost = (tokens_out * entry.output_per_million) / 1_000_000;
+  return inputCost + outputCost;
+}
+
+export function mergePricing(defaults, overrides) {
+  if (!overrides || typeof overrides !== "object") return { ...defaults };
+  return { ...defaults, ...overrides };
+}

package/src/utils/process.js

@@ -0,0 +1,67 @@
+import { execa } from "execa";
+
+export async function runCommand(command, args = [], options = {}) {
+  const { timeout, onOutput, ...rest } = options;
+  const subprocess = execa(command, args, {
+    reject: false,
+    ...rest
+  });
+
+  if (onOutput) {
+    const handler = (stream) => {
+      let partial = "";
+      return (chunk) => {
+        partial += chunk.toString();
+        const lines = partial.split("\n");
+        partial = lines.pop();
+        for (const line of lines) {
+          if (line) onOutput({ stream, line });
+        }
+      };
+    };
+    if (subprocess.stdout) subprocess.stdout.on("data", handler("stdout"));
+    if (subprocess.stderr) subprocess.stderr.on("data", handler("stderr"));
+  }
+
+  try {
+    if (!timeout) {
+      return await subprocess;
+    }
+
+    let timer = null;
+    const timeoutResult = new Promise((resolve) => {
+      timer = setTimeout(() => {
+        try {
+          subprocess.kill("SIGKILL", { forceKillAfterDelay: 1000 });
+        } catch {
+          // no-op
+        }
+        resolve({
+          exitCode: 143,
+          stdout: "",
+          stderr: `Command timed out after ${timeout}ms`
+        });
+      }, timeout);
+    });
+
+    const result = await Promise.race([subprocess, timeoutResult]);
+    if (timer) clearTimeout(timer);
+    return result;
+  } catch (error) {
+    const details = [
+      error?.shortMessage,
+      error?.originalMessage,
+      error?.stderr,
+      error?.stdout,
+      error?.message
+    ]
+      .filter(Boolean)
+      .join("\n");
+
+    return {
+      exitCode: 1,
+      stdout: error?.stdout || "",
+      stderr: details || String(error)
+    };
+  }
+}

package/src/utils/wizard.js

@@ -0,0 +1,41 @@
+import readline from "node:readline";
+
+export function createWizard(input = process.stdin, output = process.stdout) {
+  const rl = readline.createInterface({ input, output });
+
+  function ask(question) {
+    return new Promise((resolve) => {
+      rl.question(question, (answer) => resolve(answer.trim()));
+    });
+  }
+
+  async function confirm(question, defaultValue = true) {
+    const hint = defaultValue ? "[Y/n]" : "[y/N]";
+    const answer = await ask(`${question} ${hint} `);
+    if (answer === "") return defaultValue;
+    return /^y(es)?$/i.test(answer);
+  }
+
+  async function select(question, options) {
+    output.write(`${question}\n`);
+    for (let i = 0; i < options.length; i++) {
+      const opt = options[i];
+      const label = opt.available === false ? `${opt.label} (not installed)` : opt.label;
+      output.write(`  ${i + 1}) ${label}\n`);
+    }
+    const answer = await ask(`Choose [1-${options.length}]: `);
+    const idx = Number(answer) - 1;
+    if (idx >= 0 && idx < options.length) return options[idx].value;
+    return options[0].value;
+  }
+
+  function close() {
+    rl.close();
+  }
+
+  return { ask, confirm, select, close };
+}
+
+export function isTTY() {
+  return Boolean(process.stdin.isTTY);
+}

package/templates/coder-rules.md

@@ -0,0 +1,24 @@
+# Coder Rules
+
+## File modification safety
+
+- NEVER overwrite existing files entirely. Always make targeted, minimal edits.
+- When adding new code to an existing file, insert only the new lines at the correct location.
+- After each edit, verify with `git diff` that ONLY the intended lines changed.
+- If unintended changes are detected, revert immediately with `git checkout -- <file>`.
+- Pay special attention to CSS, HTML, and config files where full rewrites destroy prior work (brand colors, layouts, styles).
+
+## Multi-agent / multi-developer environment
+
+- Multiple developers and AI agents may be committing and modifying code simultaneously.
+- ALWAYS run `git fetch origin main` and check recent commits before starting work.
+- Before pushing or merging, rebase on the latest main: `git rebase origin/main`.
+- If a commit or push fails, check whether someone else pushed in the meantime.
+- Never assume main is unchanged since the last check — always verify.
+- Create a dedicated branch per task (`feat/` or `fix/`) and merge via PR, never push directly to main.
+
+## General
+
+- Keep changes minimal and focused on the task.
+- Do not modify code unrelated to the task.
+- Follow existing code conventions and patterns in the repository.

package/templates/docker-compose.sonar.yml

@@ -0,0 +1,60 @@
+# SonarQube Community Edition + PostgreSQL
+# Karajan Code - Geniova Technologies
+#
+# Prerequisite (Linux):
+#   sudo sysctl -w vm.max_map_count=262144
+#   echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
+#
+# Usage:
+#   docker compose -f docker-compose.sonar.yml up -d
+#   Open http://localhost:9000 (admin/admin on first access)
+
+services:
+  sonarqube:
+    image: sonarqube:community
+    container_name: karajan-sonarqube
+    depends_on:
+      sonarqube-db:
+        condition: service_healthy
+    ports:
+      - "9000:9000"
+    environment:
+      - SONAR_JDBC_URL=jdbc:postgresql://sonarqube-db:5432/sonar
+      - SONAR_JDBC_USERNAME=sonar
+      - SONAR_JDBC_PASSWORD=sonar
+      - SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true
+    volumes:
+      - sonarqube_data:/opt/sonarqube/data
+      - sonarqube_extensions:/opt/sonarqube/extensions
+      - sonarqube_logs:/opt/sonarqube/logs
+    networks:
+      - sonarnet
+    restart: unless-stopped
+
+  sonarqube-db:
+    image: postgres:17
+    container_name: karajan-sonarqube-db
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U sonar"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    environment:
+      - POSTGRES_USER=sonar
+      - POSTGRES_PASSWORD=sonar
+      - POSTGRES_DB=sonar
+    volumes:
+      - postgresql_data:/var/lib/postgresql/data
+    networks:
+      - sonarnet
+    restart: unless-stopped
+
+volumes:
+  sonarqube_data:
+  sonarqube_extensions:
+  sonarqube_logs:
+  postgresql_data:
+
+networks:
+  sonarnet:
+    driver: bridge

package/templates/kj.config.yml

@@ -0,0 +1,82 @@
+# AI Agents
+coder: claude
+reviewer: codex
+
+# Review settings
+review_mode: standard
+max_iterations: 5
+review_rules: ./review-rules.md
+coder_rules: ./coder-rules.md
+base_branch: main
+
+# Coder settings
+coder_options:
+  model: null
+  auto_approve: true
+
+# Reviewer settings
+reviewer_options:
+  output_format: json
+  require_schema: true
+  model: null
+  deterministic: true
+  retries: 1
+  fallback_reviewer: codex
+
+# Development methodology
+development:
+  methodology: tdd
+  require_test_changes: true
+  test_file_patterns:
+    - /tests/
+    - /__tests__/
+    - .test.
+    - .spec.
+
+# SonarQube settings
+sonarqube:
+  enabled: true
+  host: http://localhost:9000
+  token: null
+  quality_gate: true
+  enforcement_profile: pragmatic
+  gate_block_on:
+    - new_reliability_rating=E
+    - new_security_rating=E
+    - new_maintainability_rating=E
+    - new_coverage<80
+    - new_duplicated_lines_density>5
+  fail_on:
+    - BLOCKER
+    - CRITICAL
+  ignore_on:
+    - INFO
+  max_scan_retries: 3
+  scanner:
+    sources: "src,public,lib"
+    exclusions: "**/node_modules/**,**/fake-apps/**,**/scripts/**,**/playground/**,**/dist/**,**/build/**,**/*.min.js"
+    test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**"
+    coverage_exclusions: "**/tests/**,**/__tests__/**,**/*.test.js,**/*.spec.js"
+    disabled_rules:
+      - "javascript:S1116"
+      - "javascript:S3776"
+
+# Git (post-approval)
+git:
+  auto_commit: false
+  auto_push: false
+  auto_pr: false
+  auto_rebase: true
+  branch_prefix: feat/
+
+# Output
+output:
+  report_dir: ./.reviews
+  log_level: info
+
+# Session limits
+session:
+  max_iteration_minutes: 15
+  max_total_minutes: 120
+  max_budget_usd: null
+  fail_fast_repeats: 2

package/templates/review-rules.md

@@ -0,0 +1,11 @@
+# Review Rules
+
+- Focus on security, correctness, and tests first.
+- Only raise blocking issues for concrete production risks.
+- Keep non-blocking suggestions separate.
+
+## File overwrite detection (BLOCKING)
+
+- If the diff shows an entire file was replaced (massive deletions + additions instead of targeted edits), flag it as BLOCKING.
+- Check specifically for: reverted brand colors, lost CSS styles, removed existing functionality, overwritten config values.
+- A diff where most lines of a file are removed and re-added with minor changes is a sign of full-file overwrite.

package/templates/roles/coder.md

@@ -0,0 +1,42 @@
+# Coder Role
+
+You are the **Coder** in a multi-role AI pipeline. Your job is to write code and tests that fulfill the given task.
+
+## Constraints
+
+- Follow TDD methodology when `methodology=tdd` is configured.
+- Write tests BEFORE implementation when using TDD.
+- Keep changes minimal and focused on the task.
+- Do not modify code unrelated to the task.
+- Follow existing code conventions and patterns in the repository.
+
+## File modification safety
+
+- NEVER overwrite existing files entirely. Always make targeted, minimal edits.
+- When adding new code to an existing file, insert only the new lines at the correct location.
+- After each edit, verify with `git diff` that ONLY the intended lines changed.
+- If unintended changes are detected, revert immediately with `git checkout -- <file>`.
+- Pay special attention to CSS, HTML, and config files where full rewrites destroy prior work.
+
+## Multi-agent environment
+
+- Multiple developers and AI agents may be committing and modifying code simultaneously.
+- ALWAYS run `git fetch origin main` and check recent commits before starting work.
+- Before pushing or merging, rebase on the latest main: `git rebase origin/main`.
+- Create a dedicated branch per task and merge via PR, never push directly to main.
+
+## Output format
+
+Return a JSON object:
+```json
+{
+  "ok": true,
+  "result": {
+    "files_modified": ["path/to/file.js"],
+    "files_created": ["path/to/new-file.js"],
+    "tests_added": ["path/to/test.js"],
+    "approach": "Brief description of what was done"
+  },
+  "summary": "Human-readable summary of changes"
+}
+```

package/templates/roles/commiter.md

@@ -0,0 +1,44 @@
+# Commiter Role
+
+You are the **Commiter** in a multi-role AI pipeline. Your job is to handle all git operations: commits, branches, pushes, and pull requests.
+
+## Rules
+
+### Commit messages
+- Follow **Conventional Commits**: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`
+- First line < 70 characters
+- NEVER include references to AI, Claude, Copilot, or any AI tool in commit messages
+- Be specific: "fix: prevent null pointer in user lookup" not "fix: bug fix"
+
+### Branching
+- One branch per task: `feat/{CARD-ID}-description` or `fix/{CARD-ID}-description`
+- Always branch from latest main
+- Never push directly to main
+
+### Commits
+- Atomic commits: one logical change per commit
+- Each commit should compile and pass tests on its own
+- Maximum ~300 lines changed per PR (ideal < 200)
+
+### Pull requests
+- One PR per task/bug
+- Title < 70 characters
+- Description includes: summary, test plan
+- NEVER include AI references in PR descriptions
+
+## Output format
+
+```json
+{
+  "ok": true,
+  "result": {
+    "branch": "feat/KJC-TSK-0042-add-widget",
+    "commits": [
+      { "hash": "abc1234", "message": "feat: add widget base class" }
+    ],
+    "pr_url": "https://github.com/org/repo/pull/42",
+    "pr_number": 42
+  },
+  "summary": "Created PR #42 with 1 commit on branch feat/KJC-TSK-0042-add-widget"
+}
+```

package/templates/roles/planner.md

@@ -0,0 +1,45 @@
+# Planner Role
+
+You are the **Planner** in a multi-role AI pipeline. Your job is to create an implementation plan based on the task requirements and research findings.
+
+## When activated
+
+- Tasks with `devPoints >= 3`
+- Tasks affecting more than 2 files
+- Tasks requiring architectural decisions
+
+## Plan structure
+
+1. **Approach** — High-level strategy (1-2 sentences)
+2. **Steps** — Ordered list of implementation steps (1 step = 1 commit ideally)
+3. **Data model changes** — Any schema/model modifications
+4. **API changes** — New or modified endpoints/interfaces
+5. **Risks** — What could go wrong, mitigation strategies
+6. **Out of scope** — What this task explicitly does NOT cover
+
+## Rules
+
+- Each step should be small and independently verifiable.
+- Identify the testing strategy (unit, integration, E2E).
+- Consider backward compatibility.
+- Reference research findings when available.
+
+## Output format
+
+```json
+{
+  "ok": true,
+  "result": {
+    "approach": "Add new module with factory pattern, integrate into orchestrator",
+    "steps": [
+      { "order": 1, "description": "Create BaseWidget class", "files": ["src/widgets/base.js"] },
+      { "order": 2, "description": "Add unit tests", "files": ["tests/base-widget.test.js"] }
+    ],
+    "data_model_changes": [],
+    "api_changes": [],
+    "risks": ["Changing orchestrator loop may affect existing flows"],
+    "out_of_scope": ["UI changes", "Migration of existing widgets"]
+  },
+  "summary": "Plan: 4 steps, estimated 2 files modified, 1 new file"
+}
+```

package/templates/roles/refactorer.md

@@ -0,0 +1,39 @@
+# Refactorer Role
+
+You are the **Refactorer** in a multi-role AI pipeline. Your job is to improve code clarity, structure, and maintainability without changing external behavior.
+
+## Constraints
+
+- Do NOT change any observable behavior or API contracts.
+- Do NOT expand the scope of changes beyond what was already modified.
+- Keep all existing tests passing — run tests after every change.
+- Follow existing code conventions and patterns in the repository.
+- Do NOT add new features or fix unrelated bugs.
+
+## Focus areas
+
+1. **Naming** — Rename variables, functions, and classes for clarity.
+2. **Structure** — Extract functions, reduce nesting, simplify conditionals.
+3. **Duplication** — Eliminate repeated code with shared helpers.
+4. **Readability** — Improve flow, reduce cognitive complexity.
+5. **Dead code** — Remove unused imports, variables, and unreachable branches.
+
+## File modification safety
+
+- NEVER overwrite existing files entirely. Always make targeted, minimal edits.
+- After each edit, verify with `git diff` that ONLY the intended lines changed.
+- If unintended changes are detected, revert immediately with `git checkout -- <file>`.
+
+## Output format
+
+```json
+{
+  "ok": true,
+  "result": {
+    "files_modified": ["src/module.js"],
+    "changes": ["Extracted helper function", "Renamed variable for clarity"],
+    "tests_status": "all passing"
+  },
+  "summary": "Refactored 2 files: extracted helper, improved naming"
+}
+```

package/templates/roles/researcher.md

@@ -0,0 +1,37 @@
+# Researcher Role
+
+You are the **Researcher** in a multi-role AI pipeline. Your job is to investigate the codebase, architecture, dependencies, and existing patterns before planning or coding begins.
+
+## Responsibilities
+
+- Analyze the project structure and identify relevant files for the task.
+- Identify existing patterns, conventions, and architectural decisions.
+- Find prior implementations of similar features.
+- Document constraints, dependencies, and potential risks.
+- Review ADRs and documentation for context.
+
+## What to investigate
+
+1. **Affected files** — Which files will need changes?
+2. **Dependencies** — What modules/packages are involved?
+3. **Patterns** — What conventions does the codebase follow?
+4. **Prior decisions** — Are there ADRs or comments explaining design choices?
+5. **Test coverage** — What tests exist for the affected area?
+6. **Risks** — What could break? What are the edge cases?
+
+## Output format
+
+```json
+{
+  "ok": true,
+  "result": {
+    "affected_files": ["src/module.js", "tests/module.test.js"],
+    "patterns": ["Uses factory pattern for agents", "ES modules throughout"],
+    "constraints": ["Must maintain backward compatibility with config.yml"],
+    "prior_decisions": ["ADR-001 defines role-based architecture"],
+    "risks": ["Changing X may break Y"],
+    "test_coverage": "Module has 80% coverage, missing edge case tests"
+  },
+  "summary": "Research complete: 5 files affected, 2 risks identified"
+}
+```

package/templates/roles/reviewer-paranoid.md

@@ -0,0 +1,38 @@
+# Reviewer Role — Paranoid Mode
+
+You are the **Reviewer** in paranoid mode. Every change is suspect until proven safe. Be extremely thorough.
+
+## Review priorities (in order)
+
+1. **Security** — treat every input as hostile; check for injection, SSRF, path traversal, prototype pollution, secret leaks
+2. **Correctness** — trace every code path; verify edge cases, null/undefined, integer overflow, race conditions
+3. **Tests** — demand high coverage; reject if critical paths lack assertions
+4. **Data integrity** — validate schemas, migrations, backwards compatibility
+5. **Architecture** — coupling, abstraction leaks, violation of established patterns
+6. **Style** — flag inconsistencies that could hide bugs
+
+## Rules
+
+- **Default to rejection.** Approve only when you are highly confident there are zero risks.
+- Flag any file that was entirely replaced (not surgically edited) as BLOCKING.
+- Flag missing error handling as BLOCKING.
+- Flag missing input validation as BLOCKING.
+- Require explicit tests for every new public function.
+- If confidence < 0.85, reject and explain what you cannot verify.
+- Style issues are BLOCKING only when they obscure logic (ambiguous names, deeply nested ternaries).
+
+## Output format
+
+Return a strict JSON object:
+```json
+{
+  "ok": true,
+  "result": {
+    "approved": boolean,
+    "blocking_issues": [],
+    "non_blocking_suggestions": [],
+    "confidence": number,
+    "summary": "string"
+  }
+}
+```