@erclx/canon 5.48.0 → 5.49.0

package/src/commands/pr.ts

@@ -1,5 +1,5 @@
 import { existsSync, statSync } from 'node:fs'
-import { readFile, realpath } from 'node:fs/promises'
+import { mkdir, readFile, realpath, writeFile } from 'node:fs/promises'
 import { basename, join, resolve } from 'node:path'
 import { $ } from 'bun'
 import type { Command } from 'commander'
@@ -81,10 +81,20 @@ import {
   type MergeRefusal,
   type MergeRequest,
 } from '@/pr/merge'
+import { listWorktrees } from '@/git/worktree'
+import {
+  branchSlug,
+  buildDriveCopy,
+  changedSince,
+  loadPreviewConfig,
+  readWorktreeStatus,
+  type StatusEntry,
+} from '@/pr/drive-copy'
 import { machineListenerReader } from '@/listeners/machine'
 import { loadPaintedPatterns } from '@/pr/painted'
 import {
   dropAddressLine,
+  maskLocalAddress,
   findLocalServer,
   type LocalRefusal,
   type LocalRunner,
@@ -177,6 +187,29 @@ interface TickOptions extends ReadOptions {
   readonly head?: string
 }
 
+interface DriveCopyOptions extends ReadOptions {
+  readonly baseline?: boolean
+  readonly check?: boolean
+}
+
+type DriveCopyRefusal =
+  | 'no-worktree'
+  | 'no-branch'
+  | 'no-baseline'
+  | 'unreadable-tree'
+  | 'bad-flags'
+
+const DRIVE_COPY_REFUSALS: Record<DriveCopyRefusal, string> = {
+  'no-worktree':
+    'No local worktree holds the pull request branch, so there is no tree to copy from or check.',
+  'no-branch':
+    'The checkout holds no branch, so no copy root could be named. Pass the pull request number.',
+  'no-baseline':
+    'No baseline was recorded for this pull request. Run --baseline before --check.',
+  'unreadable-tree': 'git could not read the worktree status.',
+  'bad-flags': '--baseline and --check cannot be combined.',
+}
+
 type TickReason =
   | TickRefusal
   | 'count-mismatch'
@@ -1037,7 +1070,10 @@ export function register(program: Command): void {
     .helpOption('-h, --help', 'Show this help message')
     .option('--root <path>', 'Worktree to read, defaulting to the cwd')
     .option('--json', 'Add a machine-readable record on stdout')
-    .option('--remove', "Drop the evidence comment's preview address line")
+    .option(
+      '--remove',
+      "Drop the evidence comment's preview address line and mask local addresses in UI reviews",
+    )
     .addHelpText(
       'after',
       [
@@ -1060,6 +1096,11 @@ export function register(program: Command): void {
         'and drops the hosted link too because the same close deletes the',
         "branch's preview deployments.",
         '',
+        'It also rewrites the loopback address on the Driven at line of every',
+        'review carrying the review-ui marker to "a local preview", keeping',
+        'the head and the renderer. A hosted address and a code review are',
+        'left alone, and `reviews` on the JSON record counts the rewrites.',
+        '',
         'Read `reason` on the JSON record:',
         '  ok                  a page answered, with its address in `url`',
         '  no-server           nothing inside this worktree served a page',
@@ -1070,7 +1111,8 @@ export function register(program: Command): void {
         '',
         'Refusals, read off `reason`:',
         '  gh-missing  `--remove` needs `gh` and it is not on the path',
-        '  gh-failed   `--remove` could not read or edit the comment',
+        '  gh-failed   `--remove` could not read the thread, or edit the',
+        '              comment or a review, after trying every edit',
         '',
         'Exit codes:',
         '  0  a server was found, or --remove finished, including a no-op',
@@ -1153,6 +1195,83 @@ export function register(program: Command): void {
       process.exitCode = await runTick(number, opts)
     })
 
+  pr.command('drive-copy')
+    .description(
+      "Copy the folders a running preview saves into, so a UI pass drives a throwaway copy, and check the worker's worktree gained no change",
+    )
+    .argument(
+      '[number]',
+      'Pull request whose worktree to read, defaulting to the checkout at --root',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--baseline',
+      "Rebuild the copy, then record the worktree's git status",
+    )
+    .option(
+      '--check',
+      'Report each path changed since the baseline, copying nothing',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'A project names what its preview writes in',
+        '`canon/config/preview.json` as `{ "writes": [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.',
+        '',
+        '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.",
+        '',
+        '--baseline records `git status` for the worktree under',
+        '`.canon/tmp/pr/review-ui/<number>/`, and --check reports each path',
+        'whose status or content changed since, an untracked file included.',
+        'Both run with no config, since a project that saves drives and never',
+        'declared it is the case the check exists for. An edit the worker makes',
+        'during the pass reads as changed too.',
+        '',
+        'Read `reason` on the JSON record:',
+        '  copied     the copy was rebuilt, with `copyRoot`, `env`, `copied`, and',
+        '             `missing` for a declared path the worktree does not hold',
+        '  no-config  the project declares no preview, so nothing was copied',
+        '  clean      --check found no change since the baseline',
+        '  changed    --check found changes, listed in `paths`, exit 1',
+        '',
+        'Refusals, read off `reason`:',
+        '  no-worktree      no local worktree holds the branch, as for a cloud',
+        "                   worker's, so there is no tree to check",
+        '  no-branch        the checkout holds no branch',
+        '  no-baseline      --check ran before any --baseline for this number',
+        '  bad-config       preview.json does not parse or lacks a writes list',
+        '  unsafe-path      a writes path is absolute or climbs with `..`',
+        '  unreadable-tree  git could not read the worktree status',
+        '  bad-flags        --baseline and --check were combined',
+        '  gh-failed, ambiguous-pull, gh-missing',
+        '',
+        'Exit codes:',
+        '  0  copied, no-config, or clean',
+        '  1  changed, or refused, with the reason in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr drive-copy --json',
+        '  canon pr drive-copy 1341 --baseline --json',
+        '  canon pr drive-copy 1341 --check --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: DriveCopyOptions) => {
+      process.exitCode = await runDriveCopy(number, 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`,
@@ -1733,7 +1852,7 @@ async function listReviews(cwd: string, number: string) {
   return listPages<RestReview>(
     cwd,
     `repos/{owner}/{repo}/pulls/${number}/reviews`,
-    'body, commit_id, submitted_at',
+    'id, body, commit_id, submitted_at',
   )
 }
 
@@ -2922,9 +3041,9 @@ async function runLocal(opts: LocalOptions): Promise<number> {
 }
 
 /**
- * Drops the address line on the marked comment. The verb writes here rather
- * than handing a body back, because its caller is a close workflow with no
- * session to post one.
+ * Drops the address line on the marked comment and masks the loopback address
+ * on every UI review. The verb writes here rather than handing a body back,
+ * because its caller is a close workflow with no session to post one.
  */
 async function runLocalRemove(
   number: string | undefined,
@@ -2951,32 +3070,79 @@ async function runLocalRemove(
       root,
     )
   }
-  const comments = await listComments(root, resolved.number)
-  if (comments === undefined) {
+  const [comments, reviews] = await Promise.all([
+    listComments(root, resolved.number),
+    listReviews(root, resolved.number),
+  ])
+  if (comments === undefined && reviews.kind === 'refused') {
     return refuseWith('gh-failed', LOCAL_REFUSALS['gh-failed'], emitJson, root)
   }
 
-  const finish = (reason: string, message: string): number => {
-    logStep(reason === 'removed' ? 'Removed' : 'Skipped')
-    logInfo(message)
-    outro()
-    if (emitJson) {
-      process.stdout.write(`${JSON.stringify({ root, reason })}\n`)
-    }
-    return 0
+  // A refused read on one side still lets the other side's edits land, and
+  // counts as a failure beside them, so one unread listing never strands both.
+  const [evidence, masked] = await Promise.all([
+    comments === undefined
+      ? Promise.resolve<EvidenceRemoval>({ kind: 'failed' })
+      : removeEvidenceAddress(root, comments),
+    reviews.kind === 'refused'
+      ? Promise.resolve({ rewritten: 0, failed: true })
+      : maskUiReviews(root, resolved.number, reviews.rows),
+  ])
+  if (evidence.kind === 'failed' || masked.failed) {
+    return refuseWith(
+      'gh-failed',
+      LOCAL_REFUSALS['gh-failed'],
+      emitJson,
+      root,
+      {
+        reviews: masked.rewritten,
+      },
+    )
+  }
+
+  logStep(evidence.reason === 'removed' ? 'Removed' : 'Skipped')
+  logInfo(evidence.message)
+  logInfo(`${masked.rewritten} UI review addresses masked`)
+  outro()
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ root, reason: evidence.reason, reviews: masked.rewritten })}\n`,
+    )
   }
+  return 0
+}
 
+type EvidenceRemoval =
+  | {
+      readonly kind: 'done'
+      readonly reason: 'removed' | 'no-comment' | 'no-line'
+      readonly message: string
+    }
+  | { readonly kind: 'failed' }
+
+async function removeEvidenceAddress(
+  root: string,
+  comments: readonly { url?: string; body: string }[],
+): Promise<EvidenceRemoval> {
   const commentId = findEvidenceCommentId(comments)
   const marked = comments.find((comment) =>
     comment.url?.endsWith(`#issuecomment-${commentId}`),
   )
   if (commentId === undefined || marked === undefined) {
-    return finish('no-comment', 'No comment carries the evidence marker.')
+    return {
+      kind: 'done',
+      reason: 'no-comment',
+      message: 'No comment carries the evidence marker.',
+    }
   }
 
   const dropped = dropAddressLine(marked.body)
   if (dropped === undefined) {
-    return finish('no-line', 'The evidence comment carries no address line.')
+    return {
+      kind: 'done',
+      reason: 'no-line',
+      message: 'The evidence comment carries no address line.',
+    }
   }
 
   const patched = await gh(root, [
@@ -2987,11 +3153,43 @@ async function runLocalRemove(
     '-f',
     `body=${dropped}`,
   ])
-  if (patched === null) {
-    return refuseWith('gh-failed', LOCAL_REFUSALS['gh-failed'], emitJson, root)
-  }
+  return patched === null
+    ? { kind: 'failed' }
+    : { kind: 'done', reason: 'removed', message: `comment ${commentId}` }
+}
 
-  return finish('removed', `comment ${commentId}`)
+const UI_REVIEW_MARKER = '<!-- review-ui: head='
+
+/**
+ * Masks the loopback address on each review `review-ui` posted, selected by
+ * its marker so a code review quoting a local URL is never edited. Every
+ * update is tried before a refusal is reported, so one refused review leaves
+ * the rest masked.
+ */
+async function maskUiReviews(
+  root: string,
+  number: string,
+  reviews: readonly RestReview[],
+): Promise<{ readonly rewritten: number; readonly failed: boolean }> {
+  const updates = reviews.flatMap((review) => {
+    const body = review.body ?? ''
+    if (review.id === undefined || !body.includes(UI_REVIEW_MARKER)) return []
+    const masked = maskLocalAddress(body)
+    if (masked === undefined) return []
+    return [
+      gh(root, [
+        'api',
+        '-X',
+        'PUT',
+        `repos/{owner}/{repo}/pulls/${number}/reviews/${review.id}`,
+        '-f',
+        `body=${masked}`,
+      ]),
+    ]
+  })
+  const results = await Promise.all(updates)
+  const rewritten = results.filter((stdout) => stdout !== null).length
+  return { rewritten, failed: rewritten < results.length }
 }
 
 const POSITIVE_WHOLE = /^[1-9]\d*$/
@@ -3997,6 +4195,196 @@ function refuse(reason: Refusal, emitJson: boolean, root: string): number {
   return refuseWith(reason, REFUSALS[reason], emitJson, root)
 }
 
+/** The scratch folder `review-ui` writes under, at the main worktree root. */
+const REVIEW_UI_SCRATCH = join('.canon', 'tmp', 'pr', 'review-ui')
+
+type DriveTarget =
+  | {
+      readonly kind: 'found'
+      readonly main: string
+      readonly worktree: string
+      readonly branch: string
+      readonly number: string | undefined
+    }
+  | {
+      readonly kind: 'refused'
+      readonly reason: DriveCopyRefusal | PullRefusal
+    }
+
+/**
+ * The worker's worktree and its branch. A named pull request resolves through
+ * its head ref, since a reviewer runs at the main root on the trunk. With no
+ * number the checkout at `root` answers, and a number is looked up only when
+ * the mode needs one, so a worker can build the copy before its pull request
+ * exists.
+ */
+async function resolveDriveTarget(
+  root: string,
+  number: string | undefined,
+  needsNumber: boolean,
+): Promise<DriveTarget> {
+  const worktrees = await listWorktrees(root)
+  const main = worktrees[0]?.path ?? root
+
+  if (number === undefined) {
+    const toplevel = await resolveWorktreeRoot(root)
+    const realPaths = await Promise.all(
+      worktrees.map((candidate) =>
+        realpath(candidate.path).catch(() => candidate.path),
+      ),
+    )
+    const entry = worktrees[realPaths.indexOf(toplevel)]
+    const branch = entry?.branch ?? null
+    if (branch === null) return { kind: 'refused', reason: 'no-branch' }
+    if (!needsNumber) {
+      return { kind: 'found', main, worktree: toplevel, branch, number }
+    }
+    if (Bun.which('gh') === null) {
+      return { kind: 'refused', reason: 'gh-missing' }
+    }
+    const resolved = await resolvePullNumber(root, undefined)
+    if (resolved.kind === 'refused') return resolved
+    return {
+      kind: 'found',
+      main,
+      worktree: toplevel,
+      branch,
+      number: resolved.number,
+    }
+  }
+
+  if (Bun.which('gh') === null) return { kind: 'refused', reason: 'gh-missing' }
+  const read = await readPull(root, number)
+  if (read.kind === 'refused') return read
+  const headRef = read.row.head?.ref
+  if (headRef === undefined || headRef === '') {
+    return { kind: 'refused', reason: 'no-worktree' }
+  }
+  const entry = worktrees.find((candidate) => candidate.branch === headRef)
+  if (entry === undefined) return { kind: 'refused', reason: 'no-worktree' }
+  return {
+    kind: 'found',
+    main,
+    worktree: entry.path,
+    branch: headRef,
+    number,
+  }
+}
+
+async function runDriveCopy(
+  number: string | undefined,
+  opts: DriveCopyOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+  const baseline = opts.baseline ?? false
+  const check = opts.check ?? false
+
+  intro('canon pr drive-copy')
+
+  const refuse = (
+    reason: DriveCopyRefusal | PullRefusal | string,
+    message: string,
+  ) => refuseWith(reason, message, emitJson, root)
+
+  if (baseline && check) {
+    return refuse('bad-flags', DRIVE_COPY_REFUSALS['bad-flags'])
+  }
+
+  const target = await resolveDriveTarget(root, number, baseline || check)
+  if (target.kind === 'refused') {
+    const reason = target.reason
+    return refuse(
+      reason,
+      reason in DRIVE_COPY_REFUSALS
+        ? DRIVE_COPY_REFUSALS[reason as DriveCopyRefusal]
+        : PULL_REFUSALS[reason as PullRefusal],
+    )
+  }
+
+  const scratch = join(target.main, REVIEW_UI_SCRATCH)
+  const baselinePath =
+    target.number === undefined
+      ? undefined
+      : join(scratch, target.number, 'drive-baseline.json')
+  const emit = (record: Record<string, unknown>) => {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ root, worktree: target.worktree, branch: target.branch, ...record })}\n`,
+      )
+    }
+  }
+
+  if (check && baselinePath !== undefined) {
+    let prior: readonly StatusEntry[]
+    try {
+      prior = JSON.parse(await readFile(baselinePath, 'utf8'))
+    } catch {
+      return refuse('no-baseline', DRIVE_COPY_REFUSALS['no-baseline'])
+    }
+    const current = await readWorktreeStatus(target.worktree)
+    if (current === undefined) {
+      return refuse('unreadable-tree', DRIVE_COPY_REFUSALS['unreadable-tree'])
+    }
+    const paths = changedSince(prior, current)
+    if (paths.length === 0) {
+      logStep('Clean')
+      logInfo(`No change in ${target.worktree} since the baseline.`)
+      outro()
+      emit({ reason: 'clean', paths })
+      return 0
+    }
+    logStep('Changed')
+    for (const path of paths) logWarn(path)
+    outro()
+    emit({ reason: 'changed', paths })
+    return 1
+  }
+
+  const config = loadPreviewConfig(target.worktree)
+  if (config.kind === 'refused') return refuse(config.reason, config.detail)
+
+  let copy: Record<string, unknown>
+  if (config.kind === 'absent') {
+    logStep('No config')
+    logInfo('The project declares no preview writes, so nothing was copied.')
+    copy = { reason: 'no-config' }
+  } else {
+    const copyRoot = join(scratch, branchSlug(target.branch), 'board')
+    const { copied, missing } = buildDriveCopy(
+      target.worktree,
+      copyRoot,
+      config.config.writes,
+    )
+    logStep('Copied')
+    logInfo(`${config.config.env}=${copyRoot}`)
+    for (const path of missing) logWarn(`${path} is not in the worktree`)
+    copy = {
+      reason: 'copied',
+      copyRoot,
+      env: config.config.env,
+      copied,
+      missing,
+    }
+  }
+
+  if (baseline && baselinePath !== undefined) {
+    const status = await readWorktreeStatus(target.worktree)
+    if (status === undefined) {
+      return refuse('unreadable-tree', DRIVE_COPY_REFUSALS['unreadable-tree'])
+    }
+    await mkdir(join(baselinePath, '..'), { recursive: true })
+    await writeFile(baselinePath, `${JSON.stringify(status)}\n`)
+    logStep('Baseline')
+    logInfo(`Recorded ${plural(status.length, 'status line')}.`)
+    copy = { ...copy, baseline: baselinePath }
+  }
+
+  outro()
+  emit(copy)
+  return 0
+}
+
 function refuseWith(
   reason: string,
   message: string,

package/src/commands/records.ts

@@ -31,6 +31,7 @@ import {
   RECORD_KINDS,
   type RecordKind,
   type ValidateOutcome,
+  type StructureFinding,
   validateRecords,
 } from '@/records/validate'
 import {
@@ -89,6 +90,10 @@ export function register(program: Command): void {
     .command('validate')
     .description('Report where a file and the standard governing it disagree')
     .argument('<kind>', `Record folder: ${RECORD_KINDS.join(', ')}`)
+    .argument(
+      '[record]',
+      'One plan stem or folder slug, narrowing both findings and structure to it',
+    )
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
     .option('--root <path>', 'Project root, defaulting to the main worktree')
@@ -101,12 +106,18 @@ export function register(program: Command): void {
         '  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',
         '',
+        'Structure, under `structure` and never in the exit:',
+        "  S1 to S5 from the plan standard, read on plans, a track's README and",
+        '  numbered files, and intake clusters, plus intake-spill for content under',
+        '  a field. A record written before the criteria misses S1, so it reports alone.',
+        '',
         'Refusals, read off `reason`:',
         "  no-folder     none of the kind's directories exist at either record root",
+        '  no-record     the folder holds no record by the name given',
         '  unknown-kind  the argument names no published kind',
         '',
         'Exit codes:',
-        '  0  every check passed',
+        '  0  no record carries a finding, whatever structure reports',
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one record carries a finding',
         '',
@@ -115,14 +126,21 @@ export function register(program: Command): void {
         '',
         'Examples:',
         '  canon records validate plans',
+        '  canon records validate plans feature-records-by-heading',
         '  canon records validate teach',
         '  canon records validate intake --json',
         '',
       ].join('\n'),
     )
-    .action(async (kind: string, opts: ValidateCommandOptions) => {
-      process.exitCode = await runValidate(kind, opts)
-    })
+    .action(
+      async (
+        kind: string,
+        record: string | undefined,
+        opts: ValidateCommandOptions,
+      ) => {
+        process.exitCode = await runValidate(kind, record, opts)
+      },
+    )
 
   records
     .command('ordinal')
@@ -721,6 +739,7 @@ function reportRefusal(
 
 async function runValidate(
   kind: string,
+  record: string | undefined,
   opts: ValidateCommandOptions,
 ): Promise<number> {
   const emitJson = opts.json ?? false
@@ -739,7 +758,11 @@ async function runValidate(
 
   const root = opts.root ?? (await mainWorktreeRoot())
 
-  return report(await validateWithStacks(root, kind), emitJson, root)
+  // A plan named with its extension and without it is one record, so the walk
+  // and the cross-plan filter below both read the bare stem.
+  const stem = record?.replace(/\.md$/, '')
+
+  return report(await validateWithStacks(root, kind, stem), emitJson, root)
 }
 
 /**
@@ -749,18 +772,21 @@ async function runValidate(
 async function validateWithStacks(
   root: string,
   kind: RecordKind,
+  record: string | undefined,
 ): Promise<ValidateOutcome> {
-  const outcome = await validateRecords(root, kind)
+  const outcome = await validateRecords(root, kind, record)
   if (!outcome.ok || kind !== 'plans') return outcome
 
   const live = await readLivePlans(root)
+  const across = [...stackFindings(live), ...fanInFindings(live)]
 
   return {
     ...outcome,
     findings: [
       ...outcome.findings,
-      ...stackFindings(live),
-      ...fanInFindings(live),
+      ...(record === undefined
+        ? across
+        : across.filter((found) => found.record === `${record}.md`)),
     ],
   }
 }
@@ -801,6 +827,7 @@ function report(
         kind: outcome.kind,
         records: outcome.records,
         findings: outcome.findings,
+        structure: outcome.structure,
       })}\n`,
     )
   } else {
@@ -814,6 +841,11 @@ function report(
     } else {
       for (const found of outcome.findings) logWarn(describe(found))
     }
+
+    if (outcome.structure.length > 0) {
+      logStep('Structure, reported and never in the exit')
+      for (const entry of outcome.structure) logInfo(describeStructure(entry))
+    }
     outro()
   }
 
@@ -825,6 +857,11 @@ function describe(found: Finding): string {
   return `${scope}${found.subject} ${found.message}`
 }
 
+function describeStructure(entry: StructureFinding): string {
+  const scope = entry.record === entry.subject ? '' : `${entry.record}/`
+  return `${entry.criterion} ${scope}${entry.subject}:${entry.line} ${entry.message}`
+}
+
 async function runOrdinal(
   kind: string,
   slug: string,