envsitter/AGENTS.md

AGENTS.md (envsitter)

This repo contains envsitter: a TypeScript (ESM) library + CLI for safely inspecting and matching .env secrets without exposing values.

Ground rules (security)

• Never print or log raw secret values from .env files or external providers.
• Do not add any API that returns a plaintext value (no getValue() style APIs).
• Prefer comparisons via deterministic fingerprints (HMAC) and boolean match results.
• Prefer passing candidate secrets via stdin (to avoid shell history): --candidate-stdin.
• Keep all generated peppers/secrets out of git (see .gitignore).
• envsitter-guard (separate repo) exposes this package's exports to AI agents as tools, so every new export is agent-reachable.

Project layout

• src/index.ts: public exports (the only surface npm users and envsitter-guard see)
• src/envsitter.ts: EnvSitter read-only facade (keys, fingerprints, matchers, scan, redactor)
• src/cli.ts: CLI entrypoint (bin -> dist/cli.js); one if (cmd === ...) block per command in run()
• src/file-ops.ts: file-level mutations for the library API (read, edit, atomic write only when write: true)
• src/pepper.ts: pepper resolution + auto-create; src/fingerprint.ts: HMAC-SHA-256
• src/sources/: DotenvFileSource, ExternalCommandSource (both parse with dotenv/parse.ts)
• src/dotenv/document.ts: the only dotenv grammar; round-trippable, keeps comments, blank lines, and line/column issues
• src/dotenv/parse.ts: values-only view of document.ts (read path)
• src/dotenv/edit.ts: pure string-in/string-out edits (copy, format, annotate, add/set/unset/delete); owns the edit types that file-ops.ts re-exports
• src/dotenv/io.ts: readTextFileOrEmpty, writeTextFileAtomic (keeps file mode, writes through symlinks, new files 0600); src/dotenv/utils.ts: value quoting
• src/paths.ts: path policy (isEnvFile, isExampleEnvFile, isSensitiveEnvFile, isEnvSitterPepperFile)
• src/regex.ts: regexTest; use it for every user-supplied regex (resets lastIndex for g/y flags)
• src/redact.ts: createRedactor behind EnvSitter#redactor() and the redact command; decides which values look secret (key names, token shape, URL passwords, PEM)
• src/test/*.test.ts: Node test suite (compiled to dist/test/*.test.js); cli.test.ts spawns dist/cli.js
• .github/workflows/: ci.yml (push, PR, reusable), release.yml (tag vX.Y.Z -> CI -> npm trusted publishing -> GitHub Release), pages.yml (deploys site/); .github/dependabot.yml groups weekly npm and Actions updates
• .github/scripts/changelog-section.mjs: prints a version's CHANGELOG section; fails if missing or still (Unreleased)
• site/: static docs site for envsitter and envsitter-guard (no build step); site/DESIGN.md is its design contract and is not published

Gotchas

• Grammar changes go in dotenv/document.ts only; parseDotenv, validate, and every edit follow automatically.
• CLI file commands are thin wrappers over file-ops.ts; change behavior there, then keep the CLI's text (non-JSON) output in step.
• src/paths.ts is the policy envsitter-guard enforces. Widening or narrowing isSensitiveEnvFile changes what agents are blocked from; add a case to paths.test.ts for every change.
• src/test/envsitter.test.ts resolves the default pepper (<cwd>/.envsitter/pepper) unless ENVSITTER_PEPPER is set, so npm test creates that file on first run.

Build / typecheck / test

There is no linter configured (no ESLint/Prettier). Use tsc + tests as quality gates. Husky pre-commit runs npm test.

npm install
npm run build       # tsc -p tsconfig.json -> dist/
npm run typecheck   # tsc --noEmit
npm test            # build, then scripts/run-tests.mjs runs every dist/test/*.test.js
# tests execute from compiled JS, so build before running one file or one test
npm run build && node --test dist/test/envsitter.test.js
npm run build && node --test --test-name-pattern "outside-in" dist/test/envsitter.test.js

--test-name-pattern takes a substring/regex matching the test('name', ...) title.

Releasing

• Bump package.json, date the CHANGELOG heading, commit, push tag vX.Y.Z. The Release workflow does the rest; never npm publish by hand.
• Push to origin (Gitea, git.boxpositron.dev); it mirrors to GitHub, where the workflows run. Jobs are guarded with if: github.server_url == 'https://github.com' so Gitea's runner skips them.
• npm trusted publishing (OIDC) authenticates the publish; no npm token exists in the repo. Keep release.yml as the publishing workflow name, because the npm trusted-publisher config pins it.

Bun

The CLI is runnable under Bun:

• bun src/cli.ts keys --file .env

Tests currently run under Node’s built-in test runner. If you add Bun tests, keep Node tests working.

Code style and conventions

TypeScript / module system

• This repo is ESM: "type": "module" in package.json.
• TS config is strict and includes:
  • strict: true
  • noUncheckedIndexedAccess: true
  • exactOptionalPropertyTypes: true
• Use ESM import specifiers with .js extensions when importing local TS modules.
  • Example: import { parseDotenv } from '../dotenv/parse.js'
• Prefer node: specifiers for built-ins:
  • import { readFile } from 'node:fs/promises'

Formatting

• No formatter is enforced.
• Keep diffs small and consistent with existing file style.
• Prefer 2-space indentation and trailing commas where already used.

Imports

• Group imports by origin:
  1. node: built-ins
  2. third-party (if any)
  3. local ./ and ../
• Avoid unused imports; keep import lists minimal.

Naming

• Types: PascalCase (EnvSitterFingerprint)
• Functions/vars: camelCase (resolvePepper, candidateValue)
• Constants: camelCase unless truly global constant.
• File names: kebab-case.ts for tests; otherwise match existing structure.

Types and optional properties (important)

exactOptionalPropertyTypes is enabled.

• Do not pass undefined as a value for an optional property.
  • Prefer conditional spreads:
    • ...(maybe ? { prop: maybe } : {})
• Prefer returning undefined by omitting optional properties rather than setting them.

Error handling

• Prefer throwing Error with actionable messages.
• Avoid empty catch blocks.
• Avoid logging by default. If debugging output is needed:
  • Gate it behind process.env.ENVSITTER_DEBUG === '1'.

Security-sensitive comparisons

• Use constant-time comparison for digests:
  • timingSafeEqual for fingerprint digest bytes.

IO and side effects

• .env values should only exist in memory.
• Pepper auto-creation is allowed, but must write only to the gitignored location:
  • default: .envsitter/pepper
• Never write .env values elsewhere (no caches, no exports to new files).

CLI behavior

• CLI should return useful exit codes:
  • 0 success / match found
  • 1 mismatch / no match found
  • 2 usage or runtime error
• Prefer JSON output for machine consumption when --json is provided.
• Never print secret values; only keys, booleans, metadata (length), and fingerprints.

Editor/assistant rules

• No Cursor rules found in .cursor/rules/ or .cursorrules.
• No Copilot instructions found in .github/copilot-instructions.md.

If you add any of the above rule files later, update this document to summarize the relevant constraints.