@cat-factory/app 0.41.0 → 0.42.0

package/app/composables/usePipelineErrorToast.spec.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { usePipelineErrorToast, parseConflict } from '~/composables/usePipelineErrorToast'
+import { ApiError } from '~/composables/api/errors'
+import en from '../../i18n/locales/en.json'
+
+/**
+ * The i18n pilot: the pipeline-error toast resolves user-facing copy from
+ * `errors.conflict.*` message KEYS by the backend's machine-readable `reason`, and only
+ * ever shows raw backend prose as a last-resort description. These specs assert the KEYS
+ * and params a code path resolves (never the English text), so they stay locale-agnostic.
+ */
+
+/** Dot-path lookup into the real `en.json`, so `te` mirrors which keys actually ship. */
+function hasKey(path: string): boolean {
+  return (
+    path.split('.').reduce<unknown>((node, seg) => {
+      return node && typeof node === 'object' ? (node as Record<string, unknown>)[seg] : undefined
+    }, en) !== undefined
+  )
+}
+
+let add: ReturnType<typeof vi.fn>
+let t: ReturnType<typeof vi.fn>
+let openAiProviderSetup: ReturnType<typeof vi.fn>
+
+beforeEach(() => {
+  add = vi.fn()
+  // `t` echoes the key so the toast's title/description IS the resolved key — assert on it.
+  t = vi.fn((key: string) => key)
+  openAiProviderSetup = vi.fn()
+  vi.stubGlobal('useToast', () => ({ add }))
+  vi.stubGlobal('useUiStore', () => ({ openAiProviderSetup }))
+  vi.stubGlobal('useI18n', () => ({ t, te: (key: string) => hasKey(key) }))
+})
+
+function conflict(reason?: string, details: Record<string, unknown> = {}, message?: string) {
+  return new ApiError(409, {
+    error: { code: 'conflict', message, details: { reason, ...details } },
+  })
+}
+
+describe('parseConflict', () => {
+  it('extracts reason + raw message + details from a 409 conflict', () => {
+    const parsed = parseConflict(conflict('dependencies_unmet', { foo: 1 }, 'raw msg'))
+    expect(parsed).toEqual({
+      reason: 'dependencies_unmet',
+      message: 'raw msg',
+      details: { reason: 'dependencies_unmet', foo: 1 },
+    })
+  })
+
+  it('returns null for a non-conflict error', () => {
+    expect(parseConflict(new ApiError(500, { error: { code: 'internal' } }))).toBeNull()
+    expect(parseConflict(new Error('network'))).toBeNull()
+  })
+})
+
+describe('usePipelineErrorToast', () => {
+  it('titles a mapped conflict reason from its errors.conflict.title.<reason> key', () => {
+    usePipelineErrorToast().present(conflict('dependencies_unmet'))
+    expect(add).toHaveBeenCalledTimes(1)
+    expect(add.mock.calls[0]![0].title).toBe('errors.conflict.title.dependencies_unmet')
+    expect(t).toHaveBeenCalledWith('errors.conflict.title.dependencies_unmet')
+  })
+
+  it('falls back to the caller fallback key when the reason has no dedicated title', () => {
+    usePipelineErrorToast().present(conflict('totally_unknown_reason'), 'errors.action.retryFailed')
+    expect(add.mock.calls[0]![0].title).toBe('errors.action.retryFailed')
+  })
+
+  it('shows the raw backend message as the conflict description', () => {
+    usePipelineErrorToast().present(conflict('dependencies_unmet', {}, 'A depends on B'))
+    expect(add.mock.calls[0]![0].description).toBe('A depends on B')
+  })
+
+  it('falls back to a translated description when the backend sends no message', () => {
+    usePipelineErrorToast().present(conflict('dependencies_unmet'))
+    expect(add.mock.calls[0]![0].description).toBe('errors.conflict.fallbackMessage')
+  })
+
+  it('interpolates the model list for providers_unconfigured and offers the AI setup jump', () => {
+    usePipelineErrorToast().present(
+      conflict('providers_unconfigured', { models: ['gpt-x', 'claude-y'] }),
+    )
+    const arg = add.mock.calls[0]![0]
+    expect(arg.title).toBe('errors.conflict.providersUnconfigured.title')
+    expect(t).toHaveBeenCalledWith('errors.conflict.providersUnconfigured.body', {
+      models: 'gpt-x, claude-y',
+    })
+    arg.actions[0].onClick()
+    expect(openAiProviderSetup).toHaveBeenCalledOnce()
+  })
+
+  it('uses the fallback title key + raw message for a non-conflict error', () => {
+    usePipelineErrorToast().present(new Error('boom'), 'errors.action.startFailed')
+    const arg = add.mock.calls[0]![0]
+    expect(arg.title).toBe('errors.action.startFailed')
+    expect(arg.description).toBe('boom')
+  })
+})

package/app/composables/usePipelineErrorToast.ts

@@ -4,8 +4,15 @@
  * `error.details.reason` (kernel `ConflictReason`), so we can word each case precisely
  * instead of dumping the raw message — and, for `providers_unconfigured`, surface the
  * SAME guidance + "Configure AI" jump as the no-AI-provider startup banner.
+ *
+ * i18n boundary (see CLAUDE.md / the i18n plan): user-facing titles are resolved from
+ * `errors.conflict.*` message keys by the machine-readable `reason`. The raw backend
+ * `message` is shown only as the description fallback and stays untranslated — the
+ * contract is "if a server message must be localizable, the backend emits a code and the
+ * frontend maps it", not "translate arbitrary server prose on the client".
  */
 
+import type { ConflictReason } from '@cat-factory/contracts'
 import { apiErrorEnvelope } from './api/errors'
 
 /** The parsed shape of a backend conflict (`{ error: { code: 'conflict', details } }`). */
@@ -15,41 +22,55 @@ interface ConflictDetails {
   [key: string]: unknown
 }
 
-/** Pull a 409 conflict's `{ reason, message, details }` out of a thrown API error, else null. */
+/**
+ * Per-reason toast title KEYS, keyed off the kernel/contracts `ConflictReason`. Being an
+ * EXHAUSTIVE `Record` over the union is the real drift guard: a new backend conflict reason
+ * fails THIS typecheck until it is mapped here. (The typed-message-keys feature can't see the
+ * `t()` lookup because the key is resolved at runtime via this map, not written as a literal —
+ * so the exhaustiveness of the map, not `t()`, is what makes a missing reason a build error.)
+ * `providers_unconfigured` is excluded: it has bespoke handling + its own `providersUnconfigured.*`
+ * key namespace, so it never reaches the generic lookup below.
+ */
+const CONFLICT_TITLE_KEYS: Record<Exclude<ConflictReason, 'providers_unconfigured'>, string> = {
+  dependencies_unmet: 'errors.conflict.title.dependencies_unmet',
+  task_limit_reached: 'errors.conflict.title.task_limit_reached',
+  tester_infra_unsupported: 'errors.conflict.title.tester_infra_unsupported',
+  agent_backend_unconfigured: 'errors.conflict.title.agent_backend_unconfigured',
+  run_not_retryable: 'errors.conflict.title.run_not_retryable',
+  no_pr_to_merge: 'errors.conflict.title.no_pr_to_merge',
+  github_not_connected: 'errors.conflict.title.github_not_connected',
+  bootstrap_not_retryable: 'errors.conflict.title.bootstrap_not_retryable',
+  bootstrap_reference_missing: 'errors.conflict.title.bootstrap_reference_missing',
+}
+
+/**
+ * Pull a 409 conflict's `{ reason, message, details }` out of a thrown API error, else null.
+ * `message` is the raw backend prose (may be absent); the translated fallback is applied at
+ * the call site where the i18n `t` is available.
+ */
 export function parseConflict(
   error: unknown,
-): { reason?: string; message: string; details: ConflictDetails } | null {
+): { reason?: string; message?: string; details: ConflictDetails } | null {
   const body = apiErrorEnvelope(error)
   if (body?.code !== 'conflict') return null
   const details = (body.details as ConflictDetails | undefined) ?? {}
   return {
     reason: typeof details.reason === 'string' ? details.reason : undefined,
-    message: body.message ?? 'This action conflicts with the current state.',
+    message: typeof body.message === 'string' ? body.message : undefined,
     details,
   }
 }
 
-/** Per-reason toast titles for conflicts that don't get bespoke handling below. */
-const CONFLICT_TITLES: Record<string, string> = {
-  dependencies_unmet: 'Blocked by dependencies',
-  task_limit_reached: 'Concurrency limit reached',
-  tester_infra_unsupported: 'Test infrastructure not configured',
-  run_not_retryable: 'Run can’t be retried',
-  no_pr_to_merge: 'No PR to merge',
-  github_not_connected: 'GitHub not connected',
-  bootstrap_not_retryable: 'Bootstrap can’t be retried',
-  bootstrap_reference_missing: 'Reference architecture is gone',
-}
-
 export function usePipelineErrorToast() {
   const toast = useToast()
   const ui = useUiStore()
+  const { t, te } = useI18n()
 
   /**
-   * Present `error` as a toast. `fallbackTitle` is used for non-conflict failures and any
-   * conflict reason without a dedicated title.
+   * Present `error` as a toast. `fallbackTitleKey` is an i18n message key used for
+   * non-conflict failures and any conflict reason without a dedicated title.
    */
-  function present(error: unknown, fallbackTitle = 'Action failed'): void {
+  function present(error: unknown, fallbackTitleKey = 'common.actionFailed'): void {
     const conflict = parseConflict(error)
 
     // The headline case: a pipeline step's model has no usable provider. Name the
@@ -59,16 +80,15 @@ export function usePipelineErrorToast() {
       const models = Array.isArray(conflict.details.models) ? conflict.details.models : []
       const list = models.join(', ')
       toast.add({
-        title: 'No AI provider for this model',
+        title: t('errors.conflict.providersUnconfigured.title'),
         description: list
-          ? `No provider is configured for ${list}. Add a provider key, connect a subscription, ` +
-            'or enable Cloudflare AI to run it.'
-          : conflict.message,
+          ? t('errors.conflict.providersUnconfigured.body', { models: list })
+          : (conflict.message ?? t('errors.conflict.fallbackMessage')),
         color: 'error',
         icon: 'i-lucide-cpu',
         actions: [
           {
-            label: 'Configure AI',
+            label: t('errors.conflict.providersUnconfigured.action'),
             icon: 'i-lucide-settings',
             onClick: () => ui.openAiProviderSetup(),
           },
@@ -78,9 +98,14 @@ export function usePipelineErrorToast() {
     }
 
     if (conflict) {
+      // Per-reason title key from the exhaustive map; fall back to the caller's title key when
+      // this reason has no mapped/translated copy (`te` = translation-exists, so a key missing
+      // in the active locale never leaks as raw text). An unknown reason isn't in the map.
+      const reasonKey =
+        CONFLICT_TITLE_KEYS[conflict.reason as Exclude<ConflictReason, 'providers_unconfigured'>]
       toast.add({
-        title: CONFLICT_TITLES[conflict.reason ?? ''] ?? fallbackTitle,
-        description: conflict.message,
+        title: reasonKey && te(reasonKey) ? t(reasonKey) : t(fallbackTitleKey),
+        description: conflict.message ?? t('errors.conflict.fallbackMessage'),
         color: 'warning',
         icon: 'i-lucide-triangle-alert',
       })
@@ -89,7 +114,7 @@ export function usePipelineErrorToast() {
 
     // Not a conflict (a 4xx/5xx or a network fault) — surface its message plainly.
     toast.add({
-      title: fallbackTitle,
+      title: t(fallbackTitleKey),
       description: error instanceof Error ? error.message : String(error),
       color: 'error',
       icon: 'i-lucide-triangle-alert',

package/app/stores/agentRuns.ts

@@ -109,7 +109,7 @@ export const useAgentRunsStore = defineStore('agentRuns', () => {
         await ws.refresh()
       })
     } catch (e) {
-      runErrors.present(e, 'Retry failed')
+      runErrors.present(e, 'errors.action.retryFailed')
     }
   }
 

package/app/stores/execution.ts

@@ -141,7 +141,7 @@ export const useExecutionStore = defineStore('execution', () => {
         await ws.refresh()
       })
     } catch (e) {
-      runErrors.present(e, 'Failed to start')
+      runErrors.present(e, 'errors.action.startFailed')
       return false
     }
   }
@@ -240,7 +240,7 @@ export const useExecutionStore = defineStore('execution', () => {
       await api.mergeBlock(ws.requireId(), blockId)
       await ws.refresh()
     } catch (e) {
-      runErrors.present(e, 'Failed to merge')
+      runErrors.present(e, 'errors.action.mergeFailed')
     }
   }
 
@@ -261,7 +261,7 @@ export const useExecutionStore = defineStore('execution', () => {
         await ws.refresh()
       })
     } catch (e) {
-      runErrors.present(e, 'Failed to restart')
+      runErrors.present(e, 'errors.action.restartFailed')
       return false
     }
   }

package/i18n/i18n.config.ts

@@ -0,0 +1,29 @@
+// vue-i18n options for the @cat-factory/app layer. Referenced from `nuxt.config.ts`
+// as the bare filename `i18n.config.ts` so @nuxtjs/i18n resolves it per-layer (see the
+// `i18n` block there). `defineI18nConfig` is auto-imported by the module.
+//
+// Locale MESSAGES are NOT defined here — they live in `i18n/locales/*.json` so the
+// module can deep-merge them across the `extends` layer chain. This file carries only
+// the runtime vue-i18n behaviour (fallback, number/date formats) shared by every locale.
+export default defineI18nConfig(() => ({
+  legacy: false,
+  fallbackLocale: 'en',
+
+  // Locale-aware number/currency formatting. Use `$n(value, 'currency')` etc. at call
+  // sites instead of a raw `Intl.NumberFormat`; `$n`/`$d` are thin `Intl` wrappers so
+  // `en` behaviour is identical. `currency` style needs a `currency` override per call
+  // (`$n(n, 'currency', { currency: s.currency })`) — the backend supplies the code.
+  numberFormats: {
+    en: {
+      decimal: { style: 'decimal' },
+      currency: { style: 'currency', currency: 'USD', currencyDisplay: 'narrowSymbol' },
+      percent: { style: 'percent', maximumFractionDigits: 1 },
+    },
+  },
+  datetimeFormats: {
+    en: {
+      short: { dateStyle: 'medium' },
+      long: { dateStyle: 'long', timeStyle: 'short' },
+    },
+  },
+}))

package/i18n/locales/en.json

@@ -0,0 +1,35 @@
+{
+  "common": {
+    "save": "Save",
+    "cancel": "Cancel",
+    "retry": "Retry",
+    "actionFailed": "Action failed"
+  },
+  "errors": {
+    "action": {
+      "retryFailed": "Retry failed",
+      "startFailed": "Failed to start",
+      "mergeFailed": "Failed to merge",
+      "restartFailed": "Failed to restart"
+    },
+    "conflict": {
+      "title": {
+        "dependencies_unmet": "Blocked by dependencies",
+        "task_limit_reached": "Concurrency limit reached",
+        "tester_infra_unsupported": "Test infrastructure not configured",
+        "agent_backend_unconfigured": "Agent backend not configured",
+        "run_not_retryable": "Run can’t be retried",
+        "no_pr_to_merge": "No PR to merge",
+        "github_not_connected": "GitHub not connected",
+        "bootstrap_not_retryable": "Bootstrap can’t be retried",
+        "bootstrap_reference_missing": "Reference architecture is gone"
+      },
+      "fallbackMessage": "This action conflicts with the current state.",
+      "providersUnconfigured": {
+        "title": "No AI provider for this model",
+        "body": "No provider is configured for {models}. Add a provider key, connect a subscription, or enable Cloudflare AI to run it.",
+        "action": "Configure AI"
+      }
+    }
+  }
+}

package/nuxt.config.ts

@@ -32,7 +32,29 @@ export default defineNuxtConfig({
     },
   },
 
-  modules: ['@nuxt/ui', '@pinia/nuxt', 'pinia-plugin-persistedstate/nuxt'],
+  modules: ['@nuxt/ui', '@pinia/nuxt', 'pinia-plugin-persistedstate/nuxt', '@nuxtjs/i18n'],
+
+  // i18n lives in THIS layer's `i18n/` dir (the v9+ `restructureDir` convention).
+  // @nuxtjs/i18n is layer-aware: it scans `i18n/locales/` in every layer of the
+  // `extends` chain and DEEP-MERGES them (the consumer layer wins on key conflicts),
+  // so a downstream deployment can override/add a locale by dropping its own
+  // `i18n/locales/*.json` with no change here. Unlike the css block above, the paths
+  // here MUST be bare filenames (not `layerDir`-anchored absolutes): the module
+  // resolves `vueI18n`/`langDir` per-layer itself, and an absolute path would break
+  // that per-layer resolution.
+  i18n: {
+    // Pure SPA (`ssr: false`): a single in-app locale, no URL-prefix routing.
+    strategy: 'no_prefix',
+    defaultLocale: 'en',
+    locales: [{ code: 'en', language: 'en-US', file: 'en.json', name: 'English' }],
+    vueI18n: 'i18n.config.ts',
+    experimental: {
+      // Generate types from the `en` messages so an unknown `$t`/`t` key is a `nuxt
+      // typecheck` failure — the load-bearing maintainability guardrail given the repo
+      // lints with oxlint only (no `@intlify/eslint-plugin-vue-i18n` `no-raw-text`).
+      typedOptionsAndMessages: 'default',
+    },
+  },
 
   // This is a Nuxt *layer*. @pinia/nuxt's default `storesDirs` is an ABSOLUTE path
   // resolved against the CONSUMER's srcDir, so when this layer is `extends`ed it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "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",
@@ -9,6 +9,7 @@
   },
   "files": [
     "app",
+    "i18n",
     "nuxt.config.ts"
   ],
   "type": "module",
@@ -18,6 +19,7 @@
   },
   "dependencies": {
     "@nuxt/ui": "^4.9.0",
+    "@nuxtjs/i18n": "^10.4.0",
     "@pinia/nuxt": "^0.11.3",
     "@toad-contracts/core": "0.3.1",
     "@toad-contracts/frontend-http-client": "0.3.1",
@@ -32,7 +34,7 @@
     "pinia-plugin-persistedstate": "^4.7.1",
     "vue": "^3.5.38",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.40.0"
+    "@cat-factory/contracts": "0.40.1"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.1",