karajan-code 2.17.0 → 2.18.0

package/src/utils/display/resume-hint.js

@@ -0,0 +1,41 @@
+/**
+ * Prints — as the LAST line of a stopped `kj run` / `kj plan` — the exact
+ * command to resume it. A halted run that never tells you how to restart
+ * it is the resilience gap this closes (resilience audit, Phase 1).
+ *
+ *   Quota hibernation → `kj standby resume <id>`
+ *   Solomon pause     → `kj resume <id> --answer "..."`
+ *   Stopped / failed  → `kj resume <id>`
+ *   Success           → nothing.
+ *
+ * @param {object} result          - the flow / command result
+ * @param {object} [opts]
+ * @param {(line:string)=>void} [opts.print] - sink, default console.log
+ */
+export function printResumeHint(result, { print = console.log } = {}) {
+  if (!result || typeof result !== "object") return;
+  const id = result.sessionId || result.session?.id || null;
+
+  if (result.hibernated === true) {
+    print("");
+    print("⏸  Run hibernated — provider quota exhausted.");
+    print(`   Resume when the quota resets:  kj standby resume ${id || "<session-id>"}`);
+    if (!id) print("   (run `kj standby list` to find the id)");
+    return;
+  }
+
+  if (result.paused === true && id) {
+    print("");
+    print("⏸  Run paused — waiting for your input.");
+    print(`   Resume:  kj resume ${id} --answer "<your answer>"`);
+    return;
+  }
+
+  // Stopped / failed / aborted but with a session on record → resumable.
+  // A successful run has approved === true and prints nothing.
+  if (id && result.approved !== true && result.paused !== true) {
+    print("");
+    print("✗  Run stopped before finishing.");
+    print(`   Resume:  kj resume ${id}`);
+  }
+}

package/src/utils/install-hints.js

@@ -0,0 +1,136 @@
+// Platform-aware install hints for external tools that `kj audit` /
+// `kj webperf` use (semgrep, osv-scanner, lighthouse).
+//
+// `kj doctor` calls these to render hint strings ("Install with:
+// pipx install semgrep") that match what's actually available on the
+// user's machine, rather than a generic "see docs" message. The same
+// metadata drives `kj install-tools` (HU2) — it decides which package
+// manager to invoke per tool.
+//
+// We probe each package manager once with `which`/`where`-style checks
+// and cache the result for the lifetime of the process.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * @typedef {"pipx"|"brew"|"go"|"npm"|"pip"|"apt"|"dnf"|"choco"|"scoop"|"docker"} PackageManager
+ */
+
+/** @type {Record<PackageManager, boolean>|null} */
+let cachedAvailability = null;
+
+const PROBES = [
+  ["pipx", ["--version"]],
+  ["brew", ["--version"]],
+  ["go", ["version"]],
+  ["npm", ["--version"]],
+  ["pip", ["--version"]],
+  ["apt", ["--version"]],
+  ["dnf", ["--version"]],
+  ["choco", ["--version"]],
+  ["scoop", ["--version"]],
+  ["docker", ["--version"]],
+];
+
+async function probeOne(bin, args) {
+  try {
+    await execFileAsync(bin, args, { timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect which package managers are reachable on PATH. Cached on first
+ * call. Exported for tests; production callers go through getInstallHint.
+ */
+export async function detectPackageManagers() {
+  if (cachedAvailability) return cachedAvailability;
+  const entries = await Promise.all(
+    PROBES.map(async ([bin, args]) => [bin, await probeOne(bin, args)]),
+  );
+  cachedAvailability = Object.fromEntries(entries);
+  return cachedAvailability;
+}
+
+/** Test helper — reset the cache between unit cases. */
+export function resetPackageManagerCache() {
+  cachedAvailability = null;
+}
+
+/**
+ * Returns the install command for a tool, preferring the highest-priority
+ * package manager available on the current system.
+ *
+ * The order encodes our recommendation when multiple managers can install
+ * the same tool. We prefer isolated installs (pipx, brew) over global
+ * `pip install` so we don't pollute the user's site-packages.
+ *
+ * @param {"semgrep"|"osv-scanner"|"lighthouse"|"docker"} tool
+ * @param {Record<PackageManager, boolean>} [available] — pre-computed availability; if omitted, detects.
+ * @returns {Promise<{ command: string|null, manager: PackageManager|null, manualUrl: string }>}
+ */
+export async function getInstallHint(tool, available = null) {
+  const avail = available || (await detectPackageManagers());
+  const candidates = INSTALL_CANDIDATES[tool] || [];
+  for (const { manager, command } of candidates) {
+    if (avail[manager]) return { command, manager, manualUrl: MANUAL_URLS[tool] };
+  }
+  // Nothing matched — fall back to the first candidate's command as a
+  // suggestion, so the user at least sees a working recipe.
+  const first = candidates[0];
+  return {
+    command: first ? first.command : null,
+    manager: null,
+    manualUrl: MANUAL_URLS[tool],
+  };
+}
+
+const INSTALL_CANDIDATES = {
+  semgrep: [
+    { manager: "pipx", command: "pipx install semgrep" },
+    { manager: "brew", command: "brew install semgrep" },
+    { manager: "pip", command: "pip install semgrep" },
+  ],
+  "osv-scanner": [
+    { manager: "go", command: "go install github.com/google/osv-scanner@latest" },
+    { manager: "brew", command: "brew install osv-scanner" },
+  ],
+  lighthouse: [
+    { manager: "npm", command: "npm install -g lighthouse" },
+  ],
+  docker: [
+    // Docker Desktop / Engine cannot be installed by a package manager
+    // reliably across platforms — always point users to the official docs.
+    // Listing brew anyway as a hint for macOS users.
+    { manager: "brew", command: "brew install --cask docker" },
+  ],
+};
+
+const MANUAL_URLS = {
+  semgrep: "https://semgrep.dev/docs/getting-started",
+  "osv-scanner": "https://google.github.io/osv-scanner/installation/",
+  lighthouse: "https://github.com/GoogleChrome/lighthouse#using-the-cli",
+  docker: "https://docs.docker.com/get-docker/",
+};
+
+/**
+ * Tools whose hint depends on the project stack. lighthouse is only
+ * relevant for frontend projects; suppressing the hint elsewhere keeps
+ * `kj doctor` output free of irrelevant noise.
+ *
+ * @param {string} tool
+ * @param {Object} stack — shape returned by detectProjectStack()
+ */
+export function appliesToStack(tool, stack) {
+  if (tool === "lighthouse") {
+    if (!stack) return false;
+    return Boolean(stack.isFrontend || stack.isFullstack);
+  }
+  // semgrep, osv-scanner, docker, sonar — always relevant.
+  return true;
+}

package/src/utils/process.js

@@ -152,6 +152,24 @@ export async function runCommand(command, args = [], options = {}) {
 function enrichResult(result, stdoutAccum, _stderrAccum) {
   if (result.timedOut) return result;
 
+  // execa with reject:false RESOLVES (does not throw) on a spawn
+  // failure — ENOENT (binary not in PATH), EACCES, etc. The result
+  // then carries exitCode null/undefined, an empty stderr, and the
+  // real cause only in `code` / `shortMessage`. Surface it: a missing
+  // agent CLI used to fail with a completely empty error message,
+  // leaving the user with "coder failed" and no idea what to install.
+  if (result.failed && result.exitCode == null && !result.signal) {
+    const reason = result.shortMessage || result.message
+      || `spawn failed${result.code ? ` (${result.code})` : ""}`;
+    return {
+      ...result,
+      exitCode: 1,
+      stdout: result.stdout || stdoutAccum,
+      stderr: result.stderr || reason,
+      spawnError: result.code || true,
+    };
+  }
+
   const killed = result.killed || !!result.signal;
   const signal = result.signal || null;
 

package/src/utils/rate-limit-detector.js

@@ -39,6 +39,26 @@ export function parseCooldown(message) {
     }
   }
 
+  // 5. Claude Code session / weekly limit: "resets 10:10pm" / "resets 4am"
+  //    (12-hour clock, no date). Resolve to the next wall-clock occurrence
+  //    of that time in the machine's local timezone. Claude Code reports
+  //    the reset in the user's local TZ and kj runs on the same machine,
+  //    so the parenthesised "(Europe/Madrid)" hint is ignored on purpose.
+  const ampmMatch = /reset(?:s|ting)?\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*([ap]m)\b/i.exec(
+    message
+  );
+  if (ampmMatch) {
+    let hour = Number.parseInt(ampmMatch[1], 10) % 12;
+    if (/pm/i.test(ampmMatch[3])) hour += 12;
+    const minute = ampmMatch[2] ? Number.parseInt(ampmMatch[2], 10) : 0;
+    if (hour < 24 && minute < 60) {
+      const target = new Date();
+      target.setHours(hour, minute, 0, 0);
+      if (target.getTime() <= Date.now()) target.setDate(target.getDate() + 1);
+      return { cooldownUntil: target.toISOString(), cooldownMs: target.getTime() - Date.now() };
+    }
+  }
+
   // 2. Relative seconds: "retry after 120 seconds" / "retry in 120s" / "Retry-After: 120"
   const secMatch = /(?:retry[\s-]*after|retry\s+in|wait)\s*:?\s*(\d+)\s*(?:seconds?|secs?|s\b)/i.exec(
     message
@@ -69,6 +89,8 @@ const RATE_LIMIT_PATTERNS = [
   { pattern: /usage limit/i, agent: "claude" },
   { pattern: /plan's usage limit/i, agent: "claude" },
   { pattern: /Claude Pro usage limit/i, agent: "claude" },
+  { pattern: /session limit/i, agent: "claude" },
+  { pattern: /weekly limit/i, agent: "claude" },
 
   // OpenAI / Codex CLI
   { pattern: /exceeded your current quota/i, agent: "codex" },

package/src/utils/run-registry.js

@@ -20,6 +20,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { writeJsonAtomicSync } from "./atomic-write.js";
 
 /**
  * Directorio raíz donde viven los registros de run.
@@ -54,7 +55,7 @@ export function registerRun(info = {}) {
       source: info.source || "cli",
       startedAt: new Date().toISOString(),
     };
-    fs.writeFileSync(filePath, JSON.stringify(entry, null, 2), "utf8");
+    writeJsonAtomicSync(filePath, entry);
     return runId;
   } catch {
     return null;