@cat-factory/app 0.37.0 → 0.37.1

package/app/composables/useSourceIntegration.ts

@@ -0,0 +1,107 @@
+import { type ComputedRef, type Ref, computed, ref } from 'vue'
+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 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 = []
+    }
+  }
+
+  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/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.1",
   "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",