@cat-factory/app 0.189.0 → 0.190.1

package/README.md

@@ -54,6 +54,16 @@ over the WebSocket. How that sync works is written up in
 | `types/`          | TypeScript domain unions (`domain.ts`) and wire types mirroring the contracts.                                                                        |
 | `utils/`          | Small pure helpers.                                                                                                                                   |
 
+### Always import a layer component explicitly
+
+**Import a component under `components/` by path before using it in a template.** Do not lean on Nuxt's auto-registration. This layer sets no `components` config, so the default `pathPrefix: true` applies and a component is registered under its path-prefixed name: `components/panels/StepEffortReport.vue` becomes `PanelsStepEffortReport`, and a bare `<StepEffortReport>` matches nothing.
+
+Some bare tags do work, which is exactly what makes this worth writing down. Nuxt drops a directory segment the filename already repeats, so `pipeline/PipelinePicker.vue` registers as `PipelinePicker` and resolves bare, while `pipeline/AgentKindIcon.vue` in the same folder registers as `PipelineAgentKindIcon` and does not. Whether a tag resolves therefore depends on a coincidence between a folder name and a filename, and renaming either end breaks the tag with no error. An explicit import does not care.
+
+The failure is silent, which is why this is a rule rather than a preference. An unresolved tag warns in dev and then renders nothing, so a built SPA has a hole where the component should be. Nothing catches it: not typecheck, not the unit tests, not the e2e suite, and not the user, who reads it as a backend returning no data. Seven components had shipped this way.
+
+`scripts/check-component-imports.mjs` enforces it (CI's `repo-guards` job). If a panel section is missing and the data looks right, check the import first.
+
 ## Interface modes (basic / advanced)
 
 The SPA renders at one of two **interface tiers**. `basic` (the default) is the everyday

package/app/components/environments/EnvironmentSetupWizard.vue

@@ -17,6 +17,7 @@
 import { computed } from 'vue'
 import { JourneyHost, JourneyOutlet } from '@modular-vue/journeys'
 import { environmentSetupHandle } from '~/modular/journeys/environmentSetup'
+import EnvSetupStepper from '~/components/environments/EnvSetupStepper.vue'
 
 const ui = useUiStore()
 const { t } = useI18n()

package/app/components/panels/AgentStepDetail.vue

@@ -6,6 +6,8 @@ import { agentKindMeta } from '~/utils/catalog'
 import StepRestartControl from '~/components/panels/StepRestartControl.vue'
 import StepMetadataCard from '~/components/panels/StepMetadataCard.vue'
 import StepTestReport from '~/components/panels/StepTestReport.vue'
+import StepEffortReport from '~/components/panels/StepEffortReport.vue'
+import StepFragmentAdherence from '~/components/panels/StepFragmentAdherence.vue'
 import EnvironmentStatusPanel from '~/components/environments/EnvironmentStatusPanel.vue'
 import FrontendBindingsResolved from '~/components/panels/inspector/FrontendBindingsResolved.vue'
 import { UI_TESTER_AGENT_KIND } from '@cat-factory/contracts'

package/app/components/panels/ReportsPanel.vue

@@ -16,6 +16,7 @@ import {
   segmentPct,
   trendMagnitude,
 } from './ReportsPanel.logic'
+import ReportsSpendBreakdown from '~/components/panels/ReportsSpendBreakdown.vue'
 
 // Reports: cross-cutting usage analytics for the active account — where the spend and the
 // work actually go. Spend per model and agent kind, spend + run activity per workspace /

package/app/components/panels/inspector/TaskRunSettings.vue

@@ -8,6 +8,7 @@ import { showOverrideField } from '~/utils/uiMode'
 import InspectorSection from '~/components/panels/inspector/InspectorSection.vue'
 import RiskPolicyPicker from '~/components/riskPolicy/RiskPolicyPicker.vue'
 import TaskAprioriBranches from '~/components/panels/inspector/TaskAprioriBranches.vue'
+import DocReferenceRepos from '~/components/panels/inspector/DocReferenceRepos.vue'
 
 const props = defineProps<{ block: Block }>()
 

package/app/components/pipeline/PipelinePreview.vue

@@ -12,6 +12,7 @@ import { computed } from 'vue'
 import type { Pipeline } from '~/types/domain'
 import { agentKindMeta } from '~/utils/catalog'
 import { pipelineDisplaySteps, pipelineGateCount } from '~/utils/pipeline'
+import AgentKindIcon from '~/components/pipeline/AgentKindIcon.vue'
 
 const props = defineProps<{ pipeline: Pipeline }>()
 const { t } = useI18n()

package/app/components/prReview/PrReviewWindow.vue

@@ -24,6 +24,7 @@ import { subtaskIconClass } from '~/utils/pipelineRender'
 import { activeChunkLabels, chunkReviewPercent, hasNoSlicePlan } from '~/utils/prReviewProgress'
 import ResultWindowShell from '~/components/panels/ResultWindowShell.vue'
 import StepRunMeta from '~/components/panels/StepRunMeta.vue'
+import StepFragmentAdherence from '~/components/panels/StepFragmentAdherence.vue'
 
 const execution = useExecutionStore()
 const board = useBoardStore()

package/app/components/settings/RiskPolicyPanel.vue

@@ -12,6 +12,7 @@ import {
   RISK_POLICY_CEILING_FIELD,
   type RiskPolicyAxis,
 } from '~/utils/riskPolicy'
+import MergeClassRulesEditor from '~/components/settings/MergeClassRulesEditor.vue'
 
 const { t } = useI18n()
 

package/app/components/settings/SharedStacksPanel.vue

@@ -6,6 +6,7 @@
 // they succeed only on the local facade (elsewhere the backend returns a clear error surfaced as
 // a toast). Renders inline inside the Infrastructure window's "Shared stacks" tab.
 import { computed, reactive, ref } from 'vue'
+import { describeComposeSource, normalizeComposeFileRefs } from '@cat-factory/contracts'
 import type {
   SharedStack,
   SharedStackRecommendation,
@@ -76,8 +77,26 @@ function tokens(value: string): string[] {
     .filter(Boolean)
 }
 
+// A stack's compose layers may be bare in-repo paths (what this form authors and what the
+// autodetect scan returns) or explicit sources — an inline document, or a file in another repo —
+// which arrive through the API / a deployment's programmatic seeds. The form edits only the
+// former; a stack carrying any of the latter shows its layers read-only and its save omits
+// `composeFiles` entirely, so editing the name or the profiles can never silently flatten a
+// declaration this form has no editor for.
+const editingStack = computed(() => stacks.value.find((s) => s.id === editingId.value) ?? null)
+const advancedLayers = computed(() =>
+  (editingStack.value?.composeFiles ?? []).some((ref) => typeof ref !== 'string'),
+)
+const layerLabels = computed(() =>
+  normalizeComposeFileRefs(editingStack.value?.composeFiles ?? []).map(describeComposeSource),
+)
+
+// A repo-LESS stack (every layer inline / from another repo) needs no clone URL, so the form
+// requires one only while the layers it can author — in-repo paths — are what is being saved.
 const canSave = computed(
-  () => form.name.trim() && form.cloneUrl.trim() && tokens(form.composeFiles).length > 0,
+  () =>
+    form.name.trim() &&
+    (advancedLayers.value || (form.cloneUrl.trim() && tokens(form.composeFiles).length > 0)),
 )
 
 function resetForm() {
@@ -97,10 +116,12 @@ function resetForm() {
 function startEdit(stack: SharedStack) {
   editingId.value = stack.id
   form.name = stack.name
-  form.cloneUrl = stack.cloneUrl
+  form.cloneUrl = stack.cloneUrl ?? ''
   form.gitRef = stack.gitRef ?? ''
   form.directory = ''
-  form.composeFiles = stack.composeFiles.join(', ')
+  // Only bare in-repo paths are editable here; a stack with richer layers renders them read-only
+  // below and keeps them untouched through the save.
+  form.composeFiles = stack.composeFiles.filter((ref) => typeof ref === 'string').join(', ')
   form.composeProfiles = stack.composeProfiles.join(', ')
   form.managedNetworks = stack.managedNetworks.join(', ')
   form.allowHostCommands = stack.allowHostCommands
@@ -179,7 +200,17 @@ async function saveStack() {
   }
   try {
     if (editing) {
-      await store.update(editing, { ...payload, gitRef: form.gitRef.trim() || null })
+      // `composeFiles` is omitted when the stack carries layers this form can't author — the
+      // partial update preserves them, exactly as it already does for setup steps and the health
+      // gate. `cloneUrl` goes through as an explicit null when cleared, so a stack can be moved to
+      // the repo-less shape from here too.
+      const { composeFiles, ...rest } = payload
+      await store.update(editing, {
+        ...rest,
+        cloneUrl: form.cloneUrl.trim() || null,
+        gitRef: form.gitRef.trim() || null,
+        ...(advancedLayers.value ? {} : { composeFiles }),
+      })
     } else {
       await store.create(payload)
     }
@@ -402,6 +433,23 @@ async function remove(stack: SharedStack) {
       </p>
 
       <UFormField
+        v-if="advancedLayers"
+        :label="t('settings.sharedStacks.add.composeFiles')"
+        :help="t('settings.sharedStacks.add.composeLayersManagedHelp')"
+      >
+        <ul class="space-y-1" data-testid="shared-stack-compose-layers">
+          <li
+            v-for="(label, index) in layerLabels"
+            :key="index"
+            class="font-mono text-[11px] text-slate-500"
+          >
+            {{ label }}
+          </li>
+        </ul>
+      </UFormField>
+
+      <UFormField
+        v-else
         :label="t('settings.sharedStacks.add.composeFiles')"
         :help="t('settings.sharedStacks.add.composeFilesHelp')"
       >

package/app/composables/api/client.spec.ts

@@ -0,0 +1,50 @@
+import type { ApiContract } from '@toad-contracts/core'
+import { describe, expect, it } from 'vitest'
+import { type SendParams, withoutUndefinedQueryParams } from '~/composables/api/client'
+
+// An omitted optional query param used to reach the server as `key=`: the contract client
+// serialises with `fast-querystring`, whose `stringify({ blockId: undefined })` is `'blockId='`,
+// and request validation waves the key through because `v.optional(...)` accepts `undefined`. On
+// `listTasksContract`, whose `blockId` carries a `minLength(1)`, that made every unscoped
+// `listTasks()` a guaranteed 400. These lock the strip in.
+
+// The helper is contract-generic and only ever reads `queryParams`, so the cases below describe
+// request params structurally rather than picking a real contract per shape.
+type Params = Record<string, unknown>
+const strip = (params: Params): Params =>
+  withoutUndefinedQueryParams(params as SendParams<ApiContract>) as Params
+
+describe('withoutUndefinedQueryParams', () => {
+  it('drops undefined-valued query keys so they never reach the query string', () => {
+    const out = strip({ pathPrefix: '/workspaces/ws_1', queryParams: { blockId: undefined } })
+    expect(out.queryParams).toEqual({})
+  })
+
+  // The guard against "fix" it with a falsy check: 0, false and '' are all values a caller
+  // deliberately sent, and only `undefined` means absent.
+  it('keeps defined values, including falsy ones a caller meant to send', () => {
+    const out = strip({ queryParams: { blockId: 'blk_1', page: 0, all: false, q: '' } })
+    expect(out.queryParams).toEqual({ blockId: 'blk_1', page: 0, all: false, q: '' })
+  })
+
+  it('drops only the undefined keys from a mixed set', () => {
+    const out = strip({ queryParams: { window: '7d', workspaceId: undefined } })
+    expect(out.queryParams).toEqual({ window: '7d' })
+  })
+
+  it('leaves other request params untouched', () => {
+    const params = {
+      pathPrefix: '/workspaces/ws_1',
+      pathParams: { source: 'jira' },
+      body: { a: 1 },
+    }
+    expect(strip(params)).toEqual(params)
+  })
+
+  it('returns the same object when there is nothing to strip', () => {
+    const params = { queryParams: { blockId: 'blk_1' } }
+    expect(strip(params)).toBe(params)
+    const noQuery = { pathPrefix: '/workspaces/ws_1' }
+    expect(strip(noQuery)).toBe(noQuery)
+  })
+})

package/app/composables/api/client.ts

@@ -71,6 +71,31 @@ export function createApiClient(): WretchInstance {
   ])
 }
 
+/**
+ * Drop query keys whose value is `undefined`, so an omitted optional param is absent from the
+ * query string instead of present-but-empty.
+ *
+ * `sendByApiContract` serialises with `fast-querystring`, and `stringify({ blockId: undefined })`
+ * is `'blockId='`. Request validation does not catch it, because `v.optional(...)` accepts
+ * `undefined` and the key only becomes empty on the way out. The server then validates the parsed
+ * `''`, so any optional param carrying a `minLength(1)` rejects the whole request with a 400. That
+ * is what made an unscoped `listTasks()` uncallable. Params with no length check are luckier but
+ * still wrong: the handler reads `''` where it asked for absence.
+ *
+ * Stripping at this one chokepoint fixes every contract at once, which is the point. Writing
+ * `queryParams: { foo }` for an optional `foo` is the obvious thing to write and it should work,
+ * rather than each call site remembering to spread the key in conditionally.
+ */
+export function withoutUndefinedQueryParams<T extends ApiContract>(
+  params: SendParams<T>,
+): SendParams<T> {
+  const query = (params as { queryParams?: Record<string, unknown> }).queryParams
+  if (!query) return params
+  const present = Object.entries(query).filter(([, value]) => value !== undefined)
+  if (present.length === Object.keys(query).length) return params
+  return { ...params, queryParams: Object.fromEntries(present) }
+}
+
 /**
  * Send a contract request and unwrap to the success body (or throw the typed error).
  * The public signature preserves per-contract inference for callers; inside,
@@ -82,7 +107,7 @@ export async function sendContract<T extends ApiContract>(
   contract: T,
   params: SendParams<T>,
 ): Promise<SuccessBodyOf<T>> {
-  const outcome = await sendByApiContract(client, contract, params)
+  const outcome = await sendByApiContract(client, contract, withoutUndefinedQueryParams(params))
   if (outcome.error) {
     const error = outcome.error
     // A contract-declared non-2xx is reported as a plain `{ statusCode, headers, body }`

package/app/stores/environmentWizard/save.ts

@@ -95,7 +95,13 @@ export function createSaveActions(ctx: WizardContext) {
       await board.updateBlock(id, {
         provisioning: {
           type: 'docker-compose',
-          ...(pruned.composeFiles?.[0] ? { composePath: pruned.composeFiles[0] } : {}),
+          // `composePath` is the single-file fallback the provider uses when a recipe declares no
+          // layers, so only a bare in-repo path can fill it. The wizard's layers always are ones
+          // (they come from the deterministic detector); an `inline` / other-repo layer, which the
+          // API can supply, simply leaves it unset — the recipe below already carries the layer.
+          ...(typeof pruned.composeFiles?.[0] === 'string'
+            ? { composePath: pruned.composeFiles[0] }
+            : {}),
           ...(build ? { composeBuild: true } : {}),
           recipe: pruned,
         },

package/i18n/locales/de.json

@@ -630,6 +630,7 @@
         "directoryHelp": "Wird nur von der automatischen Erkennung verwendet: das Monorepo-Unterverzeichnis, in dem der Compose-Stack liegt.",
         "composeFiles": "Compose-Dateien",
         "composeFilesHelp": "Kommagetrennt, repo-relativ, in Override-Reihenfolge.",
+        "composeLayersManagedHelp": "Über die API verwaltet — dieser Stack hat Layer, die inline bereitgestellt oder aus einem anderen Repository gelesen werden; sie werden hier schreibgeschützt angezeigt und beim Speichern nicht verändert.",
         "composeProfiles": "Compose-Profile (optional)",
         "managedNetworks": "Verwaltete Netzwerke (optional)",
         "managedNetworksHelp": "Netzwerke, die dieser Stack für Konsumenten erstellt und besitzt, um sich damit zu verbinden.",

package/i18n/locales/en.json

@@ -2923,6 +2923,7 @@
         "directoryHelp": "Used only by Autodetect: the monorepo subdirectory the compose stack lives in.",
         "composeFiles": "Compose files",
         "composeFilesHelp": "Comma-separated, repo-relative, in override order.",
+        "composeLayersManagedHelp": "Managed through the API — this stack has layers supplied inline or read from another repo, so they are shown read-only here and left untouched when you save.",
         "composeProfiles": "Compose profiles (optional)",
         "managedNetworks": "Managed networks (optional)",
         "managedNetworksHelp": "Networks this stack creates and owns for consumers to attach to.",

package/i18n/locales/es.json

@@ -2703,6 +2703,7 @@
         "directoryHelp": "Solo lo usa la detección automática: el subdirectorio del monorepo donde se encuentra el stack de compose.",
         "composeFiles": "Archivos de Compose",
         "composeFilesHelp": "Separados por comas, relativos al repositorio, en orden de anulación.",
+        "composeLayersManagedHelp": "Gestionado mediante la API: esta pila tiene capas suministradas en línea o leídas desde otro repositorio, por lo que aquí se muestran como solo lectura y no se modifican al guardar.",
         "composeProfiles": "Perfiles de Compose (opcional)",
         "managedNetworks": "Redes gestionadas (opcional)",
         "managedNetworksHelp": "Redes que este stack crea y posee para que los consumidores se conecten.",

package/i18n/locales/fr.json

@@ -2703,6 +2703,7 @@
         "directoryHelp": "Utilisé uniquement par la détection automatique : le sous-répertoire du monorepo où se trouve le stack compose.",
         "composeFiles": "Fichiers Compose",
         "composeFilesHelp": "Séparés par des virgules, relatifs au dépôt, dans l'ordre de surcharge.",
+        "composeLayersManagedHelp": "Géré via l'API — cette pile comporte des couches fournies en ligne ou lues depuis un autre dépôt ; elles sont affichées en lecture seule ici et restent intactes à l'enregistrement.",
         "composeProfiles": "Profils Compose (facultatif)",
         "managedNetworks": "Réseaux gérés (facultatif)",
         "managedNetworksHelp": "Réseaux que ce stack crée et possède pour que les consommateurs s'y connectent.",

package/i18n/locales/he.json

@@ -2843,6 +2843,7 @@
         "directoryHelp": "בשימוש רק על ידי הזיהוי האוטומטי: תת-הספרייה במונורפו שבה נמצא מקבץ ה-compose.",
         "composeFiles": "קובצי Compose",
         "composeFilesHelp": "מופרדים בפסיקים, יחסית למאגר, לפי סדר הדריסה.",
+        "composeLayersManagedHelp": "מנוהל דרך ה-API — למחסנית הזו יש שכבות שסופקו בתוך ההגדרה או נקראות ממאגר אחר, ולכן הן מוצגות כאן לקריאה בלבד ונשארות ללא שינוי בשמירה.",
         "composeProfiles": "פרופילי Compose (אופציונלי)",
         "managedNetworks": "רשתות מנוהלות (אופציונלי)",
         "managedNetworksHelp": "רשתות שהמקבץ יוצר ומחזיק כדי שצרכנים יתחברו אליהן.",

package/i18n/locales/it.json

@@ -630,6 +630,7 @@
         "directoryHelp": "Usato solo dal rilevamento automatico: la sottodirectory del monorepo in cui si trova lo stack compose.",
         "composeFiles": "File compose",
         "composeFilesHelp": "Separati da virgola, relativi al repository, in ordine di override.",
+        "composeLayersManagedHelp": "Gestito tramite API: questo stack ha livelli forniti inline o letti da un altro repository, quindi qui sono mostrati in sola lettura e restano invariati al salvataggio.",
         "composeProfiles": "Profili compose (facoltativo)",
         "managedNetworks": "Reti gestite (facoltativo)",
         "managedNetworksHelp": "Reti che questo stack crea e possiede affinche i consumatori vi si colleghino.",

package/i18n/locales/ja.json

@@ -2844,6 +2844,7 @@
         "directoryHelp": "自動検出でのみ使用されます。compose スタックが存在するモノレポのサブディレクトリです。",
         "composeFiles": "Compose ファイル",
         "composeFilesHelp": "カンマ区切り、リポジトリ相対、オーバーライド順。",
+        "composeLayersManagedHelp": "API で管理されています。このスタックにはインラインで指定された層、または別のリポジトリから読み込まれる層があるため、ここでは読み取り専用で表示され、保存時にも変更されません。",
         "composeProfiles": "Compose プロファイル（任意）",
         "managedNetworks": "マネージドネットワーク（任意）",
         "managedNetworksHelp": "コンシューマーが接続するために、このスタックが作成・所有するネットワーク。",

package/i18n/locales/pl.json

@@ -2703,6 +2703,7 @@
         "directoryHelp": "Używane tylko przez automatyczne wykrywanie: podkatalog monorepo, w którym znajduje się stos compose.",
         "composeFiles": "Pliki Compose",
         "composeFilesHelp": "Rozdzielone przecinkami, względem repozytorium, w kolejności nadpisywania.",
+        "composeLayersManagedHelp": "Zarządzane przez API — ten stos ma warstwy podane bezpośrednio lub odczytywane z innego repozytorium, więc są tu tylko do odczytu i pozostają nietknięte przy zapisie.",
         "composeProfiles": "Profile Compose (opcjonalnie)",
         "managedNetworks": "Zarządzane sieci (opcjonalnie)",
         "managedNetworksHelp": "Sieci, które ten stos tworzy i posiada, aby konsumenci mogli się z nimi łączyć.",

package/i18n/locales/tr.json

@@ -2844,6 +2844,7 @@
         "directoryHelp": "Yalnızca otomatik algılama tarafından kullanılır: compose yığınının bulunduğu monorepo alt dizini.",
         "composeFiles": "Compose dosyaları",
         "composeFilesHelp": "Virgülle ayrılmış, depoya göreli, geçersiz kılma sırasında.",
+        "composeLayersManagedHelp": "API üzerinden yönetilir — bu yığında satır içi verilen veya başka bir depodan okunan katmanlar var; burada salt okunur gösterilir ve kaydettiğinizde değiştirilmez.",
         "composeProfiles": "Compose profilleri (isteğe bağlı)",
         "managedNetworks": "Yönetilen ağlar (isteğe bağlı)",
         "managedNetworksHelp": "Tüketicilerin bağlanması için bu yığının oluşturup sahip olduğu ağlar.",

package/i18n/locales/uk.json

@@ -2703,6 +2703,7 @@
         "directoryHelp": "Використовується лише автовизначенням: підкаталог монорепозиторію, де розташований стек compose.",
         "composeFiles": "Файли Compose",
         "composeFilesHelp": "Через кому, відносно репозиторію, у порядку перевизначення.",
+        "composeLayersManagedHelp": "Керується через API — цей стек має шари, задані безпосередньо або зчитані з іншого репозиторію, тож тут вони показані лише для читання й не змінюються під час збереження.",
         "composeProfiles": "Профілі Compose (необов'язково)",
         "managedNetworks": "Керовані мережі (необов'язково)",
         "managedNetworksHelp": "Мережі, які цей стек створює й якими володіє, щоб споживачі під'єднувалися до них.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.189.0",
+  "version": "0.190.1",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.40",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.196.0"
+    "@cat-factory/contracts": "0.197.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",