@erclx/canon 4.3.0 → 4.4.0

package/src/claude/cases/misc.ts

@@ -24,4 +24,8 @@ export const MISC_CASES: readonly SkillCase[] = [
     prompt: "This test just started failing and I don't know why yet.",
     expect: 'systematic-debugging',
   },
+  {
+    prompt: 'Does our github about text still match what the readme says?',
+    expect: 'repo-metadata',
+  },
 ]

package/src/cli.ts

@@ -37,6 +37,7 @@ import { register as deps } from '@/commands/deps'
 import { register as labels } from '@/commands/labels'
 import { register as autoship } from '@/commands/autoship'
 import { register as pr } from '@/commands/pr'
+import { register as repo } from '@/commands/repo'
 import { register as census } from '@/commands/census'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
@@ -86,6 +87,7 @@ function showHelp(): void {
     `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
     `${GREY}│${NC}    autoship [cmd]     ${GREY}# Decide whether a changed set needs the review pass (classify)${NC}`,
     `${GREY}│${NC}    pr [cmd]           ${GREY}# Read a pull request body against its own diff (key-changes)${NC}`,
+    `${GREY}│${NC}    repo [cmd]         ${GREY}# This repository's own remote metadata (metadata propose, apply)${NC}`,
     `${GREY}│${NC}    census [path]      ${GREY}# Report tracked file count, extension breakdown, and line totals${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}    gate [cmd]         ${GREY}# Run the merge gate stage by stage (run)${NC}`,
@@ -135,6 +137,7 @@ function showHelp(): void {
     `${GREY}│${NC}    canon secrets scan --json`,
     `${GREY}│${NC}    canon deps audit --json`,
     `${GREY}│${NC}    canon labels audit --json`,
+    `${GREY}│${NC}    canon repo metadata propose --json`,
     `${GREY}│${NC}    canon census --json`,
     `${GREY}│${NC}    canon audits run --json`,
     `${GREY}│${NC}    canon gate run --all --no-write`,
@@ -192,6 +195,7 @@ deps(program)
 labels(program)
 autoship(program)
 pr(program)
+repo(program)
 census(program)
 audits(program)
 gate(program)

package/src/commands/repo.ts

@@ -0,0 +1,393 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+import {
+  compareMetadata,
+  type CurrentMetadata,
+  isValidTopic,
+  type MetadataDiff,
+  proposeMetadata,
+} from '@/repo/metadata'
+import {
+  intro,
+  logAdd,
+  logInfo,
+  logRemove,
+  logStep,
+  logWarn,
+  outro,
+} from '@/ui'
+
+const GH_TIMEOUT_MS = 30_000
+
+type SourceRefusal = 'gh-missing' | 'gh-failed'
+type ApplyRefusal =
+  | SourceRefusal
+  | 'no-changes'
+  | 'empty-topics'
+  | 'invalid-topics'
+  | 'wrong-repo'
+
+const REFUSALS: Record<ApplyRefusal, string> = {
+  'gh-missing': 'gh is not on the path, so no remote could be read.',
+  'gh-failed':
+    'gh could not read this repository. Check the remote and gh auth status.',
+  'no-changes':
+    'Nothing to apply. Pass --description, --homepage, or --topics with the answered value.',
+  'empty-topics':
+    '--topics carried no usable topic, and this command never reads that as a request to remove every topic the remote carries. Pass the full desired set, or omit the flag to leave topics untouched.',
+  'invalid-topics':
+    '--topics carried an entry GitHub does not accept as a topic (lowercase letters, digits, and internal hyphens only). This command never narrows the desired set silently, since dropping it changes what the remaining diff removes.',
+  'wrong-repo':
+    'The remote --root resolved to is not the one --repo named. This command never writes to a repository the invocation did not explicitly confirm.',
+}
+
+interface ProposeOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
+interface ApplyOptions {
+  readonly description?: string
+  readonly homepage?: string
+  readonly topics?: string
+  readonly repo: string
+  readonly root?: string
+  readonly json?: boolean
+}
+
+type CurrentRead =
+  | {
+      readonly kind: 'read'
+      readonly current: CurrentMetadata
+      readonly nameWithOwner: string
+    }
+  | { readonly kind: 'refused'; readonly reason: SourceRefusal }
+
+/** Reads what the remote already carries. The one network call this domain makes to read. */
+async function readCurrent(cwd: string): Promise<CurrentRead> {
+  if (Bun.which('gh') === null) return { kind: 'refused', reason: 'gh-missing' }
+
+  try {
+    const result = await execa(
+      'gh',
+      [
+        'repo',
+        'view',
+        '--json',
+        'description,homepageUrl,repositoryTopics,nameWithOwner',
+      ],
+      { cwd, timeout: GH_TIMEOUT_MS, env: gitEnv(), extendEnv: false },
+    )
+    const row = JSON.parse(result.stdout) as {
+      description?: string
+      homepageUrl?: string
+      repositoryTopics?: readonly { name: string }[]
+      nameWithOwner?: string
+    }
+    return {
+      kind: 'read',
+      current: {
+        description: row.description ?? '',
+        homepage: row.homepageUrl ?? '',
+        topics: (row.repositoryTopics ?? []).map((topic) => topic.name),
+      },
+      nameWithOwner: row.nameWithOwner ?? '',
+    }
+  } catch {
+    return { kind: 'refused', reason: 'gh-failed' }
+  }
+}
+
+export function register(program: Command): void {
+  const repo = program
+    .command('repo')
+    .description('Read and write this repository’s own remote metadata')
+    .helpOption('-h, --help', 'Show this help message')
+
+  const metadata = repo
+    .command('metadata')
+    .description('The About description, homepage, and topics GitHub shows')
+    .helpOption('-h, --help', 'Show this help message')
+
+  metadata
+    .command('propose')
+    .description(
+      'Compare a locally computed description, homepage, and topic set against the remote',
+    )
+    .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',
+      [
+        '',
+        "Computes from the tree alone: a description from the README's opening",
+        'line past its title and badges, and a homepage and topics from',
+        "package.json's own homepage and keywords fields. A field neither file",
+        'declares is never diffed, so an undeclared topic set never reads as a',
+        'proposal to clear what the remote already carries.',
+        '',
+        'This is the read half. It never writes. Run `canon repo metadata apply`',
+        'with the answered fields once a proposal is worth taking.',
+        '',
+        'Exit codes:',
+        '  0  the remote already carries what this run computed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  a difference was found',
+        '',
+        'Examples:',
+        '  canon repo metadata propose',
+        '  canon repo metadata propose --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ProposeOptions) => {
+      process.exitCode = await runPropose(opts)
+    })
+
+  metadata
+    .command('apply')
+    .description(
+      'Write an explicitly supplied description, homepage, or topic set to the remote',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .requiredOption(
+      '--repo <owner/name>',
+      'Repository this run is allowed to write to, checked against what gh resolves',
+    )
+    .option('--description <text>', 'About text to write')
+    .option('--homepage <url>', 'Homepage URL to write')
+    .option(
+      '--topics <list>',
+      'Comma-separated topic set to write, replacing what the remote carries',
+    )
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Takes the answered value for each field directly rather than',
+        're-running propose, so a change this writes is always one a person or',
+        'a second invocation already read and confirmed. --topics is the full',
+        'desired set. gh only takes an add and a remove list, so this reads the',
+        'current set once to compute both. An entry shaped like something other',
+        'than a GitHub topic refuses the whole run rather than being dropped.',
+        '',
+        '--repo is required and takes no default, since --root silently',
+        'resolving to the caller’s own cwd is what turned a verification run',
+        'against this exact command into a live write against a public remote.',
+        'The value is checked against what gh resolves for --root, so the',
+        'write refuses on any repository the invocation did not name aloud.',
+        '',
+        'Exit codes:',
+        '  0  the write succeeded, or the remote already matched',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon repo metadata apply --repo erclx/canon --description "One source for conventions."',
+        '  canon repo metadata apply --repo erclx/canon --topics cli-tool,governance,standards',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ApplyOptions) => {
+      process.exitCode = await runApply(opts)
+    })
+}
+
+function refuse(
+  reason: ApplyRefusal,
+  emitJson: boolean,
+  root: string,
+  detail?: string,
+): number {
+  const message =
+    detail === undefined ? REFUSALS[reason] : `${REFUSALS[reason]} ${detail}`
+
+  logStep('Refused')
+  logWarn(message)
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
+  }
+  return 1
+}
+
+async function runPropose(opts: ProposeOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon repo metadata propose')
+
+  const [proposal, currentRead] = await Promise.all([
+    proposeMetadata(root),
+    readCurrent(root),
+  ])
+
+  if (currentRead.kind === 'refused') {
+    return refuse(currentRead.reason, emitJson, root)
+  }
+
+  const diff: MetadataDiff = compareMetadata(currentRead.current, proposal)
+  const changed = Object.keys(diff).length > 0
+
+  logStep('Repository')
+  logInfo(currentRead.nameWithOwner)
+
+  logStep('Computed')
+  if (
+    proposal.description === undefined &&
+    proposal.homepage === undefined &&
+    proposal.topics === undefined
+  ) {
+    logInfo('nothing local resolved a description, a homepage, or topics')
+  } else {
+    if (proposal.description !== undefined) {
+      logInfo(`description: ${proposal.description}`)
+    }
+    if (proposal.homepage !== undefined)
+      logInfo(`homepage: ${proposal.homepage}`)
+    if (proposal.topics !== undefined) {
+      logInfo(`topics: ${proposal.topics.join(', ')}`)
+    }
+  }
+
+  logStep(changed ? 'Difference' : 'No difference')
+  if (!changed) {
+    logInfo('the remote already carries what this run computed')
+  } else {
+    if (diff.description !== undefined) {
+      logWarn(
+        `description: "${diff.description.current}" → "${diff.description.proposed}"`,
+      )
+    }
+    if (diff.homepage !== undefined) {
+      logWarn(
+        `homepage: "${diff.homepage.current}" → "${diff.homepage.proposed}"`,
+      )
+    }
+    if (diff.topics !== undefined) {
+      for (const topic of diff.topics.added) logAdd(`topic: ${topic}`)
+      for (const topic of diff.topics.removed) logRemove(`topic: ${topic}`)
+    }
+    logInfo(
+      'Run `canon repo metadata apply` with the answered fields. This run writes nothing.',
+    )
+  }
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        repo: currentRead.nameWithOwner,
+        current: currentRead.current,
+        proposal,
+        diff,
+      })}\n`,
+    )
+  }
+
+  return changed ? 2 : 0
+}
+
+async function runApply(opts: ApplyOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon repo metadata apply')
+
+  if (
+    opts.description === undefined &&
+    opts.homepage === undefined &&
+    opts.topics === undefined
+  ) {
+    return refuse('no-changes', emitJson, root)
+  }
+
+  let desired: ReadonlySet<string> | undefined
+  if (opts.topics !== undefined) {
+    const entries = opts.topics
+      .split(',')
+      .map((topic) => topic.trim().toLowerCase())
+      .filter((topic) => topic !== '')
+    if (entries.length === 0) return refuse('empty-topics', emitJson, root)
+
+    const invalid = entries.filter((topic) => !isValidTopic(topic))
+    if (invalid.length > 0) {
+      return refuse(
+        'invalid-topics',
+        emitJson,
+        root,
+        `Invalid: ${invalid.join(', ')}`,
+      )
+    }
+
+    desired = new Set(entries)
+  }
+
+  // Read ahead of every write, never only for --topics, since this is the
+  // one call that confirms --repo names the remote --root actually resolved
+  // to. A write skipping it on a description-only or homepage-only run would
+  // reopen the gap --repo exists to close.
+  const currentRead = await readCurrent(root)
+  if (currentRead.kind === 'refused')
+    return refuse(currentRead.reason, emitJson, root)
+  if (currentRead.nameWithOwner !== opts.repo) {
+    return refuse('wrong-repo', emitJson, root)
+  }
+
+  const args = ['repo', 'edit']
+  if (opts.description !== undefined)
+    args.push('--description', opts.description)
+  if (opts.homepage !== undefined) args.push('--homepage', opts.homepage)
+
+  if (desired !== undefined) {
+    const currentSet = new Set(currentRead.current.topics)
+    const toAdd = [...desired].filter((topic) => !currentSet.has(topic))
+    const toRemove = currentRead.current.topics.filter(
+      (topic) => !desired.has(topic),
+    )
+
+    if (toAdd.length > 0) args.push('--add-topic', toAdd.join(','))
+    if (toRemove.length > 0) args.push('--remove-topic', toRemove.join(','))
+  }
+
+  if (args.length === 2) {
+    logStep('Applied')
+    logInfo('the remote already matches every field supplied. Nothing written.')
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(`${JSON.stringify({ root, written: false })}\n`)
+    }
+    return 0
+  }
+
+  if (Bun.which('gh') === null) return refuse('gh-missing', emitJson, root)
+
+  try {
+    await execa('gh', args, {
+      cwd: root,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+  } catch {
+    return refuse('gh-failed', emitJson, root)
+  }
+
+  logStep('Applied')
+  logInfo('gh repo edit wrote the supplied fields to the remote.')
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, written: true })}\n`)
+  }
+
+  return 0
+}

package/src/commands/tasks.ts

@@ -1,5 +1,6 @@
 import { relative } from 'node:path'
 import type { Command } from 'commander'
+import { type AnswersOutcome, planAnswers } from '@/tasks/answers'
 import {
   type ArchiveOutcome,
   archiveTask,
@@ -54,6 +55,11 @@ interface CitationsCommandOptions {
   readonly root?: string
 }
 
+interface AnswersCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
 interface PullRequestCommandOptions {
   readonly json?: boolean
   readonly plan?: string
@@ -173,6 +179,42 @@ export function register(program: Command): void {
       process.exitCode = await runCitations(task, opts)
     })
 
+  tasks
+    .command('plan-answers')
+    .description('Report whether a plan still waits on the operator to answer')
+    .argument('<plan>', 'Plan path or its slug, as in dispatch-answer-gate')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the plan is launchable',
+        '  1  refused as no-plan, archived, or bad-input',
+        '  2  the plan waits on the operator, and open names every slot',
+        '',
+        'A blank Answer accepts the Suggested line above it, so only',
+        '`- Suggested: needs your call, <why>` over an empty slot is a stop.',
+        'It reports and never writes. Branch on launchable rather than on the',
+        'exit code, which a shell function wrapping canon can flatten to zero.',
+        '',
+        'A relative path resolves against the project root first and against',
+        '.claude/tasks/ second, so the ../plans/ link a board row writes works.',
+        '',
+        'Examples:',
+        '  canon tasks plan-answers dispatch-answer-gate',
+        '  canon tasks plan-answers .claude/plans/feature-dispatch-answer-gate.md',
+        '  canon tasks plan-answers ../plans/feature-dispatch-answer-gate.md',
+        '  canon tasks plan-answers dispatch-answer-gate --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (plan: string, opts: AnswersCommandOptions) => {
+      process.exitCode = await runAnswers(plan, opts)
+    })
+
   tasks
     .command('pull-request')
     .description('Record a pull request number on the task a branch closes')
@@ -539,6 +581,64 @@ function describeCitations(outcome: PlanCitations): string {
   return `shares ${outcome.target} with ${outcome.citedBy.join(', ')}, so the sweep leaves it.`
 }
 
+async function runAnswers(
+  plan: string,
+  opts: AnswersCommandOptions,
+): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await planAnswers(root, plan)
+
+  return reportAnswers(outcome, opts.json ?? false, root)
+}
+
+function reportAnswers(
+  outcome: AnswersOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
+      )
+      return 1
+    }
+
+    intro('canon tasks plan-answers')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ ...outcome, root })}\n`)
+    return outcome.launchable ? 0 : EXIT_FINDINGS
+  }
+
+  intro('canon tasks plan-answers')
+  logStep(outcome.plan)
+
+  if (outcome.launchable) {
+    logInfo('waits on nobody, so the dispatch may launch it.')
+    outro()
+    return 0
+  }
+
+  for (const question of outcome.open) {
+    logWarn(`${question.label} ${question.why}`)
+  }
+
+  const one = outcome.open.length === 1
+
+  logError(
+    `${outcome.open.length} question${one ? '' : 's'} ${one ? 'waits' : 'wait'} on you, so the dispatch holds this row.`,
+  )
+  outro()
+
+  return EXIT_FINDINGS
+}
+
 function reportValidation(
   outcome: ValidateOutcome,
   emitJson: boolean,

package/src/paths.ts

@@ -0,0 +1,16 @@
+import { sep } from 'node:path'
+
+/**
+ * Whether a resolved path is the directory itself or sits inside it. The
+ * separator guard is the whole of it: a bare prefix test reads
+ * `.claude/plans-archive` as living under `.claude/plans`, which is a sibling
+ * rather than a child and is exactly the pair the plan folders spell.
+ *
+ * It lives at the root rather than beside either caller because both resolve
+ * plan paths and only one of them may reach `src/tasks/archive.ts`, whose
+ * index regeneration pulls in a Bun-only import that a test running under
+ * Vitest cannot load.
+ */
+export function isUnder(path: string, dir: string): boolean {
+  return path === dir || path.startsWith(`${dir}${sep}`)
+}