feat(workspace): browser-based workspace creation handoff
Summary
Adds a browser-based workspace creation handoff to the CLI: post-scan / altimate-code link opens the Altimate SaaS on <tenant>.ws.myaltimate.com/create-and-link with the current project's context, the user approves in a single modal, and the SaaS delivers the newly-created workspace's id back to a CLI-local loopback listener (same pattern as gateway sign-in). CLI then binds the current project via the existing POST /datamate-project-bindings/bind.
Stacked on the Workspaces draft PR (#1099 / feat/agent-workspaces).
What's added
packages/opencode/src/altimate/workspace/browser-handoff.ts(new) — per-flow loopback listener (own instance, walks 7317..7325 past a live OAuth listener), tenant-mismatch guard, typed failure reasons. Duplicates the loopback pattern fromaltimate.tsdeliberately — shared-helper refactor is a follow-up once both flows have prod experience.OfferDialog(post-scan) — adds "Set up in browser (recommended)" as the default option when the deployment supports it (freemium only for pilot;resolveWorkspaceWebUrlreturnsnullotherwise and the option auto-hides).altimate-code linkpicker — adds "+ Set up in browser" as the first row under the same condition.- Dev escape hatch —
ALTIMATE_WORKSPACE_WEB_URLenv var overrides the deployment map lookup (used for local integration testing; never set in production).
What's unchanged
Every pre-existing option in the post-scan dialog and altimate-code link picker (Create quick workspace here, Link to an existing workspace, Skip for now, existing workspace-picker rows) continues to work exactly as it does today. The browser-handoff option is strictly additive. Rolling back is a single-commit revert with no schema, no cache format, and no backend-contract implications.
A user whose deployment doesn't support the browser flow (localhost, enterprise) sees zero behavior change — the new option auto-hides.
Tests
- 14 new unit tests for
browser-handoff.tscovering URL resolution edge cases (freemium / localhost / enterprise / malformed), pre-flight failures (unavailable / not-configured), end-to-end via dependency-injected browser opener (happy path, tenant mismatch, cancel via?error=cancelled, missing workspace_id, invalid workspace_id, browser-open failure withauthorizeUrlcopyable), and port walk past a squatting listener on 7317. - 32/32 workspace + plugin tests pass — no regressions.
- Typecheck clean.
E2E verified against the live backend
Ran the CLI-side round-trip against a live altimate-backend on localhost:
- ✅ CLI URL construction with all expected params (
client,redirect,state,project_path,project_name,#cli_context) - ✅ Loopback listener binds + receives callback
- ✅ State + tenant validation
- ✅ Real backend
POST /datamates/creates workspace - ✅ Real backend
POST /bindlinks withproject_path-based binding (no git remote) - ✅ Real backend
GET /by-pathreturns the binding after - ✅ Local cache persists to XDG state dir with correct schema
- ✅ 409-conflict handling on repeated runs is the intended behavior
Full SaaS-side E2E (real browser clicking Approve) is a manual smoke once the paired SaaS PR is up.
Paired SaaS PR
AltimateAI/altimate-frontend PR (feat/AI-8510-workspace-browser-handoff) — stacked on Ralph's feature/AI-8496-ws-list-create branch.
Follow-ups (deliberately out of scope)
- Loopback-listener extraction into a shared helper (currently duplicated from
altimate.tswith a TODO comment). - Google-first-time-on-
ws.UX (session gate returns user to default post-auth destination instead of/create-and-link; password login works correctly). - Enterprise workspace-web-host mapping.
- Removing the CLI-direct create path (a discussion for after this ships).
🤖 Generated with Claude Code
https://claude.ai/code/session_016H42Vt4pt5dcD7opRqckeM
Summary by cubic
Adds a browser-based workspace create-and-link flow for CLI and TUI. Previously linking ran only in the CLI; now users approve in the SaaS, the CLI receives a 127.0.0.1 callback, re-verifies credentials, and binds the project. Also adds a persistent “linked” confirmation and a right‑pane sidebar tile.
-
Loopback handoff (new packages/opencode/src/altimate/workspace/browser-handoff.ts): ports 7317–7325 with Host header guard; CSRF state; tenant DNS‑label guard; strictly decimal and Number.isSafeInteger workspace_id; fragment‑only project_remote/project_path; 15‑min unref’d timeout; AbortSignal support with silent return when a newer handoff supersedes an older one; post‑listen error handler; force close of open sockets; typed failures (incl. browser_open_failed with copyable URL); success/cancel via top‑level navigation; returns a credential fingerprint for bind‑time re‑verify.
-
CLI (packages/opencode/src/cli/cmd/link.ts): offers “+ Set up in browser” only when available, unlinked, and pre‑check passes; on success binds, writes a canonical cache key (identifier.projectPath ?? directory), prints the manage URL; maps typed failures; re‑verifies credentials before binding.
-
TUI (packages/opencode/src/plugin/tui/altimate/workspace.tsx): adds “Set up in browser (recommended)” when available; guards credential errors; aborts stale handoffs via a module‑level AbortController and silently ignores superseded results; re‑verifies credentials before bind; replaces success toasts with a persistent linked dialog that can open a safe http(s) manage URL.
-
Sidebar (packages/opencode/src/plugin/tui/altimate/workspace-sidebar.tsx, registered in packages/opencode/src/plugin/tui/altimate/index.ts): read‑only tile shows current workspace and manage URL, marks “(pinned via --workspace)” when applicable, polls every 30s with memoized manage base; gated by the same flag.
-
Local cache (packages/opencode/src/altimate/workspace/state.ts): canonicalizes directory keys via realpathSync on read/write with a one‑shot migration; wraps migration writes in try/catch; best‑effort writes.
-
Availability: resolveWorkspaceWebUrl maps freemium only (api.myaltimate.com → .ws.myaltimate.com), validates tenants, and honors ALTIMATE_WORKSPACE_WEB_URL for dev.
-
Tests (packages/opencode/test/altimate/workspace/browser-handoff.test.ts): cover URL resolution, preflight errors, tenant mismatch, cancel, CSRF state‑mismatch where the legitimate callback wins, fragment handling, port walk, browser‑open failure; isolate ALTIMATE_WORKSPACE_WEB_URL.
-
Rollout
- Behind Flag.ALTIMATE_WORKSPACE (TUI plugin, sidebar, post‑scan offer, CLI menu).
- Freemium only; enterprise/local/custom domains hide the browser option.
- No backend migrations; local cache migration is transparent. Existing CLI link flows remain unchanged.
Summary by CodeRabbit
- New Features
- Added workspace linking and management through the
linkcommand. - Added browser-based workspace setup, direct creation, and existing workspace selection.
- Added workspace status and management details to the TUI sidebar.
- Added optional workspace tools controlled by a feature flag.
- Added local binding persistence for faster workspace access.
- Added workspace linking and management through the
- Bug Fixes
- Added validation for credentials, tenants, callbacks, permissions, and unsafe URLs.
- Added handling for offline use, cancellations, timeouts, and setup failures.
- Tests
- Added coverage for browser handoff, callback validation, URL handling, and fallback behavior.