infra-kit 0.1.114 → 0.1.117

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

@@ -6,7 +6,12 @@ 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, getRepoName } from 'src/lib/git-utils'
 
-import { getInfraKitConfig, resetInfraKitConfigCache, resolveConfiguredIdes } from '../infra-kit-config'
+import {
+  getInfraKitConfig,
+  resetInfraKitConfigCache,
+  resolveCmuxLayout,
+  resolveConfiguredIdes,
+} from '../infra-kit-config'
 import type { InfraKitConfig } from '../infra-kit-config'
 
 vi.mock('src/lib/git-utils', () => {
@@ -32,7 +37,7 @@ const withTmpRepo = async (fn: (tmp: string) => Promise<void>): Promise<void> =>
   vi.mocked(getProjectRoot).mockResolvedValue(tmp)
   vi.mocked(getRepoName).mockResolvedValue(path.basename(tmp))
   // Point os.homedir() at the tmp dir so user-scope override layers
-  // (~/.infra-kit/config.json, ~/.infra-kit/projects/<repo>/infra-kit.json)
+  // (~/.infra-kit/infra-kit.json, ~/.infra-kit/projects/<repo>/infra-kit.json)
   // can't leak the developer's real config into the test.
   const homedirSpy = vi.spyOn(os, 'homedir').mockReturnValue(tmp)
 
@@ -240,7 +245,7 @@ describe('getInfraKitConfig', () => {
 
       fs.mkdirSync(userGlobalDir, { recursive: true })
       fs.writeFileSync(
-        path.join(userGlobalDir, 'config.json'),
+        path.join(userGlobalDir, 'infra-kit.json'),
         JSON.stringify({ worktrees: { openInGithubDesktop: false, openInCmux: true } }),
       )
 
@@ -258,7 +263,7 @@ describe('getInfraKitConfig', () => {
       const userGlobalDir = path.join(tmp, '.infra-kit')
 
       fs.mkdirSync(userGlobalDir, { recursive: true })
-      fs.writeFileSync(path.join(userGlobalDir, 'config.json'), '   \n')
+      fs.writeFileSync(path.join(userGlobalDir, 'infra-kit.json'), '   \n')
 
       const cfg = await getInfraKitConfig()
 
@@ -320,7 +325,7 @@ describe('getInfraKitConfig', () => {
     })
   })
 
-  it('ignores a non-loaded config.example.jsonc in the user-global layer', async () => {
+  it('ignores a non-loaded infra-kit.example.jsonc in the user-global layer', async () => {
     await withTmpRepo(async (tmp) => {
       fs.writeFileSync(path.join(tmp, 'infra-kit.json'), VALID_JSON)
 
@@ -328,7 +333,10 @@ describe('getInfraKitConfig', () => {
 
       fs.mkdirSync(userGlobalDir, { recursive: true })
       // Schema-failing content that must never be merged.
-      fs.writeFileSync(path.join(userGlobalDir, 'config.example.jsonc'), '{\n  // comment\n  "environments": []\n}\n')
+      fs.writeFileSync(
+        path.join(userGlobalDir, 'infra-kit.example.jsonc'),
+        '{\n  // comment\n  "environments": []\n}\n',
+      )
 
       const cfg = await getInfraKitConfig()
 
@@ -431,3 +439,66 @@ describe('resolveConfiguredIdes', () => {
     expect(resolveConfiguredIdes(base)).toEqual([])
   })
 })
+
+describe('resolveCmuxLayout', () => {
+  const base = {
+    environments: ['dev'],
+    envManagement: { provider: 'doppler', config: { name: 'p' } },
+  } as InfraKitConfig
+
+  it('defaults to two-columns when worktrees.cmux is unset', () => {
+    expect(resolveCmuxLayout(base)).toBe('two-columns')
+  })
+
+  it('defaults to two-columns when worktrees is set but cmux.layout is unset', () => {
+    const cfg = { ...base, worktrees: { openInCmux: true } } as InfraKitConfig
+
+    expect(resolveCmuxLayout(cfg)).toBe('two-columns')
+  })
+
+  it('returns the explicit two-columns layout', () => {
+    const cfg = { ...base, worktrees: { cmux: { layout: 'two-columns' } } } as InfraKitConfig
+
+    expect(resolveCmuxLayout(cfg)).toBe('two-columns')
+  })
+
+  it('returns the explicit three-pane layout', () => {
+    const cfg = { ...base, worktrees: { cmux: { layout: 'three-pane' } } } as InfraKitConfig
+
+    expect(resolveCmuxLayout(cfg)).toBe('three-pane')
+  })
+})
+
+describe('worktrees.cmux schema validation', () => {
+  it('accepts a valid cmux.layout and round-trips it through getInfraKitConfig', async () => {
+    await withTmpRepo(async (tmp) => {
+      fs.writeFileSync(
+        path.join(tmp, 'infra-kit.json'),
+        JSON.stringify({
+          environments: ['dev'],
+          envManagement: { provider: 'doppler', config: { name: 'p' } },
+          worktrees: { openInCmux: true, cmux: { layout: 'three-pane' } },
+        }),
+      )
+
+      const cfg = await getInfraKitConfig()
+
+      expect(resolveCmuxLayout(cfg)).toBe('three-pane')
+    })
+  })
+
+  it('rejects an unknown cmux.layout value', async () => {
+    await withTmpRepo(async (tmp) => {
+      fs.writeFileSync(
+        path.join(tmp, 'infra-kit.json'),
+        JSON.stringify({
+          environments: ['dev'],
+          envManagement: { provider: 'doppler', config: { name: 'p' } },
+          worktrees: { cmux: { layout: 'four-pane' } },
+        }),
+      )
+
+      await expect(getInfraKitConfig()).rejects.toThrow(/Invalid.*infra-kit/i)
+    })
+  })
+})

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

@@ -4,6 +4,14 @@ export {
   infraKitConfigSchema,
   infraKitOverrideConfigSchema,
   resetInfraKitConfigCache,
+  resolveCmuxLayout,
   resolveConfiguredIdes,
+  USER_CONFIG_DIR_NAME,
+} from './infra-kit-config'
+export type {
+  CmuxLayout,
+  ConfiguredIde,
+  EnvAutoLoadConfig,
+  InfraKitConfig,
+  InfraKitConfigPaths,
 } from './infra-kit-config'
-export type { ConfiguredIde, InfraKitConfig, InfraKitConfigPaths } from './infra-kit-config'

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

@@ -3,12 +3,19 @@ import os from 'node:os'
 import path from 'node:path'
 import { z } from 'zod'
 
-import { getProjectRoot, getRepoName } from 'src/lib/git-utils'
+import { getProjectRoot } from 'src/lib/git-utils'
 
 const INFRA_KIT_CONFIG_FILE = 'infra-kit.json'
 
-const USER_CONFIG_DIR_NAME = '.infra-kit'
-const USER_GLOBAL_CONFIG_FILE = 'config.json'
+/**
+ * Directory under the user's home that holds all machine-local infra-kit config:
+ * the runtime `infra-kit.json` merge layer, per-project overrides, and the factory
+ * registry (`vendor.json`). Single source of truth for `.infra-kit`, reused
+ * by the vendor factory-config loader (no import cycle — this module imports no
+ * `lib/vendor` code).
+ */
+export const USER_CONFIG_DIR_NAME = '.infra-kit'
+const USER_GLOBAL_CONFIG_FILE = 'infra-kit.json'
 const USER_PROJECTS_DIR = 'projects'
 
 // envManagement
@@ -64,12 +71,40 @@ const jiraTaskManagerSchema = z.object({
 
 const taskManagerSchema = z.discriminatedUnion('provider', [jiraTaskManagerSchema])
 
+// cmux pane layout for opened worktree workspaces. Named presets keep the config
+// typo-proof (an enum, not a free string) and let the opener switch on a single
+// value; extend the enum + the opener's switch to add a layout.
+//   two-columns — left | right, both full-height (default)
+//   three-pane  — left split top/bottom + full-height right (legacy layout)
+const cmuxLayouts = ['two-columns', 'three-pane'] as const
+
+const cmuxConfigSchema = z.object({
+  layout: z.enum(cmuxLayouts).optional(),
+})
+
 // worktrees prompt defaults
 const worktreesConfigSchema = z.object({
   openInGithubDesktop: z.boolean().optional(),
   openInCmux: z.boolean().optional(),
+  cmux: cmuxConfigSchema.optional(),
 })
 
+// env auto-load: opt-in convenience that primes Doppler env when you work inside
+// this project / a worktree. Absent => disabled. `trigger` selects the moment
+// (pick one):
+//   shell-startup  — when a new shell opens inside the project
+//   cli-invocation — before each `infra-kit` command (primes SUBSEQUENT commands)
+// `config` names which environment to load. It is intentionally NOT validated
+// against `environments` here: an invalid name must DISABLE the feature at
+// resolve time (lib/env-autoload), never throw inside the merged-config parse and
+// brick every command.
+const envAutoLoadSchema = z
+  .object({
+    trigger: z.enum(['shell-startup', 'cli-invocation']),
+    config: z.string().min(1),
+  })
+  .strict()
+
 // Base object shape, kept separate so `.partial()` (which only works on a plain
 // ZodObject, not the `.superRefine`-wrapped full schema) can derive the override
 // schema from it.
@@ -79,6 +114,7 @@ const infraKitConfigObject = z.object({
   ide: idesSchema.optional(),
   taskManager: taskManagerSchema.optional(),
   worktrees: worktreesConfigSchema.optional(),
+  envAutoLoad: envAutoLoadSchema.optional(),
 })
 
 // Full schema = base object + a parse-time uniqueness check on the `ide` array.
@@ -110,6 +146,9 @@ export const infraKitOverrideConfigSchema = infraKitConfigObject.partial()
 
 export type InfraKitConfig = z.infer<typeof infraKitConfigSchema>
 
+/** Resolved env auto-load config (`{ trigger, config }`), or `undefined` when off. */
+export type EnvAutoLoadConfig = z.infer<typeof envAutoLoadSchema>
+
 /** A single resolved IDE entry (`{ provider, config }`). */
 export type ConfiguredIde = z.infer<typeof ideSchema>
 
@@ -131,6 +170,25 @@ export const resolveConfiguredIdes = (config: InfraKitConfig): ConfiguredIde[] =
   return Array.isArray(ide) ? ide : [ide]
 }
 
+/** A cmux pane layout preset (see {@link cmuxLayouts}). */
+export type CmuxLayout = (typeof cmuxLayouts)[number]
+
+/** The layout applied when `worktrees.cmux.layout` is left unset. */
+export const DEFAULT_CMUX_LAYOUT: CmuxLayout = 'two-columns'
+
+/**
+ * Resolve the cmux pane layout for opened worktree workspaces, falling back to
+ * {@link DEFAULT_CMUX_LAYOUT} when unconfigured. The one source of truth for
+ * "which layout should the cmux opener build."
+ *
+ * @example
+ * resolveCmuxLayout({ worktrees: { cmux: { layout: 'three-pane' } } }) // => 'three-pane'
+ * resolveCmuxLayout({})                                                // => 'two-columns'
+ */
+export const resolveCmuxLayout = (config: InfraKitConfig): CmuxLayout => {
+  return config.worktrees?.cmux?.layout ?? DEFAULT_CMUX_LAYOUT
+}
+
 export interface InfraKitConfigPaths {
   /** Committed project config (required). */
   main: string
@@ -158,14 +216,16 @@ let cached: CacheEntry | null = null
  * const paths = await getInfraKitConfigPaths()
  * // {
  * //   main:        '/Users/arthur/projects/api/infra-kit.json',
- * //   userGlobal:  '/Users/arthur/.infra-kit/config.json',
+ * //   userGlobal:  '/Users/arthur/.infra-kit/infra-kit.json',
  * //   userProject: '/Users/arthur/.infra-kit/projects/api/infra-kit.json',
  * //   projectName: 'api',
  * // }
  */
 export const getInfraKitConfigPaths = async (): Promise<InfraKitConfigPaths> => {
   const projectRoot = await getProjectRoot()
-  const projectName = await getRepoName()
+  // Repo name is the project-root basename (same as getRepoName), derived here to
+  // avoid a second `git rev-parse` — getRepoName would re-resolve the root.
+  const projectName = path.basename(projectRoot)
   const userConfigDir = path.join(os.homedir(), USER_CONFIG_DIR_NAME)
 
   return {
@@ -180,7 +240,7 @@ export const getInfraKitConfigPaths = async (): Promise<InfraKitConfigPaths> =>
  * Read and validate `infra-kit.json`, with optional override layers shallow-merged
  * on top in this order (later wins):
  *   1. project `infra-kit.json`                            — committed source of truth
- *   2. `~/.infra-kit/config.json`                          — user-global defaults
+ *   2. `~/.infra-kit/infra-kit.json`                       — user-global defaults
  *   3. `~/.infra-kit/projects/<repo-name>/infra-kit.json`  — user-scope per-project overrides
  *
  * Top-level keys (entire capability sections like `ide`, `envManagement`)
@@ -189,7 +249,7 @@ export const getInfraKitConfigPaths = async (): Promise<InfraKitConfigPaths> =>
  *
  * @example
  * // infra-kit.json:           { "environments": ["dev"], "envManagement": { "provider": "doppler", "config": { "name": "p" } } }
- * // ~/.infra-kit/config.json: { "ide": { "provider": "cursor", "config": { "workspaceConfigPath": "./ws.code-workspace" } } }
+ * // ~/.infra-kit/infra-kit.json: { "ide": { "provider": "cursor", "config": { "workspaceConfigPath": "./ws.code-workspace" } } }
  * const cfg = await getInfraKitConfig()
  * // => { environments: ['dev'], envManagement: {...}, ide: { provider: 'cursor', config: { workspaceConfigPath: './ws.code-workspace' } } }
  */
@@ -233,7 +293,7 @@ export const getInfraKitConfig = async (): Promise<InfraKitConfig> => {
 
   const layers: ConfigLayer[] = [
     { label: 'infra-kit.json', path: paths.main, required: true },
-    { label: '~/.infra-kit/config.json', path: paths.userGlobal, required: false },
+    { label: '~/.infra-kit/infra-kit.json', path: paths.userGlobal, required: false },
     {
       label: `~/.infra-kit/projects/${paths.projectName}/infra-kit.json`,
       path: paths.userProject,
@@ -335,12 +395,12 @@ interface ConfigLayer {
  * An empty/whitespace-only file is treated as `{}` (JSON.parse would throw).
  *
  * @example
- * await loadLayer({ label: '~/.infra-kit/config.json', path: '/missing.json', required: false })
+ * await loadLayer({ label: '~/.infra-kit/infra-kit.json', path: '/missing.json', required: false })
  * // => null
  *
  * @example
- * // /home/me/.infra-kit/config.json: '{ "ide": { "provider": "cursor", "config": { "workspaceConfigPath": "./ws.code-workspace" } } }'
- * await loadLayer({ label: '~/.infra-kit/config.json', path: '/home/me/.infra-kit/config.json', required: false })
+ * // /home/me/.infra-kit/infra-kit.json: '{ "ide": { "provider": "cursor", "config": { "workspaceConfigPath": "./ws.code-workspace" } } }'
+ * await loadLayer({ label: '~/.infra-kit/infra-kit.json', path: '/home/me/.infra-kit/infra-kit.json', required: false })
  * // => { ide: { provider: 'cursor', config: { workspaceConfigPath: './ws.code-workspace' } } }
  */
 const loadLayer = async (layer: ConfigLayer): Promise<Record<string, unknown> | null> => {

package/src/lib/json-output/__tests__/json-output.test.ts

@@ -0,0 +1,139 @@
+import { Command } from 'commander'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { addJsonOption, emit, jsonOutput } from '../json-output'
+
+describe('json-output', () => {
+  afterEach(() => {
+    jsonOutput.enabled = false
+  })
+
+  describe('emit', () => {
+    it('writes structuredContent as pretty JSON when enabled', () => {
+      jsonOutput.enabled = true
+      const writes: string[] = []
+
+      const result = emit({ structuredContent: { version: '1.2.3' } }, (text) => {
+        writes.push(text)
+      })
+
+      expect(writes).toHaveLength(1)
+      const [payload = ''] = writes
+
+      expect(JSON.parse(payload)).toEqual({ version: '1.2.3' })
+      // returns the result unchanged for pass-through use (emit(await handler()))
+      expect(result).toEqual({ structuredContent: { version: '1.2.3' } })
+    })
+
+    it('is a no-op when json mode is disabled', () => {
+      jsonOutput.enabled = false
+      const writes: string[] = []
+
+      emit({ structuredContent: { a: 1 } }, (text) => {
+        writes.push(text)
+      })
+
+      expect(writes).toHaveLength(0)
+    })
+
+    it('writes nothing when structuredContent is undefined or null, even if enabled', () => {
+      jsonOutput.enabled = true
+      const writes: string[] = []
+
+      emit(undefined, (text) => {
+        writes.push(text)
+      })
+      emit({}, (text) => {
+        writes.push(text)
+      })
+      emit({ structuredContent: null }, (text) => {
+        writes.push(text)
+      })
+
+      expect(writes).toHaveLength(0)
+    })
+  })
+
+  // Regression: `--json` must activate on grouped/nested subcommands, not just
+  // flat top-level commands. Commander binds a post-subcommand `--json` to the
+  // parent group, so the preAction hook must read `optsWithGlobals()`, not
+  // `opts()`. This drives the real Commander parse path end-to-end.
+  describe('grouped subcommand --json (regression)', () => {
+    const buildProgram = (writes: string[]): Command => {
+      const program = new Command()
+      const group = program.command('group')
+
+      group.command('leaf').action(() => {
+        emit({ structuredContent: { ok: true } }, (text) => {
+          writes.push(text)
+        })
+      })
+
+      program.commands.forEach(addJsonOption)
+      program.hook('preAction', (_thisCommand, actionCommand) => {
+        jsonOutput.enabled = Boolean(actionCommand.optsWithGlobals().json)
+      })
+
+      return program
+    }
+
+    it('emits JSON for `group leaf --json` (post-subcommand flag on a nested command)', async () => {
+      const writes: string[] = []
+
+      await buildProgram(writes).parseAsync(['node', 'cli', 'group', 'leaf', '--json'])
+
+      expect(writes).toHaveLength(1)
+      const [payload = ''] = writes
+
+      expect(JSON.parse(payload)).toEqual({ ok: true })
+    })
+
+    it('emits nothing for `group leaf` without --json', async () => {
+      const writes: string[] = []
+
+      await buildProgram(writes).parseAsync(['node', 'cli', 'group', 'leaf'])
+
+      expect(writes).toHaveLength(0)
+    })
+  })
+
+  describe('addJsonOption', () => {
+    it('registers --json on a command', () => {
+      const cmd = new Command('demo')
+
+      addJsonOption(cmd)
+
+      expect(
+        cmd.options.some((option) => {
+          return option.long === '--json'
+        }),
+      ).toBe(true)
+    })
+
+    it('is idempotent (does not double-register)', () => {
+      const cmd = new Command('demo')
+
+      addJsonOption(cmd)
+      addJsonOption(cmd)
+
+      const jsonOptions = cmd.options.filter((option) => {
+        return option.long === '--json'
+      })
+
+      expect(jsonOptions).toHaveLength(1)
+    })
+
+    it('registers --json on nested subcommands too', () => {
+      const parent = new Command('parent')
+      const child = parent.command('child')
+
+      addJsonOption(parent)
+
+      expect(
+        child.options.some((option) => {
+          return option.long === '--json'
+        }),
+      ).toBe(true)
+    })
+  })
+})

package/src/lib/json-output/index.ts

@@ -0,0 +1 @@
+export { addJsonOption, emit, jsonOutput } from './json-output'

package/src/lib/json-output/json-output.ts

@@ -0,0 +1,47 @@
+import type { Command } from 'commander'
+import process from 'node:process'
+
+/**
+ * `--json` output mode for the CLI. This is a presentation concern only: every
+ * command handler already returns a `structuredContent` payload (the same one
+ * the MCP surface consumes). Human/log output goes to stderr (see lib/logger),
+ * so writing the structured payload to stdout never collides with it.
+ */
+
+export interface CommandResult {
+  structuredContent?: unknown
+}
+
+/** Mutable holder (object so `prefer-const` holds while the flag toggles per run). */
+export const jsonOutput = { enabled: false }
+
+/**
+ * In `--json` mode, write a command result's `structuredContent` to stdout as
+ * pretty JSON and return the result unchanged. Outside `--json` mode it is a
+ * no-op pass-through. The writer is injectable for testing.
+ */
+export const emit = <T extends CommandResult | void>(
+  result: T,
+  write: (text: string) => void = (text) => {
+    process.stdout.write(text)
+  },
+): T => {
+  if (jsonOutput.enabled && result && result.structuredContent != null) {
+    write(`${JSON.stringify(result.structuredContent, null, 2)}\n`)
+  }
+
+  return result
+}
+
+/** Register `--json` on a command and every nested subcommand (idempotent). */
+export const addJsonOption = (cmd: Command): void => {
+  const alreadyHasJson = cmd.options.some((option) => {
+    return option.long === '--json'
+  })
+
+  if (!alreadyHasJson) {
+    cmd.option('--json', 'Output the structured result as JSON on stdout (human logs stay on stderr)')
+  }
+
+  cmd.commands.forEach(addJsonOption)
+}

package/src/lib/managed-block/managed-block.ts

@@ -4,8 +4,8 @@
  *
  * This is the same mechanism `infra-kit init` already uses for the `~/.zshrc`
  * shell block (`# -- infra-kit:begin -- … # -- infra-kit:end --`), lifted here so
- * it can be reused for the repo agent-instruction files (`AGENTS.md`,
- * `CLAUDE.md` import region, `.cursor/rules`). It mirrors the design of OMC's
+ * it can be reused for the repo agent-instruction guidance block in `CLAUDE.md`.
+ * It mirrors the design of OMC's
  * `<!-- OMC:START --> … <!-- OMC:END -->` CLAUDE.md installer.
  */
 
@@ -64,7 +64,7 @@ export const removeManagedBlock = (content: string, startMarker: string, endMark
 
   if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return null
 
-  // eslint-disable-next-line sonarjs/slow-regex
+  // eslint-disable-next-line sonarjs/super-linear-regex
   const before = content.slice(0, startIdx).replace(/\n+$/, '')
   const after = content.slice(endIdx + endMarker.length).replace(/^\n+/, '')
 
@@ -138,7 +138,7 @@ export const upsertManagedBlock = ({
   // append-end, or replace-in-place with no existing block: drop any stale block
   // then append the fresh one at end-of-file.
   const stripped = present ? (removeManagedBlock(content, startMarker, endMarker) ?? content) : content
-  // eslint-disable-next-line sonarjs/slow-regex
+  // eslint-disable-next-line sonarjs/super-linear-regex
   const base = stripped.replace(/\n+$/, '')
 
   return base.length > 0 ? `${base}\n${block}\n` : `${block}\n`

package/src/lib/package-config/package-config.ts

@@ -31,9 +31,7 @@ export interface InfraKitPackageConfig {
  * `defineConfig` input: a plain object, a sync factory, or an async factory.
  */
 export type InfraKitPackageConfigInput =
-  | InfraKitPackageConfig
-  | (() => InfraKitPackageConfig)
-  | (() => Promise<InfraKitPackageConfig>)
+  InfraKitPackageConfig | (() => InfraKitPackageConfig) | (() => Promise<InfraKitPackageConfig>)
 
 /**
  * Identity helper that gives `infra-kit.config.js` authors full type inference

package/src/lib/path-display/index.ts

@@ -0,0 +1 @@
+export { fileExists, tildify } from './path-display'

package/src/lib/path-display/path-display.ts

@@ -0,0 +1,42 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+
+/**
+ * Shared path-display helpers for CLI output. Extracted from `commands/config`
+ * and `commands/init/migrate-config` (which each had private copies) so config
+ * surfaces print paths consistently. Keep this dependency-light (node builtins
+ * only) — it is imported by several commands.
+ */
+
+/**
+ * Resolve whether a file is reachable, suppressing ENOENT (and any access error)
+ * into a boolean. Used to render `[✓]`/`[ ]` existence markers.
+ *
+ * @example
+ * await fileExists('/etc/hosts') // => true
+ * await fileExists('/nope.txt')  // => false
+ */
+export const fileExists = async (filePath: string): Promise<boolean> => {
+  try {
+    await fs.access(filePath)
+
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Replace the user's home prefix with `~` so logged paths stay short and portable
+ * across machines. Leaves non-home paths untouched.
+ *
+ * @example
+ * // os.homedir() === '/Users/arthur'
+ * tildify('/Users/arthur/.infra-kit/infra-kit.json') // => '~/.infra-kit/infra-kit.json'
+ * tildify('/etc/hosts')                              // => '/etc/hosts'
+ */
+export const tildify = (filePath: string): string => {
+  const home = os.homedir()
+
+  return filePath.startsWith(home) ? `~${filePath.slice(home.length)}` : filePath
+}

package/src/lib/render/__tests__/render.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+
+import { formatAlignedRows } from '../render'
+
+describe('formatAlignedRows', () => {
+  it('pads every left cell to the widest left cell and joins with the default 2-space gap', () => {
+    expect(
+      formatAlignedRows([
+        ['a', 'x'],
+        ['bbb', 'y'],
+      ]),
+    ).toEqual(['a    x', 'bbb  y'])
+  })
+
+  it('honours a custom gap', () => {
+    expect(
+      formatAlignedRows(
+        [
+          ['a', 'x'],
+          ['bb', 'y'],
+        ],
+        ' | ',
+      ),
+    ).toEqual(['a  | x', 'bb | y'])
+  })
+
+  it('reproduces the menu label format (name padded + 2 spaces + description)', () => {
+    const rows: ReadonlyArray<readonly [string, string]> = [
+      ['merge-dev', 'Merge dev branch into every release branch'],
+      ['release-list', 'List all release branches'],
+    ]
+
+    const width = Math.max(
+      ...rows.map(([left]) => {
+        return left.length
+      }),
+    )
+    const expected = rows.map(([left, right]) => {
+      return `${left.padEnd(width)}  ${right}`
+    })
+
+    expect(formatAlignedRows(rows)).toEqual(expected)
+  })
+
+  it('returns an empty array for no rows', () => {
+    expect(formatAlignedRows([])).toEqual([])
+  })
+})

package/src/lib/render/index.ts

@@ -0,0 +1 @@
+export { formatAlignedRows } from './render'

package/src/lib/render/render.ts

@@ -0,0 +1,24 @@
+/**
+ * Small shared rendering helpers for aligned terminal output. These replace
+ * the ad-hoc "compute the max width, then padEnd each row" pattern that the
+ * interactive menu (and similar list views) hand-rolled. Pure string helpers —
+ * no I/O, no color — so they are trivially testable and reusable.
+ */
+
+/**
+ * Align a list of two-column rows: pad every left cell to the widest left cell,
+ * then join the two cells with `gap`. Returns one rendered line per row.
+ *
+ * @example
+ * formatAlignedRows([['a', 'x'], ['bbb', 'y']])
+ * // ['a    x', 'bbb  y']   (left padded to width 3, default 2-space gap)
+ */
+export const formatAlignedRows = (rows: ReadonlyArray<readonly [string, string]>, gap = '  '): string[] => {
+  const width = rows.reduce((max, [left]) => {
+    return Math.max(max, left.length)
+  }, 0)
+
+  return rows.map(([left, right]) => {
+    return `${left.padEnd(width)}${gap}${right}`
+  })
+}