infra-kit 0.1.102 → 0.1.105

package/src/commands/gh-release-deliver/gh-release-deliver.ts

@@ -1,7 +1,7 @@
 import confirm from '@inquirer/confirm'
 import select from '@inquirer/select'
 import process from 'node:process'
-import { z } from 'zod/v4'
+import { z } from 'zod'
 import { $ } from 'zx'
 
 import { getReleasePRsWithInfo } from 'src/integrations/gh'
@@ -12,7 +12,14 @@ import { formatZxError } from 'src/lib/errors/format-zx-error'
 import { OperationError } from 'src/lib/errors/operation-error'
 import { getCurrentWorktrees, getProjectRoot, getRepoName } from 'src/lib/git-utils'
 import { logger } from 'src/lib/logger'
-import { detectReleaseType, formatBranchChoices, getJiraDescriptions } from 'src/lib/release-utils'
+import { displayLabel, formatJiraName, formatRcTitle, parseBranchName } from 'src/lib/release-id'
+import type { ReleaseId } from 'src/lib/release-id'
+import {
+  detectReleaseType,
+  formatBranchChoices,
+  getJiraDescriptions,
+  resolveReleaseBranch,
+} from 'src/lib/release-utils'
 import type { ReleaseType } from 'src/lib/release-utils'
 import { removeWorktrees } from 'src/lib/worktrees'
 import { defineMcpTool, textContent } from 'src/types'
@@ -62,8 +69,8 @@ const fetchPRByHead = async (head: string): Promise<PRStatus | null> => {
  * the merge step on resume. Title-matched on purpose: an older MERGED RC PR
  * from a different release must not short-circuit this version's flow.
  */
-const fetchMergedRcPRForVersion = async (version: string): Promise<PRStatus | null> => {
-  const expectedTitle = `Release v${version} (RC)`
+const fetchMergedRcPRForVersion = async (id: ReleaseId): Promise<PRStatus | null> => {
+  const expectedTitle = formatRcTitle(id)
   const result = await $`gh pr list --head dev --base main --state merged --json number,state,title --limit 20`
   const prs = JSON.parse(result.stdout) as PRStatus[]
   const match = prs.find((pr) => {
@@ -92,7 +99,7 @@ interface ResolvedTarget {
 }
 
 const resolveTargetFromVersion = async (version: string): Promise<ResolvedTarget> => {
-  const selectedReleaseBranch = `release/v${version}`
+  const selectedReleaseBranch = resolveReleaseBranch(version)
   const pr = await fetchPRByHead(selectedReleaseBranch)
 
   if (!pr) {
@@ -208,8 +215,9 @@ const mergeReleasePR = async (args: MergeReleasePRArgs): Promise<void> => {
   )
 }
 
-const resolveRcPRNumber = async (selectedVersion: string): Promise<number> => {
-  const expectedTitle = `Release v${selectedVersion} (RC)`
+const resolveRcPRNumber = async (id: ReleaseId): Promise<number> => {
+  const selectedLabel = displayLabel(id)
+  const expectedTitle = formatRcTitle(id)
   const existingOpen = await fetchOpenDevToMainPR()
 
   // Adopt any existing open dev→main PR. GitHub permits only one open PR per
@@ -221,7 +229,7 @@ const resolveRcPRNumber = async (selectedVersion: string): Promise<number> => {
 
     if (existingOpen.title !== expectedTitle) {
       logger.info(
-        `Adopting open dev → main PR #${rcNumber} ("${existingOpen.title}") and retitling for v${selectedVersion}`,
+        `Adopting open dev → main PR #${rcNumber} ("${existingOpen.title}") and retitling for ${selectedLabel}`,
       )
       await runStep(
         `retitle dev → main PR #${rcNumber} to "${expectedTitle}"`,
@@ -236,7 +244,7 @@ const resolveRcPRNumber = async (selectedVersion: string): Promise<number> => {
   }
 
   await runStep(
-    `create RC PR (dev → main) for v${selectedVersion}`,
+    `create RC PR (dev → main) for ${selectedLabel}`,
     `run 'gh pr create --base main --head dev' manually to surface the underlying error (e.g. no commits between dev and main)`,
     async () => {
       await $`gh pr create --base main --head dev --title ${expectedTitle} --body ""`
@@ -247,7 +255,7 @@ const resolveRcPRNumber = async (selectedVersion: string): Promise<number> => {
 
   if (!created) {
     throw new OperationError(undefined, {
-      operation: `look up RC PR for v${selectedVersion}`,
+      operation: `look up RC PR for ${selectedLabel}`,
       remediation: `verify the RC PR was created ('gh pr list --head dev --base main')`,
     })
   }
@@ -255,19 +263,20 @@ const resolveRcPRNumber = async (selectedVersion: string): Promise<number> => {
   return created.number
 }
 
-const ensureRcPRMerged = async (selectedVersion: string): Promise<void> => {
-  const alreadyMerged = await fetchMergedRcPRForVersion(selectedVersion)
+const ensureRcPRMerged = async (id: ReleaseId): Promise<void> => {
+  const selectedLabel = displayLabel(id)
+  const alreadyMerged = await fetchMergedRcPRForVersion(id)
 
   if (alreadyMerged) {
-    logger.info(`✓ RC PR for v${selectedVersion} already merged into main — skipping`)
+    logger.info(`✓ RC PR for ${selectedLabel} already merged into main — skipping`)
 
     return
   }
 
-  const rcNumber = await resolveRcPRNumber(selectedVersion)
+  const rcNumber = await resolveRcPRNumber(id)
 
   await runStep(
-    `merge RC PR #${rcNumber} (dev → main) for v${selectedVersion}`,
+    `merge RC PR #${rcNumber} (dev → main) for ${selectedLabel}`,
     `check 'gh pr view ${rcNumber}' for mergeability and required reviews`,
     async () => {
       await $`gh pr merge ${rcNumber} --squash --admin`
@@ -299,7 +308,7 @@ const syncMainIntoDev = async (): Promise<void> => {
   )
 }
 
-const deliverJiraReleaseSafely = async (selectedReleaseBranch: string): Promise<void> => {
+const deliverJiraReleaseSafely = async (id: ReleaseId): Promise<void> => {
   const jiraConfig = await loadJiraConfigOptional()
 
   if (!jiraConfig) {
@@ -309,7 +318,8 @@ const deliverJiraReleaseSafely = async (selectedReleaseBranch: string): Promise<
   }
 
   try {
-    const versionName = selectedReleaseBranch.replace('release/', '')
+    // Jira fix version name: `v1.2.3` | `<name>` — must match create-time formatJiraName.
+    const versionName = formatJiraName(id)
 
     await deliverJiraRelease({ versionName }, jiraConfig)
   } catch (error) {
@@ -333,9 +343,21 @@ export const ghReleaseDeliver = async (args: GhReleaseDeliverArgs) => {
     ? await resolveTargetFromVersion(version)
     : await resolveTargetInteractively()
 
-  const selectedVersion = selectedReleaseBranch.replace('release/v', '')
+  // selectedReleaseBranch is always a release branch (operator ref strictly
+  // parsed, or picked from discovery-filtered choices) so this cannot be null.
+  const releaseId = parseBranchName(selectedReleaseBranch)
+
+  if (!releaseId) {
+    throw new OperationError(undefined, {
+      operation: `deliver release ${selectedReleaseBranch}`,
+      remediation: 'pass a version (e.g. "1.2.5") or a release name (e.g. "checkout-redesign")',
+    })
+  }
+
+  const selectedVersion = displayLabel(releaseId)
 
   commandEcho.addOption('--version', selectedVersion)
+  logger.info(`Delivering ${releaseId.kind === 'name' ? 'named release' : 'version'} ${selectedReleaseBranch}`)
 
   const releaseType: ReleaseType = detectReleaseType(releasePrTitle)
 
@@ -363,7 +385,7 @@ export const ghReleaseDeliver = async (args: GhReleaseDeliverArgs) => {
   await mergeReleasePR({ selectedReleaseBranch, releaseType })
 
   if (releaseType !== 'hotfix') {
-    await ensureRcPRMerged(selectedVersion)
+    await ensureRcPRMerged(releaseId)
   }
 
   await dispatchDeployWorkflow()
@@ -371,7 +393,7 @@ export const ghReleaseDeliver = async (args: GhReleaseDeliverArgs) => {
 
   $.quiet = false
 
-  await deliverJiraReleaseSafely(selectedReleaseBranch)
+  await deliverJiraReleaseSafely(releaseId)
 
   logger.info(`Successfully delivered ${selectedReleaseBranch} to production!`)
 
@@ -396,7 +418,11 @@ export const ghReleaseDeliverMcpTool = defineMcpTool({
   description:
     'Deliver a release to production. For hotfixes: squash-merges the release branch to main and dispatches the deploy-all workflow. For regular releases: squash-merges to dev, opens an RC PR, merges dev into main, dispatches the deploy-all workflow, then syncs main back to dev. Also releases the matching Jira fix version if Jira is configured. Dispatches the deploy workflow fire-and-forget — the tool returns once the workflow is accepted by GitHub, not when the deployment finishes. PR-merge steps are idempotent: re-running after a partial failure skips PRs that are already merged. Irreversible production operation: the confirmation prompt is auto-skipped for MCP calls, so the caller is responsible for gating. "version" is required when invoked via MCP (the picker is unreachable without a TTY).',
   inputSchema: {
-    version: z.string().describe('Release version to deliver to production (e.g., "1.2.5"). Required for MCP calls.'),
+    version: z
+      .string()
+      .describe(
+        'Accepts a release version (e.g. "1.2.5") OR a release name (e.g. "checkout-redesign") to deliver to production. Required for MCP calls.',
+      ),
   },
   outputSchema: {
     releaseBranch: z.string().describe('The release branch that was delivered'),

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

@@ -1,5 +1,5 @@
 import select from '@inquirer/select'
-import { z } from 'zod/v4'
+import { z } from 'zod'
 import { $ } from 'zx'
 
 import { getReleasePRsWithInfo } from 'src/integrations/gh'
@@ -7,7 +7,13 @@ import { commandEcho } from 'src/lib/command-echo'
 import { OperationError } from 'src/lib/errors/operation-error'
 import { getInfraKitConfig } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
-import { detectReleaseType, formatBranchChoices, getJiraDescriptions } from 'src/lib/release-utils'
+import {
+  detectReleaseType,
+  formatBranchChoices,
+  getJiraDescriptions,
+  releaseLabelFromBranch,
+  resolveReleaseBranch,
+} from 'src/lib/release-utils'
 import type { ReleaseType } from 'src/lib/release-utils'
 import { defineMcpTool, textContent } from 'src/types'
 
@@ -25,10 +31,10 @@ export const ghReleaseDeployAll = async (args: GhReleaseDeployAllArgs) => {
 
   commandEcho.start('release-deploy-all')
 
-  let selectedReleaseBranch = '' // "release/v1.8.0"
+  let selectedReleaseBranch = '' // "release/v1.8.0" | "release/n/checkout-redesign" | "dev"
 
   if (version) {
-    selectedReleaseBranch = version === 'dev' ? 'dev' : `release/v${version}`
+    selectedReleaseBranch = version === 'dev' ? 'dev' : resolveReleaseBranch(version)
   } else {
     commandEcho.setInteractive()
 
@@ -52,7 +58,7 @@ export const ghReleaseDeployAll = async (args: GhReleaseDeployAllArgs) => {
     })
   }
 
-  const selectedVersion = selectedReleaseBranch === 'dev' ? 'dev' : selectedReleaseBranch.replace('release/v', '')
+  const selectedVersion = releaseLabelFromBranch(selectedReleaseBranch)
 
   commandEcho.addOption('--version', selectedVersion)
 
@@ -109,7 +115,7 @@ export const ghReleaseDeployAll = async (args: GhReleaseDeployAllArgs) => {
 
     const structuredContent = {
       releaseBranch: selectedReleaseBranch,
-      version: selectedReleaseBranch.replace('release/v', ''),
+      version: selectedVersion,
       environment: selectedEnv,
       skipTerraformDeploy: shouldSkipTerraform,
       success: true,
@@ -137,7 +143,7 @@ export const ghReleaseDeployAllMcpTool = defineMcpTool({
     version: z
       .string()
       .describe(
-        'Release version to deploy from (e.g. "1.2.5") — resolves to the release/vX.Y.Z branch. Pass "dev" to deploy from the dev branch instead. Required for MCP calls.',
+        'Accepts a release version (e.g. "1.2.5") OR a release name (e.g. "checkout-redesign") — resolves to the release/vX.Y.Z or release/n/<name> branch. Pass "dev" to deploy from the dev branch instead. Required for MCP calls.',
       ),
     env: z
       .string()

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

@@ -3,7 +3,7 @@ import select from '@inquirer/select'
 import fs from 'node:fs/promises'
 import { resolve } from 'node:path'
 import yaml from 'yaml'
-import { z } from 'zod/v4'
+import { z } from 'zod'
 import { $ } from 'zx'
 
 import { getReleasePRsWithInfo } from 'src/integrations/gh'
@@ -12,7 +12,13 @@ import { OperationError } from 'src/lib/errors/operation-error'
 import { getProjectRoot } from 'src/lib/git-utils'
 import { getInfraKitConfig } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
-import { detectReleaseType, formatBranchChoices, getJiraDescriptions } from 'src/lib/release-utils'
+import {
+  detectReleaseType,
+  formatBranchChoices,
+  getJiraDescriptions,
+  releaseLabelFromBranch,
+  resolveReleaseBranch,
+} from 'src/lib/release-utils'
 import type { ReleaseType } from 'src/lib/release-utils'
 import { defineMcpTool, textContent } from 'src/types'
 
@@ -35,7 +41,7 @@ export const ghReleaseDeploySelected = async (args: GhReleaseDeploySelectedArgs)
   let selectedReleaseBranch = ''
 
   if (version) {
-    selectedReleaseBranch = version === 'dev' ? 'dev' : `release/v${version}`
+    selectedReleaseBranch = version === 'dev' ? 'dev' : resolveReleaseBranch(version)
   } else {
     commandEcho.setInteractive()
 
@@ -59,7 +65,7 @@ export const ghReleaseDeploySelected = async (args: GhReleaseDeploySelectedArgs)
     })
   }
 
-  const selectedVersion = selectedReleaseBranch === 'dev' ? 'dev' : selectedReleaseBranch.replace('release/v', '')
+  const selectedVersion = releaseLabelFromBranch(selectedReleaseBranch)
 
   commandEcho.addOption('--version', selectedVersion)
 
@@ -172,7 +178,7 @@ export const ghReleaseDeploySelected = async (args: GhReleaseDeploySelectedArgs)
 
     const structuredContent = {
       releaseBranch: selectedReleaseBranch,
-      version: selectedReleaseBranch.replace('release/v', ''),
+      version: selectedVersion,
       environment: selectedEnv,
       services: selectedServices,
       skipTerraformDeploy: shouldSkipTerraform,
@@ -226,7 +232,7 @@ export const ghReleaseDeploySelectedMcpTool = defineMcpTool({
     version: z
       .string()
       .describe(
-        'Release version to deploy from (e.g. "1.2.5") — resolves to the release/vX.Y.Z branch. Pass "dev" to deploy from the dev branch instead. Required for MCP calls.',
+        'Accepts a release version (e.g. "1.2.5") OR a release name (e.g. "checkout-redesign") — resolves to the release/vX.Y.Z or release/n/<name> branch. Pass "dev" to deploy from the dev branch instead. Required for MCP calls.',
       ),
     env: z
       .string()

package/src/commands/gh-release-list/gh-release-list.ts

@@ -1,7 +1,8 @@
-import { z } from 'zod/v4'
+import { z } from 'zod'
 
 import { getReleasePRsWithInfo } from 'src/integrations/gh'
 import { logger } from 'src/lib/logger'
+import { displayLabel, formatJiraName, parseBranchName } from 'src/lib/release-id'
 import { detectReleaseType, formatVersionLabel, getJiraDescriptions } from 'src/lib/release-utils'
 import { defineMcpTool, textContent } from 'src/types'
 
@@ -11,11 +12,21 @@ import { defineMcpTool, textContent } from 'src/types'
 export const ghReleaseList = async () => {
   const releasePRs = await getReleasePRsWithInfo()
 
-  const releases = releasePRs.map((pr) => {
-    return {
-      version: pr.branch.replace('release/', ''),
-      type: detectReleaseType(pr.title),
-    }
+  // Skip branches that do not parse as release ids (lenient discovery source).
+  const releases = releasePRs.flatMap((pr) => {
+    const id = parseBranchName(pr.branch)
+
+    if (!id) return []
+
+    return [
+      {
+        // Human display label: `1.2.3` | `<name>`.
+        version: displayLabel(id),
+        // Jira-descriptions map is keyed by the Jira version NAME (`v1.2.3` | `<name>`).
+        jiraKey: formatJiraName(id),
+        type: detectReleaseType(pr.title),
+      },
+    ]
   })
 
   const jiraDescriptions = await getJiraDescriptions()
@@ -28,7 +39,7 @@ export const ghReleaseList = async () => {
 
   const formattedLines = releases.map((release) => {
     const label = formatVersionLabel(release.version, release.type, maxVersionLength)
-    const description = jiraDescriptions.get(release.version)
+    const description = jiraDescriptions.get(release.jiraKey)
 
     if (description) {
       return `${label}  ${description}`
@@ -45,7 +56,7 @@ export const ghReleaseList = async () => {
       return {
         version: release.version,
         type: release.type,
-        description: jiraDescriptions.get(release.version) || null,
+        description: jiraDescriptions.get(release.jiraKey) || null,
       }
     }),
     count: releases.length,

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

@@ -0,0 +1,160 @@
+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 AFTER the mock is declared so the module picks up the mocked dep.
+import { getProjectRoot, getRepoName } from 'src/lib/git-utils'
+
+import { migrateLegacyConfig } from '../migrate-config'
+
+vi.mock('src/lib/git-utils', () => {
+  return {
+    getProjectRoot: vi.fn(),
+    getRepoName: vi.fn(),
+  }
+})
+
+const MAIN_YML = `environments:
+  - dev
+  - staging
+envManagement:
+  provider: doppler
+  config:
+    name: my-project
+`
+
+const writeFile = (filePath: string, content: string): void => {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, content, 'utf-8')
+}
+
+const withTmpRepo = async (fn: (tmp: string) => Promise<void>): Promise<void> => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'infra-kit-init-migrate-test-'))
+
+  vi.mocked(getProjectRoot).mockResolvedValue(tmp)
+  vi.mocked(getRepoName).mockResolvedValue(path.basename(tmp))
+  const homedirSpy = vi.spyOn(os, 'homedir').mockReturnValue(tmp)
+
+  try {
+    await fn(tmp)
+  } finally {
+    homedirSpy.mockRestore()
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
+describe('migrateLegacyConfig', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('converts a legacy infra-kit.yml to infra-kit.json and removes the .yml', async () => {
+    await withTmpRepo(async (tmp) => {
+      const ymlPath = path.join(tmp, 'infra-kit.yml')
+      const jsonPath = path.join(tmp, 'infra-kit.json')
+
+      writeFile(ymlPath, MAIN_YML)
+
+      await migrateLegacyConfig()
+
+      expect(fs.existsSync(ymlPath)).toBe(false)
+      expect(fs.existsSync(jsonPath)).toBe(true)
+      expect(JSON.parse(fs.readFileSync(jsonPath, 'utf-8'))).toEqual({
+        environments: ['dev', 'staging'],
+        envManagement: { provider: 'doppler', config: { name: 'my-project' } },
+      })
+    })
+  })
+
+  it('is an idempotent no-op when the config is already JSON', async () => {
+    await withTmpRepo(async (tmp) => {
+      const jsonPath = path.join(tmp, 'infra-kit.json')
+      const json = '{"environments":["dev"],"envManagement":{"provider":"doppler","config":{"name":"p"}}}'
+
+      writeFile(jsonPath, json)
+
+      await expect(migrateLegacyConfig()).resolves.toBeUndefined()
+
+      expect(fs.readFileSync(jsonPath, 'utf-8')).toBe(json)
+    })
+  })
+
+  it('warns and skips (does not throw or overwrite) when both .yml and .json exist', async () => {
+    await withTmpRepo(async (tmp) => {
+      const ymlPath = path.join(tmp, 'infra-kit.yml')
+      const jsonPath = path.join(tmp, 'infra-kit.json')
+      const existingJson = '{"environments":["keep"],"envManagement":{"provider":"doppler","config":{"name":"keep"}}}'
+
+      writeFile(ymlPath, MAIN_YML)
+      writeFile(jsonPath, existingJson)
+
+      await expect(migrateLegacyConfig()).resolves.toBeUndefined()
+
+      // Conflict left untouched — no overwrite, .yml preserved.
+      expect(fs.existsSync(ymlPath)).toBe(true)
+      expect(fs.readFileSync(jsonPath, 'utf-8')).toBe(existingJson)
+    })
+  })
+
+  it('skips an invalid layer but still converts a valid sibling layer (non-fatal, per-layer)', async () => {
+    await withTmpRepo(async (tmp) => {
+      const mainYml = path.join(tmp, 'infra-kit.yml')
+      const mainJson = path.join(tmp, 'infra-kit.json')
+      const userGlobalYml = path.join(tmp, '.infra-kit', 'config.yml')
+      const userGlobalJson = path.join(tmp, '.infra-kit', 'config.json')
+
+      writeFile(mainYml, MAIN_YML)
+      // Invalid override: environments present but empty (min(1) fails).
+      writeFile(userGlobalYml, 'environments: []\n')
+
+      await expect(migrateLegacyConfig()).resolves.toBeUndefined()
+
+      // Valid main layer converted…
+      expect(fs.existsSync(mainYml)).toBe(false)
+      expect(fs.existsSync(mainJson)).toBe(true)
+      // …invalid user-global layer left as-is (no JSON written).
+      expect(fs.existsSync(userGlobalYml)).toBe(true)
+      expect(fs.existsSync(userGlobalJson)).toBe(false)
+    })
+  })
+
+  it('warns and skips a malformed .yml without throwing', async () => {
+    await withTmpRepo(async (tmp) => {
+      const ymlPath = path.join(tmp, 'infra-kit.yml')
+      const jsonPath = path.join(tmp, 'infra-kit.json')
+
+      // Unparseable YAML (bad indentation / flow) — yaml.parse throws.
+      writeFile(ymlPath, 'environments: [dev\n  : : :\n')
+
+      await expect(migrateLegacyConfig()).resolves.toBeUndefined()
+
+      expect(fs.existsSync(ymlPath)).toBe(true)
+      expect(fs.existsSync(jsonPath)).toBe(false)
+    })
+  })
+
+  it('converts all three merge-chain layers in one run', async () => {
+    await withTmpRepo(async (tmp) => {
+      const projectName = path.basename(tmp)
+      const mainYml = path.join(tmp, 'infra-kit.yml')
+      const userGlobalYml = path.join(tmp, '.infra-kit', 'config.yml')
+      const userProjectYml = path.join(tmp, '.infra-kit', 'projects', projectName, 'infra-kit.yml')
+
+      writeFile(mainYml, MAIN_YML)
+      writeFile(userGlobalYml, 'worktrees:\n  openInCmux: true\n')
+      writeFile(userProjectYml, 'worktrees:\n  openInGithubDesktop: false\n')
+
+      await migrateLegacyConfig()
+
+      for (const yml of [mainYml, userGlobalYml, userProjectYml]) {
+        expect(fs.existsSync(yml)).toBe(false)
+        expect(fs.existsSync(yml.replace(/\.yml$/, '.json'))).toBe(true)
+      }
+    })
+  })
+})

package/src/commands/init/init.ts

@@ -4,49 +4,53 @@ import path from 'node:path'
 
 import { logger } from 'src/lib/logger'
 
+import { migrateLegacyConfig } from './migrate-config'
+
 export const MARKER_START = '# -- infra-kit:begin --'
 export const MARKER_END = '# -- infra-kit:end --'
 
 const LEGACY_PAIRED: [start: string, end: string][] = [['# region infra-kit', '# endregion infra-kit']]
 const LEGACY_SINGLE = '# infra-kit shell functions'
 
-const USER_GLOBAL_CONFIG_STUB = `# infra-kit user-global config — ~/.infra-kit/config.yml
-#
-# Merge chain (later layers override earlier ones at top-level keys):
-#   1. <repo>/infra-kit.yml                            — committed project config (required)
-#   2. ~/.infra-kit/config.yml                         — this file (user-global)
-#   3. ~/.infra-kit/projects/<repo-name>/infra-kit.yml — user-scope per-project override
-#
-# Merge is shallow: setting a top-level key here replaces that whole section
-# from layer 1. Arrays do not concatenate. Top-level keys recognized:
-# environments, envManagement, ide, taskManager, worktrees.
-#
-# Uncomment the blocks you want to apply globally across every project on this
-# machine. Per-project tweaks belong in layer 3 — run \`infra-kit config edit\`.
-
-# Per-developer IDE config
-# ide:
-#   provider: cursor
-#   config:
-#     mode: workspace
-#     workspaceConfigPath: /path/to/your.code-workspace
-
-# Worktree prompt defaults — silences the follow-up prompts in \`worktrees-add\`
-# worktrees:
-#   openInGithubDesktop: false
-#   openInCmux: true
+// JSON can't carry comments, so the real config is an empty-but-valid object…
+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
+//
+// 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)
+//   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.
+//
+// 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
+// keys). Per-project tweaks belong in layer 3 — run \`infra-kit config edit\`.
+{
+  // "ide": {
+  //   "provider": "cursor",
+  //   "config": { "mode": "workspace", "workspaceConfigPath": "/path/to/your.code-workspace" }
+  // },
+  // "worktrees": { "openInGithubDesktop": false, "openInCmux": true }
+}
 `
 
 /**
- * Append infra-kit shell functions to .zshrc and seed the user-global
- * config stub at ~/.infra-kit/config.yml on first run. Idempotent: a
- * subsequent run replaces the existing zshrc block in place and leaves
+ * Append infra-kit shell functions to .zshrc, migrate any legacy
+ * `infra-kit.yml` config layers to JSON, 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, and leaves
  * the user-global config untouched.
  *
  * @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 stub to /Users/me/.infra-kit/config.yml
+ * // INFO: Wrote user-global config to /Users/me/.infra-kit/config.json (see …/config.example.jsonc …)
  * // INFO: Run `source ~/.zshrc` or open a new terminal to activate.
  */
 export const init = async (): Promise<void> => {
@@ -63,23 +67,29 @@ export const init = async (): Promise<void> => {
   fs.appendFileSync(zshrcPath, `\n${shellBlock}\n`)
   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.
+  await migrateLegacyConfig()
+
   seedUserGlobalConfig()
 
   logger.info('Run `source ~/.zshrc` or open a new terminal to activate.')
 }
 
 /**
- * Create `~/.infra-kit/config.yml` with the documented stub when absent.
- * Skips silently if the file already exists so user edits are preserved.
+ * 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.
  *
  * @example
  * seedUserGlobalConfig()
- * // first call:  writes ~/.infra-kit/config.yml from USER_GLOBAL_CONFIG_STUB
- * // later calls: leaves the file alone, logs that it is already present
+ * // first call:  writes ~/.infra-kit/config.json ({}) + config.example.jsonc
+ * // later calls: leaves the config alone, logs that it is already present
  */
 const seedUserGlobalConfig = (): void => {
   const userConfigDir = path.join(os.homedir(), '.infra-kit')
-  const userConfigPath = path.join(userConfigDir, 'config.yml')
+  const userConfigPath = path.join(userConfigDir, 'config.json')
+  const userConfigExamplePath = path.join(userConfigDir, 'config.example.jsonc')
 
   if (fs.existsSync(userConfigPath)) {
     logger.info(`User-global config already present at ${userConfigPath}`)
@@ -89,8 +99,11 @@ const seedUserGlobalConfig = (): void => {
 
   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 stub to ${userConfigPath}`)
+  logger.info(
+    `Wrote user-global config to ${userConfigPath} (see ${userConfigExamplePath} for the annotated reference)`,
+  )
 }
 
 const isBlockLine = (line: string): boolean => {