# prod-debug

A **secure, dev-only CLI tool** for debugging production React/SPAs with local source maps using Chrome DevTools Overrides, **without deploying source maps publicly**.

## Overview

`prod-debug` creates a pre-wired Chromium debugging session that allows you to:
- Debug production builds with local source maps
- Set breakpoints in original source files
- View stack traces with original file names and line numbers
- Keep source maps completely local (never exposed publicly)

## Requirements

- Node.js 22.0.0 or higher
- Chrome/Chromium browser
- Local production build directory with `.js` and `.js.map` files

## Installation

```bash
npm install -g prod-debug
```

Or use with `npx`:

```bash
npx prod-debug <url> --build <path>
```

## Usage

### Basic Usage

```bash
prod-debug https://app.example.com --build ./build
```

### Options

| Option | Description |
|--------|-------------|
| `<url>` | Production URL to debug (required) |
| `--build <path>` | Local production build directory containing `.js` and `.js.map` files (required) |
| `--ssr` | Enable SSR mode (partial decoding allowed) |
| `--browser <path>` | Custom Chrome/Chromium binary path |
| `--keep-profile` | Do not delete temp profile on exit (debug only) |
| `--verbose` | Enable debug logs |
| `--dry-run` | Do everything except launching browser |

### Examples

**Debug a production React app:**
```bash
prod-debug https://myapp.com --build ./dist
```

**Debug with SSR mode (for apps with large inline scripts):**
```bash
prod-debug https://myapp.com --build ./dist --ssr
```

**Dry-run to test configuration:**
```bash
prod-debug https://myapp.com --build ./dist --dry-run --verbose
```

**Use custom Chrome binary:**
```bash
prod-debug https://myapp.com --build ./dist --browser /path/to/chrome
```

## How It Works

1. **Fetch & Parse**: Fetches HTML from the production URL and parses all `<script>` tags
2. **Match Artifacts**: Matches production JS bundle URLs to local build artifacts by filename and hash
3. **Create Profile**: Creates a temporary Chrome profile with DevTools Overrides enabled
4. **Setup Overrides**: Copies local source maps to Chrome's Overrides directory, mirroring production paths
5. **Launch Chrome**: Launches Chrome with DevTools automatically opened
6. **Cleanup**: Removes temporary profile on exit (unless `--keep-profile` is used)

## Security & Isolation

- **Ephemeral Profile**: Uses a brand-new temporary Chrome profile (no extensions, no sync, no cookies)
- **Local Source Maps**: Source maps never leave your filesystem
- **No Network Exposure**: Source maps are not served over HTTP
- **Automatic Cleanup**: All temporary files are deleted on exit

## Limitations

- **Chromium-only**: No Safari support
- **Hash Matching**: Production JS filenames must match local build artifacts (including hash)
- **No Runtime JS**: Cannot debug encrypted or runtime-generated JavaScript
- **No Retroactive Decoding**: Stack traces generated before DevTools opens won't be decoded
- **Rebuild Required**: If production hash changes, you must rebuild locally

## SSR Mode

When using `--ssr`, the tool allows large inline scripts (which cannot be source-mapped) and provides warnings instead of errors. This is useful for SSR applications where some JavaScript is injected server-side.

## Troubleshooting

### "No matching build artifact found"

- Ensure your local build directory contains the same JS files as production (with matching hashes)
- Check that source map files (`.js.map`) exist alongside JS files
- Use `--verbose` to see detailed matching information

### "Hash mismatch"

- Your local build doesn't match production
- Rebuild your application to match production
- Check that you're pointing to the correct build directory

### "Large inline script detected"

- Production HTML contains large inline JavaScript that cannot be source-mapped
- Use `--ssr` flag if this is expected (SSR applications)
- Consider moving inline scripts to external files for better debugging

### DevTools Overrides not working

- Ensure Chrome version is 90 or higher
- Check that source maps are being copied to the Overrides directory (use `--keep-profile` and inspect)
- Verify that the Overrides folder is set correctly in Chrome DevTools Settings

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev <url> --build <path>
```

## License

MIT