@cat-factory/app 0.37.0 → 0.37.2

package/app/components/auth/LoginScreen.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
+import { apiErrorEnvelope } from '~/composables/api/errors'
 
 const auth = useAuthStore()
 
@@ -37,8 +38,7 @@ async function submitPassword() {
     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.'
+      apiErrorEnvelope(e)?.message ?? 'Sign-in failed. Check your details and try again.'
   } finally {
     busy.value = false
   }

package/app/components/layout/AccountTeamSettings.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { computed, onMounted, ref, watch } from 'vue'
+import { apiErrorEnvelope } from '~/composables/api/errors'
 import type { AccountRole } from '~/types/domain'
 import AccountDeploymentSettings from '~/components/layout/AccountDeploymentSettings.vue'
 
@@ -39,9 +40,7 @@ async function updateMemberRoles(userId: string, roles: AccountRole[]) {
 function notifyError(title: string, e: unknown) {
   toast.add({
     title,
-    description:
-      (e as { data?: { error?: { message?: string } } })?.data?.error?.message ??
-      (e instanceof Error ? e.message : String(e)),
+    description: apiErrorEnvelope(e)?.message ?? (e instanceof Error ? e.message : String(e)),
     icon: 'i-lucide-triangle-alert',
     color: 'error',
   })

package/app/composables/api/client.ts

@@ -11,6 +11,7 @@ import {
   type WretchInstance,
 } from '@toad-contracts/frontend-http-client'
 import wretch from 'wretch'
+import { ApiError } from './errors'
 
 /**
  * The validated success-response body inferred from a route contract (every REST
@@ -75,7 +76,16 @@ export async function sendContract<T extends ApiContract>(
   params: SendParams<T>,
 ): Promise<SuccessBodyOf<T>> {
   const outcome = await sendByApiContract(client, contract, params)
-  if (outcome.error) throw outcome.error
+  if (outcome.error) {
+    const error = outcome.error
+    // A contract-declared non-2xx is reported as a plain `{ statusCode, headers, body }`
+    // value (not an Error). Wrap it so call sites get `instanceof Error` + the server's
+    // message; anything already an Error (UnexpectedResponseError, request-validation
+    // SchemaValidationError, a network fault) is rethrown unchanged.
+    if (error instanceof Error) throw error
+    const { statusCode, body } = error as { statusCode: number; body: unknown }
+    throw new ApiError(statusCode, body)
+  }
   return outcome.result!.body as SuccessBodyOf<T>
 }
 

package/app/composables/api/errors.spec.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { ApiError, apiErrorEnvelope, apiErrorStatus } from '~/composables/api/errors'
+
+// The contract client (`sendByApiContract`) reports a declared non-2xx as a plain
+// `{ statusCode, headers, body }` value — body under `.body`, NOT an Error. Before the
+// `ApiError` wrap, every `instanceof Error` check rendered "[object Object]" and every
+// `.data.error` reader (parseConflict / parseCredentialError / login + probe messages)
+// silently returned nothing. These tests lock that in.
+
+describe('ApiError', () => {
+  const body = { error: { code: 'conflict', message: 'Nope', details: { reason: 'task_limit' } } }
+
+  it('is a real Error carrying the server message, status, and body', () => {
+    const e = new ApiError(409, body)
+    expect(e).toBeInstanceOf(Error)
+    expect(e.message).toBe('Nope') // not "[object Object]"
+    expect(e.statusCode).toBe(409)
+    expect(e.envelope).toEqual(body.error)
+  })
+
+  it('falls back to a status message when the body carries no envelope', () => {
+    expect(new ApiError(500, 'gateway down').message).toBe('Request failed (HTTP 500)')
+  })
+})
+
+describe('apiErrorEnvelope', () => {
+  const envelope = { code: 'credential_required', message: 'Unlock', details: { vendor: 'claude' } }
+
+  it('reads the envelope from a wrapped ApiError (contract client)', () => {
+    expect(apiErrorEnvelope(new ApiError(428, { error: envelope }))).toEqual(envelope)
+  })
+
+  it('reads the envelope from a bare { body } value (contract client, unwrapped)', () => {
+    expect(apiErrorEnvelope({ statusCode: 428, body: { error: envelope } })).toEqual(envelope)
+  })
+
+  it('reads the envelope from a legacy $fetch FetchError (body under .data)', () => {
+    expect(apiErrorEnvelope({ statusCode: 428, data: { error: envelope } })).toEqual(envelope)
+  })
+
+  it('returns undefined for a network/non-API error', () => {
+    expect(apiErrorEnvelope(new Error('socket hang up'))).toBeUndefined()
+    expect(apiErrorEnvelope(undefined)).toBeUndefined()
+  })
+})
+
+describe('apiErrorStatus', () => {
+  it('reads .statusCode (contract client) and .status (legacy)', () => {
+    expect(apiErrorStatus(new ApiError(503, {}))).toBe(503)
+    expect(apiErrorStatus({ status: 500 })).toBe(500)
+    expect(apiErrorStatus(new Error('x'))).toBeUndefined()
+  })
+})

package/app/composables/api/errors.ts

@@ -0,0 +1,63 @@
+/**
+ * A failed API call, normalised to a real `Error`.
+ *
+ * The contract client (`sendByApiContract`) reports a contract-declared non-2xx as a
+ * plain `{ statusCode, headers, body }` value — NOT an `Error` — with the parsed
+ * `{ error: { code, message, details } }` envelope under `body`. Throwing that bare
+ * object breaks every `error instanceof Error` check (they fall to `String(error)` =
+ * `"[object Object]"`) and hides the server's message. `sendContract` wraps it in this
+ * class so call sites get `instanceof Error`, a real `.message` (the server's), the
+ * `.statusCode`, and the typed `.envelope`.
+ */
+export class ApiError extends Error {
+  readonly statusCode: number
+  /** The parsed response body (the `{ error: {...} }` envelope for our controllers). */
+  readonly body: unknown
+
+  constructor(statusCode: number, body: unknown) {
+    super(envelopeOf(body)?.message ?? `Request failed (HTTP ${statusCode})`)
+    this.name = 'ApiError'
+    this.statusCode = statusCode
+    this.body = body
+  }
+
+  /** The `{ code, message, details, issues }` envelope, when the body carries one. */
+  get envelope(): ApiErrorEnvelope | undefined {
+    return envelopeOf(this.body)
+  }
+}
+
+/** The error envelope every controller emits (`handleError` / contract request-validator). */
+export interface ApiErrorEnvelope {
+  code?: string
+  message?: string
+  details?: unknown
+  issues?: { path?: string; message: string }[]
+}
+
+/** Read the `{ error: {...} }` envelope out of a parsed response body, else undefined. */
+function envelopeOf(body: unknown): ApiErrorEnvelope | undefined {
+  if (!body || typeof body !== 'object') return undefined
+  const error = (body as { error?: unknown }).error
+  return error && typeof error === 'object' ? (error as ApiErrorEnvelope) : undefined
+}
+
+/**
+ * Pull the server error envelope out of any thrown API error, regardless of which client
+ * produced it: the contract client (`ApiError`, body under `.body`) or the legacy `$fetch`
+ * path (ofetch `FetchError`, body under `.data`). Returns undefined for network faults or
+ * non-API errors.
+ */
+export function apiErrorEnvelope(error: unknown): ApiErrorEnvelope | undefined {
+  if (error instanceof ApiError) return error.envelope
+  const e = error as { body?: unknown; data?: unknown }
+  return envelopeOf(e?.body) ?? envelopeOf(e?.data)
+}
+
+/** The HTTP status of a thrown API error, when present (contract client or `$fetch`). */
+export function apiErrorStatus(error: unknown): number | undefined {
+  const e = error as { statusCode?: unknown; status?: unknown }
+  if (typeof e?.statusCode === 'number') return e.statusCode
+  if (typeof e?.status === 'number') return e.status
+  return undefined
+}

package/app/composables/usePipelineErrorToast.ts

@@ -6,6 +6,8 @@
  * SAME guidance + "Configure AI" jump as the no-AI-provider startup banner.
  */
 
+import { apiErrorEnvelope } from './api/errors'
+
 /** The parsed shape of a backend conflict (`{ error: { code: 'conflict', details } }`). */
 interface ConflictDetails {
   reason?: string
@@ -13,15 +15,13 @@ interface ConflictDetails {
   [key: string]: unknown
 }
 
-/** Pull a 409 conflict's `{ reason, message, details }` out of a thrown fetch error, else null. */
+/** Pull a 409 conflict's `{ reason, message, details }` out of a thrown API error, else null. */
 export function parseConflict(
   error: unknown,
 ): { reason?: string; message: string; details: ConflictDetails } | null {
-  const body = (
-    error as { data?: { error?: { code?: string; message?: string; details?: ConflictDetails } } }
-  )?.data?.error
+  const body = apiErrorEnvelope(error)
   if (body?.code !== 'conflict') return null
-  const details = body.details ?? {}
+  const details = (body.details as ConflictDetails | undefined) ?? {}
   return {
     reason: typeof details.reason === 'string' ? details.reason : undefined,
     message: body.message ?? 'This action conflicts with the current state.',

package/app/composables/useSourceIntegration.ts

@@ -0,0 +1,107 @@
+import { type ComputedRef, type Ref, computed, ref } from 'vue'
+import { apiErrorEnvelope, apiErrorStatus } from '~/composables/api/errors'
+import { useUpsertList } from '~/composables/useUpsertList'
+
+/**
+ * The source-integration lifecycle shared by the document-source and task-source stores:
+ * the opt-in `available` gate, the per-source `connections` list, the `descriptorFor` /
+ * `connectionFor` / `isConnected` lookups, and a `probe()` that resolves all of it (hiding
+ * the UI when the integration is off). Both stores previously hand-rolled this, with
+ * inconsistent error handling — one captured the probe failure, the other swallowed it.
+ * Standardising here means every integration now records WHY a probe failed
+ * (`probeError`: a 503 "turned off on this deployment" vs a 500 "the backend errored"), so
+ * a settings panel can explain the empty state instead of a blanket "install it first".
+ *
+ * The store supplies only what differs: how to fetch its sources + connections, and the
+ * connect/disconnect calls (which feed `upsertConnection` / `removeConnection`). Source-
+ * specific extras (diagnostics, per-source enable toggles, plan/spawn) stay in the store.
+ */
+export function useSourceIntegration<
+  Source extends string,
+  Conn extends { source: Source },
+  Desc extends { source: Source },
+>(opts: {
+  /** Fetch the configured sources + live connections; throws when the integration is off. */
+  fetch: () => Promise<{ sources: Desc[]; connections: Conn[] }>
+  /** Gate the probe (e.g. skip until a workspace is selected). */
+  enabled?: () => boolean
+}): {
+  available: Ref<boolean | null>
+  probeError: Ref<{ status: number | null; message: string } | null>
+  sources: Ref<Desc[]>
+  connections: Ref<Conn[]>
+  connectedSources: ComputedRef<Desc[]>
+  anyConnected: ComputedRef<boolean>
+  descriptorFor: (source: Source) => Desc | undefined
+  connectionFor: (source: Source) => Conn | undefined
+  isConnected: (source: Source) => boolean
+  upsertConnection: (conn: Conn) => void
+  removeConnection: (source: Source) => void
+  probe: () => Promise<void>
+} {
+  /** null = unknown (not probed yet), true/false = integration on/off. */
+  const available = ref<boolean | null>(null)
+  /** Why the last probe failed, when it did (kept rather than swallowed). */
+  const probeError = ref<{ status: number | null; message: string } | null>(null)
+  const sources = ref<Desc[]>([]) as Ref<Desc[]>
+  const { items: connections, upsert: upsertConnection } = useUpsertList<Conn>({
+    key: (c) => c.source,
+  })
+
+  const connectedSources = computed(() =>
+    sources.value.filter((s) => connections.value.some((c) => c.source === s.source)),
+  )
+  const anyConnected = computed(() => connections.value.length > 0)
+
+  function descriptorFor(source: Source): Desc | undefined {
+    return sources.value.find((s) => s.source === source)
+  }
+  function connectionFor(source: Source): Conn | undefined {
+    return connections.value.find((c) => c.source === source)
+  }
+  function isConnected(source: Source): boolean {
+    return connectionFor(source) !== undefined
+  }
+  function removeConnection(source: Source) {
+    connections.value = connections.value.filter((c) => c.source !== source)
+  }
+
+  /** Probe the integration: resolves `available`, the sources and connections. */
+  async function probe() {
+    if (opts.enabled && !opts.enabled()) return
+    try {
+      const { sources: srcs, connections: conns } = await opts.fetch()
+      available.value = true
+      probeError.value = null
+      sources.value = srcs
+      connections.value = conns
+    } catch (e) {
+      // 503 (integration disabled) or any error → hide the UI entry points, but keep the
+      // reason so a panel can explain it (503 = off here; 500 = the backend errored, e.g. an
+      // unapplied migration).
+      available.value = false
+      const serverMessage = apiErrorEnvelope(e)?.message
+      probeError.value = {
+        status: apiErrorStatus(e) ?? null,
+        message: serverMessage || (e instanceof Error ? e.message : String(e)),
+      }
+      sources.value = []
+      connections.value = []
+    }
+  }
+
+  return {
+    available,
+    probeError,
+    sources,
+    connections,
+    connectedSources,
+    anyConnected,
+    descriptorFor,
+    connectionFor,
+    isConnected,
+    upsertConnection,
+    removeConnection,
+    probe,
+  }
+}

package/app/composables/useUpsertList.spec.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+import { useUpsertList } from '~/composables/useUpsertList'
+
+interface Item {
+  id: string
+  v: number
+}
+
+describe('useUpsertList', () => {
+  it('appends new items by default and replaces in place by key', () => {
+    const { items, upsert } = useUpsertList<Item>({ key: (x) => x.id })
+    upsert({ id: 'a', v: 1 })
+    upsert({ id: 'b', v: 2 })
+    upsert({ id: 'a', v: 9 }) // replace, not duplicate
+    expect(items.value).toEqual([
+      { id: 'a', v: 9 },
+      { id: 'b', v: 2 },
+    ])
+  })
+
+  it('prepends new items when prepend is set (newest-first)', () => {
+    const { items, upsert } = useUpsertList<Item>({ key: (x) => x.id, prepend: true })
+    upsert({ id: 'a', v: 1 })
+    upsert({ id: 'b', v: 2 })
+    expect(items.value.map((x) => x.id)).toEqual(['b', 'a'])
+  })
+
+  it('removes by key and looks up by key', () => {
+    const { items, upsert, remove, get } = useUpsertList<Item>({ key: (x) => x.id })
+    upsert({ id: 'a', v: 1 })
+    upsert({ id: 'b', v: 2 })
+    expect(get('b')).toEqual({ id: 'b', v: 2 })
+    remove('a')
+    expect(items.value.map((x) => x.id)).toEqual(['b'])
+    remove('missing') // no-op
+    expect(items.value).toHaveLength(1)
+  })
+
+  it('supports composite keys and hydrate-from-snapshot', () => {
+    interface Doc {
+      source: string
+      externalId: string
+    }
+    const { items, upsert, hydrate } = useUpsertList<Doc>({
+      key: (d) => `${d.source}:${d.externalId}`,
+    })
+    hydrate([{ source: 'jira', externalId: '1' }])
+    upsert({ source: 'jira', externalId: '1' }) // same composite key → replace
+    upsert({ source: 'gh', externalId: '1' }) // different source → new
+    expect(items.value).toHaveLength(2)
+  })
+
+  it('seeds from initial without aliasing the caller array', () => {
+    const seed: Item[] = [{ id: 'a', v: 1 }]
+    const { items, upsert } = useUpsertList<Item>({ key: (x) => x.id, initial: seed })
+    upsert({ id: 'b', v: 2 })
+    expect(items.value).toHaveLength(2)
+    expect(seed).toHaveLength(1) // original untouched
+  })
+})

package/app/composables/useUpsertList.ts

@@ -0,0 +1,57 @@
+import { type Ref, ref } from 'vue'
+
+/**
+ * A keyed list with find-by-key upsert — the pattern reimplemented in ~13 stores
+ * (`const i = list.findIndex((x) => x.id === item.id); if (i >= 0) list[i] = item else …`).
+ * Wraps a reactive `T[]` and exposes `upsert` (replace-in-place or insert), `remove`,
+ * `get`, and `hydrate` (replace from a server snapshot), all keyed by a caller-supplied
+ * `key` function. New items append by default, or `prepend: true` for newest-first inboxes.
+ *
+ * The returned `items` ref stays directly assignable, so a store can expose it under a
+ * domain name (`const { items: documents, upsert } = useUpsertList(...)`) and callers /
+ * tests can still do `store.documents = [...]`.
+ */
+export function useUpsertList<T>(opts: {
+  /** Stable identity for an item (e.g. `(x) => x.id`, or `(x) => `${x.source}:${x.externalId}``). */
+  key: (item: T) => unknown
+  /** Insert position for a brand-new item: `true` ⇒ unshift (newest-first), else push. */
+  prepend?: boolean
+  /** Seed contents (copied, not aliased). */
+  initial?: T[]
+}): {
+  items: Ref<T[]>
+  upsert: (item: T) => void
+  remove: (keyValue: unknown) => void
+  get: (keyValue: unknown) => T | undefined
+  hydrate: (next: T[]) => void
+  indexOf: (keyValue: unknown) => number
+} {
+  const items = ref<T[]>(opts.initial ? [...opts.initial] : []) as Ref<T[]>
+
+  function indexOf(keyValue: unknown): number {
+    return items.value.findIndex((x) => opts.key(x) === keyValue)
+  }
+
+  function upsert(item: T) {
+    const i = indexOf(opts.key(item))
+    if (i >= 0) items.value[i] = item
+    else if (opts.prepend) items.value.unshift(item)
+    else items.value.push(item)
+  }
+
+  function remove(keyValue: unknown) {
+    const i = indexOf(keyValue)
+    if (i >= 0) items.value.splice(i, 1)
+  }
+
+  function get(keyValue: unknown): T | undefined {
+    const i = indexOf(keyValue)
+    return i >= 0 ? items.value[i] : undefined
+  }
+
+  function hydrate(next: T[]) {
+    items.value = [...next]
+  }
+
+  return { items, upsert, remove, get, hydrate, indexOf }
+}

package/app/stores/documents.ts

@@ -1,5 +1,5 @@
 import { defineStore } from 'pinia'
-import { computed, ref } from 'vue'
+import { ref } from 'vue'
 import type {
   DocumentBoardPlan,
   DocumentConnection,
@@ -8,6 +8,8 @@ import type {
   DocumentSourceKind,
   SourceDocument,
 } from '~/types/domain'
+import { useSourceIntegration } from '~/composables/useSourceIntegration'
+import { useUpsertList } from '~/composables/useUpsertList'
 import { useWorkspaceStore } from '~/stores/workspace'
 
 /**
@@ -24,83 +26,46 @@ export const useDocumentsStore = defineStore('documents', () => {
   const api = useApi()
   const workspace = useWorkspaceStore()
 
-  /** null = unknown (not probed yet), true/false = integration on/off. */
-  const available = ref<boolean | null>(null)
-  /** The configured sources and their connect/import descriptors. */
-  const sources = ref<DocumentSourceDescriptor[]>([])
-  /** Live connections, one per connected source. */
-  const connections = ref<DocumentConnection[]>([])
-  const documents = ref<SourceDocument[]>([])
+  // Shared opt-in / probe / connections lifecycle (see `useSourceIntegration`).
+  const integration = useSourceIntegration<
+    DocumentSourceKind,
+    DocumentConnection,
+    DocumentSourceDescriptor
+  >({
+    enabled: () => !!workspace.workspaceId,
+    fetch: async () => {
+      const [{ sources }, { connections }] = await Promise.all([
+        api.listDocumentSources(workspace.requireId()),
+        api.listDocumentConnections(workspace.requireId()),
+      ])
+      return { sources, connections }
+    },
+  })
+  const { available, sources, connections, connectedSources, anyConnected } = integration
+  const { descriptorFor, connectionFor, isConnected, probe } = integration
+
+  const { items: documents, upsert: upsertDoc } = useUpsertList<SourceDocument>({
+    key: (d) => `${d.source}:${d.externalId}`,
+    prepend: true,
+  })
   const loading = ref(false)
 
-  /** Sources the workspace currently has a live connection to. */
-  const connectedSources = computed(() =>
-    sources.value.filter((s) => connections.value.some((c) => c.source === s.source)),
-  )
-  const anyConnected = computed(() => connections.value.length > 0)
-
-  function descriptorFor(source: DocumentSourceKind): DocumentSourceDescriptor | undefined {
-    return sources.value.find((s) => s.source === source)
-  }
-
-  function connectionFor(source: DocumentSourceKind): DocumentConnection | undefined {
-    return connections.value.find((c) => c.source === source)
-  }
-
-  function isConnected(source: DocumentSourceKind): boolean {
-    return connectionFor(source) !== undefined
-  }
-
   /** Imported documents currently attached to a given block. */
   function docsForBlock(blockId: string): SourceDocument[] {
     return documents.value.filter((d) => d.linkedBlockId === blockId)
   }
 
-  /** Merge a document returned by the backend into the local cache. */
-  function upsertDoc(doc: SourceDocument) {
-    const i = documents.value.findIndex(
-      (d) => d.source === doc.source && d.externalId === doc.externalId,
-    )
-    if (i >= 0) documents.value[i] = doc
-    else documents.value.unshift(doc)
-  }
-
-  function upsertConnection(conn: DocumentConnection) {
-    const i = connections.value.findIndex((c) => c.source === conn.source)
-    if (i >= 0) connections.value[i] = conn
-    else connections.value.push(conn)
-  }
-
-  /** Probe the integration: resolves `available`, the sources and connections. */
-  async function probe() {
-    if (!workspace.workspaceId) return
-    try {
-      const [{ sources: srcs }, { connections: conns }] = await Promise.all([
-        api.listDocumentSources(workspace.requireId()),
-        api.listDocumentConnections(workspace.requireId()),
-      ])
-      available.value = true
-      sources.value = srcs
-      connections.value = conns
-    } catch {
-      // 503 (integration disabled) or any error → hide the UI entry points.
-      available.value = false
-      sources.value = []
-      connections.value = []
-    }
-  }
-
   /** Connect the workspace to a source with its credential bag. */
   async function connect(source: DocumentSourceKind, credentials: Record<string, string>) {
     const conn = await api.connectDocumentSource(workspace.requireId(), source, credentials)
-    upsertConnection(conn)
+    integration.upsertConnection(conn)
     available.value = true
   }
 
   /** Disconnect the workspace from a source. */
   async function disconnect(source: DocumentSourceKind) {
     await api.disconnectDocumentSource(workspace.requireId(), source)
-    connections.value = connections.value.filter((c) => c.source !== source)
+    integration.removeConnection(source)
   }
 
   /** Load the imported documents for the workspace (across sources). */

package/app/stores/notifications.ts

@@ -1,6 +1,7 @@
 import { defineStore } from 'pinia'
-import { computed, ref } from 'vue'
+import { computed } from 'vue'
 import type { Notification } from '~/types/domain'
+import { useUpsertList } from '~/composables/useUpsertList'
 import { useWorkspaceStore } from '~/stores/workspace'
 
 /**
@@ -14,7 +15,11 @@ export const useNotificationsStore = defineStore('notifications', () => {
   const api = useApi()
 
   /** All open notifications, newest-first. */
-  const open = ref<Notification[]>([])
+  const {
+    items: open,
+    upsert: upsertOpen,
+    remove,
+  } = useUpsertList<Notification>({ key: (n) => n.id, prepend: true })
 
   /** Replace the cache from a server snapshot. */
   function hydrate(notifications: Notification[]) {
@@ -28,13 +33,11 @@ export const useNotificationsStore = defineStore('notifications', () => {
    * replaced in place; a resolved one (acted/dismissed) is removed from the inbox.
    */
   function upsert(notification: Notification) {
-    const i = open.value.findIndex((n) => n.id === notification.id)
     if (notification.status !== 'open') {
-      if (i >= 0) open.value.splice(i, 1)
+      remove(notification.id)
       return
     }
-    if (i >= 0) open.value[i] = notification
-    else open.value.unshift(notification)
+    upsertOpen(notification)
   }
 
   /** Open notifications for a given block (for the board card badge). */

package/app/stores/personalSubscriptions.ts

@@ -1,5 +1,6 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
+import { apiErrorEnvelope } from '~/composables/api/errors'
 import type {
   PersonalSubscriptionStatus,
   StorePersonalSubscriptionInput,
@@ -45,7 +46,7 @@ export interface PendingCredential {
 export function parseCredentialError(
   error: unknown,
 ): { vendor: SubscriptionVendor; reason: PendingCredential['reason'] } | null {
-  const data = (error as { data?: { error?: { code?: string; details?: unknown } } })?.data?.error
+  const data = apiErrorEnvelope(error)
   if (data?.code !== 'credential_required') return null
   const details = data.details as {
     vendor?: SubscriptionVendor

package/app/stores/tasks.ts

@@ -8,6 +8,8 @@ import type {
   TaskSourceKind,
   TaskSourceState,
 } from '~/types/domain'
+import { useSourceIntegration } from '~/composables/useSourceIntegration'
+import { useUpsertList } from '~/composables/useUpsertList'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { useBoardStore } from '~/stores/board'
 
@@ -27,95 +29,42 @@ export const useTasksStore = defineStore('tasks', () => {
   const api = useApi()
   const workspace = useWorkspaceStore()
 
-  /** null = unknown (not probed yet), true/false = integration on/off. */
-  const available = ref<boolean | null>(null)
-  /**
-   * Why the last probe failed, when it did — captured (rather than swallowed) so
-   * the settings panel can explain *why* nothing is surfaced (integration disabled
-   * vs a server/backend error) instead of a blanket "install integration first".
-   */
-  const probeError = ref<{ status: number | null; message: string } | null>(null)
-  /** The configured sources, each with its descriptor + per-workspace state (available + enabled). */
-  const sources = ref<TaskSourceState[]>([])
-  /** Live connections, one per connected (credentialed) source. */
-  const connections = ref<TaskConnection[]>([])
-  const tasks = ref<SourceTask[]>([])
+  // Shared opt-in / probe / connections lifecycle (see `useSourceIntegration`). Its
+  // `probeError` is what lets the settings panel explain *why* nothing is surfaced
+  // (integration disabled vs a server/backend error) instead of "install it first".
+  const integration = useSourceIntegration<TaskSourceKind, TaskConnection, TaskSourceState>({
+    enabled: () => !!workspace.workspaceId,
+    fetch: async () => {
+      const [{ sources }, { connections }] = await Promise.all([
+        api.listTaskSources(workspace.requireId()),
+        api.listTaskConnections(workspace.requireId()),
+      ])
+      return { sources, connections }
+    },
+  })
+  const { available, probeError, sources, connections, connectedSources, anyConnected } =
+    integration
+  const { descriptorFor, connectionFor, isConnected, probe } = integration
+
+  const { items: tasks, upsert: upsertTask } = useUpsertList<SourceTask>({
+    key: (t) => `${t.source}:${t.externalId}`,
+    prepend: true,
+  })
   /** The last live setup-check verdict per source (from `checkSetup`). */
   const diagnostics = ref<Partial<Record<TaskSourceKind, TaskSourceDiagnostic>>>({})
   /** The source currently running a setup check, if any. */
   const checking = ref<TaskSourceKind | null>(null)
   const loading = ref(false)
 
-  /** Sources the workspace currently has a live connection to. */
-  const connectedSources = computed(() =>
-    sources.value.filter((s) => connections.value.some((c) => c.source === s.source)),
-  )
-  const anyConnected = computed(() => connections.value.length > 0)
-
   /** Sources offered for import: available (connected / App installed) AND enabled. */
   const offeredSources = computed(() => sources.value.filter((s) => s.available && s.enabled))
   const anyOffered = computed(() => offeredSources.value.length > 0)
 
-  function descriptorFor(source: TaskSourceKind): TaskSourceState | undefined {
-    return sources.value.find((s) => s.source === source)
-  }
-
-  function connectionFor(source: TaskSourceKind): TaskConnection | undefined {
-    return connections.value.find((c) => c.source === source)
-  }
-
-  function isConnected(source: TaskSourceKind): boolean {
-    return connectionFor(source) !== undefined
-  }
-
   /** Imported issues currently attached to a given block. */
   function tasksForBlock(blockId: string): SourceTask[] {
     return tasks.value.filter((t) => t.linkedBlockId === blockId)
   }
 
-  /** Merge an issue returned by the backend into the local cache. */
-  function upsertTask(task: SourceTask) {
-    const i = tasks.value.findIndex(
-      (t) => t.source === task.source && t.externalId === task.externalId,
-    )
-    if (i >= 0) tasks.value[i] = task
-    else tasks.value.unshift(task)
-  }
-
-  function upsertConnection(conn: TaskConnection) {
-    const i = connections.value.findIndex((c) => c.source === conn.source)
-    if (i >= 0) connections.value[i] = conn
-    else connections.value.push(conn)
-  }
-
-  /** Probe the integration: resolves `available`, the sources and connections. */
-  async function probe() {
-    if (!workspace.workspaceId) return
-    try {
-      const [{ sources: srcs }, { connections: conns }] = await Promise.all([
-        api.listTaskSources(workspace.requireId()),
-        api.listTaskConnections(workspace.requireId()),
-      ])
-      available.value = true
-      probeError.value = null
-      sources.value = srcs
-      connections.value = conns
-    } catch (e) {
-      // 503 (integration disabled) or any error → hide the UI entry points, but keep
-      // the reason so the settings panel can explain it (a 503 is "turned off on this
-      // deployment"; a 500 is "the backend errored — e.g. a migration isn't applied").
-      available.value = false
-      const err = e as { statusCode?: number; data?: { error?: { message?: string } } }
-      const serverMessage = err?.data?.error?.message
-      probeError.value = {
-        status: err?.statusCode ?? null,
-        message: serverMessage || (e instanceof Error ? e.message : String(e)),
-      }
-      sources.value = []
-      connections.value = []
-    }
-  }
-
   /**
    * Run a live setup check for a source (authenticate + read), caching the verdict
    * so the panel can show exactly what's wrong (missing App / wrong token / lacking
@@ -137,14 +86,14 @@ export const useTasksStore = defineStore('tasks', () => {
   /** Connect the workspace to a source with its credential bag. */
   async function connect(source: TaskSourceKind, credentials: Record<string, string>) {
     const conn = await api.connectTaskSource(workspace.requireId(), source, credentials)
-    upsertConnection(conn)
+    integration.upsertConnection(conn)
     available.value = true
   }
 
   /** Disconnect the workspace from a source. */
   async function disconnect(source: TaskSourceKind) {
     await api.disconnectTaskSource(workspace.requireId(), source)
-    connections.value = connections.value.filter((c) => c.source !== source)
+    integration.removeConnection(source)
   }
 
   /** Enable or disable a source for the workspace (the per-workspace toggle). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.37.0",
+  "version": "0.37.2",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -32,7 +32,7 @@
     "pinia-plugin-persistedstate": "^4.7.1",
     "vue": "^3.5.38",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.35.0"
+    "@cat-factory/contracts": "0.36.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.1",