infra-kit 0.1.113 → 0.1.115

package/src/commands/doctor/doctor.ts

@@ -4,13 +4,9 @@ import path from 'node:path'
 import { z } from 'zod'
 import { $ } from 'zx'
 
-import {
-  AGENTS_IMPORT_END,
-  AGENTS_IMPORT_START,
-  AGENTS_MARKER_END,
-  AGENTS_MARKER_START,
-} from 'src/commands/init/agent-files'
+import { AGENTS_MARKER_END, AGENTS_MARKER_START } from 'src/commands/init/agent-files'
 import { MARKER_END, MARKER_START, buildShellBlock } from 'src/commands/init/init'
+import { getDopplerProject, listDopplerProjects } from 'src/integrations/doppler'
 import { getProjectRoot } from 'src/lib/git-utils/git-utils'
 import {
   getInfraKitConfig,
@@ -20,6 +16,7 @@ import {
 } from 'src/lib/infra-kit-config'
 import { logger } from 'src/lib/logger'
 import { hasManagedBlock } from 'src/lib/managed-block'
+import { tildify } from 'src/lib/path-display'
 import { defineMcpTool, textContent } from 'src/types'
 
 interface CheckResult {
@@ -89,7 +86,7 @@ const checkPnpmWorkspaceVirtualStore = async (): Promise<CheckResult> => {
     }
 
     const content = fs.readFileSync(yamlPath, 'utf-8')
-    // eslint-disable-next-line sonarjs/slow-regex
+    // eslint-disable-next-line sonarjs/super-linear-regex
     const enabled = /^\s*enableGlobalVirtualStore\s*:\s*true\s*$/m.test(content)
 
     if (!enabled) {
@@ -127,6 +124,44 @@ const checkInfraKitConfigValid = async (): Promise<CheckResult> => {
   }
 }
 
+/**
+ * Verify the Doppler project configured in infra-kit.json (`envManagement.config.name`)
+ * actually exists in the authenticated account — the proactive catch for the
+ * mismatch that otherwise only surfaces as a cryptic `env-load` failure. Skips
+ * (informational pass) when the config can't be read or the project list can't be
+ * fetched (auth/network), so a logged-out user isn't misdiagnosed as
+ * missing-project — the adjacent `doppler authenticated` check owns that failure.
+ */
+export const checkDopplerProjectExists = async (): Promise<CheckResult> => {
+  const name = 'doppler project exists'
+
+  let project: string
+
+  try {
+    project = await getDopplerProject()
+  } catch {
+    return { name, status: 'pass', message: 'Skipped — infra-kit config could not be read (see config check)' }
+  }
+
+  const projects = await listDopplerProjects()
+
+  if (projects === null) {
+    return { name, status: 'pass', message: 'Skipped — could not list Doppler projects (see doppler auth check)' }
+  }
+
+  if (projects.includes(project)) {
+    return { name, status: 'pass', message: `Doppler project "${project}" exists` }
+  }
+
+  return {
+    name,
+    status: 'fail',
+    message: `Doppler project "${project}" not found (set in infra-kit.json → envManagement.config.name). Available: ${
+      projects.length > 0 ? projects.join(', ') : 'none'
+    }`,
+  }
+}
+
 /**
  * Surface where this developer's user-scope override file would live and
  * whether it has been created. Always passes — informational only — so the
@@ -160,6 +195,54 @@ const checkUserOverridePath = async (): Promise<CheckResult> => {
   }
 }
 
+/**
+ * Surface a lingering legacy `~/.infra-kit/config.json` left behind after the
+ * user-global config was renamed to `infra-kit.json`. The on-`init` auto-rename
+ * is the migration path, but a user who edits the file and never re-runs `init`
+ * would silently have their overrides stop applying — this makes that visible.
+ *
+ * Branches on whether the canonical `infra-kit.json` already exists so the
+ * message is accurate: only the "no infra-kit.json yet" case means overrides are
+ * not being applied; when both exist the legacy file is merely stale.
+ * Informational pass (no warning) when the paths can't resolve — mirrors
+ * {@link checkIdeInstalled}: nothing to surface if there's no resolvable target.
+ *
+ * @example
+ * await checkLegacyUserGlobalConfig()
+ * // { name: 'legacy user-global config', status: 'fail', message: 'Legacy user-global config.json found …' }
+ */
+export const checkLegacyUserGlobalConfig = async (): Promise<CheckResult> => {
+  const name = 'legacy user-global config'
+
+  let paths: Awaited<ReturnType<typeof getInfraKitConfigPaths>>
+
+  try {
+    paths = await getInfraKitConfigPaths()
+  } catch {
+    return { name, status: 'pass', message: 'Skipped — infra-kit config paths could not be resolved' }
+  }
+
+  const legacyPath = path.join(path.dirname(paths.userGlobal), 'config.json')
+
+  if (!fs.existsSync(legacyPath)) {
+    return { name, status: 'pass', message: 'No legacy user-global config.json' }
+  }
+
+  if (!fs.existsSync(paths.userGlobal)) {
+    return {
+      name,
+      status: 'fail',
+      message: `Legacy user-global config.json found at ${tildify(legacyPath)} — run \`infra-kit init\` to migrate it (your overrides are not being applied).`,
+    }
+  }
+
+  return {
+    name,
+    status: 'fail',
+    message: `Stale legacy config.json found at ${tildify(legacyPath)} — ${tildify(paths.userGlobal)} is active; remove the old file.`,
+  }
+}
+
 interface IdeProbe {
   ok: boolean
   label: string
@@ -300,10 +383,11 @@ const checkRtkConfigured = async (): Promise<CheckResult> => {
 }
 
 /**
- * Check that the repo agent-instruction files managed by `infra-kit init` exist:
- * the `AGENTS.md` block, the `@AGENTS.md` import region in `CLAUDE.md`, and the
- * `.cursor/rules` block. Presence only. Repo-gated: returns no checks when run
- * outside an infra-kit repo so doctor never crashes there.
+ * Check that the repo agent-instruction guidance managed by `infra-kit init` exists:
+ * the guidance block in `CLAUDE.md`. Presence only. Repo-gated: returns no checks
+ * when run outside an infra-kit repo so doctor never crashes there. A repo that
+ * predates the AGENTS.md→CLAUDE.md migration will report this check as failing until
+ * `infra-kit init` is re-run.
  */
 export const checkAgentFiles = async (): Promise<CheckResult[]> => {
   let mainConfigPath: string
@@ -316,43 +400,17 @@ export const checkAgentFiles = async (): Promise<CheckResult[]> => {
 
   if (!fs.existsSync(mainConfigPath)) return []
 
-  const root = path.dirname(mainConfigPath)
-
-  const blockPresent = (relPath: string, start: string, end: string): boolean => {
-    const filePath = path.join(root, relPath)
-    const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : ''
-
-    return hasManagedBlock(content, start, end)
-  }
+  const claudePath = path.join(path.dirname(mainConfigPath), 'CLAUDE.md')
+  const content = fs.existsSync(claudePath) ? fs.readFileSync(claudePath, 'utf-8') : ''
+  const present = hasManagedBlock(content, AGENTS_MARKER_START, AGENTS_MARKER_END)
 
-  const entries = [
-    {
-      name: 'AGENTS.md block',
-      present: blockPresent('AGENTS.md', AGENTS_MARKER_START, AGENTS_MARKER_END),
-      okMessage: 'AGENTS.md block present',
-      missingMessage: 'infra-kit block missing from AGENTS.md. Run: infra-kit init',
-    },
+  return [
     {
-      name: 'CLAUDE.md import',
-      present: blockPresent('CLAUDE.md', AGENTS_IMPORT_START, AGENTS_IMPORT_END),
-      okMessage: 'CLAUDE.md imports @AGENTS.md',
-      missingMessage: '@AGENTS.md import block missing from CLAUDE.md. Run: infra-kit init',
-    },
-    {
-      name: '.cursor/rules block',
-      present: blockPresent(path.join('.cursor', 'rules', 'infra-kit.mdc'), AGENTS_MARKER_START, AGENTS_MARKER_END),
-      okMessage: '.cursor/rules/infra-kit.mdc block present',
-      missingMessage: '.cursor/rules/infra-kit.mdc block missing. Run: infra-kit init',
+      name: 'CLAUDE.md block',
+      status: present ? 'pass' : 'fail',
+      message: present ? 'CLAUDE.md block present' : 'infra-kit block missing from CLAUDE.md. Run: infra-kit init',
     },
   ]
-
-  return entries.map((entry): CheckResult => {
-    return {
-      name: entry.name,
-      status: entry.present ? 'pass' : 'fail',
-      message: entry.present ? entry.okMessage : entry.missingMessage,
-    }
-  })
 }
 
 /**
@@ -403,11 +461,19 @@ export const doctor = async () => {
       'RTK is installed',
       'RTK is not installed. Install from: https://github.com/rtk-ai/rtk',
     ),
+    checkCommand(
+      'typescript-language-server installed',
+      ['typescript-language-server', '--version'],
+      'typescript-language-server is installed',
+      'typescript-language-server is not installed. Install from: https://github.com/typescript-language-server/typescript-language-server#installing',
+    ),
     checkRtkConfigured(),
     Promise.resolve(checkZshrcInitialized()),
     checkPnpmWorkspaceVirtualStore(),
     checkInfraKitConfigValid(),
+    checkDopplerProjectExists(),
     checkUserOverridePath(),
+    checkLegacyUserGlobalConfig(),
     checkIdeInstalled(),
   ])
 

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

@@ -0,0 +1,12 @@
+import { runEnvAutoLoad } from 'src/lib/env-autoload'
+
+/**
+ * Internal command invoked (backgrounded) by the `infra-kit init` shell-startup
+ * integration. Runs the 'shell-startup' trigger, writing env-load.sh when
+ * envAutoLoad is configured for it + eligible; the shell precmd hook sources it on
+ * a subsequent prompt. Intentionally writes NOTHING to stdout and never throws —
+ * auto-load must never disrupt shell startup.
+ */
+export const envAutoload = async (): Promise<void> => {
+  await runEnvAutoLoad({ expectedTrigger: 'shell-startup' })
+}

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

@@ -0,0 +1 @@
+export { envAutoload } from './env-autoload'

package/src/commands/env-clear/__tests__/env-clear.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+
+import { buildEnvClearLines } from '../env-clear'
+
+describe('buildEnvClearLines', () => {
+  it('unsets every loaded var name passed in', () => {
+    const lines = buildEnvClearLines(['FOO', 'BAR'])
+
+    expect(lines).toContain('unset FOO')
+    expect(lines).toContain('unset BAR')
+  })
+
+  it('unsets the session metadata vars and the auto-load marker', () => {
+    const lines = buildEnvClearLines([])
+
+    expect(lines).toContain('unset INFRA_KIT_ENV_CONFIG')
+    expect(lines).toContain('unset INFRA_KIT_ENV_PROJECT')
+    expect(lines).toContain('unset INFRA_KIT_ENV_LOADED_AT')
+    expect(lines).toContain('unset INFRA_KIT_ENV_AUTOLOADED')
+  })
+
+  it('exports the clear sentinel so cli-invocation auto-load stays suppressed', () => {
+    const lines = buildEnvClearLines([])
+
+    expect(lines).toContain("export INFRA_KIT_ENV_CLEARED='1'")
+  })
+})

package/src/commands/env-clear/env-clear.ts

@@ -6,6 +6,8 @@ import { z } from 'zod'
 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_LOADED_AT_VAR,
   INFRA_KIT_ENV_PROJECT_VAR,
@@ -15,6 +17,25 @@ import {
 } from 'src/lib/constants'
 import { defineMcpTool, textContent } from 'src/types'
 
+/**
+ * Build the lines for env-clear.sh: `unset` every loaded var plus the session
+ * metadata (config/project/loadedAt) and the auto-load marker, then EXPORT the
+ * clear sentinel so cli-invocation auto-load stays suppressed in this shell until
+ * an explicit `env-load` (which unsets it) or a new shell. Pure for testability.
+ */
+export const buildEnvClearLines = (varNames: string[]): string[] => {
+  return [
+    ...varNames.map((v) => {
+      return `unset ${v}`
+    }),
+    `unset ${INFRA_KIT_ENV_CONFIG_VAR}`,
+    `unset ${INFRA_KIT_ENV_PROJECT_VAR}`,
+    `unset ${INFRA_KIT_ENV_LOADED_AT_VAR}`,
+    `unset ${INFRA_KIT_ENV_AUTOLOADED_VAR}`,
+    `export ${INFRA_KIT_ENV_CLEARED_VAR}='1'`,
+  ]
+}
+
 /**
  * Clear loaded env vars. Prints a file path to stdout that must be sourced to apply.
  * The env-clear shell alias does this automatically. Throws when no env is loaded
@@ -30,14 +51,7 @@ export const envClear = async () => {
 
   const varNames = parseVarNamesFromEnvFile(envLoadPath)
 
-  const unsetLines = [
-    ...varNames.map((v) => {
-      return `unset ${v}`
-    }),
-    `unset ${INFRA_KIT_ENV_CONFIG_VAR}`,
-    `unset ${INFRA_KIT_ENV_PROJECT_VAR}`,
-    `unset ${INFRA_KIT_ENV_LOADED_AT_VAR}`,
-  ]
+  const unsetLines = buildEnvClearLines(varNames)
 
   const clearFilePath = path.resolve(cacheDir, ENV_CLEAR_FILE)
 

package/src/commands/env-load/__tests__/env-load.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, it } from 'vitest'
 
-import { DOPPLER_MAX_OUTPUT_BYTES, assertDopplerOutputSize, assertValidEnvContent, shellSingleQuote } from '../env-load'
+import {
+  DOPPLER_MAX_OUTPUT_BYTES,
+  assertDopplerOutputSize,
+  assertValidEnvContent,
+  buildEnvLoadFileLines,
+  shellSingleQuote,
+} from '../env-load'
 
 describe('shellSingleQuote', () => {
   it('wraps plain values in single quotes', () => {
@@ -130,3 +136,32 @@ describe('assertDopplerOutputSize', () => {
     }).toThrow(/unexpectedly large output/)
   })
 })
+
+describe('buildEnvLoadFileLines', () => {
+  const args = { envContent: 'A=1\nB=2', config: 'dev', project: 'proj', loadedAt: '2026-01-01T00:00:00.000Z' }
+
+  it('wraps the body in set -a / set +a and records config/project/loadedAt', () => {
+    const lines = buildEnvLoadFileLines({ ...args, autoLoaded: false })
+
+    expect(lines[0]).toBe('set -a')
+    expect(lines.at(-1)).toBe('set +a')
+    expect(lines).toContain("INFRA_KIT_ENV_CONFIG='dev'")
+    expect(lines).toContain("INFRA_KIT_ENV_PROJECT='proj'")
+    expect(lines).toContain("INFRA_KIT_ENV_LOADED_AT='2026-01-01T00:00:00.000Z'")
+  })
+
+  it('writes the AUTOLOADED marker only when autoLoaded is true', () => {
+    const lines = buildEnvLoadFileLines({ ...args, autoLoaded: true })
+
+    expect(lines).toContain("INFRA_KIT_ENV_AUTOLOADED='1'")
+    expect(lines).not.toContain('unset INFRA_KIT_ENV_AUTOLOADED')
+  })
+
+  it('drops the marker and lifts the clear sentinel on a manual load (autoLoaded false)', () => {
+    const lines = buildEnvLoadFileLines({ ...args, autoLoaded: false })
+
+    expect(lines).toContain('unset INFRA_KIT_ENV_AUTOLOADED')
+    expect(lines).toContain('unset INFRA_KIT_ENV_CLEARED')
+    expect(lines).not.toContain("INFRA_KIT_ENV_AUTOLOADED='1'")
+  })
+})

package/src/commands/env-load/env-load.ts

@@ -6,18 +6,27 @@ import process from 'node:process'
 import { z } from 'zod'
 import { $ } from 'zx'
 
-import { validateDopplerCliAndAuth } from 'src/integrations/doppler'
-import { getDopplerProject } from 'src/integrations/doppler/doppler-project'
+import {
+  buildDopplerNotFoundMessage,
+  classifyDopplerDownloadError,
+  getDopplerProject,
+  listDopplerConfigs,
+  listDopplerProjects,
+  validateDopplerCliAndAuth,
+} from 'src/integrations/doppler'
 import { commandEcho } from 'src/lib/command-echo'
 import {
   ENV_LOAD_FILE,
   ENV_VAR_LINE_PATTERN,
+  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,
   atomicWriteFileSync,
   getSessionCacheDir,
 } from 'src/lib/constants'
+import { extractStderr } from 'src/lib/errors/operation-error'
 import { getInfraKitConfig } from 'src/lib/infra-kit-config'
 import { defineMcpTool, textContent } from 'src/types'
 
@@ -25,12 +34,112 @@ interface EnvLoadArgs {
   config?: string
 }
 
+interface WriteEnvLoadFileArgs {
+  /** Resolved Doppler config / environment name (no interactive picker here). */
+  config: string
+  /**
+   * Marks the produced file as auto-loaded. `true` writes the
+   * INFRA_KIT_ENV_AUTOLOADED marker; `false` (a manual load) instead unsets the
+   * marker and lifts any clear suppression so a deliberate load wins.
+   */
+  autoLoaded?: boolean
+}
+
+export interface EnvLoadFileResult {
+  filePath: string
+  variableCount: number
+  project: string
+  config: string
+}
+
+interface EnvLoadFileLinesArgs {
+  envContent: string
+  config: string
+  project: string
+  loadedAt: string
+  autoLoaded: boolean
+}
+
 /**
- * Load environment variables from Doppler for the given config
+ * The auto-load marker lines appended to env-load.sh. Pure so the marker policy
+ * is unit-testable without touching Doppler or the filesystem.
+ *
+ * @example
+ * buildAutoLoadMarkerLines(true)  // => ["INFRA_KIT_ENV_AUTOLOADED='1'"]
+ * buildAutoLoadMarkerLines(false) // => ['unset INFRA_KIT_ENV_AUTOLOADED', 'unset INFRA_KIT_ENV_CLEARED']
  */
-export const envLoad = async (args: EnvLoadArgs) => {
+const buildAutoLoadMarkerLines = (autoLoaded: boolean): string[] => {
+  if (autoLoaded) {
+    return [`${INFRA_KIT_ENV_AUTOLOADED_VAR}=${shellSingleQuote('1')}`]
+  }
+
+  // Manual load: drop any auto marker so auto-load never re-clobbers a deliberate
+  // choice, and lift a prior clear suppression so the manual load takes effect.
+  return [`unset ${INFRA_KIT_ENV_AUTOLOADED_VAR}`, `unset ${INFRA_KIT_ENV_CLEARED_VAR}`]
+}
+
+/**
+ * Build the dotenv-format shell lines for env-load.sh. Pure (no I/O) so callers
+ * can assert the exact marker behavior. `set -a`/`set +a` auto-export every
+ * assignment when the file is sourced.
+ */
+export const buildEnvLoadFileLines = ({
+  envContent,
+  config,
+  project,
+  loadedAt,
+  autoLoaded,
+}: EnvLoadFileLinesArgs): string[] => {
+  return [
+    'set -a',
+    envContent,
+    `${INFRA_KIT_ENV_CONFIG_VAR}=${shellSingleQuote(config)}`,
+    `${INFRA_KIT_ENV_PROJECT_VAR}=${shellSingleQuote(project)}`,
+    `${INFRA_KIT_ENV_LOADED_AT_VAR}=${shellSingleQuote(loadedAt)}`,
+    ...buildAutoLoadMarkerLines(autoLoaded),
+    'set +a',
+  ]
+}
+
+/**
+ * Download Doppler secrets for a resolved config and atomically write env-load.sh
+ * to the session cache dir. Does NOT print to stdout — shared by the CLI/MCP
+ * `envLoad` entry (which prints the path) and the auto-load path (which lets the
+ * shell precmd hook source the file).
+ */
+export const writeEnvLoadFile = async ({
+  config,
+  autoLoaded = false,
+}: WriteEnvLoadFileArgs): Promise<EnvLoadFileResult> => {
   await validateDopplerCliAndAuth()
 
+  const project = await getDopplerProject()
+
+  const envContent = await downloadDopplerSecrets(project, config)
+
+  assertValidEnvContent(envContent)
+
+  const loadedAt = new Date().toISOString()
+  const envFileLines = buildEnvLoadFileLines({ envContent, config, project, loadedAt, autoLoaded })
+
+  const cacheDir = getSessionCacheDir()
+  const envFilePath = path.resolve(cacheDir, ENV_LOAD_FILE)
+
+  fs.mkdirSync(cacheDir, { recursive: true, mode: 0o700 })
+  atomicWriteFileSync(envFilePath, `${envFileLines.join('\n')}\n`, 0o600)
+
+  return {
+    filePath: envFilePath,
+    variableCount: countEnvVarLines(envContent),
+    project,
+    config,
+  }
+}
+
+/**
+ * Load environment variables from Doppler for the given config
+ */
+export const envLoad = async (args: EnvLoadArgs) => {
   const { config } = args
 
   commandEcho.start('env-load')
@@ -40,6 +149,11 @@ export const envLoad = async (args: EnvLoadArgs) => {
   if (config) {
     selectedConfig = config
   } else {
+    // Validate auth before the interactive picker so an unauthenticated user fails
+    // fast instead of choosing an env first. writeEnvLoadFile re-checks (cheap) for
+    // the non-interactive path where this branch is skipped.
+    await validateDopplerCliAndAuth()
+
     const { environments } = await getInfraKitConfig()
 
     commandEcho.setInteractive()
@@ -58,43 +172,21 @@ export const envLoad = async (args: EnvLoadArgs) => {
 
   commandEcho.addOption('--config', selectedConfig)
 
-  const project = await getDopplerProject()
-
-  const envContent = await downloadDopplerSecrets(project, selectedConfig)
-
-  assertValidEnvContent(envContent)
-
-  // Build env file content in dotenv format
-  const loadedAt = new Date().toISOString()
-  const envFileLines = [
-    'set -a',
-    envContent,
-    `${INFRA_KIT_ENV_CONFIG_VAR}=${shellSingleQuote(selectedConfig)}`,
-    `${INFRA_KIT_ENV_PROJECT_VAR}=${shellSingleQuote(project)}`,
-    `${INFRA_KIT_ENV_LOADED_AT_VAR}=${shellSingleQuote(loadedAt)}`,
-    'set +a',
-  ]
-
-  const cacheDir = getSessionCacheDir()
-  const envFilePath = path.resolve(cacheDir, ENV_LOAD_FILE)
-
-  fs.mkdirSync(cacheDir, { recursive: true, mode: 0o700 })
-  atomicWriteFileSync(envFilePath, `${envFileLines.join('\n')}\n`, 0o600)
+  // A manual load is authoritative: autoLoaded=false drops the auto marker.
+  const result = await writeEnvLoadFile({ config: selectedConfig, autoLoaded: false })
 
   // REQUIRED
-  process.stdout.write(`${envFilePath}\n`)
+  process.stdout.write(`${result.filePath}\n`)
 
   // Logs to stderr (pino → pretty-print), so it doesn't pollute the captured
   // file path that the shell wrapper reads from stdout.
   commandEcho.print()
 
-  const varCount = countEnvVarLines(envContent)
-
   const structuredContent = {
-    filePath: envFilePath,
-    variableCount: varCount,
-    project,
-    config: selectedConfig,
+    filePath: result.filePath,
+    variableCount: result.variableCount,
+    project: result.project,
+    config: result.config,
   }
 
   return {
@@ -122,10 +214,15 @@ const downloadDopplerSecrets = async (project: string, config: string): Promise<
 
   $.quiet = true
   try {
-    const result =
-      await $`doppler secrets download --no-file --format env --project ${project} --config ${config}`.timeout(
+    let result
+
+    try {
+      result = await $`doppler secrets download --no-file --format env --project ${project} --config ${config}`.timeout(
         DOPPLER_DOWNLOAD_TIMEOUT_MS,
       )
+    } catch (error: unknown) {
+      throw await translateDopplerDownloadError(error, project, config)
+    }
 
     assertDopplerOutputSize(result.stdout)
 
@@ -135,6 +232,26 @@ const downloadDopplerSecrets = async (project: string, config: string): Promise<
   }
 }
 
+/**
+ * Turn a raw `doppler secrets download` failure into an actionable error. A
+ * recognized project/config not-found is enriched (on this error path only) with
+ * the list of available names and rethrown as a clean `Error` pointing at the
+ * exact infra-kit.json field. Anything else — auth, network, timeout — is
+ * rethrown untouched so it degrades to the existing behavior, never worse.
+ */
+const translateDopplerDownloadError = async (error: unknown, project: string, config: string): Promise<Error> => {
+  const stderr = extractStderr(error) ?? (error instanceof Error ? error.message : String(error))
+  const kind = classifyDopplerDownloadError(stderr)
+
+  if (kind === 'unknown') {
+    return error instanceof Error ? error : new Error(String(error))
+  }
+
+  const available = kind === 'project' ? await listDopplerProjects() : await listDopplerConfigs(project)
+
+  return new Error(buildDopplerNotFoundMessage({ kind, project, config, available }))
+}
+
 export const assertDopplerOutputSize = (stdout: string): void => {
   const bytes = Buffer.byteLength(stdout, 'utf-8')
 

package/src/commands/env-load/index.ts

@@ -1 +1,2 @@
-export { envLoad, envLoadMcpTool } from './env-load'
+export { buildEnvLoadFileLines, envLoad, envLoadMcpTool, writeEnvLoadFile } from './env-load'
+export type { EnvLoadFileResult } from './env-load'