@cat-factory/app 1.0.0

package/app/types/execution.ts

@@ -0,0 +1,110 @@
+// ---------------------------------------------------------------------------
+// Execution model: a pipeline of agents running against a single block.
+// Mirrors the `@cat-factory/contracts` execution schemas.
+// ---------------------------------------------------------------------------
+
+import type { AgentKind } from './domain'
+
+/** Runtime state of a single agent within a running execution. */
+export type AgentState =
+  | 'pending' // not started
+  | 'working' // actively (visually) working
+  | 'waiting_decision' // paused, needs a human decision
+  | 'done' // finished
+
+/** A decision an agent surfaces mid-step that a human must resolve. */
+export interface Decision {
+  id: string
+  question: string
+  options: string[]
+  chosen: string | null
+}
+
+/** One entry of a running step's todo list — its label and current status. */
+export interface StepSubtaskItem {
+  label: string
+  status: 'pending' | 'in_progress' | 'completed'
+}
+
+/** Live subtask counts a running step reports from the agent's own todo list. */
+export interface StepSubtasks {
+  completed: number
+  inProgress: number
+  total: number
+  /** The individual todo entries, so a zoomed-in card can show the actual list. */
+  items?: StepSubtaskItem[]
+}
+
+// ---------------------------------------------------------------------------
+// Shared "agent run" failure model. Both flows that run an agent in a container
+// — a task pipeline `execution` and a repo `bootstrap` — surface failures with
+// this shape, so the board renders one failure banner + retry for either. Mirrors
+// `agentFailureSchema` in `@cat-factory/contracts`.
+// ---------------------------------------------------------------------------
+
+/** The agent flows that produce a container-backed "agent run". */
+export type AgentRunKind = 'bootstrap' | 'execution'
+
+/** How an agent run faulted, so the board can classify it (and hint at a retry).
+ * The union spans both flows; a given flow only ever produces a subset. */
+export type AgentFailureKind =
+  | 'preflight'
+  | 'dispatch'
+  | 'evicted'
+  | 'timeout'
+  | 'agent'
+  | 'job_failed'
+  | 'decision_timeout'
+  | 'unknown'
+
+/** Structured diagnostics captured when an agent run fails. */
+export interface AgentFailure {
+  kind: AgentFailureKind
+  /** Human-readable summary (mirrors the run's one-line `error`). */
+  message: string
+  /** Extended detail when available (the harness's reason, an HTTP body, …). */
+  detail: string | null
+  /** Where to look next (e.g. "check the container logs for this job id"). */
+  hint: string | null
+  /** Epoch ms the failure was recorded. */
+  occurredAt: number
+  /** Last subtask counts seen before the failure, for context (null if none). */
+  lastSubtasks: StepSubtasks | null
+}
+
+/** One agent's slot in a running pipeline. */
+export interface PipelineStep {
+  agentKind: AgentKind
+  state: AgentState
+  /** 0..1 progress of this individual step */
+  progress: number
+  /** live "N/M done" subtask counts while an async (container) step runs */
+  subtasks?: StepSubtasks
+  /** present + unresolved => the step (and block) is blocked */
+  decision: Decision | null
+  /** text the agent produced for this step (when LLM execution is enabled). */
+  output?: string
+  /** identifier of the model that produced `output`, for transparency. */
+  model?: string
+  /** prompt-fragment library ids folded into this step (manual ∪ selector pick). */
+  selectedFragmentIds?: string[]
+}
+
+/** A pipeline instance running against one block. */
+export interface ExecutionInstance {
+  id: string
+  blockId: string
+  pipelineId: string
+  pipelineName: string
+  steps: PipelineStep[]
+  /** index into steps of the currently active step */
+  currentStep: number
+  /**
+   * 'paused' = halted by the spend safeguard until the budget frees up;
+   * 'failed' = the run faulted (see `failure`) — surfaces the shared failure
+   * banner + retry, instead of the old success-looking `pr_ready` lie.
+   */
+  status: 'running' | 'blocked' | 'done' | 'paused' | 'failed'
+  /** Structured failure diagnostics when `status` is `failed`; null otherwise. */
+  failure?: AgentFailure | null
+}

package/app/types/fragments.ts

@@ -0,0 +1,72 @@
+// ---------------------------------------------------------------------------
+// Prompt-fragment library (ADR 0006). Mirrors the `@cat-factory/contracts`
+// fragment-library schemas: the managed, tenant-scoped catalog a workspace
+// resolves (built-in ∪ account ∪ workspace), plus the repo sources that feed it.
+// ---------------------------------------------------------------------------
+
+import type { AgentKind, BlockType } from './domain'
+import type { PromptFragment } from './models'
+
+/** Which scope owns a managed fragment / source. */
+export type FragmentOwnerKind = 'account' | 'workspace'
+
+/** The tier a resolved fragment originates from after override-by-id. */
+export type FragmentTier = 'builtin' | 'account' | 'workspace'
+
+/** Inputs for creating a hand-authored fragment at a tier. */
+export interface CreatePromptFragmentInput {
+  id?: string
+  title: string
+  category?: string
+  summary: string
+  body: string
+  tags?: string[]
+  appliesTo?: { blockTypes?: BlockType[]; agentKinds?: AgentKind[] }
+  version?: string
+}
+
+/** Partial patch for editing a fragment at a tier. */
+export type UpdatePromptFragmentInput = Partial<CreatePromptFragmentInput>
+
+/** A fragment after the three tiers are merged for a workspace. */
+export interface ResolvedFragment extends PromptFragment {
+  tier: FragmentTier
+}
+
+/** A repo directory linked as a source of Markdown guideline files. */
+export interface FragmentSource {
+  id: string
+  ownerKind: FragmentOwnerKind
+  ownerId: string
+  repoOwner: string
+  repoName: string
+  gitRef: string
+  dirPath: string
+  lastSyncedSha: string | null
+  lastSyncedAt: number | null
+  createdAt: number
+}
+
+/** Inputs for linking a repo directory as a fragment source. */
+export interface LinkFragmentSourceInput {
+  repoOwner: string
+  repoName: string
+  gitRef?: string
+  dirPath?: string
+}
+
+/** Outcome of resyncing a source. */
+export interface FragmentSyncResult {
+  upserted: number
+  tombstoned: number
+  unchanged: number
+  lastSyncedSha: string | null
+}
+
+/** Cheap "check for changes" result (no writes); powers the resync badge. */
+export interface FragmentSourceStatus {
+  changed: boolean
+  changedCount: number
+  lastSyncedSha: string | null
+  remoteSha: string | null
+}

package/app/types/github.ts

@@ -0,0 +1,153 @@
+// ---------------------------------------------------------------------------
+// GitHub integration. The backend's `GitHubModule` projects GitHub data
+// (repos/branches, pull requests/issues) into D1 and serves it fast and
+// rate-limit-free, alongside connect/resync/write endpoints. These mirror the
+// `@cat-factory/contracts` GitHub schemas so responses drop straight into the
+// Pinia store, just as the document-source types do for Confluence/Notion.
+// ---------------------------------------------------------------------------
+
+/** A workspace's GitHub App installation, as exposed to clients (no token). */
+export interface GitHubConnection {
+  installationId: number
+  accountLogin: string
+  targetType: 'Organization' | 'User'
+  connectedAt: number
+  /**
+   * Whether cat-factory can create repos under this account itself (privileged
+   * App tier). When true, the bootstrap UI drops the manual "create on GitHub"
+   * step. Defaults to false for older backends that don't send it.
+   */
+  canCreateRepos?: boolean
+}
+
+/**
+ * A discoverable App installation for the connect picker. `connected` says
+ * whether it's already bound: to THIS workspace, to ANOTHER (so connecting would
+ * be rejected), or to NONE (free to connect).
+ */
+export interface GitHubInstallationOption {
+  installationId: number
+  accountLogin: string
+  targetType: 'Organization' | 'User'
+  accountAvatarUrl: string | null
+  connected: 'this' | 'other' | 'none'
+}
+
+/** A repository the integration tracks for a workspace. */
+export interface GitHubRepo {
+  githubId: number
+  installationId: number
+  owner: string
+  name: string
+  defaultBranch: string | null
+  private: boolean
+  /** Optional link to a board block this repo backs. */
+  blockId: string | null
+  syncedAt: number
+}
+
+export interface GitHubBranch {
+  repoGithubId: number
+  name: string
+  headSha: string
+  protected: boolean
+  syncedAt: number
+}
+
+/**
+ * A repo the connected installation can access, annotated with whether the
+ * current workspace links it. Drives the per-workspace repo picker — repos are
+ * linked explicitly per board, since the installation is shared across an
+ * account's workspaces.
+ */
+export interface GitHubAvailableRepo {
+  githubId: number
+  owner: string
+  name: string
+  defaultBranch: string | null
+  private: boolean
+  linked: boolean
+}
+
+export type GitHubPullRequestState = 'open' | 'closed'
+
+export interface GitHubPullRequest {
+  repoGithubId: number
+  number: number
+  githubId: number
+  title: string
+  state: GitHubPullRequestState
+  headRef: string | null
+  baseRef: string | null
+  headSha: string | null
+  merged: boolean
+  author: string | null
+  updatedAt: number | null
+  syncedAt: number
+}
+
+export type GitHubIssueState = 'open' | 'closed'
+
+export interface GitHubIssue {
+  repoGithubId: number
+  number: number
+  githubId: number
+  title: string
+  state: GitHubIssueState
+  author: string | null
+  labels: string[]
+  updatedAt: number | null
+  syncedAt: number
+}
+
+// ---- request inputs -------------------------------------------------------
+
+/** Trigger a resync. Defaults to an incremental resync of all tracked repos. */
+export interface ResyncRequest {
+  /** Limit the resync to a single repo (by its GitHub numeric id). */
+  repoGithubId?: number
+  /** Run a full backfill (durable Workflow) instead of an incremental pass. */
+  full?: boolean
+}
+
+export interface CreateBranchInput {
+  name: string
+  fromSha: string
+}
+
+/** Body for programmatic repo creation (privileged App tier). */
+export interface CreateRepoRequest {
+  /** A single GitHub name segment — no "owner/" prefix. */
+  name: string
+  private?: boolean
+  description?: string
+}
+
+/** The freshly-created repository returned by the create-repo endpoint. */
+export interface CreatedRepo {
+  githubId: number
+  owner: string
+  name: string
+  defaultBranch: string | null
+  private: boolean
+}
+
+export interface CommitFilesInput {
+  branch: string
+  message: string
+  files: { path: string; content: string }[]
+  /** Parent commit to build on; defaults to the branch tip. */
+  baseSha?: string
+}
+
+export interface OpenPullRequestInput {
+  title: string
+  head: string
+  base: string
+  body?: string
+  draft?: boolean
+}
+
+export interface MergePullRequestInput {
+  method?: 'merge' | 'squash' | 'rebase'
+}

package/app/types/models.ts

@@ -0,0 +1,48 @@
+// ---------------------------------------------------------------------------
+// Model selection & best-practice prompt fragments. Mirrors the
+// `@cat-factory/contracts` schemas served read-only by the backend.
+// ---------------------------------------------------------------------------
+
+import type { AgentKind, BlockType } from './domain'
+
+/**
+ * A selectable LLM model, resolved to the flavour actually in use for this
+ * deployment (served by `GET /models`). `flavor` is `direct` when the model's
+ * own provider key is configured, else `cloudflare`. Mirrors `ModelOption` in
+ * `@cat-factory/contracts`.
+ */
+export interface ModelOption {
+  id: string
+  label: string
+  description: string
+  flavor: 'cloudflare' | 'direct'
+  providerLabel: string
+  provider: string
+  model: string
+}
+
+/**
+ * A curated best-practice "prompt fragment" served read-only by the backend
+ * (`GET /prompt-fragments`). Users pick which apply to a block; the backend folds
+ * the selected fragments' bodies into the agent system prompt at run time.
+ */
+export interface PromptFragment {
+  id: string
+  version: string
+  title: string
+  category: string
+  summary: string
+  body: string
+  appliesTo?: {
+    blockTypes?: BlockType[]
+    agentKinds?: AgentKind[]
+  }
+  /** Free-form tags the relevance selector uses (managed/sourced fragments only). */
+  tags?: string[]
+  /** Provenance when sourced from a repo; absent for built-in/hand-authored. */
+  source?: {
+    sourceId: string
+    path: string
+    sha: string
+  }
+}

package/app/types/requirements.ts

@@ -0,0 +1,38 @@
+// Requirements-review wire types. Mirror of `@cat-factory/contracts`'
+// requirements.ts, kept in sync by hand like the rest of `~/types/*` (the SPA
+// does not import the backend package directly).
+//
+// A stateless reviewer agent inspects a block's collected requirements and
+// raises questions / gaps / clarifications; a human answers or dismisses each;
+// then the agent folds the answers back into the block's requirements.
+
+export type ReviewItemCategory = 'gap' | 'clarification' | 'assumption' | 'risk' | 'question'
+
+export type ReviewItemSeverity = 'low' | 'medium' | 'high'
+
+export type ReviewItemStatus = 'open' | 'answered' | 'resolved' | 'dismissed'
+
+export interface RequirementReviewItem {
+  id: string
+  category: ReviewItemCategory
+  severity: ReviewItemSeverity
+  title: string
+  detail: string
+  status: ReviewItemStatus
+  reply: string | null
+  createdAt: number
+  updatedAt: number
+}
+
+export type RequirementReviewStatus = 'ready' | 'incorporated'
+
+export interface RequirementReview {
+  id: string
+  blockId: string
+  status: RequirementReviewStatus
+  items: RequirementReviewItem[]
+  model: string | null
+  incorporatedRequirements: string | null
+  createdAt: number
+  updatedAt: number
+}

package/app/types/scenarios.ts

@@ -0,0 +1,36 @@
+// ---------------------------------------------------------------------------
+// Acceptance test scenarios.
+//
+// A feature-scoped, black-box acceptance scenario in Given / When / Then form.
+// These are what the `acceptance` agent produces from a block's requirements
+// (description + linked PRDs), and what the `playwright` agent turns into
+// end-to-end tests. The board is server-owned, but — like the agent palette —
+// scenarios are an editable, client-side prototype surface, persisted locally so
+// a user can author and refine the set for a feature before wiring up real runs.
+// ---------------------------------------------------------------------------
+
+/** Where a scenario came from: drafted by the acceptance agent or hand-written. */
+export type ScenarioSource = 'generated' | 'manual'
+
+/** Review state of a scenario in its feature's current set. */
+export type ScenarioStatus = 'draft' | 'approved'
+
+/** A single acceptance scenario for a feature. */
+export interface AcceptanceScenario {
+  id: string
+  /** The feature (matching `Block.features`) this scenario verifies. */
+  feature: string
+  /** Short, human title — also the name of the generated Playwright test. */
+  title: string
+  /** Preconditions (one clause per entry). */
+  given: string[]
+  /** The user action under test (kept to a single clear action). */
+  when: string[]
+  /** Observable, asserted outcomes. */
+  then: string[]
+  status: ScenarioStatus
+  source: ScenarioSource
+  /** True once a Playwright test has been generated for this scenario. */
+  hasPlaywrightTest: boolean
+  createdAt: number
+}

package/app/types/tasks.ts

@@ -0,0 +1,67 @@
+// ---------------------------------------------------------------------------
+// Task-source integration. Individual issues imported from external task
+// trackers (Jira, …) can be attached to a board task as agent context. These
+// mirror the `@cat-factory/contracts` task schemas; the abstraction is
+// source-agnostic, keyed by `source`. Unlike document sources there is no
+// plan/spawn — an issue is linked for context, never expanded into structure.
+// ---------------------------------------------------------------------------
+
+import type { CredentialField } from './documents'
+
+/** The external task trackers cat-factory can link to. */
+export type TaskSourceKind = 'jira'
+
+export type { CredentialField }
+
+/** A source's self-description: drives the generic connect + import UI. */
+export interface TaskSourceDescriptor {
+  source: TaskSourceKind
+  label: string
+  /** Lucide icon name for the source. */
+  icon: string
+  credentialFields: CredentialField[]
+  refLabel: string
+  refPlaceholder: string
+}
+
+/** A workspace's connection to a task source (never carries credentials). */
+export interface TaskConnection {
+  source: TaskSourceKind
+  /** Human-friendly label for what we're connected to (site URL). */
+  label: string
+  /** When the connection was established (epoch ms). */
+  connectedAt: number
+}
+
+/** A single comment on an issue, with its body as lightweight Markdown. */
+export interface TaskComment {
+  author: string
+  createdAt: string
+  body: string
+}
+
+/** An issue imported from a source into the workspace, as a structured record. */
+export interface SourceTask {
+  source: TaskSourceKind
+  /** The source's canonical key for the issue (e.g. `PROJ-123`). */
+  externalId: string
+  title: string
+  url: string
+  /** Workflow status name, e.g. `In Progress`. */
+  status: string
+  /** Issue type name, e.g. `Bug`. */
+  type: string
+  /** Assignee display name, or null when unassigned. */
+  assignee: string | null
+  /** Priority name, or null when none. */
+  priority: string | null
+  labels: string[]
+  /** Issue description as lightweight Markdown. */
+  description: string
+  comments: TaskComment[]
+  /** Short plain-text preview of the issue. */
+  excerpt: string
+  /** The board block this issue is attached to as context, if any. */
+  linkedBlockId: string | null
+  syncedAt: number
+}

package/app/utils/catalog.spec.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest'
+import type { AgentKind, BlockStatus, BlockType } from '~/types/domain'
+import {
+  AGENT_ARCHETYPES,
+  AGENT_BY_KIND,
+  BLOCK_TYPE_META,
+  STATUS_META,
+  DEFAULT_CONFIDENCE_THRESHOLD,
+  uid,
+} from '~/utils/catalog'
+
+const AGENT_KINDS: AgentKind[] = [
+  'architect',
+  'researcher',
+  'coder',
+  'tester',
+  'reviewer',
+  'documenter',
+  'integrator',
+  'acceptance',
+  'playwright',
+  'mocker',
+  'business-documenter',
+  'business-reviewer',
+]
+const BLOCK_TYPES: BlockType[] = [
+  'frontend',
+  'service',
+  'api',
+  'database',
+  'queue',
+  'integration',
+  'external',
+]
+const BLOCK_STATUSES: BlockStatus[] = [
+  'planned',
+  'ready',
+  'in_progress',
+  'blocked',
+  'pr_ready',
+  'done',
+]
+
+describe('catalog', () => {
+  it('indexes every archetype by its kind', () => {
+    expect(Object.keys(AGENT_BY_KIND).sort()).toEqual([...AGENT_KINDS].sort())
+    for (const a of AGENT_ARCHETYPES) {
+      expect(AGENT_BY_KIND[a.kind]).toBe(a)
+    }
+  })
+
+  it('provides metadata for every block type', () => {
+    for (const t of BLOCK_TYPES) {
+      expect(BLOCK_TYPE_META[t]).toMatchObject({
+        label: expect.any(String),
+        icon: expect.any(String),
+        accent: expect.any(String),
+      })
+    }
+  })
+
+  it('provides metadata for every block status', () => {
+    for (const s of BLOCK_STATUSES) {
+      expect(STATUS_META[s]).toMatchObject({
+        label: expect.any(String),
+        color: expect.any(String),
+        chip: expect.any(String),
+        icon: expect.any(String),
+      })
+    }
+  })
+
+  it('keeps the default confidence threshold within 0..1', () => {
+    expect(DEFAULT_CONFIDENCE_THRESHOLD).toBeGreaterThan(0)
+    expect(DEFAULT_CONFIDENCE_THRESHOLD).toBeLessThanOrEqual(1)
+  })
+
+  it('uid produces prefixed, unique-ish ids', () => {
+    expect(uid('blk')).toMatch(/^blk_[a-z0-9]+$/)
+    expect(uid('blk')).not.toBe(uid('blk'))
+  })
+})