karajan-code 2.7.4 → 2.9.0

package/src/utils/prompt-project-name.js

@@ -0,0 +1,35 @@
+/**
+ * PR-H: ask the user "Nombre del proyecto?" before saving a plan.
+ *
+ * The user's words: "El nombre del board debería de deducirse del
+ * cwd o del nombre del plan, pero no darlo por hecho, preguntar al
+ * usuario siempre, por si quiere cambiarlo."
+ *
+ * Pre-fills the prompt with the suggested name (derived from the
+ * task / cwd) so accepting the default is one ENTER away. Returns
+ * the trimmed answer; falls back to the default when the user just
+ * hits ENTER (empty input).
+ *
+ * Caller is responsible for skipping this when stdin/stdout are not
+ * a TTY, when --yes is set, or when --json is set.
+ */
+
+import readline from "node:readline";
+
+/**
+ * @param {string} defaultName — pre-filled suggestion shown in [brackets]
+ * @returns {Promise<string>} the user's answer (defaults to defaultName)
+ */
+export async function promptProjectName(defaultName) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const fallback = String(defaultName || "").trim();
+  const hint = fallback ? ` [${fallback}]` : "";
+  return new Promise((resolve) => {
+    rl.question(`Nombre del proyecto${hint}: `, (answer) => {
+      rl.close();
+      const trimmed = String(answer || "").trim();
+      resolve(trimmed || fallback);
+    });
+    rl.on("SIGINT", () => { rl.close(); resolve(fallback); });
+  });
+}

package/src/utils/role-assigner.js

@@ -128,4 +128,4 @@ export function applyRoleAssignments(config, assignments) {
   return config;
 }
 
-export { CAPABILITY_TIERS, ROLE_PREFERENCES };
+export { CAPABILITY_TIERS };

package/src/utils/run-context.js

@@ -0,0 +1,75 @@
+/**
+ * Per-run context store — makes module-level state in `utils/git.js`,
+ * `review/diff-generator.js`, etc. safe under concurrent `runFlow` calls.
+ *
+ * Pre-v2.7.5 the orchestrator mutated module-scope variables at pipeline
+ * start:
+ *   setDiffRunner(rtkRunner); setDiffProjectDir(diffScope);
+ *   setGitRunner(rtkRunner);
+ *   // …later…
+ *   // every git/diff op reads those globals
+ *
+ * That is fine for a single-threaded CLI invocation but corrupts when the
+ * MCP server fields two `kj_run` tool calls in parallel: each run would
+ * overwrite the others' runner/projectDir during setup, and subsequent
+ * reads would see a mix.
+ *
+ * TSK-0338 isolates that state to a per-run AsyncLocalStorage scope.
+ * `runFlow` wraps its execution in `withRunContext(ctx, fn)`, and the
+ * read paths in git.js / diff-generator.js look up
+ * `getRunContext()?.runner` before falling back to the module-level
+ * `_runner` (kept as a back-compat entry for callers outside a
+ * `runFlow` — CLI helpers, tests — that set state directly).
+ *
+ * What lives here vs. elsewhere:
+ *   - `runContext` (this module) — runner, projectDir, snapshot — the
+ *     pieces git/diff touches synchronously on every op.
+ *   - `PipelineContext` (src/orchestrator/pipeline-context.js) — the
+ *     richer structure ferried between stages. The two could merge
+ *     eventually, but PipelineContext is created after preflight, and
+ *     the runner/projectDir must be in scope BEFORE preflight runs
+ *     (which itself calls git commands).
+ *
+ * The invariant `tests/orchestrator/concurrent-runs.test.js` exercises
+ * the isolation: two parallel `withRunContext(A, …)` and
+ * `withRunContext(B, …)` see their own runner, not each other's.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * @typedef {Object} RunContext
+ * @property {((command: string, args?: string[], options?: object) => Promise<object>)|null} [runner]
+ *   Pipeline-scoped command runner. When present, git.js + diff-generator.js
+ *   route commands through it instead of the default `runCommand`.
+ * @property {string|null} [projectDir]
+ *   Directory scope for `git diff`. Prevents leaking unrelated subdir
+ *   changes when `kj run` is invoked from a subpath of a monorepo.
+ * @property {Map<string, string>|null} [snapshot]
+ *   Pre-coder filesystem snapshot for snapshot-based diff when git is
+ *   unavailable (greenfield projects with no initial commit).
+ */
+
+const runStore = new AsyncLocalStorage();
+
+/**
+ * Run `fn` with `ctx` as the active RunContext. All reads of
+ * `getRunContext()` inside (including from awaited callees) see `ctx`.
+ * Concurrent `withRunContext` invocations are fully isolated from each
+ * other — that's what AsyncLocalStorage guarantees.
+ *
+ * @param {RunContext} ctx
+ * @param {() => Promise<any>} fn
+ * @returns {Promise<any>}
+ */
+export function withRunContext(ctx, fn) {
+  return runStore.run(ctx ?? {}, fn);
+}
+
+/**
+ * @returns {RunContext|undefined} the active RunContext, or undefined when
+ *   called outside any `withRunContext` scope (legacy CLI paths, tests).
+ */
+export function getRunContext() {
+  return runStore.getStore();
+}

package/src/utils/run-log.js

@@ -57,6 +57,18 @@ export function createRunLog(projectDir) {
   // Truncate/create the log file
   fs.writeFileSync(logPath, `--- Karajan run started at ${new Date().toISOString()} ---\n`);
 
+  // Audit recommendation (perf-LOW): suggested createWriteStream + queue.
+  // Tried it; broke the contract. `readRunLog` (used by `kj_status`,
+  // `kj-tail`, and the HU board's chokidar tick) reads the file with
+  // `fs.readFileSync` and expects every prior write to be visible the
+  // moment the writer's `logEvent()` returns — which is what
+  // `fs.writeSync(fd, ...)` guarantees and `stream.write()` does NOT.
+  //
+  // The current shape is already opened-once: `fs.openSync(logPath, "a")`
+  // returns an fd that every subsequent `fs.writeSync` reuses (no extra
+  // open/close per call). The hot-path complaint was about the FALLBACK
+  // `fs.appendFileSync` line, which only fires when openSync itself
+  // fails (rare; FS error or RO mount).
   let fd = null;
   try {
     fd = fs.openSync(logPath, "a");

package/src/utils/task-file.js

@@ -49,7 +49,7 @@ export async function readTaskFile(filePath, opts = {}) {
   try {
     stat = await fs.stat(resolved);
   } catch (err) {
-    throw new Error(`Task file not found: ${resolved} (${err.code || err.message})`);
+    throw new Error(`Task file not found: ${resolved} (${err.code || err.message})`, { cause: err });
   }
   if (!stat.isFile()) {
     throw new Error(`Task file is not a regular file: ${resolved}`);

package/src/utils/telemetry.js

@@ -32,7 +32,19 @@ export async function sendTelemetryEvent(eventName, data, config) {
     } finally {
       clearTimeout(timeout);
     }
-  } catch { /* never block, never fail */ }
+  } catch (err) {
+    // Audit follow-up: was a silent catch{}. Telemetry MUST stay
+    // fire-and-forget (never block the user's pipeline, never throw),
+    // but completely silent failures hide DNS/network bugs that matter
+    // when debugging the telemetry pipeline itself. Surface the error
+    // to stderr only when KJ_DEBUG=1 is explicitly set, so normal runs
+    // are still silent.
+    if (process.env.KJ_DEBUG === "1") {
+      // Stderr (not console — telemetry runs from CLI commands and is
+      // legitimate user-visible diagnostic output under KJ_DEBUG).
+      process.stderr.write(`[telemetry-debug] ${eventName}: ${err.message}\n`);
+    }
+  }
 }
 
 /**

package/src/webperf/devtools-detect.js

@@ -3,7 +3,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
-import { isOpenSkillsAvailable, installSkill, listSkills } from "../skills/openskills-client.js";
+import { isOpenSkillsAvailable, listSkills } from "../skills/openskills-client.js";
 
 /** Skill names relevant for WebPerf analysis. Already installed globally via openskills. */
 export const WEBPERF_SKILLS = [

package/templates/coder-rules.md

@@ -22,3 +22,16 @@
 - Keep changes minimal and focused on the task.
 - Do not modify code unrelated to the task.
 - Follow existing code conventions and patterns in the repository.
+
+## Tests location (MANDATORY)
+
+- Tests live in a top-level `tests/` directory mirroring `src/` (e.g. a function in
+  `src/services/foo.js` is tested by `tests/services/foo.test.js`).
+- DO NOT scatter `*.test.js` files inside `src/` unless the project's local
+  `.karajan/coder-rules.md` explicitly overrides this.
+- When generating a project from scratch:
+  - Create `tests/` and point the test runner at it (`include: ['tests/**/*.test.{js,ts}']`).
+  - Exclude `tests/` from the production bundle.
+  - If you write `sonar-project.properties`, set `sonar.tests=tests` AND make sure
+    that directory exists. Never declare a path that doesn't exist — Sonar will
+    refuse to scan and the run will fail every iteration with the same error.

package/templates/roles/coder.md

@@ -28,6 +28,40 @@ Before reporting done, verify that ALL parts of the task are addressed:
 - If you write tests first (TDD), the implementation MUST make those tests pass.
 - Do NOT commit code that doesn't compile or doesn't pass tests.
 
+## Test file location (MANDATORY convention)
+
+Tests live in a top-level `tests/` directory (or `test/` if the project already
+established that convention). Mirror the source tree under it: a function in
+`src/services/foo.js` is tested by `tests/services/foo.test.js`, NOT by a
+sibling file inside `src/`. This is the default Karajan convention; the only
+exception is when a `.karajan/coder-rules.md` in the project repo explicitly
+overrides it.
+
+Why this matters:
+- Reviewers and humans look in `tests/`, not next to source. Buried tests get
+  treated as "no tests exist" even when they do.
+- Sonar's default `sonar.tests=tests` (and equivalents in other scanners) only
+  finds tests there. Putting tests under `src/` produces empty coverage and
+  scanner errors.
+- Bundlers (Vite, esbuild, Astro, etc.) skip a `tests/` tree by default;
+  in-source tests can leak into production bundles unless every config
+  explicitly excludes them.
+
+When generating a project from scratch:
+- Create the `tests/` directory.
+- Configure the test runner to look there (`include: ['tests/**/*.test.{js,ts}']`
+  in vitest, `testMatch` in jest, etc.).
+- Configure the build tool to ignore it (`vite.config` excludes, etc.).
+- Configure Sonar (if `sonar-project.properties` is generated) with
+  `sonar.sources=src`, `sonar.tests=tests`, and verify both directories exist
+  before writing the file. NEVER write `sonar.tests=tests` without a `tests/`
+  folder — Sonar will refuse to scan and the run will burn iterations.
+
+When modifying an existing project:
+- Match whatever convention is already in place; do NOT introduce a second
+  one. If `tests/` exists, put new tests there. If only `src/**/*.test.js`
+  exists, follow that.
+
 ## Secrets and environment variables
 
 - NEVER hardcode API keys, tokens, passwords, secrets, or credentials in source code. No exceptions, not even for public keys or test keys.

package/templates/roles/repairer.md

@@ -0,0 +1,94 @@
+# Repairer Role
+
+You are the **Repairer** in a multi-role AI pipeline. Your single job is
+to look at a **failing acceptance test** that the coder has tried and
+failed to satisfy across multiple iterations, decide whether the test
+**itself** is broken (vs. the code), and — if it is — return a corrected
+test that preserves the original intent.
+
+## When you are invoked
+
+The Brain calls you when an HU's acceptance test has failed N
+consecutive iterations with the same error signature, and the coder
+cannot make it pass. The Brain has classified the failure as
+*possibly infeasible* (the test may itself be the problem, not the
+implementation under test).
+
+## Your task
+
+You receive:
+
+- The failing acceptance test (string or `{ type, content }`).
+- The most recent error output from running it.
+- The HU's title and scope so you understand intent.
+- A list of all of the HU's other acceptance tests (so any rewrite
+  stays consistent with them).
+
+Decide:
+
+1. **fixable**: the test has a syntactic / structural bug you can
+   correct (e.g. invalid `jq` query, wrong shell quoting, unreachable
+   path assumed to exist, command name typo). Return the corrected
+   test content.
+2. **unfixable**: the test is fundamentally impossible (asks for a
+   contradiction, depends on an external service that's unreachable,
+   the HU's intent itself is wrong). Escalate.
+
+## Diagnostic checklist (apply in order)
+
+For shell tests:
+- Does `bash -n -c '<cmd>'` parse? If not → syntax fix.
+- Does the test invoke `jq`? Run `echo '{}' | jq <query>` to check
+  the jq query parses. If "Cannot index array with string", the test
+  likely uses `as $n | .field` after a transform — restructure with
+  `as $r` binding the root.
+- Does the test reference a file path that the HU explicitly creates?
+  If the path doesn't match what the HU actually produces, fix the
+  path.
+- Does the test depend on a tool not in the project's runtime
+  (`pnpm` vs `npm` vs `yarn`, `python3` vs `python`)? Match what's
+  actually used.
+
+For Gherkin tests:
+- Are Given/When/Then well-formed? If a step is ambiguous, narrow it.
+- Does the test rely on state set up by another scenario? Inline the
+  setup or mark the scenario as needing the upstream HU.
+
+## When NOT to "fix"
+
+- The test is correct and the code is wrong → return `unfixable` with
+  reason `"test is correct; coder must fix the implementation"`. The
+  Brain will treat this as a normal failure, not as a repair.
+- The HU's intent contradicts the test (the HU asks to do A, the test
+  checks B) → return `unfixable` with reason `"intent mismatch"`.
+  This is an FDE problem, not a Repairer problem.
+
+## Output format
+
+Return ONLY a single valid JSON object:
+
+```json
+{
+  "verdict": "fixable" | "unfixable",
+  "fixed_test": { "type": "shell" | "gherkin", "content": "..." } | null,
+  "reason": "one-sentence explanation of what was wrong (or why unfixable)",
+  "diagnostics": ["any tool-output snippets you used to diagnose"]
+}
+```
+
+- When `verdict: "fixable"`, `fixed_test` is REQUIRED and `reason`
+  describes the bug class (e.g. `"jq query had 'as $n | .field' on
+  the array tail"`).
+- When `verdict: "unfixable"`, `fixed_test` is `null` and `reason`
+  explains why (`"test depends on Sonar 9000 reachable, network
+  isolated"`, `"intent mismatch — HU asks X, test checks Y"`).
+
+## Constraints
+
+- NEVER soften an assertion just to make it pass. If the test was
+  asking the right question, your job is to make it ask it correctly,
+  not weakly.
+- NEVER rewrite a test to pass against the CURRENT code. The test
+  defines the contract; the code is what's measured against it.
+- Keep changes minimal. One bug at a time. If the test has multiple
+  problems, fix the most blocking one first.