@erclx/aitk 0.8.0

package/src/sync/engine.ts

@@ -0,0 +1,416 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { isAbsolute, relative, resolve } from 'node:path'
+import { copyPreservingMode } from '@/copy'
+import {
+  type DomainHashes,
+  hashFile,
+  readStamp,
+  type StampSource,
+  stampedHashes,
+  toStampKey,
+  writeStamp,
+} from '@/sync/stamp'
+import { isDirectory } from '@/target'
+import {
+  intro,
+  isNonInteractive,
+  logAdd,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  select,
+} from '@/ui'
+
+const GREEN = '\x1b[0;32m'
+const NC = '\x1b[0m'
+
+/**
+ * One installed file in three path flavours: absolute, relative to the
+ * domain's installed root, and relative to the target. Adapters match on
+ * `relToRoot` and every log line prints `rel`.
+ */
+export interface InstalledFile {
+  readonly path: string
+  readonly relToRoot: string
+  readonly rel: string
+}
+
+export interface RetiredSurface {
+  readonly path: string
+  readonly rel: string
+  readonly notice: string
+}
+
+export type SyncChange =
+  | {
+      readonly kind: 'copy'
+      readonly source: string
+      readonly dest: string
+      readonly rel: string
+    }
+  | { readonly kind: 'delete'; readonly dest: string; readonly rel: string }
+
+/**
+ * How an installed file compares to its toolkit source, and when it differs,
+ * who moved it. `stale` and `customized` need the stamp to tell apart, so
+ * `drifted` stays the verdict for a difference no stamp covers.
+ *
+ * `orphaned` and `stranded` both mean the walk found no source, and they are
+ * separate because they need opposite treatment. A project-authored file is
+ * orphaned and stays that way forever. A stamped file the toolkit no longer
+ * installs to is stranded, which is a relocation waiting on a decision.
+ */
+export type EntryState =
+  | 'matching'
+  | 'stale'
+  | 'customized'
+  | 'drifted'
+  | 'orphaned'
+  | 'stranded'
+
+export interface ScanEntry {
+  readonly state: EntryState
+  readonly rel: string
+}
+
+export interface SyncPlan {
+  readonly entries: readonly ScanEntry[]
+  readonly retired: readonly RetiredSurface[]
+  readonly changes: readonly SyncChange[]
+}
+
+/**
+ * What a headless run does once the plan has changes. Domains whose files the
+ * toolkit owns apply them. Domains whose files a project is expected to edit
+ * refuse, because an unattended overwrite of a customized file is data loss
+ * with no prompt in front of it.
+ */
+export type NonInteractivePolicy =
+  | { readonly kind: 'apply' }
+  | {
+      readonly kind: 'refuse'
+      readonly message: string
+      readonly hint: string
+    }
+
+/**
+ * The two holes every domain sync leaves open: where a destination file's
+ * source lives, and what counts as a change beyond a plain content diff.
+ * Everything else in a sync is identical across gov, snippets, and standards,
+ * so it lives in the engine.
+ *
+ * The optional members exist because one adapter needed each of them. Leaving
+ * all three unset reproduces the behavior gov and snippets already had.
+ */
+export interface SyncAdapter {
+  readonly banner: string
+  /** Rendered as `Scanning <label>`. */
+  readonly label: string
+  readonly missingMessage: string
+  /** Noun for the completion count, e.g. `changes`. */
+  readonly unit: string
+  installedRoot(target: string): string
+  locateSource(file: InstalledFile): string | undefined
+  /** Surfaces the file walk cannot see, such as a retired doc to delete. */
+  collectRetired?(target: string): RetiredSurface[]
+  /** Dropped from the walk, so neither matching nor orphaned. */
+  isExcluded?(file: InstalledFile): boolean
+  /** Defaults to applying. */
+  readonly nonInteractive?: NonInteractivePolicy
+  /** Runs on a completed sync, including one with no changes. */
+  onComplete?(target: string): Promise<void>
+  /** Where this domain's hashes are stamped. Unset domains go unstamped. */
+  readonly stamp?: StampSource
+}
+
+/**
+ * Lists installed markdown, dotfiles included. `Bun.Glob` skips entries
+ * beginning with a dot unless `dot` is set, and every domain installs under
+ * `.claude/`, so a nested dot-directory would silently drop out of the walk.
+ */
+export function listInstalled(root: string, target: string): InstalledFile[] {
+  if (!existsSync(root)) return []
+
+  return [
+    ...new Bun.Glob('**/*.md').scanSync({
+      cwd: root,
+      onlyFiles: true,
+      dot: true,
+    }),
+  ]
+    .sort()
+    .map((relToRoot) => {
+      const path = resolve(root, relToRoot)
+      return { path, relToRoot, rel: relative(target, path) }
+    })
+}
+
+/**
+ * Classifies every installed file against its source without writing anything.
+ * A file with no source is left alone rather than deleted, which is what keeps
+ * project-authored rules alive across a sync.
+ */
+export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
+  const entries: ScanEntry[] = []
+  const changes: SyncChange[] = []
+
+  const hashes = stampedHashes(readStamp(target), adapter.stamp?.domain)
+  const walked = new Set<string>()
+
+  for (const file of listInstalled(adapter.installedRoot(target), target)) {
+    if (adapter.isExcluded?.(file) === true) continue
+    walked.add(toStampKey(file.rel))
+
+    const source = adapter.locateSource(file)
+
+    if (source === undefined || !existsSync(source)) {
+      entries.push({ state: 'orphaned', rel: file.rel })
+      continue
+    }
+
+    if (sameContent(source, file.path)) {
+      entries.push({ state: 'matching', rel: file.rel })
+      continue
+    }
+
+    entries.push({ state: attribute(hashes, file), rel: file.rel })
+    changes.push({
+      kind: 'copy',
+      source,
+      dest: file.path,
+      rel: file.rel,
+    })
+  }
+
+  entries.push(...strandedByRelocation(target, hashes, walked))
+
+  const retired = adapter.collectRetired?.(target) ?? []
+  for (const surface of retired) {
+    changes.push({ kind: 'delete', dest: surface.path, rel: surface.rel })
+  }
+
+  return { entries, retired, changes }
+}
+
+export async function applyChanges(
+  changes: readonly SyncChange[],
+): Promise<void> {
+  logStep('Applying changes')
+
+  for (const change of changes) {
+    if (change.kind === 'copy') {
+      await copyPreservingMode(change.source, change.dest)
+      logAdd(change.rel)
+      continue
+    }
+
+    await rm(change.dest, { force: true })
+    logWarn(`removed ${change.rel}`)
+  }
+}
+
+export interface SyncRunOptions {
+  /** Path the sync refuses to run against, normally the toolkit root. */
+  readonly protectedRoot: string
+}
+
+/**
+ * Runs one domain sync end to end and returns the process exit code. Callers
+ * register a command, build an adapter, and hand both to this function.
+ */
+export async function runDomainSync(
+  adapter: SyncAdapter,
+  target: string,
+  options: SyncRunOptions,
+): Promise<number> {
+  intro(adapter.banner)
+
+  const resolved = resolve(target)
+
+  if (!isDirectory(resolved)) {
+    logError(`Target directory not found: ${target}`)
+    outro()
+    return 1
+  }
+
+  if (resolved === options.protectedRoot) {
+    logError(
+      'Cannot run against toolkit root. Files here are the source of truth.',
+    )
+    outro()
+    return 1
+  }
+
+  const plan = planSync(adapter, resolved)
+
+  if (
+    !existsSync(adapter.installedRoot(resolved)) &&
+    plan.retired.length === 0
+  ) {
+    logWarn(adapter.missingMessage)
+    outro()
+    return 0
+  }
+
+  report(adapter, plan)
+
+  const count = plan.changes.length
+  if (count === 0) {
+    await adapter.onComplete?.(resolved)
+    await recordStamp(adapter, resolved, new Date())
+    outro()
+    process.stderr.write(`${GREEN}✓ Everything up to date${NC}\n`)
+    return 0
+  }
+
+  const policy = adapter.nonInteractive ?? { kind: 'apply' }
+  if (
+    policy.kind === 'refuse' &&
+    isNonInteractive() &&
+    hasUnattributedDrift(plan)
+  ) {
+    logWarn(policy.message)
+    logInfo(policy.hint)
+    outro()
+    return 0
+  }
+
+  const shouldApply = await select({
+    message: `Apply ${count} changes?`,
+    options: [
+      { value: true, label: 'Apply all' },
+      { value: false, label: 'Cancel' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!shouldApply) {
+    logWarn('Sync cancelled')
+    outro()
+    return 0
+  }
+
+  await applyChanges(plan.changes)
+  await adapter.onComplete?.(resolved)
+  await recordStamp(adapter, resolved, new Date())
+
+  outro()
+  process.stderr.write(
+    `${GREEN}✓ Sync complete${NC} \x1b[0;90m(${count} ${adapter.unit})${NC}\n`,
+  )
+  return 0
+}
+
+/**
+ * Reports in walk order rather than grouped by state, so a long rule tree
+ * reads as a directory listing with drift called out in place.
+ */
+function report(adapter: SyncAdapter, plan: SyncPlan): void {
+  logStep(`Scanning ${adapter.label}`)
+
+  for (const entry of plan.entries) {
+    if (entry.state === 'matching') logInfo(entry.rel)
+    else if (entry.state === 'drifted') logWarn(entry.rel)
+    else if (entry.state === 'stale') logWarn(`${entry.rel} (toolkit updated)`)
+    else if (entry.state === 'customized')
+      logWarn(`${entry.rel} (locally customized)`)
+    else if (entry.state === 'stranded')
+      logWarn(`${entry.rel} (installed here by an older toolkit, now moved)`)
+    else logWarn(`${entry.rel} (not in toolkit source, skipping)`)
+  }
+
+  for (const surface of plan.retired) {
+    logWarn(surface.notice)
+  }
+}
+
+function sameContent(left: string, right: string): boolean {
+  return readFileSync(left).equals(readFileSync(right))
+}
+
+/**
+ * Splits a difference by cause. Matching the stamp means the file is untouched
+ * since install and the toolkit is what moved, so the update is mechanical.
+ * Anything else is a local edit, and an uncovered file stays unattributed.
+ */
+function attribute(hashes: DomainHashes, file: InstalledFile): EntryState {
+  const stamped = hashes[toStampKey(file.rel)]
+  if (stamped === undefined) return 'drifted'
+
+  return stamped === hashFile(file.path) ? 'stale' : 'customized'
+}
+
+/**
+ * Stamped paths the walk never reached, because the toolkit installs to a root
+ * it no longer uses. Reporting them is what makes a relocation visible instead
+ * of silent. They are left alone, and queue no change.
+ *
+ * A key escaping the target is dropped rather than reported, so a hand-edited
+ * stamp cannot make the report name paths outside the project.
+ */
+function strandedByRelocation(
+  target: string,
+  hashes: DomainHashes,
+  walked: ReadonlySet<string>,
+): ScanEntry[] {
+  const entries: ScanEntry[] = []
+
+  for (const key of Object.keys(hashes).sort()) {
+    if (walked.has(key)) continue
+
+    const path = resolve(target, key)
+    if (!isInside(target, path) || !existsSync(path)) continue
+
+    entries.push({ state: 'stranded', rel: relative(target, path) })
+  }
+
+  return entries
+}
+
+function isInside(target: string, path: string): boolean {
+  const rel = relative(target, path)
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)
+}
+
+/**
+ * Drift a refusing domain must not touch unattended. A file proven to match
+ * what was installed carries no local edit to lose, so it does not count.
+ */
+function hasUnattributedDrift(plan: SyncPlan): boolean {
+  return plan.entries.some(
+    (entry) => entry.state === 'customized' || entry.state === 'drifted',
+  )
+}
+
+/**
+ * Records what the toolkit placed, after the copies land, so a partial apply
+ * that throws leaves the previous stamp rather than a claim the target does not
+ * meet. Files with no source are project-authored and stay out.
+ *
+ * Reads the installed tree rather than the caller's file list, so a partial
+ * install still stamps the domain's whole installed set.
+ */
+export async function recordStamp(
+  adapter: SyncAdapter,
+  target: string,
+  now: Date,
+): Promise<void> {
+  const stampSource = adapter.stamp
+  if (stampSource === undefined) return
+
+  const hashes: Record<string, string> = {}
+
+  for (const file of listInstalled(adapter.installedRoot(target), target)) {
+    if (adapter.isExcluded?.(file) === true) continue
+
+    const source = adapter.locateSource(file)
+    if (source === undefined || !existsSync(source)) continue
+
+    hashes[toStampKey(file.rel)] = hashFile(file.path)
+  }
+
+  await writeStamp(target, stampSource, hashes, now)
+}

package/src/sync/git.ts

@@ -0,0 +1,204 @@
+import { basename } from 'node:path'
+import { execa } from 'execa'
+import type { SyncDomain } from '@/sync/target'
+import { pipeOutput } from '@/ui'
+
+const FILE_LIST_MAX = 3
+
+export type DomainVerb = 'Add' | 'Remove' | 'Update'
+
+export interface DomainChange {
+  readonly domain: SyncDomain
+  readonly verb: DomainVerb
+  readonly names: readonly string[]
+  readonly paths: readonly string[]
+}
+
+export class GitCommandError extends Error {}
+
+/**
+ * Pulls the path out of each porcelain line by taking the last whitespace
+ * separated field, which is what the bash `awk '{print $NF}'` did. A rename
+ * reports `old -> new` and so yields the destination, and a sync never
+ * produces one because the workflow refuses a dirty tree before it starts.
+ */
+export function changedPaths(status: string): string[] {
+  const paths: string[] = []
+
+  for (const line of status.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+    const fields = trimmed.split(/\s+/)
+    paths.push(fields[fields.length - 1])
+  }
+
+  return paths
+}
+
+export function changedNames(status: string): string[] {
+  const names = changedPaths(status).map((path) => basename(path))
+  return [...new Set(names)].sort()
+}
+
+/**
+ * Classifies a domain's porcelain output as one verb for the pull request body.
+ * Only an all-untracked change reads as `Add` and only an all-deleted one as
+ * `Remove`, so any mix falls through to `Update`.
+ */
+export function classifyStatus(status: string): DomainVerb {
+  let hasModify = false
+  let hasNew = false
+  let hasDelete = false
+
+  for (const line of status.split('\n')) {
+    if (line === '') continue
+    const code = line.slice(0, 2)
+
+    if (code === '??') hasNew = true
+    else if (code === ' D' || code === 'D ' || code === 'DD') hasDelete = true
+    else hasModify = true
+  }
+
+  if (!hasModify && !hasDelete && hasNew) return 'Add'
+  if (!hasModify && !hasNew && hasDelete) return 'Remove'
+  return 'Update'
+}
+
+export function formatFileList(files: readonly string[]): string {
+  if (files.length === 0) return ''
+  if (files.length <= FILE_LIST_MAX) return files.join(', ')
+
+  const head = files.slice(0, FILE_LIST_MAX).join(', ')
+  return `${head}, and ${files.length - FILE_LIST_MAX} more`
+}
+
+/**
+ * Names the branch at minute resolution, so two syncs inside the same minute
+ * collide by design and the collision check turns the second one away.
+ */
+export function syncBranchName(now: Date): string {
+  const pad = (value: number): string => String(value).padStart(2, '0')
+  const day = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`
+  const minute = `${pad(now.getHours())}${pad(now.getMinutes())}`
+
+  return `chore/aitk-sync-${day}-${minute}`
+}
+
+export function commitMessage(domains: readonly SyncDomain[]): string {
+  return `chore(sync): update ${domains.join(', ')} from toolkit`
+}
+
+export function pullRequestBody(changes: readonly DomainChange[]): string {
+  const domains = changes.map((change) => change.domain).join(', ')
+  const lines = [
+    '## Summary',
+    '',
+    `Sync ${domains} from toolkit.`,
+    '',
+    '## Key Changes',
+    '',
+  ]
+
+  for (const change of changes) {
+    lines.push(
+      `- ${change.verb} \`${change.domain}/\` ${formatFileList(change.names)}.`,
+    )
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * The seam every git mutation goes through, so the workflow can be driven by a
+ * fake in tests without a repository behind it. Reads swallow failure the way
+ * the bash `2>/dev/null || true` did. Mutations throw, because a failed commit
+ * or push must not be reported as a completed sync.
+ */
+export interface GitRunner {
+  status(paths: readonly string[]): Promise<string>
+  currentBranch(): Promise<string>
+  branchExists(name: string): Promise<boolean>
+  remoteBranchExists(name: string): Promise<boolean>
+  createBranch(name: string): Promise<void>
+  stage(paths: readonly string[]): Promise<void>
+  commit(message: string): Promise<void>
+  push(branch: string): Promise<void>
+}
+
+export interface PullRequestOpener {
+  create(title: string, body: string): Promise<string>
+}
+
+export function createGitRunner(target: string): GitRunner {
+  return {
+    status: (paths) => read(target, ['status', '--short', '--', ...paths]),
+    currentBranch: () => read(target, ['symbolic-ref', '--short', 'HEAD']),
+    branchExists: async (name) =>
+      (await read(target, ['branch', '--list', name])) !== '',
+    remoteBranchExists: async (name) =>
+      (await read(target, ['ls-remote', '--heads', 'origin', name])) !== '',
+    createBranch: async (name) => {
+      await mutate(target, ['checkout', '-b', name])
+    },
+    stage: async (paths) => {
+      await mutate(target, ['add', '--', ...paths])
+    },
+    commit: async (message) => {
+      await mutate(target, ['commit', '-m', message])
+    },
+    push: async (branch) => {
+      await mutate(target, ['push', '-u', 'origin', branch])
+    },
+  }
+}
+
+/**
+ * Passes the body on stdin rather than through a temp file. The bash wrote one
+ * with `mktemp` and removed it afterwards, which left the file behind whenever
+ * `gh` failed.
+ */
+export function createPullRequestOpener(target: string): PullRequestOpener {
+  return {
+    create: async (title, body) => {
+      const result = await execa(
+        'gh',
+        ['pr', 'create', '--title', title, '--body-file', '-'],
+        { cwd: target, input: body, reject: false },
+      )
+
+      if (result.exitCode !== 0) {
+        throw new GitCommandError(
+          `gh pr create failed: ${result.stderr || result.stdout}`,
+        )
+      }
+
+      return result.stdout.trim()
+    },
+  }
+}
+
+export async function hasGh(): Promise<boolean> {
+  const result = await execa('command', ['-v', 'gh'], {
+    reject: false,
+    shell: true,
+  })
+
+  return result.exitCode === 0
+}
+
+async function read(target: string, args: readonly string[]): Promise<string> {
+  const result = await execa('git', ['-C', target, ...args], { reject: false })
+  return result.exitCode === 0 ? result.stdout : ''
+}
+
+async function mutate(target: string, args: readonly string[]): Promise<void> {
+  const result = await execa('git', ['-C', target, ...args], { reject: false })
+
+  if (result.exitCode !== 0) {
+    throw new GitCommandError(
+      `git ${args[0]} failed: ${result.stderr || result.stdout}`,
+    )
+  }
+
+  if (result.stdout !== '') pipeOutput(result.stdout)
+}