@karajan-family/code 4.21.0

package/src/utils/update-check.js

@@ -0,0 +1,280 @@
+import fs from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isSea } from "node:sea";
+import { getKarajanHome } from "./paths.js";
+
+const CACHE_FILE = "update-check.json";
+// KJC-TSK-0690: 6h — kj can ship several releases a day; a session should
+// not work a full day blind. KJ_NO_UPDATE_CHECK=1 opts out (CI).
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+// MIG-A (KJC-TSK-0751): el nombre npm se lee del PROPIO manifest — con el
+// dual-publish del scope, el mismo código vive como karajan-code y como
+// @karajan-family/code y cada instalación se auto-actualiza por SU nombre.
+// Lazy + fallback: en el bundle SEA no hay package.json junto al módulo.
+let _pkgName;
+export function packageName() {
+  if (_pkgName) return _pkgName;
+  try {
+    _pkgName = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).name || "karajan-code";
+  } catch {
+    _pkgName = "karajan-code";
+  }
+  return _pkgName;
+}
+
+// URL del registro con el nombre CODIFICADO — el scoped @karajan-family/code
+// lleva @ y / que rompen la ruta sin encode (catch de codex).
+export const registryLatestUrl = (name = packageName()) =>
+  `https://registry.npmjs.org/${encodeURIComponent(name)}/latest`;
+const CHANGELOG_URL = "https://raw.githubusercontent.com/manufosela/karajan-code/main/CHANGELOG.md";
+const HIGHLIGHT_MAX = 160;
+
+/**
+ * First paragraph of a version's CHANGELOG section — the release headline
+ * ("Minor. **The method, enforced.** …"), bold stripped, truncated. Pure.
+ */
+export function parseChangelogHighlight(markdown, version) {
+  const escapedVersion = version.replaceAll(".", String.raw`\.`);
+  const section = String(markdown).split(new RegExp(String.raw`^## \[${escapedVersion}\][^\n]*$`, "m"))[1];
+  if (!section) return null;
+  const firstLine = section.split(/^##|^###/m)[0].split("\n").map((l) => l.trim()).find(Boolean);
+  if (!firstLine) return null;
+  const clean = firstLine.replaceAll("**", "");
+  return clean.length > HIGHLIGHT_MAX ? `${clean.slice(0, HIGHLIGHT_MAX - 1)}…` : clean;
+}
+
+async function fetchHighlight(version) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(CHANGELOG_URL, { signal: controller.signal });
+    clearTimeout(timeout);
+    if (!res.ok) return null;
+    return parseChangelogHighlight(await res.text(), version);
+  } catch {
+    return null;
+  }
+}
+
+const RAW_BASE = "https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts";
+export const INSTALL_SH_URL = `${RAW_BASE}/install-binary.sh`;
+export const INSTALL_PS1_URL = `${RAW_BASE}/install-binary.ps1`;
+
+/**
+ * Build the "how to update" line for the detected install channel.
+ * Pure and testable — no I/O.
+ * @param {{channel: "sea"|"npm"|"unknown", platform?: string}} opts
+ */
+export function updateInstruction({ channel, platform = process.platform }) {
+  if (channel === "sea") {
+    return platform === "win32"
+      ? `Re-run the installer: irm ${INSTALL_PS1_URL} | iex`
+      : `Re-run the installer: curl -fsSL ${INSTALL_SH_URL} | sh`;
+  }
+  if (channel === "npm") {
+    return `Run: npm install -g ${packageName()}`;
+  }
+  // Channel unknown — offer both paths, never silently pick a wrong one.
+  return `Update: npm install -g ${packageName()}  (or re-run the binary installer — see README)`;
+}
+
+/**
+ * Detect how this kj was installed: "sea" (standalone binary) or "npm"
+ * (global install / source tree). Falls back to "npm" if isSea() throws.
+ */
+export function detectInstallChannel() {
+  try {
+    return isSea() ? "sea" : "npm";
+  } catch {
+    // isSea() unexpectedly threw ⇒ treat as npm / source tree, never block.
+    return "npm";
+  }
+}
+
+/**
+ * Check npm for a newer version. Non-blocking, cached for 24h.
+ * Returns { updateAvailable, latest, current } or null if check fails/cached.
+ */
+export async function checkForUpdate(currentVersion) {
+  if (process.env.KJ_NO_UPDATE_CHECK === "1") return null;
+  try {
+    const cachePath = path.join(getKarajanHome(), CACHE_FILE);
+
+    // Check cache first
+    try {
+      const raw = await fs.readFile(cachePath, "utf8");
+      const cache = JSON.parse(raw);
+      if (cache.checkedAt && Date.now() - cache.checkedAt < CACHE_TTL_MS) {
+        if (!cache.latest || cache.latest === currentVersion) return null;
+        // Only show update if latest is actually NEWER than current
+        if (compareVersions(cache.latest, currentVersion) > 0) {
+          return { updateAvailable: true, latest: cache.latest, current: currentVersion, highlight: cache.highlight || null };
+        }
+        return null;
+      }
+    } catch { /* no cache or expired */ }
+
+    // Fetch from npm (timeout 3s, don't block)
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(registryLatestUrl(), {
+      signal: controller.signal,
+      headers: { "Accept": "application/json" },
+    });
+    clearTimeout(timeout);
+
+    if (!res.ok) return null;
+    const data = await res.json();
+    const latest = data.version;
+
+    // KJC-TSK-0690: a NEWER version also fetches its headline once — the
+    // notice tells the user what it brings, not just that it exists.
+    const newer = latest !== currentVersion && compareVersions(latest, currentVersion) > 0;
+    const highlight = newer ? await fetchHighlight(latest) : null;
+
+    // Save cache
+    await fs.mkdir(getKarajanHome(), { recursive: true });
+    await fs.writeFile(cachePath, JSON.stringify({ latest, checkedAt: Date.now(), highlight }), "utf8");
+
+    if (newer) return { updateAvailable: true, latest, current: currentVersion, highlight };
+    return null;
+  } catch {
+    return null; // Network error, offline, etc. Never block.
+  }
+}
+
+/**
+ * Print update notice if available. Call at CLI startup, non-blocking.
+ */
+export async function printUpdateNotice(currentVersion) {
+  const result = await checkForUpdate(currentVersion);
+  if (result?.updateAvailable) {
+    const channel = detectInstallChannel();
+    console.log(`\n  Update available: v${result.current} → v${result.latest}`);
+    if (result.highlight) console.log(`  What it brings: ${result.highlight}`);
+    console.log(`  ${updateInstruction({ channel })}`);
+    console.log("  Agent: tell your user and ask before updating — never update on your own.\n");
+  }
+}
+
+/**
+ * Run the self-update (`kj update`), channel-aware (KJC-BUG-0106).
+ *
+ * npm channel: `npm install -g` with CAPTURED output — success shows only
+ * progress + result; npm's deprecation / allow-scripts / funding noise never
+ * reaches the user. On failure the captured output IS surfaced.
+ *
+ * sea channel (standalone binary): npm-installing would update a copy the
+ * PATH never resolves — the running binary stays old while `kj update`
+ * reports success. Instead the binary installer is re-run (downloaded to a
+ * temp file first, never piped from the network straight into a shell).
+ *
+ * Both channels end with a PATH probe: `kj --version` must report the new
+ * version, otherwise a stale copy shadows the update and the command fails
+ * LOUDLY naming the likely cause — never a silent "updated" that isn't.
+ *
+ * @param {Object} opts
+ * @param {string} opts.currentVersion - version of the running kj
+ * @param {(cmd: string, args: string[]) => Promise<{stdout: string, stderr: string}>} [opts.exec] - injectable runner (defaults to execa)
+ * @param {Console} [opts.logger]
+ * @param {"npm"|"sea"} [opts.channel] - injectable channel (defaults to detectInstallChannel())
+ * @param {typeof fetch} [opts.fetchFn] - injectable fetch (registry lookup + installer download)
+ * @returns {Promise<{ ok: boolean, alreadyLatest?: boolean, latest?: string, manual?: boolean }>}
+ */
+export async function performSelfUpdate({ currentVersion, exec, logger = console, channel, fetchFn = fetch } = {}) {
+  const run = exec || (async (cmd, args) => (await import("execa")).execa(cmd, args));
+  const ch = channel || detectInstallChannel();
+  logger.log(`Current version: ${currentVersion}`);
+  logger.log("Checking for updates...");
+
+  let latest;
+  try {
+    // Registry over HTTP, not `npm view` — standalone-binary machines may
+    // not have npm at all.
+    const res = await fetchFn(registryLatestUrl(), {
+      headers: { Accept: "application/json" },
+    });
+    if (!res.ok) throw new Error(`registry responded ${res.status}`);
+    latest = (await res.json()).version;
+  } catch (err) {
+    logger.error(`Update failed: could not check the registry (${err.message})`);
+    return { ok: false };
+  }
+
+  if (latest === currentVersion) {
+    logger.log(`Already on the latest version (${currentVersion}).`);
+    return { ok: true, alreadyLatest: true, latest };
+  }
+
+  if (ch === "sea" && process.platform === "win32") {
+    // Executing a downloaded .ps1 from inside the binary is not supported
+    // yet — hand the user the exact command instead of half-updating.
+    logger.log(`Update available: ${currentVersion} → ${latest} (standalone binary).`);
+    logger.log(`${updateInstruction({ channel: "sea" })}`);
+    return { ok: true, latest, manual: true };
+  }
+
+  logger.log(`Updating ${currentVersion} → ${latest}... (this can take a few minutes)`);
+  try {
+    if (ch === "sea") {
+      // Re-run the binary installer: download to a temp file, then execute —
+      // never pipe the network straight into a shell.
+      const res = await fetchFn(INSTALL_SH_URL);
+      if (!res.ok) throw new Error(`installer download failed (${res.status})`);
+      const tmpScript = path.join(os.tmpdir(), `kj-install-${process.pid}.sh`);
+      await fs.writeFile(tmpScript, await res.text(), { mode: 0o700 });
+      try {
+        await run("sh", [tmpScript]);
+      } finally {
+        await fs.rm(tmpScript, { force: true });
+      }
+    } else {
+      // No stdio:inherit — capture and drop npm's warnings on the success path.
+      await run("npm", ["install", "-g", `${packageName()}@latest`]);
+    }
+  } catch (err) {
+    if (err.stdout) logger.error(err.stdout);
+    if (err.stderr) logger.error(err.stderr);
+    logger.error(`Update failed: ${err.shortMessage || err.message}`);
+    return { ok: false };
+  }
+
+  // The install succeeded — but is the kj the USER runs actually the new one?
+  const onPath = await verifyKjOnPath({ run, latest, logger });
+  if (!onPath) return { ok: false };
+  logger.log(`Updated to ${latest}. Restart Claude to pick up the new MCP server.`);
+  return { ok: true, latest };
+}
+
+/**
+ * Probe `kj --version` through the PATH and confirm it reports `latest`.
+ * A mismatch means a stale copy shadows the freshly installed one (e.g. a
+ * standalone binary in ~/.local/bin in front of the npm global prefix).
+ */
+async function verifyKjOnPath({ run, latest, logger }) {
+  let reported;
+  try {
+    const { stdout } = await run("kj", ["--version"]);
+    reported = String(stdout).trim();
+  } catch (err) {
+    logger.error(`Update installed ${latest}, but running \`kj --version\` failed: ${err.shortMessage || err.message}`);
+    return false;
+  }
+  if (reported.includes(latest)) return true;
+  logger.error(`Update installed ${latest}, but the \`kj\` on your PATH still reports ${reported}.`);
+  logger.error("A stale copy is shadowing the update. Check `which -a kj` and remove the old one, or update through the channel that owns the first entry.");
+  return false;
+}
+
+/** Simple semver compare: returns >0 if a > b, <0 if a < b, 0 if equal */
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}

package/src/utils/vector-store-orphans.js

@@ -0,0 +1,89 @@
+/**
+ * RAG vector-store orphan collector — KJC-TSK-0499 PR2.
+ *
+ * Enumerates distinct `project_slug` rows in `~/.karajan/rag.db`,
+ * augments each with chunk count + last_indexed_{at,commit}, and
+ * marks as orphan the slugs whose basename does not resolve to a
+ * directory in any of the configured `projectRoots`.
+ *
+ * Read-only. Returns rows + a copy-paste sqlite3 command per orphan.
+ * Deliberate inverse of the RAG indexer: never opens the DB for write.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { dbPath, openVecStore, projectSlug } from "../rag/vec-store.js";
+
+const DEFAULT_ROOTS = [
+  path.join(os.homedir(), "ws_npm-packages"),
+  path.join(os.homedir(), "ws_firebase"),
+  path.join(os.homedir(), "projects"),
+  path.join(os.homedir(), "code"),
+];
+
+async function listDirs(root) {
+  try {
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => path.join(root, e.name));
+  } catch {
+    return [];
+  }
+}
+
+async function buildSlugIndex(roots) {
+  const index = new Map();
+  for (const root of roots) {
+    for (const dir of await listDirs(root)) {
+      const slug = projectSlug(dir);
+      if (slug && !index.has(slug)) index.set(slug, dir);
+    }
+  }
+  return index;
+}
+
+function purgeCommand(slug) {
+  const slugSafe = slug.replace(/'/g, "''");
+  return `sqlite3 ${dbPath()} "DELETE FROM chunks WHERE project_slug='${slugSafe}'; DELETE FROM vec_store_meta WHERE project_slug='${slugSafe}';"`;
+}
+
+/**
+ * Collect RAG vector-store orphans.
+ * @param {object} [opts]
+ * @param {string[]} [opts.projectRoots] — directories to look for live
+ *   projects whose basename matches each slug. Defaults to the usual
+ *   `~/ws_*`, `~/projects`, `~/code` set.
+ * @returns {Promise<{rows: Array, orphans: Array, errors: Array}>}
+ */
+export async function collectVectorStoreOrphans({ projectRoots = DEFAULT_ROOTS } = {}) {
+  const rows = [];
+  const errors = [];
+  let db;
+  try { db = openVecStore(); } catch (e) {
+    return { rows, orphans: [], errors: [{ stage: "open", error: String(e?.message ?? e) }] };
+  }
+  try {
+    const stats = db.prepare(`
+      SELECT COALESCE(c.project_slug, '<null>') AS slug,
+             COUNT(c.id) AS chunkCount,
+             COALESCE(m.last_indexed_commit, '') AS lastCommit,
+             COALESCE(m.last_indexed_at, '') AS lastAt
+      FROM chunks c
+      LEFT JOIN vec_store_meta m ON m.project_slug = c.project_slug
+      GROUP BY c.project_slug
+      ORDER BY chunkCount DESC
+    `).all();
+    const slugIndex = await buildSlugIndex(projectRoots);
+    for (const r of stats) {
+      const resolved = slugIndex.get(r.slug) || null;
+      rows.push({ ...r, resolvedDir: resolved, orphan: !resolved && r.slug !== "<null>" });
+    }
+  } catch (e) {
+    errors.push({ stage: "query", error: String(e?.message ?? e) });
+  } finally {
+    try { db.close(); } catch { /* close errors are non-fatal */ }
+  }
+  const orphans = rows
+    .filter((r) => r.orphan)
+    .map((r) => ({ ...r, command: purgeCommand(r.slug) }));
+  return { rows, orphans, errors };
+}

package/src/utils/welcome.js

@@ -0,0 +1,47 @@
+import { printBanner } from "./banner.js";
+
+const A = {
+  reset:   "\x1b[0m",
+  bold:    "\x1b[1m",
+  dim:     "\x1b[2m",
+  cyan:    "\x1b[36m",
+  green:   "\x1b[32m",
+  yellow:  "\x1b[33m",
+};
+
+const QUICK_START = [
+  ["kj run <task>",  "Run the full coder+reviewer pipeline"],
+  ["kj init",        "Initialize config and setup"],
+  ["kj doctor",      "Check environment and agent availability"],
+  ["kj status",      "Show pipeline dashboard"],
+  ["kj report",      "Show latest session report"],
+];
+
+/**
+ * Print the CLI welcome screen.
+ * @param {object} opts
+ * @param {string} opts.version - Version string (required)
+ * @param {object} [opts.config]  - Loaded KJ config (optional, shows configured agents)
+ */
+export function printWelcomeScreen({ version, config = null }) {
+  printBanner(version, { force: true });
+
+  if (config) {
+    const coder    = config.roles?.coder?.provider    || config.coder    || "claude";
+    const reviewer = config.roles?.reviewer?.provider || config.reviewer || "codex";
+    console.log(`  ${A.bold}Agents${A.reset}`);
+    console.log(`    ${A.dim}coder:${A.reset}    ${coder}`);
+    console.log(`    ${A.dim}reviewer:${A.reset} ${reviewer}`);
+    console.log();
+  }
+
+  console.log(`  ${A.bold}Quick start${A.reset}`);
+  for (const [cmd, desc] of QUICK_START) {
+    const padded = cmd.padEnd(20);
+    console.log(`    ${A.green}${padded}${A.reset}  ${A.dim}${desc}${A.reset}`);
+  }
+
+  console.log();
+  console.log(`  ${A.dim}Run ${A.reset}kj --help${A.dim} to see all commands.${A.reset}`);
+  console.log();
+}

package/src/utils/with-timeout.js

@@ -0,0 +1,42 @@
+/**
+ * Timeout wrapper for arbitrary promises.
+ *
+ * Produces a new Promise that resolves with the original value if the
+ * underlying promise settles within `ms`, or rejects with a TimeoutError if
+ * it doesn't. Intended for wrapping individual checks in the doctor/preflight
+ * runner so a slow HTTP probe cannot hang the whole pipeline.
+ *
+ * The original promise keeps running after timeout (we cannot cancel it
+ * without cooperation). Callers should avoid calling `withTimeout` on
+ * side-effectful operations they need to be sure completed.
+ */
+
+export class TimeoutError extends Error {
+  constructor(label, ms) {
+    super(`Timeout after ${ms}ms${label ? ` (${label})` : ""}`);
+    this.name = "TimeoutError";
+    this.timeoutMs = ms;
+    this.label = label;
+  }
+}
+
+/**
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {number} ms
+ * @param {string} [label] - for error messages / logs
+ * @returns {Promise<T>}
+ */
+export function withTimeout(promise, ms, label) {
+  if (!Number.isFinite(ms) || ms <= 0) return promise;
+
+  let timerId;
+  const timeout = new Promise((_resolve, reject) => {
+    timerId = setTimeout(() => reject(new TimeoutError(label, ms)), ms);
+    if (timerId && typeof timerId.unref === "function") timerId.unref();
+  });
+
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timerId) clearTimeout(timerId);
+  });
+}

package/src/utils/wizard.js

@@ -0,0 +1,47 @@
+import readline from "node:readline";
+
+export function createWizard(inputStream = process.stdin, output = process.stdout) {
+  const rl = readline.createInterface({ input: inputStream, output, terminal: false });
+
+  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 input(question, defaultValue = "") {
+    const hint = defaultValue !== "" ? ` [${defaultValue}]` : "";
+    const answer = await ask(`${question}${hint} `);
+    return answer === "" ? defaultValue : 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, input, select, close };
+}
+
+export function isTTY() {
+  return Boolean(process.stdin.isTTY);
+}

package/src/webperf/cwv-gate.js

@@ -0,0 +1,94 @@
+/**
+ * Core Web Vitals quality gate.
+ *
+ * Evaluates LCP, CLS and INP against Google's recommended thresholds
+ * and returns a structured verdict usable by the pipeline.
+ */
+
+export const CWV_THRESHOLDS = {
+  lcp: { good: 2500, poor: 4000 },
+  cls: { good: 0.1, poor: 0.25 },
+  inp: { good: 200, poor: 500 }
+};
+
+/**
+ * Deep-merge custom thresholds on top of the defaults.
+ * Only overrides metrics/boundaries that the caller provides.
+ *
+ * @param {object} defaults - Base thresholds (e.g. CWV_THRESHOLDS)
+ * @param {object} [custom]  - Partial overrides
+ * @returns {object} Merged thresholds
+ */
+export function mergeThresholds(defaults, custom) {
+  if (!custom || typeof custom !== "object") return { ...defaults };
+
+  const merged = {};
+  for (const metric of Object.keys(defaults)) {
+    const base = defaults[metric];
+    const over = custom[metric];
+    if (over && typeof over === "object") {
+      merged[metric] = {
+        good: over.good !== undefined ? over.good : base.good,
+        poor: over.poor !== undefined ? over.poor : base.poor
+      };
+    } else {
+      merged[metric] = { ...base };
+    }
+  }
+
+  // Include any extra metrics the caller added that are not in defaults
+  for (const metric of Object.keys(custom)) {
+    if (!merged[metric] && typeof custom[metric] === "object") {
+      merged[metric] = { ...custom[metric] };
+    }
+  }
+
+  return merged;
+}
+
+function rateMetric(value, good, poor) {
+  if (value <= good) return "good";
+  if (value >= poor) return "poor";
+  return "needs-improvement";
+}
+
+/**
+ * Evaluate Core Web Vitals metrics against thresholds.
+ *
+ * @param {{ lcp?: number, cls?: number, inp?: number }} metrics
+ * @param {object} [customThresholds] - Optional per-metric overrides
+ * @returns {{
+ *   pass: boolean,
+ *   scores: Record<string, { value: number, rating: string }>,
+ *   blocking: Array<{ metric: string, value: number, threshold: number, rating: string }>,
+ *   advisory: Array<{ metric: string, value: number, threshold: number, rating: string }>
+ * }}
+ */
+export function evaluateCwv(metrics, customThresholds) {
+  const thresholds = mergeThresholds(CWV_THRESHOLDS, customThresholds);
+
+  const scores = {};
+  const blocking = [];
+  const advisory = [];
+
+  for (const [metric, bounds] of Object.entries(thresholds)) {
+    const value = metrics[metric];
+    if (value === undefined || value === null) continue;
+
+    const rating = rateMetric(value, bounds.good, bounds.poor);
+    scores[metric] = { value, rating };
+
+    if (rating === "poor") {
+      blocking.push({ metric, value, threshold: bounds.poor, rating });
+    } else if (rating === "needs-improvement") {
+      advisory.push({ metric, value, threshold: bounds.good, rating });
+    }
+  }
+
+  return {
+    pass: blocking.length === 0,
+    scores,
+    blocking,
+    advisory
+  };
+}