@cat-factory/app 0.311.3 → 0.312.0

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/workView.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_WORK_VIEW, isWorkView } from '~/utils/workView'
+
+describe('isWorkView', () => {
+  it('accepts the two views and nothing else', () => {
+    expect(isWorkView('queue')).toBe(true)
+    expect(isWorkView('board')).toBe(true)
+    // A retired or hand-edited persisted value is not a view, so the store falls back.
+    expect(isWorkView('setup')).toBe(false)
+    expect(isWorkView(null)).toBe(false)
+  })
+
+  it('lands a person who has not chosen on the queue', () => {
+    expect(DEFAULT_WORK_VIEW).toBe('queue')
+  })
+})

package/app/utils/workView.ts

@@ -0,0 +1,25 @@
+// ---------------------------------------------------------------------------
+// The two views of a board (issue #2258): the QUEUE (every task across every service, in the
+// column that says what it needs) and the BOARD (the canvas, where the work is planned).
+//
+// They are two views of one board, not two products: the queue reads the same lane verdict the
+// canvas's swimlanes do. Which one a person opens on is THEIR choice, remembered as the view they
+// used last, because the jobs differ: someone who reviews all day wants the list, someone who
+// plans the next service wants the map.
+// ---------------------------------------------------------------------------
+
+export const WORK_VIEWS = ['queue', 'board'] as const
+export type WorkView = (typeof WORK_VIEWS)[number]
+
+/**
+ * Where a person lands before they have chosen. The queue: it answers the first question a
+ * person opens the app with ("what needs me?"), and the canvas is one click away.
+ */
+export const DEFAULT_WORK_VIEW: WorkView = 'queue'
+
+export function isWorkView(value: unknown): value is WorkView {
+  return typeof value === 'string' && (WORK_VIEWS as readonly string[]).includes(value)
+}
+
+/** The query parameter that opens a view, so a link can say "look at the queue". */
+export const WORK_VIEW_PARAM = 'view'

package/i18n/locales/de.json

@@ -2773,7 +2773,9 @@
         "toggleUiMode": "Oberflächenmodus wechseln",
         "chooseRole": "Rolle wechseln",
         "foundationalServices": "Basisdienste",
-        "notificationSettings": "Benachrichtigungs-Routing verwalten"
+        "notificationSettings": "Benachrichtigungs-Routing verwalten",
+        "queueView": "Warteschlangen-Ansicht öffnen",
+        "boardView": "Board-Ansicht öffnen"
       },
       "keywords": {
         "newPipeline": "pipeline agents chain",
@@ -2801,7 +2803,9 @@
         "chooseRole": "rolle entwickler produktmanager designer persona einfachere ansicht",
         "tutorial": "tutorial tour einführung hilfe onboarding lernen grundlagen",
         "foundationalServices": "gemeinsame Fähigkeit Plattform Dienst API Vertrag OpenAPI Katalog",
-        "notificationSettings": "benachrichtigungen e-mail routing kanäle posteingang"
+        "notificationSettings": "benachrichtigungen e-mail routing kanäle posteingang",
+        "queueView": "warteschlange ansicht wartet auf dich liste",
+        "boardView": "board canvas karte ansicht planen"
       }
     },
     "shortcuts": {
@@ -8115,6 +8119,10 @@
             "title": "Das Board",
             "body": "Services, Module und Aufgaben liegen auf dieser Fläche. Ziehe zum Verschieben, scrolle zum Zoomen und klicke auf eine Karte, um Details zu sehen."
           },
+          "views": {
+            "title": "Zwei Ansichten",
+            "body": "Das Board hat eine zweite Ansicht. Die Warteschlange zeigt, was über alle Services hinweg auf dich wartet. Nach der Tour wechselst du hier zwischen der Warteschlange und dieser Arbeitsfläche. Die App öffnet die Ansicht, die du zuletzt genutzt hast."
+          },
           "sidebar": {
             "title": "Die Seitenleiste",
             "body": "Alles Weitere findest du hier: Pipelines erstellen, Repositories und Integrationen verbinden, Workspace-Einstellungen."
@@ -8734,5 +8742,56 @@
         "unsupportedVersion": "Dieses Design stammt aus einem neueren Editor-Format, als diese App versteht."
       }
     }
+  },
+  "queue": {
+    "title": "Warteschlange",
+    "summary": "{needsYou} warten auf dich · {ready} bereit zum Mergen",
+    "filter": {
+      "allServices": "Alle Services",
+      "service": "Nach Service filtern"
+    },
+    "columns": {
+      "needsYou": {
+        "label": "Wartet auf dich",
+        "empty": "Nichts wartet auf dich."
+      },
+      "inFlight": {
+        "label": "In Arbeit",
+        "empty": "Derzeit arbeitet kein Agent."
+      },
+      "readyToMerge": {
+        "label": "Bereit zum Mergen",
+        "empty": "Kein Pull Request wartet auf den Merge."
+      }
+    },
+    "waiting": {
+      "label": "Nicht begonnen ({count})",
+      "empty": "Nichts wartet auf den Start."
+    },
+    "done": {
+      "count": "Seit {date} gemergt: {count}",
+      "countAll": "Gemergt: {count}",
+      "show": "Anzeigen",
+      "hide": "Ausblenden",
+      "capped": "Zeigt die neuesten {shown} von {total}."
+    },
+    "card": {
+      "waited": "wartete {duration}",
+      "active": "vor {duration} aktiv",
+      "merged": "vor {duration} gemergt",
+      "step": "Schritt {current} von {total}",
+      "showOnBoard": "Auf dem Board zeigen",
+      "answer": "Antworten",
+      "budgetPaused": "Das Ausgabenlimit hat diesen Durchlauf angehalten. Er läuft weiter, sobald das Limit erhöht wird.",
+      "parked": "Der Durchlauf wartet auf einen Menschen. Öffne die Aufgabe, um zu sehen, was fehlt.",
+      "waitingOn": "Wartet auf {deps}",
+      "pr": "Pull Request #{number}"
+    }
+  },
+  "views": {
+    "title": "Ansichten",
+    "queue": "Warteschlange",
+    "board": "Board",
+    "openQueue": "Warteschlangen-Ansicht öffnen"
   }
 }

package/i18n/locales/en.json

@@ -2800,7 +2800,9 @@
         "toggleUiMode": "Switch interface mode",
         "chooseRole": "Change your role",
         "foundationalServices": "Foundational services",
-        "notificationSettings": "Manage notification routing"
+        "notificationSettings": "Manage notification routing",
+        "queueView": "Open the queue view",
+        "boardView": "Open the board view"
       },
       "keywords": {
         "newPipeline": "pipeline agents chain",
@@ -2828,7 +2830,9 @@
         "chooseRole": "role engineer product manager designer persona simpler view",
         "tutorial": "tutorial onboarding tour guide help learn basics",
         "foundationalServices": "shared capability platform service api contract openapi catalog",
-        "notificationSettings": "notifications email routing channels inbox"
+        "notificationSettings": "notifications email routing channels inbox",
+        "queueView": "queue view needs you inbox list waiting",
+        "boardView": "board canvas map view plan"
       }
     },
     "shortcuts": {
@@ -8434,6 +8438,10 @@
             "title": "The board",
             "body": "Services, modules, and tasks live on this canvas. Drag to pan, scroll to zoom, and click any card to inspect it."
           },
+          "views": {
+            "title": "Two views",
+            "body": "The board has a second view. The queue lists what needs you across every service. Once the tour is over, switch between the queue and this canvas here. The app opens on the view you used last."
+          },
           "sidebar": {
             "title": "The sidebar",
             "body": "Everything else lives here: building pipelines, connecting repositories and integrations, and workspace settings."
@@ -9065,5 +9073,56 @@
         "unsupportedVersion": "This theme was made with a newer editor format than this app understands."
       }
     }
+  },
+  "queue": {
+    "title": "Queue",
+    "summary": "{needsYou} need you · {ready} ready to merge",
+    "filter": {
+      "allServices": "All services",
+      "service": "Filter by service"
+    },
+    "columns": {
+      "needsYou": {
+        "label": "Needs you",
+        "empty": "Nothing waits on you."
+      },
+      "inFlight": {
+        "label": "In flight",
+        "empty": "No agent is working now."
+      },
+      "readyToMerge": {
+        "label": "Ready to merge",
+        "empty": "No pull request waits to merge."
+      }
+    },
+    "waiting": {
+      "label": "Not started ({count})",
+      "empty": "Nothing waits to start."
+    },
+    "done": {
+      "count": "Merged since {date}: {count}",
+      "countAll": "Merged: {count}",
+      "show": "Show",
+      "hide": "Hide",
+      "capped": "Shows the newest {shown} of {total}."
+    },
+    "card": {
+      "waited": "waited {duration}",
+      "active": "active {duration} ago",
+      "merged": "merged {duration} ago",
+      "step": "step {current} of {total}",
+      "showOnBoard": "Show on the board",
+      "answer": "Answer",
+      "budgetPaused": "The spend limit paused this run. It continues when the limit goes up.",
+      "parked": "The run waits for a person. Open the task to see what it needs.",
+      "waitingOn": "Waits for {deps}",
+      "pr": "Pull request #{number}"
+    }
+  },
+  "views": {
+    "title": "Views",
+    "queue": "Queue",
+    "board": "Board",
+    "openQueue": "Open the queue view"
   }
 }