@erclx/canon 4.0.0

package/src/sync/stamp.ts

@@ -0,0 +1,358 @@
+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'
+import { recordTarget } from '@/targets/registry'
+
+/**
+ * Domains the stamp can record. Governance attributes file by file through the
+ * sync engine. Tooling runs its own inject and manifest machinery, so it
+ * records the stack chain it resolved instead and carries no file hashes.
+ *
+ * A stamp written before the standards or snippets install channel closed
+ * still carries a `standards` or `snippets` record. `isStamp` ignores the key
+ * and `sortDomains` drops it on the next write, so the target loses a domain
+ * nothing can refresh rather than losing the whole file.
+ */
+export const STAMP_DOMAINS = ['governance', 'tooling'] 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
+  /**
+   * Stack names the install resolved. Tooling records the full ancestor chain,
+   * nearest stack first, because a stack that extends another cannot be
+   * reinstalled from its leaf alone, and a `--skip` run installs fewer layers
+   * than the leaf's own chain would reproduce. Governance records the single
+   * stack `canon gov install` was given, since `resolveRules` walks its
+   * ancestors internally and a reader needs only the leaf to ask it again.
+   */
+  readonly chain?: readonly string[]
+}
+
+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', 'canon', 'config.json')
+}
+
+/**
+ * Where `106115ba` moved the stamp from. No migration shipped with that move,
+ * so a target stamped before it still carries its config here, and `readStamp`
+ * falls back to this path when the current one is absent.
+ *
+ * The old tool name is deliberate and this path never renames. It names what a
+ * target already has on disk, so rewriting it to the current spelling would
+ * point the fallback at a file that has never existed anywhere.
+ */
+export function legacyStampPath(target: string): string {
+  // canon-keep-retired
+  return join(target, '.claude', 'aitk.json')
+}
+
+/**
+ * The stamp folder under the retired tool name, which is where every target
+ * stamped between `106115ba` and the rename carries its config. Retired for
+ * the same reason as the path above and kept readable on the same terms.
+ */
+export function retiredNameStampPath(target: string): string {
+  // canon-keep-retired
+  return join(target, '.claude', 'aitk', 'config.json')
+}
+
+/**
+ * Every spelling a stamp has been written under, current first. The order is
+ * the read order, so a target carrying more than one resolves to the newest.
+ *
+ * The fallback carries no end date. It costs two path reads on a command that
+ * already touches the filesystem, and dropping it later is a second breaking
+ * change aimed at exactly the targets that were slowest to migrate the first
+ * time.
+ */
+export function stampPaths(target: string): readonly string[] {
+  return [
+    stampPath(target),
+    retiredNameStampPath(target),
+    legacyStampPath(target),
+  ]
+}
+
+/**
+ * Whether `readStamp` would resolve to a retired path, so a caller can report
+ * that a target's config still sits at one. False when no path exists, since
+ * there is nothing to migrate off of.
+ */
+export function isLegacyStamped(target: string): boolean {
+  if (existsSync(stampPath(target))) return false
+  return (
+    existsSync(retiredNameStampPath(target)) ||
+    existsSync(legacyStampPath(target))
+  )
+}
+
+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.
+ *
+ * Falls back to the retired path only when the current one does not exist,
+ * read only: nothing here migrates a target's config as a side effect of a
+ * report. The check is existence rather than a successful parse, so a
+ * corrupt current stamp reads as absent rather than silently serving the
+ * retired one beside it. `isLegacyStamped` tests the same existence check,
+ * which is what keeps the two agreeing on which path a corrupt current file
+ * was read from.
+ */
+export function readStamp(target: string): Stamp | undefined {
+  const found = stampPaths(target).find((path) => existsSync(path))
+  return found === undefined ? undefined : readStampFile(found)
+}
+
+function readStampFile(path: string): Stamp | undefined {
+  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 ?? {}
+}
+
+/**
+ * The stack chain a domain's install last recorded. An empty result is the
+ * state every target predating that domain's chain recording sits in, and a
+ * reader treats it as unmeasured rather than as clean.
+ */
+export function stampedChain(
+  stamp: Stamp | undefined,
+  domain: StampDomain,
+): readonly string[] {
+  return stamp?.domains[domain]?.chain ?? []
+}
+
+/**
+ * Replaces one domain's file hashes and leaves the others, including that
+ * domain's own chain, untouched. Domains install and sync independently but
+ * share the one file, and a chain an install recorded is a separate fact a
+ * later file-only sync must not erase.
+ */
+export async function writeStamp(
+  target: string,
+  source: StampSource,
+  hashes: DomainHashes,
+  now: Date,
+): Promise<void> {
+  await putDomain(target, source, { files: sortKeys(hashes) }, now)
+}
+
+/**
+ * Records the stack chain an install resolved and leaves that domain's file
+ * hashes untouched. Tooling calls this with no files ever recorded, since
+ * `src/tooling/` never runs the sync engine and the chain is its whole record.
+ * Governance calls it alongside `writeStamp`, since it records both.
+ */
+export async function writeChainStamp(
+  target: string,
+  source: StampSource,
+  chain: readonly string[],
+  now: Date,
+): Promise<void> {
+  await putDomain(target, source, { chain: [...chain] }, now)
+}
+
+async function putDomain(
+  target: string,
+  source: StampSource,
+  payload: Partial<Pick<DomainStamp, 'files' | 'chain'>>,
+  now: Date,
+): Promise<void> {
+  const previous = readStamp(target)
+  const previousRecord = previous?.domains[source.domain]
+  const commit = await toolkitCommit(source.toolkitRoot)
+
+  const record: DomainStamp = {
+    ...(commit === undefined ? {} : { commit }),
+    syncedAt: now.toISOString(),
+    files: payload.files ?? previousRecord?.files ?? {},
+    ...resolveChainField(payload.chain, previousRecord?.chain),
+  }
+
+  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`)
+
+  // Every install and sync that stamps a target passes through here, which is
+  // what makes this the one place the machine-level index can be kept without
+  // each command remembering to. Its outcome is dropped rather than reported:
+  // the stamp just written is the authoritative record of this install, the
+  // index is a cache over every such stamp, and a state folder nobody can
+  // write is not a reason to fail a sync that already landed its files.
+  recordTarget(target, now)
+}
+
+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
+}
+
+/**
+ * A write naming no chain keeps the domain's previous one rather than dropping
+ * it, since `writeStamp` and `writeChainStamp` each touch one half of a
+ * governance record and neither should erase what the other wrote.
+ */
+function resolveChainField(
+  chain: readonly string[] | undefined,
+  previous: readonly string[] | undefined,
+): Pick<DomainStamp, 'chain'> {
+  const resolved = chain ?? previous
+  return resolved === undefined ? {} : { chain: resolved }
+}
+
+/** 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 recognized 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.
+ *
+ * A key naming no current domain is ignored rather than failing the parse. A
+ * target stamped before the standards install channel closed carries one, and
+ * rejecting the file would read as unstamped and then drop the three records it
+ * does carry on the next write. `sortDomains` retires the key at that write.
+ */
+function isStamp(value: unknown): value is Stamp {
+  if (!isRecord(value) || !isRecord(value.domains)) return false
+
+  return Object.entries(value.domains)
+    .filter(([domain]) => (STAMP_DOMAINS as readonly string[]).includes(domain))
+    .every(([, record]) => isDomainStamp(record))
+}
+
+/**
+ * `chain` is optional, which is what keeps a stamp written before tooling
+ * joined the domains readable rather than parsing as corrupt and discarding
+ * the three records it does carry.
+ */
+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
+  }
+  if (value.chain !== undefined && !isStringArray(value.chain)) return false
+
+  return Object.values(value.files).every((hash) => typeof hash === 'string')
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === '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,70 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { isDirectory } from '@/target'
+
+export const SYNC_DOMAINS = ['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> = {
+  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 `canon claude sync` writes.
+ */
+const DOMAIN_PATHS: Record<SyncDomain, readonly string[]> = {
+  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,200 @@
+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,
+  palette,
+  pipeOutput,
+  select,
+} from '@/ui'
+
+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 `CANON_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('canon 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 {
+  const { GREEN, NC } = palette(process.stderr)
+  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
+}