@cat-factory/app 0.198.1 → 0.200.0

package/app/modular/nav-contributions.ts

@@ -1,5 +1,6 @@
 import { defineModule } from '@modular-vue/core'
 import { resolveTours } from '~/utils/tutorial'
+import { filterExternalTools } from './external-tools'
 import type { AppSlots } from './slots'
 
 // Re-exported for the slice-1 importers that reach `AppSlots` through this
@@ -40,6 +41,12 @@ export type NavSurface = 'sidebar' | 'command' | 'toolbar'
  * in a list of ones most never touch; parking the two model-quality surfaces there was the
  * same mistake from the other end — neither Sandbox nor Kaizen connects to anything, they
  * evaluate what the `models` section configures.
+ *
+ * `externalTools` is the one section with NO first-party items: it holds the deployment's own
+ * applications (the `externalTools` slot, projected here by `useNavContributions`), and is
+ * dropped entirely where none are registered. It is separate from `integrations` for the same
+ * reason `models` is — an integration is a system cat-factory READS FROM or WRITES TO on your
+ * behalf, while these are places a person GOES.
  */
 export type NavSidebarGroup =
   | 'create'
@@ -48,10 +55,17 @@ export type NavSidebarGroup =
   | 'integrations'
   | 'infrastructure'
   | 'workspaceContext'
+  | 'externalTools'
   | 'configuration'
 
 /** Command-palette group (its i18n label is `layout.commandBar.groups.<group>`). */
-export type NavCommandGroup = 'create' | 'repositories' | 'integrations' | 'workspace' | 'account'
+export type NavCommandGroup =
+  | 'create'
+  | 'repositories'
+  | 'integrations'
+  | 'externalTools'
+  | 'workspace'
+  | 'account'
 
 /**
  * The reactive gate inputs a contribution's `gate` predicate reads. Backed by a
@@ -154,6 +168,7 @@ export const NAV_ACTIONS = [
   'kaizen',
   'infrastructure',
   'fragmentLibrary',
+  'foundationalServices',
   'mergeThresholds',
   'workspaceSettings',
   'modelConfiguration',
@@ -174,6 +189,14 @@ export interface NavContribution {
   id: string
   /** Default (sidebar) label i18n key. */
   labelKey: string
+  /**
+   * Literal label, winning over {@link labelKey} when present. For a contribution whose copy is
+   * DATA rather than catalog text — an external tool's registered title, the same class as a
+   * custom agent kind's `presentation.label`. A first-party destination always uses `labelKey`.
+   */
+  label?: string
+  /** Literal one-line description, rendered as the item's tooltip. Data, like {@link label}. */
+  description?: string
   icon: string
   surfaces: readonly NavSurface[]
   /** Reactive predicate over {@link NavGates}; absent = always visible. */
@@ -343,6 +366,31 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
       keywordsKey: 'layout.commandBar.keywords.fragments',
     },
   },
+  {
+    // Registering the shared capabilities the ORGANISATION already runs, so a design consumes
+    // them instead of proposing a rebuild. Advanced: the everyday delivery loop (plan a task,
+    // run it, review and merge it) never touches this — it is org-wide platform configuration,
+    // set up once by whoever knows the estate, and a board can deliver its whole backlog with an
+    // empty catalog. Beside the fragment library in `workspaceContext`, because both answer
+    // "what standing context does an agent get?".
+    id: 'foundational-services',
+    labelKey: 'nav.foundationalServices',
+    icon: 'i-lucide-boxes',
+    surfaces: S('sidebar', 'command'),
+    advanced: true,
+    gate: (g) => g.canManageSettings,
+    action: 'foundationalServices',
+    testId: 'nav-foundational-services',
+    sidebar: { group: 'workspaceContext', order: 20 },
+    command: {
+      // Appended after the pre-existing workspace commands rather than interleaved beside the
+      // fragment library, so the palette order people already know is unchanged.
+      group: 'workspace',
+      order: 110,
+      labelKey: 'layout.commandBar.cmd.foundationalServices',
+      keywordsKey: 'layout.commandBar.keywords.foundationalServices',
+    },
+  },
   {
     id: 'merge-thresholds',
     labelKey: 'layout.commandBar.cmd.mergeThresholds',
@@ -568,6 +616,7 @@ export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppS
   const gates = deps.gates
   const nav = slots.nav ?? []
   const tutorialTours = slots.tutorialTours ?? []
+  const externalTools = slots.externalTools ?? []
   return {
     ...slots,
     // No gates service wired (tests / bare install) ⇒ show everything, matching
@@ -582,6 +631,10 @@ export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppS
     // about a branch this board isn't on is dropped rather than skipped (see `resolveTours`).
     // Same gates-absent pass-through as `nav`.
     tutorialTours: gates ? resolveTours(tutorialTours, gates) : tutorialTours,
+    // External tools gate on the same two axes as `nav` — they become nav items downstream
+    // (`useNavContributions` projects them), so gating them anywhere else would let a tool the
+    // caller can't use reach the palette while its sidebar twin was correctly hidden.
+    externalTools: filterExternalTools(externalTools, gates),
   }
 }
 
@@ -593,6 +646,9 @@ export const SIDEBAR_GROUP_ORDER: readonly NavSidebarGroup[] = [
   'integrations',
   'infrastructure',
   'workspaceContext',
+  // The deployment's own applications, below what cat-factory itself offers and above the
+  // configuration tail: they are destinations someone reaches mid-work, not settings.
+  'externalTools',
   'configuration',
 ]
 
@@ -601,6 +657,7 @@ export const COMMAND_GROUP_ORDER: readonly NavCommandGroup[] = [
   'create',
   'repositories',
   'integrations',
+  'externalTools',
   'workspace',
   'account',
 ]

package/app/modular/registry.ts

@@ -111,6 +111,8 @@ export function createAppRegistry(
       taskTypeFormPanels: [],
       appOverlays: [],
       tutorialTours: [],
+      externalTools: [],
+      workspaceMetadataFields: [],
     },
   }).use(journeysPlugin())
   for (const mod of [...FIRST_PARTY_MODULES, ...extraModules, ...consumerModules]) {

package/app/modular/slots.ts

@@ -3,6 +3,8 @@ import type { ComponentEntry, PanelEntry } from '@modular-vue/core'
 import type { Block, CustomAgentKind, CustomTaskType } from '~/types/domain'
 import type { TutorialTour } from '~/utils/tutorial'
 import type { NavContribution } from './nav-contributions'
+import type { ExternalToolContribution } from './external-tools'
+import type { WorkspaceMetadataFieldDefinition } from './workspace-metadata'
 
 /**
  * The layer's aggregated slot map — the single home for every slot key the
@@ -37,6 +39,17 @@ import type { NavContribution } from './nav-contributions'
  *    from `modular/tutorial-tours.ts`; a consumer contributes its own to the same slot
  *    and they appear in the launch prompt beside the built-ins, gated per tour by its
  *    `when(gates)` predicate in the same reactive `slotFilter` that gates `nav`.
+ *  - `externalTools` — the deployment's OWN web applications, listed in their own
+ *    "External tools" sidebar section ({@link ExternalToolContribution}). Each entry resolves
+ *    its URL from the invocation context (user, workspace, the custom metadata below), so the
+ *    tool opens already scoped to what the user is looking at; `useNavContributions` projects
+ *    the gated slot onto the nav catalog, so the three shells render them like any other
+ *    destination. Data-only, like `tutorialTours` — no components.
+ *  - `workspaceMetadataFields` — the CUSTOM workspace metadata fields a deployment declares
+ *    ({@link WorkspaceMetadataFieldDefinition}). The definitions are code-shipped here; the
+ *    VALUES are per-workspace, typed into the settings panel and persisted on the workspace
+ *    settings row. The pair exists so an external tool can be handed a workspace-specific id
+ *    (`gameId`) the platform itself has no opinion about.
  *  - `appOverlays` (extension slice D) — top-level modals/overlays a consumer module
  *    contributes ({@link OverlayContribution}, an id → component `ComponentEntry`),
  *    opened by `ui.openOverlay(id, subject?)` / `useAppOverlays().open(...)` and
@@ -59,6 +72,8 @@ export interface AppSlots {
   taskTypeFormPanels: ResultViewContribution[]
   appOverlays: OverlayContribution[]
   tutorialTours: TutorialTour[]
+  externalTools: ExternalToolContribution[]
+  workspaceMetadataFields: WorkspaceMetadataFieldDefinition[]
   [key: string]: unknown[]
 }
 

package/app/modular/workspace-metadata.spec.ts

@@ -0,0 +1,160 @@
+import * as v from 'valibot'
+import { workspaceMetadataKeySchema } from '@cat-factory/contracts'
+import { describe, expect, it } from 'vitest'
+import {
+  isValidMetadataKey,
+  metadataDraftFrom,
+  metadataPatchFrom,
+  metadataValue,
+  resolveMetadataFields,
+  toMetadataBag,
+  type WorkspaceMetadataFieldDefinition,
+} from './workspace-metadata'
+
+const field = (
+  key: string,
+  extra: Partial<WorkspaceMetadataFieldDefinition> = {},
+): WorkspaceMetadataFieldDefinition => ({ key, label: key, ...extra })
+
+describe('isValidMetadataKey', () => {
+  it.each(['gameId', 'a', 'game.id', 'game-id', 'game_id', 'g1'])('accepts %s', (key) => {
+    expect(isValidMetadataKey(key)).toBe(true)
+  })
+
+  it.each(['', '1game', 'game id', 'game/id', 'game%id', '_game', 'a'.repeat(65)])(
+    'rejects %s',
+    (key) => {
+      expect(isValidMetadataKey(key)).toBe(false)
+    },
+  )
+
+  // The pattern is mirrored from the contract rather than imported (the contract expresses it
+  // as a valibot schema). This is what keeps the two copies from drifting: a key the editor
+  // renders but the store refuses would 422 every save with a message about a key the operator
+  // never typed.
+  it.each(['gameId', 'game.id-1', '1game', 'game id', 'a'.repeat(65)])(
+    'agrees with the contract schema on %s',
+    (key) => {
+      expect(isValidMetadataKey(key)).toBe(v.safeParse(workspaceMetadataKeySchema, key).success)
+    },
+  )
+})
+
+// A field key only has to be identifier-shaped, and `constructor` / `toString` / `valueOf` all
+// are. On a plain object each of those reads as an inherited FUNCTION for a field nobody has
+// filled in — truthy where the code expects `undefined`, and not a string where the code expects
+// one. These two helpers are what stop that reaching a required-metadata check, a resolver, or
+// the editor's draft.
+describe('metadataValue', () => {
+  it('reads a stored value', () => {
+    expect(metadataValue({ gameId: 'zork' }, 'gameId')).toBe('zork')
+  })
+
+  it.each(['constructor', 'toString', 'valueOf', 'hasOwnProperty'])(
+    'reads an unfilled %s as undefined rather than an inherited member',
+    (key) => {
+      expect(metadataValue({}, key)).toBeUndefined()
+    },
+  )
+
+  it('reads a non-string value as undefined', () => {
+    // The bag arrives via `JSON.parse`, so its shape is only as good as what was stored.
+    expect(
+      metadataValue({ gameId: 7 } as unknown as Record<string, string>, 'gameId'),
+    ).toBeUndefined()
+  })
+})
+
+describe('toMetadataBag', () => {
+  it('hangs the bag on a null prototype so a plain property read is total', () => {
+    // A resolver is a deployment's own code writing `ctx.metadata.gameId`; it cannot be made to
+    // call `metadataValue`, so the object it receives has to be safe by construction.
+    const bag = toMetadataBag({ gameId: 'zork' })
+
+    expect(bag.gameId).toBe('zork')
+    expect(Object.getPrototypeOf(bag)).toBeNull()
+    expect((bag as Record<string, unknown>).constructor).toBeUndefined()
+  })
+})
+
+describe('resolveMetadataFields', () => {
+  it('orders by declared order and keeps the first declaration of a duplicate key', () => {
+    const first = field('gameId', { order: 2, label: 'Game' })
+    const { fields, rejected } = resolveMetadataFields([
+      first,
+      field('region', { order: 1 }),
+      field('gameId', { label: 'Game (again)' }),
+    ])
+
+    expect(fields.map((f) => f.key)).toEqual(['region', 'gameId'])
+    expect(fields.find((f) => f.key === 'gameId')).toBe(first)
+    expect(rejected).toHaveLength(1)
+  })
+
+  it('drops a malformed key and hands it back rather than swallowing it', () => {
+    const bad = field('not a key')
+    const { fields, rejected } = resolveMetadataFields([field('gameId'), bad])
+
+    // Rendering it would build an editor whose every save is refused by the store.
+    expect(fields.map((f) => f.key)).toEqual(['gameId'])
+    expect(rejected).toEqual([bad])
+  })
+})
+
+describe('metadataDraftFrom', () => {
+  it('seeds every declared field, blank where the workspace has no value', () => {
+    expect(metadataDraftFrom([field('gameId'), field('region')], { gameId: 'zork' })).toEqual({
+      gameId: 'zork',
+      region: '',
+    })
+  })
+})
+
+describe('metadataPatchFrom', () => {
+  const fields = [field('gameId'), field('region')]
+
+  it('submits the trimmed non-empty values', () => {
+    expect(metadataPatchFrom(fields, { gameId: ' zork ', region: 'eu' }, {})).toEqual({
+      gameId: 'zork',
+      region: 'eu',
+    })
+  })
+
+  it('drops a cleared field, which is how the editor deletes a value', () => {
+    expect(metadataPatchFrom(fields, { gameId: 'zork', region: '  ' }, { region: 'eu' })).toEqual({
+      gameId: 'zork',
+    })
+  })
+
+  it('carries a stored key no field renders into the patch', () => {
+    // The update REPLACES the bag, so a value written under a field this build no longer
+    // declares (a mid-rollout deployment, a retired field still read by something) would be
+    // deleted by an unrelated save.
+    expect(
+      metadataPatchFrom(fields, { gameId: 'zork', region: '' }, { legacyId: 'keep-me' }),
+    ).toEqual({ gameId: 'zork', legacyId: 'keep-me' })
+  })
+
+  it('lets a rendered field win over the stored value it edits', () => {
+    expect(metadataPatchFrom(fields, { gameId: 'myst', region: '' }, { gameId: 'zork' })).toEqual({
+      gameId: 'myst',
+    })
+  })
+
+  it("coerces a number field's draft value instead of throwing on it", () => {
+    // A `number` field renders `<UInput type="number">`, whose v-model hands back a NUMBER
+    // however the draft is typed — `.trim()` on it is a TypeError, surfaced to the operator as
+    // an opaque "save failed". `BudgetSettings.vue` wraps the same control in `String(...)`.
+    const numeric = [field('port', { type: 'number' })]
+    expect(metadataPatchFrom(numeric, { port: 8080 }, {})).toEqual({ port: '8080' })
+  })
+
+  it('keeps a stored key named after an Object member out of the prototype', () => {
+    const patch = metadataPatchFrom(fields, { gameId: 'zork', region: '' }, { toString: 'kept' })
+
+    expect(patch).toEqual({ gameId: 'zork', toString: 'kept' })
+    expect(Object.getPrototypeOf(patch)).toBeNull()
+    // The bag is JSON on the wire, and a null prototype changes nothing about that.
+    expect(JSON.parse(JSON.stringify(patch))).toEqual({ gameId: 'zork', toString: 'kept' })
+  })
+})

package/app/modular/workspace-metadata.ts

@@ -0,0 +1,173 @@
+import type { WorkspaceMetadata } from '~/types/domain'
+
+/**
+ * CUSTOM WORKSPACE METADATA FIELDS — the deployment declares the fields in code, an operator
+ * fills in the VALUES per workspace in the settings panel, and anything that needs
+ * workspace-specific context reads them back (today: an {@link ExternalToolUrlResolver}, which
+ * is what makes "open the map editor already switched to this board's game" a registration
+ * rather than a fork).
+ *
+ * Definitions are code-shipped rather than stored, for the same reason result views and task
+ * types are: they carry behaviour (which tool reads them, what a value means) that only the
+ * deployment knows, and a deployment must be able to add, rename and retire a field without a
+ * migration. The BACKEND therefore validates only the shape of the bag, never the field list
+ * (see `workspaceMetadataSchema` in `@cat-factory/contracts`).
+ *
+ * Pure — no Vue, no stores — so the editor's merge rules are unit-testable.
+ */
+
+/** How a field's value is edited. Stored as a string either way (the bag is a string map). */
+export type WorkspaceMetadataFieldType = 'text' | 'number' | 'select'
+
+/** One declared field. */
+export interface WorkspaceMetadataFieldDefinition {
+  /**
+   * The key the value is stored under and a resolver reads off `ctx.metadata`. Must be
+   * identifier-shaped (see {@link isValidMetadataKey}) — the backend refuses anything else, so
+   * a malformed key is dropped at boot rather than 422-ing the operator's save.
+   */
+  key: string
+  /** Field label. Literal copy, like an external tool's title: deployment data, not a key. */
+  label: string
+  /** Optional help text under the input. */
+  description?: string
+  /** Placeholder for the empty input. */
+  placeholder?: string
+  /** Input flavour; defaults to `text`. */
+  type?: WorkspaceMetadataFieldType
+  /** The choices for a `select` field. Ignored for the other types. */
+  options?: readonly { value: string; label: string }[]
+  /** Ordering within the metadata editor. Defaults to 0. */
+  order?: number
+}
+
+/**
+ * The key shape the backend accepts (mirrors `workspaceMetadataKeySchema`). Mirrored rather
+ * than imported as a value because the contract expresses it as a valibot schema; the pattern
+ * is pinned equal by `workspace-metadata.spec.ts`.
+ */
+const METADATA_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/
+
+/** Whether a declared key is one the store will accept. */
+export function isValidMetadataKey(key: string): boolean {
+  return METADATA_KEY_PATTERN.test(key)
+}
+
+/**
+ * Read one value out of a stored bag, as an OWN property.
+ *
+ * A plain `bag[key]` is not that. {@link METADATA_KEY_PATTERN} requires a leading letter, which
+ * keeps `__proto__` out, but `constructor`, `toString` and `valueOf` are all legal field keys —
+ * and on a plain object (which is what `JSON.parse` hands back) each of those reads as an
+ * INHERITED function rather than `undefined` when nobody has filled the field in. That is not a
+ * cosmetic difference: a truthy read makes `resolveExternalToolUrl`'s required-metadata check
+ * conclude the field IS set, and a function reaching the editor's draft is a `TypeError` on the
+ * next save. Both failures would name a field the operator never mistyped.
+ */
+export function metadataValue(
+  bag: Readonly<Record<string, unknown>>,
+  key: string,
+): string | undefined {
+  if (!Object.hasOwn(bag, key)) return undefined
+  const value = bag[key]
+  return typeof value === 'string' ? value : undefined
+}
+
+/**
+ * A stored bag re-hung on a NULL PROTOTYPE, so `bag.anything` is either a stored string or
+ * `undefined` for every reader.
+ *
+ * {@link metadataValue} is the disciplined way to read one key, but the bag's whole purpose is
+ * to be handed to a DEPLOYMENT'S OWN resolver, which writes `ctx.metadata.gameId` and cannot be
+ * made to call our helper. Sanitising the object once at that boundary is what makes the plain
+ * property access those resolvers will write correct by construction.
+ */
+export function toMetadataBag(stored: WorkspaceMetadata): Readonly<Record<string, string>> {
+  const bag: Record<string, string> = Object.create(null)
+  for (const [key, value] of Object.entries(stored)) {
+    if (typeof value === 'string') bag[key] = value
+  }
+  return bag
+}
+
+/**
+ * The fields to render: valid keys only, first declaration wins on a duplicate, ordered.
+ *
+ * A code-shipped definition is trusted the way a code-shipped task type is — no boot-time
+ * registry validation — so a malformed key is dropped HERE, with the rejects returned rather
+ * than swallowed, and the caller warns. Rendering it instead would produce an editor whose
+ * every save 422s with a message about a key the operator never typed.
+ */
+export function resolveMetadataFields(definitions: readonly WorkspaceMetadataFieldDefinition[]): {
+  fields: WorkspaceMetadataFieldDefinition[]
+  rejected: WorkspaceMetadataFieldDefinition[]
+} {
+  const fields: WorkspaceMetadataFieldDefinition[] = []
+  const rejected: WorkspaceMetadataFieldDefinition[] = []
+  const seen = new Set<string>()
+  for (const definition of definitions) {
+    if (!isValidMetadataKey(definition.key) || seen.has(definition.key)) {
+      rejected.push(definition)
+      continue
+    }
+    seen.add(definition.key)
+    fields.push(definition)
+  }
+  return {
+    fields: fields.sort((a, b) => (a.order ?? 0) - (b.order ?? 0)),
+    rejected,
+  }
+}
+
+/** The editor's starting draft: every declared field, empty when the workspace has no value. */
+export function metadataDraftFrom(
+  fields: readonly WorkspaceMetadataFieldDefinition[],
+  stored: WorkspaceMetadata,
+): Record<string, string> {
+  const draft: Record<string, string> = {}
+  for (const field of fields) draft[field.key] = metadataValue(stored, field.key) ?? ''
+  return draft
+}
+
+/**
+ * The bag to submit: the draft's non-empty values, PLUS every stored key the editor did not
+ * render.
+ *
+ * That second half is the whole rule. The update contract replaces the bag wholesale (so a
+ * cleared field can actually disappear), which means a save from an editor showing five fields
+ * would otherwise DELETE a value written under a field this build no longer declares — a
+ * deployment mid-rollout, a retired-but-still-read field, a value another version wrote. A
+ * REPLACE-style write must never silently drop state it doesn't render.
+ *
+ * Trimming and empty-dropping mirror the backend's normalisation, so the editor shows the same
+ * bag the server will store rather than one that changes shape on the round trip.
+ *
+ * The carried-over keys count against the contract's per-workspace entry cap like any other, so
+ * a bag already near it can refuse a save over fields the editor doesn't show. That is the right
+ * end of the trade: dropping what we don't render to stay under the cap would be exactly the
+ * silent deletion this function exists to prevent, and the cap is generous next to the number of
+ * fields a deployment declares.
+ *
+ * `draft` is typed `unknown`-valued and coerced rather than trusted as a string map: it is bound
+ * straight to the editor's inputs, and a `number` field's `v-model` hands back a NUMBER, on which
+ * `.trim()` throws. `BudgetSettings.vue` wraps the same control's value in `String(...)` for the
+ * same reason. The declared type would say otherwise, which is precisely why it must not.
+ */
+export function metadataPatchFrom(
+  fields: readonly WorkspaceMetadataFieldDefinition[],
+  draft: Readonly<Record<string, unknown>>,
+  stored: WorkspaceMetadata,
+): WorkspaceMetadata {
+  const rendered = new Set(fields.map((f) => f.key))
+  // Null-prototype for the same reason as `toMetadataBag`: this is a data bag being assembled
+  // from stored keys, and an assignment to an inherited slot is never what was meant.
+  const patch: WorkspaceMetadata = Object.create(null)
+  for (const [key, value] of Object.entries(stored)) {
+    if (!rendered.has(key)) patch[key] = value
+  }
+  for (const field of fields) {
+    const value = String(draft[field.key] ?? '').trim()
+    if (value) patch[field.key] = value
+  }
+  return patch
+}

package/app/pages/index.vue

@@ -73,6 +73,9 @@ const SlackPanel = defineAsyncComponent(() => import('~/components/slack/SlackPa
 const FragmentLibraryPanel = defineAsyncComponent(
   () => import('~/components/fragments/FragmentLibraryPanel.vue'),
 )
+const FoundationalServicePanel = defineAsyncComponent(
+  () => import('~/components/foundational/FoundationalServicePanel.vue'),
+)
 // Startup advisory for invalid / outdated pipelines — only mounted while open (auto-opened
 // at most once per session by the watcher below), so it stays out of the initial bundle.
 const PipelineHealthModal = defineAsyncComponent(
@@ -487,6 +490,7 @@ watch(
       <GitHubPanel v-if="ui.githubOpen" />
       <SlackPanel v-if="ui.slackOpen" />
       <FragmentLibraryPanel v-if="ui.fragmentLibraryOpen" />
+      <FoundationalServicePanel v-if="ui.foundationalServicesOpen" />
       <PipelineHealthModal v-if="ui.pipelineHealthOpen" />
       <RiskPolicyHealthModal v-if="ui.riskPolicyHealthOpen" />
       <ModelPresetHealthModal v-if="ui.modelPresetHealthOpen" />

package/app/stores/foundationalServices.spec.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useFoundationalServicesStore } from '~/stores/foundationalServices'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+// The two store rules that the surface's correctness rests on, and that neither the backend
+// tests nor a component test would catch:
+//
+//  - opening the catalog must transfer NO contract document. The whole two-table split exists so
+//    a catalog read costs identity + operation names, and a store that eagerly hydrated bodies
+//    would quietly undo it on the one surface a human uses to check what an agent sees.
+//  - a suppress/restore must refresh the OPT-OUT list as well as the catalog. The two are
+//    complements — an entry leaves one exactly as it enters the other — so refreshing only the
+//    catalog leaves the way BACK stale, which is the failure the pair exists to prevent.
+
+const SERVICE = {
+  id: 'file-storage',
+  ownerKind: 'account' as const,
+  name: 'File Storage',
+  summary: 'Stores uploads.',
+  description: '',
+  capabilities: [],
+  contracts: [
+    {
+      contractId: 'openapi',
+      format: 'openapi',
+      title: 'HTTP API',
+      size: 42,
+      path: null,
+      operations: ['GET /files'],
+      omittedOperations: 0,
+    },
+  ],
+  sourceId: null,
+  sourcePath: null,
+  pinnedCommit: null,
+  createdAt: 1,
+  updatedAt: 1,
+}
+
+function api(over: Record<string, unknown> = {}) {
+  return {
+    listFoundationalServices: vi.fn(() => Promise.resolve([])),
+    getResolvedFoundationalServices: vi.fn(() =>
+      Promise.resolve([{ ...SERVICE, tier: 'account' }]),
+    ),
+    listFoundationalServiceSuppressions: vi.fn(() => Promise.resolve([])),
+    listFoundationalSources: vi.fn(() => Promise.resolve([])),
+    getFoundationalServiceContracts: vi.fn(() =>
+      Promise.resolve([{ ...SERVICE.contracts[0], body: 'openapi: 3.0.3' }]),
+    ),
+    suppressFoundationalService: vi.fn(() => Promise.resolve(undefined)),
+    restoreFoundationalService: vi.fn(() => Promise.resolve(undefined)),
+    ...over,
+  }
+}
+
+describe('foundational-services store', () => {
+  beforeEach(() => {
+    useWorkspaceStore().workspaceId = 'ws1'
+  })
+
+  it('probes the catalog without fetching a single contract document', async () => {
+    const client = api()
+    vi.stubGlobal('useApi', () => client)
+    const store = useFoundationalServicesStore()
+    await store.probe()
+
+    expect(store.resolved).toHaveLength(1)
+    // The manifest rode the catalog read — the body did not.
+    expect(store.resolved[0]?.contracts[0]?.operations).toEqual(['GET /files'])
+    expect(client.getFoundationalServiceContracts).not.toHaveBeenCalled()
+    expect(store.contractBodies).toEqual({})
+  })
+
+  it('fetches a document only on demand, then serves it from the session cache', async () => {
+    const client = api()
+    vi.stubGlobal('useApi', () => client)
+    const store = useFoundationalServicesStore()
+    await store.probe()
+
+    await store.contractsFor('file-storage')
+    await store.contractsFor('file-storage')
+    expect(client.getFoundationalServiceContracts).toHaveBeenCalledTimes(1)
+    expect(store.contractBodies['file-storage']?.[0]?.body).toBe('openapi: 3.0.3')
+  })
+
+  it('resets the repo-source flag too when a re-probe finds the catalog gone', async () => {
+    // `sourcesAvailable` gates an affordance rather than content, so a probe that leaves it at a
+    // previous `true` would offer repo-source linking against an owner whose catalog is now
+    // unreachable. Every view the probe owns has to come back down together.
+    const client = api()
+    vi.stubGlobal('useApi', () => client)
+    const store = useFoundationalServicesStore()
+    await store.probe()
+    expect(store.sourcesAvailable).toBe(true)
+
+    client.listFoundationalServices.mockRejectedValueOnce(new Error('503'))
+    useWorkspaceStore().workspaceId = 'ws2'
+    await store.probe()
+
+    expect(store.available).toBe(false)
+    expect(store.sourcesAvailable).toBe(false)
+    expect(store.sources).toEqual([])
+  })
+
+  it('refreshes the opt-out list alongside the catalog on suppress and restore', async () => {
+    const client = api()
+    vi.stubGlobal('useApi', () => client)
+    const store = useFoundationalServicesStore()
+    await store.probe()
+    const afterProbe = client.listFoundationalServiceSuppressions.mock.calls.length
+
+    await store.suppress('file-storage')
+    await store.restore('file-storage')
+
+    // Once per write: a suppression that only refreshed the catalog would leave the restore
+    // control missing for the very service just hidden.
+    expect(client.listFoundationalServiceSuppressions.mock.calls.length).toBe(afterProbe + 2)
+    expect(client.getResolvedFoundationalServices.mock.calls.length).toBe(afterProbe + 2)
+  })
+})