@cat-factory/app 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# `@cat-factory/app` — Frontend (Nuxt layer)
+
+The user-facing app, packaged as a **reusable Nuxt 4 layer**: a single-page app
+that runs entirely in the browser and renders the architecture board, drives agent
+pipelines, and reflects live execution. A deployment consumes it via
+`extends: ['@cat-factory/app']` (see [`deploy/frontend`](../../deploy/frontend)).
+It talks to the [backend Worker](../../backend/README.md) over REST and a single
+WebSocket, sharing wire types from
+[`@cat-factory/contracts`](../../backend/packages/contracts).
+
+The SPA source lives under `app/` (the Nuxt srcDir).
+
+## Table of contents
+
+- [What it is](#what-it-is)
+- [Tech stack](#tech-stack)
+- [Layout](#layout)
+- [Key UI surfaces](#key-ui-surfaces)
+- [Develop & test](#develop--test)
+
+## What it is
+
+A spatial planning surface. You lay out a system as a **board** of frames
+(services), modules and tasks on a [Vue Flow](https://vueflow.dev) canvas, wire up
+dependencies, attach requirements, and apply **agent pipelines** to blocks.
+Execution streams back in real time — step/subtask progress bars, decision
+prompts, failures with retry — so the canvas doubles as a live dashboard.
+
+It is a thin client: there is **no business logic here**. Every mutation calls the
+Worker API and the stores hydrate from server snapshots and live updates pushed
+over the WebSocket. How that sync works is written up in
+[`app/docs/architecture.md`](./app/docs/architecture.md).
+
+## Tech stack
+
+- **Nuxt 4 / Vue 3** SPA — single route (`pages/index.vue`).
+- **Pinia** (+ `pinia-plugin-persistedstate`) — feature stores.
+- **Vue Flow** (`core`, `background`, `controls`, `minimap`, `node-resizer`) — the canvas.
+- **Nuxt UI** + Tailwind — components and styling.
+- **VueUse** — composable utilities.
+- Lint/format via **oxlint** + **oxfmt**; tests via **vitest** + **happy-dom**.
+
+## Layout
+
+| Path              | Contents                                                                                                                                              |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `app.vue`         | Root; wraps the page in `AuthGate`.                                                                                                                   |
+| `pages/index.vue` | The only route — mounts the sidebar, canvas, toolbar, inspector, focus view, and all modals.                                                          |
+| `components/`     | UI grouped by area (see [Key UI surfaces](#key-ui-surfaces)).                                                                                         |
+| `composables/`    | `useApi` (typed client), `useWorkspaceStream` (WebSocket sync), `useBlockDrag`, `useBlockQueries`, `useBoardFlow`, `useSemanticZoom`, `useDepLabels`. |
+| `stores/`         | Pinia stores, one per feature domain.                                                                                                                 |
+| `types/`          | TypeScript domain unions (`domain.ts`) and wire types mirroring the contracts.                                                                        |
+| `utils/`          | Small pure helpers.                                                                                                                                   |
+
+## Key UI surfaces
+
+- **Board canvas** (`components/board`) — `BoardCanvas` + `nodes/` (`BlockNode`,
+  `ModuleFrame`, `TaskCard`), dependency edges, the per-block `AgentFailureCard` /
+  `AgentStopButton`, and a deep-zoom `focus/BlockFocusView`.
+- **Sidebar & chrome** (`components/layout`) — board/account switchers, palettes
+  entry points, the `SpendWarningBanner`, and the toolbar (zoom, LOD, decision
+  queue).
+- **Palettes** (`components/palettes`) — drag blocks, pipelines and agents onto
+  the board.
+- **Inspector** (`components/panels` + `panels/inspector`) — per-block tabs:
+  structure, dependencies, model + fragment picker, live execution, and linked
+  docs/issues/scenarios. Decisions resolve via `DecisionModal`.
+- **Pipeline builder** (`components/pipeline`) — assemble/edit agent chains and
+  watch `PipelineProgress`.
+- **Integrations** — modals/panels for `github`, `bootstrap`, `documents`,
+  `tasks`, `requirements` (review), `scenarios` (acceptance), and `fragments`
+  (the prompt-fragment library).
+- **Auth** (`components/auth`) — `AuthGate` / `LoginScreen` / `UserMenu`; the app
+  is gated when the backend requires sign-in.
+
+## Develop & test
+
+```bash
+pnpm install
+pnpm dev          # Nuxt dev server (expects the Worker running; set NUXT_PUBLIC_API_BASE)
+pnpm test         # vitest
+pnpm typecheck    # nuxt typecheck
+pnpm lint         # oxlint + oxfmt --check
+```
+
+> Building/deploying the static site is covered in the deployment docs — see the
+> [top-level README → Deployment](../../README.md#deployment) and
+> [`deploy/frontend/README.md`](../../deploy/frontend/README.md).

package/app/app.config.ts

@@ -0,0 +1,8 @@
+export default defineAppConfig({
+  ui: {
+    colors: {
+      primary: 'indigo',
+      neutral: 'slate',
+    },
+  },
+})

package/app/app.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+import AuthGate from '~/components/auth/AuthGate.vue'
+</script>
+
+<template>
+  <UApp>
+    <AuthGate>
+      <NuxtPage />
+    </AuthGate>
+  </UApp>
+</template>

package/app/assets/css/main.css

@@ -0,0 +1,100 @@
+@import 'tailwindcss';
+@import '@nuxt/ui';
+
+/* Toast text should be selectable. Reka UI sets `user-select: none` inline on
+ * the toast root (to support swipe-to-dismiss); since `user-select` is
+ * inherited, declaring it directly on the text slots overrides that. */
+[data-slot='viewport'] [data-slot='title'],
+[data-slot='viewport'] [data-slot='description'] {
+  user-select: text;
+}
+
+/* ---- Agent Architecture Board: shared visual language ---------------------- */
+
+:root {
+  --board-bg: #0b1020;
+}
+
+html,
+body,
+#__nuxt {
+  height: 100%;
+}
+
+body {
+  margin: 0;
+  overflow: hidden;
+}
+
+/* Vue Flow surface tuned to a dark "design board" look */
+.vue-flow__background {
+  background-color: var(--board-bg);
+}
+
+/* Status-pulse used by blocked / decision-needed blocks */
+@keyframes board-pulse {
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 rgba(245, 158, 11, 0.55);
+  }
+  50% {
+    box-shadow: 0 0 0 10px rgba(245, 158, 11, 0);
+  }
+}
+
+.board-pulse {
+  animation: board-pulse 1.4s ease-in-out infinite;
+}
+
+/* Green pulse used when a block reaches the "PR ready" state */
+@keyframes board-pulse-green {
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 rgba(34, 197, 94, 0.6);
+  }
+  50% {
+    box-shadow: 0 0 0 12px rgba(34, 197, 94, 0);
+  }
+}
+
+.board-pulse-green {
+  animation: board-pulse-green 1.2s ease-in-out infinite;
+}
+
+/* Marching-ants on edges feeding an in-progress block */
+.vue-flow__edge.is-live .vue-flow__edge-path {
+  stroke-dasharray: 6 4;
+  animation: board-dash 0.6s linear infinite;
+}
+
+/* A selected edge: highlight it so the user knows what Delete/Backspace removes */
+.vue-flow__edge.selected .vue-flow__edge-path {
+  stroke: #f43f5e !important;
+  stroke-width: 2.5 !important;
+}
+
+/* Fatter invisible hit area so thin edges are easy to click */
+.vue-flow__edge .vue-flow__edge-interaction {
+  stroke-width: 18;
+}
+
+@keyframes board-dash {
+  to {
+    stroke-dashoffset: -20;
+  }
+}
+
+/* Custom block node should not show the default node chrome */
+.vue-flow__node-block {
+  padding: 0;
+  border: none;
+  background: transparent;
+  width: auto;
+}
+
+/* Make palette drag images feel intentional. Scoped to a dedicated class so it
+ * never collides with Vue Flow's own `dragging` class, which it applies to the
+ * pane while panning (a bare `.dragging` rule would dim the whole board). */
+.palette-dragging {
+  opacity: 0.5;
+}

package/app/components/auth/AuthGate.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+import LoginScreen from '~/components/auth/LoginScreen.vue'
+
+// Resolves auth state once on mount, then either renders the app (auth off, or
+// on with a signed-in user) or the login screen. The board's own bootstrap runs
+// inside the default slot, so it only fires once the user is allowed in.
+const auth = useAuthStore()
+
+onMounted(() => auth.bootstrap())
+</script>
+
+<template>
+  <div
+    v-if="!auth.ready"
+    class="flex h-screen w-screen flex-col items-center justify-center gap-3 bg-slate-950 text-slate-400"
+  >
+    <UIcon name="i-lucide-loader" class="h-8 w-8 animate-spin" />
+    <span class="text-sm">Loading…</span>
+  </div>
+
+  <LoginScreen v-else-if="auth.required && !auth.user" />
+
+  <slot v-else />
+</template>

package/app/components/auth/LoginScreen.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+const auth = useAuthStore()
+</script>
+
+<template>
+  <div class="flex h-screen w-screen items-center justify-center bg-slate-950 text-slate-100">
+    <div
+      class="w-full max-w-sm rounded-xl border border-slate-800 bg-slate-900/80 p-8 text-center backdrop-blur"
+    >
+      <UIcon name="i-lucide-layout-dashboard" class="mx-auto mb-3 h-10 w-10 text-indigo-400" />
+      <h1 class="mb-1 text-lg font-semibold text-white">Architecture Board</h1>
+      <p class="mb-6 text-sm text-slate-400">Sign in with your GitHub account to continue.</p>
+      <UButton block size="lg" color="primary" icon="i-lucide-github" @click="auth.login()">
+        Sign in with GitHub
+      </UButton>
+    </div>
+  </div>
+</template>

package/app/components/auth/UserMenu.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+import type { DropdownMenuItem } from '@nuxt/ui'
+
+// Signed-in identity + sign-out, shown in the sidebar when auth is enabled.
+const auth = useAuthStore()
+
+const items = computed<DropdownMenuItem[][]>(() => [
+  [
+    {
+      label: 'Sign out',
+      icon: 'i-lucide-log-out',
+      onSelect: () => auth.logout(),
+    },
+  ],
+])
+</script>
+
+<template>
+  <UDropdownMenu v-if="auth.user" :items="items" :content="{ side: 'top', align: 'start' }">
+    <button
+      type="button"
+      class="flex w-full items-center gap-2 rounded-lg border border-slate-800 bg-slate-900/60 p-2 text-left transition hover:bg-slate-800/60"
+    >
+      <UAvatar
+        :src="auth.user.avatarUrl ?? undefined"
+        :alt="auth.user.login"
+        size="xs"
+        icon="i-lucide-user"
+      />
+      <div class="min-w-0 flex-1">
+        <div class="truncate text-xs font-medium text-white">
+          {{ auth.user.name || auth.user.login }}
+        </div>
+        <div class="truncate text-[10px] text-slate-500">@{{ auth.user.login }}</div>
+      </div>
+      <UIcon name="i-lucide-chevron-up" class="h-4 w-4 shrink-0 text-slate-500" />
+    </button>
+  </UDropdownMenu>
+</template>

package/app/components/board/AgentFailureCard.vue

@@ -0,0 +1,97 @@
+<script setup lang="ts">
+// Shared failure banner + retry for any failed "agent run" (a bootstrap or a
+// task execution). Self-contained: it owns the in-flight retry guard and calls
+// the unified retry through the agentRuns store, so every surface (board card,
+// inspector, task panel) gets identical behaviour from one place. Replaces the
+// three hand-rolled bootstrap banners that used to duplicate this logic.
+import type { AgentRunSummary } from '~/stores/agentRuns'
+
+const props = withDefaults(
+  defineProps<{ run: AgentRunSummary; variant?: 'compact' | 'expanded' }>(),
+  { variant: 'expanded' },
+)
+
+const agentRuns = useAgentRunsStore()
+const toast = useToast()
+
+const compact = computed(() => props.variant === 'compact')
+const failure = computed(() => props.run.failure)
+const title = computed(() => (props.run.kind === 'bootstrap' ? 'Bootstrap failed' : 'Run failed'))
+const retryLabel = computed(() =>
+  props.run.kind === 'bootstrap' ? 'Retry bootstrap' : 'Retry run',
+)
+
+const retrying = ref(false)
+async function retry() {
+  if (retrying.value) return
+  retrying.value = true
+  try {
+    await agentRuns.retry(props.run.runId)
+  } catch (e) {
+    toast.add({
+      title: 'Retry failed',
+      description: e instanceof Error ? e.message : String(e),
+      color: 'error',
+    })
+  } finally {
+    retrying.value = false
+  }
+}
+</script>
+
+<template>
+  <div
+    class="nodrag rounded-lg border border-rose-900/60 bg-rose-950/40"
+    :class="compact ? 'px-3 py-2' : 'px-3 py-2.5'"
+  >
+    <div class="flex items-center gap-1.5" :class="compact ? 'text-[11px]' : 'text-xs'">
+      <UIcon
+        name="i-lucide-alert-triangle"
+        class="shrink-0 text-rose-400"
+        :class="compact ? 'h-3.5 w-3.5' : 'h-4 w-4'"
+      />
+      <span class="text-rose-300">{{ title }}</span>
+    </div>
+
+    <p
+      v-if="failure?.message"
+      class="mt-1 leading-snug text-rose-300/90"
+      :class="compact ? 'line-clamp-2 text-[10px]' : 'text-[11px]'"
+      :title="failure.message"
+    >
+      {{ failure.message }}
+    </p>
+
+    <p
+      v-if="failure?.hint"
+      class="mt-1 leading-snug text-rose-400/70"
+      :class="compact ? 'text-[10px]' : 'text-[11px]'"
+    >
+      {{ failure.hint }}
+    </p>
+
+    <details v-if="!compact && failure?.detail && failure.detail !== failure.message" class="mt-1">
+      <summary class="cursor-pointer text-[10px] text-rose-400/60 hover:text-rose-300">
+        Show detail
+      </summary>
+      <pre
+        class="mt-1 max-h-32 overflow-auto whitespace-pre-wrap rounded bg-rose-950/60 p-1.5 text-[10px] text-rose-200/80"
+        >{{ failure.detail }}</pre
+      >
+    </details>
+
+    <button
+      type="button"
+      class="nodrag mt-2 flex items-center gap-1 rounded-md bg-rose-900/40 text-rose-200 hover:bg-rose-900/70 disabled:opacity-60"
+      :class="compact ? 'px-2 py-0.5 text-[10px]' : 'px-2 py-1 text-[11px]'"
+      :disabled="retrying"
+      @click.stop="retry"
+    >
+      <UIcon
+        :name="retrying ? 'i-lucide-loader-circle' : 'i-lucide-rotate-ccw'"
+        :class="[compact ? 'h-3 w-3' : 'h-3.5 w-3.5', { 'animate-spin': retrying }]"
+      />
+      {{ retrying ? 'Retrying…' : compact ? 'Retry' : retryLabel }}
+    </button>
+  </div>
+</template>

package/app/components/board/AgentStopButton.vue

@@ -0,0 +1,61 @@
+<script setup lang="ts">
+// Self-contained "Stop" control for a RUNNING agent run (bootstrap or execution).
+// Calls the unified stop through the agentRuns store — which kills the per-run
+// container and tears down the durable driver server-side — then toasts the
+// outcome so the user is told it actually happened. Mirrors AgentFailureCard's
+// self-contained pattern so every surface (board card, inspector, task panel)
+// behaves identically from one place.
+import type { AgentRunKind } from '~/types/domain'
+
+const props = withDefaults(
+  defineProps<{
+    runId: string
+    /** Hint for the button label only; the backend resolves the real kind. */
+    kind?: AgentRunKind
+    size?: 'xs' | 'sm' | 'md'
+    variant?: 'solid' | 'soft' | 'ghost' | 'subtle' | 'outline'
+    label?: string
+  }>(),
+  { size: 'xs', variant: 'soft', label: 'Stop' },
+)
+
+const agentRuns = useAgentRunsStore()
+const toast = useToast()
+const stopping = ref(false)
+
+async function stop() {
+  if (stopping.value) return
+  stopping.value = true
+  try {
+    const kind = await agentRuns.stop(props.runId)
+    toast.add({
+      title: kind === 'bootstrap' ? 'Bootstrap stopped' : 'Run stopped',
+      description: 'The container was killed and the run was cancelled.',
+      icon: 'i-lucide-circle-stop',
+      color: 'warning',
+    })
+  } catch (e) {
+    toast.add({
+      title: 'Stop failed',
+      description: e instanceof Error ? e.message : String(e),
+      color: 'error',
+    })
+  } finally {
+    stopping.value = false
+  }
+}
+</script>
+
+<template>
+  <UButton
+    class="nodrag"
+    color="warning"
+    :variant="variant"
+    :size="size"
+    icon="i-lucide-circle-stop"
+    :loading="stopping"
+    @click.stop="stop"
+  >
+    {{ label }}
+  </UButton>
+</template>

package/app/components/board/BoardCanvas.vue

@@ -0,0 +1,146 @@
+<script setup lang="ts">
+import { VueFlow, useVueFlow, type NodeMouseEvent } from '@vue-flow/core'
+import { Background } from '@vue-flow/background'
+import { Controls } from '@vue-flow/controls'
+import { MiniMap } from '@vue-flow/minimap'
+import BlockNode from './nodes/BlockNode.vue'
+import TaskDependencyEdges from './TaskDependencyEdges.vue'
+import { STATUS_META } from '~/utils/catalog'
+import { readDndPayload, blockIdFromEvent } from '~/utils/dnd'
+import { BOARD_FLOW_ID } from '~/composables/useBoardFlow'
+
+const board = useBoardStore()
+const pipelines = usePipelinesStore()
+const execution = useExecutionStore()
+const ui = useUiStore()
+const toast = useToast()
+
+const { onNodeDragStop, onViewportChange, screenToFlowCoordinate } = useVueFlow(BOARD_FLOW_ID)
+
+// Only frames are board nodes. Dependencies live on tasks (rendered inside the
+// frames), so there are no frame-to-frame edges on the canvas.
+//
+// Vue Flow tags every *draggable* node with the `nopan` class, which makes the
+// pane refuse to pan while the pointer is over it. An expanded frame fills much
+// of the viewport, so leaving it draggable turns the whole canvas into a dead
+// zone once tasks appear. We therefore make expanded frames non-draggable (the
+// pane pans straight through them) and move them via their header handle
+// instead — collapsed chips stay node-draggable since they're small.
+function frameExpanded(id: string) {
+  return ui.isFrameExpanded(id) && ui.lod !== 'far'
+}
+
+const nodes = computed(() =>
+  board.frames.map((b) => ({
+    id: b.id,
+    type: 'block',
+    position: b.position,
+    draggable: !frameExpanded(b.id),
+    data: {},
+  })),
+)
+
+onNodeDragStop(({ node }) => {
+  board.moveBlock(node.id, { x: node.position.x, y: node.position.y })
+})
+
+onViewportChange((vp) => {
+  ui.zoom = vp.zoom
+})
+
+function onNodeClick({ node }: NodeMouseEvent) {
+  ui.select(node.id)
+}
+
+function onNodeDoubleClick({ node }: NodeMouseEvent) {
+  // Frames are containers: double-click expands to reveal their tasks.
+  ui.toggleFrame(node.id)
+}
+
+function onPaneClick() {
+  ui.select(null)
+}
+
+function minimapColor(node: { id: string }) {
+  const b = board.getBlock(node.id)
+  return b ? STATUS_META[board.frameStatus(b.id)].color : '#475569'
+}
+
+// ---- palette drag & drop onto the canvas ----------------------------------
+function onDragOver(event: DragEvent) {
+  event.preventDefault()
+  if (event.dataTransfer) event.dataTransfer.dropEffect = 'copy'
+}
+
+async function onDrop(event: DragEvent) {
+  event.preventDefault()
+  const payload = readDndPayload(event)
+  if (!payload) return
+
+  if (payload.kind === 'block') {
+    const position = screenToFlowCoordinate({ x: event.clientX, y: event.clientY })
+    try {
+      const block = await board.addBlock(payload.blockType, position)
+      ui.select(block.id)
+    } catch {
+      toast.add({
+        title: 'Could not add block',
+        description: 'The backend rejected the request.',
+        color: 'error',
+      })
+    }
+    return
+  }
+
+  if (payload.kind === 'pipeline') {
+    // Pipelines run against tasks, not frames. The nearest [data-block-id] under
+    // the cursor is the task card when dropped inside an expanded frame.
+    const blockId = blockIdFromEvent(event)
+    const target = blockId ? board.getBlock(blockId) : undefined
+    const pipeline = pipelines.getPipeline(payload.pipelineId)
+    if (!target || !pipeline) return
+    if (target.level !== 'task') {
+      toast.add({
+        title: 'Drop onto a task',
+        description: 'Pipelines run against tasks, not services.',
+      })
+      return
+    }
+    if (!board.isRunnable(target.id)) {
+      toast.add({ title: 'Task is blocked', description: 'Its dependencies haven’t merged yet.' })
+      return
+    }
+    execution.start(target.id, pipeline)
+    ui.select(target.id)
+  }
+}
+</script>
+
+<template>
+  <div class="relative h-full w-full" @drop="onDrop" @dragover="onDragOver">
+    <VueFlow
+      :id="BOARD_FLOW_ID"
+      :nodes="nodes"
+      :min-zoom="0.2"
+      :max-zoom="2.5"
+      :default-viewport="{ x: 40, y: 20, zoom: 0.85 }"
+      :pan-on-drag="[0, 2]"
+      fit-view-on-init
+      @node-click="onNodeClick"
+      @node-double-click="onNodeDoubleClick"
+      @pane-click="onPaneClick"
+      @contextmenu.prevent
+    >
+      <Background pattern-color="#1e293b" :gap="22" :size="1.4" />
+      <MiniMap pannable zoomable :node-color="minimapColor" class="!bg-slate-900/80" />
+      <Controls position="bottom-left" />
+
+      <template #node-block="props">
+        <BlockNode :id="props.id" />
+      </template>
+    </VueFlow>
+
+    <!-- task dependency arrows, overlaid in screen space -->
+    <TaskDependencyEdges />
+  </div>
+</template>