infra-kit 0.1.101 → 0.1.105

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 => {

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

@@ -0,0 +1,146 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import yaml from 'yaml'
+import { z } from 'zod'
+
+import {
+  getInfraKitConfigPaths,
+  infraKitConfigSchema,
+  infraKitOverrideConfigSchema,
+  resetInfraKitConfigCache,
+} from 'src/lib/infra-kit-config'
+import { logger } from 'src/lib/logger'
+
+interface MigrateLayer {
+  label: string
+  /** Legacy YAML source path. */
+  yml: string
+  /** Target JSON path. */
+  json: string
+  /** Validates the parsed object before any write (main vs override schema). */
+  schema: z.ZodType
+}
+
+/**
+ * Replace the user's home prefix with `~` so logged paths stay short.
+ *
+ * @example
+ * // os.homedir() === '/Users/arthur'
+ * tildify('/Users/arthur/.infra-kit/config.yml') // => '~/.infra-kit/config.yml'
+ */
+const tildify = (filePath: string): string => {
+  const home = os.homedir()
+
+  return filePath.startsWith(home) ? `~${filePath.slice(home.length)}` : filePath
+}
+
+/**
+ * `fs.access` reduced to a boolean, swallowing ENOENT.
+ *
+ * @example
+ * await fileExists('/etc/hosts') // => true
+ */
+const fileExists = async (filePath: string): Promise<boolean> => {
+  try {
+    await fs.access(filePath)
+
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Swap a resolved `.json` config path back to its legacy `.yml` sibling.
+ *
+ * @example
+ * legacyYmlPath('/repo/infra-kit.json') // => '/repo/infra-kit.yml'
+ */
+const legacyYmlPath = (jsonPath: string): string => {
+  return jsonPath.replace(/\.json$/, '.yml')
+}
+
+/**
+ * Convert any legacy `infra-kit.yml` config layers to `infra-kit.json` as part
+ * of `infra-kit init`. Best-effort and non-fatal: each merge-chain layer
+ * (project, user-global, user-project) is migrated independently, and a
+ * conflict (both `.yml` and `.json` present) or an invalid `.yml` warns and
+ * skips that layer rather than aborting init or touching the other layers.
+ * Idempotent — already-JSON layers are left untouched.
+ *
+ * @example
+ * await migrateLegacyConfig()
+ * // INFO: ✓ Migrated infra-kit.yml → infra-kit.json
+ * // (no output when there is nothing legacy to convert)
+ */
+export const migrateLegacyConfig = async (): Promise<void> => {
+  let paths: Awaited<ReturnType<typeof getInfraKitConfigPaths>>
+
+  try {
+    paths = await getInfraKitConfigPaths()
+  } catch {
+    // No resolvable project (e.g. init run outside a repo) — nothing to migrate.
+    return
+  }
+
+  const layers: MigrateLayer[] = [
+    { label: 'infra-kit.json', yml: legacyYmlPath(paths.main), json: paths.main, schema: infraKitConfigSchema },
+    {
+      label: '~/.infra-kit/config.json',
+      yml: legacyYmlPath(paths.userGlobal),
+      json: paths.userGlobal,
+      schema: infraKitOverrideConfigSchema,
+    },
+    {
+      label: `~/.infra-kit/projects/${paths.projectName}/infra-kit.json`,
+      yml: legacyYmlPath(paths.userProject),
+      json: paths.userProject,
+      schema: infraKitOverrideConfigSchema,
+    },
+  ]
+
+  let migrated = 0
+
+  for (const layer of layers) {
+    const [ymlExists, jsonExists] = await Promise.all([fileExists(layer.yml), fileExists(layer.json)])
+
+    if (!ymlExists) continue
+
+    if (jsonExists) {
+      logger.info(
+        `⚠ Skipped ${tildify(layer.yml)} — ${tildify(layer.json)} already exists (remove the stale .yml manually)`,
+      )
+
+      continue
+    }
+
+    // Keep per-layer migration non-fatal even for malformed YAML or I/O errors
+    // (TOCTOU after the existence probe, EACCES, read-only FS): warn and skip
+    // so one bad layer never aborts `init` or the other layers.
+    try {
+      const raw = await fs.readFile(layer.yml, 'utf-8')
+      const parsed = (yaml.parse(raw) ?? {}) as unknown
+      const result = layer.schema.safeParse(parsed)
+
+      if (!result.success) {
+        logger.info(`⚠ Skipped ${tildify(layer.yml)} — invalid config: ${z.prettifyError(result.error)}`)
+
+        continue
+      }
+
+      await fs.mkdir(path.dirname(layer.json), { recursive: true })
+      await fs.writeFile(layer.json, `${JSON.stringify(result.data, null, 2)}\n`, 'utf-8')
+      await fs.rm(layer.yml, { force: true })
+
+      logger.info(`✓ Migrated ${tildify(layer.yml)} → ${tildify(layer.json)}`)
+      migrated++
+    } catch (err) {
+      logger.info(`⚠ Skipped ${tildify(layer.yml)} — ${(err as Error).message}`)
+    }
+  }
+
+  if (migrated > 0) {
+    resetInfraKitConfigCache()
+  }
+}

package/src/commands/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -0,0 +1 @@
+{"version":"4.1.8","results":[[":audit/__tests__/audit.test.ts",{"duration":0,"failed":true}]]}

package/src/commands/release-create/__tests__/release-create.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest'
+import type { z } from 'zod'
+
+import { releaseCreateMcpTool } from '../release-create'
+
+/**
+ * The MCP `releases[]` entry schema enforces that exactly one of `version` or
+ * `name` is supplied, and transforms each entry into the internal ReleaseInput
+ * shape. We exercise the schema directly (the array element) so we do not need
+ * to run the full handler (which performs git/Jira side effects).
+ */
+const entrySchema = (releaseCreateMcpTool.inputSchema.releases as z.ZodArray<z.ZodTypeAny>).element
+
+describe('release-create MCP releases[] entry schema', () => {
+  it('accepts a versioned entry and transforms it into a version ReleaseInput', () => {
+    expect(entrySchema.parse({ version: '1.2.5', type: 'hotfix' })).toEqual({
+      version: '1.2.5',
+      type: 'hotfix',
+    })
+  })
+
+  it('defaults type to regular', () => {
+    expect(entrySchema.parse({ version: '1.2.5' })).toEqual({
+      version: '1.2.5',
+      type: 'regular',
+    })
+  })
+
+  it('accepts a named entry and transforms it into a name ReleaseInput', () => {
+    expect(entrySchema.parse({ name: 'checkout-redesign', type: 'regular' })).toEqual({
+      name: 'checkout-redesign',
+      type: 'regular',
+    })
+  })
+
+  it('carries description through for named entries', () => {
+    expect(entrySchema.parse({ name: 'checkout-redesign', description: 'Q3' })).toEqual({
+      name: 'checkout-redesign',
+      type: 'regular',
+      description: 'Q3',
+    })
+  })
+
+  it('rejects an entry with both version and name (mutually exclusive)', () => {
+    expect(() => {
+      return entrySchema.parse({ version: '1.2.5', name: 'checkout-redesign' })
+    }).toThrow(/exactly one of/)
+  })
+
+  it('rejects an entry with neither version nor name', () => {
+    expect(() => {
+      return entrySchema.parse({ type: 'regular' })
+    }).toThrow(/exactly one of/)
+  })
+})

package/src/commands/release-create/release-create.ts

@@ -1,13 +1,14 @@
 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 { question } from 'zx'
 
 import { loadJiraConfig } from 'src/integrations/jira'
 import { commandEcho } from 'src/lib/command-echo'
 import { OperationError } from 'src/lib/errors/operation-error'
 import { logger } from 'src/lib/logger'
+import { InvalidReleaseNameError, displayLabel, validateName } from 'src/lib/release-id'
 import { createSingleRelease, prepareGitForRelease } from 'src/lib/release-utils'
 import type { ReleaseCreationResult, ReleaseType } from 'src/lib/release-utils'
 import {
@@ -18,12 +19,12 @@ import {
   parseVersion,
   resolveReleaseEntries,
 } from 'src/lib/version-utils'
-import type { ReleaseEntry, SemVer } from 'src/lib/version-utils'
+import type { ReleaseEntry, ReleaseInput, SemVer } from 'src/lib/version-utils'
 import { defineMcpTool, textContent } from 'src/types'
 import type { RequiredConfirmedOptionArg } from 'src/types'
 
 interface ReleaseCreateArgs extends RequiredConfirmedOptionArg {
-  releases?: ReleaseEntry[]
+  releases?: ReleaseInput[]
 }
 
 const VERSION_PROMPT_HINT = '"1.2.5" or "next"'
@@ -38,7 +39,7 @@ const trySuggestNext = (known: SemVer[], type: ReleaseType): string | null => {
   }
 }
 
-const resolveOrExit = (entries: ReleaseEntry[], known: SemVer[]): ReleaseEntry[] => {
+const resolveOrExit = (entries: ReleaseInput[], known: SemVer[]): ReleaseEntry[] => {
   try {
     return resolveReleaseEntries(entries, known)
   } catch (err) {
@@ -49,20 +50,80 @@ const resolveOrExit = (entries: ReleaseEntry[], known: SemVer[]): ReleaseEntry[]
       })
     }
 
+    if (err instanceof InvalidReleaseNameError) {
+      throw new OperationError(err, {
+        operation: 'validate release name',
+        remediation:
+          'use a kebab-case name like "checkout-redesign" (lowercase, digits, single hyphens, not a reserved word)',
+      })
+    }
+
     throw err
   }
 }
 
+const promptForVersionInput = async (running: SemVer[], type: ReleaseType): Promise<string> => {
+  const suggestion = trySuggestNext(running, type)
+  const defaultHint = suggestion ? ` [${suggestion}]` : ''
+  const versionAnswer = (await question(`  Version (e.g. ${VERSION_PROMPT_HINT})${defaultHint}: `)).trim()
+  const versionInput = versionAnswer === '' ? (suggestion ?? '') : versionAnswer
+
+  if (versionInput === '') {
+    logger.error('No version provided. Exiting...')
+    process.exit(1)
+  }
+
+  return versionInput
+}
+
+const promptForNameInput = async (): Promise<string> => {
+  const name = (await question('  Name (kebab-case, e.g. "checkout-redesign"): ')).trim()
+
+  if (name === '') {
+    logger.error('No name provided. Exiting...')
+    process.exit(1)
+  }
+
+  try {
+    validateName(name)
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+
+    logger.error(`${reason} Exiting...`)
+    process.exit(1)
+  }
+
+  return name
+}
+
 const promptForReleasesInteractive = async (ensureKnown: () => Promise<SemVer[]>): Promise<ReleaseEntry[]> => {
   commandEcho.setInteractive()
 
-  const baseKnown = await ensureKnown()
-  const running: SemVer[] = [...baseKnown]
+  let baseKnown: SemVer[] | null = null
+  const running: SemVer[] = []
+  const ensureRunning = async (): Promise<SemVer[]> => {
+    if (baseKnown === null) {
+      baseKnown = await ensureKnown()
+      running.push(...baseKnown)
+    }
+
+    return running
+  }
+
   const entries: ReleaseEntry[] = []
   let addAnother = true
 
   while (addAnother) {
     const ordinal = entries.length + 1
+    const kind = await select<'version' | 'name'>({
+      message: `Release #${ordinal} — version or name?`,
+      choices: [
+        { name: 'version (semver / next)', value: 'version' },
+        { name: 'name (free-form)', value: 'name' },
+      ],
+      default: 'version',
+    })
+
     const type = await select<ReleaseType>({
       message: `Release #${ordinal} — select type:`,
       choices: [
@@ -72,19 +133,22 @@ const promptForReleasesInteractive = async (ensureKnown: () => Promise<SemVer[]>
       default: 'regular',
     })
 
-    const suggestion = trySuggestNext(running, type)
-    const defaultHint = suggestion ? ` [${suggestion}]` : ''
-    const versionAnswer = (await question(`  Version (e.g. ${VERSION_PROMPT_HINT})${defaultHint}: `)).trim()
-    const versionInput = versionAnswer === '' ? (suggestion ?? '') : versionAnswer
+    let resolved: ReleaseEntry
 
-    if (versionInput === '') {
-      logger.error('No version provided. Exiting...')
-      process.exit(1)
-    }
+    if (kind === 'name') {
+      const name = await promptForNameInput()
+
+      resolved = resolveOrExit([{ name, type }], [])[0] as ReleaseEntry
+    } else {
+      // Versions may need prior versions for "next"; load lazily.
+      const versionInput = await promptForVersionInput(await ensureRunning(), type)
 
-    const resolved = resolveOrExit([{ version: versionInput, type }], running)[0] as ReleaseEntry
+      resolved = resolveOrExit([{ version: versionInput, type }], running)[0] as ReleaseEntry
 
-    running.push(parseVersion(`v${resolved.version}`))
+      if (resolved.id.kind === 'version') {
+        running.push(parseVersion(`v${resolved.id.raw}`))
+      }
+    }
 
     const description = (await question('  Description (optional, press Enter to skip): ')).trim()
 
@@ -97,7 +161,8 @@ const promptForReleasesInteractive = async (ensureKnown: () => Promise<SemVer[]>
 }
 
 const formatReleaseSummary = (entry: ReleaseEntry): string => {
-  const parts = [`v${entry.version}`, entry.type]
+  const label = entry.id.kind === 'version' ? `v${entry.id.raw}` : entry.id.name
+  const parts = [label, entry.type]
 
   if (entry.description) parts.push(entry.description)
 
@@ -106,9 +171,17 @@ const formatReleaseSummary = (entry: ReleaseEntry): string => {
 
 const echoReleases = (entries: ReleaseEntry[]): void => {
   for (const entry of entries) {
+    if (entry.id.kind === 'name') {
+      // Named releases echo the --name form; description is not part of the
+      // flag and is set later via release-desc-edit / interactively.
+      commandEcho.addOption('--name', entry.id.name)
+
+      continue
+    }
+
     const spec = entry.description
-      ? `${entry.version}:${entry.type}:${entry.description}`
-      : `${entry.version}:${entry.type}`
+      ? `${entry.id.raw}:${entry.type}:${entry.description}`
+      : `${entry.id.raw}:${entry.type}`
 
     commandEcho.addOption('--release', spec)
   }
@@ -120,7 +193,7 @@ interface FailedRelease {
 }
 
 const collectEntries = async (
-  inputReleases: ReleaseEntry[] | undefined,
+  inputReleases: ReleaseInput[] | undefined,
   ensureKnown: () => Promise<SemVer[]>,
 ): Promise<ReleaseEntry[]> => {
   if (inputReleases && inputReleases.length > 0) {
@@ -168,31 +241,33 @@ const executeOne = async (
   args: ExecuteOneArgs,
 ): Promise<{ result?: ReleaseCreationResult; failure?: FailedRelease }> => {
   const { entry, jiraConfig } = args
+  const label = displayLabel(entry.id)
+  const prTitleLabel = entry.id.kind === 'version' ? `v${entry.id.raw}` : entry.id.name
 
   try {
     await prepareGitForRelease(entry.type)
 
     const result = await createSingleRelease({
-      version: entry.version,
+      id: entry.id,
       jiraConfig,
       description: entry.description,
       type: entry.type,
     })
 
-    logger.info(`✅ Successfully created release: v${entry.version} (${entry.type})`)
+    logger.info(`✅ Successfully created release: ${prTitleLabel} (${entry.type})`)
     logger.info(`🔗  GitHub PR: ${result.prUrl}`)
     logger.info(`🔗  Jira Version: ${result.jiraVersionUrl}\n`)
 
     return { result }
   } catch (error) {
     const err = new OperationError(error, {
-      operation: `create release v${entry.version} (${entry.type})`,
-      remediation: 'verify the version is unique and the base branch is clean',
+      operation: `create release ${prTitleLabel} (${entry.type})`,
+      remediation: 'verify the version or name is unique and the base branch is clean',
     })
 
     logger.error(`❌ ${err.message}\n`)
 
-    return { failure: { version: entry.version, error: err.message } }
+    return { failure: { version: label, error: err.message } }
   }
 }
 
@@ -272,24 +347,53 @@ export const releaseCreate = async (args: ReleaseCreateArgs) => {
 export const releaseCreateMcpTool = defineMcpTool({
   name: 'release-create',
   description:
-    'Create one or more releases in a single call. Each entry in "releases" carries its own version, type (regular|hotfix, default regular), and optional description, so regular and hotfix releases can be mixed in the same invocation. For each release this tool switches to the appropriate base branch (dev for regular, main for hotfix), cuts the release branch, opens a GitHub release PR, and creates the matching Jira fix version. The literal token "next" auto-increments from the union of remote release branches and Jira fix versions (regular bumps minor + resets patch; hotfix bumps patch on the highest minor); multiple "next" tokens advance sequentially across mixed types. Confirmation is auto-skipped for MCP calls, so the caller is responsible for gating. Continues on per-release failure and reports successes/failures.',
+    'Create one or more releases in a single call. Each entry in "releases" carries EITHER a "version" (semver or the literal token "next") OR a "name" (free-form kebab-case identifier) — exactly one is required and they are mutually exclusive. Each entry also has its own type (regular|hotfix, default regular) and optional description, so regular and hotfix releases can be mixed in the same invocation. For each release this tool switches to the appropriate base branch (dev for regular, main for hotfix), cuts the release branch (release/v<semver> for versions, release/n/<name> for names), opens a GitHub release PR, and creates the matching Jira fix version (v<semver> for versions, <name> for names). The literal token "next" auto-increments from the union of remote release branches and Jira fix versions (regular bumps minor + resets patch; hotfix bumps patch on the highest minor); multiple "next" tokens advance sequentially across mixed types. Named releases never auto-bump and "next" is version-only. Confirmation is auto-skipped for MCP calls, so the caller is responsible for gating. Continues on per-release failure and reports successes/failures.',
   inputSchema: {
     releases: z
       .array(
-        z.object({
-          version: z
-            .string()
-            .describe('Version to create (e.g., "1.2.5") or the literal token "next" for auto-increment.'),
-          type: z
-            .enum(['regular', 'hotfix'])
-            .optional()
-            .default('regular')
-            .describe('Release type: "regular" (branches off dev) or "hotfix" (branches off main).'),
-          description: z.string().optional().describe('Optional description for the Jira version.'),
-        }),
+        z
+          .object({
+            version: z
+              .string()
+              .optional()
+              .describe(
+                'Version to create (e.g., "1.2.5") or the literal token "next" for auto-increment. Mutually exclusive with "name".',
+              ),
+            name: z
+              .string()
+              .optional()
+              .describe(
+                'Free-form kebab-case release name (e.g., "checkout-redesign"). Mutually exclusive with "version". Named releases never auto-bump.',
+              ),
+            type: z
+              .enum(['regular', 'hotfix'])
+              .optional()
+              .default('regular')
+              .describe('Release type: "regular" (branches off dev) or "hotfix" (branches off main).'),
+            description: z.string().optional().describe('Optional description for the Jira version.'),
+          })
+          .refine(
+            (entry) => {
+              return (entry.version === undefined) !== (entry.name === undefined)
+            },
+            {
+              message: 'Each release entry must have exactly one of "version" or "name" (they are mutually exclusive).',
+            },
+          )
+          .transform((entry): ReleaseInput => {
+            return entry.name !== undefined
+              ? { name: entry.name, type: entry.type, ...(entry.description ? { description: entry.description } : {}) }
+              : {
+                  version: entry.version as string,
+                  type: entry.type,
+                  ...(entry.description ? { description: entry.description } : {}),
+                }
+          }),
       )
       .min(1)
-      .describe('One or more releases to create. Each entry has its own version, type, and optional description.'),
+      .describe(
+        'One or more releases to create. Each entry has exactly one of "version" or "name", plus its own type and optional description.',
+      ),
   },
   outputSchema: {
     createdBranches: z.array(z.string()).describe('List of created release branch names'),