@cat-factory/app 0.198.1 → 0.200.0

package/README.md

@@ -267,7 +267,12 @@ by its `when(gates)` predicate (the same reactive gates service the nav uses, fi
 ## Extending the layer (consumer modules)
 
 A deployment can contribute its own components — result windows, nav entries, inspector
-panels, agent-kind palette data — **without forking**, through the auto-imported
+panels, agent-kind palette data — plus two DATA-only seams that need no components at all:
+its own applications in an **External tools** sidebar section (`externalTools`, each
+resolving its URL from the acting user / open workspace / this board's custom fields) and the
+**custom workspace metadata fields** those resolvers read (`workspaceMetadataFields`, edited
+on the Metadata tab of Workspace settings). All of it **without forking**, through the
+auto-imported
 `registerAppModule` seam (the frontend analogue of the backend's `registerAgentKind` /
 `registerGate` registries). The authoring walkthrough, the reusable shared building blocks
 (`ResultWindowShell`, the `StepRunMeta` run-metadata block, `useResultView`, …), and the

package/app/components/foundational/FoundationalContractSummary.vue

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+// One service's contract MANIFEST — id, format, size and the indexed operation names, never a
+// document body (backend/docs/adr/0031-foundational-services.md). This is exactly what an Architect's
+// catalog carries, so rendering the same fields here is what makes the surface answer "what will
+// the design actually see?".
+//
+// `omittedOperations` is rendered rather than dropped: the operation list is CAPPED, and a reader
+// who assumed it was complete would conclude the missing endpoints do not exist.
+import type { ApiContractFormat, ApiContractSummary } from '~/types/domain'
+
+defineProps<{
+  contracts: ApiContractSummary[]
+  /** Exhaustive format → translated label map, owned by the caller so the keys stay literal. */
+  formatLabel: Record<ApiContractFormat, string>
+}>()
+
+const { t, n } = useI18n()
+</script>
+
+<template>
+  <div v-if="contracts.length" class="mt-1 flex flex-col gap-1">
+    <div v-for="c in contracts" :key="c.contractId" class="text-[11px] text-slate-500">
+      <span class="text-slate-400">{{ c.title }}</span>
+      <span class="ms-1">({{ formatLabel[c.format] }}, {{ n(c.size) }})</span>
+      <span v-if="c.operations.length" class="ms-1 font-mono text-slate-500">
+        {{ c.operations.join(' · ') }}
+      </span>
+      <span v-if="c.omittedOperations > 0" class="ms-1 text-amber-500/80">
+        {{ t('foundational.contracts.omitted', { count: c.omittedOperations }) }}
+      </span>
+    </div>
+  </div>
+  <p v-else class="mt-1 text-[11px] text-amber-500/80">
+    {{ t('foundational.contracts.none') }}
+  </p>
+</template>

package/app/components/foundational/FoundationalServiceCatalogList.vue

@@ -0,0 +1,170 @@
+<script setup lang="ts">
+// The MERGED catalog an Architect is actually handed for this board — account ⊕ workspace, the
+// workspace winning by id (backend/docs/adr/0031-foundational-services.md). Workspace scope only: an
+// account has no tier above it to merge with.
+//
+// This view is where the two board-level decisions live, and they are deliberately different
+// actions rather than one "remove":
+//   - SUPPRESS an inherited account service — the board opts out, nothing is destroyed, and it is
+//     reversible with restore. The account keeps the service for every other board.
+//   - a service the board REGISTERED itself is edited or deleted in the other tab; suppressing it
+//     would be an obscure spelling of delete, and the backend refuses it as such.
+//
+// A contract body is fetched only when a human expands one, through the SAME lazy read a consumer
+// dispatch makes — so what is inspected here is what an agent would be given, and merely opening
+// the catalog transfers no documents.
+import { computed, reactive, ref } from 'vue'
+import type { ApiContractFormat, FoundationalServiceTier } from '~/types/domain'
+import { useFoundationalServicesStore } from '~/stores/foundationalServices'
+import FoundationalContractSummary from '~/components/foundational/FoundationalContractSummary.vue'
+
+const catalog = useFoundationalServicesStore()
+const toast = useToast()
+const { t } = useI18n()
+
+// Exhaustive maps of literal `t(...)` keys, so a new tier/format fails the typed-key guard.
+const tierLabel = computed<Record<FoundationalServiceTier, string>>(() => ({
+  account: t('foundational.tier.account'),
+  workspace: t('foundational.tier.workspace'),
+}))
+const formatLabel = computed<Record<ApiContractFormat, string>>(() => ({
+  openapi: t('foundational.format.openapi'),
+  'toad-contract': t('foundational.format.toadContract'),
+  'lokalise-api-contract': t('foundational.format.lokaliseApiContract'),
+}))
+// `as const` keeps the literal colour names assignable to UBadge's `color` union.
+const tierColor = {
+  account: 'info',
+  workspace: 'primary',
+} as const satisfies Record<FoundationalServiceTier, string>
+
+function notifyError(title: string, e: unknown) {
+  toast.add({
+    title,
+    description: e instanceof Error ? e.message : String(e),
+    icon: 'i-lucide-triangle-alert',
+    color: 'error',
+  })
+}
+
+const busyRows = reactive(new Set<string>())
+const rowBusy = (key: string) => busyRows.has(key)
+async function withRow(key: string, fn: () => Promise<void>) {
+  if (busyRows.has(key)) return
+  busyRows.add(key)
+  try {
+    await fn()
+  } finally {
+    busyRows.delete(key)
+  }
+}
+
+/** Service ids whose contract documents the user has expanded. */
+const expanded = ref<string[]>([])
+
+async function toggleContracts(serviceId: string) {
+  if (expanded.value.includes(serviceId)) {
+    expanded.value = expanded.value.filter((id) => id !== serviceId)
+    return
+  }
+  await withRow(`docs:${serviceId}`, async () => {
+    try {
+      await catalog.contractsFor(serviceId)
+      expanded.value = [...expanded.value, serviceId]
+    } catch (e) {
+      notifyError(t('foundational.toast.contractsFailed'), e)
+    }
+  })
+}
+
+async function suppress(serviceId: string) {
+  await withRow(`suppress:${serviceId}`, async () => {
+    try {
+      await catalog.suppress(serviceId)
+      toast.add({ title: t('foundational.toast.suppressed'), icon: 'i-lucide-eye-off' })
+    } catch (e) {
+      notifyError(t('foundational.toast.suppressFailed'), e)
+    }
+  })
+}
+</script>
+
+<template>
+  <div class="flex flex-col gap-3" data-testid="foundational-catalog">
+    <p class="text-xs text-slate-500">{{ t('foundational.catalog.intro') }}</p>
+
+    <div
+      v-for="s in catalog.resolved"
+      :key="s.id"
+      class="rounded-md border border-slate-800 bg-slate-900/60 p-3"
+    >
+      <div class="flex items-start gap-2">
+        <UIcon name="i-lucide-boxes" class="mt-0.5 h-4 w-4 shrink-0 text-sky-400" />
+        <div class="min-w-0 flex-1">
+          <p class="truncate text-sm font-medium text-slate-100">
+            {{ s.name }}
+            <code class="ms-1 text-[11px] text-slate-500">{{ s.id }}</code>
+          </p>
+          <p class="text-xs text-slate-400">{{ s.summary }}</p>
+          <div v-if="s.capabilities.length" class="mt-1 flex flex-wrap gap-1">
+            <UBadge v-for="c in s.capabilities" :key="c" size="xs" variant="subtle" color="neutral">
+              {{ c }}
+            </UBadge>
+          </div>
+          <FoundationalContractSummary :contracts="s.contracts" :format-label="formatLabel" />
+
+          <div class="mt-2 flex items-center gap-2">
+            <UButton
+              v-if="s.contracts.length"
+              size="xs"
+              variant="ghost"
+              :loading="rowBusy(`docs:${s.id}`)"
+              @click="toggleContracts(s.id)"
+            >
+              {{
+                expanded.includes(s.id)
+                  ? t('foundational.catalog.hideDocuments')
+                  : t('foundational.catalog.showDocuments')
+              }}
+            </UButton>
+          </div>
+          <!-- The lazy read, rendered verbatim: this is the text a consumer step receives. -->
+          <div v-if="expanded.includes(s.id)" class="mt-2 flex flex-col gap-2">
+            <div
+              v-for="doc in catalog.contractBodies[s.id] ?? []"
+              :key="doc.contractId"
+              class="rounded-md border border-slate-800 bg-slate-950/60 p-2"
+            >
+              <p class="mb-1 text-[11px] text-slate-400">
+                {{ doc.title }}
+                <span v-if="doc.path" class="ms-1 font-mono text-slate-600">{{ doc.path }}</span>
+              </p>
+              <pre class="max-h-64 overflow-auto text-[11px] text-slate-300">{{ doc.body }}</pre>
+            </div>
+          </div>
+        </div>
+        <div class="flex shrink-0 flex-col items-end gap-1">
+          <UBadge size="xs" :color="tierColor[s.tier]" variant="subtle">
+            {{ tierLabel[s.tier] }}
+          </UBadge>
+          <!-- Only an INHERITED entry can be suppressed; the board's own row is managed in the
+               registry tab, where deleting it is the honest action. -->
+          <UButton
+            v-if="s.tier === 'account'"
+            icon="i-lucide-eye-off"
+            size="xs"
+            variant="ghost"
+            :loading="rowBusy(`suppress:${s.id}`)"
+            :title="t('foundational.catalog.suppress')"
+            :data-testid="`foundational-suppress-${s.id}`"
+            @click="suppress(s.id)"
+          />
+        </div>
+      </div>
+    </div>
+
+    <p v-if="!catalog.resolved.length" class="text-sm text-slate-500">
+      {{ t('foundational.catalog.empty') }}
+    </p>
+  </div>
+</template>

package/app/components/foundational/FoundationalServiceManager.vue

@@ -0,0 +1,111 @@
+<script setup lang="ts">
+// Foundational-services manager (backend/docs/adr/0031-foundational-services.md), reused at two
+// scopes: a board (`workspace`) and an `account`. Register the shared capabilities the
+// organisation already runs, attach their API contracts (uploaded or synced from a repo), and —
+// at the workspace scope only — review the MERGED catalog an Architect is handed and opt the
+// board out of anything it should not design against.
+//
+// The tab split is the feature's own split, not a layout choice: "Catalog" is what an agent sees
+// (identity + operation names, never a document body), while "This tier" is what this owner
+// actually registers. An account has no tier above it, so it gets no catalog tab and no
+// suppression controls.
+import { computed, ref, watch } from 'vue'
+import type { FoundationalServiceOwnerKind } from '~/types/domain'
+import {
+  useFoundationalServices,
+  useFoundationalServicesStore,
+} from '~/stores/foundationalServices'
+import FoundationalServiceCatalogList from '~/components/foundational/FoundationalServiceCatalogList.vue'
+import FoundationalServiceRegistry from '~/components/foundational/FoundationalServiceRegistry.vue'
+import FoundationalServiceSources from '~/components/foundational/FoundationalServiceSources.vue'
+import FoundationalSuppressions from '~/components/foundational/FoundationalSuppressions.vue'
+
+const props = withDefaults(
+  defineProps<{
+    kind: FoundationalServiceOwnerKind
+    ownerId: string
+    /** Whether to show the merged-catalog tab (workspace scope only). */
+    showCatalog?: boolean
+  }>(),
+  { showCatalog: false },
+)
+
+// The workspace scope follows the active board (singleton, shared with the navbar); the account
+// scope uses an owner-keyed store so each account is isolated.
+const catalog =
+  props.kind === 'workspace'
+    ? useFoundationalServicesStore()
+    : useFoundationalServices(props.kind, props.ownerId)
+const github = useGitHubStore()
+const { t } = useI18n()
+
+watch(
+  () => props.ownerId,
+  () => {
+    void catalog.probe()
+    // The repo pickers need the active board's installation state; probe once so they light up.
+    void github.probe()
+  },
+  { immediate: true },
+)
+
+type Tab = 'catalog' | 'registry' | 'sources'
+const tab = ref<Tab>(props.showCatalog ? 'catalog' : 'registry')
+
+const ownerLabel = computed(() =>
+  props.kind === 'workspace' ? t('foundational.owner.workspace') : t('foundational.owner.account'),
+)
+
+const tabs = computed(() => {
+  const items = [
+    { value: 'registry' as const, label: ownerLabel.value, slot: 'registry' },
+    { value: 'sources' as const, label: t('foundational.tab.sources'), slot: 'sources' },
+  ]
+  if (!props.showCatalog) return items
+  return [
+    { value: 'catalog' as const, label: t('foundational.tab.catalog'), slot: 'catalog' },
+    ...items,
+  ]
+})
+
+const activeTab = computed({
+  get: () => tab.value,
+  set: (v: string) => {
+    tab.value = v as Tab
+  },
+})
+</script>
+
+<template>
+  <div class="flex flex-col gap-4" data-testid="foundational-manager">
+    <!-- The catalog is opt-in; if a deployment has not wired it, say so rather than offering
+         forms that would fail with a raw 503. -->
+    <div
+      v-if="catalog.available === false"
+      class="rounded-md border border-slate-800 bg-slate-900/40 p-3 text-sm text-slate-400"
+    >
+      {{ t('foundational.unavailable') }}
+    </div>
+
+    <UTabs
+      v-else
+      v-model="activeTab"
+      :items="tabs"
+      variant="link"
+      :ui="{ root: 'gap-4', list: 'overflow-x-auto' }"
+    >
+      <template #catalog>
+        <div class="flex flex-col gap-4">
+          <FoundationalServiceCatalogList />
+          <FoundationalSuppressions />
+        </div>
+      </template>
+      <template #registry>
+        <FoundationalServiceRegistry :kind="props.kind" :owner-id="props.ownerId" />
+      </template>
+      <template #sources>
+        <FoundationalServiceSources :kind="props.kind" :owner-id="props.ownerId" />
+      </template>
+    </UTabs>
+  </div>
+</template>

package/app/components/foundational/FoundationalServicePanel.vue

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+// The board (workspace-tier) foundational-services modal
+// (backend/docs/adr/0031-foundational-services.md). A thin shell around the shared manager at the
+// active board's scope — including the merged catalog, so the account ⊕ workspace inheritance an
+// Architect designs against is visible and the board can opt out of an inherited service.
+// Opened from the navbar / command bar via the ui store.
+import FoundationalServiceManager from '~/components/foundational/FoundationalServiceManager.vue'
+
+const ui = useUiStore()
+const workspace = useWorkspaceStore()
+const { t } = useI18n()
+
+const open = computed({
+  get: () => ui.foundationalServicesOpen,
+  set: (v: boolean) => {
+    if (!v) ui.closeFoundationalServices()
+  },
+})
+</script>
+
+<template>
+  <UModal
+    v-model:open="open"
+    :title="t('foundational.panel.title')"
+    :description="t('foundational.panel.subtitle')"
+    :ui="{ content: 'max-w-3xl' }"
+  >
+    <template #body>
+      <FoundationalServiceManager
+        v-if="workspace.workspaceId"
+        kind="workspace"
+        :owner-id="workspace.workspaceId"
+        show-catalog
+      />
+    </template>
+  </UModal>
+</template>