@erclx/canon 4.108.0 → 4.110.0

package/src/help.ts

@@ -0,0 +1,196 @@
+import { palette } from '@/ui'
+
+const HELP_WIDTH = 80
+const SIGNATURE_WIDTH = 19
+const SANDBOX_SIGNATURE_WIDTH = 26
+const ROW_INDENT = '│    '.length
+
+type CommandRow = [signature: string, description: string]
+type HelpStream = { isTTY?: boolean }
+
+// The grouping mirrors the README's domain table and has no other source, so a
+// command added to the program needs a row here or help-option.test.ts fails.
+export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
+  {
+    title: 'Project',
+    rows: [
+      ['init [path]', 'Bootstrap a project with toolkit domains'],
+      ['sync [path]', 'Sync all installed domains in a project'],
+      ['upgrade', 'Reinstall the CLI with the manager that installed it'],
+      ['migrate [cmd]', 'Move a project off a retired name or layout'],
+      ['targets [cmd]', 'Projects this toolkit installed into (list, pulls)'],
+    ],
+  },
+  {
+    title: 'Domains',
+    rows: [
+      ['gov [cmd]', 'Governance rules (install, sync, list)'],
+      ['standards [cmd]', 'Standards (install, sync, list, <name>)'],
+      ['snippets [cmd]', 'Prompt snippets (create, list)'],
+      ['tooling [cmd]', 'Tooling stacks (sync, ref, create)'],
+      ['claude [cmd]', 'Claude workflow (init, sync, setup)'],
+      ['wiki [cmd]', 'Wiki pages (init)'],
+      ['indexes [cmd]', 'Regenerate index.md files (regen)'],
+      ['docs [cmd|topic]', 'Emit toolkit reference docs (list, <topic>)'],
+    ],
+  },
+  {
+    title: 'Author and render',
+    rows: [
+      ['design [cmd]', 'Design system (render, board)'],
+      ['slides [cmd]', 'Slide decks (render, list)'],
+      ['capture [source]', 'Render HTML capture sources to PNG'],
+      ['serve [dir]', 'Serve a directory on localhost, print the link'],
+      ['demo [cmd]', 'Record a running app (compile, run)'],
+      ['inventory [subj]', 'Report one computed property across every route'],
+      ['drive <url> <run>', 'Walk a page through interactions, measure each'],
+      ['transcripts <url>', 'Fetch a YouTube transcript with frontmatter'],
+      ['teach [cmd]', 'Learning workspaces (list, open, resource, glossary)'],
+    ],
+  },
+  {
+    title: 'Session and ship',
+    rows: [
+      ['sandbox [cat:cmd]', 'Provision and run sandbox scenarios'],
+      ['tasks [cmd]', 'Task board (validate, archive)'],
+      ['intake [cmd]', 'Intake folders under .canon/intake/ (list, answer)'],
+      ['records [cmd]', 'Session records (validate, size, push, pull)'],
+      ['sessions [cmd]', 'Resolve live sessions to worktree and branch'],
+      ['worktrees [cmd]', 'Reclaim worktrees whose branches merged'],
+      ['autoship [cmd]', 'Decide whether a changed set needs review'],
+      ['pr [cmd]', 'Read a pull request (key-changes, head, checks)'],
+      ['feedback', 'Write toolkit feedback from stdin'],
+    ],
+  },
+  {
+    title: 'Repo reports',
+    rows: [
+      ['audits [cmd]', 'Run every health check as one set (run, list)'],
+      ['gate [cmd]', 'Run the merge gate stage by stage (run)'],
+      ['secrets [cmd]', 'Scan the shipped tree for credentials (scan)'],
+      ['deps [cmd]', 'Read the dependency set for advisories (audit)'],
+      ['labels [cmd]', 'Read a changed set against the label map (audit)'],
+      ['comments [cmd]', 'Measure comment density and trend (scan)'],
+      ['context [cmd]', 'Report context folder health (audit)'],
+      ['markdown [cmd]', 'Report markdown against the standards (audit)'],
+      ['repo [cmd]', 'Remote metadata (metadata propose, apply)'],
+      ['census [path]', 'Report file count, extensions, and line totals'],
+    ],
+  },
+]
+
+const SANDBOX_ROWS: CommandRow[] = [
+  ['canon sandbox', 'Interactive scenario picker'],
+  ['canon sandbox git:commit', 'Run specific scenario'],
+  ['canon sandbox reset', 'Reset sandbox to baseline'],
+  ['canon sandbox clean', 'Wipe the sandbox'],
+]
+
+const EXAMPLES = [
+  'canon sync ../my-app',
+  'canon sandbox git:commit',
+  'canon gov install react',
+  'canon gov sync ../my-app',
+  'canon gov restated --json',
+  'canon standards markdown',
+  'canon snippets list',
+  'canon init ../my-app',
+  'canon tooling sync base',
+  'canon tooling create',
+  'canon claude init',
+  'canon indexes regen',
+  'canon indexes regen --dry-run --json',
+  'canon docs list --json',
+  'canon docs agents',
+  'canon design render',
+  'canon design board',
+  'canon slides render',
+  'canon slides list --json',
+  'canon capture assets/captures/install.html --selector .window --out assets/evidence',
+  'canon serve .canon/teach',
+  'canon inventory focus --json',
+  'canon drive http://localhost:4173 run.json --json',
+  'pbpaste | canon feedback',
+  'canon transcripts https://youtu.be/VIDEO_ID',
+  'canon tasks archive --pull-request 673 --json',
+  'canon intake list toolkit-overview --unread --json',
+  'canon teach list --json',
+  'canon comments scan src --json',
+  'canon context audit --json',
+  'canon markdown audit .claude/rules --json',
+  'canon records validate plans',
+  'canon records size --json',
+  'canon records push --json',
+  'canon sessions list --json',
+  'canon worktrees list --json',
+  'canon worktrees reclaim --dry-run',
+  'canon secrets scan --json',
+  'canon deps audit --json',
+  'canon labels audit --json',
+  'canon repo metadata propose --json',
+  'canon census --json',
+  'canon audits run --json',
+  'canon gate run --all --no-write',
+  'canon upgrade --json',
+]
+
+// The frame follows stdout's TTY state rather than `palette`, whose blank
+// palette keeps every glyph so the stderr frames a captured run quotes stay
+// framed. A glyph is rendering rather than color, so NO_COLOR keeps it.
+function isFramed(stream: HelpStream): boolean {
+  return stream.isTTY === true
+}
+
+function gutter(stream: HelpStream): string {
+  if (!isFramed(stream)) return ''
+  const { GREY, NC } = palette(stream)
+  return `${GREY}│${NC}`
+}
+
+// A row past the width is cut rather than wrapped, since a wrapped row breaks
+// the alignment the grouping exists to buy. The cut is computed from the framed
+// prefix in both forms, so a pipe carries the same text as a terminal.
+export function commandRow(
+  signature: string,
+  description: string,
+  stream: HelpStream,
+): string {
+  const { GREY, NC } = palette(stream)
+  const room = HELP_WIDTH - ROW_INDENT - SIGNATURE_WIDTH - '# '.length
+  const text =
+    description.length > room
+      ? `${description.slice(0, room - 1)}…`
+      : description
+  return `${gutter(stream)}    ${signature.padEnd(SIGNATURE_WIDTH)}${GREY}# ${text}${NC}`
+}
+
+export function renderHelp(stream: HelpStream): string {
+  const { GREY, NC, WHITE } = palette(stream)
+  const bar = gutter(stream)
+  const usage = `${WHITE}Usage:${NC} canon [command]`
+  const lines = [
+    ...(isFramed(stream)
+      ? [`${GREY}┌${NC}`, `${GREY}├${NC} ${usage}`]
+      : [usage]),
+    bar,
+    `${bar}  ${WHITE}Commands:${NC}`,
+    ...COMMAND_GROUPS.flatMap((group) => [
+      bar,
+      `${bar}  ${WHITE}${group.title}${NC}`,
+      ...group.rows.map(([signature, description]) =>
+        commandRow(signature, description, stream),
+      ),
+    ]),
+    bar,
+    `${bar}  ${WHITE}Sandbox:${NC}`,
+    ...SANDBOX_ROWS.map(
+      ([signature, description]) =>
+        `${bar}    ${signature.padEnd(SANDBOX_SIGNATURE_WIDTH)}${GREY}# ${description}${NC}`,
+    ),
+    bar,
+    `${bar}  ${WHITE}Examples:${NC}`,
+    ...EXAMPLES.map((example) => `${bar}    ${example}`),
+    ...(isFramed(stream) ? [`${GREY}└${NC}`] : []),
+  ]
+  return lines.join('\n')
+}

package/src/pr/checks.ts

@@ -29,6 +29,35 @@ export interface ChecksReading {
   readonly collapsed: number
 }
 
+export interface ConflictedReading extends ChecksReading {
+  /** The branch conflicts with its base, so no run will ever start for the tip. */
+  readonly conflicted: boolean
+  /** The pull request's `mergeStateStatus`, absent when the read carried none. */
+  readonly mergeState?: string
+}
+
+/**
+ * Tells a conflicted pull request from a tip whose runs have not started.
+ *
+ * A branch that conflicts with its base gets no merge ref, so no
+ * `pull_request` workflow runs and the listing stays empty, which
+ * `collapseChecks` can only call pending. Only `DIRTY` separates the two, and
+ * only while no run belongs to the tip: a conflict arising after runs
+ * completed leaves those runs standing as a real answer. `UNKNOWN` is
+ * transient while GitHub computes it, so it reads as not conflicted and costs
+ * a caller one more poll.
+ */
+export function withMergeState(
+  mergeState: string | undefined,
+  reading: ChecksReading,
+): ConflictedReading {
+  return {
+    ...reading,
+    conflicted: mergeState === 'DIRTY' && reading.matched === 0,
+    ...(mergeState !== undefined && { mergeState }),
+  }
+}
+
 /**
  * Puts a check-run row into the shape `rollup` reads.
  *

package/src/tasks/label.ts

@@ -1,5 +1,7 @@
 import { existsSync } from 'node:fs'
+import { mkdir, readdir } from 'node:fs/promises'
 import { relative } from 'node:path'
+import { recordDir } from '@/record-root'
 import {
   archiveDir,
   declinedDir,
@@ -21,6 +23,12 @@ const FIRST_LABEL: Label = { major: 1, minor: 0 }
  */
 export const LABEL_PATTERN = /^v(\d+)\.(\d+)-/
 
+/** A reservation is named by the bare label, with no slug behind it. */
+const RESERVATION_PATTERN = /^v(\d+)\.(\d+)$/
+
+/** Bounds the claim loop. A fifth loss in a row is not a race. */
+const MAX_ATTEMPTS = 5
+
 interface Label {
   readonly major: number
   readonly minor: number
@@ -31,18 +39,23 @@ export interface NextLabel {
   readonly label: string
   /** The label this run was derived from, absent when neither folder holds one. */
   readonly highest: string | undefined
+  /** Whether this label was reserved on disk rather than only read. */
+  readonly claimed: boolean
 }
 
 export interface LabelRefused {
   readonly ok: false
-  readonly reason: 'no-board'
+  readonly reason: 'no-board' | 'label-contended'
   readonly message: string
 }
 
 export type LabelOutcome = NextLabel | LabelRefused
 
-function parseLabel(stem: string): Label | undefined {
-  const match = LABEL_PATTERN.exec(stem)
+function parseLabel(
+  stem: string,
+  pattern: RegExp = LABEL_PATTERN,
+): Label | undefined {
+  const match = pattern.exec(stem)
   if (!match) return undefined
 
   return { major: Number(match[1]), minor: Number(match[2]) }
@@ -71,6 +84,54 @@ function next(label: Label): Label {
     : { major: label.major, minor: label.minor + 1 }
 }
 
+function noBoard(root: string, dir: string): LabelRefused {
+  return {
+    ok: false,
+    reason: 'no-board',
+    message: `No task board at ${relative(root, dir)}.`,
+  }
+}
+
+function reservationsDir(root: string): string {
+  return recordDir(root, 'ordinal-locks')
+}
+
+async function listReservations(root: string): Promise<string[]> {
+  try {
+    const entries = await readdir(reservationsDir(root), {
+      withFileTypes: true,
+    })
+    return entries.filter((entry) => entry.isDirectory()).map((e) => e.name)
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return []
+    }
+    throw error
+  }
+}
+
+function highestOf(
+  names: readonly string[],
+  pattern: RegExp,
+): Label | undefined {
+  return names
+    .map((name) => parseLabel(name, pattern))
+    .filter((label): label is Label => label !== undefined)
+    .reduce<Label | undefined>(
+      (max, label) => (max === undefined || isHigher(label, max) ? label : max),
+      undefined,
+    )
+}
+
+async function readStems(root: string): Promise<string[]> {
+  const settled = [archiveDir(root), declinedDir(root)].filter((candidate) =>
+    existsSync(candidate),
+  )
+  const dirs = [tasksDir(root), ...settled]
+
+  return (await Promise.all(dirs.map((d) => listTaskStems(d)))).flat()
+}
+
 /**
  * Reports the next unused phase label, read off the true maximum across
  * `.canon/tasks/` and its `archive/` and `declined/` siblings together. A scan
@@ -78,41 +139,87 @@ function next(label: Label): Label {
  * spent, which is what let two sessions hand out the same label within
  * minutes of each other.
  *
- * It reports and never writes. Two sessions calling it in the same second can
- * still take the same answer, since the board is gitignored files rather than
- * a store with a lock, and `standards/versioning.md` permits free renumbering,
- * so a collision costs a rename rather than anything worse. A duplicate label
- * already sitting in the tree, and a gap left by a renumbering, both fold into
- * the same max scan without needing a dedicated check.
+ * It reports and never writes. `claimLabel` is the variant that reserves. A
+ * duplicate label already sitting in the tree, and a gap left by a
+ * renumbering, both fold into the same max scan without needing a dedicated
+ * check.
  */
 export async function nextLabel(root: string): Promise<LabelOutcome> {
   const dir = tasksDir(root)
+  if (!existsSync(dir)) return noBoard(root, dir)
 
-  if (!existsSync(dir)) {
-    return {
-      ok: false,
-      reason: 'no-board',
-      message: `No task board at ${relative(root, dir)}.`,
-    }
+  const highest = highestOf(await readStems(root), LABEL_PATTERN)
+
+  return {
+    ok: true,
+    label: formatLabel(highest === undefined ? FIRST_LABEL : next(highest)),
+    highest: highest === undefined ? undefined : formatLabel(highest),
+    claimed: false,
   }
+}
 
-  const settled = [archiveDir(root), declinedDir(root)].filter((candidate) =>
-    existsSync(candidate),
-  )
-  const dirs = [dir, ...settled]
-  const stems = (await Promise.all(dirs.map((d) => listTaskStems(d)))).flat()
+interface ClaimOptions {
+  /** Takes the reservation, resolving false when another claim holds it. */
+  readonly reserve?: (root: string, label: string) => Promise<boolean>
+}
 
-  const highest = stems
-    .map(parseLabel)
-    .filter((label): label is Label => label !== undefined)
-    .reduce<Label | undefined>(
-      (max, label) => (max === undefined || isHigher(label, max) ? label : max),
-      undefined,
+async function reserveLabel(root: string, label: string): Promise<boolean> {
+  await mkdir(reservationsDir(root), { recursive: true })
+
+  try {
+    await mkdir(recordDir(root, 'ordinal-locks', label), { recursive: false })
+    return true
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+      return false
+    }
+    throw error
+  }
+}
+
+/**
+ * Reserves the next label through an exclusive `mkdir` under
+ * `.canon/ordinal-locks/`, so a second claim lands on a different one.
+ *
+ * The scan counts every reservation beside the task stems. The skill writes
+ * the task file after this returns, so a reservation with no file behind it is
+ * the ordinary state for a few seconds, and a scan blind to it would offer the
+ * same label to every retry. Reservations are never expired: a claim that died
+ * leaves a gap, and `standards/versioning.md` permits gaps.
+ */
+export async function claimLabel(
+  root: string,
+  options: ClaimOptions = {},
+): Promise<LabelOutcome> {
+  const dir = tasksDir(root)
+  if (!existsSync(dir)) return noBoard(root, dir)
+
+  const reserve = options.reserve ?? reserveLabel
+
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+    const stems = highestOf(await readStems(root), LABEL_PATTERN)
+    const held = highestOf(await listReservations(root), RESERVATION_PATTERN)
+    const highest =
+      stems !== undefined && (held === undefined || isHigher(stems, held))
+        ? stems
+        : held
+    const label = formatLabel(
+      highest === undefined ? FIRST_LABEL : next(highest),
     )
 
+    if (await reserve(root, label)) {
+      return {
+        ok: true,
+        label,
+        highest: highest === undefined ? undefined : formatLabel(highest),
+        claimed: true,
+      }
+    }
+  }
+
   return {
-    ok: true,
-    label: formatLabel(highest === undefined ? FIRST_LABEL : next(highest)),
-    highest: highest === undefined ? undefined : formatLabel(highest),
+    ok: false,
+    reason: 'label-contended',
+    message: `Could not reserve a label after ${MAX_ATTEMPTS} attempts. Re-run the claim.`,
   }
 }