@cat-factory/app 0.311.2 → 0.311.3

package/app/composables/toastTitleKeys.spec.ts

@@ -0,0 +1,143 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { hasI18nKey } from '../../test/i18nKeys'
+
+// The two toast funnels take a title KEY, resolved inside the composable. Typed message keys and
+// `vue-i18n-extract` only see a key written literally inside a `t()` call, so a key handed to a funnel is
+// invisible to both: a typo renders its own key path in the toast, and deleting a live key reads
+// as a clean removal (`i18n:check` even lists these keys as unused). This spec closes that gap by
+// reading every literal key passed to a funnel and resolving it against the base catalog.
+
+const appRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+function* sources(dir: string): Generator<string> {
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry)
+    if (statSync(abs).isDirectory()) yield* sources(abs)
+    else if (/\.(vue|ts)$/.test(entry) && !entry.endsWith('.spec.ts')) yield abs
+  }
+}
+
+// The call heads whose FIRST argument is the title key, and those whose SECOND argument is: the
+// error funnel's two (after the error or the reported detail) and `useInterviewDrafts`' `flushThen`,
+// which forwards its key to `present`.
+const FIRST = /actionToast\.(?:success|info|warning|error)\(\s*/g
+const SECOND = /\b(?:present|presentReported|flushThen)\(/g
+// Options that carry a key to a funnel through a helper. Only a LITERAL value is read: the same
+// names also appear in type declarations and in the helpers that forward them.
+const OPTION = /\b(?:titleKey|failureTitleKeys)\s*:\s*/g
+// A dotted key literal. A conditional argument (`ok ? 'a.b' : 'a.c'`) yields both.
+const KEY = /'([a-zA-Z][\w-]*(?:\.[\w-]+)+)'/g
+// A tone passed around instead of called (`const show = ok ? actionToast.success : …`): every key
+// then reaches the toast through the alias, where no call head above can read it.
+const ALIAS = /actionToast\.(?:success|info|warning|error)\b(?!\s*\()/g
+
+// Files whose funnel call takes its key from somewhere other than a literal argument. A prefix
+// means the file spells its keys out in a table or in calls to a local helper, and every literal
+// under that prefix in the file is resolved instead. `null` means the file only forwards a key
+// its callers name, and those callers are read through `SECOND` and `OPTION`. A new indirect call
+// fails until it is either made literal or listed here.
+const INDIRECT: Record<string, string | null> = {
+  'composables/useConfirmAction.ts': 'common.toast.',
+  'components/github/GitHubPanel.vue': 'vcs.panel.pulls.',
+  'components/pipeline/PipelineHealthModal.vue': 'pipeline.health.toast.',
+  'components/settings/RiskPolicyPanel.vue': 'settings.riskPolicy.toast.',
+  'composables/useInterviewDrafts.ts': null,
+  'composables/useContextLinking.ts': null,
+}
+
+// The funnels themselves: they DEFINE the calls above (a signature reads like a call head), so
+// they hold no key to check.
+const FUNNELS =
+  /^composables\/(?:useActionToast|usePipelineErrorToast)\.ts$|^composables\/pipelineErrorToast\//
+
+/** The argument starting at `from`: up to the first top-level `,` or the closing `)`. */
+function argumentAt(text: string, from: number): string {
+  let depth = 0
+  for (let i = from; i < text.length; i++) {
+    const char = text[i]
+    if (char === '(' || char === '[' || char === '{') depth++
+    else if (char === ')' || char === ']' || char === '}') {
+      if (depth === 0) return text.slice(from, i)
+      depth--
+    } else if (char === ',' && depth === 0) return text.slice(from, i)
+  }
+  return text.slice(from)
+}
+
+/** Every key argument in `text`, each with the literal keys it contains (none for an indirect one). */
+function keyArguments(text: string): { arg: string; keys: string[] }[] {
+  const args: string[] = []
+  for (const m of text.matchAll(FIRST)) args.push(argumentAt(text, m.index + m[0].length))
+  for (const m of text.matchAll(SECOND)) {
+    const first = argumentAt(text, m.index + m[0].length)
+    const comma = m.index + m[0].length + first.length
+    // `present(error)` with no key takes the funnel's own default title.
+    if (text[comma] === ',') args.push(argumentAt(text, comma + 1).trim())
+  }
+  const keyed = args.map((arg) => ({
+    arg: arg.trim(),
+    keys: [...arg.matchAll(KEY)].map(([, k]) => k!),
+  }))
+  for (const m of text.matchAll(OPTION)) {
+    const keys = [...argumentAt(text, m.index + m[0].length).matchAll(KEY)].map(([, k]) => k!)
+    if (keys.length) keyed.push({ arg: m[0], keys })
+  }
+  return keyed
+}
+
+describe('toast title keys', () => {
+  it('reads the key argument of every call shape', () => {
+    const keys = (src: string) => keyArguments(src).flatMap((a) => a.keys)
+    expect(keys(`actionToast.success('a.saved', { params: { n } })`)).toEqual(['a.saved'])
+    expect(keys(`present(error, 'b.failed')`)).toEqual(['b.failed'])
+    expect(keys(`presentReported(job.error, 'b.reported', { descriptionKey: 'x' })`)).toEqual([
+      'b.reported',
+    ])
+    expect(keys(`actionToast.info(ok ? 'c.yes' : 'c.no')`)).toEqual(['c.yes', 'c.no'])
+    expect(keys(`presentLinkFailures(f, id, { titleKey: 'd.linkFailed' })`)).toEqual([
+      'd.linkFailed',
+    ])
+    expect(keys(`flushThen(submit, 'e.submitFailed')`)).toEqual(['e.submitFailed'])
+    expect(keys(`failureTitleKeys: { one: 'f.one', many: 'f.many' }`)).toEqual(['f.one', 'f.many'])
+    // A declaration or a forward names no key, and is not a call to check.
+    expect(keyArguments(`titleKey: string`)).toEqual([])
+    expect(keyArguments(`present(e)`)).toEqual([])
+    expect(keyArguments(`actionToast.success(meta.toastKey)`)).toEqual([
+      { arg: 'meta.toastKey', keys: [] },
+    ])
+  })
+
+  it('resolves every key a funnel is handed against the base catalog', () => {
+    const missing: string[] = []
+    const unreadable: string[] = []
+    let seen = 0
+    for (const file of sources(appRoot)) {
+      const rel = relative(appRoot, file).replaceAll('\\', '/')
+      if (FUNNELS.test(rel)) continue
+      const text = readFileSync(file, 'utf8')
+      for (const alias of text.matchAll(ALIAS)) unreadable.push(`${rel}: ${alias[0]} passed around`)
+      for (const { arg, keys } of keyArguments(text)) {
+        if (!keys.length && !(rel in INDIRECT)) unreadable.push(`${rel}: ${arg}`)
+        for (const key of keys) {
+          seen++
+          if (!hasI18nKey(key)) missing.push(`${rel}: ${key}`)
+        }
+      }
+      const prefix = INDIRECT[rel]
+      if (prefix !== undefined && prefix !== null) {
+        for (const [, key] of text.matchAll(KEY)) {
+          if (!key!.startsWith(prefix)) continue
+          seen++
+          if (!hasI18nKey(key!)) missing.push(`${rel}: ${key}`)
+        }
+      }
+    }
+    // A scan that matched nothing would pass vacuously, so it must have read some keys.
+    expect(seen).toBeGreaterThan(0)
+    expect(unreadable).toEqual([])
+    expect(missing).toEqual([])
+  })
+})

package/app/composables/useActionToast.spec.ts

@@ -0,0 +1,71 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { useActionToast } from '~/composables/useActionToast'
+
+// `test/setup.ts` stubs `useNuxtApp().$i18n.t` as a key echo; this spec swaps in a `t` that also
+// records its params, and a `useToast` whose `add` it can read back.
+const add = vi.fn()
+const t = vi.fn((key: string, params?: Record<string, unknown>, plural?: number) =>
+  [key, params && Object.keys(params).length ? JSON.stringify(params) : '', plural ?? '']
+    .filter((part) => part !== '')
+    .join('|'),
+)
+
+beforeEach(() => {
+  add.mockReset()
+  t.mockClear()
+  vi.stubGlobal('useToast', () => ({ add }))
+  vi.stubGlobal('useNuxtApp', () => ({ $i18n: { t } }))
+})
+
+const lastToast = () => add.mock.calls.at(-1)?.[0]
+
+describe('useActionToast', () => {
+  it('renders every success toast the same, whatever the call site', () => {
+    const toast = useActionToast()
+    toast.success('a.saved')
+    const first = lastToast()
+    toast.success('b.connected', { params: { name: 'x' } })
+    const second = lastToast()
+    for (const key of ['color', 'icon', 'duration'] as const) expect(second[key]).toBe(first[key])
+    expect(first.color).toBe('success')
+  })
+
+  it('auto-dismisses success and info, and keeps warning and error until closed', () => {
+    const toast = useActionToast()
+    toast.success('k')
+    expect(lastToast().duration).toBeUndefined()
+    toast.info('k')
+    expect(lastToast().duration).toBeUndefined()
+    toast.warning('k')
+    expect(lastToast().duration).toBe(0)
+    toast.error('k')
+    expect(lastToast().duration).toBe(0)
+  })
+
+  it('resolves the title key with its params and plural count', () => {
+    useActionToast().info('x.found', { params: { count: 3 }, plural: 3, description: 'body' })
+    expect(lastToast().title).toBe('x.found|{"count":3}|3')
+    expect(lastToast().description).toBe('body')
+  })
+
+  it('holds an undo toast exactly as long as the window and leads with the Undo action', () => {
+    const run = vi.fn()
+    const extra = { label: 'Open', onClick: vi.fn() }
+    useActionToast().success('board.toast.deleted', {
+      undo: { run, windowMs: 6000 },
+      actions: [extra],
+    })
+    const shown = lastToast()
+    expect(shown.duration).toBe(6000)
+    expect(shown.actions).toHaveLength(2)
+    expect(shown.actions[0].label).toBe('common.undo')
+    shown.actions[0].onClick()
+    expect(run).toHaveBeenCalledOnce()
+    expect(shown.actions[1]).toBe(extra)
+  })
+
+  it('sends no empty actions array', () => {
+    useActionToast().success('k')
+    expect(lastToast()).not.toHaveProperty('actions')
+  })
+})

package/app/composables/useActionToast.ts

@@ -0,0 +1,101 @@
+/**
+ * The toast for everything that is NOT a failed call: the second of the SPA's two toast funnels.
+ * A failed call goes to `usePipelineErrorToast().present(error, titleKey)`; every other toast comes
+ * from here, so `toast.add` is called from exactly those two composables
+ * (`scripts/check-frontend-feedback.mjs` enforces it).
+ *
+ * Each tone fixes its colour, its icon and whether it auto-dismisses, so two toasts of one tone
+ * render identically wherever they come from. The call site picks a TONE and supplies COPY; it
+ * cannot restyle the toast. Before this, some success toasts carried `color: 'success'` and some
+ * none, and the icon was a choice made per site (`i-lucide-check`, `-link`, `-unplug`, `-copy`,
+ * `-rocket`, or nothing).
+ *
+ * - `success`: the action the user asked for completed. Dismisses after Nuxt UI's default.
+ * - `info`: progress or a state report that asks nothing of the reader ("drafting…", "up to
+ *   date"). Dismisses after the default.
+ * - `warning`: the action ran, but the outcome is partial or nothing changed in a way the reader
+ *   should know about. Stays until closed, because it asks the reader to look at something.
+ * - `error`: a refusal in TRANSLATED copy that is not a failed call: a client-side validation that
+ *   never left the browser, or a recognised refusal reason the site maps to its own key. It has no
+ *   envelope, so `present` would misread it as a network fault (README, "Every failure toast goes
+ *   through ONE funnel"). Stays until closed, like every failure. A failure the backend reported
+ *   as DATA with its own prose (a job row's `error`) is `presentReported` on the failure funnel
+ *   instead, which keeps that prose as copyable detail rather than the headline.
+ *
+ * Titles are i18n KEYS, resolved here (the same contract as `present`), so a call site cannot hand
+ * in untranslated prose as the headline. A `description` is already-resolved text, because it
+ * often carries data (a repo name, a count line) built from several keys. A key handed in here is
+ * invisible to typed message keys and to `vue-i18n-extract`, which only read a key written literally inside a `t()` call, so
+ * `toastTitleKeys.spec.ts` resolves every literal key passed to either funnel against the catalog.
+ */
+
+/** One button on the toast. A call-to-action is content, so the call site may add one. */
+export interface ActionToastAction {
+  label: string
+  icon?: string
+  onClick: () => void
+}
+
+export interface ActionToastOptions {
+  /** Interpolation for the title key. */
+  params?: Record<string, unknown>
+  /** The plural count for the title key, when it has plural forms. */
+  plural?: number
+  /** Resolved body text. */
+  description?: string
+  actions?: ActionToastAction[]
+  /**
+   * Offer an Undo for a write whose real effect is deferred. The toast then stays exactly as long
+   * as the window the caller holds the write open for, because an Undo button that outlives the
+   * window would undo nothing.
+   */
+  undo?: { run: () => void; windowMs: number }
+}
+
+type Tone = 'success' | 'info' | 'warning' | 'error'
+
+// The only place a tone's look is decided. `duration: 0` keeps the toast until the reader closes
+// it; `undefined` takes Nuxt UI's default (5s).
+const TONES: Record<Tone, { color: Tone; icon: string; duration: number | undefined }> = {
+  success: { color: 'success', icon: 'i-lucide-circle-check', duration: undefined },
+  info: { color: 'info', icon: 'i-lucide-info', duration: undefined },
+  warning: { color: 'warning', icon: 'i-lucide-triangle-alert', duration: 0 },
+  error: { color: 'error', icon: 'i-lucide-triangle-alert', duration: 0 },
+}
+
+export function useActionToast() {
+  const toast = useToast()
+  // The Nuxt app's global i18n instance, not `useI18n()`: this is reached from store setup (the
+  // board store's undo toasts) and from `useCopyToClipboard`, which the error funnel calls from
+  // store setup. Same reason as `usePipelineErrorToast`.
+  const { t } = useNuxtApp().$i18n as ReturnType<typeof useI18n>
+
+  function show(tone: Tone, titleKey: string, opts: ActionToastOptions = {}): void {
+    const look = TONES[tone]
+    const params = opts.params ?? {}
+    const title = opts.plural === undefined ? t(titleKey, params) : t(titleKey, params, opts.plural)
+    const actions = [
+      ...(opts.undo
+        ? [{ label: t('common.undo'), icon: 'i-lucide-undo-2', onClick: opts.undo.run }]
+        : []),
+      ...(opts.actions ?? []),
+    ]
+    toast.add({
+      title,
+      description: opts.description,
+      color: look.color,
+      icon: look.icon,
+      duration: opts.undo ? opts.undo.windowMs : look.duration,
+      ...(actions.length ? { actions } : {}),
+    })
+  }
+
+  return {
+    success: (titleKey: string, opts?: ActionToastOptions) => show('success', titleKey, opts),
+    info: (titleKey: string, opts?: ActionToastOptions) => show('info', titleKey, opts),
+    warning: (titleKey: string, opts?: ActionToastOptions) => show('warning', titleKey, opts),
+    error: (titleKey: string, opts?: ActionToastOptions) => show('error', titleKey, opts),
+  }
+}
+
+export type ActionToast = ReturnType<typeof useActionToast>

package/app/composables/useBlockDeletion.ts

@@ -1,4 +1,5 @@
 import type { Block } from '~/types/domain'
+import { useActionToast } from '~/composables/useActionToast'
 
 /**
  * The single, confirm-gated block deletion used by BOTH the inspector's Delete button and
@@ -15,7 +16,7 @@ export function useBlockDeletion() {
   const execution = useExecutionStore()
   const ui = useUiStore()
   const recurring = useRecurringPipelinesStore()
-  const toast = useToast()
+  const actionToast = useActionToast()
   const { present } = usePipelineErrorToast()
   const { confirm } = useConfirm()
   const { t } = useI18n()
@@ -52,11 +53,7 @@ export function useBlockDeletion() {
     ui.select(null)
     try {
       await board.archiveService(block.id)
-      toast.add({
-        title: t('board.toast.archived', { name: block.title }),
-        icon: 'i-lucide-archive',
-        color: 'neutral',
-      })
+      actionToast.success('board.toast.archived', { params: { name: block.title } })
     } catch (e) {
       present(e, 'board.toast.archiveFailed')
     }

package/app/composables/useConfirmAction.ts

@@ -1,7 +1,7 @@
 /**
  * Confirm-gate + success-toast for the recurring destructive actions that aren't board
  * blocks (disconnect a connection, remove/revoke a credential, clear a config, destroy an
- * environment). Built on the same `useConfirm()` singleton + `useToast()` the board delete
+ * environment). Built on the same `useConfirm()` singleton + `useActionToast()` the board delete
  * path uses, so every destructive affordance across the settings/connection surfaces routes
  * through ONE confirm-then-mutate + toast path rather than each re-inventing its own copy.
  *
@@ -19,6 +19,8 @@
  * per surface. `name` is a short noun for the target (a brand like "Slack", a data value like
  * the invite email, or a feature noun like "the test environment").
  */
+import { useActionToast } from '~/composables/useActionToast'
+
 type ConfirmShape = 'disconnect' | 'remove' | 'revoke' | 'clear' | 'destroy'
 
 /**
@@ -71,7 +73,7 @@ const SHAPE_META: Record<
 
 export function useConfirmAction() {
   const { confirm } = useConfirm()
-  const toast = useToast()
+  const actionToast = useActionToast()
   const { t } = useI18n()
 
   /** Prompt before a destructive action against `name`. Resolves `true` only if confirmed. */
@@ -89,7 +91,7 @@ export function useConfirmAction() {
   /** Toast the completed destructive action (call only on real success). */
   function toastDone(shape: ConfirmShape, name: string): void {
     const meta = SHAPE_META[shape]
-    toast.add({ title: t(meta.toastKey, { name }), color: 'success', icon: 'i-lucide-check' })
+    actionToast.success(meta.toastKey, { params: { name } })
   }
 
   return { confirmAction, toastDone }

package/app/composables/useContextLinking.spec.ts

@@ -105,6 +105,7 @@ describe('resolvePending', () => {
     vi.stubGlobal('useWorkspaceStore', () => ({ workspaceId: 'ws_1' }))
     vi.stubGlobal('useToast', () => ({ add: vi.fn() }))
     vi.stubGlobal('useI18n', () => ({ t: (key: string) => key }))
+    vi.stubGlobal('useNuxtApp', () => ({ $i18n: { t: (key: string) => key } }))
     vi.stubGlobal('useCopyToClipboard', () => ({ copyAction: () => ({ label: 'copy' }) }))
   }
 
@@ -192,6 +193,7 @@ describe('presentLinkFailures', () => {
     vi.stubGlobal('useWorkspaceStore', () => ({ workspaceId: 'ws_1' }))
     vi.stubGlobal('useToast', () => ({ add }))
     vi.stubGlobal('useI18n', () => ({ t: (key: string) => key }))
+    vi.stubGlobal('useNuxtApp', () => ({ $i18n: { t: (key: string) => key } }))
     vi.stubGlobal('useCopyToClipboard', () => ({ copyAction }))
     return { add, copyAction }
   }
@@ -221,6 +223,7 @@ describe('presentLinkFailures', () => {
     const toast = add.mock.calls[0]![0]
     // Sticky so the cause stays readable, titled by the count key, and per-item reason shown.
     expect(toast.title).toBe('board.addTask.linkFailed')
+    expect(toast.color).toBe('warning')
     expect(toast.duration).toBe(0)
     expect(toast.description).toContain('GitHub denied access')
     expect(toast.actions).toHaveLength(1)

package/app/composables/useContextLinking.ts

@@ -1,5 +1,6 @@
 import type { DocumentSourceKind, TaskSourceKind } from '~/types/domain'
 import { apiErrorEnvelope, apiErrorStatus } from './api/errors'
+import { useActionToast } from '~/composables/useActionToast'
 
 // Shared model + orchestration for attaching external context (imported docs and
 // tracker issues) to a board block. A "pending" item is something the user has
@@ -121,7 +122,7 @@ export function useContextLinking() {
   const documents = useDocumentsStore()
   const tasks = useTasksStore()
   const workspace = useWorkspaceStore()
-  const toast = useToast()
+  const actionToast = useActionToast()
   const { t } = useI18n()
   const { copyAction } = useCopyToClipboard()
 
@@ -240,14 +241,12 @@ export function useContextLinking() {
   /**
    * Surface link failures as a single actionable toast: the specific per-item
    * reasons as the body, and a "Copy details" action that puts the full diagnostic
-   * report ({@link buildLinkFailureReport}) on the clipboard. Sticky (`duration: 0`)
-   * so the cause stays readable long enough to act on. No-op when nothing failed.
+   * report ({@link buildLinkFailureReport}) on the clipboard. A warning, so it stays until
+   * closed and the cause stays readable long enough to act on. No-op when nothing failed.
    *
-   * `opts.title` names what WAS created, which differs per host ("Task added, but …" vs
-   * "Initiative created, but …"). It is a resolver over the count rather than a message key, so
-   * each caller keeps a literal key at its own translation call site — passing the key through
-   * would make it a variable, which defeats both the typed-message-key check and the extractor's
-   * static scan — and the plural choice has to be made against the same count.
+   * `opts.titleKey` names what WAS created, which differs per host ("Task added, but …" vs
+   * "Initiative created, but …"). It is a plural key, resolved against the failure count;
+   * `toastTitleKeys.spec.ts` checks the literal each caller passes, which typed keys cannot see.
    */
   /**
    * A failure's line in the toast: TRANSLATED copy where the backend named a reason we have a
@@ -269,7 +268,7 @@ export function useContextLinking() {
   function presentLinkFailures(
     failures: LinkFailure[],
     blockId?: string,
-    opts: { title?: (count: number) => string } = {},
+    opts: { titleKey?: string } = {},
   ): void {
     if (failures.length === 0) return
     const description = failures.map((f) => `${f.item.title}: ${describeFailure(f)}`).join('\n')
@@ -278,14 +277,10 @@ export function useContextLinking() {
       blockId,
       when: new Date().toISOString(),
     })
-    toast.add({
-      title:
-        opts.title?.(failures.length) ??
-        t('board.addTask.linkFailed', { count: failures.length }, failures.length),
+    actionToast.warning(opts.titleKey ?? 'board.addTask.linkFailed', {
+      params: { count: failures.length },
+      plural: failures.length,
       description,
-      icon: 'i-lucide-triangle-alert',
-      color: 'warning',
-      duration: 0,
       actions: [copyAction(report)],
     })
   }

package/app/composables/useCopyToClipboard.ts

@@ -7,6 +7,7 @@
 // silent no-op the user couldn't tell apart from success. Routing every copy through this seam
 // makes the outcome always visible.
 import { useClipboard } from '@vueuse/core'
+import { useActionToast } from '~/composables/useActionToast'
 
 export function useCopyToClipboard() {
   // Resolved through the Nuxt app's global i18n instance rather than `useI18n()`, which requires an
@@ -16,7 +17,7 @@ export function useCopyToClipboard() {
   // component. `useI18n()` there throws `MUST_BE_CALL_SETUP_TOP`, and a throw in a store body takes
   // the whole app to Nuxt's error page. Same reason, and the same fix, as `usePipelineErrorToast`.
   const { t } = useNuxtApp().$i18n as ReturnType<typeof useI18n>
-  const toast = useToast()
+  const actionToast = useActionToast()
   const { copy: writeClipboard, isSupported } = useClipboard()
 
   async function copy(text: string) {
@@ -25,9 +26,9 @@ export function useCopyToClipboard() {
     try {
       if (!isSupported.value) throw new Error('clipboard unsupported')
       await writeClipboard(text)
-      toast.add({ title: t('common.copied'), color: 'success', icon: 'i-lucide-check' })
+      actionToast.success('common.copied')
     } catch {
-      toast.add({ title: t('common.copyFailed'), color: 'error', icon: 'i-lucide-x' })
+      actionToast.error('common.copyFailed')
     }
   }
 

package/app/composables/useNavContributions.ts

@@ -4,6 +4,7 @@ import { groupCommands, groupSidebar, sortToolbar } from '~/modular/nav-contribu
 import { EXTERNAL_TOOL_UNAVAILABLE_KEYS, projectExternalTools } from '~/modular/external-tools'
 import { toMetadataBag } from '~/modular/workspace-metadata'
 import type { ExternalToolContext, ExternalToolContribution } from '~/modular/external-tools'
+import { useActionToast } from '~/composables/useActionToast'
 import type {
   AppSlots,
   CommandGroup,
@@ -30,7 +31,7 @@ export function useNavContributions() {
   // an active component instance) — the same handle, and the same reason, as
   // `usePipelineErrorToast`: nothing about this composable should depend on WHERE it is called.
   const { t } = useNuxtApp().$i18n as ReturnType<typeof useI18n>
-  const toast = useToast()
+  const actionToast = useActionToast()
   const auth = useAuthStore()
   const workspace = useWorkspaceStore()
   const workspaceSettings = useWorkspaceSettingsStore()
@@ -148,13 +149,11 @@ export function useNavContributions() {
               resolution.cause,
             )
           }
-          toast.add({
-            title: t('externalTools.unavailable.title', { tool: tool.title }),
+          actionToast.error('externalTools.unavailable.title', {
+            params: { tool: tool.title },
             description: t(EXTERNAL_TOOL_UNAVAILABLE_KEYS[resolution.reason], {
               fields: resolution.missing.join(', '),
             }),
-            icon: 'i-lucide-triangle-alert',
-            color: 'warning',
           })
         },
       },

package/app/composables/usePipelineErrorToast.spec.ts

@@ -272,6 +272,30 @@ describe('usePipelineErrorToast', () => {
   })
 })
 
+describe('presentReported', () => {
+  it('keeps a failure reported as data behind the disclosure, under translated copy', () => {
+    // A job row's `error` is backend prose: it must be copyable detail, never the headline, and it
+    // must not be read as a network fault the way `present` reads a bare string.
+    usePipelineErrorToast().presentReported('stack exited with code 1', 'x.startFailed')
+    const arg = add.mock.calls[0]![0]
+    expect(arg.title).toBe('x.startFailed')
+    expect(arg.description).toBe('errors.reported.description')
+    expect(arg.duration).toBe(0)
+    arg.actions[0].onClick()
+    expect(update).toHaveBeenCalledWith('toast-1', {
+      description: 'stack exited with code 1',
+      actions: [expect.objectContaining({ label: 'common.copyDetails' })],
+    })
+  })
+
+  it('takes a site description key, and offers no disclosure when nothing was reported', () => {
+    usePipelineErrorToast().presentReported(null, 'x.failed', { descriptionKey: 'x.fallback' })
+    const arg = add.mock.calls[0]![0]
+    expect(arg.description).toBe('x.fallback')
+    expect(arg.actions).toEqual([expect.objectContaining({ label: 'common.copyDetails' })])
+  })
+})
+
 describe('describeGenericFailure', () => {
   it('maps each known status class to its own description key', () => {
     for (const code of [

package/app/composables/usePipelineErrorToast.ts

@@ -683,7 +683,12 @@ export function usePipelineErrorToast() {
     // ships in the base `en` catalog, so a locale missing it renders English via `fallbackLocale`
     // (better than the raw prose this replaced) and a bare key can never leak.
     const title = t(fallbackTitleKey, titleParams ?? {})
-    const description = t(failure.descriptionKey)
+    showFailure(title, t(failure.descriptionKey), detail)
+  }
+
+  /** The failure toast both generic paths render: translated title and description, the raw
+   * detail behind "Show details", and the whole report copyable. */
+  function showFailure(title: string, description: string, detail: string): void {
     const report = [title, description, detail].filter((part) => part.length > 0).join('\n')
     const added = toast.add({
       title,
@@ -713,6 +718,25 @@ export function usePipelineErrorToast() {
     })
   }
 
+  /**
+   * A failure the backend reported as DATA rather than as a failed call: a job row with
+   * `status: 'failed'` and its `error` text, a probe verdict with a `message`. There is no
+   * envelope, so `present` would misread it as a network fault. The reported text is backend prose
+   * and so DETAIL, never the headline: it goes behind "Show details" and into the copied report,
+   * under a translated description (`descriptionKey`, or the generic "it reported a failure").
+   */
+  function presentReported(
+    detail: string | null | undefined,
+    titleKey: string,
+    opts: { params?: Record<string, unknown>; descriptionKey?: string } = {},
+  ): void {
+    showFailure(
+      t(titleKey, opts.params ?? {}),
+      t(opts.descriptionKey ?? 'errors.reported.description'),
+      detail?.trim() ?? '',
+    )
+  }
+
   /**
    * Present `error` as a toast. `fallbackTitleKey` is an i18n message key used for
    * non-conflict failures and any conflict reason without a dedicated title; `titleParams` carries
@@ -732,5 +756,5 @@ export function usePipelineErrorToast() {
     presentGenericFailure(error, fallbackTitleKey, titleParams)
   }
 
-  return { present }
+  return { present, presentReported }
 }

package/app/composables/usePipelineLibraryActions.ts

@@ -2,6 +2,7 @@ import type { RunDefaultScope } from '@cat-factory/contracts'
 import type { Pipeline } from '~/types/domain'
 import { usePipelinesStore } from '~/stores/pipelines'
 import { usePipelineErrorToast } from '~/composables/usePipelineErrorToast'
+import { useActionToast } from '~/composables/useActionToast'
 
 /**
  * The actions a row of the saved-pipeline LIBRARY offers: archive, promote to a scope default,
@@ -14,7 +15,7 @@ import { usePipelineErrorToast } from '~/composables/usePipelineErrorToast'
  */
 export function usePipelineLibraryActions() {
   const pipelines = usePipelinesStore()
-  const toast = useToast()
+  const actionToast = useActionToast()
   const { t } = useI18n()
   const { present } = usePipelineErrorToast()
   const { confirm } = useConfirm()
@@ -24,8 +25,8 @@ export function usePipelineLibraryActions() {
     try {
       if (p.archived) await pipelines.unarchive(p.id)
       else await pipelines.archive(p.id)
-    } catch {
-      toast.add({ title: t('pipeline.builder.toast.updateFailed'), color: 'error' })
+    } catch (error) {
+      present(error, 'pipeline.builder.toast.updateFailed')
     }
   }
 
@@ -68,13 +69,11 @@ export function usePipelineLibraryActions() {
   async function clone(p: Pipeline) {
     try {
       const copy = await pipelines.clonePipeline(p.id)
-      toast.add({
-        title: t('pipeline.builder.toast.cloned', { name: p.name, copy: copy.name }),
-        color: 'success',
-        icon: 'i-lucide-copy',
+      actionToast.success('pipeline.builder.toast.cloned', {
+        params: { name: p.name, copy: copy.name },
       })
-    } catch {
-      toast.add({ title: t('pipeline.builder.toast.cloneFailed'), color: 'error' })
+    } catch (error) {
+      present(error, 'pipeline.builder.toast.cloneFailed')
     }
   }