@erclx/canon 4.0.0

package/src/ui.ts

@@ -0,0 +1,266 @@
+export interface Palette {
+  readonly GREEN: string
+  readonly RED: string
+  readonly YELLOW: string
+  readonly WHITE: string
+  readonly GREY: string
+  readonly NC: string
+}
+
+const COLOR: Palette = {
+  GREEN: '\x1b[0;32m',
+  RED: '\x1b[0;31m',
+  YELLOW: '\x1b[0;33m',
+  WHITE: '\x1b[1;37m',
+  GREY: '\x1b[0;90m',
+  NC: '\x1b[0m',
+}
+
+/**
+ * The blank palette keeps every frame character and drops only the escapes, so
+ * a captured run still reads as one block.
+ */
+const PLAIN: Palette = {
+  GREEN: '',
+  RED: '',
+  YELLOW: '',
+  WHITE: '',
+  GREY: '',
+  NC: '',
+}
+
+/**
+ * `NO_COLOR` follows the published convention, where any non-empty value turns
+ * color off whatever the value says.
+ */
+export function supportsColor(stream: { isTTY?: boolean }): boolean {
+  const optOut = process.env.NO_COLOR
+  if (optOut !== undefined && optOut !== '') return false
+  return stream.isTTY === true
+}
+
+/**
+ * The question is asked per stream rather than once for the process. The framed
+ * output goes to stderr and a structured record to stdout, so a run piping only
+ * its data keeps a terminal on stderr and keeps its color there. This is a
+ * third question again from `isNonInteractive`, which answers whether a caller
+ * can be prompted rather than whether a destination renders escapes.
+ *
+ * Read at write time rather than at import, so nothing freezes an answer taken
+ * before the caller's environment was in place.
+ */
+export function palette(stream: { isTTY?: boolean }): Palette {
+  return supportsColor(stream) ? COLOR : PLAIN
+}
+
+export function intro(title: string): void {
+  const { GREY, NC, WHITE } = palette(process.stderr)
+  process.stderr.write(`${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}${title}${NC}\n`)
+}
+
+/**
+ * Timeline log levels matching `scripts/lib/ui.sh`, so a migrated command
+ * prints the same frame as the bash it replaced. All output is stderr,
+ * leaving stdout clean for JSON and lists.
+ */
+export function logInfo(message: string): void {
+  const { GREEN, GREY, NC } = palette(process.stderr)
+  process.stderr.write(`${GREY}│${NC} ${GREEN}✓${NC} ${message}\n`)
+}
+
+export function logWarn(message: string): void {
+  const { GREY, NC, YELLOW } = palette(process.stderr)
+  process.stderr.write(`${GREY}│${NC} ${YELLOW}!${NC} ${message}\n`)
+}
+
+export function logAdd(message: string): void {
+  const { GREEN, GREY, NC } = palette(process.stderr)
+  process.stderr.write(`${GREY}│${NC} ${GREEN}+${NC} ${message}\n`)
+}
+
+export function logRemove(message: string): void {
+  const { GREY, NC, RED } = palette(process.stderr)
+  process.stderr.write(`${GREY}│${NC} ${RED}-${NC} ${message}\n`)
+}
+
+/**
+ * Renders the `✗` shape `docs/agents/output-shape.md` specifies for a failure inside an
+ * open frame. It does not exit, so the caller closes the frame and returns an
+ * exit code rather than terminating mid-write.
+ */
+export function logError(message: string): void {
+  const { GREY, NC, RED } = palette(process.stderr)
+  process.stderr.write(`${GREY}│${NC} ${RED}✗${NC} ${message}\n`)
+}
+
+export function logStep(message: string): void {
+  const { GREY, NC, WHITE } = palette(process.stderr)
+  process.stderr.write(`${GREY}│${NC}\n${GREY}├${NC} ${WHITE}${message}${NC}\n`)
+}
+
+export function outro(): void {
+  const { GREY, NC } = palette(process.stderr)
+  process.stderr.write(`${GREY}└${NC}\n`)
+}
+
+/**
+ * Indents borrowed output inside an open frame, matching `pipe_output` in
+ * `scripts/lib/ui.sh`. Used for a document the command did not compose itself,
+ * such as a pull request body or the output of a git mutation.
+ */
+export function pipeOutput(text: string): void {
+  const { GREY, NC } = palette(process.stderr)
+  const lines = text.replace(/\n$/, '').split('\n')
+  process.stderr.write(
+    `${lines.map((line) => `${GREY}│${NC}  ${line}`).join('\n')}\n`,
+  )
+}
+
+/** Counts a noun for a report line, where the plural is the bare `s` form. */
+export function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`
+}
+
+export function frameError(message: string): void {
+  const { GREY, NC, RED } = palette(process.stderr)
+  process.stderr.write(
+    `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${message}\n${GREY}└${NC}\n`,
+  )
+}
+
+export function frameSuccess(command: string, target: string): void {
+  const { GREEN, GREY, NC, WHITE } = palette(process.stderr)
+  process.stderr.write(
+    `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}${command}${NC}\n${GREY}│${NC}\n${GREY}│${NC} ${GREEN}✓${NC} ${target}\n${GREY}└${NC}\n`,
+  )
+}
+
+/**
+ * The retired spelling is still honored, and permanently.
+ *
+ * This variable is the documented way to drive any command headlessly, so
+ * every skill body, CI job, and operator script already written sets the old
+ * name. Those callers live in other repositories and in plugin caches this
+ * release cannot reach, and the failure mode of dropping the fallback is a
+ * command that quietly waits for a TTY nobody is watching rather than one that
+ * refuses and says why.
+ */
+export function isNonInteractive(): boolean {
+  return (
+    process.env.CANON_NON_INTERACTIVE === '1' ||
+    // canon-keep-retired
+    process.env.AITK_NON_INTERACTIVE === '1'
+  )
+}
+
+/**
+ * `nonInteractiveDefault` opts a prompt into the `select_option` behavior from
+ * `scripts/lib/ui.sh`, where `CANON_NON_INTERACTIVE=1` resolves to the first
+ * option instead of failing. Callers that would rather fail loudly than pick
+ * for the user leave it off.
+ */
+export async function select<Value>(opts: {
+  message: string
+  options: { value: Value; label: string; hint?: string }[]
+  nonInteractiveDefault?: boolean
+}): Promise<Value> {
+  const { message, options } = opts
+  const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
+  const count = options.length
+  let cursor = 0
+
+  if (opts.nonInteractiveDefault && isNonInteractive()) {
+    process.stderr.write(
+      `${GREY}│${NC}\n${GREY}◇${NC} ${message} ${WHITE}${options[0].label}${NC}\n`,
+    )
+    return options[0].value
+  }
+
+  const render = (): void => {
+    let out = `${GREY}│${NC}\n${GREEN}◆${NC} ${message}\n`
+    for (let i = 0; i < count; i++) {
+      const label = options[i].label
+      const hint = options[i].hint ? ` ${GREY}${options[i].hint}${NC}` : ''
+      if (i === cursor) {
+        out += `${GREY}│${NC}  ${GREEN}❯ ${label}${NC}${hint}\n`
+      } else {
+        out += `${GREY}│${NC}    ${GREY}${label}${NC}${hint}\n`
+      }
+    }
+    process.stderr.write(out)
+  }
+
+  const clear = (): void => {
+    process.stderr.write(`\x1b[${count + 2}A\x1b[J`)
+  }
+
+  return new Promise<Value>((resolve) => {
+    if (!process.stdin.isTTY) {
+      process.stderr.write(
+        `${GREY}│${NC} ${RED}✗${NC} ${message} requires a TTY. Pass an argument or set CANON_NON_INTERACTIVE=1.\n${GREY}└${NC}\n`,
+      )
+      process.exit(1)
+    }
+
+    const wasRaw = process.stdin.isRaw
+    process.stdin.setRawMode(true)
+    process.stdin.resume()
+
+    render()
+
+    const onData = (data: Buffer): void => {
+      const key = data.toString()
+
+      if (key === '\x1b[A' || key === 'k') {
+        cursor = (cursor - 1 + count) % count
+        clear()
+        render()
+      } else if (key === '\x1b[B' || key === 'j') {
+        cursor = (cursor + 1) % count
+        clear()
+        render()
+      } else if (key === '\r' || key === '\n') {
+        cleanup()
+        clear()
+        process.stderr.write(
+          `${GREY}│${NC}\n${GREY}◇${NC} ${message} ${WHITE}${options[cursor].label}${NC}\n`,
+        )
+        resolve(options[cursor].value)
+      } else if (key === '\x1b' || key === 'q' || key === '\x03') {
+        cleanup()
+        clear()
+        process.stderr.write(
+          `${GREY}│${NC}\n${GREY}◇${NC} ${message} ${RED}Cancelled${NC}\n${GREY}└${NC}\n`,
+        )
+        process.exit(1)
+      }
+    }
+
+    const cleanup = (): void => {
+      process.stdin.removeListener('data', onData)
+      process.stdin.setRawMode(wasRaw ?? false)
+      process.stdin.pause()
+    }
+
+    process.stdin.on('data', onData)
+  })
+}
+
+export async function confirm(opts: {
+  message: string
+  active?: string
+  inactive?: string
+}): Promise<boolean> {
+  const active = opts.active ?? 'Yes'
+  const inactive = opts.inactive ?? 'No'
+
+  const result = await select({
+    message: opts.message,
+    options: [
+      { value: true, label: active },
+      { value: false, label: inactive },
+    ],
+  })
+
+  return result
+}

package/src/version/compare.ts

@@ -0,0 +1,53 @@
+/**
+ * A `major.minor.patch` core with an optional prerelease tail. The registry
+ * publishes both shapes under the same dist tag, so a comparison that only
+ * understood the core would read `1.0.0-rc.1` as unparseable and report the
+ * whole lookup as unknown.
+ */
+const VERSION =
+  /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
+
+export interface ParsedVersion {
+  readonly major: number
+  readonly minor: number
+  readonly patch: number
+  /** Absent on a release, which sorts above every prerelease of the same core. */
+  readonly prerelease?: string
+}
+
+export function parseVersion(raw: string): ParsedVersion | undefined {
+  const match = VERSION.exec(raw.trim())
+  if (match === null) return undefined
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    ...(match[4] === undefined ? {} : { prerelease: match[4] }),
+  }
+}
+
+/**
+ * Negative when `left` is older, positive when it is newer, zero when the two
+ * name the same version.
+ *
+ * Prerelease identifiers compare as whole strings rather than dot segment by
+ * dot segment, which is narrower than semver states. Every version this repo
+ * publishes is a plain core, so the ordering inside a prerelease series decides
+ * nothing here, and the one comparison that matters is that any prerelease
+ * sorts below the release sharing its core.
+ */
+export function compareVersions(
+  left: ParsedVersion,
+  right: ParsedVersion,
+): number {
+  if (left.major !== right.major) return left.major - right.major
+  if (left.minor !== right.minor) return left.minor - right.minor
+  if (left.patch !== right.patch) return left.patch - right.patch
+
+  if (left.prerelease === right.prerelease) return 0
+  if (left.prerelease === undefined) return 1
+  if (right.prerelease === undefined) return -1
+
+  return left.prerelease < right.prerelease ? -1 : 1
+}

package/src/version/installed.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { PROJECT_ROOT } from '@/project-root'
+
+/** What a reader prints in place of a field the manifest did not carry. */
+export const UNKNOWN_LABEL = 'unknown'
+
+/**
+ * Either field is absent when the manifest could not be read or did not carry
+ * it. They are optional rather than sentinel strings so a caller has to narrow
+ * before using one, which is what makes a name the manifest never supplied
+ * impossible to interpolate into a shell command. A sentinel typed `string`
+ * reads as an ordinary value at every call site and hides that case.
+ */
+export interface InstalledPackage {
+  readonly name?: string
+  readonly version?: string
+}
+
+/**
+ * Read at runtime rather than inlined, because a literal is a second place the
+ * version lives and it stopped tracking `package.json` at `0.1.0`. The release
+ * tool writes one file and this follows it. `package.json` ships in every npm
+ * tarball regardless of the `files` list, so the read resolves from a registry
+ * install as well as from a clone.
+ *
+ * This sits apart from the skew read so `src/cli.ts` can name the version on
+ * every invocation without pulling the registry lookup into the startup import
+ * graph of a CLI that compiles nothing ahead of time.
+ */
+export function readInstalled(root: string = PROJECT_ROOT): InstalledPackage {
+  try {
+    const raw = readFileSync(join(root, 'package.json'), 'utf8')
+    const parsed = JSON.parse(raw) as { name?: string; version?: string }
+
+    return { name: parsed.name, version: parsed.version }
+  } catch {
+    return {}
+  }
+}

package/src/version/manager.ts

@@ -0,0 +1,67 @@
+export type ManagerId = 'bun' | 'pnpm' | 'yarn' | 'npm'
+
+export interface Manager {
+  readonly id: ManagerId
+  /** The path segment the detection matched, so a wrong read is correctable. */
+  readonly evidence: string
+}
+
+/**
+ * Segments that only appear in one manager's global install tree, checked
+ * before the `node_modules` fallback because every one of these trees contains
+ * a `node_modules` too.
+ */
+const SIGNATURES: readonly (readonly [ManagerId, string])[] = [
+  ['bun', '.bun'],
+  ['pnpm', 'pnpm'],
+  ['pnpm', '.pnpm'],
+  ['yarn', 'yarn'],
+  ['yarn', '.yarn'],
+]
+
+/**
+ * Which package manager installed the package rooted at `root`, read off the
+ * install path rather than guessed from what is on `PATH`.
+ *
+ * Removing the guess is the whole case for the upgrade verb, so a detection
+ * that cannot be read back is worth no more than the guess it replaced. The
+ * evidence travels with the answer and the verb prints it before running
+ * anything, which lets an operator correct a wrong read without the detection
+ * having to be right every time.
+ *
+ * Returns `undefined` for a path outside any install tree, which is a source
+ * checkout. That is not a case to guess at either: reinstalling over a clone
+ * would replace what the operator is working in.
+ */
+export function detectManager(root: string): Manager | undefined {
+  const segments = root.split(/[/\\]/).filter((segment) => segment !== '')
+
+  for (const [id, signature] of SIGNATURES) {
+    if (segments.includes(signature)) return { id, evidence: signature }
+  }
+
+  if (segments.includes('node_modules')) {
+    return { id: 'npm', evidence: 'node_modules' }
+  }
+
+  return undefined
+}
+
+/** The global reinstall each manager spells, pinned to the newest published. */
+export function installCommand(
+  manager: ManagerId,
+  name: string,
+): readonly string[] {
+  const spec = `${name}@latest`
+
+  switch (manager) {
+    case 'bun':
+      return ['bun', 'add', '--global', spec]
+    case 'pnpm':
+      return ['pnpm', 'add', '--global', spec]
+    case 'yarn':
+      return ['yarn', 'global', 'add', spec]
+    case 'npm':
+      return ['npm', 'install', '--global', spec]
+  }
+}

package/src/version/skew.ts

@@ -0,0 +1,192 @@
+import { PROJECT_ROOT } from '@/project-root'
+import { compareVersions, parseVersion } from '@/version/compare'
+import {
+  type InstalledPackage,
+  readInstalled,
+  UNKNOWN_LABEL,
+} from '@/version/installed'
+import { detectManager } from '@/version/manager'
+
+const REGISTRY = 'https://registry.npmjs.org'
+
+/**
+ * Short enough that a check waiting on a dead network still returns inside the
+ * time an operator would give the command anyway. The skew line is one section
+ * of a report the rest of which needs no network at all, so the budget is set
+ * against how long the report may be held up rather than against how long the
+ * registry usually takes.
+ */
+const LOOKUP_TIMEOUT_MS = 3_000
+
+/**
+ * Three states and no fourth. `unknown` covers every way the question could not
+ * be answered and carries the reason, which is what a caller reports instead of
+ * a version.
+ *
+ * An installed version ahead of the published one reports `current`. That is a
+ * source checkout between a release commit and the publish job, or a local
+ * build, and neither is skew. Giving it a state of its own would fire a warning
+ * on every maintainer run for a condition with no remedy.
+ */
+export type SkewState = 'current' | 'behind' | 'unknown'
+
+interface SkewBase {
+  readonly name: string
+  readonly installed: string
+}
+
+/**
+ * A union rather than one shape with two optional fields, so a `behind` report
+ * cannot exist without the version it is behind and an `unknown` one cannot
+ * exist without its reason. Both are what `describeSkew` renders into a line an
+ * operator reads, and an optional field renders the word `undefined` there.
+ */
+export type SkewReport =
+  | (SkewBase & {
+      readonly state: 'current' | 'behind'
+      readonly latest: string
+    })
+  | (SkewBase & { readonly state: 'unknown'; readonly reason: string })
+
+/** Resolves the newest published version, or throws for `readSkew` to absorb. */
+export type LatestLookup = (name: string) => Promise<string>
+
+export interface SkewOptions {
+  readonly installed?: InstalledPackage
+  readonly lookup?: LatestLookup
+}
+
+/**
+ * The installed version against the newest published one.
+ *
+ * Never rejects and never reports through an exit code. `canon sync --check
+ * --exit-code` gates CI on drift it measured locally, so a lookup that failed
+ * the caller would turn an offline machine into a failing check and the check
+ * would be routed around. Every failure lands in `unknown` with its reason.
+ */
+export async function readSkew(options: SkewOptions = {}): Promise<SkewReport> {
+  const installed = options.installed ?? readInstalled()
+  const lookup = options.lookup ?? fetchLatest
+  const { name, version } = installed
+
+  if (version === undefined) {
+    return unknown(
+      installed,
+      'No version in the package manifest, so there is nothing to compare.',
+    )
+  }
+
+  if (name === undefined) {
+    return unknown(
+      installed,
+      'No name in the package manifest, so the registry has nothing to look up.',
+    )
+  }
+
+  const local = parseVersion(version)
+  if (local === undefined) {
+    return unknown(
+      installed,
+      `Installed version ${version} is not a version this can parse.`,
+    )
+  }
+
+  let raw: string
+  try {
+    raw = await lookup(name)
+  } catch (error) {
+    return unknown(installed, `Registry lookup failed: ${describe(error)}`)
+  }
+
+  const published = parseVersion(raw)
+  if (published === undefined) {
+    return unknown(
+      installed,
+      `Registry reported ${raw} as the newest version, which is not a version this can parse.`,
+    )
+  }
+
+  return {
+    state: compareVersions(local, published) < 0 ? 'behind' : 'current',
+    name,
+    installed: version,
+    latest: raw,
+  }
+}
+
+function unknown(installed: InstalledPackage, reason: string): SkewReport {
+  return {
+    state: 'unknown',
+    name: installed.name ?? UNKNOWN_LABEL,
+    installed: installed.version ?? UNKNOWN_LABEL,
+    reason,
+  }
+}
+
+/** The newest published version, or `undefined` when it could not be read. */
+export function latestOf(report: SkewReport): string | undefined {
+  return report.state === 'unknown' ? undefined : report.latest
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * The dist-tag endpoint rather than the full packument, which for this package
+ * carries every published manifest and is the larger part of a megabyte. The
+ * question is one string and this is the endpoint that answers only it.
+ */
+async function fetchLatest(name: string): Promise<string> {
+  const response = await fetch(
+    `${REGISTRY}/-/package/${encodeURIComponent(name)}/dist-tags`,
+    {
+      signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
+      headers: { accept: 'application/json' },
+    },
+  )
+
+  if (!response.ok) {
+    throw new Error(`registry returned ${response.status}`)
+  }
+
+  const tags = (await response.json()) as Record<string, unknown>
+  const latest = tags.latest
+
+  if (typeof latest !== 'string') {
+    throw new Error('registry reported no latest dist-tag')
+  }
+
+  return latest
+}
+
+/**
+ * One line naming the state, for a caller that renders the skew beside sections
+ * it does not own. Held here so `canon sync --check` and `canon claude skills
+ * drift` cannot word the same three states differently.
+ *
+ * The remedy is chosen by the same detection `canon upgrade` runs, because both
+ * callers run from a source checkout routinely and that is where the verb
+ * refuses. Naming it unconditionally sends a contributor whose clone sits a
+ * release behind to a command that declines. The read is a match against the
+ * root string rather than a filesystem call, so the line stays cheap.
+ */
+export function describeSkew(
+  report: SkewReport,
+  root: string = PROJECT_ROOT,
+): string {
+  if (report.state === 'unknown') {
+    return `Installed ${report.installed}, published unknown. ${report.reason}`
+  }
+
+  if (report.state === 'current') {
+    return `Installed ${report.installed}, which is the newest published.`
+  }
+
+  const remedy =
+    detectManager(root) === undefined
+      ? 'This is a source checkout, so pull rather than reinstalling.'
+      : 'Run `canon upgrade`.'
+
+  return `Installed ${report.installed}, published ${report.latest}. ${remedy}`
+}

package/src/wiki/init.ts

@@ -0,0 +1,85 @@
+import { existsSync, statSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const WIKI_DIR = join('.claude', 'wiki')
+const LEGACY_WIKI_DIR = 'wiki'
+const INDEX_FILE = 'index.md'
+
+export const WIKI_DIR_REL = `${WIKI_DIR}/`
+export const WIKI_INDEX_REL = join(WIKI_DIR, INDEX_FILE)
+export const LEGACY_WIKI_DIR_REL = `${LEGACY_WIKI_DIR}/`
+
+const INDEX_SEED = `---
+title: Wiki
+subtitle: Reference pages for tools, workflows, and concepts
+---
+
+# Wiki
+
+Reference pages for tools, workflows, and concepts.
+`
+
+export type WikiChange = 'dir' | 'index'
+
+export interface WikiPlan {
+  readonly changes: readonly WikiChange[]
+  readonly hasIndex: boolean
+  readonly hasLegacyWiki: boolean
+}
+
+export function wikiDir(target: string): string {
+  return join(target, WIKI_DIR)
+}
+
+/**
+ * A target scaffolded before the wiki moved under `.claude/` keeps its pages at
+ * the root. The verb reports that folder rather than moving it, because a move
+ * is a migration and the `migration-*` skills own those.
+ */
+export function legacyWikiDir(target: string): string {
+  return join(target, LEGACY_WIKI_DIR)
+}
+
+/**
+ * Stands in for the `cd "$target"` in the bash `guard_root`, which validated
+ * the target existed as a side effect. Without it a typo'd path scaffolds a
+ * whole new tree, since the apply step creates parents.
+ */
+export function isWikiTarget(target: string): boolean {
+  try {
+    return statSync(target).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Reports what a scaffold would create without writing. The directory and the
+ * index are tracked separately because a target can carry one without the
+ * other, and only the index has content worth preserving.
+ */
+export function planWikiInit(target: string): WikiPlan {
+  const dir = wikiDir(target)
+  const index = join(dir, INDEX_FILE)
+  const changes: WikiChange[] = []
+
+  if (!existsSync(dir)) changes.push('dir')
+
+  const hasIndex = existsSync(index)
+  if (!hasIndex) changes.push('index')
+
+  return { changes, hasIndex, hasLegacyWiki: existsSync(legacyWikiDir(target)) }
+}
+
+export async function applyWikiInit(
+  target: string,
+  plan: WikiPlan,
+): Promise<void> {
+  const dir = wikiDir(target)
+  await mkdir(dir, { recursive: true })
+
+  if (plan.changes.includes('index')) {
+    await writeFile(join(dir, INDEX_FILE), INDEX_SEED)
+  }
+}