feat(m3.1): managed browser sessions for the tron CLI by ralyodio · Pull Request #28 · profullstack/tronbrowser.dev

ralyodio · 2026-07-04T09:44:35Z

Implements M3.1 — managed browser sessions from the M3 PRD (#27). Makes TronBrowser programmable through the existing tron CLI — no new binary, no new repo.

Commands

tron browser launch [--headless] [--profile <name|ephemeral>] [--port N] [--force]
tron browser status [--json]
tron browser tabs   [--json]
tron browser use <tab-id>
tron browser current
tron browser close
tron open <url>        # into the managed session; legacy launch if none

Design

The repo's pattern is "shell is the running CLI, TS modules are the typed/tested spec" — this mirrors it:

packages/browser-core/src/automation/ — portable, unit-tested contract: SessionDescriptor schema, CDP DevTools endpoint URL builders, and the target→tab / current-tab mapping. 21 vitest cases.
apps/desktop/launcher/tron-session — the running engine. Drives the session through the DevTools HTTP endpoints (/json/version|list|new|activate|close) using curl + python3 (both already launcher deps) — no WebSocket/dependency needed for M3.1. Writes ~/.tronbrowser/automation/session.json recording pid/port/profile and the browser webSocketDebuggerUrl — the attach point for M3.2 tooling.
apps/desktop/launcher/tronbrowser — additive automation-mode flags (--remote-debugging-port, --headless=new) gated on env. The normal tron <url> launch path is unchanged.
install.sh dispatcher — new browser case; open prefers a running session and falls back to the classic window launch (rc 3 signal) so nothing regresses.
build-release.sh — ships tron-session in the launcher payload (flows into the tarball, deb/rpm, and AppImage automatically).

Launch uses --remote-debugging-port=0 so Chromium picks a free loopback port (read from DevToolsActivePort); the endpoint is 127.0.0.1-only. Headless defaults to an ephemeral profile that's removed on close.

Acceptance criteria (PRD §22)

✅ Existing tron <url> behavior preserved (automation flags are additive/env-gated).
✅ Managed session launches the Chromium-compatible TronBrowser profile.
✅ CLI lists tabs and identifies the current tab.
✅ Headed and headless launches (Linux native/flatpak primary; macOS headed via open).

Verification

TS: typecheck + 21 unit tests green; browser-core lint/build clean.
Shell engine: exercised end-to-end against a mock CDP server (launch→status→tabs→open→use→current→close, already-running guard, headless-ephemeral cleanup, rc-3 fallback). This caught a real curl | python - <<PY stdin-vs-heredoc bug, now fixed.
Dispatcher: extracted from install.sh and validated for browser delegation + open session/legacy routing.
Full desktop + browser-core suites: 48 tests pass. install.sh/tronbrowser/tron-session pass sh -n.

Notes / scope

Requires curl + python3 (already used by the launcher and Tor helper).
Windows managed sessions out of scope for M3.1 (launcher there is tronbrowser.cmd).
See docs/managed-sessions.md.

🤖 Generated with Claude Code

Adds CDP-driven managed automation sessions (PRD M3.1) without a new binary or repo — everything routes through the existing `tron` CLI. New commands (via a `tron-session` engine shipped next to the shim): tron browser launch [--headless] [--profile <name|ephemeral>] tron browser status [--json] / tabs [--json] / use <id> / current / close tron open <url> # opens in the managed session, else legacy launch - packages/browser-core/src/automation: portable, unit-tested contract — SessionDescriptor schema, CDP endpoint URL builders, and the target→tab / current-tab mapping the shell engine mirrors (21 vitest cases). - apps/desktop/launcher/tron-session: the running engine. Drives the session over the DevTools HTTP endpoints (curl + python3, both already CLI deps); writes ~/.tronbrowser/automation/session.json recording the port, pid, profile and webSocketDebuggerUrl (the M3.2 attach point). - apps/desktop/launcher/tronbrowser: additive automation-mode flags (--remote-debugging-port, --headless=new) gated on env; the normal `tron <url>` launch path is unchanged. - install.sh dispatcher: `browser` case + `open` prefers a running session and falls back to the classic launch when none exists. - build-release.sh: ship tron-session in the launcher payload. - docs/managed-sessions.md. Launch uses --remote-debugging-port=0 so Chromium picks a free loopback port (read from DevToolsActivePort); the endpoint is 127.0.0.1-only. Headless defaults to an ephemeral profile removed on close. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

github-actions · 2026-07-04T09:44:51Z

vu1nz Security Review

0 finding(s) in PR #?

No security issues found.

Regression coverage for the running shell implementation (previously only verified ad-hoc). Drives the real `tron-session` CLI against a Node CDP mock via child_process: launch + live descriptor (incl. webSocketDebuggerUrl), tabs/current, open-as-new-tab, use, already-running guard, headless→ephemeral profile cleanup, close, and the rc-3 no-session `open` fallback signal. Skips gracefully when curl/python3 are unavailable. 8 cases, wired into the existing `pnpm -r test` / vitest suite. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@e3

…#29) Adds CDP-driven page automation on the M3.1 managed session (PRD M3.2): tron snapshot [--json] [--include-hidden] tron click @e3 tron fill @E4 "hi@example.com" Runtime pivot: snapshots/actions need programmatic CDP over a WebSocket, which the PRD's TS package layout (browser-core/sdk) already assumes. So these subcommands are implemented in TypeScript/Node and the shell `tron` dispatcher delegates to them, attaching to the session via the descriptor's webSocketDebuggerUrl (the M3.1 attach point). packages/browser-core/src/automation: - cdp-client.ts CDP JSON-RPC over Node's global WebSocket (no dependency). - snapshot-script.ts / action-script.ts in-page scripts. Snapshot tags each element with data-tron-ref so a later `tron click @e3` (a separate process) resolves the ref by attribute selector; a vanished element -> STALE_REF. - page.ts evaluate + StaleRefError + compact text formatting. - page-target.ts pick the session's current page target to drive. packages/browser-core/src/automate-cli.ts + automate-bin.ts: the `tron-automate` Node entry (snapshot/click/fill), deps injectable. Packaging: build-release.sh ships browser-core's self-contained dist tree as `automate/` (with a {"type":"module"} marker); the dispatcher runs it via node. Tests (37 new): CDP client over a real WebSocket, the in-page scripts against a real DOM (happy-dom), orchestration + CLI with fakes, and an end-to-end run of the real fetch + CdpClient transport against a mock DevTools server. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

socket-security · 2026-07-04T11:59:39Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	happy-dom@20.10.6

View full report

socket-security · 2026-07-04T11:59:41Z

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert (click "▶" to expand/collapse)
Warn		Obfuscated code: npm `happy-dom` is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: packages/browser-core/package.json → `npm/happy-dom@20.10.6` ℹ Read more on: This package \| This alert \| What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at `support@socket.dev`. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment `@SocketSecurity ignore npm/happy-dom@20.10.6`. You can also ignore all packages with `@SocketSecurity ignore-all`. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

@attr

Adds one-shot headless automation and structured extraction on the managed session (PRD M3.3), extending the M3.2 Node runtime: tron headless <url> --snapshot|--screenshot <p>|--pdf <p>|--extract <mode> [--json] tron extract <text|links|forms|tables|main|selector> [--field n=sel[@attr]] tron screenshot <path> [--full-page] tron pdf <path> - extract-script.ts: in-page extractors returning deterministic JSON; relative href/src resolve to absolute; password values omitted; hidden inputs skipped. - capture.ts: Page.captureScreenshot / Page.printToPDF -> bytes. - page.ts: goto() (navigate + wait for load) and extract(). - automate-cli.ts: extract/screenshot/pdf commands + a `headless` one-shot that runs in its own isolated temp TRONBROWSER_DATA (never touching an interactive session), launches/closes via the tron-session engine (TRON_SESSION_BIN), and always tears down (profile included), even on failure. - install.sh dispatcher routes the new subcommands to the Node runtime and passes TRON_SESSION_BIN so `tron headless` can manage its one-shot session. Tests (+20): extraction against a real DOM (happy-dom) for links/forms/tables/ custom fields, CLI for extract/screenshot/pdf/headless with injected fakes (incl. cleanup-on-failure), and extract + screenshot over the real HTTP+WS transport. 78 browser-core tests pass; dispatcher routing verified. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

ralyodio mentioned this pull request Jul 4, 2026

feat(m3.2): page snapshots and ref actions #29

Merged

ralyodio marked this pull request as ready for review July 4, 2026 11:59

ralyodio mentioned this pull request Jul 4, 2026

feat(m3.3): headless one-shot, extraction, and capture #30

Merged

ralyodio merged commit c15aa56 into main Jul 4, 2026
7 checks passed

ralyodio deleted the worktree-m3.1-managed-sessions branch July 4, 2026 12:19

ralyodio mentioned this pull request Jul 4, 2026

feat(m3.4): @tronbrowser/sdk and tron run #31

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(m3.1): managed browser sessions for the tron CLI - #28

feat(m3.1): managed browser sessions for the tron CLI#28
ralyodio merged 4 commits into
mainfrom
worktree-m3.1-managed-sessions

ralyodio commented Jul 4, 2026

Uh oh!

github-actions Bot commented Jul 4, 2026

Uh oh!

socket-security Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

socket-security Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

ralyodio commented Jul 4, 2026

Commands

Design

Acceptance criteria (PRD §22)

Verification

Notes / scope

Uh oh!

github-actions Bot commented Jul 4, 2026

vu1nz Security Review

Uh oh!

socket-security Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

socket-security Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

socket-security Bot commented Jul 4, 2026 •

edited

Loading

socket-security Bot commented Jul 4, 2026 •

edited

Loading