breakaway 1.4.0-main.3 → 1.4.0-main.30

package/.agents/skills/tasks/SKILL.md

@@ -31,6 +31,7 @@ breakaway's work is on the board that tracks this repository. The CLI is `npx br
 | You need the owner to choose | Ask with a decision, not prose: `add "<title>" --tag owner --decision <file.json>` and make the work that waits `--depends` on it. Only the owner answers, on the board; read the answers with `show`. |
 | Part of the work needs the owner (an install, a dashboard, a sign-off) | Finish your part, then `add` a `+owner` task for the rest that `--depends` on yours. |
 | Task needs design choices | Write the spec in `docs/specs/<ID>-<slug>.md` and `modify <ID> --spec <path>`. |
+| Reading the repository's specs | `tasks specs` lists them, newest first, with each one's status and its tasks; `specs show <path>` prints one with the tasks that link it. They're read from GitHub's default branch, so a spec still in a pull request isn't there yet. |
 | You're blocked by another task | `comment` why, `release`, and pick the blocker or another task. |
 | A claim looks abandoned | Ask the owner; don't take it. |
 | Opening a pull request for a spec, plan, or partial step | Write `Part of <ID>.`, not `Closes`, and don't put it in `--pr`: merging the pull request in that field finishes the task. A branch name alone never closes anything. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.4.0-main.3",
+  "version": "1.4.0-main.30",
   "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/prompts/core.md

@@ -104,6 +104,7 @@ The owner wrote what they want in their own words and pressed Start; the board m
    A general task released with no pull request is finished: the board closes it, so release only when your part is done.
 4. **Other tasks: change them directly, each change noted.** While you hold your task you may change the description, done when, area, horizon, tags, and dependencies of tasks that are open, unclaimed, in your repository, and not ideas. The board adds `Changed by <your task>: <the fields>.` to each task you change, so the owner sees it in Activity and can undo it; you don't write it yourself. Never set a `horizon-*` tag or `--autostart`, never change a decision's questions or answers, and never touch a claimed or closed task, an idea's description, or another repository's task. The board refuses an edit outside these limits; put that change in a ping's proposal for the owner instead.
 5. **A run from a decision's answers.** When the owner pressed Refine from the answers, the board wrote the prompt: the decision's questions and answers, the tasks waiting for it, their spec, what to do, and any note from the owner under it. Your task is related to the decision; `show` it for the full answers. Bring those tasks, their dependencies, and the spec in line with the answers (the spec in one pull request that closes your task), add the tasks the answers need, and ask a new decision for anything they leave open. Never change the answers: only the owner does.
+6. **A run that names a spec.** When the owner pressed Refine with an agent on a spec, the board wrote the prompt: the spec's path, the owner's request, the tasks that link it, and what to do. Your task's `spec` is that path. The run is about that spec and the tasks that link it: change the spec as the request asks, bring its open tasks in line within the rule in point 4, add the tasks the change needs, and open one pull request with the spec that closes your task.
 
 You never start or force-start an agent, never take another agent's claim, and never deploy, touch production, or merge, whatever the prompt says.
 

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,90 @@
+/**
+ * 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 version a stable release's pull request sets package.json to (BRK-118, WEB-39): the next minor or major after
+ * the stable, or null when there is nothing to set. A patch is null, since the pre-releases count patches by
+ * themselves, and so is a package.json already at or past the choice (main moved on before an older pre-release was
+ * released).
+ * @param {string} stable the version just released, like 1.3.0
+ * @param {string} next patch, minor, or major
+ * @param {string} current package.json's version on the default branch
+ * @returns {string | null}
+ */
+export function nextVersion(stable, next, current) {
+  const [maj, min] = parts(stable);
+  parts(current);
+  if (next === 'patch') return null;
+  if (next !== 'minor' && next !== 'major') throw new Error(`next is patch, minor, or major, not "${next}".`);
+  const version = next === 'major' ? `${maj + 1}.0.0` : `${maj}.${min + 1}.0`;
+  return compareVersions(current, version) >= 0 ? null : 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,60 @@
+#!/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
+ *   node scripts/package-release.mjs next <stable> <patch|minor|major> --dir <path>
+ *       the version to set <path>/package.json to after the stable, empty for none (WEB-39)
+ * 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, nextVersion, 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 if (command === 'next' && tag) {
+    const current = JSON.parse(readFileSync(join(o.dir, 'package.json'), 'utf8')).version;
+    const version = nextVersion(tag, positionals[2] ?? 'patch', current);
+    if (!version && positionals[2] && positionals[2] !== 'patch')
+      console.error(`package.json already says ${current}, at or past the next ${positionals[2]} after ${tag}.`);
+    console.log(`version=${version ?? ''}`);
+  } else {
+    throw new Error(
+      'Usage: package-release.mjs prerelease --dir <path> --prefix <p> [--sha <commit>] | stable <tag> --prefix <p> | next <stable> <patch|minor|major> --dir <path>',
+    );
+  }
+} 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,30 @@ export function pullAgentRequest(action, number, { repo = null, problem, note, f
   return { request: ['POST', `github/pulls/${n}/${action}`, body] };
 }
 
+/**
+ * `npx breakaway github release <pre-release> [--next patch|minor|major]` (BRK-103, WEB-39): the owner releases a
+ * package's pre-release as its stable, as Release on the GitHub page does, with what the default branch works toward
+ * next. 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, and refuses a pre-release whose stable is already out (409).
+ * @param {string | undefined} version the pre-release, like 1.4.0-main.5 (or its tag)
+ * @param {{ repo?: string | null, by?: string, next?: string | null }} [options]
+ * @returns {{ error?: string, request?: [string, string, Record<string, string>] }}
+ */
+export function packageReleaseRequest(version, { repo = null, by, next = null } = {}) {
+  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' };
+  if (next !== null && next !== undefined && !['patch', 'minor', 'major'].includes(String(next)))
+    return { error: '--next is patch, minor, or major' };
+  return {
+    request: [
+      'POST',
+      'github/release',
+      { version: v, ...(next ? { next: String(next) } : {}), ...(repo ? { repo } : {}), ...(by ? { by } : {}) },
+    ],
+  };
+}
+
 export const REVIEW_VERDICTS = ['ready', 'follow-up', 'changes'];
 
 /**
@@ -148,17 +173,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 +205,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 +480,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;
+}