fabro/apps/fabro-web/app/components/terminal-view-helpers.ts
Bryan Helmkamp e18772888e
Model run sandbox lifecycle explicitly (#431)
## Summary

Fixes sandbox state reporting by separating a requested sandbox plan
from an initialized sandbox instance. Runs now project sandbox lifecycle
as `planned`, `initializing`, `ready`, or `failed`, and live sandbox
operations only proceed once a real instance exists.

## Changes

- Introduces `RunSandboxPlan`, `RunSandboxInstance`, and
lifecycle-backed `RunSandbox` domain types, with serde validation that
prevents `ready` sandboxes without an instance.
- Updates store projection behavior so sandbox events transition through
planned, initializing, ready, and failed states while preserving
requested provider/image/snapshot separately from runtime metadata.
- Tightens server sandbox handlers so
details/files/services/terminal/VNC helpers require an initialized
instance and return a clear 404 when the sandbox was never created.
- Updates the OpenAPI contract and regenerated clients so `Run.sandbox`
exposes lifecycle state while `SandboxDetails.sandbox` contains only
initialized instance metadata.
- Updates the web UI to render lifecycle state directly from run
summaries, hide the Sandbox tab for pure planned sandboxes, and disable
sandbox controls until the instance is ready.
- Cleans up duplicated lifecycle display/type logic and duplicate
server-side sandbox instance loading found during review.

| Lifecycle state | Meaning | Live controls |
| --- | --- | --- |
| `planned` | Sandbox was requested but no provider instance exists |
Hidden/disabled |
| `initializing` | Provider setup has started | State view only |
| `ready` | Runtime instance exists | Enabled |
| `failed` | Provider setup failed with error details | State view only
|

## Testing

- `cargo check --workspace`
- `cargo +nightly-2026-04-14 fmt --check --all`
- `git diff --check`
- `cd apps/fabro-web && bun run typecheck`
- `cd apps/fabro-web && bun test app/routes/run-detail.test.ts
app/routes/run-sandbox.test.tsx
app/components/run-summary-panel.test.tsx`
- `cargo nextest run -p fabro-types --test sandbox_model_serde`
- `cargo nextest run -p fabro-store
run_created_projects_planned_sandbox_lifecycle
sandbox_lifecycle_events_update_projected_sandbox_state
run_failed_before_sandbox_events_leaves_sandbox_planned`
- `cargo nextest run -p fabro-server
planned_sandbox_returns_404_from_details_endpoint
planned_sandbox_rejects_live_operations
failed_sandbox_rejects_live_operations
local_sandbox_returns_provider_neutral_details`
- `cargo nextest run -p fabro-api --test run_sandbox_round_trip`
- `cargo nextest run -p fabro-api --test sandbox_details_round_trip`

---

[![Compound
Engineering](https://img.shields.io/badge/Compound_Engineering-6366f1)](https://github.com/EveryInc/compound-engineering-plugin)
🤖 Generated with GPT-5 via [Codex](https://openai.com/codex)
2026-05-27 12:48:56 -04:00

46 lines
1.6 KiB
TypeScript

import type { RunSandbox } from "@qltysh/fabro-api-client";
import { sandboxInstance, sandboxRuntime } from "../lib/run-sandbox-lifecycle";
export const TERMINAL_DOCK_CLEARANCE_CLASS =
"pb-[calc(0.125rem+var(--fabro-interview-dock-clearance,0px))]";
export interface TerminalServerMessage {
type: "ready" | "error" | "closed";
message?: string;
}
export function buildTerminalWebSocketUrl(location: Location, runId: string): string {
const protocol = location.protocol === "https:" ? "wss:" : "ws:";
return `${protocol}//${location.host}/api/v1/runs/${encodeURIComponent(runId)}/terminal`;
}
export function buildFullScreenTerminalUrl(runId: string): string {
return `/runs/${encodeURIComponent(runId)}/terminal`;
}
export function parseTerminalServerMessage(data: string): TerminalServerMessage | null {
try {
const parsed = JSON.parse(data);
if (!parsed || typeof parsed !== "object") return null;
const type = (parsed as { type?: unknown }).type;
if (type !== "ready" && type !== "error" && type !== "closed") return null;
const message = (parsed as { message?: unknown }).message;
return {
type,
message: typeof message === "string" ? message : undefined,
};
} catch {
return null;
}
}
export function terminalAccessCommandLabel(provider: string | null): string | null {
if (provider === "daytona") return "SSH";
if (provider === "docker") return "Exec";
return null;
}
export function sandboxStatusDetail(sandbox: RunSandbox | null | undefined): string | null {
const instance = sandboxInstance(sandbox);
return sandboxRuntime(sandbox)?.id ?? instance?.provider ?? null;
}