@erclx/canon 5.64.0 → 5.66.0

package/src/commands/labels.ts

@@ -14,9 +14,10 @@ import {
 } from '@/labels/density'
 import { resolveScanInput } from '@/labels/event'
 import { checkTitleFormat, type TitleFormatIssue } from '@/labels/format'
-import { MAP_REL } from '@/labels/map'
+import { MAP_REL, readLabelMap } from '@/labels/map'
 import { isReleasePullRequest, scanPhaseLabels } from '@/labels/phase'
 import { checkSections } from '@/labels/sections'
+import { missingLabels } from '@/labels/sync'
 import { BAN_SETS } from '@/markdown/bans'
 import { bodyLines, scanBans } from '@/markdown/scan'
 import { intro, logInfo, logStep, logWarn, outro, plural } from '@/cli/ui'
@@ -33,6 +34,12 @@ interface ApplyOptions extends AuditOptions {
 
 type ApplyRefusal = 'bad-number' | 'no-branch' | 'gh-failed' | 'head-mismatch'
 
+interface SyncOptions {
+  readonly root?: string
+  readonly check?: boolean
+  readonly json?: boolean
+}
+
 const GH_TIMEOUT_MS = 30_000
 
 interface ScanOptions {
@@ -187,6 +194,48 @@ export function register(program: Command): void {
       process.exitCode = await runApply(number, opts)
     })
 
+  labels
+    .command('sync')
+    .description(
+      'Create on the remote each label the map names that it lacks, never editing or deleting one',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--check', 'Report the labels missing and write nothing')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Reads the label names under [domains] in ${MAP_REL}, reads the remote's`,
+        'labels over REST, and creates each one the remote lacks. A label already',
+        'on the remote is left as it is, and one the map does not name is never',
+        'touched. A project declaring no map creates nothing and exits 0.',
+        '',
+        'Run it once after installing a map and again after adding a row, so',
+        '`canon labels apply` finds every label it earns.',
+        '',
+        'Record: labels, present, created, missing, failed',
+        '',
+        'Exit codes:',
+        '  0  the remote carries every label the map names after the run',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  labels are still missing, being any under --check, or a failed',
+        '     create otherwise',
+        '',
+        'Reasons:',
+        '  gh-failed  the remote labels could not be read, so nothing was written',
+        '',
+        'Examples:',
+        '  canon labels sync',
+        '  canon labels sync --check --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: SyncOptions) => {
+      process.exitCode = await runSync(opts)
+    })
+
   labels
     .command('scan')
     .description(
@@ -544,9 +593,7 @@ async function runApply(number: string, opts: ApplyOptions): Promise<number> {
   }
 
   for (const label of diff.missingOnRemote) {
-    logWarn(
-      `${label} is not on the remote. Create it with: gh label create ${label}`,
-    )
+    logWarn(`${label} is not on the remote. Create it with: canon labels sync`)
   }
   for (const label of failed) logWarn(`Label apply failed: ${label}`)
 
@@ -577,6 +624,107 @@ async function runApply(number: string, opts: ApplyOptions): Promise<number> {
   return owed.length === 0 ? 0 : 2
 }
 
+async function runSync(opts: SyncOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+  const isCheck = opts.check ?? false
+
+  intro('canon labels sync')
+
+  const map = readLabelMap(root)
+
+  if (map.kind === 'refused' && map.reason === 'no-map') {
+    logStep('Labels')
+    logInfo(REFUSALS['no-map'])
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          reason: 'no-map',
+          labels: [],
+          present: [],
+          created: [],
+          missing: [],
+          failed: [],
+        })}\n`,
+      )
+    }
+    return 0
+  }
+
+  const refuse = (reason: LabelAuditRefusal | 'gh-failed'): number => {
+    const message =
+      reason === 'gh-failed'
+        ? 'gh could not read the remote labels, so nothing was written.'
+        : REFUSALS[reason]
+    logStep('Refused')
+    logWarn(message)
+    outro()
+    if (emitJson) {
+      process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
+    }
+    return 1
+  }
+
+  if (map.kind === 'refused') return refuse(map.reason)
+
+  const remoteRaw = await gh(root, [
+    'api',
+    '--paginate',
+    'repos/{owner}/{repo}/labels',
+    '--jq',
+    '.[].name',
+  ])
+  if (remoteRaw === null) return refuse('gh-failed')
+
+  const labels = map.domains.map((row) => row.label)
+  const present = nonEmptyLines(remoteRaw)
+  const toCreate = missingLabels(labels, present)
+
+  const created: string[] = []
+  const failed: string[] = []
+
+  if (!isCheck) {
+    for (const label of toCreate) {
+      const wrote = await gh(root, [
+        'api',
+        '-X',
+        'POST',
+        'repos/{owner}/{repo}/labels',
+        '-f',
+        `name=${label}`,
+        '--silent',
+      ])
+      if (wrote === null) failed.push(label)
+      else created.push(label)
+    }
+  }
+
+  const missing = toCreate.filter((label) => !created.includes(label))
+
+  logStep('Labels')
+  logInfo(labels.join(', '))
+
+  if (isCheck) {
+    logStep(missing.length === 0 ? 'Nothing missing' : 'Missing')
+    for (const label of missing) logWarn(label)
+  } else {
+    logStep('Created')
+    logInfo(created.length === 0 ? 'no label was created' : created.join(', '))
+  }
+  for (const label of failed) logWarn(`Label create failed: ${label}`)
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ labels, present, created, missing, failed })}\n`,
+    )
+  }
+
+  return missing.length === 0 ? 0 : 2
+}
+
 /**
  * Reads `--closes` as the issues the body must close. Undefined when the flag
  * is absent, which skips the check, and a message when the value is neither

package/src/commands/pr.ts

@@ -74,6 +74,7 @@ import {
   readBaseStanding,
   readChangedPaths,
 } from '@/pr/lift'
+import { close, type CloseApi, type CloseRefusal } from '@/pr/close'
 import {
   merge,
   type MergeApi,
@@ -92,6 +93,7 @@ import {
 } from '@/pr/drive-copy'
 import { machineListenerReader } from '@/listeners/machine'
 import { loadPaintedPatterns } from '@/pr/painted'
+import { LOCAL_CONFIG_REL, readHealthPaths } from '@/pr/health'
 import {
   dropAddressLine,
   maskLocalAddress,
@@ -174,6 +176,12 @@ interface MergeCommandOptions extends ReadOptions {
   readonly dryRun?: boolean
 }
 
+interface CloseCommandOptions extends ReadOptions {
+  readonly reasonFile?: string
+  readonly head?: string
+  readonly keepBranch?: boolean
+}
+
 interface ReviewStateOptions extends ReadOptions {
   readonly wait?: string
 }
@@ -244,9 +252,15 @@ const AMBIGUOUS_PULL =
 /** How long the probe waits on a listener before reading it as not a server. */
 const LOCAL_PROBE_TIMEOUT_MS = 2_000
 
-const LOCAL_REFUSALS: Record<LocalRefusal | 'gh-failed', string> = {
+const LOCAL_REFUSALS: Record<
+  LocalRefusal | 'invalid-config' | 'gh-failed',
+  string
+> = {
   'no-server':
     'Nothing listening inside this worktree served an HTML page. Start the dev server here and re-run to get a link.',
+  unhealthy:
+    'A page answered inside this worktree, but a health path it declares failed. Start what the page reaches and re-run to get a link.',
+  'invalid-config': `${LOCAL_CONFIG_REL} cannot be read, so no health path was checked and no link is given. Fix or delete it and re-run.`,
   'no-listener-reader':
     'This machine offers neither lsof nor /proc, so no listening socket could be read. Nothing is posted.',
   'gh-failed':
@@ -991,6 +1005,60 @@ export function register(program: Command): void {
       process.exitCode = await runMerge(number, opts)
     })
 
+  pr.command('close')
+    .description(
+      'Close a pull request unmerged, posting the reason first and deleting its head branch',
+    )
+    .argument('<number>', 'Pull request to close')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--reason-file <path>', 'Closing comment to post, required')
+    .option(
+      '--head <branch>',
+      'Head branch the pull request must carry, defaulting to the current branch',
+    )
+    .option('--keep-branch', 'Leave the head branch in place')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'The reason is required, so a pull request this verb closes always says',
+        'why. It is checked before anything is read: banned characters, phase',
+        'labels, board references, session links, and density measured on the',
+        'reason itself. A finding refuses reason-unpublishable with the findings',
+        'in the record.',
+        '',
+        'Then the pull request is read and must be open with the head --head',
+        'names. The comment posts first, then the close, then the branch',
+        'delete, so a failure part way leaves a comment on an open pull request',
+        'rather than a close with no reason. A failed delete never fails the',
+        'close, and a head in another repository is never deleted.',
+        '',
+        'Record: number, commentUrl, branch (deleted, kept, fork, delete-failed),',
+        'findings on a reason-unpublishable refusal',
+        '',
+        'Reasons:',
+        '  closed',
+        '  no-reason, reason-unreadable, reason-unpublishable, no-head,',
+        '  gh-failed, pull-closed, head-mismatch, comment-failed, close-failed',
+        '',
+        'Every call is REST, never `gh pr close`, which runs on GraphQL.',
+        '',
+        'Exit codes:',
+        '  0  closed',
+        '  1  refused, with the reason in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr close 1341 --reason-file reason.md --json',
+        '  canon pr close 1341 --reason-file reason.md --head feat/old --keep-branch',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string, opts: CloseCommandOptions) => {
+      process.exitCode = await runClose(number, opts)
+    })
+
   pr.command('preview')
     .description(
       "Deploy the pull request's branch to a Cloudflare Pages preview and report its address",
@@ -1090,6 +1158,13 @@ export function register(program: Command): void {
         'port serving an HTML page is reported, which skips a test runner or a',
         'reload socket answering in the same tree.',
         '',
+        'A project can declare paths the page must also serve, in',
+        'canon/config/local.toml as health = ["/api/health"]. Each is requested',
+        "on the page's own port, redirects followed, and only a final 2xx",
+        'passes. A page failing one is skipped for the next page port, and the',
+        "refusal names the lowest page port's first failing path. An absent",
+        'file or an empty list checks the page alone.',
+        '',
         'A process in a sibling worktree, in the main checkout seen from a',
         'linked worktree, or in a linked worktree seen from the main checkout',
         'is never reported, since its server shows another branch. Sockets are',
@@ -1112,6 +1187,11 @@ export function register(program: Command): void {
         '  ok                  a page answered, with its address in `url`',
         '  no-server           nothing inside this worktree served a page',
         '  no-listener-reader  neither lsof nor /proc is available',
+        '  unhealthy           a page answered but a declared health path did',
+        '                      not, with `port`, `path`, and `status`, which',
+        '                      is null on a timeout',
+        '  invalid-config      canon/config/local.toml is not valid TOML, or',
+        '                      health is not a list of paths starting with /',
         '  removed             --remove dropped the line',
         '  no-comment          --remove found no marked comment, a no-op',
         '  no-line             --remove found no address line, a no-op',
@@ -3005,6 +3085,19 @@ function machineLocalRunner(): LocalRunner {
         return false
       }
     },
+    // The final status after redirects, so a login bounce ending on a 3xx or
+    // a 4xx fails rather than reading as the backend answering.
+    async check(port, path) {
+      try {
+        const response = await fetch(`http://localhost:${port}${path}`, {
+          signal: AbortSignal.timeout(LOCAL_PROBE_TIMEOUT_MS),
+        })
+        await response.body?.cancel()
+        return response.status
+      } catch {
+        return null
+      }
+    },
   }
 }
 
@@ -3025,7 +3118,35 @@ async function runLocal(opts: LocalOptions): Promise<number> {
   intro('canon pr local')
 
   const worktree = await resolveWorktreeRoot(root)
-  const result = await findLocalServer(worktree, machineLocalRunner())
+  const declaration = readHealthPaths(worktree)
+  if (declaration.kind === 'invalid') {
+    return refuseWith(
+      'invalid-config',
+      `${declaration.reason}. ${LOCAL_REFUSALS['invalid-config']}`,
+      emitJson,
+      root,
+    )
+  }
+
+  const result = await findLocalServer(
+    worktree,
+    machineLocalRunner(),
+    declaration.kind === 'paths' ? declaration.paths : [],
+  )
+  if (result.kind === 'refused' && result.reason === 'unhealthy') {
+    const { port, path, status } = result
+    const answer =
+      status === null
+        ? `gave no answer within ${LOCAL_PROBE_TIMEOUT_MS / 1000} seconds`
+        : `answered ${status}`
+    return refuseWith(
+      'unhealthy',
+      `${LOCAL_REFUSALS.unhealthy} ${path} on http://localhost:${port} ${answer}.`,
+      emitJson,
+      root,
+      { port, path, status },
+    )
+  }
   if (result.kind === 'refused') {
     return refuseWith(
       result.reason,
@@ -4394,6 +4515,146 @@ async function runDriveCopy(
   return 0
 }
 
+type CloseCommandRefusal = 'reason-unreadable' | 'no-head'
+
+const CLOSE_REFUSALS: Record<CloseRefusal | CloseCommandRefusal, string> = {
+  'no-reason':
+    'No closing reason was given. Write it to a file and pass --reason-file.',
+  'reason-unreadable': 'The --reason-file could not be read.',
+  'reason-unpublishable':
+    'The reason carries text a reader on the remote cannot use or that breaks the density limits. The findings are in the record.',
+  'no-head':
+    'This checkout is on no branch, so pass --head with the branch the pull request carries.',
+  'gh-failed': 'gh could not read the pull request, so nothing was written.',
+  'pull-closed': 'The pull request is already closed.',
+  'head-mismatch':
+    'The pull request carries another head branch than the one expected. Nothing was written to it.',
+  'comment-failed':
+    'The closing comment did not post, so the pull request was left open.',
+  'close-failed':
+    'The comment posted but the close was refused, so the pull request is still open. Close it by hand or re-run.',
+}
+
+function closeApi(root: string, number: string): CloseApi {
+  return {
+    readPull: async () => {
+      const stdout = await gh(root, [
+        'api',
+        `repos/{owner}/{repo}/pulls/${number}`,
+      ])
+      if (stdout === null) return undefined
+      try {
+        const row = JSON.parse(stdout) as RestPull
+        if (typeof row.head?.ref !== 'string') return undefined
+        const headRepo = row.head.repo?.full_name
+        return {
+          isOpen: row.state === 'open',
+          branch: row.head.ref,
+          isFork:
+            headRepo === undefined || headRepo !== row.base?.repo?.full_name,
+        }
+      } catch {
+        return undefined
+      }
+    },
+    postComment: async (body) => {
+      const url = await gh(root, [
+        'api',
+        '-X',
+        'POST',
+        `repos/{owner}/{repo}/issues/${number}/comments`,
+        '-f',
+        `body=${body}`,
+        '--jq',
+        '.html_url',
+      ])
+      return url === null || url.trim() === '' ? undefined : url.trim()
+    },
+    patchClosed: async () =>
+      (await gh(root, [
+        'api',
+        '-X',
+        'PATCH',
+        `repos/{owner}/{repo}/pulls/${number}`,
+        '-f',
+        'state=closed',
+        '--silent',
+      ])) !== null,
+    deleteBranch: async (branch) =>
+      (await gh(root, [
+        'api',
+        '-X',
+        'DELETE',
+        `repos/{owner}/{repo}/git/refs/heads/${encodeURIComponent(branch)}`,
+        '--silent',
+      ])) !== null,
+  }
+}
+
+async function runClose(
+  number: string,
+  opts: CloseCommandOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon pr close')
+
+  const refuseClose = (
+    reason: CloseRefusal | CloseCommandRefusal,
+    extra: Record<string, unknown> = {},
+  ): number =>
+    refuseWith(reason, CLOSE_REFUSALS[reason], emitJson, root, {
+      number: Number(number),
+      ...extra,
+    })
+
+  if (opts.reasonFile === undefined) return refuseClose('no-reason')
+  let reason: string
+  try {
+    reason = await readFile(resolve(root, opts.reasonFile), 'utf8')
+  } catch {
+    logWarn(`Could not read ${opts.reasonFile}`)
+    return refuseClose('reason-unreadable')
+  }
+
+  let head = opts.head
+  if (head === undefined) {
+    const branch = await $`git -C ${root} symbolic-ref --short -q HEAD`
+      .env(gitEnv())
+      .quiet()
+      .nothrow()
+    head = branch.exitCode === 0 ? branch.text().trim() : ''
+    if (head === '') return refuseClose('no-head')
+  }
+
+  const record = await close(closeApi(root, number), {
+    number: Number(number),
+    reason,
+    head,
+    isKeepBranch: opts.keepBranch ?? false,
+  })
+
+  if (!record.isOk) {
+    return refuseClose(record.reason as CloseRefusal, {
+      ...(record.commentUrl !== undefined && { commentUrl: record.commentUrl }),
+      ...(record.findings !== undefined && { findings: record.findings }),
+    })
+  }
+
+  logStep('Closed')
+  logInfo(`#${record.number} closed, branch ${record.branch}`)
+  if (record.branch === 'delete-failed') {
+    logWarn(`The branch ${head} could not be deleted. Delete it by hand.`)
+  }
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, ...record })}\n`)
+  }
+  return 0
+}
+
 function refuseWith(
   reason: string,
   message: string,