infra-kit 0.1.98 → 0.1.100

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

@@ -8,10 +8,12 @@ import { removeFoldersFromCursorWorkspace, resolveCursorWorkspacePath } from 'sr
 import { getReleasePRs } from 'src/integrations/gh'
 import { commandEcho } from 'src/lib/command-echo'
 import { WORKTREES_DIR_SUFFIX } from 'src/lib/constants'
+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 type { RequiredConfirmedOptionArg, ToolsExecutionResult } from 'src/types'
+import { defineMcpTool, textContent } from 'src/types'
+import type { RequiredConfirmedOptionArg } from 'src/types'
 
 // Constants
 const RELEASE_BRANCH_PREFIX = 'release/v'
@@ -23,7 +25,7 @@ interface WorktreeSyncArgs extends RequiredConfirmedOptionArg {}
  *
  * Creates worktrees for active release branches and removes unused ones
  */
-export const worktreesSync = async (options: WorktreeSyncArgs): Promise<ToolsExecutionResult> => {
+export const worktreesSync = async (options: WorktreeSyncArgs) => {
   const { confirmedCommand } = options
 
   commandEcho.start('worktrees-sync')
@@ -82,17 +84,15 @@ export const worktreesSync = async (options: WorktreeSyncArgs): Promise<ToolsExe
     }
 
     return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(structuredContent, null, 2),
-        },
-      ],
+      content: textContent(JSON.stringify(structuredContent, null, 2)),
       structuredContent,
     }
   } catch (error) {
     logger.error({ error }, '❌ Error managing worktrees')
-    throw error
+    throw new OperationError(error, {
+      operation: 'sync worktrees with remote',
+      remediation: "ensure 'gh auth status' is ok and you can reach origin",
+    })
   }
 }
 
@@ -143,7 +143,12 @@ const removeWorktrees = async (args: RemoveWorktreesArgs): Promise<string[]> =>
       await $`git worktree remove ${worktreePath}`
       removed.push(branch)
     } catch (error) {
-      logger.error({ error, branch }, `❌ Failed to remove worktree for ${branch}`)
+      const err = new OperationError(error, {
+        operation: `remove stale worktree for ${branch}`,
+        remediation: 'inspect the worktree dir manually; rerun with the branch checked out elsewhere',
+      })
+
+      logger.error({ error, branch, msg: err.message })
     }
   }
 
@@ -207,7 +212,7 @@ const logResults = (removed: string[]): void => {
 }
 
 // MCP Tool Registration
-export const worktreesSyncMcpTool = {
+export const worktreesSyncMcpTool = defineMcpTool({
   name: 'worktrees-sync',
   description:
     'Remove worktrees whose release PR is no longer open (stale cleanup). Only removes — never creates; use worktrees-add to create worktrees for new releases. The CLI confirmation is auto-skipped for MCP calls, so the caller is responsible for gating.',
@@ -217,4 +222,4 @@ export const worktreesSyncMcpTool = {
     count: z.number().describe('Number of worktrees removed during sync'),
   },
   handler: worktreesSync,
-}
+})

package/src/entry/cli.ts

@@ -1,5 +1,5 @@
 import select, { Separator } from '@inquirer/select'
-import { Command, Option } from 'commander'
+import { Command } from 'commander'
 import process from 'node:process'
 
 import { configEdit, configPath } from 'src/commands/config'
@@ -15,7 +15,7 @@ import { ghReleaseDeploySelected } from 'src/commands/gh-release-deploy-selected
 import { ghReleaseList } from 'src/commands/gh-release-list'
 import { init } from 'src/commands/init'
 import { releaseCreate } from 'src/commands/release-create'
-import { releaseCreateBatch } from 'src/commands/release-create-batch'
+import { releaseDescEdit } from 'src/commands/release-desc-edit'
 import { version } from 'src/commands/version'
 import { CURSOR_MODES, worktreesAdd } from 'src/commands/worktrees-add'
 import type { CursorMode } from 'src/commands/worktrees-add'
@@ -24,9 +24,14 @@ import { worktreesOpen } from 'src/commands/worktrees-open'
 import { worktreesRemove } from 'src/commands/worktrees-remove'
 import { worktreesSync } from 'src/commands/worktrees-sync'
 import { logger } from 'src/lib/logger'
+import { parseReleaseSpec } from 'src/lib/version-utils'
 
 const program = new Command()
 
+const collectReleaseSpec = (value: string, prev: string[]): string[] => {
+  return [...prev, value]
+}
+
 const normalizeCursorMode = (value: unknown): CursorMode | undefined => {
   if (typeof value === 'undefined') {
     return undefined
@@ -80,36 +85,34 @@ program
 
 program
   .command('release-create')
-  .description('Create a single release branch')
+  .description('Create one or more release branches (each entry can mix regular/hotfix and its own description)')
   .option(
-    '-v, --version <version>',
-    'Version to create, e.g. "1.2.5", "next", or "next,next,1.2.7" (multi-value routes to batch)',
+    '-r, --release <spec>',
+    'Release spec "version[:type[:description]]" (repeatable). Examples: "1.2.5", "1.2.5:hotfix", "next:regular:Holiday backend"',
+    collectReleaseSpec,
+    [],
   )
-  .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')
   .action(async (options) => {
+    const specs = options.release as string[]
+    const releases = specs.length > 0 ? specs.map(parseReleaseSpec) : undefined
+
     await releaseCreate({
-      version: options.version,
-      description: options.description,
-      type: options.type,
+      releases,
       confirmedCommand: options.yes,
     })
   })
 
 program
-  .command('release-create-batch')
-  .description('Create multiple release branches (batch operation)')
-  .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']))
+  .command('release-desc-edit')
+  .description("Edit a release's description in Jira and in the matching GitHub PR body")
+  .option('-v, --version <version>', 'Release version, e.g. 1.2.5')
+  .option('-d, --description <description>', 'New description (use "" to clear)')
   .option('-y, --yes', 'Skip confirmation prompt')
   .action(async (options) => {
-    await releaseCreateBatch({
-      versions: options.versions,
-      type: options.type,
+    await releaseDescEdit({
+      version: options.version,
+      description: options.description,
       confirmedCommand: options.yes,
     })
   })
@@ -275,7 +278,7 @@ if (process.argv.length <= 2) {
     'merge-dev',
     'release-list',
     'release-create',
-    'release-create-batch',
+    'release-desc-edit',
     'release-deploy-all',
     'release-deploy-selected',
     'release-deliver',

package/src/integrations/gh/gh-release-prs/gh-release-prs.ts

@@ -109,6 +109,27 @@ export const getReleasePRsWithInfo = async (): Promise<ReleasePRInfo[]> => {
   }
 }
 
+interface UpdateReleasePRBodyArgs {
+  branch: string
+  body: string
+}
+
+/**
+ * Update the body of an open release PR identified by its head branch.
+ */
+export const updateReleasePRBody = async (args: UpdateReleasePRBodyArgs): Promise<void> => {
+  const { branch, body } = args
+
+  try {
+    $.quiet = true
+    await $`gh pr edit ${branch} --body ${body}`
+    $.quiet = false
+  } catch (error: unknown) {
+    logger.error({ error, branch }, `Error updating release PR body for ${branch}`)
+    throw error
+  }
+}
+
 interface CreateReleaseBranchArgs {
   version: string
   jiraVersionUrl: string

package/src/integrations/gh/gh-release-prs/index.ts

@@ -1,2 +1,2 @@
-export { createReleaseBranch, getReleasePRs, getReleasePRsWithInfo } from './gh-release-prs'
+export { createReleaseBranch, getReleasePRs, getReleasePRsWithInfo, updateReleasePRBody } from './gh-release-prs'
 export type { ReleasePRInfo } from './gh-release-prs'

package/src/integrations/gh/index.ts

@@ -1,3 +1,3 @@
 export { validateGitHubCliAndAuth } from './gh-cli-auth'
-export { createReleaseBranch, getReleasePRs, getReleasePRsWithInfo } from './gh-release-prs'
+export { createReleaseBranch, getReleasePRs, getReleasePRsWithInfo, updateReleasePRBody } from './gh-release-prs'
 export type { ReleasePRInfo } from './gh-release-prs'

package/src/integrations/jira/api.ts

@@ -145,7 +145,7 @@ export const getProjectVersions = async (config: JiraConfig): Promise<JiraVersio
  * @param config - Jira configuration
  * @returns JiraVersion if found, null otherwise
  */
-const findVersionByName = async (versionName: string, config: JiraConfig): Promise<JiraVersion | null> => {
+export const findVersionByName = async (versionName: string, config: JiraConfig): Promise<JiraVersion | null> => {
   try {
     const versions = await getProjectVersions(config)
     const version = versions.find((v) => {
@@ -166,29 +166,20 @@ const findVersionByName = async (versionName: string, config: JiraConfig): Promi
  * @param config - Jira configuration
  * @returns Result containing updated version or error
  */
-const updateJiraVersion = async (
+export const updateJiraVersion = async (
   params: UpdateJiraVersionParams,
   config: JiraConfig,
 ): Promise<UpdateJiraVersionResult> => {
   try {
     const { baseUrl, token, email } = config
 
-    // Prepare request body - only include fields that are provided
-    const requestBody: Record<string, any> = {
-      released: params.released ?? true,
-      archived: params.archived ?? false,
-    }
-
-    // Add releaseDate if provided, otherwise use current date when releasing
-    if (params.releaseDate) {
-      requestBody.releaseDate = params.releaseDate
-    } else if (params.released !== false) {
-      requestBody.releaseDate = new Date().toISOString().split('T')[0] // YYYY-MM-DD
-    }
+    // Only include fields the caller explicitly passed.
+    const requestBody: Record<string, any> = {}
 
-    if (params.description !== undefined) {
-      requestBody.description = params.description
-    }
+    if (params.released !== undefined) requestBody.released = params.released
+    if (params.archived !== undefined) requestBody.archived = params.archived
+    if (params.releaseDate !== undefined) requestBody.releaseDate = params.releaseDate
+    if (params.description !== undefined) requestBody.description = params.description
 
     const url = `${baseUrl}/rest/api/3/version/${params.versionId}`
     const credentials = btoa(`${email}:${token}`)

package/src/integrations/jira/index.ts

@@ -1,9 +1,11 @@
 export {
   createJiraVersion,
   deliverJiraRelease,
+  findVersionByName,
   getProjectVersions,
   loadJiraConfig,
   loadJiraConfigOptional,
+  updateJiraVersion,
 } from './api.js'
 export type {
   CreateJiraVersionParams,

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

@@ -37,11 +37,17 @@ const withTmpRepo = async (fn: (tmp: string) => Promise<void>): Promise<void> =>
 
   vi.mocked(getProjectRoot).mockResolvedValue(tmp)
   vi.mocked(getRepoName).mockResolvedValue(path.basename(tmp))
+  // Point os.homedir() at the tmp dir so user-scope override layers
+  // (~/.infra-kit/config.yml, ~/.infra-kit/projects/<repo>/infra-kit.yml)
+  // can't leak the developer's real config into the test.
+  const homedirSpy = vi.spyOn(os, 'homedir').mockReturnValue(tmp)
+
   resetInfraKitConfigCache()
 
   try {
     await fn(tmp)
   } finally {
+    homedirSpy.mockRestore()
     resetInfraKitConfigCache()
     fs.rmSync(tmp, { recursive: true, force: true })
   }
@@ -105,6 +111,50 @@ taskManager:
     })
   })
 
+  it('accepts a worktrees prompt-defaults block', async () => {
+    await withTmpRepo(async (tmp) => {
+      fs.writeFileSync(
+        path.join(tmp, 'infra-kit.yml'),
+        `environments: [dev]
+envManagement:
+  provider: doppler
+  config:
+    name: p
+worktrees:
+  openInGithubDesktop: false
+  openInCmux: true
+`,
+      )
+
+      const cfg = await getInfraKitConfig()
+
+      expect(cfg.worktrees?.openInGithubDesktop).toBe(false)
+      expect(cfg.worktrees?.openInCmux).toBe(true)
+    })
+  })
+
+  it('lets the user-global config layer supply a worktrees block when the project omits it', async () => {
+    await withTmpRepo(async (tmp) => {
+      fs.writeFileSync(path.join(tmp, 'infra-kit.yml'), VALID_YML)
+
+      const userGlobalDir = path.join(tmp, '.infra-kit')
+
+      fs.mkdirSync(userGlobalDir, { recursive: true })
+      fs.writeFileSync(
+        path.join(userGlobalDir, 'config.yml'),
+        `worktrees:
+  openInGithubDesktop: false
+  openInCmux: true
+`,
+      )
+
+      const cfg = await getInfraKitConfig()
+
+      expect(cfg.worktrees?.openInGithubDesktop).toBe(false)
+      expect(cfg.worktrees?.openInCmux).toBe(true)
+    })
+  })
+
   it('rejects ide.cursor mode=workspace without workspaceConfigPath', async () => {
     await withTmpRepo(async (tmp) => {
       fs.writeFileSync(

package/src/lib/errors/__tests__/operation-error.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+
+import { OperationError } from '../operation-error'
+
+describe('operationError', () => {
+  it('formats a minimal message from operation alone', () => {
+    const err = new OperationError(new Error('boom'), { operation: 'do the thing' })
+
+    expect(err).toBeInstanceOf(OperationError)
+    expect(err.message).toBe('failed to do the thing')
+    expect(err.cause).toBeInstanceOf(Error)
+    expect(err.operation).toBe('do the thing')
+  })
+
+  it('appends a remediation hint when provided', () => {
+    const err = new OperationError(new Error('boom'), {
+      operation: 'do the thing',
+      remediation: 'check the docs',
+    })
+
+    expect(err.message).toBe('failed to do the thing — try: check the docs')
+    expect(err.remediation).toBe('check the docs')
+  })
+
+  it('extracts a stderr excerpt from a zx ProcessOutput-shaped cause', () => {
+    const zxLike = { stderr: 'fatal: not a git repository\n(more lines...)' }
+    const err = new OperationError(zxLike, { operation: 'run git' })
+
+    expect(err.message).toContain('stderr: fatal: not a git repository')
+  })
+
+  it('truncates oversized stderr excerpts', () => {
+    const huge = 'X'.repeat(5000)
+    const err = new OperationError({ stderr: huge }, { operation: 'run git' })
+
+    expect(err.message.length).toBeLessThan(300)
+  })
+
+  it('prefers an explicit stderrExcerpt over the cause stderr', () => {
+    const err = new OperationError(
+      { stderr: 'raw zx output' },
+      { operation: 'run git', stderrExcerpt: 'curated excerpt' },
+    )
+
+    expect(err.message).toContain('stderr: curated excerpt')
+    expect(err.message).not.toContain('raw zx output')
+  })
+
+  it('preserves the original cause', () => {
+    const cause = new Error('underlying')
+    const err = new OperationError(cause, { operation: 'do thing' })
+
+    expect(err.cause).toBe(cause)
+  })
+
+  it('handles non-Error causes', () => {
+    const err = new OperationError('a string', { operation: 'do thing' })
+
+    expect(err.message).toBe('failed to do thing')
+    expect(err.cause).toBe('a string')
+  })
+})

package/src/lib/errors/format-zx-error.ts

@@ -0,0 +1,54 @@
+const STDERR_EXCERPT_MAX_BYTES = 500
+const STDOUT_EXCERPT_MAX_BYTES = 200
+
+export interface ZxErrorFields {
+  exitCode?: number | null
+  stderr?: string
+  stdout?: string
+  message?: string
+  name?: string
+}
+
+const readTrimmedString = (value: unknown, max: number): string | undefined => {
+  if (typeof value !== 'string' || value.length === 0) return undefined
+
+  return value.slice(-max).trim()
+}
+
+/**
+ * Extract loggable fields from an error for `logger.error({ err: formatZxError(e) }, ...)`.
+ *
+ * pino's default `err` serializer handles `Error` subclasses but renders zx's
+ * `ProcessOutput` as `{}` because its informative fields (`stderr`, `stdout`,
+ * `exitCode`) are non-enumerable / on the prototype. This helper duck-types
+ * those fields so subprocess failures surface in logs instead of vanishing.
+ */
+export const formatZxError = (error: unknown): ZxErrorFields => {
+  if (error === null || typeof error !== 'object') {
+    return { message: String(error) }
+  }
+
+  const rec = error as Record<string, unknown>
+  const fields: ZxErrorFields = {}
+
+  if (error instanceof Error) {
+    fields.name = error.name
+    fields.message = error.message
+  } else if (typeof rec.message === 'string') {
+    fields.message = rec.message
+  }
+
+  const exitCode = rec.exitCode
+
+  if (typeof exitCode === 'number' || exitCode === null) fields.exitCode = exitCode
+
+  const stderr = readTrimmedString(rec.stderr, STDERR_EXCERPT_MAX_BYTES)
+
+  if (stderr) fields.stderr = stderr
+
+  const stdout = readTrimmedString(rec.stdout, STDOUT_EXCERPT_MAX_BYTES)
+
+  if (stdout) fields.stdout = stdout
+
+  return fields
+}

package/src/lib/errors/operation-error.ts

@@ -0,0 +1,80 @@
+const STDERR_EXCERPT_MAX_BYTES = 200
+
+export interface OperationErrorContext {
+  operation: string
+  remediation?: string
+  stderrExcerpt?: string
+}
+
+/**
+ * Duck-typed read of zx's `ProcessOutput.stderr` (and similar shapes) without
+ * importing zx types just for an `instanceof` check.
+ *
+ * @example
+ * extractStderr(new Error('x'))               // undefined
+ * extractStderr({ stderr: 'fatal: ...' })     // 'fatal: ...'
+ * extractStderr({ stderr: '' })               // undefined  (empty treated as missing)
+ */
+const extractStderr = (cause: unknown): string | undefined => {
+  if (cause === null || typeof cause !== 'object') return undefined
+  const stderr = (cause as { stderr?: unknown }).stderr
+
+  return typeof stderr === 'string' && stderr.length > 0 ? stderr : undefined
+}
+
+/**
+ * Compose the human-and-agent-readable message body for an `OperationError`:
+ * `"failed to <operation> [— stderr: <excerpt>] [— try: <remediation>]"`.
+ * `stderrExcerpt` overrides anything duck-typed off `cause`; both are trimmed
+ * and capped at {@link STDERR_EXCERPT_MAX_BYTES} so a runaway subprocess can't
+ * blow up the message.
+ */
+const buildMessage = (cause: unknown, ctx: OperationErrorContext): string => {
+  const stderr = ctx.stderrExcerpt ?? extractStderr(cause)
+  const parts = [`failed to ${ctx.operation}`]
+
+  if (stderr) parts.push(`stderr: ${stderr.slice(0, STDERR_EXCERPT_MAX_BYTES).trim()}`)
+  if (ctx.remediation) parts.push(`try: ${ctx.remediation}`)
+
+  return parts.join(' — ')
+}
+
+/**
+ * Error type for any handler-level failure that should surface to the caller
+ * (CLI user or MCP-connected agent) with a remediation hint. Wraps an
+ * underlying cause and renders a single-line, structured message so logs and
+ * agent tool-result text stay scannable.
+ *
+ * Pattern modeled on the exemplary Doppler errors in
+ * `src/integrations/doppler/doppler-cli-auth.ts`.
+ *
+ * @example
+ * // wrap a zx subprocess failure
+ * try {
+ *   await $`git worktree add ${path} ${branch}`
+ * } catch (err) {
+ *   throw new OperationError(err, {
+ *     operation: `git worktree add for ${branch}`,
+ *     remediation: 'check the branch name and that the parent dir is writable',
+ *   })
+ * }
+ *
+ * @example
+ * // validation failure with no underlying cause
+ * throw new OperationError(undefined, {
+ *   operation: 'launch deploy-all workflow',
+ *   remediation: `pass one of: ${environments.join(', ')}`,
+ *   stderrExcerpt: `invalid environment: ${selectedEnv}`,
+ * })
+ */
+export class OperationError extends Error {
+  readonly operation: string
+  readonly remediation?: string
+
+  constructor(cause: unknown, ctx: OperationErrorContext) {
+    super(buildMessage(cause, ctx), { cause })
+    this.name = 'OperationError'
+    this.operation = ctx.operation
+    this.remediation = ctx.remediation
+  }
+}

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

@@ -56,11 +56,18 @@ const jiraTaskManagerSchema = z.object({
 
 const taskManagerSchema = z.discriminatedUnion('provider', [jiraTaskManagerSchema])
 
+// worktrees prompt defaults
+const worktreesConfigSchema = z.object({
+  openInGithubDesktop: z.boolean().optional(),
+  openInCmux: z.boolean().optional(),
+})
+
 const infraKitConfigSchema = z.object({
   environments: z.array(z.string().min(1)).min(1),
   envManagement: envManagementSchema,
   ide: ideSchema.optional(),
   taskManager: taskManagerSchema.optional(),
+  worktrees: worktreesConfigSchema.optional(),
 })
 
 const infraKitOverrideConfigSchema = infraKitConfigSchema.partial()