From c9766e354098fad612ab752b7021b9f594034e38 Mon Sep 17 00:00:00 2001 From: garrytan Date: Tue, 6 Oct 2026 20:29:44 +0000 Subject: [PATCH] fix(browse): chain with no flow is a usage error before any daemon boots (#3039) Empty piped input, a terminal with no arguments, and a readFileSync(0) error (EAGAIN, EOF) now print the chain usage with the cause and its troubleshooting link and exit 1 before ensureServer(), instead of sending an empty argument to a daemon the CLI booted for it. Tests run the real CLI with no daemon and no browser, plus the stub-daemon flow. Co-authored-by: VaibDeveloper --- browse/src/cli.ts | 38 +++++++++++++++-- browse/test/cli-chain-stdin.test.ts | 66 +++++++++++++++++++++++++---- docs/troubleshooting.md | 14 ++++++ 3 files changed, 106 insertions(+), 12 deletions(-) diff --git a/browse/src/cli.ts b/browse/src/cli.ts index 9a189cff1..7cdcc703e 100644 --- a/browse/src/cli.ts +++ b/browse/src/cli.ts @@ -1652,6 +1652,33 @@ async function handlePairAgent(state: ServerState, args: string[]): Promise string): { ok: true; flow: string } | { ok: false; error: string } { + let cause = 'stdin is a terminal'; + if (!isTTY) { + try { + const flow = readStdin().trim(); + if (flow) return { ok: true, flow }; + cause = 'stdin was empty'; + } catch (err: any) { + cause = `stdin could not be read (${err?.code ?? err?.message ?? String(err)})`; + } + } + return { + ok: false, + error: `[browse] chain: no flow to run (${cause}).\n` + + 'Usage: echo \'[["goto","url"],["text"]]\' | browse chain\n' + + ' or: browse chain \'goto url | click @e5 | snapshot -ic\'\n' + + CHAIN_NO_FLOW_ANCHOR, + }; +} + export function withLoopbackNoProxy(env: Record): string { const entries = (env.NO_PROXY ?? env.no_proxy ?? '').split(',').map(e => e.trim()).filter(Boolean); for (const host of ['127.0.0.1', 'localhost', '::1']) if (!entries.includes(host)) entries.push(host); @@ -2037,10 +2064,15 @@ Refs: After 'snapshot', use @e1, @e2... as selectors: // Special case: chain reads from stdin. Synchronously: on Windows an awaited // Bun.stdin.text() inside this un-awaited main() did not keep the event loop // alive, so a piped flow exited 0 with nothing sent to the daemon (#3039). - // A terminal has no flow to read; the empty argument gets the server's usage. + // No flow (a terminal, empty input, an unreadable stdin) is a usage error + // before ensureServer(): it never boots a daemon. if (command === 'chain' && commandArgs.length === 0) { - const stdin = process.stdin.isTTY ? '' : fs.readFileSync(0, 'utf8'); - commandArgs.push(stdin.trim()); + const flow = readChainFlow(Boolean(process.stdin.isTTY), () => fs.readFileSync(0, 'utf8')); + if (!flow.ok) { + console.error(flow.error); + process.exit(1); + } + commandArgs.push(flow.flow); } // #2219 IRON RULE (pair-agent leg): capture whether a LIVE daemon predates diff --git a/browse/test/cli-chain-stdin.test.ts b/browse/test/cli-chain-stdin.test.ts index e9305ae48..aaa64fd04 100644 --- a/browse/test/cli-chain-stdin.test.ts +++ b/browse/test/cli-chain-stdin.test.ts @@ -3,28 +3,35 @@ * an awaited Bun.stdin.text() inside the CLI's un-awaited main() let the * process exit 0 before reading, so a replayed flow "passed" with nothing * sent to the daemon. The CLI reads stdin synchronously; this drives the real - * CLI against a stub daemon (the Windows free lane runs it natively). + * CLI against a stub daemon (the Windows free lane runs it natively). No flow + * (empty input, a terminal, an unreadable stdin) is a usage error before + * ensureServer(), so it never boots a daemon. */ import { afterEach, beforeEach, describe, expect, test } from 'bun:test'; import * as fs from 'node:fs'; import * as os from 'node:os'; import * as path from 'node:path'; +import { CHAIN_NO_FLOW_ANCHOR, readChainFlow } from '../src/cli'; + const CLI = path.resolve(import.meta.dir, '../src/cli.ts'); describe('#3039: chain reads its flow from piped stdin', () => { let scratch: string; let daemon: ReturnType; let received: Array<{ command: string; args: string[] }>; + let hits: string[]; beforeEach(() => { scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'browse-chain-stdin-')); received = []; + hits = []; daemon = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch: async (req) => { const url = new URL(req.url); + hits.push(url.pathname); if (url.pathname === '/health') return Response.json({ status: 'healthy' }); if (url.pathname === '/command') { const body = await req.json(); @@ -41,16 +48,20 @@ describe('#3039: chain reads its flow from piped stdin', () => { fs.rmSync(scratch, { recursive: true, force: true }); }); - async function runChain(stdin: string) { + async function runChain(stdin: string | 'ignore', opts: { daemon?: boolean } = {}) { const stateFile = path.join(scratch, 'browse.json'); - fs.writeFileSync(stateFile, JSON.stringify({ pid: process.pid, port: daemon.port, token: 'chain-stdin-test', mode: 'launched' })); + if (opts.daemon !== false) { + fs.writeFileSync(stateFile, JSON.stringify({ pid: process.pid, port: daemon.port, token: 'chain-stdin-test', mode: 'launched' })); + } const env: Record = {}; for (const [key, value] of Object.entries(process.env)) { - if (value !== undefined && !/^(BROWSE_|GSTACK_)/.test(key)) env[key] = value; + if (value !== undefined && !/^(BROWSE_|GSTACK_|PLAYWRIGHT_)/.test(key)) env[key] = value; } - Object.assign(env, { HOME: scratch, GSTACK_HOME: path.join(scratch, '.gstack'), BROWSE_STATE_FILE: stateFile }); + // Browser dependencies unavailable: a daemon boot attempt could not succeed. + Object.assign(env, { HOME: scratch, GSTACK_HOME: path.join(scratch, '.gstack'), BROWSE_STATE_FILE: stateFile, + PLAYWRIGHT_BROWSERS_PATH: path.join(scratch, 'no-browsers') }); const cli = Bun.spawn([process.execPath, CLI, 'chain'], { - cwd: scratch, env, stdin: new TextEncoder().encode(stdin), stdout: 'pipe', stderr: 'pipe', + cwd: scratch, env, stdin: stdin === 'ignore' ? 'ignore' : new TextEncoder().encode(stdin), stdout: 'pipe', stderr: 'pipe', }); const timer = setTimeout(() => cli.kill('SIGKILL'), 30_000); const [code, stdout, stderr] = await Promise.all([cli.exited, new Response(cli.stdout).text(), new Response(cli.stderr).text()]); @@ -66,9 +77,46 @@ describe('#3039: chain reads its flow from piped stdin', () => { expect(r.code).toBe(0); }, 45_000); - test('empty stdin is a usage error, never a silent exit 0', async () => { + test('empty stdin is a usage error, never a silent exit 0, and never reaches the daemon', async () => { const r = await runChain(''); - expect(r.code).not.toBe(0); - expect(r.out).toContain('Usage'); + expect(r.code).toBe(1); + expect(r.out).toContain('[browse] chain: no flow to run (stdin was empty).'); + expect(r.out).toContain('Usage: echo'); + expect(r.out).toContain(CHAIN_NO_FLOW_ANCHOR); + expect(hits).toEqual([]); + }, 45_000); + + test('with no daemon, whitespace-only or closed stdin exits 1 without booting one', async () => { + for (const stdin of [' \n\t\n', 'ignore'] as const) { + const r = await runChain(stdin, { daemon: false }); + expect(r.code).toBe(1); + expect(r.out).toContain('[browse] chain: no flow to run (stdin was empty).'); + expect(fs.existsSync(path.join(scratch, 'browse.json'))).toBe(false); + expect(fs.existsSync(path.join(scratch, '.gstack'))).toBe(false); + } }, 45_000); }); + +describe('readChainFlow: no flow is a usage error', () => { + test('a terminal never reads stdin', () => { + let read = false; + const r = readChainFlow(true, () => { read = true; return '[["text"]]'; }); + expect(read).toBe(false); + expect(r).toEqual({ ok: false, error: expect.stringContaining('no flow to run (stdin is a terminal)') }); + }); + + test('a read error (EAGAIN, EOF) is a usage error naming the code', () => { + for (const code of ['EAGAIN', 'EOF']) { + const r = readChainFlow(false, () => { throw Object.assign(new Error(code), { code }); }); + expect(r.ok).toBe(false); + if (!r.ok) { + expect(r.error).toContain(`no flow to run (stdin could not be read (${code}))`); + expect(r.error).toContain('Usage: echo'); + } + } + }); + + test('piped input is trimmed and returned', () => { + expect(readChainFlow(false, () => ' [["text"]]\n')).toEqual({ ok: true, flow: '[["text"]]' }); + }); +}); diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 13217c1af..cc74c25df 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -582,6 +582,20 @@ hooks stay. ## Browser + +### `[browse] chain: no flow to run (stdin was empty)` (or `stdin is a terminal`, `stdin could not be read (EAGAIN)`) + +**Meaning.** `browse chain` with no arguments runs the JSON flow piped to it. +Nothing arrived, so it exits 1 before starting a browser. It used to exit 0 on +Windows having run nothing. + +**Fix.** Pipe the flow, or pass it as an argument: + +```bash +echo '[["goto","https://example.com"],["text"]]' | browse chain +browse chain 'goto https://example.com | text' +``` + ### `Chromium at GSTACK_CHROMIUM_PATH= failed to launch: ...`