feat(dashboard): W9-B2 stack-create form (#59)

- New StackCreatePage (/app/stacks/new) wizard for human-driven stack
  creation. POST /stacks/new is multipart-only (agents can't tar source
  either), so this is the one place the dashboard drives a write itself.
- createStack(file, opts) + fetchStackStatus(slug) client helpers.
- '+ Create stack' link on DeploymentsPage.
- Comprehensive unit tests for createStack tier-wall / size limit /
  multipart handling.

Author: mastermanas805

src/App.tsx

@@ -91,6 +91,15 @@ const DeployDetailPage = lazy(() =>
 // StacksPage retired 2026-05-12 — duplicate of DeploymentsPage. UI says
 // "Deployments" (user language); the API stays /api/v1/stacks (existing
 // data model). One page, one route.
+//
+// StackCreatePage (W9) — human-driven /stacks/new wizard. Lives behind
+// /app/stacks/new because POST /stacks/new is a multipart-only endpoint
+// that's hostile to curl-shy customers. This is the one place the
+// dashboard intentionally drives a write itself (vs. the agent-driven
+// PromptCard pattern) because agents can't tar up source either.
+const StackCreatePage = lazy(() =>
+  import('./pages/StackCreatePage').then((m) => ({ default: m.StackCreatePage })),
+)
 const VaultPage = lazy(() =>
   import('./pages/VaultPage').then((m) => ({ default: m.VaultPage })),
 )
@@ -222,6 +231,12 @@ export function AppRoutes() {
           <Route path="resources/:id" element={<ResourceDetailPage />} />
           <Route path="deployments" element={<DeploymentsPage />} />
           <Route path="deployments/:id" element={<DeployDetailPage />} />
+          {/* W9: /app/stacks/new is the human-driven "Create stack"
+              wizard. We deliberately keep the path under /stacks/ (not
+              /deployments/) because the underlying api endpoint is
+              POST /stacks/new — preserving the user→api vocabulary
+              parity helps when someone hits the "open in curl" path. */}
+          <Route path="stacks/new" element={<StackCreatePage />} />
           <Route path="vault" element={<VaultPage />} />
           <Route path="team" element={<TeamPage />} />
           <Route path="billing" element={<BillingPage />} />

src/api/index.test.ts

@@ -34,6 +34,8 @@ import {
   updateDeploymentAccess,
   reportExperimentConverted,
   validatePromotion,
+  createStack,
+  fetchStackStatus,
 } from './index'
 // §10.21: FIXTURE_BILLING / FIXTURE_INVOICES imports retired. The 503
 // fallback paths in fetchBilling() and listInvoices() were removed —
@@ -1390,3 +1392,166 @@ describe('Admin URL prefix wiring', () => {
     expect(url).not.toContain('/api/v1/admin/customers')
   })
 })
+
+// ─── createStack() — POST /stacks/new multipart upload ───────────────────
+// W9: the human-driven "Create stack" form. The api endpoint is multipart-
+// only; this helper builds the FormData body. We lock the field names
+// because the api parser is strict about them.
+describe('createStack()', () => {
+  function fakeFile(name: string, size: number): File {
+    const f = new File([new ArrayBuffer(size)], name, { type: 'application/gzip' })
+    return f
+  }
+
+  it('POSTs to /stacks/new with a multipart body containing the tarball', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({
+      ok: true, slug: 'sunny-cat-9', status: 'building', url: null, name: 'sunny-cat-9', env: 'development',
+    }))
+    const f = fakeFile('app.tar.gz', 2048)
+    const r = await createStack(f, {
+      name: 'my-app',
+      port: 3000,
+      env: 'staging',
+      env_vars: { API_KEY: 'secret' },
+    })
+    expect(r.ok).toBe(true)
+    expect(r.stack.slug).toBe('sunny-cat-9')
+    expect(r.stack.status).toBe('building')
+
+    const [url, init] = m.mock.calls[0]
+    expect(String(url)).toContain('/stacks/new')
+    expect(init?.method).toBe('POST')
+    // Body is a FormData instance; assert the fields we appended.
+    const body = init!.body as FormData
+    expect(body).toBeInstanceOf(FormData)
+    expect(body.get('name')).toBe('my-app')
+    expect(body.get('port')).toBe('3000')
+    expect(body.get('env')).toBe('staging')
+    expect(body.get('env_vars')).toBe(JSON.stringify({ API_KEY: 'secret' }))
+    expect(body.get('tarball')).toBe(f)
+    // CRITICAL — Content-Type must NOT be set on the request headers; the
+    // browser generates a multipart boundary automatically. Set it
+    // ourselves and the api parser bails.
+    const headers = init?.headers as Headers
+    expect(headers.has('Content-Type')).toBe(false)
+  })
+
+  it('defaults env to "development" when caller omits it (matches platform memory 2026-05-13)', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({
+      ok: true, slug: 's', status: 'building', url: null,
+    }))
+    await createStack(fakeFile('a.tar.gz', 100), {})
+    const body = m.mock.calls[0][1]!.body as FormData
+    expect(body.get('env')).toBe('development')
+  })
+
+  it('omits name + port + env_vars from the body when not provided', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({
+      ok: true, slug: 's', status: 'building', url: null,
+    }))
+    await createStack(fakeFile('a.tar.gz', 100), {})
+    const body = m.mock.calls[0][1]!.body as FormData
+    expect(body.has('name')).toBe(false)
+    expect(body.has('port')).toBe(false)
+    expect(body.has('env_vars')).toBe(false)
+    // env always lands (defaults to 'development').
+    expect(body.has('env')).toBe(true)
+  })
+
+  it('sends an Authorization: Bearer header when a token is present', async () => {
+    const m = installFetch()
+    setToken('test-token-xyz')
+    m.mockResolvedValueOnce(jsonResponse({ ok: true, slug: 's', status: 'building', url: null }))
+    await createStack(fakeFile('a.tar.gz', 100), {})
+    const headers = m.mock.calls[0][1]?.headers as Headers
+    expect(headers.get('Authorization')).toBe('Bearer test-token-xyz')
+  })
+
+  it('propagates 402 (tier wall) so the page can show the upgrade banner', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse(
+      { error: 'tier_limit', message: 'upgrade to pro for more stacks', agent_action: 'upgrade_to_pro' },
+      { status: 402 },
+    ))
+    await expect(createStack(fakeFile('a.tar.gz', 100), {}))
+      .rejects.toMatchObject({ status: 402 })
+  })
+
+  it('propagates 400 (invalid_tarball) so the form can render the message inline', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse(
+      { error: 'invalid_tarball', message: 'missing Dockerfile' },
+      { status: 400 },
+    ))
+    await expect(createStack(fakeFile('a.tar.gz', 100), {}))
+      .rejects.toMatchObject({ status: 400, message: 'missing Dockerfile' })
+  })
+
+  it('propagates 413 (payload too large)', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({ error: 'too_large' }, { status: 413 }))
+    await expect(createStack(fakeFile('a.tar.gz', 100), {}))
+      .rejects.toMatchObject({ status: 413 })
+  })
+
+  it('returns slug + status from the 202 response shape', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({
+      ok: true,
+      slug: 'rainy-tree-3',
+      status: 'building',
+      url: null,
+      name: 'rainy-tree-3',
+      env: 'production',
+    }, { status: 202 }))
+    const r = await createStack(fakeFile('a.tar.gz', 100), {})
+    expect(r.stack.slug).toBe('rainy-tree-3')
+    expect(r.stack.status).toBe('building')
+    expect(r.stack.url).toBeNull()
+  })
+})
+
+// ─── fetchStackStatus() — GET /api/v1/stacks/:slug polling helper ───────
+describe('fetchStackStatus()', () => {
+  it('GETs /api/v1/stacks/:slug and adapts the response shape', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({
+      ok: true,
+      stack: {
+        stack_id: 's1', slug: 's1', name: 'my-stack', status: 'running',
+        url: 'https://s1.deployment.instanode.dev', env: 'production', tier: 'pro',
+        created_at: '2026-05-13T00:00:00Z',
+      },
+    }))
+    const r = await fetchStackStatus('s1')
+    expect(r.ok).toBe(true)
+    expect(r.stack?.slug).toBe('s1')
+    expect(r.stack?.status).toBe('running')
+    expect(r.stack?.url).toBe('https://s1.deployment.instanode.dev')
+    expect(String(m.mock.calls[0][0])).toContain('/api/v1/stacks/s1')
+  })
+
+  it('returns stack=null on 404 instead of throwing', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({ error: 'not_found' }, { status: 404 }))
+    const r = await fetchStackStatus('missing')
+    expect(r.ok).toBe(true)
+    expect(r.stack).toBeNull()
+  })
+
+  it('URI-encodes the slug', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({ ok: true, stack: { slug: 'a b', status: 'building' } }))
+    await fetchStackStatus('a b')
+    expect(String(m.mock.calls[0][0])).toContain('/api/v1/stacks/a%20b')
+  })
+
+  it('propagates 5xx (not 404) so the polling caller can decide to retry', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({ error: 'internal' }, { status: 500 }))
+    await expect(fetchStackStatus('s1')).rejects.toMatchObject({ status: 500 })
+  })
+})

src/api/index.ts

@@ -8,7 +8,8 @@
 // real error banner instead of lying with mock data.
 
 import type {
-  Resource, DashboardStack, DashboardDeployment, DeploymentStatus,
+  Resource, DashboardStack, StackStatus,
+  DashboardDeployment, DeploymentStatus,
   DashboardTeam, BillingDetails, Invoice,
   TeamMember, TeamInvitation, AuthMeResponse, VaultEntry, ActivityItem,
   AdminCustomerListResponse, AdminCustomerDetailResponse,
@@ -840,6 +841,174 @@ export async function getStack(slug: string): Promise<{ ok: true; stack: Dashboa
   }
 }
 
+// ─── createStack — POST /stacks/new (multipart tarball upload) ───────────
+//
+// W9: the StackCreatePage at /app/stacks/new lets a human upload a
+// .tar.gz (Dockerfile + source) and ship it without touching curl. The
+// agent API endpoint is multipart-only — fields ride alongside the
+// `tarball` file part.
+//
+// Tarball size limit: 50 MB (per platform CLAUDE.md). Validated on the
+// caller side too so the user sees an inline error before the upload
+// starts; the api enforces the same limit at the edge.
+//
+// Response shape (synchronous: 202 Accepted on success):
+//   { ok: true, slug, status: "building", url?, name?, env? }
+// The dashboard polls GET /api/v1/stacks/:slug afterwards (via
+// fetchStackStatus) until status flips to running / healthy / failed.
+//
+// Tier-wall: anonymous gets 0 stacks, hobby gets 1, pro+ gets more. The
+// api returns 402 with agent_action; the caller surfaces an upgrade prompt.
+export interface CreateStackInput {
+  /** Optional human-readable name (max 32, lowercase + hyphens). Empty →
+   *  server auto-generates a slug like `tender-sky-9421`. */
+  name?: string
+  /** Container HTTP port. Default 8080. */
+  port?: number
+  /** Env scope (production / staging / development). Default 'development'
+   *  per the 2026-05-13 platform memory (default env flipped). */
+  env?: string
+  /** Map of env vars handed to the container. Keys must be uppercase +
+   *  underscore + alphanumeric — validated by the form. */
+  env_vars?: Record<string, string>
+}
+
+export interface CreateStackResponse {
+  /** Stack slug — used in /api/v1/stacks/:slug polling and the final URL. */
+  slug: string
+  /** Current build status. 'building' on synchronous 202; the caller polls
+   *  until this flips to 'running' / 'failed'. */
+  status: StackStatus
+  /** Final live URL once status is 'running'. May be null while building. */
+  url: string | null
+  /** Echoed name (server-generated if input.name was empty). */
+  name?: string
+  /** Echoed env scope. */
+  env?: string
+}
+
+/**
+ * Upload a tarball + metadata to POST /stacks/new. The body is multipart;
+ * env_vars (a JS object) is serialized to JSON for the matching form field.
+ *
+ * Authentication: pulls the bearer token from localStorage (same as call()).
+ * 401 propagates so AuthGate redirects — we don't replicate the redirect
+ * logic here because the route is auth-gated already and the caller's page
+ * mount has already passed the gate.
+ *
+ * Errors:
+ *   - 400 with { error: 'invalid_tarball', message }: surface inline
+ *   - 402 with { error: 'tier_limit', message, agent_action }: tier wall
+ *   - 413: tarball too large (the api enforces ≤ 50 MB)
+ *   - any other 4xx/5xx: propagate as APIError so the page renders a banner
+ */
+export async function createStack(
+  file: File,
+  opts: CreateStackInput = {},
+): Promise<{ ok: true; stack: CreateStackResponse }> {
+  const fd = new FormData()
+  fd.append('tarball', file)
+  if (opts.name) fd.append('name', opts.name)
+  if (opts.port !== undefined) fd.append('port', String(opts.port))
+  // Default env: 'development' per the 2026-05-13 platform memory. Caller
+  // can override to production / staging / custom.
+  fd.append('env', opts.env ?? 'development')
+  if (opts.env_vars && Object.keys(opts.env_vars).length > 0) {
+    fd.append('env_vars', JSON.stringify(opts.env_vars))
+  }
+
+  const headers = new Headers()
+  const tok = getToken()
+  if (tok) headers.set('Authorization', `Bearer ${tok}`)
+  // CRITICAL: do NOT set Content-Type for FormData — the browser must
+  // generate its own boundary. Setting it here would break the upload at
+  // the multipart parser.
+
+  const base = getAPIBaseURL()
+  const url = new URL(
+    '/stacks/new',
+    base || (typeof window !== 'undefined' ? window.location.origin : 'http://localhost'),
+  )
+  const res = await fetch(url.toString(), { method: 'POST', headers, body: fd })
+  const ct = res.headers.get('content-type') ?? ''
+  const body: any = ct.includes('application/json')
+    ? await res.json().catch(() => null)
+    : await res.text()
+
+  if (!res.ok) {
+    const code = (body && body.error) || `http_${res.status}`
+    const msg = (body && (body.message || body.error_description)) || res.statusText
+    throw new APIError(res.status, code, msg)
+  }
+
+  // Synchronous 202 / 200 — the server hands back the slug + initial state.
+  // Fields tolerated as optional because the api may add/drop them across
+  // versions; the page polls /api/v1/stacks/:slug for the canonical state.
+  const stack: CreateStackResponse = {
+    slug: body?.slug ?? body?.stack_id ?? '',
+    status: (body?.status as StackStatus) ?? 'building',
+    url: body?.url ?? null,
+    name: body?.name,
+    env: body?.env ?? body?.environment,
+  }
+  return { ok: true as const, stack }
+}
+
+/**
+ * Poll a single stack's current state. Returns null when the slug is not
+ * found (server returns 404 if the stack was deleted mid-poll, or if the
+ * caller doesn't own it). Other errors propagate so the page can show a
+ * real banner instead of pretending the build is still in flight.
+ */
+export async function fetchStackStatus(
+  slug: string,
+): Promise<{ ok: true; stack: DashboardStack | null }> {
+  try {
+    type StackGetResp = {
+      ok: boolean
+      stack?: {
+        stack_id?: string
+        slug?: string
+        name?: string
+        status?: string
+        tier?: string
+        url?: string | null
+        env?: string
+        created_at?: string
+      }
+      // Some api builds return the row at the top level under `item`.
+      item?: {
+        stack_id?: string
+        slug?: string
+        name?: string
+        status?: string
+        tier?: string
+        url?: string | null
+        env?: string
+        created_at?: string
+      }
+    }
+    const r = await call<StackGetResp>(`/api/v1/stacks/${encodeURIComponent(slug)}`)
+    const s = r.stack ?? r.item
+    if (!s) return { ok: true as const, stack: null }
+    const stack: DashboardStack = {
+      id: s.stack_id ?? s.slug ?? slug,
+      slug: s.slug ?? s.stack_id ?? slug,
+      name: s.name ?? '',
+      status: (s.status as DashboardStack['status']) ?? 'building',
+      url: s.url ?? null,
+      created_at: s.created_at ?? '',
+      team_id: '',
+      env: (s.env as DashboardStack['env']) ?? 'production',
+      tier: (s.tier as DashboardStack['tier']) ?? 'free',
+    }
+    return { ok: true as const, stack }
+  } catch (e: any) {
+    if (e?.status === 404) return { ok: true as const, stack: null }
+    throw e
+  }
+}
+
 // §10.21: no live GET /api/v1/stacks/:slug/build-logs yet. Return an
 // honest empty buffer instead of canned build logs that don't match the
 // user's actual deploy. Real-time logs stream via streamSSE on