infra-kit 0.1.114 → 0.1.117

package/src/entry/index.ts

@@ -1,5 +1,11 @@
 // Public library entry for `import { defineConfig } from 'infra-kit'`. Uses
 // relative imports (no `src/*` alias) so the emitted .d.ts stays portable for
-// external consumers. Keep this surface minimal — only the package-config API.
+// external consumers. Keep this surface minimal.
 export { defineConfig } from '../lib/package-config/package-config'
 export type { InfraKitPackageConfig, InfraKitPackageConfigInput } from '../lib/package-config/package-config'
+// Vendor sync config authoring (`import { defineVendorConfig } from 'infra-kit'`).
+// Imported from the node-free schema module so the emitted .d.ts needs no node types.
+export { defineVendorConfig } from '../lib/vendor/config-schema'
+export type { VendorConfig, VendorCopyItem } from '../lib/vendor/config-schema'
+// The machine-local factory registry is now static JSON (~/.infra-kit/vendor.json),
+// not authored in TypeScript — so there is no `defineFactoryConfig` to export.

package/src/integrations/cmux/__tests__/open-workspace-with-layout.test.ts

@@ -0,0 +1,127 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { $ } from 'zx'
+
+import { getInfraKitConfig } from 'src/lib/infra-kit-config'
+import type { CmuxLayout } from 'src/lib/infra-kit-config'
+
+import { openCmuxWorkspaceWithLayout } from '../open-workspace-with-layout'
+
+vi.mock('src/lib/infra-kit-config', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('src/lib/infra-kit-config')>()
+
+  return {
+    ...actual,
+    getInfraKitConfig: vi.fn(),
+  }
+})
+
+vi.mock('zx', () => {
+  function makeResult(stdout: string) {
+    return Object.assign(Promise.resolve({ stdout }), {
+      quiet: () => {
+        return Promise.resolve({ stdout })
+      },
+    })
+  }
+
+  return {
+    $: vi.fn((strings: TemplateStringsArray) => {
+      const cmd = strings.join('')
+
+      if (cmd.includes('workspace create')) return makeResult('created workspace:7\n')
+      if (cmd.includes('list-pane-surfaces')) return makeResult('surface:12 (active)\n')
+
+      return makeResult('')
+    }),
+  }
+})
+
+// A worktree cwd that is not under a publicly writable directory (avoids the
+// sonarjs/publicly-writable-directories lint that flags /tmp paths).
+const WORKTREE_CWD = '/home/dev/repo/wt'
+
+type CmuxCall = [TemplateStringsArray, ...string[]]
+
+const allCommands = (): string[] => {
+  const calls = vi.mocked($).mock.calls as unknown as CmuxCall[]
+
+  return calls.map((call) => {
+    return call[0].join('')
+  })
+}
+
+const splitCommands = (): string[] => {
+  return allCommands().filter((cmd) => {
+    return cmd.includes('new-split')
+  })
+}
+
+const mockLayout = (layout: CmuxLayout): void => {
+  vi.mocked(getInfraKitConfig).mockResolvedValue({
+    environments: ['dev'],
+    envManagement: { provider: 'doppler', config: { name: 'p' } },
+    worktrees: { cmux: { layout } },
+  } as Awaited<ReturnType<typeof getInfraKitConfig>>)
+}
+
+describe('openCmuxWorkspaceWithLayout', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('two-columns layout issues a single right split (no down split)', async () => {
+    mockLayout('two-columns')
+
+    await openCmuxWorkspaceWithLayout({ cwd: WORKTREE_CWD })
+
+    const splits = splitCommands()
+
+    expect(
+      splits.some((cmd) => {
+        return cmd.includes('new-split right')
+      }),
+    ).toBe(true)
+    expect(
+      splits.some((cmd) => {
+        return cmd.includes('new-split down')
+      }),
+    ).toBe(false)
+    expect(splits).toHaveLength(1)
+  })
+
+  it('three-pane layout issues both a right and a down split', async () => {
+    mockLayout('three-pane')
+
+    await openCmuxWorkspaceWithLayout({ cwd: WORKTREE_CWD })
+
+    const splits = splitCommands()
+
+    expect(
+      splits.some((cmd) => {
+        return cmd.includes('new-split right')
+      }),
+    ).toBe(true)
+    expect(
+      splits.some((cmd) => {
+        return cmd.includes('new-split down')
+      }),
+    ).toBe(true)
+    expect(splits).toHaveLength(2)
+  })
+
+  it('renames the workspace when a title is provided', async () => {
+    mockLayout('two-columns')
+
+    await openCmuxWorkspaceWithLayout({ cwd: WORKTREE_CWD, title: 'my-title' })
+
+    const calls = vi.mocked($).mock.calls as unknown as CmuxCall[]
+    const renameCall = calls.find((call) => {
+      return call[0].join('').includes('workspace rename')
+    })
+
+    expect(renameCall).toBeDefined()
+    // The title is the last interpolated value of `cmux workspace rename … --title ${title}`,
+    // so it lands in the final tuple slot — assert on that value, not tuple membership.
+    expect(renameCall?.at(-1)).toBe('my-title')
+  })
+})

package/src/integrations/cmux/close-workspace-by-title.ts

@@ -30,7 +30,7 @@ export const closeCmuxWorkspaceByTitle = async (title: string): Promise<void> =>
  * title matches `title`, or undefined if no match. Both sides are compared via
  * {@link canonicalizeCmuxTitle} so a workspace stored under a drifted title
  * (whitespace, or an older CLI's `v`-prefixed semver) is still found — keeping
- * close symmetric with the dedup in `worktrees-open`.
+ * close symmetric with the cmux open dedup in `worktrees-reload`.
  *
  * Each line looks like:
  *   "  workspace:8  hulyo-monorepo 1.48.0"
@@ -40,7 +40,7 @@ const findWorkspaceRefByTitle = (output: string, title: string): string | undefi
   const target = canonicalizeCmuxTitle(title)
 
   for (const rawLine of output.split('\n')) {
-    // eslint-disable-next-line sonarjs/slow-regex, regexp/no-super-linear-backtracking
+    // eslint-disable-next-line sonarjs/super-linear-regex, regexp/no-super-linear-backtracking
     const match = rawLine.match(/^[* ]\s*(workspace:\d+)\s+(.+?)(?:\s+\[selected\])?\s*$/)
 
     if (!match) {

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

@@ -24,7 +24,7 @@ export const listCmuxWorkspaceTitles = async (): Promise<Set<string>> => {
     const titles = new Set<string>()
 
     for (const rawLine of output.split('\n')) {
-      // eslint-disable-next-line sonarjs/slow-regex, regexp/no-super-linear-backtracking
+      // eslint-disable-next-line sonarjs/super-linear-regex, regexp/no-super-linear-backtracking
       const match = rawLine.match(/^[* ]\s*workspace:\d+\s+(.+?)(?:\s+\[selected\])?\s*$/)
 
       if (!match) {

package/src/integrations/cmux/open-workspace-with-layout.ts

@@ -1,19 +1,25 @@
 import { $ } from 'zx'
 
+import { getInfraKitConfig, resolveCmuxLayout } from 'src/lib/infra-kit-config'
+
 interface OpenCmuxWorkspaceArgs {
   cwd: string
   title?: string
 }
 
 /**
- * Opens a new cmux workspace rooted at `cwd` with three panes:
- *   left-top (primary) | right (full-height)
- *   left-bottom        |
+ * Opens a new cmux workspace rooted at `cwd`, with panes arranged per the
+ * configured `worktrees.cmux.layout` (resolved via {@link resolveCmuxLayout},
+ * default `two-columns`):
+ *   two-columns — left | right, both full-height (two panes)
+ *   three-pane  — left-top / left-bottom | full-height right (three panes)
  * All panes inherit `cwd` from the workspace.
  */
 export const openCmuxWorkspaceWithLayout = async (args: OpenCmuxWorkspaceArgs): Promise<void> => {
   const { cwd, title } = args
 
+  const layout = resolveCmuxLayout(await getInfraKitConfig())
+
   const newWorkspaceOutput = (await $`cmux workspace create --cwd ${cwd}`).stdout
 
   const workspaceRef = parseWorkspaceRef(newWorkspaceOutput)
@@ -22,8 +28,13 @@ export const openCmuxWorkspaceWithLayout = async (args: OpenCmuxWorkspaceArgs):
 
   const leftTopRef = parseFirstSurfaceRef(surfacesOutput)
 
+  // Both layouts share the vertical split into left | right columns; only the
+  // legacy three-pane layout additionally splits the left column top/bottom.
   await $`cmux new-split right --workspace ${workspaceRef} --surface ${leftTopRef}`
-  await $`cmux new-split down --workspace ${workspaceRef} --surface ${leftTopRef}`
+
+  if (layout === 'three-pane') {
+    await $`cmux new-split down --workspace ${workspaceRef} --surface ${leftTopRef}`
+  }
 
   if (title) {
     await $`cmux workspace rename --workspace ${workspaceRef} --title ${title}`

package/src/integrations/cursor/open-cursor-workspace.ts

@@ -8,13 +8,6 @@ interface OpenCursorWorkspaceArgs {
   projectRoot: string
   worktreeDir: string
   currentBranches: string[]
-  /**
-   * When true, skip the `cursor <workspace>` relaunch if there are no release
-   * worktrees (folder reconcile still runs to strip dangling entries). Lets
-   * `worktrees-reload` avoid popping an empty Cursor window while keeping the
-   * cold-start `worktrees-open` behaviour (relaunch unconditionally) intact.
-   */
-  skipRelaunchWhenEmpty: boolean
   /**
    * The Cursor entry's config, selected by the facade from the (possibly
    * multi-IDE) infra-kit config. Passed in rather than re-read here so this
@@ -32,14 +25,16 @@ interface OpenCursorWorkspaceOutcome {
 
 /**
  * Reconciles the configured Cursor `.code-workspace` `folders` array against the
- * set of release worktrees on disk, then launches Cursor against it. Shared by
- * `worktrees-open` (cold-start restore) and `worktrees-reload` (close + reopen).
+ * set of release worktrees on disk, then launches Cursor against it (the folder
+ * reconcile still runs when there are no worktrees, but the relaunch is skipped
+ * so `worktrees-reload` never pops an empty Cursor window). Used by
+ * `worktrees-reload`.
  *
  * No-ops (returns `ran: false`) when the Cursor entry has no `workspaceConfigPath`.
  * All failures are swallowed into a warning — opening Cursor is best-effort.
  */
 export const openCursorWorkspace = async (args: OpenCursorWorkspaceArgs): Promise<OpenCursorWorkspaceOutcome> => {
-  const { projectRoot, worktreeDir, currentBranches, skipRelaunchWhenEmpty, cursorConfig } = args
+  const { projectRoot, worktreeDir, currentBranches, cursorConfig } = args
 
   if (!cursorConfig.workspaceConfigPath) {
     logger.warn('⚠️ Skipping Cursor: workspaceConfigPath is not set.')
@@ -56,7 +51,7 @@ export const openCursorWorkspace = async (args: OpenCursorWorkspaceArgs): Promis
       currentBranches,
     })
 
-    if (!(skipRelaunchWhenEmpty && currentBranches.length === 0)) {
+    if (currentBranches.length > 0) {
       await launchCursor(workspacePath)
     }
 

package/src/integrations/doppler/__tests__/doppler-errors.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+
+import { buildDopplerNotFoundMessage, classifyDopplerDownloadError } from '../doppler-errors'
+
+// Verbatim Doppler stderr observed on a not-found download (doppler v3.76.0,
+// 2026-06-27). The "" prefix is the real ANSI color on "Doppler Error:".
+const PROJECT_NOT_FOUND_STDERR =
+  "Unable to download secrets\nDoppler Error: Could not find requested project 'infra-kit'\n"
+const CONFIG_NOT_FOUND_STDERR =
+  "Unable to download secrets\nDoppler Error: Could not find requested config 'bogus-cfg'\n"
+
+describe('classifyDopplerDownloadError', () => {
+  it('classifies a project-not-found stderr as "project"', () => {
+    expect(classifyDopplerDownloadError(PROJECT_NOT_FOUND_STDERR)).toBe('project')
+  })
+
+  it('classifies a config-not-found stderr as "config"', () => {
+    expect(classifyDopplerDownloadError(CONFIG_NOT_FOUND_STDERR)).toBe('config')
+  })
+
+  it('is color-safe — the markers are matched despite ANSI codes', () => {
+    expect(classifyDopplerDownloadError('Doppler Error: Could not find requested project')).toBe('project')
+  })
+
+  it('returns "unknown" for unrelated failures (auth, network, timeout)', () => {
+    expect(classifyDopplerDownloadError('Doppler Error: you must be logged in')).toBe('unknown')
+    expect(classifyDopplerDownloadError('connect ETIMEDOUT')).toBe('unknown')
+    expect(classifyDopplerDownloadError('')).toBe('unknown')
+  })
+})
+
+describe('buildDopplerNotFoundMessage', () => {
+  it('names the missing project and points at envManagement.config.name', () => {
+    const msg = buildDopplerNotFoundMessage({ kind: 'project', project: 'infra-kit', config: 'dev', available: null })
+
+    expect(msg).toContain('Doppler project "infra-kit" not found')
+    expect(msg).toContain('envManagement.config.name')
+    expect(msg).toContain('Fix:')
+  })
+
+  it('lists available projects when the enrichment list is non-empty', () => {
+    const msg = buildDopplerNotFoundMessage({
+      kind: 'project',
+      project: 'infra-kit',
+      config: 'dev',
+      available: ['example-project', 'nomadream'],
+    })
+
+    expect(msg).toContain('Available projects: example-project, nomadream.')
+  })
+
+  it('omits the available line when the list is empty (told: none exist)', () => {
+    const msg = buildDopplerNotFoundMessage({ kind: 'project', project: 'infra-kit', config: 'dev', available: [] })
+
+    expect(msg).not.toContain('Available projects')
+  })
+
+  it('omits the available line when the list is null (lookup failed)', () => {
+    const msg = buildDopplerNotFoundMessage({ kind: 'project', project: 'infra-kit', config: 'dev', available: null })
+
+    expect(msg).not.toContain('Available projects')
+  })
+
+  it('names the missing config, its project, and points at environments', () => {
+    const msg = buildDopplerNotFoundMessage({
+      kind: 'config',
+      project: 'nomadream',
+      config: 'staging',
+      available: ['dev', 'arthur'],
+    })
+
+    expect(msg).toContain('Doppler config "staging" not found in project "nomadream"')
+    expect(msg).toContain('infra-kit.json → environments')
+    expect(msg).toContain('Available configs in "nomadream": dev, arthur.')
+  })
+})

package/src/integrations/doppler/doppler-cli-auth.ts

@@ -1,14 +1,22 @@
 import { $ } from 'zx'
 
+/**
+ * Hard upper bound for the Doppler auth probes. `doppler me` is a network call;
+ * without a timeout a hung VPN/connection would stall every caller indefinitely
+ * (notably the env auto-load preAction hook, which runs before each CLI command).
+ */
+const DOPPLER_AUTH_TIMEOUT_MS = 5_000
+
 /**
  * Validate Doppler CLI installation and authentication status. Throws on failure
  * so callers (CLI entry, MCP tool handler) can translate to the right surface —
  * CLI exits non-zero; MCP returns a structured tool error instead of tearing
- * down the server.
+ * down the server. Both probes are time-bounded so a hung Doppler/network never
+ * blocks the caller (a timeout surfaces as the same "not authenticated" path).
  */
 export const validateDopplerCliAndAuth = async (): Promise<void> => {
   try {
-    await $`doppler --version`
+    await $`doppler --version`.timeout(DOPPLER_AUTH_TIMEOUT_MS)
   } catch (error: unknown) {
     throw new Error('Doppler CLI is not installed. Install it from: https://docs.doppler.com/docs/install-cli', {
       cause: error,
@@ -16,8 +24,8 @@ export const validateDopplerCliAndAuth = async (): Promise<void> => {
   }
 
   try {
-    await $`doppler me`
+    await $`doppler me`.timeout(DOPPLER_AUTH_TIMEOUT_MS)
   } catch (error: unknown) {
-    throw new Error('Doppler CLI is not authenticated. Run: doppler login', { cause: error })
+    throw new Error('Doppler CLI is not authenticated (or timed out). Run: doppler login', { cause: error })
   }
 }

package/src/integrations/doppler/doppler-errors.ts

@@ -0,0 +1,88 @@
+/**
+ * Translate Doppler `secrets download` not-found failures into actionable,
+ * point-at-the-fix guidance. Pure (no I/O) so the classification + message policy
+ * is unit-testable without spawning the Doppler CLI — mirroring the pure-helper
+ * pattern in `commands/env-load/env-load.ts`.
+ *
+ * Observed Doppler output on a not-found download (verified 2026-06-27, doppler
+ * v3.76.0), exit 1, written to STDERR (stdout empty):
+ *   Unable to download secrets
+ *   Doppler Error: Could not find requested project 'name'
+ *   Doppler Error: Could not find requested config 'name'
+ * Only the "Doppler Error:" prefix is ANSI-colored; the "Could not find requested
+ * ..." text is plain, so substring matching is color-safe. zx's
+ * `ProcessOutput.message` also concatenates stdout+stderr, so the same markers are
+ * matchable off `.message` when `.stderr` is unavailable.
+ */
+
+/** Which kind of Doppler not-found a download failure represents (`unknown` = not a not-found error). */
+export type DopplerNotFoundKind = 'project' | 'config' | 'unknown'
+
+const PROJECT_NOT_FOUND_MARKER = 'Could not find requested project'
+const CONFIG_NOT_FOUND_MARKER = 'Could not find requested config'
+
+/**
+ * Classify a Doppler download failure from its stderr/message text. Returns
+ * `'unknown'` for anything that isn't a recognized not-found error so the caller
+ * rethrows the original untouched (degrades to status quo, never worse).
+ *
+ * @example
+ * classifyDopplerDownloadError("Doppler Error: Could not find requested project 'x'") // => 'project'
+ * classifyDopplerDownloadError("Doppler Error: Could not find requested config 'dev'") // => 'config'
+ * classifyDopplerDownloadError('network unreachable')                                  // => 'unknown'
+ */
+export const classifyDopplerDownloadError = (stderr: string): DopplerNotFoundKind => {
+  if (stderr.includes(PROJECT_NOT_FOUND_MARKER)) return 'project'
+
+  if (stderr.includes(CONFIG_NOT_FOUND_MARKER)) return 'config'
+
+  return 'unknown'
+}
+
+interface DopplerNotFoundMessageArgs {
+  /** Whether the missing entity is the project or the config within it. */
+  kind: 'project' | 'config'
+  project: string
+  config: string
+  /**
+   * Names to suggest. `null` = lookup failed/unavailable, `[]` = none exist; both
+   * omit the suggestion line so a failed enrichment probe is never misreported as
+   * a definitive "none available".
+   */
+  available?: string[] | null
+}
+
+/**
+ * Build the actionable, multi-line error body for a Doppler not-found failure:
+ * states what's missing, points at the exact infra-kit.json field, lists available
+ * names when known, and gives a concrete fix.
+ *
+ * @example
+ * buildDopplerNotFoundMessage({ kind: 'project', project: 'infra-kit', config: 'dev', available: ['nomadream'] })
+ * // => 'Doppler project "infra-kit" not found (set in infra-kit.json → envManagement.config.name).\nAvailable projects: nomadream.\nFix: ...'
+ */
+export const buildDopplerNotFoundMessage = ({
+  kind,
+  project,
+  config,
+  available,
+}: DopplerNotFoundMessageArgs): string => {
+  const lines: string[] =
+    kind === 'project'
+      ? [`Doppler project "${project}" not found (set in infra-kit.json → envManagement.config.name).`]
+      : [`Doppler config "${config}" not found in project "${project}" (set in infra-kit.json → environments).`]
+
+  if (available && available.length > 0) {
+    const label = kind === 'project' ? 'Available projects' : `Available configs in "${project}"`
+
+    lines.push(`${label}: ${available.join(', ')}.`)
+  }
+
+  lines.push(
+    kind === 'project'
+      ? 'Fix: update envManagement.config.name to an existing project, or create it in Doppler.'
+      : 'Fix: update environments to an existing config, or create it in Doppler.',
+  )
+
+  return lines.join('\n')
+}

package/src/integrations/doppler/doppler-project.ts

@@ -1,5 +1,15 @@
+import { $ } from 'zx'
+import type { ProcessPromise } from 'zx'
+
 import { getInfraKitConfig } from 'src/lib/infra-kit-config'
 
+/**
+ * Hard upper bound for the Doppler list probes. These run only on error/diagnostic
+ * paths (download-failure enrichment, `doctor`), but a hung VPN/connection must not
+ * stall them — mirrors the auth-probe budget in `doppler-cli-auth.ts`.
+ */
+const DOPPLER_LIST_TIMEOUT_MS = 5_000
+
 /**
  * Resolve Doppler project name from infra-kit.json at the project root
  */
@@ -8,3 +18,73 @@ export const getDopplerProject = async (): Promise<string> => {
 
   return envManagement.config.name
 }
+
+/**
+ * List the Doppler project names for the authenticated account, or `null` when the
+ * lookup itself fails (CLI missing, unauthenticated, network/timeout, malformed
+ * JSON). NEVER throws. Callers MUST distinguish `null` ("couldn't tell") from `[]`
+ * ("told: none exist") so an enrichment or diagnostic message never misreports a
+ * failed probe as "no projects available".
+ *
+ * @example
+ * await listDopplerProjects() // => ['example-project', 'nomadream']  (or null on failure)
+ */
+export const listDopplerProjects = async (): Promise<string[] | null> => {
+  return runDopplerNameList(() => {
+    return $`doppler projects --json`
+  })
+}
+
+/**
+ * List the Doppler config names for a project, or `null` when the lookup itself
+ * fails (see {@link listDopplerProjects} for the `null` vs `[]` contract).
+ *
+ * @example
+ * await listDopplerConfigs('nomadream') // => ['dev', 'oleg', 'prod', 'arthur']  (or null on failure)
+ */
+export const listDopplerConfigs = async (project: string): Promise<string[] | null> => {
+  return runDopplerNameList(() => {
+    return $`doppler configs --project ${project} --json`
+  })
+}
+
+/**
+ * Run a `doppler ... --json` listing quietly + time-bounded and extract the `name`
+ * field of each entry. Returns `null` on any failure (subprocess error, timeout,
+ * non-array/malformed JSON) so the caller can tell a failed probe from an empty set.
+ */
+const runDopplerNameList = async (run: () => ProcessPromise): Promise<string[] | null> => {
+  const prevQuiet = $.quiet
+
+  $.quiet = true
+  try {
+    const result = await run().timeout(DOPPLER_LIST_TIMEOUT_MS)
+
+    return parseDopplerNames(result.stdout)
+  } catch {
+    return null
+  } finally {
+    $.quiet = prevQuiet
+  }
+}
+
+/** Parse a Doppler `--json` array into its `name` strings, or `null` if the shape is unexpected. */
+const parseDopplerNames = (stdout: string): string[] | null => {
+  let parsed: unknown
+
+  try {
+    parsed = JSON.parse(stdout)
+  } catch {
+    return null
+  }
+
+  if (!Array.isArray(parsed)) return null
+
+  return parsed
+    .map((entry) => {
+      return entry !== null && typeof entry === 'object' ? (entry as { name?: unknown }).name : undefined
+    })
+    .filter((name): name is string => {
+      return typeof name === 'string'
+    })
+}

package/src/integrations/doppler/index.ts

@@ -1,2 +1,4 @@
 export { validateDopplerCliAndAuth } from './doppler-cli-auth'
-export { getDopplerProject } from './doppler-project'
+export { buildDopplerNotFoundMessage, classifyDopplerDownloadError } from './doppler-errors'
+export type { DopplerNotFoundKind } from './doppler-errors'
+export { getDopplerProject, listDopplerConfigs, listDopplerProjects } from './doppler-project'

package/src/integrations/gh/gh-cli-auth/gh-cli-auth.ts

@@ -1,6 +1,6 @@
-import process from 'node:process'
 import { $ } from 'zx'
 
+import { OperationError } from 'src/lib/errors/operation-error'
 import { logger } from 'src/lib/logger'
 
 /**
@@ -11,15 +11,19 @@ export const validateGitHubCliAndAuth = async () => {
     await $`gh --version`
   } catch (error: unknown) {
     logger.error({ error }, 'Error: GitHub CLI (gh) is not installed.')
-    logger.error('Please install it from: https://cli.github.com/')
-    process.exit(1)
+    throw new OperationError(error, {
+      operation: 'verify GitHub CLI is installed',
+      remediation: 'install gh from https://cli.github.com/',
+    })
   }
 
   try {
     await $`gh auth status`
   } catch (error: unknown) {
     logger.error({ error }, 'Error: GitHub CLI (gh) is not authenticated.')
-    logger.error('Please authenticate it from: https://cli.github.com/manual/gh_auth_login or type "gh auth login"')
-    process.exit(1)
+    throw new OperationError(error, {
+      operation: 'verify GitHub CLI authentication',
+      remediation: 'run "gh auth login" (https://cli.github.com/manual/gh_auth_login)',
+    })
   }
 }

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

@@ -1,6 +1,6 @@
-import process from 'node:process'
 import { $ } from 'zx'
 
+import { OperationError } from 'src/lib/errors/operation-error'
 import { logger } from 'src/lib/logger'
 import { compareReleaseIds, formatBranchName, formatPrTitle, parseBranchName } from 'src/lib/release-id'
 import type { ReleaseId } from 'src/lib/release-id'
@@ -84,18 +84,21 @@ export const getReleasePRs = async (): Promise<string[]> => {
     const prs = await fetchAllReleasePRs()
 
     if (prs.length === 0) {
-      logger.error('❌ No release PRs found. Check the project folder for the script. Exiting...')
-
-      process.exit(1)
+      throw new OperationError(undefined, {
+        operation: 'find open release PRs',
+        remediation: 'open a release PR first, or check you are in the right repo',
+      })
     }
 
     return sortReleasePRs(prs).map((pr) => {
       return pr.headRefName
     })
   } catch (error) {
+    if (error instanceof OperationError) throw error
+
     logger.error({ error }, '❌ Error fetching release PRs')
 
-    process.exit(1)
+    throw new OperationError(error, { operation: 'fetch release PRs' })
   }
 }
 
@@ -110,8 +113,10 @@ export const getReleasePRsWithInfo = async (): Promise<ReleasePRInfo[]> => {
     const prs = await fetchAllReleasePRs()
 
     if (prs.length === 0) {
-      logger.error('❌ No release PRs found. Check the project folder for the script. Exiting...')
-      process.exit(1)
+      throw new OperationError(undefined, {
+        operation: 'find open release PRs',
+        remediation: 'open a release PR first, or check you are in the right repo',
+      })
     }
 
     return sortReleasePRs(prs).map((pr) => {
@@ -122,8 +127,11 @@ export const getReleasePRsWithInfo = async (): Promise<ReleasePRInfo[]> => {
       }
     })
   } catch (error) {
+    if (error instanceof OperationError) throw error
+
     logger.error({ error }, '❌ Error fetching release PRs')
-    process.exit(1)
+
+    throw new OperationError(error, { operation: 'fetch release PRs' })
   }
 }