@erclx/canon 4.2.1 → 4.4.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}`)
+}

package/src/repo/metadata.ts

@@ -0,0 +1,206 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * What this run can compute from the tree alone. A field stays absent rather
+ * than empty when nothing local resolves it, so a caller never reads
+ * "nothing to propose" as "propose removing what is already there."
+ */
+export interface MetadataProposal {
+  readonly description?: string
+  readonly homepage?: string
+  readonly topics?: readonly string[]
+}
+
+/** What the remote already carries, read by the caller rather than here. */
+export interface CurrentMetadata {
+  readonly description: string
+  readonly homepage: string
+  readonly topics: readonly string[]
+}
+
+export interface MetadataDiff {
+  readonly description?: { readonly current: string; readonly proposed: string }
+  readonly homepage?: { readonly current: string; readonly proposed: string }
+  readonly topics?: {
+    readonly added: readonly string[]
+    readonly removed: readonly string[]
+  }
+}
+
+/** GitHub's own cap on the About field. */
+const MAX_DESCRIPTION_LENGTH = 350
+
+/** GitHub's own cap on topics per repository. */
+const MAX_TOPICS = 20
+
+/** GitHub's own shape for a topic: lowercase, alphanumeric, internal hyphens. */
+const TOPIC_PATTERN = /^[a-z0-9][a-z0-9-]*$/
+
+/**
+ * Whether an already-trimmed, already-lowercased string is a shape GitHub
+ * accepts as a topic. Exported so a caller validating an operator-supplied
+ * topic list checks against the same rule this reader silently filters
+ * `package.json`'s `keywords` through, rather than reimplementing it against
+ * a looser test such as non-emptiness alone.
+ */
+export function isValidTopic(topic: string): boolean {
+  return TOPIC_PATTERN.test(topic)
+}
+
+/**
+ * A bare image, or an image wrapped in a link, which is the shape a shields.io
+ * badge takes. The wrapped alternative goes first, since the bare form would
+ * otherwise match its inner image alone and leave the wrapping link behind.
+ */
+const BADGE_TOKEN = /\[!\[[^\]]*\]\([^)]*\)\]\([^)]*\)|!\[[^\]]*\]\([^)]*\)/g
+
+/** True once every badge token is stripped and nothing remains. */
+function isBadgeLine(line: string): boolean {
+  return line.replace(BADGE_TOKEN, '').trim() === ''
+}
+
+function stripInlineMarkdown(line: string): string {
+  return line
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/(\*\*|__)(.+?)\1/g, '$2')
+    .replace(/(\*|_|`)(.+?)\1/g, '$2')
+    .trim()
+}
+
+/**
+ * The first prose line past the title and any badge row, stripped of inline
+ * markdown and capped at GitHub's About field length.
+ *
+ * `undefined` only when the file carries nothing past its title and badges,
+ * per the skill requirement's refusal boundary: a resolvable line that reads
+ * as a title rather than a sentence is still proposed, since rejecting it is
+ * a judgment for the person reading the proposal rather than for this reader.
+ */
+export function extractOpeningLine(readme: string): string | undefined {
+  for (const raw of readme.split('\n')) {
+    const line = raw.trim()
+    if (line === '' || line.startsWith('#') || isBadgeLine(line)) continue
+
+    const stripped = stripInlineMarkdown(line)
+    if (stripped === '') continue
+
+    return stripped.length > MAX_DESCRIPTION_LENGTH
+      ? `${stripped.slice(0, MAX_DESCRIPTION_LENGTH - 1)}…`
+      : stripped
+  }
+  return undefined
+}
+
+/**
+ * `package.json`'s `keywords` read as candidate topics, the field the wider
+ * npm ecosystem already uses for this. Invalid entries are dropped silently
+ * rather than refused, since a manifest mixing free-text keywords with
+ * topic-shaped ones is ordinary and only the shaped half transfers.
+ */
+function readTopics(keywords: unknown): readonly string[] | undefined {
+  if (!Array.isArray(keywords)) return undefined
+
+  const topics = new Set<string>()
+  for (const entry of keywords) {
+    if (typeof entry !== 'string') continue
+    const topic = entry.trim().toLowerCase()
+    if (isValidTopic(topic)) topics.add(topic)
+    if (topics.size === MAX_TOPICS) break
+  }
+  return [...topics]
+}
+
+interface PackageFields {
+  readonly homepage?: unknown
+  readonly keywords?: unknown
+}
+
+async function readManifest(root: string): Promise<PackageFields | undefined> {
+  try {
+    const parsed: unknown = JSON.parse(
+      await readFile(join(root, 'package.json'), 'utf8'),
+    )
+    return (parsed ?? undefined) as PackageFields | undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Computes what this tree can propose for its own repository metadata, with
+ * no network call: an About text from the README's opening line, and a
+ * homepage and a topic set from `package.json`, the one manifest every
+ * target project this ships to already carries.
+ *
+ * A field a target project declares nowhere stays absent rather than empty,
+ * so the caller comparing this against the remote never treats a field this
+ * reader has no opinion on as a proposal to clear it.
+ */
+export async function proposeMetadata(root: string): Promise<MetadataProposal> {
+  const [readme, manifest] = await Promise.all([
+    readFile(join(root, 'README.md'), 'utf8').catch(() => undefined),
+    readManifest(root),
+  ])
+
+  const description =
+    readme === undefined ? undefined : extractOpeningLine(readme)
+
+  const homepage =
+    typeof manifest?.homepage === 'string' && manifest.homepage.trim() !== ''
+      ? manifest.homepage.trim()
+      : undefined
+
+  const topics = readTopics(manifest?.keywords)
+
+  return {
+    ...(description !== undefined && { description }),
+    ...(homepage !== undefined && { homepage }),
+    ...(topics !== undefined && topics.length > 0 && { topics }),
+  }
+}
+
+/**
+ * Compares a computed proposal against what the remote already carries.
+ *
+ * A field the proposal has no opinion on is never diffed, which is what
+ * keeps a target project with no `keywords` field from seeing every existing
+ * topic reported as a removal.
+ */
+export function compareMetadata(
+  current: CurrentMetadata,
+  proposed: MetadataProposal,
+): MetadataDiff {
+  const diff: {
+    description?: { current: string; proposed: string }
+    homepage?: { current: string; proposed: string }
+    topics?: { added: readonly string[]; removed: readonly string[] }
+  } = {}
+
+  if (
+    proposed.description !== undefined &&
+    proposed.description !== current.description
+  ) {
+    diff.description = {
+      current: current.description,
+      proposed: proposed.description,
+    }
+  }
+
+  if (
+    proposed.homepage !== undefined &&
+    proposed.homepage !== current.homepage
+  ) {
+    diff.homepage = { current: current.homepage, proposed: proposed.homepage }
+  }
+
+  if (proposed.topics !== undefined) {
+    const currentSet = new Set(current.topics)
+    const proposedSet = new Set(proposed.topics)
+    const added = proposed.topics.filter((topic) => !currentSet.has(topic))
+    const removed = current.topics.filter((topic) => !proposedSet.has(topic))
+    if (added.length > 0 || removed.length > 0) diff.topics = { added, removed }
+  }
+
+  return diff
+}

package/src/tasks/answers.ts

@@ -0,0 +1,195 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+import { isUnder } from '@/paths'
+import { readQuestions, splitPlanSections } from '@/records/validate'
+
+const PLANS_DIR = join('.claude', 'plans')
+const PLANS_ARCHIVE_DIR = join(PLANS_DIR, 'archive')
+const TASKS_DIR = join('.claude', 'tasks')
+
+/**
+ * The suggestion the plan standard fixes for a question that turns on the
+ * operator's preference rather than on a technical default. Every other
+ * suggestion is accepted by a blank slot, so only this phrase over an empty
+ * `- Answer:` is a stop.
+ */
+const OPERATOR_CALL = 'needs your call'
+
+const SUGGESTED_PREFIX = '- Suggested:'
+const ANSWER_PREFIX = '- Answer:'
+
+export const ANSWER_REFUSALS = ['no-plan', 'archived', 'bad-input'] as const
+
+export type AnswerRefusal = (typeof ANSWER_REFUSALS)[number]
+
+export interface AnswersRefused {
+  readonly ok: false
+  readonly reason: AnswerRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+/**
+ * One question the dispatch has to hand back. It carries the label rather than
+ * contributing to a count, since a dispatcher that refuses a row without naming
+ * the slot has nothing to give the operator.
+ */
+export interface OpenQuestion {
+  readonly label: string
+  readonly why: string
+}
+
+export interface PlanAnswers {
+  readonly ok: true
+  readonly plan: string
+  readonly launchable: boolean
+  readonly open: readonly OpenQuestion[]
+}
+
+export type AnswersOutcome = PlanAnswers | AnswersRefused
+
+/**
+ * The spellings a caller reaches a plan by, in the order they are tried. A bare
+ * slug names the live folder outright, and a path is resolved against the
+ * project root and against the board directory both.
+ *
+ * The second base is the one a dispatcher actually has to hand. A board row
+ * writes its `Plan:` link relative to `.claude/tasks/`, so the href reads
+ * `../plans/feature-<slug>.md`, and resolving that against the root alone lands
+ * a directory above the repository and refuses a plan that exists.
+ *
+ * `resolveLivePlan` reads a task's own line against the same two bases and is
+ * not this function. It tries the board first and tests containment under the
+ * live plans folder, where this tries the root first and tests nothing, so the
+ * two agree on the spellings a board writes and part company outside them.
+ * Sharing the bases is what makes a board link resolve for both, and the
+ * archive exclusion in `planAnswers` is stated separately for that reason.
+ *
+ * Root order is what keeps the documented forms unchanged. A reference that
+ * resolves from the root is taken there, and the board base is reached only by
+ * a path the root could not answer.
+ */
+export function planCandidates(root: string, reference: string): string[] {
+  if (reference.includes('/') || reference.endsWith('.md')) {
+    if (isAbsolute(reference)) return [reference]
+
+    return [resolve(root, reference), resolve(join(root, TASKS_DIR), reference)]
+  }
+
+  const slug = reference.startsWith('feature-')
+    ? reference.slice('feature-'.length)
+    : reference
+
+  return [join(root, PLANS_DIR, `feature-${slug}.md`)]
+}
+
+function suggestionOf(body: readonly string[]): string | undefined {
+  const line = body.find((entry) => entry.startsWith(SUGGESTED_PREFIX))
+
+  return line?.slice(SUGGESTED_PREFIX.length).trim()
+}
+
+/**
+ * An absent `- Answer:` line reads the same as a blank one here. The slot being
+ * missing is a conformance defect `canon tasks validate` already names, and a
+ * gate that answered it differently would refuse a row for a reason the
+ * validator has already reported.
+ */
+function isAnswered(body: readonly string[]): boolean {
+  const line = body.find((entry) => entry.startsWith(ANSWER_PREFIX))
+  if (line === undefined) return false
+
+  return line.slice(ANSWER_PREFIX.length).trim().length > 0
+}
+
+/**
+ * The standard writes the reason behind a comma and the corpus also writes it
+ * behind a full stop, so both separators come off. Reporting the phrase with
+ * whatever punctuation followed it hands the operator a stray mark where the
+ * reason should start.
+ */
+function reasonOf(suggested: string): string {
+  const rest = suggested.slice(OPERATOR_CALL.length).replace(/^[,.;:\s]+/, '')
+
+  return rest.length > 0 ? rest : 'no reason stated'
+}
+
+/**
+ * A question carrying no suggestion at all is also a stop at execution, and it
+ * is not read here. `checkQuestionContract` reports it as `suggestion-missing`
+ * and the runbook dispatches a row whose plan is already verified, so testing
+ * it again would put one rule in two places that ship on different cadences.
+ */
+function openQuestions(lines: readonly string[]): OpenQuestion[] {
+  const open: OpenQuestion[] = []
+
+  for (const question of readQuestions(lines)) {
+    const suggested = suggestionOf(question.body)
+    if (!suggested?.toLowerCase().startsWith(OPERATOR_CALL)) continue
+    if (isAnswered(question.body)) continue
+
+    open.push({ label: question.label, why: reasonOf(suggested) })
+  }
+
+  return open
+}
+
+/**
+ * Answers whether a plan is launchable, which is whether it still waits on the
+ * operator for a call only they can make. It reads the question block through
+ * the same `readQuestions` the plan validator runs, so the gate and the
+ * conformance check cannot drift into disagreeing about what a question is.
+ *
+ * It reports and never writes. Holding the row, naming the slot, and reaching
+ * the operator belong to the dispatcher, which is where the decision already
+ * sits.
+ */
+export async function planAnswers(
+  root: string,
+  reference: string,
+): Promise<AnswersOutcome> {
+  if (reference.trim().length === 0) {
+    return refuse('bad-input', 'No plan named. Pass a plan path or its slug.')
+  }
+
+  const candidates = planCandidates(root, reference)
+  const path = candidates.find((candidate) => existsSync(candidate))
+
+  if (!path) {
+    // Naming every base keeps a task-relative link from reporting the one place
+    // it does not resolve, since `relative` hands that spelling straight back.
+    const looked = candidates.map((entry) => relative(root, entry)).join(' or ')
+
+    return refuse('no-plan', `No plan at ${looked}.`, [reference])
+  }
+
+  // An archived plan answers every question and would report as launchable, so
+  // the name would clear a dispatch that `claude-autoship` Step 1 then refuses
+  // as already-shipped work. Catching it here is a step earlier than the worker.
+  if (isUnder(path, join(root, PLANS_ARCHIVE_DIR))) {
+    return refuse(
+      'archived',
+      `${relative(root, path)} sits in the plans archive, so it describes work that already shipped.`,
+      [reference],
+    )
+  }
+
+  const sections = splitPlanSections(await readFile(path, 'utf8'))
+  const open = openQuestions(sections.get('Questions') ?? [])
+
+  return {
+    ok: true,
+    plan: relative(root, path),
+    launchable: open.length === 0,
+    open,
+  }
+}
+
+function refuse(
+  reason: AnswerRefusal,
+  message: string,
+  detail: readonly string[] = [],
+): AnswersRefused {
+  return { ok: false, reason, message, detail }
+}

package/src/tasks/archive.ts

@@ -1,7 +1,8 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
-import { join, relative, resolve, sep } from 'node:path'
+import { join, relative, resolve } from 'node:path'
 import { regenOne } from '@/indexes/regen'
+import { isUnder } from '@/paths'
 
 const TASKS_DIR = join('.claude', 'tasks')
 const ARCHIVE_DIR = join(TASKS_DIR, 'archive')
@@ -180,14 +181,6 @@ function isRowFor(line: string, target: string): boolean {
   return first !== undefined && first.includes(target)
 }
 
-/**
- * Tests containment rather than a string prefix, so a sibling whose name merely
- * extends the folder's is not read as being inside it.
- */
-function isUnder(path: string, dir: string): boolean {
-  return path === dir || path.startsWith(`${dir}${sep}`)
-}
-
 /**
  * Resolves the `Plan:` target against the board and against the project root
  * both, which is how `claude-docs` reads the same line. It accepts `../plans/x.md`