karajan-code 2.4.1 → 2.6.0

package/src/skills/skill-detector.js

@@ -7,6 +7,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { loadAvailableSkills } from "./skill-loader.js";
 import { isOpenSkillsAvailable, installSkill, removeSkill } from "./openskills-client.js";
+import { isFresh as isCacheFresh, recordInstall as recordSkillInstall } from "./skills-cache.js";
 
 /**
  * Known frameworks detectable from package.json dependencies.
@@ -23,6 +24,39 @@ const PKG_JSON_FRAMEWORKS = {
   express: "express",
   fastify: "fastify",
   "@nestjs/core": "nestjs",
+  // DB / ORM
+  prisma: "prisma",
+  "@prisma/client": "prisma",
+  knex: "sql-analysis",
+  sequelize: "sql-analysis",
+  typeorm: "sql-analysis",
+  mongoose: "mongodb",
+  "better-sqlite3": "sql-analysis",
+  // Testing
+  vitest: "vitest-patterns",
+  jest: "jest-patterns",
+  "@playwright/test": "playwright-patterns",
+  cypress: "cypress-patterns",
+};
+
+/**
+ * Python dependency names (from requirements.txt or pyproject.toml) mapping
+ * to their canonical skill.
+ */
+const PYTHON_DEPS = {
+  pandas: "python-data",
+  numpy: "python-data",
+  scipy: "python-data",
+  "scikit-learn": "python-ml",
+  sklearn: "python-ml",
+  tensorflow: "python-ml",
+  torch: "python-ml",
+  pytorch: "python-ml",
+  pytest: "pytest-patterns",
+  django: "python-django",
+  flask: "python-flask",
+  fastapi: "python-fastapi",
+  sqlalchemy: "sql-analysis",
 };
 
 /**
@@ -36,14 +70,44 @@ const LANGUAGE_FILE_MARKERS = [
   { file: "go.mod", skill: "go" },
   { file: "Cargo.toml", skill: "rust" },
   { file: "pyproject.toml", skill: "python" },
+  { file: "requirements.txt", skill: "python" },
   { file: "setup.py", skill: "python" },
   { file: "Gemfile", skill: "ruby" },
   { file: "pubspec.yaml", skill: "flutter" },
   { file: "Package.swift", skill: "swift" },
   { file: "phpunit.xml", skill: "php" },
   { file: "composer.json", skill: "php" },
+  { file: "mix.exs", skill: "elixir" },
+  { file: "rebar.config", skill: "erlang" },
+];
+
+/**
+ * File EXTENSIONS whose presence anywhere under projectDir adds a skill.
+ * Uses a shallow-recursive glob with a cutoff to avoid walking node_modules.
+ */
+const EXTENSION_MARKERS = [
+  { ext: ".csproj", skill: "dotnet" },
+  { ext: ".sln", skill: "dotnet" },
+  { ext: ".ipynb", skill: "python-data" },
+  { ext: ".prisma", skill: "prisma" },
+];
+
+/**
+ * Files detected as "SQL / database schema" when they exist at repo root.
+ * Used in addition to EXTENSION_MARKERS for *.sql anywhere in the repo.
+ */
+const SQL_MARKER_FILES = [
+  "schema.sql",
+  "schema.prisma",
+  "migrations",
+  "db/migrate",
 ];
 
+const DIRECTORIES_TO_SKIP = new Set([
+  "node_modules", ".git", ".kj", ".karajan", "dist", "build", ".next", "out",
+  "target", ".venv", "venv", "__pycache__", ".vitest-cache", "coverage",
+]);
+
 /**
  * Patterns to detect framework/skill mentions in the task text.
  * Each entry: regex pattern (case-insensitive) -> skill name.
@@ -91,14 +155,21 @@ const TASK_TEXT_PATTERNS = [
 
 /**
  * Analyze the task and project to determine what skills might be needed.
+ *
  * @param {string} task - The task description text.
  * @param {string} projectDir - Absolute path to project root.
+ * @param {{ includeExtensions?: boolean, maxDepth?: number }} [options]
+ *   - includeExtensions: scan for file extensions (.csproj, .ipynb, .sql...)
+ *     that signal a stack. Default true. Disable to avoid the shallow walk
+ *     in very large repos or in tests.
+ *   - maxDepth: bound the walk (default 3 directories deep).
  * @returns {Promise<string[]>} Array of unique skill names to search for.
  */
-export async function detectNeededSkills(task, projectDir) {
+export async function detectNeededSkills(task, projectDir, options = {}) {
+  const { includeExtensions = true, maxDepth = 3 } = options;
   const needed = new Set();
 
-  // 1. Scan package.json for known frameworks
+  // 1. Scan package.json for known frameworks and JS-ecosystem deps
   if (projectDir) {
     try {
       const pkgRaw = await fs.readFile(path.join(projectDir, "package.json"), "utf8");
@@ -111,16 +182,32 @@ export async function detectNeededSkills(task, projectDir) {
       }
     } catch { /* no package.json or parse error — skip */ }
 
-    // 2. Check for language markers
+    // 2. Language marker files at repo root
     for (const marker of LANGUAGE_FILE_MARKERS) {
       try {
         await fs.access(path.join(projectDir, marker.file));
         needed.add(marker.skill);
       } catch { /* file not found — skip */ }
     }
+
+    // 3. Python deps from requirements.txt / pyproject.toml
+    await collectPythonDeps(projectDir, needed);
+
+    // 4. File extension markers (.csproj, .ipynb, .prisma, *.sql)
+    if (includeExtensions) {
+      await collectExtensionMarkers(projectDir, maxDepth, needed);
+    }
+
+    // 5. SQL / DB schema markers at well-known paths
+    for (const candidate of SQL_MARKER_FILES) {
+      try {
+        await fs.access(path.join(projectDir, candidate));
+        needed.add("sql-analysis");
+      } catch { /* skip */ }
+    }
   }
 
-  // 3. Check task text for framework mentions
+  // 6. Task text patterns
   if (task) {
     for (const { pattern, skill } of TASK_TEXT_PATTERNS) {
       if (pattern.test(task)) {
@@ -132,14 +219,91 @@ export async function detectNeededSkills(task, projectDir) {
   return Array.from(needed);
 }
 
+async function collectPythonDeps(projectDir, needed) {
+  // requirements.txt — each non-comment line is "name==ver" or "name>=ver"
+  try {
+    const raw = await fs.readFile(path.join(projectDir, "requirements.txt"), "utf8");
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim().split("#")[0].trim();
+      if (!trimmed) continue;
+      const name = trimmed.split(/[<>=!~\[\s]/)[0].toLowerCase();
+      const skill = PYTHON_DEPS[name];
+      if (skill) needed.add(skill);
+    }
+  } catch { /* no requirements.txt */ }
+
+  // pyproject.toml — simple heuristic scan for dependency names. A full TOML
+  // parse would need a dep; we just look for quoted names, which is fine.
+  try {
+    const raw = await fs.readFile(path.join(projectDir, "pyproject.toml"), "utf8");
+    const lower = raw.toLowerCase();
+    for (const [name, skill] of Object.entries(PYTHON_DEPS)) {
+      if (lower.includes(`"${name}"`) || lower.includes(`'${name}'`)) {
+        needed.add(skill);
+      }
+    }
+  } catch { /* no pyproject.toml */ }
+}
+
+async function collectExtensionMarkers(projectDir, maxDepth, needed) {
+  // Build a lookup by extension for fast decisions.
+  const byExt = new Map(EXTENSION_MARKERS.map((m) => [m.ext, m.skill]));
+  const extensions = new Set(byExt.keys());
+  extensions.add(".sql");
+  let sqlFound = false;
+
+  async function walk(dir, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (DIRECTORIES_TO_SKIP.has(entry.name)) continue;
+        if (entry.name.startsWith(".")) continue;
+        await walk(path.join(dir, entry.name), depth + 1);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const ext = path.extname(entry.name).toLowerCase();
+      if (!extensions.has(ext)) continue;
+      if (ext === ".sql") {
+        sqlFound = true;
+        continue;
+      }
+      const skill = byExt.get(ext);
+      if (skill) needed.add(skill);
+    }
+  }
+
+  await walk(projectDir, 0);
+  if (sqlFound) needed.add("sql-analysis");
+}
+
 /**
  * Auto-install needed skills that are not yet installed.
+ *
+ * When the `openskills` CLI is not available, this function degrades
+ * gracefully: it returns `osAvailable: false` and `wouldHaveUsed` with the
+ * list of skills that would have been installed if the CLI had been present.
+ * Callers (e.g. the orchestrator) can surface this info in the session
+ * report without blocking execution.
+ *
  * @param {string[]} neededSkills - Skill names to ensure are installed.
  * @param {string} projectDir - Absolute path to project root.
- * @returns {Promise<{installed: string[], failed: string[], alreadyInstalled: string[]}>}
+ * @returns {Promise<{
+ *   installed: string[],
+ *   failed: string[],
+ *   alreadyInstalled: string[],
+ *   wouldHaveUsed: string[],
+ *   osAvailable: boolean
+ * }>}
  */
 export async function autoInstallSkills(neededSkills, projectDir) {
-  const result = { installed: [], failed: [], alreadyInstalled: [] };
+  const result = { installed: [], failed: [], alreadyInstalled: [], wouldHaveUsed: [], osAvailable: true };
 
   if (!neededSkills || neededSkills.length === 0) {
     return result;
@@ -152,7 +316,10 @@ export async function autoInstallSkills(neededSkills, projectDir) {
   // Check if OpenSkills is available
   const osAvailable = await isOpenSkillsAvailable();
   if (!osAvailable) {
-    // All skills count as "failed" silently — caller should check osAvailable separately
+    result.osAvailable = false;
+    // Report what we would have installed so the session report can surface
+    // the recommendation — "install openskills globally to enable: X, Y, Z".
+    result.wouldHaveUsed = neededSkills.filter((s) => !existingNames.has(s.toLowerCase()));
     return result;
   }
 
@@ -162,10 +329,21 @@ export async function autoInstallSkills(neededSkills, projectDir) {
       continue;
     }
 
+    // Cache short-circuit: if we installed this skill in the last 7 days,
+    // assume it's still good and skip the `npx openskills install` call
+    // (which can take 10-30s). Running sessions can opt out by clearing
+    // the cache with `kj skills clear-cache`.
+    if (await isCacheFresh(skillName)) {
+      result.alreadyInstalled.push(skillName);
+      continue;
+    }
+
     try {
       const installResult = await installSkill(skillName, { projectDir });
       if (installResult.ok) {
-        result.installed.push(installResult.name || skillName);
+        const installedName = installResult.name || skillName;
+        result.installed.push(installedName);
+        await recordSkillInstall(installedName, { source: skillName }).catch(() => {});
       } else {
         result.failed.push(skillName);
       }

package/src/skills/skill-loader.js

@@ -69,12 +69,122 @@ export async function loadAvailableSkills(projectDir, options = {}) {
 
 /**
  * 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) {
+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",
     "",
@@ -87,3 +197,23 @@ export function buildSkillSection(skills) {
 
   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 || "").replace(/[^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/types/agent.js

@@ -0,0 +1,55 @@
+/**
+ * Agent result / response typedefs. Every provider agent (claude, codex,
+ * gemini, opencode, aider) returns a shape that's a superset of AgentResult.
+ *
+ * AgentResponse<T> is the generic wrapper used when a caller has parsed
+ * the raw output into a structured payload of type T.
+ */
+
+/**
+ * Raw agent result as returned by agent.runTask() / agent.reviewTask().
+ *
+ * @typedef {Object} AgentResult
+ * @property {boolean} ok                       - whether the call succeeded
+ * @property {string} [output]                  - raw stdout / response text
+ * @property {string} [summary]                 - short human summary
+ * @property {Object} [result]                  - structured result (stage-specific)
+ * @property {string} [error]
+ * @property {string} [stderr]
+ * @property {string} [stdout]
+ * @property {number} [exitCode]
+ * @property {AgentUsage} [usage]
+ * @property {string} [provider]
+ * @property {string} [model]
+ */
+
+/**
+ * Token/cost reporting shape. Fields optional because not all providers
+ * report all metrics.
+ *
+ * @typedef {Object} AgentUsage
+ * @property {number} [input_tokens]
+ * @property {number} [output_tokens]
+ * @property {number} [cached_tokens]
+ * @property {number} [total_tokens]
+ * @property {number} [cost_usd]
+ */
+
+/**
+ * Generic agent response — AgentResult whose `result` field is typed.
+ *
+ * Example:
+ *   /** @type {import("../types/agent.js").AgentResponse<import("./review-result.js").ReviewResult>} *\/
+ *
+ * @template T
+ * @typedef {Object} AgentResponse
+ * @property {boolean} ok
+ * @property {T} [result]
+ * @property {string} [output]
+ * @property {string} [summary]
+ * @property {string} [error]
+ * @property {AgentUsage} [usage]
+ * @property {string} [provider]
+ */
+
+export {};