infra-kit 0.1.85 → 0.1.87

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "infra-kit",
   "type": "module",
-  "version": "0.1.85",
+  "version": "0.1.87",
   "description": "infra-kit",
   "main": "dist/cli.js",
   "module": "dist/cli.js",
@@ -17,8 +17,8 @@
     "build": "pnpm run clean-artifacts && node ./scripts/build.js",
     "clean-artifacts": "rm -rf dist",
     "clean-cache": "rm -rf node_modules/.cache .eslintcache tsconfig.tsbuildinfo .turbo .swc",
-    "prettier-fix": "pnpm exec prettier **/* --write --no-error-on-unmatched-pattern --log-level warn --ignore-path ../../.prettierignore",
-    "prettier-check": "pnpm exec prettier **/* --check --no-error-on-unmatched-pattern --log-level warn --ignore-path ../../.prettierignore",
+    "prettier-fix": "pnpm exec prettier **/* --write --no-error-on-unmatched-pattern --log-level warn --ignore-path ../../../.prettierignore",
+    "prettier-check": "pnpm exec prettier **/* --check --no-error-on-unmatched-pattern --log-level warn --ignore-path ../../../.prettierignore",
     "eslint-check": "pnpm exec eslint --cache --quiet --report-unused-disable-directives ./src",
     "eslint-fix": "pnpm exec eslint --cache --quiet --report-unused-disable-directives ./src --fix",
     "ts-check": "tsc --noEmit",

package/src/commands/env-clear/env-clear.ts

@@ -60,6 +60,7 @@ export const envClear = async (): Promise<ToolsExecutionResult> => {
   fs.unlinkSync(envLoadPath)
 
   const structuredContent = {
+    filePath: clearFilePath,
     variableCount: varNames.length,
     unsetStatements: unsetLines,
   }
@@ -79,7 +80,7 @@ export const envClear = async (): Promise<ToolsExecutionResult> => {
 export const envClearMcpTool = {
   name: 'env-clear',
   description:
-    'Clear loaded env vars. Returns a file path that must be sourced (source <path>) to apply. The env-clear shell alias does this automatically.',
+    'Generate a shell script that unsets every env var previously loaded by env-load for this session, plus the infra-kit session metadata vars. Does NOT mutate the calling process — returns the path to a script that must be sourced ("source <filePath>") for the unsets to take effect. The infra-kit shell wrapper auto-sources; direct MCP callers must handle sourcing themselves or surface filePath to the user. Errors if no env is currently loaded.',
   inputSchema: {},
   outputSchema: {
     filePath: z.string().describe('Path to the file that must be sourced to apply'),

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

@@ -40,7 +40,8 @@ export const envList = async (): Promise<ToolsExecutionResult> => {
 // MCP Tool Registration
 export const envListMcpTool = {
   name: 'env-list',
-  description: 'List available Doppler configs for the detected project',
+  description:
+    'List the environments the project is configured to support. Returns a static list defined in infra-kit constants (not a live fetch from Doppler) plus the Doppler project name auto-detected from the current directory. Read-only.',
   inputSchema: {},
   outputSchema: {
     project: z.string().describe('Detected Doppler project name'),

package/src/commands/env-load/env-load.ts

@@ -88,6 +88,7 @@ export const envLoad = async (args: EnvLoadArgs): Promise<ToolsExecutionResult>
   }).length
 
   const structuredContent = {
+    filePath: envFilePath,
     variableCount: varCount,
     project,
     config: selectedConfig,
@@ -108,9 +109,11 @@ export const envLoad = async (args: EnvLoadArgs): Promise<ToolsExecutionResult>
 export const envLoadMcpTool = {
   name: 'env-load',
   description:
-    'Load Doppler env vars for a config. Returns a file path that must be sourced (source <path>) to apply variables. The env-load shell alias does this automatically.',
+    'Download the env vars for a Doppler config and write them to a temporary shell script. Does NOT mutate the calling process — returns the path to a script that must be sourced ("source <filePath>") for the vars to take effect. The infra-kit shell wrapper auto-sources; direct MCP callers must handle sourcing themselves or surface filePath to the user. "config" is required when invoked via MCP (the CLI interactive picker is unreachable without a TTY).',
   inputSchema: {
-    config: z.string().describe('Environment config name to load (e.g. dev, arthur, renana)'),
+    config: z
+      .string()
+      .describe('Doppler config / environment name to load (e.g. "dev", "arthur", "renana"). Required for MCP calls.'),
   },
   outputSchema: {
     filePath: z.string().describe('Path to the file that must be sourced to apply variables'),

package/src/commands/env-status/env-status.ts

@@ -78,7 +78,8 @@ export const envStatus = async (): Promise<ToolsExecutionResult> => {
 // MCP Tool Registration
 export const envStatusMcpTool = {
   name: 'env-status',
-  description: 'Show Doppler authentication status and detected project info',
+  description:
+    'Report which Doppler project/config is currently loaded in the terminal session, when it was loaded, and how many variables are cached. Read-only — use env-load / env-clear to change the terminal session.',
   inputSchema: {},
   outputSchema: {
     sessionId: z.string().describe('Current terminal session ID'),

package/src/commands/gh-merge-dev/gh-merge-dev.ts

@@ -186,9 +186,15 @@ const mergeDev = async (branch: string): Promise<boolean> => {
 // MCP Tool Registration
 export const ghMergeDevMcpTool = {
   name: 'gh-merge-dev',
-  description: 'Merge dev branch into selected release branches',
+  description:
+    'Merge origin/dev into every open regular (non-hotfix) release branch and push the result. Mutates local git state and the remote release branches. When invoked via MCP, pass all=true — the branch picker is unreachable without a TTY, and the confirmation prompt is auto-skipped for MCP calls, so the caller is responsible for gating. Irreversible once pushed.',
   inputSchema: {
-    all: z.boolean().describe('Merge dev into all release branches without prompting'),
+    all: z
+      .boolean()
+      .optional()
+      .describe(
+        'Target every open regular release branch. Must be true for MCP calls (the interactive picker is unavailable without a TTY).',
+      ),
   },
   outputSchema: {
     successfulMerges: z.number().describe('Number of successful merges'),

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

@@ -162,9 +162,10 @@ export const ghReleaseDeliver = async (args: GhReleaseDeliverArgs): Promise<Tool
 // MCP Tool Registration
 export const ghReleaseDeliverMcpTool = {
   name: 'gh-release-deliver',
-  description: 'Deliver a release branch to production',
+  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).',
   inputSchema: {
-    version: z.string().describe('Version to deliver to production (e.g., "1.2.5")'),
+    version: z.string().describe('Release version to deliver to production (e.g., "1.2.5"). Required for MCP calls.'),
   },
   outputSchema: {
     releaseBranch: z.string().describe('The release branch that was delivered'),

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

@@ -128,11 +128,20 @@ export const ghReleaseDeployAll = async (args: GhReleaseDeployAllArgs): Promise<
 // MCP Tool Registration
 export const ghReleaseDeployAllMcpTool = {
   name: 'gh-release-deploy-all',
-  description: 'Deploy a release branch to a specified environment',
+  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).',
   inputSchema: {
-    version: z.string().describe('Version to deploy (e.g., "1.2.5")'),
-    env: z.string().describe('Environment to deploy to (e.g., "dev", "renana", "oriana")'),
-    skipTerraform: z.boolean().optional().describe('Skip terraform deployment step'),
+    version: z
+      .string()
+      .describe(
+        'Release version to deploy from (e.g. "1.2.5") — resolves to the release/vX.Y.Z branch. Pass "dev" to deploy from the dev branch instead. Required for MCP calls.',
+      ),
+    env: z
+      .string()
+      .describe(
+        'Target environment name — must match an env configured for the project (e.g. "dev", "renana", "oriana"). Required for MCP calls.',
+      ),
+    skipTerraform: z.boolean().optional().describe('Skip the terraform deployment stage.'),
   },
   outputSchema: {
     releaseBranch: z.string().describe('The release branch that was deployed'),

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

@@ -211,12 +211,25 @@ const parseServicesFromWorkflow = async (): Promise<string[]> => {
 // MCP Tool Registration
 export const ghReleaseDeploySelectedMcpTool = {
   name: 'gh-release-deploy-selected',
-  description: 'Deploy selected services from a release branch to a specified environment',
+  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).',
   inputSchema: {
-    version: z.string().describe('Version to deploy (e.g., "1.2.5")'),
-    env: z.string().describe('Environment to deploy to (e.g., "dev", "renana", "oriana")'),
-    services: z.array(z.string()).describe('List of services to deploy (e.g., ["client-be", "client-fe"])'),
-    skipTerraform: z.boolean().optional().describe('Skip terraform deployment step'),
+    version: z
+      .string()
+      .describe(
+        'Release version to deploy from (e.g. "1.2.5") — resolves to the release/vX.Y.Z branch. Pass "dev" to deploy from the dev branch instead. Required for MCP calls.',
+      ),
+    env: z
+      .string()
+      .describe(
+        'Target environment name — must match an env configured for the project (e.g. "dev", "renana", "oriana"). Required for MCP calls.',
+      ),
+    services: z
+      .array(z.string())
+      .describe(
+        'Service names to deploy. Each must match a boolean input declared in .github/workflows/deploy-selected-services.yml (e.g. "client-be", "client-fe"). Required for MCP calls.',
+      ),
+    skipTerraform: z.boolean().optional().describe('Skip the terraform deployment stage.'),
   },
   outputSchema: {
     releaseBranch: z.string().describe('The release branch that was deployed'),

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

@@ -65,7 +65,8 @@ export const ghReleaseList = async (): Promise<ToolsExecutionResult> => {
 // MCP Tool Registration
 export const ghReleaseListMcpTool = {
   name: 'gh-release-list',
-  description: 'List all open release branches',
+  description:
+    'List every open release PR with its version, type (regular / hotfix), and associated Jira fix-version description. Read-only; sourced from GitHub and Jira.',
   inputSchema: {},
   outputSchema: {
     releases: z

package/src/commands/release-create/release-create.ts

@@ -160,9 +160,10 @@ export const releaseCreate = async (args: ReleaseCreateArgs): Promise<ToolsExecu
 // MCP Tool Registration
 export const releaseCreateMcpTool = {
   name: 'release-create',
-  description: 'Create a single release branch for specified version with Jira version creation',
+  description:
+    'Create a new release: cuts the release branch off the appropriate base (dev for regular releases, main for hotfixes), opens a GitHub release PR, creates the matching Jira fix version, and optionally checks out to the new branch. Confirmation is auto-skipped for MCP calls, so the caller is responsible for gating. "version" is required when invoked via MCP (the interactive input prompt is unreachable without a TTY); "type" / "description" / "checkout" default to regular / empty / true when omitted.',
   inputSchema: {
-    version: z.string().describe('Version to create (e.g., "1.2.5")'),
+    version: z.string().describe('Version to create (e.g., "1.2.5"). Required for MCP calls.'),
     description: z.string().optional().describe('Optional description for the Jira version'),
     type: z
       .enum(['regular', 'hotfix'])

package/src/commands/release-create-batch/release-create-batch.ts

@@ -158,9 +158,12 @@ export const releaseCreateBatch = async (args: ReleaseCreateBatchArgs): Promise<
 // MCP Tool Registration
 export const releaseCreateBatchMcpTool = {
   name: 'release-create-batch',
-  description: 'Create multiple release branches for specified versions with Jira version creation (batch operation)',
+  description:
+    'Create several releases in one pass: for each comma-separated version in "versions", cuts the release branch off the appropriate base (dev for regular releases, main for hotfixes), opens a GitHub PR, and creates the Jira fix version. Continues on per-version failure and reports which versions succeeded and which failed. Confirmation is auto-skipped for MCP calls, so the caller is responsible for gating. "versions" is required when invoked via MCP (the interactive input prompt is unreachable without a TTY). Use release-create for a single version with optional checkout.',
   inputSchema: {
-    versions: z.string().describe('Comma-separated list of versions to create (e.g., "1.2.5, 1.2.6")'),
+    versions: z
+      .string()
+      .describe('Comma-separated list of versions to create (e.g., "1.2.5, 1.2.6"). Required for MCP calls.'),
     type: z
       .enum(['regular', 'hotfix'])
       .optional()

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

@@ -268,12 +268,33 @@ const logResults = (created: string[]): void => {
 // MCP Tool Registration
 export const worktreesAddMcpTool = {
   name: 'worktrees-add',
-  description: 'Create git worktrees for selected release branches',
+  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" follow-up prompts are unreachable without a TTY, and the CLI confirmation is auto-skipped for MCP calls.',
   inputSchema: {
-    all: z.boolean().describe('Add git worktrees for all release branches without prompting'),
-    versions: z.string().optional().describe('Specify versions by comma, e.g. 1.2.5, 1.2.6'),
-    cursor: z.boolean().optional().describe('Open created git worktrees in Cursor'),
-    githubDesktop: z.boolean().optional().describe('Open created git worktrees in GitHub Desktop'),
+    all: z
+      .boolean()
+      .optional()
+      .describe(
+        'Add worktrees for every open release branch. Either "all" or "versions" must be provided for MCP calls (the interactive picker is unavailable without a TTY). Ignored if "versions" is provided.',
+      ),
+    versions: z
+      .string()
+      .optional()
+      .describe(
+        'Comma-separated release versions to target (e.g. "1.2.5, 1.2.6"). Either "versions" or all=true must be provided for MCP calls. Overrides "all" when set.',
+      ),
+    cursor: z
+      .boolean()
+      .optional()
+      .describe(
+        'Open each created worktree in Cursor. Defaults to false in MCP mode (the follow-up prompt is not shown).',
+      ),
+    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).',
+      ),
   },
   outputSchema: {
     createdWorktrees: z.array(z.string()).describe('List of created git worktree branches'),

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

@@ -83,7 +83,8 @@ export const worktreesList = async (): Promise<ToolsExecutionResult> => {
 // MCP Tool Registration
 export const worktreesListMcpTool = {
   name: 'worktrees-list',
-  description: 'List all git worktrees with detailed information',
+  description:
+    'List existing release-branch worktrees with version, release type (regular / hotfix), and Jira fix-version description. Read-only.',
   inputSchema: {},
   outputSchema: {
     worktrees: z

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

@@ -188,10 +188,21 @@ const logResults = (removed: string[]): void => {
 // MCP Tool Registration
 export const worktreesRemoveMcpTool = {
   name: 'worktrees-remove',
-  description: 'Remove selected worktrees',
+  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.',
   inputSchema: {
-    all: z.boolean().describe('Remove all git worktrees without prompting'),
-    versions: z.string().optional().describe('Specify versions by comma, e.g. 1.2.5, 1.2.6'),
+    all: z
+      .boolean()
+      .optional()
+      .describe(
+        'Remove every existing worktree. Either "all" or "versions" must be provided for MCP calls (the interactive picker is unavailable without a TTY). Ignored if "versions" is provided.',
+      ),
+    versions: z
+      .string()
+      .optional()
+      .describe(
+        'Comma-separated release versions to target (e.g. "1.2.5, 1.2.6"). Either "versions" or all=true must be provided for MCP calls. Overrides "all" when set.',
+      ),
   },
   outputSchema: {
     removedWorktrees: z.array(z.string()).describe('List of removed git worktree branches'),

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

@@ -145,7 +145,8 @@ const logResults = (removed: string[]): void => {
 // MCP Tool Registration
 export const worktreesSyncMcpTool = {
   name: 'worktrees-sync',
-  description: 'Synchronize worktrees with active release branches',
+  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.',
   inputSchema: {},
   outputSchema: {
     removedWorktrees: z.array(z.string()).describe('List of removed worktree branches'),

package/src/entry/cli.ts

@@ -11,7 +11,6 @@ import { ghMergeDev } from 'src/commands/gh-merge-dev'
 import { ghReleaseDeliver } from 'src/commands/gh-release-deliver'
 import { ghReleaseDeployAll } from 'src/commands/gh-release-deploy-all'
 import { ghReleaseDeploySelected } from 'src/commands/gh-release-deploy-selected'
-import { ghReleaseDeployService } from 'src/commands/gh-release-deploy-service'
 import { ghReleaseList } from 'src/commands/gh-release-list'
 import { init } from 'src/commands/init'
 import { releaseCreate } from 'src/commands/release-create'
@@ -81,22 +80,6 @@ program
     await ghReleaseDeployAll({ version: options.version, env: options.env, skipTerraform: options.skipTerraform })
   })
 
-program
-  .command('release-deploy-service')
-  .description('Deploy specific service in release branch to any environment')
-  .option('-v, --version <version>', 'Specify the version to deploy, e.g. 1.2.5')
-  .option('-e, --env <env>', 'Specify the environment to deploy to, e.g. dev')
-  .option('-s, --service <service>', 'Specify the service to deploy, e.g. client-be')
-  .option('--skip-terraform', 'Skip terraform deployment step')
-  .action(async (options) => {
-    await ghReleaseDeployService({
-      version: options.version,
-      env: options.env,
-      service: options.service,
-      skipTerraform: options.skipTerraform,
-    })
-  })
-
 program
   .command('release-deploy-selected')
   .description('Deploy selected services from release branch to any environment')
@@ -217,7 +200,6 @@ if (process.argv.length <= 2) {
     'release-create',
     'release-create-batch',
     'release-deploy-all',
-    'release-deploy-service',
     'release-deploy-selected',
     'release-deliver',
   ]

package/src/mcp/tools/index.ts

@@ -8,7 +8,6 @@ import { ghMergeDevMcpTool } from 'src/commands/gh-merge-dev'
 import { ghReleaseDeliverMcpTool } from 'src/commands/gh-release-deliver'
 import { ghReleaseDeployAllMcpTool } from 'src/commands/gh-release-deploy-all'
 import { ghReleaseDeploySelectedMcpTool } from 'src/commands/gh-release-deploy-selected'
-import { ghReleaseDeployServiceMcpTool } from 'src/commands/gh-release-deploy-service'
 import { ghReleaseListMcpTool } from 'src/commands/gh-release-list'
 import { releaseCreateMcpTool } from 'src/commands/release-create'
 import { releaseCreateBatchMcpTool } from 'src/commands/release-create-batch'
@@ -29,7 +28,6 @@ const tools = [
   ghReleaseDeliverMcpTool,
   ghReleaseDeployAllMcpTool,
   ghReleaseDeploySelectedMcpTool,
-  ghReleaseDeployServiceMcpTool,
   ghReleaseListMcpTool,
   worktreesAddMcpTool,
   worktreesListMcpTool,