@cat-factory/app 0.234.2 → 0.236.0

package/app/composables/useContextLinking.spec.ts

@@ -85,6 +85,101 @@ describe('contextKey', () => {
   })
 })
 
+describe('resolvePending', () => {
+  // Fetching an attachment moved AHEAD of the create: an unreachable page is a correction the
+  // user can still make with the form open, where the same failure afterwards leaves a task
+  // carrying context it never got. These pin the two halves that makes load-bearing: what the
+  // host gets back, and that one bad attachment does not hide a second one.
+  function stub(
+    importDocument: (source: string, ref: string) => Promise<{ externalId: string }>,
+    importTask: (
+      source: string,
+      ref: string,
+    ) => Promise<{
+      externalId: string
+      description: string
+    }> = async () => ({ externalId: 'T-1', description: '' }),
+  ) {
+    vi.stubGlobal('useDocumentsStore', () => ({ importDocument }))
+    vi.stubGlobal('useTasksStore', () => ({ importTask }))
+    vi.stubGlobal('useWorkspaceStore', () => ({ workspaceId: 'ws_1' }))
+    vi.stubGlobal('useToast', () => ({ add: vi.fn() }))
+    vi.stubGlobal('useI18n', () => ({ t: (key: string) => key }))
+    vi.stubGlobal('useCopyToClipboard', () => ({ copyAction: () => ({ label: 'copy' }) }))
+  }
+
+  afterEach(() => vi.unstubAllGlobals())
+
+  it('imports what needs it and hands back items the later link can use directly', async () => {
+    stub(async (_source, ref) => ({ externalId: `resolved:${ref}` }))
+    const already = item({ externalId: 'acme/repo:docs/done.md', needsImport: false })
+
+    const { resolved, failures } = await useContextLinking().resolvePending([item(), already])
+
+    expect(failures).toEqual([])
+    // The import's own canonical id is carried forward, not the pasted ref, and the flag flips so
+    // `linkPending` links rather than re-fetching.
+    expect(resolved.map((c) => [c.externalId, c.needsImport])).toEqual([
+      ['resolved:acme/repo:docs/x.md', false],
+      ['acme/repo:docs/done.md', false],
+    ])
+  })
+
+  it('reports EVERY failure and keeps the failed item staged', async () => {
+    stub(async (_source, ref) => {
+      throw new Error(`no access to ${ref}`)
+    })
+    const a = item({ externalId: 'acme/repo:a.md' })
+    const b = item({ externalId: 'acme/repo:b.md' })
+
+    const { resolved, failures } = await useContextLinking().resolvePending([a, b])
+
+    // Both, not just the first: fixing them one round-trip at a time is the failure mode.
+    expect(failures.map((f) => f.item.externalId)).toEqual(['acme/repo:a.md', 'acme/repo:b.md'])
+    expect(failures[0]!.message).toContain('no access to acme/repo:a.md')
+    // Still staged and still unresolved: the host aborts the create, so dropping them here would
+    // silently discard attachments the user asked for while they are fixing them.
+    expect(resolved.map((c) => c.needsImport)).toEqual([true, true])
+    // And MARKED, so the form the user is still looking at names which chip refused. The toast
+    // names them too, but the toast is gone by the time they go looking for the one to remove.
+    expect(resolved.map((c) => c.unreadable)).toEqual([
+      'no access to acme/repo:a.md',
+      'no access to acme/repo:b.md',
+    ])
+  })
+
+  it('clears a stale unreadable mark once the item does resolve', async () => {
+    // A prior failure is not a standing verdict: leaving the mark on a page that has just been
+    // fetched accuses a good attachment (and the retry is the whole point of keeping it staged).
+    stub(async (_source, ref) => ({ externalId: `resolved:${ref}` }))
+    const previouslyFailed = item({ unreadable: 'GitHub denied access (HTTP 403).' })
+
+    const { resolved } = await useContextLinking().resolvePending([previouslyFailed])
+
+    expect(resolved[0]!.unreadable).toBeUndefined()
+    expect(resolved[0]!.needsImport).toBe(false)
+  })
+
+  it("carries an imported issue's description forward, not just its id", async () => {
+    // The add-task form composes the saved description from these items on the very next statement
+    // (`linkedIssueBodies`), so an import that fetched the body and dropped it produced a task
+    // silently missing the issue text it was created from, with the bytes in hand at that moment.
+    stub(
+      async (_source, ref) => ({ externalId: ref }),
+      async () => ({ externalId: 'ENG-42', description: 'Steps to reproduce: …' }),
+    )
+    const issue = item({ kind: 'task', externalId: 'ENG-42', title: 'ENG-42 · Crash' })
+
+    const { resolved } = await useContextLinking().resolvePending([issue])
+
+    expect(resolved[0]).toMatchObject({
+      externalId: 'ENG-42',
+      needsImport: false,
+      description: 'Steps to reproduce: …',
+    })
+  })
+})
+
 describe('presentLinkFailures', () => {
   // Stub the Nuxt auto-imports `useContextLinking` pulls in, so the toast-orchestration
   // side of the composable can be exercised without a full Nuxt runtime.

package/app/composables/useContextLinking.ts

@@ -29,6 +29,17 @@ export interface PendingContext {
   description?: string
   /** True when the item must be imported before it can be linked. */
   needsImport: boolean
+  /**
+   * Why this item could not be FETCHED, when an attempt has already failed (the server's own
+   * message). Set by {@link useContextLinking.resolvePending} and by the add-task form's body
+   * pre-fetch; cleared the moment a later attempt succeeds.
+   *
+   * It exists because the fetch moved ahead of the create: a failure now costs the user the
+   * create, so the item that caused it has to be identifiable ON the form they are still looking
+   * at, not only in the toast that named it. A tracker issue has no pre-flight of its own, so this
+   * is the whole of its warning.
+   */
+  unreadable?: string
 }
 
 /**
@@ -114,6 +125,70 @@ export function useContextLinking() {
   const { t } = useI18n()
   const { copyAction } = useCopyToClipboard()
 
+  /**
+   * Import every pending item that still needs it, BEFORE the block exists.
+   *
+   * The fetch against the external source is the half of attaching that actually fails (a page
+   * that moved, a token without access, a source that is down), and it needs no block id. Running
+   * it after the block was created therefore bought nothing and cost the user their chance to fix
+   * it: the task existed, carrying context it had not got. Run here, a failure is a correction
+   * the host can ask for with the form still open and the reference still editable.
+   *
+   * Returns the items with what succeeded folded in (`needsImport: false`, so the later
+   * {@link linkPending} links them directly), alongside the failures. The batch is NOT aborted on
+   * the first failure: one unreachable page must not hide a second one, or the user fixes them
+   * one round-trip at a time.
+   *
+   * What "folded in" covers is the whole point of running this before the create, so it is more
+   * than the id: a tracker issue's own DESCRIPTION arrives with the import, and the add-task form
+   * composes the saved description from exactly these items on the next statement. Keeping only
+   * the id dropped a body the platform had in hand at the one moment it was needed.
+   */
+  async function resolvePending(
+    items: PendingContext[],
+  ): Promise<{ resolved: PendingContext[]; failures: LinkFailure[] }> {
+    const failures: LinkFailure[] = []
+    const resolved: PendingContext[] = []
+    for (const item of items) {
+      if (!item.needsImport) {
+        resolved.push(item)
+        continue
+      }
+      try {
+        resolved.push(await importPending(item))
+      } catch (e) {
+        const failure = describeLinkFailure(item, e)
+        failures.push(failure)
+        // Kept in the list, still unresolved: the host aborts on any failure, and dropping the
+        // item here would silently discard an attachment the user asked for while they fix it.
+        // Marked, so the form the user is still looking at names WHICH attachment refused.
+        resolved.push({ ...item, unreadable: failure.message })
+      }
+    }
+    return { resolved, failures }
+  }
+
+  /** Fetch one pending item, folding everything the import answers back onto it. */
+  async function importPending(item: PendingContext): Promise<PendingContext> {
+    // `unreadable` is dropped rather than preserved: a prior failure is not a standing verdict, and
+    // leaving the mark on a page that has just been fetched would accuse a good attachment.
+    const { unreadable: _cleared, ...rest } = item
+    if (item.kind === 'document') {
+      const doc = await documents.importDocument(item.source as DocumentSourceKind, item.externalId)
+      return { ...rest, externalId: doc.externalId, needsImport: false }
+    }
+    const task = await tasks.importTask(item.source as TaskSourceKind, item.externalId)
+    return {
+      ...rest,
+      externalId: task.externalId,
+      needsImport: false,
+      // The body reaches the created task through the host's description composition, which reads
+      // `description` off these items: an import that fetched it and did not carry it forward is a
+      // task silently missing the issue text it was created from.
+      ...(task.description.trim() ? { description: task.description } : {}),
+    }
+  }
+
   /**
    * Import (when needed) then link every pending item to `blockId`. Each failure
    * is captured with its actual cause rather than aborting the batch, so one bad
@@ -137,25 +212,31 @@ export function useContextLinking() {
           await tasks.linkToBlock(blockId, source, externalId)
         }
       } catch (e) {
-        // Never swallow the cause: capture the server's own message + status/code/details
-        // so the toast can name the specific reason and the copy affordance can carry the
-        // full context (incl. the upstream GitHub status the backend puts on `details`).
-        const envelope = apiErrorEnvelope(e)
-        failures.push({
-          item,
-          message: e instanceof Error ? e.message : String(e),
-          status: apiErrorStatus(e),
-          code: envelope?.code,
-          details:
-            envelope?.details && typeof envelope.details === 'object'
-              ? (envelope.details as Record<string, unknown>)
-              : undefined,
-        })
+        failures.push(describeLinkFailure(item, e))
       }
     }
     return failures
   }
 
+  /**
+   * Never swallow the cause: capture the server's own message + status/code/details so the toast
+   * can name the specific reason and the copy affordance can carry the full context (incl. the
+   * upstream GitHub status the backend puts on `details`).
+   */
+  function describeLinkFailure(item: PendingContext, e: unknown): LinkFailure {
+    const envelope = apiErrorEnvelope(e)
+    return {
+      item,
+      message: e instanceof Error ? e.message : String(e),
+      status: apiErrorStatus(e),
+      code: envelope?.code,
+      details:
+        envelope?.details && typeof envelope.details === 'object'
+          ? (envelope.details as Record<string, unknown>)
+          : undefined,
+    }
+  }
+
   /**
    * Surface link failures as a single actionable toast: the specific per-item
    * reasons as the body, and a "Copy details" action that puts the full diagnostic
@@ -209,5 +290,5 @@ export function useContextLinking() {
     })
   }
 
-  return { linkPending, presentLinkFailures }
+  return { resolvePending, linkPending, presentLinkFailures }
 }

package/app/composables/useWorkspaceStream.ts

@@ -1,6 +1,10 @@
 import { ref, onScopeDispose } from 'vue'
 import type { WorkspaceEvent } from '~/types/domain'
 import { wsOriginFor } from '~/utils/apiOrigin'
+import {
+  applyWorkspaceEvent,
+  type WorkspaceEventTargets,
+} from '~/composables/workspaceStream/applyWorkspaceEvent'
 
 /**
  * Subscribes to the backend's per-workspace WebSocket event stream and keeps the
@@ -8,11 +12,11 @@ import { wsOriginFor } from '~/utils/apiOrigin'
  * once (e.g. on the board page) after the workspace is ready.
  *
  * `execution` events patch the run + its block directly; `bootstrap` events patch
- * a repo-bootstrap run + its service frame (live "bootstrapping…" progress); the
- * coarse `board` event (module materialised, run cancelled) triggers a debounced
- * full refresh. On every (re)connect we refresh once to reconcile anything missed
- * while disconnected, so the server stays the source of truth and a dropped socket
- * self-heals.
+ * a repo-bootstrap run + its service frame (live "bootstrapping…" progress); a
+ * `board` event patches the block it carries, or triggers a debounced full refresh when it
+ * carries none (a removal, a reparent, a service-frame change). On every (re)connect we refresh
+ * once to reconcile anything missed while disconnected, so the server stays the source of truth
+ * and a dropped socket self-heals. Routing lives in {@link applyWorkspaceEvent}.
  */
 export function useWorkspaceStream() {
   const workspace = useWorkspaceStore()
@@ -81,6 +85,27 @@ export function useWorkspaceStream() {
     boardDebounce = setTimeout(() => void refreshWithRetry(workspaceId), 300)
   }
 
+  // The stores this stream feeds, bound once. Routing lives in `applyWorkspaceEvent` so the
+  // targeted-vs-coarse decision on a `board` event is unit-testable without a socket.
+  const targets: WorkspaceEventTargets = {
+    upsertExecution: (instance) => execution.upsert(instance),
+    upsertBlock: (block) => board.upsert(block),
+    upsertBootstrap: (job) => agentRuns.upsertBootstrap(job),
+    upsertEnvConfigRepair: (job) => agentRuns.upsertEnvConfigRepair(job),
+    upsertEnvironmentTest: (run) => environmentTest.upsert(run),
+    patchInfraSetup: (area, status, detail) => workspace.patchInfraSetup(area, status, detail),
+    upsertNotification: (n) => notifications.upsert(n),
+    appendLlmCall: (call) => observability.appendCall(call),
+    upsertRequirements: (r) => requirements.upsert(r),
+    upsertConsensus: (s) => consensus.upsert(s),
+    upsertClarity: (r) => clarity.upsert(r),
+    upsertBrainstorm: (s) => brainstorm.upsert(s),
+    upsertKaizen: (g) => kaizen.upsert(g),
+    upsertInitiative: (i) => initiatives.upsert(i),
+    upsertDocInterview: (s) => docInterview.upsert(s),
+    refreshBoard: () => debouncedBoardRefresh(),
+  }
+
   function onMessage(raw: string) {
     let event: WorkspaceEvent
     try {
@@ -88,78 +113,7 @@ export function useWorkspaceStream() {
     } catch {
       return
     }
-    if (event.type === 'execution') {
-      // Full instance drives the step-level UI; agentRuns derives its coarse
-      // failure/retry summary from the same store, so no extra call is needed.
-      execution.upsert(event.instance)
-      if (event.block) board.upsert(event.block)
-    } else if (event.type === 'board') {
-      debouncedBoardRefresh()
-    } else if (event.type === 'bootstrap') {
-      // Patch the run's live status/subtasks and its provisional/linked frame so
-      // the "bootstrapping…" card updates in place (then flips to a ready service
-      // or a failed badge) without a full refresh.
-      agentRuns.upsertBootstrap(event.job)
-      if (event.block) board.upsert(event.block)
-    } else if (event.type === 'env-config-repair') {
-      // A provider config-repair run advanced — patch its live status/subtasks/outcome so
-      // the infrastructure-providers window's "repairing…" indicator updates in place
-      // (then flips to ok / residual issues / a failure) without a refetch. No board block.
-      agentRuns.upsertEnvConfigRepair(event.job)
-    } else if (event.type === 'envTest') {
-      // An ephemeral-environment self-test advanced a stage — patch the run so the service
-      // inspector's "Test environment creation" control shows the live stage + final
-      // outcome in place without a refetch. No board block.
-      environmentTest.upsert(event.run)
-    } else if (event.type === 'infraSetup') {
-      // The reachability watcher found a configured infrastructure area dead (or answering again) —
-      // patch that one area so the setup banner appears/clears immediately. A full refresh would
-      // pay the whole snapshot aggregate for a one-field delta, and the projection the snapshot
-      // recomputes already folds the same recorded state.
-      workspace.patchInfraSetup(event.area, event.status, event.detail)
-    } else if (event.type === 'notification') {
-      // A PR needs a merge decision, a pipeline finished, or CI gave up — patch the
-      // inbox + per-block badge in place (resolved ones drop out of the inbox).
-      notifications.upsert(event.notification)
-    } else if (event.type === 'llmCall') {
-      // A container agent just made a model call — fold the compact summary into the
-      // observability store so an open "Model activity" panel updates live (and keeps
-      // updating even when the durable driver is evicted: the proxy emits these
-      // independently of the run's poll loop).
-      observability.appendCall(event.call)
-    } else if (event.type === 'requirements') {
-      // The async incorporate + re-review cycle changed a review's status — patch the cache
-      // so an open review window / inspector reflects it live ("incorporating…" → the next
-      // cycle / converged). The summons back, when needed, arrives as a `notification`.
-      requirements.upsert(event.review)
-    } else if (event.type === 'consensus') {
-      // A consensus session advanced (a round landed, the synthesis completed, or it
-      // failed) — patch the cache so an open Consensus Session window renders the
-      // multi-model process live, round by round.
-      consensus.upsert(event.session)
-    } else if (event.type === 'clarity') {
-      // The async incorporate + re-review cycle changed a clarity review's status — patch the
-      // cache so an open review window / inspector reflects it live ("incorporating…" → the
-      // next cycle / converged). The summons back, when needed, arrives as a `notification`.
-      clarity.upsert(event.review)
-    } else if (event.type === 'brainstorm') {
-      // The async incorporate + re-run cycle changed a brainstorm session's status — patch the
-      // cache so an open brainstorm window / inspector reflects it live.
-      brainstorm.upsert(event.session)
-    } else if (event.type === 'kaizen') {
-      // A post-run Kaizen grading was scheduled, started or completed — fold it into the
-      // run cache (so an open run window shows scheduled→running→complete live) and the
-      // Kaizen screen history. Never surfaced on the board.
-      kaizen.upsert(event.grading)
-    } else if (event.type === 'initiative') {
-      // An initiative changed (created, plan ingested, an item settled) — patch the cache
-      // so an open tracker window / the board card reflects the transition live.
-      initiatives.upsert(event.initiative)
-    } else if (event.type === 'docInterview') {
-      // The interactive document interview advanced (a fresh batch of questions, an answer, or
-      // convergence) — patch the cache so an open interview window reflects it live.
-      docInterview.upsert(event.session)
-    }
+    applyWorkspaceEvent(event, targets)
   }
 
   async function connect() {

package/app/composables/workspaceStream/applyWorkspaceEvent.spec.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { Block, WorkspaceEvent } from '~/types/domain'
+import {
+  applyWorkspaceEvent,
+  type WorkspaceEventTargets,
+} from '~/composables/workspaceStream/applyWorkspaceEvent'
+
+function targets(): WorkspaceEventTargets & { calls: string[] } {
+  const calls: string[] = []
+  const record =
+    <T extends unknown[]>(name: string) =>
+    (...args: T) => {
+      void args
+      calls.push(name)
+    }
+  return {
+    calls,
+    upsertExecution: record('upsertExecution'),
+    upsertBlock: record('upsertBlock'),
+    upsertBootstrap: record('upsertBootstrap'),
+    upsertEnvConfigRepair: record('upsertEnvConfigRepair'),
+    upsertEnvironmentTest: record('upsertEnvironmentTest'),
+    patchInfraSetup: record('patchInfraSetup'),
+    upsertNotification: record('upsertNotification'),
+    appendLlmCall: record('appendLlmCall'),
+    upsertRequirements: record('upsertRequirements'),
+    upsertConsensus: record('upsertConsensus'),
+    upsertClarity: record('upsertClarity'),
+    upsertBrainstorm: record('upsertBrainstorm'),
+    upsertKaizen: record('upsertKaizen'),
+    upsertInitiative: record('upsertInitiative'),
+    upsertDocInterview: record('upsertDocInterview'),
+    refreshBoard: record('refreshBoard'),
+  }
+}
+
+const task = {
+  id: 'blk_task',
+  title: 'Ship it',
+  type: 'service',
+  description: '',
+  position: { x: 0, y: 0 },
+  status: 'planned',
+  progress: 0,
+  dependsOn: [],
+  executionId: null,
+  level: 'task',
+  parentId: 'blk_frame',
+} as unknown as Block
+
+describe('applyWorkspaceEvent: the board branch', () => {
+  it('patches the carried block instead of refreshing the whole board', () => {
+    const to = targets()
+    const event: WorkspaceEvent = { type: 'board', reason: 'block-added', block: task, at: 1 }
+
+    applyWorkspaceEvent(event, to)
+
+    // The whole point of the change: a spawned task costs one upsert, not a snapshot fetch that
+    // REPLACES every store's list.
+    expect(to.calls).toEqual(['upsertBlock'])
+  })
+
+  it('falls back to a full refresh when the change carries no block', () => {
+    const to = targets()
+    // Everything the publisher withholds a payload for lands here: a removal that cascades, a
+    // reparent that moves a subtree, and a service FRAME whose geometry is per-board. None has a
+    // single block that states the new shape, so the client must re-read its own projection.
+    const event: WorkspaceEvent = { type: 'board', reason: 'block-removed', at: 1 }
+
+    applyWorkspaceEvent(event, to)
+
+    expect(to.calls).toEqual(['refreshBoard'])
+  })
+
+  it('falls back to a full refresh when the payload is explicitly null', () => {
+    const to = targets()
+    // The frame shape as the publishers actually emit it: `deliverableBoardBlock` answers `null`
+    // rather than omitting the key, and an absent payload and a null one must route identically.
+    const event: WorkspaceEvent = { type: 'board', reason: 'block-archived', block: null, at: 1 }
+
+    applyWorkspaceEvent(event, to)
+
+    expect(to.calls).toEqual(['refreshBoard'])
+  })
+
+  it('routes a board event through the SAME upsert an execution event uses', () => {
+    // Coherence: the monotonic live-upsert stamp that stops a stale refresh clobbering newer
+    // state lives in `board.upsert`. A targeted board event that patched `blocks` any other way
+    // would silently escape that guard.
+    const upsertBlock = vi.fn()
+    const to = { ...targets(), upsertBlock }
+
+    applyWorkspaceEvent({ type: 'board', reason: 'block-updated', block: task, at: 1 }, to)
+    applyWorkspaceEvent(
+      {
+        type: 'execution',
+        instance: { id: 'exec_1', blockId: task.id } as never,
+        block: task,
+        at: 2,
+      },
+      to,
+    )
+
+    expect(upsertBlock).toHaveBeenCalledTimes(2)
+    expect(upsertBlock).toHaveBeenNthCalledWith(1, task)
+    expect(upsertBlock).toHaveBeenNthCalledWith(2, task)
+  })
+})
+
+describe('applyWorkspaceEvent: the other branches', () => {
+  it('keeps every non-board event on its own targeted store call', () => {
+    // Each type below is delivered as a patch rather than a board refresh. This table cannot see
+    // a NEW event type (an absent member is just absent from a hand-written list). That job
+    // belongs to the `never` guard on the switch's `default`, which fails the BUILD instead.
+    const cases: [WorkspaceEvent, string][] = [
+      [{ type: 'bootstrap', job: {} as never, block: null, at: 1 }, 'upsertBootstrap'],
+      [{ type: 'env-config-repair', job: {} as never, at: 1 }, 'upsertEnvConfigRepair'],
+      [{ type: 'envTest', run: {} as never, at: 1 }, 'upsertEnvironmentTest'],
+      [
+        { type: 'infraSetup', area: 'runnerPool' as never, status: 'ok' as never, at: 1 },
+        'patchInfraSetup',
+      ],
+      [{ type: 'notification', notification: {} as never, at: 1 }, 'upsertNotification'],
+      [{ type: 'llmCall', call: {} as never, at: 1 }, 'appendLlmCall'],
+      [{ type: 'requirements', review: {} as never, at: 1 }, 'upsertRequirements'],
+      [{ type: 'consensus', session: {} as never, at: 1 }, 'upsertConsensus'],
+      [{ type: 'clarity', review: {} as never, at: 1 }, 'upsertClarity'],
+      [{ type: 'brainstorm', session: {} as never, at: 1 }, 'upsertBrainstorm'],
+      [{ type: 'kaizen', grading: {} as never, at: 1 }, 'upsertKaizen'],
+      [{ type: 'initiative', initiative: {} as never, at: 1 }, 'upsertInitiative'],
+      [{ type: 'docInterview', session: {} as never, at: 1 }, 'upsertDocInterview'],
+    ]
+
+    for (const [event, expected] of cases) {
+      const to = targets()
+      applyWorkspaceEvent(event, to)
+      expect(to.calls, `${event.type} should route to ${expected}`).toEqual([expected])
+    }
+  })
+
+  it('drops an event type it does not know rather than tearing down the session', () => {
+    // A backend one release ahead pushes types this build has never heard of. The socket carries
+    // every other event for the whole workspace, so the unknown one is dropped, not thrown on.
+    const to = targets()
+
+    applyWorkspaceEvent({ type: 'a-later-release', at: 1 } as unknown as WorkspaceEvent, to)
+
+    expect(to.calls).toEqual([])
+  })
+})