@erclx/canon 5.50.0 → 5.52.0

package/src/commands/migrate.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import type { Command } from 'commander'
+import { cliRunner } from '@/gate/sequencer'
 import { listRepositoryFiles } from '@/git/files'
 import { indexSourceRules } from '@/gov/adapter'
 import { applyRecordsMove, applyRename, readSources } from '@/migrate/apply'
@@ -35,6 +36,7 @@ import {
   SKILL_NAME_MAP,
   SKILL_NAME_RULES,
 } from '@/migrate/skill-names'
+import { readMigrationStatus, statusExitCode } from '@/migrate/status'
 import {
   planSurfaceRootsMove,
   type SurfaceRootsPlan,
@@ -1039,6 +1041,43 @@ function toSessionDefaultsRecord(
   }
 }
 
+interface StatusOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
+/**
+ * Lists every migration a project still needs by running each subcommand's own
+ * dry run, so it reads the contract they share and writes nothing.
+ */
+async function runStatus(opts: StatusOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
+  const report = await readMigrationStatus(cliRunner(root))
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: report.refused === 0, ...report })}\n`,
+    )
+  }
+
+  for (const entry of report.migrations) {
+    if (entry.state === 'pending') logInfo(`Pending: ${entry.verb}`)
+    if (entry.state === 'refused') {
+      logError(`Refused: ${entry.verb}: ${entry.reason ?? 'no reason given'}`)
+    }
+  }
+
+  if (report.pending === 0 && report.refused === 0) {
+    logInfo('No migration is pending.')
+  }
+
+  return statusExitCode(report)
+}
+
 export function register(program: Command): void {
   const migrate = program
     .command('migrate')
@@ -1446,4 +1485,42 @@ export function register(program: Command): void {
     .action(async (opts: SessionDefaultsOptions) => {
       process.exitCode = await runSessionDefaults(opts)
     })
+
+  migrate
+    .command('status')
+    .description('List every migration a project still needs, in run order')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--root <path>',
+      'Project root, defaulting to the working directory',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Runs each migrate subcommand as a dry run and sorts it by its exit',
+        'code, in the order a project runs them, records first. It passes',
+        'no --write and writes nothing. A migration is pending or not, with',
+        "the subcommand's own record attached, since the records share no",
+        'count field.',
+        '',
+        "Each dry run reads today's tree, so a clean entry can turn pending",
+        'once an earlier one is applied. Run status again after each --write.',
+        '',
+        'Exit codes:',
+        '  0  no migration is pending',
+        '  1  a subcommand refused, which outranks a pending plan',
+        '  2  at least one migration is pending',
+        '',
+        'Examples:',
+        '  canon migrate status',
+        '  canon migrate status --json',
+        '  canon migrate status --root ../project',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: StatusOptions) => {
+      process.exitCode = await runStatus(opts)
+    })
 }

package/src/commands/worktrees.ts

@@ -17,6 +17,14 @@ import {
   type WorktreeVerdict,
 } from '@/worktrees/reclaim'
 import { mainWorktreeRoot } from '@/git/worktree'
+import {
+  type Half,
+  type MemberOutcome,
+  type MemberRefusal,
+  type MembersRefusal,
+  type MembersReport,
+  retireMembers,
+} from '@/worktrees/members'
 import { machineListenerReader } from '@/listeners/machine'
 import { repairBareFlag } from '@/worktrees/bare-flag'
 import { type StopReport, stopListeners } from '@/worktrees/stop'
@@ -40,6 +48,31 @@ interface ReclaimCommandOptions {
   readonly json?: boolean
 }
 
+interface RetireMembersCommandOptions {
+  readonly pullRequest: string
+  readonly dryRun?: boolean
+  readonly json?: boolean
+}
+
+/**
+ * What the post-merge hook reads after an integrator merges. Every field it
+ * branches on is a number or a fixed word, and `members` sits last, for the
+ * reason `ReclaimRecord` states.
+ */
+export interface RetireMembersRecord {
+  readonly pullRequest: number
+  readonly reason: MembersRefusal | null
+  readonly detail: string | null
+  readonly dryRun: boolean
+  /** Members with a half deleted, or that a dry run would delete, and none kept or failed. */
+  readonly retired: number
+  /** Members with a half kept and none failed. */
+  readonly kept: number
+  /** Members with a half whose deletion failed. */
+  readonly failed: number
+  readonly members: readonly MemberOutcome[]
+}
+
 /**
  * What a caller reads instead of the frame.
  *
@@ -145,6 +178,59 @@ const CONDITIONS = [
   'keeps a directory rather than removing one.',
 ]
 
+const MEMBERS_REFUSALS: Record<MembersRefusal, string> = {
+  'gh-missing': 'gh is not on the path, so the pull request could not be read',
+  'gh-failed': 'the pull request read failed',
+  'sessions-unreadable': 'the session roster could not be read',
+  'sessions-unchecked':
+    'some session records come from another pid namespace and no socket answers for them',
+  'not-merged': 'the pull request has not merged',
+  'no-members': 'the body carries no "Fan-in members:" line',
+  'trunk-named': 'the line names the branch the pull request merged into',
+  'head-named': "the line names the integrator's own branch",
+  'open-pull-request': 'a named branch has an open pull request of its own',
+  'head-unreadable':
+    'refs/pull/<n>/head could not be fetched, or names another commit than the merged head',
+}
+
+const MEMBER_REFUSALS: Record<MemberRefusal, string> = {
+  'not-in-merged-head':
+    "its tip is not an ancestor of the integrator's merged head, so it holds work the merge did not carry",
+  'remote-unreadable': 'origin could not be read for this branch',
+  'worktree-kept':
+    'its worktree was kept, and git refuses to delete a branch a worktree holds',
+  'main-worktree': 'it is checked out in the main worktree',
+  'current-worktree': 'its worktree is the one this command runs in',
+  'detached-head': 'its worktree has a detached HEAD',
+  'uncommitted-changes': 'its worktree holds uncommitted work',
+  'unreadable-worktree': 'its worktree could not be read',
+  'held-by-session': 'a live session holds its worktree',
+}
+
+const RETIRE_CONDITIONS = [
+  'Reads the "Fan-in members:" line of a merged integrator pull request,',
+  "whose backticked branches are the members, and deletes each one's",
+  'origin branch, worktree, and local branch. Nothing outside that line',
+  'is read.',
+  '',
+  "A member half is merged when its tip is an ancestor of the integrator's",
+  'merged head, fetched from refs/pull/<n>/head, rather than of the trunk,',
+  'which a squash merge never makes it. Origin and local are judged apart,',
+  'so an unpushed commit keeps the local branch and a commit pushed after',
+  'the merge keeps the origin branch. The worktree takes the same reading',
+  '`canon worktrees list` gives, with the members counted as merged.',
+  '',
+  'These refuse the whole run, and nothing is deleted:',
+  ...Object.entries(MEMBERS_REFUSALS).map(
+    ([reason, meaning]) => `  ${reason.padEnd(22)}${meaning}`,
+  ),
+  '',
+  'These keep one half of one member, named in its "reasons":',
+  ...Object.entries(MEMBER_REFUSALS).map(
+    ([reason, meaning]) => `  ${reason.padEnd(22)}${meaning}`,
+  ),
+]
+
 export function register(program: Command): void {
   const worktrees = program
     .command('worktrees')
@@ -240,6 +326,42 @@ export function register(program: Command): void {
       process.exitCode = await runReclaim(opts)
     })
 
+  worktrees
+    .command('retire-members')
+    .description(
+      'Delete the fan-in members a merged integrator pull request names, unless --dry-run',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .requiredOption(
+      '--pull-request <number>',
+      'The merged integrator pull request',
+    )
+    .option('--dry-run', 'Report what would be deleted without deleting it')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every member was retired or kept, or the body names none',
+        '  1  refused, or a deletion failed, with the reason on stderr',
+        '',
+        ...RETIRE_CONDITIONS,
+        '',
+        'The post-merge hook runs this once per merged pull request number,',
+        'and CANON_SKIP_RECLAIM turns it off there. Run it by hand for a',
+        'merge the hook missed.',
+        '',
+        'Examples:',
+        '  canon worktrees retire-members --pull-request 2570 --dry-run',
+        '  canon worktrees retire-members --pull-request 2570 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RetireMembersCommandOptions) => {
+      process.exitCode = await runRetireMembers(opts)
+    })
+
   worktrees
     .command('repair-bare-flag', { hidden: true })
     .description('Clear a core.bare flag that worktree entry left set')
@@ -563,3 +685,154 @@ export function describe(verdict: WorktreeVerdict): string {
     `  Reclaimable. Pull request #${verdict.pullRequest} merged it, ${tree}, and no session holds it.`,
   ].join('\n')
 }
+
+function halves(member: MemberOutcome): readonly Half[] {
+  return member.worktree === null
+    ? [member.origin, member.local]
+    : [member.origin, member.worktree, member.local]
+}
+
+/**
+ * Builds the record from the report, separate from the run so the counts are
+ * testable without a repository. A member already gone everywhere counts
+ * nowhere, so a run repeated by hand does not report a retirement it did not
+ * make.
+ */
+export function retireMembersRecord(
+  pullRequest: number,
+  dryRun: boolean,
+  report: MembersReport,
+): RetireMembersRecord {
+  if (report.kind === 'refused') {
+    return {
+      pullRequest,
+      reason: report.reason,
+      detail: report.detail,
+      dryRun,
+      retired: 0,
+      kept: 0,
+      failed: 0,
+      members: [],
+    }
+  }
+
+  const states = report.members.map((member) =>
+    halves(member).map((half) => half.state),
+  )
+  const failed = states.filter((each) => each.includes('failed')).length
+  const kept = states.filter(
+    (each) => !each.includes('failed') && each.includes('kept'),
+  ).length
+  const retired = states.filter(
+    (each) =>
+      !each.includes('failed') &&
+      !each.includes('kept') &&
+      each.some((state) => state === 'deleted' || state === 'would-delete'),
+  ).length
+
+  return {
+    pullRequest,
+    reason: null,
+    detail: null,
+    dryRun,
+    retired,
+    kept,
+    failed,
+    members: report.members,
+  }
+}
+
+/**
+ * A kept half is a refusal doing its job and a body naming no members is the
+ * ordinary merge, so neither fails the run.
+ */
+export function retireMembersExit(record: RetireMembersRecord): number {
+  if (record.reason !== null && record.reason !== 'no-members') return 1
+  return record.failed > 0 ? 1 : 0
+}
+
+function describeHalf(name: string, half: Half): string {
+  if (half.state === 'kept') {
+    const reasons = half.reasons.map((reason) => MEMBER_REFUSALS[reason])
+    return `  ${name}: kept, since ${reasons.join('; ')}.`
+  }
+  const state = half.state.replace('-', ' ')
+  return half.detail === null
+    ? `  ${name}: ${state}.`
+    : `  ${name}: ${state}. ${half.detail}`
+}
+
+async function runRetireMembers(
+  opts: RetireMembersCommandOptions,
+): Promise<number> {
+  const dryRun = opts.dryRun ?? false
+  const pullRequest = Number(opts.pullRequest)
+
+  intro(
+    dryRun
+      ? 'canon worktrees retire-members (dry-run)'
+      : 'canon worktrees retire-members',
+  )
+
+  if (!Number.isInteger(pullRequest) || pullRequest <= 0) {
+    logStep('Refused')
+    logWarn(
+      `--pull-request takes a pull request number, and "${opts.pullRequest}" is not one.`,
+    )
+    outro()
+    return 1
+  }
+
+  // The reading stays on the caller's directory, which is what refuses the
+  // worktree it stands in, and every write runs from the main root.
+  const report = await retireMembers(pullRequest, {
+    cwd: process.cwd(),
+    root: await mainWorktreeRoot(),
+    dryRun,
+  })
+  const record = retireMembersRecord(pullRequest, dryRun, report)
+
+  if (report.kind === 'refused') {
+    logStep(report.reason === 'no-members' ? 'Members' : 'Refused')
+    if (report.reason === 'no-members') logInfo(report.detail)
+    else {
+      logWarn(`Nothing was deleted: ${MEMBERS_REFUSALS[report.reason]}.`)
+      logInfo(report.detail)
+    }
+  } else {
+    logStep('Members')
+    pipeOutput(
+      report.members
+        .map((member) =>
+          [
+            member.branch,
+            describeHalf('origin', member.origin),
+            ...(member.worktree === null
+              ? []
+              : [
+                  describeHalf(
+                    `worktree ${member.worktree.path}`,
+                    member.worktree,
+                  ),
+                ]),
+            describeHalf('local', member.local),
+          ].join('\n'),
+        )
+        .join('\n'),
+    )
+    if (record.failed > 0) {
+      logWarn(
+        `${plural(record.failed, 'member')} could not be fully deleted. Read the reason above and clear it by hand.`,
+      )
+    }
+    if (dryRun) {
+      logWarn(
+        'Nothing was deleted. Run this again without --dry-run to delete.',
+      )
+    }
+  }
+
+  outro()
+  if (opts.json === true) process.stdout.write(`${JSON.stringify(record)}\n`)
+  return retireMembersExit(record)
+}

package/src/gov/detect.ts

@@ -99,25 +99,35 @@ function walkFiles(target: string): string[] {
   return files.sort()
 }
 
+interface Candidates {
+  readonly paths: readonly string[]
+  readonly folders: readonly string[]
+}
+
 /**
  * The paths a file glob is matched against: every file to depth two, plus
  * every folder on the way to any listed file, so an evidence folder such as
- * `.github/workflows` matches without naming the file inside it.
+ * `.github/workflows` matches without naming the file inside it. `folders`
+ * holds the folders alone, which a pattern ending in `/` is matched against.
  */
-async function candidatePaths(target: string): Promise<string[]> {
+async function candidatePaths(target: string): Promise<Candidates> {
   const listed = (await listRepositoryFiles(target)) ?? walkFiles(target)
   const paths = new Set<string>()
+  const folders = new Set<string>()
 
   for (const file of listed) {
     let dir = dirname(file)
     while (dir !== '.') {
-      if (depth(dir) <= MAX_DIRS) paths.add(dir)
+      if (depth(dir) <= MAX_DIRS) {
+        paths.add(dir)
+        folders.add(dir)
+      }
       dir = dirname(dir)
     }
     if (depth(file) <= MAX_DIRS) paths.add(file)
   }
 
-  return [...paths].sort()
+  return { paths: [...paths].sort(), folders: [...folders].sort() }
 }
 
 /** A PEP 508 requirement's distribution name, normalized per PEP 503. */
@@ -231,6 +241,11 @@ function readDependencies(
   return deps
 }
 
+/** A pattern ending in `/` matches folders only, so a file at that depth misses. */
+function isFolderPattern(pattern: string): boolean {
+  return pattern.endsWith('/')
+}
+
 /** A glob carrying no wildcard names one path rather than a pattern. */
 function isLiteral(pattern: string): boolean {
   return !/[*?[\]{}]/.test(pattern)
@@ -245,7 +260,7 @@ function matchEntry(
   entry: DetectEntry,
   target: string,
   deps: ReadonlyMap<string, readonly string[]>,
-  paths: readonly string[],
+  candidates: Candidates,
 ): Evidence[] {
   const evidence: Evidence[] = []
 
@@ -255,9 +270,12 @@ function matchEntry(
   }
 
   for (const pattern of entry.files) {
-    const glob = new Bun.Glob(pattern)
+    const folderOnly = isFolderPattern(pattern)
+    const glob = new Bun.Glob(folderOnly ? pattern.slice(0, -1) : pattern)
     const hit =
-      paths.find((path) => glob.match(path)) ??
+      (folderOnly ? candidates.folders : candidates.paths).find((path) =>
+        glob.match(path),
+      ) ??
       (isLiteral(pattern) && existsSync(join(target, pattern))
         ? pattern
         : undefined)
@@ -287,13 +305,13 @@ export async function detectRules(
   }
 
   const live = indexRuleSources(root)
-  const paths = await candidatePaths(target)
-  const deps = readDependencies(target, paths)
+  const candidates = await candidatePaths(target)
+  const deps = readDependencies(target, candidates.paths)
 
   const proposals = loadDetectEntries(root)
     .filter((entry) => live.has(entry.rule) && !covered.has(entry.rule))
     .flatMap((entry) => {
-      const evidence = matchEntry(entry, target, deps, paths)
+      const evidence = matchEntry(entry, target, deps, candidates)
       return evidence.length === 0 ? [] : [{ rule: entry.rule, evidence }]
     })
 

package/src/hooks/post-merge.ts

@@ -39,6 +39,7 @@ export interface PostMergeInput {
 export const STEP_VERBS = {
   archive: ['tasks', 'archive'],
   push: ['records', 'push'],
+  members: ['worktrees', 'retire-members'],
   reclaim: ['worktrees', 'reclaim'],
   upgrade: ['upgrade'],
   pluginUpdate: ['claude', 'plugin-update'],
@@ -225,6 +226,33 @@ function reclaimLines(fields: Fields): string | undefined {
   return lines.length > 0 ? lines : undefined
 }
 
+/**
+ * Keyed on the fields, like the reclaim, since a run that retires one member
+ * and fails on another exits 1 with a branch already deleted. A body naming no
+ * members is every merge but an integrator's, so it stays quiet.
+ */
+function memberLines(number: number, fields: Fields): string | undefined {
+  let lines = ''
+  const retired = count(fields, 'retired')
+  if (retired > 0) {
+    lines += `\n🌿 Retired ${retired} fan-in member(s) of #${number}.\n\n`
+  }
+
+  const hint = `Run canon worktrees retire-members --pull-request ${number} --dry-run to read why.\n\n`
+  const reason = text(fields, 'reason')
+  const unfinished = count(fields, 'kept') + count(fields, 'failed')
+  if (
+    reason !== undefined &&
+    reason !== 'no-members' &&
+    reason !== 'gh-missing'
+  ) {
+    lines += `\n🌿 Fan-in members of #${number} not retired: ${reason}\n${hint}`
+  } else if (unfinished > 0) {
+    lines += `\n🌿 ${unfinished} fan-in member(s) of #${number} kept or not fully deleted.\n${hint}`
+  }
+  return lines.length > 0 ? lines : undefined
+}
+
 /**
  * Shared by the binary reinstall and the plugin update. `current` is the
  * ordinary outcome on most merges and stays quiet, and `quiet` names the
@@ -271,8 +299,10 @@ async function step(
 }
 
 /**
- * Runs the five post-merge steps in order: archive, records push, reclaim,
- * upgrade, plugin update. The reclaim sits before the upgrade, since the
+ * Runs the six post-merge steps in order: archive, records push, member
+ * retirement, reclaim, upgrade, plugin update. The member retirement sits
+ * before the reclaim, so the reclaim reads a retired member's worktree as
+ * gone rather than racing it. Both sit before the upgrade, since the
  * upgrade reinstalls the binary every later child runs under, and the two
  * network-bound moves sit last so a slow registry delays nothing else.
  *
@@ -309,11 +339,20 @@ export async function runPostMerge(input: PostMergeInput): Promise<void> {
     pushLines,
   )
 
-  // No `--root` here, and that is load-bearing. The verb reads its own working
-  // directory to refuse the worktree it stands in, so a root would turn the
-  // running worktree into an ordinary candidate and let a pull inside a
-  // linked worktree delete the ground under itself.
+  // No `--root` on either worktree step, and that is load-bearing. Each verb
+  // reads its own working directory to refuse the worktree it stands in, so a
+  // root would turn the running worktree into an ordinary candidate and let a
+  // pull inside a linked worktree delete the ground under itself. One switch
+  // covers both, since both remove worktrees.
   if (!isSkipped('CANON_SKIP_RECLAIM')) {
+    for (const number of pullRequestNumbers(input.subjects)) {
+      await step(
+        input,
+        at([...STEP_VERBS.members, '--pull-request', String(number), '--json']),
+        (_, fields) => memberLines(number, fields),
+      )
+    }
+
     await step(input, at([...STEP_VERBS.reclaim, '--json']), (_, fields) =>
       reclaimLines(fields),
     )