infra-kit 0.1.113 → 0.1.115

package/src/lib/constants/index.ts

@@ -5,6 +5,8 @@ export {
   ENV_VAR_LINE_PATTERN,
   getCacheRoot,
   getSessionCacheDir,
+  INFRA_KIT_ENV_AUTOLOADED_VAR,
+  INFRA_KIT_ENV_CLEARED_VAR,
   INFRA_KIT_ENV_CONFIG_VAR,
   INFRA_KIT_ENV_LOADED_AT_VAR,
   INFRA_KIT_ENV_PROJECT_VAR,

package/src/lib/env-autoload/__tests__/env-autoload.test.ts

@@ -0,0 +1,288 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { writeEnvLoadFile } from 'src/commands/env-load'
+import {
+  INFRA_KIT_ENV_AUTOLOADED_VAR,
+  INFRA_KIT_ENV_CLEARED_VAR,
+  INFRA_KIT_ENV_CONFIG_VAR,
+  INFRA_KIT_ENV_PROJECT_VAR,
+  INFRA_KIT_SESSION_VAR,
+} from 'src/lib/constants'
+import { getInfraKitConfig } from 'src/lib/infra-kit-config'
+import { logger } from 'src/lib/logger'
+
+import { decideAutoLoad, resolveEnvAutoLoad, runEnvAutoLoad } from '../env-autoload'
+import type { AutoLoadDecisionInput, AutoLoadEnvSnapshot } from '../env-autoload'
+
+vi.mock('src/lib/infra-kit-config', () => {
+  return { getInfraKitConfig: vi.fn() }
+})
+
+vi.mock('src/commands/env-load', () => {
+  return { writeEnvLoadFile: vi.fn() }
+})
+
+vi.mock('src/lib/logger', () => {
+  return { logger: { warn: vi.fn(), debug: vi.fn() } }
+})
+
+const baseConfig = {
+  environments: ['dev', 'prod'],
+  envManagement: { provider: 'doppler', config: { name: 'my-project' } },
+}
+
+const buildInput = (overrides: Partial<AutoLoadDecisionInput> = {}): AutoLoadDecisionInput => {
+  return {
+    trigger: 'cli-invocation',
+    expectedTrigger: 'cli-invocation',
+    targetConfig: 'dev',
+    targetProject: 'my-project',
+    env: { session: 'sess-1' },
+    ...overrides,
+  }
+}
+
+const loadedEnv = (overrides: Partial<AutoLoadEnvSnapshot> = {}): AutoLoadEnvSnapshot => {
+  return {
+    session: 'sess-1',
+    currentConfig: 'dev',
+    currentProject: 'my-project',
+    autoLoadedMarker: '1',
+    ...overrides,
+  }
+}
+
+describe('decideAutoLoad — trigger gating', () => {
+  it('loads when the configured trigger matches this callsite', () => {
+    expect(decideAutoLoad(buildInput({ trigger: 'cli-invocation', expectedTrigger: 'cli-invocation' }))).toBe('load')
+    expect(decideAutoLoad(buildInput({ trigger: 'shell-startup', expectedTrigger: 'shell-startup' }))).toBe('load')
+  })
+
+  it('skips when the configured trigger is for the other callsite', () => {
+    expect(decideAutoLoad(buildInput({ trigger: 'shell-startup', expectedTrigger: 'cli-invocation' }))).toBe('skip')
+    expect(decideAutoLoad(buildInput({ trigger: 'cli-invocation', expectedTrigger: 'shell-startup' }))).toBe('skip')
+  })
+})
+
+describe('decideAutoLoad — session + clear guards', () => {
+  it('skips when no session is set (cache dir is session-scoped)', () => {
+    expect(decideAutoLoad(buildInput({ env: { session: undefined } }))).toBe('skip')
+  })
+
+  // Regression M2: a deliberate `env-clear` must keep cli-invocation auto-load
+  // from immediately re-loading in the same shell.
+  it('skips when the clear sentinel is set (M2: stay cleared)', () => {
+    expect(decideAutoLoad(buildInput({ env: { session: 'sess-1', cleared: '1' } }))).toBe('skip')
+  })
+})
+
+describe('decideAutoLoad — manual-load protection (C1)', () => {
+  // Regression C1: env loaded WITHOUT our auto marker means a manual `env-load`;
+  // auto-load must never overwrite it, even when the target config differs.
+  it('skips a manually-loaded env even when target config differs', () => {
+    expect(
+      decideAutoLoad(
+        buildInput({
+          targetConfig: 'dev',
+          env: { session: 'sess-1', currentConfig: 'prod', currentProject: 'my-project', autoLoadedMarker: undefined },
+        }),
+      ),
+    ).toBe('skip')
+  })
+})
+
+describe('decideAutoLoad — project-aware freshness', () => {
+  it('skips when our auto-load already matches config AND project', () => {
+    expect(decideAutoLoad(buildInput({ env: loadedEnv() }))).toBe('skip')
+  })
+
+  it('loads when the auto-loaded config differs from target', () => {
+    expect(decideAutoLoad(buildInput({ targetConfig: 'prod', env: loadedEnv({ currentConfig: 'dev' }) }))).toBe('load')
+  })
+
+  it('loads when the project differs even though the config name matches (worktree leak guard)', () => {
+    expect(
+      decideAutoLoad(buildInput({ targetProject: 'other-project', env: loadedEnv({ currentProject: 'my-project' }) })),
+    ).toBe('load')
+  })
+
+  it('loads into a clean shell (nothing currently loaded)', () => {
+    expect(decideAutoLoad(buildInput({ env: { session: 'sess-1' } }))).toBe('load')
+  })
+})
+
+describe('resolveEnvAutoLoad', () => {
+  const ORIGINAL_ENV = { ...process.env }
+  let cacheRoot: string
+
+  beforeEach(() => {
+    vi.mocked(getInfraKitConfig).mockReset()
+    vi.mocked(logger.warn).mockClear()
+    // Isolate the per-session warn-dedup flag in a fresh cache dir so the warning
+    // is not suppressed by a flag left over from the dev's real session.
+    cacheRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ik-autoload-resolve-'))
+    process.env.XDG_CACHE_HOME = cacheRoot
+    process.env[INFRA_KIT_SESSION_VAR] = 'sess-resolve'
+  })
+
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV }
+    fs.rmSync(cacheRoot, { recursive: true, force: true })
+  })
+
+  it('returns null when not inside a project (getInfraKitConfig throws)', async () => {
+    vi.mocked(getInfraKitConfig).mockRejectedValue(new Error('infra-kit.json not found'))
+
+    expect(await resolveEnvAutoLoad()).toBeNull()
+  })
+
+  it('returns null when envAutoLoad is absent (feature off)', async () => {
+    vi.mocked(getInfraKitConfig).mockResolvedValue(baseConfig as never)
+
+    expect(await resolveEnvAutoLoad()).toBeNull()
+  })
+
+  it('resolves trigger + config + project from one config read', async () => {
+    vi.mocked(getInfraKitConfig).mockResolvedValue({
+      ...baseConfig,
+      envAutoLoad: { trigger: 'cli-invocation', config: 'dev' },
+    } as never)
+
+    expect(await resolveEnvAutoLoad()).toEqual({ trigger: 'cli-invocation', config: 'dev', project: 'my-project' })
+  })
+
+  it('warns and disables when config is not one of environments', async () => {
+    vi.mocked(getInfraKitConfig).mockResolvedValue({
+      ...baseConfig,
+      envAutoLoad: { trigger: 'shell-startup', config: 'nope' },
+    } as never)
+
+    expect(await resolveEnvAutoLoad()).toBeNull()
+    expect(logger.warn).toHaveBeenCalledOnce()
+    expect(vi.mocked(logger.warn).mock.calls[0]![0]).toContain('nope')
+  })
+
+  // Gap 1 regression: the shell-startup callsite discards stderr, so it must NOT
+  // warn (and must not write the dedup flag that would poison the interactive channel).
+  it('does NOT warn on bad config when canWarn is false (shell-startup channel)', async () => {
+    vi.mocked(getInfraKitConfig).mockResolvedValue({
+      ...baseConfig,
+      envAutoLoad: { trigger: 'shell-startup', config: 'nope' },
+    } as never)
+
+    expect(await resolveEnvAutoLoad(false)).toBeNull()
+    expect(logger.warn).not.toHaveBeenCalled()
+  })
+})
+
+describe('runEnvAutoLoad', () => {
+  const ORIGINAL_ENV = { ...process.env }
+  let cacheRoot: string
+
+  beforeEach(() => {
+    vi.mocked(getInfraKitConfig).mockReset()
+    vi.mocked(writeEnvLoadFile).mockReset()
+    cacheRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ik-autoload-'))
+    process.env.XDG_CACHE_HOME = cacheRoot
+    process.env[INFRA_KIT_SESSION_VAR] = 'sess-run'
+    delete process.env[INFRA_KIT_ENV_CONFIG_VAR]
+    delete process.env[INFRA_KIT_ENV_PROJECT_VAR]
+    delete process.env[INFRA_KIT_ENV_AUTOLOADED_VAR]
+    delete process.env[INFRA_KIT_ENV_CLEARED_VAR]
+  })
+
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV }
+    fs.rmSync(cacheRoot, { recursive: true, force: true })
+  })
+
+  it('writes an auto-loaded file and returns its path on load', async () => {
+    vi.mocked(getInfraKitConfig).mockResolvedValue({
+      ...baseConfig,
+      envAutoLoad: { trigger: 'shell-startup', config: 'dev' },
+    } as never)
+    vi.mocked(writeEnvLoadFile).mockResolvedValue({
+      filePath: '/cache/env-load.sh',
+      variableCount: 3,
+      project: 'my-project',
+      config: 'dev',
+    })
+
+    const result = await runEnvAutoLoad({ expectedTrigger: 'shell-startup' })
+
+    expect(result).toBe('/cache/env-load.sh')
+    expect(writeEnvLoadFile).toHaveBeenCalledWith({ config: 'dev', autoLoaded: true })
+  })
+
+  it('returns null without fetching when the configured trigger is for the other callsite', async () => {
+    vi.mocked(getInfraKitConfig).mockResolvedValue({
+      ...baseConfig,
+      envAutoLoad: { trigger: 'shell-startup', config: 'dev' },
+    } as never)
+
+    const result = await runEnvAutoLoad({ expectedTrigger: 'cli-invocation' })
+
+    expect(result).toBeNull()
+    expect(writeEnvLoadFile).not.toHaveBeenCalled()
+  })
+
+  it('returns null and never fetches when env is already fresh', async () => {
+    vi.mocked(getInfraKitConfig).mockResolvedValue({
+      ...baseConfig,
+      envAutoLoad: { trigger: 'cli-invocation', config: 'dev' },
+    } as never)
+    process.env[INFRA_KIT_ENV_CONFIG_VAR] = 'dev'
+    process.env[INFRA_KIT_ENV_PROJECT_VAR] = 'my-project'
+    process.env[INFRA_KIT_ENV_AUTOLOADED_VAR] = '1'
+
+    const result = await runEnvAutoLoad({ expectedTrigger: 'cli-invocation' })
+
+    expect(result).toBeNull()
+    expect(writeEnvLoadFile).not.toHaveBeenCalled()
+  })
+
+  it('swallows transient failures to a debug log (shell-startup) and returns null', async () => {
+    vi.mocked(getInfraKitConfig).mockResolvedValue({
+      ...baseConfig,
+      envAutoLoad: { trigger: 'shell-startup', config: 'dev' },
+    } as never)
+    vi.mocked(writeEnvLoadFile).mockRejectedValue(new Error('doppler not authenticated'))
+
+    const result = await runEnvAutoLoad({ expectedTrigger: 'shell-startup' })
+
+    expect(result).toBeNull()
+    expect(logger.debug).toHaveBeenCalled()
+    expect(logger.warn).not.toHaveBeenCalled()
+  })
+
+  it('surfaces a transient failure once on the cli-invocation channel', async () => {
+    vi.mocked(getInfraKitConfig).mockResolvedValue({
+      ...baseConfig,
+      envAutoLoad: { trigger: 'cli-invocation', config: 'dev' },
+    } as never)
+    vi.mocked(writeEnvLoadFile).mockRejectedValue(new Error('doppler not authenticated'))
+
+    const result = await runEnvAutoLoad({ expectedTrigger: 'cli-invocation' })
+
+    expect(result).toBeNull()
+    expect(logger.warn).toHaveBeenCalledOnce()
+    expect(vi.mocked(logger.warn).mock.calls[0]![0]).toContain('failed')
+  })
+
+  it('backs off: after a failure the next run skips Doppler (writeEnvLoadFile called once)', async () => {
+    vi.mocked(getInfraKitConfig).mockResolvedValue({
+      ...baseConfig,
+      envAutoLoad: { trigger: 'cli-invocation', config: 'dev' },
+    } as never)
+    vi.mocked(writeEnvLoadFile).mockRejectedValue(new Error('network down'))
+
+    expect(await runEnvAutoLoad({ expectedTrigger: 'cli-invocation' })).toBeNull()
+    expect(await runEnvAutoLoad({ expectedTrigger: 'cli-invocation' })).toBeNull()
+
+    expect(writeEnvLoadFile).toHaveBeenCalledOnce()
+  })
+})

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

@@ -0,0 +1,294 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+import { writeEnvLoadFile } from 'src/commands/env-load'
+import {
+  ENV_CLEAR_FILE,
+  ENV_LOAD_FILE,
+  INFRA_KIT_ENV_AUTOLOADED_VAR,
+  INFRA_KIT_ENV_CLEARED_VAR,
+  INFRA_KIT_ENV_CONFIG_VAR,
+  INFRA_KIT_ENV_PROJECT_VAR,
+  INFRA_KIT_SESSION_VAR,
+  getSessionCacheDir,
+} from 'src/lib/constants'
+import type { EnvAutoLoadConfig } from 'src/lib/infra-kit-config'
+import { getInfraKitConfig } from 'src/lib/infra-kit-config'
+import { logger } from 'src/lib/logger'
+
+/** Which moment a concrete callsite represents. Matches the config `trigger`. */
+export type AutoLoadTrigger = EnvAutoLoadConfig['trigger']
+
+/** Per-session flag file that de-dups the auto-load warning (misconfig or failure). */
+const WARN_SENTINEL_FILE = 'autoload-warn.flag'
+
+/** Per-session marker recording the last auto-load failure (mtime = when). */
+const FAIL_SENTINEL_FILE = 'autoload-fail.flag'
+
+/**
+ * After a failed auto-load, suppress retries for this long so a down/unauthenticated
+ * Doppler isn't re-probed on every cli-invocation. A new shell starts a fresh
+ * session cache dir, so this only throttles within one session.
+ */
+const FAIL_BACKOFF_MS = 30_000
+
+/** Resolved auto-load inputs: the chosen trigger + the env config and Doppler project to load. */
+export interface ResolvedEnvAutoLoad {
+  trigger: AutoLoadTrigger
+  config: string
+  project: string
+}
+
+/**
+ * Read the resolved + validated env auto-load inputs, or `null` when auto-load
+ * should not run. Returns `null` (never throws) when:
+ *  - we're not inside an infra-kit project (getInfraKitConfig throws), or config is unreadable;
+ *  - `envAutoLoad` is absent (feature off);
+ *  - `envAutoLoad.config` is not one of `environments` — warns once per session, then disables.
+ *
+ * Validation lives here (not in the schema) so a typo only disables this optional
+ * feature instead of throwing inside the merged-config parse and breaking every command.
+ * Resolves the Doppler project from the SAME config read (no second getInfraKitConfig),
+ * so the skip path stays cheap.
+ *
+ * `canWarn` gates the misconfig warning: the shell-startup callsite runs backgrounded
+ * with stderr discarded, so warning there is invisible AND would write the dedup flag,
+ * poisoning the only channel (cli-invocation / interactive) that can actually surface
+ * it. So shell-startup passes `false`; interactive callsites pass `true`.
+ */
+export const resolveEnvAutoLoad = async (canWarn = true): Promise<ResolvedEnvAutoLoad | null> => {
+  let config
+
+  try {
+    config = await getInfraKitConfig()
+  } catch {
+    return null
+  }
+
+  const autoLoad = config.envAutoLoad
+
+  if (!autoLoad) return null
+
+  if (!config.environments.includes(autoLoad.config)) {
+    if (canWarn) {
+      warnOnce(
+        `infra-kit: envAutoLoad.config "${autoLoad.config}" is not one of environments [${config.environments.join(
+          ', ',
+        )}] — env auto-load disabled.`,
+      )
+    }
+
+    return null
+  }
+
+  return {
+    trigger: autoLoad.trigger,
+    config: autoLoad.config,
+    project: config.envManagement.config.name,
+  }
+}
+
+/** The env-var snapshot the freshness/suppression guards read. */
+export interface AutoLoadEnvSnapshot {
+  session?: string
+  cleared?: string
+  currentConfig?: string
+  currentProject?: string
+  autoLoadedMarker?: string
+}
+
+export interface AutoLoadDecisionInput {
+  /** The configured trigger. */
+  trigger: AutoLoadTrigger
+  /** Which trigger this callsite represents. */
+  expectedTrigger: AutoLoadTrigger
+  targetConfig: string
+  targetProject: string
+  env: AutoLoadEnvSnapshot
+}
+
+export type AutoLoadDecision = 'load' | 'skip'
+
+/**
+ * Pure decision: should this callsite (auto-)load env right now? Encodes the full
+ * guard matrix so it is exhaustively unit-testable without Doppler or a shell:
+ *  - the configured trigger must match this callsite;
+ *  - a session must exist (the cache dir is session-scoped);
+ *  - an explicit clear suppresses auto-load (M2);
+ *  - a MANUAL load (config set, no auto marker) is never clobbered (C1);
+ *  - an auto-load already fresh for the same config AND project is a no-op
+ *    (project-aware so two same-named configs across different-repo worktrees
+ *    sharing one session don't leak each other's secrets).
+ */
+export const decideAutoLoad = (input: AutoLoadDecisionInput): AutoLoadDecision => {
+  const { trigger, expectedTrigger, targetConfig, targetProject, env } = input
+
+  if (trigger !== expectedTrigger) return 'skip'
+
+  if (!env.session) return 'skip'
+
+  if (env.cleared) return 'skip'
+
+  // Manual load present (a config is loaded but it wasn't auto-loaded) — leave it.
+  if (env.currentConfig && !env.autoLoadedMarker) return 'skip'
+
+  // Our own auto-load already matches the target config+project — nothing to do.
+  if (env.autoLoadedMarker && env.currentConfig === targetConfig && env.currentProject === targetProject) {
+    return 'skip'
+  }
+
+  return 'load'
+}
+
+export interface RunEnvAutoLoadArgs {
+  expectedTrigger: AutoLoadTrigger
+}
+
+/**
+ * Resolve config, evaluate the guards, and (if it should) produce env-load.sh with
+ * the auto-load marker. Returns the written file path, or `null` when auto-load was
+ * skipped or failed. NEVER throws. Transient failures (Doppler offline / not
+ * authenticated / network) record a backoff marker so they aren't re-probed on every
+ * command, and are surfaced once per session on the interactive (cli-invocation)
+ * channel. No producer-side lock — a rare cold-shell double-fetch is tolerated (the
+ * second write is atomic and idempotent).
+ */
+export const runEnvAutoLoad = async ({ expectedTrigger }: RunEnvAutoLoadArgs): Promise<string | null> => {
+  // Only the cli-invocation / interactive callsite reaches a TTY; the shell-startup
+  // spawn discards stderr, so warning there is invisible and would poison the dedup.
+  const canWarn = expectedTrigger === 'cli-invocation'
+
+  try {
+    const resolved = await resolveEnvAutoLoad(canWarn)
+
+    if (!resolved) return null
+
+    const decision = decideAutoLoad({
+      trigger: resolved.trigger,
+      expectedTrigger,
+      targetConfig: resolved.config,
+      targetProject: resolved.project,
+      env: readAutoLoadEnvSnapshot(),
+    })
+
+    if (decision === 'skip') return null
+
+    // Disk-level clear signal: a clear that hasn't yet been sourced into this
+    // process's env still suppresses auto-load (clear file newer than load file).
+    if (isClearedOnDisk()) return null
+
+    // Back off after a recent failure so a down/unauthenticated Doppler isn't
+    // re-probed on every command in the same session.
+    if (recentlyFailed()) return null
+
+    const result = await writeEnvLoadFile({ config: resolved.config, autoLoaded: true })
+
+    clearFailure()
+
+    return result.filePath
+  } catch (error) {
+    const reason = (error as Error).message
+
+    recordFailure()
+
+    // Surface the failure once per session on the interactive channel; stay silent
+    // (debug only) on the backgrounded shell-startup path.
+    if (canWarn) {
+      warnOnce(`infra-kit: env auto-load failed — ${reason} (will retry later)`)
+    } else {
+      logger.debug(`env auto-load skipped: ${reason}`)
+    }
+
+    return null
+  }
+}
+
+/** Snapshot the env vars the guards depend on. */
+const readAutoLoadEnvSnapshot = (): AutoLoadEnvSnapshot => {
+  return {
+    session: process.env[INFRA_KIT_SESSION_VAR],
+    cleared: process.env[INFRA_KIT_ENV_CLEARED_VAR],
+    currentConfig: process.env[INFRA_KIT_ENV_CONFIG_VAR],
+    currentProject: process.env[INFRA_KIT_ENV_PROJECT_VAR],
+    autoLoadedMarker: process.env[INFRA_KIT_ENV_AUTOLOADED_VAR],
+  }
+}
+
+/**
+ * True when a clear is pending on disk: an env-clear.sh exists and is at least as
+ * new as env-load.sh (or no load file remains). Belt-and-suspenders next to the
+ * INFRA_KIT_ENV_CLEARED env guard for the window before the shell sources the clear.
+ */
+const isClearedOnDisk = (): boolean => {
+  try {
+    const dir = getSessionCacheDir()
+    const clearPath = path.join(dir, ENV_CLEAR_FILE)
+
+    if (!fs.existsSync(clearPath)) return false
+
+    const loadPath = path.join(dir, ENV_LOAD_FILE)
+
+    if (!fs.existsSync(loadPath)) return true
+
+    return fs.statSync(clearPath).mtimeMs >= fs.statSync(loadPath).mtimeMs
+  } catch {
+    return false
+  }
+}
+
+/** True when an auto-load failed within the backoff window (suppress retries). */
+const recentlyFailed = (): boolean => {
+  try {
+    const flagPath = path.join(getSessionCacheDir(), FAIL_SENTINEL_FILE)
+
+    if (!fs.existsSync(flagPath)) return false
+
+    return Date.now() - fs.statSync(flagPath).mtimeMs < FAIL_BACKOFF_MS
+  } catch {
+    return false
+  }
+}
+
+/** Record an auto-load failure (refreshes the backoff window). */
+const recordFailure = (): void => {
+  try {
+    const dir = getSessionCacheDir()
+
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+    fs.writeFileSync(path.join(dir, FAIL_SENTINEL_FILE), '', { mode: 0o600 })
+  } catch {
+    // No session cache dir — nothing to back off against.
+  }
+}
+
+/** Clear the failure marker after a successful load. */
+const clearFailure = (): void => {
+  try {
+    fs.rmSync(path.join(getSessionCacheDir(), FAIL_SENTINEL_FILE), { force: true })
+  } catch {
+    // No session cache dir — nothing to clear.
+  }
+}
+
+/**
+ * Emit a warning at most once per shell session. Keyed on a flag file in the
+ * session cache dir so a misconfigured `envAutoLoad.config` (or a repeated failure)
+ * does not spam a warning on every cli-invocation. Falls back to a plain warn when
+ * no session cache dir is available.
+ */
+const warnOnce = (message: string): void => {
+  try {
+    const dir = getSessionCacheDir()
+    const flagPath = path.join(dir, WARN_SENTINEL_FILE)
+
+    if (fs.existsSync(flagPath)) return
+
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+    fs.writeFileSync(flagPath, '', { mode: 0o600 })
+  } catch {
+    // No session cache dir (e.g. INFRA_KIT_SESSION unset) — warn without de-dup.
+  }
+
+  logger.warn(message)
+}

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

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

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

@@ -15,7 +15,7 @@ export interface OperationErrorContext {
  * extractStderr({ stderr: 'fatal: ...' })     // 'fatal: ...'
  * extractStderr({ stderr: '' })               // undefined  (empty treated as missing)
  */
-const extractStderr = (cause: unknown): string | undefined => {
+export const extractStderr = (cause: unknown): string | undefined => {
   if (cause === null || typeof cause !== 'object') return undefined
   const stderr = (cause as { stderr?: unknown }).stderr
 

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

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest'
+
+import { infraKitConfigSchema, infraKitOverrideConfigSchema } from '../infra-kit-config'
+
+const baseConfig = {
+  environments: ['dev', 'prod'],
+  envManagement: { provider: 'doppler', config: { name: 'my-project' } },
+}
+
+describe('envAutoLoad schema', () => {
+  it('is optional — a config without it parses', () => {
+    const result = infraKitConfigSchema.safeParse(baseConfig)
+
+    expect(result.success).toBe(true)
+    expect(result.success && result.data.envAutoLoad).toBeUndefined()
+  })
+
+  it.each(['shell-startup', 'cli-invocation'] as const)('accepts trigger "%s"', (trigger) => {
+    const result = infraKitConfigSchema.safeParse({ ...baseConfig, envAutoLoad: { trigger, config: 'dev' } })
+
+    expect(result.success).toBe(true)
+    expect(result.success && result.data.envAutoLoad).toEqual({ trigger, config: 'dev' })
+  })
+
+  it('rejects an unknown trigger value (e.g. "both")', () => {
+    const result = infraKitConfigSchema.safeParse({ ...baseConfig, envAutoLoad: { trigger: 'both', config: 'dev' } })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects a missing trigger', () => {
+    const result = infraKitConfigSchema.safeParse({ ...baseConfig, envAutoLoad: { config: 'dev' } })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects an empty config name', () => {
+    const result = infraKitConfigSchema.safeParse({
+      ...baseConfig,
+      envAutoLoad: { trigger: 'shell-startup', config: '' },
+    })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects unknown keys (strict object)', () => {
+    const result = infraKitConfigSchema.safeParse({
+      ...baseConfig,
+      envAutoLoad: { trigger: 'shell-startup', config: 'dev', extra: true },
+    })
+
+    expect(result.success).toBe(false)
+  })
+
+  // Important: an env name not in `environments` must NOT fail the schema — it is
+  // validated (and disabled) at resolve time so a typo never bricks every command.
+  it('does NOT reject a config name absent from environments (resolve-time concern)', () => {
+    const result = infraKitConfigSchema.safeParse({
+      ...baseConfig,
+      envAutoLoad: { trigger: 'shell-startup', config: 'not-listed' },
+    })
+
+    expect(result.success).toBe(true)
+  })
+
+  it('is accepted as a partial override layer', () => {
+    const result = infraKitOverrideConfigSchema.safeParse({ envAutoLoad: { trigger: 'cli-invocation', config: 'dev' } })
+
+    expect(result.success).toBe(true)
+  })
+})