@erclx/canon 5.65.0 → 5.67.0

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,
@@ -82,16 +83,15 @@ import {
   type MergeRequest,
 } from '@/pr/merge'
 import { listWorktrees } from '@/git/worktree'
+import { branchSlug, buildDriveCopy, loadPreviewConfig } from '@/pr/drive-copy'
 import {
-  branchSlug,
-  buildDriveCopy,
   changedSince,
-  loadPreviewConfig,
   readWorktreeStatus,
   type StatusEntry,
-} from '@/pr/drive-copy'
+} from '@/git/status'
 import { machineListenerReader } from '@/listeners/machine'
 import { loadPaintedPatterns } from '@/pr/painted'
+import { LOCAL_CONFIG_REL, readHealthPaths } from '@/pr/health'
 import {
   dropAddressLine,
   maskLocalAddress,
@@ -174,6 +174,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 +250,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 +1003,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 +1156,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 +1185,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',
@@ -1226,18 +1304,28 @@ export function register(program: Command): void {
       [
         '',
         'A project names what its preview writes in',
-        '`canon/config/preview.json` as `{ "writes": [path], "env": "<NAME>" }`.',
+        '`canon/config/preview.json` as',
+        '`{ "writes": [path], "keep": [path], "env": "<NAME>" }`.',
         'Each `writes` path is relative to the worktree, and `env`, defaulting',
         'to `CANON_PREVIEW_ROOT`, is the variable the server reads for the copy',
         'root. The server resolves each declared path under that root.',
         '',
+        'Each `keep` path sits below a `writes` path, never equal to one, and',
+        'names state the running server owns there, such as a run file. A',
+        "rebuild leaves it in the copy and never copies the worktree's own, so",
+        'list it for a server that writes under a declared path. The key is',
+        'optional.',
+        '',
         'The copy lives at `.canon/tmp/pr/review-ui/<slug>/board/` at the main',
         'worktree root, where `<slug>` is the branch with a leading type',
         'segment dropped and each `/` made `-`. With a number the branch is the',
         "pull request's head, and without one it is the checkout's, so the",
         'worker starting its server before a pull request exists and the',
         'reviewer naming the number land on one copy. Every run but --check',
-        "rebuilds it from the worktree, dropping the last pass's drives.",
+        "resets each declared path from the worktree, dropping the last pass's",
+        'drives, and leaves the rest of the copy root and each `keep` path as',
+        'they are. A page added only to the copy, inside a declared path, is',
+        'wiped.',
         '',
         '--baseline records `git status` for the worktree under',
         '`.canon/tmp/pr/review-ui/<number>/`, and --check reports each path',
@@ -3005,6 +3093,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 +3126,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,
@@ -4364,6 +4493,7 @@ async function runDriveCopy(
       target.worktree,
       copyRoot,
       config.config.writes,
+      config.config.keep,
     )
     logStep('Copied')
     logInfo(`${config.config.env}=${copyRoot}`)
@@ -4394,6 +4524,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,

package/src/commands/records.ts

@@ -34,6 +34,7 @@ import {
   type StructureFinding,
   validateRecords,
 } from '@/records/validate'
+import type { SessionMapLength } from '@/records/session-map'
 import {
   intro,
   logError,
@@ -92,7 +93,7 @@ export function register(program: Command): void {
     .argument('<kind>', `Record folder: ${RECORD_KINDS.join(', ')}`)
     .argument(
       '[record]',
-      'One plan stem or folder slug, narrowing both findings and structure to it',
+      'One plan stem, folder slug, or session map stem, narrowing the report to it',
     )
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
@@ -105,6 +106,7 @@ export function register(program: Command): void {
         '  plans       filename, required sections, and the suggested-and-answer contract',
         '  groundwork  README and current-state files, numbering, dating, and a half-closed track',
         '  intake      overview file, numbering, dating, and the four bullets every item carries',
+        "  sessions    each session map's words against its cap, under `length` and never in the exit",
         '',
         'Structure, under `structure` and never in the exit:',
         "  S1 to S5 from the plan standard, read on plans, a track's README and",
@@ -128,6 +130,7 @@ export function register(program: Command): void {
         '  canon records validate plans',
         '  canon records validate plans feature-records-by-heading',
         '  canon records validate intake --json',
+        '  canon records validate sessions session-orchestrator',
         '',
       ].join('\n'),
     )
@@ -828,6 +831,7 @@ function report(
         records: outcome.records,
         findings: outcome.findings,
         structure: outcome.structure,
+        ...(outcome.length && { length: outcome.length }),
       })}\n`,
     )
   } else {
@@ -846,6 +850,14 @@ function report(
       logStep('Structure, reported and never in the exit')
       for (const entry of outcome.structure) logInfo(describeStructure(entry))
     }
+
+    if (outcome.length) {
+      logStep('Length, reported and never in the exit')
+      for (const entry of outcome.length) {
+        const log = entry.over ? logWarn : logInfo
+        log(describeLength(entry))
+      }
+    }
     outro()
   }
 
@@ -857,6 +869,11 @@ function describe(found: Finding): string {
   return `${scope}${found.subject} ${found.message}`
 }
 
+function describeLength(entry: SessionMapLength): string {
+  const verdict = entry.over ? 'over the cap' : 'within the cap'
+  return `${entry.record}: ${entry.words} of ${entry.cap} words, ${verdict}`
+}
+
 function describeStructure(entry: StructureFinding): string {
   const scope = entry.record === entry.subject ? '' : `${entry.record}/`
   return `${entry.criterion} ${scope}${entry.subject}:${entry.line} ${entry.message}`