@prenta/admin 2.6.0 → 2.7.0

package/src/__tests__/lib/job-view.test.ts

@@ -0,0 +1,437 @@
+import { describe, expect, it } from 'vitest'
+import type { Job, JobWorkerStatus } from '@prenta/core'
+
+import {
+  countJobs,
+  formatCreated,
+  formatDuration,
+  formatNextRun,
+  formatSince,
+  hasReviewAction,
+  matchJob,
+  scheduleLabel,
+  toJobRows,
+  view,
+  type JobRow,
+} from '../../lib/job-view.js'
+
+function row(overrides: Partial<JobRow>): JobRow {
+  return {
+    id: 'job',
+    type: 'batch-ai',
+    title: 'Job',
+    scope: 'Scope',
+    state: 'queued',
+    status: overrides.state ?? 'queued',
+    cancelling: false,
+    done: 0,
+    total: 10,
+    attempts: 0,
+    maxAttempts: 3,
+    error: null,
+    retryIn: 0,
+    queuePos: 0,
+    cancelledBy: null,
+    pending: 0,
+    items: false,
+    review: null,
+    took: null,
+    by: 'Brandon West',
+    created: 'now',
+    ...overrides,
+  }
+}
+
+/** jobs-data.jsx `JOBS`, field for field where `view()` and the filters read them. */
+const KIT_JOBS: JobRow[] = [
+  row({
+    id: 'job_418',
+    title: 'Generate alt text',
+    done: 9,
+    total: 64,
+    attempts: 1,
+    error: 'ImageFetchError: img_2291.webp returned 404',
+    retryIn: 52,
+    review: 'review',
+    pending: 9,
+  }),
+  row({
+    id: 'job_417',
+    title: 'Rewrite meta descriptions',
+    state: 'running',
+    done: 18,
+    total: 42,
+    attempts: 1,
+    review: 'review',
+    pending: 6,
+    items: true,
+  }),
+  row({
+    id: 'job_416',
+    type: 'content-health',
+    state: 'succeeded',
+    done: 412,
+    total: 412,
+    attempts: 1,
+    took: '17 min',
+  }),
+  row({
+    id: 'job_415',
+    title: 'Translate excerpts to Spanish',
+    state: 'dead',
+    done: 7,
+    total: 30,
+    attempts: 3,
+    error: 'ProviderError: 429 Too Many Requests',
+    review: 'review',
+    pending: 7,
+  }),
+  row({
+    id: 'job_414',
+    type: 'seo-scan',
+    state: 'succeeded',
+    done: 340,
+    total: 340,
+    attempts: 1,
+    took: '1h 52m',
+  }),
+  row({
+    id: 'job_413',
+    state: 'succeeded',
+    done: 7,
+    total: 7,
+    attempts: 1,
+    review: 'review',
+    items: true,
+    took: '8 min',
+  }),
+  row({
+    id: 'job_412',
+    state: 'cancelled',
+    done: 12,
+    total: 30,
+    attempts: 1,
+    cancelledBy: 'Dana Cole',
+    review: 'review',
+  }),
+  row({
+    id: 'job_411',
+    type: 'content-health',
+    state: 'succeeded',
+    done: 409,
+    total: 409,
+    attempts: 2,
+    took: '21 min',
+  }),
+  row({
+    id: 'job_410',
+    type: 'content-health',
+    state: 'succeeded',
+    done: 405,
+    total: 405,
+    attempts: 1,
+    took: '16 min',
+  }),
+]
+
+describe('view() (jobs-data.jsx, copied)', () => {
+  it('maps the kit fixtures to the pills in the kit', () => {
+    expect(KIT_JOBS.map((j) => [j.id, view(j)])).toEqual([
+      ['job_418', { k: 'retry', l: 'Retrying', t: 'warn', sub: 'Attempt 2 of 3 · in 52s' }],
+      ['job_417', { k: 'running', l: 'Running', t: 'acc', sub: 'Slice 19 · working' }],
+      ['job_416', { k: 'ok', l: 'Succeeded', t: 'suc', sub: 'Took 17 min' }],
+      ['job_415', { k: 'dead', l: 'Failed', t: 'err', sub: 'After 3 attempts' }],
+      ['job_414', { k: 'ok', l: 'Succeeded', t: 'suc', sub: 'Took 1h 52m' }],
+      ['job_413', { k: 'ok', l: 'Succeeded', t: 'suc', sub: 'Took 8 min' }],
+      ['job_412', { k: 'cancelled', l: 'Cancelled', t: 'mute', sub: 'by Dana Cole' }],
+      ['job_411', { k: 'ok', l: 'Succeeded', t: 'suc', sub: 'Took 21 min' }],
+      ['job_410', { k: 'ok', l: 'Succeeded', t: 'suc', sub: 'Took 16 min' }],
+    ])
+  })
+
+  it('covers the states the fixtures leave out, in the kit’s order', () => {
+    // A cancel wins over running.
+    expect(view(row({ state: 'running', cancelling: true }))).toEqual({
+      k: 'cancelling',
+      l: 'Cancelling',
+      t: 'warn',
+      sub: 'Stops after this slice',
+    })
+    expect(view(row({ type: 'seo-scan', state: 'running', done: 40 })).sub).toBe(
+      'Slice 41 · auditing',
+    )
+    expect(view(row({ done: 3 }))).toEqual({
+      k: 'between',
+      l: 'In progress',
+      t: 'acc',
+      sub: 'Waiting for the next slice',
+    })
+    // Retrying wins over "In progress" when a yielded job then failed.
+    expect(view(row({ done: 3, error: 'boom', attempts: 1, retryIn: 30 })).k).toBe('retry')
+    expect(view(row({}))).toEqual({
+      k: 'queued',
+      l: 'Queued',
+      t: 'mute',
+      sub: 'Waiting for the worker',
+    })
+    expect(view(row({ queuePos: 1 })).sub).toBe('Behind 1 job')
+    expect(view(row({ queuePos: 3 })).sub).toBe('Behind 3 jobs')
+    expect(view(row({ state: 'succeeded', pending: 1 }))).toEqual({
+      k: 'review',
+      l: 'Needs review',
+      t: 'rev',
+      sub: '1 change waiting',
+    })
+    expect(view(row({ state: 'succeeded', pending: 4 })).sub).toBe('4 changes waiting')
+    // Pending changes on a scan type never read as review.
+    expect(view(row({ type: 'seo-scan', state: 'succeeded', pending: 4 })).k).toBe('ok')
+    expect(view(row({ state: 'succeeded' })).sub).toBe('')
+    expect(view(row({ state: 'cancelled' })).sub).toBe('')
+  })
+})
+
+describe('filters and counts (jobs-view.jsx)', () => {
+  it('counts the kit fixtures as jobs-list.jpg shows them', () => {
+    expect(countJobs(KIT_JOBS)).toEqual({
+      all: 9,
+      active: 2,
+      review: 3,
+      ok: 5,
+      dead: 1,
+      cancelled: 1,
+    })
+  })
+
+  it('filters by state, with Needs review taking unfinished and failed batches', () => {
+    const ids = (f: Parameters<typeof matchJob>[1]) =>
+      KIT_JOBS.filter((j) => matchJob(j, f)).map((j) => j.id)
+    expect(ids('active')).toEqual(['job_418', 'job_417'])
+    expect(ids('review')).toEqual(['job_418', 'job_417', 'job_415'])
+    expect(ids('dead')).toEqual(['job_415'])
+    expect(ids('cancelled')).toEqual(['job_412'])
+    expect(ids('ok')).toEqual(['job_416', 'job_414', 'job_413', 'job_411', 'job_410'])
+    // A cancelled batch with changes left is not in Needs review.
+    expect(matchJob(row({ state: 'cancelled', pending: 2 }), 'review')).toBe(false)
+  })
+
+  it('counts within the type the select picks', () => {
+    expect(countJobs(KIT_JOBS.filter((j) => j.type === 'content-health'))).toEqual({
+      all: 3,
+      active: 0,
+      review: 0,
+      ok: 3,
+      dead: 0,
+      cancelled: 0,
+    })
+  })
+
+  it('shows Review on a row with pending changes it has items for', () => {
+    expect(KIT_JOBS.filter(hasReviewAction).map((j) => j.id)).toEqual(['job_417'])
+    expect(hasReviewAction(row({ state: 'succeeded', pending: 2 }))).toBe(true)
+  })
+})
+
+// Local times, so the expectations hold in any time zone.
+const NOW = new Date(2026, 9, 19, 14, 0, 0).getTime()
+const at = (ms: number) => new Date(NOW + ms).toISOString()
+const MIN = 60_000
+
+function apiJob(overrides: Partial<Job>): Job {
+  return {
+    id: 'j1',
+    type: 'batch-ai',
+    status: 'queued',
+    title: 'Rewrite meta descriptions',
+    scope: '42 posts',
+    runAt: at(0),
+    attempts: 0,
+    maxAttempts: 3,
+    progress: { done: 0, total: 42, unit: 'documents', cursor: null, completed: 0 },
+    lastError: null,
+    explain: null,
+    summary: null,
+    lockedAt: null,
+    cancelRequestedAt: null,
+    cancelledBy: null,
+    createdBy: { id: 'u1', name: 'Brandon West', initials: 'BW' },
+    createdAt: at(-19 * MIN),
+    updatedAt: at(0),
+    finishedAt: null,
+    usage: { tokensIn: 0, tokensOut: 0 },
+    payload: {
+      operation: 'meta',
+      instruction: null,
+      source: 'posts',
+      statusFilter: 'all',
+      documentIds: [],
+      review: 'review',
+      onApprove: 'draft',
+    },
+    review: { pending: 0, approved: 0, rejected: 0 },
+    ...overrides,
+  }
+}
+
+function worker(nextTickInMs: number | null): JobWorkerStatus {
+  return {
+    lastTickAt: nextTickInMs === null ? null : at(nextTickInMs - MIN),
+    lastTickMs: 1200,
+    nextTickAt: nextTickInMs === null ? null : at(nextTickInMs),
+    budgetMs: 20_000,
+    schedules: [],
+  }
+}
+
+describe('toJobRows()', () => {
+  it('times a retry to the first worker tick after its backoff', () => {
+    const job = apiJob({ attempts: 1, lastError: 'boom', runAt: at(40_000) })
+    expect(toJobRows([job], NOW, worker(25_000))[0]?.retryIn).toBe(85)
+    expect(toJobRows([job], NOW, worker(50_000))[0]?.retryIn).toBe(50)
+    // No tick ahead (never ran, or late): the backoff alone.
+    expect(toJobRows([job], NOW, null)[0]?.retryIn).toBe(40)
+    expect(toJobRows([job], NOW, worker(-5_000))[0]?.retryIn).toBe(40)
+    // A backoff that has passed while the worker is late never goes negative.
+    expect(toJobRows([apiJob({ lastError: 'x', runAt: at(-9_000) })], NOW, null)[0]?.retryIn).toBe(
+      0,
+    )
+  })
+
+  it('reads a running job with a lock older than 10 minutes as retrying', () => {
+    const [stale] = toJobRows(
+      [apiJob({ status: 'running', attempts: 1, lockedAt: at(-11 * MIN) })],
+      NOW,
+      worker(25_000),
+    )
+    expect(stale && view(stale)).toEqual({
+      k: 'retry',
+      l: 'Retrying',
+      t: 'warn',
+      sub: 'Attempt 2 of 3 · in 25s',
+    })
+    // The stored status stays running: the server only flags a running job's cancel.
+    expect(stale).toMatchObject({ state: 'queued', status: 'running' })
+    const [fresh] = toJobRows([apiJob({ status: 'running', lockedAt: at(-9 * MIN) })], NOW, null)
+    expect(fresh && view(fresh).k).toBe('running')
+    expect(fresh).toMatchObject({ state: 'running', status: 'running' })
+  })
+
+  it('counts the active jobs the worker claims first', () => {
+    const rows = toJobRows(
+      [
+        apiJob({ id: 'c', runAt: at(0), createdAt: at(-1 * MIN) }),
+        apiJob({ id: 'b', runAt: at(-10_000), createdAt: at(-2 * MIN) }),
+        apiJob({ id: 'a', status: 'running', createdAt: at(-30 * MIN) }),
+        apiJob({ id: 'done', status: 'succeeded', createdAt: at(-40 * MIN) }),
+      ],
+      NOW,
+      null,
+    )
+    expect(rows.map((r) => [r.id, r.queuePos])).toEqual([
+      ['c', 2],
+      ['b', 1],
+      ['a', 0],
+      ['done', 0],
+    ])
+  })
+
+  it('maps cancels, reviews, people and times onto the kit fields', () => {
+    const [cancelling, finished, cron, nightly, review] = toJobRows(
+      [
+        apiJob({
+          status: 'running',
+          cancelRequestedAt: at(-5_000),
+          progress: { done: 18, total: 42, unit: 'documents', cursor: '18', completed: 18 },
+        }),
+        apiJob({
+          type: 'seo-scan',
+          status: 'succeeded',
+          createdAt: at(-2 * 60 * MIN),
+          finishedAt: at(-8 * MIN),
+          createdBy: { kind: 'cron', schedule: 'weekly-seo' },
+          payload: { trigger: 'cron' },
+          review: undefined,
+        }),
+        apiJob({
+          type: 'seo-scan',
+          status: 'cancelled',
+          cancelledBy: { id: 'u2', name: 'Dana Cole', initials: 'DC' },
+          createdBy: { id: 'u2', name: 'Dana Cole', initials: 'DC' },
+          payload: { trigger: 'manual' },
+          review: undefined,
+        }),
+        apiJob({
+          type: 'content-health',
+          status: 'succeeded',
+          createdBy: { kind: 'cron', schedule: 'nightly-health' },
+          createdAt: at(-26 * 60 * MIN),
+          payload: { trigger: 'cron' },
+          review: undefined,
+        }),
+        apiJob({ status: 'succeeded', review: { pending: 2, approved: 1, rejected: 0 } }),
+      ],
+      NOW,
+      null,
+    )
+    expect(cancelling).toMatchObject({
+      cancelling: true,
+      done: 18,
+      review: 'review',
+      by: 'Brandon West',
+      created: '19 min ago',
+    })
+    expect(finished).toMatchObject({
+      took: '1h 52m',
+      by: 'Weekly cron',
+      items: false,
+      review: null,
+      created: 'Today 12:00',
+    })
+    expect(cron).toMatchObject({ cancelledBy: 'Dana Cole', by: 'Dana Cole' })
+    expect(nightly).toMatchObject({ by: 'Nightly cron', created: 'Yesterday 12:00' })
+    expect(review).toMatchObject({ pending: 2, items: true })
+    expect(review && view(review).l).toBe('Needs review')
+  })
+})
+
+describe('formatting', () => {
+  it('formats when a job was queued like the kit', () => {
+    expect(formatCreated(at(-20_000), NOW)).toBe('now')
+    expect(formatCreated(at(30_000), NOW)).toBe('now')
+    expect(formatCreated(at(-34 * MIN), NOW)).toBe('34 min ago')
+    expect(formatCreated(new Date(2026, 9, 19, 2, 30).toISOString(), NOW)).toBe('Today 02:30')
+    expect(formatCreated(new Date(2026, 9, 18, 16, 4).toISOString(), NOW)).toBe('Yesterday 16:04')
+    expect(formatCreated(new Date(2026, 9, 14, 11, 20).toISOString(), NOW)).toBe('Wed 11:20')
+    expect(formatCreated(new Date(2026, 9, 2, 9, 0).toISOString(), NOW)).toBe('2 Oct')
+    expect(formatCreated(new Date(2025, 11, 30, 9, 0).toISOString(), NOW)).toBe('30 Dec 2025')
+  })
+
+  it('formats run times and the worker’s last run', () => {
+    expect(formatDuration(12_400)).toBe('12s')
+    expect(formatDuration(17 * MIN)).toBe('17 min')
+    expect(formatDuration(112 * MIN)).toBe('1h 52m')
+    expect(formatSince(24_900)).toBe('24s')
+    expect(formatSince(3 * MIN + 5_000)).toBe('3 min')
+    expect(formatSince(5 * 60 * MIN)).toBe('5h')
+    expect(formatSince(72 * 60 * MIN)).toBe('3 days')
+  })
+
+  it('labels the scan schedules from their cron', () => {
+    expect(scheduleLabel('0 4 * * 1')).toBe('Mon 04:00 UTC')
+    expect(scheduleLabel('30 2 * * *')).toBe('Daily 02:30 UTC')
+    expect(scheduleLabel('*/5 * * * *')).toBe('*/5 * * * *')
+    expect(scheduleLabel('0 4 1 * *')).toBe('0 4 1 * *')
+  })
+
+  it('says when a scan runs next, in UTC like its schedule', () => {
+    const utcNow = Date.UTC(2026, 9, 19, 14, 0)
+    const utc = (day: number, hour: number, minute = 0) =>
+      new Date(Date.UTC(2026, 9, day, hour, minute)).toISOString()
+    expect(formatNextRun(utc(19, 22, 30), utcNow)).toBe('next tonight')
+    expect(formatNextRun(utc(20, 2, 30), utcNow)).toBe('next tonight')
+    expect(formatNextRun(utc(19, 16), utcNow)).toBe('next today')
+    expect(formatNextRun(utc(20, 9), utcNow)).toBe('next tomorrow')
+    // "Mon 04:00 UTC" is a Monday even where it's still Sunday evening locally.
+    expect(formatNextRun(utc(26, 4), utcNow)).toBe('next Mon 26 Oct')
+    expect(formatNextRun(utc(26, 0, 30), utcNow)).toBe('next Mon 26 Oct')
+  })
+})

package/src/__tests__/lib/jobs-service.test.ts

@@ -0,0 +1,98 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+/*
+ * The drawer's calls in the Jobs service: the review page query, the
+ * decision envelope's `documentStatus` and `notice`, and reading why a
+ * decision was refused.
+ */
+
+const cmsApi = vi.hoisted(() => vi.fn())
+vi.mock('../../lib/api.js', () => ({ cmsApi, getApiBase: () => '/api/cms' }))
+
+const { decideReviewItem, listReviewItems, reviewConflict } =
+  await import('../../lib/jobs-service.js')
+
+beforeEach(() => cmsApi.mockReset())
+
+describe('listReviewItems', () => {
+  it('asks for 20 at a time, from a cursor', async () => {
+    cmsApi.mockResolvedValue({ data: { items: [], nextCursor: null }, status: 200 })
+    await listReviewItems('job 1')
+    await listReviewItems('job 1', { cursor: 'r20' })
+    await listReviewItems('job 1', { limit: 40 })
+    expect(cmsApi.mock.calls.map(([endpoint]) => endpoint)).toEqual([
+      '/jobs/job%201/review?limit=20',
+      '/jobs/job%201/review?limit=20&cursor=r20',
+      '/jobs/job%201/review?limit=40',
+    ])
+  })
+
+  it('passes a 403 on', async () => {
+    cmsApi.mockResolvedValue({ error: 'Only people who can edit content…', status: 403 })
+    expect(await listReviewItems('job')).toEqual({
+      ok: false,
+      error: 'Only people who can edit content…',
+      status: 403,
+    })
+  })
+})
+
+describe('decideReviewItem', () => {
+  it('reads documentStatus and notice beside data', async () => {
+    const item = { id: 'r1', status: 'pending' }
+    cmsApi.mockResolvedValue({
+      data: item,
+      body: { data: item, documentStatus: 'PUBLISHED', notice: 'The document stays published.' },
+      status: 200,
+    })
+    const res = await decideReviewItem('job', 'r1', { action: 'undo' })
+    expect(res).toEqual({
+      ok: true,
+      value: { item, documentStatus: 'PUBLISHED', notice: 'The document stays published.' },
+    })
+    expect(cmsApi).toHaveBeenCalledWith('/jobs/job/review/r1', {
+      method: 'POST',
+      body: '{"action":"undo"}',
+    })
+  })
+
+  it('has no status for an image and no notice by default', async () => {
+    cmsApi.mockResolvedValue({
+      data: { id: 'r1' },
+      body: { data: { id: 'r1' }, documentStatus: null },
+      status: 200,
+    })
+    const res = await decideReviewItem('job', 'r1', { action: 'approve', onApprove: 'publish' })
+    expect(res.ok && res.value).toMatchObject({ documentStatus: null, notice: null })
+  })
+})
+
+describe('reviewConflict', () => {
+  // The messages cms-core's jobs/review.ts sends with a 409.
+  it.each([
+    [
+      'This document is published, so the change stays in review. Approve it with Publish to apply it live.',
+      'published',
+    ],
+    [
+      'The document changed while this was being saved, so nothing was written. Try again.',
+      'changed',
+    ],
+    ["The page this links to, /about, isn't published at that address any more.", 'link-gone'],
+    ['The page this links to, /about, isn’t published at that address any more.', 'link-gone'],
+    ['This change was already decided.', 'decided'],
+    ['This change no longer exists.', 'gone'],
+    ["The document no longer exists, so the change can't be applied.", 'gone'],
+    ['This document already links to /about.', null],
+    [
+      'The field changed after this was approved. Restore it from the document history instead.',
+      null,
+    ],
+  ])('reads %j as %s', (message, kind) => {
+    expect(reviewConflict(409, message)).toBe(kind)
+  })
+
+  it('reads only 409s', () => {
+    expect(reviewConflict(400, 'This change was already decided.')).toBeNull()
+  })
+})

package/src/__tests__/router/admin-route-order.test.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * AdminRoot matches routes top to bottom and returns on the first hit, so a
+ * literal route listed after a param route of the same shape never renders:
+ * `/pages/trash` behind `/pages/:id` opened the page editor with id "trash".
+ */
+const source = readFileSync(fileURLToPath(new URL('../../AdminRoot.tsx', import.meta.url)), 'utf8')
+
+/** Every `matchRoute('…')` pattern in source order (template-literal routes skipped). */
+const patterns = [...source.matchAll(/matchRoute\(\s*'([^']+)'\s*\)/g)].map((m) => m[1]!)
+
+function shadows(param: string, literal: string): boolean {
+  const a = param.split('/').filter(Boolean)
+  const b = literal.split('/').filter(Boolean)
+  return a.length === b.length && a.every((part, i) => part.startsWith(':') || part === b[i])
+}
+
+describe('AdminRoot route order', () => {
+  it('finds the routes it checks', () => {
+    expect(patterns).toContain('/pages/trash')
+    expect(patterns).toContain('/pages/:id')
+  })
+
+  it('lists every literal route before any param route that would swallow it', () => {
+    const problems: string[] = []
+    patterns.forEach((literal, i) => {
+      if (literal.includes(':')) return
+      for (const earlier of patterns.slice(0, i)) {
+        if (earlier.includes(':') && shadows(earlier, literal)) {
+          problems.push(`${literal} is unreachable behind ${earlier}`)
+        }
+      }
+    })
+    expect(problems).toEqual([])
+  })
+})