itworksbut 0.6.0 → 0.7.0

package/README.md

@@ -49,6 +49,8 @@ Common commands:
 
 ```sh
 itworksbut scan --path .
+itworksbut deps
+itworksbut stress
 itworksbut scan --fail-on high
 itworksbut scan --json
 itworksbut scan --sarif > itworksbut.sarif
@@ -63,11 +65,20 @@ itworksbut --version
 
 ```text
 itworksbut scan [options]
+itworksbut deps [options]
+itworksbut stress [options]
 ```
 
+- `deps`: Run only dependency checks, including lockfile hygiene, install-script risk, audit script availability, and outdated packages.
+- `stress`: Discover API endpoints and run a controlled Artillery load test against local or explicitly authorized targets.
 - `--path <path>`: Scan a specific project directory. Defaults to the current directory.
 - `--config <path>`: Use a custom config file. Defaults to `itworksbut.config.json` when present.
 - `--fail-on <severity>`: Exit with code `1` when a finding at or above the severity exists. Levels: `critical`, `high`, `medium`, `low`, `info`. Default: `low`.
+- `--target <url>`: Stress-test target. Defaults to `http://localhost:3000`. External targets require `--i-own-this`.
+- `--duration <seconds>`: Stress-test duration. Default `30`, maximum `300`.
+- `--arrival-rate <number>`: Arrival rate in requests per second. Default `5`, maximum `50`.
+- `--max-vusers <number>`: Virtual user cap. Default `50`, maximum `100`.
+- `--i-own-this`: Required for non-local stress-test targets.
 - `--json`: Print machine-readable JSON only. No banner, colors, spinner, table, or extra text.
 - `--sarif`: Print SARIF JSON for GitHub Code Scanning. No banner, colors, spinner, table, or extra text.
 - `--todo`: Write an AI-ready `todo.md` into the scanned project with prioritized findings, fix prompts, and acceptance criteria.
@@ -119,6 +130,16 @@ itworksbut scan --report
 
 This writes `report.md` to the current working directory with check statuses, summaries, details, and recommendations.
 
+To run a controlled API stress test:
+
+```sh
+itworksbut stress
+itworksbut stress --target https://my-own-api.example --i-own-this
+itworksbut stress --report
+```
+
+`stress` only tests local targets by default. For external hosts, pass `--i-own-this` to confirm that you own the target or have explicit authorization. Mutating endpoints such as `POST`, `PUT`, `PATCH`, and `DELETE` are discovered but skipped automatically.
+
 ## GitHub Actions
 
 ```yaml

package/bin/itworksbut.js

@@ -11,6 +11,7 @@ import { reportJson } from '../src/reporters/jsonReporter.js';
 import { reportSarif } from '../src/reporters/sarifReporter.js';
 import { writeTodoReport } from '../src/reporters/todoReporter.js';
 import { writeMarkdownReport } from '../src/reporters/markdownReport.js';
+import { runStressCommand } from '../src/commands/stress.js';
 
 async function main() {
     const args = parseArgs(process.argv.slice(2));
@@ -25,7 +26,11 @@ async function main() {
         return 0;
     }
 
-    if (args.command !== 'scan') {
+    if (args.command === 'stress') {
+        return await runStressCommand(args);
+    }
+
+    if (!['scan', 'deps'].includes(args.command)) {
         printUsage();
         return 2;
     }
@@ -42,6 +47,7 @@ async function main() {
             configPath: args.config,
             failOn: args.failOn,
             verbose: args.verbose,
+            categories: args.command === 'deps' ? ['dependencies'] : undefined,
         });
         if (spinner) spinner.succeed('Scan complete. Now the receipts.');
     } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "itworksbut",
-    "version": "0.6.0",
+    "version": "0.7.0",
     "description": "Static CI checks for common security, repo, dependency, build, and deployment risks in JavaScript vibe coding projects.",
     "type": "module",
     "bin": {
@@ -36,6 +36,7 @@
     ],
     "license": "MIT",
     "dependencies": {
+        "artillery": "^2.0.30",
         "boxen": "^8.0.1",
         "chalk": "^5.6.2",
         "cli-table3": "^0.6.5",

package/src/cli/output.js

@@ -5,12 +5,19 @@ export function printUsage() {
 
 Usage:
   itworksbut scan [options]
+  itworksbut deps [options]
+  itworksbut stress [options]
 
 Options:
   --path <path>       Project path to scan. Defaults to current directory.
   --config <path>     Optional itworksbut.config.json path.
   --fail-on <level>   Exit 1 when findings meet or exceed this severity.
                      Levels: critical, high, medium, low, info. Default: low.
+  --target <url>      Stress-test target. Defaults to http://localhost:3000.
+  --duration <sec>    Stress-test duration. Default: 30, max: 300.
+  --arrival-rate <n>  Stress-test arrival rate. Default: 5, max: 50.
+  --max-vusers <n>    Stress-test virtual user cap. Default: 50, max: 100.
+  --i-own-this        Required to stress-test non-local targets.
   --json              Print machine-readable JSON.
   --sarif             Print SARIF for GitHub Code Scanning.
   --todo              Write an AI-ready todo.md to the scanned project.

package/src/cli/parseArgs.js

@@ -1,5 +1,5 @@
-const FLAG_WITH_VALUE = new Set(["--fail-on", "--config", "--path"]);
-const BOOLEAN_FLAGS = new Set(["--json", "--sarif", "--todo", "--report", "--verbose", "--help", "-h", "--version", "-v", "--no-color", "--no-banner", "--quiet"]);
+const FLAG_WITH_VALUE = new Set(["--fail-on", "--config", "--path", "--target", "--duration", "--arrival-rate", "--max-vusers"]);
+const BOOLEAN_FLAGS = new Set(["--json", "--sarif", "--todo", "--report", "--i-own-this", "--verbose", "--help", "-h", "--version", "-v", "--no-color", "--no-banner", "--quiet"]);
 
 export function parseArgs(argv) {
   const args = {
@@ -11,6 +11,11 @@ export function parseArgs(argv) {
     sarif: false,
     todo: false,
     report: false,
+    target: undefined,
+    duration: undefined,
+    arrivalRate: undefined,
+    maxVusers: undefined,
+    iOwnThis: false,
     verbose: false,
     noColor: false,
     noBanner: false,
@@ -50,6 +55,7 @@ export function parseArgs(argv) {
       if (token === "--sarif") args.sarif = true;
       if (token === "--todo") args.todo = true;
       if (token === "--report") args.report = true;
+      if (token === "--i-own-this") args.iOwnThis = true;
       if (token === "--verbose") args.verbose = true;
       if (token === "--no-color") args.noColor = true;
       if (token === "--no-banner") args.noBanner = true;
@@ -71,5 +77,9 @@ function assignValue(args, flag, value) {
   if (flag === "--fail-on") args.failOn = value;
   else if (flag === "--config") args.config = value;
   else if (flag === "--path") args.path = value;
+  else if (flag === "--target") args.target = value;
+  else if (flag === "--duration") args.duration = value;
+  else if (flag === "--arrival-rate") args.arrivalRate = value;
+  else if (flag === "--max-vusers") args.maxVusers = value;
   else throw new Error(`Unknown argument: ${flag}`);
 }

package/src/commands/stress.js

@@ -0,0 +1,114 @@
+import path from "node:path";
+import { validateStressOptions } from "../utils/targetSafety.js";
+import { discoverEndpoints } from "../stress/discoverEndpoints.js";
+import { createArtilleryConfig } from "../stress/stressConfig.js";
+import { runArtillery } from "../stress/artilleryRunner.js";
+import { parseArtilleryResult } from "../stress/stressResultParser.js";
+import { reportStressConsole } from "../stress/stressRenderer.js";
+import { writeStressMarkdownReport } from "../reporters/stressMarkdownReport.js";
+
+export async function runStressCommand(args, options = {}) {
+  if (args.todo || args.sarif) {
+    throw new Error("The stress command supports console output, --json, and --report.");
+  }
+
+  const result = await runStress({
+    rootPath: path.resolve(args.path || "."),
+    ...validateStressOptions(args)
+  }, options);
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    reportStressConsole(result, args);
+  }
+
+  if (args.report) {
+    const report = await writeStressMarkdownReport(result);
+    if (!args.json && !args.quiet) {
+      const verb = report.overwritten ? "Overwrote" : "Wrote";
+      process.stdout.write(`${verb} stress report: ${report.filePath}\n`);
+    }
+  }
+
+  return result.status === "fail" ? 1 : 0;
+}
+
+export async function runStress(options, runnerOptions = {}) {
+  const startedAt = new Date();
+  const discovery = await discoverEndpoints(options.rootPath);
+  const baseDetails = {
+    target: options.target,
+    duration: options.duration,
+    arrivalRate: options.arrivalRate,
+    maxVusers: options.maxVusers,
+    endpointsFound: discovery.endpoints.length,
+    safeEndpoints: discovery.safeEndpoints.length,
+    skippedEndpoints: discovery.skippedEndpoints,
+    startedAt: startedAt.toISOString()
+  };
+
+  if (discovery.endpoints.length === 0) {
+    return stressResult({
+      status: "skip",
+      summary: "No API endpoints found.",
+      details: {
+        ...baseDetails,
+        testedEndpoints: [],
+        warnings: 0,
+        failed: 0,
+        completedAt: new Date().toISOString()
+      }
+    });
+  }
+
+  if (discovery.safeEndpoints.length === 0) {
+    return stressResult({
+      status: "fail",
+      summary: "No safe GET/HEAD endpoints can be tested automatically.",
+      details: {
+        ...baseDetails,
+        testedEndpoints: [],
+        warnings: 0,
+        failed: 1,
+        completedAt: new Date().toISOString()
+      }
+    });
+  }
+
+  const config = createArtilleryConfig({
+    target: options.target,
+    duration: options.duration,
+    arrivalRate: options.arrivalRate,
+    maxVusers: options.maxVusers,
+    endpoints: discovery.safeEndpoints
+  });
+
+  const artillery = await runArtillery(config, {
+    rootPath: options.rootPath,
+    duration: options.duration,
+    ...runnerOptions
+  });
+  const parsed = parseArtilleryResult(artillery, discovery.safeEndpoints);
+
+  return stressResult({
+    status: parsed.status,
+    summary: parsed.summary,
+    details: {
+      ...baseDetails,
+      testedEndpoints: parsed.testedEndpoints,
+      warnings: parsed.warnings,
+      failed: parsed.failed,
+      artilleryError: parsed.error,
+      completedAt: new Date().toISOString()
+    }
+  });
+}
+
+function stressResult(result) {
+  return {
+    id: "stress-test",
+    title: "API stress test",
+    ...result
+  };
+}

package/src/core/scanner.js

@@ -7,11 +7,14 @@ import { packageInfo } from "./packageInfo.js";
 export async function scanProject(options = {}) {
   const startedAt = new Date();
   const context = await createContext(options);
+  const includedCategories = normalizeFilter(options.categories);
   const findings = [];
   const checkResults = [];
   const warnings = [];
 
   for (const check of checks) {
+    if (includedCategories && !includedCategories.has(check.category)) continue;
+
     if (context.config.checks[check.id] === false) {
       checkResults.push(normalizeCheckResult(check, {
         status: "skip",
@@ -75,6 +78,7 @@ export async function scanProject(options = {}) {
       version: packageInfo.version,
       rootPath: context.rootPath,
       packageName: context.packageJson?.name,
+      categories: includedCategories ? [...includedCategories] : undefined,
       packageManager: context.packageManager,
       gitAvailable: context.gitAvailable,
       filesScanned: context.allFiles.length,
@@ -84,3 +88,8 @@ export async function scanProject(options = {}) {
     }
   };
 }
+
+function normalizeFilter(values) {
+  if (!Array.isArray(values) || values.length === 0) return null;
+  return new Set(values.map((value) => String(value).trim()).filter(Boolean));
+}

package/src/reporters/stressMarkdownReport.js

@@ -0,0 +1,157 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const ANSI_PATTERN = /\u001B\[[0-?]*[ -/]*[@-~]/g;
+
+export async function writeStressMarkdownReport(result, options = {}) {
+  const filePath = options.filePath || path.join(options.directoryPath || process.cwd(), "stress-report.md");
+  let overwritten = false;
+
+  try {
+    await fs.access(filePath);
+    overwritten = true;
+  } catch {
+    overwritten = false;
+  }
+
+  await fs.writeFile(filePath, reportStressMarkdown(result), "utf8");
+  return { filePath, overwritten };
+}
+
+export function reportStressMarkdown(result) {
+  const details = result.details || {};
+  const tested = details.testedEndpoints || [];
+  const skipped = details.skippedEndpoints || [];
+
+  return stripAnsi(`${[
+    "# ItWorksBut Stress Report",
+    "",
+    `Generated: ${formatTimestamp(details.completedAt || new Date())}`,
+    "",
+    `Target: ${details.target || "unknown"}`,
+    `Duration: ${details.duration ?? "unknown"}s`,
+    `Arrival rate: ${details.arrivalRate ?? "unknown"} req/s`,
+    `Max virtual users: ${details.maxVusers ?? "unknown"}`,
+    "",
+    "## Summary",
+    "",
+    "| Metric | Value |",
+    "|---|---:|",
+    `| Endpoints found | ${details.endpointsFound || 0} |`,
+    `| Endpoints tested | ${tested.length} |`,
+    `| Endpoints skipped | ${skipped.length} |`,
+    `| Warnings | ${details.warnings || 0} |`,
+    `| Failed | ${details.failed || 0} |`,
+    "",
+    "## Tested Endpoints",
+    "",
+    renderTestedEndpoints(tested),
+    "",
+    "## Skipped Endpoints",
+    "",
+    renderSkippedEndpoints(skipped),
+    renderArtilleryError(details.artilleryError),
+    renderRecommendations(result),
+  ].filter((line) => line !== null && line !== undefined).join("\n")}\n`);
+}
+
+function renderTestedEndpoints(endpoints) {
+  if (!endpoints.length) return "None.";
+
+  return [
+    "| Method | Path | Status | p95 | p99 | Errors | Error Rate |",
+    "|---|---|---|---:|---:|---:|---:|",
+    ...endpoints.map((endpoint) => (
+      `| ${escapeTable(endpoint.method)} | ${escapeTable(endpoint.path)} | ${escapeTable(endpoint.status)} | ${formatMs(endpoint.p95)} | ${formatMs(endpoint.p99)} | ${endpoint.errors || 0} | ${formatPercent(endpoint.errorRate)} |`
+    ))
+  ].join("\n");
+}
+
+function renderSkippedEndpoints(endpoints) {
+  if (!endpoints.length) return "None.";
+
+  return [
+    "| Method | Path | Reason |",
+    "|---|---|---|",
+    ...endpoints.map((endpoint) => (
+      `| ${escapeTable(endpoint.method)} | ${escapeTable(endpoint.path)} | ${escapeTable(endpoint.reason)} |`
+    ))
+  ].join("\n");
+}
+
+function renderRecommendations(result) {
+  const details = result.details || {};
+  const recommendations = [];
+
+  if ((details.warnings || 0) > 0) {
+    recommendations.push("Review slow endpoints.");
+    recommendations.push("Add caching or pagination where needed.");
+  }
+  if ((details.failed || 0) > 0 || result.status === "fail") {
+    recommendations.push("Investigate failed requests before increasing load.");
+  }
+  if ((details.skippedEndpoints || []).some((endpoint) => endpoint.reason === "unsafe method")) {
+    recommendations.push("Test mutating endpoints manually in a safe staging environment.");
+  }
+  recommendations.push("Add rate limits before public deployment.");
+
+  return [
+    "",
+    "## Recommendations",
+    "",
+    ...unique(recommendations).map((recommendation) => `- ${recommendation}`),
+    ""
+  ].join("\n");
+}
+
+function renderArtilleryError(error) {
+  if (!error) return "";
+
+  return [
+    "",
+    "## Artillery Error",
+    "",
+    error,
+    ""
+  ].join("\n");
+}
+
+function formatTimestamp(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return String(value);
+
+  const pad = (number) => String(number).padStart(2, "0");
+  return [
+    date.getFullYear(),
+    "-",
+    pad(date.getMonth() + 1),
+    "-",
+    pad(date.getDate()),
+    " ",
+    pad(date.getHours()),
+    ":",
+    pad(date.getMinutes()),
+    ":",
+    pad(date.getSeconds())
+  ].join("");
+}
+
+function formatMs(value) {
+  return value === null || value === undefined ? "n/a" : `${Math.round(value)} ms`;
+}
+
+function formatPercent(value) {
+  return `${Number(value || 0).toFixed(Number.isInteger(value) ? 0 : 2).replace(/\.00$/, "")}%`;
+}
+
+function escapeTable(value) {
+  return stripAnsi(String(value ?? "unknown")).replace(/\|/g, "\\|");
+}
+
+function stripAnsi(value) {
+  return String(value).replace(ANSI_PATTERN, "");
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}

package/src/stress/artilleryRunner.js

@@ -0,0 +1,83 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { fileExists } from "../utils/fs.js";
+
+const execFileAsync = promisify(execFile);
+const TOOL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+export async function runArtillery(config, options = {}) {
+  if (options.execute) return await options.execute(config, options);
+
+  const rootPath = options.rootPath || process.cwd();
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "itworksbut-stress-"));
+  const configPath = path.join(tempDir, "artillery-config.json");
+  const outputPath = path.join(tempDir, "artillery-report.json");
+  await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+
+  const { command, args } = await resolveArtilleryCommand(rootPath, configPath, outputPath);
+  const timeout = Math.max(90_000, ((options.duration || 30) + 60) * 1000);
+
+  try {
+    const result = await execFileAsync(command, args, {
+      cwd: rootPath,
+      timeout,
+      maxBuffer: 10 * 1024 * 1024
+    });
+    return {
+      ok: true,
+      command,
+      args,
+      stdout: result.stdout || "",
+      stderr: result.stderr || "",
+      exitCode: 0,
+      report: await readJsonFile(outputPath)
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      command,
+      args,
+      stdout: error?.stdout || "",
+      stderr: error?.stderr || error?.message || "",
+      exitCode: error?.code ?? null,
+      signal: error?.signal,
+      report: await readJsonFile(outputPath)
+    };
+  }
+}
+
+async function resolveArtilleryCommand(rootPath, configPath, outputPath) {
+  const binaryName = process.platform === "win32" ? "artillery.cmd" : "artillery";
+  const toolBin = path.join(TOOL_ROOT, "node_modules", ".bin", binaryName);
+  if (await fileExists(toolBin)) {
+    return {
+      command: toolBin,
+      args: ["run", configPath, "--output", outputPath]
+    };
+  }
+
+  const projectBin = path.join(rootPath, "node_modules", ".bin", binaryName);
+  if (await fileExists(projectBin)) {
+    return {
+      command: projectBin,
+      args: ["run", configPath, "--output", outputPath]
+    };
+  }
+
+  return {
+    command: process.platform === "win32" ? "npm.cmd" : "npm",
+    args: ["exec", "--yes", "artillery", "--", "run", configPath, "--output", outputPath]
+  };
+}
+
+async function readJsonFile(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}

package/src/stress/discoverEndpoints.js

@@ -0,0 +1,200 @@
+import path from "node:path";
+import { DEFAULT_IGNORE } from "../core/config.js";
+import { walkProject } from "../core/fileWalker.js";
+import { readFileSafe } from "../utils/fs.js";
+
+const HTTP_METHODS = ["get", "head", "post", "put", "patch", "delete"];
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+const ROUTE_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
+const DISCOVERY_IGNORE = [
+  ...DEFAULT_IGNORE,
+  "test/**",
+  "tests/**",
+  "__tests__/**",
+  "**/*.test.js",
+  "**/*.test.ts",
+  "**/*.spec.js",
+  "**/*.spec.ts"
+];
+
+export async function discoverEndpoints(rootPath) {
+  const { textFiles } = await walkProject(rootPath, DISCOVERY_IGNORE);
+  return await discoverEndpointsFromFiles({
+    rootPath,
+    files: textFiles,
+    readFile: async (relativePath) => await readFileSafe(path.join(rootPath, relativePath))
+  });
+}
+
+export async function discoverEndpointsFromFiles({ rootPath, files, readFile }) {
+  const endpoints = [];
+
+  for (const file of files.filter(isSourceFile)) {
+    const content = await readFile(file);
+    if (content === null || content === undefined) continue;
+
+    endpoints.push(...discoverExpressEndpoints(file, content));
+    endpoints.push(...discoverFetchReferences(file, content));
+    endpoints.push(...discoverNextAppRouterEndpoints(file, content));
+    endpoints.push(...discoverNextPagesRouterEndpoints(file, content));
+  }
+
+  return classifyEndpoints(dedupeEndpoints(endpoints), rootPath);
+}
+
+export function classifyEndpoints(endpoints) {
+  const all = endpoints.map((endpoint) => {
+    const method = endpoint.method.toUpperCase();
+    const dynamic = isDynamicRoute(endpoint.path);
+    const unsafe = MUTATING_METHODS.has(method);
+    let status = "selected";
+    let reason;
+
+    if (unsafe) {
+      status = "skipped";
+      reason = "unsafe method";
+    } else if (dynamic) {
+      status = "skipped";
+      reason = "dynamic route requires parameter";
+    }
+
+    return {
+      ...endpoint,
+      method,
+      dynamic,
+      status,
+      reason
+    };
+  });
+
+  return {
+    status: all.length === 0 ? "skip" : "pass",
+    endpoints: all,
+    safeEndpoints: all.filter((endpoint) => endpoint.status === "selected"),
+    skippedEndpoints: all
+      .filter((endpoint) => endpoint.status === "skipped")
+      .map(({ method, path, reason, source, type }) => ({ method, path, reason, source, type }))
+  };
+}
+
+function discoverExpressEndpoints(file, content) {
+  const endpoints = [];
+  const methods = HTTP_METHODS.join("|");
+  const regex = new RegExp(`\\b(?:app|router|server)\\s*\\.\\s*(${methods})\\s*\\(\\s*(['"\`])([^'"\`]+)\\2`, "gi");
+  let match;
+
+  while ((match = regex.exec(content)) !== null) {
+    const routePath = normalizeRoutePath(match[3]);
+    if (!routePath) continue;
+    endpoints.push(endpoint(match[1], routePath, file, "express"));
+  }
+
+  return endpoints;
+}
+
+function discoverFetchReferences(file, content) {
+  const endpoints = [];
+  const regex = /\bfetch\s*\(\s*(['"`])(\/api\/[^'"`]+)\1/gi;
+  let match;
+
+  while ((match = regex.exec(content)) !== null) {
+    const routePath = normalizeRoutePath(match[2]);
+    if (!routePath) continue;
+    endpoints.push(endpoint("GET", routePath, file, "fetch-reference"));
+  }
+
+  return endpoints;
+}
+
+function discoverNextAppRouterEndpoints(file, content) {
+  const normalized = normalizeFilePath(file);
+  const match = normalized.match(/(?:^|\/)(?:src\/)?app\/api\/(.+)\/route\.(?:js|jsx|ts|tsx|mjs|cjs)$/);
+  if (!match) return [];
+
+  const routePath = normalizeRoutePath(`/api/${routeSegmentsToPath(match[1])}`);
+  const exportedMethods = discoverExportedRouteMethods(content);
+  const methods = exportedMethods.length > 0 ? exportedMethods : ["GET"];
+
+  return methods.map((method) => endpoint(method, routePath, file, "next-app-router"));
+}
+
+function discoverNextPagesRouterEndpoints(file, content) {
+  const normalized = normalizeFilePath(file);
+  const match = normalized.match(/(?:^|\/)(?:src\/)?pages\/api\/(.+)\.(?:js|jsx|ts|tsx|mjs|cjs)$/);
+  if (!match) return [];
+
+  const routePath = normalizeRoutePath(`/api/${routeSegmentsToPath(match[1])}`);
+  const guardedMethods = discoverMethodGuards(content);
+  const methods = guardedMethods.length > 0 ? guardedMethods : ["GET"];
+
+  return methods.map((method) => endpoint(method, routePath, file, "next-pages-router"));
+}
+
+function discoverExportedRouteMethods(content) {
+  const methods = new Set();
+  const regex = /\bexport\s+(?:async\s+)?function\s+(GET|HEAD|POST|PUT|PATCH|DELETE)\b/g;
+  let match;
+
+  while ((match = regex.exec(content)) !== null) {
+    methods.add(match[1]);
+  }
+
+  return [...methods];
+}
+
+function discoverMethodGuards(content) {
+  const methods = new Set();
+  const regex = /\b(?:req|request)\.method\s*(?:===|!==|==|!=)\s*['"`](GET|HEAD|POST|PUT|PATCH|DELETE)['"`]/gi;
+  let match;
+
+  while ((match = regex.exec(content)) !== null) {
+    methods.add(match[1].toUpperCase());
+  }
+
+  return [...methods];
+}
+
+function endpoint(method, routePath, file, type) {
+  return {
+    method: method.toUpperCase(),
+    path: routePath,
+    source: file,
+    type
+  };
+}
+
+function dedupeEndpoints(endpoints) {
+  const byKey = new Map();
+  for (const endpoint of endpoints) {
+    const key = `${endpoint.method.toUpperCase()} ${endpoint.path}`;
+    if (!byKey.has(key)) byKey.set(key, endpoint);
+  }
+  return [...byKey.values()].sort((a, b) => `${a.method} ${a.path}`.localeCompare(`${b.method} ${b.path}`));
+}
+
+function isSourceFile(file) {
+  const normalized = normalizeFilePath(file);
+  return ROUTE_EXTENSIONS.has(path.extname(normalized));
+}
+
+function normalizeFilePath(file) {
+  return String(file).replace(/\\/g, "/");
+}
+
+function normalizeRoutePath(value) {
+  if (!value || value.includes("${")) return null;
+  const pathValue = value.startsWith("/") ? value : `/${value}`;
+  return pathValue.replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+}
+
+function routeSegmentsToPath(value) {
+  return value
+    .split("/")
+    .filter(Boolean)
+    .map((segment) => segment.replace(/^\[(\.\.\.)?(.+)]$/, ":$2"))
+    .join("/");
+}
+
+function isDynamicRoute(routePath) {
+  return /(^|\/):[^/]+|\[[^/]+]|\*/.test(routePath);
+}

package/src/stress/stressConfig.js

@@ -0,0 +1,31 @@
+export function createArtilleryConfig({ target, duration, arrivalRate, maxVusers, endpoints }) {
+  const flow = endpoints.map((endpoint) => ({
+    [endpoint.method.toLowerCase()]: {
+      url: endpoint.path
+    }
+  }));
+
+  return {
+    config: {
+      target,
+      phases: [
+        {
+          duration,
+          arrivalRate,
+          maxVusers
+        }
+      ],
+      defaults: {
+        headers: {
+          "user-agent": "ItWorksBut Stress"
+        }
+      }
+    },
+    scenarios: [
+      {
+        name: "Discovered API endpoints",
+        flow
+      }
+    ]
+  };
+}

package/src/stress/stressRenderer.js

@@ -0,0 +1,80 @@
+import { getChalk } from "../cli/terminal.js";
+
+export function reportStressConsole(result, options = {}) {
+  const colors = getChalk(options);
+  const details = result.details || {};
+
+  if (!options.quiet) {
+    process.stdout.write(`${colors.bold("ItWorksBut Stress")}\n\n`);
+    process.stdout.write("Only run this against systems you own or are explicitly authorized to test.\n\n");
+    process.stdout.write(`Target: ${details.target}\n`);
+    process.stdout.write(`Duration: ${details.duration}s\n`);
+    process.stdout.write(`Arrival rate: ${details.arrivalRate} req/s\n`);
+    process.stdout.write(`Max virtual users: ${details.maxVusers}\n\n`);
+
+    writeDiscovery(details, colors);
+    writeEndpoints(details, colors);
+  }
+
+  writeSummary(result, colors);
+}
+
+function writeDiscovery(details, colors) {
+  const found = details.endpointsFound || 0;
+  const safe = details.safeEndpoints || 0;
+  const skipped = details.skippedEndpoints?.length || 0;
+  const unsafe = details.skippedEndpoints?.filter((endpoint) => endpoint.reason === "unsafe method").length || 0;
+  const dynamic = details.skippedEndpoints?.filter((endpoint) => endpoint.reason === "dynamic route requires parameter").length || 0;
+
+  process.stdout.write(`${colors.green("✓")} Endpoint discovery: ${found} ${found === 1 ? "endpoint" : "endpoints"} found\n`);
+  process.stdout.write(`${colors.green("✓")} Safe endpoints: ${safe} GET/HEAD ${safe === 1 ? "endpoint" : "endpoints"} selected\n`);
+  if (skipped > 0) {
+    process.stdout.write(`- Skipped: ${unsafe} unsafe methods, ${dynamic} dynamic routes\n`);
+  }
+  process.stdout.write("\n");
+}
+
+function writeEndpoints(details, colors) {
+  const testedEndpoints = details.testedEndpoints || [];
+  if (testedEndpoints.length === 0) {
+    process.stdout.write("Running Artillery: skipped\n\n");
+    return;
+  }
+
+  process.stdout.write("Running Artillery: complete\n\n");
+  for (const endpoint of testedEndpoints) {
+    const symbol = endpoint.status === "pass" ? colors.green("✓") : endpoint.status === "warn" ? colors.yellow("⚠") : colors.red("✕");
+    process.stdout.write(`${symbol} ${endpoint.method} ${endpoint.path}\n`);
+    process.stdout.write(`  p95: ${formatMs(endpoint.p95)}\n`);
+    process.stdout.write(`  p99: ${formatMs(endpoint.p99)}\n`);
+    process.stdout.write(`  errors: ${endpoint.errors}\n`);
+    process.stdout.write(`  error rate: ${formatPercent(endpoint.errorRate)}\n\n`);
+  }
+}
+
+function writeSummary(result, colors) {
+  const details = result.details || {};
+  const warnings = details.warnings || 0;
+  const failed = details.failed || 0;
+  const tested = details.testedEndpoints?.length || 0;
+  const skipped = details.skippedEndpoints?.length || 0;
+
+  process.stdout.write("Summary:\n");
+  process.stdout.write(`${colors.green("✓")} Tested endpoints: ${tested}\n`);
+  process.stdout.write(`${colors.yellow("⚠")} Warnings: ${warnings}\n`);
+  process.stdout.write(`${colors.red("✕")} Failed: ${failed}\n`);
+  process.stdout.write(`- Skipped: ${skipped}\n`);
+  process.stdout.write(`- Status: ${result.status}\n`);
+  process.stdout.write(`- ${result.summary}\n`);
+  if (details.artilleryError) {
+    process.stdout.write(`- Artillery error: ${details.artilleryError}\n`);
+  }
+}
+
+function formatMs(value) {
+  return value === null || value === undefined ? "n/a" : `${Math.round(value)} ms`;
+}
+
+function formatPercent(value) {
+  return `${Number(value || 0).toFixed(Number.isInteger(value) ? 0 : 2).replace(/\.00$/, "")}%`;
+}

package/src/stress/stressResultParser.js

@@ -0,0 +1,155 @@
+const DEFAULT_THRESHOLDS = {
+  p95WarnMs: 500,
+  p95FailMs: 2000,
+  p99WarnMs: 1500,
+  errorRateWarn: 0,
+  errorRateFail: 10
+};
+
+export function parseArtilleryResult(artilleryResult, endpoints, options = {}) {
+  const thresholds = { ...DEFAULT_THRESHOLDS, ...(options.thresholds || {}) };
+
+  if (!artilleryResult?.report) {
+    return {
+      status: "fail",
+      summary: "Artillery did not produce a parseable report.",
+      testedEndpoints: endpoints.map((endpoint) => ({
+        method: endpoint.method,
+        path: endpoint.path,
+        status: "fail",
+        requests: 0,
+        p95: null,
+        p99: null,
+        errors: 1,
+        errorRate: 100
+      })),
+      warnings: 0,
+      failed: endpoints.length,
+      error: trimText(artilleryResult?.stderr || artilleryResult?.stdout || "Artillery failed.")
+    };
+  }
+
+  const aggregate = getAggregate(artilleryResult.report);
+  const counters = aggregate.counters || {};
+  const summaries = aggregate.summaries || {};
+  const fallbackRequests = countRequests(counters);
+  const fallbackErrors = countErrors(counters);
+
+  const testedEndpoints = endpoints.map((endpoint) => {
+    const summary = findEndpointSummary(summaries, endpoint) || summaries["http.response_time"] || {};
+    const requests = countEndpointRequests(counters, endpoint) ?? fallbackRequests;
+    const errors = countEndpointErrors(counters, endpoint) ?? fallbackErrors;
+    const errorRate = requests > 0 ? round((errors / requests) * 100, 2) : (errors > 0 ? 100 : 0);
+    const p95 = numeric(summary.p95);
+    const p99 = numeric(summary.p99);
+    const status = classifyEndpoint({ p95, p99, errorRate, errors }, thresholds);
+
+    return {
+      method: endpoint.method,
+      path: endpoint.path,
+      status,
+      requests,
+      p95,
+      p99,
+      errors,
+      errorRate
+    };
+  });
+
+  const warnings = testedEndpoints.filter((endpoint) => endpoint.status === "warn").length;
+  const failed = testedEndpoints.filter((endpoint) => endpoint.status === "fail").length;
+  const status = !artilleryResult.ok || failed > 0 ? "fail" : warnings > 0 ? "warn" : "pass";
+  const summary = summarize(testedEndpoints.length, warnings, failed, artilleryResult);
+
+  return {
+    status,
+    summary,
+    testedEndpoints,
+    warnings,
+    failed,
+    error: artilleryResult.ok ? undefined : trimText(artilleryResult.stderr || artilleryResult.stdout)
+  };
+}
+
+function getAggregate(report) {
+  if (report?.aggregate) return report.aggregate;
+  if (Array.isArray(report?.intermediate) && report.intermediate.length > 0) {
+    return report.intermediate[report.intermediate.length - 1] || {};
+  }
+  return report || {};
+}
+
+function findEndpointSummary(summaries, endpoint) {
+  const methodPath = `${endpoint.method} ${endpoint.path}`;
+  const candidates = Object.entries(summaries);
+  const match = candidates.find(([key]) => key.includes(methodPath));
+  if (match) return match[1];
+
+  const pathMatch = candidates.find(([key]) => key.includes(endpoint.path));
+  return pathMatch ? pathMatch[1] : null;
+}
+
+function countRequests(counters) {
+  if (Number.isFinite(counters["http.requests"])) return counters["http.requests"];
+  if (Number.isFinite(counters["http.responses"])) return counters["http.responses"];
+
+  return Object.entries(counters)
+    .filter(([key]) => /^http\.codes\.\d+$/.test(key))
+    .reduce((total, [, value]) => total + numeric(value), 0);
+}
+
+function countErrors(counters) {
+  const explicit = Object.entries(counters)
+    .filter(([key]) => key.startsWith("http.errors"))
+    .reduce((total, [, value]) => total + numeric(value), 0);
+  const statusErrors = Object.entries(counters)
+    .filter(([key]) => /^http\.codes\.[45]\d\d$/.test(key))
+    .reduce((total, [, value]) => total + numeric(value), 0);
+
+  return explicit + statusErrors;
+}
+
+function countEndpointRequests(counters, endpoint) {
+  return countEndpointMetric(counters, endpoint, ["requests", "responses"]);
+}
+
+function countEndpointErrors(counters, endpoint) {
+  return countEndpointMetric(counters, endpoint, ["errors"]);
+}
+
+function countEndpointMetric(counters, endpoint, names) {
+  const methodPath = `${endpoint.method} ${endpoint.path}`;
+  const matches = Object.entries(counters).filter(([key]) => {
+    return key.includes(methodPath) && names.some((name) => key.toLowerCase().includes(name));
+  });
+  if (!matches.length) return null;
+  return matches.reduce((total, [, value]) => total + numeric(value), 0);
+}
+
+function classifyEndpoint({ p95, p99, errorRate, errors }, thresholds) {
+  if (errorRate >= thresholds.errorRateFail || p95 >= thresholds.p95FailMs) return "fail";
+  if (errorRate > thresholds.errorRateWarn || errors > 0 || p95 > thresholds.p95WarnMs || p99 > thresholds.p99WarnMs) {
+    return "warn";
+  }
+  return "pass";
+}
+
+function summarize(tested, warnings, failed, artilleryResult) {
+  if (!artilleryResult.ok) return `Artillery failed after testing ${tested} ${tested === 1 ? "endpoint" : "endpoints"}.`;
+  return `${tested} ${tested === 1 ? "endpoint" : "endpoints"} tested, ${warnings} ${warnings === 1 ? "warning" : "warnings"}, ${failed} failed`;
+}
+
+function numeric(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : 0;
+}
+
+function round(value, digits) {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
+
+function trimText(value) {
+  const normalized = String(value || "").trim();
+  return normalized.length > 1000 ? `${normalized.slice(0, 1000)}...` : normalized;
+}

package/src/utils/targetSafety.js

@@ -0,0 +1,90 @@
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "0.0.0.0"]);
+
+export const STRESS_DEFAULTS = {
+  target: "http://localhost:3000",
+  duration: 30,
+  arrivalRate: 5,
+  maxVusers: 50
+};
+
+export const STRESS_LIMITS = {
+  duration: 300,
+  arrivalRate: 50,
+  maxVusers: 100
+};
+
+export function validateStressOptions(args = {}) {
+  const target = normalizeTarget(args.target || STRESS_DEFAULTS.target);
+  const duration = parsePositiveNumber(args.duration, STRESS_DEFAULTS.duration, "duration");
+  const arrivalRate = parsePositiveNumber(args.arrivalRate, STRESS_DEFAULTS.arrivalRate, "arrival-rate");
+  const maxVusers = parsePositiveInteger(args.maxVusers, STRESS_DEFAULTS.maxVusers, "max-vusers");
+
+  assertWithinLimit(duration, STRESS_LIMITS.duration, "duration", "seconds");
+  assertWithinLimit(arrivalRate, STRESS_LIMITS.arrivalRate, "arrival-rate", "requests/second");
+  assertWithinLimit(maxVusers, STRESS_LIMITS.maxVusers, "max-vusers", "virtual users");
+
+  const local = isLocalTarget(target);
+  if (!local && !args.iOwnThis) {
+    throw new Error(
+      "Refusing to stress-test an external target without --i-own-this. Only run this against systems you own or are explicitly authorized to test."
+    );
+  }
+
+  return {
+    target,
+    duration,
+    arrivalRate,
+    maxVusers,
+    iOwnThis: Boolean(args.iOwnThis),
+    local
+  };
+}
+
+export function isLocalTarget(target) {
+  let parsed;
+  try {
+    parsed = new URL(target);
+  } catch {
+    return false;
+  }
+
+  return LOCAL_HOSTS.has(parsed.hostname.toLowerCase());
+}
+
+function normalizeTarget(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`Invalid stress target URL: ${value}`);
+  }
+
+  if (!["http:", "https:"].includes(parsed.protocol)) {
+    throw new Error("Stress target must use http:// or https://.");
+  }
+
+  return parsed.toString().replace(/\/$/, "");
+}
+
+function parsePositiveNumber(value, fallback, label) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) {
+    throw new Error(`Invalid --${label}: expected a positive number.`);
+  }
+  return number;
+}
+
+function parsePositiveInteger(value, fallback, label) {
+  const number = parsePositiveNumber(value, fallback, label);
+  if (!Number.isInteger(number)) {
+    throw new Error(`Invalid --${label}: expected a positive integer.`);
+  }
+  return number;
+}
+
+function assertWithinLimit(value, limit, label, unit) {
+  if (value > limit) {
+    throw new Error(`Refusing --${label} ${value}. Maximum allowed is ${limit} ${unit}.`);
+  }
+}