browser-commander 0.17.1 → 0.17.2

package/.jscpd-baseline.json

@@ -3,6 +3,7 @@
   "fingerprints": {
     "00d381dd611ae8ac": 1,
     "029a62ef1f48e856": 1,
+    "03241c1f33f40d14": 1,
     "038170e72e0af1f5": 1,
     "04b28d01d0bb47dc": 1,
     "04f605be138bc350": 1,
@@ -30,6 +31,7 @@
     "1ac9fbd87efdb313": 1,
     "1ad4dc7e19a77f68": 1,
     "1c1baf1bc8ea0eae": 1,
+    "1cbd39b416a2b94b": 1,
     "1d61f5c49f12d2dc": 1,
     "1ef570563d4e5a08": 1,
     "1f2104c950b12a30": 1,
@@ -98,6 +100,7 @@
     "5ae9b1430fc38daf": 1,
     "602bfd129bba900e": 1,
     "608e1dd27138ec6f": 1,
+    "6098544c77ff17a2": 1,
     "60d0c58a01fc8746": 1,
     "61bcadcd8dc9f63e": 1,
     "63a3b672c8d8b50b": 1,
@@ -142,7 +145,6 @@
     "876d2c8edfc8c40a": 1,
     "8b013ac20e436d76": 1,
     "8c2b1408886c1db1": 1,
-    "8c36ed4fc291ae47": 1,
     "8cb9a984bf19a062": 1,
     "8ec18cdbd4a96518": 1,
     "8ecf2e554a04d2ef": 1,

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.17.2
+
+### Patch Changes
+
+- 539ae64: Recover a release push that lost the race to `main` instead of failing the run.
+
+  The `main-writer` concurrency group serialises the three release jobs correctly,
+  but `actions/checkout` checks out `github.sha`, so every writer after the first
+  holds a tree one commit behind `main` and its push is rejected as
+  non-fast-forward. Serialisation buys ordering, not freshness. Every push to
+  `main` now rebases and retries — after classifying the rejection, because a
+  GH006/GH013 ruleset rejection also prints "rejected" and can never be rebased
+  away.
+
 ## 0.17.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",

package/scripts/version-and-commit.mjs

@@ -16,6 +16,10 @@ import { readFileSync, appendFileSync, readdirSync } from 'fs';
 
 import { assertGeneratedFilesAreFormatted } from './check-release-format.mjs';
 
+import {
+  createGitRunner,
+  pushWithRebaseRetry,
+} from '../../scripts/push-with-rebase-retry.mjs';
 import {
   loadCommandStream,
   loadLinoArguments,
@@ -232,8 +236,15 @@ async function main() {
       const escapedMessage = commitMessage.replace(/"/g, '\\"');
       await $`git commit -m "${escapedMessage}"`;
 
-      // Push directly to main
-      await $`git push origin main`;
+      // Push directly to main.
+      //
+      // The pre-emptive rebase above runs before the version bump, so it
+      // cannot cover a writer that lands between the bump and this push.
+      // pushWithRebaseRetry closes that window and, just as importantly,
+      // distinguishes a lost race from a branch-protection rejection instead
+      // of retrying one as if it were the other.
+      const git = await createGitRunner();
+      await pushWithRebaseRetry({ git, branch: 'main' });
 
       console.log('\u2705 Version bump committed and pushed to main');
       setOutput('version_committed', 'true');

package/tests/unit/scripts/check-release-format.test.js

@@ -120,7 +120,10 @@ describe('release commit formatting gate', () => {
     );
     const check = script.indexOf('assertGeneratedFilesAreFormatted(() =>');
     const commit = script.indexOf('git commit');
-    const push = script.indexOf('git push origin main');
+    // The raw `git push origin main` this used to look for is now
+    // pushWithRebaseRetry, which rebases when another release wrote to main
+    // first. See dev/log/issues/85/pulls/86/analysis/root-causes.md (RC-1).
+    const push = script.indexOf('pushWithRebaseRetry({');
 
     assert.ok(check > 0 && commit > 0 && push > 0);
     assert.ok(

package/tests/unit/scripts/push-failure-classifier.test.js

@@ -0,0 +1,153 @@
+/**
+ * Guard for RC-1: a release job that treats every rejected push the same.
+ *
+ * Two rejections both print "rejected" and need opposite responses. A lost
+ * race is fixed by rebasing; a repository-rule violation can never be, and
+ * retrying it burns the retry and blames a race that never happened.
+ *
+ * The samples below are the literal wordings the two situations produce:
+ * `non-fast-forward` from the CI logs in dev/log/issues/85/pulls/86/ci-logs/,
+ * `fetch first` from the local reproduction in
+ * experiments/ci-repro/repro-release-push-race.sh.
+ *
+ * Analysis: dev/log/issues/85/pulls/86/analysis/root-causes.md, RC-1
+ */
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+  NON_FAST_FORWARD_PATTERNS,
+  REPOSITORY_RULE_PATTERNS,
+  classifyPushFailure,
+  isBlockedByRepositoryRule,
+  isNonFastForward,
+} from '../../../../scripts/push-failure-classifier.mjs';
+
+/** Rejection text a lost race produces, verbatim. */
+const RACE_SAMPLES = [
+  {
+    label: 'non-fast-forward (remote commits already fetched)',
+    stderr: [
+      'To https://github.com/link-foundation/browser-commander',
+      ' ! [rejected]        HEAD -> main (non-fast-forward)',
+      "error: failed to push some refs to 'https://github.com/link-foundation/browser-commander'",
+      'hint: Updates were rejected because a pushed branch tip is behind its remote',
+    ].join('\n'),
+  },
+  {
+    label: 'fetch first (remote commits not yet fetched)',
+    stderr: [
+      ' ! [rejected]        HEAD -> main (fetch first)',
+      'error: failed to push some refs',
+      'hint: Updates were rejected because the remote contains work that you do not',
+      'hint: have locally.',
+    ].join('\n'),
+  },
+];
+
+/** Rejection text a ruleset or protected branch produces, verbatim. */
+const RULE_SAMPLES = [
+  {
+    label: 'GH013 repository ruleset',
+    stderr: [
+      'remote: error: GH013: Repository rule violations found for refs/heads/main.',
+      'remote: - Changes must be made through a pull request.',
+      ' ! [remote rejected] main -> main (push declined due to repository rule violations)',
+    ].join('\n'),
+  },
+  {
+    label: 'GH006 legacy protected branch',
+    stderr: [
+      'remote: error: GH006: Protected branch update failed for refs/heads/main.',
+      ' ! [remote rejected] main -> main (protected branch hook declined)',
+    ].join('\n'),
+  },
+];
+
+describe('push failure classifier', () => {
+  it('reads a lost race as non-fast-forward', () => {
+    for (const sample of RACE_SAMPLES) {
+      assert.equal(
+        classifyPushFailure(sample),
+        'non-fast-forward',
+        `${sample.label} must be retried by rebasing`
+      );
+      assert.equal(isNonFastForward(sample), true, sample.label);
+      assert.equal(isBlockedByRepositoryRule(sample), false, sample.label);
+    }
+  });
+
+  it('never reads a rule violation as a lost race', () => {
+    // This is the whole point of the module. A ruleset rejection contains the
+    // word "rejected" too, so a naive substring check retries a push that can
+    // never succeed.
+    for (const sample of RULE_SAMPLES) {
+      assert.equal(
+        classifyPushFailure(sample),
+        'repository-rule',
+        `${sample.label} must not be retried`
+      );
+      assert.equal(isNonFastForward(sample), false, sample.label);
+      assert.equal(isBlockedByRepositoryRule(sample), true, sample.label);
+    }
+  });
+
+  it('leaves an unrelated failure unclassified so it is not retried', () => {
+    const authFailure = {
+      stderr:
+        'fatal: could not read Username for https://github.com: No such device or address',
+    };
+    assert.equal(classifyPushFailure(authFailure), 'unknown');
+    assert.equal(isNonFastForward(authFailure), false);
+    assert.equal(isBlockedByRepositoryRule(authFailure), false);
+  });
+
+  it('ignores the generic wrapper message command-stream attaches', () => {
+    // command-stream rejects with "Command failed with exit code 1"; the
+    // classification has to rest on what git wrote, not on the wrapper.
+    const wrapped = {
+      message: 'Command failed with exit code 1',
+      stdout: '',
+      stderr: 'Everything up-to-date',
+    };
+    assert.equal(classifyPushFailure(wrapped), 'unknown');
+  });
+
+  it('reads a bare string as well as a command result', () => {
+    assert.equal(
+      classifyPushFailure(' ! [rejected] main -> main (non-fast-forward)'),
+      'non-fast-forward'
+    );
+    assert.equal(
+      classifyPushFailure('remote: error: GH013:'),
+      'repository-rule'
+    );
+  });
+
+  it('survives a failure with nothing to read', () => {
+    for (const empty of [null, undefined, {}, '']) {
+      assert.equal(classifyPushFailure(empty), 'unknown');
+    }
+  });
+
+  it('matches case-insensitively, because git and GitHub disagree on case', () => {
+    assert.equal(
+      classifyPushFailure({
+        stderr: 'REMOTE: ERROR: GH013: REPOSITORY RULE VIOLATIONS',
+      }),
+      'repository-rule'
+    );
+    assert.equal(
+      classifyPushFailure({
+        stderr: '! [REJECTED] main -> main (NON-FAST-FORWARD)',
+      }),
+      'non-fast-forward'
+    );
+  });
+
+  it('keeps the pattern lists frozen so a caller cannot widen them', () => {
+    assert.throws(() => REPOSITORY_RULE_PATTERNS.push('anything'));
+    assert.throws(() => NON_FAST_FORWARD_PATTERNS.push('anything'));
+  });
+});

package/tests/unit/scripts/push-with-rebase-retry.test.js

@@ -0,0 +1,302 @@
+/**
+ * Guard for RC-1 and RC-3.
+ *
+ * RC-1: the release jobs are serialised by a concurrency group but each one
+ * checks out `github.sha`, so every writer after the first holds a tree one
+ * commit behind main and its push is rejected. Nothing rebased and retried.
+ *
+ * RC-3: a retry rebases, which rewrites the release commit. A tag created
+ * before the push would keep pointing at the pre-rebase commit and be
+ * reachable from no branch -- reproduced as case 2 of
+ * experiments/ci-repro/repro-release-push-race.sh. So the release scripts must
+ * tag only after the push has succeeded.
+ *
+ * Analysis: dev/log/issues/85/pulls/86/analysis/root-causes.md
+ */
+
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, it } from 'node:test';
+
+import {
+  DEFAULT_ATTEMPTS,
+  pushWithRebaseRetry,
+  resolveCurrentBranch,
+} from '../../../../scripts/push-with-rebase-retry.mjs';
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../../..');
+
+/** A rejection shaped like the one `command-stream` produces for git. */
+function rejection(stderr) {
+  return Object.assign(new Error('Command failed with exit code 1'), {
+    code: 1,
+    stdout: '',
+    stderr,
+  });
+}
+
+const RACE = ' ! [rejected]        HEAD -> main (non-fast-forward)\n';
+const RULE = [
+  'remote: error: GH013: Repository rule violations found for refs/heads/main.',
+  'remote: - Changes must be made through a pull request.',
+].join('\n');
+
+/**
+ * Build a fake git that fails the first `failures` pushes with `stderr`, then
+ * succeeds, recording every argv it was handed.
+ */
+function fakeGit({ failures = 0, stderr = RACE, stdout = '' } = {}) {
+  const calls = [];
+  let pushes = 0;
+  const git = async (args) => {
+    calls.push(args.join(' '));
+    if (args[0] === 'push') {
+      pushes++;
+      if (pushes <= failures) {
+        throw rejection(stderr);
+      }
+    }
+    return { stdout, stderr: '', code: 0 };
+  };
+  git.calls = calls;
+  return git;
+}
+
+/** Collect log lines instead of printing them. */
+function fakeLogger() {
+  const lines = [];
+  return { lines, log: (line) => lines.push(line) };
+}
+
+const silent = () => {};
+
+describe('pushWithRebaseRetry', () => {
+  it('pushes once when nothing else has written to the branch', async () => {
+    const git = fakeGit();
+    const result = await pushWithRebaseRetry({
+      git,
+      branch: 'main',
+      logger: fakeLogger(),
+      debugFn: silent,
+    });
+
+    assert.deepEqual(result, { pushed: true, via: 'direct', attempts: 1 });
+    assert.deepEqual(git.calls, ['push origin HEAD:main']);
+  });
+
+  it('rebases and retries after losing the race, as in run 33998729944', async () => {
+    const git = fakeGit({ failures: 1 });
+    const logger = fakeLogger();
+
+    const result = await pushWithRebaseRetry({
+      git,
+      branch: 'main',
+      logger,
+      debugFn: silent,
+    });
+
+    assert.deepEqual(result, { pushed: true, via: 'rebase', attempts: 2 });
+    assert.deepEqual(git.calls, [
+      'push origin HEAD:main',
+      'pull --rebase origin main',
+      'push origin HEAD:main',
+    ]);
+    assert.ok(
+      logger.lines.some((line) => line.startsWith('::warning::')),
+      'a recovered race must still be visible in the log'
+    );
+  });
+
+  it('does not retry a repository-rule rejection', async () => {
+    // Rebasing cannot satisfy a ruleset. Retrying it doubles the time the job
+    // takes to die and leaves a log blaming a race that never happened.
+    const git = fakeGit({ failures: DEFAULT_ATTEMPTS, stderr: RULE });
+    const logger = fakeLogger();
+
+    await assert.rejects(
+      pushWithRebaseRetry({ git, branch: 'main', logger, debugFn: silent })
+    );
+
+    assert.deepEqual(git.calls, ['push origin HEAD:main']);
+    assert.ok(
+      logger.lines.some(
+        (line) => line.startsWith('::error::') && line.includes('GH006/GH013')
+      ),
+      'the log must name the real cause'
+    );
+  });
+
+  it('does not retry a failure a rebase cannot fix', async () => {
+    const git = fakeGit({
+      failures: DEFAULT_ATTEMPTS,
+      stderr: 'fatal: could not read Username for https://github.com',
+    });
+
+    await assert.rejects(
+      pushWithRebaseRetry({
+        git,
+        branch: 'main',
+        logger: fakeLogger(),
+        debugFn: silent,
+      })
+    );
+    assert.deepEqual(git.calls, ['push origin HEAD:main']);
+  });
+
+  it('gives up after the configured number of attempts', async () => {
+    const git = fakeGit({ failures: 99 });
+
+    await assert.rejects(
+      pushWithRebaseRetry({
+        git,
+        branch: 'main',
+        attempts: 3,
+        logger: fakeLogger(),
+        debugFn: silent,
+      })
+    );
+
+    const pushes = git.calls.filter((call) => call.startsWith('push'));
+    assert.equal(pushes.length, 3, 'exactly `attempts` pushes, no more');
+  });
+
+  it('pushes the branch it is told to, not always main', async () => {
+    const git = fakeGit();
+    await pushWithRebaseRetry({
+      git,
+      remote: 'upstream',
+      branch: 'release',
+      logger: fakeLogger(),
+      debugFn: silent,
+    });
+    assert.deepEqual(git.calls, ['push upstream HEAD:release']);
+  });
+
+  it('stays silent on the debug channel unless tracing is switched on', async () => {
+    // The verbose mode has to default to off: a release log is read by people
+    // looking for the one line that matters.
+    const traced = [];
+    const git = fakeGit({ failures: 1 });
+    await pushWithRebaseRetry({
+      git,
+      branch: 'main',
+      logger: fakeLogger(),
+      debugFn: (...parts) => traced.push(parts.join(' ')),
+    });
+    assert.ok(traced.length > 0, 'the helper must offer tracing to inject');
+
+    const quiet = [];
+    const { debugWith } = await import('../../../../scripts/debug-print.mjs');
+    await pushWithRebaseRetry({
+      git: fakeGit(),
+      branch: 'main',
+      logger: fakeLogger(),
+      debugFn: (...parts) =>
+        debugWith({ env: {}, log: (l) => quiet.push(l) }, ...parts),
+    });
+    assert.deepEqual(quiet, [], 'debug output must be off by default');
+  });
+});
+
+describe('resolveCurrentBranch', () => {
+  it('reads the branch instead of assuming main', async () => {
+    // The Rust release used a bare `git push`, which follows the current
+    // branch's upstream; a hard-coded HEAD:main would change behaviour for a
+    // workflow_dispatch run started from another branch.
+    const git = fakeGit({ stdout: 'release-2.x\n' });
+    assert.equal(await resolveCurrentBranch(git), 'release-2.x');
+    assert.deepEqual(git.calls, ['rev-parse --abbrev-ref HEAD']);
+  });
+
+  it('falls back to main when git says nothing', async () => {
+    assert.equal(
+      await resolveCurrentBranch(fakeGit({ stdout: '  \n' })),
+      'main'
+    );
+  });
+
+  it('does not push HEAD:HEAD from a detached checkout', async () => {
+    // `git rev-parse --abbrev-ref HEAD` prints the literal "HEAD" when
+    // detached. Using it as the target branch would aim the push at a remote
+    // branch named HEAD instead of the release branch.
+    assert.equal(
+      await resolveCurrentBranch(fakeGit({ stdout: 'HEAD\n' })),
+      'main'
+    );
+    assert.equal(
+      await resolveCurrentBranch(fakeGit({ stdout: 'HEAD\n' }), 'release'),
+      'release'
+    );
+  });
+});
+
+describe('release scripts tag only after the push (RC-3)', () => {
+  const releaseScripts = [
+    'rust/scripts/version-and-commit.mjs',
+    'js/scripts/version-and-commit.mjs',
+  ];
+
+  for (const relativePath of releaseScripts) {
+    it(`${relativePath} never leaves an orphaned tag`, () => {
+      const source = readFileSync(join(repoRoot, relativePath), 'utf8');
+      const tagIndex = source.indexOf('git tag -a');
+      if (tagIndex === -1) {
+        return; // This script does not tag; nothing to order.
+      }
+      const pushIndex = source.indexOf('pushWithRebaseRetry({');
+      assert.notEqual(
+        pushIndex,
+        -1,
+        `${relativePath} must push through pushWithRebaseRetry`
+      );
+      assert.ok(
+        pushIndex < tagIndex,
+        `${relativePath} creates a tag before pushing; a rebase retry would ` +
+          'rewrite the commit and orphan that tag'
+      );
+    });
+  }
+
+  it('no release script pushes with the blanket --tags', () => {
+    // `git push --tags` also pushes every unrelated local tag the runner
+    // happens to have fetched.
+    for (const relativePath of releaseScripts) {
+      const source = readFileSync(join(repoRoot, relativePath), 'utf8');
+      assert.ok(
+        !source.includes('git push --tags'),
+        `${relativePath} must push its release tag by name`
+      );
+    }
+  });
+});
+
+describe('every release push site uses the shared helper', () => {
+  // The fix has to be applied everywhere: a single un-migrated push site
+  // reproduces the original failure the next time two releases run.
+  it('leaves no raw push to a shared branch behind', () => {
+    const sites = [
+      'js/scripts/version-and-commit.mjs',
+      'rust/scripts/version-and-commit.mjs',
+    ];
+    for (const relativePath of sites) {
+      const source = readFileSync(join(repoRoot, relativePath), 'utf8');
+      for (const raw of [
+        'git push`',
+        'git push origin main`',
+        'git push --tags`',
+        'git push origin HEAD:main`',
+      ]) {
+        assert.ok(
+          !source.includes(raw),
+          `${relativePath} still contains a raw \`${raw}\``
+        );
+      }
+      assert.ok(
+        source.includes('pushWithRebaseRetry'),
+        `${relativePath} must push through the shared helper`
+      );
+    }
+  });
+});