@cat-factory/app 0.311.3 → 0.313.0

package/app/components/setup/SetupChecklistPanel.vue

@@ -0,0 +1,340 @@
+<script setup lang="ts">
+import type { SetupRow, SetupRowCause, SetupRowId, SetupRowStatus } from '~/utils/setupChecklist'
+import type { SetupRemedy } from '~/utils/setupAudience'
+import SectionLabel from '~/components/common/SectionLabel.vue'
+import Spinner from '~/components/common/Spinner.vue'
+
+/**
+ * The setup checklist: every prerequisite for "a task can run and merge", its state, and one
+ * action per row (issue #2258).
+ *
+ * The probes and the surfaces each row opens are the ones the setup banners, the AI-provider
+ * dialogs and the startup health advisories already use (`useSetupChecklist`), and so is the rule
+ * for who may act: a row the caller cannot fix shows who can instead of a button. What it adds is
+ * the whole list in one place, with a finish line, instead of one interruption per missing piece.
+ * Opening a row's surface closes the checklist, so the two never stack.
+ */
+const { t } = useI18n()
+const ui = useUiStore()
+const { checklist, actionFor, refresh, patSource, patMissing } = useSetupChecklist()
+
+const open = computed({
+  get: () => ui.setupChecklistOpen,
+  set: (v: boolean) => (v ? ui.openSetupChecklist() : ui.closeSetupChecklist()),
+})
+watch(
+  () => ui.setupChecklistOpen,
+  (isOpen) => {
+    if (isOpen) refresh()
+  },
+  { immediate: true },
+)
+
+/** Open a surface from the checklist: close the checklist first, so the two never stack. */
+function go(fn: () => void) {
+  ui.closeSetupChecklist()
+  fn()
+}
+function act(row: SetupRow) {
+  const action = actionFor(row)
+  if (!action) return
+  // Asking a probe again keeps the checklist open: its answer lands here.
+  if (row.cause === 'probeFailed') action()
+  else go(action)
+}
+
+/** The rows this caller can act on, with the action to show. */
+function canAct(row: SetupRow): boolean {
+  return row.remedy === null && actionFor(row) !== null
+}
+
+/**
+ * The ONE solid button in the view: the first required row that is not done and that this caller
+ * can act on. Every other open row takes a lighter variant, so the list reads in order.
+ */
+const primaryRowId = computed<SetupRowId | null>(
+  () =>
+    checklist.value.rows.find(
+      (r) => r.required && (r.status === 'missing' || r.status === 'attention') && canAct(r),
+    )?.id ?? null,
+)
+
+const pipelineHealth = usePipelineHealth()
+const riskPolicyHealth = useRiskPolicyHealth()
+const modelPresetHealth = useModelPresetHealth()
+
+const STATUS_META: Record<SetupRowStatus, { icon: string; class: string }> = {
+  done: { icon: 'i-lucide-circle-check', class: 'text-success' },
+  missing: { icon: 'i-lucide-circle', class: 'text-dimmed' },
+  attention: { icon: 'i-lucide-circle-alert', class: 'text-warning' },
+  checking: { icon: 'i-lucide-loader-circle', class: 'text-dimmed' },
+  not_needed: { icon: 'i-lucide-circle-minus', class: 'text-dimmed' },
+}
+
+/**
+ * The action's word per state. Null for the two states that never carry an action
+ * (`useSetupChecklist.actionFor`), so no copy ships for a button that cannot render.
+ */
+const ACTION_KEYS: Record<SetupRowStatus, string | null> = {
+  done: 'setup.action.change',
+  missing: 'setup.action.connect',
+  attention: 'setup.action.fix',
+  checking: null,
+  not_needed: null,
+}
+
+function actionLabel(row: SetupRow): string {
+  if (row.cause === 'probeFailed') return t('setup.action.retry')
+  const key = ACTION_KEYS[row.status]
+  return key ? t(key) : ''
+}
+
+/** Whose token a token row is about: the remedy differs, so the row says it, as the banner does. */
+const patSourceKey = computed(() =>
+  patSource.value === 'deployment'
+    ? 'layout.githubPatPermissionsBanner.sourceDeployment'
+    : 'layout.githubPatPermissionsBanner.sourceInitiator',
+)
+
+/**
+ * Each row's title and its line for the states that are about the row. An `attention` row's line
+ * is its CAUSE (`CAUSE_KEYS`): the title already names the area, and each cause needs its own fix.
+ */
+const ROW_COPY: Record<
+  SetupRowId,
+  { title: string } & Record<Exclude<SetupRowStatus, 'attention'>, string>
+> = {
+  model: {
+    title: 'setup.rows.model.title',
+    done: 'setup.rows.model.done',
+    missing: 'setup.rows.model.missing',
+    checking: 'setup.rows.checking',
+    not_needed: 'setup.rows.notNeeded',
+  },
+  sourceControl: {
+    title: 'setup.rows.sourceControl.title',
+    done: 'setup.rows.sourceControl.done',
+    missing: 'setup.rows.sourceControl.missing',
+    checking: 'setup.rows.checking',
+    not_needed: 'setup.rows.notNeeded',
+  },
+  agentExecutor: {
+    title: 'setup.rows.agentExecutor.title',
+    done: 'setup.rows.agentExecutor.done',
+    missing: 'setup.rows.agentExecutor.missing',
+    checking: 'setup.rows.checking',
+    not_needed: 'setup.rows.agentExecutor.notNeeded',
+  },
+  ephemeralEnvironments: {
+    title: 'setup.rows.ephemeralEnvironments.title',
+    done: 'setup.rows.ephemeralEnvironments.done',
+    missing: 'setup.rows.ephemeralEnvironments.missing',
+    checking: 'setup.rows.checking',
+    not_needed: 'setup.rows.notNeeded',
+  },
+  binaryStorage: {
+    title: 'setup.rows.binaryStorage.title',
+    done: 'setup.rows.binaryStorage.done',
+    missing: 'setup.rows.binaryStorage.missing',
+    checking: 'setup.rows.checking',
+    not_needed: 'setup.rows.notNeeded',
+  },
+}
+const CAUSE_KEYS: Record<SetupRowCause, string> = {
+  unreachable: 'setup.causes.unreachable',
+  incomplete: 'setup.causes.incomplete',
+  rejected: 'setup.causes.rejected',
+  underscoped: 'setup.causes.underscoped',
+  presetBroken: 'setup.causes.presetBroken',
+  probeFailed: 'setup.causes.probeFailed',
+  notReported: 'setup.causes.notReported',
+}
+function rowLine(row: SetupRow): string {
+  return row.status === 'attention' ? t(CAUSE_KEYS[row.cause]) : t(ROW_COPY[row.id][row.status])
+}
+
+// The same "who can fix this" lines the infrastructure notice shows a caller who cannot act.
+const REMEDY_KEYS: Record<SetupRemedy, string> = {
+  workspace_admin: 'layout.infraSetupNotice.owner.workspace_admin',
+  account_admin: 'layout.infraSetupNotice.owner.account_admin',
+  operator: 'layout.infraSetupNotice.owner.operator',
+  full_surface: 'layout.infraSetupNotice.fullSurface',
+}
+
+/**
+ * The secondary list: advisories that used to open as startup dialogs, each count on its own so
+ * no sentence has to agree with a number. Only rows with work.
+ */
+const also = computed(() =>
+  [
+    {
+      id: 'pipelines',
+      labelKey: 'setup.also.pipelines',
+      counts: [
+        {
+          key: 'setup.also.counts.repair',
+          n:
+            pipelineHealth.health.value.filter((h) => h.invalid).length +
+            pipelineHealth.retired.value.length,
+        },
+        {
+          key: 'setup.also.counts.outdated',
+          n: pipelineHealth.health.value.filter((h) => !h.invalid && h.outdated).length,
+        },
+        { key: 'setup.also.counts.new', n: pipelineHealth.newPipelines.value.length },
+      ],
+      open: () => go(() => ui.openPipelineHealth()),
+    },
+    {
+      id: 'riskPolicies',
+      labelKey: 'setup.also.riskPolicies',
+      counts: [
+        { key: 'setup.also.counts.outdated', n: riskPolicyHealth.outdated.value.length },
+        { key: 'setup.also.counts.new', n: riskPolicyHealth.newPresets.value.length },
+      ],
+      open: () => go(() => ui.openRiskPolicyHealth()),
+    },
+    {
+      id: 'modelPresets',
+      labelKey: 'setup.also.modelPresets',
+      counts: [
+        { key: 'setup.also.counts.outdated', n: modelPresetHealth.outdated.value.length },
+        { key: 'setup.also.counts.new', n: modelPresetHealth.newPresets.value.length },
+      ],
+      open: () => go(() => ui.openModelPresetHealth()),
+    },
+  ]
+    .map((row) => ({ ...row, counts: row.counts.filter((c) => c.n > 0) }))
+    .filter((row) => row.counts.length > 0),
+)
+</script>
+
+<template>
+  <UModal v-model:open="open" :title="t('setup.title')" :ui="{ content: 'sm:max-w-3xl' }">
+    <template #title>
+      <span class="flex items-baseline gap-3">
+        {{ t('setup.title') }}
+        <!-- While a probe has not answered, the count is not one yet, so the badge says so. -->
+        <UBadge color="neutral" variant="subtle" data-testid="setup-progress">
+          {{
+            checklist.checking
+              ? t('setup.rows.checking')
+              : t('setup.progress', { done: checklist.done, total: checklist.total })
+          }}
+        </UBadge>
+      </span>
+    </template>
+    <template #body>
+      <div data-testid="setup-checklist">
+        <p class="text-sm text-muted">{{ t('setup.intro') }}</p>
+
+        <ul class="mt-6 space-y-3">
+          <li
+            v-for="row in checklist.rows"
+            :key="row.id"
+            class="flex items-center gap-3 rounded-lg border border-muted bg-default p-4"
+            data-testid="setup-row"
+            :data-row="row.id"
+            :data-status="row.status"
+            :data-cause="row.cause ?? undefined"
+            :data-remedy="row.remedy ?? undefined"
+          >
+            <Spinner
+              :name="STATUS_META[row.status].icon"
+              :spinning="row.status === 'checking'"
+              class="h-5 w-5 shrink-0"
+              :class="STATUS_META[row.status].class"
+            />
+            <div class="min-w-0 flex-1">
+              <div class="flex flex-wrap items-center gap-2">
+                <span class="font-medium text-highlighted">{{ t(ROW_COPY[row.id].title) }}</span>
+                <UBadge v-if="row.status !== 'done'" size="sm" color="neutral" variant="outline">
+                  {{ row.required ? t('setup.required') : t('setup.optional') }}
+                </UBadge>
+              </div>
+              <p class="mt-0.5 text-xs text-muted">{{ rowLine(row) }}</p>
+              <!-- The token rows carry the banners' second half: whose token it is, and, for a
+                   missing local token, where the new one goes. -->
+              <p
+                v-if="row.cause === 'rejected' || row.cause === 'underscoped'"
+                class="mt-0.5 text-xs text-dimmed"
+              >
+                {{ t(patSourceKey) }}
+              </p>
+              <p
+                v-else-if="row.id === 'sourceControl' && row.status === 'missing' && patMissing"
+                class="mt-0.5 text-xs text-dimmed"
+              >
+                <i18n-t keypath="layout.githubPatBanner.thenSet" tag="span" scope="global">
+                  <template #envVar>
+                    <code class="font-mono">GITHUB_PAT</code>
+                  </template>
+                </i18n-t>
+              </p>
+              <!-- A gap this caller cannot close: who can, in place of a button their save would
+                   be refused on. A done row needs neither. -->
+              <p
+                v-if="row.remedy && row.status !== 'done' && row.status !== 'not_needed'"
+                class="mt-0.5 text-xs text-dimmed"
+                data-testid="setup-row-remedy"
+              >
+                {{ t(REMEDY_KEYS[row.remedy]) }}
+              </p>
+            </div>
+            <UButton
+              v-if="canAct(row)"
+              size="sm"
+              :color="row.status === 'done' ? 'neutral' : 'primary'"
+              :variant="
+                row.id === primaryRowId ? 'solid' : row.status === 'done' ? 'outline' : 'soft'
+              "
+              data-testid="setup-row-action"
+              @click="act(row)"
+            >
+              {{ actionLabel(row) }}
+            </UButton>
+          </li>
+        </ul>
+
+        <USeparator class="my-6" />
+        <SectionLabel as="h2" class="mb-3">{{ t('setup.also.title') }}</SectionLabel>
+        <ul class="space-y-2 text-sm">
+          <li v-for="row in also" :key="row.id" class="flex flex-wrap items-center gap-2">
+            <span class="text-muted">{{ t(row.labelKey) }}</span>
+            <UBadge v-for="c in row.counts" :key="c.key" size="sm" color="neutral" variant="subtle">
+              {{ t(c.key, { count: c.n }) }}
+            </UBadge>
+            <UButton
+              class="ms-auto"
+              size="xs"
+              color="neutral"
+              variant="outline"
+              @click="row.open()"
+            >
+              {{ t('setup.action.review') }}
+            </UButton>
+          </li>
+          <li class="flex flex-wrap items-center gap-2 text-muted">
+            <span class="flex-1">{{ t('setup.also.settings') }}</span>
+            <UButton
+              size="xs"
+              color="neutral"
+              variant="ghost"
+              @click="go(() => ui.openWorkspaceSettings())"
+            >
+              {{ t('setup.also.workspaceSettings') }}
+            </UButton>
+            <UButton
+              size="xs"
+              color="neutral"
+              variant="ghost"
+              @click="go(() => ui.openIntegrations())"
+            >
+              {{ t('setup.also.integrations') }}
+            </UButton>
+          </li>
+        </ul>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/composables/useFrameLanes.ts

@@ -1,28 +1,18 @@
 import { computed, type Ref } from 'vue'
-import type { Block } from '~/types/domain'
 import { createLaneMemo } from '~/utils/laneIdentity'
 import {
   groupLaneTasks,
-  runActivityAt,
-  runWaitingSince,
   sortLaneTasks,
   type LaneTaskEntry,
   type RenderedLane,
 } from '~/utils/laneSort'
 import {
-  classifyTask,
   selectDoneLaneTasks,
   TASK_LANES,
   type DoneLaneSelection,
   type TaskLane,
 } from '~/utils/swimlanes'
 
-/** A lane entry plus the lane it was classified into. */
-interface ClassifiedEntry {
-  readonly entry: LaneTaskEntry
-  readonly lane: TaskLane
-}
-
 /**
  * Assemble a service frame's tasks into swimlanes.
  *
@@ -34,12 +24,10 @@ interface ClassifiedEntry {
  */
 export function useFrameLanes(frameId: Ref<string>) {
   const board = useBoardStore()
-  const execution = useExecutionStore()
-  const agentRuns = useAgentRunsStore()
-  const notifications = useNotificationsStore()
   const settings = useWorkspaceSettingsStore()
   const laneView = useLaneViewStore()
-  const reviews = useReviewStage()
+  // The workspace-wide classification: every frame and the queue read one verdict per task.
+  const queue = useWorkspaceQueueStore()
 
   /** Tasks directly in the frame plus those inside its modules: a module renders no box now. */
   const tasks = computed(() => board.allTasksUnder(frameId.value))
@@ -49,78 +37,14 @@ export function useFrameLanes(frameId: Ref<string>) {
     () => new Map(board.modulesOf(frameId.value).map((m) => [m.title, m.id])),
   )
 
-  /**
-   * The module a task belongs to: the module BLOCK's title when it already lives in one, else
-   * the module it DECLARES. The engine only materialises the block on merge
-   * (`applyModuleAssignment`), so keying on the parent alone would leave every unmerged task in
-   * "no module" while its own card names one.
-   */
-  function moduleNameOf(task: Block): string | null {
-    const parent = task.parentId ? board.getBlock(task.parentId) : undefined
-    if (parent?.level === 'module') return parent.title
-    return task.moduleName?.trim() || null
-  }
-
-  /**
-   * One task's lane, reason and rendered entry.
-   *
-   * Every cross-block lookup here is a Map read off an index a STORE maintains, never a reduction
-   * of its own: this composable runs ONE INSTANCE PER MOUNTED FRAME, so deriving a workspace-wide
-   * fact here makes a board with n frames pay for it n times on every change. The review-debt map
-   * (`notifications.reviewDebtByBlock`) is the worked example: a reduction over the whole
-   * workspace's open notifications, and it belongs on the store that owns its input. The rule for
-   * anything else this assembly needs: a per-FRAME derivation belongs here, a workspace-wide one
-   * belongs on that store.
-   */
-  function classify(task: Block, order: number): ClassifiedEntry {
-    const run = execution.getByBlock(task.id) ?? null
-    const decisions = execution.decisionsByBlock.get(task.id) ?? []
-    const allApprovals = execution.approvalsByBlock.get(task.id) ?? []
-    // The same suppression the card and the frame badge apply: an iterative reviewer mid-cycle
-    // holds a pending approval while the driver folds answers in, and nobody is waiting on it.
-    const humanApprovals = allApprovals.filter((a) => !reviews.isBackground(a.agentKind, a.blockId))
-
-    const { lane, reason } = classifyTask({
-      status: task.status,
-      // Read from the coarse per-block summary, which also covers a bootstrap run.
-      runFailed: agentRuns.byBlock[task.id]?.status === 'failed',
-      run,
-      // A park is background exactly when everything asking was suppressed AND nothing else
-      // asks. With no approvals at all it is NOT background: it is a park on a surface this
-      // layer cannot name, which `classifyTask` reports as `parked` rather than as work.
-      parkIsBackground:
-        decisions.length === 0 &&
-        humanApprovals.length === 0 &&
-        allApprovals.length > humanApprovals.length,
-      pendingDecision: decisions.length > 0,
-      pendingApproval: humanApprovals.length > 0,
-      hasUnmetDeps: board.unmetDeps(task.id).length > 0,
-    })
-
-    return {
-      lane,
-      entry: {
-        task,
-        reason,
-        order,
-        activityAt: runActivityAt(run),
-        waitingSince: runWaitingSince(run, notifications.reviewDebtByBlock.get(task.id) ?? null),
-        moduleName: moduleNameOf(task),
-        initiativeName: task.initiativeId
-          ? (board.getBlock(task.initiativeId)?.title ?? null)
-          : null,
-        epicName: board.epicOf(task)?.title ?? null,
-      },
-    }
-  }
-
   /** Every task bucketed by lane, in board order, before sorting. */
   const byLane = computed(() => {
     const buckets = new Map<TaskLane, LaneTaskEntry[]>(TASK_LANES.map((lane) => [lane, []]))
-    tasks.value.forEach((task, order) => {
-      const { lane, entry } = classify(task, order)
+    for (const task of tasks.value) {
+      // The store walks every frame's tasks, this one's included, so each has a verdict.
+      const { lane, entry } = queue.classified.get(task.id)!
       buckets.get(lane)!.push(entry)
-    })
+    }
     return buckets
   })
 

package/app/composables/useNavContributions.ts

@@ -55,6 +55,7 @@ export function useNavContributions() {
     foundationalServices: () => ui.openFoundationalServices(),
     mergeThresholds: () => ui.openWorkspaceSettings('merge'),
     workspaceSettings: () => ui.openWorkspaceSettings(),
+    setupChecklist: () => ui.openSetupChecklist(),
     modelConfiguration: () => ui.openModelConfig(),
     serviceFragmentDefaults: () => ui.openWorkspaceSettings('fragments'),
     localModels: () => ui.openLocalModels(),
@@ -72,6 +73,8 @@ export function useNavContributions() {
     // The QUESTION, not a toggle: with three roles there is no unambiguous "next one", and the
     // prompt is the one surface that states what each role gives you before you pick it.
     chooseRole: () => useUiRoleStore().openPrompt(),
+    queueView: () => useWorkViewStore().show('queue'),
+    boardView: () => useWorkViewStore().show('board'),
   }
 
   /** Run a contribution's action (consumer `run` closure wins over the id map). */

package/app/composables/useSetupChecklist.ts

@@ -0,0 +1,122 @@
+import { computed, ref } from 'vue'
+import { githubPatCheckNeedsAttention } from '@cat-factory/contracts'
+import { deriveSetupChecklist, type SetupRow } from '~/utils/setupChecklist'
+
+/**
+ * The store-facing half of `utils/setupChecklist.ts`: resolve every probe the checklist reads,
+ * and the existing surface each row's action opens.
+ *
+ * Every action goes to the surface the matching banner or dialog opens for the same state, so
+ * the checklist is a new index over the setup the product has, never a second copy of it.
+ */
+export function useSetupChecklist() {
+  const ui = useUiStore()
+  const github = useGitHubStore()
+  const models = useModelsStore()
+  const workspace = useWorkspaceStore()
+  const providerConnections = useProviderConnectionsStore()
+  const ai = useAiReadiness()
+  const { actor } = useSetupActor()
+  // Where each gap is fixed: the map the setup banners open through too.
+  const remedies = useSetupRemedies()
+  /** Local mode with no token: the row says where the new one goes, as the banner does. */
+  const patMissing = computed(() => !!remedies.patSetupUrl.value)
+
+  // The catalog is loaded on board open, and a failed load is dropped there on purpose (it stays
+  // retryable, see `models.prefetchForBoard`). The checklist is where that failure is stated, so
+  // it asks for the catalog itself and keeps the outcome.
+  const modelLoadFailed = ref(false)
+  async function loadModels() {
+    const id = workspace.workspaceId
+    if (!id) return
+    modelLoadFailed.value = false
+    try {
+      await models.ensureLoaded(id)
+    } catch {
+      modelLoadFailed.value = true
+    }
+  }
+
+  /**
+   * Ask every probe the checklist reads, so a row does not wait on a banner that happens to be
+   * mounted. Each is single-flighted or load-once in its store, so this costs nothing when the
+   * board already asked.
+   */
+  function refresh() {
+    void loadModels()
+    void providerConnections.ensureLoaded()
+    void github.ensureProbed()
+  }
+
+  const patCheck = computed(() => github.patCheck)
+  const patProblem = computed<'rejected' | 'underscoped' | null>(() => {
+    const check = patCheck.value
+    if (!check || !githubPatCheckNeedsAttention(check)) return null
+    return check.state === 'token_rejected' ? 'rejected' : 'underscoped'
+  })
+
+  const checklist = computed(() =>
+    deriveSetupChecklist({
+      model: {
+        loaded: ai.ready.value,
+        loadFailed: modelLoadFailed.value,
+        usable: ai.hasUsableModel.value,
+        presetBroken: ai.defaultPresetBroken.value,
+      },
+      sourceControl: {
+        available: github.available,
+        unavailableCause: github.unavailableCause,
+        connected: github.connected,
+        patMissing: patMissing.value,
+        patProblem: patProblem.value,
+      },
+      infra: workspace.infraSetup ?? null,
+      workspaceLoaded: workspace.ready,
+      infraOwners: workspace.infraSetupOwners ?? null,
+      providers: {
+        loaded: providerConnections.loaded,
+        needingConfig: providerConnections.needingConfig,
+      },
+      actor: actor.value,
+    }),
+  )
+
+  /**
+   * Where a row's action goes, by row AND state, through the remedies the matching banner uses.
+   * Null where there is nothing to open: the deployment does not use the area, or does not report
+   * it.
+   */
+  function actionFor(row: SetupRow): (() => void) | null {
+    if (row.status === 'not_needed' || row.status === 'checking') return null
+    if (row.cause === 'notReported') return null
+    switch (row.id) {
+      case 'model':
+        if (row.cause === 'probeFailed') return () => void loadModels()
+        if (row.status === 'missing') return remedies.openModelSetup
+        if (row.cause === 'presetBroken') return remedies.openPresetMismatch
+        return () => ui.openModelProviders()
+      case 'sourceControl': {
+        const setupUrl = remedies.patSetupUrl.value
+        if (setupUrl) return () => window.open(setupUrl, '_blank', 'noopener')
+        if (row.cause === 'rejected' || row.cause === 'underscoped') {
+          const remint = remedies.patRemintUrl.value
+          return () => window.open(remint, '_blank', 'noopener')
+        }
+        if (row.cause === 'probeFailed') return () => void github.probe()
+        return () => ui.openGitHub()
+      }
+      case 'agentExecutor':
+      case 'ephemeralEnvironments':
+      case 'binaryStorage': {
+        const area = row.id
+        return () => remedies.openInfraArea(area)
+      }
+      default: {
+        const unreachable: never = row.id
+        return unreachable
+      }
+    }
+  }
+
+  return { checklist, actionFor, refresh, patSource: remedies.patSource, patMissing }
+}

package/app/composables/useSetupRemedies.ts

@@ -0,0 +1,72 @@
+import { computed } from 'vue'
+import { githubPatCheckSource } from '@cat-factory/contracts'
+import type { GitHubPatKind, InfraSetupArea } from '~/types/domain'
+import { githubPatRemintUrl } from '~/utils/vcs'
+
+/**
+ * Where each setup gap is fixed: the ONE map the setup banners and the setup checklist both open
+ * through, so "the row opens what its banner opens" holds because there is one place that says
+ * it, never two copies kept in step by hand.
+ *
+ * Keyed by `InfraSetupArea` for the infrastructure, the vocabulary the server reports in, plus the
+ * model and source-control remedies, which have no area of their own.
+ */
+export function useSetupRemedies() {
+  const ui = useUiStore()
+  const auth = useAuthStore()
+  const github = useGitHubStore()
+
+  const INFRA: Record<InfraSetupArea, () => void> = {
+    agentExecutor: () => ui.openProviderConnection('runner-pool'),
+    ephemeralEnvironments: () => ui.openProviderConnection('environment'),
+    binaryStorage: () => ui.openContentStorageSettings(),
+  }
+
+  /** Open the screen that configures an infrastructure area. */
+  function openInfraArea(area: InfraSetupArea) {
+    INFRA[area]()
+  }
+
+  /** No usable model: the AI onboarding dialog. */
+  function openModelSetup() {
+    ui.openAiProviderSetup()
+  }
+
+  /** Usable models, but the default preset names one that is not: the preset-mismatch dialog. */
+  function openPresetMismatch() {
+    ui.openAiPresetMismatch()
+  }
+
+  /** Local mode with no token: GitHub's token page, scopes preselected. Null outside that case. */
+  const patSetupUrl = computed(() => auth.localMode?.githubPatSetupUrl ?? null)
+
+  /**
+   * The token page for a token GitHub rejected or under-scoped. A rejected token was never
+   * classified, so it falls back to `unknown`, which lands on the classic form, the only one
+   * GitHub lets us pre-fill.
+   */
+  const patReport = computed(() =>
+    github.patCheck?.state === 'checked' ? github.patCheck.report : undefined,
+  )
+  /** The token's kind, which picks the form. `unknown` for a token GitHub rejected outright. */
+  const patKind = computed<GitHubPatKind>(() => patReport.value?.kind ?? 'unknown')
+  const patRemintUrl = computed(() =>
+    githubPatRemintUrl(patKind.value, patReport.value?.webUrl ?? github.connection?.webUrl),
+  )
+
+  /**
+   * Whose token that is: the deployment's (replaced by whoever runs it) or the person's own
+   * (replaced in their settings). Read off the check, which carries it in every state it reports.
+   */
+  const patSource = computed(() => (github.patCheck ? githubPatCheckSource(github.patCheck) : null))
+
+  return {
+    openInfraArea,
+    openModelSetup,
+    openPresetMismatch,
+    patSetupUrl,
+    patKind,
+    patRemintUrl,
+    patSource,
+  }
+}