@cat-factory/app 0.6.0

package/app/types/merge.ts

@@ -0,0 +1,71 @@
+// Merge-policy shapes, mirroring `@cat-factory/contracts` (merge.ts). A `merger`
+// agent scores a PR on three 0..1 axes and the engine compares them against the
+// task's resolved threshold preset to auto-merge or raise a review notification.
+
+/** A `merger` agent's assessment of a pull request (each axis 0..1). */
+export interface MergeAssessment {
+  complexity: number
+  risk: number
+  impact: number
+  rationale: string
+}
+
+/**
+ * The highest reviewer-finding severity a task tolerates before the requirements review
+ * stops for a human. `none` tolerates nothing; `high` tolerates everything. Ordered
+ * none < low < medium < high.
+ */
+export type RequirementConcernLevel = 'none' | 'low' | 'medium' | 'high'
+
+/** A named, per-workspace merge policy a task can select. */
+export interface MergeThresholdPreset {
+  id: string
+  name: string
+  /** Auto-merge only when the assessment's complexity is ≤ this. */
+  maxComplexity: number
+  /** Auto-merge only when the assessment's risk is ≤ this. */
+  maxRisk: number
+  /** Auto-merge only when the assessment's impact is ≤ this. */
+  maxImpact: number
+  /** How many times the CI-fixer may try before the CI gate gives up. */
+  ciMaxAttempts: number
+  /** How many reviewer passes the requirements-review loop runs before asking the human. */
+  maxRequirementIterations: number
+  /** Findings at or below this severity auto-pass without stopping for a human. */
+  maxRequirementConcernAllowed: RequirementConcernLevel
+  /** Minutes the post-release-health gate watches the release's monitors/SLOs after deploy. */
+  releaseWatchWindowMinutes: number
+  /** How many on-call investigations the post-release-health gate may dispatch. */
+  releaseMaxAttempts: number
+  /** The workspace's fallback preset, used by tasks that pick none. */
+  isDefault: boolean
+  createdAt: number
+}
+
+/** Create a merge threshold preset. */
+export interface CreateMergePresetInput {
+  name: string
+  maxComplexity: number
+  maxRisk: number
+  maxImpact: number
+  ciMaxAttempts: number
+  maxRequirementIterations: number
+  maxRequirementConcernAllowed: RequirementConcernLevel
+  releaseWatchWindowMinutes?: number
+  releaseMaxAttempts?: number
+  isDefault?: boolean
+}
+
+/** Patch a merge threshold preset (all fields optional). */
+export interface UpdateMergePresetInput {
+  name?: string
+  maxComplexity?: number
+  maxRisk?: number
+  maxImpact?: number
+  ciMaxAttempts?: number
+  maxRequirementIterations?: number
+  maxRequirementConcernAllowed?: RequirementConcernLevel
+  releaseWatchWindowMinutes?: number
+  releaseMaxAttempts?: number
+  isDefault?: boolean
+}

package/app/types/models.ts

@@ -0,0 +1,157 @@
+// ---------------------------------------------------------------------------
+// Model selection & best-practice prompt fragments. Mirrors the
+// `@cat-factory/contracts` schemas served read-only by the backend.
+// ---------------------------------------------------------------------------
+
+import type { AgentKind, BlockType } from './domain'
+
+/** Subscription vendors whose pooled tokens drive the Claude Code / Codex harnesses. */
+export type SubscriptionVendor = 'claude' | 'codex' | 'glm' | 'kimi' | 'deepseek'
+
+/** Informational list price (per 1M tokens) for a model flavour. */
+export interface ModelCost {
+  inputPerMillion: number
+  outputPerMillion: number
+  currency: string
+}
+
+/**
+ * A selectable LLM model, resolved to the flavour in use for this deployment
+ * (served by `GET /models`). Mirrors `ModelOption` in `@cat-factory/contracts`.
+ * The base `flavor`/`provider`/`model` is the always-available fallback
+ * (cloudflare/direct), or the subscription itself for subscription-only models.
+ * `subscription` (when present) is the alternative the picker prefers once the
+ * workspace has a token for its vendor.
+ */
+export interface ModelOption {
+  id: string
+  label: string
+  description: string
+  flavor: 'cloudflare' | 'direct' | 'subscription'
+  /**
+   * Whether this model is actually selectable for the workspace: a direct API key for
+   * its provider, a connected subscription vendor, or Cloudflare AI enabled. Absent on
+   * the deployment-level catalog; present on the per-workspace `/workspaces/:id/models`.
+   */
+  available?: boolean
+  providerLabel: string
+  provider: string
+  model: string
+  vendor?: SubscriptionVendor
+  cost?: ModelCost
+  contextTokens?: number
+  /** True when the effective flavour is flat-rate quota (not budget-metered). */
+  quotaBased?: boolean
+  /** The alternative subscription flavour for a dual-mode model (GLM/Kimi). */
+  subscription?: {
+    vendor: SubscriptionVendor
+    providerLabel: string
+    provider: string
+    model: string
+    cost?: ModelCost
+    contextTokens?: number
+  }
+}
+
+/**
+ * Status of a user's personal (individual-usage) subscription — Claude consumer
+ * subscriptions are licensed per individual, so they're stored per-user (not pooled)
+ * and unlocked with a personal password. Metadata only; never the token.
+ */
+export interface PersonalSubscriptionStatus {
+  vendor: SubscriptionVendor
+  label: string
+  createdAt: number
+  updatedAt: number
+  lastUsedAt: number | null
+  /** Subscription's own expiry (null = no fixed end date). */
+  expiresAt: number | null
+  /** Whole days until `expiresAt` (negative once lapsed; null when no expiry). */
+  expiresInDays: number | null
+  expired: boolean
+  /** Whether renewal should be surfaced now (expiry within the warning window). */
+  renewSoon: boolean
+}
+
+/** Connect (or replace) the signed-in user's personal subscription for a vendor. */
+export interface StorePersonalSubscriptionInput {
+  vendor: SubscriptionVendor
+  label: string
+  token: string
+  /** Personal password gating the second encryption layer; never stored. */
+  password: string
+  /** Epoch ms the subscription expires (for renewal warnings); optional. */
+  expiresAt?: number | null
+}
+
+/** The scope a stored direct-provider API key belongs to. */
+export type ApiKeyScope = 'account' | 'workspace' | 'user'
+
+/** The direct providers that own a poolable API key. */
+export type ApiKeyProvider =
+  | 'openai'
+  | 'anthropic'
+  | 'qwen'
+  | 'deepseek'
+  | 'moonshot'
+  | 'openrouter'
+  | 'litellm'
+
+/** A connected direct-provider API key (metadata + usage), never the secret. */
+export interface ApiKey {
+  id: string
+  scope: ApiKeyScope
+  scopeId: string
+  provider: ApiKeyProvider
+  label: string
+  createdAt: number
+  lastUsedAt: number | null
+  inputTokens: number
+  outputTokens: number
+  requestCount: number
+}
+
+/** Add a direct-provider API key to a pool. `key` is write-only (the raw secret). */
+export interface AddApiKeyInput {
+  provider: ApiKeyProvider
+  label: string
+  key: string
+}
+
+/** A connected subscription credential (metadata + usage), never the secret. */
+export interface VendorCredential {
+  id: string
+  vendor: SubscriptionVendor
+  label: string
+  createdAt: number
+  lastUsedAt: number | null
+  inputTokens: number
+  outputTokens: number
+  requestCount: number
+}
+
+/**
+ * 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/notifications.ts

@@ -0,0 +1,74 @@
+// Notification shapes, mirroring `@cat-factory/contracts` (notifications.ts). A
+// notification is a first-class, human-actionable item surfaced on the board that
+// outlives the run that raised it (a PR awaiting a merge decision, a completed
+// pipeline awaiting confirmation, CI that gave up).
+
+import type { MergeAssessment } from './merge'
+
+export type NotificationType =
+  | 'merge_review'
+  | 'pipeline_complete'
+  | 'ci_failed'
+  | 'test_failed'
+  | 'requirement_review'
+  | 'clarity_review'
+  | 'release_regression'
+  | 'decision_required'
+export type NotificationStatus = 'open' | 'acted' | 'dismissed'
+
+/** The on-call agent's recommendation on a `release_regression`. */
+export type OnCallRecommendation = 'revert' | 'hold' | 'monitor'
+
+/** The on-call agent's assessment of a post-release regression. */
+export interface OnCallAssessment {
+  culpritConfidence: number
+  recommendation: OnCallRecommendation
+  rationale: string
+  evidence?: string[]
+}
+
+/** A regressed monitor/SLO on a `release_regression`. */
+export interface ReleaseSignal {
+  kind: 'monitor' | 'slo'
+  id: string
+  name: string
+  state: 'ok' | 'warn' | 'alert' | 'no_data'
+  detail?: string
+}
+
+/** Optional structured detail for rendering a notification card. */
+export interface NotificationPayload {
+  assessment?: MergeAssessment
+  prUrl?: string
+  pipelineName?: string
+  findingCount?: number
+  /** The on-call assessment, on a `release_regression`. */
+  onCallAssessment?: OnCallAssessment
+  /** The regressed monitors/SLOs, on a `release_regression`. */
+  releaseSignals?: ReleaseSignal[]
+  /** A proposed revert PR URL, when known. */
+  revertUrl?: string
+}
+
+/** A human-actionable item surfaced on the board. */
+/**
+ * Render urgency. A notification starts `normal` (the inbox's usual per-type colour) and
+ * is escalated to `urgent` (red) by the backend's sweep once it has waited for a human
+ * past the workspace's `waitingEscalationMinutes` threshold. Absent ⇒ `normal`.
+ */
+export type NotificationSeverity = 'normal' | 'urgent'
+
+export interface Notification {
+  id: string
+  type: NotificationType
+  status: NotificationStatus
+  /** Render urgency (yellow vs red); escalated by the backend sweep. Absent ⇒ normal. */
+  severity?: NotificationSeverity
+  blockId: string | null
+  executionId: string | null
+  title: string
+  body: string
+  payload?: NotificationPayload | null
+  createdAt: number
+  resolvedAt: number | null
+}

package/app/types/recurring.ts

@@ -0,0 +1,69 @@
+// Recurring-pipeline shapes, mirroring `@cat-factory/contracts` (recurring.ts). A
+// schedule attaches a pipeline to a service frame and re-runs it on a cadence —
+// run every `intervalHours`, constrained to an optional allowed window (weekdays +
+// an hour-of-day range, in the schedule's timezone). Each schedule owns one reused
+// on-board task block; firing it starts the pipeline against that block.
+
+/** Template a schedule was created from; drives the seeded block description. */
+export type ScheduleTemplate = 'dep-update' | 'tech-debt' | 'custom'
+
+/** How often a schedule fires and when it is allowed to. */
+export interface Recurrence {
+  /** Base cadence in hours (≥1). */
+  intervalHours: number
+  /** Allowed weekdays (0=Sun..6=Sat). Empty = every day. */
+  weekdays: number[]
+  /** Inclusive start of the allowed hour-of-day window, or null for no lower bound. */
+  windowStartHour: number | null
+  /** Exclusive end of the allowed hour-of-day window, or null for no upper bound. */
+  windowEndHour: number | null
+  /** IANA timezone the weekday/hour window is evaluated in (e.g. 'UTC'). */
+  timezone: string
+}
+
+/** A recurring pipeline attached to a service. */
+export interface PipelineSchedule {
+  id: string
+  /** The reused on-board task block the pipeline runs against. */
+  blockId: string
+  /** The service frame it lives in. */
+  frameId: string
+  pipelineId: string
+  template: ScheduleTemplate
+  name: string
+  recurrence: Recurrence
+  enabled: boolean
+  lastRunAt: number | null
+  /** Computed epoch-ms of the next eligible fire. */
+  nextRunAt: number
+  createdAt: number
+}
+
+/** One historical fire of a schedule (retained ~1 week), shown in the inspector. */
+export interface ScheduleRun {
+  id: string
+  scheduleId: string
+  executionId: string | null
+  status: 'running' | 'done' | 'failed' | 'skipped'
+  startedAt: number
+  finishedAt: number | null
+  outcome: string | null
+}
+
+export interface CreateScheduleInput {
+  frameId: string
+  pipelineId: string
+  template?: ScheduleTemplate
+  name: string
+  recurrence: Recurrence
+  enabled?: boolean
+  /** The prompt/description for the reused on-board task; empty → the template seed. */
+  description?: string
+}
+
+export interface UpdateScheduleInput {
+  name?: string
+  pipelineId?: string
+  recurrence?: Recurrence
+  enabled?: boolean
+}

package/app/types/releaseHealth.ts

@@ -0,0 +1,31 @@
+// Datadog post-release-health settings shapes, mirroring `@cat-factory/contracts`
+// (release.ts). Per-workspace Datadog connection (keys write-only, never read back) and
+// the per-block monitor/SLO mappings the post-release-health gate reads.
+
+/** What `GET /datadog/connection` returns — never the secret keys. */
+export interface DatadogConnectionView {
+  connected: boolean
+  site: string | null
+}
+
+/** Set/replace the workspace's Datadog connection. */
+export interface UpsertDatadogConnectionInput {
+  site: string
+  apiKey: string
+  appKey: string
+}
+
+/** A block's monitor/SLO mapping for the post-release-health gate. */
+export interface ReleaseHealthConfig {
+  blockId: string
+  monitorIds: string[]
+  sloIds: string[]
+  envTag: string | null
+}
+
+/** Create/replace a block's release-health config. */
+export interface UpsertReleaseHealthConfigInput {
+  monitorIds?: string[]
+  sloIds?: string[]
+  envTag?: string | null
+}

package/app/types/requirements.ts

@@ -0,0 +1,61 @@
+// 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
+}
+
+/**
+ * - `ready`: the reviewer raised findings awaiting human answers/dismissals.
+ * - `incorporating`: transient; the driver is folding the answers into a document (the FIRST
+ *   async stage — the user is back on the board).
+ * - `reviewing`: transient; the reviewer is RE-reviewing the folded document (the SECOND
+ *   async stage). Distinct from `incorporating` so the UI can show which stage is running.
+ * - `merged`: the companion produced a document (an internal transient on the async path).
+ * - `exceeded`: the iteration cap was hit with findings open — awaiting the human's choice.
+ * - `incorporated`: terminal; the requirements phase is settled.
+ */
+export type RequirementReviewStatus =
+  | 'ready'
+  | 'incorporating'
+  | 'reviewing'
+  | 'merged'
+  | 'exceeded'
+  | 'incorporated'
+
+/** How a human resolves a review that hit its iteration cap. */
+export type ResolveRequirementsExceededChoice = 'extra-round' | 'proceed' | 'stop-reset'
+
+export interface RequirementReview {
+  id: string
+  blockId: string
+  status: RequirementReviewStatus
+  items: RequirementReviewItem[]
+  model: string | null
+  incorporatedRequirements: string | null
+  /** Reviewer passes run so far (initial review is 1; each re-review adds one). */
+  iteration: number
+  /** The reviewer-pass budget (from the task's merge preset; an extra round bumps it). */
+  maxIterations: number
+  createdAt: number
+  updatedAt: number
+}

package/app/types/services.ts

@@ -0,0 +1,27 @@
+// In-org shared services. Mirrors the `@cat-factory/contracts` `services` wire schemas:
+// a `Service` is the account-owned unit of work (a service frame + its subtree + repo),
+// shared across the workspaces that *mount* it; a `WorkspaceMount` places a service onto a
+// workspace board with that board's own frame layout override.
+
+export interface Service {
+  id: string
+  accountId: string | null
+  frameBlockId: string
+  installationId: number | null
+  repoGithubId: number | null
+  /** Subdirectory within the linked monorepo this service lives in (null = whole repo). */
+  directory?: string | null
+  createdAt: number
+  /** How many boards mount this service. Set only on the org catalog (for the "Shared" badge). */
+  mountCount?: number
+}
+
+export interface WorkspaceMount {
+  workspaceId: string
+  serviceId: string
+  /** This board's frame position override. */
+  position: { x: number; y: number }
+  /** This board's dragged frame size; null/absent = auto-size. */
+  size?: { w: number; h: number } | null
+  createdAt: number
+}

package/app/types/slack.ts

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// Slack integration. Slack is an extra delivery transport for the existing
+// notification mechanism (merge_review / pipeline_complete / ci_failed), tapping
+// the same NotificationChannel seam server-side. These mirror the
+// `@cat-factory/contracts` Slack schemas so responses drop straight into the store.
+//
+// Two scopes: the connection (+ bot token, never sent here) is per-account; the
+// notification routing is per-workspace; the @-mention member map is per-account.
+// ---------------------------------------------------------------------------
+
+import type { NotificationType } from './notifications'
+
+/** An account's Slack connection, as exposed to clients — safe metadata only. */
+export interface SlackConnection {
+  teamId: string
+  teamName: string
+  teamIconUrl?: string | null
+  botUserId?: string | null
+  scopes?: string[]
+  connectedAt: number
+}
+
+/** Routing for a single notification type: whether it posts, and where. */
+export interface SlackRoute {
+  enabled: boolean
+  /** A channel id (`C0123…`) or name (`#general`); empty = unrouted. */
+  channel: string
+}
+
+/** A workspace's Slack notification routing. */
+export interface SlackNotificationSettings {
+  routes: Partial<Record<NotificationType, SlackRoute>>
+  mentionsEnabled: boolean
+  updatedAt: number
+}
+
+/** One internal user id → Slack member id mapping entry. */
+export type SlackMemberRole = 'product' | 'engineering'
+
+export interface SlackMemberMappingEntry {
+  /** Internal user id (`usr_*`) — the same id the member roster shows. */
+  userId: string
+  slackUserId: string
+  /**
+   * Notification role: `product` people are @-mentioned on requirement-review
+   * findings; everyone else (`engineering`) only when they created the task.
+   * Absent means `engineering`.
+   */
+  role?: SlackMemberRole
+}
+
+/** A Slack channel option for the routing picker. */
+export interface SlackChannel {
+  id: string
+  name: string
+  isPrivate: boolean
+}

package/app/types/tasks.ts

@@ -0,0 +1,82 @@
+// ---------------------------------------------------------------------------
+// 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' | 'github'
+
+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
+  /** Whether the source supports searching its catalogue by title/content. */
+  searchable?: boolean
+}
+
+/** 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
+}
+
+/** A lean hit from searching a tracker's issues (not yet imported). */
+export interface TaskSearchResult {
+  source: TaskSourceKind
+  /** The source's canonical key for the issue (re-usable as an import ref). */
+  externalId: string
+  title: string
+  url: string
+  /** Workflow status name, e.g. `In Progress` (may be empty). */
+  status: string
+  /** Short plain-text preview (may be empty). */
+  excerpt: string
+}

package/app/types/tracker.ts

@@ -0,0 +1,18 @@
+// Issue-tracker selection shapes, mirroring `@cat-factory/contracts` (tracker.ts).
+// A workspace designates one tracker — GitHub Issues or Jira — where the tech-debt
+// recurring pipeline files its ticket before implementation starts.
+
+export type TrackerKind = 'github' | 'jira'
+
+export interface TrackerSettings {
+  /** The selected tracker, or null when none is configured. */
+  tracker: TrackerKind | null
+  /** Jira project key new tickets are filed under (e.g. 'ENG'); null unless Jira. */
+  jiraProjectKey: string | null
+  updatedAt: number
+}
+
+export interface PutTrackerSettingsInput {
+  tracker: TrackerKind | null
+  jiraProjectKey?: string | null
+}