@erclx/canon 4.3.0 → 4.5.0

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/slides.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
+import { creationRel } from '@/record-root'
 import { LAYOUTS } from '@/slides/layouts'
 import { openDeck } from '@/slides/open'
 import { renderSlidesDoc } from '@/slides/render'
@@ -16,7 +17,11 @@ export function register(program: Command): void {
     .command('render')
     .description('Render a SLIDES.md source into a PowerPoint deck')
     .option('-s, --source <path>', 'Source SLIDES.md path', '.claude/SLIDES.md')
-    .option('-o, --out <path>', 'Output directory', '.claude/review/slides')
+    .option(
+      '-o, --out <path>',
+      'Output directory',
+      creationRel('review', 'slides'),
+    )
     .option('-v, --variant <variant>', 'Override variant (light or dark)')
     .option(
       '-m, --mirror <path>',

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/context/citations.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { listRepositoryFiles } from '@/git-files'
+import { RECORD_ROOTS } from '@/record-root'
 
 /**
  * Suppresses citation checking for the source line carrying it.
@@ -76,21 +77,31 @@ export function isFixture(rel: string): boolean {
   return rel.split('/').some((segment) => FIXTURE_SEGMENTS.includes(segment))
 }
 
+/**
+ * Both record roots are spelled, so a citation into a folder that has moved is
+ * still resolved. A pattern fixed at one root matches nothing after the move and
+ * reports nothing, which is a stale reference passing the check that exists to
+ * find it rather than a check that fails.
+ */
 export function citationPattern(folders: readonly string[]): RegExp {
-  const names = folders.map((name) =>
-    name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
-  )
+  const names = folders.map((name) => escape(name))
+  const roots = RECORD_ROOTS.map((name) => escape(name))
+
   return new RegExp(
-    `\\.claude/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
+    `(?:${roots.join('|')})/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
     'g',
   )
 }
 
+function escape(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
 /**
  * A backticked filename carrying no folder, the form a reference takes when it
  * names a sibling rather than a path.
  *
- * `citationPattern` spells the `.claude/` prefix and cannot see this shape at
+ * `citationPattern` spells a record-root prefix and cannot see this shape at
  * all, which is the reason the form rule exists. Widening that expression to
  * admit a bare name was the alternative and it puts one match in the position of
  * answering two questions, since a spelled path is a reference by construction

package/src/context/folders.ts

@@ -1,9 +1,10 @@
 import { existsSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import { INDEX_FILE, listIndexes } from '@/indexes/walk'
+import { RECORD_ROOTS } from '@/record-root'
 
 /**
- * Folder names under `.claude/` audited by default.
+ * Folder names under a record root audited by default.
  *
  * A named list rather than the index-plus-entry contract read off disk, so a
  * generated tree satisfying that contract is never measured against a rule
@@ -12,8 +13,8 @@ import { INDEX_FILE, listIndexes } from '@/indexes/walk'
  * here.
  *
  * It doubles as the citation check's scope, since `citationPattern` spells only
- * these names. A `.claude/` folder left off the list is never resolved, so a
- * path into one goes stale silently rather than failing a push.
+ * these names. A folder left off the list is never resolved, so a path into one
+ * goes stale silently rather than failing a push.
  */
 export const DEFAULT_FOLDERS: readonly string[] = [
   'context',
@@ -21,8 +22,17 @@ export const DEFAULT_FOLDERS: readonly string[] = [
   'wireframes',
 ]
 
-/** The base every folder in the default list sits under. */
-const CLAUDE_BASE = '.claude'
+/**
+ * The bases every folder in the default list is looked for under, in the record
+ * roots' own precedence order.
+ *
+ * `diagrams` is the one name here that is a session record and moves with them,
+ * so the list has to carry the root it moves to. `context` and `wireframes` are
+ * tracked and stay, which leaves them resolvable at a root nothing will ever put
+ * them under. That costs one `existsSync` apiece and is cheaper than a per-name
+ * base map that would state the same split twice.
+ */
+const CLAUDE_BASES: readonly string[] = RECORD_ROOTS
 
 /** The project root, reached only by a name the caller asked for. */
 const ROOT_BASE = '.'
@@ -58,7 +68,7 @@ export interface AuditedFolder {
 }
 
 /**
- * Names the requested `.claude/` folders that actually exist, which is the
+ * Names the requested record-root folders that actually exist, which is the
  * citation check's scope.
  *
  * A skill or seed pointing into `.claude/wireframes/` is a live instruction for
@@ -76,7 +86,7 @@ export function presentNames(folders: readonly AuditedFolder[]): string[] {
   return [
     ...new Set(
       folders
-        .filter((folder) => folder.base === CLAUDE_BASE)
+        .filter((folder) => CLAUDE_BASES.includes(folder.base))
         .map((folder) => folder.name),
     ),
   ]
@@ -157,7 +167,7 @@ export async function resolveFolders(
   names: readonly string[] = DEFAULT_FOLDERS,
   { canResolveAtRoot = false }: ResolveOptions = {},
 ): Promise<FolderResolution> {
-  const bases = canResolveAtRoot ? [CLAUDE_BASE, ROOT_BASE] : [CLAUDE_BASE]
+  const bases = canResolveAtRoot ? [...CLAUDE_BASES, ROOT_BASE] : CLAUDE_BASES
   const folders: AuditedFolder[] = []
   const missing: string[] = []
 

package/src/gate/measures.ts

@@ -97,7 +97,7 @@ export const SANDBOX_UNDECLARED_CEILING = 47
  * rather than derived, because this stage only ever names the file in a remedy
  * a reader has to be able to open, and `canon audits run` owns writing it.
  */
-export const AUDITS_BASELINE = '.claude/audits/baseline.json'
+export const AUDITS_BASELINE = '.claude/canon/baseline.json'
 
 export const HERO_STAMP_FAILURE =
   'The hero set disagrees with the stamp written when the image was captured. Run canon capture assets/hero.html and commit all three files together.'

package/src/intake/folder.ts

@@ -9,6 +9,7 @@ import {
   readItems,
   writeAnswerLine,
 } from '@/intake/items'
+import { recordDir } from '@/record-root'
 
 export const INTAKE_REFUSALS = [
   'no-intake',
@@ -80,7 +81,7 @@ function refuse(
 }
 
 export function intakeDir(root: string): string {
-  return join(root, '.claude', 'intake')
+  return recordDir(root, 'intake')
 }
 
 /**