feat: add mock system with UI, matching engine, and hybrid mode

- Add --mock flag for pure mock mode (no local server needed)
- Auto-enable mock when --inspect is set and vice versa
- Mock CRUD operations with SQLite persistence (mock-db.ts)
- Request matching engine: exact, prefix, regex with priority (mock-matcher.ts)
- Serve mock responses via ResponseChannel with delay support (mock-handler.ts)
- Mock management UI at /mocks on inspector server
- Mock API routes (GET/POST/PUT/DELETE/PATCH /api/mocks)
- MOCK pill badge in inspector list view, banner in detail view
- Hybrid mode: mocked paths return mock data, others proxy normally
- Make --port optional (required only without --mock)

Author: abhisawesome

packages/client/src/@types/index.d.ts

@@ -1,10 +1,11 @@
 declare global {
     interface ClientInitializationOptions {
-        port: number;
+        port?: number;
         debug?: boolean;
         token?: string;
         inspect?: boolean;
         inspectPort?: number;
+        mock?: boolean;
     }
 
     interface TunnelRequestArgument {
@@ -88,6 +89,47 @@ declare global {
         avg_duration_ms: number | null;
     }
 
+    interface MockDefinition {
+        id: string;
+        method: string;
+        path: string;
+        path_type: 'exact' | 'prefix' | 'regex';
+        status_code: number;
+        headers: string;
+        body: string | null;
+        delay_ms: number;
+        priority: number;
+        enabled: number;
+        description: string | null;
+        created_at: string;
+        updated_at: string;
+    }
+
+    interface MockInsert {
+        method?: string;
+        path: string;
+        path_type?: string;
+        status_code?: number;
+        headers?: string;
+        body?: string;
+        delay_ms?: number;
+        priority?: number;
+        description?: string;
+    }
+
+    interface MockUpdate {
+        method?: string;
+        path?: string;
+        path_type?: string;
+        status_code?: number;
+        headers?: string;
+        body?: string;
+        delay_ms?: number;
+        priority?: number;
+        enabled?: number;
+        description?: string;
+    }
+
 }
 
 export {};

packages/client/src/index.ts

@@ -23,28 +23,51 @@ program
     .name('ProxyHub')
     .description("Test your API's with ease - Tunnel localhost to the internet")
     .version(version)
-    .requiredOption('-p, --port <port>', 'Port number for proxying', portNumberCustomValidationForCommander)
+    .option('-p, --port <port>', 'Port number for proxying', portNumberCustomValidationForCommander)
     .option('-d, --debug', 'Enable debug mode', false)
     .option('-t, --token <token>', 'Token for tunnel protection')
     .option('-i, --inspect', 'Enable request inspector', false)
+    .option('-m, --mock', 'Enable mock mode', false)
     .option('--inspect-port <port>', 'Port for inspector UI', parseInt);
 
 // Parse command line arguments
 program.parse(process.argv);
 
 // Get parsed options and check for env var fallback
-const parsedOpts = program.opts() as ClientInitializationOptions;
+const parsedOpts = program.opts() as ClientInitializationOptions & { port?: number };
 const options: ClientInitializationOptions = {
     port: parsedOpts.port,
     debug: parsedOpts.debug,
     token: parsedOpts.token || process.env.PROXYHUB_TOKEN,
     inspect: parsedOpts.inspect,
     inspectPort: parsedOpts.inspectPort,
+    mock: parsedOpts.mock,
 };
 
+// Validate: need either port or mock mode
+if (!options.port && !options.mock) {
+    console.error(chalk.red('Error: Either --port or --mock is required.'));
+    console.error(chalk.gray('  Use --port <port> to proxy to a local server'));
+    console.error(chalk.gray('  Use --mock for pure mock mode (no local server needed)'));
+    process.exit(1);
+}
+
+// Mock and inspect are co-dependent — enabling either enables both
+if (options.mock || options.inspect) {
+    options.mock = true;
+    options.inspect = true;
+}
+
 // Startup logging
 console.log('\nStarting ProxyHub Client...');
-console.log('Target:', chalk.cyan(`http://localhost:${options.port}`));
+if (options.port) {
+    console.log('Target:', chalk.cyan(`http://localhost:${options.port}`));
+}
+if (options.mock && options.port) {
+    console.log('Mode:', chalk.magenta('hybrid (mock + proxy)'));
+} else if (options.mock) {
+    console.log('Mode:', chalk.magenta('pure mock (no local server)'));
+}
 if (options.token) {
     console.log('Token protection:', chalk.green('enabled'));
 }
@@ -61,7 +84,6 @@ socketHandler(options);
 
 // Start inspector if enabled
 if (options.inspect) {
-    const inspectPort = options.inspectPort || options.port + 1000;
-    startInspector(inspectPort, options.port);
+    const inspectPort = options.inspectPort || (options.port ? options.port + 1000 : 3001);
+    startInspector(inspectPort, options.port, { mock: options.mock });
 }
-

packages/client/src/lib/db.ts

@@ -40,6 +40,23 @@ export function initDb(): void {
         CREATE INDEX IF NOT EXISTS idx_requests_method ON requests(method);
         CREATE INDEX IF NOT EXISTS idx_requests_status_code ON requests(status_code);
         CREATE INDEX IF NOT EXISTS idx_requests_path ON requests(path);
+
+        CREATE TABLE IF NOT EXISTS mocks (
+            id          TEXT PRIMARY KEY,
+            method      TEXT NOT NULL DEFAULT '*',
+            path        TEXT NOT NULL,
+            path_type   TEXT NOT NULL DEFAULT 'exact',
+            status_code INTEGER NOT NULL DEFAULT 200,
+            headers     TEXT NOT NULL DEFAULT '{}',
+            body        TEXT,
+            delay_ms    INTEGER NOT NULL DEFAULT 0,
+            priority    INTEGER NOT NULL DEFAULT 0,
+            enabled     INTEGER NOT NULL DEFAULT 1,
+            description TEXT,
+            created_at  TEXT NOT NULL,
+            updated_at  TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_mocks_enabled ON mocks(enabled);
     `);
 
     // Migrate: add response_body column if missing (existing DBs)
@@ -57,7 +74,7 @@ export function closeDb(): void {
     }
 }
 
-function getDb(): Database.Database {
+export function getDb(): Database.Database {
     if (!db) throw new Error('Database not initialized. Call initDb() first.');
     return db;
 }