infra-kit 0.1.113 → 0.1.115

package/src/commands/init/init.ts

@@ -1,12 +1,18 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import process from 'node:process'
 
 import { logger } from 'src/lib/logger'
 import { removeManagedBlock, upsertManagedBlock } from 'src/lib/managed-block'
 
 import { writeAgentFiles } from './agent-files'
-import { migrateLegacyConfig, normalizeLegacyIdeStructures } from './migrate-config'
+import {
+  migrateFactoryConfigToJson,
+  migrateLegacyConfig,
+  migrateUserGlobalConfigFilename,
+  normalizeLegacyIdeStructures,
+} from './migrate-config'
 
 export const MARKER_START = '# -- infra-kit:begin --'
 export const MARKER_END = '# -- infra-kit:end --'
@@ -18,22 +24,34 @@ const LEGACY_SINGLE = '# infra-kit shell functions'
 const USER_GLOBAL_CONFIG_STUB = '{}\n'
 
 // …and the annotated guidance lives next to it in a non-loaded .example.jsonc
-// (the loader only reads the three exact `infra-kit.json` / `config.json` files).
-const USER_GLOBAL_CONFIG_EXAMPLE = `// infra-kit user-global config — ~/.infra-kit/config.json
+// (the loader only reads the three exact `infra-kit.json` files).
+const USER_GLOBAL_CONFIG_EXAMPLE = `// infra-kit user-global config — ~/.infra-kit/infra-kit.json
 //
 // Merge chain (later layers override earlier ones at top-level keys):
 //   1. <repo>/infra-kit.json                            — committed project config (required)
-//   2. ~/.infra-kit/config.json                         — user-global (the sibling of this file)
+//   2. ~/.infra-kit/infra-kit.json                      — user-global (the sibling of this file)
 //   3. ~/.infra-kit/projects/<repo-name>/infra-kit.json — user-scope per-project override
 //
 // Merge is shallow: setting a top-level key replaces that whole section from
 // layer 1. Arrays do not concatenate. Top-level keys recognized:
-// environments, envManagement, ide, taskManager, worktrees.
+// environments, envManagement, ide, taskManager, worktrees, envAutoLoad.
 //
 // This .example.jsonc is reference only — it is NOT loaded. Put real global
-// overrides in the sibling config.json (strict JSON: no comments, double-quoted
+// overrides in the sibling infra-kit.json (strict JSON: no comments, double-quoted
 // keys). Per-project tweaks belong in layer 3 — run \`infra-kit config edit\`.
+//
+// Every recognized key is documented below. NOTE: \`environments\` and
+// \`envManagement\` are REQUIRED in the committed project infra-kit.json (layer 1)
+// and are usually NOT set in this user-global layer — they are shown here only to
+// document the full, valid config shape.
 {
+  // "environments": ["dev", "staging", "prod"],   // string[] (>=1) — required in layer 1
+  //
+  // "envManagement": {                            // required in layer 1; provider-tagged
+  //   "provider": "doppler",
+  //   "config": { "name": "my-doppler-project" }
+  // },
+  //
   // "ide": {
   //   "provider": "cursor",
   //   "config": { "workspaceConfigPath": "/path/to/your.code-workspace" }
@@ -45,23 +63,60 @@ const USER_GLOBAL_CONFIG_EXAMPLE = `// infra-kit user-global config — ~/.infra
   //   { "provider": "cursor", "config": { "workspaceConfigPath": "/path/to/your.code-workspace" } },
   //   { "provider": "zed", "config": {} }
   // ],
-  // "worktrees": { "openInGithubDesktop": false, "openInCmux": true }
+  //
+  // "taskManager": {
+  //   "provider": "jira",
+  //   "config": { "baseUrl": "https://acme.atlassian.net", "projectId": 123 }
+  // },
+  //
+  // "worktrees": {
+  //   "openInGithubDesktop": false,
+  //   "openInCmux": true,
+  //   // cmux pane layout for opened worktrees: "two-columns" (default, left | right)
+  //   // or "three-pane" (left split top/bottom + full-height right).
+  //   "cmux": { "layout": "two-columns" }
+  // },
+  //
+  // // Auto-load Doppler env when working inside this project/worktree. Omit to
+  // // disable. "trigger" (pick one): "shell-startup" (new shells) | "cli-invocation"
+  // // (before each infra-kit command, primes subsequent commands). "config" is the
+  // // environment to load (must be one of "environments"). Requires the committed
+  // // infra-kit.json at the git repo root, and the zsh shell integration
+  // // (infra-kit init + a new shell). zsh only.
+  // "envAutoLoad": { "trigger": "shell-startup", "config": "dev" }
+}
+`
+
+// The machine-local factory registry lives at ~/.infra-kit/vendor.json (strict
+// JSON). This annotated sibling documents every property; the real file is
+// scaffolded by \`infra-kit vendor config --init\`, NOT by init.
+const VENDOR_CONFIG_EXAMPLE = `// infra-kit factory registry — ~/.infra-kit/vendor.json
+//
+// Machine-local registry the vendor commands (sync/manifest/diff) read to know
+// where your project repos live and which ones to stamp. This .example.jsonc is
+// reference only — it is NOT loaded. The real file is the strict-JSON sibling
+// vendor.json (no comments, double-quoted keys); run \`infra-kit vendor config --init\`
+// to scaffold it.
+{
+  // "workspaceDir": "~/projects",   // string (absolute or ~-prefixed) — where target repos are cloned
+  // "targets": ["my-repo-a", "my-repo-b"]   // string[] (>=1) — repo dir names resolved under workspaceDir
 }
 `
 
 /**
- * Append infra-kit shell functions to .zshrc, migrate any legacy
- * `infra-kit.yml` config layers to JSON, normalize existing JSON configs from
- * the old IDE structure to the new one (strip the removed `ide.config.mode`),
- * and seed the user-global config at ~/.infra-kit/config.json on first run.
- * Idempotent: a subsequent run replaces the existing zshrc block in place, has
- * nothing left to migrate or normalize, and leaves the user-global config
- * untouched.
+ * Append infra-kit shell functions to .zshrc, migrate any legacy `infra-kit.yml`
+ * config layers to JSON, normalize existing JSON configs from the old IDE structure
+ * (strip the removed `ide.config.mode`), convert a legacy factory `vendor.config.ts`
+ * to `vendor.json`, and seed the user-global config at ~/.infra-kit/infra-kit.json on
+ * first run. Idempotent: a subsequent run replaces the existing zshrc block in place,
+ * has nothing left to migrate or normalize, and leaves the REAL config files
+ * (infra-kit.json / vendor.json) untouched — but the annotated `.example.jsonc`
+ * reference files are refreshed on every run so they always reflect the current schema.
  *
  * @example
  * // CLI: `infra-kit init`  (or via the `pnpm dx-init` alias)
  * // INFO: Added infra-kit shell functions to /Users/me/.zshrc
- * // INFO: Wrote user-global config to /Users/me/.infra-kit/config.json (see …/config.example.jsonc …)
+ * // INFO: Wrote user-global config to /Users/me/.infra-kit/infra-kit.json (see …/infra-kit.example.jsonc …)
  * // INFO: Run `source ~/.zshrc` or open a new terminal to activate.
  */
 export const init = async (): Promise<void> => {
@@ -85,50 +140,79 @@ export const init = async (): Promise<void> => {
   logger.info(`Added infra-kit shell functions to ${zshrcPath}`)
 
   // Convert any legacy infra-kit.yml config layers to JSON before seeding, so a
-  // migrated config.json is not re-seeded as an empty stub.
+  // migrated infra-kit.json is not re-seeded as an empty stub.
   await migrateLegacyConfig()
 
   // Migrate existing JSON configs from the old IDE structure to the new one
   // (strip the removed `ide.config.mode` field). No-op for already-clean configs.
   await normalizeLegacyIdeStructures()
 
+  // Rename a legacy user-global config.json → infra-kit.json (single canonical
+  // filename). MUST run before seeding: otherwise the seeder checks the new name,
+  // doesn't find it, and writes an empty stub that shadows the user's real config.
+  await migrateUserGlobalConfigFilename()
+
+  // Convert a legacy machine-local factory config from executable TS
+  // (~/.infra-kit/vendor.config.ts) to static JSON (~/.infra-kit/vendor.json).
+  // Independent of the infra-kit.json layers; grouped with the other migrations.
+  await migrateFactoryConfigToJson()
+
   seedUserGlobalConfig()
 
   // Best-effort, non-fatal, repo-gated: keep the agent-instruction files in sync
   // with the CLI surface. A no-op outside an infra-kit repo.
   await writeAgentFiles()
 
+  // The shell integration is zsh-only (zmodload zsh/stat, add-zsh-hook, ${dir:h}).
+  // Warn non-fatally if the user's login shell isn't zsh so the block isn't a
+  // silent no-op for them.
+  const shell = process.env.SHELL ?? ''
+
+  if (!shell.includes('zsh')) {
+    logger.warn(
+      `Your login shell ($SHELL=${shell || 'unset'}) is not zsh. The infra-kit shell integration (env-load/env-clear/auto-load) is zsh-only and won't activate in bash/fish.`,
+    )
+  }
+
   logger.info('Run `source ~/.zshrc` or open a new terminal to activate.')
 }
 
 /**
- * Create `~/.infra-kit/config.json` (empty `{}`) plus an annotated
- * `~/.infra-kit/config.example.jsonc` reference when absent. Skips silently if
- * the config already exists so user edits are preserved.
+ * Seed the user-global config on first run and (re)write the annotated reference
+ * files. The real `~/.infra-kit/infra-kit.json` (empty `{}`) is written only when
+ * absent so user edits are preserved. The non-loaded `.example.jsonc` reference
+ * files (`infra-kit.example.jsonc` + `vendor.example.jsonc`) are rewritten on EVERY
+ * run so existing users always get the current, complete schema documentation.
+ *
+ * Deliberately seeds NO real `vendor.json` — that is scaffolded by
+ * `infra-kit vendor config --init` (a stub here would block `--init`, trip the
+ * factory migration's no-overwrite guard, and fail the schema's `targets.min(1)`).
  *
  * @example
  * seedUserGlobalConfig()
- * // first call:  writes ~/.infra-kit/config.json ({}) + config.example.jsonc
- * // later calls: leaves the config alone, logs that it is already present
+ * // first call:  writes ~/.infra-kit/infra-kit.json ({}) + both .example.jsonc files
+ * // later calls: leaves infra-kit.json alone, refreshes both .example.jsonc files
  */
-const seedUserGlobalConfig = (): void => {
+export const seedUserGlobalConfig = (): void => {
   const userConfigDir = path.join(os.homedir(), '.infra-kit')
-  const userConfigPath = path.join(userConfigDir, 'config.json')
-  const userConfigExamplePath = path.join(userConfigDir, 'config.example.jsonc')
+  const userConfigPath = path.join(userConfigDir, 'infra-kit.json')
+
+  fs.mkdirSync(userConfigDir, { recursive: true })
+
+  // Reference examples are non-loaded docs — always refresh them so re-running init
+  // delivers the current schema (and the newly-added vendor example) to existing users.
+  fs.writeFileSync(path.join(userConfigDir, 'infra-kit.example.jsonc'), USER_GLOBAL_CONFIG_EXAMPLE, 'utf-8')
+  fs.writeFileSync(path.join(userConfigDir, 'vendor.example.jsonc'), VENDOR_CONFIG_EXAMPLE, 'utf-8')
 
   if (fs.existsSync(userConfigPath)) {
-    logger.info(`User-global config already present at ${userConfigPath}`)
+    logger.info(`User-global config already present at ${userConfigPath} (refreshed reference examples)`)
 
     return
   }
 
-  fs.mkdirSync(userConfigDir, { recursive: true })
   fs.writeFileSync(userConfigPath, USER_GLOBAL_CONFIG_STUB, 'utf-8')
-  fs.writeFileSync(userConfigExamplePath, USER_GLOBAL_CONFIG_EXAMPLE, 'utf-8')
 
-  logger.info(
-    `Wrote user-global config to ${userConfigPath} (see ${userConfigExamplePath} for the annotated reference)`,
-  )
+  logger.info(`Wrote user-global config to ${userConfigPath} (see the sibling .example.jsonc files for reference)`)
 }
 
 const isBlockLine = (line: string): boolean => {
@@ -168,7 +252,7 @@ const removeExistingBlock = (content: string): string => {
 
   if (legacyIdx === -1) return content
 
-  // eslint-disable-next-line sonarjs/slow-regex
+  // eslint-disable-next-line sonarjs/super-linear-regex
   const before = content.slice(0, legacyIdx).replace(/\n+$/, '')
   const afterLines = content.slice(legacyIdx).split('\n')
 
@@ -238,6 +322,31 @@ export const buildShellBody = (): string => {
     'if (( _INFRA_KIT_SHELL_STARTED > 0 )); then',
     '  add-zsh-hook precmd _infra_kit_autoload',
     'fi',
+    // One-shot env auto-load when a NEW shell opens inside an infra-kit project
+    // or worktree (config: envAutoLoad.trigger "shell-startup"). Cheap pure-zsh
+    // project gate (walk up for infra-kit.json) avoids spawning node in unrelated
+    // shells; the INFRA_KIT_ENV_CONFIG guard skips subshells that already inherited
+    // a loaded env. The spawn is DETACHED+backgrounded ( ... & ) so it never blocks
+    // the prompt; it only WRITES env-load.sh and the precmd hook above is the sole
+    // sourcer (picked up on a subsequent prompt). Trade-off: the gate can't read the
+    // merged JSON config, so a fresh shell in a project WITHOUT envAutoLoad still
+    // spawns one background process that resolves config, finds nothing, and exits.
+    '_infra_kit_startup_autoload() {',
+    '  [[ -z "$INFRA_KIT_SESSION" ]] && return',
+    '  [[ -n "$INFRA_KIT_ENV_CONFIG" ]] && return',
+    '  local dir="$PWD"',
+    '  while [[ "$dir" != / ]]; do',
+    '    if [[ -f "$dir/infra-kit.json" ]]; then',
+    `      ( ${runCmd} env-autoload & ) >/dev/null 2>&1`,
+    '      return',
+    '    fi',
+    // eslint-disable-next-line no-template-curly-in-string
+    '    dir="${dir:h}"',
+    '  done',
+    '}',
+    'if (( _INFRA_KIT_SHELL_STARTED > 0 )); then',
+    '  _infra_kit_startup_autoload',
+    'fi',
   ].join('\n')
 }
 

package/src/commands/init/migrate-config.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises'
-import os from 'node:os'
 import path from 'node:path'
+import { pathToFileURL } from 'node:url'
 import yaml from 'yaml'
 import { z } from 'zod'
 
@@ -11,6 +11,9 @@ import {
   resetInfraKitConfigCache,
 } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
+import { fileExists, tildify } from 'src/lib/path-display'
+import { getFactoryConfigPath } from 'src/lib/vendor/factory-config'
+import { factoryConfigSchema } from 'src/lib/vendor/factory-config-schema'
 
 interface MigrateLayer {
   label: string
@@ -22,35 +25,6 @@ interface MigrateLayer {
   schema: z.ZodType
 }
 
-/**
- * Replace the user's home prefix with `~` so logged paths stay short.
- *
- * @example
- * // os.homedir() === '/Users/arthur'
- * tildify('/Users/arthur/.infra-kit/config.yml') // => '~/.infra-kit/config.yml'
- */
-const tildify = (filePath: string): string => {
-  const home = os.homedir()
-
-  return filePath.startsWith(home) ? `~${filePath.slice(home.length)}` : filePath
-}
-
-/**
- * `fs.access` reduced to a boolean, swallowing ENOENT.
- *
- * @example
- * await fileExists('/etc/hosts') // => true
- */
-const fileExists = async (filePath: string): Promise<boolean> => {
-  try {
-    await fs.access(filePath)
-
-    return true
-  } catch {
-    return false
-  }
-}
-
 /**
  * Swap a resolved `.json` config path back to its legacy `.yml` sibling.
  *
@@ -87,8 +61,13 @@ export const migrateLegacyConfig = async (): Promise<void> => {
   const layers: MigrateLayer[] = [
     { label: 'infra-kit.json', yml: legacyYmlPath(paths.main), json: paths.main, schema: infraKitConfigSchema },
     {
-      label: '~/.infra-kit/config.json',
-      yml: legacyYmlPath(paths.userGlobal),
+      label: '~/.infra-kit/infra-kit.json',
+      // The user-global JSON filename changed (config.json → infra-kit.json), but
+      // the legacy YAML it converts from kept the old `config.yml` name. Pin it
+      // here so it does not drift to `infra-kit.yml` via legacyYmlPath(); the
+      // main/userProject layers keep deriving their `.yml` sibling normally
+      // because their `.json` filename never changed.
+      yml: path.join(path.dirname(paths.userGlobal), 'config.yml'),
       json: paths.userGlobal,
       schema: infraKitOverrideConfigSchema,
     },
@@ -145,6 +124,155 @@ export const migrateLegacyConfig = async (): Promise<void> => {
   }
 }
 
+/**
+ * Rename the user-global config from the legacy `config.json` filename to the
+ * canonical `infra-kit.json` (and its `config.example.jsonc` reference to
+ * `infra-kit.example.jsonc`), so every merge-chain layer shares one filename.
+ * Run by `infra-kit init` before the user-global config is seeded, so a user's
+ * existing overrides are carried forward instead of being shadowed by a fresh
+ * `{}` stub written under the new name.
+ *
+ * Best-effort and non-fatal per file: a missing source is skipped silently
+ * (idempotent — nothing to rename on a second run), and an already-present
+ * target is never overwritten (the stale `config.json` is left in place so no
+ * bytes are lost — the user reconciles it manually). Resets the config cache
+ * when anything was renamed.
+ *
+ * @example
+ * await migrateUserGlobalConfigFilename()
+ * // ✓ Renamed ~/.infra-kit/config.json → ~/.infra-kit/infra-kit.json
+ * // (no output when there is nothing legacy to rename)
+ */
+export const migrateUserGlobalConfigFilename = async (): Promise<void> => {
+  let paths: Awaited<ReturnType<typeof getInfraKitConfigPaths>>
+
+  try {
+    paths = await getInfraKitConfigPaths()
+  } catch {
+    // No resolvable project (e.g. init run outside a repo) — nothing to rename.
+    return
+  }
+
+  const dir = path.dirname(paths.userGlobal)
+  // The config.json → infra-kit.json rename carries forward a user's REAL config and
+  // is load-bearing. The example-file rename is now largely redundant: seedUserGlobalConfig
+  // rewrites infra-kit.example.jsonc unconditionally moments later, so a renamed legacy
+  // example is overwritten anyway (and if infra-kit.example.jsonc already exists, the
+  // no-overwrite guard simply leaves an orphaned config.example.jsonc behind — harmless).
+  const pairs: { from: string; to: string }[] = [
+    { from: path.join(dir, 'config.json'), to: paths.userGlobal },
+    { from: path.join(dir, 'config.example.jsonc'), to: path.join(dir, 'infra-kit.example.jsonc') },
+  ]
+
+  let renamed = 0
+
+  for (const { from, to } of pairs) {
+    const [fromExists, toExists] = await Promise.all([fileExists(from), fileExists(to)])
+
+    if (!fromExists) continue
+
+    if (toExists) {
+      logger.info(`⚠ Skipped ${tildify(from)} — ${tildify(to)} already exists (remove the stale file manually)`)
+
+      continue
+    }
+
+    // Same-directory rename is atomic; per-file try/catch keeps a TOCTOU race or
+    // I/O error (EACCES, read-only FS) non-fatal so one bad file never aborts init.
+    try {
+      await fs.mkdir(path.dirname(to), { recursive: true })
+      await fs.rename(from, to)
+
+      logger.info(`✓ Renamed ${tildify(from)} → ${tildify(to)}`)
+      renamed++
+    } catch (err) {
+      logger.info(`⚠ Skipped ${tildify(from)} — ${(err as Error).message}`)
+    }
+  }
+
+  if (renamed > 0) {
+    resetInfraKitConfigCache()
+  }
+}
+
+/**
+ * Convert a legacy machine-local factory config from executable TypeScript
+ * (`~/.infra-kit/vendor.config.ts`) to static JSON (`~/.infra-kit/vendor.json`) as
+ * part of `infra-kit init`. The factory config used to be a `.ts` module loaded via
+ * dynamic `import()`; it is now strict JSON read with `JSON.parse`. This one-shot
+ * migration dynamic-imports the old `.ts` (the ONLY remaining dynamic import of the
+ * factory file), resolves a factory-function or object default export, validates it,
+ * writes `vendor.json`, and removes the old `.ts`.
+ *
+ * Best-effort, non-fatal, idempotent (no old `.ts` → no-op), and never overwrites an
+ * existing `vendor.json`. When the old export was a FUNCTION, its resolved output is
+ * frozen into static JSON — so a DISTINCT warning is emitted (not a plain
+ * `✓ Migrated`) because dynamic re-evaluation (env vars, directory globbing) no
+ * longer happens. No `resetInfraKitConfigCache()` — the factory loader shares no
+ * cache with the `infra-kit.json` layers.
+ *
+ * @example
+ * await migrateFactoryConfigToJson()
+ * // ✓ Migrated ~/.infra-kit/vendor.config.ts → ~/.infra-kit/vendor.json
+ * // (no output when there is nothing legacy to convert)
+ */
+export const migrateFactoryConfigToJson = async (): Promise<void> => {
+  const newJson = getFactoryConfigPath() // ~/.infra-kit/vendor.json
+  const dir = path.dirname(newJson)
+  const oldTs = path.join(dir, 'vendor.config.ts')
+
+  const [oldExists, newExists] = await Promise.all([fileExists(oldTs), fileExists(newJson)])
+
+  if (!oldExists) return // idempotent: nothing to migrate (incl. after a prior successful run)
+
+  if (newExists) {
+    logger.info(
+      `⚠ Skipped ${tildify(oldTs)} — ${tildify(newJson)} already exists (remove the stale vendor.config.ts manually)`,
+    )
+
+    return
+  }
+
+  // The factory `.ts` is executable; read it once via dynamic import (Node native
+  // type stripping) with an mtime cache-bust, resolving a factory-function or object
+  // default export. Per-file try/catch keeps a malformed module or I/O error
+  // non-fatal so one bad file never aborts init.
+  try {
+    const stat = await fs.stat(oldTs)
+    const moduleUrl = `${pathToFileURL(oldTs).href}?mtime=${Number(stat.mtimeMs)}`
+    const imported = (await import(moduleUrl)) as { default?: unknown }
+    const raw = imported.default
+    const wasFunction = typeof raw === 'function'
+    const resolved = wasFunction ? await (raw as () => unknown)() : raw
+
+    const result = factoryConfigSchema.safeParse(resolved)
+
+    if (!result.success) {
+      logger.info(`⚠ Skipped ${tildify(oldTs)} — invalid factory config: ${z.prettifyError(result.error)}`)
+
+      return // leave the old .ts in place so the user can fix and re-run; do not delete unconverted data
+    }
+
+    await fs.mkdir(dir, { recursive: true })
+    await fs.writeFile(newJson, `${JSON.stringify(result.data, null, 2)}\n`, 'utf-8')
+    await fs.rm(oldTs, { force: true })
+
+    if (wasFunction) {
+      // The old export was a function: its values were resolved ONCE and frozen into
+      // static JSON. Disclose the lost dynamism instead of reporting a clean success.
+      logger.info(
+        `⚠ Migrated ${tildify(oldTs)} → ${tildify(newJson)} as a STATIC SNAPSHOT — the old file was a ` +
+          `function (export default () => ({...})); computed values (env vars, directory globbing) were ` +
+          `frozen at their current values and no longer re-evaluate. Edit ${tildify(newJson)} directly to change them.`,
+      )
+    } else {
+      logger.info(`✓ Migrated ${tildify(oldTs)} → ${tildify(newJson)}`)
+    }
+  } catch (err) {
+    logger.info(`⚠ Skipped ${tildify(oldTs)} — ${(err as Error).message}`)
+  }
+}
+
 /**
  * Surgically strip the removed `ide.config.mode` field from a parsed config
  * object (single-provider or array form). The windows-removal made `mode` a dead

package/src/commands/vendor-check/__tests__/runtime-isolation.test.ts

@@ -0,0 +1,71 @@
+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 { writeManifest } from 'src/lib/vendor'
+import { execMock, zxModuleMock } from 'src/lib/vendor/__tests__/zx-mock'
+
+import { vendorCheck } from '../vendor-check'
+
+// Spy on every subprocess-spawning and config-loading collaborator. The
+// invariant under test is RUNTIME: invoking `vendor check` must spawn zero
+// subprocess and load zero vendor.config.ts — regardless of what the single
+// bundled CLI artifact happens to contain.
+vi.mock('zx', () => {
+  return zxModuleMock()
+})
+
+const loadVendorConfigMock = vi.fn()
+
+vi.mock('src/lib/vendor/config', async (importActual) => {
+  const actual = await importActual<typeof import('src/lib/vendor/config')>()
+
+  return { ...actual, loadVendorConfig: loadVendorConfigMock }
+})
+
+const loadFactoryConfigMock = vi.fn()
+
+vi.mock('src/lib/vendor/factory-config', async (importActual) => {
+  const actual = await importActual<typeof import('src/lib/vendor/factory-config')>()
+
+  return { ...actual, loadFactoryConfig: loadFactoryConfigMock }
+})
+
+let root: string
+let vendorRoot: string
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'vendor-isolation-test-'))
+  vendorRoot = path.join(root, 'vendor')
+  fs.mkdirSync(path.join(vendorRoot, 'configs'), { recursive: true })
+  fs.writeFileSync(path.join(vendorRoot, 'configs', 'a.js'), 'aaa')
+  writeManifest(vendorRoot, { source: 's', commit: 'c' })
+})
+
+afterEach(() => {
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+describe('vendor check runtime isolation', () => {
+  it('spawns no subprocess and loads no vendor.config.ts on a clean check', async () => {
+    const { structuredContent } = await vendorCheck({ cwd: root })
+
+    expect(structuredContent.ok).toBe(true)
+    expect(execMock).not.toHaveBeenCalled()
+    expect(loadVendorConfigMock).not.toHaveBeenCalled()
+    expect(loadFactoryConfigMock).not.toHaveBeenCalled()
+  })
+
+  it('spawns no subprocess even when reporting drift', async () => {
+    fs.writeFileSync(path.join(vendorRoot, 'configs', 'a.js'), 'CHANGED')
+
+    const { structuredContent } = await vendorCheck({ cwd: root })
+
+    expect(structuredContent.ok).toBe(false)
+    expect(execMock).not.toHaveBeenCalled()
+    expect(loadVendorConfigMock).not.toHaveBeenCalled()
+    expect(loadFactoryConfigMock).not.toHaveBeenCalled()
+  })
+})

package/src/commands/vendor-check/__tests__/vendor-check.test.ts

@@ -0,0 +1,87 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { writeManifest } from 'src/lib/vendor'
+
+import { vendorCheck } from '../vendor-check'
+
+let root: string
+let vendorRoot: string
+
+const writeVendor = (rel: string, content: string): void => {
+  const full = path.join(vendorRoot, rel)
+
+  fs.mkdirSync(path.dirname(full), { recursive: true })
+  fs.writeFileSync(full, content, 'utf8')
+}
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'vendor-check-test-'))
+  vendorRoot = path.join(root, 'vendor')
+})
+
+afterEach(() => {
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+describe('vendorCheck exit-code matrix', () => {
+  it('missing vendor/ → ok (skip)', async () => {
+    const { structuredContent } = await vendorCheck({ cwd: root })
+
+    expect(structuredContent.status).toBe('skipped')
+    expect(structuredContent.ok).toBe(true)
+  })
+
+  it('missing manifest → not ok', async () => {
+    writeVendor('a.js', 'a')
+    const { structuredContent } = await vendorCheck({ cwd: root })
+
+    expect(structuredContent.status).toBe('missing-manifest')
+    expect(structuredContent.ok).toBe(false)
+  })
+
+  it('clean tree → ok', async () => {
+    writeVendor('configs/a.js', 'a')
+    writeVendor('packages/p/b.ts', 'b')
+    writeManifest(vendorRoot, { source: 's', commit: 'c' })
+
+    const { structuredContent } = await vendorCheck({ cwd: root })
+
+    expect(structuredContent.status).toBe('clean')
+    expect(structuredContent.ok).toBe(true)
+    expect(structuredContent.fileCount).toBe(2)
+  })
+
+  it('drifted tree → not ok with categorized paths', async () => {
+    writeVendor('a.js', 'a')
+    writeVendor('b.js', 'b')
+    writeManifest(vendorRoot, { source: 's', commit: 'c' })
+
+    fs.writeFileSync(path.join(vendorRoot, 'a.js'), 'CHANGED')
+    writeVendor('c.js', 'c')
+    fs.rmSync(path.join(vendorRoot, 'b.js'))
+
+    const { structuredContent } = await vendorCheck({ cwd: root })
+
+    expect(structuredContent.status).toBe('drift')
+    expect(structuredContent.ok).toBe(false)
+    expect(structuredContent.modified).toEqual(['a.js'])
+    expect(structuredContent.added).toEqual(['c.js'])
+    expect(structuredContent.removed).toEqual(['b.js'])
+  })
+
+  it('unknown future schemaVersion → not ok (fail-closed)', async () => {
+    writeVendor('a.js', 'a')
+    const manifest = writeManifest(vendorRoot, { source: 's', commit: 'c' })
+    const bumped = { ...manifest, schemaVersion: (manifest.schemaVersion ?? 1) + 1 }
+
+    fs.writeFileSync(path.join(vendorRoot, '.sync-manifest.json'), JSON.stringify(bumped))
+
+    const { structuredContent } = await vendorCheck({ cwd: root })
+
+    expect(structuredContent.status).toBe('unknown-schema')
+    expect(structuredContent.ok).toBe(false)
+  })
+})

package/src/commands/vendor-check/index.ts

@@ -0,0 +1 @@
+export { vendorCheck, vendorCheckMcpTool } from './vendor-check'