@karajan-family/code 4.21.0

package/src/sonar/scanner.js

@@ -0,0 +1,307 @@
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { runCommand } from "../utils/process.js";
+import { sonarUp } from "./manager.js";
+import { resolveSonarProjectKey } from "./project-key.js";
+import {
+  resolveSonarHost,
+  resolveSonarToken as resolveToken,
+  resolveSonarCredentials,
+} from "./config-resolver.js";
+
+async function findNativeSonarScanner() {
+  const which = await runCommand("sh", ["-c", "command -v sonar-scanner"]);
+  if (which.exitCode === 0) {
+    const bin = String(which.stdout || "").trim();
+    if (bin) return bin;
+  }
+  return null;
+}
+
+export async function pickSonarScanner(scannerConfig = {}, deps = {}) {
+  const find = deps.findNativeSonarScanner || findNativeSonarScanner;
+  const arch = deps.arch || os.arch();
+  const forced = String(scannerConfig.command || "").trim().toLowerCase();
+  if (forced === "docker") return { type: "docker" };
+  if (forced === "native" || forced === "sonar-scanner" || forced.endsWith("/sonar-scanner")) {
+    const bin = (forced === "native" || forced === "sonar-scanner") ? await find() : forced;
+    if (bin) return { type: "native", bin };
+    return { type: "docker", reason: "native sonar-scanner not found on PATH" };
+  }
+  if (arch === "arm64") {
+    const bin = await find();
+    if (bin) return { type: "native", bin, reason: "ARM64 host — preferring native binary" };
+  }
+  return { type: "docker" };
+}
+
+export function buildScannerOpts(projectKey, scanner = {}) {
+  const opts = [`-Dsonar.projectKey=${projectKey}`];
+  if (scanner.sources) opts.push(`-Dsonar.sources=${scanner.sources}`);
+  if (scanner.exclusions) opts.push(`-Dsonar.exclusions=${scanner.exclusions}`);
+  if (scanner.test_inclusions) opts.push(`-Dsonar.test.inclusions=${scanner.test_inclusions}`);
+  if (scanner.coverage_exclusions) opts.push(`-Dsonar.coverage.exclusions=${scanner.coverage_exclusions}`);
+  if (scanner.javascript_lcov_report_paths) {
+    opts.push(`-Dsonar.javascript.lcov.reportPaths=${scanner.javascript_lcov_report_paths}`);
+  }
+  const rules = scanner.disabled_rules || [];
+  if (rules.length > 0) {
+    // KJC-BUG-0139: the list property is declared ONCE — one `multicriteria=`
+    // per rule was last-wins, silently un-ignoring every rule but the final one.
+    opts.push(`-Dsonar.issue.ignore.multicriteria=${rules.map((_, i) => `e${i + 1}`).join(",")}`);
+    rules.forEach((rule, i) => {
+      opts.push(
+        `-Dsonar.issue.ignore.multicriteria.e${i + 1}.ruleKey=${rule}`,
+        `-Dsonar.issue.ignore.multicriteria.e${i + 1}.resourceKey=**/*`
+      );
+    });
+  }
+  return opts.join(" ");
+}
+
+function normalizeScannerConfig(scanner = {}) {
+  const out = { ...scanner };
+  if (typeof out.sources === "string" && out.sources.trim()) {
+    const existing = out.sources
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .filter((entry) => fs.existsSync(entry));
+
+    if (existing.length > 0) {
+      out.sources = existing.join(",");
+    }
+  }
+  return out;
+}
+
+function parseJsonSafe(text) {
+  try {
+    return JSON.parse(text);
+  } catch { /* invalid JSON */
+    return null;
+  }
+}
+
+async function validateAdminCredentials(host, user, password) {
+  const res = await runCommand("curl", [
+    "-sS",
+    "-u",
+    `${user}:${password}`,
+    `${host}/api/authentication/validate`
+  ]);
+  if (res.exitCode !== 0) return false;
+  const parsed = parseJsonSafe(res.stdout);
+  return Boolean(parsed?.valid);
+}
+
+async function generateUserToken(host, user, password) {
+  const tokenName = `karajan-${Date.now()}`;
+  const res = await runCommand("curl", [
+    "-sS",
+    "-u",
+    `${user}:${password}`,
+    "-X",
+    "POST",
+    "--data-urlencode",
+    `name=${tokenName}`,
+    `${host}/api/user_tokens/generate`
+  ]);
+  if (res.exitCode !== 0) return null;
+  const parsed = parseJsonSafe(res.stdout);
+  return parsed?.token || null;
+}
+
+function coverageConfig(config) {
+  return config?.sonarqube?.coverage || {};
+}
+
+function checkLcovExists(lcovPath, blockOnFailure, stdout = "") {
+  if (!lcovPath) return { ok: true, scannerPatch: {} };
+  if (fs.existsSync(lcovPath)) {
+    return { ok: true, scannerPatch: { javascript_lcov_report_paths: lcovPath } };
+  }
+  if (blockOnFailure) {
+    return { ok: false, exitCode: 1, stdout, stderr: `Configured lcov report path does not exist: ${lcovPath}` };
+  }
+  return { ok: true, scannerPatch: {} };
+}
+
+function handleCoverageNoCommand(lcovPath, blockOnFailure) {
+  if (!lcovPath) {
+    return {
+      ok: false, exitCode: 1, stdout: "",
+      stderr: "Sonar coverage is enabled but neither coverage.command nor coverage.lcov_report_path is configured."
+    };
+  }
+  return checkLcovExists(lcovPath, blockOnFailure);
+}
+
+async function maybeRunCoverage(config) {
+  const coverage = coverageConfig(config);
+  if (!coverage.enabled) return { ok: true, scannerPatch: {} };
+
+  const lcovPath = String(coverage.lcov_report_path || "").trim();
+  const blockOnFailure = coverage.block_on_failure !== false;
+
+  if (!String(coverage.command || "").trim()) {
+    return handleCoverageNoCommand(lcovPath, blockOnFailure);
+  }
+
+  const command = String(coverage.command || "").trim();
+  const timeout = Number(coverage.timeout_ms) > 0 ? Number(coverage.timeout_ms) : 5 * 60 * 1000;
+  const run = await runCommand("bash", ["-lc", command], { timeout });
+
+  if (run.exitCode !== 0) {
+    if (blockOnFailure) {
+      return { ok: false, exitCode: run.exitCode, stdout: run.stdout || "", stderr: run.stderr || "Coverage command failed" };
+    }
+    return { ok: true, scannerPatch: {} };
+  }
+
+  return checkLcovExists(lcovPath, blockOnFailure, run.stdout || "");
+}
+
+async function resolveSonarTokenWithFallback(config, apiHost) {
+  const explicitToken = resolveToken(config);
+  if (explicitToken) return explicitToken;
+
+  const { user: adminUser, passwords } = await resolveSonarCredentials(config);
+  if (!adminUser || passwords.length === 0) return null;
+
+  for (const password of passwords) {
+    const valid = await validateAdminCredentials(apiHost, adminUser, password);
+    if (!valid) continue;
+    const token = await generateUserToken(apiHost, adminUser, password);
+    if (token) return token;
+  }
+
+  return null;
+}
+
+async function ensureSonarProjectProperties(cwd = process.cwd()) {
+  const propsPath = path.join(cwd, "sonar-project.properties");
+  try {
+    await fsPromises.access(propsPath);
+    return; // already exists
+  } catch {
+    // Auto-generate based on project structure
+    let pkg = {};
+    try {
+      const raw = await fsPromises.readFile(path.join(cwd, "package.json"), "utf8");
+      pkg = JSON.parse(raw);
+    } catch {
+      // no package.json or invalid JSON — use defaults
+    }
+    const projectKey = (pkg.name || path.basename(cwd)).replaceAll(/[^a-zA-Z0-9_.-]/g, "_");
+    const props = [
+      `sonar.projectKey=${projectKey}`,
+      `sonar.projectName=${pkg.name || path.basename(cwd)}`,
+      `sonar.sources=src`,
+      `sonar.tests=tests`,
+      `sonar.javascript.lcov.reportPaths=coverage/lcov.info`,
+      `sonar.exclusions=**/node_modules/**,**/dist/**,**/build/**,**/coverage/**`,
+    ].join("\n");
+    await fsPromises.writeFile(propsPath, props + "\n", "utf8");
+  }
+}
+
+export async function runSonarScan(config, projectKey = null) {
+  let effectiveProjectKey;
+  try {
+    effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey });
+  } catch (error) {
+    return {
+      ok: false,
+      projectKey: null,
+      stdout: "",
+      stderr: error?.message || String(error),
+      exitCode: 1
+    };
+  }
+  const sonarConfig = config?.sonarqube || {};
+  const rawHost = sonarConfig.host || "http://localhost:9000";
+  const isExternalSonar = sonarConfig.external === true;
+  const scannerTimeout = Number(sonarConfig?.timeouts?.scanner_ms) > 0
+    ? Number(sonarConfig.timeouts.scanner_ms)
+    : 15 * 60 * 1000;
+  const sonarNetwork = sonarConfig.network || "karajan_sonar_net";
+  const apiHost = resolveSonarHost(rawHost);
+  const isLocalHost = /localhost|127\.0\.0\.1/.test(rawHost);
+  const host = isLocalHost ? rawHost.replaceAll(/localhost|127\.0\.0\.1/g, "host.docker.internal") : rawHost;
+
+  const start = await sonarUp(rawHost);
+  if (start.exitCode !== 0) {
+    return {
+      ok: false,
+      stdout: start.stdout || "",
+      stderr: start.stderr || "Failed to start SonarQube service",
+      exitCode: start.exitCode
+    };
+  }
+  await ensureSonarProjectProperties();
+  const token = await resolveSonarTokenWithFallback(config, apiHost);
+  if (!token) {
+    return {
+      ok: false,
+      stdout: "",
+      stderr:
+        "Unable to resolve Sonar token. Fix: (1) run 'kj init' to configure it, (2) set KJ_SONAR_TOKEN env var, or (3) add sonarqube.token to ~/.karajan/kj.config.yml.",
+      exitCode: 1
+    };
+  }
+  process.env.KJ_SONAR_TOKEN = token;
+  const coverage = await maybeRunCoverage(config);
+  if (!coverage.ok) {
+    return {
+      ok: false,
+      stdout: coverage.stdout || "",
+      stderr: coverage.stderr || "Failed to generate coverage report for SonarQube",
+      exitCode: coverage.exitCode || 1
+    };
+  }
+  const scannerConfig = normalizeScannerConfig({
+    ...sonarConfig.scanner,
+    ...coverage.scannerPatch
+  });
+
+  const pick = await pickSonarScanner(sonarConfig.scanner);
+  const env = {
+    ...process.env,
+    SONAR_HOST_URL: pick.type === "native" ? rawHost : host,
+    SONAR_TOKEN: token || "",
+    SONAR_SCANNER_OPTS: buildScannerOpts(effectiveProjectKey, scannerConfig)
+  };
+
+  let cmd, args;
+  if (pick.type === "native") {
+    cmd = pick.bin;
+    args = [];
+  } else {
+    cmd = "docker";
+    args = [
+      "run",
+      "--rm",
+      "-v",
+      `${process.cwd()}:/usr/src`,
+      ...(isLocalHost ? ["--add-host", "host.docker.internal:host-gateway"] : []),
+      ...(isLocalHost || isExternalSonar ? [] : ["--network", sonarNetwork]),
+      "-e", "SONAR_HOST_URL",
+      "-e", "SONAR_TOKEN",
+      "-e", "SONAR_SCANNER_OPTS",
+      "sonarsource/sonar-scanner-cli"
+    ];
+  }
+
+  const result = await runCommand(cmd, args, { timeout: scannerTimeout, env });
+  return {
+    ok: result.exitCode === 0,
+    projectKey: effectiveProjectKey,
+    scanner: pick.type,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode: result.exitCode
+  };
+}

package/src/sonar/token-bootstrap.js

@@ -0,0 +1,205 @@
+/**
+ * Sonar token bootstrap (KJC-TSK-0367).
+ *
+ * On `kj init`, after the SonarQube container is up, try to generate the
+ * analysis token via the REST API instead of asking the user to walk
+ * through the web UI manually. The bootstrapper:
+ *
+ *   1. Probes the host with admin/admin (the container default).
+ *   2. If login succeeds AND the password is still default, it rotates
+ *      the password to a freshly generated value and persists that to
+ *      `~/.karajan/sonar.admin-password` (mode 0600). This avoids
+ *      leaving the deployment with the well-known default credentials.
+ *   3. Generates a Global Analysis Token named `karajan-cli` via
+ *      `POST /api/user_tokens/generate` and returns it.
+ *   4. Persists the token to `~/.karajan/sonar.token` (mode 0600). The
+ *      caller writes it into `config.sonarqube.token` separately.
+ *
+ * On any HTTP error, we return `{ ok: false, reason }` and let the
+ * caller fall back to the manual-flow instructions that existed before
+ * this card. We never throw — the wizard must keep going.
+ */
+
+import { writeFileSync, chmodSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { getKarajanHome } from "../utils/paths.js";
+import path from "node:path";
+
+const DEFAULT_USER = "admin";
+const DEFAULT_PASS = "admin";
+const TOKEN_NAME = "karajan-cli";
+
+/**
+ * @param {string} host        e.g. http://localhost:9000
+ * @param {string} pathname    "/api/..."
+ * @param {object} opts
+ * @param {"GET"|"POST"} [opts.method="GET"]
+ * @param {Record<string,string>} [opts.form]   form-urlencoded body
+ * @param {string} opts.user
+ * @param {string} opts.pass
+ * @returns {Promise<{ status: number, body: any }>}
+ */
+async function call(host, pathname, opts) {
+  const url = host.replace(/\/$/, "") + pathname;
+  const headers = {
+    Authorization: "Basic " + Buffer.from(`${opts.user}:${opts.pass}`).toString("base64"),
+  };
+  let body;
+  if (opts.method === "POST" && opts.form) {
+    headers["Content-Type"] = "application/x-www-form-urlencoded";
+    body = new URLSearchParams(opts.form).toString();
+  }
+  const res = await fetch(url, { method: opts.method || "GET", headers, body });
+  let parsed = null;
+  const text = await res.text();
+  if (text) {
+    try { parsed = JSON.parse(text); } catch { parsed = text; }
+  }
+  return { status: res.status, body: parsed };
+}
+
+/**
+ * Generate a strong (32-byte hex) random password. We never re-use the
+ * default `admin` password and never persist `admin` to disk.
+ */
+function generatePassword() {
+  return randomBytes(24).toString("base64url");
+}
+
+/**
+ * Persist a value at `~/.karajan/<filename>` with mode 0600.
+ */
+function persistSecret(filename, value) {
+  const home = getKarajanHome();
+  const target = path.join(home, filename);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, value, { mode: 0o600 });
+  try { chmodSync(target, 0o600); } catch { /* best-effort on Windows */ }
+  return target;
+}
+
+/**
+ * Bootstrap the Sonar analysis token. Idempotent: if the
+ * `karajan-cli` token already exists Sonar will refuse to create it
+ * again (HTTP 400 with `"errors":[{"msg":"A user token...exists"}]`).
+ * In that case we delete-and-recreate so kj init always returns a
+ * usable token.
+ *
+ * @param {object} opts
+ * @param {string} opts.host           Default http://localhost:9000
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   token?: string,
+ *   savedTo?: string,
+ *   passwordRotated?: boolean,
+ *   passwordSavedTo?: string,
+ *   reason?: string,
+ * }>}
+ */
+export async function bootstrapSonarToken({ host = "http://localhost:9000" } = {}) {
+  let user = DEFAULT_USER;
+  let pass = DEFAULT_PASS;
+  let passwordRotated = false;
+  let passwordSavedTo = null;
+  // KJC-BUG-0035: capture rotation failures so the caller can log them
+  // instead of swallowing the error silently. Pre-fix the rotation
+  // returned status 403/500/network were ignored and the user never knew.
+  let passwordRotationError = null;
+
+  // 1) Probe: does admin/admin still work?
+  const probe = await call(host, "/api/authentication/validate", { user, pass }).catch((err) => ({ status: 0, body: err.message }));
+  if (probe.status === 0) {
+    return { ok: false, reason: `network error reaching ${host}: ${probe.body}` };
+  }
+  if (probe.status === 401 || (probe.body && probe.body.valid === false)) {
+    return { ok: false, reason: "admin/admin login failed (password may already be customized — set sonarqube.token manually)" };
+  }
+
+  // 2) Rotate the default password if it's still in place. This stops
+  //    the well-known credentials from being a stable attack surface
+  //    on this user's machine.
+  const newPass = generatePassword();
+  const change = await call(host, "/api/users/change_password", {
+    method: "POST",
+    user,
+    pass,
+    form: { login: user, previousPassword: pass, password: newPass },
+  }).catch((err) => ({ status: 0, body: err.message }));
+
+  if (change.status === 204 || change.status === 200) {
+    pass = newPass;
+    passwordRotated = true;
+    passwordSavedTo = persistSecret("sonar.admin-password", pass);
+  } else if (change.status === 400 && Array.isArray(change.body?.errors)
+              && change.body.errors.some(e => /default/i.test(e.msg))) {
+    // Sonar complained the password matches a default — rare. Try with
+    // a longer one.
+    const longerPass = generatePassword() + generatePassword();
+    const retry = await call(host, "/api/users/change_password", {
+      method: "POST",
+      user,
+      pass,
+      form: { login: user, previousPassword: pass, password: longerPass },
+    }).catch(() => ({ status: 0 }));
+    if (retry.status === 204 || retry.status === 200) {
+      pass = longerPass;
+      passwordRotated = true;
+      passwordSavedTo = persistSecret("sonar.admin-password", pass);
+    } else {
+      passwordRotationError = `rotate-retry HTTP ${retry.status}: ${detailFromBody(retry.body)}`;
+    }
+  } else if (change.status === 401) {
+    // Expected: admin already changed password — not a failure.
+  } else if (change.status !== 0) {
+    // KJC-BUG-0035: ANY other non-success status (403, 500, 400-without-default, …)
+    // means the rotation didn't happen and admin/admin is still live on disk.
+    // Surface it via the result so the caller can warn the user.
+    passwordRotationError = `rotate HTTP ${change.status}: ${detailFromBody(change.body)}`;
+  } else {
+    // status === 0: network error before getting any HTTP response.
+    passwordRotationError = `rotate network error: ${detailFromBody(change.body)}`;
+  }
+
+  // 3) Token already exists? Revoke it so we can re-create cleanly.
+  await call(host, "/api/user_tokens/revoke", {
+    method: "POST",
+    user,
+    pass,
+    form: { name: TOKEN_NAME },
+  }).catch(() => { /* token may not exist — that's fine */ });
+
+  // 4) Generate the analysis token.
+  const gen = await call(host, "/api/user_tokens/generate", {
+    method: "POST",
+    user,
+    pass,
+    form: { name: TOKEN_NAME, type: "GLOBAL_ANALYSIS_TOKEN" },
+  }).catch((err) => ({ status: 0, body: err.message }));
+
+  if (gen.status !== 200 || !gen.body?.token) {
+    const detail = gen.body?.errors?.[0]?.msg || gen.body || `HTTP ${gen.status}`;
+    return { ok: false, reason: `token generation failed: ${detail}`, passwordRotated, passwordSavedTo };
+  }
+
+  const token = gen.body.token;
+  const savedTo = persistSecret("sonar.token", token);
+
+  return {
+    ok: true,
+    token,
+    savedTo,
+    passwordRotated,
+    passwordSavedTo: passwordRotated ? passwordSavedTo : null,
+    passwordRotationError,
+  };
+}
+
+function detailFromBody(body) {
+  if (!body) return "no body";
+  if (typeof body === "string") return body.slice(0, 200);
+  if (Array.isArray(body.errors)) {
+    return body.errors.map(e => e?.msg || JSON.stringify(e)).join("; ").slice(0, 200);
+  }
+  try { return JSON.stringify(body).slice(0, 200); } catch { return "(unserialisable)"; }
+}

package/src/sonar/token-recovery.js

@@ -0,0 +1,67 @@
+// Sonar 401 auto-recovery — KJC-BUG-0057 / v2.19.2.
+//
+// When the Sonar API returns 401 (token missing / invalid / expired / revoked)
+// and we still have admin/admin (or a user/pass we saved at `kj init` time),
+// regenerate the analysis token VIA THE REST API and persist it. The caller
+// retries the original request once with the new token.
+//
+// Programmatic, no LLM involvement. The whole point of the user feedback was
+// that this is plumbing, not a decision: Karajan has the credentials to
+// re-bootstrap and should do it without asking.
+
+import { bootstrapSonarToken } from "./token-bootstrap.js";
+import { saveSonarToken } from "./credentials.js";
+
+// Per-process latch: a single Sonar run that 401s on every endpoint must
+// only trigger ONE bootstrap attempt — not one per endpoint. The latch
+// resets when the process exits.
+let _recoveryAttempted = false;
+
+/**
+ * @internal Reset the latch between tests (mirrors __resetKjHomeWarningForTests).
+ */
+export function __resetSonarRecoveryLatchForTests() {
+  _recoveryAttempted = false;
+}
+
+/**
+ * Attempt to re-bootstrap the Sonar token after a 401. Mutates `config`
+ * in place when successful so the immediate retry picks up the new token.
+ *
+ * @param {object} config       Karajan config (will be mutated on success).
+ * @param {object} [logger]
+ * @returns {Promise<{ ok: boolean, reason?: string, newToken?: string, savedTo?: string, passwordRotated?: boolean }>}
+ */
+export async function recoverSonarToken(config, logger = null) {
+  if (_recoveryAttempted) {
+    return { ok: false, reason: "recovery already attempted in this process" };
+  }
+  _recoveryAttempted = true;
+
+  const host = config?.sonarqube?.host || "http://localhost:9000";
+  logger?.warn?.(`[sonar-recovery] 401 from ${host} — attempting token re-bootstrap`);
+
+  const result = await bootstrapSonarToken({ host });
+
+  if (!result.ok) {
+    logger?.warn?.(`[sonar-recovery] bootstrap failed: ${result.reason}`);
+    return { ok: false, reason: result.reason };
+  }
+
+  // Mutate the in-memory config so the caller's retry sees the new token.
+  config.sonarqube = config.sonarqube || {};
+  config.sonarqube.token = result.token;
+
+  // Also persist to ~/.karajan/sonar-credentials.json so future processes
+  // pick it up via the normal config-resolver chain instead of triggering
+  // recovery again. token-bootstrap.js already wrote sonar.token; this
+  // mirrors it into the structured credentials file the resolver reads.
+  try {
+    await saveSonarToken(result.token);
+  } catch (err) {
+    logger?.warn?.(`[sonar-recovery] persist to sonar-credentials.json failed (non-blocking): ${err.message}`);
+  }
+
+  logger?.info?.(`[sonar-recovery] new token persisted to ${result.savedTo}${result.passwordRotated ? " (admin password rotated)" : ""} — retrying original request`);
+  return { ok: true, newToken: result.token, savedTo: result.savedTo, passwordRotated: result.passwordRotated };
+}

package/src/spec-review/refine-loop.js

@@ -0,0 +1,58 @@
+// Refine loop for the spec-reviewer (KJC-PCS-0048 PR 3). Called from
+// run-spec-review.js when the user picks [r]efine. Asks the role for a
+// rewritten v2, persists v1.md / v2.md, opens $EDITOR for the user to
+// tweak, uses a SHA-256 hash diff to flag whether the v2 needs a fresh
+// review pass (user modified it) or can proceed as-is.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+
+const sha256 = (s) => crypto.createHash("sha256").update(String(s || ""), "utf8").digest("hex");
+
+function openEditor(filePath, { logger, openEditorFn = null } = {}) {
+  if (openEditorFn) return openEditorFn(filePath);
+  const raw = process.env.VISUAL || process.env.EDITOR || "vi"; // same precedence as src/commands/config.js
+  const parts = raw.split(/\s+/);
+  logger?.info?.(`Opening ${parts[0]} on ${filePath}`);
+  return spawnSync(parts[0], [...parts.slice(1), filePath], { stdio: "inherit" }).status === 0;
+}
+
+/**
+ * Single refine iteration. The outer loop in run-spec-review.js decides
+ * whether to re-invoke us based on the returned `hashChanged` flag
+ * (re-review the v2 because the user modified it) or accept the v2 as
+ * the final spec (`hashChanged === false`).
+ *
+ * @returns {Promise<{ok, refinedSpec?, hashChanged, error?, v2Path?}>}
+ */
+export async function runRefinePass({ spec, findings, role, projectDir, taskFile, logger, fs: fsOverride, openEditorFn }) {
+  const _fs = fsOverride || fs;
+  const refineRes = await role.refineSpec({ spec, findings });
+  if (!refineRes.ok) return { ok: false, error: refineRes.error || "refine failed", hashChanged: false };
+
+  let v2Path;
+  try {
+    const root = projectDir || process.cwd();
+    const ts = new Date().toISOString().replaceAll(/[:.]/g, "-");
+    const dir = path.join(root, ".reviews", `spec-review-${ts}`);
+    await _fs.mkdir(dir, { recursive: true });
+    await _fs.writeFile(path.join(dir, "spec-v1.md"), spec, "utf8");
+    v2Path = path.join(dir, "spec-v2.md");
+    await _fs.writeFile(v2Path, refineRes.refinedSpec, "utf8");
+    if (taskFile) {
+      // Mirror the v2 next to the user's --task-file so they find it
+      // without diving into .reviews/.
+      const p = path.parse(taskFile);
+      await _fs.writeFile(path.join(p.dir, `${p.name}.v2${p.ext || ".md"}`), refineRes.refinedSpec, "utf8").catch(() => {});
+    }
+  } catch (err) { return { ok: false, error: `persist failed: ${err.message}`, hashChanged: false }; }
+
+  const before = sha256(refineRes.refinedSpec);
+  await openEditor(v2Path, { logger, openEditorFn });
+  let after;
+  try { after = await _fs.readFile(v2Path, "utf8"); }
+  catch (err) { return { ok: false, error: `read v2 failed: ${err.message}`, hashChanged: false }; }
+  return { ok: true, refinedSpec: after, hashChanged: before !== sha256(after), v2Path };
+}