@erclx/canon 4.0.0

package/src/sync/git.ts

@@ -0,0 +1,225 @@
+import { basename } from 'node:path'
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+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/canon-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,
+          env: gitEnv(),
+          extendEnv: 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
+}
+
+/**
+ * Both seams strip git's repository-resolution variables, since a hook exports
+ * `GIT_DIR` into every process it runs and it beats `-C`. A sync driven from
+ * inside one would otherwise read the hook's repository and, through `mutate`,
+ * commit and push into it.
+ */
+async function read(target: string, args: readonly string[]): Promise<string> {
+  const result = await execa('git', ['-C', target, ...args], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: 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,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+
+  if (result.exitCode !== 0) {
+    throw new GitCommandError(
+      `git ${args[0]} failed: ${result.stderr || result.stdout}`,
+    )
+  }
+
+  if (result.stdout !== '') pipeOutput(result.stdout)
+}

package/src/sync/history.ts

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { sep } from 'node:path'
+import { execaSync } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/** Blob SHA to the newest commit whose post-image for that path held it. */
+export type PathHistory = ReadonlyMap<string, string>
+
+/** Source path relative to the toolkit root, to that path's known blobs. */
+export type HistoryIndex = ReadonlyMap<string, PathHistory>
+
+const EMPTY_BLOB = '0000000000000000000000000000000000000000'
+
+/**
+ * Git's own object name for a file's contents: sha1 over `blob <len>\0` and the
+ * bytes. Computed here rather than shelled out to `git hash-object`, which would
+ * cost a process per file inside the attribution pass.
+ *
+ * A repository normalizing line endings on checkout stores a blob the working
+ * tree never holds, so this returns a name that matches no historical version.
+ * The caller treats an unmatched file as unattributed, which is the safe label.
+ */
+export function gitBlobHash(content: Buffer): string {
+  const header = Buffer.from(`blob ${content.length}\0`, 'utf8')
+  return createHash('sha1').update(header).update(content).digest('hex')
+}
+
+/**
+ * Reads `--raw` log output into blob-to-commit maps, one per path.
+ *
+ * Reverse-chronological input means the first commit naming a blob is the
+ * newest that produced it, so an existing key is never overwritten. Content
+ * reverted and restored therefore reports the recent commit rather than the
+ * original, which is the one an operator can act on.
+ */
+export function parseRawLog(output: string): HistoryIndex {
+  const index = new Map<string, Map<string, string>>()
+  let commit = ''
+
+  for (const line of output.split('\n')) {
+    if (line === '') continue
+
+    if (!line.startsWith(':')) {
+      commit = line.trim()
+      continue
+    }
+
+    const [meta, path] = line.split('\t')
+    if (path === undefined || commit === '') continue
+
+    const blob = meta.trim().split(/\s+/)[3]
+    if (blob === undefined || blob === EMPTY_BLOB) continue
+
+    const blobs = index.get(path) ?? new Map<string, string>()
+    if (!blobs.has(blob)) blobs.set(blob, commit)
+    index.set(path, blobs)
+  }
+
+  return index
+}
+
+/**
+ * Every historical version of the given toolkit-relative paths, or `undefined`
+ * when this toolkit has no history to read. A package installed from the
+ * registry ships source without `.git`, so absence is an ordinary state rather
+ * than a failure, and the caller degrades to the unattributed path.
+ *
+ * Renames are disabled so a raw line always carries exactly one path. Detection
+ * would emit a two-path form that the parser would read as an unknown blob.
+ */
+export function readHistoryIndex(
+  toolkitRoot: string,
+  paths: readonly string[],
+): HistoryIndex | undefined {
+  if (paths.length === 0) return new Map()
+
+  const result = execaSync(
+    'git',
+    [
+      '-C',
+      toolkitRoot,
+      'log',
+      '--all',
+      '--raw',
+      '--no-renames',
+      '--no-abbrev',
+      '--relative',
+      '--format=%H',
+      '--',
+      ...paths.map(toRepoPath),
+    ],
+    { reject: false, env: gitEnv(), extendEnv: false },
+  )
+
+  return result.exitCode === 0 ? parseRawLog(result.stdout) : undefined
+}
+
+/**
+ * Git prints and accepts posix separators on every platform, so a Windows
+ * caller's `relative()` output has to be converted before it can match a path
+ * the log emitted.
+ */
+export function toRepoPath(path: string): string {
+  return path.split(sep).join('/')
+}
+
+/**
+ * The commit whose version of `sourceRel` matches what sits at `installedPath`.
+ * A match proves the file is untouched since it was installed, so the toolkit is
+ * what moved. No match means the content matches nothing this toolkit ever
+ * published, which is a local edit and stays unattributed.
+ */
+export function findInstalledOrigin(
+  index: HistoryIndex,
+  sourceRel: string,
+  installedPath: string,
+): string | undefined {
+  const blobs = index.get(toRepoPath(sourceRel))
+  if (blobs === undefined) return undefined
+
+  return blobs.get(gitBlobHash(readFileSync(installedPath)))
+}

package/src/sync/layout.ts

@@ -0,0 +1,140 @@
+import { existsSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { SUBDIRS } from '@/claude/seeds'
+import type { StampDomain } from '@/sync/stamp'
+
+const CLAUDE_DIR = '.claude'
+
+/**
+ * Domains an older toolkit installed at the project root, each with the source
+ * folder naming what it owns. Governance is absent because its rules have always
+ * landed under `.claude/rules/`, so there is no earlier location to be stranded
+ * at. Standards and snippets are absent because no copy installs into a target
+ * at all now, so a root `standards/` or `snippets/` folder there is the
+ * project's own authoring surface and reporting it as unmigrated would propose
+ * moving files nothing installed.
+ *
+ * A tuple array rather than a partial record, so the domain key stays typed
+ * without asserting an `Object.entries` result back into the union. Empty
+ * now that both former entries retired their install channels. A future
+ * domain installing at a target's root, the way an older toolkit installed
+ * standards and snippets there, would be the next entry to add.
+ */
+const ROOT_LAYOUTS: readonly (readonly [
+  StampDomain,
+  string,
+  (root: string) => string,
+])[] = []
+
+/**
+ * A target file that a shipped seed folder replaced. Carries no source and
+ * queues no change, because the file holds content the project wrote and only
+ * the user can decide where it moves.
+ */
+export interface SupersededEntry {
+  readonly rel: string
+  readonly replacedBy: string
+}
+
+/**
+ * A domain whose files sit at the root layout an older toolkit installed to,
+ * with nothing at the path the current one reads. Distinct from a domain that
+ * was never installed, which has neither.
+ */
+export interface UnmigratedDomain {
+  readonly domain: StampDomain
+  readonly rootPath: string
+  readonly installPath: string
+  /** Root files the toolkit ships under this domain, not every file present. */
+  readonly files: number
+}
+
+/**
+ * Pairs each seed subdirectory against an uppercase-stem sibling in the target,
+ * so a project still holding `.claude/TASKS.md` is reported against the
+ * `.claude/tasks/` folder that replaced it.
+ *
+ * Deriving from the seed tree rather than from a fixed list means a folder
+ * added later is covered without editing this file. The cost is that only an
+ * exact stem matches, so a suffixed variant such as `TASKS-ARCHIVE.md` is not
+ * reported.
+ */
+export function collectSuperseded(target: string): SupersededEntry[] {
+  const entries: SupersededEntry[] = []
+
+  for (const subdir of SUBDIRS) {
+    const rel = join(CLAUDE_DIR, `${subdir.toUpperCase()}.md`)
+    if (!isFile(join(target, rel))) continue
+
+    entries.push({ rel, replacedBy: join(CLAUDE_DIR, subdir) })
+  }
+
+  return entries
+}
+
+/**
+ * Domains the target holds at the root rather than under `.claude/`. Reported
+ * separately from the per-domain scan because that scan lists only domains it
+ * finds installed, so an unmigrated project would otherwise read as one that
+ * never installed the domain at all.
+ *
+ * A root folder is claimed only when it holds a file the toolkit ships under
+ * that domain. Presence of the folder alone is not evidence: a project can
+ * carry its own `snippets/` of prompts it wrote and never have installed the
+ * domain, and calling that unmigrated would fail `--exit-code` with no action
+ * that clears it.
+ */
+export function detectUnmigrated(
+  toolkitRoot: string,
+  target: string,
+): UnmigratedDomain[] {
+  const found: UnmigratedDomain[] = []
+
+  for (const [domain, rootPath, sourceDir] of ROOT_LAYOUTS) {
+    const installPath = join(CLAUDE_DIR, rootPath)
+    if (isDirectoryWithFiles(join(target, installPath))) continue
+
+    const files = countToolkitOwned(
+      join(target, rootPath),
+      sourceDir(toolkitRoot),
+    )
+    if (files === 0) continue
+
+    found.push({ domain, rootPath, installPath, files })
+  }
+
+  return found
+}
+
+/**
+ * Root files whose basename matches something the toolkit ships for this domain.
+ * Basenames rather than relative paths, because the root layout an older toolkit
+ * wrote is flat while the source nests by category, and the question here is only
+ * whether any file is toolkit-owned rather than which source each one came from.
+ */
+function countToolkitOwned(dir: string, sourceDir: string): number {
+  const owned = new Set(listMarkdown(sourceDir).map((rel) => basename(rel)))
+  if (owned.size === 0) return 0
+
+  return listMarkdown(dir).filter((rel) => owned.has(basename(rel))).length
+}
+
+function isFile(path: string): boolean {
+  return existsSync(path) && statSync(path).isFile()
+}
+
+function isDirectoryWithFiles(path: string): boolean {
+  return listMarkdown(path).length > 0
+}
+
+function listMarkdown(dir: string): string[] {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return []
+
+  return [
+    ...new Bun.Glob('**/*.md').scanSync({
+      cwd: dir,
+      onlyFiles: true,
+      dot: true,
+    }),
+  ]
+}