@erclx/canon 5.12.0 → 5.14.0

package/src/commands/pr.ts

@@ -36,6 +36,19 @@ import {
   readOwed,
   renderEvidenceBody,
 } from '@/pr/evidence'
+import {
+  dropFrames,
+  FRAMES_BRANCH,
+  type FramesApi,
+  type FramesRefusal,
+  frameLink,
+  isFrameHead,
+  isFramePass,
+  pruneFrames,
+  pushFrame,
+  readFrame,
+  type TreeEntry,
+} from '@/pr/frames'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
 import {
   findLocalServer,
@@ -50,6 +63,8 @@ import { KEY_CHANGES } from '@/pr/paths'
 import {
   findDeployWorkflow,
   mintPreview,
+  type PreviewHeadReason,
+  readPreviewHead,
   type PreviewRefusal,
   type PreviewRunner,
   type RunRow,
@@ -114,8 +129,58 @@ const LOCAL_REFUSALS: Record<LocalRefusal | 'gh-failed', string> = {
     'gh could not read or edit the marked comment on this pull request.',
 }
 
+interface FramesOptions extends ReadOptions {
+  readonly add?: string
+  readonly box?: string
+  readonly head?: string
+  readonly pass?: string
+  readonly drop?: boolean
+  readonly prune?: string
+}
+
+type FramesCommandRefusal =
+  | FramesRefusal
+  | 'bad-mode'
+  | 'no-number'
+  | 'bad-box'
+  | 'bad-head'
+  | 'bad-pass'
+  | 'bad-days'
+  | 'unreadable-frame'
+  | 'read-only'
+  | 'gh-missing'
+  | 'gh-failed'
+  | 'no-object-head'
+
+const FRAMES_REFUSALS: Record<FramesCommandRefusal, string> = {
+  'bad-mode':
+    'Pass exactly one of --add, --drop, or --prune. --prune reads every pull request on the branch, so it takes no number.',
+  'no-number':
+    '--add and --drop write for one pull request, so name its number.',
+  'bad-box':
+    '--add takes --box <n>, a positive whole number naming the checklist box.',
+  'bad-head':
+    '--head takes a commit sha, 7 to 40 lowercase hex characters. A branch name or a path would file the frame under a folder that names no commit.',
+  'bad-pass':
+    '--add takes --pass <stamp>, the instant the pass started in compact UTC such as 20261002T154450Z, so a second pass never replaces an earlier one.',
+  'bad-days': '--prune takes a positive whole number of days.',
+  'unreadable-frame':
+    'The file named by --add is missing, empty, or not a PNG, so it would embed as a broken image. Nothing is pushed.',
+  'read-only': `GitHub refused the write to ${FRAMES_BRANCH}. The token cannot write this repository, which is what a fork pull request's workflow token gets, so describe the frame in words instead.`,
+  'gh-missing':
+    'gh is not on the path, so the branch could not be read or written.',
+  'gh-failed':
+    'gh could not answer for this repository or pull request, so no link could be built.',
+  'no-object-head':
+    'The pull request object reported no head commit and no --head was passed, so the frame has no head to file under.',
+  'unreadable-tip': `The ${FRAMES_BRANCH} branch could not be read, so nothing was written. A missing branch is not this, since an add creates it.`,
+  'push-failed': `A write to ${FRAMES_BRANCH} failed partway. The ref did not move, so the branch is as it was.`,
+  'ref-conflict': `Another writer kept moving ${FRAMES_BRANCH} through every attempt, so the add gave up. Re-run it.`,
+}
+
 interface PreviewOptions extends ReadOptions {
   readonly timeout?: string
+  readonly check?: boolean
 }
 
 /** How long `canon pr preview` waits on the deploy run by default, in minutes. */
@@ -124,8 +189,13 @@ const PREVIEW_TIMEOUT_MINUTES = 15
 /** How often the deploy run is re-read while waiting on it. */
 const PREVIEW_POLL_MS = 15_000
 
-const PREVIEW_REFUSALS: Record<PreviewRefusal | 'bad-timeout', string> = {
+const PREVIEW_REFUSALS: Record<
+  PreviewRefusal | 'bad-timeout' | 'check-timeout',
+  string
+> = {
   'bad-timeout': '--timeout takes a positive number of minutes.',
+  'check-timeout':
+    '--check only reads the deploy runs and waits on nothing, so it takes no --timeout.',
   'no-deploy':
     'No workflow under .github/workflows/ runs pages deploy and carries a workflow_dispatch trigger, so there is nothing to dispatch.',
   // biome-ignore lint/suspicious/noTemplateCurlyInString: a workflow expression, not a template
@@ -141,6 +211,17 @@ const PREVIEW_REFUSALS: Record<PreviewRefusal | 'bad-timeout', string> = {
     'The deploy run did not finish inside the bound. The preview may still land. Re-run with a longer --timeout or read the run.',
 }
 
+/** What a reader does about each way `canon pr preview --check` answers. */
+const PREVIEW_HEAD_NOTES: Record<PreviewHeadReason, string> = {
+  fresh: 'The newest successful deploy built the branch tip.',
+  stale:
+    'The newest successful deploy built an earlier head than the branch tip. Mint again with canon pr preview before driving the preview.',
+  building:
+    'A deploy of the branch tip is still running. Wait for it rather than minting again.',
+  'no-build':
+    'No successful deploy exists for this branch. Mint one with canon pr preview.',
+}
+
 /** Why a head-sensitive read produced no answer about a commit. */
 type PullRefusal =
   | 'gh-missing'
@@ -528,8 +609,11 @@ export function register(program: Command): void {
     .option('--json', 'Add a machine-readable record on stdout')
     .option(
       '--timeout <minutes>',
-      'How long to wait on the deploy run',
-      String(PREVIEW_TIMEOUT_MINUTES),
+      `How long to wait on the deploy run (default ${PREVIEW_TIMEOUT_MINUTES})`,
+    )
+    .option(
+      '--check',
+      'Read whether the newest successful deploy built the branch tip, dispatching nothing',
     )
     .addHelpText(
       'after',
@@ -554,13 +638,22 @@ export function register(program: Command): void {
         '  run-failed  the deploy run finished without succeeding',
         '  timeout     the run did not finish inside --timeout minutes',
         '',
+        'With --check nothing is dispatched or waited on. The newest successful',
+        'workflow_dispatch run is compared with the branch tip read from the remote.',
+        'Read `reason` on the JSON record, with `built`, `tip`, and `runId`:',
+        '  fresh       the newest successful deploy built the tip',
+        '  stale       the newest successful deploy built an earlier head',
+        '  building    a deploy of the tip is still running, so wait',
+        '  no-build    no deploy of this branch has succeeded',
+        '',
         'Exit codes:',
-        '  0  a preview was published',
-        '  1  refused, with the reason on stderr or in the JSON record',
+        '  0  a preview was published, or --check read fresh',
+        '  1  refused, or --check read anything but fresh',
         '',
         'Examples:',
         '  canon pr preview --json',
         '  canon pr preview 1341 --json --timeout 20',
+        '  canon pr preview 1341 --check --json',
         '',
       ].join('\n'),
     )
@@ -628,6 +721,82 @@ export function register(program: Command): void {
           ? await runLocalRemove(number, opts)
           : await runLocal(opts)
     })
+
+  pr.command('frames')
+    .description(
+      `Push a UI review frame to the never-merged ${FRAMES_BRANCH} branch and return its embed link, or drop frames from it`,
+    )
+    .argument(
+      '[number]',
+      'Pull request the frame belongs to, for --add and --drop',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to answer for, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--add <file>', 'Push this PNG as a frame')
+    .option('--box <n>', 'The checklist box the frame shows, with --add')
+    .option(
+      '--head <sha>',
+      "The head the frame was driven at, with --add, defaulting to the pull request's",
+    )
+    .option(
+      '--pass <stamp>',
+      'The instant the pass started, in compact UTC such as 20261002T154450Z, with --add',
+    )
+    .option('--drop', "Rewrite the branch without this pull request's frames")
+    .option(
+      '--prune <days>',
+      'Drop the frames of every pull request closed more than this many days ago',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Writes only refs/heads/${FRAMES_BRANCH}, through the GitHub git data API,`,
+        'so nothing is checked out and no other branch is touched. A frame lands',
+        'at pr-<number>/<short-head>/<pass>/box-<n>.png, and `link` names that',
+        `path on ${FRAMES_BRANCH}, so it survives a rewrite that drops other pull`,
+        'requests and resolves until its own pull request is dropped. The pass',
+        'segment keeps a second pass at one head and box from replacing an image',
+        'an earlier comment shows. The first --add creates the branch.',
+        '',
+        '--drop and --prune write one root commit and force-move the ref,',
+        'since a delete commit would keep every image reachable through history.',
+        'A rewrite that empties the branch deletes it. --prune keeps a pull',
+        'request still open, reopened, closed exactly the given days ago, or one',
+        'whose state could not be read, listing that last kind under `unread`.',
+        '',
+        'Read `reason` on the JSON record:',
+        '  ok                an add pushed, or a drop or prune finished',
+        '  bad-mode          not exactly one of --add, --drop, --prune',
+        '  no-number         --add or --drop named no pull request',
+        '  bad-box           --add without a positive --box',
+        '  bad-head          --head is not 7 to 40 lowercase hex characters',
+        '  bad-pass          --add without a compact UTC --pass stamp',
+        '  bad-days          --prune without a positive number of days',
+        '  unreadable-frame  the --add file is missing, empty, or not a PNG',
+        '  read-only         GitHub refused the write, as on a fork token',
+        '  unreadable-tip    the branch could not be read',
+        '  push-failed       a write failed and the ref did not move',
+        '  ref-conflict      another writer kept moving the ref',
+        '  no-object-head    no head to file the frame under',
+        '  gh-missing        gh is not on the path',
+        '  gh-failed         gh could not answer for the repository',
+        '',
+        'Exit codes:',
+        '  0  pushed, or a drop or prune finished, including one removing nothing',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr frames 1341 --add frames/3.png --box 3 --pass 20261002T154450Z --json',
+        '  canon pr frames 1341 --drop --json',
+        '  canon pr frames --prune 30 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: FramesOptions) => {
+      process.exitCode = await runFrames(number, opts)
+    })
 }
 
 interface PullRequestRead {
@@ -1712,6 +1881,7 @@ async function runEvidence(
         base,
         head: identity.head,
         body,
+        states,
         ...(commentId !== undefined && { commentId }),
         ...carried,
       })}\n`,
@@ -1773,7 +1943,7 @@ function ghPreviewRunner(root: string): PreviewRunner {
         '--limit',
         '20',
         '--json',
-        'databaseId,status,conclusion',
+        'databaseId,status,conclusion,headSha,createdAt',
       ])
       if (out === null) return undefined
       try {
@@ -1789,7 +1959,7 @@ function ghPreviewRunner(root: string): PreviewRunner {
           'view',
           String(id),
           '--json',
-          'databaseId,status,conclusion',
+          'databaseId,status,conclusion,headSha,createdAt',
         ]),
       )
     },
@@ -1810,6 +1980,15 @@ async function runPreview(
 
   intro('canon pr preview')
 
+  if (opts.check === true && opts.timeout !== undefined) {
+    return refuseWith(
+      'check-timeout',
+      PREVIEW_REFUSALS['check-timeout'],
+      emitJson,
+      root,
+    )
+  }
+
   const minutes = Number(opts.timeout ?? PREVIEW_TIMEOUT_MINUTES)
   if (!Number.isFinite(minutes) || minutes <= 0) {
     return refuseWith(
@@ -1838,6 +2017,10 @@ async function runPreview(
   }
   const { identity } = read
 
+  if (opts.check === true) {
+    return runPreviewCheck(root, emitJson, pick.path, identity)
+  }
+
   logStep('Deploy')
   logInfo(`${pick.path} on ${identity.branch}`)
 
@@ -1887,6 +2070,62 @@ async function runPreview(
   return 0
 }
 
+/**
+ * Reads the built head against the tip. The tip comes from the remote rather
+ * than `headRefOid`, which lags a push, so a build of the last head reads stale
+ * the moment a newer commit lands.
+ */
+async function runPreviewCheck(
+  root: string,
+  emitJson: boolean,
+  workflow: string,
+  identity: { readonly branch: string; readonly number?: number },
+): Promise<number> {
+  const resolved = await resolveTip(identity.branch, refReader(root))
+  if (resolved.kind === 'refused') {
+    return refuseWith(
+      resolved.reason,
+      PULL_REFUSALS[resolved.reason],
+      emitJson,
+      root,
+    )
+  }
+
+  const reading = await readPreviewHead(ghPreviewRunner(root), {
+    workflow,
+    branch: identity.branch,
+    tip: resolved.tip,
+  })
+  if (reading.reason === 'gh-failed') {
+    return refuseWith(
+      'gh-failed',
+      PREVIEW_REFUSALS['gh-failed'],
+      emitJson,
+      root,
+    )
+  }
+
+  logStep('Preview head')
+  logInfo(PREVIEW_HEAD_NOTES[reading.reason])
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        ...(identity.number !== undefined && { number: identity.number }),
+        reason: reading.reason,
+        message: PREVIEW_HEAD_NOTES[reading.reason],
+        workflow,
+        tip: reading.tip,
+        ...(reading.built !== undefined && { built: reading.built }),
+        ...(reading.runId !== undefined && { runId: reading.runId }),
+      })}\n`,
+    )
+  }
+  return reading.reason === 'fresh' ? 0 : 1
+}
+
 async function readText(path: string): Promise<string | undefined> {
   return readFile(path, 'utf8').catch(() => undefined)
 }
@@ -2098,6 +2337,319 @@ async function runLocalRemove(
   return finish('removed', `comment ${commentId}`)
 }
 
+const POSITIVE_WHOLE = /^[1-9]\d*$/
+
+/** One `gh api` call, keeping the HTTP status of a failure so a refused write can be told from a missing ref. */
+type ApiCall =
+  | { readonly ok: true; readonly data: unknown }
+  | { readonly ok: false; readonly status: number | undefined }
+
+type ApiCaller = (
+  method: string,
+  path: string,
+  body?: unknown,
+) => Promise<ApiCall>
+
+/**
+ * Runs `gh api` against the repository's own path, recording every write
+ * GitHub answered 403 or 404, which is how a token without write access
+ * reads, so a failed push can be reported as read-only rather than broken.
+ */
+function ghApiRunner(root: string): {
+  readonly call: ApiCaller
+  readonly refusedWrites: number[]
+} {
+  const refusedWrites: number[] = []
+  const call: ApiCaller = async (method, path, body) => {
+    const args = ['api', '-X', method, `repos/{owner}/{repo}/${path}`]
+    if (body !== undefined) args.push('--input', '-')
+    const result = await execa('gh', args, {
+      cwd: root,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+      reject: false,
+      ...(body !== undefined && { input: JSON.stringify(body) }),
+    })
+    if (result.exitCode !== 0) {
+      const status = /HTTP (\d{3})/.exec(String(result.stderr))?.[1]
+      const code = status === undefined ? undefined : Number(status)
+      if (method !== 'GET' && (code === 403 || code === 404)) {
+        refusedWrites.push(code)
+      }
+      return { ok: false, status: code }
+    }
+    const text = String(result.stdout).trim()
+    try {
+      return { ok: true, data: text === '' ? null : JSON.parse(text) }
+    } catch {
+      return { ok: false, status: undefined }
+    }
+  }
+  return { call, refusedWrites }
+}
+
+function shaOf(data: unknown): string | undefined {
+  if (typeof data !== 'object' || data === null || !('sha' in data)) {
+    return undefined
+  }
+  return typeof data.sha === 'string' ? data.sha : undefined
+}
+
+function isTreeEntry(value: unknown): value is TreeEntry {
+  if (typeof value !== 'object' || value === null) return false
+  const entry = value as Record<string, unknown>
+  return (
+    typeof entry.path === 'string' &&
+    typeof entry.mode === 'string' &&
+    (entry.type === 'blob' || entry.type === 'tree') &&
+    typeof entry.sha === 'string'
+  )
+}
+
+/**
+ * The git data API behind `canon pr frames`. A 422 on a ref write is GitHub
+ * refusing a move that is not a fast-forward, or a create or update on a ref
+ * that already exists or no longer does, which is another writer's doing and
+ * worth a re-read rather than a failure.
+ */
+function ghFramesApi(call: ApiCaller): FramesApi {
+  const ref = `git/refs/heads/${FRAMES_BRANCH}`
+  const refWrite = (result: ApiCall) =>
+    result.ok ? 'ok' : result.status === 422 ? 'conflict' : 'failed'
+  return {
+    async readTip() {
+      const head = await call('GET', `git/ref/heads/${FRAMES_BRANCH}`)
+      if (!head.ok) {
+        return head.status === 404
+          ? { kind: 'missing' }
+          : { kind: 'unreadable' }
+      }
+      const commit = (head.data as { object?: { sha?: unknown } } | null)
+        ?.object?.sha
+      if (typeof commit !== 'string') return { kind: 'unreadable' }
+      const read = await call('GET', `git/commits/${commit}`)
+      const tree = read.ok
+        ? (read.data as { tree?: { sha?: unknown } } | null)?.tree?.sha
+        : undefined
+      return typeof tree === 'string'
+        ? { kind: 'found', commit, tree }
+        : { kind: 'unreadable' }
+    },
+    async listTree(tree) {
+      const read = await call('GET', `git/trees/${tree}`)
+      if (!read.ok) return undefined
+      const entries = (read.data as { tree?: unknown } | null)?.tree
+      return Array.isArray(entries) && entries.every(isTreeEntry)
+        ? entries
+        : undefined
+    },
+    async createBlob(base64) {
+      const made = await call('POST', 'git/blobs', {
+        content: base64,
+        encoding: 'base64',
+      })
+      return made.ok ? shaOf(made.data) : undefined
+    },
+    async createTree(entries, base) {
+      const made = await call('POST', 'git/trees', {
+        tree: entries.map(({ path, mode, type, sha }) => ({
+          path,
+          mode,
+          type,
+          sha,
+        })),
+        ...(base !== undefined && { base_tree: base }),
+      })
+      return made.ok ? shaOf(made.data) : undefined
+    },
+    async createCommit(message, tree, parents) {
+      const made = await call('POST', 'git/commits', {
+        message,
+        tree,
+        parents,
+      })
+      return made.ok ? shaOf(made.data) : undefined
+    },
+    async createRef(commit) {
+      return refWrite(
+        await call('POST', 'git/refs', {
+          ref: `refs/heads/${FRAMES_BRANCH}`,
+          sha: commit,
+        }),
+      )
+    },
+    async moveRef(commit, force) {
+      return refWrite(await call('PATCH', ref, { sha: commit, force }))
+    },
+    async deleteRef() {
+      const gone = await call('DELETE', ref)
+      return gone.ok || gone.status === 422
+    },
+    async readPull(number) {
+      const read = await call('GET', `pulls/${number}`)
+      if (!read.ok) return undefined
+      const row = read.data as { state?: unknown; closed_at?: unknown } | null
+      if (row?.state !== 'open' && row?.state !== 'closed') return undefined
+      return {
+        state: row.state,
+        ...(typeof row.closed_at === 'string' && { closedAt: row.closed_at }),
+      }
+    },
+  }
+}
+
+/** Validates the mode and its arguments before anything reads the network. */
+function framesArgumentRefusal(
+  number: string | undefined,
+  opts: FramesOptions,
+): FramesCommandRefusal | undefined {
+  const modes = [
+    opts.add !== undefined,
+    opts.drop === true,
+    opts.prune !== undefined,
+  ]
+  if (modes.filter(Boolean).length !== 1) return 'bad-mode'
+  if (opts.prune !== undefined) {
+    if (number !== undefined) return 'bad-mode'
+    return POSITIVE_WHOLE.test(opts.prune) ? undefined : 'bad-days'
+  }
+  if (number === undefined || !POSITIVE_WHOLE.test(number)) return 'no-number'
+  if (
+    opts.add !== undefined &&
+    (opts.box === undefined || !POSITIVE_WHOLE.test(opts.box))
+  ) {
+    return 'bad-box'
+  }
+  if (opts.head !== undefined && !isFrameHead(opts.head)) return 'bad-head'
+  if (
+    opts.add !== undefined &&
+    (opts.pass === undefined || !isFramePass(opts.pass))
+  ) {
+    return 'bad-pass'
+  }
+  return undefined
+}
+
+async function readRepoName(root: string): Promise<string | undefined> {
+  const row = await gh(root, ['repo', 'view', '--json', 'nameWithOwner'])
+  if (row === null) return undefined
+  try {
+    const name = (JSON.parse(row) as { nameWithOwner?: unknown }).nameWithOwner
+    return typeof name === 'string' ? name : undefined
+  } catch {
+    return undefined
+  }
+}
+
+async function runFrames(
+  number: string | undefined,
+  opts: FramesOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+  const refuseFrames = (reason: FramesCommandRefusal) =>
+    refuseWith(reason, FRAMES_REFUSALS[reason], emitJson, root)
+
+  intro('canon pr frames')
+
+  const invalid = framesArgumentRefusal(number, opts)
+  if (invalid !== undefined) return refuseFrames(invalid)
+
+  const bytes =
+    opts.add === undefined ? undefined : await readFrame(resolve(opts.add))
+  if (opts.add !== undefined && bytes === undefined) {
+    return refuseFrames('unreadable-frame')
+  }
+
+  if (Bun.which('gh') === null) return refuseFrames('gh-missing')
+  const runner = ghApiRunner(root)
+  const api = ghFramesApi(runner.call)
+  const refuseWrite = (reason: FramesRefusal) =>
+    refuseFrames(
+      reason === 'push-failed' && runner.refusedWrites.length > 0
+        ? 'read-only'
+        : reason,
+    )
+
+  const finish = (
+    record: Record<string, unknown>,
+    lines: readonly string[],
+  ): number => {
+    logStep('Frames')
+    for (const line of lines) logInfo(line)
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ root, reason: 'ok', ...record })}\n`,
+      )
+    }
+    return 0
+  }
+
+  if (opts.prune !== undefined) {
+    const days = Number(opts.prune)
+    const result = await pruneFrames(api, days, new Date())
+    if (result.kind === 'refused') return refuseWrite(result.reason)
+    const { kind: _kind, ...rest } = result
+    return finish({ days, ...rest }, [
+      `removed ${plural(result.removed.length, 'pull request')}`,
+      ...(result.unread.length > 0
+        ? [`kept ${result.unread.map((n) => `#${n}`).join(', ')} unread`]
+        : []),
+    ])
+  }
+
+  const pull = Number(number)
+  if (opts.drop === true) {
+    const result = await dropFrames(api, [pull])
+    if (result.kind === 'refused') return refuseWrite(result.reason)
+    const { kind: _kind, ...rest } = result
+    return finish({ number: pull, ...rest }, [
+      result.removed.length === 0
+        ? `#${pull} holds no frames on ${FRAMES_BRANCH}`
+        : `dropped the frames of #${pull}`,
+    ])
+  }
+
+  const repo = await readRepoName(root)
+  if (repo === undefined) return refuseFrames('gh-failed')
+
+  let head = opts.head
+  if (head === undefined) {
+    const identity = await readIdentity(root, String(pull))
+    if (identity.kind === 'refused') return refuseFrames('gh-failed')
+    head = identity.identity.head
+  }
+  if (head === undefined || head === '') return refuseFrames('no-object-head')
+  if (!isFrameHead(head)) return refuseFrames('bad-head')
+
+  const box = Number(opts.box)
+  const pass = opts.pass ?? ''
+  const result = await pushFrame(api, {
+    number: pull,
+    head,
+    pass,
+    box,
+    bytes: bytes ?? new Uint8Array(),
+  })
+  if (result.kind === 'refused') return refuseWrite(result.reason)
+  const link = frameLink(repo, result.path)
+  return finish(
+    {
+      number: pull,
+      box,
+      head,
+      pass,
+      path: result.path,
+      commit: result.commit,
+      link,
+      created: result.created,
+    },
+    [link],
+  )
+}
+
 /**
  * Frames a refusal on stderr in both modes and puts the record on stdout alone,
  * so an operator reading the terminal sees the reason rather than a command