Table of Contents

Getting Started

• Overview
• Installation
• Quick Start
• CLI Usage
• TUI Keyboard Shortcuts
• Examples

Configuration

• Global Config
• Local Config

Development

• Available Scripts
• Tech Stack
• Project Structure
• Versioning
• Style Guide

Overview

yaos-proxy-dev is a local-first reverse proxy and interceptor CLI with a TUI dashboard. It allows you to intercept HTTPS traffic from your local domains, toggle mock responses, inject latency, and snapshot live responses — all without modifying your app code.

What Makes This Project Unique

• HTTPS reverse proxy: Route local domains to backend ports via on-the-fly TLS certs
• Mock toggling: Switch routes between live and mock responses per request
• Latency injection: Simulate network conditions globally or per-route
• Response snapshots: Capture live responses as mock files with one keystroke
• TUI dashboard: Real-time traffic log, request/response inspector, overlay controls
• CA management: Generates and optionally trusts a local CA certificate

Installation

Prerequisites

• Node.js >= 18
• openssl in PATH (standard on macOS/Linux)

# Install globally from npm
npm install -g @yaos-git/proxy-dev

# Or install as a dev dependency
npm install -D @yaos-git/proxy-dev

From Source

# Clone the repository
git clone https://github.com/YAOSGit/proxy-dev.git
cd proxy-dev

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link

Quick Start

1. Generate a global configuration and a CA certificate:

proxy-dev trust init

Note: This automatically creates ~/.config/proxy-dev/config.json and a CA certificate at ~/.config/proxy-dev/certs/.

2. Trust the CA in your OS (macOS example):

proxy-dev trust system

3. Add a route (e.g., mapping api.local to localhost port 3001):

proxy-dev routes add api.local 3001

4. Start the proxy:

# Headless mode (logs to stdout)
proxy-dev start

# TUI dashboard (interactive)
proxy-dev-tui

CLI Usage

| Command | Description | |---|---| | proxy-dev trust init | Bootstrap global config and generate CA cert | | proxy-dev trust system | Add CA to OS trust store (browsers, curl, etc.) | | proxy-dev trust status | Show trust status for system and runtimes | | proxy-dev start | Start proxy in headless mode (stdout logging) | | proxy-dev stop | Stop a running proxy-dev instance | | proxy-dev-tui | Launch the interactive TUI dashboard | | proxy-dev routes list | List all configured routes | | proxy-dev routes add <domain> <port> | Add a route (use -g <group> and -p <path>) | | proxy-dev routes remove <domain> | Remove a route | | proxy-dev groups activate <name> | Activate a route group locally | | proxy-dev groups deactivate <name> | Deactivate a route group locally | | proxy-dev mock <route> <variant> | Set active mock variant (use --off for live) | | proxy-dev daemon status | Check if hosts daemon is running | | proxy-dev daemon stop | Stop the hosts daemon |

Additional trust subcommands: proxy-dev trust firefox, node, python, java, deno, openssl

TUI Keyboard Shortcuts

| Key | Context | Action | |---|---|---| | ↑ / ↓ | Traffic table | Navigate requests | | Enter | Traffic table | Open detail inspector | | Esc | Detail / overlay | Go back | | Tab | Detail inspector | Switch request ↔ response | | ↑ / ↓ | Detail inspector | Scroll active pane | | m | Traffic table | Open mock picker | | s | Traffic table | Snapshot response as mock | | t | Traffic table | Set latency | | c | Any | Route config screen | | x | Traffic table | Clear traffic log | | h | Any | Help menu | | q | Any | Quit |

Route config screen shortcuts:

| Key | Action | |---|---| | ↑ / ↓ | Navigate items | | Enter | Select / toggle group | | g | Toggle group activation | | s | Toggle HTTPS upgrade | | d | Delete route or group | | Esc | Close |

Examples

The examples/ directory contains ready-to-run configurations at three levels of complexity:

| Example | What it demonstrates | |---------|---------------------| | single-route/ | Single route group, minimal config, one backend | | mocks-and-latency/ | Mock variants, global latency, path-based routing | | microservices/ | Three-service architecture with full mock coverage and workflow scripts |

The single-route example uses local config only (proxy-dev.json). The other examples demonstrate the global + local config split used in real projects.

Configuration

Global Config

The global configuration file lives at ~/.config/proxy-dev/config.json.

{
  "version": 1,
  "port": 443,
  "groups": {
    "services": {
      "description": "Local microservices",
      "routes": [
        { "domain": "api.local", "target": 3001 },
        { "domain": "api.local", "path": "/auth", "target": 3002 }
      ]
    }
  },
  "latency": { "globalMs": 0 }
}

Local Config

The local configuration file lives in your project root at ./proxy-dev.json.

{
  "activeGroups": ["services"],
  "mocks": {
    "api.local/users": {
      "variants": {
        "success": { "file": "./mocks/api.local/users/success.json", "status": 200 },
        "empty":   { "file": "./mocks/api.local/users/empty.json",   "status": 200 }
      },
      "active": "success"
    }
  },
  "latency": { "globalMs": 100 }
}

Available Scripts

Development Scripts

| Script | Description | |--------|-------------| | npm run dev | Run TypeScript build in watch mode | | npm run dev:typescript | Run TypeScript type checking in watch mode |

Build Scripts

| Script | Description | |--------|-------------| | npm run build | Bundle the CLI with esbuild |

Lint Scripts

| Script | Description | |--------|-------------| | npm run lint | Run type checking, linting, formatting, and audit | | npm run lint:check | Check code for linting issues with Biome | | npm run lint:fix | Check and fix linting issues with Biome | | npm run lint:format | Format all files with Biome | | npm run lint:types | Run TypeScript type checking only | | npm run lint:audit | Run npm audit |

Testing Scripts

| Script | Description | |--------|-------------| | npm test | Run all tests (unit, react, types, e2e) | | npm run test:unit | Run unit tests | | npm run test:react | Run React component tests | | npm run test:types | Run TypeScript type tests | | npm run test:e2e | Run end-to-end tests |

Tech Stack

Core

• React 19 - UI component library
• Ink 6 - React for CLIs
• TypeScript 5 - Type-safe JavaScript
• Commander - CLI argument parsing
• http-proxy - Programmable proxying library
• zod - TypeScript-first schema validation

Build & Development

• esbuild - Fast bundler
• Vitest - Unit testing framework
• Biome - Linter and formatter

UI Components

• Chalk - Terminal string styling

Project Structure

proxy-dev/
├── src/
│   ├── app/                # Application entry points
│   │   ├── cli.ts          # CLI commands and parsing
│   │   ├── app.tsx         # Main TUI component
│   │   ├── providers.tsx   # Context providers composition
│   │   └── index.tsx       # Root exports
│   ├── components/         # React TUI components
│   │   ├── SystemHeader/   # Uptime and system status
│   │   ├── TrafficTable/   # Request log table
│   │   ├── SummaryBar/     # Request summary details
│   │   ├── ControlBar/     # Bottom bar for shortcuts
│   │   ├── DetailInspector/# Request/response drilldown
│   │   └── overlays/       # Overlays (MockPicker, LatencyInput, HelpMenu, etc.)
│   ├── hooks/              # Custom React hooks
│   │   ├── useTraffic/     # Manages traffic entry buffer
│   │   ├── useRoutes/      # Manages config routing and latency state
│   │   ├── useProxy/       # Manages proxy worker process
│   │   ├── useHosts/       # Manages system hosts file wrapper
│   │   └── useUIState/     # Manages active views and overlays
│   ├── providers/          # React context providers
│   ├── proxy/              # Proxy core logic
│   │   ├── server.ts       # Main proxy worker process
│   │   ├── interceptor.ts  # Traffic interception and matching
│   │   ├── latency.ts      # Latency simulation resolver
│   │   └── ipc.ts          # IPC messages definition
│   ├── ssl/                # TLS certification management
│   │   ├── ca.ts           # Root CA generation
│   │   ├── leaf.ts         # Per-domain cert generation
│   │   └── trust.ts        # OS-specific cert trust utilities
│   ├── hosts/              # System /etc/hosts integration
│   │   ├── parser.ts       # Parse the hosts definition format
│   │   └── manager.ts      # Hosts writer via sudo subprocess
│   ├── utils/              # Pure utility functions
│   │   ├── config/         # Config loading, validating, saving
│   │   ├── format/         # Terminal formatting utilities
│   │   ├── snapshot/       # Response-to-mock dumping functionality
│   │   └── platform/       # OS-specific directory/file mappings
│   └── types/              # TypeScript type definitions
├── examples/               # Usage examples
│   ├── basic/              # Single route, minimal config
│   ├── custom/             # Mocks, latency, path routing
│   └── integration/        # Multi-service environment
├── e2e/                    # End-to-end testing
│   ├── cli-commands.e2e.ts # Testing command lines directly
│   ├── mock-system.e2e.ts  # Mock state workflows
│   └── proxy-flow.e2e.ts   # Actual request proxy routing
├── dist/                   # Built output
├── biome.json              # Biome configuration
├── tsconfig.json           # Base TypeScript configuration
├── tsconfig.app.json       # App TypeScript configuration
├── vitest.config.ts        # Vitest base configuration
├── vitest.unit.config.ts   # Unit test configuration
├── vitest.react.config.ts  # React component test configuration
├── vitest.type.config.ts   # Type test configuration
├── vitest.e2e.config.ts    # E2E test configuration
├── esbuild.config.js       # Bundler configuration
└── package.json

Versioning

This project uses a custom versioning scheme: MAJORYY.MINOR.PATCH

| Part | Description | Example | |------|-------------|---------| | MAJOR | Major version number | 1 | | YY | Year (last 2 digits) | 26 for 2026 | | MINOR | Minor version | 0 | | PATCH | Patch version | 0 |

Example: 126.0.0 = Major version 1, released in 2026, minor 0, patch 0

This format allows you to quickly identify both the major version and the year of release at a glance.

Style Guide

Conventions for contributing to this project. All rules are enforced by code review; Biome handles formatting and lint.

Exports

• Named exports only — no export default. Every module uses export function, export const, or export type.
• import type — always use import type for type-only imports.
• .js extensions — all relative imports use explicit .js extensions (ESM requirement).

File Structure

src/
├── app/              # Entry points, root component, providers wrapper
├── components/       # React components (PascalCase directories)
│   └── MyComponent/
│       ├── index.tsx
│       ├── MyComponent.types.ts
│       └── MyComponent.test.tsx
├── hooks/            # Custom hooks (camelCase directories)
│   └── useMyHook/
│       ├── index.ts
│       ├── useMyHook.types.ts
│       └── useMyHook.test.tsx
├── providers/        # React context providers (PascalCase directories)
│   └── MyProvider/
│       ├── index.tsx
│       ├── MyProvider.types.ts
│       └── MyProvider.test.tsx
├── types/            # Shared type definitions (PascalCase directories)
│   └── MyType/
│       ├── index.ts
│       └── MyType.test-d.ts
└── utils/            # Pure utility functions (camelCase directories)
    └── myUtil/
        ├── index.ts
        └── myUtil.test.ts

Components & Providers

• Components use function declarations: export function MyComponent(props: MyComponentProps) {} (or arrow syntax for shorter ones).
• Providers use React.FC arrow syntax: export const MyProvider: React.FC<Props> = ({ children }) => {}
• Props are defined in a co-located .types.ts file using the interface or type keyword.
• Components receive data via props — never read global state directly if avoidable.

Types

• Use type for data shapes and unions. Use interface for component props.
• Shared types live in src/types/TypeName/index.ts with a co-located TypeName.test-d.ts.
• Local types live in co-located .types.ts files — never inline in implementation files.
• No duplicate type definitions — import from the canonical source.
• Runtime constants must not live in src/types/ — use .consts.ts files.

Constants

• Named constants go in .consts.ts files (e.g., useMyHook.consts.ts).
• No magic numbers in implementation files — extract to named constants.

Testing

• Every module has a co-located test file.
• Components: ComponentName.test.tsx
• Hooks: hookName.test.tsx
• Utils: utilName.test.ts
• Types: TypeName.test-d.ts (type-level tests using expectTypeOf/assertType)

License

ISC