infra-kit 0.1.95 → 0.1.98

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 : [],
+  })
+}

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

@@ -0,0 +1,148 @@
+import type { ReleaseType } from 'src/lib/release-utils'
+
+import { parseVersion, sortVersions } from './version-utils'
+
+export const NEXT_TOKEN = 'next'
+
+export type SemVer = readonly [number, number, number]
+
+export interface ExistingVersionsSources {
+  remoteBranches?: string[]
+  jiraVersions?: string[]
+}
+
+const VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)$/
+
+const stripBranchPrefix = (raw: string): string => {
+  return raw.replace(/^.*release\//, '')
+}
+
+const tryParse = (raw: string): SemVer | null => {
+  const cleaned = stripBranchPrefix(raw.trim())
+  const match = VERSION_RE.exec(cleaned)
+
+  if (!match) return null
+
+  return [Number(match[1]), Number(match[2]), Number(match[3])]
+}
+
+const semverKey = (v: SemVer): string => {
+  return `${v[0]}.${v[1]}.${v[2]}`
+}
+
+export const collectKnownVersions = (sources: ExistingVersionsSources): SemVer[] => {
+  const all = [...(sources.remoteBranches ?? []), ...(sources.jiraVersions ?? [])]
+  const parsed: SemVer[] = []
+  const seen = new Set<string>()
+
+  for (const raw of all) {
+    const v = tryParse(raw)
+
+    if (!v) continue
+
+    const key = semverKey(v)
+
+    if (seen.has(key)) continue
+
+    seen.add(key)
+    parsed.push(v)
+  }
+
+  return sortVersions(
+    parsed.map((v) => {
+      return semverKey(v)
+    }),
+  ).map((s) => {
+    return parseVersion(`v${s}`)
+  })
+}
+
+export class NoPriorVersionsError extends Error {
+  constructor() {
+    super('No prior release versions found from git or Jira. Specify the version explicitly.')
+    this.name = 'NoPriorVersionsError'
+  }
+}
+
+/**
+ * Compute the next semantic version based on release type.
+ * - regular: bump minor, reset patch to 0
+ * - hotfix: bump patch on the highest minor (any patch)
+ *
+ * Returns the version without the leading "v" (e.g. "1.64.0").
+ */
+export const computeNextVersion = (known: SemVer[], type: ReleaseType): string => {
+  if (known.length === 0) throw new NoPriorVersionsError()
+
+  const max = known[known.length - 1] as SemVer
+
+  if (type === 'hotfix') {
+    const [major, minor] = max
+
+    const highestPatchOnMinor = known.reduce((acc, v) => {
+      if (v[0] === major && v[1] === minor) return Math.max(acc, v[2])
+
+      return acc
+    }, 0)
+
+    return `${major}.${minor}.${highestPatchOnMinor + 1}`
+  }
+
+  const [major, minor] = max
+
+  return `${major}.${minor + 1}.0`
+}
+
+const isNextToken = (token: string): boolean => {
+  return token.trim().toLowerCase() === NEXT_TOKEN
+}
+
+/**
+ * Resolve a list of input tokens (mix of "next" and explicit semver strings)
+ * into concrete version strings. Each "next" advances based on the running
+ * max so "next,next" produces sequential versions.
+ */
+export const resolveVersionTokens = (tokens: string[], type: ReleaseType, known: SemVer[]): string[] => {
+  const running: SemVer[] = [...known]
+  const resolved: string[] = []
+
+  for (const token of tokens) {
+    const trimmed = token.trim()
+
+    if (trimmed === '') continue
+
+    if (isNextToken(trimmed)) {
+      const next = computeNextVersion(running, type)
+
+      resolved.push(next)
+      running.push(parseVersion(`v${next}`))
+      continue
+    }
+
+    const parsed = tryParse(trimmed)
+
+    if (!parsed) {
+      throw new Error(`Invalid version "${trimmed}". Expected semver like "1.2.5" or the token "next".`)
+    }
+
+    const explicit = `${parsed[0]}.${parsed[1]}.${parsed[2]}`
+
+    resolved.push(explicit)
+    running.push(parsed)
+  }
+
+  return resolved
+}
+
+/**
+ * Split a raw user input into tokens, trimming and removing empties.
+ * Accepts both whitespace-separated and comma-separated lists.
+ */
+export const splitVersionInput = (input: string): string[] => {
+  return input
+    .split(',')
+    .map((t) => {
+      return t.trim()
+    })
+    .filter(Boolean)
+}

package/src/mcp/tools/index.ts

@@ -14,6 +14,7 @@ import { releaseCreateBatchMcpTool } from 'src/commands/release-create-batch'
 import { versionMcpTool } from 'src/commands/version'
 import { worktreesAddMcpTool } from 'src/commands/worktrees-add'
 import { worktreesListMcpTool } from 'src/commands/worktrees-list'
+import { worktreesOpenMcpTool } from 'src/commands/worktrees-open'
 import { worktreesRemoveMcpTool } from 'src/commands/worktrees-remove'
 import { worktreesSyncMcpTool } from 'src/commands/worktrees-sync'
 import { createToolHandler } from 'src/lib/tool-handler'
@@ -33,6 +34,7 @@ const tools = [
   versionMcpTool,
   worktreesAddMcpTool,
   worktreesListMcpTool,
+  worktreesOpenMcpTool,
   worktreesRemoveMcpTool,
   worktreesSyncMcpTool,
 ]