> ## Documentation Index
> Fetch the complete documentation index at: https://envtrap.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer & Contributing Guide

> Setting up the development environment, running unit tests, and understanding the Clean Architecture design.

# Developer & Contributing Guide

Thank you for contributing to `envtrap`! This guide covers local repository setup, building the project, running the test suites, and extending the codebase.

***

## Local Setup

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/EnvTrap/envtrap-package.git
    cd envtrap-package
    ```
  </Step>

  <Step title="Install dependencies">
    Install development and build dependencies using `pnpm`:

    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="Build TypeScript and hook assets">
    Compile the TypeScript source files and copy runtime hook assets into `dist/`:

    ```bash theme={null}
    pnpm run build
    ```
  </Step>

  <Step title="Run unit tests">
    Run the complete unit test suite using Node's native test runner:

    ```bash theme={null}
    pnpm test
    ```
  </Step>
</Steps>

***

## Architecture & Codebase Layout

`envtrap` is built strictly according to **Clean Architecture & SOLID principles**, segregating domain logic from Node.js runtime adapters:

<CardGroup cols={2}>
  <Card title="Domain Layer (src/domain)" icon="cube">
    * `SecretMatcher.ts`: Pure substring matching gated by candidate filters.
    * `ContentClamp.ts`: Prevents memory exhaustion by limiting scan buffers to 1 MB.
    * `DedupCache.ts`: TTL-based duplicate alert throttling.
    * `OutputRedactor.ts`: Hash-based string redaction (`[REDACTED: SHA256:...]`).
  </Card>

  <Card title="MITM TLS Engine (src/mitm)" icon="lock">
    * `CertificateAuthority.ts`: In-memory 2048-bit Root CA generation and per-domain certificate minting.
    * `MitmServer.ts`: Loopback HTTP server and proxy connection orchestrator.
    * `ConnectHandler.ts`: HTTPS CONNECT tunnel interception and TLS socket creation.
    * `TlsInterceptor.ts`: Sliding-window TLS stream scanner.
  </Card>

  <Card title="Runtime Hooks (src/hooks)" icon="anchor">
    * `hooks.mjs`: Node.js ESM customization hooks (`resolve`, `load`, `initialize`).
    * `virtual/child-process.mjs`: Virtual module wrapping `node:child_process`.
    * `virtual/dns.mjs`: Virtual module wrapping `node:dns`.
    * `shared.mjs`: Stack-trace parsing and caller path exclusion matching.
  </Card>

  <Card title="CLI & Orchestration (src/cli)" icon="terminal">
    * `RunCommandBuilder.ts`: Composition root wiring SOLID adapters to ports.
    * `ChildProcessManager.ts`: Process spawner and standard stream router.
    * `HookMessageParser.ts`: Decodes out-of-band IPC messages from runtime hooks.
    * `ChildEnvBuilder.ts`: Sets up child process proxy and CA environment variables.
  </Card>
</CardGroup>

***

## Extending envtrap

### Adding a Custom Secret Source

To load credentials from a custom store (e.g. AWS Secrets Manager, HashiCorp Vault, Doppler):

1. Implement the `ISecretSource` interface located in `src/ports/ISecretSource.ts`:
   ```typescript theme={null}
   export interface ISecretSource {
     load(): Promise<Secret[]> | Secret[];
   }
   ```
2. Register your implementation inside `SecretSourceComposer`.

### Adding a Custom Leak Reporter

To stream leak alerts to a remote observability endpoint (e.g. Datadog, Slack, PagerDuty):

1. Implement the `ILeakReporter` interface in `src/reporting/ILeakReporter.ts`:
   ```typescript theme={null}
   export interface ILeakReporter {
     report(event: LeakEvent): void;
   }
   ```
2. Register your reporter with `CompositeReporter` in `RunCommandBuilder.ts`.

***

## Running Documentation Locally

To test documentation updates locally using Mintlify:

```bash theme={null}
cd docs
pnpm exec mintlify dev --port 3333
```

Your local documentation server will be available at `http://localhost:3333`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.