@erclx/canon 4.0.0

package/src/commands/upgrade.ts

@@ -0,0 +1,231 @@
+import type { Command } from 'commander'
+import { execa } from 'execa'
+import { PROJECT_ROOT } from '@/project-root'
+import {
+  frameError,
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  select,
+} from '@/ui'
+import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
+import { detectManager, installCommand, type Manager } from '@/version/manager'
+import {
+  describeSkew,
+  latestOf,
+  readSkew,
+  type SkewReport,
+} from '@/version/skew'
+
+interface UpgradeOptions {
+  readonly json?: boolean
+}
+
+interface UpgradeRecord {
+  readonly root: string
+  readonly manager?: string
+  readonly command?: string
+  readonly before: string
+  readonly after?: string
+  readonly latest?: string
+  readonly state: 'upgraded' | 'current' | 'cancelled' | 'refused'
+  readonly reason?: string
+}
+
+export function register(program: Command): void {
+  program
+    .command('upgrade')
+    .description(
+      'Reinstall the CLI globally with whichever package manager installed it',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the binary is current, the reinstall completed, or it was cancelled',
+        '  1  refused or the reinstall failed, with the reason on stderr',
+        '',
+        'The package manager is read off the install path rather than guessed',
+        'from PATH, and named before anything runs. A source checkout matches no',
+        'install tree and is refused rather than reinstalled over.',
+        '',
+        'Examples:',
+        '  canon upgrade',
+        '  canon upgrade --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: UpgradeOptions) => {
+      process.exitCode = await runUpgrade(opts)
+    })
+}
+
+/**
+ * Detection runs before the registry lookup so the one case that cannot upgrade
+ * at all, a source checkout, refuses without waiting on a network call whose
+ * answer it would then discard.
+ */
+async function runUpgrade(opts: UpgradeOptions): Promise<number> {
+  const installed = readInstalled()
+  const before = installed.version ?? UNKNOWN_LABEL
+
+  intro('canon upgrade')
+  logStep('Installed')
+  logInfo(`${installed.name ?? UNKNOWN_LABEL} ${before}`)
+  logInfo(PROJECT_ROOT)
+
+  const manager = detectManager(PROJECT_ROOT)
+  if (manager === undefined) {
+    return refuse(
+      opts,
+      before,
+      `No package manager owns ${PROJECT_ROOT}. A source checkout is upgraded by pulling, not by reinstalling over it.`,
+    )
+  }
+
+  // A manifest that did not parse, or carried no `name`, would otherwise reach
+  // `installCommand` and produce a global install of whatever sits under that
+  // placeholder on the registry. The prompt below defaults to yes headlessly,
+  // so nothing downstream would stop it.
+  if (installed.name === undefined) {
+    return refuse(
+      opts,
+      before,
+      `No package name in ${PROJECT_ROOT}/package.json, so there is nothing safe to reinstall. Repair the manifest, or reinstall by name yourself.`,
+      manager,
+    )
+  }
+
+  const command = installCommand(manager.id, installed.name)
+  logStep('Detected')
+  logInfo(`${manager.id}, from the \`${manager.evidence}\` path segment`)
+  logInfo(command.join(' '))
+
+  const skew = await readSkew({ installed })
+  logStep('Published')
+  logInfo(describeSkew(skew))
+
+  if (skew.state === 'current') {
+    outro()
+    emit(opts, {
+      ...base(before, manager, command, skew),
+      after: before,
+      state: 'current',
+    })
+    return 0
+  }
+
+  return await applyUpgrade(opts, before, skew, manager, command)
+}
+
+/**
+ * Runs the reinstall and reads the version back off disk rather than trusting
+ * the manager's own report, since each spells success differently and one of
+ * them exits zero on a no-op. The read is the same `package.json` the CLI names
+ * on `--version`, which the install has overwritten by this point.
+ *
+ * An `unknown` skew reaches here rather than stopping. The operator asked for
+ * the reinstall, and the manager reports its own network failure in terms the
+ * dist-tag endpoint cannot.
+ */
+async function applyUpgrade(
+  opts: UpgradeOptions,
+  before: string,
+  skew: SkewReport,
+  manager: Manager,
+  command: readonly string[],
+): Promise<number> {
+  const proceed = await select({
+    message: `Run \`${command.join(' ')}\`?`,
+    options: [
+      { value: true, label: 'Upgrade' },
+      { value: false, label: 'Cancel' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!proceed) {
+    logWarn('Cancelled')
+    outro()
+    emit(opts, { ...base(before, manager, command, skew), state: 'cancelled' })
+    return 0
+  }
+
+  logStep('Upgrading')
+  const [bin, ...args] = command
+  // The manager's own progress goes to stderr with the rest of the UI, leaving
+  // stdout carrying nothing but the record. Inheriting all three streams would
+  // put npm's output ahead of the JSON and break every wrapper parsing it.
+  const result = await execa(bin, args, {
+    reject: false,
+    stdin: 'inherit',
+    stdout: process.stderr,
+    stderr: 'inherit',
+  })
+
+  if (result.exitCode !== 0) {
+    return refuse(
+      opts,
+      before,
+      `\`${command.join(' ')}\` exited ${result.exitCode}. Run it yourself to read what it reported.`,
+      manager,
+    )
+  }
+
+  const after = readInstalled().version ?? UNKNOWN_LABEL
+  logStep('Installed')
+  logInfo(after === before ? `${after}, unchanged` : `${before} to ${after}`)
+  outro()
+
+  emit(opts, {
+    ...base(before, manager, command, skew),
+    after,
+    state: 'upgraded',
+  })
+  return 0
+}
+
+function base(
+  before: string,
+  manager: Manager,
+  command: readonly string[],
+  skew: SkewReport,
+): Omit<UpgradeRecord, 'state'> {
+  const latest = latestOf(skew)
+
+  return {
+    root: PROJECT_ROOT,
+    manager: manager.id,
+    command: command.join(' '),
+    before,
+    ...(latest === undefined ? {} : { latest }),
+  }
+}
+
+function refuse(
+  opts: UpgradeOptions,
+  before: string,
+  reason: string,
+  manager?: Manager,
+): number {
+  outro()
+  frameError(reason)
+  emit(opts, {
+    root: PROJECT_ROOT,
+    ...(manager === undefined ? {} : { manager: manager.id }),
+    before,
+    state: 'refused',
+    reason,
+  })
+  return 1
+}
+
+function emit(opts: UpgradeOptions, record: UpgradeRecord): void {
+  if (opts.json !== true) return
+  process.stdout.write(`${JSON.stringify(record)}\n`)
+}

package/src/commands/wiki.ts

@@ -0,0 +1,100 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { PROJECT_ROOT } from '@/project-root'
+import {
+  intro,
+  logAdd,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  palette,
+  select,
+} from '@/ui'
+import {
+  applyWikiInit,
+  isWikiTarget,
+  LEGACY_WIKI_DIR_REL,
+  planWikiInit,
+  WIKI_DIR_REL,
+  WIKI_INDEX_REL,
+} from '@/wiki/init'
+
+export function register(program: Command): void {
+  const wiki = program
+    .command('wiki')
+    .description('Wiki commands (init)')
+    .helpOption('-h, --help', 'Show this help message')
+
+  wiki
+    .command('init')
+    .description('Scaffold .claude/wiki/ with a stub index.md')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .action(async (target: string) => {
+      process.exitCode = await runInit(target)
+    })
+}
+
+async function runInit(target: string): Promise<number> {
+  intro('canon wiki')
+
+  const resolved = resolve(target)
+
+  if (!isWikiTarget(resolved)) {
+    logError(`Target directory not found: ${target}`)
+    outro()
+    return 1
+  }
+
+  if (resolved === PROJECT_ROOT) {
+    logError(
+      'Cannot run against toolkit root. Files here are the source of truth.',
+    )
+    outro()
+    return 1
+  }
+
+  const plan = planWikiInit(resolved)
+  const { GREEN, NC } = palette(process.stderr)
+
+  logStep(`Scanning ${WIKI_DIR_REL}`)
+  if (plan.changes.includes('dir')) logAdd(WIKI_DIR_REL)
+  if (plan.hasIndex) logInfo(WIKI_INDEX_REL)
+  else logAdd(WIKI_INDEX_REL)
+
+  if (plan.hasLegacyWiki) {
+    logWarn(`${LEGACY_WIKI_DIR_REL} found at the target root, not migrated`)
+  }
+
+  const count = plan.changes.length
+  if (count === 0) {
+    outro()
+    process.stderr.write(`${GREEN}✓ Wiki already initialized${NC}\n`)
+    return 0
+  }
+
+  const shouldApply = await select({
+    message: `Apply ${count} change(s)?`,
+    options: [
+      { value: true, label: 'Apply all' },
+      { value: false, label: 'Cancel' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!shouldApply) {
+    logWarn('Cancelled')
+    outro()
+    return 0
+  }
+
+  logStep('Applying changes')
+  await applyWikiInit(resolved, plan)
+  if (plan.changes.includes('index')) logAdd(WIKI_INDEX_REL)
+
+  outro()
+  process.stderr.write(`${GREEN}✓ Wiki ready${NC}\n`)
+  return 0
+}

package/src/commands/worktrees.ts

@@ -0,0 +1,191 @@
+import type { Command } from 'commander'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/ui'
+import {
+  type Refusal,
+  reclaimReport,
+  type Unreadable,
+  type WorktreeVerdict,
+} from '@/worktrees/reclaim'
+
+interface ListCommandOptions {
+  readonly json?: boolean
+}
+
+const REFUSALS: Record<Refusal, string> = {
+  'main-worktree': 'the main worktree, which is never reclaimable',
+  'detached-head': 'detached HEAD, so no branch names a pull request',
+  'no-merged-pull-request': 'no merged pull request for its branch',
+  'uncommitted-changes': 'uncommitted work no history stands behind',
+  'unreadable-worktree': 'the working tree could not be read',
+  'held-by-session': 'a live session still holds it',
+}
+
+const UNREADABLE: Record<Unreadable, string> = {
+  'gh-missing':
+    'gh is not on the path, so the merge state could not be read. Install it and run this again.',
+  'gh-failed':
+    'The pull request read failed, so every worktree would report as unmerged whatever its real state. Authenticate gh and run this again.',
+  'sessions-unreadable':
+    'The session roster could not be read, so nothing was read about which worktrees are still held.',
+}
+
+export function register(program: Command): void {
+  const worktrees = program
+    .command('worktrees')
+    .description('Report which worktrees are reclaimable and which are not')
+    .helpOption('-h, --help', 'Show this help message')
+
+  worktrees
+    .command('list')
+    .description(
+      'Report every worktree with a reclaim verdict and the reason behind it',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every worktree was read',
+        '  1  refused, with the reason on stderr',
+        '',
+        'A worktree is reclaimable when all three hold: its branch has a merged',
+        'pull request, its working tree is clean, and no live session holds it.',
+        'Each alone has a case where removal loses something, so "refusals"',
+        'carries every failing condition rather than the first.',
+        '',
+        'The merged state comes from gh rather than from git ancestry. A',
+        'repository that squash merges never makes a merged branch an ancestor',
+        'of its trunk, so ancestry calls shipped work unmerged and calls an',
+        'abandoned branch sitting at a release commit merged.',
+        '',
+        'This reports and removes nothing. "route" names which removal shape',
+        'applies: "session" when a live session holds the directory, where',
+        '`claude rm <name>` takes the session and its worktree together, and',
+        '"worktree" when the session has ended, where `git worktree remove`',
+        'and a branch delete are the pair.',
+        '',
+        'An unreadable input refuses the whole reading rather than reporting',
+        'every worktree as not reclaimable, since an absent merge state and a',
+        'branch with no merged pull request produce the same empty answer.',
+        '',
+        'The merge read covers the most recent 200 merged pull requests. A',
+        'worktree older than that reads as having none and is refused, which',
+        'keeps a directory rather than removing one.',
+        '',
+        'Examples:',
+        '  canon worktrees list',
+        '  canon worktrees list --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ListCommandOptions) => {
+      process.exitCode = await runList(opts)
+    })
+}
+
+async function runList(opts: ListCommandOptions): Promise<number> {
+  const report = await reclaimReport({ cwd: process.cwd() })
+
+  intro('canon worktrees list')
+
+  if (report.kind === 'unreadable') {
+    logStep('Refused')
+    logWarn(UNREADABLE[report.reason])
+    logInfo(report.detail)
+    outro()
+
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({
+          reason: report.reason,
+          detail: report.detail,
+          worktrees: [],
+        })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  reportWorktrees(report.worktrees)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        reason: null,
+        detail: null,
+        worktrees: report.worktrees,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+function reportWorktrees(worktrees: readonly WorktreeVerdict[]): void {
+  logStep('Worktrees')
+
+  if (worktrees.length === 0) {
+    logInfo('No worktree resolved here. Run this inside a repository.')
+    return
+  }
+
+  logInfo(plural(worktrees.length, 'worktree'))
+  pipeOutput(worktrees.map(describe).join('\n'))
+
+  const reclaimable = worktrees.filter((entry) => entry.reclaimable)
+
+  logStep('Reclaimable')
+  if (reclaimable.length === 0) {
+    logInfo('None. Every worktree fails at least one condition.')
+    return
+  }
+
+  logWarn(
+    `${plural(reclaimable.length, 'worktree')} can be reclaimed. This reports and removes nothing, so run the named command yourself.`,
+  )
+}
+
+/**
+ * Names the evidence beside the conclusion on every row.
+ *
+ * The reading has two consumers and they act on different halves. The sweep
+ * reads the verdict to decide what to offer, and a person reads it to decide
+ * what to remove, so a row phrased for the first alone leaves the second
+ * removing a directory on a conclusion it cannot check.
+ */
+function describe(verdict: WorktreeVerdict): string {
+  const held = verdict.branch ?? 'detached'
+  const head = `${verdict.path}  ${held}`
+
+  if (!verdict.reclaimable) {
+    const reasons = verdict.refusals.map((refusal) => REFUSALS[refusal])
+    // A name is quoted because a session carries whatever string it was
+    // launched under, spaces included, and one command per name because a
+    // joined list reads as a single argument.
+    const routes =
+      verdict.route === 'session'
+        ? verdict.sessions.map(
+            (name) => `\n  Removal there goes through: claude rm '${name}'`,
+          )
+        : []
+    return `${head}\n  Refused: ${reasons.join('; ')}.${routes.join('')}`
+  }
+
+  return [
+    head,
+    `  Reclaimable. Pull request #${verdict.pullRequest} merged it, the tree is clean, and no session holds it.`,
+    `  Remove with: git worktree remove ${verdict.path} && git branch -D ${held}`,
+  ].join('\n')
+}