Skip to content

cli: show rendering tiers, never engine names - #6

Merged
DibbayajyotiRoy merged 1 commit into
mainfrom
fix/no-engine-names
Oct 22, 2026
Merged

DibbayajyotiRoy merged 1 commit into
mainfrom
fix/no-engine-names

Conversation

@DibbayajyotiRoy

Copy link
Copy Markdown
Collaborator

Stacked on #4 (base feat/tui-progress); retargets to main when #4 merges.

Product rule: customers never see the internal engine or browser names. The public tiers are fetch, js and browser, and users do not choose engines.

What the API does

It already maps every public endpoint to a tier (router.Engine.Tier, fail-closed to browser), so the CLI was the one leaking: its help, flags, goldens, spec copy and docs were written before the API moved. /v1/sessions and /v1/browser take fetch|js|browser and still accept the old names silently. /v1/scrape and /v1/batch ignore engine and headless (ENGINE_IGNORED).

Changes

  • sessions create --engine and browser url --engine take and list a tier. The old names (obscura, chromium, camoufox) still work and are sent as typed, with warning: --engine: this value is deprecated; use ... on stderr that does not repeat the name. sessions list --engine takes a tier (the API accepts old names too).
  • scrape / batch submit: --engine and the display flag are hidden from --help but still accepted, since the API ignores them and already warns. The spinner no longer reads an engine pin. --stealth help no longer names its browser.
  • browser url: the display flag is hidden, the CDP hints no longer name client libraries, the default engine is browser.
  • Human output maps any engine name the API sends to its tier (output.Tier: moli/obscura/headless -> js, fetch -> fetch, anything else -> browser, same as the API): logs ENGINE column and logs get, sessions list/get/create/release, usage --group-by engine, scrape --meta. Warnings, hints, errors and info lines rewrite engine names in server prose (output.PublicText, same set as the API's router.PublicText).
  • JSON and --jsonl are untouched: the scrape wrapper's engine, session bodies and the rest stay exactly as the API sent them.
  • openapi.yaml refreshed with make spec, schemas regenerated (go generate ./internal/schema/), embedded skill.md synced from the docs site. README, DESIGN.md (new contract item 10) and CHANGELOG use tier names.

Goldens

Fixtures now carry the API's real tier values, so the regenerated goldens change only for that: browser/* and browser_human/url (engine=chromium -> engine=browser in the token URL), sessions/* and sessions_human/* (chromium -> browser, obscura -> js, one invented warning replaced), usage_human/by_engine_unattributed (row chromium -> Browser rendering), and the schema/* and schema_human/* digests (regenerated schemas).

Tests

internal/cmd/engine_names_test.go: every command's --help, the human output of scrape/sessions/logs/usage against an API that leaks engine names, the live summary line and the error block, the embedded skill, schemas and openapi.yaml never contain the names; JSON output stays verbatim. Unit tests for Tier and PublicText. go vet ./... and go test -race ./... pass.

Left on purpose

headless is still a wire field in the API's spec (a deprecated, ignored scrape field and a /v1/browser option), so it stays in openapi.yaml, the schemas, the synced skill and the hidden flag. The tests allow that one word in those files.

Customers see three tiers (fetch, js, browser), not the engines behind them.
The API already reports tiers on every public endpoint, so the CLI follows.

- sessions create/list and browser url take a tier with --engine. The names
  older CLIs took still work (sent as typed) with a stderr notice that does
  not repeat them.
- scrape/batch submit keep --engine and the display flag hidden: the API
  ignores both (ENGINE_IGNORED). The spinner no longer reads an engine pin.
- Human output maps any engine name the API sends to its tier (logs, sessions,
  usage, --meta) and rewrites engine names in warnings, hints and errors.
  --json and --jsonl stay exactly as sent.
- openapi.yaml, the schemas and the embedded skill are re-synced from the docs
  site (make spec); README, DESIGN.md and CHANGELOG use tier names.
- Tests: help, human output, live summary, errors, the embedded skill and the
  specs never name an engine; goldens updated to the API's tier values.
@DibbayajyotiRoy
DibbayajyotiRoy changed the base branch from feat/tui-progress to main October 22, 2026 09:01
@DibbayajyotiRoy DibbayajyotiRoy self-assigned this Oct 22, 2026
@DibbayajyotiRoy DibbayajyotiRoy added bug Something isn't working documentation Improvements or additions to documentation enhancement New feature or request labels Oct 22, 2026
@DibbayajyotiRoy
DibbayajyotiRoy merged commit 1a91e4d into main Oct 22, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant