@cat-factory/app 1.0.0

package/app/stores/workspace.ts

@@ -0,0 +1,201 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import type { SpendStatus, Workspace, WorkspaceSnapshot } from '~/types/domain'
+import { useAccountsStore } from '~/stores/accounts'
+import { useBoardStore } from '~/stores/board'
+import { usePipelinesStore } from '~/stores/pipelines'
+import { useExecutionStore } from '~/stores/execution'
+import { useAgentRunsStore } from '~/stores/agentRuns'
+
+/**
+ * Owns the active workspace and bootstraps the app against the backend. On load
+ * it resolves the user's accounts, lists the boards in the active account, opens
+ * the persisted one (or the first, or a fresh seeded board), and hydrates the
+ * board / pipelines / execution stores from its snapshot.
+ *
+ * Boards are scoped to an account: switching account re-scopes the board list,
+ * and new boards are stamped with the active account so a team can keep org
+ * boards separate from personal ones. Only the active workspace id is persisted —
+ * all board data lives on the server.
+ */
+export const useWorkspaceStore = defineStore(
+  'workspace',
+  () => {
+    const api = useApi()
+
+    /** Active workspace id (persisted so a reload reopens the same board). */
+    const workspaceId = ref<string | null>(null)
+    /** Every board visible to the user, across the accounts they belong to. */
+    const workspaces = ref<Workspace[]>([])
+    /** True once the initial snapshot has been loaded and stores hydrated. */
+    const ready = ref(false)
+    /** Set when bootstrap fails so the UI can show a retry. */
+    const error = ref<string | null>(null)
+    /** Latest spend-safeguard status from the server (null until first load). */
+    const spend = ref<SpendStatus | null>(null)
+
+    /** The boards belonging to the active account (all boards when auth is off). */
+    const accountWorkspaces = computed(() => {
+      const accounts = useAccountsStore()
+      if (!accounts.enabled || !accounts.activeAccountId) return workspaces.value
+      return workspaces.value.filter((w) => w.accountId === accounts.activeAccountId)
+    })
+
+    /** The active board's row (for the switcher label). */
+    const activeWorkspace = computed(
+      () => workspaces.value.find((w) => w.id === workspaceId.value) ?? null,
+    )
+
+    /** Push a snapshot into the data stores. */
+    function hydrate(snapshot: WorkspaceSnapshot) {
+      workspaceId.value = snapshot.workspace.id
+      spend.value = snapshot.spend ?? null
+      // Keep the board list in step (e.g. a freshly created board, or a rename).
+      const i = workspaces.value.findIndex((w) => w.id === snapshot.workspace.id)
+      if (i >= 0) workspaces.value[i] = snapshot.workspace
+      else workspaces.value.unshift(snapshot.workspace)
+      useBoardStore().hydrate(snapshot.blocks)
+      usePipelinesStore().hydrate(snapshot.pipelines)
+      useExecutionStore().hydrate(snapshot.executions)
+      useAgentRunsStore().hydrate(snapshot.bootstrapJobs ?? [])
+    }
+
+    /** Resolve accounts + boards, then open the right board for the active account. */
+    async function init() {
+      ready.value = false
+      error.value = null
+      try {
+        // Accounts are an auth concept — empty in dev, which leaves boards unscoped.
+        await useAccountsStore()
+          .load()
+          .catch(() => {})
+        workspaces.value = await api.listWorkspaces()
+        await resolveActiveBoard()
+        ready.value = true
+      } catch (e) {
+        error.value = e instanceof Error ? e.message : 'Failed to reach the backend.'
+      }
+    }
+
+    /** Open the persisted board (aligning the active account to it), else pick/create one. */
+    async function resolveActiveBoard() {
+      const accounts = useAccountsStore()
+      if (workspaceId.value) {
+        const existing = workspaces.value.find((w) => w.id === workspaceId.value)
+        if (existing) {
+          if (accounts.enabled && existing.accountId) accounts.activeAccountId = existing.accountId
+          hydrate(await api.getWorkspace(existing.id))
+          return
+        }
+        // Persisted board is gone (deleted, or now another tenant's) — fall through.
+        workspaceId.value = null
+      }
+      const first = accountWorkspaces.value[0]
+      if (first) {
+        hydrate(await api.getWorkspace(first.id))
+      } else {
+        hydrate(
+          await api.createWorkspace({
+            seed: true,
+            accountId: accounts.activeAccountId ?? undefined,
+          }),
+        )
+      }
+    }
+
+    /** Switch to another board (within reach of the active account). */
+    async function switchTo(id: string) {
+      if (id === workspaceId.value) return
+      hydrate(await api.getWorkspace(id))
+    }
+
+    /** Switch the active account, then open one of its boards (creating one if needed). */
+    async function selectAccount(id: string) {
+      const accounts = useAccountsStore()
+      if (id === accounts.activeAccountId) return
+      accounts.switchTo(id)
+      workspaceId.value = null
+      await resolveActiveBoard()
+    }
+
+    /** Create a new board in the active account and open it. */
+    async function create(name?: string) {
+      const accounts = useAccountsStore()
+      const snapshot = await api.createWorkspace({
+        seed: true,
+        name,
+        accountId: accounts.activeAccountId ?? undefined,
+      })
+      hydrate(snapshot)
+      return snapshot.workspace
+    }
+
+    /** Rename a board. */
+    async function rename(id: string, name: string) {
+      const updated = await api.renameWorkspace(id, name)
+      const i = workspaces.value.findIndex((w) => w.id === id)
+      if (i >= 0) workspaces.value[i] = updated
+      return updated
+    }
+
+    /** Delete a board; if it was active, fall back to another in the account. */
+    async function remove(id: string) {
+      await api.deleteWorkspace(id)
+      workspaces.value = workspaces.value.filter((w) => w.id !== id)
+      if (workspaceId.value === id) {
+        workspaceId.value = null
+        await resolveActiveBoard()
+      }
+    }
+
+    /** Re-fetch the snapshot and re-hydrate (after mutations and on stream (re)connect). */
+    async function refresh() {
+      if (!workspaceId.value) return
+      hydrate(await api.getWorkspace(workspaceId.value))
+    }
+
+    /** Discard the current workspace and start a fresh, seeded one in this account. */
+    async function reset() {
+      const prev = workspaceId.value
+      workspaceId.value = null
+      await create()
+      if (prev) {
+        workspaces.value = workspaces.value.filter((w) => w.id !== prev)
+        await api.deleteWorkspace(prev).catch(() => {})
+      }
+    }
+
+    /** The active workspace id, or throw if the app isn't bootstrapped yet. */
+    function requireId(): string {
+      if (!workspaceId.value) throw new Error('No active workspace')
+      return workspaceId.value
+    }
+
+    /** Resume runs paused by the spend safeguard, then refresh the snapshot. */
+    async function resumeSpend() {
+      await api.resumeSpend(requireId())
+      await refresh()
+    }
+
+    return {
+      workspaceId,
+      workspaces,
+      accountWorkspaces,
+      activeWorkspace,
+      ready,
+      error,
+      spend,
+      init,
+      switchTo,
+      selectAccount,
+      create,
+      rename,
+      remove,
+      refresh,
+      reset,
+      requireId,
+      resumeSpend,
+    }
+  },
+  { persist: { pick: ['workspaceId'] } },
+)

package/app/types/accounts.ts

@@ -0,0 +1,38 @@
+// ---------------------------------------------------------------------------
+// Account tenancy. An account owns workspaces (boards): either a single user's
+// `personal` account or an `org` shared by many engineers. Memberships map users
+// to accounts with a role. Mirrors the `@cat-factory/contracts` account schemas
+// so responses drop straight into the Pinia store.
+// ---------------------------------------------------------------------------
+
+export type AccountType = 'personal' | 'org'
+export type AccountRole = 'owner' | 'member'
+
+/** An account, annotated with the signed-in caller's role in it. */
+export interface Account {
+  id: string
+  type: AccountType
+  name: string
+  githubAccountLogin: string | null
+  createdAt: number
+  /** The caller's role in this account (`null` in the auth-disabled path). */
+  role: AccountRole | null
+}
+
+/** A member of an account. */
+export interface AccountMember {
+  accountId: string
+  userId: number
+  role: AccountRole
+  createdAt: number
+}
+
+export interface CreateAccountInput {
+  name: string
+  githubAccountLogin?: string
+}
+
+export interface AddMemberInput {
+  userId: number
+  role?: AccountRole
+}

package/app/types/bootstrap.ts

@@ -0,0 +1,83 @@
+// ---------------------------------------------------------------------------
+// Repo-bootstrap domain types. Mirrors the `@cat-factory/contracts` bootstrap
+// schemas so backend payloads drop straight into the Pinia store.
+//
+// A "reference architecture" is a managed base repo (an opinionated starter the
+// org wants new services to follow); the "bootstrap repo" task creates a new repo
+// from one and runs a bootstrapper agent in a container to adapt it.
+// ---------------------------------------------------------------------------
+
+import type { AgentFailure, AgentFailureKind, StepSubtasks } from './execution'
+
+/** A managed base repository new repos are bootstrapped from. */
+export interface ReferenceArchitecture {
+  id: string
+  workspaceId: string
+  name: string
+  description: string
+  repoOwner: string
+  repoName: string
+  defaultInstructions: string
+  createdAt: number
+  updatedAt: number
+}
+
+/** Body to register a reference architecture. */
+export interface CreateReferenceArchitectureInput {
+  name: string
+  description?: string
+  repoOwner: string
+  repoName: string
+  defaultInstructions?: string
+}
+
+/** Body to patch a reference architecture (only supplied fields change). */
+export type UpdateReferenceArchitectureInput = Partial<CreateReferenceArchitectureInput>
+
+/** Lifecycle of a single "bootstrap repo" run. */
+export type BootstrapStatus = 'pending' | 'running' | 'succeeded' | 'failed'
+
+/**
+ * A bootstrap run's failure is now the shared {@link AgentFailure} (same shape
+ * execution runs use), so the board renders one failure banner + retry for any
+ * agent. These aliases stay for back-compat / documentation of the bootstrap
+ * subset; `bootstrapFailureKindSchema` on the backend stays narrow.
+ */
+export type BootstrapFailureKind = AgentFailureKind
+
+/** Structured failure diagnostics captured when a bootstrap run fails. */
+export type BootstrapFailure = AgentFailure
+
+/** One "bootstrap repo" run with its outcome. */
+export interface BootstrapJob {
+  id: string
+  workspaceId: string
+  /** Reference architecture the run was based on, or null for a from-scratch run. */
+  referenceArchitectureId: string | null
+  /** Denormalized reference architecture name, or null for a from-scratch run. */
+  referenceArchitectureName: string | null
+  repoName: string
+  repoOwner: string | null
+  repoUrl: string | null
+  instructions: string
+  status: BootstrapStatus
+  /** The board service frame this run materialises, or null if none was created. */
+  blockId: string | null
+  /** Live subtask counts from the bootstrapper agent, or null until it reports. */
+  subtasks: StepSubtasks | null
+  error: string | null
+  /** Structured failure diagnostics when `status` is `failed`; null otherwise. */
+  failure: BootstrapFailure | null
+  createdAt: number
+  updatedAt: number
+}
+
+/** Body to kick off a bootstrap run. Omit `referenceArchitectureId` to bootstrap
+ * from a freeform prompt alone (then `instructions` must be non-empty). */
+export interface BootstrapRepoInput {
+  referenceArchitectureId?: string | null
+  repoName: string
+  description?: string
+  private?: boolean
+  instructions?: string
+}

package/app/types/documents.ts

@@ -0,0 +1,92 @@
+// ---------------------------------------------------------------------------
+// Document-source integration. Requirements / RFCs / PRDs imported from external
+// sources (Confluence, Notion, …) can be expanded into board structure or
+// attached to a task as agent context. These mirror the `@cat-factory/contracts`
+// document schemas; the abstraction is source-agnostic, keyed by `source`.
+// ---------------------------------------------------------------------------
+
+import type { BlockType } from './domain'
+
+/** The external document sources cat-factory can link to. */
+export type DocumentSourceKind = 'confluence' | 'notion'
+
+/** One credential a provider needs to connect (rendered as a form field). */
+export interface CredentialField {
+  key: string
+  label: string
+  help?: string
+  placeholder?: string
+  secret?: boolean
+}
+
+/** A source's self-description: drives the generic connect + import UI. */
+export interface DocumentSourceDescriptor {
+  source: DocumentSourceKind
+  label: string
+  /** Lucide icon name for the source. */
+  icon: string
+  credentialFields: CredentialField[]
+  refLabel: string
+  refPlaceholder: string
+}
+
+/** A workspace's connection to a document source (never carries credentials). */
+export interface DocumentConnection {
+  source: DocumentSourceKind
+  /** Human-friendly label for what we're connected to (site URL, workspace name). */
+  label: string
+  /** When the connection was established (epoch ms). */
+  connectedAt: number
+}
+
+/** A page imported from a source into the workspace. */
+export interface SourceDocument {
+  source: DocumentSourceKind
+  /** The source's stable id for the page. */
+  externalId: string
+  title: string
+  url: string
+  /** Short plain-text preview of the page body. */
+  excerpt: string
+  /** The board block this document is attached to as context, if any. */
+  linkedBlockId: string | null
+  syncedAt: number
+}
+
+/** A proposed task within a planned frame/module. */
+export interface PlanTask {
+  title: string
+  description?: string
+  features?: string[]
+}
+
+/** A proposed module grouping tasks within a planned frame. */
+export interface PlanModule {
+  name: string
+  tasks: PlanTask[]
+}
+
+/** A proposed top-level frame with its modules and loose tasks. */
+export interface PlanFrame {
+  type: BlockType
+  title: string
+  description?: string
+  modules: PlanModule[]
+  tasks: PlanTask[]
+}
+
+/** A board structure extracted from an imported document. */
+export interface DocumentBoardPlan {
+  source: DocumentSourceKind
+  externalId: string
+  /** Whether an LLM produced the plan or the deterministic heading parser did. */
+  planner: 'llm' | 'headings'
+  frames: PlanFrame[]
+}
+
+/** Counts of blocks created by spawning a plan onto the board. */
+export interface SpawnResult {
+  frames: number
+  modules: number
+  tasks: number
+}

package/app/types/domain.ts

@@ -0,0 +1,216 @@
+// ---------------------------------------------------------------------------
+// Domain model for the Agent Architecture Board.
+//
+// These shapes mirror the `@cat-factory/contracts` wire schemas exactly, so a
+// payload returned by the backend drops straight into the Pinia stores without
+// translation. The board and its agent pipelines are owned by the backend; the
+// frontend renders and mutates that state over the REST API.
+//
+// This module holds the core board vocabulary. Adjacent concerns live in
+// sibling modules and are re-exported below so `~/types/domain` stays the single
+// import surface:
+//   - execution model  → ./execution
+//   - models/fragments  → ./models
+//   - document sources  → ./documents
+// ---------------------------------------------------------------------------
+
+import type { ExecutionInstance } from './execution'
+import type { BootstrapJob } from './bootstrap'
+
+/** Lifecycle of an architecture building block. */
+export type BlockStatus =
+  | 'planned' // sketched, no dependencies satisfied yet
+  | 'ready' // dependencies done, can be implemented
+  | 'in_progress' // a pipeline is (visually) running against it
+  | 'blocked' // a pipeline step is waiting on a human decision
+  | 'pr_ready' // pipeline finished — a PR is open and awaiting merge
+  | 'done' // PR merged, implementation complete
+
+/** Kind of architecture building block (drives icon + accent). */
+export type BlockType =
+  | 'frontend'
+  | 'service'
+  | 'api'
+  | 'database'
+  | 'queue'
+  | 'integration'
+  | 'external'
+  | 'environment'
+
+/**
+ * Where a block sits in the granularity hierarchy. Both `frame` and `module`
+ * are containers ("frames") that hold draggable tasks:
+ *  - `frame`   a top-level Service; the only level rendered as a board node
+ *  - `module`  a sub-frame inside a service; created when a task assigned to a
+ *              not-yet-existing module is implemented (tasks can also be dragged in)
+ *  - `task`    a draggable unit of work living inside a service or a module
+ */
+export type BlockLevel = 'frame' | 'module' | 'task'
+
+/** A building block dropped on the board. */
+export interface Block {
+  id: string
+  title: string
+  type: BlockType
+  description: string
+  /** position relative to the parent container (service or module). */
+  position: { x: number; y: number }
+  status: BlockStatus
+  /** 0..1 implementation progress, derived from the running execution. */
+  progress: number
+  /** ids of tasks that must be implemented before this one (drives arrows). */
+  dependsOn: string[]
+  /** id of the ExecutionInstance currently running against this block, if any. */
+  executionId: string | null
+  /** granularity level; absent on legacy/persisted data means `frame`. */
+  level: BlockLevel
+  /** parent container: service or module for a task, service for a module. */
+  parentId: string | null
+  /** task-only: 0..1 confidence produced when the pipeline finishes. */
+  confidence?: number
+  /** task-only: auto-merge the PR when confidence ≥ this threshold (0..1). */
+  confidenceThreshold?: number
+  /** task-only: the module this task belongs to (created on implement if absent). */
+  moduleName?: string
+  /** task-only: the features this task implements (definition metadata). */
+  features?: string[]
+  /** ids of best-practice prompt fragments folded into this block's agent prompts. */
+  fragmentIds?: string[]
+  /** id of the model (from MODEL_CATALOG) to run this block's agents with; absent = default. */
+  modelId?: string
+  /** where this block's acceptance / Playwright tests run; absent = no preference. */
+  testTarget?: TestTarget
+  /** the PR the block's implementer agent opened for its work; absent = none yet. */
+  pullRequest?: PullRequestRef
+}
+
+/**
+ * A lightweight link from a block to the pull request its implementer agent
+ * opened. Just enough to display the PR on the board and navigate to it; mirrors
+ * `PullRequestRef` in `@cat-factory/contracts`.
+ */
+export interface PullRequestRef {
+  /** The PR's web URL, opened when the user clicks through from the board. */
+  url: string
+  /** The PR number within the repo, shown as `#<number>` when known. */
+  number?: number
+  /** The head branch the agent pushed its work to, when known. */
+  branch?: string
+}
+
+/**
+ * Where a block's acceptance / Playwright tests run:
+ *  - `github_actions`  in the project's CI, against a service spun up in the run
+ *  - `ephemeral_env`   against the provisioned ephemeral environment for the run
+ */
+export type TestTarget = 'github_actions' | 'ephemeral_env'
+
+/** The kinds of agents available in the agent palette. */
+export type AgentKind =
+  | 'architect'
+  | 'researcher'
+  | 'coder'
+  | 'tester'
+  | 'reviewer'
+  | 'documenter'
+  | 'integrator'
+  | 'acceptance'
+  | 'playwright'
+  | 'mocker'
+  | 'business-documenter'
+  | 'business-reviewer'
+
+/** A draggable agent definition shown in the agent palette. */
+export interface AgentArchetype {
+  kind: AgentKind
+  label: string
+  /** iconify name (lucide) */
+  icon: string
+  /** tailwind-ish accent token used across chips / borders */
+  color: string
+  description: string
+}
+
+/** A reusable, linear sequence of agents. */
+export interface Pipeline {
+  id: string
+  name: string
+  /** ordered agent kinds — the chain executes left to right */
+  agentKinds: AgentKind[]
+}
+
+/**
+ * Spend-safeguard status for the current billing period (a calendar month).
+ * Token usage is priced into a single currency and gated by a budget; once
+ * `exceeded`, runs are paused and the frontend shows a large warning.
+ */
+export interface SpendStatus {
+  /** Start of the current billing period (epoch ms). */
+  periodStart: number
+  inputTokens: number
+  outputTokens: number
+  /** Estimated spend this period, in `currency`. */
+  costSpent: number
+  /** Configured budget for one period, in `currency`. */
+  costLimit: number
+  /** ISO 4217 currency (e.g. 'EUR'). */
+  currency: string
+  /** True once the budget is reached: execution is paused. */
+  exceeded: boolean
+}
+
+/** A board/project container owned by the backend. */
+export interface Workspace {
+  id: string
+  name: string
+  createdAt: number
+  /** The account this board belongs to, or null for a legacy/unscoped board. */
+  accountId: string | null
+}
+
+/** Full server-side state of a workspace, returned on load and after resets. */
+export interface WorkspaceSnapshot {
+  workspace: Workspace
+  blocks: Block[]
+  pipelines: Pipeline[]
+  executions: ExecutionInstance[]
+  /** Bootstrap runs (the unified `agent_runs` bootstrap rows), so the board can
+   * render a bootstrap's live progress / failure + retry on load. Absent on
+   * older servers. */
+  bootstrapJobs?: BootstrapJob[]
+  /** Current spend-safeguard status; absent on older servers. */
+  spend?: SpendStatus
+}
+
+/**
+ * Real-time events pushed over the workspace WebSocket stream (see
+ * `useWorkspaceStream`). Mirrors `WorkspaceEvent` in `@cat-factory/contracts`.
+ */
+export type WorkspaceEvent =
+  | { type: 'execution'; instance: ExecutionInstance; block: Block | null; at: number }
+  | { type: 'board'; reason: string; at: number }
+  | { type: 'bootstrap'; job: BootstrapJob; block: Block | null; at: number }
+
+/** Level-of-detail buckets driven by the canvas zoom level. */
+export type LodLevel = 'far' | 'mid' | 'close'
+
+/** The signed-in GitHub user, as returned by the backend's /auth/me. */
+export interface AuthUser {
+  /** GitHub user id (stable across renames). */
+  id: number
+  login: string
+  name: string | null
+  avatarUrl: string | null
+}
+
+// Re-export the adjacent domain modules so `~/types/domain` remains the single
+// import surface for the whole frontend.
+export type * from './execution'
+export type * from './models'
+export type * from './fragments'
+export type * from './documents'
+export type * from './tasks'
+export type * from './scenarios'
+export type * from './bootstrap'
+export type * from './github'
+export type * from './accounts'