@erclx/aitk 0.109.0 → 0.111.0

package/src/cli.ts

@@ -1,7 +1,5 @@
 #!/usr/bin/env bun
 
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
 import { Command } from 'commander'
 import { register as init } from '@/commands/init'
 import { register as sandbox } from '@/commands/sandbox'
@@ -27,7 +25,9 @@ import { register as context } from '@/commands/context'
 import { register as markdown } from '@/commands/markdown'
 import { register as records } from '@/commands/records'
 import { register as sessions } from '@/commands/sessions'
-import { PROJECT_ROOT } from '@/project-root'
+import { register as audits } from '@/commands/audits'
+import { register as upgrade } from '@/commands/upgrade'
+import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 
 const GREY = '\x1b[0;90m'
 const WHITE = '\x1b[1;37m'
@@ -63,6 +63,8 @@ function showHelp(): void {
     `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
     `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, push, pull)${NC}`,
     `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
+    `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
+    `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
     `${GREY}│${NC}`,
     `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
     `${GREY}│${NC}    aitk sandbox             ${GREY}# Interactive scenario picker${NC}`,
@@ -101,31 +103,17 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk records validate plans`,
     `${GREY}│${NC}    aitk records push --json`,
     `${GREY}│${NC}    aitk sessions list --json`,
+    `${GREY}│${NC}    aitk audits run --json`,
+    `${GREY}│${NC}    aitk upgrade --json`,
     `${GREY}└${NC}`,
   ]
   console.log(lines.join('\n'))
 }
 
-/**
- * Read at runtime rather than inlined, because a literal here 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.
- */
-function readVersion(): string {
-  try {
-    const raw = readFileSync(join(PROJECT_ROOT, 'package.json'), 'utf8')
-    return (JSON.parse(raw) as { version?: string }).version ?? 'unknown'
-  } catch {
-    return 'unknown'
-  }
-}
-
 const program = new Command()
 program
   .name('aitk')
-  .version(readVersion())
+  .version(readInstalled().version ?? UNKNOWN_LABEL)
   .enablePositionalOptions()
   .helpOption(false)
 program.action(() => showHelp())
@@ -159,5 +147,7 @@ context(program)
 markdown(program)
 records(program)
 sessions(program)
+audits(program)
+upgrade(program)
 
 program.parse()

package/src/commands/audits.ts

@@ -0,0 +1,342 @@
+import { execa } from 'execa'
+import type { Command } from 'commander'
+import {
+  BASELINE_REL,
+  type Baseline,
+  baselineFrom,
+  compareBaseline,
+  type Delta,
+  readBaseline,
+  writeBaseline,
+} from '@/audits/baseline'
+import { AUDITS, type AuditResult } from '@/audits/catalog'
+import {
+  exitCodeFor,
+  runAudits,
+  spawnAudit,
+  type Summary,
+  summarize,
+} from '@/audits/run'
+import { gitEnv } from '@/git-env'
+import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+import { currentWorktreeRoot } from '@/worktree'
+
+interface RunCommandOptions {
+  readonly json?: boolean
+  readonly record?: boolean
+  readonly root?: string
+}
+
+interface ListCommandOptions {
+  readonly json?: boolean
+}
+
+export function register(program: Command): void {
+  const audits = program
+    .command('audits')
+    .description('Run every health check this repository owns as one set')
+    .helpOption('-h, --help', 'Show this help message')
+
+  audits
+    .command('run')
+    .description(
+      'Run every audit, report per check under one verdict, and compare each count to the recorded baseline',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--root <path>',
+      'Tree to measure, defaulting to the current worktree',
+    )
+    .option(
+      '--record',
+      `Write this run's tracked counts to ${BASELINE_REL} as the new baseline`,
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every audit reported and none carried a finding that is a fact',
+        '  1  refused, with the reason on stderr',
+        '  2  an audit carries a finding that is a fact',
+        '  3  an audit did not report, so the run measured less than the set',
+        '',
+        'It gates on exactly what already gates a push and on nothing new:',
+        'an unresolved context citation, a banned character, word, or spelling,',
+        'and a skill folder carrying no REQUIREMENT.md. Every other measure is a',
+        'judgment a reader settles, and failing a push on one teaches',
+        'contributors to route around the stage.',
+        '',
+        'Exit 3 is a defect in the run rather than in the tree. An aggregate that',
+        'reports a pass over a set it did not finish measuring is the failure this',
+        'command exists against, so a verb that did not report takes its own code.',
+        '',
+        `The baseline at ${BASELINE_REL} holds the counts from the last recorded`,
+        'run, so a measure that reports rather than gates still costs something',
+        'when it grows. Only a tracked corpus is retained: a gitignored record',
+        "folder holds one machine's scratch, and its counts answer nobody else.",
+        '',
+        'Examples:',
+        '  aitk audits run',
+        '  aitk audits run --json',
+        '  aitk audits run --record',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RunCommandOptions) => {
+      process.exitCode = await runAll(opts)
+    })
+
+  audits
+    .command('list')
+    .description(
+      'List every audit this command runs and what each one gates on',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit JSON with the id, invocation, corpus, and gate')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the catalog was listed',
+        '',
+        'Examples:',
+        '  aitk audits list',
+        '  aitk audits list --json',
+        '',
+      ].join('\n'),
+    )
+    .action((opts: ListCommandOptions) => {
+      process.exitCode = runList(opts)
+    })
+}
+
+function runList(opts: ListCommandOptions): number {
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        audits: AUDITS.map((audit) => ({
+          id: audit.id,
+          label: audit.label,
+          command: `aitk ${audit.argv.join(' ')}`,
+          corpus: audit.corpus,
+          gates: audit.gatingExits.length > 0,
+        })),
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk audits list')
+  for (const audit of AUDITS) {
+    logStep(audit.label)
+    logInfo(`aitk ${audit.argv.join(' ')}`)
+    logInfo(
+      `${audit.corpus} corpus, ${audit.gatingExits.length > 0 ? 'gates on a fact' : 'reports only'}`,
+    )
+  }
+  outro()
+  return 0
+}
+
+/**
+ * The day a record is stamped with, as `YYYY-MM-DD`.
+ *
+ * Local rather than UTC, because the stamp is read beside a commit date in a
+ * context entry and a run taken in the evening should not record tomorrow.
+ */
+function today(): string {
+  const now = new Date()
+  return [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, '0'),
+    String(now.getDate()).padStart(2, '0'),
+  ].join('-')
+}
+
+/**
+ * The commit the counts were read at, or `unknown` outside a repository.
+ *
+ * A target project can install this CLI without a git history behind it, and
+ * refusing there would withhold the whole report over a field that only makes
+ * the record reproducible.
+ */
+async function headCommit(root: string): Promise<string> {
+  const result = await execa('git', ['-C', root, 'rev-parse', 'HEAD'], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+  return result.exitCode === 0 ? result.stdout.trim() : 'unknown'
+}
+
+async function runAll(opts: RunCommandOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = opts.root ?? (await currentWorktreeRoot())
+
+  let baseline: Baseline | undefined
+  try {
+    baseline = await readBaseline(root)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (emitJson) {
+      process.stderr.write(`${message}\n`)
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: 'bad-baseline', message })}\n`,
+      )
+      return 1
+    }
+    intro('aitk audits run')
+    logStep('Refused')
+    logError(message)
+    outro()
+    return 1
+  }
+
+  const results = await runAudits(AUDITS, spawnAudit(root))
+  const deltas = compareBaseline(baseline, results)
+  const summary = summarize(results, deltas)
+
+  let recorded: string | undefined
+  if (opts.record) {
+    const next = baselineFrom(results, {
+      recordedAt: today(),
+      commit: await headCommit(root),
+    })
+    recorded = await writeBaseline(root, next)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        // Flat scalars, so a shell stage greps one out without a JSON parser.
+        // The nested arrays below carry the detail behind each number.
+        summary,
+        baseline: baseline
+          ? { recordedAt: baseline.recordedAt, commit: baseline.commit }
+          : undefined,
+        recorded,
+        audits: results,
+        deltas,
+      })}\n`,
+    )
+  } else {
+    report(results, deltas, baseline, recorded, summary)
+  }
+
+  return exitCodeFor(results)
+}
+
+/** The counts of one result, rendered as `key n` pairs a reader can scan. */
+function countLine(counts: Record<string, number>): string {
+  return Object.entries(counts)
+    .map(([key, value]) => `${key} ${value}`)
+    .join(', ')
+}
+
+/**
+ * The delta line for one audit, or nothing when there is no comparison to
+ * report. A first run says so rather than showing a delta of zero, since zero
+ * against an absent baseline says the same as a corpus that did not move.
+ */
+function deltaLine(delta: Delta): string | undefined {
+  if (delta.kind === 'per-machine' || delta.kind === 'unmeasured') {
+    return undefined
+  }
+  if (delta.kind === 'unrecorded') return 'No recorded baseline to compare'
+
+  const parts = [
+    ...delta.moved.map(
+      ({ key, from, to, delta: moved }) =>
+        `${key} ${from} to ${to} (${moved > 0 ? '+' : ''}${moved})`,
+    ),
+    ...delta.added.map(({ key, to }) => `${key} ${to}, newly measured`),
+    ...delta.dropped.map(({ key, from }) => `${key} was ${from}, not measured`),
+  ]
+
+  return parts.length === 0 ? undefined : parts.join(', ')
+}
+
+function report(
+  results: readonly AuditResult[],
+  deltas: readonly Delta[],
+  baseline: Baseline | undefined,
+  recorded: string | undefined,
+  summary: Summary,
+): void {
+  const byId = new Map(deltas.map((delta) => [delta.id, delta]))
+
+  intro('aitk audits run')
+
+  logStep('Baseline')
+  if (baseline === undefined) {
+    logWarn(`None recorded. Take one with aitk audits run --record.`)
+  } else {
+    logInfo(`${baseline.recordedAt} at ${baseline.commit.slice(0, 8)}`)
+  }
+
+  for (const result of results) {
+    logStep(result.label)
+
+    if (result.status === 'absent') {
+      logInfo(`No corpus on this machine: ${result.reason ?? 'not found'}`)
+      continue
+    }
+
+    if (result.status === 'unmeasured') {
+      logWarn(`Did not report: ${result.reason ?? 'no reason given'}`)
+      continue
+    }
+
+    const counts = result.counts ?? {}
+    const line = countLine(counts)
+    if (result.status === 'finding') {
+      logError(line === '' ? 'A finding that is a fact' : line)
+    } else {
+      logInfo(line === '' ? 'Reported' : line)
+    }
+
+    if (!result.tracked) {
+      logInfo('Per-machine corpus, so no baseline is kept')
+      continue
+    }
+
+    const moved = deltaLine(
+      byId.get(result.id) ?? { id: result.id, kind: 'unrecorded' },
+    )
+    if (moved !== undefined) logInfo(moved)
+  }
+
+  if (recorded !== undefined) {
+    logStep('Recorded')
+    logInfo(recorded)
+  }
+
+  logStep('Verdict')
+
+  if (summary.verdict === 'findings') {
+    logError(
+      `${plural(summary.facts, 'audit')} carrying a finding that is a fact. Fix what each names.`,
+    )
+  } else if (summary.verdict === 'incomplete') {
+    logError(
+      `${plural(summary.unmeasured, 'audit')} did not report, so this run measured less than the set.`,
+    )
+  } else if (summary.verdict === 'reported') {
+    logInfo('No fact. Every other finding is a judgment a reader settles.')
+  } else {
+    logInfo('Every audit reported and every count is zero.')
+  }
+
+  // Stated on every run, including a clean one. A count of what passed reads as
+  // a verdict on the whole set unless the run also says what it never reached.
+  logInfo(
+    `${summary.audited} of ${results.length} corpora measured, ${summary.absent} absent on this machine`,
+  )
+
+  outro()
+}

package/src/commands/claude.ts

@@ -48,6 +48,7 @@ import {
   plural,
   select,
 } from '@/ui'
+import { describeSkew, readSkew, type SkewReport } from '@/version/skew'
 
 const GREEN = '\x1b[0;32m'
 const GREY = '\x1b[0;90m'
@@ -249,14 +250,18 @@ export function register(program: Command): void {
         'copy. Passing a ref older than the oldest load over-reports, which is',
         'the safe direction. Confirm a name by reading the body.',
         '',
+        'Every run also reports the installed version against the newest',
+        'published one. That report never changes the exit code, so an offline',
+        'machine reads it as unknown rather than as a failure.',
+        '',
         'Examples:',
         '  aitk claude skills drift HEAD~20',
         '  aitk claude skills drift 02d7b265 --json',
         '',
       ].join('\n'),
     )
-    .action((ref: string, opts: SkillsDriftOptions) => {
-      process.exitCode = runSkillsDrift(ref, opts)
+    .action(async (ref: string, opts: SkillsDriftOptions) => {
+      process.exitCode = await runSkillsDrift(ref, opts)
     })
 }
 
@@ -506,16 +511,28 @@ function runSkillsList(opts: SkillsListOptions): number {
  * it answers every run with nothing moved, which is the silence this reports
  * against.
  */
-function runSkillsDrift(ref: string, opts: SkillsDriftOptions): number {
+async function runSkillsDrift(
+  ref: string,
+  opts: SkillsDriftOptions,
+): Promise<number> {
   const root = process.cwd()
   const report = readDrift(root, ref)
+  const skew = await readSkew()
 
   if (report.kind === 'measured') {
     intro('aitk claude skills drift')
+    reportSkew(skew)
     reportDrift(report, ref)
     outro()
   } else {
     frameError(report.reason)
+    // The refusal path names the binary too. A project consuming the plugin
+    // from a marketplace cache is refused here for having no history, and that
+    // is the moment a skew warning is worth most, since an old binary is one
+    // reason the cache and the CLI disagree in the first place.
+    if (skew.state === 'behind') {
+      process.stderr.write(`${GREY}${describeSkew(skew)}${NC}\n`)
+    }
   }
 
   if (opts.json) {
@@ -528,8 +545,9 @@ function runSkillsDrift(ref: string, opts: SkillsDriftOptions): number {
               base: report.base,
               head: report.head,
               moved: report.moved,
+              skew,
             }
-          : { root, ref, unreadable: report.reason },
+          : { root, ref, unreadable: report.reason, skew },
       )}\n`,
     )
   }
@@ -537,6 +555,18 @@ function runSkillsDrift(ref: string, opts: SkillsDriftOptions): number {
   return report.kind === 'measured' ? 0 : 1
 }
 
+/**
+ * The binary reports before the range does, for the reason the range section
+ * states about itself: the command answers what changed on disk, and a binary
+ * behind the published one is a second way the tree a session reads differs
+ * from the tree it holds.
+ */
+function reportSkew(skew: SkewReport): void {
+  logStep('Toolkit version')
+  if (skew.state === 'behind') logWarn(describeSkew(skew))
+  else logInfo(describeSkew(skew))
+}
+
 /**
  * States the bound on every run, including the run that names nothing. A report
  * listing only what moved reads as a verdict on what a session holds, and the

package/src/commands/sync.ts

@@ -30,6 +30,7 @@ import {
   logWarn,
   outro,
 } from '@/ui'
+import { describeSkew } from '@/version/skew'
 
 const GREY = '\x1b[0;90m'
 const YELLOW = '\x1b[0;33m'
@@ -100,6 +101,8 @@ async function runCheck(target: string, options: SyncOptions): Promise<number> {
 function renderCheck(report: CheckReport): void {
   intro('aitk sync --check')
 
+  renderSkew(report)
+
   if (!report.managed) {
     logStep('Not a toolkit project')
     logWarn('No .claude/ directory and no CLAUDE.md at the target.')
@@ -182,6 +185,24 @@ function renderCheck(report: CheckReport): void {
   )
 }
 
+/**
+ * The binary reports before any domain does, since a stale binary is what makes
+ * every section below it a reading from the wrong toolkit. It prints on all
+ * three states rather than only when behind: a check that goes quiet when the
+ * registry is unreachable is indistinguishable from one that found nothing.
+ */
+function renderSkew(report: CheckReport): void {
+  const { skew } = report
+  logStep('toolkit version')
+
+  if (skew.state === 'behind') {
+    logWarn(describeSkew(skew))
+    return
+  }
+
+  logInfo(describeSkew(skew))
+}
+
 /**
  * Tooling prints whether it was measured before it prints any count, because a
  * target with no chain recorded produces the same zero a current target does.