breakaway 1.4.0-main.6 → 1.4.0-main.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.4.0-main.6",
+  "version": "1.4.0-main.8",
   "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",
@@ -28,6 +28,7 @@
     "src/prompt.js",
     "src/redact.js",
     "src/repos.js",
+    "src/specs.js",
     "src/versions.js",
     "prompts/*.md",
     "taskrc",

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/init.js

@@ -32,13 +32,18 @@ export const HOOKS_FROM_COPY = false;
 /** The session hooks' entry files, and where their copy goes: its own folder, so it never touches the repository's src/. */
 export const HOOK_ENTRIES = ['scripts/tasks/session-hook.mjs', 'scripts/tasks/message-wait.mjs'];
 export const HOOKS_DIR = 'tools/tasks/cli/';
-/** The release helpers a repository's Deploy, Promote, and Roll back workflows run (BRK-45), copied with what they import. */
+/**
+ * The release helpers a repository's Deploy, Promote, Roll back, and Release workflows run (BRK-45), copied with what
+ * they import: the deploy helpers, and the package's version numbers (BRK-90, `npx breakaway pipeline init`).
+ */
 export const RELEASE_ENTRIES = [
   'scripts/record-deployment.mjs',
   'scripts/promote-check.mjs',
   'scripts/release-notes.mjs',
   'scripts/check-migrations.mjs',
   'scripts/release-artifact.mjs',
+  'scripts/deploy-plan.mjs',
+  'scripts/package-release.mjs',
 ];
 /** Copied unchanged: the board's shared core and stub, and the Taskwarrior settings the new .taskrc includes. */
 const COPIED = ['prompts/core.md', 'prompts/stub.md'];