@thebattlearena/corner 0.8.0 → 0.9.0

package/ring/scripts/live.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // The live feed of a bout: `<bout dir>/live.jsonl`, one JSON event per line, the last ones only.
-// Ringside reads it every couple of seconds to show who is acting right now.
+// Ringside reads it every couple of seconds to show who is acting right now. A sparring keeps the
+// same feed in `<ring home>/sparrings/<slug>/live.jsonl` (árbitro, rudo and juez only).
 // Zero-dependency. Every writer is BEST EFFORT: it never throws, never blocks and never prints
 // anything to the user; a feed that cannot be written is simply not written.
 //
@@ -30,6 +31,7 @@ import {
   closeSync,
   existsSync,
   openSync,
+  readdirSync,
   readFileSync,
   renameSync,
   rmSync,
@@ -441,3 +443,96 @@ export function sessionRegistered(dir, sessionId) {
     return false;
   }
 }
+
+// ---------------------------------------------------------------- the sparrings' sessions
+
+/** Where the sparrings live: `<ring home>/sparrings/<slug>/sparring.json` (+ its live.jsonl). */
+export const SPARRINGS_DIR = 'sparrings';
+export const SPARRING_FILE = 'sparring.json';
+/** Verdicts that end a sparring: after them nobody writes its feed and Ringside stops showing it. */
+export const FINAL_VERDICTS = ['ko', 'discard'];
+
+/** Is the sparring still being fought (no verdict, or a rematch)? PURE. */
+export const isOpenSparring = (state) =>
+  !!state && !FINAL_VERDICTS.includes(state.verdict?.call);
+
+export const sparringsHome = (env = process.env) =>
+  join(ringHome(env), SPARRINGS_DIR);
+
+const readSparringFile = (dir) =>
+  JSON.parse(readFileSync(join(dir, SPARRING_FILE), 'utf8'));
+
+/** Every sparring on this machine as { dir, state }; an unreadable one is skipped. Never throws. */
+export function sparringsOf(env = process.env) {
+  try {
+    const home = sparringsHome(env);
+    return readdirSync(home)
+      .map((slug) => join(home, slug))
+      .flatMap((dir) => {
+        try {
+          return [{ dir, state: readSparringFile(dir) }];
+        } catch {
+          return [];
+        }
+      });
+  } catch {
+    return [];
+  }
+}
+
+const sparringRecency = (dir) =>
+  Math.max(
+    mtime(join(dir, LIVE_LOG)),
+    mtime(join(dir, SPARRING_FILE)),
+    mtime(join(dir, 'card.md')),
+  );
+
+/**
+ * The open sparring this session registered, for an event with `hint` (the Agent description: the
+ * rudo's says «Rudo: <slug> <repo>»). PURE over the sparrings list ({ dir, state }): the one the
+ * hint names, else the most recently touched (`recencyOf`). Null when the session registered none.
+ */
+export function pickSparring(
+  sparrings,
+  { sessionId, hint },
+  recencyOf = sparringRecency,
+) {
+  const own = sparrings.filter(
+    ({ state }) => isOpenSparring(state) && isRegistered(state, sessionId),
+  );
+  const words = new Set(
+    String(hint ?? '')
+      .toLowerCase()
+      .split(/[^a-z0-9-]+/),
+  );
+  const named = own.find(({ state }) => words.has(state.slug));
+  if (named) return named.dir;
+  return (
+    [...own].sort((a, b) => recencyOf(b.dir) - recencyOf(a.dir))[0]?.dir ?? null
+  );
+}
+
+/** The sparring directory of this session for an event, or null. Never throws. */
+export function findSparring({ sessionId, hint } = {}, env = process.env) {
+  if (!sessionId) return null;
+  return pickSparring(sparringsOf(env), { sessionId, hint });
+}
+
+/**
+ * Registers a session in a sparring's sparring.json (`sessions`, like a bout's). Never throws;
+ * true when it is registered. Only the file is rewritten: the card does not list sessions.
+ */
+export function registerSparringSession(dir, sessionId, role = 'referee') {
+  try {
+    const state = readSparringFile(dir);
+    const next = withSession(state, sessionId, role);
+    if (next !== state)
+      writeFileSync(
+        join(dir, SPARRING_FILE),
+        JSON.stringify(next, null, 2) + '\n',
+      );
+    return isRegistered(next, sessionId);
+  } catch {
+    return false;
+  }
+}

package/ring/scripts/mask-guard.mjs

@@ -26,8 +26,11 @@ import {
   boutDir,
   chronicleStale,
   DEFAULTS,
+  DO_NOT_MERGE,
   isMain,
+  isSparringBranch,
   loadConfig,
+  OPTIONAL_GATES,
   projectDir,
   repoSlug,
   slugFromRemote,
@@ -642,7 +645,117 @@ function pullAvoidsMerge(git) {
   return git.configs['pull.ff'] === 'only';
 }
 
+// ---------------------------------------------------------------- sparring drafts
+
+/** The current branch of `dir`, or null when git cannot say: a sparring rule never fails a command. */
+function branchOrNull(ctx, dir) {
+  try {
+    return ctx.currentBranch(dir);
+  } catch {
+    return null;
+  }
+}
+
+/** Does a `.env.sparring` (anywhere in the repo) go into this commit? */
+const commitsSparringEnv = (git, ctx) =>
+  ctx
+    .committedFiles(git, commitsWorkingTree(git))
+    .some((path) => basename(path) === '.env.sparring');
+
+/** Does a push take a sparring branch (by name, or HEAD on one) to a branch that is not one? */
+function pushesSparringOut(git, ctx) {
+  const positional = git.args.filter((arg) => !arg.startsWith('-'));
+  const refspecs = positional.slice(1);
+  const current = () => branchOrNull(ctx, git.dir);
+  if (!refspecs.length) return false;
+  return refspecs.some((refspec) => {
+    const plain = refspec.replace(/^\+/, '');
+    if (!plain.includes(':')) return false;
+    const [source, target] = plain.split(':');
+    if (!source || isSparringBranch(target)) return false;
+    const from = source === 'HEAD' ? current() : source;
+    return isSparringBranch(from);
+  });
+}
+
+/** The value of `--name <v>`, `--name=<v>` or `-x <v>` in gh args, every time it appears. PURE. */
+function optionValues(args, ...names) {
+  const values = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const inline = names.find((name) => args[i].startsWith(`${name}=`));
+    if (inline) values.push(args[i].slice(inline.length + 1));
+    if (names.includes(args[i]) && i + 1 < args.length)
+      values.push(args[i + 1]);
+  }
+  return values;
+}
+
+/** The head branch a `gh pr create` opens from: --head, else the current branch. */
+const createHead = (gh, ctx) =>
+  optionValues(gh.args, '--head', '-H')[0] ?? branchOrNull(ctx, null);
+
+/** A `gh pr create` from a sparring branch that is not a draft with the do-not-merge label. */
+function sparringCreateUnsafe(gh, ctx) {
+  if (gh.group !== 'pr' || gh.action !== 'create') return false;
+  if (!isSparringBranch(createHead(gh, ctx))) return false;
+  const labels = optionValues(gh.args, '--label', '-l').flatMap((value) =>
+    value.split(','),
+  );
+  return !hasFlag(gh.args, '--draft', '-d') || !labels.includes(DO_NOT_MERGE);
+}
+
+/** Does `gh pr ready|merge` target a sparring PR (by branch, number/URL, or the current branch)? */
+function targetsSparringPr(gh, ctx) {
+  if (gh.group !== 'pr' || !['ready', 'merge'].includes(gh.action))
+    return false;
+  if (gh.action === 'ready' && gh.args.includes('--undo')) return false;
+  const target = gh.args.find((arg) => !arg.startsWith('-'));
+  if (!target) return isSparringBranch(branchOrNull(ctx, null));
+  if (isSparringBranch(target)) return true;
+  const number = /^(\d+)$|\/pull\/(\d+)/.exec(target);
+  if (!number) return false;
+  return isSparringBranch(ctx.prHead(gh, Number(number[1] ?? number[2])));
+}
+
+const sparringGitRules = [
+  {
+    always: true,
+    when: (git, ctx) => git.sub === 'commit' && commitsSparringEnv(git, ctx),
+    reason: () =>
+      '`.env.sparring` holds the credentials of a sparring and is never committed. Unstage it (`git restore --staged .env.sparring`) and commit again.',
+  },
+  {
+    always: true,
+    when: (git) =>
+      git.sub === 'merge' && git.args.some((arg) => isSparringBranch(arg)),
+    reason: () =>
+      'A sparring branch is never merged: it only proves value. A KO is promoted with `node "$RING/scripts/sparring.mjs" promote <slug>` (mainevent/<slug> from its tip, into release/<slug>), and a ring bout cleans the main event.',
+  },
+  {
+    always: true,
+    when: (git, ctx) => git.sub === 'push' && pushesSparringOut(git, ctx),
+    reason: () =>
+      "A sparring branch is pushed only to `sparring/*`. Its code leaves only through a KO: `node \"$RING/scripts/sparring.mjs\" promote <slug>`, which refuses unless the verdict is ko.",
+  },
+];
+
+const sparringGhRules = [
+  {
+    always: true,
+    when: (gh, ctx) => sparringCreateUnsafe(gh, ctx),
+    reason: () =>
+      `A PR from a sparring branch is opened as a draft with the ${DO_NOT_MERGE} label: use \`node "$RING/scripts/sparring.mjs" pr <slug>\`, which adds both.`,
+  },
+  {
+    always: true,
+    when: (gh, ctx) => targetsSparringPr(gh, ctx),
+    reason: () =>
+      'A sparring PR is never taken out of draft nor merged: it only proves value. On a KO, `sparring.mjs promote <slug>` opens the deliverable PR (mainevent → release).',
+  },
+];
+
 const gitRules = [
+  ...sparringGitRules,
   {
     always: true,
     when: (git) =>
@@ -921,6 +1034,7 @@ export function prNumberOf(gh) {
 }
 
 const ghRules = [
+  ...sparringGhRules,
   {
     when: (gh) =>
       gh.group === 'pr' &&
@@ -947,15 +1061,20 @@ const ghRules = [
   },
   {
     when: (gh, ctx) =>
-      requestsCopilot(gh) && !ctx.copilotRoundLeft(gh, prNumberOf(gh)),
+      requestsCopilot(gh) &&
+      ctx.isBoutPr(gh, prNumberOf(gh)) &&
+      !ctx.copilotRoundLeft(gh, prNumberOf(gh)),
     reason: () =>
-      'Requesting a Copilot review is blocked while a ring bout is active, unless /ring:title-defense set its flag for this PR and it has rounds left (at most --until-round requests after the flag was set): the human reviews first, and every re-review costs the org.',
+      'Requesting a Copilot review on the PR of an active ring bout is blocked unless /ring:title-defense set its flag for it and it has rounds left (at most --until-round requests after the flag was set): the human reviews first, and every re-review costs the org. Other PRs of the repo are free.',
   },
   {
-    when: (gh, ctx) =>
-      touchesReviewThread(gh) && !ctx.titleDefenseAllows(gh, prNumberOf(gh)),
+    when: (gh, ctx) => {
+      if (!touchesReviewThread(gh)) return false;
+      const pr = prNumberOf(gh) ?? ctx.prOfThread(gh);
+      return ctx.isBoutPr(gh, pr) && !ctx.titleDefenseAllows(gh, pr);
+    },
     reason: () =>
-      "Replying to or resolving review threads is blocked while a ring bout is active, unless /ring:title-defense set its flag for this PR. Never reply or resolve on the human's behalf otherwise.",
+      "Replying to or resolving review threads on the PR of an active ring bout is blocked unless /ring:title-defense set its flag for it. Never reply or resolve on the human's behalf otherwise; other PRs of the repo are free.",
   },
   {
     when: (gh) => dismissesReview(gh),
@@ -1169,6 +1288,9 @@ function judgeSegment(segment, words, cwd, ctx) {
         (path) => ctx.committedHash(commit, path, wide),
       );
     },
+    // Only the PR of an active bout is guarded; a PR the guard cannot name counts as one (fail closed).
+    isBoutPr: (subject, pr) =>
+      pr === null || ctx.boutPrs({ git, gh: subject, dir: cwd }).includes(pr),
     // The flag expires: once its PR got `untilRound` Copilot requests, no more (PR ids: every flag).
     copilotRoundLeft: (subject, pr) => {
       const where = { git, gh: subject, dir: cwd };
@@ -1332,7 +1454,11 @@ function realContext(cwd) {
       return loaded().heavyCommands ?? [];
     },
     get gates() {
-      return { ...loaded().gates, ...loaded().venueGates };
+      // The optional gates (`build`) are the sparring vestidor's, not a bout's: no heavy lock.
+      const gates = Object.entries(loaded().gates).filter(
+        ([gate]) => !OPTIONAL_GATES.includes(gate),
+      );
+      return { ...Object.fromEntries(gates), ...loaded().venueGates };
     },
     home: homedir(),
     env: process.env,
@@ -1453,6 +1579,36 @@ function realContext(cwd) {
         return contentHash(null);
       }
     },
+    // The PRs of the repo's active bouts: only they are guarded against Copilot requests and replies.
+    boutPrs: (where) => {
+      const slug = slugWhere(where);
+      if (!slug) return [];
+      return boutsOf(slug).map(({ state }) => state.pr);
+    },
+    // The PR a GraphQL review-thread mutation acts on, from its thread id (PRRT_…); null when unknown.
+    prOfThread: (gh) => {
+      const thread = /\bPRRT_[A-Za-z0-9_-]+/.exec(gh.args.join(' '))?.[0];
+      if (!thread) return null;
+      try {
+        const out = execFileSync(
+          'gh',
+          [
+            'api',
+            'graphql',
+            '-f',
+            'query=query($t:ID!){node(id:$t){... on PullRequestReviewThread{pullRequest{number}}}}',
+            '-F',
+            `t=${thread}`,
+            '-q',
+            '.data.node.pullRequest.number',
+          ],
+          { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+        ).trim();
+        return /^\d+$/.test(out) ? Number(out) : null;
+      } catch {
+        return null;
+      }
+    },
     // PRs whose own bout carries the title-defense flag (set by /ring:title-defense).
     titleDefensePrs: (where) => {
       const slug = slugWhere(where);
@@ -1512,6 +1668,28 @@ function realContext(cwd) {
       git(dirOf(dir), ['status', '--porcelain', '--untracked-files=no']) !== '',
     currentBranch: (dir) =>
       git(dirOf(dir), ['rev-parse', '--abbrev-ref', 'HEAD']),
+    // The head branch of a PR, or null when gh cannot say: outside a bout an unreachable GitHub
+    // must not block every `gh pr ready`, and during one the bout rules still block it.
+    prHead: (gh, pr) => {
+      try {
+        return execFileSync(
+          'gh',
+          [
+            'pr',
+            'view',
+            String(pr),
+            ...(gh.repo ? ['-R', gh.repo] : []),
+            '--json',
+            'headRefName',
+            '-q',
+            '.headRefName',
+          ],
+          { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+        ).trim();
+      } catch {
+        return null;
+      }
+    },
     readFile: (file, dir) => {
       const path = isAbsolute(file) ? file : resolve(dirOf(dir), file);
       return existsSync(path) ? readFileSync(path, 'utf8') : '';

package/ring/scripts/monitors.mjs

@@ -16,7 +16,7 @@
 // runs that slash command (another mod's, say, that opens its own pane), `{ "pane": "<id>" }`
 // names a pane the person opens themselves (one mod cannot open another mod's pane).
 
-/** The ring's own actors. A monitor can never take one of these ids. */
+/** The ring's own actors (the rudo writes sparrings). A monitor can never take one of these ids. */
 export const CORE_ACTORS = [
   'arbitro',
   'luchador',
@@ -24,6 +24,7 @@ export const CORE_ACTORS = [
   'campana',
   'copilot',
   'juez',
+  'rudo',
 ];
 
 const ID = /^[a-z0-9][a-z0-9_-]{0,31}$/;

package/ring/scripts/play-by-play.mjs

@@ -3,6 +3,10 @@
 // Deterministic and read-only: the bout dir, git and GitHub. Zero-dependency.
 //
 //   node play-by-play.mjs <pr> [--repo <owner/name>] [--tz <Area/City>] [--extra <json|file>] [--no-gh]
+//   node play-by-play.mjs --sparring <slug> [--tz <Area/City>] [--extra <json|file>] [--no-gh]
+//
+// A fight that starts at a sparring is one chronicle (fight.mjs): `--sparring <slug>`, or a bout
+// opened `--from-sparring <slug>`, prints the sparring's falls and every bout of it as the third.
 //
 // Output: { pr, repo, boutDir, generatedAt, timezone, copilotOnHead, rounds, events, score, gaps,
 // notes }. Every event carries its real time (`at`, plus `local` HH:MM in --tz) and its `source`.
@@ -11,7 +15,7 @@
 // { at, type, title, detail, ref }, inline or in a file), always marked `provided`.
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 
 import {
   checkEvents,
@@ -34,6 +38,7 @@ import {
   repoSlug,
   slugFromRemote,
 } from './config.mjs';
+import { collectFight } from './fight.mjs';
 
 const run = (bin, args, cwd) =>
   execFileSync(bin, args, {
@@ -76,18 +81,27 @@ export function readExtra(value) {
   return extraEvents(items, inline ? 'inline' : value);
 }
 
-function collect([pr, ...argv]) {
-  if (!pr)
-    throw new Error(
-      'usage: play-by-play.mjs <pr> [--repo <owner/name>] [--tz <zone>] [--extra <json|file>] [--no-gh]',
-    );
+const USAGE =
+  'usage: play-by-play.mjs <pr> [--repo <owner/name>] | --sparring <slug>; [--tz <zone>] [--extra <json|file>] [--no-gh]';
+
+const timezoneOf = (argv) =>
+  option(argv, 'tz') ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+
+/** The bout directory of `pr`: in `--repo`, else in this checkout's repo. */
+const boutDirOf = (pr, argv) => {
   const repoFlag = option(argv, 'repo');
-  const timezone =
-    option(argv, 'tz') ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
-  const dir = boutDir(
+  return boutDir(
     repoFlag ? slugFromRemote(repoFlag) : repoSlug(projectDir()),
     pr,
   );
+};
+
+/** One bout's chronicle: its ledgers, git and GitHub. */
+export function collectBout([pr, ...argv]) {
+  if (!pr) throw new Error(USAGE);
+  const repoFlag = option(argv, 'repo');
+  const timezone = timezoneOf(argv);
+  const dir = boutDirOf(pr, argv);
   if (!existsSync(join(dir, 'state.json')))
     throw new Error(`no bout for #${pr} in ${dir}`);
   const state = readState(dir);
@@ -242,6 +256,22 @@ function collect([pr, ...argv]) {
   };
 }
 
+/**
+ * The chronicle a command asks for: `--sparring <slug>` is the whole fight from that sparring; a
+ * bout opened `--from-sparring` is too (one fight, one page); any other bout is its own chronicle.
+ */
+function collect(argv) {
+  const slug = option(argv, 'sparring');
+  if (slug) return collectFight(slug, argv, { collectBout, readExtra });
+  const [pr, ...rest] = argv;
+  if (!pr) throw new Error(USAGE);
+  const file = join(boutDirOf(pr, rest), 'state.json');
+  const from = existsSync(file) ? readState(dirname(file)).fromSparring : null;
+  return from
+    ? collectFight(from, rest, { collectBout, readExtra })
+    : collectBout(argv);
+}
+
 if (isMain(import.meta.url)) {
   try {
     console.log(JSON.stringify(collect(process.argv.slice(2)), null, 2));

package/ring/scripts/round-bell.mjs

@@ -21,6 +21,7 @@ import { join } from 'node:path';
 
 import {
   boutDir,
+  DO_NOT_MERGE,
   isMain,
   projectDir,
   readState,
@@ -39,7 +40,7 @@ import {
 import { render, TEMPLATES } from './judges-card.mjs';
 import { record } from './live.mjs';
 
-export const LABEL = 'do-not-merge';
+export const LABEL = DO_NOT_MERGE;
 
 /** Paths that are tests in the usual backend layouts; excluded from the production line count. */
 export const TEST_EXCLUDES = [
@@ -176,21 +177,24 @@ function isAncestor(read, ancestor, sha) {
   }
 }
 
-/** Is the label already in the host repo? Then it is left as the repo has it (color, description). */
-export function labelExists(read) {
+/**
+ * Is the label already in the host repo? Then it is left as the repo has it (color, description).
+ * `gh label list --json` prints nothing at all (not `[]`) when the search finds no label.
+ */
+export function labelExists(read, name = LABEL) {
   const labels = JSON.parse(
     read('gh', [
       'label',
       'list',
       '--search',
-      LABEL,
+      name,
       '--json',
       'name',
       '--limit',
       '100',
-    ]),
+    ]) || '[]',
   );
-  return labels.some((label) => label.name === LABEL);
+  return labels.some((label) => label.name === name);
 }
 
 function open(argv) {