@prenta/admin 2.6.1 → 2.8.0

package/src/lib/job-drawer.ts

@@ -0,0 +1,424 @@
+import type { Job, JobEvent, JobReviewItem } from '@prenta/core'
+import { JOB_OPS, formatCreated, formatLater, jobType, view, type JobRow } from './job-view.js'
+import type { ApproveAllOutcome, OnApprove } from './jobs-service.js'
+
+/*
+ * The job drawer's copy and mappings, ported from the kit's jobs-drawer.jsx
+ * (`OVERVIEW`, the tabs, the facts grid, the activity list and the raw row).
+ * They read the list's `JobRow` for the state the screen shows, and the API's
+ * `Job` for what only the detail has.
+ */
+
+export type DrawerTab = 'overview' | 'review' | 'results' | 'activity' | 'details'
+
+/**
+ * jobs-drawer.jsx `tabs`: Review for batch AI, Results for scans. Review is
+ * left out for someone who can't read the suggested changes (a 403), and a
+ * job type the kit doesn't know has neither.
+ */
+export function drawerTabs(
+  type: string,
+  canReview: boolean,
+): Array<{ id: DrawerTab; label: string }> {
+  const second: { id: DrawerTab; label: string } | null =
+    type === 'batch-ai'
+      ? canReview
+        ? { id: 'review', label: 'Review' }
+        : null
+      : type === 'seo-scan' || type === 'content-health'
+        ? { id: 'results', label: 'Results' }
+        : null
+  return [
+    { id: 'overview', label: 'Overview' },
+    ...(second ? [second] : []),
+    { id: 'activity', label: 'Activity' },
+    { id: 'details', label: 'Details' },
+  ]
+}
+
+/** A queued job whose next run is further off than this waits out a usage limit. */
+const CAP_WAIT_MS = 2 * 60_000
+
+export interface CapWait {
+  message: string
+  until: number
+}
+
+/**
+ * A job waiting out an AI usage cap (CONFLICTS.md §4, "Cap refusals"). It
+ * yielded with the cap's message in `progress.message` and `runAt` at the
+ * reset, and with no error, because the slice didn't fail.
+ */
+export function capWait(job: Job, row: JobRow, now: number): CapWait | null {
+  if (row.state !== 'queued' || row.error || row.cancelling) return null
+  const message = job.progress.message?.trim()
+  const until = Date.parse(job.runAt)
+  if (!message || !(until - now > CAP_WAIT_MS)) return null
+  return { message, until }
+}
+
+function sentence(text: string): string {
+  return /[.!?…]$/.test(text) ? text : `${text}.`
+}
+
+function lowerFirst(text: string): string {
+  return text.charAt(0).toLowerCase() + text.slice(1)
+}
+
+/**
+ * jobs-drawer.jsx `OVERVIEW`: the plain-language status sentence. Edits:
+ * attempts read the job's `maxAttempts`; the slice copy keeps its own
+ * capitals ("the SEO digest"); "Finished in … across n slices" counts slices
+ * from the type's slice size; and a job waiting out a usage cap, or a cancel
+ * whose worker stopped, says so.
+ */
+export function overviewSentence(row: JobRow, job: Job, now: number): string {
+  const type = jobType(row.type)
+  const unit = type.unit
+  const wait = capWait(job, row, now)
+  if (wait) {
+    const done = row.done > 0 ? `${row.done} of ${row.total} ${unit} done. ` : ''
+    return `${done}Paused for a usage limit. ${sentence(wait.message)} It continues ${formatLater(wait.until, now)}.`
+  }
+  const v = view(row)
+  switch (v.k) {
+    case 'running': {
+      const slice = type.slice ? ` Each slice ${lowerFirst(type.slice)}` : ''
+      return `Running slice ${row.done + 1} of ${row.total} now.${slice} When the worker’s 20 seconds are up, the job yields and continues on the next run. Yielding isn’t a failure and doesn’t use a retry.`
+    }
+    case 'between':
+      return `${row.done} of ${row.total} ${unit} done. It’s waiting for the next worker run, about once a minute.`
+    case 'queued':
+      return `Waiting for the worker. ${
+        row.queuePos
+          ? `${row.queuePos} job${row.queuePos > 1 ? 's are' : ' is'} ahead of it.`
+          : 'It starts on the next run.'
+      }`
+    case 'retry':
+      return `The last slice threw an error, so the job will try again in ${row.retryIn} seconds. Retries wait 30 seconds, then double each time, up to 15 minutes. After ${row.maxAttempts} attempts it’s marked failed.`
+    case 'dead':
+      return `Stopped after ${row.maxAttempts} attempts at ${unit === 'pages' ? 'page' : 'document'} ${row.done + 1}. The last error is kept below. Retrying resets the attempt count and continues from where it stopped.`
+    case 'cancelled':
+      return `Cancelled${row.cancelledBy ? ` by ${row.cancelledBy}` : ''} after ${row.done} of ${row.total} ${unit}. Work already done was kept.`
+    case 'cancelling':
+      // A running job whose lock went stale ends on the next tick (CancelJobDialog).
+      return row.status === 'running' && row.state !== 'running'
+        ? 'Its last slice stopped without finishing. It stops on the next worker run, within a minute.'
+        : 'Stopping when the current slice finishes, usually within 20 seconds.'
+    case 'review':
+      return `Finished. ${row.pending} AI change${row.pending > 1 ? 's are' : ' is'} waiting for approval. Nothing is applied until someone approves it.`
+    default: {
+      const took = row.took ?? '—'
+      const slices = type.perSlice ? Math.max(1, Math.ceil(row.total / type.perSlice)) : 0
+      return slices
+        ? `Finished in ${took} across ${slices} slice${slices === 1 ? '' : 's'}.`
+        : `Finished in ${took}.`
+    }
+  }
+}
+
+/**
+ * The facts grid's "Attempts". The API counts failures, so a healthy job has
+ * 0; the kit shows the attempt a job is on or finished with ("1 of 3"), and
+ * for one waiting to retry, or failed, the attempts used.
+ */
+export function shownAttempts(row: JobRow): number {
+  const k = view(row).k
+  if (k === 'retry' || k === 'dead' || k === 'queued') return row.attempts
+  return Math.min(row.attempts + 1, row.maxAttempts)
+}
+
+/** The operation's label ("Rewrite meta descriptions"), or null when the kit doesn't know it. */
+export function operationLabel(operation: unknown): string | null {
+  return JOB_OPS.find((op) => op.id === operation)?.label ?? null
+}
+
+/** "now", "6s ago", "19m ago", then the list's "Yesterday 16:41". */
+export function formatEventTime(iso: string, now: number): string {
+  const ms = now - Date.parse(iso)
+  if (!(ms >= 5_000)) return 'now'
+  if (ms < 60_000) return `${Math.floor(ms / 1000)}s ago`
+  if (ms < 3_600_000) return `${Math.floor(ms / 60_000)}m ago`
+  return formatCreated(iso, now)
+}
+
+export type TimelineTone = 'ok' | 'err' | 'warn' | 'run' | 'none'
+
+export interface TimelineEntry {
+  key: string
+  /** ISO time; null on the two rows made up for a job with no events. */
+  at: string | null
+  title: string
+  detail: string
+  tone: TimelineTone
+}
+
+/** A fold has no key of its own: `foldIds` gives it one that lasts. */
+export type TimelineRow =
+  | { kind: 'entry'; entry: TimelineEntry }
+  | { kind: 'group'; entries: TimelineEntry[] }
+
+/** Finished slices shown before the rest collapse into "{n} earlier slices". */
+const SLICES_SHOWN = 2
+
+function eventTone(event: JobEvent, newest: boolean, running: boolean): TimelineTone {
+  switch (event.kind) {
+    case 'finished':
+    case 'slice_ok':
+      return 'ok'
+    case 'yielded':
+      return /usage limit/i.test(event.message) ? 'warn' : 'ok'
+    case 'slice_failed':
+    case 'dead':
+      return 'err'
+    case 'retry_scheduled':
+    case 'stale_lock':
+    case 'cancel_requested':
+      return 'warn'
+    case 'claimed':
+      return newest && running ? 'run' : 'none'
+    default:
+      return 'none'
+  }
+}
+
+function eventDetail(event: JobEvent, by: string): string {
+  const parts: string[] = []
+  const detail = event.detail?.trim()
+  if (detail) parts.push(detail)
+  else if (event.kind === 'queued' && event.message === 'Queued') parts.push(`${by} started it`)
+  if (typeof event.durationMs === 'number') parts.push(`${(event.durationMs / 1000).toFixed(1)}s`)
+  if (event.tokens) parts.push(`${event.tokens.toLocaleString()} tokens`)
+  if (event.kind === 'yielded' && !/usage limit/i.test(event.message)) parts.push('yielded')
+  return parts.join(' · ')
+}
+
+/**
+ * The Activity tab (jobs-drawer.jsx `act`), newest first, from the job's
+ * events. Each slice writes "Slice started" and then how it ended; the start
+ * is shown only while it runs, when it names a later attempt, and for the
+ * oldest one, so the list reads like the kit's. Past the newest two finished
+ * slices, runs of finished slices collapse into one "{n} earlier slices" row.
+ * A job with no events (from before the log existed) gets the kit's two rows.
+ */
+export function timeline(events: JobEvent[], job: Job, row: JobRow): TimelineRow[] {
+  if (events.length === 0) {
+    const succeeded = row.state === 'succeeded'
+    return [
+      {
+        kind: 'entry',
+        entry: {
+          key: 'updated',
+          at: job.updatedAt,
+          title: succeeded ? 'Finished' : 'Updated',
+          detail: row.took ? `Took ${row.took}` : '',
+          tone: succeeded ? 'ok' : 'none',
+        },
+      },
+      {
+        kind: 'entry',
+        entry: { key: 'queued', at: job.createdAt, title: 'Queued', detail: row.by, tone: 'none' },
+      },
+    ]
+  }
+  const sorted = events
+    .map((event, index) => ({ event, index }))
+    .sort((a, b) => Date.parse(b.event.at) - Date.parse(a.event.at) || a.index - b.index)
+    .map(({ event }) => event)
+  let oldestClaim = -1
+  sorted.forEach((event, index) => {
+    if (event.kind === 'claimed') oldestClaim = index
+  })
+  // Keys are counted from the oldest end, so a new event doesn't change the
+  // keys of the ones already shown (and an open group stays open).
+  const keys: string[] = []
+  const seen = new Map<string, number>()
+  for (let index = sorted.length - 1; index >= 0; index--) {
+    const event = sorted[index]!
+    const base = `${event.at}|${event.kind}|${event.message}`
+    const repeats = seen.get(base) ?? 0
+    seen.set(base, repeats + 1)
+    keys[index] = repeats ? `${base}|${repeats}` : base
+  }
+  const running = row.state === 'running'
+  const rows: TimelineRow[] = []
+  let shownSlices = 0
+  let group: TimelineEntry[] = []
+  const flush = () => {
+    const [first] = group
+    if (group.length === 1 && first) rows.push({ kind: 'entry', entry: first })
+    else if (first) rows.push({ kind: 'group', entries: group })
+    group = []
+  }
+  sorted.forEach((event, index) => {
+    const tone = eventTone(event, index === 0, running)
+    if (event.kind === 'claimed' && tone !== 'run' && !event.detail && index !== oldestClaim) return
+    const entry: TimelineEntry = {
+      key: keys[index]!,
+      at: event.at,
+      title: event.message,
+      detail: eventDetail(event, row.by),
+      tone,
+    }
+    const slice = (event.kind === 'yielded' || event.kind === 'slice_ok') && tone === 'ok'
+    if (slice && shownSlices >= SLICES_SHOWN) {
+      group.push(entry)
+      return
+    }
+    if (slice) shownSlices++
+    flush()
+    rows.push({ kind: 'entry', entry })
+  })
+  flush()
+  return rows
+}
+
+/** What `foldIds` remembers from one refresh to the next. */
+export interface FoldMemory {
+  /** Entry key → the id of the fold it was in. */
+  entries: Map<string, string>
+  next: number
+}
+
+/**
+ * An id for each fold in `rows`, in order, that lasts while any of its
+ * slices is still in it. A fold's edges all move: newer slices join it, the
+ * newest-50 window drops its oldest, and older folds shrink away, so no
+ * position or edge entry names it for long. `memory` maps each folded entry
+ * to its fold's id and is updated. When folds merge, an id in `prefer` (the
+ * open ones) wins, so an open fold stays open, and a fold made of entries
+ * never folded before gets a new id, so it never takes an open fold's state.
+ */
+export function foldIds(
+  rows: TimelineRow[],
+  memory: FoldMemory,
+  prefer: ReadonlySet<string> = new Set(),
+): string[] {
+  const used = new Set<string>()
+  const seen = new Map<string, string>()
+  const ids: string[] = []
+  for (const row of rows) {
+    if (row.kind !== 'group') continue
+    const known: string[] = []
+    for (const entry of row.entries) {
+      const id = memory.entries.get(entry.key)
+      if (id && !used.has(id) && !known.includes(id)) known.push(id)
+    }
+    const id =
+      known.find((candidate) => prefer.has(candidate)) ?? known[0] ?? `fold-${memory.next++}`
+    used.add(id)
+    for (const entry of row.entries) seen.set(entry.key, id)
+    ids.push(id)
+  }
+  // Entries no longer folded have left the window (or never come back).
+  memory.entries = seen
+  return ids
+}
+
+/**
+ * The Details tab's raw row. Like the kit, the frozen document ids read as
+ * "[42 ids]" rather than up to 1,000 of them.
+ */
+export function detailsJson(job: Job): string {
+  const payload = job.payload as Record<string, unknown>
+  const ids = payload.documentIds
+  return JSON.stringify(
+    Array.isArray(ids)
+      ? { ...job, payload: { ...payload, documentIds: `[${ids.length} ids]` } }
+      : job,
+    null,
+    2,
+  )
+}
+
+/** The link a link suggestion's `after` holds (cms-core `ai/batch-links.ts`, `LINK_IN_AFTER`). */
+const LINK_IN_AFTER = /<a href="(\/(?!\/)[^"<>\s\\]*)">([^<>]+)<\/a>/
+
+export interface LinkParts {
+  before: string
+  anchor: string
+  href: string
+  after: string
+}
+
+/**
+ * A link suggestion's line split around its link, so the drawer shows the
+ * words as text and never renders the markup. Null when `after` holds no link
+ * in the form the server writes.
+ */
+export function linkParts(after: string): LinkParts | null {
+  const match = LINK_IN_AFTER.exec(after)
+  if (!match) return null
+  return {
+    before: after.slice(0, match.index),
+    href: match[1] ?? '',
+    anchor: match[2] ?? '',
+    after: after.slice(match.index + match[0].length),
+  }
+}
+
+/** The suggested text's limit, past which its count turns red (JOBS.md: meta descriptions). */
+export function charLimit(field: string): number | null {
+  return field === 'metaDescription' ? 155 : null
+}
+
+/**
+ * A fresh read of the loaded changes, in the order suggested. A change decided
+ * here after that read started keeps the copy the decision returned, so a slow
+ * refresh can't put it back to pending.
+ */
+export function mergeReviewItems(
+  fresh: JobReviewItem[],
+  loaded: JobReviewItem[],
+  keep: ReadonlySet<string>,
+): JobReviewItem[] {
+  const local = new Map(loaded.map((item) => [item.id, item]))
+  return fresh.map((item) => (keep.has(item.id) ? (local.get(item.id) ?? item) : item))
+}
+
+/** A page appended to the loaded changes, without repeating any. */
+export function appendReviewItems(loaded: JobReviewItem[], page: JobReviewItem[]): JobReviewItem[] {
+  const seen = new Set(loaded.map((item) => item.id))
+  return [...loaded, ...page.filter((item) => !seen.has(item.id))]
+}
+
+/**
+ * "Approve all" toast (jobs-drawer.jsx `approveAll`), plus what stayed in
+ * review: approve-all skips changes to published documents when they'd be
+ * saved as drafts, changes the reviewer can't write, and saves that fail.
+ */
+export function approveAllMessage(
+  outcome: Pick<ApproveAllOutcome, 'approved' | 'remaining'>,
+  onApprove: OnApprove,
+): { title: string; description?: string } {
+  const { approved, remaining } = outcome
+  const title =
+    approved > 0
+      ? `${approved} change${approved === 1 ? '' : 's'} approved · ${onApprove === 'publish' ? 'published' : 'saved as drafts'}`
+      : 'No changes were approved'
+  if (remaining <= 0) return { title }
+  const left = `${remaining} ${remaining === 1 ? 'change' : 'changes'} stayed in review.`
+  return {
+    title,
+    description:
+      onApprove === 'publish'
+        ? `${left} They couldn’t be applied.`
+        : `${left} Changes to published documents need Publish, so approve those one at a time.`,
+  }
+}
+
+/**
+ * "Approve all" stopped because an edit couldn't be approved: nothing else
+ * was approved, so the AI's text can't replace that edit.
+ */
+export function approveAllStoppedMessage(
+  approvedEdits: number,
+  refusedEdits: number,
+): { title: string; description: string } {
+  const plural = (count: number) => `${count} edited change${count === 1 ? '' : 's'}`
+  const done = approvedEdits > 0 ? `${plural(approvedEdits)} approved. ` : ''
+  return {
+    title: 'Approve all stopped',
+    description: `${done}${plural(refusedEdits)} couldn’t be approved, so nothing else was, and the AI’s text doesn’t replace an edit. Each change says why.`,
+  }
+}