feat(studio): Karrio Studio — standalone TanStack Start foundation (decoupled), PRD & tests

.github/workflows/studio-e2e.yml

@@ -0,0 +1,94 @@
+name: studio-e2e
+
+# Run on every push and on PRs touching Studio source or its E2E specs.
+# The mocked `studio` Playwright project does NOT require a Django backend or
+# Postgres — it intercepts all API calls at the Playwright route level.
+on:
+  push:
+    paths:
+      - "apps/studio/**"
+      - "packages/e2e/tests/studio/**"
+      - "packages/e2e/helpers/studio.ts"
+      - "packages/e2e/playwright.config.ts"
+      - ".github/workflows/studio-e2e.yml"
+  pull_request:
+    paths:
+      - "apps/studio/**"
+      - "packages/e2e/tests/studio/**"
+      - "packages/e2e/helpers/studio.ts"
+      - "packages/e2e/playwright.config.ts"
+      - ".github/workflows/studio-e2e.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  studio-e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: "npm"
+          cache-dependency-path: apps/studio/package-lock.json
+
+      # Install Studio app dependencies (standalone lockfile, no turborepo).
+      - name: Install Studio deps
+        working-directory: apps/studio
+        run: npm ci
+
+      # Build the Studio app so the dev server can serve the compiled output.
+      # `vite build` produces apps/studio/dist (client) + .output/server (SSR).
+      - name: Build Studio
+        working-directory: apps/studio
+        run: npm run build
+
+      # Install Playwright + Chromium only (mocked suite only needs one browser).
+      - name: Install Playwright browsers
+        working-directory: packages/e2e
+        run: |
+          npm ci
+          npx playwright install chromium --with-deps
+
+      # Start the Studio dev server in the background and wait for it.
+      # We use `npm run dev` (vite dev) instead of the built server so hot-reload
+      # is available; the mocked suite doesn't care which mode the server is in.
+      - name: Start Studio dev server
+        working-directory: apps/studio
+        run: npm run dev &
+        env:
+          PORT: 3003
+
+      - name: Wait for Studio to be ready
+        run: |
+          for i in $(seq 1 30); do
+            curl -sf http://localhost:3003 && break || true
+            echo "Waiting for Studio ($i/30)..."
+            sleep 2
+          done
+          curl -sf http://localhost:3003 || (echo "Studio never became ready" && exit 1)
+
+      # Run the mocked `studio` Playwright project.
+      # No KARRIO_LIVE or Django API needed — all API calls are intercepted.
+      - name: Run Studio E2E (mocked)
+        working-directory: packages/e2e
+        run: npx playwright test --project=studio --reporter=github,html
+        env:
+          KARRIO_STUDIO_URL: http://localhost:3003
+          CI: "true"
+
+      # Upload the HTML report so failures are inspectable via the Actions UI.
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: studio-playwright-report
+          path: packages/e2e/playwright-report/
+          retention-days: 14

.gitignore

@@ -157,3 +157,6 @@ htmlcov/
 # Temporary files
 *.tmp
 *.backup
+
+# Claude Code harness-managed temporary agent worktrees
+.claude/worktrees/

apps/studio/.env.sample

@@ -0,0 +1,13 @@
+# Karrio backend (GraphQL + REST) — the single source of truth for ALL state.
+# Shipping data AND Studio-native state (customization, agents, MCP config) are
+# persisted on the Karrio backend (passthrough). No separate Studio database.
+# Server-side base URL
+KARRIO_API=http://localhost:5002
+# Client-side base URL (Vite exposes only VITE_-prefixed vars to the browser)
+VITE_KARRIO_API=http://localhost:5002
+
+# Studio server session (httpOnly cookie signing)
+STUDIO_SESSION_SECRET=change-me-in-production
+
+# Optional: AI Assistant / agents (Claude API)
+ANTHROPIC_API_KEY=

apps/studio/.gitignore

@@ -0,0 +1,16 @@
+node_modules
+.output
+.nitro
+.tanstack
+dist
+.env
+.env.local
+# Generated by the TanStack Start / Router plugin
+src/routeTree.gen.ts
+
+# The repo-root .gitignore has `lib/` and `build/` (build output) rules that
+# would swallow our source dirs of the same name; re-include them.
+!src/lib/
+!src/lib/**
+!src/screens/build/
+!src/screens/build/**

apps/studio/.npmrc

@@ -0,0 +1 @@
+ignore-scripts=false

apps/studio/ARCHITECTURE.md

@@ -0,0 +1,191 @@
+# Karrio Studio — Architecture
+
+Studio is a **standalone full‑stack TanStack Start app** (`apps/studio/`) that
+replaces the legacy Next.js dashboard. It is intentionally **decoupled** from the
+monorepo: its own `package.json`/lockfile, its own data layer, shadcn + Tailwind
+(no `@karrio/ui`), and its own auth (no `@karrio/hooks`/NextAuth). It talks to a
+running Karrio server purely as a **client** — there is **no Studio database**;
+Karrio is the single source of truth (passthrough).
+
+```
+            ┌──────────────────────────────────────────────────────────┐
+            │                     apps/studio (SSR)                      │
+            │                                                            │
+  Browser ──┤  TanStack Router (file routes)                            │
+            │     __root → _app (guard) → _app.$screen (lazy registry)  │
+            │                                                            │
+            │  React screens ──useQuery──►  data hooks (lib/karrio)      │
+            │                                   │                        │
+            │  Server Functions (BFF)           │ KarrioCtx              │
+            │   auth.* / assistant.*            ▼                        │
+            │        │                   client.ts (REST + GraphQL)      │
+            └────────┼───────────────────────────┼───────────────────────┘
+                     │ (server‑to‑server)         │ (browser fetch, Bearer)
+                     ▼                            ▼
+          Anthropic API                    Karrio server  (REST /v1/*, /graphql,
+          (Claude, optional)                /api/token[/refresh])
+```
+
+## 1. Module map
+
+```
+apps/studio/src/
+├── routes/                      # TanStack Router file routes
+│   ├── __root.tsx               # Providers (QueryClient, Session), <html> shell
+│   ├── index.tsx                # "/" → redirect to /home or /login
+│   ├── login.tsx signup.tsx forgot.tsx   # public auth pages
+│   ├── _app.tsx                 # authenticated layout + beforeLoad guard
+│   └── _app.$screen.tsx         # dynamic screen dispatcher (one route, N screens)
+├── server/                      # Server Functions = Studio's BFF "API"
+│   ├── auth.ts                  # login/refresh/logout/register/reset/getSession
+│   └── assistant.ts             # sendAssistantMessage → Anthropic (server-side)
+├── lib/karrio/                  # Decoupled data layer (no @karrio/*)
+│   ├── env.ts                   # base URL resolution (KARRIO_API / VITE_KARRIO_API)
+│   ├── client.ts                # restGet/restMutate/graphql + authedFetch (401→refresh)
+│   ├── session.tsx              # SessionProvider → KarrioCtx, refresh handler
+│   ├── hooks.ts                 # 19 REST + 6 GraphQL TanStack Query hooks + mutations
+│   ├── types.ts                 # local API types (no @karrio/types)
+│   ├── display.ts               # entity → display-string helpers
+│   ├── agents.ts                # AgentDef + McpServerConfig store (metafields + LS cache)
+│   ├── preferences.ts           # UI prefs (metafields + LS cache)
+│   └── metastore.ts             # per-user backend KV over Karrio metafields
+├── lib/{modes,studio-state}.ts  # nav model (Ship/Build/Govern) + UI state
+├── screens/                     # registry.tsx (React.lazy) → ship/* build/* govern/*
+└── components/                  # shell (Sidebar/Topbar), ui (primitives/Sheet/...),
+                                 #   overlays (CommandPalette/Workbench/TweaksPanel)
+```
+
+## 2. Request / data flow
+
+Reads use TanStack Query hooks; writes use mutation hooks that invalidate the
+relevant query keys. Every call carries auth + tenant context derived from the
+session.
+
+```
+Screen (useShipments)                  lib/karrio/hooks.ts
+   │ useQuery(["shipments", …])  ───►   queryFn: restGet(ctx, "/v1/shipments")
+   │                                         │
+   │                                    client.ts authedFetch(ctx, url)
+   │                                         │  headers: Authorization: Bearer <access>
+   │                                         │           x-org-id, x-test-mode
+   │                                         ▼
+   │                                    Karrio  GET /v1/shipments  ──► 200 JSON
+   │                                         │
+   │   on 401 ──► refreshHandler() ──► refreshSession() (server fn) ──► new access
+   │             (de-duped, single retry with the rotated token)
+   ▼
+ render
+```
+
+`KarrioCtx = { baseUrl, token, orgId, testMode }` is assembled once by
+`SessionProvider` and read by every hook via `useKarrioCtx()`. The token comes
+from the httpOnly session cookie (never exposed to JS except as the in-memory
+bearer surfaced through the session query).
+
+**REST vs GraphQL split** (mirrors the Karrio API surface):
+
+| Transport | Used for |
+|---|---|
+| **REST `/v1/*`** | shipments, trackers, connections, pickups, documents, manifests, batches, apps, plugins, webhooks, api_keys, admin, mcp, usage (19 hooks) |
+| **GraphQL `/graphql`** | orders, address/parcel/product templates, rate_sheets, shipping_rules, workflows (6 hooks) + mutations (create/update/delete address/parcel/product, update_user, register_user, request_password_reset) |
+
+## 3. Auth & session flow
+
+Studio runs a thin **Backend‑for‑Frontend**: server functions proxy Karrio's JWT
+endpoints and keep tokens in a single httpOnly cookie so SSR can authenticate and
+the browser never stores raw tokens.
+
+```
+Login page ──login({email,password})──►  server/auth.ts
+                                          POST {KARRIO_API}/api/token
+                                          ◄─ { access, refresh }
+                                          Set httpOnly cookie "karrio-studio-session"
+SSR / hydrate ──getSession()──► reads cookie → { access, email } → SessionProvider
+
+401 on any API call:
+  client.authedFetch ── refreshHandler ──► refreshSession() (server fn)
+                                           POST /api/token/refresh { refresh }
+                                           ◄─ { access, refresh }  (rotates)
+                                           updates cookie + cached session
+                        ◄── new access ──  retry original request once
+```
+
+Route protection: `_app.tsx`'s `beforeLoad` redirects unauthenticated requests to
+`/login`; the public auth routes opt out of the session storage state.
+
+## 4. Karrio integration points
+
+| Concern | Endpoint(s) | Notes |
+|---|---|---|
+| Auth | `POST /api/token`, `POST /api/token/refresh`, `POST /api/logout` | simplejwt; tokens in httpOnly cookie |
+| Operational data | `GET/POST/PATCH/DELETE /v1/*` | REST resources |
+| Relational/template data | `POST /graphql` | connections-style queries + typed mutations |
+| Tenancy | headers `x-org-id`, `x-test-mode` | passed from `KarrioCtx` on every call |
+| Studio-native state | `metafields` (create/update/delete_metafield + filter by key) | per-user JSON under `studio.*` (prefs, agents, MCP configs) — round-trips |
+| Registration / reset | `register_user`, `request_password_reset` GraphQL | |
+
+No schema/migrations are added to Karrio. The one backend file touched on this
+branch is `modules/documents/.../generator.py` — an offline‑CSS guard for the
+local sandbox, unrelated to Studio's runtime.
+
+## 5. Custom Studio "APIs" (server functions)
+
+These are the **net‑new endpoints Studio adds** — TanStack Start server functions
+(typed RPC), not REST routes. They form the BFF layer:
+
+| Server function | Method | Purpose |
+|---|---|---|
+| `login` | POST | exchange credentials at `/api/token`, set httpOnly session |
+| `refreshSession` | POST | rotate access via `/api/token/refresh`, update cookie |
+| `logout` | POST | clear the session cookie |
+| `register` | POST | `register_user` GraphQL mutation |
+| `requestPasswordReset` | POST | `request_password_reset` GraphQL mutation |
+| `getSession` | GET | read the session cookie for SSR + client |
+| `sendAssistantMessage` | POST | proxy to the Anthropic Messages API (Claude) server‑side, keeping `ANTHROPIC_API_KEY` off the client; returns a deterministic stub when unset |
+
+## 6. Net‑new Studio capabilities (beyond dashboard parity)
+
+- **Command palette (⌘K)**, **Workbench** dev overlay, **Tweaks** appearance panel.
+- **Self‑editable appearance** — `preferences.ts` is the single source of truth for
+  theme/accent/density/font/layout. Persisted **per‑user to the Karrio backend** as a
+  JSON **metafield** (`studio.customization`) via `metastore.ts`, with `localStorage`
+  as the offline cache. `loadFromBackend()` hydrates on login, so settings follow the
+  user across devices (full create/read/update/delete round trip — no backend change).
+- **Agents & MCP management** — `agents.ts` is a typed store for `AgentDef` and
+  `McpServerConfig`, persisted as metafields (`studio.agents` / `studio.mcp-servers`)
+  with a `localStorage` write‑through cache. MCP entries show an honest **"config‑only"**
+  status — OSS has no execution proxy, so no connection state is fabricated.
+- **Agent IDE / Assistant** — the Editor screen pairs a Claude chat (via
+  `sendAssistantMessage`) with a client‑side connector **scaffolder**.
+
+## 7. What is NOT built (honest scope / roadmap)
+
+Studio is a **frontend + thin BFF**. The following require Karrio **backend** work
+that this branch does **not** include:
+
+- **On‑the‑fly plugin editing with hot reload.** The Editor's `scaffold()` generates
+  connector files **in the browser** from an SDK‑extension template (mappers /
+  providers / schemas / tests) for display and AI‑assisted editing. It does **not**
+  write to the server's plugins directory, and nothing reloads carrier modules at
+  runtime. A real version needs: (a) an API to persist/edit connector files under
+  the Karrio plugins path, and (b) a runtime plugin loader/reloader (Karrio imports
+  connectors as Python packages at boot; hot‑reloading them is non‑trivial). Tracked
+  as roadmap.
+- **MCP tool execution** — config management only; no backend exec proxy.
+- **Deeper write‑wizards** — rate‑buy, recurring pickups, rule builder,
+  create‑manifest/run‑batch, markup editor, fulfillment/role actions, billing.
+  See `PARITY.md` (all marked 🟡).
+
+## 8. Testing & CI
+
+- `packages/e2e/tests/studio/*` — ~200 mocked Playwright specs (route‑level API
+  mocking, inline session cookie) + a live‑gated smoke project.
+- `render-smoke.spec.ts` — loads every route and fails on any runtime `pageerror`
+  (catches "build‑green‑but‑broken" crashes that `tsc`/build miss).
+- `visual.spec.ts` — screenshot baselines, gated behind `KARRIO_VISUAL=1`.
+- `.github/workflows/studio-e2e.yml` — builds Studio, starts the dev server, runs
+  the mocked project (no Django/Postgres needed).
+- Sandbox: `bin/studio-sandbox` + `apps/studio/sandbox/seed.py` provision
+  high‑fidelity data (shipments with addresses/parcels/charges, trackers,
+  orders) with a seed self‑check.
+```