@cat-factory/app 0.6.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,143 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+
+const auth = useAuthStore()
+
+// An invite token may ride in on the URL (?invite=…) — it flows through the OAuth
+// redirect and the password signup so a brand-new user can join the org on first login.
+const invite = computed(() => {
+  if (typeof window === 'undefined') return undefined
+  return new URLSearchParams(window.location.search).get('invite') || undefined
+})
+
+// Password form: signup creates a new user (invite or allowed-email-domain gated),
+// login authenticates an existing one. Default to login; flip to signup when invited.
+const mode = ref<'login' | 'signup'>(invite.value ? 'signup' : 'login')
+const email = ref('')
+const password = ref('')
+const name = ref('')
+const error = ref<string | null>(null)
+const busy = ref(false)
+
+async function submitPassword() {
+  error.value = null
+  busy.value = true
+  try {
+    if (mode.value === 'signup') {
+      await auth.signup({
+        email: email.value,
+        password: password.value,
+        name: name.value || undefined,
+        invite: invite.value,
+      })
+    } else {
+      await auth.passwordLogin({ email: email.value, password: password.value })
+    }
+    // Reload so the app boots with the new session.
+    if (typeof window !== 'undefined') window.location.assign(window.location.pathname)
+  } catch (e) {
+    error.value =
+      (e as { data?: { error?: { message?: string } } })?.data?.error?.message ??
+      'Sign-in failed. Check your details and try again.'
+  } finally {
+    busy.value = false
+  }
+}
+
+const showOAuthDivider = computed(
+  () => auth.providers.password && (auth.providers.github || auth.providers.google),
+)
+</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 backdrop-blur"
+    >
+      <div class="mb-6 text-center">
+        <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="text-sm text-slate-400">
+          {{ invite ? 'Accept your invitation to continue.' : 'Sign in to continue.' }}
+        </p>
+      </div>
+
+      <!-- OAuth providers -->
+      <div class="space-y-2">
+        <UButton
+          v-if="auth.providers.github"
+          block
+          size="lg"
+          color="primary"
+          icon="i-lucide-github"
+          @click="auth.login(invite)"
+        >
+          Continue with GitHub
+        </UButton>
+        <UButton
+          v-if="auth.providers.google"
+          block
+          size="lg"
+          color="neutral"
+          variant="subtle"
+          icon="i-lucide-mail"
+          @click="auth.loginWithGoogle(invite)"
+        >
+          Continue with Google
+        </UButton>
+      </div>
+
+      <div v-if="showOAuthDivider" class="my-4 flex items-center gap-3 text-xs text-slate-500">
+        <span class="h-px flex-1 bg-slate-800" /> or <span class="h-px flex-1 bg-slate-800" />
+      </div>
+
+      <!-- Email / password -->
+      <form v-if="auth.providers.password" class="space-y-3" @submit.prevent="submitPassword">
+        <UInput
+          v-if="mode === 'signup'"
+          v-model="name"
+          placeholder="Name (optional)"
+          icon="i-lucide-user"
+          size="lg"
+          class="w-full"
+        />
+        <UInput
+          v-model="email"
+          type="email"
+          required
+          placeholder="Email"
+          icon="i-lucide-at-sign"
+          size="lg"
+          class="w-full"
+        />
+        <UInput
+          v-model="password"
+          type="password"
+          required
+          placeholder="Password"
+          icon="i-lucide-lock"
+          size="lg"
+          class="w-full"
+        />
+        <p v-if="error" class="text-sm text-rose-400">{{ error }}</p>
+        <UButton block size="lg" color="primary" type="submit" :loading="busy">
+          {{ mode === 'signup' ? 'Create account' : 'Sign in' }}
+        </UButton>
+        <p class="text-center text-xs text-slate-400">
+          <template v-if="mode === 'login'">
+            Need an account?
+            <button type="button" class="text-indigo-400 hover:underline" @click="mode = 'signup'">
+              Sign up
+            </button>
+          </template>
+          <template v-else>
+            Already have an account?
+            <button type="button" class="text-indigo-400 hover:underline" @click="mode = 'login'">
+              Sign in
+            </button>
+          </template>
+        </p>
+      </form>
+    </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>