karajan-code 2.7.3 → 2.8.0

package/src/utils/cli-progress.js

@@ -0,0 +1,161 @@
+/**
+ * CLI progress reporter — prints live agent activity to the terminal while
+ * an agent (planner, coder, reviewer, auditor, …) is thinking.
+ *
+ * Context: commands like `kj plan --task-file spec.md` used to call
+ * `agent.runTask(...)` without an `onOutput` callback. The CLI then hung
+ * for 30 s – 3 min with zero feedback until a line like "Plan saved: …"
+ * finally appeared. Users assumed the command had deadlocked.
+ *
+ * This helper gives every CLI command the same live feedback the `kj run`
+ * orchestrator already emits: a header with role + start, a stream of
+ * tool calls / short text lines as the agent works, and a footer with
+ * outcome + elapsed time. It wraps `onOutput` so every command can pass
+ * `createCliProgressReporter({ role: "planner" }).onOutput` straight
+ * into the agent's runTask / reviewTask call.
+ *
+ * Output shape:
+ *
+ *   [planner] starting...
+ *     ▸ Read SPEC.md
+ *     ▸ Grep "architecture"
+ *     · Analyzing sections 1–5…
+ *     ▸ Write plan.json
+ *   [planner] done (42.8s)
+ *
+ * Design notes:
+ *   - Writes to `process.stderr` by default (so stdout is reserved for
+ *     structured output like `--json` mode).
+ *   - `onOutput` is shaped as `{ stream, line, kind }` to match the
+ *     contract Claude's `createStreamJsonFilter` emits — so passing
+ *     this reporter's `onOutput` into a runTask{…, onOutput} call Just
+ *     Works with Claude, Codex, Gemini, Aider and OpenCode (each one's
+ *     agent wrapper already normalizes its CLI's stream format into
+ *     that shape).
+ *   - `kind` is optional; when absent the default bullet is used.
+ *   - `quiet: true` turns the reporter into a no-op (useful when the
+ *     command is running under `--json` and should not pollute stdout).
+ */
+
+const ICONS = {
+  tool: "▸",      // ▸ right-pointing small triangle
+  text: "·",      // · middle dot
+  thinking: "…",  // …
+  heartbeat: "⠿", // braille dots — distinct from real activity icons
+};
+
+/**
+ * Rotating idle messages so the user knows the process is alive without
+ * the same string repeating every minute. Picked at random each tick;
+ * the previous one is held back so two ticks in a row never duplicate.
+ */
+const HEARTBEAT_LINES = [
+  "still working…",
+  "thinking through it…",
+  "wading through tokens…",
+  "asking the model nicely…",
+  "crunching the spec…",
+  "burning down the prompt…",
+  "kneading the context window…",
+  "still here, give me a sec…",
+  "the LLM is doing LLM things…",
+  "drafting, redrafting…",
+];
+
+/**
+ * Default cadence for the idle heartbeat. ~45s is short enough to feel
+ * responsive on a quiet planner run (Claude can think for 1-2 min on a
+ * complex spec) without spamming every few seconds.
+ */
+const DEFAULT_HEARTBEAT_MS = 45_000;
+
+/**
+ * @typedef {Object} CliProgressReporter
+ * @property {(event: { stream?: string, line: string, kind?: string }) => void} onOutput
+ * @property {(outcome?: string) => void} finish
+ */
+
+/**
+ * @param {Object} [opts]
+ * @param {string} [opts.role]     - label shown in the header/footer ("planner", "auditor", …).
+ *                                   Default: "agent".
+ * @param {NodeJS.WriteStream} [opts.stream]  - output destination. Default: process.stderr.
+ * @param {boolean} [opts.quiet]   - when true, nothing is printed (useful for --json mode).
+ * @param {number}  [opts.heartbeatMs] - silent interval before printing an
+ *   "alive" line. Defaults to 45 s. Set to 0 to disable the heartbeat
+ *   (useful in tests).
+ * @returns {CliProgressReporter}
+ */
+export function createCliProgressReporter(opts = {}) {
+  const {
+    role = "agent",
+    stream = process.stderr,
+    quiet = false,
+    heartbeatMs = DEFAULT_HEARTBEAT_MS,
+  } = opts;
+
+  if (quiet) {
+    return { onOutput: () => {}, finish: () => {} };
+  }
+
+  const startedAt = Date.now();
+  stream.write(`[${role}] starting...\n`);
+
+  // Idle heartbeat: a periodic timer that prints a varied "still alive"
+  // line whenever the agent goes quiet for longer than `heartbeatMs`.
+  // Reset on every real onOutput so heavy chatter doesn't trigger the
+  // duplicate. Always elapses to a different message than last time so
+  // two consecutive ticks never read the same.
+  let lastActivityAt = Date.now();
+  let lastHeartbeatIdx = -1;
+  let heartbeatTimer = null;
+
+  function pickHeartbeatLine() {
+    let idx;
+    do {
+      idx = Math.floor(Math.random() * HEARTBEAT_LINES.length);
+    } while (idx === lastHeartbeatIdx && HEARTBEAT_LINES.length > 1);
+    lastHeartbeatIdx = idx;
+    return HEARTBEAT_LINES[idx];
+  }
+
+  function tick() {
+    const idleFor = Date.now() - lastActivityAt;
+    if (idleFor < heartbeatMs) return;        // real activity reset us
+    const elapsed = Math.round((Date.now() - startedAt) / 1000);
+    stream.write(`  ${ICONS.heartbeat} ${pickHeartbeatLine()} (${elapsed}s)\n`);
+    lastActivityAt = Date.now();              // collapse next ticks
+  }
+
+  if (heartbeatMs > 0) {
+    heartbeatTimer = setInterval(tick, heartbeatMs);
+    if (typeof heartbeatTimer.unref === "function") heartbeatTimer.unref();
+  }
+
+  const onOutput = (event) => {
+    if (!event || typeof event !== "object") return;
+    const raw = typeof event.line === "string" ? event.line : "";
+    if (!raw) return;
+    // Strip trailing newline — we re-add our own.
+    const line = raw.replace(/\s+$/, "");
+    if (!line) return;
+    lastActivityAt = Date.now();
+    const icon = ICONS[event.kind] || ICONS.text;
+    stream.write(`  ${icon} ${line}\n`);
+  };
+
+  /**
+   * @param {string} [outcome]  default "done". Use "failed", "stopped", "timeout" etc.
+   */
+  const finish = (outcome = "done") => {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    const ms = Date.now() - startedAt;
+    const s = (ms / 1000).toFixed(1);
+    stream.write(`[${role}] ${outcome} (${s}s)\n`);
+  };
+
+  return { onOutput, finish };
+}

package/src/utils/cwd-confirm.js

@@ -0,0 +1,39 @@
+/**
+ * PR-F: ask the user "Run on $(pwd)?" before launching `kj run` from
+ * a terminal. Same defensive UX as `git push --force-with-lease`
+ * surfacing the branch — the user wants to know what they're aiming
+ * at before the rocket fires.
+ *
+ * The prompt is plain readline (no extra deps) and accepts any of:
+ *   y, yes, s, sí, ENTER  → true
+ *   n, no, ENTER+Esc      → false
+ *
+ * Skipped automatically by the caller when stdin/stdout are not a
+ * TTY, when --yes is set, or when --json is set. So this module is
+ * never called in CI / non-interactive contexts.
+ */
+
+import readline from "node:readline";
+
+/**
+ * @param {string} projectDir absolute path of the cwd / projectDir
+ * @returns {Promise<boolean>} true to continue, false to abort
+ */
+export async function confirmCwd(projectDir) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  // No emoji — keep terminal-safe even on basic Windows shells.
+  const question = `Karajan va a ejecutarse sobre:\n  ${projectDir}\n\n¿Continuar? [Y/n] `;
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const trimmed = String(answer || "").trim().toLowerCase();
+      // Empty answer = ENTER = accept the default = yes.
+      if (trimmed === "" || trimmed === "y" || trimmed === "yes" || trimmed === "s" || trimmed === "si" || trimmed === "sí") {
+        resolve(true);
+      } else {
+        resolve(false);
+      }
+    });
+    rl.on("SIGINT", () => { rl.close(); resolve(false); });
+  });
+}

package/src/utils/derive-project-name-from-cwd.js

@@ -0,0 +1,119 @@
+/**
+ * Derive a sensible default project name from the working directory,
+ * trying several signals in order:
+ *
+ *   1. `package.json` "name" field (most authoritative — that's what
+ *      the user already chose for their npm/pnpm project).
+ *   2. Git remote URL basename (strip protocol, user, `.git` suffix —
+ *      e.g. `git@github.com:foo/weather-dashboard.git` → `weather-dashboard`).
+ *   3. The cwd directory basename.
+ *
+ * Any of these is then prettified: kebab/snake → spaces, words
+ * capitalised. So `weather-dashboard` becomes `Weather Dashboard`.
+ *
+ * Returns null when no signal yields anything useful — caller can then
+ * fall back to its old "derive from task text" heuristic. This keeps
+ * the function pure / sync-friendly even though git/fs lookups are
+ * sync — they're cheap on a single-shot CLI startup.
+ *
+ * Why this matters: pre-fix, running `kj plan generate --task-file
+ * SPEC.md` inside `~/ws_demo/weather-dashboard` (an initialised git
+ * repo) suggested a project name made from the words of the SPEC's
+ * first sentence. That ignored both the directory the user was
+ * standing in and the repo they had just `git init`-ed. The right
+ * default is "the project I'm in", not "the topic of the document
+ * I just wrote".
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+/**
+ * Turn `weather-dashboard` / `weather_dashboard` / `WeatherDashboard`
+ * into `Weather Dashboard`. Preserves single-token names as-is when
+ * already title-cased.
+ */
+function prettifyName(raw) {
+  if (!raw || typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  // Insert space at camelCase boundaries, then split on -/_/whitespace.
+  const spaced = trimmed
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[-_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!spaced) return null;
+  return spaced
+    .split(" ")
+    .map((w) => (w.length ? w[0].toUpperCase() + w.slice(1) : w))
+    .join(" ");
+}
+
+function readPackageJsonName(cwd) {
+  try {
+    const pkgPath = path.join(cwd, "package.json");
+    if (!fs.existsSync(pkgPath)) return null;
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    if (typeof pkg.name === "string" && pkg.name.trim()) {
+      // Strip npm scope if present: @org/name → name
+      const unscoped = pkg.name.includes("/") ? pkg.name.split("/").pop() : pkg.name;
+      return unscoped;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function readGitRemoteBasename(cwd) {
+  try {
+    // -C points git at the cwd without us cd'ing the process.
+    // Audit follow-up: was using execSync with template-string interpolation
+    // of `cwd`. Switched to execFileSync with arg arrays so no interpolation
+    // reaches /bin/sh.
+    const out = execFileSync("git", ["-C", String(cwd), "config", "--get", "remote.origin.url"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf8",
+      timeout: 1500,
+    }).trim();
+    if (!out) return null;
+    // Strip optional protocol + user, .git suffix, trailing slash.
+    // Examples:
+    //   git@github.com:foo/weather-dashboard.git
+    //   https://github.com/foo/weather-dashboard
+    //   git@gitlab.com:team/weather-dashboard
+    const last = out.replace(/\.git\/?$/, "").split(/[/:]/).pop();
+    return last || null;
+  } catch {
+    return null;
+  }
+}
+
+function readCwdBasename(cwd) {
+  const base = path.basename(cwd || process.cwd());
+  if (!base || base === "/" || base === ".") return null;
+  return base;
+}
+
+/**
+ * Try every signal in priority order and return the first prettified
+ * non-empty result. Returns null when nothing useful is available.
+ *
+ * @param {string} [cwd] — defaults to process.cwd()
+ * @returns {string|null}
+ */
+export function deriveProjectNameFromCwd(cwd = process.cwd()) {
+  const fromPkg = prettifyName(readPackageJsonName(cwd));
+  if (fromPkg) return fromPkg;
+  const fromGit = prettifyName(readGitRemoteBasename(cwd));
+  if (fromGit) return fromGit;
+  const fromCwd = prettifyName(readCwdBasename(cwd));
+  if (fromCwd) return fromCwd;
+  return null;
+}
+
+// Exposed for unit tests so they can drive the individual signals
+// without real filesystem / git side-effects.
+export const __test__ = { prettifyName, readPackageJsonName, readGitRemoteBasename, readCwdBasename };