infra-kit 0.1.98 → 0.1.100

package/src/commands/release-desc-edit/release-desc-edit.ts

@@ -0,0 +1,207 @@
+import confirm from '@inquirer/confirm'
+import select from '@inquirer/select'
+import process from 'node:process'
+import { z } from 'zod/v4'
+import { question } from 'zx'
+
+import { getReleasePRsWithInfo, updateReleasePRBody } from 'src/integrations/gh'
+import { findVersionByName, loadJiraConfig, updateJiraVersion } from 'src/integrations/jira'
+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 type { ReleaseType } from 'src/lib/release-utils'
+import { defineMcpTool, textContent } from 'src/types'
+import type { RequiredConfirmedOptionArg } from 'src/types'
+
+interface ReleaseDescEditArgs extends RequiredConfirmedOptionArg {
+  version?: string
+  description?: string
+}
+
+const buildJiraVersionUrl = (jiraConfig: JiraConfig, version: JiraVersion): string => {
+  return `${jiraConfig.baseUrl}/projects/${version.projectId}/versions/${version.id}/tab/release-report-all-issues`
+}
+
+const buildPRBody = (jiraVersionUrl: string, description: string): string => {
+  return description.trim() !== '' ? `${jiraVersionUrl}\n\n${description}` : `${jiraVersionUrl} \n`
+}
+
+const pickReleaseBranch = async (): Promise<{ branch: string; type: ReleaseType }> => {
+  const releasePRsInfo = await getReleasePRsWithInfo()
+  const branches = releasePRsInfo.map((pr) => {
+    return pr.branch
+  })
+  const types = new Map<string, ReleaseType>(
+    releasePRsInfo.map((pr) => {
+      return [pr.branch, detectReleaseType(pr.title)]
+    }),
+  )
+  const descriptions = await getJiraDescriptions()
+
+  const branch = await select({
+    message: '🌿 Select release branch',
+    choices: formatBranchChoices({ branches, descriptions, types }),
+  })
+
+  return { branch, type: types.get(branch) || 'regular' }
+}
+
+const verifyReleasePRExists = async (selectedBranch: string): Promise<ReleaseType> => {
+  const releasePRsInfo = await getReleasePRsWithInfo()
+  const prInfo = releasePRsInfo.find((pr) => {
+    return pr.branch === selectedBranch
+  })
+
+  if (!prInfo) {
+    throw new OperationError(undefined, {
+      operation: `edit description for ${selectedBranch}`,
+      remediation: `confirm an open PR exists for ${selectedBranch} ('gh pr list')`,
+    })
+  }
+
+  return detectReleaseType(prInfo.title)
+}
+
+const promptDescription = async (current: string): Promise<string> => {
+  const hint = current === '' ? '(no current description)' : `current: "${current}"`
+  const answer = await question(`  New description ${hint}\n  (press Enter to keep current): `)
+  const trimmed = answer.replace(/\n$/, '')
+
+  return trimmed === '' ? current : trimmed
+}
+
+/**
+ * Edit a release's description in Jira (fix version) and in the matching
+ * GitHub release PR body. The PR body is rewritten canonically to
+ * `<jiraVersionUrl>\n\n<description>` (matching `release-create`).
+ */
+export const releaseDescEdit = async (args: ReleaseDescEditArgs) => {
+  const { version: versionArg, description: descriptionArg, confirmedCommand } = args
+
+  commandEcho.start('release-desc-edit')
+
+  const jiraConfig = await loadJiraConfig()
+
+  let selectedBranch: string
+
+  if (versionArg) {
+    selectedBranch = `release/v${versionArg}`
+    await verifyReleasePRExists(selectedBranch)
+  } else {
+    commandEcho.setInteractive()
+    const picked = await pickReleaseBranch()
+
+    selectedBranch = picked.branch
+  }
+
+  const selectedVersion = selectedBranch.replace('release/v', '')
+
+  commandEcho.addOption('--version', selectedVersion)
+
+  const versionName = `v${selectedVersion}`
+  const jiraVersion = await findVersionByName(versionName, jiraConfig)
+
+  if (!jiraVersion) {
+    throw new OperationError(undefined, {
+      operation: `edit description for ${versionName}`,
+      remediation: `create the Jira fix version "${versionName}" first or pick a different release`,
+    })
+  }
+
+  const previousDescription = jiraVersion.description ?? ''
+
+  let newDescription: string
+
+  if (descriptionArg !== undefined) {
+    newDescription = descriptionArg
+    commandEcho.addOption('--description', newDescription)
+  } else {
+    commandEcho.setInteractive()
+    newDescription = await promptDescription(previousDescription)
+  }
+
+  if (newDescription === previousDescription) {
+    logger.info(`No change — description for ${versionName} is already: "${previousDescription}"`)
+    commandEcho.print()
+
+    const structuredContent = {
+      version: selectedVersion,
+      branch: selectedBranch,
+      jiraVersionUrl: buildJiraVersionUrl(jiraConfig, jiraVersion),
+      previousDescription,
+      newDescription,
+      changed: false,
+    }
+
+    return {
+      content: textContent(JSON.stringify(structuredContent, null, 2)),
+      structuredContent,
+    }
+  }
+
+  const answer = confirmedCommand
+    ? true
+    : await confirm({
+        message: `Update description for ${versionName}?\n  from: "${previousDescription}"\n  to:   "${newDescription}"\n`,
+      })
+
+  if (!confirmedCommand) {
+    commandEcho.setInteractive()
+  }
+
+  if (!answer) {
+    logger.info('Operation cancelled. Exiting...')
+    process.exit(0)
+  }
+
+  commandEcho.addOption('--yes', true)
+
+  await updateJiraVersion({ versionId: jiraVersion.id, description: newDescription }, jiraConfig)
+
+  const jiraVersionUrl = buildJiraVersionUrl(jiraConfig, jiraVersion)
+  const body = buildPRBody(jiraVersionUrl, newDescription)
+
+  await updateReleasePRBody({ branch: selectedBranch, body })
+
+  logger.info(`✅ Updated description for ${versionName}`)
+  logger.info(`🔗  Jira Version: ${jiraVersionUrl}`)
+  logger.info(`🔗  PR branch: ${selectedBranch}\n`)
+
+  commandEcho.print()
+
+  const structuredContent = {
+    version: selectedVersion,
+    branch: selectedBranch,
+    jiraVersionUrl,
+    previousDescription,
+    newDescription,
+    changed: true,
+  }
+
+  return {
+    content: textContent(JSON.stringify(structuredContent, null, 2)),
+    structuredContent,
+  }
+}
+
+// MCP Tool Registration
+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.",
+  inputSchema: {
+    version: z.string().describe('Release version, e.g. "1.2.5".'),
+    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")'),
+    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'),
+    changed: z.boolean().describe('Whether the description actually changed'),
+  },
+  handler: releaseDescEdit,
+})

package/src/commands/version/version.ts

@@ -1,14 +1,14 @@
 import { z } from 'zod/v4'
 
 import { logger } from 'src/lib/logger'
-import type { ToolsExecutionResult } from 'src/types'
+import { defineMcpTool, textContent } from 'src/types'
 
 import packageJson from '../../../package.json' with { type: 'json' }
 
 /**
  * Print the infra-kit CLI version
  */
-export const version = async (): Promise<ToolsExecutionResult> => {
+export const version = async () => {
   const cliVersion = packageJson.version
 
   logger.info(cliVersion)
@@ -16,18 +16,13 @@ export const version = async (): Promise<ToolsExecutionResult> => {
   const structuredContent = { version: cliVersion }
 
   return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify(structuredContent, null, 2),
-      },
-    ],
+    content: textContent(JSON.stringify(structuredContent, null, 2)),
     structuredContent,
   }
 }
 
 // MCP Tool Registration
-export const versionMcpTool = {
+export const versionMcpTool = defineMcpTool({
   name: 'version',
   description: 'Print the installed infra-kit CLI version',
   inputSchema: {},
@@ -35,4 +30,4 @@ export const versionMcpTool = {
     version: z.string().describe('Installed infra-kit CLI version (from package.json)'),
   },
   handler: version,
-}
+})

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

@@ -11,12 +11,14 @@ import { addFoldersToCursorWorkspace, resolveCursorWorkspacePath } from 'src/int
 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
 const FEATURE_DIR = 'feature'
@@ -27,7 +29,7 @@ export const CURSOR_MODES = ['workspace', 'windows', 'none'] as const
 export type CursorMode = (typeof CURSOR_MODES)[number]
 
 interface WorktreeManagementArgs extends RequiredConfirmedOptionArg {
-  all: boolean
+  all?: boolean
   versions?: string
   cursor?: CursorMode
   githubDesktop?: boolean
@@ -38,7 +40,7 @@ interface WorktreeManagementArgs extends RequiredConfirmedOptionArg {
  * Manage git worktrees for release branches
  * Creates worktrees for active release branches and removes unused ones
  */
-export const worktreesAdd = async (options: WorktreeManagementArgs): Promise<ToolsExecutionResult> => {
+export const worktreesAdd = async (options: WorktreeManagementArgs) => {
   const { confirmedCommand, all, versions, cursor, githubDesktop, cmux } = options
 
   commandEcho.start('worktrees-add')
@@ -71,7 +73,7 @@ export const worktreesAdd = async (options: WorktreeManagementArgs): Promise<Too
         commandEcho.print()
 
         return {
-          content: [{ type: 'text', text: JSON.stringify({ createdWorktrees: [], count: 0 }, null, 2) }],
+          content: textContent(JSON.stringify({ createdWorktrees: [], count: 0 }, null, 2)),
           structuredContent: { createdWorktrees: [], count: 0 },
         }
       }
@@ -130,8 +132,12 @@ export const worktreesAdd = async (options: WorktreeManagementArgs): Promise<Too
       commandEcho.addOption('--yes', true)
     }
 
+    const config = await getInfraKitConfig()
+    const cursorConfig = config.ide?.provider === 'cursor' ? config.ide.config : undefined
+
     const cursorMode: CursorMode =
       cursor ??
+      cursorConfig?.mode ??
       (await select<CursorMode>({
         message: 'Cursor mode for created worktrees?',
         default: 'workspace',
@@ -150,16 +156,18 @@ export const worktreesAdd = async (options: WorktreeManagementArgs): Promise<Too
         ],
       }))
 
-    if (typeof cursor === 'undefined') {
+    if (typeof cursor === 'undefined' && !cursorConfig?.mode) {
       commandEcho.setInteractive()
     }
 
     commandEcho.addOption('--cursor', cursorMode)
 
     const openInGithubDesktop =
-      githubDesktop ?? (await confirm({ message: 'Open created worktrees in GitHub Desktop?' }))
+      githubDesktop ??
+      config.worktrees?.openInGithubDesktop ??
+      (await confirm({ message: 'Open created worktrees in GitHub Desktop?' }))
 
-    if (typeof githubDesktop === 'undefined') {
+    if (typeof githubDesktop === 'undefined' && config.worktrees?.openInGithubDesktop === undefined) {
       commandEcho.setInteractive()
     }
 
@@ -169,9 +177,10 @@ export const worktreesAdd = async (options: WorktreeManagementArgs): Promise<Too
       commandEcho.addOption('--no-github-desktop', true)
     }
 
-    const openInCmux = cmux ?? (await confirm({ message: 'Open created worktrees in cmux?' }))
+    const openInCmux =
+      cmux ?? config.worktrees?.openInCmux ?? (await confirm({ message: 'Open created worktrees in cmux?' }))
 
-    if (typeof cmux === 'undefined') {
+    if (typeof cmux === 'undefined' && config.worktrees?.openInCmux === undefined) {
       commandEcho.setInteractive()
     }
 
@@ -191,11 +200,8 @@ export const worktreesAdd = async (options: WorktreeManagementArgs): Promise<Too
     logResults(createdWorktrees)
 
     if (cursorMode === 'workspace') {
-      const config = await getInfraKitConfig()
-      const cursorConfig = config.ide?.provider === 'cursor' ? config.ide.config : undefined
-
       if (!cursorConfig?.workspaceConfigPath) {
-        logger.warn('⚠️ Skipping Cursor: ide.config.workspaceConfigPath is not set in infra-kit.yml')
+        logger.warn('⚠️ Skipping Cursor: ide.config.workspaceConfigPath is not set in infra-kit config')
       } else {
         const workspacePath = resolveCursorWorkspacePath(cursorConfig.workspaceConfigPath, projectRoot)
 
@@ -245,17 +251,15 @@ export const worktreesAdd = async (options: WorktreeManagementArgs): Promise<Too
     }
 
     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: 'create worktrees',
+      remediation: "verify branches don't already exist as worktrees: 'git worktree list'",
+    })
   }
 }
 
@@ -310,8 +314,12 @@ const createWorktrees = async (branches: string[], worktreeDir: string): Promise
       created.push(result.value)
     } else {
       const branch = branches[index]
+      const err = new OperationError(result.reason, {
+        operation: `git worktree add for ${branch}`,
+        remediation: 'check the branch name and that the parent dir is writable',
+      })
 
-      logger.error({ error: result.reason }, `❌ Failed to create worktree for ${branch}`)
+      logger.error({ error: result.reason, msg: err.message })
     }
   }
 
@@ -334,7 +342,7 @@ const logResults = (created: string[]): void => {
 }
 
 // MCP Tool Registration
-export const worktreesAddMcpTool = {
+export const worktreesAddMcpTool = defineMcpTool({
   name: 'worktrees-add',
   description:
     'Create local git worktrees for release branches under the worktrees directory and run "pnpm install" in each. Mutates the local filesystem. When invoked via MCP, pass either "versions" (comma-separated) or all=true — the branch picker and "open in Cursor / GitHub Desktop / cmux" follow-up prompts are unreachable without a TTY, and the CLI confirmation is auto-skipped for MCP calls.',
@@ -355,19 +363,19 @@ export const worktreesAddMcpTool = {
       .enum(CURSOR_MODES)
       .optional()
       .describe(
-        'Cursor open mode for created worktrees. "workspace" (default behavior when set interactively) appends each worktree as a folder to "ide.config.workspaceConfigPath" in infra-kit.yml and opens the workspace. "windows" opens each worktree in its own Cursor window. "none" skips Cursor. Defaults to "none" in MCP mode (the follow-up prompt is not shown).',
+        'Cursor open mode for created worktrees. "workspace" appends each worktree as a folder to "ide.config.workspaceConfigPath" in infra-kit config and opens the workspace. "windows" opens each worktree in its own Cursor window. "none" skips Cursor. Resolution order: this flag → "ide.config.mode" from infra-kit config → interactive prompt (CLI) / "none" (MCP, no TTY).',
       ),
     githubDesktop: z
       .boolean()
       .optional()
       .describe(
-        'Open each created worktree in GitHub Desktop. Defaults to false in MCP mode (the follow-up prompt is not shown).',
+        'Open each created worktree in GitHub Desktop. Resolution order: this flag → "worktrees.openInGithubDesktop" from infra-kit config → interactive prompt (CLI) / false (MCP, no TTY).',
       ),
     cmux: z
       .boolean()
       .optional()
       .describe(
-        'Open each created worktree in a new cmux workspace with a 3-pane layout (left-top, left-bottom, full-height right), all rooted at the worktree directory. Defaults to false in MCP mode (the follow-up prompt is not shown).',
+        'Open each created worktree in a new cmux workspace with a 3-pane layout (left-top, left-bottom, full-height right), all rooted at the worktree directory. Resolution order: this flag → "worktrees.openInCmux" from infra-kit config → interactive prompt (CLI) / false (MCP, no TTY).',
       ),
   },
   outputSchema: {
@@ -375,4 +383,4 @@ export const worktreesAddMcpTool = {
     count: z.number().describe('Number of git worktrees created'),
   },
   handler: worktreesAdd,
-}
+})

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

@@ -5,7 +5,7 @@ import { getCurrentWorktrees } from 'src/lib/git-utils'
 import { logger } from 'src/lib/logger'
 import { detectReleaseType, formatVersionLabel, getJiraDescriptions } from 'src/lib/release-utils'
 import type { ReleaseType } from 'src/lib/release-utils'
-import type { ToolsExecutionResult } from 'src/types'
+import { defineMcpTool, textContent } from 'src/types'
 
 interface WorktreeInfo {
   version: string
@@ -16,14 +16,14 @@ interface WorktreeInfo {
 /**
  * List all release git worktrees with version, type, and Jira description
  */
-export const worktreesList = async (): Promise<ToolsExecutionResult> => {
+export const worktreesList = async () => {
   const currentWorktrees = await getCurrentWorktrees('release')
 
   if (currentWorktrees.length === 0) {
     logger.info('ℹ️ No active worktrees found')
 
     return {
-      content: [{ type: 'text', text: JSON.stringify({ worktrees: [], count: 0 }, null, 2) }],
+      content: textContent(JSON.stringify({ worktrees: [], count: 0 }, null, 2)),
       structuredContent: { worktrees: [], count: 0 },
     }
   }
@@ -70,18 +70,13 @@ export const worktreesList = async (): Promise<ToolsExecutionResult> => {
   }
 
   return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify(structuredContent, null, 2),
-      },
-    ],
+    content: textContent(JSON.stringify(structuredContent, null, 2)),
     structuredContent,
   }
 }
 
 // MCP Tool Registration
-export const worktreesListMcpTool = {
+export const worktreesListMcpTool = defineMcpTool({
   name: 'worktrees-list',
   description:
     'List existing release-branch worktrees with version, release type (regular / hotfix), and Jira fix-version description. Read-only.',
@@ -99,4 +94,4 @@ export const worktreesListMcpTool = {
     count: z.number().describe('Number of worktrees'),
   },
   handler: worktreesList,
-}
+})

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

@@ -5,10 +5,11 @@ import { buildCmuxWorkspaceTitle, listCmuxWorkspaceTitles, openCmuxWorkspaceWith
 import { reconcileCursorWorkspaceFolders, resolveCursorWorkspacePath } from 'src/integrations/cursor'
 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 { ToolsExecutionResult } from 'src/types'
+import { defineMcpTool, textContent } from 'src/types'
 
 interface WorktreesOpenResult {
   openedCmux: string[]
@@ -23,7 +24,7 @@ interface WorktreesOpenResult {
  * workspace exists per worktree. Idempotent and additive — never removes
  * worktrees, never recreates running cmux workspaces.
  */
-export const worktreesOpen = async (): Promise<ToolsExecutionResult> => {
+export const worktreesOpen = async () => {
   commandEcho.start('worktrees-open')
 
   try {
@@ -46,12 +47,15 @@ export const worktreesOpen = async (): Promise<ToolsExecutionResult> => {
     commandEcho.print()
 
     return {
-      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      content: textContent(JSON.stringify(result, null, 2)),
       structuredContent: { ...result },
     }
   } catch (error) {
     logger.error({ error }, '❌ Error opening worktrees')
-    throw error
+    throw new OperationError(error, {
+      operation: 'open worktrees',
+      remediation: "run 'worktrees-list' to confirm the branches exist",
+    })
   }
 }
 
@@ -180,7 +184,7 @@ const logResults = (result: WorktreesOpenResult, context: LogResultsContext): vo
 }
 
 // MCP Tool Registration
-export const worktreesOpenMcpTool = {
+export const worktreesOpenMcpTool = defineMcpTool({
   name: 'worktrees-open',
   description:
     'Open Cursor against the configured workspace file and ensure a cmux workspace exists for each existing release worktree. Idempotent and additive — never removes worktrees, never recreates running cmux workspaces. Use after a cold start (Cursor + cmux closed). For stale-worktree cleanup, use worktrees-sync.',
@@ -194,4 +198,4 @@ export const worktreesOpenMcpTool = {
       .describe('Number of dangling worktree folders removed from the Cursor workspace file'),
   },
   handler: worktreesOpen,
-}
+})

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