{"_id":"@burhanamin/webscout","name":"@burhanamin/webscout","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@burhanamin/webscout","version":"1.0.0","description":"Terminal performance & error regression detector. Wraps any local app, logs API + browser metrics, runs Lighthouse, flags regressions with commit-blame.","bin":{"wpd":"bin/wpd.js"},"engines":{"node":">=24.0.0"},"dependencies":{"commander":"^12.1.0","http-proxy":"^1.18.1","lighthouse":"^12.2.1"},"keywords":["performance","monitoring","regression","lighthouse","web-vitals","cli"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/BurhanAmin/WebScout.git","directory":"wpd-cli"},"bugs":{"url":"https://github.com/BurhanAmin/WebScout/issues"},"homepage":"https://github.com/BurhanAmin/WebScout#readme","gitHead":"0600654e5719570b8221dedd0b8c66355799d26e","_id":"@burhanamin/webscout@1.0.0","_nodeVersion":"26.0.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-6jkWeO4gT6xHZ/NjDUXtoafPK1WvrsnYJ5OJ9iP8fZAa+ryNzl906fioQ7/xUKeu0a7lLEd4fIJ5e6NNr2NOrg==","shasum":"5fdcd0542abc8ea2c9dd9c9203fd20be170d9a00","tarball":"https://registry.npmjs.org/@burhanamin/webscout/-/webscout-1.0.0.tgz","fileCount":11,"unpackedSize":29730,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIB4Z5UiZGVlTEdO1l6cimuUvAWlrhFQU49WL1fR/r2fNAiBz/6y2H84xujc/xKu5fAQzr74wQI2vSDLyrD8lVvafWg=="}]},"_npmUser":{"name":"burhanamin","email":"aminburhanuddin2006@gmail.com"},"directories":{},"maintainers":[{"name":"burhanamin","email":"aminburhanuddin2006@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/webscout_1.0.0_1785230787921_0.6390295619951096"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-28T09:26:27.706Z","1.0.0":"2026-07-28T09:26:28.052Z","modified":"2026-07-28T09:26:28.290Z"},"maintainers":[{"name":"burhanamin","email":"aminburhanuddin2006@gmail.com"}],"description":"Terminal performance & error regression detector. Wraps any local app, logs API + browser metrics, runs Lighthouse, flags regressions with commit-blame.","homepage":"https://github.com/BurhanAmin/WebScout#readme","keywords":["performance","monitoring","regression","lighthouse","web-vitals","cli"],"repository":{"type":"git","url":"git+https://github.com/BurhanAmin/WebScout.git","directory":"wpd-cli"},"bugs":{"url":"https://github.com/BurhanAmin/WebScout/issues"},"license":"MIT","readme":"<div align=\"center\">\n\n# 🚀 WebScout\n\n### Terminal-first Web Performance & Regression Detection\n\n*Monitor performance. Detect regressions. Blame the commit.*\n\n![Node.js](https://img.shields.io/badge/Node.js-24+-339933?logo=node.js&logoColor=white)\n![SQLite](https://img.shields.io/badge/SQLite-Built--in-blue?logo=sqlite)\n![License](https://img.shields.io/badge/License-MIT-green)\n![Platform](https://img.shields.io/badge/macOS-Linux-Windows-orange)\n\n</div>\n\n---\n\n## ✨ Overview\n\nWebScout wraps your application the same way **Git wraps your repository**.\n\nInstead of modifying your codebase, simply run your application **through WebScout**.\n\nIt automatically:\n\n- 📊 Records every API request\n- ⚡ Measures real browser performance\n- 🔍 Runs Lighthouse audits\n- 📈 Detects regressions across commits\n- 🧠 Identifies the commit most likely responsible\n\nNo SDKs.\nNo code changes.\nNo external database.\n\nEverything stays local.\n\n---\n\n# 🎯 Why WebScout?\n\nMost performance bugs don't fail builds.\n\nInstead they quietly ship into production.\n\n- An endpoint becomes 30% slower\n- A JavaScript bundle grows by 500KB\n- A new API starts returning errors\n- Lighthouse score slowly drops\n\nNobody notices...\n\n...until users do.\n\nWebScout continuously records performance metrics tagged with Git commits and automatically tells you:\n\n> **\"This endpoint became 42% slower after commit `9f84c1a`.\"**\n\n---\n\n# ✨ Features\n\n| Feature | Description |\n|----------|-------------|\n| 🔄 Reverse Proxy | Transparently sits in front of your application |\n| 📊 API Monitoring | Logs every request, status code and latency |\n| 🌐 Real User Monitoring | Injects browser script automatically |\n| 🚨 Fetch Error Detection | Captures failed fetch/XHR requests |\n| 💡 Lighthouse Integration | Stores Core Web Vitals for every audit |\n| 📈 Regression Detection | Compares latest metrics with historical baseline |\n| 🧠 Commit Blame | Shows commits responsible for regressions |\n| 💾 SQLite Storage | Everything stored locally in `.wpd/metrics.db` |\n| 🛠 Zero Instrumentation | No code changes required |\n\n---\n\n# 🏗 Architecture\n\n```text\n                 Browser\n                    │\n                    ▼\n        ┌───────────────────────┐\n        │     WebScout Proxy    │\n        │        :5050          │\n        └──────────┬────────────┘\n                   │\n     Logs Requests │\n Injects RUM Script│\n                   ▼\n           Your App (:4000)\n\n                   │\n                   ▼\n        .wpd/metrics.db (SQLite)\n                   ▲\n                   │\n      Browser RUM Collector\n\n      wpd audit  ───► Lighthouse\n      wpd check  ───► Regression Engine\n      wpd blame  ───► Git History\n```\n\nEvery collected metric is tagged with the current Git commit hash.\n\n---\n\n# 📦 Requirements\n\n| Requirement | Version |\n|------------|---------|\n| Node.js | **24+** |\n| Git | Installed |\n| Chromium Browser | Chrome / Brave / Edge / Chromium |\n\nLighthouse requires a Chromium browser.\n\nIf WebScout cannot detect one automatically:\n\n```bash\nexport CHROME_PATH=\"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser\"\n```\n\n---\n\n# ⚙ Installation\n\n```bash\nnpm install -g @burhanamin/webscout\n```\n\nVerify installation:\n\n```bash\nwpd --help\n```\n\n---\n\n# 🚀 Quick Start\n\n### 1. Start monitoring\n\n```bash\nwpd run \"npm start\"\n```\n\nVisit\n\n```\nhttp://localhost:5050\n```\n\ninstead of your application's port.\n\n---\n\n### 2. Browse normally\n\nUse your application as you normally would.\n\nWebScout automatically collects:\n\n- Request latency\n- Status codes\n- Browser timings\n- Failed fetches\n\n---\n\n### 3. View metrics\n\n```bash\nwpd stats\n```\n\nExample:\n\n```\nAPI Metrics\n\nGET /api/users\nAverage: 38ms\n\nPOST /login\nAverage: 112ms\n\nBrowser Metrics\n\nFCP\n1.2s\n\nLoad Time\n2.4s\n\nFetch Errors\n0\n```\n\n---\n\n### 4. Run Lighthouse\n\n```bash\nwpd audit http://localhost:4000\n```\n\nStored metrics include:\n\n- Performance Score\n- FCP\n- LCP\n- TTI\n- Page Weight\n\n---\n\n### 5. Detect regressions\n\n```bash\nwpd check\n```\n\nExample output\n\n```\n✓ Baseline established\n\n⚠ Regression detected\n\nEndpoint:\n/api/report\n\nLatency:\n+198%\n\nCommit:\n9f84c1a\n```\n\n---\n\n### 6. Find the responsible commit\n\n```bash\nwpd blame\n```\n\nExample\n\n```\nRegression:\nLatency on /api/report\n\nLikely Cause\n\nCommit:\n9f84c1a\n\nFiles Changed\n\nsrc/report.js\nsrc/cache.js\n```\n\n---\n\n# 🧪 Example Workflow\n\n### Baseline\n\n```bash\nwpd run \"npm start\"\n```\n\nGenerate some traffic.\n\n---\n\n### Introduce a regression\n\n```bash\ngit commit -am \"Slow report endpoint\"\n```\n\n---\n\n### Generate traffic again\n\nRestart WebScout.\n\nUse the endpoint again.\n\n---\n\n### Detect it\n\n```bash\nwpd check\n```\n\nOutput\n\n```\nLatency regression\n\n/api/report\n\n+199%\n\nCommit:\n9f84c1a\n```\n\n---\n\n### Blame it\n\n```bash\nwpd blame\n```\n\nOutput\n\n```\nLikely responsible commit\n\n9f84c1a\n\nModified files\n\nsrc/report.js\n```\n\n---\n\n# ⚙ Configuration\n\nLocated in\n\n```\nsrc/regressionDetector.js\n```\n\n| Setting | Default |\n|----------|----------|\n| LATENCY_THRESHOLD | 20% |\n| WEIGHT_THRESHOLD | 20% |\n| BASELINE_WINDOW | 5 builds |\n\n---\n\n# 📁 Project Structure\n\n```text\nwpd-cli\n│\n├── bin\n│   └── wpd.js\n│\n├── src\n│   ├── proxy.js\n│   ├── injector.js\n│   ├── db.js\n│   ├── lighthouseRunner.js\n│   ├── regressionDetector.js\n│   └── commitBlame.js\n│\n├── assets\n│   └── rum.js\n│\n└── .wpd\n    └── metrics.db\n```\n\n---\n\n# 🗄 Database\n\n| Table | Purpose |\n|---------|---------|\n| `api_metrics` | Every proxied request |\n| `client_events` | Browser performance & fetch failures |\n| `build_metrics` | Lighthouse audit results |\n| `regressions` | Regression history |\n\n---\n\n# ⚠ Limitations\n\n- Designed for **local development**\n- Proxy buffers HTML responses for RUM injection\n- Commit blame depends on how frequently metrics are collected\n- Production monitoring would require a hosted collector\n\n---\n\n# 🛠 Tech Stack\n\n- Node.js 24+\n- Built-in `node:sqlite`\n- http-proxy\n- Commander.js\n- Lighthouse\n- Git\n\n---\n\n# 🛣 Roadmap\n\n- [ ] GitHub Actions integration\n- [ ] HTML performance reports\n- [ ] Live terminal dashboard\n- [ ] Flamegraph generation\n- [ ] Docker support\n- [ ] Production collector\n- [ ] Slack / Discord notifications\n- [ ] Performance trend graphs\n\n---\n\n# 📄 License\n\nMIT\n\n---\n\n<div align=\"center\">\n\n**WebScout makes performance regressions impossible to ignore.**\n\n</div>","readmeFilename":"README.md","_rev":"1-26c6fbbc5886462d4102059a680acb76"}