@cat-factory/app 0.311.3 → 0.313.0

package/app/stores/workView.ts

@@ -0,0 +1,51 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import { DEFAULT_WORK_VIEW, isWorkView, WORK_VIEW_PARAM, type WorkView } from '~/utils/workView'
+
+/**
+ * Which view of the board this person is looking at: the queue or the canvas.
+ *
+ * Persisted per BROWSER in a cookie, like the interface tier and the lane order: it is the view
+ * used LAST in this browser, so a person who prefers the canvas stays on it, and nobody on another
+ * browser is moved by their choice. See `utils/workView.ts` for why the queue is the default.
+ */
+export const useWorkViewStore = defineStore(
+  'workView',
+  () => {
+    const tutorial = useTutorialStore()
+    // Stored raw and narrowed on read, as `uiMode` does: the persisted value is untrusted input.
+    const storedView = ref<string>(DEFAULT_WORK_VIEW)
+    /**
+     * The view on screen. A running tour holds the CANVAS for its whole length: every tour anchors
+     * to canvas nodes and the canvas toolbar, which the queue covers or unmounts, so a switch mid-
+     * tour would leave its later steps with nothing to point at. A choice made meanwhile is kept
+     * and applies when the tour ends.
+     */
+    const view = computed<WorkView>(() => {
+      if (tutorial.touring) return 'board'
+      return isWorkView(storedView.value) ? storedView.value : DEFAULT_WORK_VIEW
+    })
+
+    function show(next: WorkView) {
+      storedView.value = next
+    }
+
+    /**
+     * Honour a `?view=queue` / `?view=board` link, then strip the parameter so a reload or a
+     * copied URL does not re-apply it over a later choice. Same shape as the run deep link. A
+     * `view` value that names no view is dropped without effect, rather than guessed onto one.
+     */
+    function consumeDeepLink() {
+      if (!import.meta.client) return
+      const url = new URL(window.location.href)
+      if (!url.searchParams.has(WORK_VIEW_PARAM)) return
+      const asked = url.searchParams.get(WORK_VIEW_PARAM)
+      url.searchParams.delete(WORK_VIEW_PARAM)
+      window.history.replaceState(window.history.state, '', url.toString())
+      if (isWorkView(asked)) show(asked)
+    }
+
+    return { storedView, view, show, consumeDeepLink }
+  },
+  { persist: { pick: ['storedView'] } },
+)

package/app/stores/workspaceQueue.ts

@@ -0,0 +1,148 @@
+import { defineStore } from 'pinia'
+import { computed, ref, watch } from 'vue'
+import type { Block } from '~/types/domain'
+import { useTaskLaneClassifier, type ClassifiedEntry } from '~/composables/useTaskLaneClassifier'
+import {
+  assembleQueue,
+  QUEUE_SECTION_BY_REASON,
+  type QueueAssembly,
+  type QueueEntry,
+} from '~/utils/queueSections'
+
+/**
+ * Every task on the board, across every service, classified ONCE and filed into queue sections.
+ *
+ * The store-facing half of `utils/queueSections.ts`, and a STORE rather than a composable for the
+ * reason the swimlane README gives: a workspace-wide derivation belongs on one owner, never on each
+ * consumer. The queue view, the sidebar's attention counter AND every frame's swimlanes
+ * (`useFrameLanes`) read the one classification here, so a board pays for each task's verdict once
+ * per change, however many surfaces show it.
+ *
+ * It walks the service frames rather than `board.allTasks` so it holds exactly the tasks the
+ * frames' own swimlanes hold (direct tasks plus those inside modules): a task the canvas shows
+ * nowhere is not one the queue may claim needs you.
+ */
+export const useWorkspaceQueueStore = defineStore('workspaceQueue', () => {
+  const board = useBoardStore()
+  const execution = useExecutionStore()
+  const workspace = useWorkspaceStore()
+  const settings = useWorkspaceSettingsStore()
+  const reviews = useReviewStage()
+  const { classify } = useTaskLaneClassifier()
+
+  /**
+   * Each task's lane verdict, keyed by id. `order` is the task's position in its OWN frame, which
+   * is the tiebreak the frame's lanes sort by.
+   */
+  const classified = computed(() => {
+    const byId = new Map<string, ClassifiedEntry>()
+    for (const frame of board.frames) {
+      board
+        .allTasksUnder(frame.id)
+        .forEach((task, order) => byId.set(task.id, classify(task, order)))
+    }
+    return byId
+  })
+
+  /** Narrow the queue to one service; null means all of them. Session-only, like a search box. */
+  const serviceFilter = ref<string | null>(null)
+  // A filter belongs to the board it was set on: another board's service id matches nothing there.
+  watch(
+    () => workspace.workspaceId,
+    () => (serviceFilter.value = null),
+  )
+
+  /** The service frames, for the filter. Board order, which is the order the canvas lays out. */
+  const services = computed(() => board.frames.map((f) => ({ id: f.id, title: f.title })))
+
+  /** The filter in force: a service deleted since it was picked narrows to nothing, so it lapses. */
+  const activeFilter = computed(() =>
+    serviceFilter.value && services.value.some((s) => s.id === serviceFilter.value)
+      ? serviceFilter.value
+      : null,
+  )
+
+  /** Show every service. The surfaces that send a person to the queue call it, so a filter set
+   * earlier cannot hide the work they were sent to see. */
+  function clearFilter() {
+    serviceFilter.value = null
+  }
+
+  /**
+   * A decision or approval on a block that is not a task in a service: an initiative's planning
+   * run, or a frame-level run. The swimlanes have no lane for it, but it waits on a person all the
+   * same, and the toolbar's decision count includes it, so the queue lists it under Needs you.
+   */
+  const parkedElsewhere = computed<QueueEntry[]>(() => {
+    const ids = new Set<string>()
+    for (const d of execution.openDecisions) ids.add(d.blockId)
+    for (const a of execution.openApprovals) {
+      if (!reviews.isBackground(a.agentKind, a.blockId)) ids.add(a.blockId)
+    }
+    const out: QueueEntry[] = []
+    for (const id of ids) {
+      if (classified.value.has(id)) continue
+      const block = board.getBlock(id)
+      if (!block) continue
+      out.push(parkEntry(block, out.length))
+    }
+    return out
+  })
+
+  function parkEntry(block: Block, order: number): QueueEntry {
+    const { entry } = classify(block, order)
+    const service = board.serviceOf(block)
+    return {
+      ...entry,
+      reason: execution.decisionsByBlock.has(block.id) ? 'decision' : 'approval',
+      service: service ? { id: service.id, title: service.title } : null,
+    }
+  }
+
+  /** Everything the queue lists, before the filter. The attention counter reads this, unfiltered. */
+  const entries = computed<QueueEntry[]>(() => {
+    const out: QueueEntry[] = []
+    for (const frame of board.frames) {
+      const service = { id: frame.id, title: frame.title }
+      // `classified` walks these same frames and tasks, so every one of them has a verdict.
+      for (const task of board.allTasksUnder(frame.id)) {
+        out.push({ ...classified.value.get(task.id)!.entry, service })
+      }
+    }
+    return out.concat(parkedElsewhere.value)
+  })
+
+  // `Date.now()` is read non-reactively, as the frame's Done lane does: the window is
+  // re-evaluated on every board or run change, which on a live board is constantly.
+  const queue = computed<QueueAssembly>(() =>
+    assembleQueue(
+      activeFilter.value
+        ? entries.value.filter((e) => e.service?.id === activeFilter.value)
+        : entries.value,
+      Date.now(),
+      {
+        maxItems: settings.settings.doneLaneMaxItems,
+        retentionDays: settings.settings.doneLaneRetentionDays,
+      },
+    ),
+  )
+
+  /**
+   * The ONE attention count the queue view shows: what a human must act on before an agent can
+   * continue, across every service and regardless of the filter. A pull request waiting to merge
+   * is not in it, because nothing is stalled behind it (see `utils/queueSections.ts`).
+   */
+  const needsYouCount = computed(
+    () => entries.value.filter((e) => QUEUE_SECTION_BY_REASON[e.reason] === 'needs_you').length,
+  )
+
+  return {
+    classified,
+    serviceFilter,
+    activeFilter,
+    clearFilter,
+    services,
+    queue,
+    needsYouCount,
+  }
+})

package/app/utils/queueSections.spec.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest'
+import type { Block } from '~/types/domain'
+import { LANE_BY_REASON, LANE_REASONS, type LaneReason } from '~/utils/swimlanes'
+import { assembleQueue, QUEUE_SECTION_BY_REASON, type QueueEntry } from '~/utils/queueSections'
+import type { DoneLaneCaps } from '~/utils/swimlanes'
+
+// The queue reads the frame lanes' verdict and must never contradict it. The one place it
+// splits differently (a PR waiting to merge gets its own column) is a regrouping INSIDE the
+// frame's `needs_you` lane, never a move across lanes.
+
+const NOW = 1_800_000_000_000
+const DAY = 86_400_000
+/** The caps a workspace sets for its frames' Done lane, which the queue applies too. */
+const CAPS: DoneLaneCaps = { maxItems: 20, retentionDays: 14 }
+
+function entry(id: string, reason: LaneReason, overrides: Partial<QueueEntry> = {}): QueueEntry {
+  return {
+    task: { id, title: id, status: 'ready', level: 'task' } as Block,
+    reason,
+    order: 0,
+    activityAt: null,
+    waitingSince: null,
+    moduleName: null,
+    initiativeName: null,
+    epicName: null,
+    service: { id: 'svc', title: 'Service' },
+    ...overrides,
+  }
+}
+
+describe('QUEUE_SECTION_BY_REASON', () => {
+  it('files every reason, and never across the lane the frame put it in', () => {
+    const laneOfSection = {
+      needs_you: 'needs_you',
+      ready_to_merge: 'needs_you',
+      in_flight: 'in_progress',
+      waiting: 'not_started',
+      done: 'done',
+    } as const
+    for (const reason of LANE_REASONS) {
+      expect(laneOfSection[QUEUE_SECTION_BY_REASON[reason]], reason).toBe(LANE_BY_REASON[reason])
+    }
+  })
+})
+
+describe('assembleQueue', () => {
+  it('puts a decision, a failure and a parked run in Needs you, and a waiting PR beside it', () => {
+    const { sections } = assembleQueue(
+      [
+        entry('decide', 'decision'),
+        entry('broken', 'failed'),
+        entry('parked', 'parked'),
+        entry('pr', 'pr_awaiting_merge'),
+      ],
+      NOW,
+      CAPS,
+    )
+    expect(sections.needs_you.map((e) => e.task.id).sort()).toEqual(['broken', 'decide', 'parked'])
+    expect(sections.ready_to_merge.map((e) => e.task.id)).toEqual(['pr'])
+  })
+
+  it('orders Needs you as the frame lane does: broken first, then the longest wait', () => {
+    const { sections } = assembleQueue(
+      [
+        entry('recent', 'decision', { waitingSince: NOW - 1000, order: 0 }),
+        entry('old', 'decision', { waitingSince: NOW - 5000, order: 1 }),
+        entry('broken', 'failed', { order: 2 }),
+      ],
+      NOW,
+      CAPS,
+    )
+    expect(sections.needs_you.map((e) => e.task.id)).toEqual(['broken', 'old', 'recent'])
+  })
+
+  it("applies the frames' Done-lane window: newest first, undated last, older ones left out", () => {
+    const merged = (id: string, completedAt: number | undefined) =>
+      entry(id, 'merged', {
+        task: { id, title: id, status: 'done', level: 'task', completedAt } as Block,
+      })
+    const queue = assembleQueue(
+      [
+        merged('yesterday', NOW - DAY),
+        merged('today', NOW - 1000),
+        merged('ancient', NOW - (CAPS.retentionDays! + 1) * DAY),
+        merged('undated', undefined),
+      ],
+      NOW,
+      CAPS,
+    )
+    expect(queue.sections.done.map((e) => e.task.id)).toEqual(['today', 'yesterday', 'undated'])
+    expect(queue.doneInWindow).toBe(3)
+  })
+
+  it('caps the Done list but never the count above it', () => {
+    const many = Array.from({ length: CAPS.maxItems + 3 }, (_, i) =>
+      entry(`m${i}`, 'merged', {
+        order: i,
+        task: {
+          id: `m${i}`,
+          title: '',
+          status: 'done',
+          level: 'task',
+          completedAt: NOW - i,
+        } as Block,
+      }),
+    )
+    const queue = assembleQueue(many, NOW, CAPS)
+    expect(queue.sections.done).toHaveLength(CAPS.maxItems)
+    expect(queue.doneInWindow).toBe(many.length)
+  })
+})

package/app/utils/queueSections.ts

@@ -0,0 +1,117 @@
+import type { Block } from '~/types/domain'
+import { sortLaneTasks, type LaneTaskEntry } from '~/utils/laneSort'
+import {
+  selectDoneLaneTasks,
+  type DoneLaneCaps,
+  type LaneReason,
+  type TaskLane,
+} from '~/utils/swimlanes'
+
+// ---------------------------------------------------------------------------
+// The workspace queue: the swimlane model lifted out of the service frames.
+//
+// A frame's lanes answer "what is the state of THIS service". The queue answers "what needs
+// me, across every service", which is the question a person asks first when they open the
+// app. It reads the SAME `classifyTask` verdict the frame does (see
+// `useTaskLaneClassifier`), so a task never sits in one column here and another lane there.
+//
+// It splits the verdict differently in one place, on purpose: a pull request waiting to be
+// merged is in the frame's `needs_you` lane, and here it has its own column. Answering a
+// decision and landing a finished change are different jobs done at different moments (one
+// unblocks an agent within minutes, the other is a review session), and a single column that
+// mixed them would put "merge this" between two questions an agent is parked on.
+// ---------------------------------------------------------------------------
+
+/** The queue's sections, in reading order. */
+export const QUEUE_SECTIONS = [
+  'needs_you',
+  'in_flight',
+  'waiting',
+  'ready_to_merge',
+  'done',
+] as const
+export type QueueSection = (typeof QUEUE_SECTIONS)[number]
+
+/**
+ * Each lane reason's queue section. Exhaustive, so a new reason cannot ship without deciding
+ * where the queue files it.
+ */
+export const QUEUE_SECTION_BY_REASON: Record<LaneReason, QueueSection> = {
+  unstarted: 'waiting',
+  dependencies: 'waiting',
+  running: 'in_flight',
+  background_review: 'in_flight',
+  decision: 'needs_you',
+  approval: 'needs_you',
+  failed: 'needs_you',
+  budget_paused: 'needs_you',
+  parked: 'needs_you',
+  unclassified: 'needs_you',
+  pr_awaiting_merge: 'ready_to_merge',
+  merged: 'done',
+}
+
+/**
+ * The frame lane whose `smart` order each section borrows. The queue adds no comparator of its
+ * own: an order that differed from the frame's would make the two surfaces disagree about what
+ * to look at first. Done takes the Done lane's own selection and order (below).
+ */
+const SORT_LANE_BY_SECTION: Record<Exclude<QueueSection, 'done'>, TaskLane> = {
+  needs_you: 'needs_you',
+  in_flight: 'in_progress',
+  waiting: 'not_started',
+  ready_to_merge: 'needs_you',
+}
+
+/** One queue entry: the lane entry plus the service the task belongs to. */
+export interface QueueEntry extends LaneTaskEntry {
+  /** The enclosing service frame, or null for a task the board holds outside any service. */
+  readonly service: Pick<Block, 'id' | 'title'> | null
+}
+
+/** The assembled queue. */
+export interface QueueAssembly {
+  readonly sections: Record<QueueSection, QueueEntry[]>
+  /** Every merged task inside the retention window, before the item cap. */
+  readonly doneInWindow: number
+}
+
+/**
+ * Bucket and order classified entries into queue sections. Pure, so the ordering rules are
+ * testable without a Pinia instance.
+ *
+ * The Done section is the frames' Done lane over every service: the same selection
+ * (`selectDoneLaneTasks`) under the same workspace caps, so the queue and a frame never disagree
+ * about which merges are recent.
+ */
+export function assembleQueue(
+  entries: readonly QueueEntry[],
+  now: number,
+  doneCaps: DoneLaneCaps,
+): QueueAssembly {
+  const sections = Object.fromEntries(QUEUE_SECTIONS.map((s) => [s, [] as QueueEntry[]])) as Record<
+    QueueSection,
+    QueueEntry[]
+  >
+  for (const entry of entries) sections[QUEUE_SECTION_BY_REASON[entry.reason]].push(entry)
+
+  const byId = new Map(sections.done.map((e) => [e.task.id, e]))
+  const done = selectDoneLaneTasks(
+    sections.done.map((e) => e.task),
+    doneCaps,
+    now,
+  )
+
+  for (const section of QUEUE_SECTIONS) {
+    if (section === 'done') continue
+    sections[section] = sortLaneTasks(
+      sections[section],
+      'smart',
+      SORT_LANE_BY_SECTION[section],
+    ) as QueueEntry[]
+  }
+  // Newest completion first, as the frame's Done lane orders it.
+  sections.done = done.shown.map((task) => byId.get(task.id)!)
+
+  return { sections, doneInWindow: done.shown.length + done.hiddenByCap }
+}

package/app/utils/setupChecklist.spec.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from 'vitest'
+import type { InfraSetup } from '@cat-factory/contracts'
+import { deriveSetupChecklist, type SetupProbeInput } from '~/utils/setupChecklist'
+import type { SetupActor } from '~/utils/setupAudience'
+
+// The checklist adds no probe of its own; what it owes is to state each probe's answer without
+// changing its meaning. Three rules matter most: an unanswered probe is never "missing" or
+// "done", a broken setup is never "missing" (that would send the reader to create a second one),
+// and a row only offers its action to someone whose save would land.
+
+const ALL_CONFIGURED: InfraSetup = {
+  agentExecutor: 'configured',
+  ephemeralEnvironments: 'configured',
+  binaryStorage: 'configured',
+}
+
+const ADMIN: SetupActor = {
+  fullSurface: true,
+  canManageIntegrations: true,
+  canExecuteRuns: true,
+  isAccountAdmin: true,
+  accountsEnabled: true,
+}
+
+const SOURCE_OK: SetupProbeInput['sourceControl'] = {
+  available: true,
+  unavailableCause: null,
+  connected: true,
+  patMissing: false,
+  patProblem: null,
+}
+
+function input(overrides: Partial<SetupProbeInput> = {}): SetupProbeInput {
+  return {
+    model: { loaded: true, loadFailed: false, usable: true, presetBroken: false },
+    sourceControl: SOURCE_OK,
+    infra: ALL_CONFIGURED,
+    workspaceLoaded: true,
+    infraOwners: null,
+    providers: { loaded: true, needingConfig: [] },
+    actor: ADMIN,
+    ...overrides,
+  }
+}
+
+function row(i: SetupProbeInput, id: string) {
+  const found = deriveSetupChecklist(i).rows.find((r) => r.id === id)
+  if (!found) throw new Error(`no row ${id}`)
+  return found
+}
+
+describe('deriveSetupChecklist', () => {
+  it('reports a fully set-up workspace as done, with nothing left checking', () => {
+    const c = deriveSetupChecklist(input())
+    expect(c.done).toBe(c.total)
+    expect(c.checking).toBe(false)
+  })
+
+  it('reports an unanswered probe as checking, never as missing or done', () => {
+    const c = deriveSetupChecklist(
+      input({
+        model: { loaded: false, loadFailed: false, usable: false, presetBroken: false },
+        sourceControl: { ...SOURCE_OK, available: null, connected: false },
+        infra: null,
+        workspaceLoaded: false,
+      }),
+    )
+    expect(c.rows.every((r) => r.status === 'checking')).toBe(true)
+    expect(c.checking).toBe(true)
+  })
+
+  it('keeps a configured runner checking until the providers say whether it is complete', () => {
+    const waiting = input({ providers: { loaded: false, needingConfig: [] } })
+    expect(row(waiting, 'agentExecutor').status).toBe('checking')
+    expect(deriveSetupChecklist(waiting).checking).toBe(true)
+    // Storage has no provider connection, so it does not wait on them.
+    expect(row(waiting, 'binaryStorage').status).toBe('done')
+  })
+
+  it('names the cause of each broken setup, and tells it from an absent one', () => {
+    expect(
+      row(input({ infra: { ...ALL_CONFIGURED, agentExecutor: 'unreachable' } }), 'agentExecutor'),
+    ).toMatchObject({ status: 'attention', cause: 'unreachable' })
+    expect(
+      row(input({ providers: { loaded: true, needingConfig: ['runner-pool'] } }), 'agentExecutor'),
+    ).toMatchObject({ status: 'attention', cause: 'incomplete' })
+    expect(
+      row(input({ infra: { ...ALL_CONFIGURED, agentExecutor: 'not_defined' } }), 'agentExecutor'),
+    ).toMatchObject({ status: 'missing', cause: null })
+    expect(
+      row(
+        input({ model: { loaded: true, loadFailed: false, usable: true, presetBroken: true } }),
+        'model',
+      ),
+    ).toMatchObject({ status: 'attention', cause: 'presetBroken' })
+    expect(
+      row(input({ sourceControl: { ...SOURCE_OK, patProblem: 'rejected' } }), 'sourceControl'),
+    ).toMatchObject({ status: 'attention', cause: 'rejected' })
+  })
+
+  it('states a failed probe as unanswered, never as an absent capability', () => {
+    expect(
+      row(
+        input({ model: { loaded: false, loadFailed: true, usable: false, presetBroken: false } }),
+        'model',
+      ),
+    ).toMatchObject({ status: 'attention', cause: 'probeFailed' })
+    const failed = input({
+      sourceControl: {
+        ...SOURCE_OK,
+        available: false,
+        unavailableCause: 'failed',
+        connected: false,
+      },
+    })
+    expect(row(failed, 'sourceControl')).toMatchObject({
+      status: 'attention',
+      cause: 'probeFailed',
+    })
+    // A deployment that switched the integration off does not use it: no gap to close.
+    const disabled = input({
+      sourceControl: {
+        ...SOURCE_OK,
+        available: false,
+        unavailableCause: 'disabled',
+        connected: false,
+      },
+    })
+    expect(row(disabled, 'sourceControl').status).toBe('not_needed')
+  })
+
+  it('says so when the loaded workspace does not report its infrastructure, never spins', () => {
+    const i = input({ infra: null, workspaceLoaded: true })
+    expect(row(i, 'agentExecutor')).toMatchObject({ status: 'attention', cause: 'notReported' })
+    expect(deriveSetupChecklist(i).checking).toBe(false)
+  })
+
+  it('leaves an area the deployment does not use out of the count', () => {
+    const c = deriveSetupChecklist(
+      input({ infra: { ...ALL_CONFIGURED, ephemeralEnvironments: 'not_applicable' } }),
+    )
+    expect(c.total).toBe(c.rows.length - 1)
+    expect(c.done).toBe(c.total)
+  })
+
+  describe('who can act on a row (the banners rule, `utils/setupAudience.ts`)', () => {
+    const unconfigured: InfraSetup = {
+      agentExecutor: 'not_defined',
+      ephemeralEnvironments: 'not_defined',
+      binaryStorage: 'not_defined',
+    }
+
+    it('offers a board admin who is not an account admin only the gaps they own', () => {
+      const boardAdmin = { ...ADMIN, isAccountAdmin: false }
+      const i = input({
+        infra: unconfigured,
+        infraOwners: {
+          agentExecutor: 'workspace_admin',
+          ephemeralEnvironments: 'operator',
+          binaryStorage: 'account_admin',
+        },
+        actor: boardAdmin,
+      })
+      expect(row(i, 'agentExecutor').remedy).toBeNull()
+      expect(row(i, 'ephemeralEnvironments').remedy).toBe('operator')
+      expect(row(i, 'binaryStorage').remedy).toBe('account_admin')
+    })
+
+    it('tells someone on the designer surface they can fix it themselves', () => {
+      const i = input({ infra: unconfigured, actor: { ...ADMIN, fullSurface: false } })
+      expect(row(i, 'agentExecutor').remedy).toBe('full_surface')
+    })
+
+    it('gives every caller the token page for a personal access token', () => {
+      const member = { ...ADMIN, canManageIntegrations: false, isAccountAdmin: false }
+      const i = input({
+        sourceControl: { ...SOURCE_OK, patMissing: true, connected: false },
+        actor: member,
+      })
+      expect(row(i, 'sourceControl').remedy).toBeNull()
+      expect(row(input({ actor: member }), 'model').remedy).toBe('workspace_admin')
+    })
+  })
+})