breakaway 1.4.0-main.34 → 1.4.0-main.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.4.0-main.34",
+  "version": "1.4.0-main.35",
   "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",
@@ -50,15 +50,16 @@
   },
   "scripts": {
     "dev": "vite",
-    "build": "vite build",
-    "test": "vitest run && vitest run --config scripts/tasks/vitest.config.js",
+    "prepare": "node scripts/board-files.mjs",
+    "build": "node scripts/board-files.mjs && vite build",
+    "test": "node scripts/board-files.mjs && vitest run && vitest run --config scripts/tasks/vitest.config.js",
     "brand": "node scripts/brand-lint.mjs",
     "format": "biome format --write .",
     "lint": "biome check .",
-    "typecheck": "wrangler types && tsc -p tsconfig.json && tsc -p scripts/tsconfig.json && tsc -p web/tsconfig.json",
+    "typecheck": "node scripts/board-files.mjs && wrangler types && tsc -p tsconfig.json && tsc -p scripts/tsconfig.json && tsc -p web/tsconfig.json",
     "site": "node site/build.mjs",
     "interop": "node interop.mjs",
-    "deploy": "vite build && wrangler deploy -c wrangler.jsonc"
+    "deploy": "node scripts/board-files.mjs && vite build && wrangler deploy -c wrangler.jsonc"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",

package/scripts/board-files.mjs

@@ -1,8 +1,9 @@
 #!/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.
+ * so the Worker renders an empty repository's first commit from the same files as the CLI. It's generated, never
+ * committed (BRK-148): `pnpm install`, `build`, `typecheck`, `test`, and `deploy` run this first, and the release
+ * workflow's build puts it in the bundle.
  */
 import { readFileSync, writeFileSync } from 'node:fs';
 import { boardSources } from '../src/init.js';
@@ -14,5 +15,6 @@ export const boardFiles = () => Object.fromEntries(boardSources(read).map((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.');
+  // On stderr: npm pack and npm publish run it (prepare), and their --json goes to stdout.
+  console.error('Wrote src/board-files.json.');
 }

package/scripts/tasks/cli.js

@@ -49,17 +49,18 @@ export function unknownSubcommand(command, first) {
 
 /**
  * What a CLI says about where it runs from, or null to say nothing (BRK-7). The CLI ships on npm, so `packaged` (run
- * through npx) has nothing to say. In a checkout of the board's own repository, `own` older than the board's (`board`,
- * its X-Tasks-Cli header) means pull. Anywhere else the CLI is an old copy that `repos init` used to commit: it
- * works while the API stays compatible, and on each run it says how to switch.
+ * through npx) has nothing to say. In a checkout of the board's own repository, `behind` (the board's `release`, its
+ * X-Tasks-Release header, isn't in this checkout's history: releaseBehind) means pull (BRK-148). Anywhere else the
+ * CLI is an old copy that `repos init` used to commit: it works while the API stays compatible, and on each run it says
+ * how to switch. `own` and `board` are the frozen CLI number (src/cli-version.js) such a copy carries and the board sends.
  */
-export function staleCliWarning({ own, board, boardCheckout, slug, packaged = false }) {
+export function staleCliWarning({ own, board, boardCheckout, slug, packaged = false, release = null, behind = false }) {
   if (packaged) return null;
   const theirs = Number(board);
   const older = Number.isInteger(theirs) && theirs > own;
   if (boardCheckout) {
-    if (!older) return null;
-    return `this checkout's board CLI (version ${own}) is older than the board's (${theirs}), so a command may be missing or behave differently: pull the default branch to update it.`;
+    if (!release || !behind) return null;
+    return `this checkout is behind the board's release (v${release}), so a command may be missing or behave differently: pull the default branch to update it.`;
   }
   const newer = older ? `, older than the board's (${theirs}), so a command may be missing or behave differently` : '';
   return `this checkout carries a copy of the board's CLI (version ${own}${newer}). The CLI is on npm now: run it as npx ${CLI_PACKAGE} <command> instead of node scripts/tasks.mjs, and remove the copy with npx ${CLI_PACKAGE} repos init ${slug || '<slug>'} --update, which opens a pull request here.`;
@@ -77,6 +78,22 @@ export function githubRequest(repo, { sync = false } = {}) {
   return ['GET', repo ? `github?repo=${encodeURIComponent(repo)}` : 'github', undefined];
 }
 
+/**
+ * Whether the checkout `git` runs in is behind the board's release `release` (BRK-148): it has the release's tag
+ * (`v1.4.0-main.9`, which the release workflow pushes) and that commit isn't in HEAD's history. Without the tag (tags
+ * not fetched yet), or in a `shallow` clone, whose cut history can hide an ancestor, it can't tell, and says no.
+ * `git(args)` runs git and returns its exit code.
+ * @param {string | null} release
+ * @param {(args: string[]) => number | null} git
+ * @param {{ shallow?: boolean }} [options]
+ */
+export function releaseBehind(release, git, { shallow = false } = {}) {
+  if (shallow || !release || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(release)) return false;
+  const tag = `refs/tags/v${release}`;
+  if (git(['rev-parse', '-q', '--verify', `${tag}^{commit}`]) !== 0) return false;
+  return git(['merge-base', '--is-ancestor', tag, 'HEAD']) === 1;
+}
+
 /** What `github fix` accepts for --problem: the same three the pull request page offers. */
 export const FIX_PROBLEMS = ['conflicts', 'failing', 'review'];
 

package/scripts/tasks.mjs

@@ -72,6 +72,7 @@ import {
   pullAgentSummary,
   reviewRequest,
   staleCliWarning,
+  releaseBehind,
   unknownSubcommand,
 } from './tasks/cli.js';
 import { mergeViews, pelotonLines, pelotonPost, pickPeloton } from './tasks/peloton.js';
@@ -423,7 +424,7 @@ async function call(method, path, body, { soft = false } = {}) {
       `can't reach ${BASE} (${reasonOf(error)}). Cloud sessions need ${new URL(BASE).host} allowed in their network settings.`,
     );
   }
-  warnIfStale(res.headers.get('X-Tasks-Cli'));
+  warnIfStale(res.headers.get('X-Tasks-Cli'), res.headers.get('X-Tasks-Release'));
   if (res.status === 401 && !token)
     fail(
       `no token. Set BREAKAWAY_TOKEN, put it in ${ENV_FILE}, or add it as an API credential in the cloud environment (see docs/tasks.md#cloud-agents).`,
@@ -444,8 +445,11 @@ async function call(method, path, body, { soft = false } = {}) {
 }
 
 let warnedStale = false;
-/** Once a run: say so when this copy of the CLI is older than the board's (CLD-193). On stderr, so --json stays clean. */
-function warnIfStale(board) {
+/**
+ * Once a run: say so when this copy of the CLI is older than the board's (CLD-193), or this checkout of the board's own
+ * repository is behind the release the board runs (BRK-148). On stderr, so --json stays clean.
+ */
+function warnIfStale(board, release = null) {
   // An old copy says how to switch on every run, even when the board doesn't say its version.
   if (warnedStale || (board === null && PACKAGED)) return;
   warnedStale = true;
@@ -459,7 +463,22 @@ function warnIfStale(board) {
       /* no .taskrc */
     }
   }
-  const warning = staleCliWarning({ own: CLI_VERSION, board, boardCheckout, slug, packaged: PACKAGED });
+  const git = (args) => spawnSync('git', ['-C', REPO, ...args], { encoding: 'utf8', timeout: 5000 });
+  const behind =
+    boardCheckout &&
+    Boolean(release) &&
+    releaseBehind(release, (args) => git(args).status, {
+      shallow: git(['rev-parse', '--is-shallow-repository']).stdout?.trim() === 'true',
+    });
+  const warning = staleCliWarning({
+    own: CLI_VERSION,
+    board,
+    boardCheckout,
+    slug,
+    packaged: PACKAGED,
+    release,
+    behind,
+  });
   if (warning) console.error(`tasks: ${warning}`);
 }
 
@@ -2013,7 +2032,7 @@ async function initRepo(slug) {
     title,
     '-m',
     update
-      ? `The board's core, skill, release helpers, and Taskwarrior files as they are in ${board ?? 'breakaway'} now, and the session hooks run through npx, so an old copy of the CLI is removed: run it as npx ${CLI_PACKAGE} (CLI version ${CLI_VERSION}). This repository's own files are unchanged. Updated by npx ${CLI_PACKAGE} repos init ${repo.slug} --update.`
+      ? `The board's core, skill, release helpers, and Taskwarrior files as they are in ${board ?? 'breakaway'} now, and the session hooks run through npx, so an old copy of the CLI is removed: run it as npx ${CLI_PACKAGE}. This repository's own files are unchanged. Updated by npx ${CLI_PACKAGE} repos init ${repo.slug} --update.`
       : `${first.body}${starter.files.length ? ` It also adds the deploy and release flows, rendered from ${starter.files[0].path}.` : ''}`,
   );
   const pushed = spawnSync('git', ['-C', dir, 'push', '-u', 'origin', empty ? `HEAD:refs/heads/${branch}` : work], {
@@ -2039,7 +2058,7 @@ async function initRepo(slug) {
         title,
         '--body',
         update
-          ? `The task board's copied files (its CLI, version ${CLI_VERSION}, the core and stub, the tasks skill, and the Taskwarrior files) as they are on the board's repository now, updated by \`npx breakaway repos init ${repo.slug} --update\`. This repository's own files (its agent prompt, AGENTS.md, .taskrc, .envrc, package.json, .claude/settings.json) are unchanged.`
+          ? `The task board's copied files (its CLI, the core and stub, the tasks skill, and the Taskwarrior files) as they are on the board's repository now, updated by \`npx breakaway repos init ${repo.slug} --update\`. This repository's own files (its agent prompt, AGENTS.md, .taskrc, .envrc, package.json, .claude/settings.json) are unchanged.`
           : `The files the task board's agents need to claim and work a task in this repository, added by \`npx breakaway repos init ${repo.slug}\`. Nothing that was there is changed. If this repository's linter reads plain JavaScript, exclude the copied scripts (tools/tasks/ and the release helpers) from it.${plan.todo.length ? `\n\nStill to do:\n${plan.todo.map((t) => `- ${t}`).join('\n')}` : ''}`,
       ],
       { encoding: 'utf8' },

package/src/cli-version.js

@@ -1,8 +1,7 @@
 /**
- * The version of the board's CLI and the files repos init copies with it (CLD-193). The board reports it
- * (every API answer's X-Tasks-Cli header, and health), so a copy in another repository can say it's older
- * and how to update it. scripts/tasks/version.test.js fails when the copied files change and this doesn't:
- * so it lives in the board's package (CLD-135) and the CLI imports it from here.
+ * The number the board's CLI and the files repos init copies were versioned by (CLD-193), frozen by BRK-148: never
+ * change it. The board still sends it (every API answer's X-Tasks-Cli header, and `cli` in health), so an old copy of
+ * the CLI in another repository says how to switch to npx. What a checkout compares now is the board's release (the
+ * X-Tasks-Release header): pull requests no longer bump anything when a copied file changes.
  */
 export const CLI_VERSION = 73;
-export const CLI_FINGERPRINT = '2da33f9e367765c1';

package/src/init.js

@@ -68,7 +68,7 @@ const GITATTRIBUTES = ['scripts/task text eol=lf', '.envrc text eol=lf'];
 /**
  * The board's own files initPlan reads (repository paths, sorted): the prompt template, what it copies as it is or
  * adapted, and the release helpers with what they import. src/board-files.json holds them for the Worker, and
- * scripts/tasks/init.test.js fails when it falls behind (`node scripts/board-files.mjs` writes it again).
+ * `node scripts/board-files.mjs` writes it before every build and test run (it isn't committed, BRK-148).
  */
 export function boardSources(read) {
   return [...new Set(['prompts/repository.md', ...COPIED, ...ADAPTED, ...importClosure(RELEASE_ENTRIES, read)])].sort();
@@ -116,19 +116,6 @@ export function importClosure(entries, read) {
   return [...seen].sort();
 }
 
-/**
- * Every file CLI_VERSION in src/cli-version.js versions (repository paths, sorted): what repos init copies, as it is
- * or adapted, and the CLI's own files, which the npm package carries and an old copy still holds. cli-version.js
- * itself is left out, so the fingerprint can live in it.
- */
-export function copiedSources(read) {
-  return [
-    ...new Set([...importClosure(CLI_ENTRIES, read), ...importClosure(RELEASE_ENTRIES, read), ...COPIED, ...ADAPTED]),
-  ]
-    .filter((path) => path !== 'src/cli-version.js')
-    .sort();
-}
-
 /**
  * The files an old copy of the CLI holds that npx replaces (repository paths, sorted): the CLI, its hooks, and what
  * only they import. The release helpers' files stay copied, so they are not here.
@@ -201,16 +188,6 @@ export function declaredCopies(agents) {
   return [...line.split(/ come from \[/u)[0].matchAll(/`([^`]+)`/gu)].map((m) => m[1]);
 }
 
-/** A short SHA-256 of `paths` and their text: changes whenever one of them does. */
-export async function fingerprint(paths, read) {
-  const text = paths.map((path) => `${path}\0${read(path)}\0`).join('');
-  const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
-  return [...new Uint8Array(hash)]
-    .slice(0, 8)
-    .map((b) => b.toString(16).padStart(2, '0'))
-    .join('');
-}
-
 /**
  * The Taskwarrior report and context for repository `slug` (IDEA-14): `task <slug>` lists its open work, and
  * `task context <slug>` narrows everything to it and puts new tasks in it. For the shared taskrc.