pughost 0.0.1

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Victor Durosaro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# pughost
+
+> **Localhost is a lie. Test in reality.**
+
+[![npm version](https://img.shields.io/npm/v/pughost.svg)](https://www.npmjs.com/package/pughost)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Your API works flawlessly on localhost. Then it hits production—users on 3G in Lagos, satellite connections in rural areas, congested airport WiFi—and everything breaks. Timeouts, race conditions, spinners that never stop.
+
+**Pughost** injects real-world network chaos into your local development. Find the bugs before your users do.
+
+## What It Does
+
+Pughost is a network simulation layer between your local client and server. It introduces:
+- **Latency** — delayed responses (3G, satellite)
+- **Jitter** — variable delays (unstable connections)
+- **Bandwidth limits** — throttled data transfer
+- **Packet loss** — dropped connections
+
+## Installation
+
+```bash
+npm install -g pughost
+```
+
+Automatically downloads the correct binary for your OS (macOS, Linux, Windows) and architecture (x64, arm64). No manual setup required.
+
+## Quick Start
+
+**1. Initialize** — Generate a config file in your project:
+
+```bash
+pughost init
+```
+
+This creates `pughost.json`:
+
+```json
+{
+  "upstream": "localhost:3000",
+  "proxyPort": 3001,
+  "scenarios": {
+    "mobile_3g_slow": { "latency": 1000, "jitter": 500, "bandwidth": 50 },
+    "wifi_cafe_crowded": { "latency": 100, "jitter": 800, "packet_loss": 0.05 },
+    "satellite_link": { "latency": 800, "bandwidth": 1000 }
+  }
+}
+```
+
+**2. Start your backend** — Run your server on its normal port (e.g., 3000).
+
+**3. Activate chaos** — Start the proxy with a scenario:
+
+```bash
+pughost start -s mobile_3g_slow
+```
+
+**4. Test through the proxy** — Point your client to `http://localhost:3001` instead of `:3000`.
+
+| Endpoint | Behavior |
+|----------|----------|
+| `localhost:3000` | Normal (dev mode) |
+| `localhost:3001` | Chaos (reality mode) |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `pughost init` | Create `pughost.json` config file |
+| `pughost list` | Show available scenarios |
+| `pughost start -s <name>` | Start proxy with scenario |
+| `pughost --help` | Show all commands |
+
+## Scenario Parameters
+
+| Parameter | Unit | Description |
+|-----------|------|-------------|
+| `latency` | ms | Base delay added to responses |
+| `jitter` | ms | Random variance in latency |
+| `bandwidth` | kbps | Max data transfer rate |
+| `packet_loss` | 0.0–1.0 | Probability of connection drop |
+
+## Use Cases
+
+- **Mobile app testing** — Simulate 3G/4G conditions against your local API
+- **Emerging markets** — Test for users in Nigeria, India, Indonesia
+- **Resilience testing** — Verify timeout handling, retry logic, loading states
+- **QA workflows** — Consistent network conditions for bug reproduction
+
+## How It Works
+
+Pughost wraps [Toxiproxy](https://github.com/Shopify/toxiproxy) (by Shopify) and manages its lifecycle automatically. You get battle-tested chaos engineering without the setup complexity.
+
+## Requirements
+
+- Node.js >= 18
+- Internet access on first install (downloads Toxiproxy binary)
+
+## License
+
+MIT © Victor Durosaro

package/cli.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TOXIPROXY_API = 'http://localhost:8474';
+
+const program = new Command();
+
+program
+  .name('pughost')
+  .description('Localhost is a Lie. Test in Reality.')
+  .version('0.0.1');
+
+const getBinaryPath = () => {
+  const platform = process.platform;
+  const ext = platform === 'win32' ? '.exe' : '';
+  const binPath = path.join(__dirname, 'bin', `toxiproxy-server${ext}`);
+  
+  if (!fs.existsSync(binPath)) {
+    console.error(`Critical: Engine not found at ${binPath}`);
+    console.error(`Run 'npm install' to fix.`);
+    process.exit(1);
+  }
+  return binPath;
+};
+
+const waitForToxiproxy = async (retries = 10) => {
+  for (let i = 0; i < retries; i++) {
+    try {
+      const res = await fetch(`${TOXIPROXY_API}/version`);
+      if (res.ok) return true;
+    } catch (e) {
+      await new Promise(r => setTimeout(r, 200));
+    }
+  }
+  return false;
+};
+
+let proxyProcess = null;
+const cleanup = () => {
+  if (proxyProcess) {
+    console.log('\nShutting Pughost down...');
+    proxyProcess.kill();
+    proxyProcess = null;
+  }
+  process.exit();
+};
+
+process.on('SIGINT', cleanup);
+process.on('SIGTERM', cleanup);
+
+program.command('init')
+  .description('Generate configuration file')
+  .action(() => {
+    const configPath = path.join(process.cwd(), 'pughost.json');
+    if (fs.existsSync(configPath)) {
+      console.error('Error: pughost.json already exists.');
+      process.exit(1);
+    }
+    const defaultConfig = {
+      upstream: "localhost:3000",
+      proxyPort: 3001,
+      scenarios: {
+        mobile_3g_slow: { latency: 1000, jitter: 500, bandwidth: 50 },
+        wifi_cafe_crowded: { latency: 100, jitter: 800, packet_loss: 0.05 },
+        satellite_link: { latency: 800, bandwidth: 1000 }
+      }
+    };
+    fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
+    console.log('Created pughost.json');
+  });
+
+program.command('list')
+  .description('List available scenarios')
+  .action(() => {
+    const configPath = path.join(process.cwd(), 'pughost.json');
+    if (!fs.existsSync(configPath)) {
+      console.error('No config found. Run "pughost init" first.');
+      process.exit(1);
+    }
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    console.log('\nAvailable Scenarios:');
+    Object.keys(config.scenarios).forEach(key => {
+      console.log(` - ${key}`);
+    });
+    console.log('');
+  });
+
+program.command('start')
+  .description('Start the proxy with a scenario')
+  .requiredOption('-s, --scenario <name>', 'Name of scenario')
+  .action(async (options) => {
+    const configPath = path.join(process.cwd(), 'pughost.json');
+    if (!fs.existsSync(configPath)) {
+      console.error('Error: pughost.json not found.');
+      process.exit(1);
+    }
+    
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    const scenario = config.scenarios[options.scenario];
+
+    if (!scenario) {
+      console.error(`Error: Scenario "${options.scenario}" not found.`);
+      process.exit(1);
+    }
+
+    console.log('pughost active...');
+    const binPath = getBinaryPath();
+    proxyProcess = spawn(binPath, [], { stdio: 'pipe' }); 
+    
+    proxyProcess.stderr.on('data', (data) => {
+      if (data.toString().includes('address already in use')) {
+        console.error('Error: Port 8474 is in use. Is Pughost already running?');
+        cleanup();
+      }
+    });
+
+    const ready = await waitForToxiproxy();
+    if (!ready) {
+      console.error('Error: Pughost failed to start.');
+      cleanup();
+    }
+
+    try {
+      await fetch(`${TOXIPROXY_API}/proxies/pughost`, { method: 'DELETE' }).catch(() => {});
+      const createRes = await fetch(`${TOXIPROXY_API}/proxies`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          name: 'pughost',
+          listen: `localhost:${config.proxyPort}`,
+          upstream: config.upstream,
+          enabled: true
+        })
+      });
+
+      if (!createRes.ok) throw new Error(`Failed to create proxy: ${createRes.statusText}`);
+
+      console.log(`chaos config: ${options.scenario}`);
+      
+      const toxics = [];
+      if (scenario.latency) toxics.push({ type: 'latency', attributes: { latency: scenario.latency, jitter: scenario.jitter || 0 } });
+      if (scenario.bandwidth) toxics.push({ type: 'bandwidth', attributes: { rate: scenario.bandwidth } });
+      if (scenario.packet_loss) toxics.push({ type: 'timeout', toxicity: scenario.packet_loss, attributes: { timeout: 0 } });
+
+      for (const toxic of toxics) {
+        toxic.stream = 'downstream'; 
+        
+        const res = await fetch(`${TOXIPROXY_API}/proxies/pughost/toxics`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(toxic)
+        });
+        
+        if (!res.ok) {
+           console.warn(`Failed to apply toxic ${toxic.type}: ${res.statusText}`);
+        }
+      }
+
+      console.log('\nProxy Live:');
+      console.log(`Target:   ${config.upstream}`);
+      console.log(`Proxy:    http://localhost:${config.proxyPort}\n`);
+      console.log('Press Ctrl+C to stop.\n');
+
+    } catch (err) {
+      console.error('Configuration Error:', err.message);
+      cleanup();
+    }
+  });
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "pughost",
+  "version": "0.0.1",
+  "description": "Production Parity for Local Development",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "postinstall": "node scripts/install.js",
+    "link": "npm link"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/psyberpath/pughost.git"
+  },
+  "keywords": [
+    "chaos-engineering",
+    "network",
+    "latency",
+    "jitter",
+    "toxiproxy",
+    "simulation",
+    "dx"
+  ],
+  "author": "Victor Durosaro",
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/psyberpath/pughost/issues"
+  },
+  "homepage": "https://github.com/psyberpath/pughost#readme",
+  "bin": {
+    "pughost": "./cli.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^14.0.2"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,97 @@
+import fs from 'fs';
+import path from 'path';
+import https from 'https';
+import { fileURLToPath } from 'url';
+
+const TOXIPROXY_VERSION = 'v2.11.0';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const BIN_PATH = path.join(__dirname, '..', 'bin');
+
+const getPlatform = () => {
+  switch (process.platform) {
+    case 'darwin': return 'darwin';
+    case 'linux': return 'linux';
+    case 'win32': return 'windows';
+    default:
+      console.error(`Unsupported platform: ${process.platform}`);
+      process.exit(1);
+  }
+};
+
+const getArchitecture = (platform) => {
+  const arch = process.arch;
+
+  if (platform === 'darwin' && arch === 'arm64') return 'arm64';
+  if (platform === 'darwin' && arch === 'x64') return 'amd64';
+
+  switch (arch) {
+    case 'x64': return 'amd64';
+    case 'arm64': return 'arm64';
+    case 'ia32': return '386';
+    default:
+      console.error(`Unsupported architecture: ${arch}`);
+      process.exit(1);
+  }
+};
+
+const downloadFile = (url, dest) => {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+    console.log(`Downloading from: ${url}`); 
+
+    const request = https.get(url, (response) => {
+      if (response.statusCode === 302 || response.statusCode === 301) {
+        return downloadFile(response.headers.location, dest).then(resolve).catch(reject);
+      }
+      if (response.statusCode !== 200) {
+        return reject(new Error(`Failed to download: ${response.statusCode}`));
+      }
+      response.pipe(file);
+      file.on('finish', () => {
+        file.close(() => resolve());
+      });
+    });
+
+    request.on('error', (err) => {
+      fs.unlink(dest, () => {});
+      reject(err);
+    });
+  });
+};
+
+const install = async () => {
+  const platform = getPlatform();
+  const architecture = getArchitecture(platform);
+  const ext = platform === 'windows' ? '.exe' : '';
+  
+  const binaryName = `toxiproxy-server-${platform}-${architecture}${ext}`;
+  const downloadUrl = `https://github.com/Shopify/toxiproxy/releases/download/${TOXIPROXY_VERSION}/${binaryName}`;
+  const finalPath = path.join(BIN_PATH, `toxiproxy-server${ext}`);
+
+  console.log(`\nPughost Installer`);
+  console.log(`††††††††††††††††††††††††`);
+  console.log(`Detected: ${platform} (${process.arch})`);
+  console.log(`Fetching engine: ${TOXIPROXY_VERSION}...`);
+  
+  if (!fs.existsSync(BIN_PATH)) {
+    fs.mkdirSync(BIN_PATH, { recursive: true });
+  }
+
+  try {
+    await downloadFile(downloadUrl, finalPath);
+    console.log(`Download complete.`);
+    
+    if (platform !== 'windows') {
+      fs.chmodSync(finalPath, '755');
+      console.log(`Permissions set.`);
+    }
+
+    console.log(`Ready. Run 'pughost --help' to start.\n`);
+  } catch (error) {
+    console.error(`Installation failed: ${error.message}`);
+    process.exit(1);
+  }
+};
+
+install();