cawdev-cli 1.2.0 → 1.2.2

package/lib/finish-check.mjs

@@ -21,6 +21,13 @@ import { execFile } from 'node:child_process';
 import { notAllowed, protectedChanges } from './protected.mjs';
 import { findSecret } from './secrets.mjs';
 
+// R604. Where a SHOW stage leaves what it wants shown (stage-tools.mjs names it).
+// Never committed: the daemon keeps it out of git with `.git/info/exclude`,
+// deletes it after the upload, and the filter in `leftOver` is the backstop.
+import { SHOTS_DIR } from './stage-tools.mjs';
+
+export { SHOTS_DIR };
+
 /** The profiles whose run is a branch somebody will build on. */
 export const COMMITS_ITS_WORK = new Set(['CODE']);
 
@@ -57,7 +64,8 @@ export async function leftOver(cwd, branch, { git = runGit } = {}) {
   } catch {
     return null;
   }
-  const dirty = status.split('\n').map((line) => line.slice(3).trim()).filter(Boolean);
+  const dirty = status.split('\n').map((line) => line.slice(3).trim()).filter(Boolean)
+    .filter((path) => !path.startsWith(SHOTS_DIR));
   const current = (await git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']).catch(() => '')).trim();
   const remote = (await git(cwd, ['remote']).catch(() => '')).split('\n')[0]?.trim() || null;
   const exists = await git(cwd, ['rev-parse', '--verify', '-q', `refs/heads/${branch}`])

package/lib/gate-condition.mjs

@@ -0,0 +1,11 @@
+// R586 — one failed quality-gate condition in words. Shared by the MCP server
+// (`quality_get`) and `sonar.sh` (tools/quality/scan.mjs) so the two cannot
+// drift. Zero dependencies.
+
+/** One failed gate condition, as SonarQube words it: `new_violations 1287 > 0`. A rating's step is its letter. */
+export function describeCondition({ metric, comparator, threshold, actual }) {
+  const letter = (step) => ('12345'.includes(step) && step.length === 1 ? 'ABCDE'['12345'.indexOf(step)] : step);
+  if (metric.endsWith('_rating')) return `${metric} ${letter(actual)} worse than ${letter(threshold)}`;
+  const symbol = { GT: '>', LT: '<', EQ: '=', NE: '!=' }[comparator] ?? comparator;
+  return `${metric} ${actual} ${symbol} ${threshold}`;
+}

package/lib/sonar-analysis.mjs

@@ -4,14 +4,48 @@
 // 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]}`);
+export const SONAR_REQUEST_TIMEOUT_MS = 30_000;
+
+const isAbort = (error) =>
+  ['TimeoutError', 'AbortError'].includes(error?.name) || ['TimeoutError', 'AbortError'].includes(error?.cause?.name);
+
+/**
+ * A GET against the SonarQube server a scan just reported to, authorised with the
+ * scanner's own token. Every request is bounded (R622): by `requestTimeoutMs`, by
+ * the asker's `deadline`, and by a per-call `timeoutMs`, whichever is smallest.
+ * A cut-off request throws an error with `code === 'SONAR_TIMEOUT'`, and
+ * `byDeadline` true when the deadline or the per-call limit set the limit.
+ */
+export function sonarAsker(serverUrl, token, { requestTimeoutMs = SONAR_REQUEST_TIMEOUT_MS, deadline = Infinity } = {}) {
+  return async (path, { timeoutMs } = {}) => {
+    const pathOnly = path.split('?')[0];
+    const left = Math.min(deadline - Date.now(), timeoutMs ?? Infinity);
+    const byDeadline = left < requestTimeoutMs;
+    const limit = Math.max(1, Math.min(requestTimeoutMs, left));
+    try {
+      const response = await fetch(`${serverUrl}${path}`, {
+        headers: { authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(limit),
+      });
+      if (!response.ok) {
+        await response.body?.cancel().catch(() => {});
+        throw new Error(`SonarQube answered ${response.status} to ${pathOnly}`);
+      }
+      return await response.json();
+    } catch (error) {
+      if (!isAbort(error)) {
+        throw error;
+      }
+      const timeout = new Error(
+        byDeadline
+          ? `SonarQube did not answer ${pathOnly} before the reading's time ran out`
+          : `SonarQube did not answer ${pathOnly} within ${Math.ceil(limit / 1000)}s`,
+      );
+      timeout.code = 'SONAR_TIMEOUT';
+      timeout.limitMs = limit;
+      timeout.byDeadline = byDeadline;
+      throw timeout;
     }
-    return response.json();
   };
 }
 
@@ -19,16 +53,28 @@ export function sonarAsker(serverUrl, token) {
  * 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.
+ * Each poll is limited to the time left (R622), so one unanswered request
+ * cannot outlive the deadline.
  */
 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)}`);
+    let current;
+    try {
+      ({ task: current } = await ask(`/api/ce/task?id=${encodeURIComponent(ceTaskId)}`, {
+        timeoutMs: deadline - Date.now(),
+      }));
+    } catch (error) {
+      if (error?.code === 'SONAR_TIMEOUT' && error.byDeadline) {
+        break;
+      }
+      throw error;
+    }
     if (['SUCCESS', 'FAILED', 'CANCELED'].includes(current?.status)) {
       settled = current;
       break;
     }
-    await new Promise((wake) => setTimeout(wake, 3000));
+    await new Promise((wake) => setTimeout(wake, Math.min(3000, Math.max(0, deadline - Date.now()))));
   }
   if (!settled) {
     throw new Error(`SonarQube had not finished analysing after ${timeoutSeconds}s.`);

package/lib/stage-tools.mjs

@@ -152,6 +152,12 @@ export const CARD_WRITE = `${CAWDEV}roadmap_create`;
  */
 export const SUGGEST = `${CAWDEV}backlog_file`;
 
+/**
+ * The one folder a SHOW stage may write — R604. Repository-relative, with the
+ * trailing slash; `finish-check.mjs` has the same constant for its own reason.
+ */
+export const SHOTS_DIR = '.cawdev/shots/';
+
 /**
  * Reads that only mean something once the work exists — R302.
  *
@@ -312,7 +318,7 @@ export function canRunThings(tool) {
  * tools rather than a coding run's. That ordering is what keeps R28's decision
  * the outer one.
  *
- * @param stage one of PLAN, VERIFY, IMPLEMENT, TEST, MEMORY
+ * @param stage one of PLAN, VERIFY, IMPLEMENT, TEST, SHOW, MEMORY
  * @param profileTools what the run's profile allows
  * @param testMode R129, and only TEST reads it: `TESTBOOK` narrows the stage to
  *   what cannot run anything. Absent — an older platform that does not send it —
@@ -366,6 +372,20 @@ export function toolsForStage(stage, profileTools, testMode, options = {}) {
     case 'VERIFY':
     case 'MEMORY':
       return readOnly(false);
+    case 'SHOW':
+      // R604. The reads of a read-only stage, plus every Bash the profile
+      // allows (SHOW has to start the app and run the repository's own
+      // Playwright), plus an Edit narrowed to the shots folder. Bare Write,
+      // Edit, MultiEdit and NotebookEdit never pass through. Bash can still
+      // write anywhere, and that is said plainly: this list is not the guard.
+      // The guard is the daemon's tree check after the stage, and SHOW is
+      // spawned with no permission mode so anything off this list goes to a
+      // person.
+      return [...new Set([
+        ...readOnly(false),
+        ...allowed.filter((tool) => /^Bash\b/.test(tool)),
+        `Edit(./${SHOTS_DIR}**)`,
+      ])];
     case 'TEST':
       // R129. The mirror of the claim above, with the other question asked: a
       // stage that may WRITE and cannot RUN. Same filtering of the PROFILE's
@@ -420,7 +440,7 @@ function readsGit(toolLine) {
  * person who needs to know is the one reading the run.
  */
 export function driftedFrom(stage, toolLine, testMode, readOnlyExperts = [], options = {}) {
-  const readOnly = stage === 'PLAN' || stage === 'VERIFY' || stage === 'MEMORY';
+  const readOnly = stage === 'PLAN' || stage === 'VERIFY' || stage === 'MEMORY' || stage === 'SHOW';
   // R129. A TEST stage set to write the testbook has its own thing it should
   // not have been able to do, and the same reason for saying so out loud.
   const testbook = stage === 'TEST' && testMode === 'TESTBOOK';
@@ -445,6 +465,17 @@ export function driftedFrom(stage, toolLine, testMode, readOnlyExperts = [], opt
   if (!canChangeThings(name)) {
     return null;
   }
+  // R604. SHOW ran something, which it is allowed to (the app, Playwright), or
+  // wrote into its own folder, which is what it is for.
+  if (stage === 'SHOW') {
+    if (/^Bash\b/.test(name)) {
+      return null;
+    }
+    if (/^(Write|Edit|MultiEdit)/.test(name) && String(toolLine).includes(SHOTS_DIR)
+        && !String(toolLine).includes('..')) {
+      return null;
+    }
+  }
   // R147. A delegation to an expert this stage was allowed is the one call
   // `canChangeThings` names a writer that is not one here. `describeCall`
   // writes it as `Agent(<name>) …`, and the name is the CLI's qualified one.

package/mcp/server.mjs

@@ -26,6 +26,7 @@ import {
 } from '../lib/protected.mjs';
 import { findDestructive, withinScope } from '../lib/secrets.mjs';
 import { byCodeUnit } from '../lib/order.mjs';
+import { describeCondition } from '../lib/gate-condition.mjs';
 import { COMMITS_ITS_WORK, isUnfinished, leftOver, notDoneYet } from '../lib/finish-check.mjs';
 
 const NAME = 'cawdev';
@@ -300,10 +301,14 @@ function renderRounds(where) {
  * by counting is an agent one skipped question away from acting on the wrong
  * one.
  */
+/** R612: the platform closes a question with no person behind it; it reaches us as this. */
+const THE_PLATFORM = '(the platform)';
+const bySomeone = (email) => Boolean(email) && email !== THE_PLATFORM;
+
 function renderRound(asked, answered) {
   const title = asked?.title ?? 'The round';
   const lines = answered.map((question, at) => {
-    const said = question.answeredByEmail
+    const said = bySomeone(question.answeredByEmail)
       ? `${question.answeredByEmail}: ${question.answer}`
       : question.answer;
     const opinions = (question.opinions ?? [])
@@ -328,7 +333,10 @@ function renderAnswer(answered) {
     .map((opinion) => `  ${opinion.authorEmail}: ${opinion.body}`)
     .join('\n');
 
-  const answer = `${answered.answeredByEmail} answered:\n\n${answered.answer}`;
+  // R612: no answeredByEmail means the platform closed it, not a person.
+  const answer = bySomeone(answered.answeredByEmail)
+    ? `${answered.answeredByEmail} answered:\n\n${answered.answer}`
+    : `Nobody answered — the question was closed:\n\n${answered.answer}`;
   return said ? `${answer}\n\nWhat people said before deciding:\n${said}` : answer;
 }
 
@@ -1692,7 +1700,7 @@ const TOOLS = [
       if (answered) {
         return renderRound(null, answered);
       }
-      return `Still unfinished. Call await_group again with group_id ${args.group_id}.`;
+      return `Still unfinished. Call await_group again with group_id ${args.group_id} to keep waiting. If you carry on instead, the round stays in their inbox — and the run reads as waiting on them — until this stage ends; then it is closed, and an answer given after that is refused.`;
     },
   },
 
@@ -1773,7 +1781,7 @@ const TOOLS = [
       if (answered) {
         return renderAnswer(answered);
       }
-      return `Still nothing. Call await_answer again with question_id ${args.question_id}.`;
+      return `Still nothing. Call await_answer again with question_id ${args.question_id} to keep waiting. If you carry on instead, the question stays in their inbox — and the run reads as waiting on them — until this stage ends; then it is closed, and an answer given after that is refused.`;
     },
   },
 
@@ -2005,6 +2013,36 @@ async function protectedAllowedNow(config, project, runId, policy) {
   return allowed;
 }
 
+/**
+ * R318: what a branch scan made of the finding the card was filed from, in the
+ * words the console uses (frontend `core/proven-words.ts`): still reported
+ * beats not checked beats fixed. Null when the card has no finding to prove.
+ */
+function provenLine(row) {
+  const findings = row.findings ?? [];
+  if (!findings.length) return null;
+  const name = (finding) => {
+    const rule = finding.rule ? finding.rule.replace(/^[^:]*:/, '') : finding.key;
+    const file = finding.path ? finding.path.split('/').pop() : null;
+    return file ? `${rule} in ${file}` : rule;
+  };
+  const named = (verdict) => findings.filter((finding) => finding.verdict === verdict).map(name).join(', ');
+  const plural = (n, noun) => `${n} new ${noun}${n === 1 ? '' : 's'}`;
+  const bugs = row.newBugs ?? null;
+  const vulnerabilities = row.newVulnerabilities ?? null;
+  let clause = null;
+  if (bugs !== null || vulnerabilities !== null) {
+    const parts = [];
+    if (bugs) parts.push(plural(bugs, 'bug'));
+    if (vulnerabilities) parts.push(vulnerabilities === 1 ? '1 new vulnerability' : `${vulnerabilities} new vulnerabilities`);
+    clause = parts.length ? parts.join(' and ') : '0 new problems';
+  }
+  const tail = clause ? ` · ${clause}` : '';
+  if (named('STILL_OPEN')) return `Still reported: ${named('STILL_OPEN')}${tail}`;
+  if (named('UNCHECKED')) return `Not checked: ${named('UNCHECKED')} (restart the daemon)`;
+  return named('FIXED') ? `Fixed ${named('FIXED')}${tail}` : null;
+}
+
 /**
  * The protected-file gate on `report done` — R562. Null when the branch is
  * clean of unallowed protected changes (or nothing can be judged), else the
@@ -2390,14 +2428,6 @@ function formatFileDeps(map, path) {
 /** How many finding lines a reading prints before saying "and N more" — R302. */
 const FINDING_LINES = 50;
 
-/** One failed gate condition, as SonarQube words it: `new_violations 1287 > 0`. A rating's step is its letter. */
-function describeCondition({ metric, comparator, threshold, actual }) {
-  const letter = (step) => ('12345'.includes(step) && step.length === 1 ? 'ABCDE'['12345'.indexOf(step)] : step);
-  if (metric.endsWith('_rating')) return `${metric} ${letter(actual)} worse than ${letter(threshold)}`;
-  const symbol = { GT: '>', LT: '<', EQ: '=', NE: '!=' }[comparator] ?? comparator;
-  return `${metric} ${actual} ${symbol} ${threshold}`;
-}
-
 /**
  * The reading as a session should read it — R302: one line for the default
  * branch, one for the branch asked about, then the open findings.
@@ -2467,6 +2497,8 @@ function formatQualityReading(reading, branch) {
       if (row.dashboardUrl) parts.push(row.dashboardUrl);
       lines.push(`Branch ${asked.branch}: ${parts.join(' · ')}`);
       if (row.warning) lines.push(`  ${row.warning}`);
+      const proven = provenLine(row);
+      if (proven) lines.push(`  ${proven}`);
     }
   } else if (branch === null) {
     lines.push('No branch was read: outside a run, name one to see its gate and new problems.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cawdev-cli",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "cawdev's terminal client and runner daemon — zero dependencies, on purpose",
   "type": "module",
   "bin": {