infra-kit 0.1.114 → 0.1.115

package/src/lib/vendor/manifest.ts

@@ -0,0 +1,151 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { z } from 'zod'
+
+import { sha256 } from './hash'
+import { walkVendorTree } from './walk'
+
+/** Filename of the integrity manifest inside a `vendor/` tree. */
+export const MANIFEST_FILE = '.sync-manifest.json'
+
+/**
+ * Manifest schema version the CLI understands. A manifest with a HIGHER version
+ * than this was written by a newer CLI and is treated as drift (fail-closed) —
+ * see {@link isUnknownSchema}. Legacy manifests carry no `schemaVersion` field
+ * and read as compatible.
+ */
+export const CURRENT_SCHEMA_VERSION = 1
+
+/**
+ * `schemaVersion` is OPTIONAL with no default: legacy manifests written by
+ * `writeVendorMeta` have no such field, and a required field would make
+ * `vendor check` fail-closed on every existing manifest. Absent is read as
+ * "compatible" (current). `writeManifest` always emits the current version.
+ */
+const manifestSchema = z.object({
+  schemaVersion: z.number().optional(),
+  source: z.string(),
+  commit: z.string(),
+  syncedAt: z.string(),
+  fileCount: z.number(),
+  files: z.record(z.string(), z.string()),
+})
+
+export type VendorManifest = z.infer<typeof manifestSchema>
+
+export interface ManifestDiff {
+  modified: string[]
+  added: string[]
+  removed: string[]
+}
+
+/**
+ * Whether a manifest's `schemaVersion` is newer than this CLI supports. Absent
+ * (legacy) reads as compatible; only a strictly-greater version is unknown.
+ */
+export const isUnknownSchema = (manifest: VendorManifest): boolean => {
+  return (manifest.schemaVersion ?? CURRENT_SCHEMA_VERSION) > CURRENT_SCHEMA_VERSION
+}
+
+/**
+ * Walk the vendor tree and hash every file into a `{ relativePath: sha256 }`
+ * map (sorted by walk order → stable). A file that cannot be read (e.g. a
+ * dangling symlink) surfaces an explicit error rather than crashing with a raw
+ * fs stack.
+ */
+export const buildFilesMap = (vendorRoot: string): Record<string, string> => {
+  const files: Record<string, string> = {}
+
+  for (const rel of walkVendorTree(vendorRoot)) {
+    try {
+      files[rel] = sha256(path.join(vendorRoot, rel))
+    } catch (cause) {
+      const reason = cause instanceof Error ? cause.message : String(cause)
+
+      throw new Error(`Cannot hash vendor file "${rel}" (broken symlink or unreadable file): ${reason}`)
+    }
+  }
+
+  return files
+}
+
+/**
+ * Read and validate the manifest at `<vendorRoot>/.sync-manifest.json`. Throws a
+ * descriptive error if the file is missing or malformed.
+ */
+export const readManifest = (vendorRoot: string): VendorManifest => {
+  const manifestPath = path.join(vendorRoot, MANIFEST_FILE)
+
+  let raw: string
+
+  try {
+    raw = readFileSync(manifestPath, 'utf8')
+  } catch {
+    throw new Error(`Missing ${MANIFEST_FILE} at ${manifestPath}`)
+  }
+
+  const parsed = manifestSchema.safeParse(JSON.parse(raw))
+
+  if (!parsed.success) {
+    throw new Error(`Invalid ${MANIFEST_FILE} at ${manifestPath}: ${z.prettifyError(parsed.error)}`)
+  }
+
+  return parsed.data
+}
+
+/**
+ * Build and write a fresh manifest for the current content of `vendorRoot`.
+ * Emits the CURRENT schema version, the supplied `source`/`commit`, an ISO
+ * `syncedAt`, and the per-file checksum map. Returns the written manifest.
+ *
+ * The `files` map and field set (minus `schemaVersion`) match legacy
+ * `writeVendorMeta`, so a regenerated manifest differs from a legacy one only by
+ * the added `schemaVersion` and the `syncedAt` timestamp.
+ */
+export const writeManifest = (vendorRoot: string, meta: { source: string; commit: string }): VendorManifest => {
+  const files = buildFilesMap(vendorRoot)
+
+  const manifest: VendorManifest = {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    source: meta.source,
+    commit: meta.commit,
+    syncedAt: new Date().toISOString(),
+    fileCount: Object.keys(files).length,
+    files,
+  }
+
+  writeFileSync(path.join(vendorRoot, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`)
+
+  return manifest
+}
+
+/**
+ * Compare the live `vendorRoot` tree against a manifest's recorded checksums.
+ * Returns the modified / added (present, not in manifest) / removed (in
+ * manifest, now missing) relative paths.
+ */
+export const compareToManifest = (vendorRoot: string, manifest: VendorManifest): ManifestDiff => {
+  const expected = manifest.files
+  const actualFiles = walkVendorTree(vendorRoot)
+
+  const modified: string[] = []
+  const added: string[] = []
+
+  for (const rel of actualFiles) {
+    if (!(rel in expected)) {
+      added.push(rel)
+      continue
+    }
+
+    if (sha256(path.join(vendorRoot, rel)) !== expected[rel]) {
+      modified.push(rel)
+    }
+  }
+
+  const actualSet = new Set(actualFiles)
+  const removed = Object.keys(expected).filter((rel) => {
+    return !actualSet.has(rel)
+  })
+
+  return { modified, added, removed }
+}

package/src/lib/vendor/skip-sets.ts

@@ -0,0 +1,48 @@
+/**
+ * Skip rules for walking a `vendor/` tree to build or verify its integrity
+ * manifest. This is the SINGLE source of truth consumed by both the read path
+ * (`vendor check`) and the write path (`vendor sync`/`manifest`).
+ *
+ * The set below is a strict superset of the legacy read script's
+ * `MANIFEST_SKIP_DIRS` (`scripts/vendor-check.mjs`). It additionally skips
+ * `.vitest-attachments` — a git-ignored directory (see repo `.gitignore`) that
+ * therefore never appears in a committed vendor tree. Widening the read path's
+ * skip set this way is deliberate and behavior-preserving: no existing manifest
+ * changes, and the read and write paths share this single set so they cannot
+ * diverge.
+ */
+/** Root of the mirrored tree inside each repo. Single source for read + write paths. */
+export const VENDOR_DIR = 'vendor'
+
+export const MANIFEST_SKIP_DIRS: ReadonlySet<string> = new Set([
+  'node_modules',
+  'dist',
+  '.turbo',
+  '.omc',
+  '__screenshots__',
+  '.vitest-attachments',
+  '.output',
+  '.source',
+  '.nitro',
+  '.tanstack',
+])
+
+export const MANIFEST_SKIP_FILES: ReadonlySet<string> = new Set(['.sync-manifest.json', '.eslintcache', 'log.txt'])
+
+export const MANIFEST_SKIP_SUFFIXES: readonly string[] = ['.tsbuildinfo']
+
+/** Whether a directory name should be skipped when walking the vendor tree. */
+export const isSkippedDir = (name: string): boolean => {
+  return MANIFEST_SKIP_DIRS.has(name)
+}
+
+/** Whether a file name should be skipped when walking the vendor tree. */
+export const isSkippedFile = (name: string): boolean => {
+  if (MANIFEST_SKIP_FILES.has(name)) {
+    return true
+  }
+
+  return MANIFEST_SKIP_SUFFIXES.some((suffix) => {
+    return name.endsWith(suffix)
+  })
+}

package/src/lib/vendor/sync-ops.ts

@@ -0,0 +1,290 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { $ } from 'zx'
+
+import { OperationError } from 'src/lib/errors/operation-error'
+
+import type { VendorConfig } from './config-schema'
+import { expandTilde } from './factory-config'
+import { writeManifest } from './manifest'
+import { VENDOR_DIR } from './skip-sets'
+
+/**
+ * Write-path operations for `vendor sync`/`manifest`/`diff`. This module imports
+ * `zx` at the top level and is NEVER re-exported from the read-path barrel
+ * (`./index.ts`); `vendor check` never imports it, so its runtime path stays
+ * free of `zx`/rsync.
+ */
+
+/** rsync excludes mirrored from the legacy sync script. */
+const EXCLUDE_PATTERNS = [
+  'node_modules',
+  'dist',
+  '*.tsbuildinfo',
+  '.turbo',
+  '.eslintcache',
+  '.omc',
+  '__screenshots__',
+  '.vitest-attachments',
+  '.output',
+  '.source',
+  '.nitro',
+  '.tanstack',
+  'log.txt',
+]
+
+const VENDOR_README = `# vendor/ — mirrored from the source repo
+
+**DO NOT EDIT files in this folder here.**
+
+Everything under \`vendor/\` is the single source of truth maintained in the source
+repo and copied into this repo by \`infra-kit vendor sync\`. Local edits are
+overwritten on the next sync and will fail \`infra-kit vendor check\` in CI.
+
+To change a vendored package, edit it in the source repo and re-run the sync.
+
+See \`.sync-manifest.json\` for the source commit and per-file checksums.
+`
+
+const excludeFlags = (): string[] => {
+  return EXCLUDE_PATTERNS.map((pattern) => {
+    return `--exclude=${pattern}`
+  })
+}
+
+/** Resolve the source repo's current HEAD commit (or `unknown` if unavailable). */
+export const getSourceCommit = async (sourceRoot: string): Promise<string> => {
+  try {
+    const result = await $({ cwd: sourceRoot })`git rev-parse HEAD`
+
+    return result.stdout.trim()
+  } catch {
+    return 'unknown'
+  }
+}
+
+/** rsync a directory source→target (target is replaced to avoid nested copies). */
+export const copyDirectory = async (source: string, target: string): Promise<boolean> => {
+  if (!existsSync(source)) {
+    return false
+  }
+
+  if (existsSync(target)) {
+    await $`rm -rf ${target}`
+  }
+
+  const sourceSlash = `${source}/`
+  const targetSlash = `${target}/`
+
+  await $`rsync -a ${excludeFlags()} ${sourceSlash} ${targetSlash}`
+
+  return true
+}
+
+/** Copy a single file source→target, creating the target dir as needed. */
+export const copyFile = async (source: string, target: string): Promise<boolean> => {
+  if (!existsSync(source)) {
+    return false
+  }
+
+  const targetDir = path.dirname(target)
+
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true })
+  }
+
+  await $`cp ${source} ${target}`
+
+  return true
+}
+
+/**
+ * Dry-run rsync reporting whether `target` has drifted from `source`. Returns the
+ * itemized change list (empty = in sync). `--delete` surfaces consumer-only files.
+ */
+export const diffDirectory = async (source: string, target: string): Promise<string[]> => {
+  if (!existsSync(source)) {
+    return []
+  }
+
+  if (!existsSync(target)) {
+    return [`missing target: ${target}`]
+  }
+
+  const sourceSlash = `${source}/`
+  const targetSlash = `${target}/`
+  const result = await $`rsync -ai --dry-run --delete ${excludeFlags()} ${sourceSlash} ${targetSlash}`
+
+  return result.stdout
+    .split('\n')
+    .map((line) => {
+      return line.trim()
+    })
+    .filter(Boolean)
+}
+
+/**
+ * Write `vendor/README.md` + `vendor/.sync-manifest.json` for a target repo,
+ * mirroring the legacy `writeVendorMeta`. The manifest `files` map matches legacy
+ * output; it differs only by the added `schemaVersion` and the `syncedAt` stamp.
+ */
+export const writeVendorMeta = (targetRoot: string, meta: { source: string; commit: string }): void => {
+  const vendorRoot = path.join(targetRoot, VENDOR_DIR)
+
+  if (!existsSync(vendorRoot)) {
+    return
+  }
+
+  writeFileSync(path.join(vendorRoot, 'README.md'), VENDOR_README)
+  writeManifest(vendorRoot, meta)
+}
+
+/**
+ * Resolve a target repo name to its absolute root under the machine-local
+ * `workspaceDir` (from `~/.infra-kit/vendor.json`). Replaces the old
+ * "siblings of the source repo" assumption — the working dir is now explicit.
+ */
+export const resolveTargetRoot = (workspaceDir: string, repo: string): string => {
+  return path.join(expandTilde(workspaceDir), repo)
+}
+
+/** Narrow the configured target list to an optional `--repos` allowlist. */
+export const selectTargets = (allTargets: string[], repos?: string[]): string[] => {
+  if (!repos) {
+    return allTargets
+  }
+
+  return allTargets.filter((repo) => {
+    return repos.includes(repo)
+  })
+}
+
+export interface VendorSyncResult {
+  source: string
+  commit: string
+  repos: { repo: string; copied: number; total: number; skipped: boolean }[]
+}
+
+/**
+ * Defense-in-depth path-traversal guard: throw if `child` resolves outside
+ * `root`. The schema's `safeRelPath` already rejects `..`/absolute segments at
+ * load time; this re-checks the resolved absolute paths so a symlink or odd join
+ * can never escape the source/target repo root.
+ */
+const assertContained = (root: string, child: string, label: string, rel: string, itemName: string): void => {
+  const resolvedRoot = path.resolve(root)
+  const resolved = path.resolve(child)
+
+  if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) {
+    throw new OperationError(undefined, {
+      operation: `sync vendor item ${itemName}`,
+      stderrExcerpt: `${label} escapes repo root: ${rel}`,
+    })
+  }
+}
+
+/** Copy every configured item into each existing target, then write its manifest. */
+export const runSync = async (
+  config: VendorConfig,
+  sourceRoot: string,
+  workspaceDir: string,
+  targets: string[],
+  meta: { source: string; commit: string },
+): Promise<VendorSyncResult> => {
+  const repos: VendorSyncResult['repos'] = []
+
+  for (const repo of targets) {
+    const targetRoot = resolveTargetRoot(workspaceDir, repo)
+
+    if (!existsSync(targetRoot)) {
+      repos.push({ repo, copied: 0, total: config.copy.length, skipped: true })
+      continue
+    }
+
+    let copied = 0
+
+    for (const item of config.copy) {
+      const source = path.join(sourceRoot, item.source)
+      const target = path.join(targetRoot, item.target)
+
+      assertContained(sourceRoot, source, 'source', item.source, item.name)
+      assertContained(targetRoot, target, 'target', item.target, item.name)
+
+      const ok = item.type === 'directory' ? await copyDirectory(source, target) : await copyFile(source, target)
+
+      if (ok) {
+        copied++
+      }
+    }
+
+    writeVendorMeta(targetRoot, meta)
+    repos.push({ repo, copied, total: config.copy.length, skipped: false })
+  }
+
+  return { source: meta.source, commit: meta.commit, repos }
+}
+
+/**
+ * Regenerate the manifest+README in each existing target without copying. Needs
+ * neither the source `config` (no `copy[]` involved) nor `sourceRoot` (it writes
+ * only into targets) — just where the targets live and which ones.
+ */
+export const runManifest = async (
+  workspaceDir: string,
+  targets: string[],
+  meta: { source: string; commit: string },
+): Promise<{ repo: string; skipped: boolean }[]> => {
+  const repos: { repo: string; skipped: boolean }[] = []
+
+  for (const repo of targets) {
+    const targetRoot = resolveTargetRoot(workspaceDir, repo)
+    const skipped = !existsSync(targetRoot)
+
+    if (!skipped) {
+      writeVendorMeta(targetRoot, meta)
+    }
+
+    repos.push({ repo, skipped })
+  }
+
+  return repos
+}
+
+export interface VendorDiffEntry {
+  repo: string
+  target: string
+  changes: string[]
+}
+
+/** Source-aware drift across every `vendored:true` item in each target. */
+export const runDiff = async (
+  config: VendorConfig,
+  sourceRoot: string,
+  workspaceDir: string,
+  targets: string[],
+): Promise<VendorDiffEntry[]> => {
+  const entries: VendorDiffEntry[] = []
+  const vendoredItems = config.copy.filter((item) => {
+    return item.vendored === true
+  })
+
+  for (const repo of targets) {
+    const targetRoot = resolveTargetRoot(workspaceDir, repo)
+
+    if (!existsSync(targetRoot)) {
+      continue
+    }
+
+    for (const item of vendoredItems) {
+      const source = path.join(sourceRoot, item.source)
+      const target = path.join(targetRoot, item.target)
+      const changes = await diffDirectory(source, target)
+
+      if (changes.length > 0) {
+        entries.push({ repo, target: item.target, changes })
+      }
+    }
+  }
+
+  return entries
+}

package/src/lib/vendor/walk.ts

@@ -0,0 +1,56 @@
+import { readdirSync } from 'node:fs'
+import path from 'node:path'
+
+import { isSkippedDir, isSkippedFile } from './skip-sets'
+
+/**
+ * Convert a (possibly Windows) relative path to a POSIX-normalized form so the
+ * manifest is byte-identical across operating systems.
+ */
+const toPosix = (relativePath: string): string => {
+  return relativePath.split(path.sep).join('/')
+}
+
+/**
+ * Walk a `vendor/` tree and return the relative paths of every non-skipped file,
+ * POSIX-normalized and sorted byte-wise. The sort makes the output independent
+ * of `readdirSync` order, which keeps generated manifests deterministic.
+ *
+ * Symlink handling matches the legacy scripts: only REAL directories
+ * (`entry.isDirectory()`) are recursed; a symlink is treated as a leaf and its
+ * relative path is emitted, to be hashed later by following it to target
+ * content (`sha256`/`readFileSync`). This preserves legacy behavior exactly —
+ * the manifest checksum reflects target content, never the link itself.
+ *
+ * @example
+ * walkVendorTree('/repo/vendor')
+ * // => ['README.md', 'configs/eslint-config/index.js', ...]
+ */
+export const walkVendorTree = (vendorRoot: string): string[] => {
+  const acc: string[] = []
+
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        if (isSkippedDir(entry.name)) {
+          continue
+        }
+
+        walk(full)
+        continue
+      }
+
+      if (isSkippedFile(entry.name)) {
+        continue
+      }
+
+      acc.push(toPosix(path.relative(vendorRoot, full)))
+    }
+  }
+
+  walk(vendorRoot)
+
+  return acc.sort()
+}

package/src/mcp/tools/index.ts

@@ -1,50 +1,13 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 
-import { auditMcpTool } from 'src/commands/audit'
-import { envClearMcpTool } from 'src/commands/env-clear'
-import { envListMcpTool } from 'src/commands/env-list'
-import { envLoadMcpTool } from 'src/commands/env-load'
-import { envStatusMcpTool } from 'src/commands/env-status'
-import { ghMergeDevMcpTool } from 'src/commands/gh-merge-dev'
-import { ghReleaseDeliverMcpTool } from 'src/commands/gh-release-deliver'
-import { ghReleaseDeployAllMcpTool } from 'src/commands/gh-release-deploy-all'
-import { ghReleaseDeploySelectedMcpTool } from 'src/commands/gh-release-deploy-selected'
-import { ghReleaseListMcpTool } from 'src/commands/gh-release-list'
-import { releaseCreateMcpTool } from 'src/commands/release-create'
-import { releaseDescEditMcpTool } from 'src/commands/release-desc-edit'
-import { versionMcpTool } from 'src/commands/version'
-import { worktreesAddMcpTool } from 'src/commands/worktrees-add'
-import { worktreesListMcpTool } from 'src/commands/worktrees-list'
-import { worktreesOpenMcpTool } from 'src/commands/worktrees-open'
-import { worktreesReloadMcpTool } from 'src/commands/worktrees-reload'
-import { worktreesRemoveMcpTool } from 'src/commands/worktrees-remove'
-import { worktreesSyncMcpTool } from 'src/commands/worktrees-sync'
+import { getExposedMcpTools } from 'src/lib/command-catalog'
 import { createToolHandler } from 'src/lib/tool-handler'
 
-const tools = [
-  envStatusMcpTool,
-  envListMcpTool,
-  envLoadMcpTool,
-  envClearMcpTool,
-  ghMergeDevMcpTool,
-  releaseCreateMcpTool,
-  releaseDescEditMcpTool,
-  ghReleaseDeliverMcpTool,
-  ghReleaseDeployAllMcpTool,
-  ghReleaseDeploySelectedMcpTool,
-  ghReleaseListMcpTool,
-  auditMcpTool,
-  versionMcpTool,
-  worktreesAddMcpTool,
-  worktreesListMcpTool,
-  worktreesOpenMcpTool,
-  worktreesReloadMcpTool,
-  worktreesRemoveMcpTool,
-  worktreesSyncMcpTool,
-]
-
 export const initializeTools = async (server: McpServer) => {
-  for (const tool of tools) {
+  // The registered tool set is derived from the single command catalog, filtered
+  // by its explicit `mcpExposed` allowlist. doctor / vendor-sync / vendor-manifest
+  // are intentionally excluded there and must never be registered here.
+  for (const tool of getExposedMcpTools()) {
     server.registerTool(
       tool.name,
       {

package/src/sanity.test.tsx

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 
 describe('sanity check', () => {
   it('should be testable', () => {
+    // eslint-disable-next-line sonarjs/no-trivial-assertions -- intentional test-runner sanity check
     expect(1 + 1).toBe(2)
   })
 })

package/src/tui/__tests__/no-react-boundary.test.ts

@@ -0,0 +1,51 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+// Guard the "no React on machine paths" invariant at the source level (the
+// ESLint no-restricted-imports rule enforces it during lint; this asserts it in
+// the test suite too, and documents the boundary). Only STATIC imports are
+// forbidden — the TTY branch reaches the TUI via a dynamic `import('src/tui/boot')`.
+
+const SRC_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+
+const MACHINE_PATH_FILES = ['entry/cli.ts', 'entry/mcp.ts']
+
+/** Extract the module specifier from each `import ... from '<spec>'` line. */
+const staticImportSpecifiers = (source: string): string[] => {
+  return source.split('\n').flatMap((line) => {
+    const match = /^\s*import\s.+from\s+['"]([^'"]+)['"]/.exec(line)
+
+    return match?.[1] ? [match[1]] : []
+  })
+}
+
+/** A specifier that would pull React/Ink onto a machine path if imported statically. */
+const isForbidden = (specifier: string): boolean => {
+  if (specifier === 'ink' || specifier === 'react' || specifier.startsWith('react/')) {
+    return true
+  }
+
+  return (
+    specifier === 'tui' || specifier.endsWith('/tui') || specifier.includes('/tui/') || specifier.startsWith('src/tui')
+  )
+}
+
+describe('no-React boundary', () => {
+  it.each(MACHINE_PATH_FILES)('%s does not statically import ink/react/tui', (relative) => {
+    const source = fs.readFileSync(path.join(SRC_DIR, relative), 'utf-8')
+
+    for (const specifier of staticImportSpecifiers(source)) {
+      expect(isForbidden(specifier), `forbidden static import in ${relative}: ${specifier}`).toBe(false)
+    }
+  })
+
+  it('entry/cli.ts reaches the TUI only via a dynamic import', () => {
+    const source = fs.readFileSync(path.join(SRC_DIR, 'entry/cli.ts'), 'utf-8')
+
+    // The dynamic import is how the palette is loaded; it must be present and
+    // must be a dynamic import() call, never a static `import ... from`.
+    expect(source).toMatch(/import\(\s*['"]src\/tui\/boot['"]\s*\)/)
+  })
+})