@erclx/aitk 0.8.0

package/src/sync/stamp.ts

@@ -0,0 +1,202 @@
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname, join, sep } from 'node:path'
+import { execa } from 'execa'
+
+/**
+ * Domains the stamp can attribute. Tooling runs its own inject and manifest
+ * machinery rather than the sync engine, so it is absent by design.
+ */
+export const STAMP_DOMAINS = ['standards', 'snippets', 'governance'] as const
+
+export type StampDomain = (typeof STAMP_DOMAINS)[number]
+
+/** What a domain needs to stamp itself: its key, and the clone to date it against. */
+export interface StampSource {
+  readonly domain: StampDomain
+  readonly toolkitRoot: string
+}
+
+/** Target-relative posix path to content hash, for one domain. */
+export type DomainHashes = Readonly<Record<string, string>>
+
+/**
+ * One domain's record. The anchor sits here rather than at the top level
+ * because domains sync independently, and a shared anchor would let a gov sync
+ * advance the revision standards measures its upstream range from.
+ */
+export interface DomainStamp {
+  /** Toolkit revision this domain last synced from. Absent outside a git clone. */
+  readonly commit?: string
+  readonly syncedAt: string
+  readonly files: DomainHashes
+}
+
+export interface Stamp {
+  /** Domains actually stamped in this target, so an unstamped one is legible. */
+  readonly covers: readonly StampDomain[]
+  readonly domains: Readonly<Partial<Record<StampDomain, DomainStamp>>>
+}
+
+export function stampPath(target: string): string {
+  return join(target, '.claude', 'aitk.json')
+}
+
+export function hashContent(content: Buffer | string): string {
+  return `sha256:${createHash('sha256').update(content).digest('hex')}`
+}
+
+export function hashFile(path: string): string {
+  return hashContent(readFileSync(path))
+}
+
+/**
+ * Keys are stored posix-style so a stamp written on one platform still
+ * resolves on another.
+ */
+export function toStampKey(rel: string): string {
+  return rel.split(sep).join('/')
+}
+
+/**
+ * A missing or corrupt stamp reads as absent rather than failing, which is what
+ * keeps every unstamped target on the existing unattributed path.
+ */
+export function readStamp(target: string): Stamp | undefined {
+  const path = stampPath(target)
+  if (!existsSync(path)) return undefined
+
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    return isStamp(parsed) ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** The revision this domain last synced from, which bounds its upstream range. */
+export function stampedCommit(
+  stamp: Stamp | undefined,
+  domain: StampDomain,
+): string | undefined {
+  return stamp?.domains[domain]?.commit
+}
+
+export function stampedHashes(
+  stamp: Stamp | undefined,
+  domain: StampDomain | undefined,
+): DomainHashes {
+  if (stamp === undefined || domain === undefined) return {}
+  return stamp.domains[domain]?.files ?? {}
+}
+
+/**
+ * Replaces one domain's record and leaves the others untouched, because domains
+ * install and sync independently but share the one file.
+ */
+export async function writeStamp(
+  target: string,
+  source: StampSource,
+  hashes: DomainHashes,
+  now: Date,
+): Promise<void> {
+  const previous = readStamp(target)
+  const commit = await toolkitCommit(source.toolkitRoot)
+
+  const record: DomainStamp = {
+    ...(commit === undefined ? {} : { commit }),
+    syncedAt: now.toISOString(),
+    files: sortKeys(hashes),
+  }
+
+  const domains = sortDomains({
+    ...previous?.domains,
+    [source.domain]: record,
+  })
+
+  const stamp: Stamp = {
+    covers: STAMP_DOMAINS.filter((domain) => domains[domain] !== undefined),
+    domains,
+  }
+
+  const path = stampPath(target)
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, `${JSON.stringify(stamp, null, 2)}\n`)
+}
+
+const commitCache = new Map<string, Promise<string | undefined>>()
+
+/**
+ * Resolved once per clone per process. A toolkit reached outside a git clone
+ * yields no commit, which costs the report its upstream range but not its
+ * per-file attribution.
+ */
+export function toolkitCommit(root: string): Promise<string | undefined> {
+  const cached = commitCache.get(root)
+  if (cached !== undefined) return cached
+
+  const pending = readCommit(root)
+  commitCache.set(root, pending)
+  return pending
+}
+
+async function readCommit(root: string): Promise<string | undefined> {
+  const result = await execa(
+    'git',
+    ['-C', root, 'rev-parse', '--short', 'HEAD'],
+    { reject: false },
+  )
+
+  return result.exitCode === 0 && result.stdout.trim() !== ''
+    ? result.stdout.trim()
+    : undefined
+}
+
+/** Deterministic key order keeps a re-sync diff empty and a merge conflict local. */
+function sortKeys(hashes: DomainHashes): DomainHashes {
+  return Object.fromEntries(
+    Object.entries(hashes).sort(([left], [right]) => left.localeCompare(right)),
+  )
+}
+
+function sortDomains(
+  domains: Partial<Record<StampDomain, DomainStamp>>,
+): Partial<Record<StampDomain, DomainStamp>> {
+  const sorted: Partial<Record<StampDomain, DomainStamp>> = {}
+  for (const domain of STAMP_DOMAINS) {
+    const record = domains[domain]
+    if (record !== undefined) sorted[domain] = record
+  }
+
+  return sorted
+}
+
+/**
+ * Validates every domain record rather than only the container. A stamp whose
+ * domain value is the wrong shape would otherwise reach `attribute`, where a
+ * bad hash lookup silently reads as a customization.
+ */
+function isStamp(value: unknown): value is Stamp {
+  if (!isRecord(value) || !isRecord(value.domains)) return false
+
+  return Object.entries(value.domains).every(
+    ([domain, record]) =>
+      (STAMP_DOMAINS as readonly string[]).includes(domain) &&
+      isDomainStamp(record),
+  )
+}
+
+function isDomainStamp(value: unknown): value is DomainStamp {
+  if (!isRecord(value) || !isRecord(value.files)) return false
+  if (typeof value.syncedAt !== 'string') return false
+  if (value.commit !== undefined && typeof value.commit !== 'string') {
+    return false
+  }
+
+  return Object.values(value.files).every((hash) => typeof hash === 'string')
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/sync/target.ts

@@ -0,0 +1,79 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { isDirectory } from '@/target'
+
+export const SYNC_DOMAINS = [
+  'standards',
+  'snippets',
+  'governance',
+  'claude',
+] as const
+
+export type SyncDomain = (typeof SYNC_DOMAINS)[number]
+
+export interface DomainState {
+  readonly domain: SyncDomain
+  readonly installed: boolean
+}
+
+const DOMAIN_MARKERS: Record<SyncDomain, string> = {
+  standards: join('.claude', 'standards'),
+  snippets: join('.claude', 'snippets'),
+  governance: join('.claude', 'rules'),
+  claude: '.claude',
+}
+
+/**
+ * Paths whose git status decides whether a domain contributed to the sync
+ * commit. Governance carries the retired `.claude/GOV.md` because a sync that
+ * removes it is still a governance change, and `claude` watches `.gitignore`
+ * because that is the only file `aitk claude sync` writes.
+ */
+const DOMAIN_PATHS: Record<SyncDomain, readonly string[]> = {
+  standards: ['.claude/standards/'],
+  snippets: ['.claude/snippets/'],
+  governance: ['.claude/rules/', '.claude/GOV.md'],
+  claude: ['.gitignore'],
+}
+
+export function domainPaths(domain: SyncDomain): readonly string[] {
+  return DOMAIN_PATHS[domain]
+}
+
+export function detectDomains(target: string): DomainState[] {
+  return SYNC_DOMAINS.map((domain) => ({
+    domain,
+    installed: isDirectory(join(target, DOMAIN_MARKERS[domain])),
+  }))
+}
+
+export function installedDomains(states: readonly DomainState[]): SyncDomain[] {
+  return states.filter((state) => state.installed).map((state) => state.domain)
+}
+
+/**
+ * Whether a domain's sync command should run, which is not the same question
+ * `detectDomains` answers. Governance reports as absent without
+ * `.claude/rules/`, yet still syncs when only the retired `.claude/GOV.md`
+ * remains, so that the sync can delete it. The bash drew the same distinction
+ * between `detect_domains` and `run_syncs`.
+ */
+export function shouldSync(target: string, domain: SyncDomain): boolean {
+  if (domain === 'governance') {
+    return (
+      isDirectory(join(target, '.claude', 'rules')) ||
+      existsSync(join(target, '.claude', 'GOV.md'))
+    )
+  }
+
+  return isDirectory(join(target, DOMAIN_MARKERS[domain]))
+}
+
+/**
+ * A target with no `.git/` reports clean, because `git status` fails there and
+ * the bash swallowed that failure. The guard exists to make the sync commit
+ * survivable, and a directory outside git has no commit to protect.
+ */
+export function isTreeClean(status: string): boolean {
+  return status.trim() === ''
+}

package/src/sync/workflow.ts

@@ -0,0 +1,201 @@
+import { join } from 'node:path'
+import {
+  changedNames,
+  changedPaths,
+  classifyStatus,
+  commitMessage,
+  type DomainChange,
+  type GitRunner,
+  type PullRequestOpener,
+  pullRequestBody,
+  syncBranchName,
+} from '@/sync/git'
+import { domainPaths, SYNC_DOMAINS } from '@/sync/target'
+import { isDirectory } from '@/target'
+import {
+  intro,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  select,
+} from '@/ui'
+
+const GREEN = '\x1b[0;32m'
+const NC = '\x1b[0m'
+
+const PROTECTED_BRANCHES: readonly string[] = ['main', 'master']
+
+export type WorkflowChoice = 'pr' | 'commit' | 'cancel'
+
+export interface WorkflowDeps {
+  readonly git: GitRunner
+  /** Absent when `gh` is not installed, which hides the pull request option. */
+  readonly pullRequests: PullRequestOpener | undefined
+  readonly now: Date
+  readonly nonInteractive: boolean
+  /**
+   * Defaults to the interactive prompt. A test injects it to reach the commit
+   * and pull request branches, which `select` otherwise gates behind a TTY.
+   */
+  readonly choose?: (canOpenPullRequest: boolean) => Promise<WorkflowChoice>
+}
+
+/**
+ * Groups the target's pending changes by the domain that produced them. Each
+ * domain is read independently, so the four status calls run together.
+ */
+export async function collectChanges(git: GitRunner): Promise<DomainChange[]> {
+  const results = await Promise.all(
+    SYNC_DOMAINS.map(async (domain) => {
+      const status = await git.status(domainPaths(domain))
+      return { domain, status }
+    }),
+  )
+
+  const changes: DomainChange[] = []
+
+  for (const { domain, status } of results) {
+    const names = changedNames(status)
+    if (names.length === 0) continue
+
+    changes.push({
+      domain,
+      verb: classifyStatus(status),
+      names,
+      paths: changedPaths(status),
+    })
+  }
+
+  return changes
+}
+
+/**
+ * Commits what the domain syncs wrote and optionally opens a pull request.
+ *
+ * This is the only toolkit code that writes to a git remote, which is why a
+ * headless run refuses it outright. `select_option` resolved to its first
+ * option under `AITK_NON_INTERACTIVE=1`, and the first option here was
+ * `Commit and open PR` whenever `gh` was installed, so an agent following the
+ * documented non-interactive path pushed a branch and opened a pull request on
+ * someone's repository without being asked.
+ */
+export async function runGitWorkflow(
+  target: string,
+  deps: WorkflowDeps,
+): Promise<number> {
+  if (!isDirectory(join(target, '.git'))) return 0
+
+  const changes = await collectChanges(deps.git)
+  if (changes.length === 0) return 0
+
+  const domains = changes.map((change) => change.domain)
+  const message = commitMessage(domains)
+  const body = pullRequestBody(changes)
+  const branch = syncBranchName(deps.now)
+
+  intro('aitk sync → git')
+
+  const [localTaken, remoteTaken] = await Promise.all([
+    deps.git.branchExists(branch),
+    deps.git.remoteBranchExists(branch),
+  ])
+
+  if (localTaken || remoteTaken) {
+    logWarn(
+      `${branch} already exists. Wait a minute or delete it, then re-run.`,
+    )
+    outro()
+    return 0
+  }
+
+  const currentBranch = await deps.git.currentBranch()
+  const onProtected =
+    currentBranch === '' || PROTECTED_BRANCHES.includes(currentBranch)
+
+  logStep('Preview')
+  logInfo(`Domains: ${domains.join(', ')}`)
+  logInfo(
+    onProtected
+      ? `Branch:  ${branch} (source: ${currentBranch || 'detached'})`
+      : `Branch:  ${currentBranch} (commit only) or ${branch} (PR)`,
+  )
+  logInfo(`Commit:  ${message}`)
+
+  logStep('PR body')
+  pipeOutput(body)
+
+  if (deps.nonInteractive) {
+    logWarn('Refusing the git workflow in non-interactive mode.')
+    logInfo(`Would commit ${domains.join(', ')} to ${branch}.`)
+    logInfo('Run interactively to commit, push, and open the pull request.')
+    outro()
+    return 0
+  }
+
+  const opener = deps.pullRequests
+  if (opener === undefined) {
+    logWarn(
+      'gh CLI not found — PR option unavailable. Install from https://cli.github.com',
+    )
+  }
+
+  const choose = deps.choose ?? promptChoice
+  const choice = await choose(opener !== undefined)
+
+  if (choice === 'cancel') {
+    logWarn('Skipped')
+    outro()
+    return 0
+  }
+
+  const paths = [...new Set(changes.flatMap((change) => change.paths))]
+
+  try {
+    logStep('Committing')
+
+    if (choice === 'pr' || onProtected) await deps.git.createBranch(branch)
+    await deps.git.stage(paths)
+    await deps.git.commit(message)
+
+    if (choice === 'commit' || opener === undefined) {
+      return succeed(
+        onProtected
+          ? `Committed to ${branch}. Push and open a PR when ready.`
+          : `Committed to ${currentBranch}.`,
+      )
+    }
+
+    await deps.git.push(branch)
+
+    logStep('Opening PR')
+    const url = await opener.create(message, body)
+
+    return succeed(`Synced: ${url}`)
+  } catch (error) {
+    logError(error instanceof Error ? error.message : String(error))
+    outro()
+    return 1
+  }
+}
+
+function promptChoice(canOpenPullRequest: boolean): Promise<WorkflowChoice> {
+  return select({
+    message: 'Review changes, then?',
+    options: [
+      ...(canOpenPullRequest
+        ? [{ value: 'pr' as const, label: 'Commit and open PR' }]
+        : []),
+      { value: 'commit' as const, label: 'Commit only' },
+      { value: 'cancel' as const, label: 'Cancel' },
+    ],
+  })
+}
+
+function succeed(message: string): number {
+  outro()
+  process.stderr.write(`\n${GREEN}✓ ${message}${NC}\n`)
+  return 0
+}

package/src/target.ts

@@ -0,0 +1,43 @@
+import { statSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { logError, outro } from '@/ui'
+
+export function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Stands in for `validate_target` plus `guard_root`. The bash `guard_root` read
+ * as a toolkit-root check, but its body was `cd "$target" && pwd`, so it also
+ * rejected a target that does not exist. Porting the name alone would let a
+ * typo'd path scaffold a whole new tree, since every apply step creates parents.
+ *
+ * Returns the resolved path, or the exit code the caller should hand back. The
+ * frame is already open by the time this runs, so a rejection closes it.
+ */
+export function resolveTarget(
+  target: string,
+  protectedRoot: string,
+): string | number {
+  const resolved = resolve(target)
+
+  if (!isDirectory(resolved)) {
+    logError(`Target directory not found: ${target}`)
+    outro()
+    return 1
+  }
+
+  if (resolved === protectedRoot) {
+    logError(
+      'Cannot run against toolkit root. Files here are the source of truth.',
+    )
+    outro()
+    return 1
+  }
+
+  return resolved
+}