infra-kit 0.1.128 → 0.1.129

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

@@ -1,327 +0,0 @@
-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('decideAutoLoad — force (shell-startup warm refresh)', () => {
-  // Regression for the warm-cache refresh defect: after a WARM source the shell has
-  // exported the auto-load marker + same config, which the backgrounded refresh
-  // inherits. Without `force` the refresh self-skips and stale warm secrets persist.
-  it('forces a fresh load past the same-config no-op skip', () => {
-    expect(decideAutoLoad(buildInput({ env: loadedEnv() }))).toBe('skip')
-    expect(decideAutoLoad(buildInput({ env: loadedEnv(), force: true }))).toBe('load')
-  })
-
-  it('force does NOT override the clear guard', () => {
-    expect(decideAutoLoad(buildInput({ env: loadedEnv({ cleared: '1' }), force: true }))).toBe('skip')
-  })
-
-  it('force does NOT override the manual-load guard', () => {
-    expect(
-      decideAutoLoad(
-        buildInput({
-          env: { session: 'sess-1', currentConfig: 'prod', currentProject: 'my-project', autoLoadedMarker: undefined },
-          force: true,
-        }),
-      ),
-    ).toBe('skip')
-  })
-})
-
-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(expect.objectContaining({ config: 'dev', autoLoaded: true }))
-  })
-
-  it('returns null without throwing or warning when the write is aborted (beforeWrite returned false)', async () => {
-    vi.mocked(getInfraKitConfig).mockResolvedValue({
-      ...baseConfig,
-      envAutoLoad: { trigger: 'cli-invocation', config: 'dev' },
-    } as never)
-    vi.mocked(writeEnvLoadFile).mockResolvedValue(null)
-
-    const result = await runEnvAutoLoad({ expectedTrigger: 'cli-invocation' })
-
-    expect(result).toBeNull()
-    expect(logger.warn).not.toHaveBeenCalled()
-    expect(logger.debug).not.toHaveBeenCalled()
-  })
-
-  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

@@ -1,373 +0,0 @@
-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 de-duping the MISCONFIG warning (bad envAutoLoad.config). */
-const WARN_MISCONFIG_SENTINEL_FILE = 'autoload-warn-misconfig.flag'
-/** Per-session flag de-duping the transient-FAILURE warning (Doppler down/unauth). */
-const WARN_FAIL_SENTINEL_FILE = 'autoload-warn-fail.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.`,
-        WARN_MISCONFIG_SENTINEL_FILE,
-      )
-    }
-
-    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
-  /**
-   * Bypass ONLY the "already auto-loaded, same config+project" no-op skip, forcing
-   * a fresh Doppler fetch. The shell-startup refresh sets this: after a WARM source
-   * the shell has already exported INFRA_KIT_ENV_AUTOLOADED + the same config, which
-   * the child process inherits — without `force` the refresh would self-skip and the
-   * warm (possibly rotated) secrets would never be replaced this session. Does NOT
-   * relax the clear/manual-load guards.
-   */
-  force?: boolean
-}
-
-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, force } = 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 — normally a no-op,
-  // but `force` (the shell-startup warm refresh) must re-fetch: the shell just warm
-  // -sourced these same markers, so skipping here would strand stale secrets.
-  if (!force && env.autoLoadedMarker && env.currentConfig === targetConfig && env.currentProject === targetProject) {
-    return 'skip'
-  }
-
-  return 'load'
-}
-
-export interface RunEnvAutoLoadArgs {
-  expectedTrigger: AutoLoadTrigger
-  /**
-   * Canonical (realpath'd) project dir, forwarded to `writeEnvLoadFile` to enable
-   * the project-scoped WARM cache. Only the shell-startup spawn passes it (via
-   * `--project-dir`); the cli-invocation trigger omits it, so warm is a
-   * shell-startup-only optimization.
-   */
-  projectDir?: string
-  /**
-   * Force a fresh fetch past the "already auto-loaded, same config" no-op skip. The
-   * shell-startup refresh sets this so a preceding WARM source (which exports the
-   * same markers the child inherits) is always replaced by fresh secrets. See
-   * {@link decideAutoLoad}. The cli-invocation trigger leaves it false.
-   */
-  force?: boolean
-}
-
-/**
- * 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,
-  projectDir,
-  force,
-}: 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(),
-      force,
-    })
-
-    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 preWriteMtime = readLoadFileMtime()
-    const result = await writeEnvLoadFile({
-      config: resolved.config,
-      autoLoaded: true,
-      projectDir,
-      // Re-check after the slow Doppler download: abort if a clear or a manual load
-      // landed meanwhile, so a backgrounded auto-load never clobbers a deliberate action.
-      beforeWrite: () => {
-        return !isClearedOnDisk() && !manualLoadLandedSince(preWriteMtime)
-      },
-    })
-
-    if (!result) return null
-
-    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)`, WARN_FAIL_SENTINEL_FILE)
-    } 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],
-  }
-}
-
-/** mtime of the on-disk env-load.sh, or null if absent/unreadable. */
-const readLoadFileMtime = (): number | null => {
-  try {
-    return fs.statSync(path.join(getSessionCacheDir(), ENV_LOAD_FILE)).mtimeMs
-  } catch {
-    return null
-  }
-}
-
-/**
- * True when a MANUAL env-load landed on disk after `sinceMtime` (the file now
- * exists, is newer, and carries the manual-load `unset INFRA_KIT_ENV_AUTOLOADED`
- * line). Used to abort an in-flight auto-load so it never clobbers a deliberate load.
- */
-const manualLoadLandedSince = (sinceMtime: number | null): boolean => {
-  try {
-    const p = path.join(getSessionCacheDir(), ENV_LOAD_FILE)
-
-    if (!fs.existsSync(p)) return false
-
-    const mtime = fs.statSync(p).mtimeMs
-
-    if (sinceMtime !== null && mtime <= sinceMtime) return false
-
-    // Anchor to a whole line so the marker can't match inside a single-quoted
-    // secret value that happens to contain this literal text.
-    const manualMarker = new RegExp(`^unset ${INFRA_KIT_ENV_AUTOLOADED_VAR}$`, 'm')
-
-    return manualMarker.test(fs.readFileSync(p, 'utf-8'))
-  } catch {
-    return false
-  }
-}
-
-/**
- * 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, sentinelFile: string): void => {
-  try {
-    const dir = getSessionCacheDir()
-    const flagPath = path.join(dir, sentinelFile)
-
-    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)
-}