[STG-2422] feat(cli): named contexts (local name→ID map)

[shrey150]

What & why

Browserbase contexts are identified only by an opaque ID and the platform has no server-side list endpoint, so reusing a context today means remembering (or copy-pasting) a UUID. This is also the single most-used feature of the popular community Browserbase skill on ClawHub (jamesfincher/browserbase), which keeps a local map of named contexts.

This PR ports that ergonomic into the CLI as a thin, client-side name→ID map — no API change.

• browse cloud contexts create --name github → creates the context and saves a local alias
• browse cloud contexts list → shows your saved names (new command; the API has no list, so this reflects names saved on this device)
• contexts get|update|delete and sessions create --context-id now accept a saved name or a raw ID (a resolver passes unknown refs through unchanged, so raw IDs still work everywhere)
• contexts delete prunes the local alias for the deleted context

The map lives at (XDG_CONFIG_HOME||~/.config)/browserbase/contexts.json (honoring BROWSERBASE_CONFIG_DIR), next to the CLI's existing state via the shared resolveConfigDir() helper. The file is written 0600. It stores only the same IDs the API already returns, and a missing or corrupt file degrades to "no saved contexts" rather than erroring.

Linear: STG-2422

E2E Test Matrix

Run against live Browserbase with the local build (node bin/run.js), BROWSERBASE_CONFIG_DIR pointed at a throwaway dir. Signed URLs redacted.

Command / flow	Observed output	Confidence / sufficiency
contexts create --name e2e-smoke	{"id":"45ed525f-…","uploadUrl":"<redacted>",…,"name":"e2e-smoke"}	Proves a real context is created and the name is echoed back.
cat contexts.json	{"version":1,"contexts":{"e2e-smoke":{"id":"45ed525f-…","createdAt":"2026-06-27T00:40:51Z"}}}	Proves the local name→ID map is persisted with the API-returned ID.
contexts get e2e-smoke (by name)	{"id":"45ed525f-…","projectId":"2d228d57-…",…}	Proves name→ID resolution on get hits the real /v1/contexts/<id>.
contexts list --format table	Name ID Created prod-login d98a30da 2026-06-27 00:41Z	Proves the new list command renders the saved map.
sessions create --context-id prod-login --persist (by name)	session 27f9087a-… returned with contextId == d98a30da-… → MATCHES name→id: True	Key flow: a real session attaches to the right context purely from the name.
contexts delete prod-login (by name)	{"ok":true,"id":"d98a30da-…","removedAliases":["prod-login"]} then contexts list → No saved contexts.	Proves API delete + local alias prune.
contexts delete <raw-uuid>	{"ok":true,"id":"45ed525f-…"} (no removedAliases)	Proves raw IDs still work and orphan cleanup; no alias pruned when none matched.
pnpm test:cli	Test Files 21 passed (21) · Tests 310 passed (310)	Full suite green, incl. new contexts-store unit tests + contexts-named CLI-level e2e (fake server) + updated surface test.
pnpm lint	format + eslint + tsc --noEmit all clean	Types, style, lint.

Notes

• Bump: browse: patch (matches how the CLI bumps; browse is in the changeset ignore list but still gets release-impacting patches by convention).
• No new dependencies. Pure client-side; composes with the existing config-dir convention.

🤖 Generated with Claude Code

---

Summary by cubic

Add named contexts to the CLI so you can reuse a Browserbase context by name instead of copying IDs. Implements Linear STG-2422 with a local name→ID map, typo hints, raw‑ID compatibility, and a new contexts add command; no API changes.

• New Features

  • browse cloud contexts create --name <name> saves a local alias and returns the name; browse cloud contexts add <name> <id> names an existing context (trims the ID, rejects empty; use --force to overwrite).
  • browse cloud contexts list shows saved names on this device (--json returns { "contexts": [...] }).
  • browse cloud contexts get|update|delete and browse cloud sessions create --context-id accept a saved name or a raw ID. Unknown names close to a saved one fail early with a “did you mean?” hint; unknown refs otherwise pass through so non-UUID IDs still work. contexts delete prunes aliases for the deleted ID and includes removedAliases (best effort).

• Notes

  • Aliases live at (XDG_CONFIG_HOME||~/.config)/browserbase/contexts.json (honors BROWSERBASE_CONFIG_DIR), written 0600 via atomic write; missing/corrupt files behave as empty. The map is prototype-safe, rejects UUID-shaped names, and sanitizes malformed entries on read; names must start alphanumeric, allow letters/digits/._-, max 64, and duplicates are blocked unless --force.

^{Written for commit 00fdd03. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 00fdd03

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

6 issues found and verified against the latest diff

Confidence score: 3/5

• In packages/cli/src/commands/cloud/contexts/delete.ts, remote deletion can succeed but local alias cleanup can still throw, so users may see a failure after the context is already gone and retry into confusing states — make local cleanup non-blocking (or clearly report partial success) before merging.
• In packages/cli/src/lib/cloud/contexts-store.ts, alias data from contexts.json is trusted without shape validation, so malformed entries can break name resolution/cleanup instead of degrading gracefully — validate and discard invalid alias entries as "no saved contexts."
• In packages/cli/src/commands/cloud/contexts/create.ts, allowing ID-shaped alias names can shadow real context IDs and break raw-ID workflows — block ID-like names (or add explicit disambiguation) before merge.
• In packages/cli/src/lib/cloud/contexts-store.ts, store writes are last-writer-wins and existing contexts.json files may retain permissive permissions, which can cause lost updates and leave alias data more exposed than intended — add concurrency-safe write/merge handling and enforce chmod 0o600 on existing files, then tighten packages/cli/tests/contexts-store.test.ts to assert mode bits.

<sub>Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[shubh24]

Tested this end-to-end — ✅ good to approve

Built the cloud command subtree from this branch and ran the full lifecycle against live Browserbase (throwaway BROWSERBASE_CONFIG_DIR, both test contexts cleaned up after). Every flow in the PR's matrix reproduced exactly.

Verified hands-on (live API)

Flow	Result
contexts create --name e2e-login	✅ creates context, echoes "name", saves alias
contexts.json on disk	✅ 0600 perms, correct {version, contexts} shape
duplicate --name	✅ blocked with actionable message
contexts get e2e-login (by name)	✅ resolves name→id, hits real /v1/contexts/<id>
contexts list --format table	✅ clean Name / ID / Created table; --json → {contexts:[...]}
sessions create --context-id prod-x --persist (by name)	✅ session contextId == prod-x's id — the key flow
contexts delete prod-x (by name)	✅ removedAliases:["prod-x"]
contexts delete <raw-uuid>	✅ deletes and prunes the alias by id
empty list, invalid names (leading dot / space), corrupt file	✅ all degrade gracefully
contexts-store + contexts-named test files	✅ 10/10 pass

Name validation, the 0600 file mode, corrupt-file → "no saved contexts" fallback, raw-ID passthrough everywhere, and delete-prunes-by-id all behave as described. Nicely scoped, honest, client-side only.

Non-blocking CLI-design suggestions (for a follow-up, not merge blockers)

1. No way to name an existing context. --name only works at create time. If you get an ID from a teammate or another device, there's no contexts add <name> <id> / contexts alias — you'd hand-edit contexts.json. Probably the most valuable fast-follow.
2. Typo'd name → cryptic error. The resolver silently passes unknown refs through as raw IDs (documented tradeoff), so contexts get my-loginn returns 400 Invalid Context ID instead of "no saved context named 'my-loginn'." A "did you mean?" hint on get/update/delete/--context-id when a ref is neither a UUID nor in the store would be friendlier.
3. Local map can drift from server. Deleting a context via the dashboard leaves a stale alias; list still shows it and get <name> then 404s. No prune/reconcile. Minor — list could also label output as "N contexts named on this device" so it isn't mistaken for "all my contexts."
4. Dead field: ContextAlias.projectId is defined but never populated. Wire it up or drop it.

Recommend merging; items 1 & 2 are worth a follow-up.

— tested with Claude Code

[shrey150]

Thanks for the thorough end-to-end pass @shubh24 🙏 Folded in two of your four right away (d8740e3a2):

• fix multi observe resolution, move dom settling to a method, eval passes #2 typo'd name → cryptic error — done. contexts get|update|delete and sessions create --context-id now resolve through a helper that fails with No saved context named "X". Did you mean: <closest>? (levenshtein over saved names) instead of sending a bogus id and getting 400 Invalid Context ID. A context ID (UUID) or a known name still resolves; only unknown names fail. Verified live: get my-loginn → Did you mean: my-login?, no API call.
• slimmed down observe with passing evals #4 dead projectId — dropped the field (it was never populated).

The other two I'd like to take as fast-follows rather than grow this PR:

• Pk/evals #1 name an existing context (contexts add <name> <id>) — agree it's the most valuable next step. It adds a new command to the surface, which Shrey deliberately scoped out of the first cut, so I'd rather land it as its own small PR. Tracking it.
• prettier w/ formatting #3 drift / prune / "named on this device" labeling — reasonable; queuing as a follow-up.

Also added tests for the new resolver (unit: detailed resolution + did-you-mean ranking; CLI e2e: typo'd-name failure makes no API call) and switched the contract-test fixtures from ctx_123 to a UUID so resolution stays hermetic. Full suite 318 green, lint clean.

[cubic-dev-ai]

2 issues found across 10 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[shrey150]

Update on suggestion #1 @shubh24 — decided to fold it in rather than defer. Added browse cloud contexts add <name> <id> in b944a95c1: names a context you already have (a teammate's id, another device, or one created outside the CLI), local-only like list, with --force to repoint an existing name. Validates the name (same rule as create --name) and rejects an empty id.

Verified live: create (bare) → add team-login <id> → get team-login resolves to the real context → dup rejected without --force → delete team-login prunes. Suite now 323 green.

That leaves only #3 (drift/prune/"named on this device" labeling) as a follow-up.

[cubic-dev-ai]

1 issue found across 5 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>