karajan-code 2.5.0 → 2.6.1

package/src/checks/types.js

@@ -0,0 +1,105 @@
+/**
+ * Shared check schema for doctor/preflight subsystem.
+ *
+ * A Check describes an environment requirement (binary present, port free,
+ * token configured, MCP reachable...). Each check can optionally remediate
+ * itself when it fails, using one of 4 strategies:
+ *
+ *   - "auto"   → fix without asking. Use for non-invasive, reversible changes
+ *                (in-memory runtime overrides, starting existing services,
+ *                creating files under ~/.karajan/, etc.)
+ *   - "prompt" → ask user before fixing. Use for invasive changes that touch
+ *                the user's system outside Karajan's scope (global npm install,
+ *                writing kj.config.yml, `gh auth login`, etc.)
+ *   - "manual" → cannot auto-fix, only report a hint (Node runtime upgrade,
+ *                missing Docker, missing API key with no admin creds)
+ *   - "none"   → informational check, always OK (Karajan version, feature
+ *                disabled by config)
+ */
+
+/**
+ * @typedef {Object} CheckResult
+ * @property {boolean} ok                        - true if check passes
+ * @property {"fail"|"warn"|"info"} [severity]   - relevant when !ok; default "fail"
+ * @property {string} detail                     - human-readable status
+ * @property {string} [fix]                      - remediation hint shown when manual or user declines
+ * @property {Object} [extra]                    - structured data consumed by remediate (e.g. occupant PID, host, roles)
+ */
+
+/**
+ * @typedef {Object} RemediationContext
+ * @property {Object} config                     - resolved Karajan config
+ * @property {AbortSignal} [signal]              - cancellation
+ * @property {Object} extra                      - check's CheckResult.extra
+ * @property {Object} logger                     - logger instance
+ */
+
+/**
+ * @typedef {Object} RemediationResult
+ * @property {boolean} fixed                     - true if remediation succeeded
+ * @property {string} detail                     - what was done, human-readable
+ * @property {Object} [changes]                  - runtime config overrides to merge into the active session
+ */
+
+/**
+ * @typedef {Object} Check
+ * @property {string} name                       - slug, unique across all checks (e.g. "node-version")
+ * @property {string} label                      - human label (e.g. "Node.js runtime")
+ * @property {"auto"|"prompt"|"manual"|"none"} strategy
+ * @property {(ctx: { config: Object }) => Promise<CheckResult>} detect
+ * @property {(ctx: RemediationContext) => Promise<RemediationResult>} [remediate]
+ * @property {string} [describe]                 - shown to user when strategy is "prompt"
+ * @property {(config: Object) => boolean} [applies]  - if false, check is SKIPPED (lazy evaluation). Default: always applies.
+ */
+
+/**
+ * @typedef {Object} CheckReport
+ * @property {string} name
+ * @property {string} label
+ * @property {"OK"|"FIXED"|"WARN"|"FAIL"|"SKIPPED"|"TIMEOUT"} status
+ * @property {"auto"|"prompt"|"manual"|"none"} strategy
+ * @property {string} detail                     - detect detail or remediate detail when FIXED
+ * @property {string} [fix]                      - remediation hint for FAIL/WARN
+ * @property {number} runMs                      - total time (detect + remediate + re-verify)
+ * @property {boolean} [cached]                  - future: served from cache
+ */
+
+/**
+ * @typedef {Object} RunReport
+ * @property {CheckReport[]} checks
+ * @property {Object} overrides                  - merged runtime overrides from auto-remediations
+ * @property {number} totalMs
+ * @property {{ ok: number, fixed: number, warn: number, fail: number, skipped: number, timeout: number }} summary
+ */
+
+/**
+ * Status constants.
+ */
+export const STATUS = Object.freeze({
+  OK: "OK",
+  FIXED: "FIXED",
+  WARN: "WARN",
+  FAIL: "FAIL",
+  SKIPPED: "SKIPPED",
+  TIMEOUT: "TIMEOUT",
+});
+
+export const STRATEGY = Object.freeze({
+  AUTO: "auto",
+  PROMPT: "prompt",
+  MANUAL: "manual",
+  NONE: "none",
+});
+
+export const SEVERITY = Object.freeze({
+  FAIL: "fail",
+  WARN: "warn",
+  INFO: "info",
+});
+
+/**
+ * Whether the final status blocks the pipeline (for preflight).
+ */
+export function isBlocking(status) {
+  return status === STATUS.FAIL || status === STATUS.TIMEOUT;
+}

package/src/cli.js

@@ -128,6 +128,10 @@ program
   .option("--no-smart-models", "Disable smart model selection")
   .option("--design", "Activate design refactoring mode (impeccable role applies design changes)")
   .option("--domain <text-or-path>", "Domain knowledge: inline text or path to .md file")
+  .option("--skills-mode <mode>", "Skill detection mode: auto|regex|semantic|none (default: auto)")
+  .option("--brain <mode>", "Brain decisor: on|off (default: on). When off, only legacy flags drive routing.")
+  .option("--skip-role <role...>", "Force one or more roles OFF regardless of triage (e.g. --skip-role tester security)")
+  .option("--force-role <role...>", "Force one or more roles ON regardless of triage")
   .option("--dry-run", "Show what would be executed without running anything")
   .option("--json", "Output JSON only (no styled display)")
   .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")
@@ -172,9 +176,22 @@ program
 
 program
   .command("doctor")
-  .description("Check environment requirements")
-  .action(async () => {
-    await withConfig("doctor", {}, doctorCommand);
+  .description("Check environment requirements and auto-remediate when possible")
+  .option("--check-only", "Detect issues without applying fixes")
+  .option("-y, --yes", "Auto-confirm prompts for invasive remediations (CI mode)")
+  .option("--json", "Emit machine-readable JSON instead of human output")
+  .option("--verbose", "Include fix hints and timing for every check")
+  .action(async (flags) => {
+    const exitCode = await withConfig("doctor", {}, (ctx) =>
+      doctorCommand({
+        ...ctx,
+        checkOnly: !!flags.checkOnly,
+        yes: !!flags.yes,
+        json: !!flags.json,
+        verbose: !!flags.verbose,
+      })
+    );
+    if (Number.isInteger(exitCode)) process.exit(exitCode);
   });
 
 program
@@ -198,6 +215,15 @@ program
     await reportCommand(flags);
   });
 
+program
+  .command("skills [action]")
+  .description("Manage the local OpenSkills cache (actions: list | clear-cache)")
+  .action(async (action) => {
+    const { skillsCommand } = await import("./commands/skills.js");
+    const exitCode = await skillsCommand({ action: action || "list" });
+    if (Number.isInteger(exitCode)) process.exit(exitCode);
+  });
+
 program
   .command("roles [subcommand] [role]")
   .description("List pipeline roles or show role template instructions")

package/src/commands/board.js

@@ -115,6 +115,29 @@ export async function boardStatus(port = 4000) {
   };
 }
 
+/**
+ * Render a highlighted cyan box with the HU Board URL + optional project name.
+ * Centralizes the banner used by both the init-time auto-start (flow-runner.js)
+ * and the post-planner auto-HU generation safety net so they stay in sync.
+ *
+ * @param {Object} params
+ * @param {string} params.url           - "http://localhost:4000"
+ * @param {string} params.status        - "started" | "already running"
+ * @param {string} [params.projectName] - optional project label
+ * @returns {string} ANSI-escaped box ready for console.log
+ */
+export function renderBoardBanner({ url, status, projectName }) {
+  const title = projectName ? `  Project: \u001b[1m${projectName}\u001b[0m` : null;
+  const lines = [
+    "",
+    "\u001b[36m\u256d\u2500 HU Board \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e",
+    `\u001b[36m\u2502\u001b[0m  \u001b[1m${status}\u001b[0m  \u001b[4m${url}\u001b[0m`,
+  ];
+  if (title) lines.push(`\u001b[36m\u2502\u001b[0m${title}`);
+  lines.push("\u001b[36m\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\u001b[0m", "");
+  return lines.join("\n");
+}
+
 export async function boardCommand({ action = "start", port = 4000, logger }) {
   switch (action) {
     case "start": {