infra-kit 0.1.95 → 0.1.98

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

@@ -0,0 +1,197 @@
+import { z } from 'zod/v4'
+import { $ } from 'zx'
+
+import { buildCmuxWorkspaceTitle, listCmuxWorkspaceTitles, openCmuxWorkspaceWithLayout } from 'src/integrations/cmux'
+import { reconcileCursorWorkspaceFolders, resolveCursorWorkspacePath } from 'src/integrations/cursor'
+import { commandEcho } from 'src/lib/command-echo'
+import { WORKTREES_DIR_SUFFIX } from 'src/lib/constants'
+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'
+
+interface WorktreesOpenResult {
+  openedCmux: string[]
+  skippedCmux: string[]
+  cursorFoldersAdded: number
+  cursorFoldersRemoved: number
+}
+
+/**
+ * Cold-start restore command: reconciles `Main.code-workspace` against the set
+ * of release worktrees on disk, opens Cursor against it, and ensures one cmux
+ * workspace exists per worktree. Idempotent and additive — never removes
+ * worktrees, never recreates running cmux workspaces.
+ */
+export const worktreesOpen = async (): Promise<ToolsExecutionResult> => {
+  commandEcho.start('worktrees-open')
+
+  try {
+    const projectRoot = await getProjectRoot()
+    const worktreeDir = `${projectRoot}${WORKTREES_DIR_SUFFIX}`
+    const currentBranches = await getCurrentWorktrees('release')
+
+    const cursorOutcome = await openCursor({ projectRoot, worktreeDir, currentBranches })
+    const cmuxOutcome = await openCmux({ worktreeDir, currentBranches })
+
+    const result: WorktreesOpenResult = {
+      openedCmux: cmuxOutcome.opened,
+      skippedCmux: cmuxOutcome.skipped,
+      cursorFoldersAdded: cursorOutcome.added,
+      cursorFoldersRemoved: cursorOutcome.removed,
+    }
+
+    logResults(result, { cursorRan: cursorOutcome.ran, cmuxRan: cmuxOutcome.ran })
+
+    commandEcho.print()
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      structuredContent: { ...result },
+    }
+  } catch (error) {
+    logger.error({ error }, '❌ Error opening worktrees')
+    throw error
+  }
+}
+
+interface OpenCursorArgs {
+  projectRoot: string
+  worktreeDir: string
+  currentBranches: string[]
+}
+
+interface OpenCursorOutcome {
+  ran: boolean
+  added: number
+  removed: number
+}
+
+const openCursor = async (args: OpenCursorArgs): Promise<OpenCursorOutcome> => {
+  const { projectRoot, worktreeDir, currentBranches } = args
+
+  const config = await getInfraKitConfig()
+  const cursorConfig = config.ide?.provider === 'cursor' ? config.ide.config : undefined
+
+  if (!cursorConfig || cursorConfig.mode !== 'workspace' || !cursorConfig.workspaceConfigPath) {
+    logger.warn('⚠️ Skipping Cursor: ide.provider must be "cursor", mode "workspace", and workspaceConfigPath set.')
+
+    return { ran: false, added: 0, removed: 0 }
+  }
+
+  const workspacePath = resolveCursorWorkspacePath(cursorConfig.workspaceConfigPath, projectRoot)
+
+  try {
+    const { added, removed } = await reconcileCursorWorkspaceFolders({
+      workspacePath,
+      worktreeDir,
+      currentBranches,
+    })
+
+    await $`cursor ${workspacePath}`
+
+    return { ran: true, added: added.length, removed: removed.length }
+  } catch (error) {
+    logger.warn({ error }, `⚠️ Failed to reconcile/open Cursor workspace at ${workspacePath}`)
+
+    return { ran: false, added: 0, removed: 0 }
+  }
+}
+
+interface OpenCmuxArgs {
+  worktreeDir: string
+  currentBranches: string[]
+}
+
+interface OpenCmuxOutcome {
+  ran: boolean
+  opened: string[]
+  skipped: string[]
+}
+
+const openCmux = async (args: OpenCmuxArgs): Promise<OpenCmuxOutcome> => {
+  const { worktreeDir, currentBranches } = args
+
+  if (currentBranches.length === 0) {
+    return { ran: true, opened: [], skipped: [] }
+  }
+
+  const repoName = await getRepoName()
+  const existingTitles = await listCmuxWorkspaceTitles()
+
+  const opened: string[] = []
+  const skipped: string[] = []
+
+  for (const branch of currentBranches) {
+    const title = buildCmuxWorkspaceTitle({ repoName, branch })
+
+    if (existingTitles.has(title)) {
+      skipped.push(title)
+      continue
+    }
+
+    try {
+      await openCmuxWorkspaceWithLayout({ cwd: `${worktreeDir}/${branch}`, title })
+      opened.push(title)
+    } catch (error) {
+      logger.warn({ error, title }, `⚠️ Failed to open cmux workspace for ${branch}`)
+    }
+  }
+
+  return { ran: true, opened, skipped }
+}
+
+interface LogResultsContext {
+  cursorRan: boolean
+  cmuxRan: boolean
+}
+
+const logResults = (result: WorktreesOpenResult, context: LogResultsContext): void => {
+  if (context.cursorRan) {
+    if (result.cursorFoldersAdded > 0) {
+      logger.info(`✅ Added ${result.cursorFoldersAdded} folder(s) to Cursor workspace`)
+    }
+
+    if (result.cursorFoldersRemoved > 0) {
+      logger.info(`🧹 Removed ${result.cursorFoldersRemoved} dangling folder(s) from Cursor workspace`)
+    }
+  }
+
+  if (result.openedCmux.length > 0) {
+    logger.info('✅ Opened cmux workspaces:')
+    for (const title of result.openedCmux) {
+      logger.info(title)
+    }
+  }
+
+  if (result.skippedCmux.length > 0) {
+    logger.info(`ℹ️ Skipped ${result.skippedCmux.length} cmux workspace(s) already open`)
+  }
+
+  if (
+    !context.cursorRan &&
+    result.openedCmux.length === 0 &&
+    result.skippedCmux.length === 0 &&
+    result.cursorFoldersAdded === 0 &&
+    result.cursorFoldersRemoved === 0
+  ) {
+    logger.info('ℹ️ Nothing to open')
+  }
+}
+
+// MCP Tool Registration
+export const worktreesOpenMcpTool = {
+  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.',
+  inputSchema: {},
+  outputSchema: {
+    openedCmux: z.array(z.string()).describe('Titles of cmux workspaces opened during this run'),
+    skippedCmux: z.array(z.string()).describe('Titles of cmux workspaces that were already open'),
+    cursorFoldersAdded: z.number().describe('Number of worktree folders added to the Cursor workspace file'),
+    cursorFoldersRemoved: z
+      .number()
+      .describe('Number of dangling worktree folders removed from the Cursor workspace file'),
+  },
+  handler: worktreesOpen,
+}

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

@@ -116,6 +116,7 @@ export const worktreesRemove = async (options: WorktreeManagementArgs): Promise<
       branches: selectedReleaseBranches,
       worktreeDir,
       repoName,
+      allSelected,
     })
 
     await syncCursorWorkspaceOnRemove({ removedWorktrees, worktreeDir, projectRoot })
@@ -148,13 +149,14 @@ interface RemoveWorktreesArgs {
   branches: string[]
   worktreeDir: string
   repoName: string
+  allSelected: boolean
 }
 
 /**
  * Remove worktrees for the specified branches and whole folder
  */
 const removeWorktrees = async (args: RemoveWorktreesArgs): Promise<string[]> => {
-  const { branches, worktreeDir, repoName } = args
+  const { branches, worktreeDir, repoName, allSelected } = args
 
   const results = await Promise.allSettled(
     branches.map(async (branch) => {
@@ -182,7 +184,7 @@ const removeWorktrees = async (args: RemoveWorktreesArgs): Promise<string[]> =>
     }
   }
 
-  if (removed.length === branches.length) {
+  if (allSelected && removed.length === branches.length) {
     await $`git worktree prune`
     await $`rm -rf ${worktreeDir}`
 

package/src/entry/cli.ts

@@ -2,6 +2,7 @@ import select, { Separator } from '@inquirer/select'
 import { Command, Option } from 'commander'
 import process from 'node:process'
 
+import { configEdit, configPath } from 'src/commands/config'
 import { doctor } from 'src/commands/doctor'
 import { envClear } from 'src/commands/env-clear'
 import { envList } from 'src/commands/env-list'
@@ -19,6 +20,7 @@ import { version } from 'src/commands/version'
 import { CURSOR_MODES, worktreesAdd } from 'src/commands/worktrees-add'
 import type { CursorMode } from 'src/commands/worktrees-add'
 import { worktreesList } from 'src/commands/worktrees-list'
+import { worktreesOpen } from 'src/commands/worktrees-open'
 import { worktreesRemove } from 'src/commands/worktrees-remove'
 import { worktreesSync } from 'src/commands/worktrees-sync'
 import { logger } from 'src/lib/logger'
@@ -79,25 +81,29 @@ program
 program
   .command('release-create')
   .description('Create a single release branch')
-  .option('-v, --version <version>', 'Specify the version to create, e.g. 1.2.5')
+  .option(
+    '-v, --version <version>',
+    'Version to create, e.g. "1.2.5", "next", or "next,next,1.2.7" (multi-value routes to batch)',
+  )
   .option('-d, --description <description>', 'Optional description for the Jira version')
   .addOption(new Option('-t, --type <type>', 'Release type (default: regular)').choices(['regular', 'hotfix']))
   .option('-y, --yes', 'Skip confirmation prompt')
-  .option('--no-checkout', 'Do not checkout the created branch after creation (checkout is default)')
   .action(async (options) => {
     await releaseCreate({
       version: options.version,
       description: options.description,
       type: options.type,
       confirmedCommand: options.yes,
-      checkout: options.checkout,
     })
   })
 
 program
   .command('release-create-batch')
   .description('Create multiple release branches (batch operation)')
-  .option('-v, --versions <versions>', 'Specify the versions to create by comma, e.g. 1.2.5, 1.2.6')
+  .option(
+    '-v, --versions <versions>',
+    'Comma-separated versions, e.g. "1.2.5, 1.2.6", "next,next", or "next,next,1.2.7"',
+  )
   .addOption(new Option('-t, --type <type>', 'Release type (default: regular)').choices(['regular', 'hotfix']))
   .option('-y, --yes', 'Skip confirmation prompt')
   .action(async (options) => {
@@ -191,6 +197,29 @@ program
     await worktreesRemove({ confirmedCommand: options.yes, all: options.all, versions: options.versions })
   })
 
+program
+  .command('worktrees-open')
+  .description('Open Cursor + cmux for existing release worktrees (cold-start restore)')
+  .action(async () => {
+    await worktreesOpen()
+  })
+
+const configCmd = program.command('config').description('Manage infra-kit configuration files')
+
+configCmd
+  .command('path')
+  .description('Show the resolved config merge chain and file paths')
+  .action(async () => {
+    await configPath()
+  })
+
+configCmd
+  .command('edit')
+  .description('Open the user-scope per-project override file in $EDITOR')
+  .action(async () => {
+    await configEdit()
+  })
+
 program
   .command('doctor')
   .description('Check installation and authentication status of gh and doppler CLIs')
@@ -251,8 +280,8 @@ if (process.argv.length <= 2) {
     'release-deploy-selected',
     'release-deliver',
   ]
-  const worktreeCommands = ['worktrees-add', 'worktrees-list', 'worktrees-remove', 'worktrees-sync']
-  const envCommands = ['doctor', 'init', 'version', 'env-status', 'env-list', 'env-load', 'env-clear']
+  const worktreeCommands = ['worktrees-add', 'worktrees-list', 'worktrees-open', 'worktrees-remove', 'worktrees-sync']
+  const envCommands = ['doctor', 'init', 'version', 'config', 'env-status', 'env-list', 'env-load', 'env-clear']
 
   const commandMap = new Map(
     program.commands.map((cmd) => {

package/src/integrations/cmux/index.ts

@@ -1,3 +1,4 @@
 export { closeCmuxWorkspaceByTitle } from './close-workspace-by-title'
+export { listCmuxWorkspaceTitles } from './list-workspace-titles'
 export { openCmuxWorkspaceWithLayout } from './open-workspace-with-layout'
 export { buildCmuxWorkspaceTitle } from './workspace-title'

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

@@ -0,0 +1,42 @@
+import { $ } from 'zx'
+
+import { logger } from 'src/lib/logger'
+
+/**
+ * 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".
+ *
+ * Each line of `cmux list-workspaces` looks like:
+ *   "  workspace:8  hulyo-monorepo v1.48.0"
+ *   "* workspace:6  obsidian-workspace  [selected]"
+ */
+export const listCmuxWorkspaceTitles = async (): Promise<Set<string>> => {
+  try {
+    const output = (await $`cmux list-workspaces`.quiet()).stdout
+
+    const titles = new Set<string>()
+
+    for (const rawLine of output.split('\n')) {
+      // eslint-disable-next-line sonarjs/slow-regex, regexp/no-super-linear-backtracking
+      const match = rawLine.match(/^[* ]\s*workspace:\d+\s+(.+?)(?:\s+\[selected\])?\s*$/)
+
+      if (!match) {
+        continue
+      }
+
+      const title = match[1]?.trim()
+
+      if (title) {
+        titles.add(title)
+      }
+    }
+
+    return titles
+  } catch (error) {
+    logger.debug({ error }, 'cmux: skipped listing workspace titles')
+
+    return new Set()
+  }
+}

package/src/integrations/cursor/index.ts

@@ -1,3 +1,4 @@
 export { addFoldersToCursorWorkspace } from './add-folders-to-workspace'
+export { reconcileCursorWorkspaceFolders } from './reconcile-workspace-folders'
 export { removeFoldersFromCursorWorkspace } from './remove-folders-from-workspace'
 export { resolveCursorWorkspacePath } from './resolve-workspace-path'

package/src/integrations/cursor/reconcile-workspace-folders.ts

@@ -0,0 +1,90 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { addFoldersToCursorWorkspace } from './add-folders-to-workspace'
+import { removeFoldersFromCursorWorkspace } from './remove-folders-from-workspace'
+
+interface ReconcileCursorWorkspaceFoldersArgs {
+  workspacePath: string
+  worktreeDir: string
+  currentBranches: string[]
+}
+
+interface ReconcileCursorWorkspaceFoldersResult {
+  added: string[]
+  removed: string[]
+}
+
+interface WorkspaceFolderEntry {
+  path: string
+  name?: string
+}
+
+interface WorkspaceFile {
+  folders?: WorkspaceFolderEntry[]
+  [key: string]: unknown
+}
+
+/**
+ * Reconciles the configured Cursor workspace's `folders` array against the
+ * actual set of release worktrees on disk:
+ *   - Adds any worktree folders that aren't already listed.
+ *   - Removes entries whose absolute path lives under `${worktreeDir}/release/`
+ *     but no longer corresponds to a current branch (drift from manual
+ *     `git worktree remove`, deleted branches, etc.).
+ *
+ * Non-worktree folder entries are left untouched.
+ */
+export const reconcileCursorWorkspaceFolders = async (
+  args: ReconcileCursorWorkspaceFoldersArgs,
+): Promise<ReconcileCursorWorkspaceFoldersResult> => {
+  const { workspacePath, worktreeDir, currentBranches } = args
+
+  const workspaceDir = path.dirname(workspacePath)
+  const releaseRoot = path.resolve(`${worktreeDir}/release`)
+
+  const raw = await fs.readFile(workspacePath, 'utf-8')
+  const parsed = JSON.parse(raw) as WorkspaceFile
+
+  const existingFolders = parsed.folders ?? []
+
+  const desiredAbsolutePaths = new Set(
+    currentBranches.map((branch) => {
+      return path.resolve(`${worktreeDir}/${branch}`)
+    }),
+  )
+
+  const danglingFolderPaths: string[] = []
+
+  for (const entry of existingFolders) {
+    const entryAbsolutePath = path.resolve(workspaceDir, entry.path)
+
+    const isReleaseShaped = entryAbsolutePath === releaseRoot || entryAbsolutePath.startsWith(`${releaseRoot}/`)
+
+    if (isReleaseShaped && !desiredAbsolutePaths.has(entryAbsolutePath)) {
+      danglingFolderPaths.push(entryAbsolutePath)
+    }
+  }
+
+  let removed: string[] = []
+
+  if (danglingFolderPaths.length > 0) {
+    const result = await removeFoldersFromCursorWorkspace({
+      workspacePath,
+      folderPaths: danglingFolderPaths,
+    })
+
+    removed = result.removed
+  }
+
+  const desiredFolderPaths = currentBranches.map((branch) => {
+    return `${worktreeDir}/${branch}`
+  })
+
+  const { added } =
+    desiredFolderPaths.length > 0
+      ? await addFoldersToCursorWorkspace({ workspacePath, folderPaths: desiredFolderPaths })
+      : { added: [] as string[] }
+
+  return { added, removed }
+}

package/src/lib/__tests__/infra-kit-config.test.ts

@@ -4,13 +4,14 @@ import path from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 // Import AFTER the mock is declared so the module picks up the mocked dep.
-import { getProjectRoot } from 'src/lib/git-utils'
+import { getProjectRoot, getRepoName } from 'src/lib/git-utils'
 
 import { getInfraKitConfig, resetInfraKitConfigCache } from '../infra-kit-config'
 
 vi.mock('src/lib/git-utils', () => {
   return {
     getProjectRoot: vi.fn(),
+    getRepoName: vi.fn(),
   }
 })
 
@@ -35,6 +36,7 @@ const withTmpRepo = async (fn: (tmp: string) => Promise<void>): Promise<void> =>
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'infra-kit-config-test-'))
 
   vi.mocked(getProjectRoot).mockResolvedValue(tmp)
+  vi.mocked(getRepoName).mockResolvedValue(path.basename(tmp))
   resetInfraKitConfigCache()
 
   try {

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

@@ -21,6 +21,29 @@ export const getCurrentWorktrees = async (type: 'release' | 'feature'): Promise<
   })
 }
 
+/**
+ * Extract the branch name from a `git worktree list` output line.
+ *
+ * `git worktree list` formats each line as:
+ *   <path>  <hash> [<branch>]
+ *
+ * Reads the branch from the trailing `[branch]` token so it works for the
+ * main checkout too (whose path does not encode the branch name).
+ */
+const parseWorktreeBranch = (line: string): string | null => {
+  const trimmed = line.trimEnd()
+
+  if (!trimmed.endsWith(']')) return null
+
+  const open = trimmed.lastIndexOf('[')
+
+  if (open === -1) return null
+
+  const branch = trimmed.slice(open + 1, -1)
+
+  return branch.length > 0 ? branch : null
+}
+
 /**
  * Extract a release branch name from a `git worktree list` output line.
  *
@@ -35,11 +58,9 @@ export const getCurrentWorktrees = async (type: 'release' | 'feature'): Promise<
  * // => null
  */
 const releaseWorktreePredicate = (line: string): string | null => {
-  const parts = line.split(' ').filter(Boolean)
-
-  if (parts.length < 3 || !parts[0]?.includes('release/v')) return null
+  const branch = parseWorktreeBranch(line)
 
-  return `release/${parts[0]?.split('/').pop() || ''}`
+  return branch?.startsWith('release/v') ? branch : null
 }
 
 /**
@@ -56,11 +77,9 @@ const releaseWorktreePredicate = (line: string): string | null => {
  * // => null
  */
 const featureWorktreePredicate = (line: string): string | null => {
-  const parts = line.split(' ').filter(Boolean)
-
-  if (parts.length < 3 || !parts[0]?.includes('feature/')) return null
+  const branch = parseWorktreeBranch(line)
 
-  return `feature/${parts[0]?.split('/').pop() || ''}`
+  return branch?.startsWith('feature/') ? branch : null
 }
 
 /**

package/src/lib/infra-kit-config/index.ts

@@ -1,2 +1,2 @@
-export { getInfraKitConfig, resetInfraKitConfigCache } from './infra-kit-config'
-export type { InfraKitConfig } from './infra-kit-config'
+export { getInfraKitConfig, getInfraKitConfigPaths, resetInfraKitConfigCache } from './infra-kit-config'
+export type { InfraKitConfig, InfraKitConfigPaths } from './infra-kit-config'