@erclx/aitk 0.8.0

package/src/snippets/categories.ts

@@ -0,0 +1,59 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { isDirectory } from '@/target'
+
+export const BASE_CATEGORY = 'base'
+
+export function snippetsSourceDir(root: string): string {
+  return join(root, 'snippets')
+}
+
+/**
+ * Lists the folder categories. `base` is the synthetic name for snippets
+ * sitting directly under `snippets/`, so it is not a directory and callers
+ * prepend it themselves.
+ *
+ * Nothing is filtered: toolkit-internal snippets are authored under `internal/`,
+ * which this never reads, so every category found here is publishable.
+ */
+export function listFolderCategories(root: string): string[] {
+  const dir = snippetsSourceDir(root)
+  if (!isDirectory(dir)) return []
+
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+export function listCategories(root: string): string[] {
+  return [BASE_CATEGORY, ...listFolderCategories(root)]
+}
+
+export function categoryDir(root: string, category: string): string {
+  const source = snippetsSourceDir(root)
+  return category === BASE_CATEGORY ? source : join(source, category)
+}
+
+/**
+ * Tests for a directory rather than mere existence. `snippets/` holds files
+ * alongside its category folders, so an argument naming one of them resolves
+ * to a real path that cannot be scanned as a category.
+ */
+export function categoryExists(root: string, category: string): boolean {
+  return isDirectory(categoryDir(root, category))
+}
+
+/**
+ * Lists one category's entry slugs. Only the immediate level is read, matching
+ * the `find -maxdepth 1` the bash used, so a nested folder is its own category
+ * rather than part of its parent.
+ */
+export function listEntries(root: string, category: string): string[] {
+  const dir = categoryDir(root, category)
+  if (!isDirectory(dir)) return []
+
+  return [...new Bun.Glob('*.md').scanSync({ cwd: dir, onlyFiles: true })]
+    .map((name) => name.slice(0, -'.md'.length))
+    .sort()
+}

package/src/snippets/install.ts

@@ -0,0 +1,125 @@
+import { existsSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { copyPreservingMode } from '@/copy'
+import {
+  BASE_CATEGORY,
+  categoryDir,
+  categoryExists,
+  listCategories,
+  listEntries,
+  snippetsSourceDir,
+} from '@/snippets/categories'
+import { findPreset, loadPresets } from '@/snippets/presets'
+
+export const ALL_CATEGORY = 'all'
+
+export interface SnippetFile {
+  readonly src: string
+  readonly relPath: string
+}
+
+export type SnippetResolution =
+  | {
+      readonly ok: true
+      readonly step: string
+      readonly files: readonly SnippetFile[]
+      readonly missing: readonly string[]
+    }
+  | { readonly ok: false; readonly unknownCategory: string }
+
+export function installedSnippetsDir(target: string): string {
+  return join(target, '.claude', 'snippets')
+}
+
+/**
+ * Derives the destination path. A snippet directly under `snippets/` installs
+ * flat and a nested one keeps its immediate parent, so the installed tree
+ * mirrors the source one level deep.
+ */
+export function deriveDestRelPath(root: string, src: string): string {
+  const parent = dirname(src)
+  const filename = basename(src)
+
+  return parent === snippetsSourceDir(root)
+    ? filename
+    : `${basename(parent)}/${filename}`
+}
+
+function filesInCategory(root: string, category: string): SnippetFile[] {
+  return listEntries(root, category).map((slug) => {
+    const src = join(categoryDir(root, category), `${slug}.md`)
+    return { src, relPath: deriveDestRelPath(root, src) }
+  })
+}
+
+/**
+ * Resolves the one argument three ways. `all` wins, then a preset name, then a
+ * folder, which is the bash precedence and matters because a folder sharing a
+ * preset name resolves to the preset.
+ *
+ * Preset slugs pass the internal-category filter too. A slug is a path relative
+ * to `snippets/`, so a preset naming `aitk/<slug>` would otherwise reach an
+ * internal snippet through the one install path the filter did not cover.
+ */
+export function resolveSnippets(
+  root: string,
+  category: string,
+): SnippetResolution {
+  if (category === ALL_CATEGORY) {
+    const files = listCategories(root).flatMap((name) =>
+      filesInCategory(root, name),
+    )
+    return { ok: true, step: 'Resolving all categories', files, missing: [] }
+  }
+
+  const preset = findPreset(root, category)
+  if (preset) {
+    const files: SnippetFile[] = []
+    const missing: string[] = []
+
+    for (const slug of preset.slugs) {
+      const src = join(snippetsSourceDir(root), `${slug}.md`)
+      if (existsSync(src)) files.push({ src, relPath: `${slug}.md` })
+      else missing.push(slug)
+    }
+
+    return { ok: true, step: `Resolving preset: ${category}`, files, missing }
+  }
+
+  if (category !== BASE_CATEGORY && !categoryExists(root, category)) {
+    return { ok: false, unknownCategory: category }
+  }
+
+  return {
+    ok: true,
+    step: `Resolving category: ${category}`,
+    files: filesInCategory(root, category),
+    missing: [],
+  }
+}
+
+/**
+ * Lists everything the picker offers: presets first, then `base`, then the
+ * folder categories, matching the order the bash built the menu in.
+ */
+export function installableCategories(root: string): string[] {
+  return [
+    ...loadPresets(root).map((preset) => preset.name),
+    ...listCategories(root),
+  ]
+}
+
+export async function installSnippets(
+  files: readonly SnippetFile[],
+  target: string,
+): Promise<string[]> {
+  const destDir = installedSnippetsDir(target)
+  const installed: string[] = []
+
+  for (const file of files) {
+    await copyPreservingMode(file.src, join(destDir, file.relPath))
+    installed.push(join('.claude', 'snippets', file.relPath))
+  }
+
+  return installed
+}

package/src/snippets/list.ts

@@ -0,0 +1,32 @@
+import { listCategories, listEntries } from '@/snippets/categories'
+import { loadPresets } from '@/snippets/presets'
+
+export interface CategoryCatalogEntry {
+  readonly name: string
+  readonly entries: readonly string[]
+}
+
+export interface SnippetsCatalog {
+  readonly presets: readonly {
+    readonly name: string
+    readonly slugs: readonly string[]
+  }[]
+  readonly categories: readonly CategoryCatalogEntry[]
+}
+
+/**
+ * Builds the catalog both output modes read, so the human list and the `--json`
+ * one cannot describe different corpora.
+ */
+export function buildSnippetsCatalog(root: string): SnippetsCatalog {
+  return {
+    presets: loadPresets(root).map((preset) => ({
+      name: preset.name,
+      slugs: preset.slugs,
+    })),
+    categories: listCategories(root).map((name) => ({
+      name,
+      entries: listEntries(root, name),
+    })),
+  }
+}

package/src/snippets/presets.ts

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { snippetsSourceDir } from '@/snippets/categories'
+
+export interface Preset {
+  readonly name: string
+  readonly slugs: readonly string[]
+}
+
+export function presetsPath(root: string): string {
+  return join(snippetsSourceDir(root), 'snippets.toml')
+}
+
+/**
+ * Reads every preset from `snippets.toml`. The bash read section headers with
+ * `grep '^\['` and then re-walked the file per preset with a `BASH_REMATCH`
+ * loop, so a name carrying a bracket or a slug split across lines parsed by
+ * accident rather than by rule.
+ */
+export function loadPresets(root: string): Preset[] {
+  const path = presetsPath(root)
+  if (!existsSync(path)) return []
+
+  const parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+    string,
+    unknown
+  >
+  const presets: Preset[] = []
+
+  for (const [name, table] of Object.entries(parsed)) {
+    if (typeof table !== 'object' || table === null || Array.isArray(table)) {
+      continue
+    }
+    const names = (table as Record<string, unknown>).names
+    presets.push({
+      name,
+      slugs: Array.isArray(names)
+        ? names.filter(
+            (slug): slug is string => typeof slug === 'string' && slug !== '',
+          )
+        : [],
+    })
+  }
+
+  return presets.sort((left, right) => left.name.localeCompare(right.name))
+}
+
+export function findPreset(root: string, name: string): Preset | undefined {
+  return loadPresets(root).find((preset) => preset.name === name)
+}

package/src/standards/adapter.ts

@@ -0,0 +1,51 @@
+import { existsSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import {
+  INDEX_FILE,
+  refreshIndex,
+  standardsInstallDir,
+} from '@/standards/index-refresh'
+import type { InstalledFile, SyncAdapter } from '@/sync/engine'
+
+export function standardsSourceDir(root: string): string {
+  return join(root, 'standards')
+}
+
+/**
+ * Matches installed standards to sources by filename against the flat
+ * `standards/` root. A standard that lives in a source subfolder, such as
+ * `bundled/`, has no flat sibling and so reads as project-authored, which is
+ * what keeps `install` and `sync` agreeing on the same set.
+ *
+ * Standards are seeds a project is expected to edit, unlike gov rules and
+ * snippets, so a headless run refuses to overwrite drift rather than applying
+ * it. That refusal is the reason the engine grew a per-adapter policy.
+ */
+export function createStandardsAdapter(root: string): SyncAdapter {
+  const sourceDir = standardsSourceDir(root)
+
+  return {
+    banner: 'aitk standards sync',
+    label: 'standards',
+    missingMessage:
+      "No .claude/standards/ found in target. Run 'aitk standards install' first.",
+    unit: 'standards',
+    installedRoot: standardsInstallDir,
+    isExcluded: (file: InstalledFile) => basename(file.path) === INDEX_FILE,
+    locateSource: (file: InstalledFile) =>
+      locateSource(sourceDir, basename(file.path)),
+    nonInteractive: {
+      kind: 'refuse',
+      message:
+        'Drifts detected. Refusing to auto-apply in non-interactive mode.',
+      hint: 'Run interactively, or use /claude-seed-sync for per-section audit that preserves customizations.',
+    },
+    onComplete: (target: string) => refreshIndex(sourceDir, target),
+    stamp: { domain: 'standards', toolkitRoot: root },
+  }
+}
+
+function locateSource(sourceDir: string, name: string): string | undefined {
+  const source = join(sourceDir, name)
+  return existsSync(source) ? source : undefined
+}

package/src/standards/index-refresh.ts

@@ -0,0 +1,44 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { copyPreservingMode } from '@/copy'
+import { regenOne } from '@/indexes/regen'
+import { logAdd, logWarn } from '@/ui'
+
+export const STANDARDS_REL = join('.claude', 'standards')
+export const INDEX_FILE = 'index.md'
+
+export function standardsInstallDir(target: string): string {
+  return join(target, STANDARDS_REL)
+}
+
+/**
+ * Replaces the target's `index.md` from source and rebuilds it against what
+ * actually landed. It runs on every completed install and every completed sync,
+ * including one with no changes, because the catalog can go stale from a file
+ * the toolkit stopped shipping rather than from drift in a file it still does.
+ *
+ * `install` and `sync` are peers, so this sits beside both rather than inside
+ * the sync adapter, where an install would be importing from the other verb.
+ */
+export async function refreshIndex(
+  sourceDir: string,
+  target: string,
+): Promise<void> {
+  const installedDir = standardsInstallDir(target)
+  const source = join(sourceDir, INDEX_FILE)
+
+  if (!existsSync(source)) {
+    logWarn(`No ${INDEX_FILE} in toolkit standards, leaving the target catalog`)
+    return
+  }
+
+  await copyPreservingMode(source, join(installedDir, INDEX_FILE))
+  const result = await regenOne(installedDir, { dryRun: false })
+
+  if (result.action === 'error') {
+    logWarn(`${join(STANDARDS_REL, INDEX_FILE)} regen failed: ${result.reason}`)
+    return
+  }
+
+  logAdd(join(STANDARDS_REL, INDEX_FILE))
+}

package/src/standards/install.ts

@@ -0,0 +1,52 @@
+import { existsSync, readdirSync } from 'node:fs'
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { copyPreservingMode } from '@/copy'
+import { INDEX_FILE, STANDARDS_REL } from '@/standards/index-refresh'
+
+export interface StandardsSource {
+  readonly path: string
+  readonly name: string
+}
+
+/**
+ * Lists the flat `standards/` root only, which is the same set the sync adapter
+ * matches installed files against. A standard in a source subfolder such as
+ * `bundled/` is not installed wholesale, so the two verbs agree on scope.
+ *
+ * `index.md` is excluded because install copies it separately and then rebuilds
+ * it against what landed, rather than shipping the toolkit's own catalog.
+ */
+export function planInstall(sourceDir: string): StandardsSource[] {
+  if (!existsSync(sourceDir)) return []
+
+  return readdirSync(sourceDir, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        entry.name.endsWith('.md') &&
+        entry.name !== INDEX_FILE,
+    )
+    .map((entry) => ({ path: join(sourceDir, entry.name), name: entry.name }))
+    .sort((left, right) => left.name.localeCompare(right.name))
+}
+
+/**
+ * Copies every standard and returns the labels to log. Routes through
+ * `copyPreservingMode` because the `cp` it replaces left an existing
+ * destination's mode alone, so a target file held at 600 stays there.
+ */
+export async function applyInstall(
+  files: readonly StandardsSource[],
+  destDir: string,
+): Promise<string[]> {
+  await mkdir(destDir, { recursive: true })
+
+  await Promise.all(
+    files.map((file) =>
+      copyPreservingMode(file.path, join(destDir, file.name)),
+    ),
+  )
+
+  return files.map((file) => join(STANDARDS_REL, file.name))
+}

package/src/sync/check.ts

@@ -0,0 +1,269 @@
+import { join } from 'node:path'
+import { execa } from 'execa'
+import { createGovAdapter } from '@/gov/adapter'
+import { createSnippetsAdapter } from '@/snippets/adapter'
+import { planSync, type ScanEntry, type SyncAdapter } from '@/sync/engine'
+import {
+  readStamp,
+  STAMP_DOMAINS,
+  type Stamp,
+  stampedCommit,
+  type StampDomain,
+} from '@/sync/stamp'
+import { createStandardsAdapter } from '@/standards/adapter'
+import { isDirectory } from '@/target'
+
+/**
+ * The toolkit path whose commits change what each domain holds. `claude/skills/`
+ * is deliberately absent: skills load live from the plugin directory, so they
+ * never go stale and belong in the read-only section instead.
+ */
+const SYNCED_SOURCES: Record<StampDomain, string> = {
+  standards: 'standards/',
+  snippets: 'snippets/',
+  governance: 'governance/rules/',
+}
+
+const ADAPTERS: Record<StampDomain, (root: string) => SyncAdapter> = {
+  standards: createStandardsAdapter,
+  snippets: createSnippetsAdapter,
+  governance: createGovAdapter,
+}
+
+const INSTALL_MARKERS: Record<StampDomain, readonly string[]> = {
+  standards: ['.claude', 'standards'],
+  snippets: ['.claude', 'snippets'],
+  governance: ['.claude', 'rules'],
+}
+
+export interface StateCounts {
+  readonly matching: number
+  readonly stale: number
+  readonly customized: number
+  readonly drifted: number
+  readonly orphaned: number
+  readonly stranded: number
+}
+
+export interface DomainReport {
+  readonly domain: StampDomain
+  readonly stamped: boolean
+  /** This domain's own anchor, not the target's most recent sync. */
+  readonly commit?: string
+  readonly syncedAt?: string
+  readonly counts: StateCounts
+  readonly entries: readonly ScanEntry[]
+  readonly upstream: readonly UpstreamCommit[]
+}
+
+export interface UpstreamCommit {
+  readonly sha: string
+  readonly subject: string
+}
+
+export interface CheckReport {
+  readonly covers: readonly StampDomain[]
+  readonly domains: readonly DomainReport[]
+  readonly newSkills: readonly string[]
+}
+
+export function installedStampDomains(target: string): StampDomain[] {
+  return STAMP_DOMAINS.filter((domain) =>
+    isDirectory(join(target, ...INSTALL_MARKERS[domain])),
+  )
+}
+
+export function countStates(entries: readonly ScanEntry[]): StateCounts {
+  return {
+    matching: count(entries, 'matching'),
+    stale: count(entries, 'stale'),
+    customized: count(entries, 'customized'),
+    drifted: count(entries, 'drifted'),
+    orphaned: count(entries, 'orphaned'),
+    stranded: count(entries, 'stranded'),
+  }
+}
+
+/**
+ * Whether the target has diverged from the toolkit in a way a sync could close.
+ * Orphaned files are excluded: a project-authored rule never converges, and
+ * counting it would leave `--exit-code` failing forever with no remedy.
+ */
+export function hasDrift(report: CheckReport): boolean {
+  return report.domains.some(
+    (domain) =>
+      domain.counts.stale +
+        domain.counts.customized +
+        domain.counts.drifted +
+        domain.counts.stranded >
+      0,
+  )
+}
+
+/**
+ * Bounds each domain's upstream read by that domain's own anchor and its own
+ * source path. A shared anchor would let a gov sync advance the revision
+ * standards measures from, silently dropping a standards change out of the read.
+ */
+export async function buildCheckReport(
+  toolkitRoot: string,
+  target: string,
+): Promise<CheckReport> {
+  const stamp = readStamp(target)
+
+  const domains = await Promise.all(
+    installedStampDomains(target).map((domain) =>
+      buildDomainReport(toolkitRoot, target, stamp, domain),
+    ),
+  )
+
+  const anchors = domains
+    .map((domain) => domain.commit)
+    .filter((commit): commit is string => commit !== undefined)
+
+  return {
+    covers: stamp?.covers ?? [],
+    domains,
+    newSkills: await readNewSkills(toolkitRoot, anchors),
+  }
+}
+
+async function buildDomainReport(
+  toolkitRoot: string,
+  target: string,
+  stamp: Stamp | undefined,
+  domain: StampDomain,
+): Promise<DomainReport> {
+  const plan = planSync(ADAPTERS[domain](toolkitRoot), target)
+  const record = stamp?.domains[domain]
+  const since = stampedCommit(stamp, domain)
+
+  return {
+    domain,
+    stamped: record !== undefined,
+    commit: since,
+    syncedAt: record?.syncedAt,
+    counts: countStates(plan.entries),
+    entries: plan.entries,
+    upstream:
+      since === undefined
+        ? []
+        : await readUpstream(toolkitRoot, since, SYNCED_SOURCES[domain]),
+  }
+}
+
+export function parseUpstream(log: string): UpstreamCommit[] {
+  const commits: UpstreamCommit[] = []
+
+  for (const line of log.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+
+    const boundary = trimmed.indexOf(' ')
+    if (boundary === -1) continue
+
+    commits.push({
+      sha: trimmed.slice(0, boundary),
+      subject: trimmed.slice(boundary + 1),
+    })
+  }
+
+  return commits
+}
+
+/** A skill is new when its `SKILL.md` was added, not when a support file was. */
+export function parseNewSkills(paths: string): string[] {
+  const names = paths
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.endsWith('/SKILL.md'))
+    .map((line) => line.split('/').at(-2))
+    .filter((name): name is string => name !== undefined)
+
+  return [...new Set(names)].sort()
+}
+
+async function readUpstream(
+  root: string,
+  since: string,
+  sourcePath: string,
+): Promise<UpstreamCommit[]> {
+  const log = await read(root, [
+    'log',
+    '--oneline',
+    '--no-decorate',
+    `${since}..HEAD`,
+    '--',
+    sourcePath,
+  ])
+
+  return parseUpstream(log)
+}
+
+/**
+ * Skills are not domain-scoped, so the read runs from the oldest anchor across
+ * domains. Over-reporting a skill costs a line, while measuring from the newest
+ * would hide one that arrived before the most recent domain sync.
+ */
+async function readNewSkills(
+  root: string,
+  anchors: readonly string[],
+): Promise<string[]> {
+  const since = await oldestAnchor(root, anchors)
+  if (since === undefined) return []
+
+  const paths = await read(root, [
+    'diff',
+    '--name-only',
+    '--diff-filter=A',
+    `${since}..HEAD`,
+    '--',
+    'claude/skills/',
+  ])
+
+  return parseNewSkills(paths)
+}
+
+async function oldestAnchor(
+  root: string,
+  anchors: readonly string[],
+): Promise<string | undefined> {
+  const unique = [...new Set(anchors)]
+  let oldest = unique[0]
+
+  for (const candidate of unique.slice(1)) {
+    if (await isAncestor(root, candidate, oldest)) oldest = candidate
+  }
+
+  return oldest
+}
+
+async function isAncestor(
+  root: string,
+  candidate: string,
+  reference: string,
+): Promise<boolean> {
+  const result = await execa(
+    'git',
+    ['-C', root, 'merge-base', '--is-ancestor', candidate, reference],
+    { reject: false },
+  )
+
+  return result.exitCode === 0
+}
+
+/**
+ * A toolkit outside a git clone, or a stamped revision this clone has never
+ * seen, yields no range. The per-file report still stands on its own.
+ */
+async function read(root: string, args: readonly string[]): Promise<string> {
+  const result = await execa('git', ['-C', root, ...args], { reject: false })
+  return result.exitCode === 0 ? result.stdout : ''
+}
+
+function count(
+  entries: readonly ScanEntry[],
+  state: ScanEntry['state'],
+): number {
+  return entries.filter((entry) => entry.state === state).length
+}