infra-kit 0.1.98 → 0.1.100

package/src/commands/gh-release-deliver/gh-release-deliver.ts

@@ -7,23 +7,103 @@ import { $ } from 'zx'
 import { getReleasePRsWithInfo } from 'src/integrations/gh'
 import { deliverJiraRelease, loadJiraConfigOptional } from 'src/integrations/jira'
 import { commandEcho } from 'src/lib/command-echo'
+import { formatZxError } from 'src/lib/errors/format-zx-error'
+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 type { RequiredConfirmedOptionArg, ToolsExecutionResult } from 'src/types'
+import { defineMcpTool, textContent } from 'src/types'
+import type { RequiredConfirmedOptionArg } from 'src/types'
 
 interface GhReleaseDeliverArgs extends RequiredConfirmedOptionArg {
   version: string
 }
 
+type PRState = 'OPEN' | 'MERGED' | 'CLOSED'
+
+interface PRStatus {
+  number: number
+  state: PRState
+  title: string
+}
+
 /**
- * Deliver a release branch to production
+ * Wrap a delivery step so its failure logs structured zx fields and surfaces
+ * an `OperationError` whose message names the actual step that failed —
+ * instead of the previous blanket "merging release branch into dev" message.
  */
-export const ghReleaseDeliver = async (args: GhReleaseDeliverArgs): Promise<ToolsExecutionResult> => {
-  const { version, confirmedCommand } = args
+const runStep = async <T>(operation: string, remediation: string, fn: () => Promise<T>): Promise<T> => {
+  try {
+    return await fn()
+  } catch (error) {
+    logger.error({ err: formatZxError(error) }, `❌ Failed to ${operation}`)
+    throw new OperationError(error, { operation, remediation })
+  }
+}
 
-  commandEcho.start('release-deliver')
+/**
+ * Fetch the (most-recent) PR for the given head branch, across all states, so
+ * we can resume a partially-completed delivery: a PR merged on a prior attempt
+ * still appears here as `state: 'MERGED'`, letting the caller skip the merge.
+ */
+const fetchPRByHead = async (head: string): Promise<PRStatus | null> => {
+  const result = await $`gh pr list --head ${head} --state all --json number,state,title --limit 1`
+  const prs = JSON.parse(result.stdout) as PRStatus[]
+
+  return prs[0] ?? null
+}
+
+/**
+ * Find a MERGED RC PR (dev → main) whose title matches the given version, used
+ * to detect that a prior delivery run already merged the RC and we should skip
+ * the merge step on resume. Title-matched on purpose: an older MERGED RC PR
+ * from a different release must not short-circuit this version's flow.
+ */
+const fetchMergedRcPRForVersion = async (version: string): Promise<PRStatus | null> => {
+  const expectedTitle = `Release v${version} (RC)`
+  const result = await $`gh pr list --head dev --base main --state merged --json number,state,title --limit 20`
+  const prs = JSON.parse(result.stdout) as PRStatus[]
+  const match = prs.find((pr) => {
+    return pr.title === expectedTitle
+  })
 
+  return match ?? null
+}
+
+/**
+ * Find an open dev → main PR, if any. GitHub allows at most one open PR per
+ * head/base pair, so an existing open PR here is the RC PR for this release —
+ * even if its title was set by a previous (failed) delivery run. Adopting it
+ * is what makes the flow recoverable after a mid-run failure.
+ */
+const fetchOpenDevToMainPR = async (): Promise<PRStatus | null> => {
+  const result = await $`gh pr list --head dev --base main --state open --json number,state,title --limit 5`
+  const prs = JSON.parse(result.stdout) as PRStatus[]
+
+  return prs[0] ?? null
+}
+
+interface ResolvedTarget {
+  selectedReleaseBranch: string
+  releasePrTitle: string
+}
+
+const resolveTargetFromVersion = async (version: string): Promise<ResolvedTarget> => {
+  const selectedReleaseBranch = `release/v${version}`
+  const pr = await fetchPRByHead(selectedReleaseBranch)
+
+  if (!pr) {
+    logger.error(`❌ No PR found for branch ${selectedReleaseBranch}.`)
+    throw new OperationError(undefined, {
+      operation: `deliver release ${selectedReleaseBranch}`,
+      remediation: `confirm a PR exists ('gh pr list --head ${selectedReleaseBranch} --state all')`,
+    })
+  }
+
+  return { selectedReleaseBranch, releasePrTitle: pr.title }
+}
+
+const resolveTargetInteractively = async (): Promise<ResolvedTarget> => {
   const releasePRsInfo = await getReleasePRsWithInfo()
 
   const branches = releasePRsInfo.map((pr) => {
@@ -36,36 +116,199 @@ export const ghReleaseDeliver = async (args: GhReleaseDeliverArgs): Promise<Tool
     }),
   )
 
-  let selectedReleaseBranch = '' // "release/v1.8.0"
+  commandEcho.setInteractive()
 
-  if (version) {
-    selectedReleaseBranch = `release/v${version}`
-  } else {
-    commandEcho.setInteractive()
+  const descriptions = await getJiraDescriptions()
+
+  const selectedReleaseBranch = await select({
+    message: '🌿 Select release branch',
+    choices: formatBranchChoices({ branches, descriptions, types: releaseTypes }),
+  })
 
-    const descriptions = await getJiraDescriptions()
+  const prInfo = releasePRsInfo.find((pr) => {
+    return pr.branch === selectedReleaseBranch
+  })
 
-    selectedReleaseBranch = await select({
-      message: '🌿 Select release branch',
-      choices: formatBranchChoices({ branches, descriptions, types: releaseTypes }),
+  if (!prInfo) {
+    logger.error(`❌ Release branch ${selectedReleaseBranch} not found in open PRs.`)
+    throw new OperationError(undefined, {
+      operation: `deliver release ${selectedReleaseBranch}`,
+      remediation: `confirm an open PR exists for ${selectedReleaseBranch} ('gh pr list')`,
     })
   }
 
-  const selectedVersion = selectedReleaseBranch.replace('release/v', '')
+  return { selectedReleaseBranch, releasePrTitle: prInfo.title }
+}
 
-  commandEcho.addOption('--version', selectedVersion)
+interface MergeReleasePRArgs {
+  selectedReleaseBranch: string
+  releaseType: ReleaseType
+}
 
-  // Check if release branch exists in the list
-  const prInfo = releasePRsInfo.find((pr) => {
-    return pr.branch === selectedReleaseBranch
-  })
+const mergeReleasePR = async (args: MergeReleasePRArgs): Promise<void> => {
+  const { selectedReleaseBranch, releaseType } = args
+  const mergeTarget = releaseType === 'hotfix' ? 'main' : 'dev'
+  const releasePr = await fetchPRByHead(selectedReleaseBranch)
 
-  if (!prInfo) {
-    logger.error(`❌ Release branch ${selectedReleaseBranch} not found in open PRs. Exiting...`)
-    process.exit(1)
+  if (!releasePr) {
+    throw new OperationError(undefined, {
+      operation: `look up release PR for ${selectedReleaseBranch}`,
+      remediation: `verify the PR exists in GitHub`,
+    })
   }
 
-  const releaseType: ReleaseType = detectReleaseType(prInfo.title)
+  if (releasePr.state === 'MERGED') {
+    logger.info(`✓ Release PR ${selectedReleaseBranch} already merged — skipping`)
+
+    return
+  }
+
+  if (releasePr.state === 'CLOSED') {
+    throw new OperationError(undefined, {
+      operation: `merge release PR ${selectedReleaseBranch} into ${mergeTarget}`,
+      remediation: `the PR is closed without merge; reopen it or create a new release`,
+    })
+  }
+
+  await runStep(
+    `merge release PR ${selectedReleaseBranch} into ${mergeTarget}`,
+    `check 'gh pr view ${selectedReleaseBranch}' for mergeability and required reviews`,
+    async () => {
+      await $`gh pr merge ${selectedReleaseBranch} --squash --admin --delete-branch`
+    },
+  )
+}
+
+const resolveRcPRNumber = async (selectedVersion: string): Promise<number> => {
+  const expectedTitle = `Release v${selectedVersion} (RC)`
+  const existingOpen = await fetchOpenDevToMainPR()
+
+  // Adopt any existing open dev→main PR. GitHub permits only one open PR per
+  // head/base pair, so a stale open RC PR (left behind by a prior failed run
+  // — the single most common cause of "Error merging release branch into
+  // dev") blocks `gh pr create`. Retitle it instead of fighting it.
+  if (existingOpen) {
+    const rcNumber = existingOpen.number
+
+    if (existingOpen.title !== expectedTitle) {
+      logger.info(
+        `Adopting open dev → main PR #${rcNumber} ("${existingOpen.title}") and retitling for v${selectedVersion}`,
+      )
+      await runStep(
+        `retitle dev → main PR #${rcNumber} to "${expectedTitle}"`,
+        `update manually: gh pr edit ${rcNumber} --title "${expectedTitle}"`,
+        async () => {
+          await $`gh pr edit ${rcNumber} --title ${expectedTitle}`
+        },
+      )
+    }
+
+    return rcNumber
+  }
+
+  await runStep(
+    `create RC PR (dev → main) for v${selectedVersion}`,
+    `run 'gh pr create --base main --head dev' manually to surface the underlying error (e.g. no commits between dev and main)`,
+    async () => {
+      await $`gh pr create --base main --head dev --title ${expectedTitle} --body ""`
+    },
+  )
+
+  const created = await fetchOpenDevToMainPR()
+
+  if (!created) {
+    throw new OperationError(undefined, {
+      operation: `look up RC PR for v${selectedVersion}`,
+      remediation: `verify the RC PR was created ('gh pr list --head dev --base main')`,
+    })
+  }
+
+  return created.number
+}
+
+const ensureRcPRMerged = async (selectedVersion: string): Promise<void> => {
+  const alreadyMerged = await fetchMergedRcPRForVersion(selectedVersion)
+
+  if (alreadyMerged) {
+    logger.info(`✓ RC PR for v${selectedVersion} already merged into main — skipping`)
+
+    return
+  }
+
+  const rcNumber = await resolveRcPRNumber(selectedVersion)
+
+  await runStep(
+    `merge RC PR #${rcNumber} (dev → main) for v${selectedVersion}`,
+    `check 'gh pr view ${rcNumber}' for mergeability and required reviews`,
+    async () => {
+      await $`gh pr merge ${rcNumber} --squash --admin`
+    },
+  )
+}
+
+const dispatchDeployWorkflow = async (): Promise<void> => {
+  $.quiet = false
+
+  await runStep(
+    `dispatch deploy-all workflow on main`,
+    `check 'gh workflow list' and that you have permission to dispatch deploy-all.yml`,
+    async () => {
+      await $`gh workflow run deploy-all.yml --ref main -f environment=prod`
+    },
+  )
+
+  $.quiet = true
+}
+
+const syncMainIntoDev = async (): Promise<void> => {
+  await runStep(
+    `sync main back into dev`,
+    `run manually: git switch main && git pull && git switch dev && git pull && git merge main --no-edit && git push`,
+    async () => {
+      await $`git switch main && git pull && git switch dev && git pull && git merge main --no-edit && git push`
+    },
+  )
+}
+
+const deliverJiraReleaseSafely = async (selectedReleaseBranch: string): Promise<void> => {
+  const jiraConfig = await loadJiraConfigOptional()
+
+  if (!jiraConfig) {
+    logger.info('🔔 Jira is not configured, skipping Jira release delivery')
+
+    return
+  }
+
+  try {
+    const versionName = selectedReleaseBranch.replace('release/', '')
+
+    await deliverJiraRelease({ versionName }, jiraConfig)
+  } catch (error) {
+    logger.error({ err: formatZxError(error) }, 'Failed to deliver Jira release (non-blocking)')
+  }
+}
+
+/**
+ * Deliver a release branch to production. Each network/git step is run inside
+ * `runStep` so the surfaced error names the failing operation and includes the
+ * subprocess stderr. PR-merge steps are idempotent: if the release PR or RC PR
+ * is already MERGED, the step is skipped, so re-running after a mid-flight
+ * failure picks up where it stopped.
+ */
+export const ghReleaseDeliver = async (args: GhReleaseDeliverArgs) => {
+  const { version, confirmedCommand } = args
+
+  commandEcho.start('release-deliver')
+
+  const { selectedReleaseBranch, releasePrTitle } = version
+    ? await resolveTargetFromVersion(version)
+    : await resolveTargetInteractively()
+
+  const selectedVersion = selectedReleaseBranch.replace('release/v', '')
+
+  commandEcho.addOption('--version', selectedVersion)
+
+  const releaseType: ReleaseType = detectReleaseType(releasePrTitle)
 
   const answer = confirmedCommand
     ? true
@@ -85,85 +328,43 @@ export const ghReleaseDeliver = async (args: GhReleaseDeliverArgs): Promise<Tool
   // Track --yes flag if confirmation was interactive (user confirmed)
   commandEcho.addOption('--yes', true)
 
-  try {
-    $.quiet = true
-
-    if (releaseType === 'hotfix') {
-      // Hotfix: merge directly into main, deploy, sync back to dev
-      await $`gh pr merge ${selectedReleaseBranch} --squash --admin --delete-branch`
-
-      $.quiet = false
-
-      await $`gh workflow run deploy-all.yml --ref main -f environment=prod`
-
-      $.quiet = true
+  $.quiet = true
 
-      // Sync main into dev
-      await $`git switch main && git pull && git switch dev && git pull && git merge main --no-edit && git push`
-    } else {
-      // Regular: merge into dev, create RC PR to main, merge to main, deploy, sync
-      await $`gh pr merge ${selectedReleaseBranch} --squash --admin --delete-branch`
-      await $`gh pr create --base main --head dev --title "Release v${selectedVersion} (RC)" --body ""`
-      await $`gh pr merge dev --squash --admin`
-
-      $.quiet = false
-
-      await $`gh workflow run deploy-all.yml --ref main -f environment=prod`
-
-      $.quiet = true
-
-      // Sync main into dev
-      await $`git switch main && git pull && git switch dev && git pull && git merge main --no-edit && git push`
-    }
+  await mergeReleasePR({ selectedReleaseBranch, releaseType })
 
-    $.quiet = false
+  if (releaseType !== 'hotfix') {
+    await ensureRcPRMerged(selectedVersion)
+  }
 
-    // Deliver Jira release if Jira is configured
-    const jiraConfig = await loadJiraConfigOptional()
+  await dispatchDeployWorkflow()
+  await syncMainIntoDev()
 
-    if (jiraConfig) {
-      try {
-        const versionName = selectedReleaseBranch.replace('release/', '')
+  $.quiet = false
 
-        await deliverJiraRelease({ versionName }, jiraConfig)
-      } catch (error) {
-        logger.error({ error }, 'Failed to deliver Jira release (non-blocking)')
-      }
-    } else {
-      logger.info('🔔 Jira is not configured, skipping Jira release delivery')
-    }
+  await deliverJiraReleaseSafely(selectedReleaseBranch)
 
-    logger.info(`Successfully delivered ${selectedReleaseBranch} to production!`)
+  logger.info(`Successfully delivered ${selectedReleaseBranch} to production!`)
 
-    commandEcho.print()
+  commandEcho.print()
 
-    const structuredContent = {
-      releaseBranch: selectedReleaseBranch,
-      version: selectedReleaseBranch.replace('release/v', ''),
-      type: releaseType,
-      success: true,
-    }
+  const structuredContent = {
+    releaseBranch: selectedReleaseBranch,
+    version: selectedVersion,
+    type: releaseType,
+    success: true,
+  }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(structuredContent, null, 2),
-        },
-      ],
-      structuredContent,
-    }
-  } catch (error: unknown) {
-    logger.error({ error }, '❌ Error merging release branch into dev')
-    process.exit(1)
+  return {
+    content: textContent(JSON.stringify(structuredContent, null, 2)),
+    structuredContent,
   }
 }
 
 // MCP Tool Registration
-export const ghReleaseDeliverMcpTool = {
+export const ghReleaseDeliverMcpTool = defineMcpTool({
   name: 'gh-release-deliver',
   description:
-    'Deliver a release to production. For hotfixes: squash-merges the release branch to main and dispatches the deploy-all workflow. For regular releases: squash-merges to dev, opens an RC PR, merges dev into main, dispatches the deploy-all workflow, then syncs main back to dev. Also releases the matching Jira fix version if Jira is configured. Dispatches the deploy workflow fire-and-forget — the tool returns once the workflow is accepted by GitHub, not when the deployment finishes. Irreversible production operation: the confirmation prompt is auto-skipped for MCP calls, so the caller is responsible for gating. "version" is required when invoked via MCP (the picker is unreachable without a TTY).',
+    'Deliver a release to production. For hotfixes: squash-merges the release branch to main and dispatches the deploy-all workflow. For regular releases: squash-merges to dev, opens an RC PR, merges dev into main, dispatches the deploy-all workflow, then syncs main back to dev. Also releases the matching Jira fix version if Jira is configured. Dispatches the deploy workflow fire-and-forget — the tool returns once the workflow is accepted by GitHub, not when the deployment finishes. PR-merge steps are idempotent: re-running after a partial failure skips PRs that are already merged. Irreversible production operation: the confirmation prompt is auto-skipped for MCP calls, so the caller is responsible for gating. "version" is required when invoked via MCP (the picker is unreachable without a TTY).',
   inputSchema: {
     version: z.string().describe('Release version to deliver to production (e.g., "1.2.5"). Required for MCP calls.'),
   },
@@ -174,4 +375,4 @@ export const ghReleaseDeliverMcpTool = {
     success: z.boolean().describe('Whether the delivery was successful'),
   },
   handler: ghReleaseDeliver,
-}
+})

package/src/commands/gh-release-deploy-all/gh-release-deploy-all.ts

@@ -1,15 +1,15 @@
 import select from '@inquirer/select'
-import process from 'node:process'
 import { z } from 'zod/v4'
 import { $ } from 'zx'
 
 import { getReleasePRsWithInfo } from 'src/integrations/gh'
 import { commandEcho } from 'src/lib/command-echo'
+import { OperationError } from 'src/lib/errors/operation-error'
 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 { ToolsExecutionResult } from 'src/types'
+import { defineMcpTool, textContent } from 'src/types'
 
 interface GhReleaseDeployAllArgs {
   version: string
@@ -20,7 +20,7 @@ interface GhReleaseDeployAllArgs {
 /**
  * Deploy a release branch to an environment
  */
-export const ghReleaseDeployAll = async (args: GhReleaseDeployAllArgs): Promise<ToolsExecutionResult> => {
+export const ghReleaseDeployAll = async (args: GhReleaseDeployAllArgs) => {
   const { version, env, skipTerraform } = args
 
   commandEcho.start('release-deploy-all')
@@ -79,8 +79,11 @@ export const ghReleaseDeployAll = async (args: GhReleaseDeployAllArgs): Promise<
   commandEcho.addOption('--env', selectedEnv)
 
   if (!environments.includes(selectedEnv)) {
-    logger.error(`❌ Invalid environment: ${selectedEnv}. Exiting...`)
-    process.exit(1)
+    throw new OperationError(undefined, {
+      operation: 'launch deploy-all workflow',
+      remediation: `pass one of: ${environments.join(', ')}`,
+      stderrExcerpt: `invalid environment: ${selectedEnv}`,
+    })
   }
 
   const shouldSkipTerraform = skipTerraform ?? false
@@ -113,22 +116,20 @@ export const ghReleaseDeployAll = async (args: GhReleaseDeployAllArgs): Promise<
     }
 
     return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(structuredContent, null, 2),
-        },
-      ],
+      content: textContent(JSON.stringify(structuredContent, null, 2)),
       structuredContent,
     }
   } catch (error: unknown) {
     logger.error({ error }, '❌ Error launching workflow')
-    process.exit(1)
+    throw new OperationError(error, {
+      operation: 'launch deploy-all workflow',
+      remediation: "check 'gh workflow list' and that deploy-all.yml exists on the target ref",
+    })
   }
 }
 
 // MCP Tool Registration
-export const ghReleaseDeployAllMcpTool = {
+export const ghReleaseDeployAllMcpTool = defineMcpTool({
   name: 'gh-release-deploy-all',
   description:
     'Dispatch the deploy-all.yml GitHub Actions workflow to deploy every service from a release branch to the given environment. Fire-and-forget — returns once GitHub accepts the workflow_dispatch, NOT when the deployment finishes; watch the workflow run for completion status. Use gh-release-deploy-selected for a subset of services. Pass version="dev" to deploy from the dev branch instead of a release branch. Both "version" and "env" are required when invoked via MCP (interactive pickers are unavailable without a TTY).',
@@ -153,4 +154,4 @@ export const ghReleaseDeployAllMcpTool = {
     success: z.boolean().describe('Whether the deployment was successful'),
   },
   handler: ghReleaseDeployAll,
-}
+})

package/src/commands/gh-release-deploy-selected/gh-release-deploy-selected.ts

@@ -2,19 +2,19 @@ import checkbox from '@inquirer/checkbox'
 import select from '@inquirer/select'
 import fs from 'node:fs/promises'
 import { resolve } from 'node:path'
-import process from 'node:process'
 import yaml from 'yaml'
 import { z } from 'zod/v4'
 import { $ } from 'zx'
 
 import { getReleasePRsWithInfo } from 'src/integrations/gh'
 import { commandEcho } from 'src/lib/command-echo'
+import { OperationError } from 'src/lib/errors/operation-error'
 import { getProjectRoot } 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 { ToolsExecutionResult } from 'src/types'
+import { defineMcpTool, textContent } from 'src/types'
 
 interface GhReleaseDeploySelectedArgs {
   version: string
@@ -27,7 +27,7 @@ interface GhReleaseDeploySelectedArgs {
  * Deploy selected services from a release branch to an environment
  */
 // eslint-disable-next-line sonarjs/cognitive-complexity
-export const ghReleaseDeploySelected = async (args: GhReleaseDeploySelectedArgs): Promise<ToolsExecutionResult> => {
+export const ghReleaseDeploySelected = async (args: GhReleaseDeploySelectedArgs) => {
   const { version, env, services, skipTerraform } = args
 
   commandEcho.start('release-deploy-selected')
@@ -86,17 +86,22 @@ export const ghReleaseDeploySelected = async (args: GhReleaseDeploySelectedArgs)
   commandEcho.addOption('--env', selectedEnv)
 
   if (!environments.includes(selectedEnv)) {
-    logger.error(`❌ Invalid environment: ${selectedEnv}. Exiting...`)
-    process.exit(1)
+    throw new OperationError(undefined, {
+      operation: 'launch deploy-selected workflow',
+      remediation: `pass one of: ${environments.join(', ')}`,
+      stderrExcerpt: `invalid environment: ${selectedEnv}`,
+    })
   }
 
   // Parse available services from workflow file
   const availableServices = await parseServicesFromWorkflow()
 
   if (availableServices.length === 0) {
-    logger.error('❌ No services found in workflow file. Exiting...')
-
-    process.exit(1)
+    throw new OperationError(undefined, {
+      operation: 'launch deploy-selected workflow',
+      remediation: 'check .github/workflows/deploy-selected-services.yml for boolean service inputs',
+      stderrExcerpt: 'no services found in workflow file',
+    })
   }
 
   let selectedServices: string[] = []
@@ -120,8 +125,11 @@ export const ghReleaseDeploySelected = async (args: GhReleaseDeploySelectedArgs)
   commandEcho.addOption('--services', selectedServices)
 
   if (selectedServices.length === 0) {
-    logger.error('❌ No services selected. Exiting...')
-    process.exit(1)
+    throw new OperationError(undefined, {
+      operation: 'launch deploy-selected workflow',
+      remediation: `pass at least one service from: ${availableServices.join(', ')}`,
+      stderrExcerpt: 'no services selected',
+    })
   }
 
   // Validate all selected services
@@ -130,10 +138,11 @@ export const ghReleaseDeploySelected = async (args: GhReleaseDeploySelectedArgs)
   })
 
   if (invalidServices.length > 0) {
-    logger.error(
-      `❌ Invalid services: ${invalidServices.join(', ')}. Available services: ${availableServices.join(', ')}`,
-    )
-    process.exit(1)
+    throw new OperationError(undefined, {
+      operation: 'launch deploy-selected workflow',
+      remediation: `pass services from: ${availableServices.join(', ')}`,
+      stderrExcerpt: `invalid services: ${invalidServices.join(', ')}`,
+    })
   }
 
   const shouldSkipTerraform = skipTerraform ?? false
@@ -171,17 +180,15 @@ export const ghReleaseDeploySelected = async (args: GhReleaseDeploySelectedArgs)
     }
 
     return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(structuredContent, null, 2),
-        },
-      ],
+      content: textContent(JSON.stringify(structuredContent, null, 2)),
       structuredContent,
     }
   } catch (error: unknown) {
     logger.error({ error }, '❌ Error launching workflow')
-    process.exit(1)
+    throw new OperationError(error, {
+      operation: 'launch deploy-selected workflow',
+      remediation: "check 'gh workflow list' and that deploy-selected-services.yml exists on the target ref",
+    })
   }
 }
 
@@ -211,7 +218,7 @@ const parseServicesFromWorkflow = async (): Promise<string[]> => {
 }
 
 // MCP Tool Registration
-export const ghReleaseDeploySelectedMcpTool = {
+export const ghReleaseDeploySelectedMcpTool = defineMcpTool({
   name: 'gh-release-deploy-selected',
   description:
     'Dispatch the deploy-selected-services.yml GitHub Actions workflow to deploy a chosen subset of services from a release branch to the given environment. Fire-and-forget — returns once GitHub accepts the workflow_dispatch, NOT when the deployment finishes; watch the workflow run for completion status. Service names are validated against the boolean inputs declared in the workflow. Use gh-release-deploy-all for every service. "version", "env", and "services" are all required when invoked via MCP (interactive pickers are unavailable without a TTY).',
@@ -242,4 +249,4 @@ export const ghReleaseDeploySelectedMcpTool = {
     success: z.boolean().describe('Whether the deployment was successful'),
   },
   handler: ghReleaseDeploySelected,
-}
+})