infra-kit 0.1.107 → 0.1.109

package/src/integrations/cmux/list-workspace-titles.ts

@@ -2,14 +2,19 @@ import { $ } from 'zx'
 
 import { logger } from 'src/lib/logger'
 
+import { canonicalizeCmuxTitle } from './canonicalize-cmux-title'
+
 /**
- * Returns the set of titles for all currently-open cmux workspaces.
- * Returns an empty set if cmux isn't running, the call fails, or the
- * output can't be parsed — callers should treat "empty" as "unknown,
- * proceed as if nothing is open".
+ * Returns the set of **canonical** titles for all currently-open cmux
+ * workspaces (see {@link canonicalizeCmuxTitle}). Keying on the canonical form
+ * lets callers match a workspace even when its stored title drifted from the
+ * title they rebuild (whitespace, or an older CLI's `v`-prefixed semver).
+ * Returns an empty set if cmux isn't running, the call fails, or the output
+ * can't be parsed — callers should treat "empty" as "unknown, proceed as if
+ * nothing is open".
  *
  * Each line of `cmux list-workspaces` looks like:
- *   "  workspace:8  hulyo-monorepo v1.48.0"
+ *   "  workspace:8  hulyo-monorepo 1.48.0"
  *   "* workspace:6  obsidian-workspace  [selected]"
  */
 export const listCmuxWorkspaceTitles = async (): Promise<Set<string>> => {
@@ -29,7 +34,7 @@ export const listCmuxWorkspaceTitles = async (): Promise<Set<string>> => {
       const title = match[1]?.trim()
 
       if (title) {
-        titles.add(title)
+        titles.add(canonicalizeCmuxTitle(title))
       }
     }
 

package/src/integrations/gh/gh-release-prs/.omc/state/sessions/c6ed6186-1aac-48e0-aa2a-edc6da8e0410/pre-tool-advisory-throttle.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "entries": {
+    "79a93d4a2f8f50b95f852280616242fee1855dc99a3c75211917f55e72e95fae": {
+      "last_emitted_at_ms": 1781518823336,
+      "message": "Use parallel execution for independent tasks. Use run_in_background for long operations (npm install, builds, tests)."
+    }
+  },
+  "updated_at": "2026-06-15T10:20:23.336Z"
+}

package/src/integrations/gh/gh-release-prs/__tests__/gh-release-prs.test.ts

@@ -1,6 +1,8 @@
+import { execFileSync } from 'node:child_process'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { quote } from 'zx'
 
-import { getReleasePRs, getReleasePRsWithInfo } from '../gh-release-prs'
+import { createReleaseBranch, getReleasePRs, getReleasePRsWithInfo } from '../gh-release-prs'
 
 interface FakePR {
   number: number
@@ -12,17 +14,32 @@ interface FakePR {
 }
 
 const responses = vi.hoisted(() => {
-  return { release: [] as FakePR[], hotfix: [] as FakePR[] }
+  return {
+    release: [] as FakePR[],
+    hotfix: [] as FakePR[],
+    calls: [] as { strings: string[]; values: unknown[] }[],
+  }
 })
 
 // Mock zx's tagged-template `$`: the gh pr list call for `--base dev` returns
-// the "release" set, `--base main` returns the "hotfix" set. The command is
-// reconstructed from the template strings so we can branch on the base flag.
-vi.mock('zx', () => {
+// the "release" set, `--base main` returns the "hotfix" set, and `gh pr create`
+// returns a fake PR URL. Every invocation is captured (template strings +
+// interpolated values) so tests can reconstruct the exact command zx would run.
+// Spreading `...actual` keeps zx's real `quote` available for that reconstruction.
+vi.mock('zx', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('zx')>()
+
   return {
-    $: vi.fn((strings: TemplateStringsArray) => {
+    ...actual,
+    $: vi.fn((strings: TemplateStringsArray, ...values: unknown[]) => {
       const command = strings.join('')
 
+      responses.calls.push({ strings: [...strings], values })
+
+      if (command.includes('gh pr create')) {
+        return Promise.resolve({ stdout: 'https://github.com/acme/repo/pull/123' })
+      }
+
       if (command.includes('--base main')) {
         return Promise.resolve({ stdout: JSON.stringify(responses.hotfix) })
       }
@@ -113,3 +130,69 @@ describe('getReleasePRsWithInfo (discovery + sort)', () => {
     ])
   })
 })
+
+describe('createReleaseBranch (gh pr create title quoting)', () => {
+  beforeEach(() => {
+    responses.calls = []
+  })
+
+  // Rebuild the exact command zx would have run: interleave each template
+  // string with the zx-quoted form of its interpolated value. This reflects
+  // what the shell actually receives, including zx's ANSI-C `$'...'` escaping
+  // for values containing spaces.
+  const reconstruct = (call: { strings: string[]; values: unknown[] }): string => {
+    return call.strings
+      .map((part, i) => {
+        return i < call.values.length ? part + quote(String(call.values[i])) : part
+      })
+      .join('')
+  }
+
+  const findCreateCommand = (): string => {
+    const call = responses.calls.find((c) => {
+      return c.strings.join('').includes('gh pr create')
+    })
+
+    if (!call) throw new Error('gh pr create was not invoked')
+
+    return reconstruct(call)
+  }
+
+  // Run the reconstructed command through a real shell with `gh pr create`
+  // replaced by a function that prints back the value the shell parsed for
+  // `--title`. This is the behavioral proof of what gh would receive.
+  const shellTitleArg = (command: string): string => {
+    const probe = command.replace(
+      'gh pr create',
+      'f(){ while [ "$#" -gt 0 ]; do if [ "$1" = "--title" ]; then printf %s "$2"; return 0; fi; shift; done; }; f',
+    )
+
+    // Absolute path (not PATH-resolved) keeps the lint's command-injection guard happy.
+    return execFileSync('/bin/sh', ['-c', probe]).toString()
+  }
+
+  it("delivers a spaced title to gh as the literal string, with no $'...' corruption", async () => {
+    const id = { kind: 'version', semver: { major: 1, minor: 89, patch: 1 }, raw: '1.89.1' } as const
+
+    await createReleaseBranch({ id, jiraVersionUrl: 'https://jira.example/v1.89.1', type: 'hotfix' })
+
+    const command = findCreateCommand()
+
+    // Behavioral: the shell parses --title to exactly the intended title.
+    expect(shellTitleArg(command)).toBe('Hotfix v1.89.1')
+    // The pre-fix bug wrapped zx's `$'...'` token in literal double quotes, so
+    // the shell passed the literal `$'Hotfix v1.89.1'` to gh. That marker must be absent.
+    expect(command).not.toContain('"$\'')
+  })
+
+  it('delivers a named release title to gh as the literal string', async () => {
+    const id = { kind: 'name', name: 'checkout-redesign', raw: 'checkout-redesign' } as const
+
+    await createReleaseBranch({ id, jiraVersionUrl: 'https://jira.example/checkout-redesign', type: 'regular' })
+
+    const command = findCreateCommand()
+
+    expect(shellTitleArg(command)).toBe('Release checkout-redesign')
+    expect(command).not.toContain('"$\'')
+  })
+})

package/src/integrations/gh/gh-release-prs/gh-release-prs.ts

@@ -178,7 +178,7 @@ export const createReleaseBranch = async (
     await $`git push origin ${branchName}`
 
     // Create PR and capture URL
-    const prResult = await $`gh pr create --title "${prTitle}" --body ${body} --base ${baseBranch} --head ${branchName}`
+    const prResult = await $`gh pr create --title ${prTitle} --body ${body} --base ${baseBranch} --head ${branchName}`
 
     const prLink = prResult.stdout.trim()
 

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'