Files
gstack/test/gstack-browser-ensure.test.ts
T
Garry Tanandcapy-ai[bot] bcece3fbcd Make gstack's shell locks hold when mkdir reports a race it lost (GST-2247) (#4262)
* Make gstack's shell locks hold when mkdir reports a race it lost (GST-2247)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Fix lock tests and fixtures for gstack_lock_take; trim setup-gbrain lock prose

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Ship the lock helper with every copied runtime and fixture that runs a lock

The Claude Code wrapper's copied runtime now includes bin/gstack-lock.sh, and
bin/gstack-render-claude.sh sources it beside itself, so gstack-config set
works in a copied runtime and the render lock is taken by every caller.
Test fixtures that copy single bin scripts now copy the helper too, and the
mkdir lock guard is registered as a repo-wide docs reader.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Release a lock whose owner file could not be fully written

gstack_lock_take created the owner file with a noclobber redirect and, when
that redirect failed, treated an existing file as a competing holder. If the
file was created but the write then failed (disk full, quota, ulimit -f), the
helper found its own empty file, returned 1 and left a lock nobody held;
freeze's state lock has no stale recovery, so it stayed busy until removed by
hand. The helper now tells "opened but write failed" from "already held",
removes its own file and directory, and returns 3. The inline copy in
gstack-ff-update is updated byte for byte, and a new test under ulimit -f 0
fails on the old helper.

Review-Finding: s11/outside-voice#1 reader=outside-voice
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Describe the lease lock as gstack_lock_take's O_EXCL owner file

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-11-17 09:05:25 +00:00

294 lines
17 KiB
TypeScript

/**
* bin/gstack-browser-ensure: the lazy Chromium install the browse preflight
* runs on first use. Pinned on the wire lines (BROWSER_OK / BROWSER_UNAVAILABLE),
* exit codes, the no-install `--check` mode, the install-then-reprobe path
* under setup's lock, and the preflight wiring in scripts/resolvers/browse.ts.
* Chromium itself is a stub `node_modules/playwright` whose launch succeeds
* only once a marker the stubbed `bunx playwright install` writes exists.
*/
import { afterEach, describe, expect, test } from 'bun:test';
import { spawnSync } from 'child_process';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import { generateBrowseFallback, generateBrowseSetup } from '../scripts/resolvers/browse';
import { HOST_PATHS } from '../scripts/resolvers/types';
const ctxFor = (host: 'claude' | 'codex', skillName: string) => ({ skillName, tmplPath: '', host, paths: HOST_PATHS[host] });
const REPO = path.resolve(import.meta.dir, '..');
const bases: string[] = [];
afterEach(() => { for (const b of bases.splice(0)) fs.rmSync(b, { recursive: true, force: true }); });
const write = (file: string, text: string, mode = 0o644) => {
fs.mkdirSync(path.dirname(file), { recursive: true });
fs.writeFileSync(file, text, { mode });
};
function fixture(opts: { playwright?: boolean } = {}) {
const base = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'browser-ensure-')));
bases.push(base);
const root = path.join(base, 'gstack');
const stub = path.join(base, 'stub');
const marker = path.join(base, 'chromium-installed');
fs.mkdirSync(stub, { recursive: true });
fs.mkdirSync(path.join(root, 'bin'), { recursive: true });
fs.copyFileSync(path.join(REPO, 'bin/gstack-browser-ensure'), path.join(root, 'bin/gstack-browser-ensure'));
fs.chmodSync(path.join(root, 'bin/gstack-browser-ensure'), 0o755);
fs.copyFileSync(path.join(REPO, 'bin/gstack-lock.sh'), path.join(root, 'bin/gstack-lock.sh'));
if (opts.playwright !== false) {
write(path.join(root, 'node_modules/playwright/index.js'), [
'const fs = require("fs");',
`const marker = ${JSON.stringify(marker)};`,
'module.exports.chromium = { launch: async () => {',
' if (!fs.existsSync(marker)) throw new Error("browserType.launch: Executable doesn\'t exist at /nowhere/chrome");',
' return { version: () => "141.0.7390.37", close: async () => {}, newPage: async () => ({ setContent: async () => {}, title: async () => "gstack smoke test" }) };',
'} };',
].join('\n'));
}
// A winget-shaped Bun (#3131): `bun` and no `bunx` anywhere on PATH. `bun x playwright install chromium`
// "installs" by writing the marker and logging its argv.
write(path.join(stub, 'bun'), `#!/usr/bin/env bash\n[ "$1" = --version ] && { echo 1.4.2; exit 0; }\n[ "$1" = x ] || exit 0\nshift\necho "$*" >> "${base}/bunx-calls"\ncase "$*" in *"playwright install"*) touch "${marker}" ;; *) exit 9 ;; esac\n`, 0o755);
const rest = (process.env.PATH ?? '').split(path.delimiter).filter((d) => d && !fs.existsSync(path.join(d, 'bunx')));
const env: Record<string, string> = { PATH: [stub, ...rest].join(path.delimiter), HOME: base, TMPDIR: base, GSTACK_PLAYWRIGHT_INSTALL_TIMEOUT: '20' };
const run = (args: string[] = [], extra: Record<string, string> = {}) =>
spawnSync('bash', [path.join(root, 'bin/gstack-browser-ensure'), ...args], { encoding: 'utf8', env: { ...env, ...extra }, timeout: 60_000 });
return { base, root, marker, run, calls: () => fs.existsSync(path.join(base, 'bunx-calls')) ? fs.readFileSync(path.join(base, 'bunx-calls'), 'utf8') : '' };
}
const lastLine = (s: string) => s.trim().split('\n').at(-1);
// Value: protects=a runtime root with no package.json (~/.codex/skills/gstack and
// the other host roots) probes the dependencies of the gstack checkout its
// .source-path names, and only of a real gstack checkout; fails_when=the
// helper ignores the pointer, or follows an empty, stale, relative, linked or
// non-gstack one, or lets a pointer override a root's own package.json, or
// --check writes anything; why_new=no fixture had a .source-path;
// seam=none; no_claim=a real Chromium launch (Playwright is a stub).
describe('gstack-browser-ensure in a runtime root without package.json', () => {
const playwrightStub = (version: string) =>
`module.exports.chromium = { launch: async () => ({ version: () => ${JSON.stringify(version)}, close: async () => {}, newPage: async () => ({ setContent: async () => {}, title: async () => "gstack smoke test" }) }) };\n`;
function runtime(checkoutName = 'checkout') {
const f = fixture({ playwright: false });
const checkout = path.join(f.base, checkoutName);
write(path.join(checkout, 'package.json'), '{\n "name": "gstack",\n "version": "0.0.0"\n}\n');
write(path.join(checkout, 'bin/gstack-browser-ensure'), '#!/usr/bin/env bash\n', 0o755);
write(path.join(checkout, 'node_modules/playwright/index.js'), playwrightStub('141.1.0'));
const point = (text: string) => write(path.join(f.root, '.source-path'), text);
const tree = () => walkFiles(f.base).filter(p => !p.startsWith(path.join(f.base, 'stub'))).sort();
return { ...f, checkout, point, tree };
}
const walkFiles = (dir: string): string[] => fs.readdirSync(dir, { withFileTypes: true })
.flatMap(e => e.isDirectory() ? walkFiles(path.join(dir, e.name)) : [path.join(dir, e.name)]);
const unavailable = (root: string) => `BROWSER_UNAVAILABLE playwright is not installed under ${root}/node_modules`;
for (const [label, name, eol] of [
['the recorded checkout', 'checkout', '\n'],
['a checkout path with spaces', 'gstack checkout', '\n'],
['a CRLF pointer', 'checkout', '\r\n'],
] as const) {
test(`--check probes ${label} and writes nothing`, () => {
const f = runtime(name);
f.point(f.checkout + eol);
const files = f.tree();
const r = f.run(['--check']);
expect(r.status, r.stdout + r.stderr).toBe(0);
expect(lastLine(r.stdout)).toBe('BROWSER_OK node 141.1.0');
expect(f.tree()).toEqual(files);
expect(f.calls()).toBe('');
});
}
test('without --check a valid pointer is a probe only, and a link to the checkout resolves to it', () => {
const f = runtime();
const link = path.join(f.base, 'checkout-link');
fs.symlinkSync(f.checkout, link);
f.point(link + '\n');
const r = f.run();
expect(r.status, r.stdout + r.stderr).toBe(0);
expect(lastLine(r.stdout)).toBe('BROWSER_OK node 141.1.0');
expect(fs.existsSync(path.join(f.root, 'node_modules'))).toBe(false);
expect(f.calls()).toBe('');
});
const refused: Array<[string, (f: ReturnType<typeof runtime>) => void]> = [
['an empty pointer', f => f.point('\n')],
['a stale pointer', f => f.point(path.join(f.base, 'gone') + '\n')],
['a relative pointer', f => f.point(path.relative(process.cwd(), f.checkout) + '\n')],
['a pointer file that is a link', f => { write(path.join(f.base, 'elsewhere'), f.checkout + '\n'); fs.symlinkSync(path.join(f.base, 'elsewhere'), path.join(f.root, '.source-path')); }],
['a directory whose package.json is not gstack\'s', f => { write(path.join(f.checkout, 'package.json'), '{\n "name": "left-pad"\n}\n'); f.point(f.checkout + '\n'); }],
['a directory whose package.json is a link', f => {
write(path.join(f.base, 'real-package.json'), fs.readFileSync(path.join(f.checkout, 'package.json'), 'utf8'));
fs.rmSync(path.join(f.checkout, 'package.json'));
fs.symlinkSync(path.join(f.base, 'real-package.json'), path.join(f.checkout, 'package.json'));
f.point(f.checkout + '\n');
}],
['a directory without gstack-browser-ensure', f => { fs.rmSync(path.join(f.checkout, 'bin'), { recursive: true }); f.point(f.checkout + '\n'); }],
];
for (const [label, setUp] of refused) {
test(`--check ignores ${label} and reports the runtime root, as before`, () => {
const f = runtime();
setUp(f);
const files = f.tree();
const r = f.run(['--check']);
expect(r.status, r.stdout + r.stderr).toBe(1);
expect(lastLine(r.stdout)).toBe(unavailable(f.root));
expect(f.tree()).toEqual(files);
expect(f.calls()).toBe('');
});
}
test('a root with its own package.json keeps its own dependencies over a valid pointer', () => {
const f = runtime();
write(path.join(f.root, 'package.json'), '{\n "name": "gstack"\n}\n');
write(path.join(f.root, 'node_modules/playwright/index.js'), playwrightStub('142.2.0'));
f.point(f.checkout + '\n');
const r = f.run(['--check']);
expect(r.status, r.stdout + r.stderr).toBe(0);
expect(lastLine(r.stdout)).toBe('BROWSER_OK node 142.2.0');
});
});
describe('gstack-browser-ensure', () => {
test('--check never installs: unavailable Chromium is BROWSER_UNAVAILABLE, exit 1, with the fix line and code', () => {
const f = fixture();
const r = f.run(['--check']);
expect(r.status).toBe(1);
expect(lastLine(r.stdout)).toMatch(/^BROWSER_UNAVAILABLE Chromium did not launch via node \(browserType\.launch: Executable doesn't exist/);
expect(r.stderr).toContain('(BROWSER_UNAVAILABLE; https://github.com/garrytan/gstack/blob/main/docs/troubleshooting.md#browser-ensure-failed)');
expect(r.stderr).toContain(`fix: ${f.root}/bin/gstack-browser-ensure`);
expect(f.calls()).toBe('');
expect(fs.existsSync(f.marker)).toBe(false);
});
test('a missing node_modules is reported, not installed, under --check', () => {
const f = fixture({ playwright: false });
const r = f.run(['--check']);
expect(r.status).toBe(1);
expect(lastLine(r.stdout)).toBe(`BROWSER_UNAVAILABLE playwright is not installed under ${f.root}/node_modules`);
expect(r.stderr).toContain(`fix: cd ${f.root} && ./setup`);
});
test('first use installs Chromium under setup\'s lock, re-probes and prints BROWSER_OK; the second run is a probe only', () => {
const f = fixture();
const first = f.run();
expect(first.status, first.stdout + first.stderr).toBe(0);
expect(lastLine(first.stdout)).toBe('BROWSER_OK node 141.0.7390.37');
expect(f.calls().trim()).toBe('playwright install chromium');
expect(first.stderr).toContain('installing Playwright Chromium');
expect(fs.existsSync(path.join(f.base, 'gstack-playwright-install.lock'))).toBe(false);
const second = f.run(['--quiet']);
expect(second.status).toBe(0);
expect(second.stdout.trim()).toBe('BROWSER_OK node 141.0.7390.37');
expect(second.stderr).toBe('');
expect(f.calls().trim()).toBe('playwright install chromium');
});
test('--with-deps reaches the installer; a held lock by a live process is waited on, a dead holder is reclaimed', () => {
const f = fixture();
const lock = path.join(f.base, 'gstack-playwright-install.lock');
fs.mkdirSync(lock);
fs.writeFileSync(path.join(lock, 'pid'), '999999999\n');
const r = f.run(['--with-deps']);
expect(r.status, r.stdout + r.stderr).toBe(0);
expect(f.calls().trim()).toBe('playwright install --with-deps chromium');
expect(fs.existsSync(lock)).toBe(false);
});
test('an installer failure is BROWSER_UNAVAILABLE with the exit code; usage errors exit 2; --help exits 0', () => {
const f = fixture();
fs.writeFileSync(path.join(f.base, 'stub/bun'), '#!/usr/bin/env bash\nexit 7\n');
const r = f.run();
expect(r.status).toBe(1);
expect(lastLine(r.stdout)).toBe(`BROWSER_UNAVAILABLE ${path.join(f.base, 'stub/bun')} x playwright install chromium exited 7 (offline, proxy, or blocked download?)`);
expect(f.run(['--bogus']).status).toBe(2);
const help = f.run(['--help']);
expect(help.status).toBe(0);
expect(help.stdout).toContain('--check');
});
});
describe('gstack-browser-ensure with a winget-shaped Bun (#3131)', () => {
test('the install runs as `bun x` when no bunx exists, then re-probes to BROWSER_OK', () => {
const f = fixture();
const r = f.run();
expect(r.status, r.stdout + r.stderr).toBe(0);
expect(lastLine(r.stdout)).toBe('BROWSER_OK node 141.0.7390.37');
expect(f.calls().trim()).toBe('playwright install chromium');
});
test('exit 127 names the resolved bun and Bun from bun.sh, not the network', () => {
const f = fixture();
fs.writeFileSync(path.join(f.base, 'stub/bun'), '#!/usr/bin/env bash\nexit 127\n');
const r = f.run();
expect(r.status).toBe(1);
expect(lastLine(r.stdout)).toBe(`BROWSER_UNAVAILABLE ${path.join(f.base, 'stub/bun')} x playwright install chromium exited 127 (command not found)`);
expect(r.stderr).toContain('fix: install Bun from bun.sh (winget Bun ships no bunx), then re-run');
expect(r.stderr).not.toContain('Playwright CDN');
});
});
// Generated by /ship Step 7 coverage audit (GSTA-97).
// Value: protects=a missing node_modules is installed production-only, a stale lockfile is refreshed before the retry, and a failed install ends in BROWSER_UNAVAILABLE;
// fails_when=--production leaves either install, the lockfile refresh is lost, or a failed install no longer reports the fix line;
// why_new=setup-production-deps.test.ts matches the line's text only, and the --check case never installs;
// seam=none; no_claim=a real bun install (a stub bun records argv, models Bun's frozen --production rule and restores a stub playwright)
describe('gstack-browser-ensure installs a missing node_modules production-only (GSTA-97)', () => {
function installing(frozenRc: number, fallbackRc: number) {
const f = fixture();
fs.writeFileSync(f.marker, '');
fs.renameSync(path.join(f.root, 'node_modules/playwright'), path.join(f.base, 'playwright-stub'));
fs.writeFileSync(path.join(f.base, 'stub/bun'), [
'#!/usr/bin/env bash',
'[ "$1" = install ] || exit 9',
`echo "$*" >> ${JSON.stringify(path.join(f.base, 'install-calls'))}`,
`refreshed=${JSON.stringify(path.join(f.base, 'lockfile-refreshed'))}`,
`case "$*" in\n *--lockfile-only*) rc=${fallbackRc}; [ "$rc" -eq 0 ] && : > "$refreshed"; exit "$rc" ;;\n *--frozen-lockfile*) rc=${frozenRc}; [ -f "$refreshed" ] && rc=0 ;;\n *) exit 9 ;;\nesac`,
`[ "$rc" -eq 0 ] && mkdir -p node_modules && cp -R ${JSON.stringify(path.join(f.base, 'playwright-stub'))} node_modules/playwright`,
'exit "$rc"',
].join('\n') + '\n', { mode: 0o755 });
const r = f.run();
const calls = fs.existsSync(path.join(f.base, 'install-calls')) ? fs.readFileSync(path.join(f.base, 'install-calls'), 'utf8').trim().split('\n') : [];
return { f, r, calls };
}
test('the frozen production install, then BROWSER_OK', () => {
const { r, calls } = installing(0, 0);
expect(r.status, r.stdout + r.stderr).toBe(0);
expect(calls).toEqual(['install --production --frozen-lockfile']);
expect(lastLine(r.stdout)).toBe('BROWSER_OK node 141.0.7390.37');
});
test('a stale lockfile is refreshed, then installed production-only again', () => {
const { r, calls } = installing(1, 0);
expect(r.status, r.stdout + r.stderr).toBe(0);
expect(calls).toEqual(['install --production --frozen-lockfile', 'install --lockfile-only', 'install --production --frozen-lockfile']);
expect(lastLine(r.stdout)).toBe('BROWSER_OK node 141.0.7390.37');
});
test('a failed install is BROWSER_UNAVAILABLE with the fix line', () => {
const { f, r, calls } = installing(1, 1);
expect(r.status).toBe(1);
expect(calls).toEqual(['install --production --frozen-lockfile', 'install --lockfile-only']);
expect(lastLine(r.stdout)).toBe(`BROWSER_UNAVAILABLE bun install failed under ${f.root}`);
expect(r.stderr).toContain(`fix: cd ${f.root} && bun install --production --frozen-lockfile, then re-run`);
});
});
describe('browse preflight wiring (scripts/resolvers/browse.ts)', () => {
test('every browser skill\'s $B detection runs gstack-browser-ensure from the install root before READY', () => {
for (const host of ['claude', 'codex'] as const) {
const fallback = generateBrowseFallback(ctxFor(host, 'browse'));
expect(fallback).toContain('[ -x "$B" ] && "${B%/browse/*}/bin/gstack-browser-ensure" && echo "READY: $B" || echo "NEEDS_SETUP"');
const setup = generateBrowseSetup(ctxFor(host, 'pair-agent'));
expect(setup).toContain('if [ -x "$B" ] && "${B%/browse/*}/bin/gstack-browser-ensure"; then');
expect(setup).toContain('BROWSER_UNAVAILABLE <reason>');
}
});
test('the suffix strip resolves the install root for every $B shape', () => {
const r = spawnSync('bash', ['-c', 'for B in /home/u/.claude/skills/gstack/browse/dist/browse /r/.agents/skills/gstack/browse/dist/browse.exe /home/browse/.claude/skills/gstack/browse/dist/browse; do echo "${B%/browse/*}"; done'], { encoding: 'utf8', timeout: 10_000 });
expect(r.stdout.trim().split('\n')).toEqual(['/home/u/.claude/skills/gstack', '/r/.agents/skills/gstack', '/home/browse/.claude/skills/gstack']);
});
});