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

# Development Guide

> Set up the envtrap development environment and contribute to the project.

## Clone the Repository

```bash theme={null}
git clone https://github.com/Vishal-770/envtrap.git
cd envtrap
```

## Install Dependencies

envtrap uses **pnpm** workspace features:

```bash theme={null}
pnpm install
```

## Project Structure

The project is structured as a pnpm monorepo:

```text theme={null}
envtrap/
├── package/          # Core envtrap security agent npm package
│   ├── src/          # TypeScript source code
│   │   ├── index.ts      # CLI entry point: commander commands, secret loader, child spawner
│   │   ├── hooks.mjs     # ESM customization hooks & CommonJS Module.prototype.require patch
│   │   ├── config.ts     # envtrap.json schema validator, loader, and deepMerge logic
│   │   ├── types.ts      # Shared TypeScript interfaces (Secret, LeakEvent, ScanResult, etc.)
│   │   ├── ca.ts         # In-memory 2048-bit RSA Root CA (node-forge), OS trust store inject/remove
│   │   ├── proxy.ts      # MITM TLS HTTP/HTTPS proxy server (127.0.0.1, random port)
│   │   ├── scanner.ts    # Stateful scan engine: 1MB clamp, 1.5s TTL dedup cache, block routing
│   │   ├── fingerprint.ts# looksLikeSecret gate, shannonEntropy, scanContent, formatNetworkContext
│   │   └── reporter.ts   # Terminal output: chalk alerts, run summary, JSONL log writer
│   └── dist/         # Compiled JS and copied ESM hooks
├── test-server/      # Integration test suite (Express web app + mock TLS server)
│   └── test/
│       └── integration.test.js # Comprehensive test runner
├── landing-page/     # Next.js product landing page
└── docs/             # Mintlify documentation (you are here)
```

## Building

To compile the TypeScript package source and copy raw ESM customization hooks to `dist`:

```bash theme={null}
cd package
pnpm run build
```

## Running Tests

Integration tests verify interceptors under real process spawns, CommonJS imports, ESM loader injections, and network MITM proxied connections.

First, ensure the package is built, then run tests in the `test-server` folder:

```bash theme={null}
# Build the agent package
cd package && pnpm run build

# Run the integration test suite
cd ../test-server
pnpm test
```

## Running the Landing Page Locally

```bash theme={null}
cd landing-page
pnpm dev
```

The site will be available at `http://localhost:3000`.

## Running the Docs Locally

Install the Mintlify CLI:

```bash theme={null}
npm install -g mintlify
```

Then start the dev server from the `docs/` directory:

```bash theme={null}
cd docs
mintlify dev
```

The docs will be available at `http://localhost:3000`.

## Architecture Overview

If you want to contribute to the code:

1. **CLI Commands and Spawner**: Handle flags and set up proxy/hooks environments in `package/src/index.ts`.
2. **ESM loader/CJS patches**: Any changes to intercepted hooks for `node:dns` or `node:child_process` go in `package/src/hooks.mjs`.
3. **MITM HTTPS Decryption**: The proxy handling and response blocking go in `package/src/proxy.ts`.
4. **Secret Scanning**: The candidate filter and entropy logic go in `package/src/fingerprint.ts`.

## Submitting a PR

1. Fork the repository
2. Create a branch: `git checkout -b feat/my-feature`
3. Make your changes and add tests in `test-server/test/integration.test.js`
4. Verify tests pass with `pnpm test`
5. Submit a pull request with a clear description