infra-kit 0.1.108 → 0.1.109

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "infra-kit",
   "type": "module",
-  "version": "0.1.108",
+  "version": "0.1.109",
   "description": "infra-kit",
   "main": "dist/index.js",
   "module": "dist/index.js",

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

@@ -8,6 +8,7 @@ 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 { assertManagementContext } from 'src/lib/git-guard'
 import { logger } from 'src/lib/logger'
 import { detectReleaseType, formatBranchChoices, getJiraDescriptions, releaseBranchLabels } from 'src/lib/release-utils'
 import { defineMcpTool, textContent } from 'src/types'
@@ -25,6 +26,8 @@ export const ghMergeDev = async (args: GhMergeDevArgs) => {
 
   commandEcho.start('merge-dev')
 
+  await assertManagementContext({ operation: 'merge dev into release branches', requiredBranch: 'dev' })
+
   // Only merge dev into regular releases (not hotfixes, which target main)
   const allPRs = await getReleasePRsWithInfo()
   const releasePRsList = allPRs

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

@@ -10,6 +10,7 @@ import { commandEcho } from 'src/lib/command-echo'
 import { WORKTREES_DIR_SUFFIX } from 'src/lib/constants'
 import { formatZxError } from 'src/lib/errors/format-zx-error'
 import { OperationError } from 'src/lib/errors/operation-error'
+import { assertManagementContext } from 'src/lib/git-guard'
 import { getCurrentWorktrees, getProjectRoot, getRepoName } from 'src/lib/git-utils'
 import { logger } from 'src/lib/logger'
 import { displayLabel, formatJiraName, formatRcTitle, parseBranchName } from 'src/lib/release-id'
@@ -339,6 +340,10 @@ export const ghReleaseDeliver = async (args: GhReleaseDeliverArgs) => {
 
   commandEcho.start('release-deliver')
 
+  // Branch-agnostic (operates on release/RC PRs via gh and self-switches), so
+  // only the worktree + clean-tree legs apply.
+  await assertManagementContext({ operation: 'deliver release' })
+
   const { selectedReleaseBranch, releasePrTitle } = version
     ? await resolveTargetFromVersion(version)
     : await resolveTargetInteractively()

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

@@ -1,7 +1,11 @@
 import { describe, expect, it } from 'vitest'
 import type { z } from 'zod'
 
-import { releaseCreateMcpTool } from '../release-create'
+import { OperationError } from 'src/lib/errors/operation-error'
+import type { ReleaseType } from 'src/lib/release-utils'
+import type { ReleaseEntry } from 'src/lib/version-utils'
+
+import { assertHomogeneousReleaseType, releaseCreateMcpTool } from '../release-create'
 
 /**
  * The MCP `releases[]` entry schema enforces that exactly one of `version` or
@@ -53,3 +57,36 @@ describe('release-create MCP releases[] entry schema', () => {
     }).toThrow(/exactly one of/)
   })
 })
+
+const entryOfType = (type: ReleaseType): ReleaseEntry => {
+  return {
+    id: { kind: 'version', semver: { major: 1, minor: 2, patch: 3 }, raw: '1.2.3' },
+    type,
+  } as ReleaseEntry
+}
+
+describe('assertHomogeneousReleaseType', () => {
+  it('accepts an all-regular batch', () => {
+    expect(() => {
+      return assertHomogeneousReleaseType([entryOfType('regular'), entryOfType('regular')])
+    }).not.toThrow()
+  })
+
+  it('accepts an all-hotfix batch', () => {
+    expect(() => {
+      return assertHomogeneousReleaseType([entryOfType('hotfix')])
+    }).not.toThrow()
+  })
+
+  it('rejects a mixed regular+hotfix batch with an OperationError', () => {
+    expect(() => {
+      return assertHomogeneousReleaseType([entryOfType('regular'), entryOfType('hotfix')])
+    }).toThrow(OperationError)
+  })
+
+  it('mixed-batch error mentions separate invocations', () => {
+    expect(() => {
+      return assertHomogeneousReleaseType([entryOfType('regular'), entryOfType('hotfix')])
+    }).toThrow(/separate invocations/)
+  })
+})

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

@@ -7,9 +7,10 @@ import { question } from 'zx'
 import { loadJiraConfig } from 'src/integrations/jira'
 import { commandEcho } from 'src/lib/command-echo'
 import { OperationError } from 'src/lib/errors/operation-error'
+import { assertManagementContext } from 'src/lib/git-guard'
 import { logger } from 'src/lib/logger'
 import { InvalidReleaseNameError, displayLabel, validateName } from 'src/lib/release-id'
-import { createSingleRelease, prepareGitForRelease } from 'src/lib/release-utils'
+import { createSingleRelease, getBaseBranch, prepareGitForRelease } from 'src/lib/release-utils'
 import type { ReleaseCreationResult, ReleaseType } from 'src/lib/release-utils'
 import {
   NoPriorVersionsError,
@@ -212,6 +213,28 @@ const collectEntries = async (
   return interactive
 }
 
+/**
+ * Reject a batch that mixes regular and hotfix releases. They branch off
+ * different bases (dev vs main), so the batch has no single required branch for
+ * the management guard — they must be created in separate invocations.
+ * Exported for unit testing without running the side-effecting handler.
+ */
+export const assertHomogeneousReleaseType = (entries: ReleaseEntry[]): void => {
+  const types = new Set(
+    entries.map((entry) => {
+      return entry.type
+    }),
+  )
+
+  if (types.size > 1) {
+    throw new OperationError(undefined, {
+      operation: 'create release',
+      remediation: 'create regular and hotfix releases in separate invocations',
+      stderrExcerpt: 'mixed regular and hotfix releases in one batch are not supported',
+    })
+  }
+}
+
 const confirmReleases = async (entries: ReleaseEntry[], confirmedCommand: boolean): Promise<void> => {
   const summary = entries.map(formatReleaseSummary).join('\n  - ')
   const answer = confirmedCommand
@@ -284,8 +307,10 @@ const logFinalSummary = (total: number, successCount: number, failureCount: numb
 
 /**
  * Create one or more release branches. Each release carries its own type
- * (regular/hotfix) and optional Jira description, so a single invocation
- * may mix regular and hotfix releases off their respective base branches.
+ * (regular/hotfix) and optional Jira description. All entries in a single
+ * invocation must share the same type — regular and hotfix releases branch off
+ * different bases (dev vs main), so mixed batches are rejected and must be
+ * created separately.
  */
 export const releaseCreate = async (args: ReleaseCreateArgs) => {
   const { releases: inputReleases, confirmedCommand } = args
@@ -311,6 +336,13 @@ export const releaseCreate = async (args: ReleaseCreateArgs) => {
     })
   }
 
+  assertHomogeneousReleaseType(entries)
+
+  await assertManagementContext({
+    operation: 'create release',
+    requiredBranch: getBaseBranch(entries[0]!.type),
+  })
+
   await confirmReleases(entries, Boolean(confirmedCommand))
 
   const created: ReleaseCreationResult[] = []
@@ -347,7 +379,7 @@ export const releaseCreate = async (args: ReleaseCreateArgs) => {
 export const releaseCreateMcpTool = defineMcpTool({
   name: 'release-create',
   description:
-    'Create one or more releases in a single call. Each entry in "releases" carries EITHER a "version" (semver or the literal token "next") OR a "name" (free-form kebab-case identifier) — exactly one is required and they are mutually exclusive. Each entry also has its own type (regular|hotfix, default regular) and optional description, so regular and hotfix releases can be mixed in the same invocation. For each release this tool switches to the appropriate base branch (dev for regular, main for hotfix), cuts the release branch (release/v<semver> for versions, release/n/<name> for names), opens a GitHub release PR, and creates the matching Jira fix version (v<semver> for versions, <name> for names). The literal token "next" auto-increments from the union of remote release branches and Jira fix versions (regular bumps minor + resets patch; hotfix bumps patch on the highest minor); multiple "next" tokens advance sequentially across mixed types. Named releases never auto-bump and "next" is version-only. Confirmation is auto-skipped for MCP calls, so the caller is responsible for gating. Continues on per-release failure and reports successes/failures.',
+    'Create one or more releases in a single call. Each entry in "releases" carries EITHER a "version" (semver or the literal token "next") OR a "name" (free-form kebab-case identifier) — exactly one is required and they are mutually exclusive. Each entry also has its own type (regular|hotfix, default regular) and optional description; all entries in one call must share the same type — mixed regular+hotfix batches are rejected (create them in separate invocations). For each release this tool switches to the appropriate base branch (dev for regular, main for hotfix), cuts the release branch (release/v<semver> for versions, release/n/<name> for names), opens a GitHub release PR, and creates the matching Jira fix version (v<semver> for versions, <name> for names). The literal token "next" auto-increments from the union of remote release branches and Jira fix versions (regular bumps minor + resets patch; hotfix bumps patch on the highest minor); multiple "next" tokens advance sequentially. Named releases never auto-bump and "next" is version-only. Must be run from the main repository checkout (not a linked worktree) on the matching base branch with a clean working tree. Confirmation is auto-skipped for MCP calls, so the caller is responsible for gating. Continues on per-release failure and reports successes/failures.',
   inputSchema: {
     releases: z
       .array(

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

@@ -17,6 +17,7 @@ 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 { assertManagementContext } from 'src/lib/git-guard'
 import { getCurrentWorktrees, getProjectRoot, getRepoName } from 'src/lib/git-utils'
 import { getInfraKitConfig } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
@@ -50,6 +51,8 @@ export const worktreesAdd = async (options: WorktreeManagementArgs) => {
 
   commandEcho.start('worktrees-add')
 
+  await assertManagementContext({ operation: 'create worktrees', requiredBranch: 'dev' })
+
   try {
     const currentWorktrees = await getCurrentWorktrees('release')
     const projectRoot = await getProjectRoot()

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

@@ -8,6 +8,7 @@ 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 { assertManagementContext } from 'src/lib/git-guard'
 import { getCurrentWorktrees, getProjectRoot, getRepoName } from 'src/lib/git-utils'
 import { getInfraKitConfig } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
@@ -33,6 +34,8 @@ export const worktreesRemove = async (options: WorktreeManagementArgs) => {
 
   commandEcho.start('worktrees-remove')
 
+  await assertManagementContext({ operation: 'remove worktrees', requiredBranch: 'dev' })
+
   try {
     const currentWorktrees = await getCurrentWorktrees('release')
 

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

@@ -9,6 +9,7 @@ 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 { assertManagementContext } from 'src/lib/git-guard'
 import { getCurrentWorktrees, getProjectRoot, getRepoName } from 'src/lib/git-utils'
 import { getInfraKitConfig } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
@@ -28,6 +29,8 @@ export const worktreesSync = async (options: WorktreeSyncArgs) => {
 
   commandEcho.start('worktrees-sync')
 
+  await assertManagementContext({ operation: 'sync worktrees', requiredBranch: 'dev' })
+
   try {
     const currentWorktrees = await getCurrentWorktrees('release')
     const projectRoot = await getProjectRoot()

package/src/lib/git-guard/__tests__/git-guard.test.ts

@@ -0,0 +1,92 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { OperationError } from 'src/lib/errors/operation-error'
+import { assertManagementContext } from 'src/lib/git-guard'
+
+const mocks = vi.hoisted(() => {
+  return {
+    isInsideLinkedWorktree: vi.fn(),
+    getCurrentBranch: vi.fn(),
+    isWorkingTreeClean: vi.fn(),
+  }
+})
+
+vi.mock('src/lib/git-utils', () => {
+  return {
+    isInsideLinkedWorktree: mocks.isInsideLinkedWorktree,
+    getCurrentBranch: mocks.getCurrentBranch,
+    isWorkingTreeClean: mocks.isWorkingTreeClean,
+  }
+})
+
+describe('assertManagementContext', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+
+    // Default: main checkout, on dev, clean tree (the all-pass baseline).
+    mocks.isInsideLinkedWorktree.mockResolvedValue(false)
+    mocks.getCurrentBranch.mockResolvedValue('dev')
+    mocks.isWorkingTreeClean.mockResolvedValue(true)
+  })
+
+  it('resolves when in main checkout, on the required branch, with a clean tree', async () => {
+    await expect(
+      assertManagementContext({ operation: 'create release', requiredBranch: 'dev' }),
+    ).resolves.toBeUndefined()
+  })
+
+  it('throws when inside a linked worktree', async () => {
+    mocks.isInsideLinkedWorktree.mockResolvedValue(true)
+
+    await expect(assertManagementContext({ operation: 'create release', requiredBranch: 'dev' })).rejects.toMatchObject(
+      {
+        message: expect.stringContaining('worktree'),
+      },
+    )
+  })
+
+  it('checks the worktree before the branch', async () => {
+    mocks.isInsideLinkedWorktree.mockResolvedValue(true)
+    mocks.getCurrentBranch.mockResolvedValue('feature/x')
+
+    await expect(assertManagementContext({ operation: 'create release', requiredBranch: 'dev' })).rejects.toThrow(
+      /worktree/,
+    )
+    expect(mocks.getCurrentBranch).not.toHaveBeenCalled()
+  })
+
+  it('throws on the wrong branch when requiredBranch is set', async () => {
+    mocks.getCurrentBranch.mockResolvedValue('main')
+
+    await expect(assertManagementContext({ operation: 'create release', requiredBranch: 'dev' })).rejects.toMatchObject(
+      {
+        message: expect.stringContaining('switch to dev'),
+      },
+    )
+  })
+
+  it('skips the branch check when requiredBranch is omitted', async () => {
+    mocks.getCurrentBranch.mockResolvedValue('main')
+
+    await expect(assertManagementContext({ operation: 'deliver release' })).resolves.toBeUndefined()
+    expect(mocks.getCurrentBranch).not.toHaveBeenCalled()
+  })
+
+  it('throws when the working tree is dirty', async () => {
+    mocks.isWorkingTreeClean.mockResolvedValue(false)
+
+    await expect(assertManagementContext({ operation: 'create release', requiredBranch: 'dev' })).rejects.toMatchObject(
+      {
+        message: expect.stringContaining('commit or stash'),
+      },
+    )
+  })
+
+  it('throws OperationError (not a plain Error) on violation', async () => {
+    mocks.isWorkingTreeClean.mockResolvedValue(false)
+
+    await expect(
+      assertManagementContext({ operation: 'sync worktrees', requiredBranch: 'dev' }),
+    ).rejects.toBeInstanceOf(OperationError)
+  })
+})

package/src/lib/git-guard/git-guard.ts

@@ -0,0 +1,55 @@
+import { OperationError } from 'src/lib/errors/operation-error'
+import { getCurrentBranch, isInsideLinkedWorktree, isWorkingTreeClean } from 'src/lib/git-utils'
+
+export interface AssertManagementContextArgs {
+  /** Operation name surfaced in the failure message, e.g. 'create release'. */
+  operation: string
+  /**
+   * Canonical branch the command must run from (e.g. 'dev' / 'main'). Omit to
+   * skip the branch check for commands that are branch-agnostic or self-switch.
+   */
+  requiredBranch?: string
+}
+
+/**
+ * Guard release- and worktree-management commands so they run only from the
+ * main repository checkout, with a clean working tree, and (where applicable)
+ * on the canonical branch.
+ *
+ * Checks run most-structural-first — worktree, then branch, then clean — so the
+ * operator fixes the most fundamental problem first. The worktree and clean-tree
+ * checks always run; the branch check runs only when `requiredBranch` is set.
+ * Throws {@link OperationError} on the first violation, which surfaces uniformly
+ * to both CLI users and MCP-connected agents.
+ */
+export const assertManagementContext = async (args: AssertManagementContextArgs): Promise<void> => {
+  const { operation, requiredBranch } = args
+
+  if (await isInsideLinkedWorktree()) {
+    throw new OperationError(undefined, {
+      operation,
+      remediation: 'run this from the main repository checkout, not a linked git worktree',
+      stderrExcerpt: 'command run from inside a linked worktree',
+    })
+  }
+
+  if (requiredBranch) {
+    const currentBranch = await getCurrentBranch()
+
+    if (currentBranch !== requiredBranch) {
+      throw new OperationError(undefined, {
+        operation,
+        remediation: `switch to ${requiredBranch} first (git switch ${requiredBranch})`,
+        stderrExcerpt: `current branch is "${currentBranch}", expected "${requiredBranch}"`,
+      })
+    }
+  }
+
+  if (!(await isWorkingTreeClean())) {
+    throw new OperationError(undefined, {
+      operation,
+      remediation: 'commit or stash your changes, then retry',
+      stderrExcerpt: 'working tree has uncommitted changes',
+    })
+  }
+}

package/src/lib/git-guard/index.ts

@@ -0,0 +1,2 @@
+export { assertManagementContext } from './git-guard'
+export type { AssertManagementContextArgs } from './git-guard'

package/src/lib/git-utils/__tests__/git-primitives.test.ts

@@ -0,0 +1,96 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { getCurrentBranch, isInsideLinkedWorktree, isWorkingTreeClean } from 'src/lib/git-utils'
+
+// Controllable per-command git output. The mocked `$` dispatches on the command
+// text so a single test can make `--absolute-git-dir` and `--git-common-dir`
+// return DIFFERENT values — which the shared single-stdout mock cannot express.
+const git = vi.hoisted(() => {
+  return {
+    toplevel: '/repo',
+    branch: 'dev',
+    status: '',
+    absoluteGitDir: '/repo/.git',
+    commonDir: '.git',
+  }
+})
+
+vi.mock('zx', () => {
+  const run = (strings: TemplateStringsArray): Promise<{ stdout: string }> => {
+    const command = strings.join('')
+
+    if (command.includes('--show-toplevel')) return Promise.resolve({ stdout: `${git.toplevel}\n` })
+    if (command.includes('--abbrev-ref HEAD')) return Promise.resolve({ stdout: `${git.branch}\n` })
+    if (command.includes('status --porcelain')) return Promise.resolve({ stdout: git.status })
+    if (command.includes('--absolute-git-dir')) return Promise.resolve({ stdout: `${git.absoluteGitDir}\n` })
+    if (command.includes('--git-common-dir')) return Promise.resolve({ stdout: `${git.commonDir}\n` })
+
+    return Promise.resolve({ stdout: '' })
+  }
+
+  // zx's `$` supports both tagged-template form (`$`...``) and an options form
+  // (`$({ cwd })`...``) that returns a fresh tagged-template function.
+  const $ = vi.fn((first: unknown) => {
+    if (!Array.isArray(first)) {
+      return (strings: TemplateStringsArray) => {
+        return run(strings)
+      }
+    }
+
+    return run(first as unknown as TemplateStringsArray)
+  })
+
+  return { $ }
+})
+
+describe('getCurrentBranch', () => {
+  beforeEach(() => {
+    git.branch = 'dev'
+  })
+
+  it('returns the trimmed branch name', async () => {
+    git.branch = 'release/v1.2.3'
+
+    await expect(getCurrentBranch()).resolves.toBe('release/v1.2.3')
+  })
+})
+
+describe('isWorkingTreeClean', () => {
+  it('returns true when porcelain output is empty', async () => {
+    git.status = ''
+
+    await expect(isWorkingTreeClean()).resolves.toBe(true)
+  })
+
+  it('returns true when porcelain output is whitespace only', async () => {
+    git.status = '\n'
+
+    await expect(isWorkingTreeClean()).resolves.toBe(true)
+  })
+
+  it('returns false when there are changes', async () => {
+    git.status = ' M src/foo.ts\n?? new.ts\n'
+
+    await expect(isWorkingTreeClean()).resolves.toBe(false)
+  })
+})
+
+describe('isInsideLinkedWorktree', () => {
+  beforeEach(() => {
+    git.toplevel = '/repo'
+  })
+
+  it('returns false in the main checkout (git dir resolves to the common dir)', async () => {
+    git.absoluteGitDir = '/repo/.git'
+    git.commonDir = '.git'
+
+    await expect(isInsideLinkedWorktree()).resolves.toBe(false)
+  })
+
+  it('returns true in a linked worktree (git dir under .git/worktrees, differs from common dir)', async () => {
+    git.absoluteGitDir = '/repo/.git/worktrees/release-v1.2.3'
+    git.commonDir = '/repo/.git'
+
+    await expect(isInsideLinkedWorktree()).resolves.toBe(true)
+  })
+})

package/src/lib/git-utils/git-utils.ts

@@ -93,6 +93,47 @@ export const getProjectRoot = async (): Promise<string> => {
   return result.stdout.trim()
 }
 
+/**
+ * Get the current git branch name (e.g. `dev`, `main`, `release/v1.2.3`).
+ */
+export const getCurrentBranch = async (): Promise<string> => {
+  const result = await $`git rev-parse --abbrev-ref HEAD`
+
+  return result.stdout.trim()
+}
+
+/**
+ * Whether the working tree has no staged, unstaged, or untracked changes.
+ */
+export const isWorkingTreeClean = async (): Promise<boolean> => {
+  const result = await $`git status --porcelain`
+
+  return result.stdout.trim().length === 0
+}
+
+/**
+ * Whether the current checkout is a linked git worktree rather than the main
+ * repository checkout.
+ *
+ * A linked worktree's git dir lives under `<main>/.git/worktrees/<name>`, so it
+ * differs from the shared common dir; in the main checkout the two resolve to
+ * the same path. Both are anchored to the toplevel so `--git-common-dir` (which
+ * git may report relative to cwd) resolves consistently.
+ */
+export const isInsideLinkedWorktree = async (): Promise<boolean> => {
+  const cwd = await getProjectRoot()
+
+  const [gitDirResult, commonDirResult] = await Promise.all([
+    $({ cwd })`git rev-parse --absolute-git-dir`,
+    $({ cwd })`git rev-parse --git-common-dir`,
+  ])
+
+  const gitDir = gitDirResult.stdout.trim()
+  const commonDir = path.resolve(cwd, commonDirResult.stdout.trim())
+
+  return gitDir !== commonDir
+}
+
 /**
  * Get the current repository name (basename of the project root)
  */

package/src/lib/git-utils/index.ts

@@ -1 +1,8 @@
-export { getCurrentWorktrees, getProjectRoot, getRepoName } from './git-utils'
+export {
+  getCurrentBranch,
+  getCurrentWorktrees,
+  getProjectRoot,
+  getRepoName,
+  isInsideLinkedWorktree,
+  isWorkingTreeClean,
+} from './git-utils'