@karajan-family/code 4.21.0

package/src/skills/skill-loader.js

@@ -0,0 +1,219 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const SKILL_DIRS = [".agent/skills", ".claude/skills"];
+const SKILL_FILE = "SKILL.md";
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/**
+ * Extract the `type` field from SKILL.md frontmatter.
+ * Returns "technical" (default) or "domain".
+ * @param {string} content — raw SKILL.md content
+ * @returns {{type: string, body: string}}
+ */
+function parseSkillType(content) {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return { type: "technical", body: content };
+
+  const frontmatter = match[1];
+  const body = match[2];
+
+  // Simple regex extraction — avoid full YAML parser for a single field
+  const typeMatch = frontmatter.match(/^type:\s*(.+)$/m);
+  const type = typeMatch ? typeMatch[1].trim().toLowerCase() : "technical";
+
+  return { type, body };
+}
+
+/**
+ * Scans known skill directories for SKILL.md files.
+ * @param {string} projectDir — absolute path to the project root
+ * @param {{type?: string}} [options] — filter by type: "technical" (default), "domain", or undefined (all)
+ * @returns {Promise<Array<{name: string, content: string, type: string}>>}
+ */
+export async function loadAvailableSkills(projectDir, options = {}) {
+  const skills = [];
+  const filterType = options.type || null;
+
+  for (const rel of SKILL_DIRS) {
+    const dir = join(projectDir, rel);
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      continue; // directory does not exist — skip
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const skillPath = join(dir, entry.name, SKILL_FILE);
+      try {
+        const raw = await readFile(skillPath, "utf-8");
+        const { type, body } = parseSkillType(raw);
+
+        // Filter by type if specified
+        if (filterType && type !== filterType) continue;
+
+        // For backward compat: existing callers get content without frontmatter for domain skills,
+        // but full content for technical skills (they never had frontmatter before)
+        const content = type === "domain" ? body.trim() : raw;
+        skills.push({ name: entry.name, content, type });
+      } catch {
+        // no SKILL.md in this subdirectory — skip
+      }
+    }
+  }
+
+  return skills;
+}
+
+/**
+ * Builds a prompt section from loaded skills.
+ *
+ * For Anthropic (Claude Sonnet 4.5+), skills are delivered as Agent Skills
+ * natively (loaded by the runtime from SKILL.md) — duplicating their full
+ * content in the prompt wastes tokens and risks drifting from the canonical
+ * source. When `provider === "anthropic"`, this function emits a lightweight
+ * reference list; Claude will load the SKILL.md files on demand.
+ *
+ * For every other provider, the full SKILL.md body is inlined (previous
+ * behaviour preserved).
+ *
+ * When `role` is supplied, skills are filtered to those relevant to the role
+ * (e.g. a reviewer only sees `*-code-review`, `*-security-*`, and general
+ * patterns; see ROLE_SKILL_PATTERNS). Setting role to null/undefined keeps
+ * the legacy behavior of injecting every skill (useful for the coder role,
+ * which benefits from broad context).
+ *
+ * @param {Array<{name: string, content: string}>} skills
+ * @param {{ provider?: string, role?: string }} [options]
+ * @returns {string} prompt section or empty string
+ */
+export function buildSkillSection(skills, options = {}) {
+  if (!skills || skills.length === 0) return "";
+
+  const filtered = options.role ? filterSkillsForRole(skills, options.role) : skills;
+  if (filtered.length === 0) return "";
+
+  const providerSlug = normalize(options.provider);
+
+  if (providerSlug === "anthropic") {
+    return buildReferenceSection(filtered);
+  }
+
+  return buildInlineSection(filtered);
+}
+
+/**
+ * Role → substring patterns that skills must match to be included. A skill
+ * matches the role if its name contains ANY of the role's patterns OR if it
+ * appears in the role's explicit allowlist. Coder is omitted on purpose: it
+ * receives everything.
+ *
+ * The patterns target the skill NAMING convention shipped by openskills.cc
+ * where skills are typically named like `react-patterns`, `java-code-review`,
+ * `pytest-patterns`, `owasp-top-10`, etc.
+ */
+/**
+ * Role → filter config.
+ *
+ * Two modes:
+ *   - `includes` present: skill name must contain ANY include AND NOT contain
+ *     any exclude. `allow` bypasses both checks (explicit allowlist by name).
+ *   - `includes` absent (or empty) + `excludes` present: skill passes unless
+ *     its name contains an exclude pattern. This is the "accept broad, trim
+ *     obvious mismatches" mode used by architect.
+ */
+const ROLE_SKILL_PATTERNS = {
+  reviewer: {
+    includes: ["code-review", "security", "lint", "style", "antipatterns", "owasp"],
+    excludes: [],
+    allow: ["sql-analysis"],
+  },
+  architect: {
+    // Architect sees everything except test-framework patterns. Architecture
+    // decisions touch every domain, so keep the filter permissive.
+    includes: null,
+    excludes: ["pytest", "vitest", "jest", "playwright", "cypress"],
+    allow: [],
+  },
+  tester: {
+    includes: ["test", "pytest", "vitest", "jest", "playwright", "cypress"],
+    excludes: [],
+    allow: [],
+  },
+  security: {
+    includes: ["security", "owasp", "sast"],
+    excludes: [],
+    allow: [],
+  },
+  planner: {
+    // Planner gets broad stack context except test frameworks.
+    includes: null,
+    excludes: ["pytest", "vitest", "jest", "playwright", "cypress"],
+    allow: [],
+  },
+  solomon: {
+    includes: ["security", "code-review"],
+    excludes: [],
+    allow: [],
+  },
+};
+
+/**
+ * Filter skills for a given role using the ROLE_SKILL_PATTERNS map. Unknown
+ * roles get ALL skills (conservative default for the coder role and any
+ * future addition). Matching is case-insensitive substring.
+ *
+ * @param {Array<{name: string}>} skills
+ * @param {string} role
+ * @returns {Array} filtered array
+ */
+export function filterSkillsForRole(skills, role) {
+  const cfg = ROLE_SKILL_PATTERNS[role];
+  if (!cfg) return skills; // unknown role (e.g. coder) → no filter
+  const includes = Array.isArray(cfg.includes) ? cfg.includes.map((s) => s.toLowerCase()) : null;
+  const excludes = (cfg.excludes || []).map((s) => s.toLowerCase());
+  const allow = new Set((cfg.allow || []).map((s) => s.toLowerCase()));
+  return skills.filter((s) => {
+    const name = (s.name || "").toLowerCase();
+    if (allow.has(name)) return true;
+    if (excludes.some((pat) => name.includes(pat))) return false;
+    if (!includes || includes.length === 0) return true; // exclude-only mode
+    return includes.some((pat) => name.includes(pat));
+  });
+}
+
+function buildInlineSection(skills) {
+  const header = [
+    "## Domain Skills",
+    "",
+    "The following domain-specific knowledge is available for this task:"
+  ].join("\n");
+
+  const blocks = skills.map(
+    (s) => `### ${s.name}\n${s.content}`
+  );
+
+  return [header, ...blocks].join("\n\n");
+}
+
+function buildReferenceSection(skills) {
+  const names = skills.map((s) => s.name).join(", ");
+  return [
+    "## Domain Skills",
+    "",
+    `Skills available natively via your Agent Skills capability: ${names}.`,
+    "Each skill's SKILL.md is already loaded in your runtime; invoke its guidance as needed without re-reading the full content."
+  ].join("\n");
+}
+
+function normalize(value) {
+  if (!value) return null;
+  const lc = String(value).toLowerCase();
+  if (lc === "claude" || lc === "anthropic") return "anthropic";
+  if (lc === "codex" || lc === "openai") return "openai";
+  if (lc === "gemini" || lc === "google") return "google";
+  if (lc === "opencode") return "opencode";
+  return lc;
+}

package/src/skills/skills-cache.js

@@ -0,0 +1,128 @@
+/**
+ * Local cache for installed OpenSkills, backed by `~/.karajan/skills-cache/`.
+ *
+ * The cache records WHEN each skill was last installed so we can skip
+ * redundant `npx openskills install X` calls during the 7-day TTL window
+ * (each call can take 10-30s even when the skill is already present).
+ *
+ * This is intentionally simple: one directory per skill name with a
+ * `meta.json` describing the last install time. Skill content is NOT copied
+ * to the cache — OpenSkills owns the real content on disk; we only track
+ * freshness.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getKarajanHome } from "../utils/paths.js";
+
+const CACHE_DIR_NAME = "skills-cache";
+const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+export function getCacheRoot() {
+  return path.join(getKarajanHome(), CACHE_DIR_NAME);
+}
+
+function sanitize(name) {
+  // Allow safe skill name characters, replace everything else with "_".
+  return String(name || "").replaceAll(/[^A-Za-z0-9._-]/g, "_");
+}
+
+function metaPath(name) {
+  return path.join(getCacheRoot(), sanitize(name), "meta.json");
+}
+
+/**
+ * Read cached metadata for a skill. Returns null if missing or unreadable.
+ * @param {string} name
+ * @returns {Promise<{cachedAt: string, source?: string}|null>}
+ */
+export async function getCachedMeta(name) {
+  if (!name) return null;
+  try {
+    const raw = await fs.readFile(metaPath(name), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.cachedAt !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True iff the skill was cached more recently than `ttlMs` ago.
+ * @param {string} name
+ * @param {number} [ttlMs=DEFAULT_TTL_MS]
+ * @returns {Promise<boolean>}
+ */
+export async function isFresh(name, ttlMs = DEFAULT_TTL_MS) {
+  const meta = await getCachedMeta(name);
+  if (!meta) return false;
+  const cachedTime = Date.parse(meta.cachedAt);
+  if (Number.isNaN(cachedTime)) return false;
+  return Date.now() - cachedTime < ttlMs;
+}
+
+/**
+ * Record that a skill was just (re-)installed. Creates the cache subdir if
+ * needed.
+ * @param {string} name
+ * @param {{ source?: string }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function recordInstall(name, opts = {}) {
+  if (!name) return;
+  const dir = path.join(getCacheRoot(), sanitize(name));
+  await fs.mkdir(dir, { recursive: true });
+  const meta = {
+    name,
+    cachedAt: new Date().toISOString(),
+    ...(opts.source ? { source: opts.source } : {}),
+  };
+  await fs.writeFile(path.join(dir, "meta.json"), JSON.stringify(meta, null, 2), "utf8");
+}
+
+/**
+ * Remove all cached skill metadata (does not touch real installed skills,
+ * only clears the freshness tracker).
+ * @returns {Promise<{removed: number}>}
+ */
+export async function clearCache() {
+  const root = getCacheRoot();
+  let removed = 0;
+  try {
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      await fs.rm(path.join(root, entry.name), { recursive: true, force: true });
+      removed++;
+    }
+  } catch { /* cache dir does not exist — nothing to clear */ }
+  return { removed };
+}
+
+/**
+ * List cached skill names with their cachedAt timestamp, sorted oldest first.
+ * @returns {Promise<Array<{name: string, cachedAt: string, fresh: boolean}>>}
+ */
+export async function listCached(ttlMs = DEFAULT_TTL_MS) {
+  const root = getCacheRoot();
+  const out = [];
+  let entries;
+  try {
+    entries = await fs.readdir(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const meta = await getCachedMeta(entry.name);
+    if (!meta) continue;
+    const cachedTime = Date.parse(meta.cachedAt);
+    const fresh = !Number.isNaN(cachedTime) && (Date.now() - cachedTime < ttlMs);
+    out.push({ name: meta.name || entry.name, cachedAt: meta.cachedAt, fresh });
+  }
+  out.sort((a, b) => a.cachedAt.localeCompare(b.cachedAt));
+  return out;
+}
+
+export { DEFAULT_TTL_MS };

package/src/sonar/api.js

@@ -0,0 +1,128 @@
+import { runCommand } from "../utils/process.js";
+import { withRetry } from "../utils/retry.js";
+import { resolveSonarProjectKey } from "./project-key.js";
+import { resolveSonarToken } from "./config-resolver.js";
+import { filterFalsePositives } from "./issue-filter.js";
+import { recoverSonarToken } from "./token-recovery.js";
+
+class SonarApiError extends Error {
+  constructor(message, { url, httpStatus, hint } = {}) {
+    super(message);
+    this.name = "SonarApiError";
+    this.url = url;
+    this.httpStatus = httpStatus;
+    this.hint = hint;
+  }
+}
+
+function tokenFromConfig(config) {
+  return resolveSonarToken(config) || "";
+}
+
+function parseHttpResponse(stdout) {
+  const lines = stdout.split("\n");
+  const httpCode = Number.parseInt(lines.pop(), 10) || 0;
+  const body = lines.join("\n");
+  return { httpCode, body };
+}
+
+async function sonarFetchOnce(config, urlPath, { _retriedAfterRecovery = false, logger = null } = {}) {
+  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) {
+    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);
+
+  if (httpCode === 401) {
+    // KJC-BUG-0057 (v2.19.2): try to bootstrap a fresh token via the Sonar
+    // REST API and retry ONCE. If recovery still fails — or this was already
+    // the retry — surface the actionable error like before.
+    if (!_retriedAfterRecovery) {
+      const recovery = await recoverSonarToken(config, logger);
+      if (recovery.ok) {
+        return sonarFetchOnce(config, urlPath, { _retriedAfterRecovery: true, logger });
+      }
+      throw new SonarApiError(
+        `SonarQube authentication failed (HTTP 401) and auto-recovery failed: ${recovery.reason}. Regenerate the token manually with 'kj init' or save admin user/password in ~/.karajan/sonar-credentials.json.`,
+        { url, httpStatus: 401, hint: "Run 'kj init' to regenerate the SonarQube token, or save admin credentials in ~/.karajan/sonar-credentials.json so Karajan can re-bootstrap automatically." }
+      );
+    }
+    throw new SonarApiError(
+      `SonarQube authentication failed (HTTP 401) even after auto-recovery. The newly generated token is also being rejected — the Sonar instance may be in an inconsistent state.`,
+      { url, httpStatus: 401, hint: "Inspect the Sonar UI directly; consider 'kj sonar restart'." }
+    );
+  }
+
+  if (httpCode >= 400) {
+    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}`);
+
+  try {
+    const parsed = JSON.parse(body);
+    return { ok: true, status: parsed.projectStatus?.status || "ERROR", conditions: parsed.projectStatus?.conditions || [], raw: parsed };
+  } catch { /* SonarQube response is not valid JSON */
+    return { ok: false, status: "ERROR", conditions: [], raw: body };
+  }
+}
+
+export async function getOpenIssues(config, projectKey = null) {
+  const effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey });
+  const body = await sonarFetch(config, `/api/issues/search?projectKeys=${effectiveProjectKey}&statuses=OPEN`);
+
+  let parsedIssues = [];
+  let parsedRaw = body;
+  try {
+    const parsed = JSON.parse(body);
+    parsedIssues = parsed.issues || [];
+    parsedRaw = parsed;
+  } catch { /* SonarQube response is not valid JSON */ }
+
+  // KJC-TSK-0416: pre-filtro de falsos positivos antes de devolver al
+  // caller. El coder, audit y scan consumen lo que pasa el filtro;
+  // suppressed se devuelve aparte para observabilidad.
+  // v2.17.0: accepts both legacy config.sonar.false_positives (no `tool`
+  // field, implicit "sonar") and the new generalised config.audit.false_positives.
+  const sonarLegacy = (config?.sonar?.false_positives || []).map((r) => ({ tool: "sonar", ...r }));
+  const auditRules = (config?.audit?.false_positives || []).filter((r) => (r.tool || "sonar") === "sonar");
+  const taggedIssues = parsedIssues.map((i) => ({ ...i, tool: "sonar" }));
+  const { kept, suppressed } = filterFalsePositives(taggedIssues, {
+    extraRules: [...sonarLegacy, ...auditRules],
+    projectRoot: config?.projectDir,
+  });
+
+  return {
+    total: kept.length,
+    issues: kept,
+    suppressed,
+    raw: parsedRaw,
+  };
+}

package/src/sonar/cloud-scanner.js

@@ -0,0 +1,78 @@
+import { runCommand } from "../utils/process.js";
+import { resolveSonarProjectKey } from "./project-key.js";
+
+function buildCloudScannerArgs(projectKey, config) {
+  const sc = config.sonarcloud || {};
+  const scanner = sc.scanner || {};
+  const host = sc.host || "https://sonarcloud.io";
+  const organization = process.env.KJ_SONARCLOUD_ORG || sc.organization;
+
+  const args = [
+    `-Dsonar.host.url=${host}`,
+    `-Dsonar.projectKey=${projectKey}`
+  ];
+
+  // Token passed via SONAR_TOKEN env var, not CLI args (invisible in `ps aux`)
+  if (organization) args.push(`-Dsonar.organization=${organization}`);
+  if (scanner.sources) args.push(`-Dsonar.sources=${scanner.sources}`);
+  if (scanner.exclusions) args.push(`-Dsonar.exclusions=${scanner.exclusions}`);
+  if (scanner.test_inclusions) args.push(`-Dsonar.test.inclusions=${scanner.test_inclusions}`);
+
+  return args;
+}
+
+export async function runSonarCloudScan(config, projectKey = null) {
+  const sc = config.sonarcloud || {};
+  const token = process.env.KJ_SONARCLOUD_TOKEN || sc.token;
+  const organization = sc.organization || process.env.KJ_SONARCLOUD_ORG;
+
+  if (!token) {
+    return {
+      ok: false,
+      projectKey: null,
+      stdout: "",
+      stderr: "SonarCloud token not configured. Set sonarcloud.token in kj.config.yml or KJ_SONARCLOUD_TOKEN env var.",
+      exitCode: 1
+    };
+  }
+
+  if (!organization) {
+    return {
+      ok: false,
+      projectKey: null,
+      stdout: "",
+      stderr: "SonarCloud organization not configured. Set sonarcloud.organization in kj.config.yml or KJ_SONARCLOUD_ORG env var.",
+      exitCode: 1
+    };
+  }
+
+  let effectiveProjectKey;
+  try {
+    effectiveProjectKey = projectKey || sc.project_key || await resolveSonarProjectKey(config, { projectKey });
+  } catch (error) {
+    return {
+      ok: false,
+      projectKey: null,
+      stdout: "",
+      stderr: error?.message || String(error),
+      exitCode: 1
+    };
+  }
+
+  const scannerTimeout = 15 * 60 * 1000;
+  const args = buildCloudScannerArgs(effectiveProjectKey, config);
+
+  // Pass token via process env, not CLI args — invisible in `ps aux`
+  const env = { ...process.env };
+  if (token) env.SONAR_TOKEN = token;
+
+  const result = await runCommand("npx", ["@sonar/scan", ...args], { timeout: scannerTimeout, env });
+
+  return {
+    ok: result.exitCode === 0,
+    projectKey: effectiveProjectKey,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode: result.exitCode
+  };
+}

package/src/sonar/config-resolver.js

@@ -0,0 +1,88 @@
+/**
+ * Centralized SonarQube configuration resolution.
+ *
+ * Single source of truth for host URL, token, and admin credentials.
+ * Consumers: scanner.js, preflight-checks.js, api.js.
+ */
+
+import { loadSonarCredentials } from "./credentials.js";
+
+const DEFAULT_HOST = "http://localhost:9000";
+
+/**
+ * Normalize SonarQube host URL for API calls (replace Docker-internal hostname).
+ * @param {string|undefined} rawHost - Raw host from config or env
+ * @returns {string} Normalized host URL without trailing slash
+ */
+export function resolveSonarHost(rawHost) {
+  const host = String(rawHost || DEFAULT_HOST)
+    .replaceAll(/host\.docker\.internal/g, "localhost")
+    .replace(/\/+$/, "");
+  return host;
+}
+
+/**
+ * Resolve SonarQube auth token from (in priority order):
+ *   1. KJ_SONAR_TOKEN env var
+ *   2. config.sonarqube.token
+ *   3. SONAR_TOKEN env var
+ *
+ * For async resolution (including credentials file), use resolveSonarTokenAsync.
+ *
+ * @param {object} [config={}] - Karajan config object
+ * @returns {string|null} Token string or null if none found
+ */
+export function resolveSonarToken(config = {}) {
+  const token =
+    process.env.KJ_SONAR_TOKEN ||
+    config.sonarqube?.token ||
+    process.env.SONAR_TOKEN ||
+    null;
+  return token || null;
+}
+
+/**
+ * Async version of resolveSonarToken that also checks the credentials file
+ * for previously generated tokens.
+ *
+ * @param {object} [config={}] - Karajan config object
+ * @returns {Promise<string|null>} Token string or null if none found
+ */
+export async function resolveSonarTokenAsync(config = {}) {
+  const syncToken = resolveSonarToken(config);
+  if (syncToken) return syncToken;
+
+  // Check credentials file for persisted token
+  const fileCreds = (await loadSonarCredentials()) || {};
+  return fileCreds.token || null;
+}
+
+/**
+ * Resolve SonarQube admin credentials from (in priority order):
+ *   1. Env vars: KJ_SONAR_ADMIN_USER / KJ_SONAR_ADMIN_PASSWORD
+ *   2. Config: sonarqube.admin_user / sonarqube.admin_password
+ *   3. Credentials file: ~/.karajan/sonar-credentials.json
+ *
+ * Returns all candidate passwords (de-duped) so callers can try each.
+ *
+ * @param {object} [config={}] - Karajan config object
+ * @returns {Promise<{ user: string|null, passwords: string[] }>}
+ */
+export async function resolveSonarCredentials(config = {}) {
+  const fileCreds = (await loadSonarCredentials()) || {};
+
+  const user =
+    process.env.KJ_SONAR_ADMIN_USER ||
+    config.sonarqube?.admin_user ||
+    fileCreds.user ||
+    "admin"; // Default for fresh SonarQube installs
+
+  const candidates = [
+    process.env.KJ_SONAR_ADMIN_PASSWORD,
+    config.sonarqube?.admin_password,
+    fileCreds.password,
+    "admin", // Default password for fresh SonarQube installs (zero-config)
+  ].filter(Boolean);
+
+  return { user, passwords: [...new Set(candidates)] };
+}