feat: post-scan Workspaces prompt + `altimate-code link` subcommand

Merged
SA
3mo ago
+2722-2

Summary

Adds the CLI half of Workspaces (server-side epic AI-8390): after a project scan completes, the TUI offers to create or link an Altimate workspace. Also adds an on-demand altimate-code link subcommand for the same flow at any time.

  • TUI plugin (packages/opencode/src/plugin/tui/altimate/workspace.tsx) — fork-owned single file, wired through the existing altimateTuiPlugins() aggregator. Renders three dialogs: Create-or-Link-or-Skip, Already-linked (with drift + unverified-cache flags), and a picker over the user's workspaces. Post-scan trigger uses a one-shot session.idle listener so the dialog opens after the LLM's onboarding menu finishes streaming (not while it's still generating).
  • altimate-code link subcommand — picker-first UX (currently-linked row marked, "+ Create new" as the first row, auto-named from the git repo or directory basename). Shares the WorkspaceApi client + state cache + project-identifier detection with the plugin so the two entry points can't drift.
  • Project identity is repo_remote when a git remote is present (stronger — survives directory moves), else the absolute symlink-resolved project_path. Neither is required to be non-null in isolation, but at least one must be present.
  • Local binding cache at ~/.local/share/altimate-code/altimate-workspace-bindings.json, chmod 0o600, scoped to (tenant, apiUrl) so an account switch invalidates the file. Server is always authoritative; the cache is offline fallback with a mandatory "unverified" render flag.
  • Skip latch persists across sessions via TuiPluginApi.kv — 7-day rolling suppression keyed on sha1(repoRemote ?? projectPath). The subcommand deliberately bypasses it (user-initiated).
  • Feature flag Flag.ALTIMATE_WORKSPACE — off by default; existing onboarding behavior is unchanged when unset.

Talks to datamate-project-bindings/* endpoints on altimate-backend (see the paired backend PR).

Test plan

  • bun turbo typecheck — clean
  • bun test test/altimate/plugin/workspace.test.ts — 18/18 (including the new path-only latch case)
  • bun test test/altimate — 4047 pass, 10 pre-existing sample_setup timeout failures unrelated to this change
  • Manual smoke against a real backend for both the post-scan and on-demand paths
  • Manual smoke against a project with no git remote (the reason for the path-based fallback identifier)

Fork markers

All fork-only code is wrapped in altimate_change start / altimate_change end markers or altimate_change - new file, per the ADR at docs/internal/2026-06-23-tui-fork-features-as-plugins-adr.md. Zero edits to packages/tui/**.

🤖 Generated with Claude Code

https://claude.ai/code/session_016H42Vt4pt5dcD7opRqckeM


Summary by cubic

Adds a post-scan Workspaces prompt, a altimate-code link subcommand, and a --workspace <name> launch flag behind Flag.ALTIMATE_WORKSPACE. Previously sessions couldn’t attach to a workspace at launch and projects couldn’t link; now the TUI offers create/link after the scan goes idle, users can link on demand, and launch can pin the session to the workspace linked in this directory without blocking startup.

  • Registers the TUI plugin and link command only when ALTIMATE_WORKSPACE is set (does not inherit OPENCODE_EXPERIMENTAL).

  • Post-scan trigger: listens for session idle via the non-deprecated EventV2 Status stream; installs one serialized listener and tears it down; on install failure clears pending sessions; 7‑day skip latch keyed by remote or path and scoped to tenant+apiUrl; rejects future timestamps.

  • Project identity and re-linking: uses {repoRemote?, projectPath} (symlink‑resolved); pre-check tries remote then path and returns which matched; re-link uses the matched identifier; surfaces drift; supports path‑only projects.

  • API client and cache: 15s timeout across fetch and body reads; distinguishes timeout vs network errors; parses FastAPI detail; rejects empty or null 2xx bodies; accepts /datamates envelopes {datamates: [...]}, [...], or {data: [...]} with guards for non-arrays and null rows; validates manage_url is http(s); local binding cache scoped to tenant+apiUrl with canonicalized directory keys, runtime shape validation, and best‑effort writes (chmod 0600 post‑write).

  • Picker and conflicts: marks the linked workspace and offers “+ Create new”; creating while linked rebinds to the new workspace; submit guard prevents duplicate binds; subcommand fails fast when stdin isn’t a TTY; on pre‑check failure a 409 bind retries as a re‑link using the server’s conflict detail to choose the endpoint; mismatch copy points to altimate-code link.

  • Launch flag (AI‑8504 item 1): altimate-code tui --workspace <name> resolves by exact (case‑insensitive, trimmed) name against this directory’s local binding only; on mismatch it prints a note and attaches to the currently linked workspace; never blocks launch; hands off the resolved id via altimate/workspace/session-context. Builder registers --workspace before --agent.

  • Rollout: opt‑in by setting ALTIMATE_WORKSPACE; requires backend /datamate-project-bindings/* and /datamates/. No migrations; users must be signed in to Altimate or the prompt is skipped.

Summary by CodeRabbit

  • New Features

    • Added workspace linking through the altimate-code link command.
    • Added TUI workspace setup, selection, re-linking, and management actions.
    • Added project-to-workspace binding with secure, account-aware local persistence.
    • Added optional post-scan workspace telemetry.
    • Added seven-day skip preferences for workspace prompts.
    • Workspace features are available only when enabled.
  • Bug Fixes

    • Improved handling of workspace conflicts, access errors, network failures, invalid local state, and credential-protected project remotes.