@erclx/aitk 3.56.0 → 3.57.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.56.0",
+  "version": "3.57.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/commands.md

@@ -41,6 +41,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk records size`        | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                                                          |
 | `aitk records push`        | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                                            |
 | `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                               |
+| `aitk migrate rename`      | Rewrite every unprotected `aitk` token to `canon` and move the paths that carry the name, reporting the plan without `--write` (`--scope`, `--json`)                  |
 | `aitk sessions list`       | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                                        |
 | `aitk worktrees list`      | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                            |
 | `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.56.0",
+  "version": "3.57.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/cli.ts

@@ -26,6 +26,7 @@ import { register as teach } from '@/commands/teach'
 import { register as comments } from '@/commands/comments'
 import { register as context } from '@/commands/context'
 import { register as markdown } from '@/commands/markdown'
+import { register as migrate } from '@/commands/migrate'
 import { register as records } from '@/commands/records'
 import { register as sessions } from '@/commands/sessions'
 import { register as worktrees } from '@/commands/worktrees'
@@ -182,6 +183,7 @@ comments(program)
 context(program)
 markdown(program)
 records(program)
+migrate(program)
 sessions(program)
 targets(program)
 worktrees(program)

package/src/commands/migrate.ts

@@ -0,0 +1,175 @@
+import type { Command } from 'commander'
+import { listRepositoryFiles } from '@/git-files'
+import { applyRename, readSources } from '@/migrate/apply'
+import { isToolkitOwned, planRename, type RenamePlan } from '@/migrate/plan'
+import { logError, logInfo, logStep, logWarn, pipeOutput, plural } from '@/ui'
+
+interface RenameOptions {
+  readonly json?: boolean
+  readonly write?: boolean
+  readonly root?: string
+  readonly scope?: string
+}
+
+const SCOPES = ['self', 'target'] as const
+
+type Scope = (typeof SCOPES)[number]
+
+function isScope(value: string): value is Scope {
+  return (SCOPES as readonly string[]).includes(value)
+}
+
+/**
+ * Reports rather than writes without `--write`, matching `aitk records
+ * migrate`. A rename touching this many files has no undo short of the branch
+ * it ran on, so the safe outcome sits on the default path.
+ */
+async function runRename(opts: RenameOptions): Promise<number> {
+  const root = opts.root ?? process.cwd()
+  const scope = opts.scope ?? 'self'
+
+  if (!isScope(scope)) {
+    logError(`Unknown scope ${scope}. Use one of ${SCOPES.join(', ')}.`)
+    return 1
+  }
+
+  const files = await listRepositoryFiles(root)
+  if (files === undefined) {
+    logError(`Could not list files under ${root}. Is it a git repository?`)
+    return 1
+  }
+
+  const scoped = scope === 'target' ? files.filter(isToolkitOwned) : files
+  const sources = await readSources(root, scoped)
+  const plan = planRename(sources)
+
+  // A target scope reports the citations it did not rewrite, since prose the
+  // project wrote is theirs to change and a sweep editing it underneath them
+  // is the failure this scope exists to avoid.
+  const citations =
+    scope === 'target'
+      ? planRename(
+          await readSources(
+            root,
+            files.filter((f) => !isToolkitOwned(f)),
+          ),
+        ).entries.length
+      : 0
+
+  if (opts.json) {
+    pipeOutput(
+      JSON.stringify(toRecord(plan, scope, citations, opts.write), null, 2),
+    )
+  }
+
+  report(plan, scope, citations)
+
+  if (plan.entries.length === 0) return 0
+  if (!opts.write) {
+    logWarn('Nothing was written. Pass --write to apply this plan.')
+    return 2
+  }
+
+  const applied = await applyRename(root, plan)
+  logStep(
+    `Rewrote ${plural(applied.written, 'file')} and moved ${plural(applied.moved, 'path')}.`,
+  )
+
+  if (applied.failed.length > 0) {
+    logError(`Could not move ${plural(applied.failed.length, 'path')}.`)
+    for (const path of applied.failed) logError(`  ${path}`)
+    return 1
+  }
+
+  return 0
+}
+
+function report(plan: RenamePlan, scope: Scope, citations: number): void {
+  logInfo(`Scope ${scope}.`)
+  logInfo(
+    `${plural(plan.entries.length, 'file')} to change, ${plural(plan.renamed, 'occurrence')} to rewrite.`,
+  )
+  logInfo(`${plural(plan.moves, 'path')} to move.`)
+  logInfo(
+    `${plural(plan.protectedCount, 'occurrence')} protected and left alone.`,
+  )
+
+  if (plan.excluded.length > 0) {
+    logInfo(`Excluded: ${plan.excluded.join(', ')}.`)
+  }
+
+  if (citations > 0) {
+    logWarn(
+      `${plural(citations, 'file')} outside toolkit-owned folders still cite the old name. They are yours to change.`,
+    )
+  }
+}
+
+function toRecord(
+  plan: RenamePlan,
+  scope: Scope,
+  citations: number,
+  wrote: boolean | undefined,
+): unknown {
+  return {
+    scope,
+    wrote: wrote === true,
+    files: plan.entries.length,
+    renamed: plan.renamed,
+    moves: plan.moves,
+    protected: plan.protectedCount,
+    excluded: plan.excluded,
+    citations,
+    paths: plan.entries.map((entry) => ({
+      path: entry.path,
+      ...(entry.movesTo === undefined ? {} : { movesTo: entry.movesTo }),
+      renamed: entry.renamed,
+    })),
+  }
+}
+
+export function register(program: Command): void {
+  const migrate = program
+    .command('migrate')
+    .description('Move a project off the retired aitk name')
+    .helpOption('-h, --help', 'Show this help message')
+
+  migrate
+    .command('rename')
+    .description('Rewrite every unprotected aitk token to canon')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--write', 'Apply the plan rather than reporting it')
+    .option(
+      '--root <path>',
+      'Project root, defaulting to the working directory',
+    )
+    .option('--scope <scope>', `What to rewrite: ${SCOPES.join(', ')}`, 'self')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scopes:',
+        '  self    every tracked file, for the toolkit repository itself',
+        '  target  toolkit-owned folders only, reporting the rest as citations',
+        '',
+        'Exit codes:',
+        '  0  nothing to rewrite, or --write applied the whole plan',
+        '  1  refused, or a move failed',
+        '  2  a plan exists and --write was not passed',
+        '',
+        'The changelog is never rewritten. Its entries record what shipped',
+        'under the old name, and GitHub redirects the links they carry.',
+        'aitk-sandbox is a separate repository and is left alone.',
+        '',
+        'Examples:',
+        '  aitk migrate rename',
+        '  aitk migrate rename --write',
+        '  aitk migrate rename --scope target --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RenameOptions) => {
+      process.exitCode = await runRename(opts)
+    })
+}

package/src/migrate/apply.ts

@@ -0,0 +1,115 @@
+import { $ } from 'bun'
+import { readFile, mkdir, rmdir, writeFile } from 'node:fs/promises'
+import { dirname, join, relative } from 'node:path'
+import { gitEnv } from '@/git-env'
+import type { RenamePlan, RenameSource } from '@/migrate/plan'
+
+/**
+ * A file whose bytes carry a NUL is read as binary and its content is left
+ * alone, which lets the path still move. Reporting the empty string rather
+ * than a flag keeps the planner pure: an unchanged content rewrite is already
+ * how it expresses "path only", so binary needs no branch of its own there.
+ */
+export async function readSources(
+  root: string,
+  paths: readonly string[],
+): Promise<RenameSource[]> {
+  const sources: RenameSource[] = []
+
+  for (const path of paths) {
+    const bytes = await readFile(join(root, path)).catch(() => undefined)
+    if (bytes === undefined) continue
+
+    const binary = bytes.includes(0)
+    sources.push({ path, text: binary ? '' : bytes.toString('utf8') })
+  }
+
+  return sources
+}
+
+export interface ApplyResult {
+  readonly written: number
+  readonly moved: number
+  readonly failed: readonly string[]
+}
+
+/**
+ * Writes the plan. Content lands first and the move follows, so a failed move
+ * leaves the rewrite on a path that still exists rather than stranding content
+ * at a destination nothing points at yet.
+ *
+ * `git mv` rather than a filesystem rename, so the history follows the file and
+ * a reviewer reading the pull request sees a rename instead of a delete beside
+ * an add.
+ */
+export async function applyRename(
+  root: string,
+  plan: RenamePlan,
+): Promise<ApplyResult> {
+  let written = 0
+  let moved = 0
+  const failed: string[] = []
+
+  for (const entry of plan.entries) {
+    if (entry.text !== undefined) {
+      await writeFile(join(root, entry.path), entry.text)
+      written += 1
+    }
+
+    if (entry.movesTo === undefined) continue
+
+    await mkdir(dirname(join(root, entry.movesTo)), { recursive: true })
+    const result = await $`git -C ${root} mv ${entry.path} ${entry.movesTo}`
+      .env(gitEnv())
+      .quiet()
+      .nothrow()
+
+    if (result.exitCode === 0) moved += 1
+    else failed.push(entry.path)
+  }
+
+  await pruneEmptyParents(
+    root,
+    plan.entries
+      .filter((entry) => entry.movesTo !== undefined)
+      .map((entry) => dirname(entry.path)),
+  )
+
+  return { written, moved, failed }
+}
+
+/**
+ * Removes the directories a move emptied.
+ *
+ * Git tracks files rather than directories, so moving the last file out of one
+ * leaves the directory on disk with nothing in it and nothing in the diff to
+ * say so. A renamed skill folder that keeps its old shell beside the new one
+ * reads to a person, and to a plugin loader walking the tree, as though the
+ * rename only half happened.
+ *
+ * `rmdir` refuses a directory that still holds anything, which is the guard:
+ * a folder with an untracked file in it stays, and the refusal is ignored
+ * rather than reported because it means the folder was not empty to begin
+ * with.
+ */
+async function pruneEmptyParents(
+  root: string,
+  directories: readonly string[],
+): Promise<void> {
+  const deepestFirst = [...new Set(directories)].sort(
+    (left, right) => right.length - left.length,
+  )
+
+  for (const directory of deepestFirst) {
+    let current = directory
+
+    while (current !== '.' && !current.startsWith('..')) {
+      const removed = await rmdir(join(root, current))
+        .then(() => true)
+        .catch(() => false)
+      if (!removed) break
+
+      current = relative(root, join(root, current, '..'))
+    }
+  }
+}

package/src/migrate/plan.ts

@@ -0,0 +1,103 @@
+import {
+  isExcludedPath,
+  renamePath,
+  renameText,
+  scanText,
+} from '@/migrate/rename'
+
+/** One tracked file, as the planner reads it. */
+export interface RenameSource {
+  readonly path: string
+  readonly text: string
+}
+
+/**
+ * One file the sweep touches. `text` is absent when only the path moves, so a
+ * caller writing the plan can tell a content rewrite from a pure move and
+ * leave a binary file's bytes alone.
+ */
+export interface RenameEntry {
+  readonly path: string
+  readonly movesTo?: string
+  readonly text?: string
+  readonly renamed: number
+  readonly protectedCount: number
+}
+
+export interface RenamePlan {
+  readonly entries: readonly RenameEntry[]
+  readonly excluded: readonly string[]
+  readonly renamed: number
+  readonly protectedCount: number
+  readonly moves: number
+}
+
+/**
+ * Folders a target receives from the toolkit and does not author.
+ *
+ * The rename may rewrite these in a consuming project, because their content
+ * came from here and a stale spelling in them is the toolkit's own defect.
+ * Everything else in a target is prose that project wrote, where a citation is
+ * reported for a person to decide rather than rewritten underneath them.
+ */
+const TOOLKIT_OWNED: readonly string[] = [
+  '.claude/aitk/',
+  '.claude/canon/',
+  '.claude/rules/',
+  '.claude/tooling/',
+]
+
+export function isToolkitOwned(path: string): boolean {
+  return TOOLKIT_OWNED.some((owned) => path.startsWith(owned))
+}
+
+/**
+ * What the sweep would do to a set of files.
+ *
+ * Pure, so the decision and the write are separable and the same plan can be
+ * reported or applied. A file whose content and path both stay put is dropped
+ * rather than carried as a no-op entry, which keeps the reported count equal
+ * to the number of files the sweep actually changes.
+ */
+export function planRename(sources: readonly RenameSource[]): RenamePlan {
+  const entries: RenameEntry[] = []
+  const excluded: string[] = []
+
+  for (const source of sources) {
+    if (isExcludedPath(source.path)) {
+      excluded.push(source.path)
+      continue
+    }
+
+    const movesTo = renamePath(source.path)
+    const rewritten = renameText(source.text)
+    const counts = scanText(source.text)
+    const moved = movesTo !== source.path
+    const changed = rewritten !== source.text
+
+    if (!moved && !changed) continue
+
+    entries.push({
+      path: source.path,
+      ...(moved ? { movesTo } : {}),
+      ...(changed ? { text: rewritten } : {}),
+      renamed: counts.renamed,
+      protectedCount: counts.protectedCount,
+    })
+  }
+
+  return {
+    entries,
+    excluded,
+    renamed: total(entries, (entry) => entry.renamed),
+    protectedCount: total(entries, (entry) => entry.protectedCount),
+    moves: entries.filter((entry) => entry.movesTo !== undefined).length,
+  }
+}
+
+function total(
+  entries: readonly RenameEntry[],
+  read: (entry: RenameEntry) => number,
+): number {
+  return entries.reduce((sum, entry) => sum + read(entry), 0)
+}

package/src/migrate/rename.ts

@@ -0,0 +1,183 @@
+/**
+ * The token rewrite behind the `aitk` to `canon` rename.
+ *
+ * The sweep is mechanical and its danger is entirely in what it must not
+ * touch, so the scanner is one pass with the protected forms tried first
+ * rather than a chain of replacements. A chain reprocesses its own output,
+ * which is how a protected form that contains the token gets rewritten by a
+ * later rule that cannot see it was already decided.
+ */
+
+/**
+ * Forms carrying the token that name something other than this tool, matched
+ * ahead of the token itself so they pass through untouched.
+ *
+ * `aitk-sandbox` is a separate repository that is not being renamed. It has to
+ * win against the bare token, and it also has to win against the owner-scoped
+ * spelling, since `erclx/aitk-sandbox` would otherwise rewrite to
+ * `erclx/canon-sandbox` and name a repository that does not exist.
+ */
+const PROTECTED = ['aitk-sandbox'] as const
+
+/**
+ * Every spelling of the token, and what each becomes. Case is carried in the
+ * map rather than derived, because the uppercase form is an environment
+ * variable prefix and the title-case form is a heading word, and a derived
+ * transform would have to guess which convention it was looking at.
+ */
+const REPLACEMENT: Readonly<Record<string, string>> = {
+  aitk: 'canon',
+  AITK: 'CANON',
+  Aitk: 'Canon',
+}
+
+/**
+ * One alternation so the engine decides each position once. Group 1 is a
+ * protected form and group 2 is a token to rewrite, and the protected branch
+ * sits first because a regex alternation is ordered.
+ */
+const SCAN = new RegExp(
+  `(${PROTECTED.join('|')})|(${Object.keys(REPLACEMENT).join('|')})`,
+  'g',
+)
+
+/**
+ * Files whose content is left alone entirely.
+ *
+ * The changelog is release history. Its entries record what shipped under the
+ * old name, so rewriting them falsifies the record, and the pull request links
+ * it carries keep resolving because GitHub redirects a renamed repository's
+ * old URLs.
+ *
+ * The sweep's own source is the other member, and it is not a preference. This
+ * module states the token map as literal keys, so rewriting it turns every key
+ * into its own replacement and leaves a rewriter that maps `canon` to `canon`
+ * and matches nothing. Its tests name both spellings on purpose for the same
+ * reason, and the command's help text documents the old name a caller is
+ * migrating off. Whatever these four files should say after the rename is
+ * written by hand, because the sweep cannot be the thing that decides it.
+ */
+/**
+ * An eval result is a transcript. It records the commands a session actually
+ * ran and the paths it actually opened, under whatever name was current when
+ * the run happened, so rewriting one makes it testify to a session that never
+ * took place. The changelog is excluded for the same reason and differs only
+ * in living at a fixed path.
+ */
+const EXCLUDED_PREFIXES: readonly string[] = [
+  'src/migrate/',
+  'scripts/eval/result-',
+]
+
+/**
+ * The four test files below exist to prove the retired spellings still
+ * resolve, so both names appear in each on purpose. Rewriting one is worse
+ * than a broken test: the retired-variable case would collapse into a copy of
+ * the current-variable case beside it and keep passing, reporting coverage for
+ * a fallback nothing exercises any more.
+ */
+const EXCLUDED_PATHS: readonly string[] = [
+  'CHANGELOG.md',
+  'src/commands/migrate.ts',
+  'src/sync/stamp.test.ts',
+  'src/targets/registry.test.ts',
+  'src/targets/sweep.test.ts',
+  'src/ui.test.ts',
+]
+
+export interface ScanCount {
+  readonly renamed: number
+  readonly protectedCount: number
+}
+
+export function isExcludedPath(path: string): boolean {
+  if (EXCLUDED_PATHS.includes(path)) return true
+  return EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix))
+}
+
+/**
+ * An indefinite article that agreed with the retired name and no longer
+ * agrees with the replacement.
+ *
+ * The old name opens on a vowel sound and the new one does not, so every
+ * `an aitk` in the corpus reads wrong the moment the token moves. This matches
+ * against the already-rewritten text rather than the source, which is what
+ * keeps it clear of the protected forms: `an aitk-sandbox` still says
+ * `aitk-sandbox` afterward, so it never matches here.
+ *
+ * The tail rejects a following letter rather than asking for a word boundary,
+ * which is what separates `an canonical` from `an CANON_STATE_DIR`. A boundary
+ * treats the underscore as part of the word and declines the environment
+ * variable, where the whole identifier is the token continuing.
+ */
+const ARTICLE = /\b([Aa])n(\s+`?)(canon|CANON|Canon)(?![A-Za-z])/g
+
+/**
+ * Marks a line that names the retired spelling on purpose.
+ *
+ * A fallback path, a retired environment variable, and a dictionary entry
+ * covering the record corpora all have to keep saying the old name, and a
+ * second run over an already-renamed tree would otherwise strip exactly the
+ * compatibility this rename shipped. The marker sits on the line itself or on
+ * the one above it, which is the same placement `canon-allow-superseded`
+ * already uses in this repository.
+ */
+const KEEP_MARKER = 'canon-keep-retired'
+
+/** Rewrites every unprotected spelling of the token. */
+export function renameText(text: string): string {
+  const lines = text.split('\n')
+  const rewritten = lines.map((line, index) =>
+    isKept(lines, index) ? line : renameLine(line),
+  )
+
+  return rewritten.join('\n')
+}
+
+function isKept(lines: readonly string[], index: number): boolean {
+  if (lines[index]?.includes(KEEP_MARKER)) return true
+  return index > 0 && (lines[index - 1]?.includes(KEEP_MARKER) ?? false)
+}
+
+function renameLine(line: string): string {
+  const replaced = line.replace(SCAN, (match, guarded: string | undefined) =>
+    guarded === undefined ? REPLACEMENT[match] : guarded,
+  )
+
+  return replaced.replace(
+    ARTICLE,
+    (_match, article: string, gap: string, token: string) =>
+      `${article}${gap}${token}`,
+  )
+}
+
+/**
+ * What `renameText` would do, without doing it. Reported rather than inferred
+ * from a diff so a run can say how much it protected, which is the number a
+ * reader needs to trust that the exclusions fired at all.
+ */
+export function scanText(text: string): ScanCount {
+  let renamed = 0
+  let protectedCount = 0
+  const lines = text.split('\n')
+
+  for (const [index, line] of lines.entries()) {
+    if (isKept(lines, index)) continue
+
+    for (const [, guarded] of line.matchAll(SCAN)) {
+      if (guarded === undefined) renamed += 1
+      else protectedCount += 1
+    }
+  }
+
+  return { renamed, protectedCount }
+}
+
+/**
+ * The path a file moves to. Runs the same scanner as the content rewrite, so
+ * a protected form appearing in a path is protected there too and the two
+ * halves of the sweep cannot disagree about what the token means.
+ */
+export function renamePath(path: string): string {
+  return renameText(path)
+}