phantomback 1.0.3 → 2.0.0

package/README.md

@@ -284,14 +284,59 @@ curl http://localhost:3777/api/users \
 
 ---
 
+## Reality Mode — Chaos Engineering
+
+Test your frontend's resilience by simulating real-world production failures.
+
+Enable in `phantom.config.js`:
+
+```js
+export default {
+  // ...
+  chaos: {
+    enabled: true,
+    latency:            { min: 200, max: 5000 }, // latency jitter range (ms)
+    failureRate:        0.1,                      // 10% random 5xx responses
+    errorCodes:         [500, 502, 503, 504],
+    connectionDropRate: 0.02,                     // 2% abrupt connection drops
+    corruptionRate:     0.02,                     // 2% malformed JSON
+    timeoutRate:        0.03,                     // 3% hanging responses
+    scenarios:          ['latency', 'failure', 'drop', 'corruption', 'timeout'],
+  },
+};
+```
+
+Or enable instantly from the CLI:
+
+```bash
+phantomback start --chaos                           # enable with defaults
+phantomback start --chaos --chaos-failure 0.2      # 20% failure rate
+phantomback start --chaos --chaos-latency 500,3000 # 500–3000 ms jitter
+```
+
+| Scenario | Config Key | Description |
+|---|---|---|
+| `latency` | `latency` | Injects random delay on ~30% of requests |
+| `failure` | `failureRate` | Returns a random 5xx error |
+| `drop` | `connectionDropRate` | Abruptly closes the TCP connection |
+| `corruption` | `corruptionRate` | Sends malformed / partial JSON |
+| `timeout` | `timeoutRate` | Hangs the response for ~30 seconds |
+
+> **Full guide →** [phantombackxdocs.vercel.app/docs/reality-mode](https://phantombackxdocs.vercel.app/docs/reality-mode)
+
+---
+
 ## CLI Reference
 
 ```bash
-phantomback start              # start with phantom.config.js
-phantomback start --zero       # zero-config demo mode
-phantomback start --port 4000  # custom port
-phantomback start --config ./my-api.config.js
-phantomback init               # generate starter config
+phantomback start                              # start with phantom.config.js
+phantomback start --zero                       # zero-config demo mode
+phantomback start --port 4000                  # custom port
+phantomback start --config ./my-api.config.js  # custom config path
+phantomback start --chaos                      # enable Reality Mode
+phantomback start --chaos --chaos-failure 0.2  # 20% failure rate
+phantomback start --chaos --chaos-latency 200,5000  # latency jitter range
+phantomback init                               # generate starter config
 phantomback --help
 ```
 

package/bin/phantomback.js

@@ -23,6 +23,9 @@ program
   .option('--prefix <prefix>', 'API route prefix', '/api')
   .option('-c, --config <path>', 'Path to config file')
   .option('-z, --zero', 'Zero-config mode: generate a full demo backend')
+  .option('--chaos', 'Enable Reality Mode (chaos engineering)')
+  .option('--chaos-failure <rate>', 'Failure rate for Reality Mode (0-1)', parseFloat)
+  .option('--chaos-latency <range>', 'Latency range in ms (e.g. "200,5000")')
   .action(async (options) => {
     const { startCommand } = await import('../src/cli/commands.js');
     await startCommand(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phantomback",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "description": "Instant fake backend generator with smart responses & chaos engineering. Drop in your API schema → get a fully functional, stateful REST server with realistic data, auth, pagination, filtering, and Reality Mode for chaos testing.",
   "type": "module",
   "main": "./src/index.js",
@@ -27,6 +27,10 @@
     "development",
     "prototyping",
     "chaos-engineering",
+    "reality-mode",
+    "chaos-testing",
+    "fault-injection",
+    "resilience",
     "testing",
     "frontend",
     "faker",

package/src/cli/commands.js

@@ -69,14 +69,24 @@ export default {
     },
   },
 
-  // Chaos Engineering (Reality Mode) — Phase 2
-  // chaos: {
-  //   enabled: true,
-  //   jitter: { min: 100, max: 3000 },
-  //   failureRate: 0.1,
-  //   duplicateRate: 0.05,
-  //   connectionDropRate: 0.02,
-  // },
+  // Chaos Engineering (Reality Mode)
+  chaos: {
+    enabled: false,
+    // Latency jitter range (ms) — random delays injected on ~30% of requests
+    latency: { min: 200, max: 5000 },
+    // Probability (0-1) of returning a random 5xx error
+    failureRate: 0.1,
+    // HTTP error codes used for random failures
+    errorCodes: [500, 502, 503, 504],
+    // Probability of abruptly dropping the connection
+    connectionDropRate: 0.02,
+    // Probability of sending malformed/partial JSON
+    corruptionRate: 0.02,
+    // Probability of request hanging (30s timeout)
+    timeoutRate: 0.03,
+    // Which chaos scenarios to activate
+    scenarios: ['latency', 'failure', 'drop', 'corruption', 'timeout'],
+  },
 };
 `;
 
@@ -114,6 +124,31 @@ export async function startCommand(options) {
   if (options.port) config.port = parseInt(options.port, 10);
   if (options.prefix) config.prefix = options.prefix;
 
+  // Reality Mode (Chaos) CLI overrides
+  if (options.chaos) {
+    config.chaos = config.chaos || {};
+    config.chaos.enabled = true;
+  }
+  if (options.chaosFailure !== undefined) {
+    config.chaos = config.chaos || {};
+    config.chaos.enabled = true;
+    const rate = options.chaosFailure;
+    if (rate < 0 || rate > 1) {
+      logger.warn('--chaos-failure must be between 0 and 1. Clamping to valid range.');
+    }
+    config.chaos.failureRate = Math.max(0, Math.min(1, rate));
+  }
+  if (options.chaosLatency) {
+    config.chaos = config.chaos || {};
+    config.chaos.enabled = true;
+    const parts = options.chaosLatency.split(',').map(Number);
+    if (parts.length === 2 && !isNaN(parts[0]) && !isNaN(parts[1]) && parts[0] >= 0 && parts[1] >= parts[0]) {
+      config.chaos.latency = { min: parts[0], max: parts[1] };
+    } else {
+      logger.warn('Invalid --chaos-latency format. Expected "min,max" (e.g. "200,5000"). Using defaults.');
+    }
+  }
+
   // Check if using defaults (no config found and no resources)
   if (Object.keys(config.resources).length === 0) {
     logger.warn('No config found and no resources defined. Using zero-config defaults.');

package/src/features/chaos.js

@@ -0,0 +1,468 @@
+/**
+ * Reality Mode — Chaos Engineering Middleware for PhantomBack
+ *
+ * Simulates real-world production instability during development:
+ *   • Latency spikes (jitter)
+ *   • Random HTTP failures (5xx errors)
+ *   • Connection drops (socket destruction)
+ *   • Response corruption (malformed JSON)
+ *   • Request timeouts (hanging responses)
+ *   • Out-of-order response delays
+ *
+ * Configuration:
+ *   chaos: {
+ *     enabled: true,
+ *     latency:            { min: 200, max: 5000 },
+ *     failureRate:        0.1,
+ *     errorCodes:         [500, 502, 503, 504],
+ *     connectionDropRate: 0.02,
+ *     corruptionRate:     0.02,
+ *     timeoutRate:        0.03,
+ *     scenarios:          ['latency', 'failure', 'drop', 'corruption', 'timeout'],
+ *   }
+ */
+
+import { logger } from '../utils/logger.js';
+
+// ─── Default Chaos Configuration ─────────────────────────────────────────────
+
+const DEFAULT_CHAOS_CONFIG = {
+  enabled: false,
+  latency: { min: 200, max: 5000 },
+  failureRate: 0.1,
+  errorCodes: [500, 502, 503, 504],
+  connectionDropRate: 0.02,
+  corruptionRate: 0.02,
+  timeoutRate: 0.03,
+  scenarios: ['latency', 'failure', 'drop', 'corruption', 'timeout'],
+};
+
+// ─── Chaos Engine ────────────────────────────────────────────────────────────
+
+export class ChaosEngine {
+  constructor(config = {}) {
+    this.config = {
+      ...DEFAULT_CHAOS_CONFIG,
+      ...config,
+      latency: {
+        ...DEFAULT_CHAOS_CONFIG.latency,
+        ...(config.latency || {}),
+      },
+      errorCodes: config.errorCodes || DEFAULT_CHAOS_CONFIG.errorCodes,
+      scenarios: config.scenarios || DEFAULT_CHAOS_CONFIG.scenarios,
+    };
+    this.stats = {
+      totalRequests: 0,
+      chaosApplied: 0,
+      latencySpikes: 0,
+      failures: 0,
+      drops: 0,
+      corruptions: 0,
+      timeouts: 0,
+      startedAt: new Date().toISOString(),
+    };
+    this.paused = false;
+  }
+
+  /** Check if a specific scenario is enabled */
+  isScenarioEnabled(name) {
+    return this.config.enabled && !this.paused && this.config.scenarios.includes(name);
+  }
+
+  /** Roll the dice — returns true with the given probability (0-1) */
+  shouldTrigger(rate) {
+    return Math.random() < rate;
+  }
+
+  /** Generate a random latency value within the configured jitter range */
+  getJitter() {
+    const { min, max } = this.config.latency;
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+  }
+
+  /** Pick a random error code from the configured list */
+  getRandomErrorCode() {
+    const codes = this.config.errorCodes;
+    return codes[Math.floor(Math.random() * codes.length)];
+  }
+
+  /** Enable chaos at runtime */
+  enable() {
+    this.config.enabled = true;
+    this.paused = false;
+    logger.chaos('Reality Mode ENABLED');
+  }
+
+  /** Disable chaos at runtime */
+  disable() {
+    this.config.enabled = false;
+    logger.chaos('Reality Mode DISABLED');
+  }
+
+  /** Pause chaos temporarily */
+  pause() {
+    this.paused = true;
+    logger.chaos('Reality Mode PAUSED');
+  }
+
+  /** Resume chaos after pause */
+  resume() {
+    this.paused = false;
+    logger.chaos('Reality Mode RESUMED');
+  }
+
+  /** Update chaos configuration at runtime */
+  configure(newConfig) {
+    this.config = { ...this.config, ...newConfig };
+    logger.chaos('Configuration updated');
+  }
+
+  /** Get current status and stats */
+  getStatus() {
+    return {
+      enabled: this.config.enabled,
+      paused: this.paused,
+      active: this.config.enabled && !this.paused,
+      config: this.config,
+      stats: { ...this.stats },
+    };
+  }
+
+  /** Reset stats counters */
+  resetStats() {
+    this.stats = {
+      totalRequests: 0,
+      chaosApplied: 0,
+      latencySpikes: 0,
+      failures: 0,
+      drops: 0,
+      corruptions: 0,
+      timeouts: 0,
+      startedAt: new Date().toISOString(),
+    };
+  }
+}
+
+// ─── Chaos Scenarios ─────────────────────────────────────────────────────────
+
+const ERROR_MESSAGES = {
+  500: 'Internal Server Error — [Reality Mode] Simulated server crash',
+  502: 'Bad Gateway — [Reality Mode] Upstream service unavailable',
+  503: 'Service Unavailable — [Reality Mode] Server overloaded',
+  504: 'Gateway Timeout — [Reality Mode] Upstream request timed out',
+};
+
+/**
+ * Scenario: Latency Spike
+ * Adds a random delay to simulate network jitter or slow backends
+ */
+function applyLatencySpike(engine, _req, _res) {
+  if (!engine.isScenarioEnabled('latency')) return null;
+  if (!engine.shouldTrigger(0.3)) return null; // 30% of requests get jitter
+
+  const delay = engine.getJitter();
+  engine.stats.latencySpikes++;
+
+  return new Promise((resolve) => {
+    logger.chaos(`Latency spike: +${delay}ms`);
+    setTimeout(resolve, delay);
+  });
+}
+
+/**
+ * Scenario: Random Failure
+ * Returns a random 5xx error response
+ */
+function applyFailure(engine, _req, res) {
+  if (!engine.isScenarioEnabled('failure')) return false;
+  if (!engine.shouldTrigger(engine.config.failureRate)) return false;
+
+  const code = engine.getRandomErrorCode();
+  engine.stats.failures++;
+
+  logger.chaos(`Random failure: HTTP ${code}`);
+  res.status(code).json({
+    success: false,
+    error: {
+      status: code,
+      message: ERROR_MESSAGES[code] || `HTTP ${code} — [Reality Mode] Simulated failure`,
+      chaos: true,
+    },
+  });
+
+  return true;
+}
+
+/**
+ * Scenario: Connection Drop
+ * Destroys the socket mid-request to simulate network issues
+ */
+function applyConnectionDrop(engine, req, _res) {
+  if (!engine.isScenarioEnabled('drop')) return false;
+  if (!engine.shouldTrigger(engine.config.connectionDropRate)) return false;
+
+  engine.stats.drops++;
+  logger.chaos(`Connection drop: ${req.method} ${req.originalUrl}`);
+
+  // Destroy the underlying socket
+  if (req.socket) {
+    req.socket.destroy();
+  }
+
+  return true;
+}
+
+/**
+ * Scenario: Response Corruption
+ * Sends back malformed/partial JSON to test error handling
+ */
+function applyCorruption(engine, req, res) {
+  if (!engine.isScenarioEnabled('corruption')) return false;
+  if (!engine.shouldTrigger(engine.config.corruptionRate)) return false;
+
+  engine.stats.corruptions++;
+  logger.chaos(`Response corruption: ${req.method} ${req.originalUrl}`);
+
+  // Pick a random corruption type
+  const corruptions = [
+    // Truncated JSON
+    () => {
+      res.setHeader('Content-Type', 'application/json');
+      res.status(200).end('{"success":true,"data":[{"id":"abc","na');
+    },
+    // Invalid JSON
+    () => {
+      res.setHeader('Content-Type', 'application/json');
+      res.status(200).end('{success: true, data: undefined}');
+    },
+    // Empty body with 200
+    () => {
+      res.status(200).end('');
+    },
+    // Wrong content type
+    () => {
+      res.setHeader('Content-Type', 'text/html');
+      res.status(200).end('<html><body>Unexpected HTML response</body></html>');
+    },
+    // Partial response with wrong status
+    () => {
+      res.status(206).json({
+        success: true,
+        data: null,
+        error: { message: '[Reality Mode] Partial response — data truncated' },
+        chaos: true,
+      });
+    },
+  ];
+
+  const corrupt = corruptions[Math.floor(Math.random() * corruptions.length)];
+  corrupt();
+  return true;
+}
+
+/**
+ * Scenario: Request Timeout
+ * Holds the connection open without responding (simulates hung backend)
+ */
+function applyTimeout(engine, req, _res) {
+  if (!engine.isScenarioEnabled('timeout')) return false;
+  if (!engine.shouldTrigger(engine.config.timeoutRate)) return false;
+
+  engine.stats.timeouts++;
+  logger.chaos(`Request timeout: ${req.method} ${req.originalUrl} (hanging for 30s)`);
+
+  // Return a promise that resolves after 30s (or until client gives up)
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, 30000);
+
+    // Clean up if client disconnects
+    req.on('close', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+// ─── Main Chaos Middleware ───────────────────────────────────────────────────
+
+/**
+ * Create the Reality Mode middleware.
+ * This is the main entry point — attach to Express before resource routes.
+ *
+ * @param {ChaosEngine} engine - Chaos engine instance
+ * @returns {Function} Express middleware
+ */
+export function chaosMiddleware(engine) {
+  return async (req, res, next) => {
+    engine.stats.totalRequests++;
+
+    // Skip if chaos is disabled or paused
+    if (!engine.config.enabled || engine.paused) {
+      return next();
+    }
+
+    // Skip chaos control endpoints
+    if (req.path.includes('/_chaos')) {
+      return next();
+    }
+
+    // Skip health check
+    if (req.path.includes('/_health')) {
+      return next();
+    }
+
+    // Add chaos header so clients know Reality Mode is active
+    res.setHeader('X-PhantomBack-Chaos', 'active');
+
+    // ── Execute scenarios in priority order ──
+
+    // 1. Connection Drop (highest priority — immediate termination)
+    if (applyConnectionDrop(engine, req, res)) {
+      engine.stats.chaosApplied++;
+      return; // Socket destroyed, nothing more to do
+    }
+
+    // 2. Request Timeout (holds connection)
+    const timeoutResult = applyTimeout(engine, req, res);
+    if (timeoutResult instanceof Promise) {
+      engine.stats.chaosApplied++;
+      await timeoutResult;
+      // After timeout, destroy the socket (client likely already disconnected)
+      if (req.socket && !req.socket.destroyed) {
+        req.socket.destroy();
+      }
+      return;
+    }
+
+    // 3. Random Failure (returns error response)
+    if (applyFailure(engine, req, res)) {
+      engine.stats.chaosApplied++;
+      return;
+    }
+
+    // 4. Response Corruption (sends malformed data)
+    if (applyCorruption(engine, req, res)) {
+      engine.stats.chaosApplied++;
+      return;
+    }
+
+    // 5. Latency Spike (adds delay, then continues to real handler)
+    const latencyResult = applyLatencySpike(engine, req, res);
+    if (latencyResult instanceof Promise) {
+      engine.stats.chaosApplied++;
+      await latencyResult;
+    }
+
+    // If no chaos blocked the request, proceed normally
+    next();
+  };
+}
+
+// ─── Chaos Control Routes ────────────────────────────────────────────────────
+
+/**
+ * Register chaos control endpoints on the Express app.
+ * These allow runtime control of Reality Mode.
+ *
+ * Routes:
+ *   GET  {prefix}/_chaos            — Status & stats
+ *   POST {prefix}/_chaos/enable     — Enable chaos
+ *   POST {prefix}/_chaos/disable    — Disable chaos
+ *   POST {prefix}/_chaos/pause      — Pause chaos
+ *   POST {prefix}/_chaos/resume     — Resume chaos
+ *   POST {prefix}/_chaos/configure  — Update config
+ *   POST {prefix}/_chaos/reset      — Reset stats
+ */
+export function createChaosRoutes(app, engine, config) {
+  const prefix = config.prefix || '/api';
+
+  // GET /_chaos — status dashboard
+  app.get(`${prefix}/_chaos`, (_req, res) => {
+    const status = engine.getStatus();
+    res.json({
+      success: true,
+      message: status.active
+        ? '🔥 Reality Mode is ACTIVE — chaos is being injected!'
+        : '😴 Reality Mode is inactive',
+      ...status,
+    });
+  });
+
+  // POST /_chaos/enable
+  app.post(`${prefix}/_chaos/enable`, (_req, res) => {
+    engine.enable();
+    res.json({
+      success: true,
+      message: '🔥 Reality Mode ENABLED — brace yourself!',
+      ...engine.getStatus(),
+    });
+  });
+
+  // POST /_chaos/disable
+  app.post(`${prefix}/_chaos/disable`, (_req, res) => {
+    engine.disable();
+    res.json({
+      success: true,
+      message: '😴 Reality Mode DISABLED — back to calm waters',
+      ...engine.getStatus(),
+    });
+  });
+
+  // POST /_chaos/pause
+  app.post(`${prefix}/_chaos/pause`, (_req, res) => {
+    engine.pause();
+    res.json({
+      success: true,
+      message: '⏸️  Reality Mode PAUSED',
+      ...engine.getStatus(),
+    });
+  });
+
+  // POST /_chaos/resume
+  app.post(`${prefix}/_chaos/resume`, (_req, res) => {
+    engine.resume();
+    res.json({
+      success: true,
+      message: '▶️  Reality Mode RESUMED',
+      ...engine.getStatus(),
+    });
+  });
+
+  // POST /_chaos/configure — update chaos config at runtime
+  app.post(`${prefix}/_chaos/configure`, (req, res) => {
+    const updates = req.body;
+    if (!updates || typeof updates !== 'object') {
+      return res.status(400).json({
+        success: false,
+        error: { status: 400, message: 'Request body must be a JSON object with chaos config' },
+      });
+    }
+
+    engine.configure(updates);
+    res.json({
+      success: true,
+      message: '⚙️  Chaos configuration updated',
+      ...engine.getStatus(),
+    });
+  });
+
+  // POST /_chaos/reset — reset stats
+  app.post(`${prefix}/_chaos/reset`, (_req, res) => {
+    engine.resetStats();
+    res.json({
+      success: true,
+      message: '📊 Chaos stats reset',
+      ...engine.getStatus(),
+    });
+  });
+
+  // Log registered chaos routes
+  logger.chaos('Control endpoints registered:');
+  logger.route('GET', `${prefix}/_chaos`);
+  logger.route('POST', `${prefix}/_chaos/enable`);
+  logger.route('POST', `${prefix}/_chaos/disable`);
+  logger.route('POST', `${prefix}/_chaos/pause`);
+  logger.route('POST', `${prefix}/_chaos/resume`);
+  logger.route('POST', `${prefix}/_chaos/configure`);
+  logger.route('POST', `${prefix}/_chaos/reset`);
+}

package/src/index.js

@@ -64,4 +64,5 @@ export { createServer } from './server/createServer.js';
 export { parseConfig } from './schema/parser.js';
 export { DEFAULT_RESOURCES } from './schema/defaults.js';
 export { DataStore } from './data/store.js';
+export { ChaosEngine, chaosMiddleware, createChaosRoutes } from './features/chaos.js';
 export { logger } from './utils/logger.js';

package/src/schema/parser.js

@@ -16,6 +16,13 @@ export const DEFAULT_CONFIG = {
   },
   chaos: {
     enabled: false,
+    latency: { min: 200, max: 5000 },
+    failureRate: 0.1,
+    errorCodes: [500, 502, 503, 504],
+    connectionDropRate: 0.02,
+    corruptionRate: 0.02,
+    timeoutRate: 0.03,
+    scenarios: ['latency', 'failure', 'drop', 'corruption', 'timeout'],
   },
   resources: {},
   snapshot: false,
@@ -79,6 +86,8 @@ async function findConfigFile() {
  * Merge user config with defaults
  */
 function mergeConfig(userConfig) {
+  const userChaos = userConfig.chaos || {};
+
   return {
     ...DEFAULT_CONFIG,
     ...userConfig,
@@ -88,7 +97,13 @@ function mergeConfig(userConfig) {
     },
     chaos: {
       ...DEFAULT_CONFIG.chaos,
-      ...(userConfig.chaos || {}),
+      ...userChaos,
+      latency: {
+        ...DEFAULT_CONFIG.chaos.latency,
+        ...(userChaos.latency || {}),
+      },
+      errorCodes: userChaos.errorCodes || DEFAULT_CONFIG.chaos.errorCodes,
+      scenarios: userChaos.scenarios || DEFAULT_CONFIG.chaos.scenarios,
     },
   };
 }

package/src/server/createServer.js

@@ -1,6 +1,7 @@
 import { createExpressApp, addErrorHandling } from './middleware.js';
 import { createRouter } from './router.js';
 import { createAuthRoutes } from '../features/auth.js';
+import { ChaosEngine, chaosMiddleware, createChaosRoutes } from '../features/chaos.js';
 import { seedAll } from '../data/seeder.js';
 import { DataStore } from '../data/store.js';
 import { logger } from '../utils/logger.js';
@@ -15,6 +16,22 @@ export async function createServer(config) {
   const store = new DataStore();
   const app = createExpressApp(config);
 
+  // Initialize Reality Mode (Chaos Engine)
+  const chaosConfig = config.chaos || {};
+  const chaos = new ChaosEngine(chaosConfig);
+
+  // Register chaos control endpoints (before chaos middleware so they're never affected)
+  createChaosRoutes(app, chaos, config);
+
+  // Always mount chaos middleware so runtime toggling via /_chaos/enable works
+  // The middleware itself checks engine.config.enabled internally
+  app.use(chaosMiddleware(chaos));
+
+  // Print chaos banner if enabled at startup
+  if (chaosConfig.enabled) {
+    logger.chaosBanner(chaosConfig);
+  }
+
   // Seed data
   seedAll(config.resources, store);
 
@@ -43,6 +60,7 @@ export async function createServer(config) {
     app,
     server,
     store,
+    chaos,
     stop: () =>
       new Promise((resolve) => {
         server.close(resolve);
@@ -53,5 +71,6 @@ export async function createServer(config) {
       logger.info('Store has been reset and re-seeded');
     },
     getStore: () => store.toJSON(),
+    getChaos: () => chaos.getStatus(),
   };
 }

package/src/utils/logger.js

@@ -29,7 +29,7 @@ export const logger = {
     console.log(chalk.hex('#a78bfa').bold('  ╔═══════════════════════════════════════╗'));
     console.log(
       chalk.hex('#a78bfa').bold('  ║         ') +
-        chalk.white.bold('PhantomBack v1.0.0') +
+        chalk.white.bold('PhantomBack v2.0.0') +
         chalk.hex('#a78bfa').bold('         ║'),
     );
     console.log(
@@ -55,4 +55,70 @@ export const logger = {
     }
     console.log('');
   },
+
+  // ── Reality Mode (Chaos) Logging ──
+  chaos: (...args) =>
+    console.log(PREFIX, chalk.hex('#ff6b6b').bold('⚡CHAOS'), ...args),
+
+  chaosBanner: (config) => {
+    console.log('');
+    console.log(chalk.hex('#ff6b6b').bold('  ┌───────────────────────────────────────┐'));
+    console.log(
+      chalk.hex('#ff6b6b').bold('  │    ') +
+        chalk.white.bold('⚡ Reality Mode ACTIVE ⚡') +
+        chalk.hex('#ff6b6b').bold('        │'),
+    );
+    console.log(
+      chalk.hex('#ff6b6b').bold('  │  ') +
+        chalk.dim('Chaos is being injected into your API') +
+        chalk.hex('#ff6b6b').bold(' │'),
+    );
+    console.log(chalk.hex('#ff6b6b').bold('  └───────────────────────────────────────┘'));
+    console.log('');
+    if (config) {
+      const scenarios = config.scenarios || [];
+      console.log(PREFIX, chalk.hex('#ff6b6b').bold('Active Scenarios:'));
+      if (scenarios.includes('latency')) {
+        console.log(
+          PREFIX,
+          chalk.dim('  ├─'),
+          chalk.yellow('⏱  Latency Spikes'),
+          chalk.dim(`(${config.latency?.min || 200}–${config.latency?.max || 5000}ms)`),
+        );
+      }
+      if (scenarios.includes('failure')) {
+        console.log(
+          PREFIX,
+          chalk.dim('  ├─'),
+          chalk.red('💥 Random Failures'),
+          chalk.dim(`(${(config.failureRate || 0.1) * 100}% rate)`),
+        );
+      }
+      if (scenarios.includes('drop')) {
+        console.log(
+          PREFIX,
+          chalk.dim('  ├─'),
+          chalk.magenta('🔌 Connection Drops'),
+          chalk.dim(`(${(config.connectionDropRate || 0.02) * 100}% rate)`),
+        );
+      }
+      if (scenarios.includes('corruption')) {
+        console.log(
+          PREFIX,
+          chalk.dim('  ├─'),
+          chalk.hex('#ff9f43')('🧩 Response Corruption'),
+          chalk.dim(`(${(config.corruptionRate || 0.02) * 100}% rate)`),
+        );
+      }
+      if (scenarios.includes('timeout')) {
+        console.log(
+          PREFIX,
+          chalk.dim('  ├─'),
+          chalk.hex('#ee5a24')('⏳ Request Timeouts'),
+          chalk.dim(`(${(config.timeoutRate || 0.03) * 100}% rate)`),
+        );
+      }
+      console.log('');
+    }
+  },
 };