breakaway 1.4.0-main.2 → 1.4.0-main.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.4.0-main.2",
+  "version": "1.4.0-main.20",
   "description": "The task board for you and your coding agents: a Cloudflare Worker, its web app, Taskwarrior sync, and the CLI (npx breakaway).",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",
@@ -21,13 +21,16 @@
     "!scripts/install/*.test.js",
     "src/cli-version.js",
     "src/decision.js",
+    "src/init.js",
     "src/install.js",
     "src/model.js",
+    "src/packages.js",
     "src/ping.js",
     "src/promote.js",
     "src/prompt.js",
     "src/redact.js",
     "src/repos.js",
+    "src/specs.js",
     "src/versions.js",
     "prompts/*.md",
     "taskrc",

package/scripts/board-files.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Writes src/board-files.json (BRK-132): the board's files repos init reads (boardSources in src/init.js), by path,
+ * so the Worker renders an empty repository's first commit from the same files as the CLI. scripts/tasks/init.test.js
+ * fails when it's behind them; run `node scripts/board-files.mjs` after changing one.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { boardSources } from '../src/init.js';
+
+const ROOT = new URL('../', import.meta.url);
+const read = (path) => readFileSync(new URL(path, ROOT), 'utf8');
+
+export const boardFiles = () => Object.fromEntries(boardSources(read).map((path) => [path, read(path)]));
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  writeFileSync(new URL('src/board-files.json', ROOT), `${JSON.stringify(boardFiles(), null, 2)}\n`);
+  console.log('Wrote src/board-files.json.');
+}

package/scripts/deploy-plan.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * The steps a repository's Deploy, Promote, Roll back, and Release workflows run before they act
+ * (scripts/lib/deploy-plan.js). Each prints key=value lines for $GITHUB_OUTPUT and its reason on stderr.
+ *   node scripts/deploy-plan.mjs checks --sha <commit> --checks '["CI"]'
+ *       ready=true when every check workflow passed on the commit
+ *   node scripts/deploy-plan.mjs plan --staging <worker> --sha <commit> --checks '["CI"]' [--branch main] [--paths <file>]
+ *       deploy=true when staging should deploy the commit, and from=<the commit staging ran before>
+ *   node scripts/deploy-plan.mjs live --environment <worker>              sha=<the commit it runs>
+ *   node scripts/deploy-plan.mjs sha-of --environment <worker> --version <id>   sha=<the commit that version came from>
+ *   node scripts/deploy-plan.mjs current < deployments.json               version=<what wrangler deployments list runs>
+ *   node scripts/deploy-plan.mjs uploaded < wrangler-output.ndjson        version=<what wrangler just uploaded>
+ *   node scripts/deploy-plan.mjs missing < wrangler-error.txt             exits 1 unless the Worker doesn't exist yet
+ * Reads GITHUB_TOKEN and GITHUB_REPOSITORY (or --repo owner/name). Copied into a repository by `repos init`.
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import {
+  checksPassed,
+  currentVersionId,
+  deployPatterns,
+  liveSha,
+  planDeploy,
+  shaOfVersion,
+  uploadedVersionId,
+  workerMissing,
+} from './lib/deploy-plan.js';
+import { USER_AGENT, deploymentsOf } from './lib/deployments.js';
+
+const { positionals, values: o } = parseArgs({
+  allowPositionals: true,
+  options: {
+    repo: { type: 'string' },
+    sha: { type: 'string' },
+    checks: { type: 'string' },
+    staging: { type: 'string' },
+    branch: { type: 'string', default: 'main' },
+    paths: { type: 'string' },
+    environment: { type: 'string' },
+    version: { type: 'string' },
+  },
+});
+const token = process.env.GITHUB_TOKEN;
+const repo = o.repo ?? process.env.GITHUB_REPOSITORY;
+const stdin = () => readFileSync(0, 'utf8');
+
+/** @returns {Promise<any>} */
+async function get(path) {
+  const res = await fetch(`https://api.github.com/repos/${repo}${path}`, {
+    headers: {
+      accept: 'application/vnd.github+json',
+      authorization: `Bearer ${token}`,
+      'user-agent': USER_AGENT,
+      'x-github-api-version': '2022-11-28',
+    },
+  });
+  if (!res.ok) throw new Error(`GitHub answered ${res.status} for ${path}: ${(await res.text()).slice(0, 200)}`);
+  return res.json();
+}
+
+async function checks() {
+  if (!/^[0-9a-f]{40}$/u.test(o.sha ?? '')) throw new Error('Give the full commit: --sha <commit>.');
+  let names;
+  try {
+    names = JSON.parse(o.checks ?? '');
+  } catch {
+    names = null;
+  }
+  if (!Array.isArray(names) || !names.length) throw new Error('Name the check workflows as JSON: --checks \'["CI"]\'.');
+  const { workflow_runs: runs } = await get(`/actions/runs?head_sha=${o.sha}&per_page=100`);
+  return checksPassed(runs, names, o.sha);
+}
+
+/** The files changed between two commits, or null when git can't say (the older one isn't in this checkout). */
+function changedFiles(from, to) {
+  try {
+    return execFileSync('git', ['diff', '--name-only', from, to], { encoding: 'utf8' }).split('\n').filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+try {
+  const [command] = positionals;
+  if (command === 'checks') {
+    const result = await checks();
+    console.error(result.reason);
+    console.log(`ready=${result.ready}`);
+  } else if (command === 'plan') {
+    if (!o.staging) throw new Error('Name the staging Worker: --staging <worker>.');
+    const ready = await checks();
+    const [tip, staging] = ready.ready
+      ? await Promise.all([
+          get(`/commits/${encodeURIComponent(o.branch)}`),
+          deploymentsOf({ token, repo, environment: o.staging }),
+        ])
+      : [null, []];
+    const from = staging.find((d) => d.task === 'deploy' && d.state === 'success')?.sha;
+    const patterns = o.paths ? deployPatterns(JSON.parse(readFileSync(o.paths, 'utf8'))) : [];
+    const plan = planDeploy({
+      sha: o.sha,
+      tip: tip?.sha ?? null,
+      checks: ready,
+      staging,
+      files: from ? changedFiles(from, o.sha) : null,
+      patterns,
+    });
+    console.error(plan.reason);
+    console.log(`deploy=${plan.deploy}\nfrom=${plan.from}`);
+  } else if (command === 'live' || command === 'sha-of') {
+    if (!o.environment) throw new Error('Name the Worker: --environment <worker>.');
+    const list = await deploymentsOf({ token, repo, environment: o.environment });
+    console.log(`sha=${(command === 'live' ? liveSha(list) : shaOfVersion(list, o.version)) ?? ''}`);
+  } else if (command === 'current') {
+    console.log(`version=${currentVersionId(JSON.parse(stdin() || '[]')) ?? ''}`);
+  } else if (command === 'uploaded') {
+    const version = uploadedVersionId(stdin());
+    if (!version) throw new Error("wrangler's output names no version it uploaded.");
+    console.log(`version=${version}`);
+  } else if (command === 'missing') {
+    if (!workerMissing(stdin()))
+      throw new Error(
+        "Couldn't list the Worker's deployments, so there would be nothing to roll back to. Check that CLOUDFLARE_ACCOUNT_ID is your account's ID and that CLOUDFLARE_API_TOKEN can read and edit the Worker.",
+      );
+    console.log('missing=true');
+  } else {
+    throw new Error(
+      'Usage: deploy-plan.mjs checks | plan | live | sha-of | current | uploaded | missing (see the file)',
+    );
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/scripts/lib/deploy-plan.js

@@ -0,0 +1,102 @@
+/**
+ * What a repository's Deploy, Promote, Roll back, and Release workflows decide before they act
+ * (docs/specs/IDEA-27-move-ci-cd-to-the-deploy-flow.md, section 2): whether every check passed on the commit,
+ * whether staging needs it, and which Worker version is which. Pure over GitHub's and wrangler's answers, so the
+ * tests run without either. Copied into a repository by `repos init`, with scripts/deploy-plan.mjs.
+ */
+import { candidate, productionSha, versionOf } from './promote.js';
+
+/**
+ * Whether every check workflow passed on `sha`. `runs` are GitHub's workflow runs for the commit
+ * (`{ id, name, head_sha, status, conclusion }`); each check counts by its latest run.
+ * @param {Array<{ id: number, name: string, head_sha: string, status: string, conclusion: string | null }>} runs
+ * @param {string[]} checks the check workflows' names
+ * @param {string} sha
+ * @returns {{ ready: boolean, reason: string }}
+ */
+export function checksPassed(runs, checks, sha) {
+  const latest = new Map();
+  for (const run of runs ?? []) {
+    if (run.head_sha !== sha || !checks.includes(run.name)) continue;
+    if (!latest.has(run.name) || latest.get(run.name).id < run.id) latest.set(run.name, run);
+  }
+  const short = sha.slice(0, 7);
+  const missing = checks.filter((name) => !latest.has(name));
+  if (missing.length) return { ready: false, reason: `${missing.join(', ')} hasn't run on ${short} yet.` };
+  const failed = checks.filter(
+    (name) => latest.get(name).status === 'completed' && latest.get(name).conclusion !== 'success',
+  );
+  if (failed.length) return { ready: false, reason: `${failed.join(', ')} didn't pass on ${short}.` };
+  const running = checks.filter((name) => latest.get(name).status !== 'completed');
+  if (running.length)
+    return { ready: false, reason: `${running.join(', ')} is still running on ${short}; its own run deploys it.` };
+  return { ready: true, reason: `${checks.join(', ')} passed on ${short}.` };
+}
+
+/**
+ * Whether staging should deploy `sha`. `tip` is the branch's latest commit, `staging` the staging Worker's
+ * Deployments (newest first, as deploymentsOf reads them), `files` the paths changed since staging's last successful
+ * deploy (null when they can't be known), and `patterns` the deploy paths' regular expressions.
+ * @returns {{ deploy: boolean, from: string, reason: string }}
+ */
+export function planDeploy({ sha, tip, checks, staging, files, patterns }) {
+  const short = sha.slice(0, 7);
+  const no = (reason, from = '') => ({ deploy: false, from, reason });
+  if (!checks.ready) return no(checks.reason);
+  if (tip && tip !== sha)
+    return no(`${short} isn't the branch's latest commit any more: ${tip.slice(0, 7)} deploys next, with it.`);
+  const last = candidate(staging ?? []);
+  const from = last?.sha ?? '';
+  if (from === sha) return no(`Staging already runs ${short}.`, from);
+  if (!from) return { deploy: true, from, reason: `Staging has no deploy yet, so ${short} goes first.` };
+  if (files && patterns?.length && !files.some((file) => patterns.some((pattern) => pattern.test(file))))
+    return no(`Nothing since ${from.slice(0, 7)} touches the deploy paths, so staging stays as it is.`, from);
+  return { deploy: true, from, reason: `${short} goes to staging, after ${from.slice(0, 7)}.` };
+}
+
+/** The deploy paths file (`{ worker: "regex" }`) as regular expressions; a pattern that doesn't compile is an error. */
+export function deployPatterns(json) {
+  if (!json || typeof json !== 'object' || Array.isArray(json))
+    throw new Error('The deploy paths file is an object of Worker names and regular expressions.');
+  return Object.entries(json).map(([worker, pattern]) => {
+    try {
+      return new RegExp(String(pattern), 'u');
+    } catch {
+      throw new Error(`The deploy path for ${worker} isn't a regular expression: ${pattern}`);
+    }
+  });
+}
+
+/** The version a Worker runs, from `wrangler deployments list --json`: what a rollback goes back to. */
+export function currentVersionId(deployments) {
+  const list = Array.isArray(deployments) ? deployments : [];
+  const newest = [...list].sort((a, b) => String(b.created_on ?? '').localeCompare(String(a.created_on ?? '')))[0];
+  const best = [...(newest?.versions ?? [])].sort((a, b) => (b.percentage ?? 0) - (a.percentage ?? 0))[0];
+  return best?.version_id ?? null;
+}
+
+/** The version wrangler just uploaded or deployed, from its output file (WRANGLER_OUTPUT_FILE_PATH, one JSON a line). */
+export function uploadedVersionId(ndjson) {
+  const entries = String(ndjson ?? '')
+    .split('\n')
+    .filter((line) => line.trim())
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+  return entries.filter((e) => ['version-upload', 'deploy'].includes(e.type) && e.version_id).pop()?.version_id ?? null;
+}
+
+/** Whether wrangler's output from a failed `deployments list` says the Worker doesn't exist yet (Cloudflare error 10007). */
+export const workerMissing = (output) =>
+  /\[code: 10007\]|worker does not exist on your account/iu.test(String(output ?? ''));
+
+/** The commit an environment runs now: its latest successful deploy or rollback. */
+export const liveSha = (deployments) => productionSha(deployments ?? []);
+
+/** The commit a Worker version was deployed from, by the Deployments that recorded it. */
+export const shaOfVersion = (deployments, version) =>
+  (deployments ?? []).find((d) => d.state === 'success' && versionOf(d.description) === version)?.sha ?? null;

package/scripts/lib/package-release.js

@@ -0,0 +1,71 @@
+/**
+ * The version numbers of a repository's npm releases (docs/specs/IDEA-27-move-ci-cd-to-the-deploy-flow.md, section
+ * 2b), worked out the way breakaway's own Release workflow does (scripts/release/lib.js uses these): every merge
+ * stages `X.Y.Z-main.N` on next, and the owner promotes one to a stable `X.Y.Z` on latest. The tags remember the
+ * numbers: `<prefix>X.Y.Z-main.N` for each pre-release and `<prefix>X.Y.Z` for each stable, where the prefix is `v`,
+ * or `<package>@` in a repository whose production deploys already tag `v…`. Pure, so it's tested without git.
+ * Copied into a repository by `repos init`, with scripts/package-release.mjs.
+ */
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/u;
+const escapeRegex = (text) => text.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+const prereleasePattern = (prefix) => new RegExp(`^${escapeRegex(prefix)}(\\d+\\.\\d+\\.\\d+)-main\\.(\\d+)$`, 'u');
+const stablePattern = (prefix) => new RegExp(`^${escapeRegex(prefix)}(\\d+\\.\\d+\\.\\d+)$`, 'u');
+
+/** @param {string} v @returns {[number, number, number]} */
+function parts(v) {
+  const m = SEMVER.exec(v);
+  if (!m) throw new Error(`"${v}" isn't a version like 1.4.0.`);
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/** Negative, zero, or positive, like a sort comparator, for two X.Y.Z versions. */
+export function compareVersions(a, b) {
+  const [x, y] = [parts(a), parts(b)];
+  return x[0] - y[0] || x[1] - y[1] || x[2] - y[2];
+}
+
+/** The tags' prefix: `v`, or `<package>@` when the repository's production deploys already tag `v…`. */
+export const tagPrefix = (name, { workers = false } = {}) => (workers ? `${name}@` : 'v');
+
+/**
+ * The next pre-release. `current` is package.json's version, the release being worked toward; once its stable tag
+ * exists the work is toward the next patch, so a pre-release never sorts below a stable.
+ * @param {string} current
+ * @param {string[]} tags every tag in the repository
+ * @param {string} [prefix]
+ * @returns {{ version: string, base: string, tag: string }}
+ */
+export function nextPrerelease(current, tags, prefix = 'v') {
+  parts(current);
+  const stable = stablePattern(prefix);
+  const prerelease = prereleasePattern(prefix);
+  const stables = tags.map((t) => stable.exec(t)?.[1]).filter(Boolean);
+  let base = current;
+  for (const s of stables) {
+    if (compareVersions(s, base) >= 0) {
+      const [maj, min, pat] = parts(s);
+      base = `${maj}.${min}.${pat + 1}`;
+    }
+  }
+  const last = tags
+    .map((t) => prerelease.exec(t))
+    .filter((m) => m?.[1] === base)
+    .reduce((n, m) => Math.max(n, Number(m[2])), 0);
+  const version = `${base}-main.${last + 1}`;
+  return { version, base, tag: `${prefix}${version}` };
+}
+
+/** The pre-release among `tags` (the tags on one commit), if one was already staged from it. */
+export function prereleaseAmong(tags, prefix = 'v') {
+  const prerelease = prereleasePattern(prefix);
+  const tag = tags.find((t) => prerelease.test(t));
+  return tag ? { tag, version: tag.slice(prefix.length) } : null;
+}
+
+/** The stable version a pre-release tag (`v1.4.0-main.37`) is promoted to. */
+export function stableOf(prereleaseTag, prefix = 'v') {
+  const m = prereleasePattern(prefix).exec(prereleaseTag);
+  if (!m) throw new Error(`"${prereleaseTag}" isn't a pre-release tag like ${prefix}1.4.0-main.37.`);
+  return m[1];
+}

package/scripts/package-release.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * The Release workflow's version numbers for a repository's npm package (scripts/lib/package-release.js). Prints
+ * key=value lines for $GITHUB_OUTPUT.
+ *   node scripts/package-release.mjs prerelease --dir <path> --prefix <tag prefix> [--sha <commit>]
+ *       the next pre-release's version and tag, from <path>/package.json and the repository's tags; with --sha,
+ *       exists=true when that commit already has a pre-release (a second run for one merge stages nothing)
+ *   node scripts/package-release.mjs stable <pre-release tag> --prefix <tag prefix>
+ *       the stable version and tag it becomes, and the commit it was staged from; stops if that stable exists
+ * Reads the tags with git, so run it in a checkout with its tags (fetch-depth: 0). Copied by `repos init`.
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { nextPrerelease, prereleaseAmong, stableOf } from './lib/package-release.js';
+
+const { positionals, values: o } = parseArgs({
+  allowPositionals: true,
+  options: { dir: { type: 'string', default: '.' }, prefix: { type: 'string', default: 'v' }, sha: { type: 'string' } },
+});
+const git = (...args) => execFileSync('git', args, { encoding: 'utf8' }).split('\n').filter(Boolean);
+
+try {
+  const [command, tag] = positionals;
+  if (command === 'prerelease') {
+    const current = JSON.parse(readFileSync(join(o.dir, 'package.json'), 'utf8')).version;
+    const staged = o.sha ? prereleaseAmong(git('tag', '--points-at', o.sha), o.prefix) : null;
+    if (staged) {
+      console.error(`${o.sha.slice(0, 7)} already has a pre-release, ${staged.tag}, so this run stages nothing.`);
+      console.log(`version=${staged.version}\ntag=${staged.tag}\nexists=true`);
+    } else {
+      const next = nextPrerelease(current, git('tag', '-l'), o.prefix);
+      console.log(`version=${next.version}\ntag=${next.tag}\nexists=false`);
+    }
+  } else if (command === 'stable' && tag) {
+    const version = stableOf(tag, o.prefix);
+    const tags = git('tag', '-l');
+    if (!tags.includes(tag)) throw new Error(`There is no pre-release ${tag}. Pick one the Release workflow staged.`);
+    if (tags.includes(`${o.prefix}${version}`))
+      throw new Error(`${o.prefix}${version} is already released. Pick a newer pre-release.`);
+    const [commit] = git('rev-list', '-n', '1', `refs/tags/${tag}`);
+    console.log(`version=${version}\ntag=${o.prefix}${version}\ncommit=${commit}`);
+  } else {
+    throw new Error(
+      'Usage: package-release.mjs prerelease --dir <path> --prefix <p> [--sha <commit>] | stable <tag> --prefix <p>',
+    );
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/scripts/tasks/cli.js

@@ -14,6 +14,7 @@ export const SUBCOMMANDS = {
   horizon: ['close'],
   hook: ['session', 'wait'],
   peloton: ['checkin', 'step', 'reply'],
+  specs: ['list', 'show'],
 };
 
 /** Commands that take nothing after their name, so a word there is a mistake (an old copy's missing subcommand, say). */
@@ -104,6 +105,21 @@ export function pullAgentRequest(action, number, { repo = null, problem, note, f
   return { request: ['POST', `github/pulls/${n}/${action}`, body] };
 }
 
+/**
+ * `npx breakaway github release <pre-release>` (BRK-103): the owner releases a package's pre-release as its stable, as
+ * Release on the GitHub page does. The board starts the repository's release.yml stable job, and npm waits for the
+ * owner's 2FA; it refuses an agent, so the request always says who asks.
+ * @param {string | undefined} version the pre-release, like 1.4.0-main.5 (or its tag)
+ * @param {{ repo?: string | null, by?: string }} [options]
+ * @returns {{ error?: string, request?: [string, string, Record<string, string>] }}
+ */
+export function packageReleaseRequest(version, { repo = null, by } = {}) {
+  const v = String(version ?? '').trim();
+  if (!/^(?:\S+@|v)?\d+\.\d+\.\d+-main\.\d+$/u.test(v))
+    return { error: 'say which pre-release: npx breakaway github release <version>, like 1.4.0-main.5' };
+  return { request: ['POST', 'github/release', { version: v, ...(repo ? { repo } : {}), ...(by ? { by } : {}) }] };
+}
+
 export const REVIEW_VERDICTS = ['ready', 'follow-up', 'changes'];
 
 /**
@@ -148,17 +164,27 @@ export function forceFields(force, by) {
  * With `decision` (`agents new --decision <ID> ["<note>"]`, BRK-110) the board writes the prompt from that answered
  * decision, in the decision's repository, and the text is the owner's note under it. With `next`
  * (`agents new --next minor|major ["<note>"]`, BRK-100) it writes the prompt that sets the repository's next version.
+ * With `spec` (`agents new --spec <path> "<what should change>"`, BRK-121) it writes the prompt that refines that spec
+ * and the tasks that link it, and the text, required, is what should change.
  * @param {string} prompt
- * @param {{ repo?: string | null, force?: boolean, by?: string, decision?: string | null, next?: string | null }} [options]
+ * @param {{ repo?: string | null, force?: boolean, by?: string, decision?: string | null, next?: string | null, spec?: string | null }} [options]
  */
-export function generalAgentRequest(prompt, { repo = null, force = false, by, decision = null, next = null } = {}) {
+export function generalAgentRequest(
+  prompt,
+  { repo = null, force = false, by, decision = null, next = null, spec = null } = {},
+) {
   const text = String(prompt ?? '').trim();
-  if (decision && next) return { error: 'start one from --decision or --next, not both' };
+  if ([decision, next, spec].filter(Boolean).length > 1)
+    return { error: 'start one from --decision, --spec, or --next: only one of them' };
   if (next && !['minor', 'major'].includes(next))
     return { error: 'patches count by themselves: --next minor or --next major' };
+  if (spec && !text)
+    return {
+      error: 'say what should change in the spec: npx breakaway agents new --spec <path> "<what should change>"',
+    };
   if (!text && !decision && !next)
     return { error: 'say what the agent should do: npx breakaway agents new "Tidy the docs" [--image <file>]' };
-  const board = decision ? { decision } : next ? { next } : null;
+  const board = decision ? { decision } : next ? { next } : spec ? { spec: specPath(spec) } : null;
   const body = {
     ...(board ? { ...board, ...(text ? { note: text } : {}) } : { prompt: text }),
     ...(repo ? { repo } : {}),
@@ -170,18 +196,54 @@ export function generalAgentRequest(prompt, { repo = null, force = false, by, de
 
 /**
  * What the CLI says about a general agent's answer: the task and that it started, or why it waits (and whether Force
- * start could skip that), or, from a decision or for the next version (`next`), the open one that already has it.
+ * start could skip that), or, from a decision, for the next version (`next`), or on a spec (`spec`), the open one
+ * that already has it.
  * @param {{ task: { wid?: string, short?: string }, run?: { url?: string, agent?: string } | null, waiting?: string | null, forceable?: boolean, already?: string | null }} answer
- * @param {{ next?: string | null }} [options]
+ * @param {{ next?: string | null, spec?: unknown }} [options]
  */
-export function generalAgentSummary({ task, run, waiting, forceable, already }, { next = null } = {}) {
+export function generalAgentSummary({ task, run, waiting, forceable, already }, { next = null, spec = null } = {}) {
   const id = task.wid ?? task.short;
-  if (!run && already)
-    return `${id} already ${next ? 'prepares the next version' : 'refines from these answers'}: ${already}.`;
+  if (!run && already) {
+    const what = next ? 'prepares the next version' : spec ? 'refines this spec' : 'refines from these answers';
+    return `${id} already ${what}: ${already}.`;
+  }
   if (run) return `Started ${run.agent ? `${run.agent} ` : 'an agent '}on ${id}${run.url ? `: ${run.url}` : ''}`;
   return `Saved ${id}, waiting to start: ${waiting ?? 'no room yet'}.${forceable ? ` Start it now past the board's limits: npx breakaway agents start ${id} --force` : ''}`;
 }
 
+/** A spec's path as the board reads it: no leading `./`, no doubled or trailing slashes. */
+const specPath = (path) =>
+  String(path ?? '')
+    .trim()
+    .replace(/^(\.\/)+/u, '')
+    .split('/')
+    .filter((part) => part && part !== '.')
+    .join('/');
+
+/**
+ * The request behind `npx breakaway specs [list]` (BRK-121): the specs of the checkout's repository, or the one `--repo`
+ * names; without either, the board answers with its default repository's.
+ * @param {string | null} repo
+ * @returns {[string, string, undefined]}
+ */
+export function specsRequest(repo) {
+  return ['GET', repo ? `specs?repo=${encodeURIComponent(repo)}` : 'specs', undefined];
+}
+
+/**
+ * The request behind `npx breakaway specs show <path>` (BRK-121): one spec, by its path in the repository. The board
+ * refuses a path outside the specs directory; one that climbs out with `..` is refused here first.
+ * @param {string | undefined} path
+ * @param {string | null} repo
+ */
+export function specRequest(path, repo) {
+  const clean = specPath(path);
+  if (!clean) return { error: 'say which spec: npx breakaway specs show <path>, like docs/specs/BRK-1-thing.md' };
+  if (clean.split('/').includes('..')) return { error: `${clean.slice(0, 200)} climbs out of the repository` };
+  const query = repo ? `?repo=${encodeURIComponent(repo)}` : '';
+  return { request: ['GET', `specs/${clean.split('/').map(encodeURIComponent).join('/')}${query}`, undefined] };
+}
+
 /**
  * What the CLI says about an answer to those requests: which task and agent took the pull request, or who already has it.
  * @param {'fix' | 'review'} action
@@ -409,3 +471,64 @@ export function chaseSummary(slug, { dryRun, chase, started = [], wouldStart = [
   }
   return [first, '', ...chaseLines(chase, slug)].join('\n');
 }
+
+/** A spec's tasks in a few words: "3 tasks, 2 open", or "no tasks". */
+const specTaskCount = (tasks = []) => {
+  if (!tasks.length) return 'no tasks';
+  const open = tasks.filter((t) => t.status === 'pending').length;
+  return `${plural(tasks.length, 'task')}, ${open} open`;
+};
+
+/**
+ * What `npx breakaway specs` prints: the repository's specs newest first, each with its work ID, status, title, and its
+ * tasks' count; with none, where specs go and how to point the board at another directory.
+ * @param {{ slug: string, dir: string, missing?: boolean, readme?: { path: string } | null, specs: any[] }} answer
+ */
+export function specListLines({ slug, dir, missing, readme, specs }) {
+  if (!specs.length)
+    return [
+      `No specs in ${dir} yet${missing ? `: ${slug} has no ${dir} on its default branch` : ''}.`,
+      'A spec is a Markdown file in that directory, merged like any change.',
+      `If ${slug} keeps its specs somewhere else, the owner sets it with npx breakaway repos modify ${slug} --specs <dir>.`,
+    ];
+  const intro = readme ? ` (its introduction is ${readme.path})` : '';
+  const out = [`${slug}: ${plural(specs.length, 'spec')} in ${dir}${intro}`, ''];
+  for (const s of specs) {
+    const extra = s.tooLarge ? ', over 1 MB: read it on GitHub' : '';
+    out.push(
+      `  ${(s.wid ?? '').padEnd(9)} ${(s.status ?? '-').padEnd(10)} ${s.title}  (${specTaskCount(s.tasks)}${extra})`,
+    );
+  }
+  out.push('', `Read one: npx breakaway specs show <path>, like ${specs[0].path}`);
+  return out;
+}
+
+/**
+ * What `npx breakaway specs show <path>` prints: the spec's title and path, status, the commit that last changed it,
+ * its GitHub link, its Markdown (or, over 1 MB, a pointer to GitHub), and the tasks that link it.
+ * @param {any} spec
+ */
+export function specLines(spec) {
+  const out = [`${spec.title} (${spec.path})`, ''];
+  const row = (k, v) => v && out.push(`  ${k.padEnd(11)} ${v}`);
+  row('Status', spec.status);
+  const c = spec.commit;
+  if (c)
+    row(
+      'Changed',
+      `${c.date ? `${String(c.date).slice(0, 16).replace('T', ' ')} ` : ''}in ${String(c.sha).slice(0, 7)}${c.message ? `: ${c.message}` : ''}`,
+    );
+  row('GitHub', spec.url);
+  out.push('');
+  if (spec.tooLarge || spec.text === null || spec.text === undefined)
+    out.push('Over 1 MB, too large to show here: read it on GitHub.');
+  else out.push(String(spec.text).replace(/\s+$/u, ''));
+  const tasks = spec.tasks ?? [];
+  out.push('');
+  if (tasks.length) {
+    out.push(`  Tasks (${tasks.length}, ${tasks.filter((t) => t.status === 'pending').length} open)`);
+    for (const t of tasks) out.push(`    ${idOf(t).padEnd(9)} ${t.status.padEnd(9)} ${t.description}`);
+  } else out.push(`  No task links it yet: npx breakaway modify <ref> --spec ${spec.path}`);
+  out.push('', `Refine it: npx breakaway agents new --spec ${spec.path} "<what should change>"`);
+  return out;
+}