Skip to content

docs: document Chrome as a prerequisite#12

Open
samyakLambda wants to merge 7 commits intomainfrom
docs/recommend-npx-and-chrome-note
Open

docs: document Chrome as a prerequisite#12
samyakLambda wants to merge 7 commits intomainfrom
docs/recommend-npx-and-chrome-note

Conversation

@samyakLambda
Copy link
Copy Markdown
Collaborator

@samyakLambda samyakLambda commented Apr 27, 2026 •
edited
Loading

Summary

Adds a "Chrome (required)" section to the README documenting that kane-cli needs Google Chrome at standard system paths, with copy-paste install paths per OS and the KANE_CLI_CHROME_PATH / KANE_CLI_SKIP_BROWSER_DOWNLOAD escape hatches.

Single file change (README.md).

Pairs with

Test plan

  • README rendering on github.com/LambdaTest/kane-cli reads cleanly — Chrome section sits under Install, before "First run".
  • Cross-references to v16#446 and homebrew-kane#3 are accurate.

🤖 Generated with Claude Code

samyakLambda and others added 2 commits April 28, 2026 00:31
@samyakLambda @claude
docs: lead with npx; add Chrome auto-install note
127862d 
Reorders the Install section to recommend `npx @testmuai/kane-cli@latest` for
one-off / CI use, demoting `npm i -g` to "install once, run often". Adds an
"About Chrome" subsection documenting the upcoming auto-managed
Chrome-for-Testing build, the cache location (~/.cache/kane-cli/chrome), and
the two opt-out env vars (KANE_CLI_SKIP_BROWSER_DOWNLOAD, KANE_CLI_CHROME_PATH).

Documentation-only — pairs with a 0.3.0 source-side change that adds the
@puppeteer/browsers postinstall hook. DO NOT MERGE until 0.3.0 is published
to npm, or users following the new instructions will get the old behavior
(no auto-Chrome).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samyakLambda @claude
docs: address review — fix npx example, add cold-start note
cb57942 
- The single-line `npx ... run "..."` example would land first-time
  users on an auth error (no `kane-cli login` yet). Replaced with a
  three-step sequence: verify install -> login -> run.

- Added explicit cold-start note: first invocation downloads Chrome
  (~150 MB, one-time); subsequent invocations reuse the cache. Closes
  the expectation gap where "pulls on demand" reads as instant but
  reality is 30-90s on a fresh machine.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samyakLambda samyakLambda mentioned this pull request Apr 27, 2026
Closed
3 tasks
@samyakLambda
Copy link
Copy Markdown
Collaborator Author

samyakLambda commented Apr 27, 2026

⚠️ Design premise may be wrong — investigation in progress

While verifying this PR end-to-end, found that kane-cli does not appear to consume a local Chrome binary path anywhere:

  1. executable_path returns zero matches anywhere in LambdatestIncPrivate/v16.
  2. BrowserConfig (in browser-agent/src/config.py) has only cdp_endpoint and ws_endpoint — no local-launch field.
  3. RunConfig (in kane-cli/src/runner/types.ts) confirms three modes: 
    cdp_endpoint?: string;  // Optional — omit for --cft mode (Playwright self-manages browser)
ws_endpoint?: string;   // Optional — Playwright wire protocol (LambdaTest wss:// URL)
    • ws_endpoint set → LambdaTest cloud grid (no local browser).
    • cdp_endpoint set → BYO existing Chrome via CDP.
    • --cft mode → Playwright self-manages its own Chromium (lives at ~/Library/Caches/ms-playwright/, not ~/.cache/kane-cli/chrome/).

If accurate, the postinstall in this PR downloads ~150 MB of Chrome to a path nothing reads, and the real local-browser story belongs to Playwright (Python side, in the Nuitka-built v16-runner binary).

Holding this PR (and the sibling kane-cli#12 + homebrew-kane#3) as drafts while I investigate v16-runner/build.py and the --cft codepath to determine the actual fix shape. Will update with findings.

If anyone has prior context on (a) how --cft mode handles its browser today, or (b) what Nuitka does with Playwright's bundled chromium, please drop a note — would save investigation cycles.

@samyakLambda samyakLambda marked this pull request as ready for review April 27, 2026 21:35
@samyakLambda
Copy link
Copy Markdown
Collaborator Author

samyakLambda commented Apr 27, 2026

Update — investigation complete, premise is correct after all

Earlier comment about wrong premise was based on incomplete grep results. kane-cli/src/chrome/manager.ts exists and DOES need a local Chrome binary (it spawns Chrome with --remote-debugging-port and connects via CDP) — gh search returned zero matches for chrome in kane-cli/src/ due to indexing lag. Direct directory listing surfaced it.

Wiring commit just landed on v16#446 (be771fb):

  • kane-cli/src/chrome/manager.ts: findChromeBinary() now checks the postinstall-cached CfT path first, falls through to system search.
  • kane-cli/package.json: adds @puppeteer/browsers so manager.ts can compute the cached path via computeExecutablePath().

This closes the "regression" gate. Auto-Chrome via npx now works end-to-end.

All three PRs marked ready for review.

@samyakLambda @claude
docs: update Chrome section to reflect detect-real-Chrome design
86214c4 
Pivots the README from describing an in-package Chrome-for-Testing
download (~150 MB to ~/.cache/kane-cli/chrome) to the actual behavior
shipping in 0.3.0+: kane-cli requires real Google Chrome stable at the
standard system paths.

- Drops "Cold start downloads Chrome" framing from the npx section.
  Replaces with a brief "requires Node 18+ and Google Chrome" note.
- Renames "About Chrome" -> "Chrome (required)" and rewrites contents
  to describe the per-platform postinstall behavior:
    * Homebrew auto-installs via the google-chrome cask (formula PR #3)
    * macOS npm/npx attempts `brew install --cask google-chrome`
    * Linux/Windows npm/npx prints install instructions
    * KANE_CLI_CHROME_PATH and KANE_CLI_SKIP_BROWSER_DOWNLOAD escape hatches

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samyakLambda
Copy link
Copy Markdown
Collaborator Author

samyakLambda commented Apr 28, 2026

Pivot — detect real Chrome instead of bundling CfT

Per offline discussion, the design changed:

  • ❌ Postinstall downloads Chrome-for-Testing via @puppeteer/browsers to ~/.cache/kane-cli/chrome/
  • ✅ Postinstall detects real Google Chrome stable at the standard system paths and installs it via brew on macOS if missing; prints platform-specific install instructions on Linux/Windows. Never auto-sudoes or pops UAC.

Why: real Chrome at standard paths is what findChromeBinary() already searches, auto-updates from Google, and is reusable by other apps. CfT in a kane-cli-private cache duplicated Chrome on disk and required runner-side wiring to use.

Latest commits in each PR:

  • LambdatestIncPrivate/v16#446 → ada8fb8 — drops @puppeteer/browsers dep, reverts manager.ts wiring, rewrites postinstall as detect-and-install.
  • LambdaTest/kane-cli#12 → 86214c4 — README "About Chrome" rewritten as "Chrome (required)" describing the per-platform behavior.
  • LambdaTest/homebrew-kane#3 → 0543c2c — formula adds depends_on cask: "google-chrome" (brew installs Chrome to /Applications/Google Chrome.app automatically).

The merge-order discipline (homebrew + readme PRs gate on 0.3.0 publish from v16#446) is unchanged.

@samyakLambda @claude
docs: simplify Chrome section — runtime gate, no postinstall
9ef2326 
The postinstall script was dropped in v16#446 in favor of a single
runtime gate in src/orchestration/prepare-chrome.ts. Updates the README
to match: drops postinstall references and describes the runtime check
behavior instead.

- Per-platform postinstall narrative -> single bullet noting
  install-Chrome-yourself + clean per-platform runtime error.
- "Skip the postinstall check" -> "Skip the runtime check" (same env
  var, same effect, accurate wording).
- Removes the brew-attempt-on-macOS line (no longer happens).

Brew users still get fully automatic Chrome via depends_on cask.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samyakLambda
Copy link
Copy Markdown
Collaborator Author

samyakLambda commented Apr 28, 2026

Pivot — runtime gate is the only Chrome detection path

Stripped the postinstall script. The runtime gate in kane-cli/src/orchestration/prepare-chrome.ts (calling new isChromeAvailable() in manager.ts) handles missing-Chrome cleanly across all install paths (npm i -g, npx, brew, curl) — no install-time complexity needed.

What stayed (the actual value):

  • manager.ts: new isChromeAvailable(), chromeMissingErrorMessage(), KANE_CLI_CHROME_PATH support.
  • prepare-chrome.ts: gate calling isChromeAvailable() before launchChrome with KANE_CLI_SKIP_BROWSER_DOWNLOAD opt-out.

What got removed:

  • kane-cli/scripts/install-chrome.cjs — the entire postinstall script.
  • npm-packages/public/kane-cli/package.json — postinstall script entry, scripts/ from files allowlist.
  • .github/workflows/public-release-kane-cli.yml — cp -r kane-cli/scripts ... step.

Net v16#446 delta: 5 files / +276 → 2 files / +125. Brew formula keeps depends_on cask: "google-chrome" (cleanest brew UX). README simplified to describe the runtime gate.

Tip commits:

  • LambdatestIncPrivate/v16#446 → fdb7302
  • LambdaTest/kane-cli#12 → 9ef2326
  • LambdaTest/homebrew-kane#3 → 5b494d5

@samyakLambda samyakLambda changed the title docs: lead Install with npx; document upcoming Chrome auto-install docs: lead Install with npx; document Chrome as a prerequisite Apr 28, 2026
@samyakLambda @claude
Merge main + remove npx section from Install
7baf914 
Brings in the user-guide docs added on main since this branch was
created. Resolves the README.md conflict by keeping both my Chrome
(required) section AND main's "Full install reference" link
(complementary, not exclusive).

Also removes the npx section from Install per discussion — npx adds
no install-path benefit now that the runtime gate (v16#446) handles
missing Chrome cleanly across all install paths. Reverts the npm
heading back to "recommended, requires Node 18+".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samyakLambda samyakLambda changed the title docs: lead Install with npx; document Chrome as a prerequisite docs: document Chrome as a prerequisite Apr 28, 2026
samyakLambda and others added 2 commits April 28, 2026 17:20
@samyakLambda @claude
docs: drop KANE_CLI_CHROME_PATH bullet (no longer supported)
e04d673 
Mirrors the v16#446 change that removed KANE_CLI_CHROME_PATH from
findChromeBinary() and isChromeAvailable(). Users with Chrome at a
non-standard path now need to symlink to a standard location or add
to PATH. KANE_CLI_SKIP_BROWSER_DOWNLOAD remains as the only gate
opt-out.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samyakLambda @claude
Merge main — pull TUI doc fix and v0.2.7 skill update
e8b28a4 
Conflicts in README.md resolved by taking main's version for the
NDJSON example (token_usage block removed) and the field table
(adds the `credits` row, drops slimmer column padding from earlier
formatter run). Both my actual additions (Chrome (required) section)
preserved.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@samyakLambda