feat(cli): add --no-browser-deps to skip browser OS dependency install

[Chase J (chajac)]

Note

PR body AI drafted & edited as needed

Overview of Changes

On Linux the CLI unconditionally runs playwright install --with-deps <browser> before web flows. The --with-deps step shells out to apt-get, which requires root even when every system library is already installed (apt needs its lock). On non-root machines without sudo, Playwright falls back to su root -c "apt-get …", which either aborts (playwright install chromium failed: Password:) or hangs indefinitely waiting for a password — there is no timeout. This makes flows run unusable on non-root CI runners regardless of how well-provisioned the image is.

• --no-browser-deps (on flows run, install, and install browsers): drops --with-deps from the Playwright invocation, so only the browsers themselves are installed — no apt, no root. Commander's negated-boolean handling keeps the default (browserDeps: true) unchanged for everyone else. Intended for environments where system libraries are preinstalled (e.g. images baked with playwright install-deps); if they aren't, the failure moves to browser launch, where Playwright names the exact missing packages.
• Parent/child flag resolution (browserDepsFlag.ts): both install and install browsers register the flag, and in Commander's default parsing mode the parent consumes it even when written after the subcommand name — leaving the subcommand's opts at the default. mergedBrowserDeps ANDs both scopes (exact, since the flag is negation-only). Found via runtime verification; covered by a regression test reproducing the topology.

Testing

bun run test
bun run typecheck
bun run lint
bun run format:check
bun run knip

• New tests: buildArgs omits --with-deps on Linux when browserDeps is false; flag registered with default true on all three commands; mergedBrowserDeps parent-consumption regression.
• A/B verified against the built CLI in an ubuntu:24.04 container as a non-root user with no sudo (real playwright@1.58.2 + @qawolf/flows@0.1.4, real browser download):

Scenario	Pre-fix / no flag	With --no-browser-deps
flows run, bare Ubuntu 24.04, non-root, no sudo	❌ wedges at su root -c apt-get…, then playwright install chromium failed: Password:	✅ chromium installed, flow ran, exit 0, no su spawned
Same box after every system library was installed (as root, image-build style)	❌ still fails — apt needs root even with nothing to install	✅ install step no-ops
Flow that launches real Chromium, navigates, asserts title/text (libs baked into image)	—	✅ passes as non-root
Arg matrix via arg-logging playwright stub (install browsers, install, flows run × flag)	default keeps install --with-deps chromium	flag yields install chromium on all three commands
Probes	—	typo --no-browser-dep → (Did you mean --no-browser-deps?); flag twice → idempotent

Checklist

• Changes follow the code style of this project
• Self-review completed
• Tests added/updated
• No breaking changes

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0127ac25-be42-4a34-8a81-e7f611845a5a

📥 Commits

Reviewing files that changed from the base of the PR and between 65779e5 and 7dcf05a.

⛔ Files ignored due to path filters (1)

• src/commands/__snapshots__/help.test.ts.snap is excluded by !**/*.snap

📒 Files selected for processing (18)

• .changeset/no-browser-deps-flag.md
• src/commands/flows/buildFlowsRunDeps.ts
• src/commands/flows/hybridRun.test.ts
• src/commands/flows/run.register.ts
• src/commands/flows/runDefaults.handle.test.ts
• src/commands/flows/runDefaults.reporterWiring.test.ts
• src/commands/flows/runStagedFlows.test.ts
• src/commands/install/all.ts
• src/commands/install/browserDepsFlag.test.ts
• src/commands/install/browserDepsFlag.ts
• src/commands/install/browsers.fixtures.ts
• src/commands/install/browsers.test.ts
• src/commands/install/browsers.ts
• src/commands/install/index.ts
• src/commands/program.test.ts
• src/domains/install/browsers.ts
• src/domains/runner/run.fixtures.ts
• src/domains/runner/runInternals.ts

---

Walkthrough

Adds --no-browser-deps to flows run, install, and install browsers. The option propagates through command handlers to Playwright browser installation, where Linux uses --with-deps only when enabled. Nested Commander parsing merges parent and subcommand values, with tests covering registration, propagation, and argument construction.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant CommandHandler
  participant installBrowsers
  participant installBrowserList
  participant Playwright
  CLI->>CommandHandler: Parse --no-browser-deps
  CommandHandler->>installBrowsers: Pass browserDeps
  installBrowsers->>installBrowserList: Forward browserDeps
  installBrowserList->>Playwright: Run install with or without --with-deps

Loading

Suggested reviewers: smonn, michael-pr

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows Conventional Commits, uses an allowed type/scope, is imperative, and clearly describes the browser-deps flag change.
Description check	✅ Passed	The description includes the required Overview, Testing, and Checklist sections and is detailed enough despite omitting the optional issue link.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chajac/with-deps-nonroot-fail

Warning

Billing warning: we have not been able to collect payment for this subscription for more than 72 hours. Please update the payment method or pay any pending invoices in Billing to avoid service interruption.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/commands/install/browserDepsFlag.test.ts`:
- Around line 49-51: Add a Commander integration test alongside the direct
mergedBrowserDeps tests that calls parseAsync with ["--no-browser-deps",
"browsers"] and asserts the browsers command action receives false. Keep the
existing helper-level test unchanged and configure the command hierarchy so the
flag is parsed on the parent before the subcommand.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: eeee8246-c0c7-4d4d-813c-74aa6ce31453

📥 Commits

Reviewing files that changed from the base of the PR and between 60f761a and 582154e.

⛔ Files ignored due to path filters (1)

• src/commands/__snapshots__/help.test.ts.snap is excluded by !**/*.snap

📒 Files selected for processing (18)

• .changeset/no-browser-deps-flag.md
• src/commands/flows/buildFlowsRunDeps.ts
• src/commands/flows/hybridRun.test.ts
• src/commands/flows/run.register.ts
• src/commands/flows/runDefaults.handle.test.ts
• src/commands/flows/runDefaults.reporterWiring.test.ts
• src/commands/flows/runStagedFlows.test.ts
• src/commands/install/all.ts
• src/commands/install/browserDepsFlag.test.ts
• src/commands/install/browserDepsFlag.ts
• src/commands/install/browsers.fixtures.ts
• src/commands/install/browsers.test.ts
• src/commands/install/browsers.ts
• src/commands/install/index.ts
• src/commands/program.test.ts
• src/domains/install/browsers.ts
• src/domains/runner/run.fixtures.ts
• src/domains/runner/runInternals.ts