@forumone/throughline 0.0.0-stage → 1.0.0-next.0

package/bin/payload-cli.mjs

@@ -0,0 +1,443 @@
+/*
+The Payload CLI, wrapped so a hung run cannot outlive the shell that started it.
+`bin/throughline-payload.mjs` is the entry point; this module is the runner and
+the pure pieces its tests exercise.
+
+`pnpm payload generate:types` is three processes deep — shell, pnpm, node — and
+pnpm (like npm and yarn) does not forward signals to the script child it
+spawns. Kill the shell (a Ctrl-C, an agent tool-call timeout, a closed
+terminal, a cancelled CI step) and pnpm dies while node keeps running,
+reparented to PID 1. When the run was hung rather than merely slow, that orphan
+spins on a core indefinitely: 48 of them piled up on one machine inside a day,
+~90 CPU-minutes each, at a load average of 300.
+
+Three layers, because no single one covers every way this exits.
+
+1. The child is spawned `detached`, so it leads its own process group. That is
+   what makes it killable as a *group* by pid — the whole subtree dies with it,
+   and nothing is ever matched by process name, which would put unrelated node
+   work on the same machine at risk.
+2. SIGINT, SIGTERM and SIGHUP are forwarded to that group, and a wall-clock
+   timeout kills it as well. Between them that covers Ctrl-C, a tool-call
+   timeout, and a hangup from a closing terminal.
+3. If this runner is itself SIGKILLed, no handler of ours can run. So each
+   spawn is recorded in `.payload-cli-pids` at the workspace root and the
+   *next* run (or `--reap`) sweeps the file. See `verdict` for what an entry
+   must satisfy before anything is signalled.
+
+PAYLOAD_CLI_TIMEOUT_MS sets the wall clock; 0 disables it. The default is five
+minutes, except for the `migrate` family (`migrate`, `migrate:create`, …),
+which gets none: a large migration is legitimately long, and `migrate:create`
+can stop at an interactive prompt. Layers 1 and 3 apply regardless.
+*/
+import { execFile, spawn } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { promisify } from 'node:util'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const execFileAsync = promisify(execFile)
+
+export const PID_FILE_NAME = '.payload-cli-pids'
+export const DEFAULT_TIMEOUT_MS = 300_000
+export const DEFAULT_GRACE_MS = 5_000
+/** Exit code for "gave up waiting", as coreutils `timeout` uses. */
+export const TIMEOUT_EXIT_CODE = 124
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+const log = (message) => process.stderr.write(`throughline-payload: ${message}\n`)
+
+/** Collapse runs of whitespace, so `ps` column padding never decides a match. */
+export const norm = (value) => (value ?? '').trim().replace(/\s+/g, ' ')
+
+// ---------------------------------------------------------------------------
+// Pure pieces
+// ---------------------------------------------------------------------------
+
+/**
+ * `--reap` alone sweeps and exits. Anything else is passed to the Payload CLI
+ * untouched, including flags that look like ours further along the argv.
+ */
+export function parseArgs(argv) {
+  if (argv[0] === '--reap') return { mode: 'reap', args: [] }
+  return { mode: 'run', args: [...argv] }
+}
+
+/** `migrate`, `migrate:create`, `migrate:status`, `migrate:fresh`, … */
+export const isMigrateCommand = (args) => /^migrate(:|$)/.test(args[0] ?? '')
+
+function readMs(env, name, fallback) {
+  const raw = env[name]
+  if (raw === undefined || raw.trim() === '') return fallback
+  const value = Number(raw)
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`${name} must be a whole number of milliseconds (0 disables it), got '${raw}'`)
+  }
+  return value
+}
+
+/**
+ * The wall clock for a run, in ms; 0 means none. An explicit
+ * PAYLOAD_CLI_TIMEOUT_MS always wins. A malformed one is an error rather than
+ * silently "no timeout", which is the failure this exists to prevent.
+ */
+export function selectTimeout(args, env) {
+  return readMs(env, 'PAYLOAD_CLI_TIMEOUT_MS', isMigrateCommand(args) ? 0 : DEFAULT_TIMEOUT_MS)
+}
+
+/** How long a group gets between the polite signal and SIGKILL. */
+export const selectGrace = (env) => readMs(env, 'PAYLOAD_CLI_GRACE_MS', DEFAULT_GRACE_MS)
+
+/**
+ * The directory that owns the pid file: the nearest ancestor of `cwd` holding
+ * `pnpm-workspace.yaml` — the workspace root, so every app in a monorepo
+ * shares one file and one `payload:reap` — or, outside a pnpm workspace, the
+ * nearest directory with a `package.json`. Real path, because that is what
+ * the spawned command line contains.
+ */
+export function findRoot(cwd, exists = fs.existsSync) {
+  const real = fs.realpathSync(cwd)
+  let nearestPackage
+  for (let dir = real; ; dir = path.dirname(dir)) {
+    if (exists(path.join(dir, 'pnpm-workspace.yaml'))) return dir
+    if (!nearestPackage && exists(path.join(dir, 'package.json'))) nearestPackage = dir
+    if (path.dirname(dir) === dir) break
+  }
+  return nearestPackage ?? real
+}
+
+const ENTRY_FIELDS = {
+  pid: 'number',
+  pgid: 'number',
+  start: 'string',
+  command: 'string',
+  runnerPid: 'number',
+  runnerStart: 'string',
+}
+
+/**
+ * One JSON object per line. A torn line from an abrupt exit, or anything
+ * missing a field verification needs, is dropped — never guessed at.
+ */
+export function parsePidFile(text) {
+  return text
+    .split('\n')
+    .filter((line) => line.trim())
+    .flatMap((line) => {
+      let entry
+      try {
+        entry = JSON.parse(line)
+      } catch {
+        return []
+      }
+      if (!entry || typeof entry !== 'object') return []
+      for (const [field, type] of Object.entries(ENTRY_FIELDS)) {
+        if (typeof entry[field] !== type) return []
+      }
+      if (!Number.isInteger(entry.pid) || entry.pid <= 1) return []
+      if (entry.pgid !== entry.pid) return [] // We only ever record group leaders.
+      return [entry]
+    })
+}
+
+export const serializeEntries = (entries) =>
+  entries.map((entry) => `${JSON.stringify(entry)}\n`).join('')
+
+/**
+ * What the sweep does with one recorded entry, given what `ps` reports now
+ * (`undefined` fields mean the pid is gone):
+ *
+ *   'forget' — the pid is gone, or it is no longer the process we recorded:
+ *              its start time differs (the OS recycled the pid), its command
+ *              line differs, or that command line is not rooted in this
+ *              workspace. Nothing is signalled.
+ *   'keep'   — it is ours and its runner is still alive: a concurrent run in
+ *              this workspace, which keeps its child.
+ *   'reap'   — it is ours and its runner is gone: an orphan.
+ *
+ * Only 'reap' leads to a signal, and only to the recorded process group.
+ */
+export function verdict(entry, observed, root) {
+  if (!observed.start) return 'forget'
+  if (norm(observed.start) !== norm(entry.start)) return 'forget'
+  if (norm(observed.command) !== norm(entry.command)) return 'forget'
+  if (!entry.command.includes(`${root}${path.sep}`)) return 'forget'
+  if (observed.runnerStart && norm(observed.runnerStart) === norm(entry.runnerStart)) return 'keep'
+  return 'reap'
+}
+
+/** 128 + signal number, as a shell reports a signalled exit. */
+export const signalExitCode = (signal) => 128 + (os.constants.signals[signal] ?? 0)
+
+// ---------------------------------------------------------------------------
+// Processes
+// ---------------------------------------------------------------------------
+
+/*
+`payload/bin.js` is not in the package's `exports`, so it cannot be resolved
+directly. Resolve the package entry from the app's directory — never from this
+package's own install — and walk up to the directory that owns it. The result
+is a real path inside this workspace, which is what makes the spawned argv
+unambiguous: one node process whose command line names this workspace.
+*/
+export function resolvePayloadBin(fromDir) {
+  const require = createRequire(path.join(fromDir, 'package.json'))
+  let entry
+  try {
+    entry = require.resolve('payload')
+  } catch {
+    throw new Error(`could not resolve 'payload' from ${fromDir} — is it a dependency of this app?`)
+  }
+  for (let dir = path.dirname(entry); ; dir = path.dirname(dir)) {
+    const manifest = path.join(dir, 'package.json')
+    if (fs.existsSync(manifest)) {
+      const { name, bin } = JSON.parse(fs.readFileSync(manifest, 'utf8'))
+      if (name === 'payload') {
+        const relative = typeof bin === 'string' ? bin : bin?.payload
+        if (relative) return fs.realpathSync(path.join(dir, relative))
+        break
+      }
+    }
+    if (path.dirname(dir) === dir) break
+  }
+  throw new Error(`could not find the payload CLI's bin from ${fromDir}`)
+}
+
+/*
+One `ps` field for a set of pids, as a map; a pid that is gone is absent. `-ww`
+so a long command line is never truncated. Every process is listed and then
+filtered, rather than asking for the pids with `-p`: one implausible pid in the
+file ("process id too large" on macOS) makes `ps -p` fail for the whole batch,
+which would blind the sweep.
+*/
+async function psField(pids, field) {
+  const found = new Map()
+  if (!pids.length) return found
+  const wanted = new Set(pids)
+  let stdout
+  try {
+    ;({ stdout } = await execFileAsync('ps', ['-A', '-ww', '-o', `pid=,${field}=`], {
+      maxBuffer: 64 * 1024 * 1024,
+    }))
+  } catch (error) {
+    stdout = error?.stdout ?? ''
+  }
+  for (const line of stdout.split('\n')) {
+    const match = line.match(/^\s*(\d+)\s+(.*)$/)
+    if (match && wanted.has(Number(match[1]))) found.set(Number(match[1]), match[2])
+  }
+  return found
+}
+
+const groupAlive = (pgid) => {
+  try {
+    process.kill(-pgid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/*
+`signal` to the group, then SIGKILL to whatever is left after the grace period.
+The wait is on the whole group, not just its leader, so a grandchild that
+ignores the first signal is still caught.
+*/
+async function killGroup(pgid, signal, graceMs) {
+  try {
+    process.kill(-pgid, signal)
+  } catch {
+    return // Already gone.
+  }
+  for (let waited = 0; waited < graceMs; waited += 100) {
+    if (!groupAlive(pgid)) return
+    await delay(100)
+  }
+  try {
+    process.kill(-pgid, 'SIGKILL')
+  } catch {
+    // Exited during the grace period.
+  }
+}
+
+function pidFileStore(root) {
+  const file = path.join(root, PID_FILE_NAME)
+  const read = () => {
+    try {
+      return parsePidFile(fs.readFileSync(file, 'utf8'))
+    } catch {
+      return []
+    }
+  }
+  const write = (entries) => {
+    if (!entries.length) fs.rmSync(file, { force: true })
+    else fs.writeFileSync(file, serializeEntries(entries))
+  }
+  return {
+    read,
+    write,
+    append: (entry) => fs.appendFileSync(file, serializeEntries([entry])),
+    drop: (pid) => write(read().filter((entry) => entry.pid !== pid)),
+  }
+}
+
+/** The backstop: reap orphans this workspace recorded. Returns how many. */
+export async function sweep(root, graceMs) {
+  const store = pidFileStore(root)
+  const entries = store.read()
+  if (!entries.length) return 0
+
+  const pids = [...new Set(entries.flatMap((entry) => [entry.pid, entry.runnerPid]))]
+  const [starts, commands] = await Promise.all([psField(pids, 'lstart'), psField(pids, 'args')])
+
+  const keep = []
+  let reaped = 0
+  for (const entry of entries) {
+    const result = verdict(
+      entry,
+      {
+        start: starts.get(entry.pid),
+        command: commands.get(entry.pid),
+        runnerStart: starts.get(entry.runnerPid),
+      },
+      root,
+    )
+    if (result === 'keep') keep.push(entry)
+    if (result !== 'reap') continue
+    log(
+      `reaping orphaned '${entry.script ?? 'payload'}' (pid ${entry.pid}, started ${entry.at ?? entry.start})`,
+    )
+    await killGroup(entry.pgid, 'SIGTERM', graceMs)
+    reaped += 1
+  }
+  // Re-read so an entry a concurrent run appended meanwhile is not lost.
+  const handled = new Set(entries.map((entry) => entry.pid))
+  const kept = new Set(keep.map((entry) => entry.pid))
+  store.write(store.read().filter((entry) => !handled.has(entry.pid) || kept.has(entry.pid)))
+  return reaped
+}
+
+export async function main({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  env = process.env,
+} = {}) {
+  let parsed, timeoutMs, graceMs, root
+  try {
+    parsed = parseArgs(argv)
+    timeoutMs = selectTimeout(parsed.args, env)
+    graceMs = selectGrace(env)
+    root = findRoot(cwd)
+  } catch (error) {
+    log(error.message)
+    process.exit(2)
+  }
+
+  if (process.platform === 'win32') {
+    // No process groups and no `ps`: run it plainly rather than not at all.
+    if (parsed.mode === 'reap') return
+    const child = spawn(process.execPath, [resolvePayloadBin(cwd), ...parsed.args], {
+      stdio: 'inherit',
+      cwd,
+    })
+    child.on('exit', (code) => process.exit(code ?? 1))
+    return
+  }
+
+  const reaped = await sweep(root, graceMs)
+  if (parsed.mode === 'reap') {
+    log(reaped ? `reaped ${reaped} orphaned run(s)` : 'nothing to reap')
+    return
+  }
+
+  let bin
+  try {
+    bin = resolvePayloadBin(cwd)
+  } catch (error) {
+    log(error.message)
+    process.exit(1)
+  }
+
+  const store = pidFileStore(root)
+  const childArgv = [bin, ...parsed.args]
+  const child = spawn(process.execPath, childArgv, { stdio: 'inherit', detached: true, cwd, env })
+
+  let timer
+  let finished = false
+  let stopping = false
+  const finish = (code) => {
+    if (finished) return
+    finished = true
+    clearTimeout(timer)
+    if (child.pid) store.drop(child.pid)
+    process.exit(code)
+  }
+
+  /*
+  Kill the group and then exit with `code`. Exiting is deliberately left to
+  this, not to the child's 'exit' event: the leader usually dies on the first
+  signal, and exiting then would abandon the grace period — and with it the
+  SIGKILL for a grandchild that ignored that signal.
+  */
+  const stop = async (signal, code) => {
+    if (stopping || finished) return
+    stopping = true
+    if (child.pid) await killGroup(child.pid, signal, graceMs)
+    finish(code)
+  }
+
+  child.on('error', (error) => {
+    log(error.message)
+    if (!stopping) finish(1)
+  })
+  child.on('exit', async (code, signal) => {
+    if (stopping) return
+    // Payload is done. Anything it left running in its group goes with it.
+    if (groupAlive(child.pid)) {
+      stopping = true
+      await killGroup(child.pid, 'SIGTERM', graceMs)
+    }
+    finish(signal ? signalExitCode(signal) : (code ?? 0))
+  })
+
+  /*
+  The child is in its own group, so a terminal Ctrl-C reaches this runner
+  alone. Forwarding the same signal lets Payload clean up as it would have;
+  the grace period then escalates to SIGKILL.
+  */
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(signal, () => stop(signal, signalExitCode(signal)))
+  }
+
+  if (timeoutMs > 0) {
+    timer = setTimeout(() => {
+      log(
+        `no exit after ${Math.round(timeoutMs / 1000)}s — killing process group ${child.pid}. ` +
+          'Set PAYLOAD_CLI_TIMEOUT_MS higher, or 0, if this run is legitimately slow.',
+      )
+      stop('SIGTERM', TIMEOUT_EXIT_CODE)
+    }, timeoutMs)
+  }
+
+  if (!child.pid) return // Spawn failed; 'error' handles it.
+
+  /*
+  Recorded after the spawn, so a run that exits before this lands leaves an
+  entry the next sweep forgets on its first condition. The command is the argv
+  we spawned, not what `ps` shows this instant — just after fork the child can
+  still carry this runner's argv.
+  */
+  const starts = await psField([child.pid, process.pid], 'lstart')
+  if (finished) return
+  store.append({
+    pid: child.pid,
+    pgid: child.pid, // `detached` makes the child its own group leader.
+    start: norm(starts.get(child.pid)),
+    command: [process.execPath, ...childArgv].join(' '),
+    runnerPid: process.pid,
+    runnerStart: norm(starts.get(process.pid)),
+    script: parsed.args[0] ?? 'payload',
+    at: new Date().toISOString(),
+  })
+}

package/bin/throughline-payload.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// The Payload CLI, run in its own process group under a wall clock, with a
+// sweep for runs a killed shell left behind. See ./payload-cli.mjs.
+import { main } from './payload-cli.mjs'
+
+await main()

package/dist/access/coreCollections.d.ts

@@ -0,0 +1,18 @@
+import type { SanitizedConfig } from 'payload';
+/** Payload's own slug for the lock table. */
+export declare const LOCKED_DOCUMENTS_SLUG = "payload-locked-documents";
+export interface HardenCoreCollectionsOptions {
+    /**
+     * Who may take, read and release document locks. A lock is created by
+     * whoever opens a document for editing, so this must include everyone who
+     * edits. Default: users with the `admin` or `editor` role.
+     */
+    canLock?: (user: unknown) => boolean;
+}
+/**
+ * Close the `defaultAccess` holes on the collections Payload adds for itself.
+ * Mutates and returns the config. Throws if a collection it expects is absent,
+ * because a silent no-op here is a reopened hole nobody would see.
+ */
+export declare function hardenCoreCollections(config: SanitizedConfig, options?: HardenCoreCollectionsOptions): SanitizedConfig;
+//# sourceMappingURL=coreCollections.d.ts.map

package/dist/access/coreCollections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coreCollections.d.ts","sourceRoot":"","sources":["../../src/access/coreCollections.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,eAAe,EAAE,MAAM,SAAS,CAAA;AAmCtD,6CAA6C;AAC7C,eAAO,MAAM,qBAAqB,6BAA6B,CAAA;AAQ/D,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAA;CACrC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,4BAAiC,GACzC,eAAe,CAajB"}

package/dist/access/coreCollections.js

@@ -0,0 +1,56 @@
+/*
+Narrowing a collection Payload adds for itself, after the fact. From
+forumone-2026's `access/coreCollections.ts` (audit 04 F-12 there).
+
+`payload-locked-documents` ships with all four operations at `defaultAccess`,
+which is `Boolean(user)`. So any authenticated principal (an approver, a
+role-less account, an MCP API key) could read, create, update and delete every
+lock row through a full REST surface. Two consequences:
+
+- **Deleting locks defeats a control the publishing service depends on.** The
+  publish and unpublish writes pass `overrideLock: false`, so that unpublishing a
+  page somebody has open is a refusal. Deleting the lock first gets round it.
+- **Creating them is an editorial denial of service.** One row per document
+  makes every document read-only in the admin.
+
+## Why a function on the sanitized config
+
+There is no override point. The collection does not exist while the config is
+written or while plugins run: `buildConfig` runs every plugin first and then
+`sanitizeConfig` builds this collection. `lockDocuments: false` everywhere would
+remove it, and `overrideLock: false` with it. What is left is to patch the
+sanitized result:
+
+```ts
+export default buildConfig({ ... }).then(hardenCoreCollections)
+```
+
+Access functions are read per request off `collection.config.access`, so
+replacing them there is the same as having declared them. It depends on the
+slug, so it throws when the collection is missing rather than becoming a silent
+no-op after a Payload upgrade renames it.
+*/
+/** Payload's own slug for the lock table. */
+export const LOCKED_DOCUMENTS_SLUG = 'payload-locked-documents';
+/** Default: a user whose `roles` include `admin` or `editor`. */
+function editorsAndAdmins(user) {
+    const roles = user?.roles;
+    return Array.isArray(roles) && (roles.includes('admin') || roles.includes('editor'));
+}
+/**
+ * Close the `defaultAccess` holes on the collections Payload adds for itself.
+ * Mutates and returns the config. Throws if a collection it expects is absent,
+ * because a silent no-op here is a reopened hole nobody would see.
+ */
+export function hardenCoreCollections(config, options = {}) {
+    const locked = config.collections.find((collection) => collection.slug === LOCKED_DOCUMENTS_SLUG);
+    if (!locked) {
+        throw new Error(`hardenCoreCollections: no "${LOCKED_DOCUMENTS_SLUG}" collection in the sanitized config. ` +
+            'Payload has renamed or stopped adding it, and its access rules are no longer being narrowed.');
+    }
+    const canLock = options.canLock ?? editorsAndAdmins;
+    const rule = ({ req }) => canLock(req.user);
+    locked.access = { ...locked.access, create: rule, read: rule, update: rule, delete: rule };
+    return config;
+}
+//# sourceMappingURL=coreCollections.js.map

package/dist/access/coreCollections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coreCollections.js","sourceRoot":"","sources":["../../src/access/coreCollections.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BE;AAEF,6CAA6C;AAC7C,MAAM,CAAC,MAAM,qBAAqB,GAAG,0BAA0B,CAAA;AAE/D,iEAAiE;AACjE,SAAS,gBAAgB,CAAC,IAAa;IACrC,MAAM,KAAK,GAAI,IAA+C,EAAE,KAAK,CAAA;IACrE,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAA;AACtF,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAuB,EACvB,UAAwC,EAAE;IAE1C,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,KAAK,qBAAqB,CAAC,CAAA;IACjG,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,8BAA8B,qBAAqB,wCAAwC;YACzF,8FAA8F,CACjG,CAAA;IACH,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAA;IACnD,MAAM,IAAI,GAAW,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACnD,MAAM,CAAC,MAAM,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;IAC1F,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/approvals/collection.d.ts

@@ -0,0 +1,21 @@
+import type { CollectionConfig } from 'payload';
+import { type PluginAdminOptions } from '../plugin-contract/admin.js';
+export interface CreateApprovalsCollectionOptions {
+    /** Override the collection slug. Default: 'approvals'. */
+    slug?: string;
+    /** Slug of the users collection that approver/requester relationships point at. Default: 'users'. */
+    usersSlug?: string;
+    /** Allowed group slugs from the plugin's `groups` option. Used as the select options on the approverGroups field. */
+    groupSlugs: string[];
+    /** Sidebar placement. Default: the `'Throughline'` group; `group: false` leaves it ungrouped. */
+    admin?: PluginAdminOptions;
+}
+export declare const DEFAULT_APPROVALS_SLUG = "approvals";
+/**
+ * Builds the approvals collection config. The collection is read-mostly:
+ * `create` is system-only (the plugin's tools mint records via the local
+ * API), `update` is admin-only (so a stuck pending record can be corrected),
+ * `delete` is denied (audit trail must remain).
+ */
+export declare function createApprovalsCollection(options: CreateApprovalsCollectionOptions): CollectionConfig;
+//# sourceMappingURL=collection.d.ts.map

package/dist/approvals/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../src/approvals/collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAC/C,OAAO,EAAE,KAAK,kBAAkB,EAAqB,MAAM,6BAA6B,CAAA;AAExF,MAAM,WAAW,gCAAgC;IAC/C,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qHAAqH;IACrH,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,iGAAiG;IACjG,KAAK,CAAC,EAAE,kBAAkB,CAAA;CAC3B;AAED,eAAO,MAAM,sBAAsB,cAAc,CAAA;AAEjD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gCAAgC,GACxC,gBAAgB,CAgGlB"}

package/dist/approvals/collection.js

@@ -0,0 +1,99 @@
+import { resolveAdminGroup } from '../plugin-contract/admin.js';
+export const DEFAULT_APPROVALS_SLUG = 'approvals';
+/**
+ * Builds the approvals collection config. The collection is read-mostly:
+ * `create` is system-only (the plugin's tools mint records via the local
+ * API), `update` is admin-only (so a stuck pending record can be corrected),
+ * `delete` is denied (audit trail must remain).
+ */
+export function createApprovalsCollection(options) {
+    const slug = options.slug ?? DEFAULT_APPROVALS_SLUG;
+    const usersSlug = options.usersSlug ?? 'users';
+    return {
+        slug,
+        admin: {
+            ...resolveAdminGroup(options.admin),
+            useAsTitle: 'targetTitle',
+            defaultColumns: ['targetTitle', 'status', 'requestedBy', 'requestedAt', 'expiresAt'],
+            description: 'Approval workflow state. Mostly read-only here; changes come from approval actions.',
+        },
+        access: {
+            read: ({ req }) => {
+                const roles = req.user?.['roles'] ?? [];
+                return roles.includes('admin') || roles.includes('editor') || roles.includes('approver');
+            },
+            create: () => false,
+            update: ({ req }) => (req.user?.['roles'] ?? []).includes('admin'),
+            delete: () => false,
+        },
+        fields: [
+            // Target
+            { name: 'targetCollection', type: 'text', required: true },
+            { name: 'targetId', type: 'text', required: true },
+            { name: 'targetTitle', type: 'text', required: true },
+            {
+                name: 'targetVersion',
+                type: 'text',
+                required: true,
+                admin: {
+                    description: 'Hash of the document content at request time. Any content change invalidates the approval.',
+                },
+            },
+            { name: 'previewUrl', type: 'text' },
+            // Request
+            { name: 'requestedBy', type: 'relationship', relationTo: usersSlug, required: true },
+            {
+                name: 'requestedAt',
+                type: 'date',
+                required: true,
+                defaultValue: () => new Date().toISOString(),
+            },
+            { name: 'requestReason', type: 'textarea' },
+            { name: 'changesSummary', type: 'textarea', required: true },
+            {
+                name: 'approverGroups',
+                type: 'select',
+                hasMany: true,
+                required: true,
+                options: options.groupSlugs.map((s) => ({ label: s, value: s })),
+            },
+            // Decision
+            {
+                name: 'status',
+                type: 'select',
+                required: true,
+                defaultValue: 'pending',
+                options: [
+                    { label: 'Pending', value: 'pending' },
+                    { label: 'Granted', value: 'granted' },
+                    { label: 'Declined', value: 'declined' },
+                    { label: 'Changes requested', value: 'changes-requested' },
+                    { label: 'Expired', value: 'expired' },
+                ],
+            },
+            { name: 'decidedBy', type: 'relationship', relationTo: usersSlug },
+            { name: 'decidedAt', type: 'date' },
+            { name: 'decisionNotes', type: 'textarea' },
+            // Workflow state
+            {
+                name: 'notifiedApprovers',
+                type: 'json',
+                defaultValue: [],
+                admin: { description: 'IDs of users notified for this request.' },
+            },
+            { name: 'expiresAt', type: 'date', required: true },
+            {
+                name: 'consumedTokens',
+                type: 'json',
+                defaultValue: [],
+                admin: { description: 'Action tokens already consumed; prevents replay.' },
+            },
+        ],
+        indexes: [
+            { fields: ['targetCollection', 'targetId', 'status'] },
+            { fields: ['status', 'expiresAt'] },
+            { fields: ['requestedBy', 'requestedAt'] },
+        ],
+    };
+}
+//# sourceMappingURL=collection.js.map

package/dist/approvals/collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.js","sourceRoot":"","sources":["../../src/approvals/collection.ts"],"names":[],"mappings":"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"}