@cat-factory/app 0.176.0 → 0.178.0

package/app/components/settings/ComposeEnvironmentSetupSection.vue

@@ -0,0 +1,102 @@
+<script setup lang="ts">
+// The guided per-service Docker Compose environment setup, as a section of the Infrastructure
+// window's "Test environments" tab.
+//
+// It used to be its own top-level sidebar destination called "Environment setup", which was
+// wrong twice over: the name said nothing about WHAT it sets up (people read it as the place
+// to configure environments in general, which is the rest of this tab), and a wizard that
+// fills in one field of one service's config sat at the same level as the workspace-wide
+// infrastructure it depends on. It lives here now, next to the two settings it writes: the
+// service's provision type and the workspace's Docker Compose handler.
+//
+// The section deliberately carries a full explanation rather than a one-line hint. The wizard
+// is a five-minute flow that touches a repo and can trial-provision a stack, so "when you need
+// this / when you don't" has to be answerable BEFORE opening it — most services on most boards
+// never need it at all.
+const { t } = useI18n()
+const ui = useUiStore()
+
+/** Bullet lists rendered below; static literal keys so the typed-key check sees them. */
+const steps = computed(() => [
+  t('settings.composeEnvSetup.how.scan'),
+  t('settings.composeEnvSetup.how.analyse'),
+  t('settings.composeEnvSetup.how.preflight'),
+  t('settings.composeEnvSetup.how.save'),
+])
+const needed = computed(() => [
+  t('settings.composeEnvSetup.needed.running'),
+  t('settings.composeEnvSetup.needed.compose'),
+  t('settings.composeEnvSetup.needed.setup'),
+])
+const notNeeded = computed(() => [
+  t('settings.composeEnvSetup.notNeeded.inContainer'),
+  t('settings.composeEnvSetup.notNeeded.otherBackend'),
+  t('settings.composeEnvSetup.notNeeded.noRepo'),
+])
+
+// The wizard is its own modal, so hand over rather than stacking: close this window first.
+function start() {
+  ui.closeProviderConnection()
+  ui.openEnvironmentSetup()
+}
+</script>
+
+<template>
+  <section class="space-y-3" data-testid="compose-env-setup-section">
+    <div>
+      <h3 class="text-sm font-semibold text-slate-200">
+        {{ t('settings.composeEnvSetup.title') }}
+      </h3>
+      <p class="mt-1 text-xs leading-relaxed text-slate-400">
+        {{ t('settings.composeEnvSetup.lead') }}
+      </p>
+    </div>
+
+    <div class="rounded border border-slate-800 bg-slate-900/40 p-3">
+      <p class="text-[11px] font-medium uppercase tracking-wide text-slate-400">
+        {{ t('settings.composeEnvSetup.how.title') }}
+      </p>
+      <ol class="mt-2 list-decimal space-y-1 ps-4 text-[11px] leading-relaxed text-slate-400">
+        <li v-for="(step, i) in steps" :key="`how-${i}`">{{ step }}</li>
+      </ol>
+      <p class="mt-2 text-[11px] leading-relaxed text-slate-500">
+        {{ t('settings.composeEnvSetup.how.outcome') }}
+      </p>
+    </div>
+
+    <div class="grid gap-2 sm:grid-cols-2">
+      <div class="rounded border border-emerald-900/50 bg-emerald-950/20 p-3">
+        <p class="flex items-center gap-1.5 text-[11px] font-medium text-emerald-200/90">
+          <UIcon name="i-lucide-check" class="h-3.5 w-3.5 shrink-0" />
+          {{ t('settings.composeEnvSetup.needed.title') }}
+        </p>
+        <ul class="mt-1.5 list-disc space-y-1 ps-4 text-[11px] leading-relaxed text-slate-400">
+          <li v-for="(item, i) in needed" :key="`need-${i}`">{{ item }}</li>
+        </ul>
+      </div>
+      <div class="rounded border border-slate-800 bg-slate-900/40 p-3">
+        <p class="flex items-center gap-1.5 text-[11px] font-medium text-slate-300">
+          <UIcon name="i-lucide-minus" class="h-3.5 w-3.5 shrink-0" />
+          {{ t('settings.composeEnvSetup.notNeeded.title') }}
+        </p>
+        <ul class="mt-1.5 list-disc space-y-1 ps-4 text-[11px] leading-relaxed text-slate-400">
+          <li v-for="(item, i) in notNeeded" :key="`skip-${i}`">{{ item }}</li>
+        </ul>
+      </div>
+    </div>
+
+    <div class="flex items-center gap-2">
+      <UButton
+        size="xs"
+        color="primary"
+        variant="soft"
+        icon="i-lucide-wand-sparkles"
+        data-testid="compose-env-setup-start"
+        @click="start()"
+      >
+        {{ t('settings.composeEnvSetup.start') }}
+      </UButton>
+      <span class="text-[11px] text-slate-500">{{ t('settings.composeEnvSetup.rerunHint') }}</span>
+    </div>
+  </section>
+</template>

package/app/components/settings/InfrastructureWindow.vue

@@ -6,7 +6,10 @@
 //     mode — the warm-container-pool + checkout-reuse settings (the local agent-container
 //     runtime, folded in from the former LocalModeSettingsPanel).
 //   - "Test environments" — where the Tester's ephemeral environments run. Shows the test-env
-//     backend selector and the environment-provider connection.
+//     backend selector, the environment-provider connection, and the guided per-service Docker
+//     Compose setup (formerly a standalone "Environment setup" sidebar entry — it writes a
+//     service's Compose recipe plus the workspace's Compose handler, so it belongs beside the
+//     settings it edits rather than at the same level as them).
 // Local-specific affordances render inline, gated on `auth.localMode?.enabled`. A tab whose
 // backend integration is disabled (503) simply doesn't render.
 import { computed, ref, watch } from 'vue'
@@ -16,6 +19,7 @@ import InfraHandlersConfigurator from '~/components/settings/InfraHandlersConfig
 import DefaultProvisionTypeSection from '~/components/settings/DefaultProvisionTypeSection.vue'
 import LocalContainerPoolSettings from '~/components/settings/LocalContainerPoolSettings.vue'
 import SharedStacksPanel from '~/components/settings/SharedStacksPanel.vue'
+import ComposeEnvironmentSetupSection from '~/components/settings/ComposeEnvironmentSetupSection.vue'
 
 // The shared-stacks tab uses its own slot key beyond the provider-connection kinds.
 type InfraTabValue = ProviderConnectionKind | 'shared-stacks'
@@ -142,6 +146,12 @@ watch([tabs, () => store.loaded], () => {
               <div class="border-t border-slate-800 pt-4">
                 <InfraHandlersConfigurator />
               </div>
+              <!-- The guided per-SERVICE Compose flow (formerly the standalone "Environment
+                   setup" sidebar entry). Last, because it fills in one service's recipe on
+                   top of the workspace-wide choices above. -->
+              <div class="border-t border-slate-800 pt-4">
+                <ComposeEnvironmentSetupSection />
+              </div>
             </div>
           </template>
           <template #shared-stacks>

package/app/composables/api/validationChecks.ts

@@ -1,5 +1,6 @@
 import {
   deleteServiceValidationConfigContract,
+  detectServiceValidationChecksContract,
   getServiceValidationConfigContract,
   listServiceValidationConfigsContract,
   setServiceValidationConfigContract,
@@ -30,6 +31,13 @@ export function validationChecksApi({ send, ws }: ApiContext) {
         body,
       }),
 
+    /** Suggest checks from the service repo's manifests — a read; the operator still saves. */
+    detectServiceValidationChecks: (workspaceId: string, blockId: string) =>
+      send(detectServiceValidationChecksContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { blockId },
+      }),
+
     deleteServiceValidationConfig: (workspaceId: string, blockId: string) =>
       send(deleteServiceValidationConfigContract, {
         pathPrefix: ws(workspaceId),

package/app/composables/useIntegrationBack.ts

@@ -10,8 +10,9 @@ import type { Ref, WritableComputedRef } from 'vue'
  * resort to an obscure comma-operator expression. A named handler reads clearly instead.
  *
  * Returns to whichever hub the panel was reached from: the user-scoped "My setup" hub when
- * `cameFromPersonal` is set, else the workspace Integrations hub. A shared panel (e.g. the
- * vendor-credentials modal, reachable from both) thus lands the user back where they were.
+ * `cameFromPersonal` is set, the Model providers hub when `cameFromModelProviders` is set,
+ * else the workspace Integrations hub. A shared panel (e.g. the vendor-credentials modal,
+ * reachable from all three) thus lands the user back where they were.
  *
  * Pass the panel's `open` model (the writable ref/computed bound to its `UModal`).
  */
@@ -19,8 +20,10 @@ export function useIntegrationBack(open: Ref<boolean> | WritableComputedRef<bool
   const ui = useUiStore()
   return () => {
     const toPersonal = ui.cameFromPersonal
+    const toModelProviders = ui.cameFromModelProviders
     open.value = false
     if (toPersonal) ui.openPersonalSetup()
+    else if (toModelProviders) ui.openModelProviders()
     else ui.openIntegrations()
   }
 }

package/app/composables/useNavContributions.ts

@@ -33,10 +33,10 @@ export function useNavContributions() {
     addFromRepo: () => ui.openAddService(),
     bootstrapRepo: () => ui.openBootstrap(),
     integrationsHub: () => ui.openIntegrations(),
+    modelProviders: () => ui.openModelProviders(),
     sandbox: () => ui.openSandbox(),
     kaizen: () => ui.openKaizen(),
     infrastructure: () => ui.openInfrastructure(),
-    environmentSetup: () => ui.openEnvironmentSetup(),
     fragmentLibrary: () => ui.openFragmentLibrary(),
     mergeThresholds: () => ui.openWorkspaceSettings('merge'),
     workspaceSettings: () => ui.openWorkspaceSettings(),

package/app/modular/nav-contributions.spec.ts

@@ -99,12 +99,15 @@ describe('navSlotFilter', () => {
     expect(kept).toContain('integrations-hub')
     expect(kept).toContain('workspace-settings')
     expect(kept).toContain('model-config')
+    // Model providers are NOT an integration: the split is what makes the engines findable.
+    expect(kept).toContain('model-providers')
     // ...and so does everything the everyday delivery loop runs on, however deep it feels:
     // authoring a flow, the standards library, and the PREnv/runner plumbing.
     expect(kept).toContain('build-pipeline')
     expect(kept).toContain('fragments')
+    // Also the only route to the guided per-service Compose environment setup, which folded
+    // into this window rather than staying a sibling nav entry.
     expect(kept).toContain('infrastructure')
-    expect(kept).toContain('environment-setup')
     // What drops is either a shortcut basic mode reaches another way, or a capability
     // deliberately kept out of the tier (experimentation, one-off repo setup, the
     // deployment-wide operator rollups).
@@ -134,7 +137,7 @@ describe('navSlotFilter', () => {
       },
       'local-models': {
         kind: 'reached-another-way',
-        why: 'integrations-hub -> Local runners',
+        why: 'model-providers -> My local runners',
       },
       sandbox: {
         kind: 'out-of-tier',
@@ -250,6 +253,7 @@ describe('NAV_CONTRIBUTIONS catalog integrity', () => {
     for (const group of [
       'create',
       'repositories',
+      'models',
       'integrations',
       'infrastructure',
       'workspaceContext',
@@ -275,15 +279,19 @@ describe('nav grouping helpers', () => {
     expect(groups.map((g) => g.group)).toEqual([
       'create',
       'repositories',
+      'models',
       'integrations',
       'infrastructure',
       'workspaceContext',
       'configuration',
     ])
+    // The engines are their own section, ahead of the optional integrations; `model-config`
+    // sits beside the providers it picks models from rather than under `configuration`.
+    const models = groups.find((g) => g.group === 'models')
+    expect(models?.items.map((i) => i.id)).toEqual(['model-providers', 'model-config'])
     const configuration = groups.find((g) => g.group === 'configuration')
     expect(configuration?.items.map((i) => i.id)).toEqual([
       'workspace-settings',
-      'model-config',
       'account-settings',
       'operator-dashboard',
       'reports',

package/app/modular/nav-contributions.ts

@@ -25,10 +25,21 @@ export type { AppSlots } from './slots'
 /** Which shell(s) render a contribution. */
 export type NavSurface = 'sidebar' | 'command' | 'toolbar'
 
-/** Sidebar section a contribution lands in (its i18n header is `nav.<group>`). */
+/**
+ * Sidebar section a contribution lands in (its i18n header is `nav.<group>`).
+ *
+ * `models` and `integrations` are deliberately SEPARATE sections even though a model
+ * provider is technically also an external system we connect to. They answer different
+ * questions: `models` is the ENGINE the harnesses run on (no provider ⇒ nothing runs at
+ * all), `integrations` is the optional systems that feed a run context or receive its
+ * output (source control, trackers, documents, chat, observability) — each of which a
+ * deployment can live without. Folding the providers in among them buried the one
+ * connection every deployment must make in a list of ones most never touch.
+ */
 export type NavSidebarGroup =
   | 'create'
   | 'repositories'
+  | 'models'
   | 'integrations'
   | 'infrastructure'
   | 'workspaceContext'
@@ -90,10 +101,10 @@ export const NAV_ACTIONS = [
   'addFromRepo',
   'bootstrapRepo',
   'integrationsHub',
+  'modelProviders',
   'sandbox',
   'kaizen',
   'infrastructure',
-  'environmentSetup',
   'fragmentLibrary',
   'mergeThresholds',
   'workspaceSettings',
@@ -164,7 +175,7 @@ const S = (...s: NavSurface[]) => s as readonly NavSurface[]
  *  - `merge-thresholds` / `service-fragment-defaults` — palette shortcuts into Workspace
  *    settings tabs (Merge, Service best practices), which basic mode reaches via
  *    `workspace-settings`.
- *  - `local-models` — a per-user endpoint knob the Integrations hub already offers.
+ *  - `local-models` — a per-user endpoint knob the Model providers hub already offers.
  *
  * OUT OF THE TIER — the sole route, hidden deliberately, so the capability itself is absent
  * from basic mode. This is a product decision, not an oversight: each of these answers a
@@ -180,8 +191,9 @@ const S = (...s: NavSurface[]) => s as readonly NavSurface[]
  *
  * Everything else stays in basic because the delivery loop needs it: authoring a flow
  * (`build-pipeline`), adding a repo (`add-from-repo`), the standards/skills library
- * (`fragments`), the PREnv + runner plumbing (`infrastructure`, `environment-setup`), and the
- * workspace/model configuration a run actually reads (`workspace-settings`, `model-config`).
+ * (`fragments`), the PREnv + runner plumbing (`infrastructure`, which is also the only route
+ * to the guided per-service Compose environment setup), and the workspace/model configuration
+ * a run actually reads (`workspace-settings`, `model-config`).
  */
 export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
   {
@@ -233,6 +245,19 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
       keywordsKey: 'layout.commandBar.keywords.bootstrapRepo',
     },
   },
+  {
+    // The engines. Kept out of `integrations-hub` on purpose (see NavSidebarGroup): a
+    // deployment with no provider connected cannot run anything, so this is the one
+    // connection that must not sit in a list of optional ones.
+    id: 'model-providers',
+    labelKey: 'nav.modelProviders',
+    icon: 'i-lucide-plug-zap',
+    surfaces: S('sidebar'),
+    gate: (g) => g.canManageIntegrations,
+    action: 'modelProviders',
+    testId: 'nav-model-providers',
+    sidebar: { group: 'models', order: 10 },
+  },
   {
     id: 'integrations-hub',
     labelKey: 'nav.integrations',
@@ -280,16 +305,6 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     testId: 'nav-infrastructure',
     sidebar: { group: 'infrastructure', order: 10 },
   },
-  {
-    id: 'environment-setup',
-    labelKey: 'nav.environmentSetup',
-    icon: 'i-lucide-flask-conical',
-    surfaces: S('sidebar'),
-    gate: (g) => g.infrastructureAvailable,
-    action: 'environmentSetup',
-    testId: 'nav-environment-setup',
-    sidebar: { group: 'infrastructure', order: 20 },
-  },
   {
     id: 'fragments',
     labelKey: 'nav.contextFragments',
@@ -344,7 +359,10 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     gate: (g) => g.canManageSettings,
     action: 'modelConfiguration',
     testId: 'nav-model-config',
-    sidebar: { group: 'configuration', order: 20 },
+    // Beside `model-providers`, not in `configuration`: "which key do we hold" and "which
+    // model does each agent kind use" are two halves of one question, and splitting them
+    // across sections is what sent people to Integrations looking for a model.
+    sidebar: { group: 'models', order: 20 },
     command: {
       group: 'workspace',
       order: 40,
@@ -491,6 +509,7 @@ export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppS
 export const SIDEBAR_GROUP_ORDER: readonly NavSidebarGroup[] = [
   'create',
   'repositories',
+  'models',
   'integrations',
   'infrastructure',
   'workspaceContext',

package/app/pages/index.vue

@@ -89,6 +89,9 @@ const ModelPresetHealthModal = defineAsyncComponent(
 const IntegrationsHub = defineAsyncComponent(
   () => import('~/components/layout/IntegrationsHub.vue'),
 )
+const ModelProvidersHub = defineAsyncComponent(
+  () => import('~/components/layout/ModelProvidersHub.vue'),
+)
 const PersonalSetupModal = defineAsyncComponent(
   () => import('~/components/layout/PersonalSetupModal.vue'),
 )
@@ -429,6 +432,7 @@ watch(
       <RiskPolicyHealthModal v-if="ui.riskPolicyHealthOpen" />
       <ModelPresetHealthModal v-if="ui.modelPresetHealthOpen" />
       <IntegrationsHub v-if="ui.integrationsOpen" />
+      <ModelProvidersHub v-if="ui.modelProvidersOpen" />
       <PersonalSetupModal v-if="ui.personalSetupOpen" />
       <WorkspaceSettingsPanel v-if="ui.workspaceSettingsOpen" />
       <AccountSettingsPanel v-if="ui.accountSettingsOpen" />

package/app/stores/ui/modals.ts

@@ -952,20 +952,28 @@ function createConsumerOverlayHost() {
  * the shared hub came-from markers.
  */
 export function createUiModals() {
-  // Integrations / My-setup hub came-from markers — the one piece of state SHARED across slices
-  // (many `open*` handlers reset it), so it lives here and `resetHubReturn` is threaded into the
-  // slices that need it. `cameFromIntegrations` is true while an integration's own panel is showing
-  // AND it was reached from the Integrations hub; `cameFromPersonal` is the My-setup analogue.
+  // Model-providers / Integrations / My-setup hub came-from markers — the one piece of state
+  // SHARED across slices (many `open*` handlers reset it), so it lives here and `resetHubReturn`
+  // is threaded into the slices that need it. `cameFromIntegrations` is true while an
+  // integration's own panel is showing AND it was reached from the Integrations hub;
+  // `cameFromModelProviders` and `cameFromPersonal` are the analogues for the other two hubs.
+  //
+  // Three hubs, not two, because the vendor-credentials / OpenRouter / local-runner panels are
+  // reachable from more than one of them and a Back control that lands somewhere the user was
+  // never at is worse than none.
   const cameFromIntegrations = ref(false)
+  const cameFromModelProviders = ref(false)
   const cameFromPersonal = ref(false)
   const integrationsOpen = ref(false)
+  const modelProvidersOpen = ref(false)
   const personalSetupOpen = ref(false)
 
-  // Clear BOTH hub came-from markers. Every direct `open*` in the slices calls this so that a
+  // Clear EVERY hub came-from marker. Every direct `open*` in the slices calls this so that a
   // panel opened outside the hubs never grows a dead Back control, and so switching from one
-  // hub's panel to the other's clears the stale marker.
+  // hub's panel to another's clears the stale marker.
   function resetHubReturn() {
     cameFromIntegrations.value = false
+    cameFromModelProviders.value = false
     cameFromPersonal.value = false
   }
   function openIntegrations() {
@@ -977,6 +985,13 @@ export function createUiModals() {
   function closeIntegrations() {
     integrationsOpen.value = false
   }
+  function openModelProviders() {
+    resetHubReturn()
+    modelProvidersOpen.value = true
+  }
+  function closeModelProviders() {
+    modelProvidersOpen.value = false
+  }
   function openPersonalSetup() {
     resetHubReturn()
     personalSetupOpen.value = true
@@ -1000,6 +1015,12 @@ export function createUiModals() {
     cameFromIntegrations.value = true
     integrationsOpen.value = false
   }
+  // The Model-providers analogue of `openFromIntegrations`.
+  function openFromModelProviders(open: () => void) {
+    open()
+    cameFromModelProviders.value = true
+    modelProvidersOpen.value = false
+  }
 
   const health = createHealthAdvisoryModals()
   const misc = createMiscModals()
@@ -1014,11 +1035,16 @@ export function createUiModals() {
   return {
     integrationsOpen,
     cameFromIntegrations,
+    modelProvidersOpen,
+    cameFromModelProviders,
     personalSetupOpen,
     cameFromPersonal,
     openIntegrations,
     closeIntegrations,
     openFromIntegrations,
+    openModelProviders,
+    closeModelProviders,
+    openFromModelProviders,
     openPersonalSetup,
     closePersonalSetup,
     openFromPersonal,

package/app/stores/validationChecks.ts

@@ -1,6 +1,10 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
-import type { ServiceValidationConfig, ValidationCheck } from '~/types/validationChecks'
+import type {
+  DetectedValidationChecks,
+  ServiceValidationConfig,
+  ValidationCheck,
+} from '~/types/validationChecks'
 import { VALIDATION_DEFAULT_MAX_ATTEMPTS } from '~/types/validationChecks'
 import { useUpsertList } from '~/composables/useUpsertList'
 import { useWorkspaceStore } from '~/stores/workspace'
@@ -107,5 +111,16 @@ export const useValidationChecksStore = defineStore('validationChecks', () => {
     dropLocal(blockId)
   }
 
-  return { configs, loading, available, load, ensureLoaded, forBlock, save, remove }
+  /**
+   * Ask the backend what this service's repo implies. Nothing is stored: the suggestion goes
+   * into the panel's unsaved rows, so the operator reviews and saves it like anything they
+   * typed. Deliberately NOT folded into `configs` — a suggestion that looked like saved
+   * config would report a service as configured when no run would run a single command.
+   */
+  async function detect(blockId: string): Promise<DetectedValidationChecks> {
+    const ws = useWorkspaceStore()
+    return api.detectServiceValidationChecks(ws.requireId(), blockId)
+  }
+
+  return { configs, loading, available, load, ensureLoaded, forBlock, save, remove, detect }
 })

package/app/types/validationChecks.ts

@@ -9,6 +9,9 @@ export type {
   ValidationReport,
   ServiceValidationConfig,
   UpsertServiceValidationConfigInput,
+  DetectedValidationChecks,
+  ValidationDetectionStatus,
+  ValidationEcosystem,
 } from '@cat-factory/contracts'
 export {
   VALIDATION_DEFAULT_MAX_ATTEMPTS,

package/app/utils/validationDetection.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+import { mergeDetectedChecks } from './validationDetection'
+
+const check = (label: string, command: string) => ({ label, command })
+
+describe('mergeDetectedChecks', () => {
+  it('appends suggestions to an empty (or blank-row) panel', () => {
+    const result = mergeDetectedChecks(
+      [check('', '')],
+      [check('install', 'pnpm install --frozen-lockfile'), check('lint', 'pnpm run lint')],
+      10,
+    )
+    expect(result.rows).toEqual([
+      check('install', 'pnpm install --frozen-lockfile'),
+      check('lint', 'pnpm run lint'),
+    ])
+    expect(result.added).toBe(2)
+    expect(result.dropped).toBe(0)
+  })
+
+  it('never rewrites or duplicates what the operator already has', () => {
+    // The same command with a hand-tuned label must survive untouched, and pressing Detect
+    // again must be a no-op rather than a second copy of every check.
+    const existing = [check('our lint', 'pnpm run lint')]
+    const result = mergeDetectedChecks(existing, [check('lint', 'pnpm run lint')], 10)
+    expect(result.rows).toEqual(existing)
+    expect(result.added).toBe(0)
+  })
+
+  it('disambiguates a label that collides with an existing row', () => {
+    // A duplicate label is REJECTED by the write contract, so a collision the merge created
+    // would surface as a save error on a row the operator never typed.
+    const result = mergeDetectedChecks(
+      [check('test', 'make test')],
+      [check('test', 'go test ./...')],
+      10,
+    )
+    expect(result.rows.map((r) => r.label)).toEqual(['test', 'test 2'])
+  })
+
+  it('reports what the row cap dropped instead of silently truncating', () => {
+    const result = mergeDetectedChecks(
+      [check('lint', 'pnpm run lint')],
+      [check('test', 'pnpm run test'), check('build', 'pnpm run build')],
+      2,
+    )
+    expect(result.rows).toHaveLength(2)
+    expect(result.added).toBe(1)
+    expect(result.dropped).toBe(1)
+  })
+})

package/app/utils/validationDetection.ts

@@ -0,0 +1,67 @@
+import type { ValidationCheck } from '~/types/validationChecks'
+
+// Folding an autodetected suggestion into the pre-PR validation panel's UNSAVED rows.
+//
+// Pure, and separate from the panel, because the merge carries the two rules that make the
+// button safe to press: it never destroys what the operator already typed, and it never
+// produces a row set the write contract would reject.
+
+/** What a merge did, so the panel can say something specific rather than "done". */
+export interface MergedDetection {
+  rows: ValidationCheck[]
+  /** Suggestions appended as new rows. */
+  added: number
+  /** Suggestions dropped because the row cap was already reached. */
+  dropped: number
+}
+
+/**
+ * Append detected checks to the rows already on screen.
+ *
+ * - A suggestion whose COMMAND is already present is skipped, so pressing Detect twice (or
+ *   pressing it on a service that is already configured) adds nothing rather than
+ *   duplicating every check.
+ * - Existing rows are never rewritten. The button is assistive; silently replacing an
+ *   operator's hand-tuned command with the generic guess would be a worse failure than not
+ *   detecting anything.
+ * - Wholly blank rows (an unused "Add check" click) are dropped first, so the suggestion
+ *   lands in a contiguous list instead of after a gap.
+ * - Labels are made unique against the surviving rows, because the write contract REJECTS a
+ *   duplicate label — a merge that produced one would surface as an unexplained save error
+ *   on rows the operator did not write.
+ */
+export function mergeDetectedChecks(
+  existing: ValidationCheck[],
+  detected: ValidationCheck[],
+  maxRows: number,
+): MergedDetection {
+  const rows = existing.filter((r) => r.label.trim() !== '' || r.command.trim() !== '')
+  const commands = new Set(rows.map((r) => r.command.trim()))
+  const labels = new Set(rows.map((r) => r.label.trim()).filter((l) => l !== ''))
+
+  let added = 0
+  let dropped = 0
+  for (const candidate of detected) {
+    const command = candidate.command.trim()
+    if (command === '' || commands.has(command)) continue
+    if (rows.length >= maxRows) {
+      dropped += 1
+      continue
+    }
+    const label = uniqueLabel(candidate.label.trim() || command, labels)
+    rows.push({ label, command })
+    commands.add(command)
+    labels.add(label)
+    added += 1
+  }
+  return { rows, added, dropped }
+}
+
+/** `lint` → `lint 2` → `lint 3` … until it no longer collides. Clamped to the contract's 80. */
+function uniqueLabel(base: string, taken: Set<string>): string {
+  if (!taken.has(base)) return base.slice(0, 80)
+  for (let n = 2; ; n += 1) {
+    const candidate = `${base} ${n}`.slice(0, 80)
+    if (!taken.has(candidate)) return candidate
+  }
+}