@kernhq/module-inventory 0.1.2 → 0.3.0

package/src/client/errors.test.ts

@@ -0,0 +1,365 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import {
+  codeOf,
+  errorLine,
+  errorMessage,
+  isInputValidation,
+  messageOf,
+  reasonKeys,
+  reasonOf,
+} from './errors.js'
+import { en } from './messages.js'
+
+/**
+ * Every actionable failure a person can hit, in a language they chose.
+ *
+ * Eight call sites read `toast.error(error.message || t('common.error'))`, and `error.message` is a
+ * sentence the *server* wrote in English. So a Persian reader losing a race on a handover was shown
+ * "Somebody changed who is holding this a moment before you did. Reload to see where it is now." —
+ * the single most useful sentence this module has, in the wrong language, at the exact moment they
+ * needed to read it.
+ *
+ * Three things are checked here, and the third is the one that lasts:
+ *
+ *   1. the reason token is found wherever a transport puts it, and the code when there is none;
+ *   2. every key this file can name exists in the catalogue, so none renders as its own key;
+ *   3. **every reason the server actually throws has a sentence here** — read out of
+ *      `src/server`, so a refusal added next month fails in this file rather than reaching
+ *      somebody's screen in English.
+ */
+const conflict = (reason: string, message = 'English prose the server wrote.') => ({
+  code: 'CONFLICT',
+  message,
+  data: { reason },
+})
+
+describe('reading what the server sent', () => {
+  it('finds the reason where `kernErrorToORPC` puts it', () => {
+    // The reason is folded into `data` rather than sent beside it, because `data` is what oRPC
+    // already carries to the client.
+    expect(reasonOf(conflict('inventory.custody.conflict'))).toBe('inventory.custody.conflict')
+  })
+
+  it('finds it on the error itself too, which is where the in-memory mock carries it', () => {
+    expect(reasonOf({ code: 'CONFLICT', reason: 'inventory.custody.not_held' })).toBe(
+      'inventory.custody.not_held',
+    )
+  })
+
+  it('has no reason for a plain failure, rather than inventing one', () => {
+    expect(reasonOf(new Error('network'))).toBe(null)
+    expect(reasonOf(null)).toBe(null)
+    expect(reasonOf({ data: { reason: 42 } })).toBe(null)
+  })
+
+  it('reads the code, and keeps the server sentence for the fallback line', () => {
+    expect(codeOf({ code: 'NOT_FOUND' })).toBe('NOT_FOUND')
+    expect(codeOf(new Error('boom'))).toBe(null)
+    expect(messageOf(new Error('  boom  '))).toBe('boom')
+    expect(messageOf({ message: '   ' })).toBe(null)
+  })
+})
+
+describe('which sentence a refusal earns', () => {
+  it('translates the conflict on a handover, which is the message that mattered most', () => {
+    expect(errorLine(conflict('inventory.custody.conflict'))).toEqual({
+      key: 'error_custody_conflict',
+      detail: null,
+    })
+  })
+
+  it('drops the server prose once it has named the failure itself', () => {
+    // Keeping it would print an English sentence under the Persian one, undoing the translation.
+    expect(errorLine(conflict('inventory.category.name_taken')).detail).toBe(null)
+  })
+
+  /**
+   * A **disabled capability answers 404, not 403** — the module contract says so, and the shell has
+   * already hidden the navigation for it. So a workspace that switches `repairs` off mid-session
+   * lands here, and "it is no longer there, reload" is the right sentence for it.
+   */
+  it('falls back to the class of failure when there is no reason', () => {
+    expect(errorLine({ code: 'NOT_FOUND', message: 'Asset not found' })).toEqual({
+      key: 'error_not_found',
+      detail: null,
+    })
+    expect(errorLine({ code: 'MODULE_DISABLED', message: 'Module inventory is disabled' }).key).toBe(
+      'error_module_disabled',
+    )
+    expect(errorLine({ code: 'FORBIDDEN' }).key).toBe('error_forbidden')
+  })
+
+  it('prefers the reason over the code, because it is the more specific fact', () => {
+    expect(errorLine(conflict('inventory.repair.already_open')).key).toBe('error_repair_already_open')
+    expect(errorLine({ code: 'CONFLICT' }).key).toBe('error_conflict')
+  })
+
+  /**
+   * A reason a newer server invented, an error from core, a socket that died. The generic sentence
+   * says what happened and the server's words are kept as the only actionable clue left — as
+   * *detail*, under a sentence that is at least in the reader's language.
+   */
+  it('keeps the server words only for a failure it does not recognise', () => {
+    const unknown = { code: 'CONFLICT', message: 'Some newer refusal.', data: { reason: 'inventory.x.y' } }
+    // A reason nothing here maps falls through to the code, which is still translated.
+    expect(errorLine(unknown).key).toBe('error_conflict')
+    expect(errorLine(new Error('Failed to fetch'))).toEqual({
+      key: 'error_unknown',
+      detail: 'Failed to fetch',
+    })
+  })
+
+  it('says something rather than nothing for a failure with no words at all', () => {
+    expect(errorLine({})).toEqual({ key: 'error_unknown', detail: null })
+    expect(errorMessage({}, (key) => key)).toBe('error_unknown')
+  })
+
+  /**
+   * The four refusals that were told to go and check a form where nothing was wrong.
+   *
+   * `KernError.badRequest` and oRPC's own schema failure both come out as `BAD_REQUEST`, and the
+   * client mapped every one of them to "Something in the form was not accepted. Check what you
+   * entered." The server was actually saying "That person is not a member of this workspace", "That
+   * file has not finished uploading yet", "That file is not one this workspace can attach" and
+   * "That page marker is not one this list issued" — none of which is a field somebody typed
+   * wrong. A confident wrong instruction is worse than a vague right one: nobody finds the mistake,
+   * because there isn't one.
+   *
+   * `data.issues` is the only structural difference between the two, and oRPC always sets it —
+   * `validateInput` throws `ORPCError('BAD_REQUEST', { data: { issues } })`.
+   */
+  describe('a refusal is not a form error', () => {
+    const refusal = (message: string) => ({ code: 'BAD_REQUEST', message })
+
+    it('tells a validation failure from a service refusing', () => {
+      expect(isInputValidation({ code: 'BAD_REQUEST', data: { issues: [{ message: 'too long' }] } })).toBe(
+        true,
+      )
+      expect(isInputValidation(refusal('That file has not finished uploading yet.'))).toBe(false)
+      expect(isInputValidation({ data: { issues: 'nope' } })).toBe(false)
+      expect(isInputValidation(null)).toBe(false)
+    })
+
+    it('keeps "check what you entered" for the failure that really is about the form', () => {
+      expect(
+        errorLine({
+          code: 'BAD_REQUEST',
+          message: 'Input validation failed',
+          data: { issues: [{ message: 'Too long' }] },
+        }),
+      ).toEqual({ key: 'error_bad_request', detail: null })
+      // `VALIDATION` is the code making that claim itself, so it needs no issues to be believed.
+      expect(errorLine({ code: 'VALIDATION' }).key).toBe('error_bad_request')
+    })
+
+    it('does not send anybody to the form for any of the four the server actually refuses', () => {
+      for (const message of [
+        'That person is not a member of this workspace, so nothing can be handed to them.',
+        'That file has not finished uploading yet.',
+        'That file is not one this workspace can attach.',
+        'That page marker is not one this list issued',
+      ]) {
+        expect(errorLine(refusal(message))).toEqual({ key: 'error_refused', detail: message })
+      }
+    })
+
+    /**
+     * Until those four carry a stable `reason`, the server's own sentence is the only thing that
+     * says *which* refusal it was — so it is kept, as detail under a translated line. Dropping it
+     * would leave "That was not accepted." and nothing else.
+     */
+    it('keeps the server’s explanation, because nothing else identifies the refusal', () => {
+      expect(errorMessage(refusal('That file has not finished uploading yet.'), (key) => `<${key}>`)).toBe(
+        '<error_refused> — That file has not finished uploading yet.',
+      )
+      // And says something rather than nothing when there are no words at all.
+      expect(errorLine({ code: 'BAD_REQUEST' })).toEqual({ key: 'error_refused', detail: null })
+    })
+
+    /**
+     * The moment the server does carry one, that reason wins and the sentence is fully translated.
+     * Nothing is required of this file then except an entry in `REASON_KEYS` — this checks the
+     * precedence is already the right way round.
+     */
+    it('prefers a reason over the refusal fallback, once the server carries one', () => {
+      expect(
+        errorLine({
+          code: 'BAD_REQUEST',
+          message: 'This item is archived. Restore it before handing it over.',
+          data: { reason: 'inventory.custody.archived' },
+        }),
+      ).toEqual({ key: 'error_custody_archived', detail: null })
+    })
+  })
+
+  it('joins the sentence and the detail into one line for the toast', () => {
+    expect(errorMessage(new Error('Failed to fetch'), (key) => `<${key}>`)).toBe(
+      '<error_unknown> — Failed to fetch',
+    )
+    expect(errorMessage(conflict('inventory.custody.not_held'), (key) => `<${key}>`)).toBe(
+      '<error_custody_not_held>',
+    )
+  })
+})
+
+// ------------------------------------------------------- the two lists that have to stay in step
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SERVER = join(HERE, '..', 'server')
+
+/**
+ * Every reason literal the server passes to a `KernError`, dug out of the source.
+ *
+ * Deliberately not a grep for `'inventory.…'`: permission keys, capability ids and notification
+ * types all look exactly like a reason token, and matching them would demand a sentence for things
+ * that are not refusals. This reads the argument position instead — the second of `conflict` and
+ * `notFound`, the fourth of the constructor — which is the only place a reason can be.
+ */
+function serverReasons(): string[] {
+  const found = new Set<string>()
+  const files = readdirSync(SERVER, { recursive: true, encoding: 'utf8' }).filter(
+    (file) => file.endsWith('.ts') && !file.endsWith('.test.ts'),
+  )
+  for (const file of files) {
+    const source = readFileSync(join(SERVER, file), 'utf8')
+    for (const [call, position] of [
+      ['KernError.conflict(', 1],
+      ['KernError.notFound(', 1],
+      ['new KernError(', 3],
+    ] as const) {
+      let at = source.indexOf(call)
+      while (at !== -1) {
+        const args = argumentsOf(source, at + call.length - 1)
+        const literal = args?.[position]?.trim().match(/^'([^']+)'$/)?.[1]
+        if (literal?.startsWith('inventory.')) found.add(literal)
+        at = source.indexOf(call, at + 1)
+      }
+    }
+  }
+  return [...found].sort()
+}
+
+/**
+ * The arguments of a call, split on the commas that are actually arguments.
+ *
+ * **String-aware, and that is not fussiness.** The first version split on every top-level comma and
+ * missed `inventory.custody.not_held` — because its message is "Nobody is holding this item, so
+ * there is nothing to hand on. Assign it instead." and the comma inside the sentence made the
+ * reason the *third* argument. A scanner that silently finds fewer things than there are is worse
+ * than no scanner: it passes.
+ */
+function argumentsOf(source: string, open: number): string[] | null {
+  const parts: string[] = []
+  let depth = 0
+  let quote: string | null = null
+  let start = open + 1
+  for (let i = open; i < source.length; i++) {
+    const ch = source[i]
+    if (quote) {
+      if (ch === '\\') i++
+      else if (ch === quote) quote = null
+      continue
+    }
+    if (ch === "'" || ch === '"' || ch === '`') quote = ch
+    else if (ch === '(' || ch === '{' || ch === '[') depth++
+    else if (ch === ')' || ch === '}' || ch === ']') {
+      depth--
+      if (depth === 0) {
+        parts.push(source.slice(start, i))
+        return parts
+      }
+    } else if (ch === ',' && depth === 1) {
+      parts.push(source.slice(start, i))
+      start = i + 1
+    }
+  }
+  return null
+}
+
+/**
+ * Every sentence the server passes to `KernError.badRequest`, dug out of the source.
+ *
+ * The same trick `serverReasons` uses and for the same reason: the list grows. It was four when
+ * this was written — a non-member, an unfinished upload, a file from another workspace, a page
+ * marker this list never issued — and by the time it was finished it was six. None of them is a
+ * form-validation failure, and every one of them used to arrive as "check what you entered".
+ */
+function serverBadRequests(): string[] {
+  const found = new Set<string>()
+  const call = 'KernError.badRequest('
+  const files = readdirSync(SERVER, { recursive: true, encoding: 'utf8' }).filter(
+    (file) => file.endsWith('.ts') && !file.endsWith('.test.ts'),
+  )
+  for (const file of files) {
+    const source = readFileSync(join(SERVER, file), 'utf8')
+    let at = source.indexOf(call)
+    while (at !== -1) {
+      const literal = argumentsOf(source, at + call.length - 1)?.[0]
+        ?.trim()
+        .match(/^'((?:[^'\\]|\\.)*)'$/)?.[1]
+      if (literal) found.add(literal)
+      at = source.indexOf(call, at + 1)
+    }
+  }
+  return [...found].sort()
+}
+
+describe('the catalogue keeps up with the server', () => {
+  /**
+   * Not one of the module's own `BAD_REQUEST` refusals is about a field somebody typed, so not one
+   * of them may land on `error_bad_request`. This reads them out of `src/server` rather than
+   * listing them, so a refusal added next month is covered the day it is written — and if one ever
+   * *is* a form error, it fails here and asks for a `reason` instead of a reworded sentence.
+   */
+  it('sends no refusal the server actually throws back to the form', () => {
+    const refusals = serverBadRequests()
+    expect(refusals.length).toBeGreaterThan(3)
+    for (const message of refusals)
+      expect({ message, line: errorLine({ code: 'BAD_REQUEST', message }) }).toEqual({
+        message,
+        line: { key: 'error_refused', detail: message },
+      })
+  })
+
+  it('has a translated sentence for every reason the server throws', () => {
+    // If this fails, a refusal was added to `src/server` without a sentence — and it will reach a
+    // Persian, Arabic, German or Turkish reader as English prose. Add the reason to `REASON_KEYS`
+    // and the sentence to all five bundles.
+    const missing = serverReasons().filter((reason) => !reasonKeys().includes(reason))
+    expect(missing).toEqual([])
+  })
+
+  it('is reading the server rather than passing on an empty sweep', () => {
+    // An empty result would make the check above pass for ever. The services throw eleven of these.
+    expect(serverReasons().length).toBeGreaterThan(8)
+  })
+
+  it('names no reason the server does not throw', () => {
+    // The other direction: a sentence for a refusal that cannot happen is dead weight nobody will
+    // ever notice has gone wrong.
+    const server = serverReasons()
+    expect(reasonKeys().filter((key) => !server.includes(key))).toEqual([])
+  })
+
+  it('names a key the catalogue actually has, for every reason and every code', () => {
+    const keys = new Set<string>()
+    for (const reason of reasonKeys()) keys.add(errorLine(conflict(reason)).key)
+    for (const code of [
+      'NOT_FOUND',
+      'FORBIDDEN',
+      'MODULE_DISABLED',
+      'CONFLICT',
+      'BAD_REQUEST',
+      'VALIDATION',
+      'UNAUTHORIZED',
+      'RATE_LIMITED',
+      'UNAVAILABLE',
+      'INTERNAL',
+    ])
+      keys.add(errorLine({ code }).key)
+    for (const key of keys) expect({ key, has: `inventory.${key}` in en }).toEqual({ key, has: true })
+  })
+})

package/src/client/errors.ts

@@ -0,0 +1,201 @@
+/**
+ * Turning a refusal from the server into a sentence in the reader's own language.
+ *
+ * **Every actionable failure this module could produce reached the user in English, in all five
+ * locales.** Eight call sites were written as `toast.error(error.message || t('common.error'))`,
+ * and `error.message` is prose the *server* wrote: "Somebody changed who is holding this a moment
+ * before you did. Reload to see where it is now." That is the most useful sentence in the module
+ * and a Persian reader was shown it in English, at exactly the moment they needed to understand it.
+ * The comments at those call sites even said so — that the server's message was "the actionable
+ * one" — which was true, and was an argument for translating it rather than for printing it.
+ *
+ * The thing a client can translate is the **reason**, not the message. `KernError.conflict(message,
+ * reason)` has carried one since it was written, and `kernErrorToORPC` puts it in `data.reason`
+ * precisely so a client can branch on it: `inventory.custody.already_held` is a stable token that
+ * ships with the contract, where the sentence is prose that changes when somebody rewords it. So:
+ *
+ *   1. a `reason` this module knows → its own translated sentence;
+ *   2. otherwise the error **code** → the sentence that class of failure deserves;
+ *   3. otherwise a generic failure, and the server's own words underneath it.
+ *
+ * Step three is not a shrug. Dropping the server's message entirely would hide the one clue
+ * somebody could act on when the reason is one this build has never heard of — a newer server, an
+ * error from core rather than from here. It is shown as *detail*, under a sentence that at least
+ * names what failed, rather than as the whole of what the interface has to say.
+ *
+ * Pure and string-free: this file decides *which* key, `i18n.ts` holds the words, and a `.svelte`
+ * file cannot be unit-tested. `errorMessage()` at the bottom is the one function the screens call.
+ */
+
+/** What oRPC hands a screen. `code` is the contract's `ErrorCode`; `data` is what the server put in it. */
+export interface ServerError {
+  code?: unknown
+  message?: unknown
+  data?: unknown
+  status?: unknown
+}
+
+/**
+ * The reason token, out of wherever this particular transport put it.
+ *
+ * `data.reason` is the real one — that is what `kernErrorToORPC` folds it into. `reason` on the
+ * error itself is read too, because that is where a `KernError` thrown in-process carries it, and
+ * the mock in this package is neither: a demo that could not reproduce a translated conflict would
+ * be a demo that hides the branch this file exists for.
+ */
+export function reasonOf(err: unknown): string | null {
+  if (!err || typeof err !== 'object') return null
+  const e = err as ServerError & { reason?: unknown }
+  const data = e.data as { reason?: unknown } | undefined
+  const found = (data && typeof data === 'object' ? data.reason : undefined) ?? e.reason
+  return typeof found === 'string' && found ? found : null
+}
+
+/** The `ErrorCode` the server refused with, if this is one of its errors at all. */
+export function codeOf(err: unknown): string | null {
+  if (!err || typeof err !== 'object') return null
+  const { code } = err as ServerError
+  return typeof code === 'string' && code ? code : null
+}
+
+/**
+ * Whether a `BAD_REQUEST` is oRPC saying the *input* was malformed, or a service refusing.
+ *
+ * **Both arrive as `BAD_REQUEST`, and only one of them is about the form.** oRPC throws
+ * `ORPCError('BAD_REQUEST', { message: 'Input validation failed', data: { issues } })` when a zod
+ * schema rejects the input — that one really is "check what you entered". The ones this module's
+ * own services throw are not:
+ *
+ *   - "That person is not a member of this workspace, so nothing can be handed to them."
+ *   - "That file has not finished uploading yet."
+ *   - "That file is not one this workspace can attach."
+ *   - "That page marker is not one this list issued"
+ *   - "That category is not one this workspace has."
+ *   - "A repair cannot be sent in the future."
+ *
+ * Every field on those forms is fine. Sending somebody to re-read them is worse than saying
+ * nothing, because it is a confident wrong instruction: nobody finds the mistake, because there
+ * isn't one. `issues` is the one structural difference between the two, so it is what decides.
+ *
+ * This is a stopgap, and the report that came with it says so. The right fix is a **stable reason
+ * token** on each of those four — `KernError.badRequest` takes `details` where `conflict` takes a
+ * `reason`, so today they carry nothing a client can branch on and the server's English prose is
+ * the only clue that survives. Once they carry one, they belong in `REASON_KEYS` with a sentence
+ * each in all five languages, and this branch goes back to being about validation alone.
+ */
+export function isInputValidation(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false
+  const data = (err as ServerError).data as { issues?: unknown } | undefined
+  return Boolean(data && typeof data === 'object' && Array.isArray(data.issues))
+}
+
+/** Whatever the server said, for the detail line under a failure nothing here recognises. */
+export function messageOf(err: unknown): string | null {
+  if (!err) return null
+  if (typeof err === 'string') return err.trim() || null
+  if (typeof err !== 'object') return null
+  const { message } = err as ServerError
+  return typeof message === 'string' && message.trim() ? message.trim() : null
+}
+
+/**
+ * Every reason this module's server actually throws, and the sentence each one earns.
+ *
+ * Not "every reason imaginable": each key here is one this package's own services produce, and
+ * `errors.test.ts` reads them out of `src/server` to hold the two lists together. A sentence for a
+ * refusal that cannot happen is dead weight nobody will ever notice is wrong; a refusal with no
+ * sentence is English on somebody's screen, which is the defect this file was written for.
+ *
+ * The wording is what the reader can *do*, in the same voice as the rest of the module. A lost race
+ * says to look again; a conflict of state says which handover to use instead.
+ */
+const REASON_KEYS: Record<string, string> = {
+  'inventory.custody.conflict': 'error_custody_conflict',
+  'inventory.custody.archived': 'error_custody_archived',
+  'inventory.custody.already_held': 'error_custody_already_held',
+  'inventory.custody.not_held': 'error_custody_not_held',
+  'inventory.asset.still_held': 'error_asset_still_held',
+  'inventory.asset.under_repair': 'error_asset_under_repair',
+  'inventory.repair.already_open': 'error_repair_already_open',
+  'inventory.repair.archived': 'error_repair_archived',
+  'inventory.repair.already_complete': 'error_repair_already_complete',
+  'inventory.repair.returned_before_sent': 'error_repair_returned_before_sent',
+  'inventory.category.name_taken': 'error_category_name_taken',
+}
+
+export const reasonKeys = (): readonly string[] => Object.keys(REASON_KEYS)
+
+/**
+ * The sentence a whole class of failure earns, when no reason narrows it further.
+ *
+ * `NOT_FOUND` and `MODULE_DISABLED` are the two worth spelling out. A 404 here almost always means
+ * somebody else archived or removed the row while this screen was open, so "it is no longer there —
+ * reload" is both true and the next step. `MODULE_DISABLED` is what a workspace gets when Inventory
+ * is switched off underneath it, and "Forbidden" would be the wrong word for it entirely.
+ *
+ * A **disabled capability answers 404, not 403** — that is the module contract — so a capability
+ * switched off mid-session lands on `NOT_FOUND` here, which is the same "it is not there any more,
+ * look again" sentence, and correctly so.
+ */
+const CODE_KEYS: Record<string, string> = {
+  NOT_FOUND: 'error_not_found',
+  FORBIDDEN: 'error_forbidden',
+  MODULE_DISABLED: 'error_module_disabled',
+  CONFLICT: 'error_conflict',
+  // Reached only when the request really did fail validation — `errorLine` peels off the refusals
+  // first. `VALIDATION` is here because the code itself is the claim; `BAD_REQUEST` is not.
+  BAD_REQUEST: 'error_bad_request',
+  VALIDATION: 'error_bad_request',
+  UNAUTHORIZED: 'error_unauthorized',
+  RATE_LIMITED: 'error_rate_limited',
+  UNAVAILABLE: 'error_unavailable',
+}
+
+/**
+ * Which sentence to show, and whether the server's own words go under it.
+ *
+ * `detail` is filled only for the fallback: when this module named the failure itself, repeating
+ * the server's English beneath its own Persian sentence would undo the translation.
+ */
+export interface ErrorLine {
+  /** A key for `t()`, always one this module's catalogue has. */
+  key: string
+  /** The server's own sentence, for a failure nothing here recognised. Null otherwise. */
+  detail: string | null
+}
+
+export function errorLine(err: unknown): ErrorLine {
+  const reason = reasonOf(err)
+  const byReason = reason ? REASON_KEYS[reason] : undefined
+  if (byReason) return { key: byReason, detail: null }
+
+  const code = codeOf(err)
+
+  // A `BAD_REQUEST` with no validation issues on it is a service refusing something, not a schema
+  // rejecting a field — so it gets a sentence that does not send anybody back to a form that is
+  // fine, and the server's own explanation as the detail. That prose is English until those four
+  // refusals carry a reason token; an English clue under a translated sentence is worse than a
+  // translated one and much better than a confident wrong instruction.
+  if (code === 'BAD_REQUEST' && !isInputValidation(err))
+    return { key: 'error_refused', detail: messageOf(err) }
+
+  const byCode = code ? CODE_KEYS[code] : undefined
+  if (byCode) return { key: byCode, detail: null }
+
+  // Nothing recognised it — a newer server, a failure from core, or the network. The generic
+  // sentence names what happened and the server's words are kept as the only actionable clue left.
+  return { key: 'error_unknown', detail: messageOf(err) }
+}
+
+/**
+ * The one call a screen makes: `toast.error(errorMessage(error, t))`.
+ *
+ * `t` is passed in rather than imported so this file goes on importing nothing — `i18n.ts` reaches
+ * `@kernhq/ui`, and that entry point drags a Svelte compiler into whatever imports it, which is
+ * what makes a helper untestable.
+ */
+export function errorMessage(err: unknown, translate: (key: string) => string): string {
+  const line = errorLine(err)
+  const sentence = translate(line.key)
+  return line.detail ? `${sentence} — ${line.detail}` : sentence
+}