infra-kit 0.1.114 → 0.1.117

package/src/commands/env-status/env-status.ts

@@ -2,9 +2,10 @@ import path from 'node:path'
 import process from 'node:process'
 import { z } from 'zod'
 
-import { validateDopplerCliAndAuth } from 'src/integrations/doppler'
 import {
   ENV_LOAD_FILE,
+  INFRA_KIT_ENV_AUTOLOADED_VAR,
+  INFRA_KIT_ENV_CLEARED_VAR,
   INFRA_KIT_ENV_CONFIG_VAR,
   INFRA_KIT_ENV_LOADED_AT_VAR,
   INFRA_KIT_ENV_PROJECT_VAR,
@@ -16,11 +17,13 @@ import { logger } from 'src/lib/logger'
 import { defineMcpTool, textContent } from 'src/types'
 
 /**
- * Show Doppler authentication status and detected project info
+ * Report which env is currently loaded in the terminal session. Pure local
+ * introspection: reads only `process.env` + the cached env-load.sh — it makes NO
+ * Doppler call (use `doctor` for auth/CLI checks), so it works offline and never
+ * hangs. Surfaces whether the env was auto-loaded vs manually loaded and whether a
+ * clear is currently suppressing auto-load.
  */
 export const envStatus = async () => {
-  await validateDopplerCliAndAuth()
-
   logger.info('Environment session status:')
 
   // Check session-loaded vars — getSessionCacheDir() throws if INFRA_KIT_SESSION is unset
@@ -35,6 +38,8 @@ export const envStatus = async () => {
   const sessionConfig = process.env[INFRA_KIT_ENV_CONFIG_VAR] ?? null
   const sessionProject = process.env[INFRA_KIT_ENV_PROJECT_VAR] ?? null
   const sessionLoadedAt = process.env[INFRA_KIT_ENV_LOADED_AT_VAR] ?? null
+  const autoLoaded = process.env[INFRA_KIT_ENV_AUTOLOADED_VAR] === '1'
+  const cleared = Boolean(process.env[INFRA_KIT_ENV_CLEARED_VAR])
 
   if (sessionConfig) {
     const varNames = parseVarNamesFromEnvFile(envLoadPath)
@@ -47,9 +52,10 @@ export const envStatus = async () => {
     }
 
     const loadedAtDisplay = sessionLoadedAt?.replace(/\.\d{3}Z$/, '') ?? null
+    const origin = autoLoaded ? 'auto-loaded' : 'manually loaded'
 
     logger.info(
-      `  ${sessionConfig}: ${sessionLoadedCount} of ${sessionTotalCount} vars loaded (project: ${sessionProject}, loadedAt: ${loadedAtDisplay}, session: ${sessionId})\n`,
+      `  ${sessionConfig}: ${sessionLoadedCount} of ${sessionTotalCount} vars loaded (${origin}, project: ${sessionProject}, loadedAt: ${loadedAtDisplay}, session: ${sessionId})\n`,
     )
 
     if (sessionTotalCount > 0 && sessionLoadedCount < sessionTotalCount) {
@@ -60,7 +66,9 @@ export const envStatus = async () => {
       )
     }
   } else {
-    logger.info(`  Session ${sessionId}: no env loaded\n`)
+    const clearedNote = cleared ? ' (cleared — auto-load suppressed until a new shell or explicit env-load)' : ''
+
+    logger.info(`  Session ${sessionId}: no env loaded${clearedNote}\n`)
   }
 
   const structuredContent = {
@@ -70,6 +78,8 @@ export const envStatus = async () => {
     sessionConfig,
     sessionProject,
     sessionLoadedAt,
+    autoLoaded,
+    cleared,
   }
 
   return {
@@ -82,7 +92,7 @@ export const envStatus = async () => {
 export const envStatusMcpTool = defineMcpTool({
   name: 'env-status',
   description:
-    'Report which Doppler project/config is currently loaded in the terminal session, when it was loaded, and how many variables are cached. Read-only — use env-load / env-clear to change the terminal session.',
+    'Report which Doppler project/config is currently loaded in the terminal session, when it was loaded, how many variables are cached, whether it was auto-loaded, and whether a clear is suppressing auto-load. Pure local introspection — makes NO Doppler call (use doctor for auth). Read-only — use env-load / env-clear to change the terminal session.',
   inputSchema: {},
   outputSchema: {
     sessionId: z.string().describe('Current terminal session ID'),
@@ -91,6 +101,8 @@ export const envStatusMcpTool = defineMcpTool({
     sessionConfig: z.string().nullable().describe('Doppler config name of the loaded session (environment name)'),
     sessionProject: z.string().nullable().describe('Doppler project name of the loaded session'),
     sessionLoadedAt: z.string().nullable().describe('ISO 8601 timestamp of when the env was loaded'),
+    autoLoaded: z.boolean().describe('True when the loaded env was applied by env auto-load (not a manual env-load)'),
+    cleared: z.boolean().describe('True when env-clear is currently suppressing auto-load in this shell'),
   },
   handler: envStatus,
 })

package/src/commands/gh-release-deploy-all/gh-release-deploy-all.ts

@@ -1,3 +1,4 @@
+import confirm from '@inquirer/confirm'
 import select from '@inquirer/select'
 import { z } from 'zod'
 import { $ } from 'zx'
@@ -21,13 +22,39 @@ interface GhReleaseDeployAllArgs {
   version: string
   env: string
   skipTerraform?: boolean
+  confirmedCommand?: boolean
+}
+
+interface ConfirmDeployArgs {
+  confirmedCommand?: boolean
+  branch: string
+  env: string
+}
+
+/**
+ * Gate the workflow dispatch behind an interactive confirmation. Returns true to
+ * proceed; `confirmedCommand` (CLI `--yes`) skips the prompt. Mirrors the
+ * confirm+commandEcho pattern used by worktrees-remove.
+ */
+const confirmDeploy = async (args: ConfirmDeployArgs): Promise<boolean> => {
+  const { confirmedCommand, branch, env } = args
+
+  if (confirmedCommand) return true
+
+  commandEcho.setInteractive()
+
+  const answer = await confirm({ message: `Deploy ${branch} → ${env}?`, default: false })
+
+  if (answer) commandEcho.addOption('--yes', true)
+
+  return answer
 }
 
 /**
  * Deploy a release branch to an environment
  */
 export const ghReleaseDeployAll = async (args: GhReleaseDeployAllArgs) => {
-  const { version, env, skipTerraform } = args
+  const { version, env, skipTerraform, confirmedCommand } = args
 
   commandEcho.start('release-deploy-all')
 
@@ -98,6 +125,23 @@ export const ghReleaseDeployAll = async (args: GhReleaseDeployAllArgs) => {
     commandEcho.addOption('--skip-terraform', true)
   }
 
+  if (!(await confirmDeploy({ confirmedCommand, branch: selectedReleaseBranch, env: selectedEnv }))) {
+    logger.info('Deployment cancelled')
+
+    const structuredContent = {
+      releaseBranch: selectedReleaseBranch,
+      version: selectedVersion,
+      environment: selectedEnv,
+      skipTerraformDeploy: shouldSkipTerraform,
+      success: false,
+    }
+
+    return {
+      content: textContent(JSON.stringify(structuredContent, null, 2)),
+      structuredContent,
+    }
+  }
+
   try {
     $.quiet = true
 

package/src/commands/gh-release-deploy-selected/gh-release-deploy-selected.ts

@@ -1,4 +1,5 @@
 import checkbox from '@inquirer/checkbox'
+import confirm from '@inquirer/confirm'
 import select from '@inquirer/select'
 import fs from 'node:fs/promises'
 import { resolve } from 'node:path'
@@ -27,6 +28,32 @@ interface GhReleaseDeploySelectedArgs {
   env: string
   services: string[]
   skipTerraform?: boolean
+  confirmedCommand?: boolean
+}
+
+interface ConfirmDeployArgs {
+  confirmedCommand?: boolean
+  branch: string
+  env: string
+}
+
+/**
+ * Gate the workflow dispatch behind an interactive confirmation. Returns true to
+ * proceed; `confirmedCommand` (CLI `--yes`) skips the prompt. Mirrors the
+ * confirm+commandEcho pattern used by worktrees-remove.
+ */
+const confirmDeploy = async (args: ConfirmDeployArgs): Promise<boolean> => {
+  const { confirmedCommand, branch, env } = args
+
+  if (confirmedCommand) return true
+
+  commandEcho.setInteractive()
+
+  const answer = await confirm({ message: `Deploy ${branch} → ${env}?`, default: false })
+
+  if (answer) commandEcho.addOption('--yes', true)
+
+  return answer
 }
 
 /**
@@ -34,7 +61,7 @@ interface GhReleaseDeploySelectedArgs {
  */
 // eslint-disable-next-line sonarjs/cognitive-complexity
 export const ghReleaseDeploySelected = async (args: GhReleaseDeploySelectedArgs) => {
-  const { version, env, services, skipTerraform } = args
+  const { version, env, services, skipTerraform, confirmedCommand } = args
 
   commandEcho.start('release-deploy-selected')
 
@@ -157,6 +184,24 @@ export const ghReleaseDeploySelected = async (args: GhReleaseDeploySelectedArgs)
     commandEcho.addOption('--skip-terraform', true)
   }
 
+  if (!(await confirmDeploy({ confirmedCommand, branch: selectedReleaseBranch, env: selectedEnv }))) {
+    logger.info('Deployment cancelled')
+
+    const structuredContent = {
+      releaseBranch: selectedReleaseBranch,
+      version: selectedVersion,
+      environment: selectedEnv,
+      services: selectedServices,
+      skipTerraformDeploy: shouldSkipTerraform,
+      success: false,
+    }
+
+    return {
+      content: textContent(JSON.stringify(structuredContent, null, 2)),
+      structuredContent,
+    }
+  }
+
   try {
     $.quiet = true
 

package/src/commands/init/__tests__/agent-files.test.ts

@@ -5,7 +5,13 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { getProjectRoot, getRepoName } from 'src/lib/git-utils'
 
-import { AGENTS_IMPORT_START, AGENTS_MARKER_END, AGENTS_MARKER_START, writeAgentFiles } from '../agent-files'
+import {
+  AGENTS_IMPORT_END,
+  AGENTS_IMPORT_START,
+  AGENTS_MARKER_END,
+  AGENTS_MARKER_START,
+  writeAgentFiles,
+} from '../agent-files'
 
 vi.mock('src/lib/git-utils', () => {
   return {
@@ -46,32 +52,30 @@ describe('writeAgentFiles', () => {
     vi.clearAllMocks()
   })
 
-  it('creates AGENTS.md, the CLAUDE.md import, and the .cursor rule on a fresh repo', async () => {
+  it('writes the full guidance block only to CLAUDE.md, and creates no other files, on a fresh repo', async () => {
     await withTmpRepo(async (tmp) => {
       const result = await writeAgentFiles()
 
       expect(result.skipped).toBe(false)
       expect(result.root).toBe(tmp)
 
-      const agents = fs.readFileSync(path.join(tmp, 'AGENTS.md'), 'utf-8')
-
-      expect(agents).toContain(AGENTS_MARKER_START)
-      expect(agents).toContain(AGENTS_MARKER_END)
-      expect(agents).toContain('<!-- infra-kit:version ')
-
       const claude = fs.readFileSync(path.join(tmp, 'CLAUDE.md'), 'utf-8')
 
-      expect(claude).toContain(AGENTS_IMPORT_START)
-      expect(claude).toContain('@AGENTS.md')
-
-      const cursor = fs.readFileSync(path.join(tmp, '.cursor', 'rules', 'infra-kit.mdc'), 'utf-8')
-
-      expect(cursor).toContain('alwaysApply: true')
-      expect(cursor).toContain(AGENTS_MARKER_START)
+      expect(claude).toContain(AGENTS_MARKER_START)
+      expect(claude).toContain(AGENTS_MARKER_END)
+      expect(claude).toContain('<!-- infra-kit:version ')
+      expect(claude).toContain('# infra-kit')
+      // The migrated `@AGENTS.md` import region must never appear.
+      expect(claude).not.toContain(AGENTS_IMPORT_START)
+      expect(claude).not.toContain('@AGENTS.md')
+
+      // CLAUDE.md is the only output — infra-kit no longer touches AGENTS.md or .cursor.
+      expect(fs.existsSync(path.join(tmp, 'AGENTS.md'))).toBe(false)
+      expect(fs.existsSync(path.join(tmp, '.cursor'))).toBe(false)
     })
   })
 
-  it('preserves existing hand-authored CLAUDE.md content verbatim (ticket conventions)', async () => {
+  it('preserves existing hand-authored CLAUDE.md content and appends the block after it', async () => {
     await withTmpRepo(async (tmp) => {
       const claudePath = path.join(tmp, 'CLAUDE.md')
       const userContent = '# CLAUDE.md\n\n## Ticket Naming Convention\n\n- `[FE]` — frontend\n- `[BE]` — backend\n'
@@ -84,17 +88,19 @@ describe('writeAgentFiles', () => {
 
       expect(updated).toContain('## Ticket Naming Convention')
       expect(updated).toContain('`[FE]` — frontend')
-      expect(updated).toContain(AGENTS_IMPORT_START)
+      expect(updated).toContain(AGENTS_MARKER_START)
+      // The managed block lands AFTER the hand-authored content.
+      expect(updated.indexOf('## Ticket Naming Convention')).toBeLessThan(updated.indexOf(AGENTS_MARKER_START))
     })
   })
 
-  it('is idempotent — a second run does not duplicate the block', async () => {
+  it('is idempotent — a second run does not duplicate the block and reports unchanged (same CLI version)', async () => {
     await withTmpRepo(async (tmp) => {
       await writeAgentFiles()
-      const first = fs.readFileSync(path.join(tmp, 'AGENTS.md'), 'utf-8')
+      const first = fs.readFileSync(path.join(tmp, 'CLAUDE.md'), 'utf-8')
 
       const second = await writeAgentFiles()
-      const after = fs.readFileSync(path.join(tmp, 'AGENTS.md'), 'utf-8')
+      const after = fs.readFileSync(path.join(tmp, 'CLAUDE.md'), 'utf-8')
 
       expect(after).toBe(first)
       expect(after.match(new RegExp(AGENTS_MARKER_START, 'g'))?.length).toBe(1)
@@ -113,35 +119,147 @@ describe('writeAgentFiles', () => {
 
         expect(result.skipped).toBe(true)
         expect(result.root).toBeNull()
-        expect(fs.existsSync(path.join(tmp, 'AGENTS.md'))).toBe(false)
+        expect(fs.existsSync(path.join(tmp, 'CLAUDE.md'))).toBe(false)
       },
       { repo: false },
     )
   })
 
-  it('refuses to write through a symlinked AGENTS.md', async () => {
+  it('refuses to write through a symlinked CLAUDE.md', async () => {
     await withTmpRepo(async (tmp) => {
       const realTarget = path.join(tmp, 'elsewhere.md')
 
       writeFile(realTarget, 'sensitive')
-      fs.symlinkSync(realTarget, path.join(tmp, 'AGENTS.md'))
+      fs.symlinkSync(realTarget, path.join(tmp, 'CLAUDE.md'))
 
       await expect(writeAgentFiles()).rejects.toThrow(/symlink/)
     })
   })
 
-  it('backs up an existing AGENTS.md before overwriting', async () => {
+  it('backs up an existing CLAUDE.md before overwriting', async () => {
     await withTmpRepo(async (tmp) => {
-      writeFile(path.join(tmp, 'AGENTS.md'), 'previous content without markers\n')
+      writeFile(path.join(tmp, 'CLAUDE.md'), 'previous content without markers\n')
 
       await writeAgentFiles()
 
       const backups = fs.readdirSync(tmp).filter((f) => {
-        return f.startsWith('AGENTS.md.backup.')
+        return f.startsWith('CLAUDE.md.backup.')
       })
 
-      expect(backups.length).toBe(1)
+      expect(backups).toHaveLength(1)
       expect(fs.readFileSync(path.join(tmp, backups[0]!), 'utf-8')).toContain('previous content without markers')
     })
   })
+
+  describe('legacy AGENTS.md migration', () => {
+    /** Seed a repo in the pre-migration state: AGENTS.md (full block) + CLAUDE.md (@AGENTS.md import). */
+    const seedLegacy = async (
+      tmp: string,
+      opts: { agentsExtra?: string; claudeExtra?: string } = {},
+    ): Promise<void> => {
+      const agentsBlock = `${AGENTS_MARKER_START}\n# infra-kit\nlegacy body\n${AGENTS_MARKER_END}\n`
+      const importBlock = `${AGENTS_IMPORT_START}\n@AGENTS.md\n${AGENTS_IMPORT_END}\n`
+
+      writeFile(path.join(tmp, 'AGENTS.md'), `${opts.agentsExtra ?? ''}${agentsBlock}`)
+      writeFile(path.join(tmp, 'CLAUDE.md'), `${opts.claudeExtra ?? ''}${importBlock}`)
+    }
+
+    it('removes a purely-generated AGENTS.md (with a backup) and strips the @AGENTS.md import from CLAUDE.md', async () => {
+      await withTmpRepo(async (tmp) => {
+        await seedLegacy(tmp)
+
+        await writeAgentFiles()
+
+        // AGENTS.md is gone, but a backup survives.
+        expect(fs.existsSync(path.join(tmp, 'AGENTS.md'))).toBe(false)
+        const backups = fs.readdirSync(tmp).filter((f) => {
+          return f.startsWith('AGENTS.md.backup.')
+        })
+
+        expect(backups).toHaveLength(1)
+
+        // CLAUDE.md now carries the full block and no longer imports @AGENTS.md.
+        const claude = fs.readFileSync(path.join(tmp, 'CLAUDE.md'), 'utf-8')
+
+        expect(claude).toContain(AGENTS_MARKER_START)
+        expect(claude).not.toContain(AGENTS_IMPORT_START)
+        expect(claude).not.toContain('@AGENTS.md')
+      })
+    })
+
+    it('retains an AGENTS.md that has hand-authored content (block removed, file kept, backup made)', async () => {
+      await withTmpRepo(async (tmp) => {
+        await seedLegacy(tmp, { agentsExtra: '# My own notes\n\nkeep me\n\n' })
+
+        await writeAgentFiles()
+
+        // File retained with hand content; the infra-kit block is stripped.
+        expect(fs.existsSync(path.join(tmp, 'AGENTS.md'))).toBe(true)
+        const agents = fs.readFileSync(path.join(tmp, 'AGENTS.md'), 'utf-8')
+
+        expect(agents).toContain('# My own notes')
+        expect(agents).toContain('keep me')
+        expect(agents).not.toContain(AGENTS_MARKER_START)
+
+        // A backup of the pre-strip file exists.
+        const backups = fs.readdirSync(tmp).filter((f) => {
+          return f.startsWith('AGENTS.md.backup.')
+        })
+
+        expect(backups).toHaveLength(1)
+      })
+    })
+
+    it('leaves an AGENTS.md with no infra-kit block untouched (not ours)', async () => {
+      await withTmpRepo(async (tmp) => {
+        const handAuthored = '# AGENTS\n\nentirely hand-written, no markers\n'
+
+        writeFile(path.join(tmp, 'AGENTS.md'), handAuthored)
+
+        await writeAgentFiles()
+
+        expect(fs.readFileSync(path.join(tmp, 'AGENTS.md'), 'utf-8')).toBe(handAuthored)
+        const backups = fs.readdirSync(tmp).filter((f) => {
+          return f.startsWith('AGENTS.md.backup.')
+        })
+
+        expect(backups).toHaveLength(0)
+      })
+    })
+
+    it('is idempotent after migration — a second run finds nothing left to migrate', async () => {
+      await withTmpRepo(async (tmp) => {
+        await seedLegacy(tmp)
+        await writeAgentFiles()
+
+        const second = await writeAgentFiles()
+
+        expect(
+          second.written.every((w) => {
+            return w.action === 'unchanged'
+          }),
+        ).toBe(true)
+      })
+    })
+  })
+
+  it('does not touch a pre-existing .cursor/rules file — infra-kit no longer supports Cursor rules', async () => {
+    await withTmpRepo(async (tmp) => {
+      const cursorPath = path.join(tmp, '.cursor', 'rules', 'infra-kit.mdc')
+      // Even a file that carries our managed block is left completely alone now.
+      const existing = `---\ndescription: x\n---\n${AGENTS_MARKER_START}\n# infra-kit\nold body\n${AGENTS_MARKER_END}\n`
+
+      writeFile(cursorPath, existing)
+
+      await writeAgentFiles()
+
+      // Untouched: same content, no backup, no deletion.
+      expect(fs.readFileSync(cursorPath, 'utf-8')).toBe(existing)
+      const backups = fs.readdirSync(path.join(tmp, '.cursor', 'rules')).filter((f) => {
+        return f.startsWith('infra-kit.mdc.backup.')
+      })
+
+      expect(backups).toHaveLength(0)
+    })
+  })
 })

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

@@ -6,7 +6,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 // Import AFTER the mock is declared so the module picks up the mocked dep.
 import { getProjectRoot, getRepoName } from 'src/lib/git-utils'
 
-import { migrateLegacyConfig, normalizeLegacyIdeStructures } from '../migrate-config'
+import { migrateLegacyConfig, migrateUserGlobalConfigFilename, normalizeLegacyIdeStructures } from '../migrate-config'
 
 vi.mock('src/lib/git-utils', () => {
   return {
@@ -105,8 +105,10 @@ describe('migrateLegacyConfig', () => {
     await withTmpRepo(async (tmp) => {
       const mainYml = path.join(tmp, 'infra-kit.yml')
       const mainJson = path.join(tmp, 'infra-kit.json')
+      // The user-global legacy YAML keeps the old `config.yml` name; its JSON
+      // target is the renamed canonical `infra-kit.json`.
       const userGlobalYml = path.join(tmp, '.infra-kit', 'config.yml')
-      const userGlobalJson = path.join(tmp, '.infra-kit', 'config.json')
+      const userGlobalJson = path.join(tmp, '.infra-kit', 'infra-kit.json')
 
       writeFile(mainYml, MAIN_YML)
       // Invalid override: environments present but empty (min(1) fails).
@@ -151,9 +153,17 @@ describe('migrateLegacyConfig', () => {
 
       await migrateLegacyConfig()
 
-      for (const yml of [mainYml, userGlobalYml, userProjectYml]) {
+      // The user-global legacy `config.yml` migrates to the renamed canonical
+      // `infra-kit.json`; main/userProject keep their `.yml`→`.json` sibling name.
+      const pairs: [yml: string, json: string][] = [
+        [mainYml, path.join(tmp, 'infra-kit.json')],
+        [userGlobalYml, path.join(tmp, '.infra-kit', 'infra-kit.json')],
+        [userProjectYml, path.join(tmp, '.infra-kit', 'projects', projectName, 'infra-kit.json')],
+      ]
+
+      for (const [yml, json] of pairs) {
         expect(fs.existsSync(yml)).toBe(false)
-        expect(fs.existsSync(yml.replace(/\.yml$/, '.json'))).toBe(true)
+        expect(fs.existsSync(json)).toBe(true)
       }
     })
   })
@@ -221,7 +231,7 @@ describe('normalizeLegacyIdeStructures', () => {
 
   it('normalizes the user-global config layer too', async () => {
     await withTmpRepo(async (tmp) => {
-      const userGlobalJson = path.join(tmp, '.infra-kit', 'config.json')
+      const userGlobalJson = path.join(tmp, '.infra-kit', 'infra-kit.json')
 
       writeFile(userGlobalJson, JSON.stringify({ ide: { provider: 'zed', config: { mode: 'windows' } } }))
 
@@ -289,3 +299,124 @@ describe('normalizeLegacyIdeStructures', () => {
     })
   })
 })
+
+describe('migrateUserGlobalConfigFilename', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  const userGlobalPaths = (tmp: string) => {
+    const dir = path.join(tmp, '.infra-kit')
+
+    return {
+      legacyConfig: path.join(dir, 'config.json'),
+      newConfig: path.join(dir, 'infra-kit.json'),
+      legacyExample: path.join(dir, 'config.example.jsonc'),
+      newExample: path.join(dir, 'infra-kit.example.jsonc'),
+    }
+  }
+
+  it('renames config.json → infra-kit.json (and the example) preserving content', async () => {
+    await withTmpRepo(async (tmp) => {
+      const p = userGlobalPaths(tmp)
+      const configBody = JSON.stringify({ worktrees: { openInCmux: true } })
+      const exampleBody = '// example\n{}\n'
+
+      writeFile(p.legacyConfig, configBody)
+      writeFile(p.legacyExample, exampleBody)
+
+      await migrateUserGlobalConfigFilename()
+
+      expect(fs.existsSync(p.legacyConfig)).toBe(false)
+      expect(fs.existsSync(p.legacyExample)).toBe(false)
+      expect(fs.readFileSync(p.newConfig, 'utf-8')).toBe(configBody)
+      expect(fs.readFileSync(p.newExample, 'utf-8')).toBe(exampleBody)
+    })
+  })
+
+  it('is a no-op when there is no legacy config.json (idempotent)', async () => {
+    await withTmpRepo(async (tmp) => {
+      const p = userGlobalPaths(tmp)
+
+      await expect(migrateUserGlobalConfigFilename()).resolves.toBeUndefined()
+
+      expect(fs.existsSync(p.legacyConfig)).toBe(false)
+      expect(fs.existsSync(p.newConfig)).toBe(false)
+    })
+  })
+
+  it('never overwrites an existing infra-kit.json; leaves the stale config.json in place', async () => {
+    await withTmpRepo(async (tmp) => {
+      const p = userGlobalPaths(tmp)
+      const legacyBody = JSON.stringify({ worktrees: { openInCmux: false } })
+      const activeBody = JSON.stringify({ worktrees: { openInCmux: true } })
+
+      writeFile(p.legacyConfig, legacyBody)
+      writeFile(p.newConfig, activeBody)
+
+      await migrateUserGlobalConfigFilename()
+
+      // Active config untouched (NOT clobbered); legacy file preserved for the user.
+      expect(fs.readFileSync(p.newConfig, 'utf-8')).toBe(activeBody)
+      expect(fs.readFileSync(p.legacyConfig, 'utf-8')).toBe(legacyBody)
+    })
+  })
+
+  it('migrates each file independently (example present, config absent)', async () => {
+    await withTmpRepo(async (tmp) => {
+      const p = userGlobalPaths(tmp)
+      const exampleBody = '// example only\n{}\n'
+
+      writeFile(p.legacyExample, exampleBody)
+
+      await migrateUserGlobalConfigFilename()
+
+      expect(fs.existsSync(p.legacyExample)).toBe(false)
+      expect(fs.readFileSync(p.newExample, 'utf-8')).toBe(exampleBody)
+      // No config.json existed → nothing created on that side.
+      expect(fs.existsSync(p.newConfig)).toBe(false)
+    })
+  })
+
+  it('yAML-legacy upgrade: migrateLegacyConfig + rename land config at infra-kit.json', async () => {
+    await withTmpRepo(async (tmp) => {
+      const p = userGlobalPaths(tmp)
+      const legacyYml = path.join(tmp, '.infra-kit', 'config.yml')
+
+      writeFile(legacyYml, 'worktrees:\n  openInCmux: true\n')
+
+      // migrateLegacyConfig converts the pinned config.yml source → infra-kit.json;
+      // the rename then has nothing left to do for the user-global config.
+      await migrateLegacyConfig()
+      await migrateUserGlobalConfigFilename()
+
+      expect(fs.existsSync(legacyYml)).toBe(false)
+      expect(fs.existsSync(p.legacyConfig)).toBe(false)
+      expect(JSON.parse(fs.readFileSync(p.newConfig, 'utf-8')).worktrees.openInCmux).toBe(true)
+    })
+  })
+
+  it('both-legacy files: YAML wins via migrateLegacyConfig, config.json is left untouched', async () => {
+    await withTmpRepo(async (tmp) => {
+      const p = userGlobalPaths(tmp)
+      const legacyYml = path.join(tmp, '.infra-kit', 'config.yml')
+      const jsonBody = JSON.stringify({ worktrees: { openInCmux: false } })
+
+      writeFile(legacyYml, 'worktrees:\n  openInCmux: true\n')
+      writeFile(p.legacyConfig, jsonBody)
+
+      // init() order: migrateLegacyConfig (yml→infra-kit.json) then the rename.
+      await migrateLegacyConfig()
+      await migrateUserGlobalConfigFilename()
+
+      // YAML content won at infra-kit.json; the rename's no-overwrite guard then
+      // skipped config.json, leaving it untouched (no data loss).
+      expect(JSON.parse(fs.readFileSync(p.newConfig, 'utf-8')).worktrees.openInCmux).toBe(true)
+      expect(fs.readFileSync(p.legacyConfig, 'utf-8')).toBe(jsonBody)
+    })
+  })
+})