karajan-code 2.10.1 → 2.10.2

package/README.md

@@ -23,7 +23,9 @@
 
 ---
 
-> **v2.10.1 released** — Patch release. One-line fix for a stdout contamination bug in `kj audit --agent-readiness --json` (the `[info]` banner was breaking downstream `jq` pipes), plus polish in the asciinema demo scripts. Safe upgrade from 2.10.0.
+> **v2.10.2 released** — Patch release. `kj init` wizard expanded from 9 prompts to a full setup: per-role provider selection (10 roles, "inherit / pick CLI / disable"), automatic SonarQube token generation via REST API (no more web UI walkthrough), git automation flags (`auto_commit/push/pr`) and HU Board security (bind host + port). +16 new tests. Safe upgrade from 2.10.1.
+>
+> **v2.10.1** — Patch release. One-line fix for a stdout contamination bug in `kj audit --agent-readiness --json` (the `[info]` banner was breaking downstream `jq` pipes), plus polish in the asciinema demo scripts. Safe upgrade from 2.10.0.
 >
 > **v2.10.0** — Agent-readiness release. Karajan is now the first orchestrator with a full agent-readability surface: an `llms.txt` index at the root, a `SKILL.md` per CLI command under `docs/agents/`, and a static auditor that scores any third-party repo against the same shape. Highlights: (1) **`kj audit --agent-readiness`** scores any repo 0–100 across seven checks (llms.txt, robots AI-bot allowlist, page token budgets ≤ 32 KB, heading hierarchy, agents/README, SKILL.md coverage). LLM-free, deterministic, JSON-able. Karajan-on-Karajan: **100/100**. (2) **Six new SKILL.md files** (`kj doctor / init / board / review / resume / clean`) under `docs/agents/`, all with the same `What it does · Inputs · Outputs · Side effects · Failure modes · Example` contract; CI guards every link in `llms.txt` resolves. (3) **Webperf quality gate inside the iteration loop** (`pipeline.perf.enabled`): PASS continues, FAIL pushes blocking-metric feedback to the coder, scanner-missing skips best-effort. (4) **HU Board hardening**: binds 127.0.0.1 by default, opt-in `--bind 0.0.0.0` enforces an auto-generated token, helmet headers, rate limiting at 300 req/min — "safe by default on a coffee-shop WiFi". (5) **a11y skills auto-route**: tasks mentioning `accessibility / WCAG / ARIA / screen reader / keyboard nav` automatically pull the `frontend-ui-engineering` skill. (6) **Asciinema demo scripts** under `docs/demos/` so the recordings re-record per release instead of rotting. 5 PRs merged (#605–#609 + #610), 4358/4358 tests passing. See [CHANGELOG.md](./CHANGELOG.md) for the full punch list.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.10.1",
+  "version": "2.10.2",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/commands/init.js

@@ -13,6 +13,200 @@ import { detectOsLocale, SUPPORTED_LANGUAGES } from "../utils/locale.js";
 import { detectRtk } from "../utils/rtk-detect.js";
 import { installRtk } from "../utils/rtk-install.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
+import { bootstrapSonarToken } from "../sonar/token-bootstrap.js";
+
+/**
+ * Roles asked individually after coder/reviewer. Each entry:
+ *   - key: config.roles.<key>.provider
+ *   - pipelineKey: config.pipeline.<key>.enabled (omit when not gated by a flag)
+ *   - default: which role's CLI to inherit ("coder" | "reviewer")
+ *   - allowDisable: true if "off" is a valid choice
+ *
+ * Order matters — keep the most-impactful first so the wizard never hides
+ * critical roles behind a long tail of opt-ins.
+ */
+const PER_ROLE_QUESTIONS = [
+  { key: "planner",     pipelineKey: "planner",     default: "coder",    allowDisable: true,  label: "Planner (decomposes complex tasks into HUs)" },
+  { key: "researcher",  pipelineKey: "researcher",  default: "coder",    allowDisable: true,  label: "Researcher (explores codebase before coding)" },
+  { key: "architect",   pipelineKey: "architect",   default: "coder",    allowDisable: true,  label: "Architect (designs solution + contracts)" },
+  { key: "tester",      pipelineKey: "tester",      default: "coder",    allowDisable: false, label: "Tester (verifies tests + coverage)" },
+  { key: "security",    pipelineKey: "security",    default: "coder",    allowDisable: false, label: "Security (OWASP audit)" },
+  { key: "solomon",     pipelineKey: "solomon",     default: "reviewer", allowDisable: false, label: "Solomon (judge AI for dilemmas)" },
+  { key: "refactorer",  pipelineKey: "refactorer",  default: "coder",    allowDisable: true,  label: "Refactorer (clarity passes)" },
+  { key: "impeccable",  pipelineKey: "impeccable",  default: "coder",    allowDisable: true,  label: "Impeccable (UI/UX audit — frontend only)" },
+  { key: "perf",        pipelineKey: "perf",        default: "coder",    allowDisable: true,  label: "Perf (Core Web Vitals gate — frontend only)" },
+  { key: "hu_reviewer", pipelineKey: "hu_reviewer", default: "reviewer", allowDisable: true,  label: "HU Reviewer (mandatory user-story certification)" },
+];
+
+// ---- Sub-asks ----
+
+async function askAgents(wizard, available, config, logger) {
+  if (available.length === 1) {
+    const only = available[0].name;
+    logger.info(`Only one agent available: ${only}. Using it for all roles.\n`);
+    config.coder = only;
+    config.reviewer = only;
+    config.roles.coder.provider = only;
+    config.roles.reviewer.provider = only;
+    return { coder: only, reviewer: only };
+  }
+
+  const agentOptions = available.map((a) => ({
+    label: `${a.name} (${a.version})`,
+    value: a.name,
+    available: true,
+  }));
+
+  const coder = await wizard.select("Select default CODER agent:", agentOptions);
+  config.coder = coder;
+  config.roles.coder.provider = coder;
+  logger.info(`  -> Coder: ${coder}`);
+
+  const reviewer = await wizard.select("Select default REVIEWER agent:", agentOptions);
+  config.reviewer = reviewer;
+  config.roles.reviewer.provider = reviewer;
+  logger.info(`  -> Reviewer: ${reviewer}`);
+
+  return { coder, reviewer };
+}
+
+/**
+ * For each non-coder/non-reviewer role, ask: use coder default | use reviewer
+ * default | pick a specific CLI | (when allowed) disable. The choice is
+ * persisted as `config.roles.<role>.provider` (null means "inherit from
+ * coder" at runtime). Pipeline-flag-gated roles also flip
+ * `config.pipeline.<role>.enabled`.
+ *
+ * `available.length === 1` short-circuits: every role uses the only CLI
+ * available, no point asking.
+ */
+async function askPerRoleProviders(wizard, available, config, { coder, reviewer }, logger) {
+  if (available.length <= 1) return;
+
+  logger.info("");
+  logger.info("Configure provider per role (Enter accepts the default):");
+
+  // Make sure containers exist for every role/pipeline key we touch —
+  // older configs may have a sparser shape than DEFAULTS.
+  config.roles = config.roles || {};
+  config.pipeline = config.pipeline || {};
+
+  for (const role of PER_ROLE_QUESTIONS) {
+    config.roles[role.key] = config.roles[role.key] || { provider: null, model: null };
+    if (role.pipelineKey) {
+      config.pipeline[role.pipelineKey] = config.pipeline[role.pipelineKey] || { enabled: false };
+    }
+
+    const defaultLabel = role.default === "coder" ? `coder (${coder})` : `reviewer (${reviewer})`;
+    const baseOptions = [
+      { label: `Use ${defaultLabel} — default`, value: "__default__", available: true },
+    ];
+    for (const a of available) {
+      if ((role.default === "coder" && a.name === coder) || (role.default === "reviewer" && a.name === reviewer)) continue;
+      baseOptions.push({ label: a.name, value: a.name, available: true });
+    }
+    if (role.allowDisable) {
+      baseOptions.push({ label: "Disable role", value: "__disabled__", available: true });
+    }
+
+    const choice = await wizard.select(`  ${role.label}:`, baseOptions);
+
+    if (choice === "__disabled__") {
+      if (role.pipelineKey) config.pipeline[role.pipelineKey].enabled = false;
+      logger.info(`    -> ${role.key}: disabled`);
+    } else if (choice === "__default__") {
+      // Inherit from coder/reviewer at runtime — leave provider null.
+      config.roles[role.key].provider = null;
+      if (role.pipelineKey) config.pipeline[role.pipelineKey].enabled = true;
+      logger.info(`    -> ${role.key}: ${defaultLabel}`);
+    } else {
+      config.roles[role.key].provider = choice;
+      if (role.pipelineKey) config.pipeline[role.pipelineKey].enabled = true;
+      logger.info(`    -> ${role.key}: ${choice}`);
+    }
+  }
+}
+
+async function askMethodology(wizard, config, logger) {
+  const methodology = await wizard.select("Development methodology:", [
+    { label: "TDD (test-driven development)", value: "tdd", available: true },
+    { label: "Standard (no TDD enforcement)", value: "standard", available: true },
+  ]);
+  config.development.methodology = methodology;
+  config.development.require_test_changes = methodology === "tdd";
+  logger.info(`  -> Methodology: ${methodology}`);
+}
+
+async function askLanguages(wizard, config, logger) {
+  const detectedLocale = detectOsLocale();
+  const allLangEntries = Object.entries(SUPPORTED_LANGUAGES).map(([code, name]) => ({
+    label: `${name} (${code})`,
+    value: code,
+    available: true,
+  }));
+  const languageOptions = [
+    ...allLangEntries.filter((o) => o.value === detectedLocale),
+    ...allLangEntries.filter((o) => o.value !== detectedLocale),
+  ];
+
+  const pipelineLang = await wizard.select("Pipeline language:", languageOptions);
+  config.language = pipelineLang;
+  logger.info(`  -> Pipeline language: ${pipelineLang}`);
+
+  const huLangOptions = [
+    ...allLangEntries.filter((o) => o.value === pipelineLang),
+    ...allLangEntries.filter((o) => o.value !== pipelineLang),
+  ];
+  const huLang = await wizard.select("HU language (for user stories):", huLangOptions);
+  config.hu_language = huLang;
+  logger.info(`  -> HU language: ${huLang}`);
+}
+
+async function askGitAutomation(wizard, config, logger) {
+  config.git = config.git || {};
+  const autoCommit = await wizard.confirm("Auto-commit per HU? (recommended for `kj run` so commits show up in git log)", false);
+  config.git.auto_commit = autoCommit;
+  logger.info(`  -> auto_commit: ${autoCommit}`);
+
+  const autoPush = await wizard.confirm("Auto-push to remote after each commit?", false);
+  config.git.auto_push = autoPush;
+  logger.info(`  -> auto_push: ${autoPush}`);
+
+  const autoPr = await wizard.confirm("Auto-open a Pull Request when the run finishes?", false);
+  config.git.auto_pr = autoPr;
+  logger.info(`  -> auto_pr: ${autoPr}`);
+
+  // Branch prefix only worth asking when auto_commit is on; otherwise leave default.
+  if (autoCommit) {
+    const prefix = await wizard.ask("Branch prefix (e.g. feat/, kj/, ai/) [feat/]: ");
+    config.git.branch_prefix = (prefix && prefix.trim()) || "feat/";
+    logger.info(`  -> branch_prefix: ${config.git.branch_prefix}`);
+  }
+}
+
+async function askBoardSecurity(wizard, config, logger) {
+  if (!config.hu_board?.enabled) return;
+
+  const bindChoice = await wizard.select(
+    "HU Board bind host:",
+    [
+      { label: "127.0.0.1 (loopback only — recommended for personal laptops)", value: "127.0.0.1", available: true },
+      { label: "0.0.0.0 (LAN exposure — token auth auto-enforced for non-loopback peers)", value: "0.0.0.0", available: true },
+    ],
+  );
+  config.hu_board.bind = bindChoice;
+  logger.info(`  -> HU Board bind: ${bindChoice}`);
+
+  if (bindChoice === "0.0.0.0") {
+    logger.info("     A secret token will be auto-generated on first start at ~/.karajan/hu-board/token (mode 0600).");
+    logger.info("     Open the URL printed by `kj board start` to grab it.");
+  }
+
+  const portInput = await wizard.ask("HU Board port [4000]: ");
+  const port = Number.parseInt(portInput, 10);
+  config.hu_board.port = Number.isFinite(port) && port > 0 && port < 65536 ? port : 4000;
+  logger.info(`  -> HU Board port: ${config.hu_board.port}`);
+}
 
 async function runWizard(config, logger) {
   const agents = await detectAvailableAgents();
@@ -41,30 +235,7 @@ async function runWizard(config, logger) {
 
   const wizard = createWizard();
   try {
-    if (available.length === 1) {
-      const only = available[0].name;
-      logger.info(`Only one agent available: ${only}. Using it for all roles.\n`);
-      config.coder = only;
-      config.reviewer = only;
-      config.roles.coder.provider = only;
-      config.roles.reviewer.provider = only;
-    } else {
-      const agentOptions = available.map((a) => ({
-        label: `${a.name} (${a.version})`,
-        value: a.name,
-        available: true
-      }));
-
-      const coder = await wizard.select("Select default CODER agent:", agentOptions);
-      config.coder = coder;
-      config.roles.coder.provider = coder;
-      logger.info(`  -> Coder: ${coder}`);
-
-      const reviewer = await wizard.select("Select default REVIEWER agent:", agentOptions);
-      config.reviewer = reviewer;
-      config.roles.reviewer.provider = reviewer;
-      logger.info(`  -> Reviewer: ${reviewer}`);
-    }
+    const { coder, reviewer } = await askAgents(wizard, available, config, logger);
 
     const enableTriage = await wizard.confirm("Enable triage (auto-classify task complexity)?", false);
     config.pipeline.triage = config.pipeline.triage || {};
@@ -84,38 +255,19 @@ async function runWizard(config, logger) {
     }
     logger.info(`  -> HU Board: ${enableHuBoard ? "enabled (auto-start on kj run)" : "disabled"}`);
 
-    const methodology = await wizard.select("Development methodology:", [
-      { label: "TDD (test-driven development)", value: "tdd", available: true },
-      { label: "Standard (no TDD enforcement)", value: "standard", available: true }
-    ]);
-    config.development.methodology = methodology;
-    config.development.require_test_changes = methodology === "tdd";
-    logger.info(`  -> Methodology: ${methodology}`);
+    await askPerRoleProviders(wizard, available, config, { coder, reviewer }, logger);
+    await askMethodology(wizard, config, logger);
+    await askLanguages(wizard, config, logger);
 
-    const detectedLocale = detectOsLocale();
-    const allLangEntries = Object.entries(SUPPORTED_LANGUAGES).map(([code, name]) => ({
-      label: `${name} (${code})`,
-      value: code,
-      available: true
-    }));
-    // Put detected locale first so it becomes the default selection
-    const languageOptions = [
-      ...allLangEntries.filter((o) => o.value === detectedLocale),
-      ...allLangEntries.filter((o) => o.value !== detectedLocale)
-    ];
-
-    const pipelineLang = await wizard.select("Pipeline language:", languageOptions);
-    config.language = pipelineLang;
-    logger.info(`  -> Pipeline language: ${pipelineLang}`);
+    logger.info("");
+    logger.info("Git automation:");
+    await askGitAutomation(wizard, config, logger);
 
-    // Reorder for HU language with pipeline language as default
-    const huLangOptions = [
-      ...allLangEntries.filter((o) => o.value === pipelineLang),
-      ...allLangEntries.filter((o) => o.value !== pipelineLang)
-    ];
-    const huLang = await wizard.select("HU language (for user stories):", huLangOptions);
-    config.hu_language = huLang;
-    logger.info(`  -> HU language: ${huLang}`);
+    if (enableHuBoard) {
+      logger.info("");
+      logger.info("HU Board security:");
+      await askBoardSecurity(wizard, config, logger);
+    }
 
     logger.info("");
   } finally {
@@ -182,7 +334,7 @@ async function ensureCoderRules(coderRulesPath, logger) {
   logger.info("Created .karajan/coder-rules.md");
 }
 
-async function setupSonarQube(config, logger) {
+async function setupSonarQube(config, logger, { interactive } = {}) {
   if (config.sonarqube?.enabled === false) {
     logger.info("SonarQube disabled — skipping container setup.");
     return;
@@ -212,8 +364,32 @@ async function setupSonarQube(config, logger) {
   }
 
   logger.info("SonarQube container started");
+
+  // KJC-TSK-0367: try to bootstrap the analysis token automatically. The
+  // bootstrapper logs in with admin/admin, rotates the password if it's
+  // still the default, and POSTs to /api/user_tokens/generate. On 401 or
+  // any other failure, we fall back to the manual flow that was the only
+  // option before this card.
+  if (interactive) {
+    logger.info("Bootstrapping SonarQube token automatically...");
+    const result = await bootstrapSonarToken({
+      host: config.sonarqube.host || "http://localhost:9000",
+      configPath: getConfigPath(),
+    });
+    if (result.ok) {
+      config.sonarqube.token = result.token;
+      logger.info(`  -> Sonar token saved to ${result.savedTo}`);
+      if (result.passwordRotated) {
+        logger.info(`  -> Sonar admin password rotated. New value at ${result.passwordSavedTo}`);
+      }
+      return;
+    }
+    logger.warn(`Could not auto-generate Sonar token: ${result.reason}`);
+    logger.info("Falling back to manual flow:");
+  }
+
   logger.info("");
-  logger.info("To configure the SonarQube token:");
+  logger.info("To configure the SonarQube token manually:");
   logger.info("  1. Open http://localhost:9000");
   logger.info("  2. Log in (default credentials: admin / admin)");
   logger.info("  3. Go to: My Account > Security > Generate Token");
@@ -402,9 +578,12 @@ export async function initCommand({ logger, flags = {} }) {
     }
   }
 
-  await setupSonarQube(config, logger);
+  await setupSonarQube(config, logger, { interactive });
   await scaffoldCiGateway(config, flags, logger);
 
+  // Persist any changes setupSonarQube made (token, etc.) back to disk.
+  await writeConfig(configPath, config);
+
   // Telemetry: anonymous install event (non-blocking)
   const { sendTelemetryEvent } = await import("../utils/telemetry.js");
   const { readFileSync } = await import("node:fs");
@@ -416,3 +595,14 @@ export async function initCommand({ logger, flags = {} }) {
     sendTelemetryEvent("install", { version }, config).catch(() => {});
   } catch { /* non-blocking */ }
 }
+
+// Internal exports for unit testing (KJC-TSK-0367)
+export const __test__ = {
+  askAgents,
+  askPerRoleProviders,
+  askMethodology,
+  askLanguages,
+  askGitAutomation,
+  askBoardSecurity,
+  PER_ROLE_QUESTIONS,
+};

package/src/sonar/token-bootstrap.js

@@ -0,0 +1,182 @@
+/**
+ * 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;
+
+  // 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 if (change.status !== 0 && change.status !== 401) {
+    // Non-fatal: probably the admin already changed the password. We
+    // continue using whatever credentials worked at the probe step.
+  }
+
+  // 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,
+  };
+}