infra-kit 0.1.97 → 0.1.98

package/src/entry/cli.ts

@@ -2,6 +2,7 @@ import select, { Separator } from '@inquirer/select'
 import { Command, Option } from 'commander'
 import process from 'node:process'
 
+import { configEdit, configPath } from 'src/commands/config'
 import { doctor } from 'src/commands/doctor'
 import { envClear } from 'src/commands/env-clear'
 import { envList } from 'src/commands/env-list'
@@ -80,25 +81,29 @@ program
 program
   .command('release-create')
   .description('Create a single release branch')
-  .option('-v, --version <version>', 'Specify the version to create, e.g. 1.2.5')
+  .option(
+    '-v, --version <version>',
+    'Version to create, e.g. "1.2.5", "next", or "next,next,1.2.7" (multi-value routes to batch)',
+  )
   .option('-d, --description <description>', 'Optional description for the Jira version')
   .addOption(new Option('-t, --type <type>', 'Release type (default: regular)').choices(['regular', 'hotfix']))
   .option('-y, --yes', 'Skip confirmation prompt')
-  .option('--no-checkout', 'Do not checkout the created branch after creation (checkout is default)')
   .action(async (options) => {
     await releaseCreate({
       version: options.version,
       description: options.description,
       type: options.type,
       confirmedCommand: options.yes,
-      checkout: options.checkout,
     })
   })
 
 program
   .command('release-create-batch')
   .description('Create multiple release branches (batch operation)')
-  .option('-v, --versions <versions>', 'Specify the versions to create by comma, e.g. 1.2.5, 1.2.6')
+  .option(
+    '-v, --versions <versions>',
+    'Comma-separated versions, e.g. "1.2.5, 1.2.6", "next,next", or "next,next,1.2.7"',
+  )
   .addOption(new Option('-t, --type <type>', 'Release type (default: regular)').choices(['regular', 'hotfix']))
   .option('-y, --yes', 'Skip confirmation prompt')
   .action(async (options) => {
@@ -199,6 +204,22 @@ program
     await worktreesOpen()
   })
 
+const configCmd = program.command('config').description('Manage infra-kit configuration files')
+
+configCmd
+  .command('path')
+  .description('Show the resolved config merge chain and file paths')
+  .action(async () => {
+    await configPath()
+  })
+
+configCmd
+  .command('edit')
+  .description('Open the user-scope per-project override file in $EDITOR')
+  .action(async () => {
+    await configEdit()
+  })
+
 program
   .command('doctor')
   .description('Check installation and authentication status of gh and doppler CLIs')
@@ -260,7 +281,7 @@ if (process.argv.length <= 2) {
     'release-deliver',
   ]
   const worktreeCommands = ['worktrees-add', 'worktrees-list', 'worktrees-open', 'worktrees-remove', 'worktrees-sync']
-  const envCommands = ['doctor', 'init', 'version', 'env-status', 'env-list', 'env-load', 'env-clear']
+  const envCommands = ['doctor', 'init', 'version', 'config', 'env-status', 'env-list', 'env-load', 'env-clear']
 
   const commandMap = new Map(
     program.commands.map((cmd) => {

package/src/lib/__tests__/infra-kit-config.test.ts

@@ -4,13 +4,14 @@ 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 } from 'src/lib/git-utils'
+import { getProjectRoot, getRepoName } from 'src/lib/git-utils'
 
 import { getInfraKitConfig, resetInfraKitConfigCache } from '../infra-kit-config'
 
 vi.mock('src/lib/git-utils', () => {
   return {
     getProjectRoot: vi.fn(),
+    getRepoName: vi.fn(),
   }
 })
 
@@ -35,6 +36,7 @@ const withTmpRepo = async (fn: (tmp: string) => Promise<void>): Promise<void> =>
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'infra-kit-config-test-'))
 
   vi.mocked(getProjectRoot).mockResolvedValue(tmp)
+  vi.mocked(getRepoName).mockResolvedValue(path.basename(tmp))
   resetInfraKitConfigCache()
 
   try {

package/src/lib/infra-kit-config/index.ts

@@ -1,2 +1,2 @@
-export { getInfraKitConfig, resetInfraKitConfigCache } from './infra-kit-config'
-export type { InfraKitConfig } from './infra-kit-config'
+export { getInfraKitConfig, getInfraKitConfigPaths, resetInfraKitConfigCache } from './infra-kit-config'
+export type { InfraKitConfig, InfraKitConfigPaths } from './infra-kit-config'

package/src/lib/infra-kit-config/infra-kit-config.ts

@@ -1,12 +1,16 @@
 import fs from 'node:fs/promises'
+import os from 'node:os'
 import path from 'node:path'
 import yaml from 'yaml'
 import { z } from 'zod/v4'
 
-import { getProjectRoot } from 'src/lib/git-utils'
+import { getProjectRoot, getRepoName } from 'src/lib/git-utils'
 
 const INFRA_KIT_CONFIG_FILE = 'infra-kit.yml'
-const INFRA_KIT_LOCAL_CONFIG_FILE = 'infra-kit.local.yml'
+
+const USER_CONFIG_DIR_NAME = '.infra-kit'
+const USER_GLOBAL_CONFIG_FILE = 'config.yml'
+const USER_PROJECTS_DIR = 'projects'
 
 // envManagement
 const dopplerEnvManagementSchema = z.object({
@@ -59,81 +63,148 @@ const infraKitConfigSchema = z.object({
   taskManager: taskManagerSchema.optional(),
 })
 
-const infraKitLocalConfigSchema = infraKitConfigSchema.partial()
+const infraKitOverrideConfigSchema = infraKitConfigSchema.partial()
 
 export type InfraKitConfig = z.infer<typeof infraKitConfigSchema>
 
+export interface InfraKitConfigPaths {
+  /** Committed project config (required). */
+  main: string
+  /** User-scope global overrides applied to every project. */
+  userGlobal: string
+  /** User-scope per-project overrides — `<userProjectsDir>/<projectName>/infra-kit.yml`. */
+  userProject: string
+  /** Repo basename (`path.basename(projectRoot)`) used to namespace the user-project file. */
+  projectName: string
+}
+
 interface CacheEntry {
-  mainMtimeMs: number
-  localMtimeMs: number | null
+  mtimes: Record<keyof Omit<InfraKitConfigPaths, 'projectName'>, number | null>
   value: InfraKitConfig
 }
 
 let cached: CacheEntry | null = null
 
 /**
- * Read and validate `infra-kit.yml`, with optional `infra-kit.local.yml` overrides
- * shallow-merged on top (per-developer, gitignored). Top-level keys (entire
- * capability sections like `ide`, `envManagement`) replace wholesale. Results are
- * cached per file mtimes so the long-running MCP server picks up edits without a
- * restart.
+ * Resolve every file path that participates in the config merge chain. Always
+ * returns paths even for files that don't yet exist, so callers can use them
+ * for "where would my override go?" prompts.
+ *
+ * @example
+ * const paths = await getInfraKitConfigPaths()
+ * // {
+ * //   main:        '/Users/arthur/projects/api/infra-kit.yml',
+ * //   userGlobal:  '/Users/arthur/.infra-kit/config.yml',
+ * //   userProject: '/Users/arthur/.infra-kit/projects/api/infra-kit.yml',
+ * //   projectName: 'api',
+ * // }
  */
-export const getInfraKitConfig = async (): Promise<InfraKitConfig> => {
+export const getInfraKitConfigPaths = async (): Promise<InfraKitConfigPaths> => {
   const projectRoot = await getProjectRoot()
-  const mainPath = path.join(projectRoot, INFRA_KIT_CONFIG_FILE)
-  const localPath = path.join(projectRoot, INFRA_KIT_LOCAL_CONFIG_FILE)
+  const projectName = await getRepoName()
+  const userConfigDir = path.join(os.homedir(), USER_CONFIG_DIR_NAME)
+
+  return {
+    main: path.join(projectRoot, INFRA_KIT_CONFIG_FILE),
+    userGlobal: path.join(userConfigDir, USER_GLOBAL_CONFIG_FILE),
+    userProject: path.join(userConfigDir, USER_PROJECTS_DIR, projectName, INFRA_KIT_CONFIG_FILE),
+    projectName,
+  }
+}
+
+/**
+ * Read and validate `infra-kit.yml`, with optional override layers shallow-merged
+ * on top in this order (later wins):
+ *   1. project `infra-kit.yml`                            — committed source of truth
+ *   2. `~/.infra-kit/config.yml`                          — user-global defaults
+ *   3. `~/.infra-kit/projects/<repo-name>/infra-kit.yml`  — user-scope per-project overrides
+ *
+ * Top-level keys (entire capability sections like `ide`, `envManagement`)
+ * replace wholesale. Results are cached per file mtimes so the long-running
+ * MCP server picks up edits without a restart.
+ *
+ * @example
+ * // infra-kit.yml:           { environments: ['dev'], envManagement: { provider: 'doppler', config: { name: 'p' } } }
+ * // ~/.infra-kit/config.yml: { ide: { provider: 'cursor', config: { mode: 'windows' } } }
+ * const cfg = await getInfraKitConfig()
+ * // => { environments: ['dev'], envManagement: {...}, ide: { provider: 'cursor', config: { mode: 'windows' } } }
+ */
+export const getInfraKitConfig = async (): Promise<InfraKitConfig> => {
+  const paths = await getInfraKitConfigPaths()
 
   let mainStat: Awaited<ReturnType<typeof fs.stat>>
 
   try {
-    mainStat = await fs.stat(mainPath)
+    mainStat = await fs.stat(paths.main)
   } catch {
     cached = null
-    throw new Error(`infra-kit.yml not found at ${mainPath}`)
+    throw new Error(`infra-kit.yml not found at ${paths.main}`)
   }
 
-  const localStat = await statIfExists(localPath)
-  const mainMtimeMs = Number(mainStat.mtimeMs)
-  const localMtimeMs = localStat ? Number(localStat.mtimeMs) : null
+  const [userGlobalStat, userProjectStat] = await Promise.all([
+    statIfExists(paths.userGlobal),
+    statIfExists(paths.userProject),
+  ])
 
-  if (cached && cached.mainMtimeMs === mainMtimeMs && cached.localMtimeMs === localMtimeMs) {
-    return cached.value
+  const mtimes = {
+    main: Number(mainStat.mtimeMs),
+    userGlobal: userGlobalStat ? Number(userGlobalStat.mtimeMs) : null,
+    userProject: userProjectStat ? Number(userProjectStat.mtimeMs) : null,
   }
 
-  const mainRaw = await fs.readFile(mainPath, 'utf-8')
-  const mainParsed = yaml.parse(mainRaw)
+  if (cached && shallowEqual(cached.mtimes, mtimes)) {
+    return cached.value
+  }
 
-  let merged: unknown = mainParsed
+  const layers: ConfigLayer[] = [
+    { label: 'infra-kit.yml', path: paths.main, required: true },
+    { label: '~/.infra-kit/config.yml', path: paths.userGlobal, required: false },
+    {
+      label: `~/.infra-kit/projects/${paths.projectName}/infra-kit.yml`,
+      path: paths.userProject,
+      required: false,
+    },
+  ]
 
-  if (localStat) {
-    const localRaw = await fs.readFile(localPath, 'utf-8')
-    const localParsedRaw = yaml.parse(localRaw) ?? {}
+  let merged: Record<string, unknown> = {}
 
-    const localResult = infraKitLocalConfigSchema.safeParse(localParsedRaw)
+  for (const layer of layers) {
+    const data = await loadLayer(layer)
 
-    if (!localResult.success) {
-      throw new Error(`Invalid infra-kit.local.yml at ${localPath}: ${z.prettifyError(localResult.error)}`)
-    }
+    if (data === null) continue
 
-    merged = { ...(mainParsed as object), ...localResult.data }
+    merged = { ...merged, ...data }
   }
 
-  const result = infraKitConfigSchema.safeParse(merged)
+  const finalResult = infraKitConfigSchema.safeParse(merged)
 
-  if (!result.success) {
-    throw new Error(`Invalid infra-kit.yml at ${mainPath}: ${z.prettifyError(result.error)}`)
+  if (!finalResult.success) {
+    throw new Error(`Invalid merged infra-kit config: ${z.prettifyError(finalResult.error)}`)
   }
 
-  cached = { mainMtimeMs, localMtimeMs, value: result.data }
+  cached = { mtimes, value: finalResult.data }
 
-  return result.data
+  return finalResult.data
 }
 
-/** For tests — drops the in-memory cache. */
+/**
+ * For tests — drops the in-memory cache so the next read hits disk.
+ *
+ * @example
+ * resetInfraKitConfigCache()
+ * await getInfraKitConfig() // re-reads files even if mtimes look unchanged
+ */
 export const resetInfraKitConfigCache = (): void => {
   cached = null
 }
 
+/**
+ * `fs.stat` that returns `null` instead of throwing on ENOENT. Used so the
+ * resolver can probe optional files in the merge chain without try/catch noise.
+ *
+ * @example
+ * const stat = await statIfExists('/does/not/exist') // => null
+ */
 const statIfExists = async (filePath: string): Promise<Awaited<ReturnType<typeof fs.stat>> | null> => {
   try {
     return await fs.stat(filePath)
@@ -141,3 +212,78 @@ const statIfExists = async (filePath: string): Promise<Awaited<ReturnType<typeof
     return null
   }
 }
+
+/**
+ * `fs.readFile` that returns `null` instead of throwing on ENOENT.
+ *
+ * @example
+ * const raw = await readIfExists('/missing.yml') // => null
+ * const raw = await readIfExists('/exists.yml')  // => 'environments: [dev]\n'
+ */
+const readIfExists = async (filePath: string): Promise<string | null> => {
+  try {
+    return await fs.readFile(filePath, 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Reference-equality comparison of every key in two flat records. Used to
+ * cheaply detect whether the cached mtime fingerprint still matches.
+ *
+ * @example
+ * shallowEqual({ a: 1, b: 2 }, { a: 1, b: 2 }) // => true
+ * shallowEqual({ a: 1 },       { a: 1, b: 2 }) // => false
+ * shallowEqual({ a: 1 },       { a: 2 })       // => false
+ */
+const shallowEqual = <T extends Record<string, unknown>>(a: T, b: T): boolean => {
+  const keys = Object.keys(a)
+
+  if (keys.length !== Object.keys(b).length) return false
+
+  return keys.every((k) => {
+    return a[k] === b[k]
+  })
+}
+
+interface ConfigLayer {
+  label: string
+  path: string
+  required: boolean
+}
+
+/**
+ * Read a single layer of the merge chain: parse the YAML if the file exists
+ * and validate it against the override schema. Returns `null` if an optional
+ * layer is missing; throws if the layer is required or invalid.
+ *
+ * @example
+ * await loadLayer({ label: '~/.infra-kit/config.yml', path: '/missing.yml', required: false })
+ * // => null
+ *
+ * @example
+ * // /home/me/.infra-kit/config.yml: 'ide:\n  provider: cursor\n  config: { mode: windows }'
+ * await loadLayer({ label: '~/.infra-kit/config.yml', path: '/home/me/.infra-kit/config.yml', required: false })
+ * // => { ide: { provider: 'cursor', config: { mode: 'windows' } } }
+ */
+const loadLayer = async (layer: ConfigLayer): Promise<Record<string, unknown> | null> => {
+  const raw = await readIfExists(layer.path)
+
+  if (raw === null) {
+    if (layer.required) {
+      throw new Error(`${layer.label} not found at ${layer.path}`)
+    }
+
+    return null
+  }
+
+  const parsedRaw = yaml.parse(raw) ?? {}
+  const result = infraKitOverrideConfigSchema.safeParse(parsedRaw)
+
+  if (!result.success) {
+    throw new Error(`Invalid ${layer.label} at ${layer.path}: ${z.prettifyError(result.error)}`)
+  }
+
+  return result.data as Record<string, unknown>
+}

package/src/lib/version-utils/__tests__/next-version.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  NoPriorVersionsError,
+  collectKnownVersions,
+  computeNextVersion,
+  resolveVersionTokens,
+  splitVersionInput,
+} from '../next-version'
+
+describe('collectKnownVersions', () => {
+  it('parses remote branch refs and Jira version names and dedupes', () => {
+    const known = collectKnownVersions({
+      remoteBranches: ['release/v1.62.0', 'refs/heads/release/v1.63.0', 'release/v1.62.0'],
+      jiraVersions: ['v1.63.0', 'v1.64.5'],
+    })
+
+    expect(known).toEqual([
+      [1, 62, 0],
+      [1, 63, 0],
+      [1, 64, 5],
+    ])
+  })
+
+  it('ignores non-semver inputs', () => {
+    const known = collectKnownVersions({
+      remoteBranches: ['release/v1.62.0', 'release/v-bogus', 'main'],
+      jiraVersions: ['v1.63.0', 'random-name'],
+    })
+
+    expect(known).toEqual([
+      [1, 62, 0],
+      [1, 63, 0],
+    ])
+  })
+
+  it('returns [] when sources are empty or undefined', () => {
+    expect(collectKnownVersions({})).toEqual([])
+    expect(collectKnownVersions({ remoteBranches: [], jiraVersions: [] })).toEqual([])
+  })
+})
+
+describe('computeNextVersion', () => {
+  it('regular bumps minor and resets patch', () => {
+    const known = collectKnownVersions({ remoteBranches: ['release/v1.63.5', 'release/v1.62.0'] })
+
+    expect(computeNextVersion(known, 'regular')).toBe('1.64.0')
+  })
+
+  it('hotfix bumps patch on the highest minor (any patch)', () => {
+    const known = collectKnownVersions({
+      remoteBranches: ['release/v1.63.5', 'release/v1.63.0', 'release/v1.62.0'],
+    })
+
+    expect(computeNextVersion(known, 'hotfix')).toBe('1.63.6')
+  })
+
+  it('hotfix uses the highest minor even when patch chain has gaps', () => {
+    const known = collectKnownVersions({
+      remoteBranches: ['release/v1.55.10', 'release/v1.55.20', 'release/v1.55.30'],
+    })
+
+    expect(computeNextVersion(known, 'hotfix')).toBe('1.55.31')
+  })
+
+  it('throws NoPriorVersionsError when there are no known versions', () => {
+    expect(() => {
+      return computeNextVersion([], 'regular')
+    }).toThrow(NoPriorVersionsError)
+  })
+})
+
+describe('resolveVersionTokens', () => {
+  const known = collectKnownVersions({ remoteBranches: ['release/v1.63.0'] })
+
+  it('resolves "next,next" sequentially for regular', () => {
+    expect(resolveVersionTokens(['next', 'next'], 'regular', known)).toEqual(['1.64.0', '1.65.0'])
+  })
+
+  it('mixes literals and next, advancing running max', () => {
+    expect(resolveVersionTokens(['next', '1.70.0', 'next'], 'regular', known)).toEqual(['1.64.0', '1.70.0', '1.71.0'])
+  })
+
+  it('accepts NEXT and " next " (case + whitespace insensitive)', () => {
+    expect(resolveVersionTokens(['NEXT', ' next '], 'regular', known)).toEqual(['1.64.0', '1.65.0'])
+  })
+
+  it('strips leading v on explicit versions', () => {
+    expect(resolveVersionTokens(['v1.70.0'], 'regular', known)).toEqual(['1.70.0'])
+  })
+
+  it('throws on invalid token', () => {
+    expect(() => {
+      return resolveVersionTokens(['nope'], 'regular', known)
+    }).toThrow(/Invalid version/)
+  })
+
+  it('hotfix sequence advances patch each step', () => {
+    expect(resolveVersionTokens(['next', 'next'], 'hotfix', known)).toEqual(['1.63.1', '1.63.2'])
+  })
+})
+
+describe('splitVersionInput', () => {
+  it('splits comma-separated input and trims', () => {
+    expect(splitVersionInput(' 1.2.3 , next, ,1.2.4 ')).toEqual(['1.2.3', 'next', '1.2.4'])
+  })
+
+  it('returns empty array for empty input', () => {
+    expect(splitVersionInput('')).toEqual([])
+    expect(splitVersionInput('   ')).toEqual([])
+  })
+})

package/src/lib/version-utils/index.ts

@@ -1 +1,12 @@
+export { loadExistingVersions } from './load-existing-versions'
+export {
+  collectKnownVersions,
+  computeNextVersion,
+  type ExistingVersionsSources,
+  NEXT_TOKEN,
+  NoPriorVersionsError,
+  resolveVersionTokens,
+  type SemVer,
+  splitVersionInput,
+} from './next-version'
 export { parseVersion, sortVersions } from './version-utils'

package/src/lib/version-utils/load-existing-versions.ts

@@ -0,0 +1,67 @@
+import { $ } from 'zx'
+
+import { getProjectVersions, loadJiraConfigOptional } from 'src/integrations/jira'
+import { logger } from 'src/lib/logger'
+
+import { collectKnownVersions } from './next-version'
+import type { SemVer } from './next-version'
+
+const parseRemoteRefs = async (): Promise<string[]> => {
+  const previousQuiet = $.quiet
+
+  try {
+    $.quiet = true
+    const result = await $`git ls-remote --heads origin 'release/v*'`
+    const lines = result.stdout.split('\n')
+
+    return lines
+      .map((line) => {
+        const tab = line.indexOf('\t')
+
+        if (tab === -1) return ''
+
+        return line.slice(tab + 1).replace(/^refs\/heads\//, '')
+      })
+      .filter(Boolean)
+  } finally {
+    $.quiet = previousQuiet
+  }
+}
+
+const fetchJiraVersionNames = async (): Promise<string[]> => {
+  const config = await loadJiraConfigOptional()
+
+  if (!config) return []
+
+  const versions = await getProjectVersions(config)
+
+  return versions.map((v) => {
+    return v.name
+  })
+}
+
+/**
+ * Load known release versions from the union of:
+ * - remote release branches (`release/v*` on origin)
+ * - Jira fix versions (when configured)
+ *
+ * Each source is queried in parallel; if either fails, we log a warning
+ * and continue with the other so a transient outage doesn't block release
+ * creation.
+ */
+export const loadExistingVersions = async (): Promise<SemVer[]> => {
+  const [branchesResult, jiraResult] = await Promise.allSettled([parseRemoteRefs(), fetchJiraVersionNames()])
+
+  if (branchesResult.status === 'rejected') {
+    logger.warn({ error: branchesResult.reason }, 'Failed to list remote release branches; continuing without them')
+  }
+
+  if (jiraResult.status === 'rejected') {
+    logger.warn({ error: jiraResult.reason }, 'Failed to fetch Jira versions; continuing without them')
+  }
+
+  return collectKnownVersions({
+    remoteBranches: branchesResult.status === 'fulfilled' ? branchesResult.value : [],
+    jiraVersions: jiraResult.status === 'fulfilled' ? jiraResult.value : [],
+  })
+}