@prenta/admin 2.6.1 → 2.8.0

package/src/lib/job-view.ts

@@ -0,0 +1,550 @@
+import type { Job, JobStatus, JobWorkerStatus } from '@prenta/core'
+
+/*
+ * The Jobs screen's state mapping, ported from the kit's jobs-data.jsx
+ * (`TYPES`, `view`, `active`) and jobs-view.jsx (`FILTERS`, `match`). The kit
+ * works on its own fixture rows, so `toJobRows` maps API jobs onto that shape
+ * first and `view()` stays the kit's function.
+ */
+
+export type JobTone = 'acc' | 'suc' | 'err' | 'warn' | 'mute' | 'rev'
+
+export interface JobTypeInfo {
+  label: string
+  unit: 'pages' | 'documents'
+  /** "Started by" for a cron run, and the cancel copy ("The next weekly cron run…"). */
+  who: string
+  /** Fallback schedule label when the worker status has none. */
+  when: string
+  /** What one slice does (the drawer's Slice fact and running sentence). Empty when unknown. */
+  slice: string
+  /**
+   * Pages or documents one slice takes: the handlers' `AUDIT_QUEUE_SLICE`,
+   * `CONTENT_HEALTH_SLICE` and one batch item. 0 when unknown.
+   */
+  perSlice: number
+}
+
+/** jobs-data.jsx `TYPES`. */
+export const JOB_TYPES = {
+  'seo-scan': {
+    label: 'SEO scan',
+    unit: 'pages',
+    who: 'Weekly cron',
+    when: 'Mon 04:00 UTC',
+    slice: 'Audits the next batch of pages. Sends the SEO digest when the run finishes.',
+    perSlice: 100,
+  },
+  'content-health': {
+    label: 'Content health',
+    unit: 'documents',
+    who: 'Nightly cron',
+    when: 'Daily 02:30 UTC',
+    slice: 'Scans 25 documents, then resolves issues that are gone.',
+    perSlice: 25,
+  },
+  'batch-ai': {
+    label: 'Batch AI',
+    unit: 'documents',
+    who: 'Started by an editor',
+    when: 'On demand',
+    slice: 'Applies the operation to one document.',
+    perSlice: 1,
+  },
+} as const satisfies Record<string, JobTypeInfo>
+
+type KnownJobType = keyof typeof JOB_TYPES
+
+function isKnownJobType(type: string): type is KnownJobType {
+  return Object.hasOwn(JOB_TYPES, type)
+}
+
+/** A type the kit doesn't know still gets a row (CONFLICTS.md §4: generic tile). */
+export function jobType(type: string): JobTypeInfo {
+  return isKnownJobType(type)
+    ? JOB_TYPES[type]
+    : { label: type, unit: 'documents', who: 'System', when: '', slice: '', perSlice: 0 }
+}
+
+/** jobs-data.jsx `OPS`: the batch AI operations, with the wizard's copy. */
+export const JOB_OPS = [
+  {
+    id: 'meta',
+    label: 'Rewrite meta descriptions',
+    d: 'Writes a description under 155 characters from the page content.',
+    field: 'Meta description',
+    filter: 'Missing or over 160 characters',
+  },
+  {
+    id: 'alt',
+    label: 'Generate image alt text',
+    d: 'Describes each image for screen readers and search.',
+    field: 'Alt text',
+    filter: 'No alt text',
+  },
+  {
+    id: 'titles',
+    label: 'Shorten long titles',
+    d: 'Keeps the meaning, trims SEO titles to 60 characters.',
+    field: 'SEO title',
+    filter: 'Over 60 characters',
+  },
+  {
+    id: 'excerpt',
+    label: 'Write excerpts',
+    d: 'A two-sentence summary for cards and feeds.',
+    field: 'Excerpt',
+    filter: 'No excerpt',
+  },
+  {
+    id: 'links',
+    label: 'Add internal links',
+    d: 'Suggests up to 3 links to related pages in the body.',
+    field: 'Body links',
+    filter: 'Fewer than 2 internal links',
+  },
+  {
+    id: 'custom',
+    label: 'Custom instruction',
+    d: 'Describe the change in your own words.',
+    field: 'Field you choose',
+    filter: 'Any',
+  },
+] as const
+
+/** A job in the shape the kit's `view()` reads (the fixture rows in jobs-data.jsx). */
+export interface JobRow {
+  id: string
+  type: string
+  title: string
+  scope: string
+  /** The state the screen shows. A running job with a stale lock reads as queued (retrying). */
+  state: JobStatus
+  /** The stored status, which a stale lock leaves at running. */
+  status: JobStatus
+  /** A cancel is waiting for the current slice to finish. */
+  cancelling: boolean
+  done: number
+  total: number
+  attempts: number
+  maxAttempts: number
+  /** One-line last error. On a queued job it means the job is retrying. */
+  error: string | null
+  /** Seconds until a retrying job runs again. */
+  retryIn: number
+  /** Active jobs the worker takes before this queued one. */
+  queuePos: number
+  cancelledBy: string | null
+  /** Batch AI: changes waiting for review. */
+  pending: number
+  /** Batch AI: the job has review items (the kit's loaded `items`). */
+  items: boolean
+  /** Batch AI approval mode, for the cancel copy. Null for scans. */
+  review: 'review' | 'auto' | null
+  /**
+   * Batch AI: only an admin may retry it, because "Apply automatically" was
+   * chosen when it was queued. A job from `/ai/batch` (a list's bulk actions)
+   * also applies directly, but stores no review mode, so it isn't admin-only.
+   */
+  adminRetry: boolean
+  /** Run time of a finished job, e.g. "17 min". */
+  took: string | null
+  /** Who queued it: a person, or the cron. */
+  by: string
+  /** The id of the person who queued it; null for a cron run. */
+  byId: string | null
+  /** When it was queued, e.g. "34 min ago" or "Yesterday 16:04". */
+  created: string
+}
+
+export interface JobStateView {
+  k:
+    | 'cancelling'
+    | 'running'
+    | 'retry'
+    | 'between'
+    | 'queued'
+    | 'dead'
+    | 'cancelled'
+    | 'review'
+    | 'ok'
+  /** Pill label. */
+  l: string
+  /** Pill and progress tone. */
+  t: JobTone
+  /** The line under the pill. */
+  sub: string
+}
+
+/**
+ * jobs-data.jsx `view()`, copied. Two edits: attempts read the job's
+ * `maxAttempts` (always 3 today) instead of a literal 3, and a cancel with no
+ * known canceller leaves the sub-line empty instead of "by undefined".
+ */
+export function view(j: JobRow): JobStateView {
+  if (j.cancelling)
+    return { k: 'cancelling', l: 'Cancelling', t: 'warn', sub: 'Stops after this slice' }
+  if (j.state === 'running')
+    return {
+      k: 'running',
+      l: 'Running',
+      t: 'acc',
+      sub: `Slice ${(j.done || 0) + 1} · ${jobType(j.type).unit === 'pages' ? 'auditing' : 'working'}`,
+    }
+  if (j.state === 'queued' && j.error)
+    return {
+      k: 'retry',
+      l: 'Retrying',
+      t: 'warn',
+      sub: `Attempt ${j.attempts + 1} of ${j.maxAttempts} · in ${j.retryIn}s`,
+    }
+  if (j.state === 'queued' && j.done > 0)
+    return { k: 'between', l: 'In progress', t: 'acc', sub: 'Waiting for the next slice' }
+  if (j.state === 'queued')
+    return {
+      k: 'queued',
+      l: 'Queued',
+      t: 'mute',
+      sub: j.queuePos
+        ? `Behind ${j.queuePos} job${j.queuePos > 1 ? 's' : ''}`
+        : 'Waiting for the worker',
+    }
+  if (j.state === 'dead')
+    return { k: 'dead', l: 'Failed', t: 'err', sub: `After ${j.maxAttempts} attempts` }
+  if (j.state === 'cancelled')
+    return {
+      k: 'cancelled',
+      l: 'Cancelled',
+      t: 'mute',
+      sub: j.cancelledBy ? `by ${j.cancelledBy}` : '',
+    }
+  if (j.type === 'batch-ai' && j.pending > 0)
+    return {
+      k: 'review',
+      l: 'Needs review',
+      t: 'rev',
+      sub: `${j.pending} change${j.pending > 1 ? 's' : ''} waiting`,
+    }
+  return { k: 'ok', l: 'Succeeded', t: 'suc', sub: j.took ? `Took ${j.took}` : '' }
+}
+
+/** jobs-data.jsx `active()`: the worker still has work to do on it. */
+export function active(j: Pick<JobRow, 'state'>): boolean {
+  return j.state === 'queued' || j.state === 'running'
+}
+
+/** jobs-view.jsx `FILTERS`. */
+export const JOB_FILTERS = [
+  { id: 'all', label: 'All' },
+  { id: 'active', label: 'Active' },
+  { id: 'review', label: 'Needs review' },
+  { id: 'ok', label: 'Succeeded' },
+  { id: 'dead', label: 'Failed' },
+  { id: 'cancelled', label: 'Cancelled' },
+] as const
+
+export type JobFilter = (typeof JOB_FILTERS)[number]['id']
+
+/** jobs-view.jsx `match()`. */
+export function matchJob(j: JobRow, f: JobFilter): boolean {
+  const v = view(j)
+  if (f === 'all') return true
+  if (f === 'active') return active(j)
+  if (f === 'review')
+    return v.k === 'review' || (j.type === 'batch-ai' && j.pending > 0 && j.state !== 'cancelled')
+  if (f === 'ok') return j.state === 'succeeded'
+  if (f === 'dead') return j.state === 'dead'
+  return j.state === 'cancelled'
+}
+
+/** Counts per filter, over the rows the type select leaves (jobs-view.jsx `counts`). */
+export function countJobs(rows: JobRow[]): Record<JobFilter, number> {
+  const counts = {} as Record<JobFilter, number>
+  for (const { id } of JOB_FILTERS) counts[id] = rows.filter((row) => matchJob(row, id)).length
+  return counts
+}
+
+/** Whether the row shows a Review button (jobs-view.jsx row actions). */
+export function hasReviewAction(j: JobRow): boolean {
+  return view(j).k === 'review' || (j.items && j.pending > 0)
+}
+
+/** "document 8" or "page 101": where a retry picks up (jobs-drawer.jsx footer, jobs-view.jsx toast). */
+export function retryPoint(j: Pick<JobRow, 'type' | 'done'>): string {
+  return `${jobType(j.type).unit === 'pages' ? 'page' : 'document'} ${j.done + 1}`
+}
+
+/** Who is looking at the Jobs screen, from the admin session. */
+export interface JobViewer {
+  role: string | null
+  userId: string | null
+}
+
+/** Roles that may run, cancel and retry jobs: cms-core `WRITE_ROLES` (`requireStaffAccess`). */
+const JOB_WRITE_ROLES: ReadonlySet<string> = new Set(['OWNER', 'ADMIN', 'EDITOR', 'AUTHOR'])
+/** cms-core `ADMIN_ROLES`: may retry any batch. */
+const JOB_ADMIN_ROLES: ReadonlySet<string> = new Set(['OWNER', 'ADMIN'])
+
+function roleOf(viewer: JobViewer): string {
+  return (viewer.role ?? '').toUpperCase()
+}
+
+/** Run now and Cancel. An unknown role fails closed; the server checks every request anyway. */
+export function canActOnJobs(viewer: JobViewer): boolean {
+  return JOB_WRITE_ROLES.has(roleOf(viewer))
+}
+
+/**
+ * Retry, as cms-core's retry route allows it: a write role, and for a batch
+ * (`batchRetryDenial`) an admin, or the person who queued it when it doesn't
+ * apply changes directly. The server also wants their role unchanged since
+ * they queued it, which the list doesn't carry; it refuses that with a 403.
+ */
+export function canRetryJob(
+  j: Pick<JobRow, 'type' | 'adminRetry' | 'byId'>,
+  viewer: JobViewer,
+): boolean {
+  if (!canActOnJobs(viewer)) return false
+  if (j.type !== 'batch-ai' || JOB_ADMIN_ROLES.has(roleOf(viewer))) return true
+  return !j.adminRetry && j.byId !== null && j.byId === viewer.userId
+}
+
+/** The job actions a row or the drawer footer (jobs-drawer.jsx `.jd-f`) offers this viewer. */
+export interface JobActions {
+  /** Cancel job: while it's queued or running, until a cancel is asked for. */
+  cancel: boolean
+  /** "Retry from document {n+1}": a failed job. */
+  retry: boolean
+  /**
+   * "Retry now": a job waiting out a failed slice's backoff. Not on a stale
+   * lock, which the server still holds as running (the next worker run picks
+   * it up), and not while cancelling: a retry clears the cancel.
+   */
+  retryNow: boolean
+}
+
+export function jobActions(j: JobRow, viewer: JobViewer): JobActions {
+  const retryable = canRetryJob(j, viewer)
+  return {
+    cancel: canActOnJobs(viewer) && active(j) && !j.cancelling,
+    retry: retryable && j.state === 'dead',
+    retryNow:
+      retryable && j.state === 'queued' && j.status === 'queued' && !!j.error && !j.cancelling,
+  }
+}
+
+/** A running job whose lock is older than this crashed mid-slice (JOBS.md). */
+const STALE_LOCK_MS = 10 * 60_000
+/** The worker cron runs once a minute. */
+const TICK_MS = 60_000
+
+const WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] as const
+const MONTHS = [
+  'Jan',
+  'Feb',
+  'Mar',
+  'Apr',
+  'May',
+  'Jun',
+  'Jul',
+  'Aug',
+  'Sep',
+  'Oct',
+  'Nov',
+  'Dec',
+] as const
+
+function pad(value: number): string {
+  return String(value).padStart(2, '0')
+}
+
+function clock(date: Date): string {
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}`
+}
+
+/** Calendar days from `from` to `to`, in local time. */
+function dayDiff(to: Date, from: Date): number {
+  const start = (date: Date) => new Date(date.getFullYear(), date.getMonth(), date.getDate())
+  return Math.round((start(to).getTime() - start(from).getTime()) / 86_400_000)
+}
+
+/** "now", "34 min ago", "Today 02:30", "Yesterday 16:04", "Mon 04:00", then "12 Oct". */
+export function formatCreated(iso: string, now: number): string {
+  const at = new Date(iso)
+  const ms = now - at.getTime()
+  if (ms < 60_000) return 'now'
+  if (ms < 3_600_000) return `${Math.floor(ms / 60_000)} min ago`
+  const days = dayDiff(new Date(now), at)
+  if (days === 0) return `Today ${clock(at)}`
+  if (days === 1) return `Yesterday ${clock(at)}`
+  if (days < 7) return `${WEEKDAYS[at.getDay()]} ${clock(at)}`
+  const year = at.getFullYear() === new Date(now).getFullYear() ? '' : ` ${at.getFullYear()}`
+  return `${at.getDate()} ${MONTHS[at.getMonth()]}${year}`
+}
+
+/** "today 14:00", "tomorrow 00:00", then "Sun 1 Nov 00:00": a time still to come, in local time. */
+export function formatLater(at: number, now: number): string {
+  const date = new Date(at)
+  const days = dayDiff(date, new Date(now))
+  if (days <= 0) return `today ${clock(date)}`
+  if (days === 1) return `tomorrow ${clock(date)}`
+  return `${WEEKDAYS[date.getDay()]} ${date.getDate()} ${MONTHS[date.getMonth()]} ${clock(date)}`
+}
+
+/** "12s", "17 min", "1h 52m". */
+export function formatDuration(ms: number): string {
+  const seconds = Math.max(0, Math.round(ms / 1000))
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.round(seconds / 60)
+  if (minutes < 60) return `${minutes} min`
+  return `${Math.floor(minutes / 60)}h ${minutes % 60}m`
+}
+
+/** "24s", "3 min", "5h", "2 days": how long ago the worker last ran. */
+export function formatSince(ms: number): string {
+  const seconds = Math.max(0, Math.floor(ms / 1000))
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.floor(seconds / 60)
+  if (minutes < 60) return `${minutes} min`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 48) return `${hours}h`
+  return `${Math.floor(hours / 24)} days`
+}
+
+/** "Mon 04:00 UTC" or "Daily 02:30 UTC" from a weekly or daily cron; anything else as written. */
+export function scheduleLabel(cron: string): string {
+  const [minute, hour, dayOfMonth, month, weekday, ...rest] = cron.trim().split(/\s+/)
+  const simple =
+    rest.length === 0 &&
+    /^\d{1,2}$/.test(minute ?? '') &&
+    /^\d{1,2}$/.test(hour ?? '') &&
+    dayOfMonth === '*' &&
+    month === '*'
+  if (!simple) return cron
+  const time = `${pad(Number(hour))}:${pad(Number(minute))} UTC`
+  if (weekday === '*') return `Daily ${time}`
+  if (weekday !== undefined && /^[0-6]$/.test(weekday))
+    return `${WEEKDAYS[Number(weekday)]} ${time}`
+  return cron
+}
+
+/**
+ * "next tonight", "next today", "next tomorrow" or "next Mon 19 Oct". In UTC,
+ * like the schedule it follows ("Mon 04:00 UTC · next Mon 26 Oct"), so the
+ * weekday never disagrees with the label.
+ */
+export function formatNextRun(iso: string, now: number): string {
+  const at = new Date(iso)
+  const utcDay = (date: Date) =>
+    Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate())
+  const days = Math.round((utcDay(at) - utcDay(new Date(now))) / 86_400_000)
+  const night = at.getUTCHours() >= 18 || at.getUTCHours() < 6
+  if (at.getTime() - now < 86_400_000 && night && days <= 1) return 'next tonight'
+  if (days <= 0) return 'next today'
+  if (days === 1) return 'next tomorrow'
+  return `next ${WEEKDAYS[at.getUTCDay()]} ${at.getUTCDate()} ${MONTHS[at.getUTCMonth()]}`
+}
+
+/**
+ * Seconds until a retry runs: the first worker tick at or after its backoff.
+ * Without a tick ahead (the worker hasn't run, or is late) it's the backoff alone.
+ */
+function retryInSeconds(runAt: number, now: number, nextTickAt: number | null): number {
+  let at = runAt
+  if (nextTickAt !== null && nextTickAt > now) {
+    at = nextTickAt + Math.max(0, Math.ceil((runAt - nextTickAt) / TICK_MS)) * TICK_MS
+  }
+  return Math.max(0, Math.ceil((at - now) / 1000))
+}
+
+function who(job: Job): string {
+  const by = job.createdBy
+  if (!by) return jobType(job.type).who
+  if ('kind' in by) return by.schedule === 'weekly-seo' ? 'Weekly cron' : 'Nightly cron'
+  return by.name
+}
+
+function whoId(job: Job): string | null {
+  const by = job.createdBy
+  return by && 'id' in by ? by.id : null
+}
+
+/** Claim order (`claimNext`): earliest `runAt`, then oldest. */
+function claimsBefore(a: Job, b: Job): boolean {
+  const runA = Date.parse(a.runAt)
+  const runB = Date.parse(b.runAt)
+  if (runA !== runB) return runA < runB
+  return Date.parse(a.createdAt) < Date.parse(b.createdAt)
+}
+
+/**
+ * How many units a job covers. A batch's worker sets `progress.total` on its
+ * first slice, so until then it's the documents frozen in its payload.
+ */
+export function jobTotal(job: Job): number {
+  if (job.progress.total > 0 || job.type !== 'batch-ai') return job.progress.total
+  const ids = 'documentIds' in job.payload ? job.payload.documentIds : null
+  return Array.isArray(ids) ? ids.length : 0
+}
+
+/**
+ * API jobs in the kit's row shape. `now` is when the list was fetched, so the
+ * retry countdown and "34 min ago" move with each poll. `worker` aligns the
+ * retry countdown with the once-a-minute worker.
+ */
+export function toJobRows(jobs: Job[], now: number, worker: JobWorkerStatus | null): JobRow[] {
+  const nextTickAt = worker?.nextTickAt ? Date.parse(worker.nextTickAt) : null
+  const isActive = (job: Job) => job.status === 'queued' || job.status === 'running'
+  return jobs.map((job) => {
+    const stale =
+      job.status === 'running' &&
+      job.lockedAt !== null &&
+      now - Date.parse(job.lockedAt) > STALE_LOCK_MS
+    // A stale lock is handled as a failed slice on the next tick (JOBS.md).
+    const state: JobStatus = stale ? 'queued' : job.status
+    const error = stale ? 'Worker stopped mid-slice' : job.lastError
+    const finished = state === 'succeeded' ? (job.finishedAt ?? job.updatedAt) : null
+    const review = job.review
+    return {
+      id: job.id,
+      type: job.type,
+      title: job.title,
+      scope: job.scope,
+      state,
+      status: job.status,
+      cancelling: !!job.cancelRequestedAt && isActive(job),
+      done: job.progress.done,
+      total: jobTotal(job),
+      attempts: job.attempts,
+      maxAttempts: job.maxAttempts,
+      error,
+      retryIn:
+        state === 'queued' && error
+          ? retryInSeconds(stale ? now : Date.parse(job.runAt), now, nextTickAt)
+          : 0,
+      queuePos:
+        state === 'queued' && !error
+          ? jobs.filter(
+              (other) =>
+                other.id !== job.id &&
+                isActive(other) &&
+                (other.status === 'running' || claimsBefore(other, job)),
+            ).length
+          : 0,
+      cancelledBy: job.cancelledBy?.name ?? null,
+      pending: review?.pending ?? 0,
+      items: !!review && review.pending + review.approved + review.rejected > 0,
+      review: job.type === 'batch-ai' && 'review' in job.payload ? job.payload.review : null,
+      // cms-core `batchAiWriter`: only a stored `review: 'auto'` is admin-only.
+      adminRetry:
+        job.type === 'batch-ai' &&
+        'review' in job.payload &&
+        job.payload.review === 'auto' &&
+        job.payload.origin !== 'ai-batch',
+      took: finished ? formatDuration(Date.parse(finished) - Date.parse(job.createdAt)) : null,
+      by: who(job),
+      byId: whoId(job),
+      created: formatCreated(job.createdAt, now),
+    }
+  })
+}