@erclx/canon 4.68.0 → 4.70.0

package/src/commands/claude.ts

@@ -3,7 +3,16 @@ import { chmod, readFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 import type { Command } from 'commander'
+import { execa } from 'execa'
+import { singleLine } from '@/commands/upgrade'
+import { gitEnv } from '@/git-env'
 import { claudeChain, pendingEntries, planGitignore } from '@/claude/gitignore'
+import {
+  matchInstall,
+  type PluginInstall,
+  readPluginName,
+  updatedMessage,
+} from '@/claude/plugin-update'
 import {
   applySeeds,
   countByScope,
@@ -90,6 +99,37 @@ interface SkillsDriftOptions {
   readonly json?: boolean
 }
 
+interface PluginUpdateOptions {
+  readonly json?: boolean
+}
+
+/**
+ * `no-claude` and `no-plugin` name permanent conditions on a machine that
+ * never carries the marketplace plugin at all, matching the `gh-missing` and
+ * `no-repository` reasons `.husky/post-merge`'s other two steps already stay
+ * quiet on forever rather than nagging a project that will never fix them.
+ * Every other reason is a real defect and prints.
+ */
+type PluginUpdateReason =
+  | 'no-claude'
+  | 'no-manifest'
+  | 'no-name'
+  | 'list-failed'
+  | 'no-plugin'
+  | 'ambiguous'
+  | 'update-failed'
+  | 'after-list-failed'
+
+interface PluginUpdateRecord {
+  readonly root: string
+  readonly id?: string
+  readonly before?: string
+  readonly after?: string
+  readonly state: 'updated' | 'current' | 'refused'
+  readonly reason?: PluginUpdateReason
+  readonly message: string
+}
+
 interface SkillsReachOptions {
   readonly json?: boolean
 }
@@ -111,11 +151,24 @@ const SEEDED_FILES: readonly string[] = [
 const SEEDED_DIRS: readonly string[] = ['memory', 'tasks', 'wireframes']
 const USER_DIR = join('tooling', 'claude', 'user')
 const STATUSLINE = 'statusline-command.sh'
+const PLUGIN_MANIFEST = join('claude', '.claude-plugin', 'plugin.json')
+
+/** A local cache read, not a network round trip, matching reclaim.ts's own bound for `claude agents --json`. */
+const PLUGIN_LIST_TIMEOUT_MS = 10_000
+
+/**
+ * `claude plugin update` fetches a marketplace archive over the network, so a
+ * stalled fetch should not hang the caller, which is a git hook on the
+ * ordinary path.
+ */
+const PLUGIN_UPDATE_TIMEOUT_MS = 60_000
 
 export function register(program: Command): void {
   const claude = program
     .command('claude')
-    .description('Claude workflow (init, seeds, sync, setup, routing)')
+    .description(
+      'Claude workflow (init, seeds, sync, setup, routing, plugin-update)',
+    )
     .helpOption('-h, --help', 'Show this help message')
     .addHelpText(
       'after',
@@ -227,6 +280,39 @@ export function register(program: Command): void {
       process.exitCode = runRouting(path, opts)
     })
 
+  claude
+    .command('plugin-update')
+    .description(
+      'Update the installed marketplace plugin cache to match this CLI',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Mechanics:',
+        '  Reads the plugin name out of claude/.claude-plugin/plugin.json,',
+        '  matches it against an installed row from `claude plugin list',
+        '  --json` by id prefix (<name>@), then runs `claude plugin update',
+        '  <id> -y`. There is no --json on the update call itself, so the',
+        '  version is read back off `claude plugin list --json` again and',
+        '  compared to what it was before.',
+        '',
+        'Exit codes:',
+        '  0  current already, or the update ran',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  canon claude plugin-update',
+        '  canon claude plugin-update --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: PluginUpdateOptions) => {
+      process.exitCode = await runPluginUpdate(opts)
+    })
+
   const skills = claude
     .command('skills')
     .description('Plugin skill catalog (list, audit, drift, reach, rank)')
@@ -830,6 +916,200 @@ function reportRouting(
   )
 }
 
+/**
+ * Reads the plugin name off the manifest, matches it against an installed row,
+ * runs the update, and reads the version back off the same list rather than
+ * trusting the update call's own report, since `claude plugin update` carries
+ * no `--json` to answer with. `canon upgrade` makes the identical move for the
+ * package managers it drives.
+ */
+async function runPluginUpdate(opts: PluginUpdateOptions): Promise<number> {
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  intro('canon claude plugin-update')
+  if (mismatch !== undefined) logWarn(mismatch)
+
+  const manifestPath = join(PROJECT_ROOT, PLUGIN_MANIFEST)
+  let manifestText: string
+  try {
+    manifestText = await readFile(manifestPath, 'utf8')
+  } catch {
+    return refusePluginUpdate(
+      opts,
+      'no-manifest',
+      `No manifest at ${manifestPath}, so there is no plugin name to update.`,
+    )
+  }
+
+  const name = readPluginName(manifestText)
+  if (name === undefined) {
+    return refusePluginUpdate(
+      opts,
+      'no-name',
+      `No name field in ${manifestPath}, so there is nothing to match against an installed plugin.`,
+    )
+  }
+
+  logStep('Manifest')
+  logInfo(`${name}, from ${manifestPath}`)
+
+  const before = await listPluginInstalls()
+  if (before.kind === 'missing') {
+    return refusePluginUpdate(
+      opts,
+      'no-claude',
+      'claude is not on PATH, so no installed plugin could be read.',
+    )
+  }
+  if (before.kind === 'failed') {
+    return refusePluginUpdate(
+      opts,
+      'list-failed',
+      `\`claude plugin list --json\` failed. ${before.detail}`,
+    )
+  }
+
+  const match = matchInstall(name, before.installs)
+  if (match.kind === 'none') {
+    return refusePluginUpdate(
+      opts,
+      'no-plugin',
+      `No installed plugin carries the id prefix "${name}@". Install it with \`claude plugin install\` first.`,
+    )
+  }
+  if (match.kind === 'many') {
+    return refusePluginUpdate(
+      opts,
+      'ambiguous',
+      `Multiple installed plugins share the name "${name}": ${match.installs
+        .map((install) => install.id)
+        .join(', ')}. Refusing rather than picking one.`,
+    )
+  }
+
+  const { install } = match
+  logStep('Installed')
+  logInfo(`${install.id} ${install.version}`)
+
+  logStep('Updating')
+  const result = await execa('claude', ['plugin', 'update', install.id, '-y'], {
+    reject: false,
+    timeout: PLUGIN_UPDATE_TIMEOUT_MS,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+
+  if (result.exitCode !== 0) {
+    return refusePluginUpdate(
+      opts,
+      'update-failed',
+      `\`claude plugin update ${install.id} -y\` exited ${result.exitCode}. ${(result.stderr || result.stdout).trim()}`,
+      install.id,
+      install.version,
+    )
+  }
+
+  const after = await listPluginInstalls()
+  if (after.kind !== 'ok') {
+    return refusePluginUpdate(
+      opts,
+      'after-list-failed',
+      '`claude plugin update` ran, but `claude plugin list --json` failed to read the version back.',
+      install.id,
+      install.version,
+    )
+  }
+
+  const afterVersion =
+    after.installs.find((row) => row.id === install.id)?.version ??
+    install.version
+  const state = afterVersion === install.version ? 'current' : 'updated'
+
+  logStep('Installed')
+  logInfo(
+    afterVersion === install.version
+      ? `${afterVersion}, unchanged`
+      : `${install.version} to ${afterVersion}`,
+  )
+  outro()
+
+  emitPluginUpdate(opts, {
+    root: PROJECT_ROOT,
+    id: install.id,
+    before: install.version,
+    after: afterVersion,
+    state,
+    message: updatedMessage(install.version, afterVersion),
+  })
+  return 0
+}
+
+type ListInstallsResult =
+  | { readonly kind: 'ok'; readonly installs: readonly PluginInstall[] }
+  | { readonly kind: 'missing' }
+  | { readonly kind: 'failed'; readonly detail: string }
+
+/**
+ * `missing` separates a `claude` binary that is not on PATH from every other
+ * failure, since only that condition is permanent enough for the hook to
+ * silence forever. execa reports it as `ENOENT` on the result rather than by
+ * throwing, because the call runs with `reject: false`.
+ */
+async function listPluginInstalls(): Promise<ListInstallsResult> {
+  const result = await execa('claude', ['plugin', 'list', '--json'], {
+    reject: false,
+    timeout: PLUGIN_LIST_TIMEOUT_MS,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+
+  if (result.code === 'ENOENT') return { kind: 'missing' }
+  if (result.exitCode !== 0) {
+    return { kind: 'failed', detail: (result.stderr || result.stdout).trim() }
+  }
+
+  try {
+    return {
+      kind: 'ok',
+      installs: JSON.parse(result.stdout) as readonly PluginInstall[],
+    }
+  } catch {
+    return {
+      kind: 'failed',
+      detail: '`claude plugin list --json` did not print valid JSON.',
+    }
+  }
+}
+
+function refusePluginUpdate(
+  opts: PluginUpdateOptions,
+  reason: PluginUpdateReason,
+  message: string,
+  id?: string,
+  before?: string,
+): number {
+  outro()
+  frameError(message)
+  emitPluginUpdate(opts, {
+    root: PROJECT_ROOT,
+    ...(id === undefined ? {} : { id }),
+    ...(before === undefined ? {} : { before }),
+    state: 'refused',
+    reason,
+    message,
+  })
+  return 1
+}
+
+function emitPluginUpdate(
+  opts: PluginUpdateOptions,
+  record: PluginUpdateRecord,
+): void {
+  if (opts.json !== true) return
+  process.stdout.write(
+    `${JSON.stringify({ ...record, message: singleLine(record.message) })}\n`,
+  )
+}
+
 /** What a reader does about the one way the corpus fails to build. */
 const REACH_REFUSALS: Record<ReachRefusal, string> = {
   'no-skills':

package/src/commands/demo.ts

@@ -54,7 +54,7 @@ export function register(program: Command): void {
   demo
     .command('compile')
     .description('Turn a screencast draft into a plan a run can drive')
-    .argument('<draft>', 'Screencast draft written by canon-screencast')
+    .argument('<draft>', 'Screencast draft written by draft-screencast')
     .helpOption('-h, --help', 'Show this help message')
     .option('-o, --out <dir>', 'Directory the plan is written to', DEFAULT_OUT)
     .option('-s, --slug <slug>', 'Plan name, defaulting to the draft filename')

package/src/commands/feedback.ts

@@ -7,11 +7,11 @@ import {
   missingField,
   missingFieldMessage,
 } from '@/commands/feedback-format'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { creationRel } from '@/record-root'
 import { createGithubIssue } from '@/github'
 import { issueFailureMessage } from '@/github-format'
-import { frameError, frameSuccess, palette } from '@/ui'
+import { frameError, frameSuccess, logWarn, palette } from '@/ui'
 
 function readStdin(): Promise<string> {
   return new Promise((resolveStream, rejectStream) => {
@@ -45,7 +45,7 @@ function isToolkitSource(): boolean {
  * hand, so each writes under its own name and the enclosing folder keeps the
  * single ignore entry and the single backed-folder entry it already had.
  */
-function writeLocal(body: string): string {
+function writeLocal(body: string, mismatch: string | undefined): string {
   // Resolved against the same root the write joins onto, so a checkout that has
   // not migrated its records writes this beside the ones already there rather
   // than opening a second root nothing reads.
@@ -55,7 +55,16 @@ function writeLocal(body: string): string {
   const filename = `feedback-${deriveSlug(body)}-${timestamp()}.md`
   const filePath = join(reviewDir, filename)
   writeFileSync(filePath, `${body}\n`, 'utf8')
-  frameSuccess('canon feedback', join(relativeDir, filename))
+
+  // Manual frame rather than `frameSuccess`, since the mismatch warning is a
+  // frame-interior line landing between the opener and the command title,
+  // matching the convention `#1587` set at its other six sites.
+  const { GREEN, GREY, NC, WHITE } = palette(process.stderr)
+  process.stderr.write(`${GREY}┌${NC}\n`)
+  if (mismatch !== undefined) logWarn(mismatch)
+  process.stderr.write(
+    `${GREY}│${NC} ${WHITE}canon feedback${NC}\n${GREY}│${NC}\n${GREY}│${NC} ${GREEN}✓${NC} ${join(relativeDir, filename)}\n${GREY}└${NC}\n`,
+  )
   return filePath
 }
 
@@ -124,7 +133,8 @@ export function register(program: Command): void {
         return
       }
 
-      const filePath = writeLocal(body)
+      const mismatch = checkoutMismatchWarning(process.cwd())
+      const filePath = writeLocal(body, mismatch)
       process.stdout.write(`${filePath}\n`)
     })
 }

package/src/commands/gate.ts

@@ -12,7 +12,7 @@ import {
   summarize,
 } from '@/gate/sequencer'
 import { STAGES } from '@/gate/stages'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import {
   intro,
   logError,
@@ -89,6 +89,7 @@ export function register(program: Command): void {
 
 async function runGate(opts: RunCommandOptions): Promise<number> {
   const root = PROJECT_ROOT
+  const mismatch = checkoutMismatchWarning(process.cwd())
   const emitJson = opts.json ?? false
   const nested = opts.nested ?? false
   const write = opts.write ?? true
@@ -102,6 +103,7 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
     ? { scoped: false, files: [] }
     : await collectChangedFiles(run)
   if (!emitJson && changed.notice !== undefined) logWarn(changed.notice)
+  if (mismatch !== undefined) logWarn(mismatch)
 
   const ctx: GateContext = {
     root,

package/src/commands/pr.ts

@@ -18,6 +18,7 @@ import {
 import { type CheckRunListing, collapseChecks } from '@/pr/checks'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
 import { KEY_CHANGES } from '@/pr/paths'
+import { type ReviewListing, resolveReviewScope } from '@/pr/review-scope'
 import { intro, logInfo, logStep, logWarn, outro, plural } from '@/ui'
 
 const GH_TIMEOUT_MS = 30_000
@@ -49,7 +50,12 @@ interface ReadOptions {
 }
 
 /** Why a head-sensitive read produced no answer about a commit. */
-type PullRefusal = 'gh-missing' | 'gh-failed' | 'no-branch' | 'runs-unreadable'
+type PullRefusal =
+  | 'gh-missing'
+  | 'gh-failed'
+  | 'no-branch'
+  | 'runs-unreadable'
+  | 'reviews-unreadable'
 
 /** What a reader does about each way the two sha-keyed verbs produced nothing. */
 const PULL_REFUSALS: Record<PullRefusal | HeadRefusal, string> = {
@@ -67,6 +73,8 @@ const PULL_REFUSALS: Record<PullRefusal | HeadRefusal, string> = {
     'The pull request object reported no head commit, so there is nothing to compare the tip against.',
   'runs-unreadable':
     'The check runs for this commit could not be read. An empty answer here would report a commit as having no check rather than as unread, so nothing is reported.',
+  'reviews-unreadable':
+    'The reviews on this pull request could not be read. An empty answer here would report a reviewed pull request as never reviewed, which routes the next pass to the whole change, so nothing is reported.',
 }
 
 /** Why the read produced no comparison, ahead of the ones the compare owns. */
@@ -236,6 +244,47 @@ export function register(program: Command): void {
     .action(async (number: string | undefined, opts: ReadOptions) => {
       process.exitCode = await runChecks(number, opts)
     })
+
+  pr.command('review-state')
+    .description('Report the commit and instant the last review pass covered')
+    .argument('[number]', 'Pull request to read, defaulting to this branch')
+    .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')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'A review carries two stamps GitHub writes at submission: `commit.oid`',
+        'names whatever the head was at that instant and `submittedAt` names the',
+        'instant itself. Neither describes the commit the reviewing session read.',
+        'A push landing inside the compose window moves `commit.oid` onto a commit',
+        'nobody reviewed, and the next pass then scopes its delta past that work',
+        'and reports it covered.',
+        '',
+        '`review-pr` writes the commit it read and the instant it read it as a',
+        'marker on the last line of every body it posts. This is the one place',
+        'that marker is parsed, so `review-pr` and the orchestrator poll read one',
+        'answer rather than carrying a copy of the format each.',
+        '',
+        'Read `source` before trusting the rest:',
+        '  marker    the pass wrote its own read-time record, which is authority',
+        '  fallback  a pass posted before the marker shipped, off GitHub stamps',
+        '  none      the thread carries no pass, so the next one is a first pass',
+        '',
+        'Exit codes:',
+        '  0  the thread was read, whether it carries a pass or not',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr review-state',
+        '  canon pr review-state 1341 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: ReadOptions) => {
+      process.exitCode = await runReviewState(number, opts)
+    })
 }
 
 interface PullRequestRead {
@@ -768,6 +817,86 @@ async function runChecks(
   return 0
 }
 
+async function runReviewState(
+  number: string | undefined,
+  opts: ReadOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon pr review-state')
+
+  if (Bun.which('gh') === null) {
+    return refuseWith('gh-missing', PULL_REFUSALS['gh-missing'], emitJson, root)
+  }
+
+  const args = ['pr', 'view']
+  if (number !== undefined) args.push(number)
+  // `number` rides along so the record names the pull request a caller that
+  // passed no argument was answered about. The comment families the poll reads
+  // stay out of the query, since nothing here parses one and a listing the
+  // caller discards is a payload paid for twice.
+  args.push('--json', 'number,reviews')
+
+  const stdout = await gh(root, args)
+  if (stdout === null) {
+    return refuseWith('gh-failed', PULL_REFUSALS['gh-failed'], emitJson, root)
+  }
+
+  let listing: ReviewListing & { number?: number }
+  try {
+    listing = JSON.parse(stdout)
+  } catch {
+    return refuseWith(
+      'reviews-unreadable',
+      PULL_REFUSALS['reviews-unreadable'],
+      emitJson,
+      root,
+    )
+  }
+
+  const scope = resolveReviewScope(listing)
+
+  logStep('Scope')
+  logInfo(
+    listing.number === undefined
+      ? 'the pull request on this branch'
+      : `#${listing.number}`,
+  )
+
+  if (scope.source === 'none') {
+    logStep('First pass')
+    logInfo('the thread carries no review, so nothing has been covered yet')
+  } else if (scope.source === 'marker') {
+    logStep(scope.state === 'open' ? 'Open' : 'Closed')
+    logInfo(
+      `the last pass read ${scope.commit?.slice(0, 8)} at ${scope.readAt}, which is what it covered`,
+    )
+  } else {
+    logStep(scope.state === 'open' ? 'Open' : 'Closed')
+    // Named rather than folded into the line above, since the whole point of
+    // the marker is that these two fields describe the submission and not the
+    // read, and a caller cannot tell the two apart from the values alone.
+    logWarn(
+      `the last pass carries no read-time marker, so ${scope.commit === undefined ? 'no commit' : scope.commit.slice(0, 8)} and ${scope.submittedAt ?? 'no instant'} come off GitHub's submission stamps. A push inside that pass's compose window is invisible here.`,
+    )
+  }
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        ...(listing.number !== undefined && { number: listing.number }),
+        ...scope,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
 /**
  * Frames a refusal on stderr in both modes and puts the record on stdout alone,
  * so an operator reading the terminal sees the reason rather than a command

package/src/commands/sandbox.ts

@@ -78,6 +78,7 @@ interface CheckOptions {
   readonly writes?: string
   readonly escapes?: string
   readonly escapesWatched?: boolean
+  readonly concurrentSessions?: string
   readonly json?: boolean
   readonly strict?: boolean
 }
@@ -349,7 +350,7 @@ function runCheck(
 
   const parsed = parseTarget(target)
   if (parsed === undefined) {
-    logError('Invalid target. Use <category>:<command>, e.g. claude:docs.')
+    logError('Invalid target. Use <category>:<command>, e.g. claude:docs-fold.')
     outro()
     process.exitCode = 1
     return
@@ -376,6 +377,7 @@ function runCheck(
         options.escapes === undefined
           ? undefined
           : options.escapesWatched === true,
+      concurrentSessions: readPathList(options.concurrentSessions),
       envelope: readEnvelope(options.envelope),
     },
   )
@@ -414,7 +416,10 @@ export function register(program: Command): void {
   sandbox
     .command('check')
     .description('Check a provisioned sandbox against a scenario expectation')
-    .argument('<target>', 'Scenario as <category>:<command>, e.g. claude:docs')
+    .argument(
+      '<target>',
+      'Scenario as <category>:<command>, e.g. claude:docs-fold',
+    )
     .argument('[arm]', 'Named scenario arm, e.g. drift')
     .helpOption('-h, --help', 'Show this help message')
     .option('--envelope <file>', 'Run envelope JSON from claude -p')
@@ -427,6 +432,10 @@ export function register(program: Command): void {
       '--escapes-watched',
       'At least one watched root held a target this run, so a zero-escape file is a clean watch rather than one with nothing to watch',
     )
+    .option(
+      '--concurrent-sessions <file>',
+      'Newline-delimited sessions live in the registry both before and after this run, a witness for an unbounded escape',
+    )
     .option('--json', 'Emit the verdict as JSON on stdout')
     .option('--strict', 'Exit non-zero when the arm declares no expectation')
     .addHelpText(
@@ -434,8 +443,8 @@ export function register(program: Command): void {
       [
         '',
         'Examples:',
-        '  canon sandbox check claude:docs drift',
-        '  canon sandbox check claude:docs drift --envelope run.json --json',
+        '  canon sandbox check claude:docs-fold drift',
+        '  canon sandbox check claude:docs-fold drift --envelope run.json --json',
         '',
         'Exit codes: 0 on pass or unchecked, 1 on failure.',
         'With --strict, unchecked exits 1 as well.',