cawdev-cli 1.1.0 → 1.2.0

package/lib/finish-check.mjs

@@ -18,6 +18,7 @@
 // finish that pushes a key is worse than one that leaves a file behind.
 
 import { execFile } from 'node:child_process';
+import { notAllowed, protectedChanges } from './protected.mjs';
 import { findSecret } from './secrets.mjs';
 
 /** The profiles whose run is a branch somebody will build on. */
@@ -109,8 +110,16 @@ export function notDoneYet(left) {
  * was), and `{ ok: false, reason }` otherwise, in words for the run's summary.
  * Never forces; a remote that has moved is a reason, not something to win.
  */
-export async function settleBranch(cwd, branch, { git = runGit, push, label = 'cawdev' } = {}) {
+export async function settleBranch(cwd, branch,
+  { git = runGit, push, label = 'cawdev', protected: policy = null } = {}) {
   const left = await leftOver(cwd, branch, { git });
+  // R562. Before the "nothing left" return: a protected change already
+  // committed and pushed (by a CLI that has no gate of its own) is exactly what
+  // this door exists to catch.
+  const held = left ? await heldProtected(cwd, policy) : [];
+  if (held.length) {
+    return { ok: false, reason: protectedHeld(held) };
+  }
   if (!left || !isUnfinished(left)) {
     return { ok: true, note: null };
   }
@@ -122,6 +131,10 @@ export async function settleBranch(cwd, branch, { git = runGit, push, label = 'c
     };
   }
 
+  // R562. The daemon has no session to ask, so a protected change nobody
+  // allowed fails the run (above, before anything is staged), held in the
+  // checkout. ASK fails too: Carry on, and the next `report done` asks.
+
   let committed = [];
   if (left.dirty.length) {
     await git(cwd, ['add', '-A']);
@@ -159,6 +172,10 @@ export async function settleBranch(cwd, branch, { git = runGit, push, label = 'c
         : null,
     };
   }
+  const heldNow = await heldProtected(cwd, policy);
+  if (heldNow.length) {
+    return { ok: false, reason: protectedHeld(heldNow) };
+  }
   const pushed = await push(cwd, branch);
   if (!pushed.ok) {
     return {
@@ -176,3 +193,19 @@ export async function settleBranch(cwd, branch, { git = runGit, push, label = 'c
       : `The daemon pushed ${branch}, which the session had committed and not pushed.`,
   };
 }
+
+/** The protected paths this checkout changes that nobody has allowed. */
+export async function heldProtected(cwd, policy) {
+  if (!policy?.globs?.length || !policy.base) {
+    return [];
+  }
+  const changed = await protectedChanges(cwd, policy.base, policy.globs);
+  return notAllowed(changed, policy.allowed ?? []);
+}
+
+/** The sentence for a protected change at a door with nobody to ask. */
+export function protectedHeld(paths) {
+  return `${named(paths)} ${paths.length === 1 ? 'is' : 'are'} protected in this project and `
+    + "were changed without a person's leave, so nothing was committed or pushed. The work is "
+    + 'held in the checkout.';
+}

package/lib/harness-prompt.mjs

@@ -105,6 +105,12 @@ export function harnessPrompt({
       + 'least one tool under the prefix, before this stage is finished.\n'
       + mustServers.map((each) => `- \`${each.prefix}__…\` — ${each.name}`).join('\n'));
   }
+  // R319. A server that knows when it is worth reaching for says so, required
+  // or not; one that does not still gets nothing.
+  const adviceFor = (mcpServers ?? []).filter((each) => each.when);
+  if (adviceFor.length) {
+    reach.push(adviceFor.map((each) => `- \`${each.prefix}__…\` (${each.name}): ${each.when}`).join('\n'));
+  }
   if (reach.length) {
     parts.push(`## What this session may reach\n\n${reach.join('\n\n')}`);
   }

package/lib/order.mjs

@@ -0,0 +1,7 @@
+// Code-unit order: what Array#sort does to strings by default and what Java's
+// String.compareTo does, said out loud. Never localeCompare here: ICU weighs
+// `-`, `.` and `_` differently, and an export must not churn (R315) nor a
+// refusal reorder its paths.
+export function byCodeUnit(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/lib/protected.mjs

@@ -0,0 +1,225 @@
+// Protected files — R562.
+//
+// A project lists globs an agent may not change. Three layers enforce it and
+// this is the part that does not depend on the CLI: `protectedChanges` compares
+// the branch with the commit it was cut from, so it catches an Edit, a shell
+// `git checkout main -- pom.xml`, a `git mv`, a `sed -i` and a build step alike,
+// on every CLI and on a machine set to allow everything.
+//
+// Zero dependencies, like the rest of tools/.
+
+import { execFile } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { matches, normalise } from './secrets.mjs';
+import { byCodeUnit } from './order.mjs';
+
+/** The modes a project can choose. REFUSE is what an unreadable policy means. */
+export const MODES = ['REFUSE', 'ASK'];
+
+/**
+ * The policy out of a shield, whatever shape it arrived in.
+ *
+ * Unreadable or missing is REFUSE with no globs — never a way of allowing.
+ */
+export function protectedPolicy(shield) {
+  const globs = Array.isArray(shield?.protectedPaths)
+    ? shield.protectedPaths.filter((glob) => typeof glob === 'string' && glob.trim())
+      .map((glob) => glob.trim())
+    : [];
+  const mode = String(shield?.protectedMode ?? '').toUpperCase() === 'ASK' ? 'ASK' : 'REFUSE';
+  const allowed = Array.isArray(shield?.protectedAllowed)
+    ? shield.protectedAllowed.filter((path) => typeof path === 'string')
+    : [];
+  return { globs, mode, allowed };
+}
+
+/**
+ * Whether a path, absolute or relative to the checkout, is a protected one.
+ *
+ * A path that leaves the checkout is not protected here — it is the scope
+ * rule's business — and a symlink is followed when it exists, so a link into a
+ * protected directory is the directory.
+ */
+export function isProtected(path, root, globs) {
+  if (typeof path !== 'string' || !path || !Array.isArray(globs) || globs.length === 0) {
+    return false;
+  }
+  const base = normalise(root);
+  const candidates = [normalise(path.startsWith('/') ? path : `${base}/${path}`)];
+  const real = resolveReal(candidates[0]);
+  if (real && real !== candidates[0]) {
+    candidates.push(real);
+  }
+  let realBase = base;
+  try {
+    realBase = realpathSync(base);
+  } catch {
+    // The checkout is not there; the lexical answer stands.
+  }
+  return candidates.some((resolved) => {
+    for (const root of [base, realBase]) {
+      if (resolved === root || resolved.startsWith(`${root}/`)) {
+        const relative = resolved === root ? '' : resolved.slice(root.length + 1);
+        return globs.some((glob) => matchesHere(relative, glob.replace(/^\.\//, '')));
+      }
+    }
+    return false;
+  });
+}
+
+/**
+ * Whether a relative path is under a glob. On macOS and Windows the default
+ * volume is case-insensitive, so `POM.XML` IS `pom.xml` there; comparing
+ * without case protects a little more than a case-sensitive volume needs, which
+ * is the safe direction to be wrong in.
+ */
+function matchesHere(path, glob) {
+  return process.platform === 'darwin' || process.platform === 'win32'
+    ? matches(path.toLowerCase(), glob.toLowerCase())
+    : matches(path, glob);
+}
+
+/** The real path of the longest part that exists, with the rest appended. */
+function resolveReal(path) {
+  const parts = path.split('/');
+  for (let keep = parts.length; keep > 1; keep -= 1) {
+    const head = parts.slice(0, keep).join('/') || '/';
+    try {
+      const real = realpathSync(head);
+      return normalise([real, ...parts.slice(keep)].join('/'));
+    } catch {
+      // Not there yet; try the parent.
+    }
+  }
+  return null;
+}
+
+function runGit(cwd, args) {
+  return new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) {
+        reject(new Error(stderr?.trim() || error.message));
+      } else {
+        resolve(stdout);
+      }
+    });
+  });
+}
+
+/**
+ * The protected paths this branch changes, sorted and unique.
+ *
+ * The committed diff against `base` (a diff, not a log, so a change later
+ * reverted does not count; `--no-renames`, so moving a protected file away is
+ * caught on its old path) plus the working tree. Empty when there is nothing to
+ * judge: no globs, or no base.
+ */
+export async function protectedChanges(cwd, base, globs, { git = runGit } = {}) {
+  if (!base || !Array.isArray(globs) || globs.length === 0) {
+    return [];
+  }
+  const touched = new Set();
+  // A git failure THROWS. An unreadable base (garbage-collected, a shallow
+  // clone) is not a reason to say the branch is clean: the callers turn a throw
+  // into a refusal, which is the direction this fails in.
+  const diff = await git(cwd, ['diff', '--name-only', '--no-renames', '-z', base, 'HEAD']);
+  for (const path of diff.split('\0')) {
+    if (path) {
+      touched.add(path);
+    }
+  }
+  const status = await git(cwd, ['status', '--porcelain', '-z', '--untracked-files=all']);
+  const entries = status.split('\0');
+  for (let at = 0; at < entries.length; at += 1) {
+    const entry = entries[at];
+    if (entry.length < 4) {
+      continue;
+    }
+    touched.add(entry.slice(3));
+    // A rename or copy carries the old path as the next field.
+    if (entry[0] === 'R' || entry[0] === 'C' || entry[1] === 'R' || entry[1] === 'C') {
+      at += 1;
+      if (entries[at]) {
+        touched.add(entries[at]);
+      }
+    }
+  }
+  return [...touched]
+    .filter((path) => globs.some((glob) => matchesHere(path, glob.replace(/^\.\//, ''))))
+    .sort(byCodeUnit);
+}
+
+/** The base a branch was cut from: the merge-base with its upstream, else the claim's commit. */
+export async function protectedBase(cwd, baseBranch, fallback, { git = runGit } = {}) {
+  if (baseBranch) {
+    for (const ref of [`origin/${baseBranch}`, baseBranch]) {
+      try {
+        const sha = (await git(cwd, ['merge-base', ref, 'HEAD'])).trim();
+        if (sha) {
+          return sha;
+        }
+      } catch {
+        // Try the next ref.
+      }
+    }
+  }
+  return fallback || null;
+}
+
+/** What is changed and not allowed. */
+export function notAllowed(changed, allowed = []) {
+  const leave = new Set(allowed);
+  return changed.filter((path) => !leave.has(path));
+}
+
+/** The sentence a refusal gives, shared by every door. */
+export function protectedRefusal(paths, base) {
+  const list = paths.join(', ');
+  return `Not finished — this branch changes protected file(s) the project never lets an agent `
+    + `change: ${list}. Restore them (git checkout ${base ? base.slice(0, 12) : '<base>'} -- `
+    + `<path>, or delete what you added), commit, push, and report done again.`;
+}
+
+/** The paragraph every prompt carries. Null when nothing is protected. */
+export function protectedLine(policy, already = []) {
+  const globs = policy?.globs ?? [];
+  if (!globs.length) {
+    return null;
+  }
+  const how = policy.mode === 'ASK'
+    ? 'Changing one stops and asks a person first, and an allowed change is marked on the card in '
+      + 'red; prefer a design that leaves them alone.'
+    : 'An agent never changes them — not with an edit, not with the shell, not with git; the run '
+      + 'cannot finish while the branch changes one.';
+  const lines = [
+    `**Protected files.** This project protects: ${globs.map((glob) => `\`${glob}\``).join(', ')}. `
+      + `${how} Check your plan against this list before you start.`,
+  ];
+  if (already.length) {
+    lines.push(`This branch already changes ${already.map((path) => `\`${path}\``).join(', ')}, `
+      + 'which are protected; deal with that first.');
+  }
+  return lines.join('\n\n');
+}
+
+/**
+ * Rules for the CLI's permission list, one per glob.
+ *
+ * Only `Edit(path)` is matched — Claude Code rejects `Write(path)` as "not
+ * matched by file permission checks" and applies Edit rules to every
+ * file-editing tool, NotebookEdit included (measured on 2.1.307; see
+ * `protectFiles` in the runner).
+ */
+export function denyRules(globs) {
+  return (globs ?? []).map((glob) => `Edit(./${glob.replace(/^\.\//, '')})`);
+}
+
+/** A path relative to the checkout, or null when it is outside it. */
+export function relativeTo(path, root) {
+  const base = normalise(root);
+  const resolved = normalise(String(path).startsWith('/') ? String(path) : `${base}/${path}`);
+  if (resolved === base) {
+    return '';
+  }
+  return resolved.startsWith(`${base}/`) ? resolved.slice(base.length + 1) : null;
+}

package/lib/roadmap-format.mjs

@@ -4,6 +4,8 @@
 // is not a fixed point and the generated file churns on every release. Keeping
 // both halves in one file is how they stay agreed.
 
+import { byCodeUnit } from './order.mjs';
+
 /**
  * What to call a card — R127 — and, since R221, what identifies one.
  *
@@ -506,7 +508,7 @@ function originWord(origin) {
     case 'SONARQUBE':
       return 'SonarQube';
     case 'FEEDBACK':
-      return 'Feedback';
+      return origin.label ? `Feedback (from ${origin.label})` : 'Feedback';
     case 'APPLICATION':
       return origin.label ? `An application (${origin.label})` : 'An application';
     case 'SESSION':
@@ -613,7 +615,7 @@ function renderEntry(entry) {
   }
   if (entry.tags?.length) {
     // R315. Sorted, so the export does not churn on the set's own order.
-    lines.push(`Tags: ${[...entry.tags].sort().join(', ')}`);
+    lines.push(`Tags: ${[...entry.tags].sort(byCodeUnit).join(', ')}`);
   }
   if (entry.assignee?.username) {
     // R331. Nothing for a card with nobody, so today's files stay byte-identical.

package/lib/runner-config.mjs

@@ -25,6 +25,15 @@
  * Adding a key that IS captured would make the daemon claim it applied
  * something it did not, which is worse than saying restart.
  */
+/**
+ * R577: the name this machine registers under — the environment first, then the
+ * file, then a default. The daemon and the CLI both ask it, so `cawdev config
+ * planning-limit` finds the same machine the daemon registered.
+ */
+export function runnerNameOf(file, env = process.env) {
+  return env.CAWDEV_RUNNER_NAME ?? file?.name ?? 'this-machine';
+}
+
 export const HOT_SWAPPABLE = Object.freeze(['agentCommands', 'grantable', 'acceptsRulesFromConsole',
   'autoWorkspaces']);
 

package/lib/secrets.mjs

@@ -217,7 +217,7 @@ export function withinScope(path, root, scope = null) {
  * daemon's cwd is not the checkout. A silent dependence on where the daemon
  * happens to be standing is exactly the bug this function exists to not have.
  */
-function normalise(path) {
+export function normalise(path) {
   const absolute = path.startsWith('/');
   const out = [];
   for (const part of path.split('/')) {
@@ -244,7 +244,7 @@ function normalise(path) {
  * zero-dep constraint is what makes `tools/` a directory somebody can read
  * before running it against their repositories.
  */
-function matches(path, glob) {
+export function matches(path, glob) {
   if (typeof glob !== 'string' || !glob) {
     return false;
   }

package/lib/sonar-analysis.mjs

@@ -0,0 +1,52 @@
+// The SonarQube server side of a scan, shared by the runner daemon
+// (tools/runner/runner.mjs, scanQuality) and `sonar.sh` (tools/quality/scan.mjs):
+// the scanner's report-task.txt, a GET with the scanner's own token, and the wait
+// for the server's analysis task. One place, so the two cannot drift (R584).
+// Zero dependencies, like all of tools/.
+
+/** A GET against the SonarQube server a scan just reported to, authorised with the scanner's own token. */
+export function sonarAsker(serverUrl, token) {
+  return async (path) => {
+    const response = await fetch(`${serverUrl}${path}`, { headers: { authorization: `Bearer ${token}` } });
+    if (!response.ok) {
+      throw new Error(`SonarQube answered ${response.status} to ${path.split('?')[0]}`);
+    }
+    return response.json();
+  };
+}
+
+/**
+ * Waits for a queued analysis to settle — shared by every scan path, BRANCH,
+ * MAIN and PROJECT alike. Throws rather than reports: every caller runs
+ * inside `scanQuality`'s own try/catch, which turns it into an error reading.
+ */
+export async function waitForAnalysis(ask, ceTaskId, deadline, timeoutSeconds) {
+  let settled = null;
+  while (Date.now() < deadline) {
+    const { task: current } = await ask(`/api/ce/task?id=${encodeURIComponent(ceTaskId)}`);
+    if (['SUCCESS', 'FAILED', 'CANCELED'].includes(current?.status)) {
+      settled = current;
+      break;
+    }
+    await new Promise((wake) => setTimeout(wake, 3000));
+  }
+  if (!settled) {
+    throw new Error(`SonarQube had not finished analysing after ${timeoutSeconds}s.`);
+  }
+  if (settled.status !== 'SUCCESS') {
+    throw new Error(settled.errorMessage ?? `SonarQube ${settled.status.toLowerCase()} the analysis.`);
+  }
+  return settled;
+}
+
+/** `key=value` lines — the shape of the scanner's `report-task.txt`. */
+export function parseProperties(text) {
+  const parsed = {};
+  for (const line of text.split('\n')) {
+    const at = line.indexOf('=');
+    if (at > 0) {
+      parsed[line.slice(0, at).trim()] = line.slice(at + 1).trim();
+    }
+  }
+  return parsed;
+}

package/lib/sonarqube-mcp.mjs

@@ -0,0 +1,50 @@
+// R319. What the daemon adds to SonarSource's MCP server before it is spawned.
+//
+// The registry row says WHAT to run (`java -jar <file name>`); this says where
+// the jar is on this machine and under which credentials, because those are
+// facts about the machine and the platform must not hold them. Pure, so the
+// three refusals can be tested without a daemon.
+
+import { isAbsolute, join } from 'node:path';
+
+/** The directory, on this machine, that holds the jar the row names. */
+export const JAR_DIR_ENV = 'CAWDEV_SONARQUBE_MCP_DIR';
+
+const trimSlash = (text) => String(text).replace(/\/+$/, '');
+
+/**
+ * The arguments and environment to spawn the server with, or the sentence
+ * saying why it is not attached. Never throws.
+ *
+ * - the token is `process.env[quality.tokenEnv]` — the credential R300 already
+ *   holds — and is put in the SERVER's environment only;
+ * - the URL is the machine's override, else the project's connection, so a
+ *   project on another server gets that server;
+ * - a machine with no `quality` block for the project, no token, no URL or no
+ *   jar directory does not get the server, and is told which.
+ */
+export function sonarqubeLaunch({ skill, quality, sonarUrl, env, storagePath }) {
+  const name = skill.name ?? skill.key;
+  const dir = env[JAR_DIR_ENV];
+  if (!dir || !isAbsolute(dir)) {
+    return { skip: `${name} was not attached: set ${JAR_DIR_ENV} to the absolute directory that `
+      + `holds ${skill.args.find((arg) => String(arg).endsWith('.jar')) ?? 'the server jar'}.` };
+  }
+  if (!quality) {
+    return { skip: `${name} was not attached: this machine has no "quality" block for this `
+      + 'project, so it holds no scanner token for the server to use.' };
+  }
+  const token = env[quality.tokenEnv];
+  if (!token) {
+    return { skip: `${name} was not attached: $${quality.tokenEnv} is not set on this machine.` };
+  }
+  const url = quality.url ?? sonarUrl;
+  if (!url) {
+    return { skip: `${name} was not attached: neither the project's connection nor this machine's `
+      + 'quality block names a SonarQube server.' };
+  }
+  return {
+    args: skill.args.map((arg) => (String(arg).endsWith('.jar') && !isAbsolute(arg) ? join(dir, arg) : arg)),
+    env: { SONARQUBE_TOKEN: token, SONARQUBE_URL: trimSlash(url), STORAGE_PATH: storagePath },
+  };
+}

package/lib/stage-tools.mjs

@@ -22,6 +22,15 @@
  * named string behind one named option — rather than an entry in `CAWDEV_READS`,
  * which would hand a write to every read-only stage of every profile and call it
  * a read.
+ *
+ * The second exception — R572 — is {@link SUGGEST}, `backlog_file`, and every
+ * read-only stage keeps it. It files FEEDBACK: a pending item a person accepts or
+ * refuses. It changes no file, no card, no status and no discussion, so "cannot
+ * change anything" survives it in every sense the claim was ever about. It is
+ * here because the read-only stages are where a session reads the most code and
+ * notices the most that is not this card's, and the only place that left them to
+ * say so was a report nobody files from. Named for `CARD_WRITE`'s reason: a
+ * writer let through on purpose, not a writer renamed a read.
  */
 
 /** Reading git without being able to change it. */
@@ -98,6 +107,26 @@ export const CAWDEV_READS = new Set([
  */
 const STAGE_READS = new Set([...CAWDEV_READS].filter((name) => name !== 'report'));
 
+/**
+ * R319. SonarSource's server, judged by a NAMED list for the reason
+ * {@link CAWDEV_READS} is: shape is the worst signal available, and here it is
+ * wrong — `change_sonar_issue_status`, `toggle_automatic_analysis` and
+ * `create_webhook` are writers the loose end-of-name test below reads as reads.
+ * What is not on this list is a writer, including a tool a later version adds.
+ * Pinned in stage-tools.test.mjs against the tool list read at 1.29.0.
+ */
+export const SONARQUBE_READS = new Set([
+  'show_rule', 'list_languages', 'search_sonar_issues_in_projects',
+  'search_security_hotspots', 'show_security_hotspot', 'get_project_quality_gate_status',
+  'list_quality_gates', 'get_component_measures', 'search_metrics',
+  'search_my_sonarqube_projects', 'list_branches', 'list_pull_requests',
+  'get_raw_source', 'search_files_by_coverage', 'get_file_coverage_details',
+  'search_duplicated_files', 'get_duplications',
+]);
+
+/** The `mcp__sonarqube__` prefix, once. */
+const SONARQUBE = 'mcp__sonarqube__';
+
 /** The `mcp__cawdev__` prefix, once. */
 const CAWDEV = 'mcp__cawdev__';
 
@@ -114,6 +143,15 @@ const REPORT = `${CAWDEV}report`;
  */
 export const CARD_WRITE = `${CAWDEV}roadmap_create`;
 
+/**
+ * The platform write every read-only stage may hold — R572. See the header.
+ *
+ * <p>A stage still only holds it when the PROFILE handed it over: this lets it
+ * through the read-only filter, it never adds it. `canChangeThings` goes on
+ * calling it a writer, which is what keeps it an exception.
+ */
+export const SUGGEST = `${CAWDEV}backlog_file`;
+
 /**
  * Reads that only mean something once the work exists — R302.
  *
@@ -221,6 +259,14 @@ export function canChangeThings(tool) {
   if (tool.startsWith(CAWDEV)) {
     return !STAGE_READS.has(tool.slice(CAWDEV.length));
   }
+  // The bare server (`mcp__sonarqube`) is Claude Code's whole-server grant and
+  // covers the writers too, so it is one.
+  if (tool === SONARQUBE.slice(0, -2)) {
+    return true;
+  }
+  if (tool.startsWith(SONARQUBE)) {
+    return !SONARQUBE_READS.has(tool.slice(SONARQUBE.length));
+  }
   // Everybody else's MCP tools, where shape is all there is: one that writes
   // usually says so in its name. A guess, and acceptable only because the
   // alternative — treating every third-party MCP tool as a writer — would strip
@@ -302,7 +348,8 @@ export function toolsForStage(stage, profileTools, testMode, options = {}) {
   const readOnly = (keepsCardWrite) => [
     ...allowed.filter((tool) => !canChangeThings(tool)
       || (delegates && DELEGATES.test(tool))
-      || (keepsCardWrite && tool === CARD_WRITE)),
+      || (keepsCardWrite && tool === CARD_WRITE)
+      || tool === SUGGEST),
     ...GIT_READS.filter((tool) => allowed.includes(tool) || allowed.includes('Bash(git *)')),
   ];
   switch (stage) {
@@ -412,6 +459,10 @@ export function driftedFrom(stage, toolLine, testMode, readOnlyExperts = [], opt
   if (stage === 'PLAN' && options.writesItsOwnCard && name === CARD_WRITE) {
     return null;
   }
+  // R572. Filing a suggestion is the other write a read-only stage was given.
+  if (name === SUGGEST) {
+    return null;
+  }
   return `cawdev: the ${stage} stage called ${name}, which it should not have been able to. `
     + notice;
 }

package/lib/version-files.mjs

@@ -0,0 +1,99 @@
+// R587: the project's version out of a file that declares it. Moved from
+// tools/release/plan.mjs so the release plan, `sonar.sh` (through
+// tools/quality/scan.mjs) and the daemon's scan (runner.mjs, scanQuality) read
+// a version one way. Pure and zero dependencies, like all of tools/.
+//
+// A file is told apart by its NAME: `pom.xml`, `package.json`, and a `.yaml` /
+// `.yml` with an `info:` block (openapi.yaml). Anything else has no version
+// here: null, never a guess.
+
+import { readFile } from 'node:fs/promises';
+import { basename, isAbsolute, resolve, sep } from 'node:path';
+
+/**
+ * The project's own version in a pom: the first `<version>` OUTSIDE
+ * `<parent>`, which carries Spring Boot's, and outside `<dependencies>`,
+ * `<build>` and the rest, which carry their libraries'.
+ */
+export function pomVersion(pom) {
+  const top = pom
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(parent|dependencies|dependencyManagement|build|profiles|properties)>[\s\S]*?<\/\1>/g, '');
+  const match = /<version>\s*([^<\s]+)\s*<\/version>/.exec(top);
+  return match ? match[1] : null;
+}
+
+/**
+ * `info.version` in openapi.yaml: a `version:` key directly under `info:`,
+ * at the block's own indentation: `info.description` is a block scalar
+ * with blank lines in it, and a deeper `version:` is somebody's schema.
+ */
+export function openapiVersion(yaml) {
+  const lines = yaml.split('\n');
+  const start = lines.findIndex((line) => /^info:\s*$/.test(line));
+  if (start === -1) return null;
+  let indent = null;
+  for (const line of lines.slice(start + 1)) {
+    if (!line.trim()) continue;
+    const own = /^(\s*)/.exec(line)[1].length;
+    if (own === 0) return null;
+    indent ??= own;
+    if (own !== indent) continue;
+    const match = /^\s*version:\s*['"]?([^'"\s]+)/.exec(line);
+    if (match) return match[1];
+  }
+  return null;
+}
+
+/** The top-level `version` of a package.json, or null (not JSON, no version). */
+export function packageJsonVersion(text) {
+  try {
+    const version = JSON.parse(text)?.version;
+    return typeof version === 'string' && version.trim() ? version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The version `text` declares, by what `path` is called; null for a kind it does not know. */
+export function versionOf(path, text) {
+  const name = basename(String(path));
+  if (name === 'pom.xml') return pomVersion(text);
+  if (name === 'package.json') return packageJsonVersion(text);
+  if (/\.ya?ml$/i.test(name)) return openapiVersion(text);
+  return null;
+}
+
+/**
+ * The first declared file that yields a version: `{version, file}`, or null.
+ * `read(path)` returns the text, or throws for a file that is not there; both
+ * a throw and a non-string mean "not this one". Order is the project's.
+ */
+export async function firstVersion(files, read) {
+  for (const file of files ?? []) {
+    let text;
+    try { text = await read(file); } catch { continue; }
+    if (typeof text !== 'string') continue;
+    const version = versionOf(file, text);
+    if (version) return { version, file };
+  }
+  return null;
+}
+
+/**
+ * R587: the first of the project's declared version files that parses, read
+ * from the workspace: `{version, file}` or null. A file that is missing, does
+ * not parse, or would climb out of the checkout is skipped, never an error.
+ * Only a branch analysis has a new-code period of its own and never touches the
+ * project's gate; a MAIN analysis (`whenBranchesRefused: "main"`) is the one
+ * the version matters to, since SonarQube reads a versionless one as a change.
+ */
+export async function workspaceVersion(cwd, files) {
+  const root = resolve(cwd);
+  return firstVersion(files, async (file) => {
+    if (isAbsolute(file)) return null;
+    const path = resolve(root, file);
+    if (path !== root && !path.startsWith(`${root}${sep}`)) return null;
+    return readFile(path, 'utf8');
+  });
+}