breakaway 1.4.0-main.5 → 1.4.0-main.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.4.0-main.5",
+  "version": "1.4.0-main.7",
   "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/tasks.mjs

@@ -236,6 +236,7 @@ Working
   repos modify <slug>    change one (owner): --area <project:PREFIX> adds an area, --remove-area <project> drops one with no tasks, --name, --branch, --github,
                          --agents-max <n|none> and --agents-hourly <n|none> cap its agents under the board's shared limits,
                          --prompt <path|none> says where its agent prompt is in its checkout (default tools/tasks/routine-prompt.md)
+                         --specs <dir|none> says where its specs are (default docs/specs)
                          --pipeline <file.json|none> sets its deploy pipeline ({"workers": {"staging", "production"}, "workflows": {...}, "deployPaths"}) or clears it
   features add <slug>    new feature: its tasks join by carrying <slug> as a tag  [--title <text>]
                          [--brief <text> | --brief-file <path>] [--release <x.y.z>] (agents add one without a release)
@@ -935,9 +936,14 @@ const commands = {
     if (sub === 'modify') {
       const slug = need(args[1], 'repository');
       const change = fields();
+      const routineFlags =
+        opts['agents-max'] !== undefined || opts['agents-hourly'] !== undefined || opts.prompt !== undefined;
+      const current =
+        routineFlags || opts.specs !== undefined
+          ? (await call('GET', 'repos')).repos.find((r) => r.slug === slug.toLowerCase())
+          : null;
       // Its caps on agents, under the board's shared limits, and where its agent prompt is (CLD-127): kept with the rest of its routine settings.
-      if (opts['agents-max'] !== undefined || opts['agents-hourly'] !== undefined || opts.prompt !== undefined) {
-        const current = (await call('GET', 'repos')).repos.find((r) => r.slug === slug.toLowerCase());
+      if (routineFlags) {
         const routine = { ...current?.routine };
         for (const [flag, key] of [
           ['agents-max', 'max'],
@@ -948,6 +954,9 @@ const commands = {
         if (opts.prompt !== undefined) routine.prompt = opts.prompt === 'none' ? null : String(opts.prompt);
         change.routine = routine;
       }
+      // Where its specs are (IDEA-31), kept with the rest of its settings; none goes back to docs/specs.
+      if (opts.specs !== undefined)
+        change.settings = { ...current?.settings, specs: opts.specs === 'none' ? null : String(opts.specs) };
       // Its deploy pipeline (BRK-44): a JSON file, or none to clear it; the board refuses one it couldn't use, with the reason.
       if (opts.pipeline !== undefined) {
         if (opts.pipeline === 'none') change.pipeline = null;

package/src/cli-version.js

@@ -4,5 +4,5 @@
  * 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.
  */
-export const CLI_VERSION = 63;
-export const CLI_FINGERPRINT = '4e27258ce14d0ac7';
+export const CLI_VERSION = 64;
+export const CLI_FINGERPRINT = '7c834da9bbef354a';

package/src/repos.js

@@ -10,6 +10,7 @@
  * repository, and a prefix to exactly one area, so a work ID means one task across the install.
  */
 import { AREA_NAMES, InputError, PROJECTS } from './model.js';
+import { checkSettings } from './specs.js';
 
 /** The slug a task without `repo` falls back to while the registry has no default: nothing is registered, so no task is. */
 export const NO_REPO = 'default';
@@ -292,6 +293,7 @@ export function checkRepo(
   for (const key of JSON_FIELDS) if (key in input) row[key] = jsonField(input[key], key);
   if ('pipeline' in input) row.pipeline = checkPipeline(row.pipeline);
   if ('routine' in input) row.routine = checkRoutine(row.routine, caps);
+  if ('settings' in input) row.settings = checkSettings(row.settings);
 
   const adding = [...list(input.areas), ...list(input.addAreas)].map(parseArea);
   for (const project of list(input.removeAreas).map((p) => String(p).trim().toLowerCase())) {

package/src/specs.js

@@ -0,0 +1,96 @@
+/**
+ * A repository's specs (docs/specs/IDEA-31-specs-view.md, sections 1 and 2): where they are, and what the board
+ * reads from each file. Pure, so it's tested without the Durable Object; reading them through GitHub is in
+ * store-specs.js. The board never stores a spec: it reads the files on the default branch when asked.
+ */
+import { InputError } from './model.js';
+
+/** Where a repository keeps its specs when its settings don't say: where breakaway and the template put them. */
+export const DEFAULT_SPECS_DIR = 'docs/specs';
+/** The largest spec the board reads; a bigger one is a link to GitHub. */
+export const SPEC_MAX_BYTES = 1_048_576;
+const SPECS_DIR = /^(?!\/)(?!.*\.\.)[\w./-]{1,200}$/u;
+const SPEC_NAME = /^[\w.-]{1,200}\.md$/u;
+const WID = /^([A-Z]{2,8}-\d+)(?:[-.]|$)/u;
+
+/**
+ * A repository's specs directory as the owner sets it (`settings.specs`): a relative directory, with no `..`,
+ * of at most 200 characters, checked like `routine.prompt`. Empty or null means the default, so it's left out.
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function checkSpecsDir(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const dir = String(value).trim().replace(/^\.\//u, '').replace(/\/+$/u, '');
+  if (!SPECS_DIR.test(dir) || dir.split('/').some((part) => part === '' || part === '.'))
+    throw new InputError('settings.specs is a directory in the repository, like docs/specs');
+  return dir;
+}
+
+/**
+ * A repository's `settings`, checked: its specs directory (`specs`) when it has one; the rest is kept as it is.
+ * @param {Record<string, any> | null} settings
+ */
+export function checkSettings(settings) {
+  if (!settings) return null;
+  const out = { ...settings };
+  const specs = checkSpecsDir(out.specs);
+  if (specs) out.specs = specs;
+  else delete out.specs;
+  return Object.keys(out).length ? out : null;
+}
+
+/** The directory, in the repository, its specs are in. */
+export const specsDirOf = (repo) => repo?.settings?.specs || DEFAULT_SPECS_DIR;
+
+/** A path as a task's `spec` field or a request may give it: no leading `./` or `/`. */
+export const normalPath = (path) =>
+  String(path ?? '')
+    .trim()
+    .replace(/^(?:\.\/|\/)+/u, '');
+
+/**
+ * Whether `path` is a file the board reads as one of the repository's specs: a Markdown file directly in `dir`
+ * (its README.md too). Subdirectories, other files, and anything outside it are refused.
+ * @param {string} dir
+ * @param {string} path
+ */
+export function inSpecsDir(dir, path) {
+  const p = normalPath(path);
+  if (!p.startsWith(`${dir}/`)) return false;
+  const name = p.slice(dir.length + 1);
+  return SPEC_NAME.test(name) && !name.startsWith('.');
+}
+
+/** Whether a file in the directory is a spec, not its introduction. */
+export const isSpecFile = (name) => SPEC_NAME.test(name) && !name.startsWith('.') && name.toLowerCase() !== 'readme.md';
+
+/**
+ * What the list shows for one spec: its title (the first `# ` heading, else the file name), its status (the
+ * first word after `Status:` on the line under the heading, as the template has it, else null), and the work ID
+ * its file name starts with, if any. `text` is null for a file the board didn't read (too large).
+ * @param {string} name the file name
+ * @param {string | null} text
+ */
+export function specMeta(name, text) {
+  const wid = WID.exec(name)?.[1] ?? null;
+  const fallback = name.replace(/\.md$/u, '');
+  if (text === null || text === undefined) return { wid, title: fallback, status: null };
+  const lines = String(text).split(/\r?\n/u);
+  const at = lines.findIndex((l) => /^#\s+\S/u.test(l));
+  if (at < 0) return { wid, title: fallback, status: null };
+  const title =
+    lines[at]
+      .replace(/^#\s+/u, '')
+      .replace(/\s+#+\s*$/u, '')
+      .trim() || fallback;
+  const under = lines.slice(at + 1).find((l) => l.trim() !== '') ?? '';
+  const status = /\bStatus:\s*\**\s*([A-Za-z][\w-]*)/u.exec(under)?.[1]?.toLowerCase() ?? null;
+  return { wid, title, status };
+}
+
+/** Newest first by the work ID's number, then by path; specs without a work ID last. */
+export function bySpecOrder(a, b) {
+  const n = (s) => (s.wid ? Number(s.wid.split('-')[1]) : -1);
+  return n(b) - n(a) || a.path.localeCompare(b.path);
+}