browser-commander 0.16.1 → 0.17.0

package/tests/unit/scripts/run-with-budget-warning.test.js

@@ -0,0 +1,115 @@
+/**
+ * The wrapper that gives a long step its own deadline.
+ *
+ * A job killed by `timeout-minutes` is reported as cancelled, which is not a
+ * failure; a step that owns its budget exits non-zero instead, so the overrun
+ * turns a check red and names the deadline it blew. These tests pin the three
+ * properties the workflows depend on: the command's own exit status is passed
+ * through untouched, an overrun exits 124 with an error annotation, and the
+ * whole process tree is killed rather than just the direct child.
+ *
+ * See docs/CI-TIMEOUT-BUDGETS.md.
+ */
+
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+
+import { BASH_AVAILABLE, repoPath, runBashScript } from '../../helpers/repo.js';
+
+const SCRIPT = repoPath('scripts/run-with-budget-warning.sh');
+
+function runWrapper(args, env = {}) {
+  return runBashScript(SCRIPT, args, {
+    env: { BUDGET_GRACE_SECONDS: '1', ...env },
+  });
+}
+
+describe('run-with-budget-warning.sh', { skip: !BASH_AVAILABLE }, () => {
+  it('passes a successful command through', () => {
+    const { status, output } = runWrapper(['5', 'quick step', 'true']);
+
+    assert.equal(status, 0);
+    assert.match(
+      output,
+      /quick step finished in \d+s of its 5s budget \(exit 0\)/
+    );
+  });
+
+  it("passes a failing command's own exit status through", () => {
+    const { status } = runWrapper([
+      '5',
+      'failing step',
+      'bash',
+      '-c',
+      'exit 7',
+    ]);
+
+    assert.equal(status, 7);
+  });
+
+  it('exits 124 and annotates the overrun', () => {
+    const { status, output } = runWrapper(['1', 'slow step', 'sleep', '30']);
+
+    assert.equal(status, 124);
+    assert.match(
+      output,
+      /::error title=slow step exceeded its execution budget::/
+    );
+  });
+
+  it('kills the whole process group, not just the direct child', async () => {
+    // Test runners spawn workers; killing only the direct child leaves orphans
+    // holding the runner, which is why timeout(1) is not sufficient here. The
+    // worker is watched through the file it writes rather than through
+    // `kill -0`, which also succeeds for a killed-but-unreaped zombie.
+    const directory = mkdtempSync(path.join(tmpdir(), 'budget-wrapper-'));
+    const tickFile = path.join(directory, 'ticks');
+
+    try {
+      const { status } = runWrapper([
+        '1',
+        'step with a worker',
+        'bash',
+        '-c',
+        `while true; do echo tick >> ${JSON.stringify(tickFile)}; sleep 0.2; done & wait`,
+      ]);
+
+      assert.equal(status, 124);
+
+      const ticksAtTermination = readFileSync(tickFile, 'utf8').length;
+
+      assert.ok(ticksAtTermination > 0, 'the worker never started');
+
+      await new Promise((resolve) => setTimeout(resolve, 1500));
+
+      assert.equal(
+        readFileSync(tickFile, 'utf8').length,
+        ticksAtTermination,
+        'the worker outlived the budget termination'
+      );
+    } finally {
+      rmSync(directory, { force: true, recursive: true });
+    }
+  });
+
+  it('warns before the budget expires', () => {
+    const { status, output } = runWrapper(['10', 'warned step', 'sleep', '2'], {
+      BUDGET_WARN_PERCENT: '10',
+    });
+
+    assert.equal(status, 0);
+    assert.match(
+      output,
+      /::warning title=warned step is approaching its execution budget::/
+    );
+  });
+
+  it('rejects a budget that is not a positive number of seconds', () => {
+    assert.equal(runWrapper(['soon', 'bad budget', 'true']).status, 2);
+    assert.equal(runWrapper(['0', 'bad budget', 'true']).status, 2);
+    assert.equal(runWrapper(['5']).status, 2);
+  });
+});

package/tests/unit/scripts/use-module-adoption.test.js

@@ -0,0 +1,74 @@
+/**
+ * Guard that keeps every pipeline script on the use-m interop shim.
+ *
+ * A raw `const { $ } = await use('command-stream')` yields `undefined` on Node
+ * 23+ because of the synthetic `module.exports` CommonJS export, so the script
+ * dies with `TypeError: $ is not a function` inside a release job — which is
+ * exactly how the JS Release and Rust Auto Release jobs failed on 2026-09-04.
+ * Loading through scripts/use-module.mjs normalises that namespace, and this
+ * test covers both language directories so the fix cannot be reintroduced in
+ * only one of them.
+ */
+
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+const repositoryRoot = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  '..',
+  '..'
+);
+
+// Every directory holding release automation that loads packages through use-m.
+const SCRIPT_DIRECTORIES = ['js/scripts', 'rust/scripts', 'scripts'];
+const SHIM = 'use-module.mjs';
+
+function scriptSources() {
+  return SCRIPT_DIRECTORIES.flatMap((directory) =>
+    readdirSync(join(repositoryRoot, directory))
+      .filter((name) => name.endsWith('.mjs') && name !== SHIM)
+      .map((name) => ({
+        name: `${directory}/${name}`,
+        source: readFileSync(join(repositoryRoot, directory, name), 'utf8'),
+      }))
+  );
+}
+
+describe('pipeline scripts load use-m through the interop shim', () => {
+  it('finds the scripts it is meant to guard', () => {
+    assert.ok(scriptSources().length > 10);
+  });
+
+  it('never destructures a package straight off use()', () => {
+    const offenders = scriptSources()
+      .filter(({ source }) =>
+        /const\s*\{[^}]*\}\s*=\s*await\s+use\(/.test(source)
+      )
+      .map(({ name }) => name);
+    assert.deepEqual(offenders, []);
+  });
+
+  it('never fetches and evals use.js inline', () => {
+    const offenders = scriptSources()
+      .filter(({ source }) =>
+        /eval\(\s*\n?\s*await\s*\(await\s*fetch\(/.test(source)
+      )
+      .map(({ name }) => name);
+    assert.deepEqual(offenders, []);
+  });
+
+  it('routes every shim consumer through scripts/use-module.mjs', () => {
+    const offenders = scriptSources()
+      .filter(({ source }) =>
+        /load(CommandStream|LinoArguments)\(/.test(source)
+      )
+      .filter(({ source }) => !source.includes(SHIM))
+      .map(({ name }) => name);
+    assert.deepEqual(offenders, []);
+  });
+});

package/tests/unit/scripts/use-module-integration.test.js

@@ -0,0 +1,64 @@
+/**
+ * End-to-end guard for the use-m interop shim.
+ *
+ * use-module.test.js pins the namespace shapes we normalise; this file loads
+ * `command-stream` through the real, unpinned use-m on the same Node version
+ * the release jobs run (`node-version: '24.x'`) and asserts `$` is callable.
+ * Without it the interop breakage only surfaces on `main`, inside a job that
+ * pushes tags and publishes to npm.
+ *
+ * The test needs network access. When the fetch of use.js or the package
+ * install fails, it logs the reason and passes, so offline development and
+ * sandboxed runs are not blocked by an unreachable CDN.
+ */
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+  loadCommandStream,
+  USE_M_URL,
+} from '../../../../scripts/use-module.mjs';
+
+async function hasNetwork() {
+  try {
+    return (await fetch(USE_M_URL, { method: 'HEAD' })).ok;
+  } catch {
+    return false;
+  }
+}
+
+describe('use-m loads command-stream on this Node version', () => {
+  it('exposes a callable $ from command-stream', async (t) => {
+    if (process.platform === 'win32') {
+      // use-m imports the resolved file by its bare absolute path, which the
+      // Windows ESM loader rejects with ERR_UNSUPPORTED_ESM_URL_SCHEME. That is
+      // an upstream loader bug, independent of the namespace shape this shim
+      // normalises; the Linux and macOS runs still cover the interop.
+      return t.skip('use-m cannot import absolute paths on Windows');
+    }
+
+    if (!(await hasNetwork())) {
+      return t.skip(
+        `${USE_M_URL} is unreachable, so use-m cannot be evaluated`
+      );
+    }
+
+    let commandStream;
+    try {
+      commandStream = await loadCommandStream();
+    } catch (error) {
+      if (
+        /fetch|network|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|registry/i.test(
+          error.message
+        )
+      ) {
+        return t.skip(error.message);
+      }
+      throw error;
+    }
+
+    console.log(`Loaded command-stream on ${process.version}`);
+    assert.equal(typeof commandStream.$, 'function');
+  });
+});

package/tests/unit/scripts/use-module.test.js

@@ -0,0 +1,182 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+  describeModule,
+  loadCommandStream,
+  loadLinoArguments,
+  loadUse,
+  resolveNamedExport,
+  USE_M_URL,
+} from '../../../../scripts/use-module.mjs';
+
+const dollar = () => {};
+
+function commandStreamExports() {
+  return Object.assign(() => {}, { $: dollar, sh: () => {}, run: () => {} });
+}
+
+/**
+ * Namespace `import()` produces for a CommonJS file on Node < 23. use-m unwraps
+ * it because `default` is the only key, so `const { $ }` works. Measured on
+ * node v20.20.2 and v22.21.1.
+ */
+function nodeTwentyTwoNamespace() {
+  return { default: commandStreamExports() };
+}
+
+/**
+ * The same file on Node 23+: the synthetic `module.exports` key makes use-m
+ * skip the unwrap and hand the raw namespace to the caller. Measured on
+ * node v24.20.0, the version every workflow in this repository requests.
+ */
+function nodeTwentyFourNamespace() {
+  return {
+    default: commandStreamExports(),
+    'module.exports': commandStreamExports(),
+  };
+}
+
+function textResponse(
+  body,
+  { ok = true, status = 200, statusText = 'OK' } = {}
+) {
+  return {
+    ok,
+    status,
+    statusText,
+    async text() {
+      return body;
+    },
+  };
+}
+
+describe('use-module interop shim', () => {
+  it('reproduces the Node 24 namespace that breaks destructuring', () => {
+    // This is the CI failure verbatim: `$` is undefined, so the first tagged
+    // template threw `TypeError: $ is not a function` in the release jobs.
+    const { $ } = nodeTwentyFourNamespace();
+    assert.equal($, undefined);
+  });
+
+  it('resolves $ from the Node 23+ CommonJS namespace', () => {
+    const resolved = resolveNamedExport(
+      nodeTwentyFourNamespace(),
+      '$',
+      'command-stream'
+    );
+    assert.equal(typeof resolved.$, 'function');
+  });
+
+  it('resolves $ from the Node < 23 CommonJS namespace', () => {
+    const resolved = resolveNamedExport(
+      nodeTwentyTwoNamespace(),
+      '$',
+      'command-stream'
+    );
+    assert.equal(typeof resolved.$, 'function');
+  });
+
+  it('resolves $ when use-m already unwrapped the module', () => {
+    const resolved = resolveNamedExport(
+      commandStreamExports(),
+      '$',
+      'command-stream'
+    );
+    assert.equal(typeof resolved.$, 'function');
+  });
+
+  it('resolves $ from a real ES module namespace with named exports', () => {
+    const namespace = { $: dollar, sh: () => {}, default: dollar };
+    assert.equal(
+      resolveNamedExport(namespace, '$', 'command-stream'),
+      namespace
+    );
+  });
+
+  it('resolves a double-wrapped default', () => {
+    const resolved = resolveNamedExport(
+      { default: { default: commandStreamExports() } },
+      '$',
+      'command-stream'
+    );
+    assert.equal(typeof resolved.$, 'function');
+  });
+
+  it('names the observed keys when no candidate exposes the export', () => {
+    assert.throws(
+      () => resolveNamedExport({ nope: 1 }, '$', 'command-stream'),
+      (error) =>
+        error.message.includes("use('command-stream')") &&
+        error.message.includes('keys [nope]')
+    );
+  });
+
+  it('reports the received value when use-m resolved nothing', () => {
+    assert.throws(
+      () => resolveNamedExport(undefined, '$', 'command-stream'),
+      /Received undefined/
+    );
+  });
+
+  it('describes null, primitives and objects', () => {
+    assert.equal(describeModule(null), 'null');
+    assert.equal(describeModule(7), 'number');
+    assert.equal(describeModule({ a: 1, b: 2 }), 'object with keys [a, b]');
+  });
+
+  it('loads command-stream through an injected use() implementation', async () => {
+    const calls = [];
+    const use = async (name) => {
+      calls.push(name);
+      return nodeTwentyFourNamespace();
+    };
+    const module = await loadCommandStream(use);
+    assert.deepEqual(calls, ['command-stream']);
+    assert.equal(typeof module.$, 'function');
+  });
+
+  it('loads lino-arguments through an injected use() implementation', async () => {
+    const calls = [];
+    const use = async (name) => {
+      calls.push(name);
+      return { default: { makeConfig: () => ({}) } };
+    };
+    const module = await loadLinoArguments(use);
+    assert.deepEqual(calls, ['lino-arguments']);
+    assert.equal(typeof module.makeConfig, 'function');
+  });
+
+  it('points at the unpinned use-m entry point', () => {
+    assert.equal(USE_M_URL, 'https://unpkg.com/use-m/use.js');
+  });
+
+  it('reports the HTTP status when use.js cannot be fetched', async () => {
+    // Without this the error page would be eval'd and surface as a SyntaxError.
+    await assert.rejects(
+      loadUse({
+        fetchImpl: async () =>
+          textResponse('<html>Not Found</html>', {
+            ok: false,
+            status: 404,
+            statusText: 'Not Found',
+          }),
+      }),
+      /404 Not Found/
+    );
+  });
+
+  it('reports a use.js payload that exposes no callable use()', async () => {
+    await assert.rejects(
+      loadUse({ fetchImpl: async () => textResponse('({ nope: 1 })') }),
+      /did not export a callable "use"/
+    );
+  });
+
+  it('evaluates a well-formed use.js payload', async () => {
+    const use = await loadUse({
+      fetchImpl: async () => textResponse('({ use: async () => ({}) })'),
+    });
+    assert.equal(typeof use, 'function');
+  });
+});

package/.husky/pre-commit

@@ -1 +0,0 @@
-npx lint-staged

package/.prettierrc

@@ -1,10 +0,0 @@
-{
-  "semi": true,
-  "trailingComma": "es5",
-  "singleQuote": true,
-  "printWidth": 80,
-  "tabWidth": 2,
-  "useTabs": false,
-  "arrowParens": "always",
-  "endOfLine": "lf"
-}