@erclx/canon 5.50.0 → 5.51.0

package/scripts/ci/stack-issues.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Opens, updates, or closes one issue per stack from the outcomes stack-verify.yml
+# recorded under results/<stack>, called by its report job. Takes the stacks as
+# arguments and reads GH_TOKEN, GH_REPO, and RUN_URL from the step env.
+set -euo pipefail
+
+for stack in "$@"; do
+  title="stack-verify: $stack"
+  # A job that died before recording counts as a failure
+  outcome=failure
+  [ -f "results/$stack" ] && outcome=$(cat "results/$stack")
+  number=$(gh issue list --state open --search "\"$title\" in:title" --json number,title \
+    --jq "[.[] | select(.title == \"$title\")][0].number // empty")
+  if [ "$outcome" = success ]; then
+    if [ -n "$number" ]; then
+      gh issue close "$number" --comment "Passing again in $RUN_URL"
+    fi
+  elif [ -n "$number" ]; then
+    gh issue comment "$number" --body "Still failing in $RUN_URL"
+  else
+    gh issue create --title "$title" \
+      --body "\`canon tooling verify $stack\` failed in $RUN_URL. The issue closes itself when a later run passes."
+  fi
+done

package/scripts/ci/verify-npm-token.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Checks that the npm publish credential is set and authenticates, so a release
+# is never cut it cannot publish. release-please.yml passes NPM_TOKEN from the
+# step env, which keeps the secret named in the workflow.
+set -e
+
+if [ -z "$NPM_TOKEN" ]; then
+  echo "::error::NPM_TOKEN is not set. Add the secret before a release can be cut."
+  exit 1
+fi
+if ! curl -sf -H "Authorization: Bearer $NPM_TOKEN" https://registry.npmjs.org/-/whoami >/dev/null; then
+  echo "::error::NPM_TOKEN did not authenticate. It is likely expired or revoked."
+  exit 1
+fi

package/src/cli/help.ts

@@ -20,6 +20,7 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['sync [path]', 'Sync all installed domains in a project'],
       ['upgrade', 'Reinstall the CLI with the manager that installed it'],
       ['migrate [cmd]', 'Move a project off a retired name or layout'],
+      ['changelog', 'Read the releases between a stamp and this binary'],
       ['targets [cmd]', 'Projects this toolkit installed into'],
     ],
   },

package/src/cli.ts

@@ -40,6 +40,7 @@ import { register as census } from '@/commands/census'
 import { register as upstream } from '@/commands/upstream'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
+import { register as changelog } from '@/commands/changelog'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { renderHelp } from '@/cli/help'
 import { renderAll, routeHelp } from '@/cli/help-all'
@@ -100,6 +101,7 @@ upstream(program)
 audits(program)
 gate(program)
 upgrade(program)
+changelog(program)
 
 const route = routeHelp(program, process.argv.slice(2))
 if (route.kind === 'top') showHelp()

package/src/commands/changelog.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import type { Command } from 'commander'
+import { PROJECT_ROOT } from '@/roots/project'
+import { readStamp } from '@/sync/stamp'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/cli/ui'
+import { type ChangelogReport, resolveChangelog } from '@/version/changelog'
+import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
+
+interface ChangelogOptions {
+  readonly since?: string
+  readonly root?: string
+  readonly json?: boolean
+}
+
+const REFUSALS = {
+  'no-stamp':
+    'the target carries no stamped version and --since named none, so there is no start to range from',
+  'no-changelog':
+    'the installed package carries no CHANGELOG.md with release entries to read',
+  'unknown-version':
+    'the changelog lists no such release, so the range would be a guess',
+} as const
+
+const HELP = [
+  '',
+  'Prints the release entries after a version, up to the running one, from the',
+  'CHANGELOG.md the installed package ships. It reads no registry and needs no',
+  '`gh`, so it answers offline.',
+  '',
+  'The start defaults to the oldest `version` across the target stamp domains,',
+  'since the oldest domain is the one furthest behind. --since overrides it.',
+  '',
+  'Exit codes:',
+  '  0  the range was read, empty when the target is already current',
+  '  1  refused, with the reason on stderr',
+  '',
+  'A refusal names a "reason" rather than printing an empty range. no-stamp',
+  'means no start was recorded or given, no-changelog means the file or its',
+  'release headings are missing, and unknown-version means the start or the',
+  'running version is absent from the file, which covers a pre-release and a',
+  'start newer than the binary.',
+  '',
+  'The JSON carries "since", "running", and "entries", each an object with the',
+  'release "version" and its raw "markdown". Read the record rather than the',
+  'exit when a skill consumes this, since a shell function wrapping the binary',
+  'may flatten the status.',
+  '',
+  'Examples:',
+  '  canon changelog',
+  '  canon changelog --since 5.47.0 --json',
+  '  canon changelog --root ../frameboard',
+  '',
+].join('\n')
+
+export function register(program: Command): void {
+  program
+    .command('changelog')
+    .description(
+      'Print the release entries after a version up to the running one',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--since <version>',
+      'Start after this version instead of the stamp',
+    )
+    .option('--root <path>', 'Target whose stamp sets the start', '.')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText('after', HELP)
+    .action((opts: ChangelogOptions) => {
+      process.exitCode = runChangelog(opts)
+    })
+}
+
+function readChangelogText(): string | undefined {
+  const path = join(PROJECT_ROOT, 'CHANGELOG.md')
+
+  return existsSync(path) ? readFileSync(path, 'utf8') : undefined
+}
+
+function stampedVersions(root: string): string[] {
+  const stamp = readStamp(root)
+  if (stamp === undefined) return []
+
+  return Object.values(stamp.domains)
+    .map((domain) => domain?.version)
+    .filter((version): version is string => version !== undefined)
+}
+
+function runChangelog(opts: ChangelogOptions): number {
+  intro('canon changelog')
+
+  const root = resolve(opts.root ?? '.')
+  const report = resolveChangelog({
+    text: readChangelogText(),
+    running: readInstalled().version ?? UNKNOWN_LABEL,
+    since: opts.since,
+    stamped: stampedVersions(root),
+  })
+
+  if (report.kind === 'range') {
+    reportRange(report)
+  } else {
+    reportRefusal(report)
+  }
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(report)}\n`)
+  }
+
+  return report.kind === 'range' ? 0 : 1
+}
+
+function reportRange(
+  report: Extract<ChangelogReport, { kind: 'range' }>,
+): void {
+  logStep('Range')
+  logInfo(`${report.since} to ${report.running}`)
+
+  if (report.entries.length === 0) {
+    logInfo('No release after the start, so nothing is pending')
+    return
+  }
+
+  logStep(plural(report.entries.length, 'release'))
+  for (const entry of report.entries) {
+    pipeOutput(entry.markdown)
+  }
+}
+
+function reportRefusal(
+  report: Extract<ChangelogReport, { kind: 'refused' }>,
+): void {
+  logStep('Refused')
+  const version = report.version === undefined ? '' : ` (${report.version})`
+  logWarn(`${report.reason}${version}: ${REFUSALS[report.reason]}`)
+}

package/src/commands/hooks.ts

@@ -39,14 +39,16 @@ export function register(program: Command): void {
         'Runs these steps in order, each a child call reading its --json record:',
         ...Object.values(STEP_VERBS).map((verb) => `  canon ${verb.join(' ')}`),
         '',
-        'The archive runs once per pull request number the merge brought in.',
-        'Lines go to stderr, and an ordinary merge prints nothing.',
+        'The archive and the member retirement run once per pull request',
+        'number the merge brought in. Lines go to stderr, and an ordinary merge',
+        'prints nothing.',
         '',
-        'The reclaim runs from the working directory with no root, so a pull',
-        'inside a linked worktree never removes the worktree it stands in.',
+        'The member retirement and the reclaim run from the working directory',
+        'with no root, so a pull inside a linked worktree never removes the',
+        'worktree it stands in.',
         '',
         'Environment:',
-        '  CANON_SKIP_RECLAIM=1        skip the worktree reclaim',
+        '  CANON_SKIP_RECLAIM=1        skip the member retirement and the reclaim',
         '  CANON_SKIP_UPGRADE=1        skip the CLI reinstall',
         '  CANON_SKIP_PLUGIN_UPDATE=1  skip the plugin update',
         '',

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)
+}