infra-kit 0.1.127 → 0.1.129

package/src/lib/env-autoload/index.ts

@@ -1,9 +0,0 @@
-export { decideAutoLoad, resolveEnvAutoLoad, runEnvAutoLoad } from './env-autoload'
-export type {
-  AutoLoadDecision,
-  AutoLoadDecisionInput,
-  AutoLoadEnvSnapshot,
-  AutoLoadTrigger,
-  ResolvedEnvAutoLoad,
-  RunEnvAutoLoadArgs,
-} from './env-autoload'

package/src/lib/error-handlers/index.ts

@@ -1,36 +0,0 @@
-import process from 'node:process'
-import type { Logger } from 'pino'
-
-import { LOG_FILE_PATH } from '../logger/index'
-
-/**
- * Setup error handlers for the application
- * @param logger - The logger instance
- *
- * ONLY FOR SERVER!
- */
-export const setupErrorHandlers = (logger: Logger) => {
-  process.on('SIGINT', () => {
-    logger.info({ msg: 'Received SIGINT. Shutting down...' })
-    process.exit(0)
-  })
-
-  process.on('SIGTERM', () => {
-    logger.info({ msg: 'Received SIGTERM. Shutting down...' })
-    process.exit(0)
-  })
-
-  process.on('uncaughtException', (error) => {
-    logger.fatal({ err: error, msg: 'Uncaught Exception' })
-    logger.error(`Uncaught Exception! Check ${LOG_FILE_PATH}. Shutting down...`)
-    logger.flush()
-    process.exit(1)
-  })
-
-  process.on('unhandledRejection', (reason, promise) => {
-    logger.fatal({ reason, promise, msg: 'Unhandled Rejection' })
-    logger.error(`Unhandled Rejection! Check ${LOG_FILE_PATH}. Shutting down...`)
-    logger.flush()
-    process.exit(1)
-  })
-}

package/src/lib/errors/__tests__/is-prompt-cancellation.test.ts

@@ -1,48 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { isPromptCancellation } from '../is-prompt-cancellation'
-import { OperationError } from '../operation-error'
-
-/** Mirrors the @inquirer/core error shape (matched by `name`, not class). */
-const makeNamedError = (name: string): Error => {
-  const err = new Error('prompt ended')
-
-  err.name = name
-
-  return err
-}
-
-describe('isPromptCancellation', () => {
-  it('detects a Ctrl-C / Esc ExitPromptError', () => {
-    expect(isPromptCancellation(makeNamedError('ExitPromptError'))).toBe(true)
-  })
-
-  it('detects a signal-driven AbortPromptError', () => {
-    expect(isPromptCancellation(makeNamedError('AbortPromptError'))).toBe(true)
-  })
-
-  it('unwraps a cancellation re-wrapped in an OperationError', () => {
-    const wrapped = new OperationError(makeNamedError('ExitPromptError'), {
-      operation: 'create worktrees',
-      remediation: 'irrelevant',
-    })
-
-    expect(isPromptCancellation(wrapped)).toBe(true)
-  })
-
-  it('returns false for a genuine operational error', () => {
-    expect(isPromptCancellation(new Error('fatal: not a git repository'))).toBe(false)
-  })
-
-  it('returns false for an OperationError wrapping a real failure', () => {
-    const wrapped = new OperationError(new Error('boom'), { operation: 'create worktrees' })
-
-    expect(isPromptCancellation(wrapped)).toBe(false)
-  })
-
-  it('returns false for non-error values', () => {
-    expect(isPromptCancellation(undefined)).toBe(false)
-    expect(isPromptCancellation(null)).toBe(false)
-    expect(isPromptCancellation('ExitPromptError')).toBe(false)
-  })
-})

package/src/lib/errors/__tests__/operation-error.test.ts

@@ -1,62 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { OperationError } from '../operation-error'
-
-describe('operationError', () => {
-  it('formats a minimal message from operation alone', () => {
-    const err = new OperationError(new Error('boom'), { operation: 'do the thing' })
-
-    expect(err).toBeInstanceOf(OperationError)
-    expect(err.message).toBe('failed to do the thing')
-    expect(err.cause).toBeInstanceOf(Error)
-    expect(err.operation).toBe('do the thing')
-  })
-
-  it('appends a remediation hint when provided', () => {
-    const err = new OperationError(new Error('boom'), {
-      operation: 'do the thing',
-      remediation: 'check the docs',
-    })
-
-    expect(err.message).toBe('failed to do the thing — try: check the docs')
-    expect(err.remediation).toBe('check the docs')
-  })
-
-  it('extracts a stderr excerpt from a zx ProcessOutput-shaped cause', () => {
-    const zxLike = { stderr: 'fatal: not a git repository\n(more lines...)' }
-    const err = new OperationError(zxLike, { operation: 'run git' })
-
-    expect(err.message).toContain('stderr: fatal: not a git repository')
-  })
-
-  it('truncates oversized stderr excerpts', () => {
-    const huge = 'X'.repeat(5000)
-    const err = new OperationError({ stderr: huge }, { operation: 'run git' })
-
-    expect(err.message.length).toBeLessThan(300)
-  })
-
-  it('prefers an explicit stderrExcerpt over the cause stderr', () => {
-    const err = new OperationError(
-      { stderr: 'raw zx output' },
-      { operation: 'run git', stderrExcerpt: 'curated excerpt' },
-    )
-
-    expect(err.message).toContain('stderr: curated excerpt')
-    expect(err.message).not.toContain('raw zx output')
-  })
-
-  it('preserves the original cause', () => {
-    const cause = new Error('underlying')
-    const err = new OperationError(cause, { operation: 'do thing' })
-
-    expect(err.cause).toBe(cause)
-  })
-
-  it('handles non-Error causes', () => {
-    const err = new OperationError('a string', { operation: 'do thing' })
-
-    expect(err.message).toBe('failed to do thing')
-    expect(err.cause).toBe('a string')
-  })
-})

package/src/lib/errors/format-zx-error.ts

@@ -1,54 +0,0 @@
-const STDERR_EXCERPT_MAX_BYTES = 500
-const STDOUT_EXCERPT_MAX_BYTES = 200
-
-export interface ZxErrorFields {
-  exitCode?: number | null
-  stderr?: string
-  stdout?: string
-  message?: string
-  name?: string
-}
-
-const readTrimmedString = (value: unknown, max: number): string | undefined => {
-  if (typeof value !== 'string' || value.length === 0) return undefined
-
-  return value.slice(-max).trim()
-}
-
-/**
- * Extract loggable fields from an error for `logger.error({ err: formatZxError(e) }, ...)`.
- *
- * pino's default `err` serializer handles `Error` subclasses but renders zx's
- * `ProcessOutput` as `{}` because its informative fields (`stderr`, `stdout`,
- * `exitCode`) are non-enumerable / on the prototype. This helper duck-types
- * those fields so subprocess failures surface in logs instead of vanishing.
- */
-export const formatZxError = (error: unknown): ZxErrorFields => {
-  if (error === null || typeof error !== 'object') {
-    return { message: String(error) }
-  }
-
-  const rec = error as Record<string, unknown>
-  const fields: ZxErrorFields = {}
-
-  if (error instanceof Error) {
-    fields.name = error.name
-    fields.message = error.message
-  } else if (typeof rec.message === 'string') {
-    fields.message = rec.message
-  }
-
-  const exitCode = rec.exitCode
-
-  if (typeof exitCode === 'number' || exitCode === null) fields.exitCode = exitCode
-
-  const stderr = readTrimmedString(rec.stderr, STDERR_EXCERPT_MAX_BYTES)
-
-  if (stderr) fields.stderr = stderr
-
-  const stdout = readTrimmedString(rec.stdout, STDOUT_EXCERPT_MAX_BYTES)
-
-  if (stdout) fields.stdout = stdout
-
-  return fields
-}

package/src/lib/errors/is-prompt-cancellation.ts

@@ -1,38 +0,0 @@
-/**
- * Names of the `@inquirer/core` error classes thrown when an interactive prompt
- * ends without a value: `ExitPromptError` (user pressed Ctrl-C / Esc) and
- * `AbortPromptError` (the prompt was aborted via an `AbortSignal`). Both are
- * intentional cancellations, not failures.
- */
-const CANCELLATION_ERROR_NAMES = new Set(['ExitPromptError', 'AbortPromptError'])
-
-const hasCancellationName = (value: unknown): boolean => {
-  return value instanceof Error && CANCELLATION_ERROR_NAMES.has(value.name)
-}
-
-/**
- * True when `error` represents a user (or signal) cancellation of an
- * `@inquirer/*` prompt — i.e. pressing Ctrl-C / Esc in the branch picker or a
- * confirm step. Matched by `name` rather than `instanceof` so it stays correct
- * even when pnpm dedupes more than one copy of `@inquirer/core` into the tree
- * (an `instanceof` check fails across realms/duplicate classes).
- *
- * Also unwraps one level of `cause`, so a cancellation re-wrapped in an
- * {@link ./operation-error.OperationError} is still recognised at the top-level
- * error boundary.
- *
- * @example
- * try {
- *   await checkbox({ message: 'Select release branches', choices })
- * } catch (err) {
- *   if (isPromptCancellation(err)) process.exit(0) // clean back-out, not an error
- *   throw err
- * }
- */
-export const isPromptCancellation = (error: unknown): boolean => {
-  if (hasCancellationName(error)) return true
-
-  const cause = (error as { cause?: unknown } | null | undefined)?.cause
-
-  return hasCancellationName(cause)
-}

package/src/lib/errors/operation-error.ts

@@ -1,80 +0,0 @@
-const STDERR_EXCERPT_MAX_BYTES = 200
-
-export interface OperationErrorContext {
-  operation: string
-  remediation?: string
-  stderrExcerpt?: string
-}
-
-/**
- * Duck-typed read of zx's `ProcessOutput.stderr` (and similar shapes) without
- * importing zx types just for an `instanceof` check.
- *
- * @example
- * extractStderr(new Error('x'))               // undefined
- * extractStderr({ stderr: 'fatal: ...' })     // 'fatal: ...'
- * extractStderr({ stderr: '' })               // undefined  (empty treated as missing)
- */
-export const extractStderr = (cause: unknown): string | undefined => {
-  if (cause === null || typeof cause !== 'object') return undefined
-  const stderr = (cause as { stderr?: unknown }).stderr
-
-  return typeof stderr === 'string' && stderr.length > 0 ? stderr : undefined
-}
-
-/**
- * Compose the human-and-agent-readable message body for an `OperationError`:
- * `"failed to <operation> [— stderr: <excerpt>] [— try: <remediation>]"`.
- * `stderrExcerpt` overrides anything duck-typed off `cause`; both are trimmed
- * and capped at {@link STDERR_EXCERPT_MAX_BYTES} so a runaway subprocess can't
- * blow up the message.
- */
-const buildMessage = (cause: unknown, ctx: OperationErrorContext): string => {
-  const stderr = ctx.stderrExcerpt ?? extractStderr(cause)
-  const parts = [`failed to ${ctx.operation}`]
-
-  if (stderr) parts.push(`stderr: ${stderr.slice(0, STDERR_EXCERPT_MAX_BYTES).trim()}`)
-  if (ctx.remediation) parts.push(`try: ${ctx.remediation}`)
-
-  return parts.join(' — ')
-}
-
-/**
- * Error type for any handler-level failure that should surface to the caller
- * (CLI user or MCP-connected agent) with a remediation hint. Wraps an
- * underlying cause and renders a single-line, structured message so logs and
- * agent tool-result text stay scannable.
- *
- * Pattern modeled on the exemplary Doppler errors in
- * `src/integrations/doppler/doppler-cli-auth.ts`.
- *
- * @example
- * // wrap a zx subprocess failure
- * try {
- *   await $`git worktree add ${path} ${branch}`
- * } catch (err) {
- *   throw new OperationError(err, {
- *     operation: `git worktree add for ${branch}`,
- *     remediation: 'check the branch name and that the parent dir is writable',
- *   })
- * }
- *
- * @example
- * // validation failure with no underlying cause
- * throw new OperationError(undefined, {
- *   operation: 'launch deploy-all workflow',
- *   remediation: `pass one of: ${environments.join(', ')}`,
- *   stderrExcerpt: `invalid environment: ${selectedEnv}`,
- * })
- */
-export class OperationError extends Error {
-  readonly operation: string
-  readonly remediation?: string
-
-  constructor(cause: unknown, ctx: OperationErrorContext) {
-    super(buildMessage(cause, ctx), { cause })
-    this.name = 'OperationError'
-    this.operation = ctx.operation
-    this.remediation = ctx.remediation
-  }
-}

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

@@ -1,92 +0,0 @@
-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

@@ -1,55 +0,0 @@
-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

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