infra-kit 0.1.113 → 0.1.115

package/src/lib/vendor/__tests__/config-schema.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+
+import { vendorCopyItemSchema } from '../config-schema'
+
+const base = { name: 'Configs', type: 'directory' as const }
+
+describe('vendorCopyItemSchema — safeRelPath containment', () => {
+  it('accepts a normal repo-relative path', () => {
+    const result = vendorCopyItemSchema.safeParse({ ...base, source: 'vendor/configs', target: 'vendor/configs' })
+
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects a target that escapes the repo root with ".."', () => {
+    const result = vendorCopyItemSchema.safeParse({ ...base, source: 'vendor/configs', target: '../escape' })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects an absolute source path', () => {
+    const result = vendorCopyItemSchema.safeParse({ ...base, source: '/etc/passwd', target: 'vendor/configs' })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects an empty path', () => {
+    const result = vendorCopyItemSchema.safeParse({ ...base, source: '', target: 'vendor/configs' })
+
+    expect(result.success).toBe(false)
+  })
+})

package/src/lib/vendor/__tests__/config.test.ts

@@ -0,0 +1,63 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { defineVendorConfig, loadVendorConfig } from '../config'
+
+let root: string
+
+const writeConfig = (body: string): void => {
+  fs.writeFileSync(path.join(root, 'vendor.config.ts'), body, 'utf8')
+}
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'vendor-config-test-'))
+})
+
+afterEach(() => {
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+describe('defineVendorConfig', () => {
+  it('is an identity helper', () => {
+    const config = { copy: [] }
+
+    expect(defineVendorConfig(config)).toBe(config)
+  })
+})
+
+describe('loadVendorConfig', () => {
+  it('loads an object default export', async () => {
+    writeConfig(
+      `export default { copy: [{ name: 'Configs', source: 'vendor/configs', target: 'vendor/configs', type: 'directory', vendored: true }] }`,
+    )
+
+    const config = await loadVendorConfig(root)
+
+    expect(config.copy[0]?.name).toBe('Configs')
+    expect(config.copy[0]?.vendored).toBe(true)
+  })
+
+  it('loads a factory (function) default export', async () => {
+    writeConfig(`export default () => ({ copy: [] })`)
+
+    const config = await loadVendorConfig(root)
+
+    expect(config.copy).toEqual([])
+  })
+
+  it('throws on a missing config file', async () => {
+    await expect(loadVendorConfig(root)).rejects.toThrow(/vendor\.config\.ts not found/)
+  })
+
+  it('throws on a schema-invalid config', async () => {
+    writeConfig(`export default { copy: 'not-an-array' }`)
+    await expect(loadVendorConfig(root)).rejects.toThrow(/Invalid vendor\.config\.ts/)
+  })
+
+  it('rejects a stray `targets` key (now machine-local, not in the source config)', async () => {
+    writeConfig(`export default { targets: ['travelist-monorepo'], copy: [] }`)
+    await expect(loadVendorConfig(root)).rejects.toThrow(/Invalid vendor\.config\.ts/)
+  })
+})

package/src/lib/vendor/__tests__/factory-config.test.ts

@@ -0,0 +1,92 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { expandTilde, getFactoryConfigPath, loadFactoryConfig } from '../factory-config'
+
+let home: string
+let configDir: string
+let configPath: string
+
+const writeConfig = (body: string): void => {
+  fs.mkdirSync(configDir, { recursive: true })
+  fs.writeFileSync(configPath, body, 'utf8')
+}
+
+beforeEach(() => {
+  home = fs.mkdtempSync(path.join(os.tmpdir(), 'factory-config-test-'))
+  // getFactoryConfigPath() resolves under os.homedir(); point it at the fixture.
+  vi.spyOn(os, 'homedir').mockReturnValue(home)
+  configDir = path.join(home, '.infra-kit')
+  configPath = path.join(configDir, 'vendor.json')
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  fs.rmSync(home, { recursive: true, force: true })
+})
+
+describe('expandTilde', () => {
+  it('expands a bare ~ to the home dir', () => {
+    expect(expandTilde('~')).toBe(home)
+  })
+
+  it('expands ~/x to a home-relative path', () => {
+    expect(expandTilde('~/projects')).toBe(path.join(home, 'projects'))
+  })
+
+  it('passes an absolute path through unchanged', () => {
+    expect(expandTilde('/abs/dir')).toBe('/abs/dir')
+  })
+
+  it('throws on a non-absolute, non-~ path', () => {
+    expect(() => {
+      return expandTilde('rel/dir')
+    }).toThrow(/must be absolute or ~-prefixed/)
+  })
+})
+
+describe('getFactoryConfigPath', () => {
+  it('points at ~/.infra-kit/vendor.json', () => {
+    expect(getFactoryConfigPath()).toBe(configPath)
+  })
+})
+
+describe('loadFactoryConfig', () => {
+  it('loads a JSON config', async () => {
+    writeConfig(JSON.stringify({ workspaceDir: '~/projects', targets: ['travelist-monorepo'] }))
+
+    const config = await loadFactoryConfig()
+
+    expect(config.workspaceDir).toBe('~/projects')
+    expect(config.targets).toEqual(['travelist-monorepo'])
+  })
+
+  it('throws an actionable error when the file is absent', async () => {
+    await expect(loadFactoryConfig()).rejects.toThrow(/vendor-config --init/)
+  })
+
+  it('throws a descriptive error on malformed JSON', async () => {
+    writeConfig('{ not valid json ')
+    await expect(loadFactoryConfig()).rejects.toThrow(/Invalid JSON in vendor\.json/)
+  })
+
+  it('throws on a schema-invalid config (missing targets)', async () => {
+    writeConfig(JSON.stringify({ workspaceDir: '~/projects' }))
+    await expect(loadFactoryConfig()).rejects.toThrow(/Invalid factory config/)
+  })
+
+  it('rejects a stray `copy` key (.strict())', async () => {
+    writeConfig(JSON.stringify({ workspaceDir: '~/projects', targets: ['a'], copy: [] }))
+    await expect(loadFactoryConfig()).rejects.toThrow(/Invalid factory config/)
+  })
+
+  it('reads the current file on every call so an edit is picked up without a restart', async () => {
+    writeConfig(JSON.stringify({ workspaceDir: '~/projects', targets: ['first'] }))
+    expect((await loadFactoryConfig()).targets).toEqual(['first'])
+
+    writeConfig(JSON.stringify({ workspaceDir: '~/projects', targets: ['second'] }))
+    expect((await loadFactoryConfig()).targets).toEqual(['second'])
+  })
+})

package/src/lib/vendor/__tests__/vendor-lib.test.ts

@@ -0,0 +1,158 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import {
+  CURRENT_SCHEMA_VERSION,
+  MANIFEST_FILE,
+  buildFilesMap,
+  compareToManifest,
+  isUnknownSchema,
+  readManifest,
+  sha256,
+  walkVendorTree,
+  writeManifest,
+} from 'src/lib/vendor'
+
+let tmp: string
+
+const write = (rel: string, content: string): void => {
+  const full = path.join(tmp, rel)
+
+  fs.mkdirSync(path.dirname(full), { recursive: true })
+  fs.writeFileSync(full, content, 'utf8')
+}
+
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'vendor-lib-test-'))
+})
+
+afterEach(() => {
+  fs.rmSync(tmp, { recursive: true, force: true })
+})
+
+describe('walkVendorTree', () => {
+  it('returns POSIX relative paths sorted byte-wise', () => {
+    write('b.txt', 'b')
+    write('a/nested.txt', 'n')
+    write('a.txt', 'a')
+
+    expect(walkVendorTree(tmp)).toEqual(['a.txt', 'a/nested.txt', 'b.txt'])
+  })
+
+  it('is deterministic regardless of creation order', () => {
+    write('z.txt', 'z')
+    write('m/x.txt', 'x')
+    write('a.txt', 'a')
+
+    const first = walkVendorTree(tmp)
+    // Re-create in a different order in a fresh dir.
+    const tmp2 = fs.mkdtempSync(path.join(os.tmpdir(), 'vendor-lib-test2-'))
+
+    fs.writeFileSync(path.join(tmp2, 'a.txt'), 'a')
+    fs.mkdirSync(path.join(tmp2, 'm'))
+    fs.writeFileSync(path.join(tmp2, 'm', 'x.txt'), 'x')
+    fs.writeFileSync(path.join(tmp2, 'z.txt'), 'z')
+    const second = walkVendorTree(tmp2)
+
+    fs.rmSync(tmp2, { recursive: true, force: true })
+
+    expect(first).toEqual(second)
+  })
+
+  it('skips configured dirs, files, and suffixes (incl. .vitest-attachments union member)', () => {
+    write('keep.ts', 'keep')
+    write('node_modules/pkg/index.js', 'x')
+    write('dist/out.js', 'x')
+    write('.vitest-attachments/blob', 'x')
+    write('.sync-manifest.json', '{}')
+    write('.eslintcache', 'x')
+    write('log.txt', 'x')
+    write('build.tsbuildinfo', 'x')
+
+    expect(walkVendorTree(tmp)).toEqual(['keep.ts'])
+  })
+
+  it('follows a symlink and hashes its target content (legacy semantics)', () => {
+    write('real.txt', 'payload')
+    fs.symlinkSync(path.join(tmp, 'real.txt'), path.join(tmp, 'link.txt'))
+
+    const files = buildFilesMap(tmp)
+
+    expect(Object.keys(files).sort()).toEqual(['link.txt', 'real.txt'])
+    // Followed → identical content → identical hash.
+    expect(files['link.txt']).toBe(files['real.txt'])
+  })
+
+  it('surfaces an explicit error for a dangling symlink', () => {
+    fs.symlinkSync(path.join(tmp, 'does-not-exist'), path.join(tmp, 'dangling.txt'))
+
+    expect(() => {
+      return buildFilesMap(tmp)
+    }).toThrow(/broken symlink or unreadable file/)
+  })
+})
+
+describe('manifest read/write/compare', () => {
+  it('write-then-check parity: a freshly written manifest reports no drift', () => {
+    write('configs/a.js', 'aaa')
+    write('packages/p/b.ts', 'bbb')
+
+    const manifest = writeManifest(tmp, { source: 'starter-workspace', commit: 'abc123' })
+
+    expect(manifest.schemaVersion).toBe(CURRENT_SCHEMA_VERSION)
+    expect(manifest.fileCount).toBe(2)
+
+    const diff = compareToManifest(tmp, manifest)
+
+    expect(diff).toEqual({ modified: [], added: [], removed: [] })
+  })
+
+  it('detects modified / added / removed files', () => {
+    write('a.js', 'a')
+    write('b.js', 'b')
+    const manifest = writeManifest(tmp, { source: 's', commit: 'c' })
+
+    fs.writeFileSync(path.join(tmp, 'a.js'), 'CHANGED')
+    write('c.js', 'c')
+    fs.rmSync(path.join(tmp, 'b.js'))
+
+    const diff = compareToManifest(tmp, manifest)
+
+    expect(diff.modified).toEqual(['a.js'])
+    expect(diff.added).toEqual(['c.js'])
+    expect(diff.removed).toEqual(['b.js'])
+  })
+
+  it('reads a legacy manifest with no schemaVersion as compatible', () => {
+    write('a.js', 'a')
+    const legacy = {
+      source: 'starter-workspace',
+      commit: 'deadbeef',
+      syncedAt: new Date().toISOString(),
+      fileCount: 1,
+      files: { 'a.js': sha256(path.join(tmp, 'a.js')) },
+    }
+
+    fs.writeFileSync(path.join(tmp, MANIFEST_FILE), JSON.stringify(legacy))
+
+    const manifest = readManifest(tmp)
+
+    expect(manifest.schemaVersion).toBeUndefined()
+    expect(isUnknownSchema(manifest)).toBe(false)
+    expect(compareToManifest(tmp, manifest)).toEqual({ modified: [], added: [], removed: [] })
+  })
+
+  it('flags a newer schemaVersion as unknown (fail-closed)', () => {
+    const manifest = { ...writeManifest(tmp, { source: 's', commit: 'c' }), schemaVersion: CURRENT_SCHEMA_VERSION + 1 }
+
+    expect(isUnknownSchema(manifest)).toBe(true)
+  })
+
+  it('throws on a missing manifest', () => {
+    expect(() => {
+      return readManifest(tmp)
+    }).toThrow(/Missing \.sync-manifest\.json/)
+  })
+})

package/src/lib/vendor/__tests__/zx-mock.ts

@@ -0,0 +1,32 @@
+import { vi } from 'vitest'
+
+/**
+ * Shared spy for every `zx` subprocess call in the vendor write-path tests.
+ * Tests assert against it, e.g. `expect(execMock).not.toHaveBeenCalled()`.
+ */
+export const execMock = vi.fn(() => {
+  return Promise.resolve({ stdout: '' })
+})
+
+/**
+ * `vi.mock('zx')` factory body. Returns a `$` handling both the tagged-template
+ * `` $`cmd` `` and the `$({ cwd })` options form, routing every call through
+ * {@link execMock}. Referencing this imported function (rather than a top-level
+ * const) keeps the hoisted `vi.mock` factory hoist-safe.
+ *
+ * @example
+ * vi.mock('zx', () => zxModuleMock())
+ */
+export const zxModuleMock = () => {
+  const $ = (first: unknown) => {
+    if (Array.isArray(first)) {
+      return execMock()
+    }
+
+    return () => {
+      return execMock()
+    }
+  }
+
+  return { $ }
+}

package/src/lib/vendor/config-schema.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod'
+
+/**
+ * Pure (node-free) vendor config schema + authoring helper. Kept separate from
+ * `config.ts` (which imports node builtins for the runtime loader) so the public
+ * lib entry can re-export `defineVendorConfig` without dragging node types into
+ * the emitted `.d.ts`.
+ */
+
+/**
+ * Filename a source repo provides at its root to declare WHAT `vendor sync`
+ * copies (`copy[]`). Lives ONLY on the write path — `vendor check` never loads it.
+ * WHERE/WHICH to stamp (`workspaceDir` + `targets`) is machine-local and lives in
+ * the user-global factory config (`~/.infra-kit/vendor.json`).
+ */
+export const VENDOR_CONFIG_FILE = 'vendor.config.ts'
+
+/**
+ * A non-empty, repo-relative path with no `..` segments and no absolute prefix
+ * (POSIX `/`, UNC/`\`, or a Windows drive like `C:`). Containment guard for
+ * vendor copy items so a malicious/typo config can't read or write outside the
+ * source/target repo roots. Kept as a string/regex check (no `node:path`) to
+ * respect this file's node-free constraint — `sync-ops.ts` does the resolved
+ * runtime containment assert as defense in depth.
+ */
+const safeRelPath = z.string().refine(
+  (p) => {
+    const isAbsolute = /^(?:[/\\]|[a-z]:)/i.test(p)
+    const hasDotDotSegment = p.split(/[\\/]/).includes('..')
+
+    return !isAbsolute && !hasDotDotSegment && p.trim().length > 0
+  },
+  { message: 'must be a non-empty repo-relative path without ".." segments' },
+)
+
+/**
+ * One item to sync from the source repo into each target. `vendored: true` marks
+ * workspace packages that must land under `vendor/` (the single-source-of-truth
+ * code); everything else is root-level tooling that stays at the repo root.
+ */
+export const vendorCopyItemSchema = z.object({
+  name: z.string(),
+  source: safeRelPath,
+  target: safeRelPath,
+  type: z.enum(['file', 'directory']),
+  vendored: z.boolean().optional(),
+})
+
+export const vendorConfigSchema = z
+  .object({
+    /** Files/dirs to copy. Items with `vendored: true` land under `vendor/`. */
+    copy: z.array(vendorCopyItemSchema),
+  })
+  // Reject stray keys so a leftover `targets` (now machine-local, in
+  // ~/.infra-kit/vendor.json) yields a clear "unrecognized key" error rather
+  // than being silently ignored.
+  .strict()
+
+export type VendorCopyItem = z.infer<typeof vendorCopyItemSchema>
+export type VendorConfig = z.infer<typeof vendorConfigSchema>
+
+/**
+ * Identity helper for authoring a type-safe `vendor.config.ts` in a source repo.
+ * Re-exported from the public lib entry so a source repo can
+ * `import { defineVendorConfig } from 'infra-kit'`.
+ *
+ * NOTE: a `vendor.config.ts` must be type-strippable — Node's native type
+ * stripping (Node >= 24) loads it without a build step, which forbids `enum`,
+ * `namespace`, and parameter properties.
+ *
+ * @example
+ * export default defineVendorConfig({
+ *   copy: [{ name: 'Configs', source: 'vendor/configs', target: 'vendor/configs', type: 'directory', vendored: true }],
+ * })
+ */
+export const defineVendorConfig = (config: VendorConfig): VendorConfig => {
+  return config
+}

package/src/lib/vendor/config.ts

@@ -0,0 +1,58 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { z } from 'zod'
+
+import { VENDOR_CONFIG_FILE, vendorConfigSchema } from './config-schema'
+import type { VendorConfig } from './config-schema'
+
+// Convenience re-export so importers of the loader can also grab the authoring
+// helper from one module. The node-free definitions live in `./config-schema`
+// (the public `.d.ts` emit imports from there to stay node-type-free).
+export { defineVendorConfig } from './config-schema'
+
+/**
+ * Load, resolve, and validate a source repo's `vendor.config.ts`.
+ *
+ * Reuses the established loader pattern from
+ * `package-validator/loader/config-loader.ts`: dynamic-import the `.ts` file via
+ * Node's native type stripping with an mtime cache-bust (so a long-running MCP
+ * server picks up edits), resolve a Vite-style factory or object default export,
+ * then validate against {@link vendorConfigSchema}. No new dependency (no
+ * jiti/tsx). Throws a descriptive error when the file is absent or malformed.
+ *
+ * @example
+ * await loadVendorConfig('/Users/me/projects/starter-workspace')
+ */
+export const loadVendorConfig = async (rootDir: string): Promise<VendorConfig> => {
+  const configPath = path.join(rootDir, VENDOR_CONFIG_FILE)
+
+  let stat
+
+  try {
+    stat = await fs.stat(configPath)
+  } catch {
+    throw new Error(`${VENDOR_CONFIG_FILE} not found at ${configPath}`)
+  }
+
+  // Cache-bust with the file mtime so repeated loads pick up edits without a
+  // process restart. `.ts` configs load via Node's native type stripping.
+  const moduleUrl = `${pathToFileURL(configPath).href}?mtime=${Number(stat.mtimeMs)}`
+
+  const imported = (await import(moduleUrl)) as { default?: unknown }
+  const rawExport = imported.default
+
+  if (rawExport === undefined) {
+    throw new Error(`${VENDOR_CONFIG_FILE} at ${configPath} has no default export`)
+  }
+
+  const resolvedExport = typeof rawExport === 'function' ? await (rawExport as () => unknown)() : rawExport
+
+  const parsed = vendorConfigSchema.safeParse(resolvedExport)
+
+  if (!parsed.success) {
+    throw new Error(`Invalid ${VENDOR_CONFIG_FILE} at ${configPath}: ${z.prettifyError(parsed.error)}`)
+  }
+
+  return parsed.data
+}

package/src/lib/vendor/factory-config-schema.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod'
+
+/**
+ * Pure (node-free) factory config schema. Kept separate from `factory-config.ts`
+ * (which imports node builtins for the runtime loader) so the public lib entry can
+ * re-export the `FactoryConfig` type without dragging node types into the emitted
+ * `.d.ts` — same split as `config-schema.ts` / `config.ts`.
+ */
+
+/**
+ * Basename of the machine-local factory config, which lives at
+ * `~/.infra-kit/vendor.json`. It is static JSON (no longer an executable `.ts`
+ * module): the loader reads it with `JSON.parse`. The committed SOURCE-repo config
+ * keeps the `vendor.config.ts` basename — always refer to this one as "the
+ * user-global factory config".
+ */
+export const FACTORY_CONFIG_FILE = 'vendor.json'
+
+/**
+ * The machine-local factory registry. Answers "where do my project repos live"
+ * (`workspaceDir`) and "which ones does the factory stamp" (`targets`). The
+ * portable "what to vendor" definition (`copy[]`) lives in the committed SOURCE
+ * `vendor.config.ts`, never here. `.strict()` rejects a stray `copy` key so a
+ * misplaced source config produces a clear error.
+ */
+export const factoryConfigSchema = z
+  .object({
+    /** Absolute (or `~`-prefixed) dir where the target project repos are cloned. */
+    workspaceDir: z.string().min(1),
+    /** Target repo directory names, resolved under `workspaceDir`. */
+    targets: z.array(z.string()).min(1),
+  })
+  .strict()
+
+export type FactoryConfig = z.infer<typeof factoryConfigSchema>

package/src/lib/vendor/factory-config.ts

@@ -0,0 +1,91 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { z } from 'zod'
+
+import { USER_CONFIG_DIR_NAME } from 'src/lib/infra-kit-config'
+
+import { FACTORY_CONFIG_FILE, factoryConfigSchema } from './factory-config-schema'
+import type { FactoryConfig } from './factory-config-schema'
+
+/**
+ * Absolute path to the machine-local factory config (`~/.infra-kit/vendor.json`).
+ * Always returned, even when the file does not exist, so callers can surface a
+ * "where would it go?" prompt.
+ *
+ * @example
+ * getFactoryConfigPath() // => '/Users/arthur/.infra-kit/vendor.json'
+ */
+export const getFactoryConfigPath = (): string => {
+  return path.join(os.homedir(), USER_CONFIG_DIR_NAME, FACTORY_CONFIG_FILE)
+}
+
+/**
+ * Expand a leading `~` to the home dir. Absolute paths pass through unchanged.
+ * A non-absolute, non-`~` value throws — cwd-relative resolution is ambiguous
+ * across CLI vs long-running MCP-server invocations, so we reject it loudly.
+ *
+ * @example
+ * expandTilde('~')          // => '/Users/arthur'
+ * expandTilde('~/projects') // => '/Users/arthur/projects'
+ * expandTilde('/abs/dir')   // => '/abs/dir'
+ * expandTilde('rel/dir')    // throws
+ */
+export const expandTilde = (p: string): string => {
+  if (p === '~') return os.homedir()
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2))
+  if (path.isAbsolute(p)) return p
+
+  throw new Error(`workspaceDir must be absolute or ~-prefixed, got: ${p}`)
+}
+
+/**
+ * Load and validate the user-global factory config at `~/.infra-kit/vendor.json`.
+ * Reads the static JSON with `JSON.parse` (an empty/whitespace-only file is treated
+ * as `{}`), then validates against {@link factoryConfigSchema}.
+ *
+ * Reads the file on every call (no module cache to bust — unlike a `.ts`
+ * `import()`, `JSON.parse` always sees the current bytes), so an absent → present
+ * transition works within one process: a `--init` scaffold followed by a load
+ * succeeds, and a long-running MCP server picks up edits without a restart.
+ * Throws an actionable error pointing at `infra-kit vendor-config --init` when the
+ * file is absent.
+ *
+ * @example
+ * const { workspaceDir, targets } = await loadFactoryConfig()
+ */
+export const loadFactoryConfig = async (): Promise<FactoryConfig> => {
+  const configPath = getFactoryConfigPath()
+
+  let raw: string
+
+  try {
+    raw = await fs.readFile(configPath, 'utf-8')
+  } catch {
+    throw new Error(
+      `Factory config not found at ${configPath}. infra-kit needs a machine-local factory ` +
+        `registry to know where your project repos live and which to stamp. Run ` +
+        `\`infra-kit vendor-config --init\` to scaffold it, or create it manually as JSON:\n\n` +
+        `  {\n` +
+        `    "workspaceDir": "~/projects",\n` +
+        `    "targets": ["my-repo"]\n` +
+        `  }\n`,
+    )
+  }
+
+  let data: unknown
+
+  try {
+    data = raw.trim() === '' ? {} : JSON.parse(raw)
+  } catch (err) {
+    throw new Error(`Invalid JSON in vendor.json at ${configPath}: ${(err as Error).message}`)
+  }
+
+  const parsed = factoryConfigSchema.safeParse(data)
+
+  if (!parsed.success) {
+    throw new Error(`Invalid factory config at ${configPath}: ${z.prettifyError(parsed.error)}`)
+  }
+
+  return parsed.data
+}

package/src/lib/vendor/hash.ts

@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+
+/**
+ * SHA-256 of a file's contents, hex-encoded. Matches the legacy scripts'
+ * `createHash('sha256').update(readFileSync(path)).digest('hex')`.
+ *
+ * `readFileSync` follows symlinks, so a symlinked file is hashed by its target
+ * content — the behavior both legacy scripts already relied on.
+ *
+ * @example
+ * sha256('/repo/vendor/configs/eslint-config/index.js') // => 'a1b2c3...'
+ */
+export const sha256 = (filePath: string): string => {
+  return createHash('sha256').update(readFileSync(filePath)).digest('hex')
+}

package/src/lib/vendor/index.ts

@@ -0,0 +1,23 @@
+export { sha256 } from './hash'
+export {
+  buildFilesMap,
+  compareToManifest,
+  CURRENT_SCHEMA_VERSION,
+  isUnknownSchema,
+  MANIFEST_FILE,
+  readManifest,
+  writeManifest,
+} from './manifest'
+export type { ManifestDiff, VendorManifest } from './manifest'
+/**
+ * Read-path barrel for the vendor integrity primitives. This is the SINGLE
+ * source of truth for walk/hash/manifest logic, consumed by `vendor check` and
+ * (via the same functions) the write-path commands.
+ *
+ * IMPORTANT: this barrel intentionally re-exports ONLY the read path. The config
+ * loader (`./config`) and rsync/`zx` (`./sync-ops`) live with the write commands;
+ * `vendor check` never imports them, so its runtime path stays free of them. The
+ * skip-set constants are an internal detail (`./skip-sets`) used by `walk`.
+ */
+export { VENDOR_DIR } from './skip-sets'
+export { walkVendorTree } from './walk'