manigent-server 0.1.0__py3-none-any.whl

manigent/web/frontend/src/utils/hubThread.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from 'vitest'
+import {
+  checkHubPayload, closedBanner, hubLinkPausesSending, hubThreadInputState, offlineConfirmText, payloadTooLargeLine, type HubThreadInput,
+} from './hubThread'
+import { NOW_S, hubConfig, hubTarget } from '../test/hubFixtures'
+import type { HubErrorBody } from '../api/endpoints/hub'
+
+const names = { display: 'scout@acme.dev', name: 'scout', deploymentName: 'acme.dev', fingerprint: '3f9a1c2e5b7d9f00' }
+const live = { agent_online: true, deployment_connected: true, accepting_messages: true, listed: true }
+const base = (o: Partial<HubThreadInput> = {}): HubThreadInput =>
+  ({ config: hubConfig(), names, hubTarget: hubTarget(), live, lastError: null, nowMs: NOW_S * 1000, ...o })
+const err = (code: string, extra: Record<string, unknown> = {}): HubErrorBody => ({ code, message: '', ...extra })
+const reason = (i: HubThreadInput) => {
+  const s = hubThreadInputState(i)
+  return s.enabled ? (s.confirm ?? 'enabled') : s.reason
+}
+
+describe('hubThreadInputState precedence (first match wins)', () => {
+  it('enabled when everything is fine', () => {
+    expect(hubThreadInputState(base())).toEqual({ enabled: true, confirm: null, notice: null })
+  })
+
+  it('mode off beats everything, and reads as history on a thread', () => {
+    const s = hubThreadInputState(base({ config: hubConfig({ mode: 'off', registration: 'none' }), hubTarget: hubTarget({ closed_reason: 'key_revoked' }) }))
+    expect(s).toMatchObject({ enabled: false, reason: 'hub_off', text: 'The hub is turned off on this server. This conversation is kept as history.' })
+  })
+
+  it.each(['none', 'pending_email', 'held_for_reclaim'])('registration %s → not registered', (registration) => {
+    expect(reason(base({ config: hubConfig({ registration, mode: 'discover_only' }) }))).toBe('not_registered')
+  })
+
+  it('a live hub_not_registered error → not registered', () => {
+    expect(reason(base({ lastError: err('hub_not_registered') }))).toBe('not_registered')
+  })
+
+  it('suspended, then browse-only, then untrusted', () => {
+    expect(reason(base({ config: hubConfig({ registration: 'suspended', mode: 'discover_only' }) }))).toBe('suspended')
+    expect(reason(base({ config: hubConfig({ mode: 'discover_only', hub_link: 'untrusted' }) }))).toBe('browse_only')
+    expect(reason(base({ config: hubConfig({ hub_link: 'untrusted' }), hubTarget: hubTarget({ closed_reason: 'key_revoked' }) }))).toBe('untrusted')
+    expect(reason(base({ lastError: err('hub_untrusted') }))).toBe('untrusted')
+  })
+
+  it('a stored closed_reason beats unlisted and unreachable', () => {
+    const s = hubThreadInputState(base({
+      config: hubConfig({ deployment_connected: false }),
+      hubTarget: hubTarget({ closed_reason: 'identity_changed', listed: false }),
+    }))
+    expect(s).toMatchObject({ enabled: false, reason: 'closed', closedReason: 'identity_changed' })
+  })
+
+  it('a live close from the last send error until hub_target catches up', () => {
+    expect(hubThreadInputState(base({ lastError: err('agent_unlisted') }))).toMatchObject({ reason: 'closed', closedReason: 'agent_unlisted' })
+  })
+
+  it('unlisted from hub_target or from the agent detail', () => {
+    expect(reason(base({ hubTarget: hubTarget({ listed: false }) }))).toBe('unlisted')
+    expect(reason(base({ live: { ...live, listed: false } }))).toBe('unlisted')
+  })
+
+  it('unreachable from the link, the deployment, or a send error, with last_connected_at', () => {
+    expect(reason(base({ config: hubConfig({ hub_link: 'unreachable' }) }))).toBe('unreachable')
+    expect(reason(base({ config: hubConfig({ deployment_connected: false }) }))).toBe('unreachable')
+    const s = hubThreadInputState(base({ lastError: err('hub_unreachable', { last_connected_at: NOW_S - 3600 }) }))
+    expect(s).toMatchObject({ reason: 'unreachable' })
+    expect(!s.enabled && s.text).toContain('Last connected')
+  })
+
+  it("mode auto: an idle or not-yet-connected socket doesn't pause sending (a send connects first)", () => {
+    for (const link of ['off', 'unreachable'] as const) {
+      const config = hubConfig({ mode: 'auto', hub_link: link, deployment_connected: false })
+      expect(hubLinkPausesSending(config)).toBe(false)
+      expect(reason(base({ config }))).toBe('enabled')
+    }
+  })
+
+  it("mode auto: the server's own refusal, untrusted or suspended still block", () => {
+    const idle = { mode: 'auto' as const, hub_link: 'off' as const, deployment_connected: false }
+    const s = hubThreadInputState(base({ config: hubConfig(idle), lastError: err('hub_unreachable', { last_connected_at: NOW_S - 3600 }) }))
+    expect(s).toMatchObject({ enabled: false, reason: 'unreachable' })
+    expect(!s.enabled && s.text).toContain('Sending to other servers is paused.')
+    expect(reason(base({ config: hubConfig({ ...idle, hub_link: 'untrusted' }) }))).toBe('untrusted')
+    expect(reason(base({ config: hubConfig({ ...idle, registration: 'suspended' }) }))).toBe('suspended')
+  })
+
+  it('modes full and discover_only: a link that is down still pauses', () => {
+    for (const mode of ['full', 'discover_only'] as const) {
+      expect(hubLinkPausesSending(hubConfig({ mode, hub_link: 'unreachable' }))).toBe(true)
+      expect(hubLinkPausesSending(hubConfig({ mode, deployment_connected: false }))).toBe(true)
+      expect(hubLinkPausesSending(hubConfig({ mode }))).toBe(false)
+    }
+    expect(reason(base({ config: hubConfig({ mode: 'full', hub_link: 'off', deployment_connected: false }) }))).toBe('unreachable')
+  })
+
+  it('a running rate-limit wait shows a countdown', () => {
+    const s = hubThreadInputState(base({ rateLimitedUntil: NOW_S * 1000 + 42_000 }))
+    expect(s).toMatchObject({ reason: 'rate_limited', waitSeconds: 42 })
+    expect(!s.enabled && s.text).toBe("You're sending too fast to scout@acme.dev. You can send again in 0:42.")
+    expect(reason(base({ rateLimitedUntil: NOW_S * 1000 - 1 }))).toBe('enabled')
+  })
+
+  it('not accepting, then offline confirms', () => {
+    expect(reason(base({ live: { ...live, accepting_messages: false } }))).toBe('not_accepting')
+    expect(reason(base({ live: { ...live, deployment_connected: false, agent_online: false } }))).toBe('deployment_offline')
+    expect(reason(base({ live: { ...live, agent_online: false } }))).toBe('agent_offline')
+  })
+
+  it('needs approval is a notice, not a block', () => {
+    const s = hubThreadInputState(base({ live: { ...live, needs_approval: true } }))
+    expect(s).toEqual({ enabled: true, confirm: null, notice: "scout's owner approves new contacts first. Your first message waits until they accept you." })
+  })
+
+  it('a draft (no thread) still checks the hub state', () => {
+    expect(reason(base({ hubTarget: null, config: hubConfig({ mode: 'off' }) }))).toBe('hub_off')
+    expect(reason(base({ hubTarget: null }))).toBe('enabled')
+  })
+
+  it('a send refused as conversation_closed takes the real reason from the body\'s closed_reason', () => {
+    const err = (closed_reason?: unknown) => ({ code: 'conversation_closed', message: 'closed', ...(closed_reason === undefined ? {} : { closed_reason }) })
+    const open = hubTarget({ closed_reason: null })
+    expect(hubThreadInputState(base({ hubTarget: open, lastError: err('deployment_suspended') }))).toMatchObject({
+      reason: 'closed', closedReason: 'deployment_suspended', canStartNew: false,
+    })
+    expect(hubThreadInputState(base({ hubTarget: open, lastError: err('hub_off_on_server') }))).toMatchObject({ closedReason: 'hub_off_on_server' })
+    // No closed_reason (or not a string): the code stands in, as before.
+    expect(hubThreadInputState(base({ hubTarget: open, lastError: err() }))).toMatchObject({ closedReason: 'conversation_closed' })
+    expect(hubThreadInputState(base({ hubTarget: open, lastError: err(7) }))).toMatchObject({ closedReason: 'conversation_closed' })
+  })
+
+  it('conversation_closed offers a new one only while listed', () => {
+    expect(hubThreadInputState(base({ hubTarget: hubTarget({ closed_reason: 'conversation_closed' }) }))).toMatchObject({ canStartNew: true })
+    expect(hubThreadInputState(base({ hubTarget: hubTarget({ closed_reason: 'conversation_closed' }), live: { ...live, listed: false } }))).toMatchObject({ canStartNew: false })
+  })
+})
+
+describe('closedBanner', () => {
+  const now = NOW_S * 1000
+  it('agent_unlisted adds the drain sentence for 10 minutes', () => {
+    expect(closedBanner('agent_unlisted', names, NOW_S - 60, now)).toBe(
+      'scout@acme.dev is no longer listed on the hub. This conversation is kept as history. Replies already on their way may still arrive for a few minutes.')
+    expect(closedBanner('agent_unlisted', names, NOW_S - 11 * 60, now)).toBe(
+      'scout@acme.dev is no longer listed on the hub. This conversation is kept as history.')
+  })
+  it('identity_changed names the old fingerprint', () => {
+    expect(closedBanner('identity_changed', names, null, now)).toContain('(was 3f9a1c2e)')
+  })
+  it('each reason, and an unknown one', () => {
+    expect(closedBanner('key_revoked', names, null, now)).toBe("This agent's hub key was revoked by its owner. This conversation is kept as history.")
+    expect(closedBanner('deployment_suspended', names, null, now)).toBe('The hub has suspended acme.dev. This conversation is kept as history.')
+    expect(closedBanner('conversation_closed', names, null, now)).toBe('scout@acme.dev closed this conversation. Start a new one to continue.')
+    expect(closedBanner('hub_off_on_server', names, null, now)).toBe('The hub is turned off on this server. This conversation is kept as history.')
+    expect(closedBanner('martian', names, null, now)).toBe('This conversation is closed.')
+  })
+})
+
+describe('offline confirms', () => {
+  it('two variants', () => {
+    expect(offlineConfirmText('agent_offline', names)).toBe(
+      "scout@acme.dev is offline. acme.dev will hold your message and the agent answers when it's back. Send anyway?")
+    expect(offlineConfirmText('deployment_offline', names)).toBe(
+      'acme.dev is offline. Your message waits on this server and is sent when acme.dev reconnects, for up to 72 hours. Send anyway?')
+  })
+})
+
+describe('payload checks', () => {
+  const c = hubConfig()
+  const MB = 1024 * 1024
+  it('passes within limits', () => {
+    expect(checkHubPayload('hi', [{ name: 'a.pdf', size: MB }], c)).toBeNull()
+  })
+  it('names an oversized file', () => {
+    expect(checkHubPayload('hi', [{ name: 'deck.pdf', size: 12.4 * MB }], c)).toMatchObject({ limit: 'file', fileName: 'deck.pdf' })
+    expect(checkHubPayload('hi', [{ name: 'deck.pdf', size: 12.4 * MB }], c)?.text).toContain('deck.pdf 12.4 MB — over the 10 MB limit for other servers')
+  })
+  it('too many files, too much total, text too long', () => {
+    expect(checkHubPayload('', Array.from({ length: 6 }, (_, i) => ({ name: `${i}`, size: 1 })), c)?.limit).toBe('files')
+    expect(checkHubPayload('', [1, 2, 3].map((i) => ({ name: `${i}`, size: 9 * MB })), c)?.limit).toBe('envelope')
+    expect(checkHubPayload('x'.repeat(33 * 1024), [], c)?.limit).toBe('text')
+  })
+  it('turns the 413 extras into a sentence and the file', () => {
+    expect(payloadTooLargeLine({ limit: 'file', max: 10 * MB, actual: 12 * MB, file_id: 'deck.pdf' })).toEqual({
+      text: 'A file is 12 MB — over the 10 MB limit for other servers.', fileId: 'deck.pdf' })
+    expect(payloadTooLargeLine({ limit: 'weird', max: 1, actual: 2 }).text).toBe('The message is too large for other servers.')
+  })
+})

manigent/web/frontend/src/utils/hubThread.ts

@@ -0,0 +1,247 @@
+import type {
+  EpochSeconds, HubConfig, HubErrorBody, HubTarget, PayloadTooLarge, SendWarning,
+} from '../api/endpoints/hub'
+import { closedReasonOf, lastConnectedOf } from '../api/endpoints/hub'
+import { formatHubDate, shortFingerprint } from './hubDisplay'
+
+/**
+ * The composer of a hub thread: one pure function decides whether the user can
+ * send, and what the banner says when they can't. Every state that must survive
+ * a reload is read from stored fields (config, hub_target); the last error is
+ * only a live fallback until the next refetch.
+ */
+
+/** Names for the copy, already passed through safeRemoteText. */
+export interface HubThreadNames {
+  /** name@deployment_name */
+  display: string
+  name: string
+  deploymentName: string
+  /** Genesis fingerprint of the remote server. */
+  fingerprint: string
+}
+
+/** What the thread knows of the remote agent right now (detail or start answer). */
+export interface HubTargetLive {
+  agent_online: boolean
+  deployment_connected: boolean
+  accepting_messages?: boolean
+  listed?: boolean
+  needs_approval?: boolean
+}
+
+export type HubBlockReason =
+  | 'hub_off' | 'not_registered' | 'suspended' | 'browse_only' | 'untrusted' | 'closed'
+  | 'unlisted' | 'unreachable' | 'rate_limited' | 'not_accepting'
+
+export type HubInputState =
+  | {
+      enabled: true
+      /** Sending needs the offline confirm first. */
+      confirm: SendWarning | null
+      /** "…'s owner approves new contacts first…", shown above the composer. */
+      notice: string | null
+    }
+  | {
+      enabled: false
+      reason: HubBlockReason
+      /** The banner sentence. */
+      text: string
+      /** The closed_reason when reason === 'closed' (stored or live). */
+      closedReason?: string
+      /** A conversation_closed thread whose agent is still listed. */
+      canStartNew?: boolean
+      /** Seconds left on a rate-limit wait. */
+      waitSeconds?: number
+    }
+
+/** Replies may still arrive this long after a close (the owner's drain). */
+export const DRAIN_WINDOW_S = 10 * 60
+
+/** Live close reasons a send error can carry before hub_target catches up. */
+const LIVE_CLOSE_CODES = new Set(['agent_unlisted', 'key_revoked', 'identity_changed', 'conversation_closed'])
+
+export const HUB_COPY = {
+  hubOff: 'The hub is turned off on this server.',
+  notRegistered: "This server isn't registered with the hub yet. Ask its operator.",
+  suspended: 'The hub has suspended this server. Ask its operator.',
+  browseOnly: "This server can browse the hub but can't send or receive hub messages right now.",
+  untrusted: "This server can't verify the hub's identity, so nothing is sent to it. Ask this server's operator.",
+  unreachable: (last: EpochSeconds | null) =>
+    "Can't reach the hub. Sending to other servers is paused." +
+    (last !== null ? ` Last connected ${formatHubDate(last)}.` : ''),
+  history: 'This conversation is kept as history.',
+  cantSend: "You can't send new messages",
+  drain: 'Replies already on their way may still arrive for a few minutes.',
+  unlisted: (n: HubThreadNames) => `${n.display} is no longer listed on the hub.`,
+  notAccepting: (n: HubThreadNames) => `${n.name} isn't taking new messages right now`,
+  rateLimited: (n: HubThreadNames, s: number) =>
+    `You're sending too fast to ${n.display}. You can send again in ${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}.`,
+  needsApproval: (n: HubThreadNames) =>
+    `${n.name}'s owner approves new contacts first. Your first message waits until they accept you.`,
+  agentOffline: (n: HubThreadNames) =>
+    `${n.display} is offline. ${n.deploymentName} will hold your message and the agent answers when it's back. Send anyway?`,
+  deploymentOffline: (n: HubThreadNames) =>
+    `${n.deploymentName} is offline. Your message waits on this server and is sent when ${n.deploymentName} reconnects, for up to 72 hours. Send anyway?`,
+} as const
+
+/** The banner for a closed conversation, by closed_reason. */
+export function closedBanner(reason: string, n: HubThreadNames, closedAt: EpochSeconds | null, nowMs: number): string {
+  switch (reason) {
+    case 'agent_unlisted': {
+      const draining = closedAt !== null && nowMs / 1000 - closedAt < DRAIN_WINDOW_S
+      return `${HUB_COPY.unlisted(n)} ${HUB_COPY.history}${draining ? ` ${HUB_COPY.drain}` : ''}`
+    }
+    case 'key_revoked':
+      return `This agent's hub key was revoked by its owner. ${HUB_COPY.history}`
+    case 'deployment_suspended':
+      return `The hub has suspended ${n.deploymentName}. ${HUB_COPY.history}`
+    case 'conversation_closed':
+      return `${n.display} closed this conversation. Start a new one to continue.`
+    case 'hub_off_on_server':
+      return `${HUB_COPY.hubOff} ${HUB_COPY.history}`
+    case 'identity_changed':
+      return `${n.deploymentName}'s identity changed. The server now using this name has a different key ` +
+        `(was ${shortFingerprint(n.fingerprint)}). Messages here won't go to it. ` +
+        'This can be a re-install, or someone else using the name.'
+    default:
+      return 'This conversation is closed.'
+  }
+}
+
+export interface HubThreadInput {
+  config: HubConfig
+  names: HubThreadNames
+  /** null for a new-chat draft (no thread yet). */
+  hubTarget: HubTarget | null
+  live?: HubTargetLive | null
+  lastError?: HubErrorBody | null
+  /** Epoch ms until which a rate-limit wait runs. */
+  rateLimitedUntil?: number | null
+  nowMs: number
+}
+
+const KNOWN_REGISTRATION_BLOCKS = new Set(['active', 'suspended'])
+
+/**
+ * Whether the config's link state alone means sending is paused. In mode
+ * 'auto' the server's hub socket is closed while idle and a send connects it
+ * first, so a closed or not-yet-connected link is not a reason to pause: only
+ * the server's own refusal (a hub_unreachable answer, a directory served from
+ * cache) or a state checked separately (off, suspended, untrusted) is. The
+ * explicit modes keep the socket open, so there a link that is down pauses.
+ */
+export function hubLinkPausesSending(config: Pick<HubConfig, 'mode' | 'hub_link' | 'deployment_connected'>): boolean {
+  if (config.mode === 'auto') return false
+  return config.hub_link === 'unreachable' || !config.deployment_connected
+}
+
+/** First match wins; see the Public tab plan's ordered list. */
+export function hubThreadInputState(i: HubThreadInput): HubInputState {
+  const { config, names: n, hubTarget: t, live, nowMs } = i
+  const code = i.lastError?.code ?? null
+  const off = (reason: HubBlockReason, text: string, extra: Partial<HubInputState> = {}): HubInputState =>
+    ({ enabled: false, reason, text, ...extra }) as HubInputState
+
+  if (config.mode === 'off') {
+    return off('hub_off', t ? `${HUB_COPY.hubOff} ${HUB_COPY.history}` : HUB_COPY.hubOff)
+  }
+  if (!KNOWN_REGISTRATION_BLOCKS.has(config.registration) || code === 'hub_not_registered') {
+    return off('not_registered', HUB_COPY.notRegistered)
+  }
+  if (config.registration === 'suspended') return off('suspended', HUB_COPY.suspended)
+  if (config.mode === 'discover_only' || code === 'hub_discover_only') return off('browse_only', HUB_COPY.browseOnly)
+  if (config.hub_link === 'untrusted' || code === 'hub_untrusted') return off('untrusted', HUB_COPY.untrusted)
+
+  const closed = t?.closed_reason
+    ?? (code !== null && LIVE_CLOSE_CODES.has(code) ? closedReasonOf(i.lastError ?? null) ?? code : null)
+  if (closed !== null) {
+    return off('closed', closedBanner(closed, n, t?.closed_at ?? null, nowMs), {
+      closedReason: closed,
+      canStartNew: closed === 'conversation_closed' && t?.listed !== false && live?.listed !== false,
+    })
+  }
+  if (t?.listed === false || live?.listed === false) return off('unlisted', HUB_COPY.unlisted(n))
+
+  if (hubLinkPausesSending(config) || code === 'hub_unreachable') {
+    const last = code === 'hub_unreachable' ? lastConnectedOf(i.lastError ?? null) ?? config.last_connected_at : config.last_connected_at
+    return off('unreachable', HUB_COPY.unreachable(last))
+  }
+  if (i.rateLimitedUntil && i.rateLimitedUntil > nowMs) {
+    const s = Math.ceil((i.rateLimitedUntil - nowMs) / 1000)
+    return off('rate_limited', HUB_COPY.rateLimited(n, s), { waitSeconds: s })
+  }
+  if (live?.accepting_messages === false) return off('not_accepting', HUB_COPY.notAccepting(n))
+
+  const notice = live?.needs_approval ? HUB_COPY.needsApproval(n) : null
+  if (live && !live.deployment_connected) return { enabled: true, confirm: 'deployment_offline', notice }
+  if (live && !live.agent_online) return { enabled: true, confirm: 'agent_offline', notice }
+  return { enabled: true, confirm: null, notice }
+}
+
+/** The confirm sentence for an offline warning. */
+export function offlineConfirmText(w: SendWarning, n: HubThreadNames): string {
+  return w === 'deployment_offline' ? HUB_COPY.deploymentOffline(n) : HUB_COPY.agentOffline(n)
+}
+
+// ── attachments ───────────────────────────────────────────────────────────
+
+/** "12.4 MB", "820 KB", "512 bytes". */
+export function formatBytes(n: number): string {
+  if (n >= 1024 * 1024) return `${Math.round((n / (1024 * 1024)) * 10) / 10} MB`
+  if (n >= 1024) return `${Math.round(n / 1024)} KB`
+  return `${n} bytes`
+}
+
+export interface PayloadProblem {
+  limit: 'file' | 'files' | 'envelope' | 'text'
+  text: string
+  /** The file to mark, when one file is the problem. */
+  fileName?: string
+}
+
+type Limits = Pick<HubConfig, 'max_file_bytes' | 'max_files' | 'max_envelope_bytes' | 'max_text_bytes'>
+
+export function limitsSentence(c: Limits): string {
+  return `Remove a file to send. Up to ${c.max_files} files, ${formatBytes(c.max_file_bytes)} each, ` +
+    `${formatBytes(c.max_envelope_bytes)} total.`
+}
+
+/** Checked before upload against the server's limits from /api/hub/config. */
+export function checkHubPayload(text: string, files: { name: string; size: number }[], c: Limits): PayloadProblem | null {
+  if (new TextEncoder().encode(text).length > c.max_text_bytes) {
+    return { limit: 'text', text: `The message is too long for other servers (up to ${formatBytes(c.max_text_bytes)}).` }
+  }
+  if (files.length > c.max_files) {
+    return { limit: 'files', text: `Too many files for other servers. ${limitsSentence(c)}` }
+  }
+  const big = files.find((f) => f.size > c.max_file_bytes)
+  if (big) {
+    return {
+      limit: 'file', fileName: big.name,
+      text: `${big.name} ${formatBytes(big.size)} — over the ${formatBytes(c.max_file_bytes)} limit for other servers. ${limitsSentence(c)}`,
+    }
+  }
+  const total = files.reduce((s, f) => s + f.size, 0)
+  if (total > c.max_envelope_bytes) {
+    return { limit: 'envelope', text: `The files add up to ${formatBytes(total)}. ${limitsSentence(c)}` }
+  }
+  return null
+}
+
+/** The server's 413 answer, as a sentence and the file it names. */
+export function payloadTooLargeLine(p: PayloadTooLarge): { text: string; fileId?: string } {
+  const fileId = p.file_id ?? undefined
+  switch (p.limit) {
+    case 'file':
+      return { text: `A file is ${formatBytes(p.actual)} — over the ${formatBytes(p.max)} limit for other servers.`, fileId }
+    case 'files':
+      return { text: `Too many files: ${p.actual}. Up to ${p.max} can go to other servers.`, fileId }
+    case 'envelope':
+      return { text: `The files add up to ${formatBytes(p.actual)} — over the ${formatBytes(p.max)} total for other servers.`, fileId }
+    case 'text':
+      return { text: `The message is too long for other servers (up to ${formatBytes(p.max)}).`, fileId }
+    default:
+      return { text: 'The message is too large for other servers.', fileId }
+  }
+}

manigent/web/frontend/src/utils/labelErrors.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'vitest'
+import { ApiError } from '../api/client'
+import { labelErrorCopy, labelErrorMessage, parseLabelError } from './labelErrors'
+import { toRegistry } from './labelView'
+
+const api = (status: number, detail: string) => new ApiError(status, detail, { detail })
+
+/** Every code in contract §9's table, plus the two fallbacks that matter more
+ *  than any of them. */
+const CODES = [
+  'labels.cap_exceeded',
+  'labels.invalid_slug',
+  'labels.slug_too_long',
+  'labels.name_too_long',
+  'labels.duplicate',
+  'labels.kind_conflict',
+  'labels.kind_mismatch',
+  'labels.kind_immutable',
+  'labels.registry_full',
+  'labels.unknown_color',
+  'labels.unknown_slug',
+  'labels.unknown_merge_target',
+  'labels.merge_self',
+  'labels.invalid_kind',
+  'labels.invalid_type',
+]
+
+describe('parseLabelError', () => {
+  it.each(CODES)('%s parses into code + sentence', (code) => {
+    const p = parseLabelError(api(400, `${code}: a human sentence`))
+    expect(p.code).toBe(code)
+    expect(p.sentence).toBe('a human sentence')
+    expect(p.status).toBe(400)
+  })
+
+  it('parses err.MESSAGE, not err.data — the client already lifted detail', () => {
+    // api/client.ts lifts `detail` into ApiError.message. Reaching into
+    // err.data works today and breaks on the first non-JSON body.
+    const e = new ApiError(400, 'labels.duplicate: label "office" already exists', 'raw text')
+    expect(parseLabelError(e).code).toBe('labels.duplicate')
+  })
+
+  it('an UNCODED error falls back to the whole detail string', () => {
+    // Every other error in this codebase is uncoded. A client that assumes a
+    // code breaks on the first 401 or any non-label 404.
+    const p = parseLabelError(api(401, 'Authentication required'))
+    expect(p.code).toBeNull()
+    expect(p.sentence).toBe('Authentication required')
+    expect(p.status).toBe(401)
+  })
+
+  it('a plain Error, a string and an unknown throw all yield a usable sentence', () => {
+    expect(parseLabelError(new Error('network down')).sentence).toBe('network down')
+    expect(parseLabelError('boom').sentence).toBe('boom')
+    expect(parseLabelError(undefined).sentence).toBeTruthy()
+    expect(parseLabelError(undefined).code).toBeNull()
+  })
+
+  it('does not throw on any of them', () => {
+    for (const v of [null, undefined, 0, {}, [], new Error('')]) {
+      expect(() => parseLabelError(v)).not.toThrow()
+    }
+  })
+
+  it('a near-miss prefix is NOT treated as a code', () => {
+    expect(parseLabelError(api(400, 'label.duplicate: nope')).code).toBeNull()
+    expect(parseLabelError(api(400, 'labels: nope')).code).toBeNull()
+  })
+})
+
+describe('labelErrorCopy', () => {
+  const reg = toRegistry([], 'ready')
+
+  it('kind_conflict is STILL MAPPED — it renders the server sentence now', () => {
+    // THIS ASSERTION TESTED COPY THAT NAMED AN AXIS THAT NO LONGER EXISTS. It
+    // read "kind_conflict copy is GENERATED and names the key to press", and
+    // the generated half was the point: the client held the other row's kind,
+    // so it could say "press ! instead" where the server could only describe
+    // the conflict. There is no other kind and no second key, so `wanted` and
+    // `otherKind` are gone from `LabelErrorContext` with the rewrite they fed.
+    //
+    // WHAT REPLACED IT is the thing that must NOT change: the CODE stays
+    // mapped. The server can still emit `labels.kind_conflict` for a registry
+    // row written before the retirement, and an unmapped code renders raw on
+    // screen. So the case survives and renders the server's own sentence, which
+    // is already written for the owner.
+    const detail = '"next" is a state, not a context'
+    const msg = labelErrorMessage(api(409, `labels.kind_conflict: ${detail}`), { slug: 'next' })
+    expect(msg).toBe(detail)
+    expect(msg).not.toContain('press !')
+  })
+
+  it('the other three kind codes stay mapped too, and render a real sentence', () => {
+    // Never "something went wrong": all four are reachable for a pre-existing
+    // row, and dropping one turns a legible refusal into a raw code.
+    for (const code of ['labels.invalid_kind', 'labels.kind_immutable', 'labels.kind_mismatch']) {
+      const msg = labelErrorMessage(api(409, `${code}: a sentence for the owner`))
+      expect(msg).not.toContain(code)
+      expect(msg.length).toBeGreaterThan(0)
+      expect(msg).not.toBe('Something went wrong. Try again.')
+    }
+  })
+
+  it('cap_exceeded keeps the server RESULT count verbatim', () => {
+    // "got 10" on an 8-label item plus two — the number the owner needs.
+    const msg = labelErrorMessage(api(400, 'labels.cap_exceeded: at most 8 labels per to-do (got 10)'))
+    expect(msg).toContain('got 10')
+  })
+
+  it('an UNRECOGNISED labels.* code still shows the server sentence', () => {
+    // The whole reason code and sentence are separate fields on the wire.
+    const msg = labelErrorMessage(api(400, 'labels.some_future_code: the future is unevenly distributed'))
+    expect(msg).toBe('the future is unevenly distributed')
+    expect(msg).not.toMatch(/something went wrong/i)
+  })
+
+  it('an uncoded 401 renders its own words, not a shrug', () => {
+    expect(labelErrorMessage(api(401, 'Authentication required'))).toBe('Authentication required')
+  })
+
+  it('takes a pre-parsed error too', () => {
+    expect(labelErrorCopy(parseLabelError(api(400, 'labels.merge_self: cannot merge')), {})).toContain(
+      'cannot be merged into itself',
+    )
+    expect(reg.labels).toEqual([])
+  })
+})