@cat-factory/app 0.199.0 → 0.200.0

package/app/composables/useNavContributions.ts

@@ -49,6 +49,7 @@ export function useNavContributions() {
     kaizen: () => ui.openKaizen(),
     infrastructure: () => ui.openInfrastructure(),
     fragmentLibrary: () => ui.openFragmentLibrary(),
+    foundationalServices: () => ui.openFoundationalServices(),
     mergeThresholds: () => ui.openWorkspaceSettings('merge'),
     workspaceSettings: () => ui.openWorkspaceSettings(),
     modelConfiguration: () => ui.openModelConfig(),

package/app/composables/usePipelineErrorToast.ts

@@ -224,6 +224,10 @@ const CONFLICT_INFO: Record<Exclude<ConflictReason, BespokeConflictReason>, Conf
     titleKey: 'errors.conflict.title.foundational_service_exists',
     descriptionKey: 'errors.conflict.description.foundational_service_exists',
   },
+  foundational_service_not_inherited: {
+    titleKey: 'errors.conflict.title.foundational_service_not_inherited',
+    descriptionKey: 'errors.conflict.description.foundational_service_not_inherited',
+  },
   pipeline_schedule_intake_unconfigured: {
     titleKey: 'errors.conflict.title.pipeline_schedule_intake_unconfigured',
     descriptionKey: 'errors.conflict.description.pipeline_schedule_intake_unconfigured',

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

@@ -124,6 +124,7 @@ describe('navSlotFilter', () => {
     expect(kept).not.toContain('bootstrap-repo')
     expect(kept).not.toContain('operator-dashboard')
     expect(kept).not.toContain('reports')
+    expect(kept).not.toContain('foundational-services')
   })
 
   it('states, per advanced item, whether basic mode still reaches its capability', () => {
@@ -166,6 +167,10 @@ describe('navSlotFilter', () => {
         kind: 'out-of-tier',
         why: 'deployment-wide spend/activity rollup - an operator job, not a delivery one',
       },
+      'foundational-services': {
+        kind: 'out-of-tier',
+        why: 'org-wide platform inventory, set up once - a board delivers fine with none',
+      },
     }
     const advanced = NAV_CONTRIBUTIONS.filter((i) => i.advanced).map((i) => i.id)
     expect(advanced.sort()).toEqual(Object.keys(REASON).sort())
@@ -344,6 +349,7 @@ describe('nav grouping helpers', () => {
       'keyboard-shortcuts',
       'ui-mode',
       'tutorial',
+      'foundational-services',
     ])
   })
 

package/app/modular/nav-contributions.ts

@@ -168,6 +168,7 @@ export const NAV_ACTIONS = [
   'kaizen',
   'infrastructure',
   'fragmentLibrary',
+  'foundationalServices',
   'mergeThresholds',
   'workspaceSettings',
   'modelConfiguration',
@@ -365,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',

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)
+  })
+})

package/app/stores/foundationalServices.ts

@@ -0,0 +1,276 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import type {
+  ApiContractDocument,
+  CreateFoundationalServiceInput,
+  FoundationalService,
+  FoundationalServiceOwnerKind,
+  FoundationalServiceSource,
+  FoundationalServiceSuppression,
+  FoundationalServiceSyncResult,
+  LinkFoundationalServiceSourceInput,
+  ResolvedFoundationalService,
+  UpdateFoundationalServiceInput,
+} from '~/types/domain'
+import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * The foundational-services catalog for one owner — a board (`workspace`) or an `account`
+ * (backend/docs/adr/0031-foundational-services.md). Holds that owner's own (raw) tier of registered
+ * services, its linked repo sources, and — at the **workspace** tier only — the merged catalog an
+ * Architect actually sees (account ⊕ workspace, workspace winning).
+ *
+ * Three things about this store follow the feature's design rather than the fragment library's:
+ *
+ * - **Contract documents are never held here.** The catalog reads carry a contract MANIFEST
+ *   (id, format, size, operation names) and no bodies, because that is the whole reason a design
+ *   prompt scales with the number of an org's services rather than the size of its specs. A body
+ *   is fetched on demand, per service, by {@link contractsFor}, and cached only for the session.
+ * - **`suppress` / `restore` are workspace-only**, and they are not "delete". Suppression opts a
+ *   board out of an INHERITED account service and destroys nothing; deleting removes the board's
+ *   own registration and its uploaded documents.
+ * - **`sourcesAvailable` is the finer gate**, exactly as in the skill library: the catalog works
+ *   without the GitHub integration (contracts can be uploaded directly), while the repo-source
+ *   routes 503 without it.
+ */
+function foundationalServicesSetup(
+  kind: FoundationalServiceOwnerKind,
+  resolveOwnerId: () => string | null,
+) {
+  const api = useApi()
+
+  /** The merged/resolved catalog only exists at the workspace tier. */
+  const hasResolved = kind === 'workspace'
+
+  /** null = not probed yet; true/false = the catalog is on/off for this deployment. */
+  const available = ref<boolean | null>(null)
+  /** false when the GitHub integration is off: the catalog works, repo sources do not. */
+  const sourcesAvailable = ref(true)
+  /** This owner's own registered services (its tier, raw). */
+  const services = ref<FoundationalService[]>([])
+  /** The merged catalog an Architect sees (workspace tier only; empty otherwise). */
+  const resolved = ref<ResolvedFoundationalService[]>([])
+  /**
+   * What this board is opted OUT of (workspace tier only; empty otherwise). Its own read because
+   * a suppressed id is by construction absent from {@link resolved} — without it, suppression
+   * would be a one-way door.
+   */
+  const suppressions = ref<FoundationalServiceSuppression[]>([])
+  /** Linked repo sources for this owner. */
+  const sources = ref<FoundationalServiceSource[]>([])
+  /** Per-source "changes available" flag from the last status check. */
+  const sourceChanges = ref<Record<string, boolean>>({})
+  /**
+   * Session cache of fetched contract DOCUMENTS, keyed by service id. Populated only by an
+   * explicit {@link contractsFor}, so opening the surface never transfers a document body — the
+   * property the whole two-table split exists to guarantee.
+   */
+  const contractBodies = ref<Record<string, ApiContractDocument[]>>({})
+
+  /** How many entries of the merged catalog this board inherits rather than owns. */
+  const inheritedCount = computed(
+    () => resolved.value.filter((entry) => entry.tier === 'account').length,
+  )
+
+  function requireOwnerId(): string {
+    const id = resolveOwnerId()
+    if (!id) throw new Error('No foundational-services owner')
+    return id
+  }
+
+  function requireWorkspaceId(): string {
+    if (!hasResolved) throw new Error('Foundational-service inheritance is workspace-scoped')
+    return requireOwnerId()
+  }
+
+  /** Probe the feature + load this owner's tier, sources and (ws) the merged catalog. */
+  async function runProbe() {
+    const id = resolveOwnerId()
+    if (!id) return
+    try {
+      const [tier, merged, opted] = await Promise.all([
+        api.listFoundationalServices(kind, id),
+        hasResolved
+          ? api.getResolvedFoundationalServices(id)
+          : Promise.resolve([] as ResolvedFoundationalService[]),
+        hasResolved
+          ? api.listFoundationalServiceSuppressions(id)
+          : Promise.resolve([] as FoundationalServiceSuppression[]),
+      ])
+      services.value = tier
+      resolved.value = merged
+      suppressions.value = opted
+      available.value = true
+    } catch {
+      // Reset EVERY view, `sourcesAvailable` included. Leaving it at its previous value would
+      // let a re-probe of an owner whose catalog is now unreachable keep claiming the repo-source
+      // half is wired, which is the one flag here that gates an affordance rather than content.
+      available.value = false
+      services.value = []
+      resolved.value = []
+      suppressions.value = []
+      sources.value = []
+      sourceChanges.value = {}
+      sourcesAvailable.value = false
+      return
+    }
+    // Repo sources need the GitHub integration; a 503 here hides only the linking UI — the
+    // catalog read above already succeeded, so the feature itself is on.
+    try {
+      sources.value = await api.listFoundationalSources(kind, id)
+      sourcesAvailable.value = true
+    } catch {
+      sources.value = []
+      sourcesAvailable.value = false
+    }
+  }
+  // Single-flight the probe keyed on the owner id, so a panel-open fan-out loads once per owner.
+  const { probe, ensureProbed } = useSingleFlightProbe(runProbe, () => resolveOwnerId())
+
+  async function reloadTier() {
+    services.value = await api.listFoundationalServices(kind, requireOwnerId())
+  }
+
+  async function refreshResolved() {
+    if (!hasResolved) return
+    const id = requireOwnerId()
+    // Both in one pass: a write that changes the merge routinely changes the opt-out list too
+    // (suppressing removes an entry from one and adds it to the other), and refreshing only the
+    // catalog would leave the way BACK stale — the exact state the pair exists to avoid.
+    const [merged, opted] = await Promise.all([
+      api.getResolvedFoundationalServices(id),
+      api.listFoundationalServiceSuppressions(id),
+    ])
+    resolved.value = merged
+    suppressions.value = opted
+  }
+
+  /** Every write invalidates both views: a tier edit changes what the merge resolves to. */
+  async function reload() {
+    await Promise.all([reloadTier(), refreshResolved()])
+  }
+
+  async function create(input: CreateFoundationalServiceInput) {
+    await api.createFoundationalService(kind, requireOwnerId(), input)
+    await reload()
+  }
+
+  async function update(serviceId: string, patch: UpdateFoundationalServiceInput) {
+    await api.updateFoundationalService(kind, requireOwnerId(), serviceId, patch)
+    // A contract replacement changes the stored bodies, so drop the cached copy rather than
+    // letting a stale document be shown as what a consumer would receive.
+    delete contractBodies.value[serviceId]
+    await reload()
+  }
+
+  /** Remove this tier's OWN registration (and its uploaded documents). */
+  async function remove(serviceId: string) {
+    await api.deleteFoundationalService(kind, requireOwnerId(), serviceId)
+    delete contractBodies.value[serviceId]
+    await reload()
+  }
+
+  /** Opt this board out of an inherited ACCOUNT service. Destroys nothing; reversible. */
+  async function suppress(serviceId: string) {
+    await api.suppressFoundationalService(requireWorkspaceId(), serviceId)
+    await reload()
+  }
+
+  /** Lift a suppression, so the board inherits the account service again. */
+  async function restore(serviceId: string) {
+    await api.restoreFoundationalService(requireWorkspaceId(), serviceId)
+    await reload()
+  }
+
+  /**
+   * Fetch (and cache for the session) one service's full contract documents — the same lazy read
+   * a consumer dispatch makes, so what a human inspects here is what an agent would be handed.
+   */
+  async function contractsFor(serviceId: string): Promise<ApiContractDocument[]> {
+    const cached = contractBodies.value[serviceId]
+    if (cached) return cached
+    const documents = await api.getFoundationalServiceContracts(requireWorkspaceId(), serviceId)
+    contractBodies.value = { ...contractBodies.value, [serviceId]: documents }
+    return documents
+  }
+
+  async function reloadSources() {
+    sources.value = await api.listFoundationalSources(kind, requireOwnerId())
+  }
+
+  async function linkSource(input: LinkFoundationalServiceSourceInput) {
+    const source = await api.linkFoundationalSource(kind, requireOwnerId(), input)
+    sources.value = [source, ...sources.value]
+    // Sync immediately so the linked repo's services land in the catalog rather than waiting for
+    // the autorefresh sweep — a freshly linked source that shows nothing reads as a broken link.
+    await syncSource(source.id)
+    return source
+  }
+
+  async function unlinkSource(sourceId: string) {
+    await api.unlinkFoundationalSource(kind, requireOwnerId(), sourceId)
+    sources.value = sources.value.filter((s) => s.id !== sourceId)
+    delete sourceChanges.value[sourceId]
+    await reload()
+  }
+
+  /** Resync a source's definitions into the catalog, then refresh both views. */
+  async function syncSource(sourceId: string): Promise<FoundationalServiceSyncResult> {
+    const result = await api.syncFoundationalSource(kind, requireOwnerId(), sourceId)
+    delete sourceChanges.value[sourceId]
+    await Promise.all([reloadSources(), reload()])
+    return result
+  }
+
+  /** The cheap commit-version "check for changes" for a source; caches the flag. */
+  async function checkSource(sourceId: string) {
+    const status = await api.foundationalSourceStatus(kind, requireOwnerId(), sourceId)
+    sourceChanges.value = { ...sourceChanges.value, [sourceId]: status.changed }
+    return status
+  }
+
+  return {
+    kind,
+    hasResolved,
+    available,
+    sourcesAvailable,
+    services,
+    resolved,
+    suppressions,
+    sources,
+    sourceChanges,
+    contractBodies,
+    inheritedCount,
+    probe,
+    ensureProbed,
+    create,
+    update,
+    remove,
+    suppress,
+    restore,
+    contractsFor,
+    linkSource,
+    unlinkSource,
+    syncSource,
+    checkSource,
+  }
+}
+
+/**
+ * The workspace-tier catalog for the **active** board — a singleton that resolves the owner
+ * lazily, so it follows board switches and is shared by the navbar and the board modal.
+ */
+export const useFoundationalServicesStore = defineStore('foundationalServices', () =>
+  foundationalServicesSetup('workspace', () => useWorkspaceStore().workspaceId),
+)
+
+/**
+ * An owner-keyed catalog store, used for the **account** tier (and reusable for any explicit
+ * owner). Keyed by `(kind, ownerId)` so each account gets isolated state.
+ */
+export function useFoundationalServices(kind: FoundationalServiceOwnerKind, ownerId: string) {
+  return defineStore(`foundationalServices:${kind}:${ownerId}`, () =>
+    foundationalServicesSetup(kind, () => ownerId),
+  )()
+}

package/app/stores/ui/modals.ts

@@ -344,6 +344,9 @@ function createOverlayModals() {
   // Prompt-fragment library panel (manage the board's best-practice catalog +
   // linked guideline repos; ADR 0006).
   const fragmentLibraryOpen = ref(false)
+  // Foundational-services panel (register the shared capabilities the org already runs, and see
+  // the merged catalog an Architect designs against; backend/docs/adr/0031-foundational-services.md).
+  const foundationalServicesOpen = ref(false)
   // Command bar (⌘K) — searchable launcher for every navbar action.
   const commandBarOpen = ref(false)
   // Keyboard-shortcuts cheatsheet (?) — a modal listing every global shortcut.
@@ -373,6 +376,12 @@ function createOverlayModals() {
   function closeFragmentLibrary() {
     fragmentLibraryOpen.value = false
   }
+  function openFoundationalServices() {
+    foundationalServicesOpen.value = true
+  }
+  function closeFoundationalServices() {
+    foundationalServicesOpen.value = false
+  }
   function openCommandBar() {
     commandBarOpen.value = true
   }
@@ -411,6 +420,7 @@ function createOverlayModals() {
     bootstrapOpen,
     addServiceOpen,
     fragmentLibraryOpen,
+    foundationalServicesOpen,
     commandBarOpen,
     shortcutsHelpOpen,
     mobileNavOpen,
@@ -421,6 +431,8 @@ function createOverlayModals() {
     closeAddService,
     openFragmentLibrary,
     closeFragmentLibrary,
+    openFoundationalServices,
+    closeFoundationalServices,
     openCommandBar,
     closeCommandBar,
     toggleCommandBar,

package/app/types/domain.ts

@@ -177,6 +177,7 @@ export type * from './execution'
 export type * from './models'
 export type * from './fragments'
 export type * from './skills'
+export type * from './foundationalServices'
 export type * from './documents'
 export type * from './tasks'
 export type * from './bugHunt'

package/app/types/foundationalServices.ts

@@ -0,0 +1,32 @@
+// ---------------------------------------------------------------------------
+// Foundational services (backend/docs/adr/0031-foundational-services.md). Mirrors the
+// `@cat-factory/contracts` schemas: the tiered catalog of shared capabilities an
+// organisation already runs (file storage, notifications, audit …), each with its
+// API contracts, plus the repo sources that feed it.
+//
+// Note `ApiContractSummary` (no body) and `ApiContractDocument` (with body) are two
+// separate types on purpose — the catalog read never carries a document, and the
+// management surface reads one only when a human opens it.
+// ---------------------------------------------------------------------------
+//
+// All wire shapes are sourced from @cat-factory/contracts (single source of truth).
+
+export type {
+  ApiContractDocument,
+  ApiContractFormat,
+  ApiContractSummary,
+  CreateFoundationalServiceInput,
+  FoundationalService,
+  FoundationalServiceOwnerKind,
+  FoundationalServiceSelection,
+  FoundationalServiceSource,
+  FoundationalServiceSourceMode,
+  FoundationalServiceSourceStatus,
+  FoundationalServiceSuppression,
+  FoundationalServiceSyncResult,
+  FoundationalServiceTier,
+  LinkFoundationalServiceSourceInput,
+  ResolvedFoundationalService,
+  UpdateFoundationalServiceInput,
+  UploadApiContract,
+} from '@cat-factory/contracts'