infra-kit 0.1.102 → 0.1.105

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'),

package/src/commands/release-desc-edit/release-desc-edit.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 { question } from 'zx'
 
 import { getReleasePRsWithInfo, updateReleasePRBody } from 'src/integrations/gh'
@@ -10,7 +10,13 @@ import type { JiraConfig, JiraVersion } 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 { detectReleaseType, formatBranchChoices, getJiraDescriptions } from 'src/lib/release-utils'
+import { displayLabel, formatJiraName, parseBranchName } from 'src/lib/release-id'
+import {
+  detectReleaseType,
+  formatBranchChoices,
+  getJiraDescriptions,
+  resolveReleaseBranch,
+} from 'src/lib/release-utils'
 import type { ReleaseType } from 'src/lib/release-utils'
 import { defineMcpTool, textContent } from 'src/types'
 import type { RequiredConfirmedOptionArg } from 'src/types'
@@ -87,7 +93,7 @@ export const releaseDescEdit = async (args: ReleaseDescEditArgs) => {
   let selectedBranch: string
 
   if (versionArg) {
-    selectedBranch = `release/v${versionArg}`
+    selectedBranch = resolveReleaseBranch(versionArg)
     await verifyReleasePRExists(selectedBranch)
   } else {
     commandEcho.setInteractive()
@@ -96,11 +102,23 @@ export const releaseDescEdit = async (args: ReleaseDescEditArgs) => {
     selectedBranch = picked.branch
   }
 
-  const selectedVersion = selectedBranch.replace('release/v', '')
+  // selectedBranch is always a release branch here (operator ref strictly parsed,
+  // or picked from discovery-filtered choices), so parseBranchName cannot be null.
+  const releaseId = parseBranchName(selectedBranch)
+
+  if (!releaseId) {
+    throw new OperationError(undefined, {
+      operation: `edit description for ${selectedBranch}`,
+      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)
 
-  const versionName = `v${selectedVersion}`
+  // Jira fix version is named by the Jira convention: `v1.2.3` | `<name>`.
+  const versionName = formatJiraName(releaseId)
   const jiraVersion = await findVersionByName(versionName, jiraConfig)
 
   if (!jiraVersion) {
@@ -190,14 +208,16 @@ export const releaseDescEdit = async (args: ReleaseDescEditArgs) => {
 export const releaseDescEditMcpTool = defineMcpTool({
   name: 'release-desc-edit',
   description:
-    "Edit a release's description in Jira and in the matching GitHub release PR body. Targets the Jira fix version named `v<version>` and the open PR on branch `release/v<version>`. The PR body is rewritten canonically to `<jiraVersionUrl>\\n\\n<description>` — any prior manual edits to the body are overwritten. Both `version` and `description` are required for MCP calls (the picker/prompt are unreachable without a TTY). Empty `description` clears the description on both sides. Confirmation is auto-skipped for MCP, so the caller is responsible for gating.",
+    "Edit a release's description in Jira and in the matching GitHub release PR body. Accepts a release version or a release name: targets the Jira fix version named `v<version>` (versioned) or `<name>` (named) and the open PR on branch `release/v<version>` or `release/n/<name>`. The PR body is rewritten canonically to `<jiraVersionUrl>\\n\\n<description>` — any prior manual edits to the body are overwritten. Both `version` and `description` are required for MCP calls (the picker/prompt are unreachable without a TTY). Empty `description` clears the description on both sides. Confirmation is auto-skipped for MCP, so the caller is responsible for gating.",
   inputSchema: {
-    version: z.string().describe('Release version, e.g. "1.2.5".'),
+    version: z
+      .string()
+      .describe('Accepts a release version (e.g. "1.2.5") OR a release name (e.g. "checkout-redesign").'),
     description: z.string().describe('New description. Empty string clears the description.'),
   },
   outputSchema: {
     version: z.string().describe('Release version'),
-    branch: z.string().describe('Release branch name (e.g. "release/v1.2.5")'),
+    branch: z.string().describe('Release branch name (e.g. "release/v1.2.5" or "release/n/checkout-redesign")'),
     jiraVersionUrl: z.string().describe('Jira fix version URL'),
     previousDescription: z.string().describe('The description before the update'),
     newDescription: z.string().describe('The description after the update'),

package/src/commands/version/version.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod/v4'
+import { z } from 'zod'
 
 import { logger } from 'src/lib/logger'
 import { defineMcpTool, textContent } from 'src/types'

package/src/commands/worktrees-add/worktrees-add.ts

@@ -3,7 +3,7 @@ import checkbox from '@inquirer/checkbox'
 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 { buildCmuxWorkspaceTitle, openCmuxWorkspaceWithLayout } from 'src/integrations/cmux'
@@ -15,7 +15,8 @@ import { OperationError } from 'src/lib/errors/operation-error'
 import { getCurrentWorktrees, getProjectRoot, getRepoName } 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 { formatBranchName, isReleaseBranch, parseReleaseRef } from 'src/lib/release-id'
+import { detectReleaseType, formatBranchChoices, getJiraDescriptions, releaseBranchLabels } from 'src/lib/release-utils'
 import type { ReleaseType } from 'src/lib/release-utils'
 import { defineMcpTool, textContent } from 'src/types'
 import type { RequiredConfirmedOptionArg } from 'src/types'
@@ -23,7 +24,6 @@ import type { RequiredConfirmedOptionArg } from 'src/types'
 // Constants
 const FEATURE_DIR = 'feature'
 const RELEASE_DIR = 'release'
-const RELEASE_BRANCH_PREFIX = 'release/v'
 
 export const CURSOR_MODES = ['workspace', 'windows', 'none'] as const
 export type CursorMode = (typeof CURSOR_MODES)[number]
@@ -58,7 +58,7 @@ export const worktreesAdd = async (options: WorktreeManagementArgs) => {
 
     if (versions) {
       selectedReleaseBranches = versions.split(',').map((v) => {
-        return `release/v${v.trim()}`
+        return formatBranchName(parseReleaseRef(v.trim()))
       })
     } else {
       const releasePRsInfo = await getReleasePRsWithInfo()
@@ -103,12 +103,7 @@ export const worktreesAdd = async (options: WorktreeManagementArgs) => {
     if (all) {
       commandEcho.addOption('--all', true)
     } else {
-      commandEcho.addOption(
-        '--versions',
-        selectedReleaseBranches.map((branch) => {
-          return branch.replace('release/v', '')
-        }),
-      )
+      commandEcho.addOption('--versions', releaseBranchLabels(selectedReleaseBranches))
     }
 
     // Ask for confirmation
@@ -282,7 +277,7 @@ const categorizeWorktrees = (args: CategorizeWorktreesArgs): { branchesToCreate:
   const { selectedReleaseBranches, currentWorktrees } = args
 
   const currentBranchNames = currentWorktrees.filter((branch) => {
-    return branch.startsWith(RELEASE_BRANCH_PREFIX)
+    return isReleaseBranch(branch)
   })
 
   const branchesToCreate = selectedReleaseBranches.filter((branch) => {
@@ -357,7 +352,7 @@ export const worktreesAddMcpTool = defineMcpTool({
       .string()
       .optional()
       .describe(
-        'Comma-separated release versions to target (e.g. "1.2.5, 1.2.6"). Either "versions" or all=true must be provided for MCP calls. Overrides "all" when set.',
+        'Comma-separated release versions or names to target (e.g. "1.2.5, 1.2.6" or "checkout-redesign, 1.2.5"). Either "versions" or all=true must be provided for MCP calls. Overrides "all" when set.',
       ),
     cursor: z
       .enum(CURSOR_MODES)