AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• src/ contains all TypeScript source. Public entrypoint is src/index.ts, which re‑exports the main API (envParse) and error types.
• Core logic lives in src/structured.ts; errors are defined in src/errors.ts.
• Tests are colocated in src/*.test.ts (currently src/structured.test.ts).
• Build output goes to dist/ (generated by tsc; not committed).

Build, Test, and Development Commands

This repo uses Bun + TypeScript.

• bun install — install dependencies.
• bun run build — compile src/ to dist/ using tsconfig.build.json.
• bun run typecheck — run TypeScript in --noEmit mode.
• bun run lint — type‑aware lint via oxlint and formatting check via oxfmt --check.
• bun run fmt — auto‑format files with oxfmt.
• bunx vitest — run the Vitest suite (config: vitest.config.ts). Add --watch for TDD.

Coding Style & Naming Conventions

• TypeScript, ESM ("type": "module"). Keep imports/exports explicit and tree‑shakable.
• Indentation: 2 spaces. Prefer double quotes in TS to match existing files.
• Filenames: kebab-case.ts; tests: *.test.ts.
• Keep API surface in src/index.ts; add new helpers in focused modules under src/.
• Run bun run fmt before pushing.

Testing Guidelines

• Framework: Vitest. Tests should live next to the module they cover (e.g., src/foo.test.ts).
• Prefer small, deterministic unit tests. Cover both valid parsing and validation error paths.

Commit & Pull Request Guidelines

• Commit messages are short, imperative, and scoped to the change (e.g., fix defaults, add async guard). No enforced conventional‑commit format.
• PRs should include: a clear description, rationale, and any API changes with examples. If behavior changes, add/adjust tests.

Security & Configuration Tips

• Never commit real secrets. Use .env locally and document new variables in README.md examples.