io.github.Patrizzos/envspeak

EnvSpeak

MCP server and CLI that resolves config/env-var cascade across .env files, Docker Compose, and Kubernetes — tells AI agents (and you) what a variable actually evaluates to at runtime, and why.

Same problem shape as CSS cascade — several sources, non-obvious precedence rules, and a value that "wins" only because of where it's defined — applied to application configuration instead of stylesheets. A sibling project to stylesafe and stylespeak, which do the same thing for CSS.

The problem

A real app's config comes from .env, .env.local, .env.production, docker-compose.yml (environment: vs env_file:), Kubernetes ConfigMap/Secret objects, and hard-coded fallbacks in code — five-plus layers, each with its own precedence rules that don't compose the way you'd guess. The best-known gotcha: a plain .env.local overrides .env.production unless you also have a .env.production.local — because "local" outranks "environment-specific" in the conventional dotenv cascade. An agent editing config has no way to know what a variable actually resolves to, or what breaks if it changes one layer.

Tools

• resolve_variable — what does DATABASE_URL actually evaluate to, and which file wins?
• trace_variable — every place this variable is set, across every domain and environment.
• impact_preview — if I change this value in this file, what actually changes downstream — and what's shielded by something higher-precedence?
• config_manifest — a compressed, whole-project summary: every variable, its sources, and risk hotspots (secrets sitting in a tracked file, variables read in code with no fallback and no source anywhere).
• diff_environments — resolve every variable under two environments/services/workloads and see what's actually different between them.

Install

npm install -g @patrizzos/envspeak

As an MCP server

{
  "mcpServers": {
    "envspeak": {
      "command": "envspeak"
    }
  }
}

As a CLI

envspeak resolve DATABASE_URL --environment production
envspeak trace LOG_LEVEL
envspeak impact --file .env --variable LOG_LEVEL --newValue debug
envspeak manifest
envspeak diff --a '{"nodeEnv":"development"}' --b '{"nodeEnv":"production"}'

If --files is omitted, envspeak auto-discovers .env*, Compose, and Kubernetes manifest files under --projectRoot (default: current directory). Pass --files a,b,c to scope it explicitly — recommended for MCP calls, so the agent controls exactly what's read.

Precedence conventions encoded

dotenv (Next.js/Vite-style, the de facto standard): process.env (shell) > .env.[env].local > .env.local > .env.[env] > .env > code fallback (process.env.X || 'default'). Note .env.local outranks .env.[env] — the gotcha above.

Docker Compose: docker compose run -e (CLI) > environment: > env_file: (last file in the list wins on conflicts) > Dockerfile ENV (not analyzed).

Kubernetes: inline env: always overrides envFrom: (bulk ConfigMap/Secret import; last entry in the list wins among those). Env values are frozen at pod start — editing a referenced ConfigMap/Secret does not reach a running pod without a restart or rollout. impact_preview flags this.

Every result includes a confidence level and a caveat string, because a shell-exported or CLI-passed override is always possible and never visible to static analysis — envspeak says so explicitly rather than pretending certainty it doesn't have.

Security

• Zero runtime dependencies. The YAML subset parser used for Compose/Kubernetes files is hand-written rather than pulled in from npm, so there's no third-party supply-chain surface. npm audit is clean by construction.
• Path-traversal guarded. File reads are resolved against projectRoot and refuse to escape it, even if a tool call is given a crafted relative path.
• Prototype-pollution guarded. Object keys parsed from YAML content (__proto__, constructor, prototype) are never used for property assignment.
• Secrets are redacted by default. Kubernetes Secret values are shown only as ab***yz, never in full, regardless of which tool surfaces them.
• Secret-likelihood heuristics. Variable names and value shapes (AWS keys, GitHub tokens, PEM blocks, high-entropy credential-shaped strings) are flagged, cross-referenced against .gitignore, and surfaced as a secretFlag / risk hotspot rather than silently passed through.
• Bounded, non-backtracking regexes. Pattern matching used for code-default scanning caps match length and avoids nested quantifiers to avoid ReDoS on large files.
• Regardless of these guards, envspeak reads whatever files you point it at — scope the files list an agent can pass, the same way you'd scope any tool with filesystem access.

Development

npm test   # zero dependencies — no install step needed

License

MIT