@cat-factory/app 0.6.0

package/app/stores/clarity.ts

@@ -0,0 +1,196 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { ClarityReview, ResolveClarityExceededChoice, ReviewItemStatus } from '~/types/clarity'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * Clarity-review state. On the pipeline path the reviewer runs as the first gate
+ * step: the run parks while the human answers/dismisses findings about the bug report,
+ * then asks to incorporate. Incorporation + the re-review run ASYNCHRONOUSLY in the
+ * durable driver — the call returns at once (status `incorporating`) and the user goes
+ * back to the board; they are summoned again (a notification) only if the re-review
+ * yields findings or hits the cap. The store is patched both from call responses and
+ * from live `clarity` stream events (see `upsert`). `available` mirrors the backend's
+ * opt-in gate (a 503 hides the UI). Per-workspace; nothing is persisted client-side.
+ */
+export const useClarityStore = defineStore('clarity', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+
+  /** null = unknown (not probed), true/false = feature on/off. */
+  const available = ref<boolean | null>(null)
+  /** The current review per block id (null = fetched, none exists). */
+  const reviews = ref<Record<string, ClarityReview | null>>({})
+  /** Block ids whose reviewer is currently running (review / re-review). */
+  const reviewing = ref<Set<string>>(new Set())
+  /** Review ids currently incorporating their answers. */
+  const incorporating = ref<Set<string>>(new Set())
+  /** Block ids whose current review is being fetched (the initial `load`). */
+  const loadingByBlock = ref<Set<string>>(new Set())
+  /**
+   * In-flight `load()` promises keyed by block id, so concurrent callers for the same
+   * block (the inspector's badge watch + the review window opening together) share ONE
+   * request instead of each firing its own. Plain Map — internal bookkeeping, not
+   * reactive. Cleared once the request settles.
+   */
+  const inFlight = new Map<string, Promise<void>>()
+
+  function reviewFor(blockId: string): ClarityReview | null {
+    return reviews.value[blockId] ?? null
+  }
+  /**
+   * The async background stage a block's review is in, or null. While the driver folds the
+   * answers (`incorporating`) then re-reviews the document (`reviewing`), NO human action is
+   * needed — so the board suppresses the "Approval needed" gate and shows this working state
+   * instead, with copy that names which of the two stages is running.
+   */
+  function backgroundStage(blockId: string): 'incorporating' | 'reviewing' | null {
+    const status = reviews.value[blockId]?.status
+    return status === 'incorporating' || status === 'reviewing' ? status : null
+  }
+  function isReviewing(blockId: string): boolean {
+    return reviewing.value.has(blockId)
+  }
+  function isLoading(blockId: string): boolean {
+    return loadingByBlock.value.has(blockId)
+  }
+  function isIncorporating(reviewId: string): boolean {
+    return incorporating.value.has(reviewId)
+  }
+
+  /** Findings still needing a human (status `open`). */
+  function openCount(review: ClarityReview): number {
+    return review.items.filter((i) => i.status === 'open').length
+  }
+  /** Findings the human answered (a reply recorded), which the companion folds in. */
+  function answeredCount(review: ClarityReview): number {
+    return review.items.filter((i) => i.status === 'answered' || i.status === 'resolved').length
+  }
+  /** Every finding is settled (answered or dismissed) — none still open. */
+  function allSettled(review: ClarityReview): boolean {
+    return openCount(review) === 0
+  }
+  /** Incorporation is possible: all findings settled AND at least one was answered. */
+  function canIncorporate(review: ClarityReview): boolean {
+    return allSettled(review) && answeredCount(review) > 0
+  }
+  /** Proceed (skip the companion) is possible: all findings settled but none answered. */
+  function canProceed(review: ClarityReview): boolean {
+    return allSettled(review) && answeredCount(review) === 0
+  }
+
+  function store(review: ClarityReview) {
+    reviews.value = { ...reviews.value, [review.blockId]: review }
+  }
+
+  function withFlag(set: typeof reviewing, key: string, on: boolean) {
+    const next = new Set(set.value)
+    if (on) next.add(key)
+    else next.delete(key)
+    set.value = next
+  }
+
+  /** Fetch the current review for a block (probing the feature's availability). */
+  async function load(blockId: string) {
+    if (!workspace.workspaceId) return
+    // Coalesce overlapping loads of the same block onto a single request.
+    const pending = inFlight.get(blockId)
+    if (pending) return pending
+    const promise = (async () => {
+      withFlag(loadingByBlock, blockId, true)
+      try {
+        const review = await api.getClarityReview(workspace.requireId(), blockId)
+        available.value = true
+        reviews.value = { ...reviews.value, [blockId]: review }
+      } catch {
+        // 503 (feature off) or any error → hide the UI entry points.
+        available.value = false
+      } finally {
+        withFlag(loadingByBlock, blockId, false)
+        inFlight.delete(blockId)
+      }
+    })()
+    inFlight.set(blockId, promise)
+    return promise
+  }
+
+  /** Record a human's answer to one item. */
+  async function reply(review: ClarityReview, itemId: string, text: string) {
+    store(await api.replyClarityItem(workspace.requireId(), review.id, itemId, text))
+  }
+
+  /** Set an item's status (dismiss / reopen). */
+  async function setItemStatus(review: ClarityReview, itemId: string, status: ReviewItemStatus) {
+    store(await api.setClarityItemStatus(workspace.requireId(), review.id, itemId, status))
+  }
+
+  /**
+   * Ask the driver to incorporate the answers ASYNCHRONOUSLY. Optional `feedback` is the "do
+   * it differently" direction when redoing a merge. Returns at once with the `incorporating`
+   * review (the fold + re-review run in the background); the caller returns the user to the
+   * board. A live `clarity` event / a notification reflects the outcome later.
+   */
+  async function incorporate(review: ClarityReview, feedback?: string) {
+    withFlag(incorporating, review.id, true)
+    try {
+      const updated = await api.incorporateClarity(workspace.requireId(), review.blockId, feedback)
+      store(updated)
+      return updated
+    } finally {
+      withFlag(incorporating, review.id, false)
+    }
+  }
+
+  /** Re-review the clarified report (one more reviewer pass; may converge/advance). */
+  async function reReview(blockId: string): Promise<ClarityReview> {
+    withFlag(reviewing, blockId, true)
+    try {
+      const updated = await api.reReviewClarity(workspace.requireId(), blockId)
+      store(updated)
+      return updated
+    } finally {
+      withFlag(reviewing, blockId, false)
+    }
+  }
+
+  /** Proceed: settle the clarity review and advance the parked run. */
+  async function proceed(blockId: string): Promise<ClarityReview> {
+    const updated = await api.proceedClarity(workspace.requireId(), blockId)
+    store(updated)
+    return updated
+  }
+
+  /** Resolve a capped review: extra-round / proceed / stop-reset. */
+  async function resolveExceeded(
+    blockId: string,
+    choice: ResolveClarityExceededChoice,
+  ): Promise<ClarityReview> {
+    const updated = await api.resolveClarityExceeded(workspace.requireId(), blockId, choice)
+    store(updated)
+    return updated
+  }
+
+  return {
+    available,
+    reviews,
+    reviewFor,
+    backgroundStage,
+    isReviewing,
+    isLoading,
+    isIncorporating,
+    openCount,
+    answeredCount,
+    allSettled,
+    canIncorporate,
+    canProceed,
+    load,
+    reply,
+    setItemStatus,
+    incorporate,
+    reReview,
+    proceed,
+    resolveExceeded,
+    // Patch the cache from a live `clarity` stream event.
+    upsert: store,
+  }
+})

package/app/stores/consensus.ts

@@ -0,0 +1,60 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { ConsensusSession } from '~/types/consensus'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * Consensus session state. A consensus-enabled step runs a multi-model process (panel /
+ * debate / ranked voting); its transcript is pushed live via the `consensus` stream event
+ * and patched here by `upsert`. The dedicated window loads the latest session for a block
+ * on open (`load`) so a reload shows a completed session. Per-workspace; nothing persisted
+ * client-side.
+ */
+export const useConsensusStore = defineStore('consensus', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+
+  /** The latest session per block id (null = fetched, none exists / consensus off). */
+  const sessions = ref<Record<string, ConsensusSession | null>>({})
+  /** Block ids whose session is currently being fetched. */
+  const loading = ref<Set<string>>(new Set())
+
+  function sessionFor(blockId: string): ConsensusSession | null {
+    return sessions.value[blockId] ?? null
+  }
+
+  function isLoading(blockId: string): boolean {
+    return loading.value.has(blockId)
+  }
+
+  function store(session: ConsensusSession) {
+    sessions.value = { ...sessions.value, [session.blockId]: session }
+  }
+
+  /** Patch the cache from a live `consensus` stream event (newest wins per block). */
+  function upsert(session: ConsensusSession) {
+    const existing = sessions.value[session.blockId]
+    // Keep the freshest by updatedAt so out-of-order pushes don't regress the transcript.
+    if (existing && existing.id === session.id && existing.updatedAt > session.updatedAt) return
+    store(session)
+  }
+
+  /** Load the latest session for a block (window open / reload). Best-effort. */
+  async function load(blockId: string): Promise<void> {
+    const wsId = workspace.workspaceId
+    if (!wsId) return
+    loading.value = new Set(loading.value).add(blockId)
+    try {
+      const { session } = await api.getConsensusSession(wsId, blockId)
+      sessions.value = { ...sessions.value, [blockId]: session }
+    } catch {
+      // Consensus off / no session — leave the cache as-is; the window shows its empty state.
+    } finally {
+      const next = new Set(loading.value)
+      next.delete(blockId)
+      loading.value = next
+    }
+  }
+
+  return { sessions, sessionFor, isLoading, load, upsert }
+})

package/app/stores/documents.ts

@@ -0,0 +1,176 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import type {
+  DocumentBoardPlan,
+  DocumentConnection,
+  DocumentSearchResult,
+  DocumentSourceDescriptor,
+  DocumentSourceKind,
+  SourceDocument,
+} from '~/types/domain'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * Document-source integration state: the sources the backend offers (and their
+ * connect metadata), the workspace's per-source connections, and the pages it
+ * has imported — plus the actions that connect/import/plan/spawn/link against the
+ * backend. `available` mirrors the backend's opt-in gate: a 503 from the source
+ * probe means the integration is off, and the UI hides its entry points (just as
+ * `auth.required` gates the login UI). The abstraction is source-agnostic; every
+ * action is keyed by a `DocumentSourceKind`. Per-workspace, like the board
+ * itself; nothing is persisted client-side.
+ */
+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[]>([])
+  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)
+    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)
+  }
+
+  /** Load the imported documents for the workspace (across sources). */
+  async function loadDocuments() {
+    documents.value = await api.listDocuments(workspace.requireId())
+  }
+
+  /** Import (fetch + persist) a page by id or URL from a source. */
+  async function importDocument(source: DocumentSourceKind, ref: string): Promise<SourceDocument> {
+    loading.value = true
+    try {
+      const doc = await api.importDocument(workspace.requireId(), source, { ref })
+      upsertDoc(doc)
+      return doc
+    } finally {
+      loading.value = false
+    }
+  }
+
+  /** Search a connected source's catalogue by free text (title/content). */
+  async function search(
+    source: DocumentSourceKind,
+    query: string,
+  ): Promise<DocumentSearchResult[]> {
+    const { results } = await api.searchDocumentSource(workspace.requireId(), source, query)
+    return results
+  }
+
+  /** Preview the board structure a page would expand into (no writes). */
+  function plan(source: DocumentSourceKind, externalId: string): Promise<DocumentBoardPlan> {
+    return api.planDocument(workspace.requireId(), source, externalId)
+  }
+
+  /** Apply a page's structure to the board, then refresh the board snapshot. */
+  async function spawn(source: DocumentSourceKind, externalId: string, frameId?: string) {
+    const { result } = await api.spawnDocument(workspace.requireId(), source, {
+      externalId,
+      frameId,
+    })
+    await workspace.refresh()
+    return result
+  }
+
+  /** Attach an imported page to a block as agent context. */
+  async function linkToBlock(blockId: string, source: DocumentSourceKind, externalId: string) {
+    const doc = await api.linkDocument(workspace.requireId(), { source, externalId, blockId })
+    upsertDoc(doc)
+    return doc
+  }
+
+  return {
+    available,
+    sources,
+    connections,
+    documents,
+    loading,
+    connectedSources,
+    anyConnected,
+    descriptorFor,
+    connectionFor,
+    isConnected,
+    docsForBlock,
+    probe,
+    connect,
+    disconnect,
+    loadDocuments,
+    importDocument,
+    search,
+    plan,
+    spawn,
+    linkToBlock,
+  }
+})