karajan-code 4.56.0 → 4.57.0

package/package.json

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

package/scripts/osv-gate.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * osv-gate (KJC-TSK-1097): CI fails on any advisory osv-scanner scores 9 or more
+ * (critical), naming the lockfile, package, version and advisory. Output it cannot
+ * read fails too: a scanner that broke is not a clean scan.
+ *
+ * Usage: osv-scanner --format=json -r . > osv.json; node scripts/osv-gate.mjs osv.json
+ */
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseOsvOutput } from "../src/audit/osv-findings.js";
+
+const CRITICAL = 9;
+
+/** One line per critical package and advisory, paths relative to the repo root. */
+export function criticalAdvisories(raw, root) {
+  const lines = parseOsvOutput(raw).vulnerabilities
+    .filter((v) => v.score !== null && v.score >= CRITICAL)
+    .map((v) => `${relative(root, v.source)}: ${v.package}@${v.version} ${v.id} (${v.score})`);
+  return [...new Set(lines)];
+}
+
+/** The gate's verdict for the scanner's raw output. */
+export function gateReport(text, root) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    raw = null;
+  }
+  if (!Array.isArray(raw?.results)) return { ok: false, message: "osv-gate: could not read the osv-scanner output (no results list)" };
+  const found = criticalAdvisories(raw, root);
+  if (found.length === 0) return { ok: true, message: "osv-gate: no critical advisories" };
+  const details = found.map((line) => "- " + line).join("\n");
+  return { ok: false, message: `osv-gate: ${found.length} critical advisory(ies):\n${details}` };
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const file = process.argv[2];
+  if (!file) throw new Error("osv-gate: pass the osv-scanner JSON file");
+  const { ok, message } = gateReport(readFileSync(file, "utf8"), process.cwd());
+  console.log(message);
+  process.exitCode = ok ? 0 : 1;
+}

package/src/audit/osv-findings.js

@@ -103,6 +103,7 @@ export function parseOsvOutput(raw) {
           id: vuln.id || vuln.aliases?.[0] || "UNKNOWN",
           aliases: vuln.aliases || [],
           severity: extractSeverity(vuln, groups),
+          score: groupScore(vuln, groups),
           summary: vuln.summary || vuln.details?.split("\n")[0] || "",
           publishedAt: vuln.published || null, // the ADVISORY's date — the Steward ages by it (KJC-TSK-0789 AC6)
           package: name,
@@ -141,6 +142,13 @@ function extractSeverity(vuln, groups) {
   return "UNKNOWN";
 }
 
+/** KJC-TSK-1097: the numeric CVSS score of the vuln's group (9 or more is critical), or null. */
+function groupScore(vuln, groups) {
+  const group = groups.find((g) => g.ids?.includes(vuln.id) && g.max_severity);
+  const score = group ? Number.parseFloat(group.max_severity) : Number.NaN;
+  return Number.isNaN(score) ? null : score;
+}
+
 function extractFixedVersion(vuln) {
   const ranges = vuln.affected?.[0]?.ranges || [];
   for (const range of ranges) {

package/src/checks/release-check.js

@@ -70,7 +70,13 @@ async function policyRangeCheck(projectDir) {
     const skipped = prScoped.size > 0 ? `; ${prScoped.size} diff-threshold invariant(s) skipped (PR-scoped)` : "";
     if (hard.length > 0) {
       const list = hard.map((v) => `[${v.rule_id}]${v.file ? ` ${v.file}` : ""}`).join(", ");
-      return { name: "policy", ok: false, detail: `${hard.length} deny violation(s) in ${scope} against the current policy: ${list}` };
+      // KJC-BUG-0374: supervisor files the seal does not back (an older kj's seal, or an
+      // unsealed edit) are fixed by regenerating and resealing, never by a tag or a grant.
+      const why = sup.note ? ` (${sup.note})` : "";
+      const reseal = hard.some((v) => v.rule_id === "defaults.supervisor.write")
+        ? ` — the supervisor seal does not back these files${why}: run kj harden, then ask your user for kj harden --commit`
+        : "";
+      return { name: "policy", ok: false, detail: `${hard.length} deny violation(s) in ${scope} against the current policy: ${list}${reseal}` };
     }
     return { name: "policy", ok: true, detail: `${scope} clean against the current policy (${violations.length} warning(s))${skipped}` };
   } catch (err) {

package/src/cli/register-meta.js

@@ -1048,6 +1048,7 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--no-config", "Skip lint/format/commit config files (hooks only)")
     .option("--no-ci", "Skip CI quality workflows")
     .option("--no-guidelines", "Skip AI-agent guideline files (AGENTS.md/CLAUDE.md)")
+    .option("--no-sandbox", "Leave the host Bash sandbox alone (by default it is turned on where it can start)")
     .option("--mutation", "Also seed an opt-in nightly/manual mutation CI job (never a PR gate)")
     .option("--only <dirs...>", "Harden only these language roots (e.g. frontend backend)")
     .option("--exclude <globs...>", "Skip language roots matching these globs (e.g. wrappers)")
@@ -1065,6 +1066,7 @@ export function registerMeta(program, { pkgVersion }) {
           config: flags.config !== false,
           ci: flags.ci !== false,
           guidelines: flags.guidelines !== false,
+          sandbox: flags.sandbox !== false,
           mutation: Boolean(flags.mutation),
           only: flags.only ?? [],
           exclude: flags.exclude ?? [],

package/src/commands/harden.js

@@ -23,6 +23,7 @@ import { commandsForLanguage } from "../harden/hook-commands.js";
 import { installHooks } from "../harden/harden-engine.js";
 import { installHarnessHooks } from "../harden/harness-hooks.js";
 import { installSentinelHooks } from "../harden/sentinel-hooks.js";
+import { installSandbox } from "../harden/sandbox.js";
 import { detectStackRoots } from "../harden/stack-roots.js";
 import { installWorkflows } from "../harden/workflow-engine.js";
 import { adviseBranchProtection } from "../harden/branch-protection.js";
@@ -91,6 +92,7 @@ export async function hardenCommand({
   only = [],
   exclude = [],
   commitSupervisor = false,
+  sandbox = true,
   kjVersion = null,
   // KJC-BUG-0289: the contract files already dirty before anything was generated
   // (kj init captures them before writing its own). What is dirty NOW is the person's.
@@ -160,6 +162,8 @@ export async function hardenCommand({
       // sin sello, que es como una sesión se dejaba sin herramientas.
       const sh = installSentinelHooks({ projectDir, logger, human: commitSupervisor });
       result.sentinelHooks = sh.wired ? "wired" : "script-only";
+      // KJC-TSK-1092: the host sandbox, on by default wherever it can start here.
+      if (sandbox) result.sandbox = installSandbox({ projectDir, logger }).state;
     }
   } catch (err) {
     if (json) logger.info?.(JSON.stringify({ ok: false, error: err.message }));

package/src/commands/worktree.js

@@ -34,7 +34,8 @@ export async function worktreeCommand({ config = null, action, args = [], flags
       throw new Error(`lane "${slug}" already exists — cd ${wtPath}, or finish it with: kj worktree done ${slug}`);
     }
     const branch = `feat/${slug}`;
-    await git(["worktree", "add", "-b", branch, wtPath]);
+    // KJC-TSK-1093: --no-track, so no upstream lands in .git/config (read-only in the host sandbox).
+    await git(["worktree", "add", "--no-track", "-b", branch, wtPath]);
     const boot = await bootstrapWorktree({ worktreePath: wtPath, setupCommand: config?.session?.worktree_setup || null });
     console.log(`✓ lane ready: ${branch}`);
     console.log(`  cd ${wtPath}`);

package/src/git/hu-automation.js

@@ -150,9 +150,9 @@ export async function prepareHuBranch({ story, huBranches, config, logger, cardI
  */
 export function pushRemedy(message, branch) {
   if (/workflow/i.test(message) && /scope/i.test(message)) {
-    return `the token lacks the workflow scope: run gh auth refresh -h github.com -s workflow, then git push -u origin ${branch}`;
+    return `the token lacks the workflow scope: run gh auth refresh -h github.com -s workflow, then git push origin ${branch}`;
   }
-  return `push the branch yourself: git push -u origin ${branch}`;
+  return `push the branch yourself: git push origin ${branch}`;
 }
 
 /** The warnings a run reports when the push or the PR of any HU failed. */

package/src/harden/config-engine.js

@@ -48,10 +48,13 @@ export function configLeftAlone(cfg, altDirs) {
   const variant = findEquivalentIn(altDirs, id);
   if (variant) return { action: "covered", by: variant };
   // KJC-BUG-0137: no tool ⇒ no config — report the actionable gap instead.
-  if (cfg.requires && !hasTool(altDirs, cfg.requires)) {
-    return { action: "omitted", note: `${cfg.requires} is not installed — npm i -D ${cfg.requires}, then re-run kj harden` };
-  }
-  return null;
+  return missingToolGap(cfg, altDirs);
+}
+
+/** KJC-BUG-0376: the first tool the config needs and the project lacks, as a report entry. */
+function missingToolGap(cfg, dirs) {
+  const missing = [cfg.requires ?? []].flat().find((tool) => !hasTool(dirs, tool));
+  return missing ? { action: "omitted", note: `${missing} is not installed — npm i -D ${missing}, then re-run kj harden` } : null;
 }
 
 function writeFile(target, content) {
@@ -89,6 +92,12 @@ function seedInto(targetDir, configs, dryRun, prefix, results, altDirs = [target
       results.push({ file, action: "skipped" });
       continue;
     }
+    // KJC-BUG-0376: never rewrite a managed block into one the project cannot load.
+    const gap = exists ? missingToolGap(cfg, altDirs) : null;
+    if (gap) {
+      results.push({ file, ...gap });
+      continue;
+    }
     const { content, action } = upsertManagedBlock({
       source,
       blockId: cfg.blockId,

package/src/harden/config-templates.js

@@ -72,6 +72,19 @@ export const ESLINT_BODY = [
   "];",
 ].join("\n");
 
+// KJC-BUG-0376: a TypeScript root gets the same rules with the TypeScript parser;
+// without it ESLint 9 fails every .ts/.tsx file with "Parsing error".
+const JS_LANGUAGE_OPTIONS = 'languageOptions: { ecmaVersion: 2025, sourceType: "module" }';
+if (!ESLINT_BODY.includes(JS_LANGUAGE_OPTIONS)) throw new Error("config-templates: ESLINT_BODY lost its languageOptions line");
+export const ESLINT_TS_BODY = [
+  'import tsParser from "@typescript-eslint/parser";',
+  "",
+  ESLINT_BODY.replace(
+    JS_LANGUAGE_OPTIONS,
+    'languageOptions: { parser: tsParser, ecmaVersion: 2025, sourceType: "module", parserOptions: { ecmaFeatures: { jsx: true } } }',
+  ),
+].join("\n");
+
 // Ruff covers lint + format for Python; `UP` (pyupgrade) is the analogue of
 // the ES2025 deprecated-API ban — it rewrites legacy idioms to modern Python.
 export const RUFF_BODY = [
@@ -114,6 +127,9 @@ export const JS_CONFIGS = [
   { file: "eslint.config.js", blockId: "eslint", style: "slash", body: ESLINT_BODY, requires: "eslint" },
   { file: ".prettierrc.json", json: true, body: PRETTIER_BODY, requires: "prettier" },
 ];
+export const TS_CONFIGS = JS_CONFIGS.map((cfg) => (cfg.file === "eslint.config.js"
+  ? { ...cfg, body: ESLINT_TS_BODY, requires: ["eslint", "@typescript-eslint/parser"] }
+  : cfg));
 export const PY_CONFIGS = [{ file: "ruff.toml", blockId: "ruff", style: "hash", body: RUFF_BODY }];
 export const GO_CONFIGS = [{ file: ".golangci.yml", blockId: "golangci", style: "hash", body: GOLANGCI_BODY }];
 
@@ -135,7 +151,7 @@ export const GENERATED_CONFIG_FILES = new Set(
 /** Lint/format configs by detected language. Unknown ⇒ universal only. */
 export const CONFIGS_BY_LANGUAGE = {
   javascript: JS_CONFIGS,
-  typescript: JS_CONFIGS,
+  typescript: TS_CONFIGS,
   python: PY_CONFIGS,
   go: GO_CONFIGS,
   php: PHP_CONFIGS,

package/src/harden/sandbox.js

@@ -0,0 +1,120 @@
+/**
+ * sandbox — kj harden turns the host's Bash sandbox on (KJC-TSK-1087, ADR 0015).
+ *
+ * Claude Code sandboxes Bash with bubblewrap on Linux and seatbelt on macOS. With
+ * allowUnsandboxedCommands off, a sandbox that cannot start leaves the session with
+ * no Bash at all (pilot KJC-TSK-1083: Ubuntu 24.04 restricts user namespaces until
+ * bwrap has an AppArmor profile). So the probe runs first, on this machine.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const USERNS_SYSCTL = "/proc/sys/kernel/apparmor_restrict_unprivileged_userns";
+
+const whichOnPath = (bin) => (process.env.PATH ?? "").split(delimiter).map((d) => join(d, bin)).find((p) => existsSync(p)) ?? null;
+const runSync = (bin, args) => spawnSync(bin, args, { encoding: "utf8", timeout: 10_000 });
+
+const missing = (tool, pkg) => ({ ok: false, reason: `${tool} is not installed`, remedy: `install ${pkg} (apt install ${pkg}, dnf install ${pkg})` });
+
+function userNamespacesRestricted(readFile) {
+  try { return readFile(USERNS_SYSCTL).trim() === "1"; } catch { return false; }
+}
+
+function probeLinux({ which, run, readFile }) {
+  const bwrap = which("bwrap");
+  if (!bwrap) return missing("bubblewrap (bwrap)", "bubblewrap");
+  if (!which("socat")) return missing("socat", "socat");
+  // The same namespaces Claude Code's sandbox asks for: user and network.
+  const res = run(bwrap, ["--ro-bind", "/", "/", "--dev", "/dev", "--unshare-user", "--unshare-net", "true"]);
+  if (res.status === 0) return { ok: true };
+  if (userNamespacesRestricted(readFile)) {
+    return {
+      ok: false,
+      reason: "AppArmor restricts unprivileged user namespaces and bwrap has no profile",
+      remedy: "add /etc/apparmor.d/bwrap allowing userns for /usr/bin/bwrap, then load it with apparmor_parser -r (your user does this)",
+    };
+  }
+  const detail = String(res.stderr ?? "").trim() || "exit " + res.status;
+  return { ok: false, reason: `bwrap cannot create its namespaces: ${detail}`, remedy: "fix bwrap on this machine, then run kj harden again" };
+}
+
+/**
+ * Can the host sandbox start on this machine? Never throws.
+ * @returns {{ok: true} | {ok: false, reason: string, remedy?: string}}
+ */
+export function probeSandbox({ platform = process.platform, which = whichOnPath, run = runSync, readFile = (p) => readFileSync(p, "utf8"), exists = existsSync } = {}) {
+  if (platform === "linux") return probeLinux({ which, run, readFile });
+  if (platform === "darwin") {
+    if (!exists("/usr/bin/sandbox-exec")) return { ok: false, reason: "sandbox-exec is missing from /usr/bin" };
+    const res = run("/usr/bin/sandbox-exec", ["-p", "(version 1)(allow default)", "/usr/bin/true"]);
+    const detail = String(res.stderr ?? "").trim() || "exit " + res.status;
+    return res.status === 0 ? { ok: true } : { ok: false, reason: `sandbox-exec cannot start a sandbox: ${detail}` };
+  }
+  return { ok: false, reason: `the host sandbox does not run on ${platform}` };
+}
+
+// KJC-TSK-1092: what the method needs from the sandbox (lessons of the pilot, KJC-TSK-1083).
+// gh keeps its tokens in the keyring over D-Bus; kj review reaches a local SonarQube,
+// which the sandbox's private localhost cannot (the reviewer agents run inside it).
+// Outside the project only kj's state and package caches are writable, and the
+// supervisor and the phone key stay out of reach.
+const METHOD_SANDBOX = {
+  excludedCommands: ["gh *", "kj review *"],
+  denyWrite: [".karajan/harness", ".karajan/supervisor-provenance.json", "~/.karajan/supervisor-phone.json"],
+  allowWrite: ["~/.karajan", "~/.npm/_cacache", "~/.npm/_logs", "~/.npm/_npx", "~/.cache", "~/.config/configstore"],
+  allowedDomains: [
+    "github.com", "api.github.com", "*.githubusercontent.com", "uploads.github.com", "registry.npmjs.org",
+    "api.openai.com", "chatgpt.com", "*.openai.com", "api.anthropic.com", "*.anthropic.com", "claude.ai",
+    "api.githubcopilot.com", "*.githubcopilot.com", "*.googleapis.com",
+  ],
+};
+
+const union = (have, add) => [...new Set([...(Array.isArray(have) ? have : []), ...add])];
+
+function withMethodSandbox(settings) {
+  const sb = settings.sandbox ?? {};
+  const fsCfg = sb.filesystem ?? {};
+  const net = sb.network ?? {};
+  return {
+    ...settings,
+    sandbox: {
+      ...sb,
+      enabled: true,
+      allowUnsandboxedCommands: false,
+      excludedCommands: union(sb.excludedCommands, METHOD_SANDBOX.excludedCommands),
+      filesystem: { ...fsCfg, denyWrite: union(fsCfg.denyWrite, METHOD_SANDBOX.denyWrite), allowWrite: union(fsCfg.allowWrite, METHOD_SANDBOX.allowWrite) },
+      network: { ...net, allowedDomains: union(net.allowedDomains, METHOD_SANDBOX.allowedDomains) },
+    },
+  };
+}
+
+/**
+ * Turn the host sandbox on in .claude/settings.local.json when it can start here.
+ * @returns {{state: "on" | "off" | "left-off" | "untouched", reason?: string}}
+ */
+export function installSandbox({ projectDir, logger = console, probe = probeSandbox }) {
+  const ready = probe();
+  if (!ready.ok) {
+    const remedy = ready.remedy ? `; ${ready.remedy}` : "";
+    logger.info?.(`kj harden: host sandbox left off, ${ready.reason}${remedy}`);
+    return { state: "off", reason: ready.reason };
+  }
+  const path = join(projectDir, ".claude", "settings.local.json");
+  let settings = {};
+  if (existsSync(path)) {
+    try {
+      settings = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      logger.warn?.(`kj harden: ${path} is not valid JSON, the host sandbox was not written`);
+      return { state: "untouched", reason: "invalid JSON" };
+    }
+  }
+  if (settings.sandbox?.enabled === false) {
+    logger.info?.(`kj harden: the host sandbox stays off, ${path} says enabled: false`);
+    return { state: "left-off", reason: "enabled: false" };
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(withMethodSandbox(settings), null, 2)}\n`);
+  return { state: "on" };
+}

package/src/harden/sentinel/sentinel-shell.mjs

@@ -87,20 +87,21 @@ export const isGhIssueCreate = (cmd) => shellSegments(cmd).some((words) => {
 });
 
 // KJC-BUG-0204: the real command puts flags between the verb's words
-// (firebase --account a@b deploy), so they are read in order, not adjacent.
-const PUBLISH_VERBS = [["npm", "publish"], ["firebase", "deploy"], ["gh", "release", "create"]];
+// (npm --prefix x publish), so they are read in order, not adjacent.
+// KJC-BUG-0373: only a release of the package; a deploy (database rules, a site)
+// is not one, and gating it kept an open database open.
+const PUBLISH_VERBS = [["npm", "publish"], ["gh", "release", "create"]];
 // Known options that take a separate value: that value is not a subcommand word
 // (npm --tag publish test does not publish). An unknown option is not skipped, so
 // a real publish behind it is still read (a false positive costs less than a miss).
 const VALUE_OPTIONS = {
   npm: ["--prefix", "--tag", "--registry", "--userconfig", "--workspace", "-w", "--otp", "--access", "--cache", "--loglevel", "-C"],
-  firebase: ["--account", "--project", "-P", "--config", "-c", "--only", "--except", "--token", "--message", "-m"],
   gh: ["--repo", "-R", "--hostname"],
 };
 
 /**
- * KJC-BUG-0333 (#2093): a simple command whose head is npm, firebase or gh and
- * whose own words then say publish/deploy/release create. Words inside a quoted
+ * KJC-BUG-0333 (#2093): a simple command whose head is npm or gh and whose own
+ * words then say publish/release create. Words inside a quoted
  * argument of another command (a kj rag query text, a commit message) are one
  * word of THAT command, so they never read as a publish.
  * @param {string} cmd

package/src/review/tests-with-code.js

@@ -8,7 +8,9 @@
  * No escape (ADR 0015): deletions and comment-only cleanups already pass.
  */
 
-const DEFAULT_TEST_PATTERNS = ["/tests/", "/__tests__/", ".test.", ".spec."];
+import { isGenerated } from "./loc-budget.js";
+
+const DEFAULT_TEST_PATTERNS =["/tests/", "/__tests__/", ".test.", ".spec."];
 const DEFAULT_SOURCE_EXTS = [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".rb", ".php", ".cs"];
 
 /**
@@ -22,8 +24,9 @@ export function sourceFilesOf(config = {}, files = []) {
   // Staged paths are repo-relative (no leading slash) — normalize so the
   // "/tests/" style patterns also match the top-level tests directory.
   const isTest = (f) => patterns.some((p) => `/${f}`.includes(p));
+  // KJC-BUG-0377: build output (a rebuilt docs site's _astro/*.js) is nobody's code.
   return {
-    sources: files.filter((f) => !isTest(f) && exts.some((e) => f.endsWith(e))),
+    sources: files.filter((f) => !isTest(f) && !isGenerated(f) && exts.some((e) => f.endsWith(e))),
     hasTests: files.some(isTest),
   };
 }

package/src/utils/git.js

@@ -307,8 +307,10 @@ export async function hasRemote(cwd = null) {
   return res.exitCode === 0;
 }
 
+// KJC-TSK-1093: no -u, which writes the upstream into .git/config, read-only inside
+// the host sandbox. Nothing in kj reads a feature branch's upstream.
 export async function pushBranch(branch, cwd = null) {
-  await runGit(["push", "-u", "origin", branch], cwd ? { cwd } : {});
+  await runGit(["push", "origin", branch], cwd ? { cwd } : {});
 }
 
 export async function createPullRequest({ baseBranch, branch, title, body, cwd = null }) {