@karajan-family/code 4.21.0

package/src/cli/register-standby.js

@@ -0,0 +1,26 @@
+// KJC-TSK-0414 PR2: registra `kj standby list` + `kj standby resume <id>`.
+// `resume` es subcomando de standby para no colisionar con el `kj resume`
+// pre-existente (Solomon pauses con --answer). Modelos mentales distintos:
+//   - `kj resume <id> --answer X`  → Solomon pauseado (existente)
+//   - `kj standby resume <id>`     → run hibernada por quota
+import { resumeCommand, standbyListCommand } from "../commands/standby.js";
+
+export function registerStandby(program) {
+  const standby = program.command("standby").description("Sesiones hibernadas (QUOTA_EXHAUSTED_DAILY etc.)");
+  standby
+    .command("list", { isDefault: true })
+    .description("Lista sesiones pendientes de reanudar")
+    .option("--json", "Output JSON")
+    .action(async (flags) => {
+      await standbyListCommand({ json: flags.json });
+    });
+
+  standby
+    .command("resume")
+    .description("Reanuda una sesión hibernada (re-spawn comando original)")
+    .argument("<sessionId>")
+    .option("--force", "Reanudar aunque cooldownUntil todavía esté en el futuro (no recomendado)")
+    .action(async (sessionId, flags) => {
+      await resumeCommand({ sessionId, force: Boolean(flags.force) });
+    });
+}

package/src/cli.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { Command, Help } from "commander";
+import { loadConfig } from "./config.js";
+import { isAdvancedCommand } from "./cli/advanced-commands.js";
+import { registerPipeline } from "./cli/register-pipeline.js";
+import { registerPlan } from "./cli/register-plan.js";
+import { registerRolesSkills } from "./cli/register-roles-skills.js";
+import { registerMeta } from "./cli/register-meta.js";
+import { registerSonar } from "./cli/register-sonar.js";
+import { registerStandby } from "./cli/register-standby.js";
+import { printUpdateNotice } from "./utils/update-check.js";
+import { printWelcomeScreen } from "./utils/welcome.js";
+import { migrateKjToKarajan } from "./utils/home-migration.js";
+
+const PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
+const PKG_VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
+
+// Non-blocking update check (runs in background, prints after command output)
+printUpdateNotice(PKG_VERSION).catch(() => {});
+
+const program = new Command();
+program
+  .name("kj")
+  .description("Karajan Code CLI")
+  .version(PKG_VERSION)
+  // Tell Commander to surface "did you mean…?" + a help pointer on every
+  // CLI error (typo'd subcommand, missing required arg, etc.). Propagates
+  // automatically to subcommands.
+  .showSuggestionAfterError(true)
+  .showHelpAfterError("(usa 'kj --help' para ver los comandos disponibles)")
+  // Accept unknown options + extra positional args at the ROOT only.
+  // Without these two, typing `kj generate plan --task-file SPEC.md`
+  // errors with "unknown option --task-file" or "too many arguments"
+  // before the welcome action ever sees that 'generate' wasn't a valid
+  // subcommand. With them, both are captured and the welcome action
+  // gets a chance to emit a useful "no such command" message. Subcommands
+  // keep their own strict checking because both flags are per-command,
+  // not inherited.
+  .allowUnknownOption(true)
+  .allowExcessArguments(true);
+
+// KJC-TSK-0582: the flat list had grown to 37 commands. Show only the core
+// basics in `kj --help`; the advanced/specialized ones live under
+// `kj advanced`. The filter applies to the ROOT help only — subcommand help
+// keeps listing its own subcommands untouched.
+program.configureHelp({
+  visibleCommands(cmd) {
+    const cmds = Help.prototype.visibleCommands.call(this, cmd);
+    if (cmd !== program) return cmds;
+    return cmds.filter((c) => !isAdvancedCommand(c.name()));
+  },
+});
+
+// KJC-TSK-0571/0582: orient a newcomer to the few commands they need and
+// point them at `kj advanced` for everything else.
+program.addHelpText(
+  "after",
+  `
+Getting started (the basics — start here):
+  kj init             Set up Karajan in this project (run once)
+  kj run "<task>"     Build or fix something end-to-end (coder + review)
+  kj plan "<task>"    Break a task into user stories first, then run them
+  kj doctor           Check your environment is ready
+  kj harden           Add quality git hooks + CI to any repo
+
+  kj advanced         List every advanced/specialized command, grouped by area`
+);
+
+registerPipeline(program, { pkgVersion: PKG_VERSION });
+registerPlan(program, { pkgVersion: PKG_VERSION });
+registerRolesSkills(program, { pkgVersion: PKG_VERSION });
+registerMeta(program, { pkgVersion: PKG_VERSION });
+registerSonar(program);
+registerStandby(program);
+
+/**
+ * Find subcommands whose name is "close enough" to a typo. Used by the
+ * fallback action below so `kj generate plan` suggests `kj plan`. Cheap
+ * heuristic — same first letter OR substring match OR Levenshtein ≤ 2 —
+ * which is all we need for the small set of commands kj exposes.
+ */
+function suggestSimilarCommands(bad, known) {
+  const lower = bad.toLowerCase();
+  const out = new Set();
+  for (const name of known) {
+    const n = name.toLowerCase();
+    if (n.includes(lower) || lower.includes(n)) out.add(name);
+    else if (n[0] === lower[0] && Math.abs(n.length - lower.length) <= 2) out.add(name);
+    else if (levenshtein(n, lower) <= 2) out.add(name);
+  }
+  return [...out].slice(0, 3);
+}
+
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  const m = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+  for (let i = 0; i <= a.length; i += 1) m[i][0] = i;
+  for (let j = 0; j <= b.length; j += 1) m[0][j] = j;
+  for (let i = 1; i <= a.length; i += 1) {
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      m[i][j] = Math.min(m[i - 1][j] + 1, m[i][j - 1] + 1, m[i - 1][j - 1] + cost);
+    }
+  }
+  return m[a.length][b.length];
+}
+
+// Default action — fires when no subcommand matched. Two cases:
+//   1. No args at all  → friendly welcome screen (preserved behaviour).
+//   2. Args were given → user typed an unknown command. Print a clear
+//      error pointing at WHICH word was wrong, suggest a close match,
+//      list every valid command, and exit non-zero. Commander's own
+//      "unknown option" error never fires for these because we set
+//      allowUnknownOption(true) on the root above.
+program.action(async (_opts, command) => {
+  if (command.args.length > 0) {
+    const bad = command.args[0];
+    const known = program.commands.map((c) => c.name()).sort();
+    process.stderr.write(`error: '${bad}' no es un comando válido de kj\n`);
+    const suggestions = suggestSimilarCommands(bad, known);
+    if (suggestions.length > 0) {
+      const list = suggestions.map((s) => `'${s}'`).join(suggestions.length === 2 ? " o " : ", ");
+      process.stderr.write(`\n¿Quisiste decir ${list}?\n`);
+    }
+    process.stderr.write("\nComandos disponibles:\n");
+    for (const c of known) process.stderr.write(`  ${c}\n`);
+    process.stderr.write("\nUsa 'kj --help' para más información, o 'kj <comando> --help' para detalles de un subcomando.\n");
+    process.exit(1);
+  }
+  const { config } = await loadConfig().catch(() => ({ config: null }));
+  printWelcomeScreen({ version: PKG_VERSION, config });
+});
+
+// One-shot ~/.kj/ → ~/.karajan/ consolidation. Idempotent via marker
+// file; failures non-blocking. See src/utils/home-migration.js.
+// Static import — the migrator runs on every kj invocation, no
+// lazy-load benefit + the architectural dynamic-imports budget would
+// otherwise grow by one for a permanent caller.
+try {
+  await migrateKjToKarajan();
+} catch (err) {
+  console.warn(`\x1b[33m[warn]\x1b[0m home migration skipped: ${err.message}`);
+}
+
+try {
+  await program.parseAsync();
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/src/commands/advanced.js

@@ -0,0 +1,31 @@
+// KJC-TSK-0582: `kj advanced` prints every advanced/specialized command,
+// grouped by area, with the one-line description commander already holds for
+// it. Pure formatter (takes a name→description map) so it's trivially
+// testable without spinning up the whole CLI.
+import { ADVANCED_GROUPS } from "../cli/advanced-commands.js";
+
+const NAME_PAD = 14;
+
+/**
+ * Build the `kj advanced` index text.
+ * @param {Record<string,string>|Map<string,string>} descriptions name → one-line description
+ */
+export function formatAdvancedIndex(descriptions) {
+  const lookup = descriptions instanceof Map ? descriptions : new Map(Object.entries(descriptions || {}));
+  const firstLine = (text) => String(text || "").split("\n")[0].trim();
+
+  const lines = [
+    "Comandos avanzados y especializados (agrupados por área).",
+    "Todos siguen siendo invocables directamente: kj <comando>.",
+    "",
+  ];
+  for (const group of ADVANCED_GROUPS) {
+    lines.push(`${group.title}:`);
+    for (const name of group.commands) {
+      lines.push(`  kj ${name.padEnd(NAME_PAD)} ${firstLine(lookup.get(name))}`.trimEnd());
+    }
+    lines.push("");
+  }
+  lines.push("Usa 'kj <comando> --help' para los detalles de cualquiera de ellos.");
+  return lines.join("\n");
+}

package/src/commands/agent-run.js

@@ -0,0 +1,63 @@
+/**
+ * `kj agent run <agent> "<task>"` (AB-D, KJC-TSK-0654) — the brain's
+ * inter-agent bus. The host agent decides WHO does WHAT; kj provides the
+ * plumbing it shouldn't have to fight: binary detection, subprocess
+ * workarounds (CLAUDECODE strip, stdin, silence timeouts), usage capture.
+ * The brain reads the output and decides — kj never interprets it.
+ */
+import { createAgent, getAvailableAgents } from "../agents/index.js";
+import { detectAvailableAgents } from "../utils/agent-detect.js";
+
+export async function agentRunCommand({ agent, task, config = {}, logger = null, flags = {} }) {
+  if (!task || !task.trim()) {
+    throw new Error("kj agent run requires a task: kj agent run <agent> \"<task>\"");
+  }
+  const known = getAvailableAgents().map((a) => a.name);
+  const detected = await detectAvailableAgents();
+  const up = detected.filter((a) => a.available).map((a) => a.name).join(", ") || "none";
+  if (!known.includes(agent)) {
+    throw new Error(`unknown agent "${agent}" — supported: ${known.join(", ")}; available on this machine: ${up}`);
+  }
+  const entry = detected.find((a) => a.name === agent);
+  if (!entry?.available) {
+    throw new Error(`agent "${agent}" is not available on this machine (available: ${up}) — install its CLI or pick another`);
+  }
+
+  let timeoutMs;
+  if (flags.timeoutMinutes !== undefined) {
+    const minutes = Number(flags.timeoutMinutes);
+    if (!Number.isFinite(minutes) || minutes <= 0) {
+      throw new Error(`--timeout-minutes must be a positive number, got "${flags.timeoutMinutes}"`);
+    }
+    timeoutMs = minutes * 60000;
+  }
+
+  // --json must emit ONLY the serialized result — no informational lines,
+  // and a crash of the delegated subprocess still yields one JSON payload.
+  if (!flags.json) logger?.info?.(`kj agent run: delegating to ${agent}`);
+  const instance = createAgent(agent, config, logger);
+  let result;
+  try {
+    result = await instance.runTask({ prompt: task, role: "delegate", timeoutMs });
+  } catch (err) {
+    result = { ok: false, output: "", error: err.message };
+  }
+
+  const res = {
+    ok: Boolean(result?.ok),
+    agent,
+    output: result?.output || "",
+    error: result?.error || null,
+    usage: result?.tokens_out != null
+      ? { tokens_in: result.tokens_in ?? null, tokens_out: result.tokens_out, cached_tokens: result.cached_tokens ?? null }
+      : null,
+  };
+  if (flags.json) {
+    console.log(JSON.stringify(res));
+  } else {
+    if (res.output) console.log(res.output);
+    if (!res.ok && res.error) console.error(res.error);
+  }
+  process.exitCode = res.ok ? 0 : 1;
+  return res;
+}

package/src/commands/agents.js

@@ -0,0 +1,105 @@
+import { loadConfig, writeConfig, getConfigPath, getProjectConfigPath, loadProjectConfig, resolveRole } from "../config.js";
+import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
+
+// Exportados para que el --help se autoalimente de las constantes reales
+// (KJC-TSK-0755, hallazgo de campo: la firma genérica obligaba a preguntar).
+export const ASSIGNABLE_ROLES = [
+  "coder", "reviewer", "planner", "refactorer", "triage",
+  "researcher", "tester", "security", "solomon"
+];
+
+export const VALID_PROVIDERS = KNOWN_AGENTS.map((a) => a.name);
+
+export function listAgents(config, sessionOverrides = {}, projectConfig = null) {
+  return ASSIGNABLE_ROLES.map((role) => {
+    const resolved = resolveRole(config, role);
+    const sessionProvider = sessionOverrides[role];
+    const projectProvider = projectConfig?.roles?.[role]?.provider;
+    let scope = "global";
+    if (sessionProvider) scope = "session";
+    else if (projectProvider) scope = "project";
+    return {
+      role,
+      provider: sessionProvider || resolved.provider || "-",
+      model: resolved.model || "-",
+      scope
+    };
+  });
+}
+
+export async function setAgent(role, provider, { global: isGlobal = false } = {}) {
+  if (!ASSIGNABLE_ROLES.includes(role)) {
+    throw new Error(`Unknown role "${role}". Valid roles: ${ASSIGNABLE_ROLES.join(", ")}`);
+  }
+  if (!VALID_PROVIDERS.includes(provider)) {
+    const bin = await checkBinary(provider);
+    if (!bin.ok) {
+      throw new Error(`Provider "${provider}" not found. Available: ${VALID_PROVIDERS.join(", ")}`);
+    }
+  }
+
+  if (isGlobal) {
+    const { config } = await loadConfig();
+    config.roles = config.roles || {};
+    config.roles[role] = config.roles[role] || {};
+    config.roles[role].provider = provider;
+    const configPath = getConfigPath();
+    await writeConfig(configPath, config);
+    return { role, provider, scope: "global", configPath };
+  }
+
+  // Session scope — write to the process-lifetime runtime-overrides store.
+  // Post-v2.7.5 this store lives at the session layer
+  // (src/session/runtime-overrides.js) instead of under src/mcp/, so the
+  // CLI no longer reaches into the MCP layer. The store is in-memory for
+  // the current process: MCP server long-lived invocations see the
+  // override across tool calls, CLI short-lived invocations naturally
+  // lose it at exit (that's fine — CLI users who want persistence pass
+  // --global or let it fall through to the project config below).
+  const { setRuntimeOverride } = await import("../session/runtime-overrides.js");
+  setRuntimeOverride(role, provider);
+
+  // Also mirror to the project config file so future CLI invocations pick
+  // it up. (The in-memory store alone is useless for CLI because the
+  // process exits immediately after.)
+  try {
+    const projectConfigPath = getProjectConfigPath();
+    const projectConfig = (await loadProjectConfig()) || {};
+    projectConfig.roles = projectConfig.roles || {};
+    projectConfig.roles[role] = projectConfig.roles[role] || {};
+    projectConfig.roles[role].provider = provider;
+    await writeConfig(projectConfigPath, projectConfig);
+    return { role, provider, scope: "project", configPath: projectConfigPath };
+  } catch {
+    // Project config not writable — still counts as a session-scope set
+    // because the in-memory store got updated above.
+    return { role, provider, scope: "session" };
+  }
+}
+
+export async function agentsCommand({ config, subcommand, role, provider, global: isGlobal }) {
+  if (subcommand === "set") {
+    if (!role || !provider) {
+      console.log("Usage: kj agents set <role> <provider> [--global]");
+      console.log(`Roles: ${ASSIGNABLE_ROLES.join(", ")}`);
+      console.log(`Providers: ${VALID_PROVIDERS.join(", ")}`);
+      return;
+    }
+    const result = await setAgent(role, provider, { global: isGlobal ?? true });
+    console.log(`Set ${result.role} -> ${result.provider} (scope: ${result.scope})`);
+    return result;
+  }
+
+  const projectConfig = await loadProjectConfig();
+  const agents = listAgents(config, {}, projectConfig);
+  const roleWidth = Math.max(...agents.map((a) => a.role.length), 4);
+  const provWidth = Math.max(...agents.map((a) => a.provider.length), 8);
+  const scopeWidth = Math.max(...agents.map((a) => a.scope.length), 5);
+  console.log(`${"Role".padEnd(roleWidth)}  ${"Provider".padEnd(provWidth)}  ${"Scope".padEnd(scopeWidth)}  Model`);
+  console.log("-".repeat(roleWidth + provWidth + scopeWidth + 14));
+  for (const a of agents) {
+    console.log(`${a.role.padEnd(roleWidth)}  ${a.provider.padEnd(provWidth)}  ${a.scope.padEnd(scopeWidth)}  ${a.model}`);
+  }
+  return agents;
+}
+

package/src/commands/architect.js

@@ -0,0 +1,123 @@
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { resolveRole } from "../config.js";
+import { buildArchitectPrompt, parseArchitectOutput } from "../prompts/architect.js";
+import { createCliProgressReporter } from "../utils/cli-progress.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+function formatLayers(layers, lines) {
+  lines.push("### Layers");
+  for (const l of layers) {
+    lines.push(typeof l === "string" ? `- ${l}` : `- **${l.name}**: ${l.responsibility || ""}`);
+  }
+  lines.push("");
+}
+
+function formatTradeoffs(tradeoffs, lines) {
+  lines.push("### Tradeoffs");
+  for (const t of tradeoffs) {
+    lines.push(`- **${t.decision}**: ${t.rationale || ""}`);
+    if (t.alternatives?.length) lines.push(`  Alternatives: ${t.alternatives.join(", ")}`);
+  }
+  lines.push("");
+}
+
+function formatApiContracts(contracts, lines) {
+  lines.push("### API Contracts");
+  for (const c of contracts) {
+    lines.push(`- \`${c.method || "GET"} ${c.endpoint}\``);
+  }
+  lines.push("");
+}
+
+function formatArchitecture(arch, lines) {
+  if (arch.type) lines.push(`**Type:** ${arch.type}`, "");
+  if (arch.layers?.length) formatLayers(arch.layers, lines);
+  if (arch.patterns?.length) {
+    lines.push("### Patterns");
+    for (const p of arch.patterns) lines.push(`- ${p}`);
+    lines.push("");
+  }
+  if (arch.tradeoffs?.length) formatTradeoffs(arch.tradeoffs, lines);
+  if (arch.apiContracts?.length) formatApiContracts(arch.apiContracts, lines);
+}
+
+function formatArchitect(result) {
+  const lines = [];
+  lines.push(`## Architecture Design`);
+  lines.push(`**Verdict:** ${result.verdict || "unknown"}`, "");
+
+  if (result.architecture) formatArchitecture(result.architecture, lines);
+
+  if (result.questions?.length) {
+    lines.push("### Clarification Questions");
+    for (const q of result.questions) lines.push(`- ${q.question || q}`);
+    lines.push("");
+  }
+
+  if (result.summary) lines.push(`---\n${result.summary}`);
+  return lines.join("\n");
+}
+
+export async function architectCommand({ task, config, logger, context, json }) {
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("architect", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const architectRole = resolveRole(config, "architect");
+    await assertAgentsAvailable([architectRole.provider]);
+    logger.info(`Architect (${architectRole.provider}) starting...`);
+    runLog.logText(`[architect] provider=${architectRole.provider}`);
+
+    const agent = createAgent(architectRole.provider, config, logger);
+    const prompt = await buildArchitectPrompt({ task, researchContext: context });
+    const progress = createCliProgressReporter({ role: "architect" });
+    let result;
+    try {
+      result = await withBrainRecovery({
+        agent, taskArgs: { prompt, onOutput: progress.onOutput, role: "architect" },
+        role: "architect", provider: architectRole.provider, logger,
+      });
+      progress.finish(result.ok ? "done" : (result.action || "failed"));
+    } catch (err) { progress.finish("failed"); throw err; }
+
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Architect failed");
+    }
+
+    const parsed = parseArchitectOutput(result.output);
+
+    if (json) {
+      console.log(JSON.stringify(parsed || result.output, null, 2));
+      return { ok: true };
+    }
+
+    if (parsed?.verdict) {
+      console.log(formatArchitect(parsed));
+    } else {
+      console.log(result.output);
+    }
+
+    // Persist ADRs from the architect's tradeoffs[] (v2.7.5). One ADR
+    // per tradeoff in Nygard format under `~/.kj/plans/_loose/adrs/`.
+    // Coder/reviewer in subsequent runs can pull the active ADRs into
+    // their prompt for context — done in a follow-up PR.
+    if (parsed?.architecture && config?.projectDir) {
+      try {
+        const { persistAdrsFromArchitecture } = await import("../plan/adr-generator.js");
+        const { adrs, paths } = await persistAdrsFromArchitecture({
+          projectDir: config.projectDir,
+          planId: null,                  // standalone architect → "_loose" bucket
+          architecture: parsed.architecture,
+        });
+        if (paths.length > 0) {
+          console.log(`\n${adrs.length} ADR${adrs.length === 1 ? "" : "s"} written:`);
+          for (const p of paths) console.log(`  - ${p}`);
+        }
+      } catch (err) {
+        logger.warn(`ADR write skipped: ${err.message}`);
+      }
+    }
+
+    logger.info("Architect completed.");
+    return { ok: true };
+  });
+}