infra-kit 0.1.99 → 0.1.100

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

@@ -9,16 +9,18 @@ import { removeFoldersFromCursorWorkspace, resolveCursorWorkspacePath } from 'sr
 import { getReleasePRsWithInfo } 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 { detectReleaseType, formatBranchChoices, getJiraDescriptions } from 'src/lib/release-utils'
 import type { ReleaseType } from 'src/lib/release-utils'
-import type { RequiredConfirmedOptionArg, ToolsExecutionResult } from 'src/types'
+import { defineMcpTool, textContent } from 'src/types'
+import type { RequiredConfirmedOptionArg } from 'src/types'
 
 // Constants
 interface WorktreeManagementArgs extends RequiredConfirmedOptionArg {
-  all: boolean
+  all?: boolean
   versions?: string
 }
 
@@ -26,7 +28,7 @@ interface WorktreeManagementArgs extends RequiredConfirmedOptionArg {
  * Manage git worktrees for release branches
  * Creates worktrees for active release branches and removes unused ones
  */
-export const worktreesRemove = async (options: WorktreeManagementArgs): Promise<ToolsExecutionResult> => {
+export const worktreesRemove = async (options: WorktreeManagementArgs) => {
   const { confirmedCommand, all, versions } = options
 
   commandEcho.start('worktrees-remove')
@@ -40,7 +42,7 @@ export const worktreesRemove = async (options: WorktreeManagementArgs): Promise<
       commandEcho.print()
 
       return {
-        content: [{ type: 'text', text: JSON.stringify({ removedWorktrees: [], count: 0 }, null, 2) }],
+        content: textContent(JSON.stringify({ removedWorktrees: [], count: 0 }, null, 2)),
         structuredContent: { removedWorktrees: [], count: 0 },
       }
     }
@@ -131,17 +133,15 @@ export const worktreesRemove = async (options: WorktreeManagementArgs): Promise<
     }
 
     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: 'remove worktrees',
+      remediation: "check 'git worktree list' for the path; uncommitted changes block removal",
+    })
   }
 }
 
@@ -179,8 +179,12 @@ const removeWorktrees = async (args: RemoveWorktreesArgs): Promise<string[]> =>
       removed.push(result.value)
     } else {
       const branch = branches[index]
+      const err = new OperationError(result.reason, {
+        operation: `remove worktree for ${branch}`,
+        remediation: "check 'git worktree list' for the path; uncommitted changes block removal",
+      })
 
-      logger.error({ error: result.reason }, `❌ Failed to remove worktree for ${branch}`)
+      logger.error({ error: result.reason, msg: err.message })
     }
   }
 
@@ -252,7 +256,7 @@ const logResults = (removed: string[]): void => {
 }
 
 // MCP Tool Registration
-export const worktreesRemoveMcpTool = {
+export const worktreesRemoveMcpTool = defineMcpTool({
   name: 'worktrees-remove',
   description:
     'Remove local git worktrees for release branches. When everything is removed, also runs "git worktree prune" and deletes the worktrees directory. When invoked via MCP, pass either "versions" (comma-separated) or all=true — the branch picker is unreachable without a TTY, and the CLI confirmation is auto-skipped for MCP calls, so the caller is responsible for gating.',
@@ -275,4 +279,4 @@ export const worktreesRemoveMcpTool = {
     count: z.number().describe('Number of git worktrees removed'),
   },
   handler: worktreesRemove,
-}
+})

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

@@ -15,6 +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 { 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'
@@ -102,6 +103,20 @@ program
     })
   })
 
+program
+  .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 releaseDescEdit({
+      version: options.version,
+      description: options.description,
+      confirmedCommand: options.yes,
+    })
+  })
+
 program
   .command('release-deploy-all')
   .description('Deploy any release branch to any environment')
@@ -263,6 +278,7 @@ if (process.argv.length <= 2) {
     'merge-dev',
     'release-list',
     'release-create',
+    '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/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/mcp/tools/index.ts

@@ -10,6 +10,7 @@ import { ghReleaseDeployAllMcpTool } from 'src/commands/gh-release-deploy-all'
 import { ghReleaseDeploySelectedMcpTool } from 'src/commands/gh-release-deploy-selected'
 import { ghReleaseListMcpTool } from 'src/commands/gh-release-list'
 import { releaseCreateMcpTool } from 'src/commands/release-create'
+import { releaseDescEditMcpTool } from 'src/commands/release-desc-edit'
 import { versionMcpTool } from 'src/commands/version'
 import { worktreesAddMcpTool } from 'src/commands/worktrees-add'
 import { worktreesListMcpTool } from 'src/commands/worktrees-list'
@@ -25,6 +26,7 @@ const tools = [
   envClearMcpTool,
   ghMergeDevMcpTool,
   releaseCreateMcpTool,
+  releaseDescEditMcpTool,
   ghReleaseDeliverMcpTool,
   ghReleaseDeployAllMcpTool,
   ghReleaseDeploySelectedMcpTool,

package/src/types.ts

@@ -1,12 +1,66 @@
-export interface ToolsExecutionResult {
+import type { z } from 'zod/v4'
+
+export interface ToolsExecutionResult<TStructured = Record<string, unknown>> {
   [x: string]: unknown
   content: {
     type: 'text'
     text: string
   }[]
-  structuredContent?: { [x: string]: unknown }
+  structuredContent?: TStructured
 }
 
 export interface RequiredConfirmedOptionArg {
   confirmedCommand: boolean
 }
+
+export interface McpTool<TIn extends z.ZodRawShape = z.ZodRawShape, TOut extends z.ZodRawShape = z.ZodRawShape> {
+  name: string
+  description: string
+  inputSchema: TIn
+  outputSchema: TOut
+  handler: (
+    params: z.infer<z.ZodObject<TIn>> & RequiredConfirmedOptionArg,
+  ) => Promise<ToolsExecutionResult<z.infer<z.ZodObject<TOut>>>>
+}
+
+/**
+ * Build the dual-channel content array shared by every MCP tool. Narrows the
+ * literal `type: 'text'` so handlers can use inferred return types without TS
+ * widening `type` to `string` — which would otherwise break assignability
+ * against the MCP SDK's content union.
+ *
+ * @example
+ * return {
+ *   content: textContent(JSON.stringify(structuredContent, null, 2)),
+ *   structuredContent,
+ * }
+ */
+export const textContent = (text: string): ToolsExecutionResult['content'] => {
+  return [{ type: 'text', text }]
+}
+
+/**
+ * Factory that ties the handler's return type to the declared `outputSchema`
+ * so `structuredContent` is checked against the schema at compile time. If a
+ * handler accidentally drops or renames a field, TS errors at the registration
+ * site rather than at runtime in an MCP client.
+ *
+ * @example
+ * export const envLoadMcpTool = defineMcpTool({
+ *   name: 'env-load',
+ *   description: '...',
+ *   inputSchema: { config: z.string() },
+ *   outputSchema: {
+ *     filePath: z.string(),
+ *     variableCount: z.number(),
+ *     project: z.string(),
+ *     config: z.string(),
+ *   },
+ *   handler: envLoad,
+ * })
+ */
+export const defineMcpTool = <TIn extends z.ZodRawShape, TOut extends z.ZodRawShape>(
+  tool: McpTool<TIn, TOut>,
+): McpTool<TIn, TOut> => {
+  return tool
+}