@erclx/canon 5.39.0 → 5.41.0

package/src/commands/gov.ts

@@ -84,6 +84,7 @@ const CANON_RULES_REL = join('.claude', 'rules', 'canon')
 
 interface InstallOptions {
   readonly add?: string
+  readonly yes?: boolean
 }
 
 interface RegenOptions {
@@ -147,6 +148,7 @@ export function register(program: Command): void {
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
     .option('--add <rules>', 'Comma-separated rules to layer on the stack')
+    .option('--yes', 'Answer the install confirm without a prompt')
     .addHelpText(
       'after',
       [
@@ -156,6 +158,7 @@ export function register(program: Command): void {
         '  canon gov install node ../my-app',
         '  canon gov install node --add astro,shadcn ../my-app',
         '  canon gov install --add tasks,plan ../my-app',
+        '  canon gov install node --yes ../my-app',
         '',
         'With --add and no stack, the named rules install alone. A first',
         'positional naming a stack is read as the stack, so pass . or a path',
@@ -164,6 +167,10 @@ export function register(program: Command): void {
         'Copies each rule into .claude/rules/canon/, replacing a copy already',
         'there. Rules under .claude/rules/project/ are never read.',
         '',
+        'The install confirm needs a TTY. --yes answers it, so a headless call',
+        'installs without setting CANON_NON_INTERACTIVE=1. It does not pick a',
+        'stack, so a headless call still names one.',
+        '',
         'Exit codes:',
         '  0  installed, the stack held no rules, or the prompt was cancelled',
         '  1  refused: no stack named headlessly, an unknown stack, no --add',
@@ -349,6 +356,10 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one stated figure disagrees with the tree',
         '',
+        'Reasons:',
+        '  no-git       git could not list the tree',
+        '  no-markdown  the tree holds no markdown file',
+        '',
         'It reports and never gates. The false-positive rate is read off the',
         'first run rather than assumed, and a push failing on a stated figure',
         'that reads correctly to a person would teach a contributor to route',
@@ -415,6 +426,9 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one declaration asserts either',
         '',
+        'Refuses an empty superseded value, a superseded value equal to its',
+        'replacement, and a tree git cannot list. An empty replacement is allowed.',
+        '',
         'Examples:',
         '  canon gov superseded feature-feat- feature-',
         '  canon gov superseded feature-feat- feature- --json',
@@ -496,6 +510,9 @@ export function register(program: Command): void {
         '  2  at least one cited path resolves to nothing, or one glob matches',
         '     nothing in this tree',
         '',
+        'Refuses a tree holding neither rule corpus, and a `git check-ignore`',
+        'read that fails.',
+        '',
         'Examples:',
         '  canon gov citations',
         '  canon gov citations --json',
@@ -543,6 +560,10 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one instruction is restated outside a declared mirror',
         '',
+        'Reasons:',
+        '  no-instructions  the tree holds no always-loaded file or seed to read',
+        '  no-surfaces      the tree holds no skills tree or rules tree to match against',
+        '',
         'Examples:',
         '  canon gov restated',
         '  canon gov restated --json',
@@ -1268,8 +1289,9 @@ async function runInstall(
   intro('canon gov install')
 
   const add = opts.add ?? ''
+  const yes = opts.yes === true
   if (add !== '' && isAddWithoutStack(stack, target)) {
-    return installExtras(add, stack ?? target)
+    return installExtras(add, stack ?? target, yes)
   }
 
   const resolved = resolveTarget(target, PROJECT_ROOT)
@@ -1314,14 +1336,7 @@ async function runInstall(
   for (const rule of missing) logWarn(`${rule} (source not found, skipping)`)
   for (const source of found) logInfo(source.rule)
 
-  const shouldInstall = await select({
-    message: `Install ${found.length} rules to ${displayPath(target, CANON_RULES_REL)}?`,
-    options: [
-      { value: true, label: 'Yes' },
-      { value: false, label: 'No' },
-    ],
-    nonInteractiveDefault: true,
-  })
+  const shouldInstall = await confirmInstall(found.length, target, yes)
 
   if (!shouldInstall) {
     logWarn('Cancelled')
@@ -1347,6 +1362,28 @@ async function runInstall(
   return 0
 }
 
+/**
+ * The install confirm. `--yes` answers it without a prompt, so the line it
+ * would have printed is skipped rather than duplicated under
+ * `CANON_NON_INTERACTIVE=1`.
+ */
+async function confirmInstall(
+  count: number,
+  target: string,
+  yes: boolean,
+): Promise<boolean> {
+  if (yes) return true
+  return select({
+    message: `Install ${count} rules to ${displayPath(target, CANON_RULES_REL)}?`,
+    options: [
+      { value: true, label: 'Yes' },
+      { value: false, label: 'No' },
+    ],
+    nonInteractiveDefault: true,
+    ttyHint: 'Pass --yes',
+  })
+}
+
 /**
  * Whether `--add` runs with no stack under it. Commander fills the first
  * positional before the second, so `--add a,b ../my-app` arrives with the
@@ -1366,7 +1403,11 @@ function isAddWithoutStack(stack: string | undefined, target: string): boolean {
  * extras are not a stack, and overwriting the chain would cost a target the
  * missing-rule report its stack install recorded.
  */
-async function installExtras(add: string, target: string): Promise<number> {
+async function installExtras(
+  add: string,
+  target: string,
+  yes: boolean,
+): Promise<number> {
   const resolved = resolveTarget(target, PROJECT_ROOT)
   if (typeof resolved === 'number') return resolved
 
@@ -1382,14 +1423,7 @@ async function installExtras(add: string, target: string): Promise<number> {
     return 1
   }
 
-  const shouldInstall = await select({
-    message: `Install ${found.length} rules to ${displayPath(target, CANON_RULES_REL)}?`,
-    options: [
-      { value: true, label: 'Yes' },
-      { value: false, label: 'No' },
-    ],
-    nonInteractiveDefault: true,
-  })
+  const shouldInstall = await confirmInstall(found.length, target, yes)
 
   if (!shouldInstall) {
     logWarn('Cancelled')

package/src/commands/intake.ts

@@ -64,6 +64,12 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-intake       the project holds no intake folder',
+        '  no-folder       no folder matches the slug',
+        '  ambiguous-slug  a bare slug matches more than one ordinal-prefixed',
+        '                  folder, all named in `detail`',
         '',
         'Exit codes:',
         '  0  the folders or items were listed',
@@ -105,6 +111,17 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-intake       the project holds no intake folder',
+        '  no-folder       no folder matches the slug',
+        '  ambiguous-slug  a bare slug matches more than one ordinal-prefixed',
+        '                  folder, all named in `detail`',
+        '  no-cluster      the cluster file named does not exist',
+        '  no-item         the item number named does not exist in the cluster',
+        '  answered        the item already carries an answer',
+        '  bad-input       a malformed command line, such as no selection, an empty',
+        '                  answer, or two answers for one item',
         '',
         'Exit codes:',
         '  0  every named item now carries its answer',

package/src/commands/labels.ts

@@ -111,6 +111,10 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one changed path is reached by no row',
         '',
+        'Reasons:',
+        '  no-map  the project declares no label map, so it labels nothing. An',
+        '          expected absence for `canon audits run`, not a fault',
+        '',
         'Examples:',
         '  canon labels audit',
         '  canon labels audit --json',
@@ -130,7 +134,10 @@ export function register(program: Command): void {
     )
     .argument('<number>', "This branch's open pull request")
     .helpOption('-h, --help', 'Show this help message')
-    .option('--base <ref>', 'Far side of the range, defaulting to the trunk')
+    .option(
+      '--base <ref>',
+      "Read the git range back to this ref instead of the pull request's files",
+    )
     .option('--root <path>', 'Repository to read, defaulting to the cwd')
     .option('--check', 'Report the labels owed and write nothing')
     .option('--json', 'Add a machine-readable record on stdout')
@@ -138,9 +145,10 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Resolves the earned set the way `canon labels audit` does, binds to the',
-        'pull request only when its head is the current branch and it is open,',
-        'and adds each earned label the pull request lacks over REST.',
+        "Resolves the earned set from the pull request's own files listing, or",
+        'from the git range when --base is passed, binds to the pull request only',
+        'when its head is the current branch and it is open, and adds each earned',
+        'label the pull request lacks over REST.',
         '',
         'It adds and never removes, so a label a person applied by hand stays.',
         'A label the remote does not carry is reported under missingOnRemote and',
@@ -155,6 +163,12 @@ export function register(program: Command): void {
         '  2  labels are still owed, being any under --check, or a label the',
         '     remote lacks or a failed add otherwise',
         '',
+        'Reasons:',
+        '  head-mismatch  the pull request is not open on the current branch, under',
+        '                 --check as well',
+        '  gh-failed      the files listing or the labels could not be read, and the',
+        '                 run does not fall back to git',
+        '',
         'Examples:',
         '  canon labels apply 123 --json',
         '  canon labels apply 123 --check',
@@ -396,7 +410,26 @@ async function runApply(number: string, opts: ApplyOptions): Promise<number> {
   if (target === null) return refuse('gh-failed')
   if (target.trim() !== `${head} open`) return refuse('head-mismatch')
 
-  const report = await auditLabels(root, { base: opts.base })
+  // An explicit --base is an explicit request for the git route. Otherwise the
+  // pull request's own file listing is the diff the labels describe, and a
+  // failed read refuses rather than falling back, since binding needed gh too.
+  let paths: string[] | undefined
+  if (opts.base === undefined) {
+    const listing = await gh(root, [
+      'api',
+      '--paginate',
+      `repos/{owner}/{repo}/pulls/${number}/files`,
+      '--jq',
+      '.[].filename',
+    ])
+    if (listing === null) return refuse('gh-failed')
+    paths = nonEmptyLines(listing)
+  }
+
+  const report = await auditLabels(root, {
+    base: opts.base,
+    ...(paths !== undefined && { paths }),
+  })
 
   // A project declaring no map earns nothing and is labelled silently, which
   // is an answer and exits clean rather than reading as a break.