feat(workspace): browser-based workspace creation handoff

Merged
SA
3mo ago
+1635-100

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 from altimate.ts deliberately — 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; resolveWorkspaceWebUrl returns null otherwise and the option auto-hides).
  • altimate-code link picker — adds "+ Set up in browser" as the first row under the same condition.
  • Dev escape hatch — ALTIMATE_WORKSPACE_WEB_URL env 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.ts covering 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 with authorizeUrl copyable), 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 /bind links with project_path-based binding (no git remote)
  • ✅ Real backend GET /by-path returns 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.ts with 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 link command.
    • 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.
  • 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.