itworksbut 0.1.1 → 0.2.0

package/README.md

@@ -4,17 +4,20 @@ ItWorksBut is a Node.js CI tool for static checks in JavaScript, Node.js, web, T
 
 It focuses on common "it works, but..." risks often found in AI-generated or rushed prototypes: committed env files, missing lockfiles, weak CI, unsafe web APIs, broad desktop permissions, and similar issues.
 
+For every finding, ItWorksBut gives you a copy-ready fix prompt you can paste into your coding agent. It does not just say what is wrong; it tells your AI exactly what to inspect, what to change, and what not to leak.
+
 It only reads files and reports findings. It does not call external APIs, does not send telemetry, and does not modify the scanned project.
 
 ## Installation
 
 ```sh
-npx itworksbut scan
+npm install --global itworksbut
+itworksbut scan
 ```
 
 ### Homebrew
 
-After the formula is committed to the tap, install with:
+With the Homebrew tap:
 
 ```sh
 brew tap oliverjessner/tap
@@ -22,85 +25,68 @@ brew install itworksbut
 itworksbut scan
 ```
 
-One-line install:
-
-```sh
-brew install oliverjessner/tap/itworksbut
-```
-
-The `itworksbut` formula belongs in the Homebrew tap repo, not in this app repo:
-
-```text
-https://github.com/oliverjessner/homebrew-tap
-└── Formula/
-    └── itworksbut.rb
-```
-
-This repository contains a one-command release script. It runs checks, publishes the npm package, generates the Homebrew formula, commits it to the tap, and pushes the tap:
+## Quick Start
 
 ```sh
-npm login
-npm run publish
+itworksbut scan
 ```
 
-Do not run `npm publish` directly. The package blocks direct npm publishing so the Homebrew tap cannot be forgotten.
+`scan` is intentionally the strict/default path: all checks are enabled, only heavy generated folders are skipped, and the default `fail-on` threshold is `low` so more issues fail early. Use `--config` only when you deliberately want to tune or suppress checks.
 
-Preview everything without publishing:
+Common commands:
 
 ```sh
-npm run publish -- --dry-run
+itworksbut scan --path .
+itworksbut scan --fail-on high
+itworksbut scan --json
+itworksbut scan --sarif > itworksbut.sarif
+itworksbut scan --config itworksbut.config.json
+itworksbut scan --verbose
+itworksbut --version
 ```
 
-By default the script expects the tap checkout at `../homebrew-tap`. Override it when needed:
+## Options
 
-```sh
-npm run publish -- --tap-path /path/to/homebrew-tap
+```text
+itworksbut scan [options]
 ```
 
-Use `--no-push` when you want the script to commit the tap formula but leave the push to you.
+- `--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`.
+- `--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.
+- `--verbose`: Include scanner warnings and extra metadata in console output.
+- `--quiet`: Print only the summary.
+- `--no-color`: Disable colored output.
+- `--no-banner`: Disable the ASCII intro banner.
+- `--version`, `-v`: Print the installed ItWorksBut version.
 
-## Local Usage
+Exit codes:
 
-```sh
-node ./bin/itworksbut.js scan
-node ./bin/itworksbut.js scan --json
-node ./bin/itworksbut.js scan --sarif
-node ./bin/itworksbut.js scan --fail-on high
-node ./bin/itworksbut.js scan --config itworksbut.config.json
-node ./bin/itworksbut.js scan --path .
-node ./bin/itworksbut.js scan --verbose
-```
+- `0`: no findings at or above the configured `fail-on` severity
+- `1`: at least one finding at or above the configured `fail-on` severity
+- `2`: tool/runtime error
 
-`scan` is intentionally the strict/default path: all checks are enabled, only heavy generated folders are skipped, and the default `fail-on` threshold is `low` so more issues fail early. Use `--config` only when you deliberately want to tune or suppress checks.
+Severity levels are `critical`, `high`, `medium`, `low`, and `info`.
 
 ## Terminal Experience
 
 Normal console output is intentionally more opinionated than the machine-readable reporters:
 
 ```sh
-node ./bin/itworksbut.js scan --theme toxic
+itworksbut scan
 ```
 
 Console-only flags:
 
 - `--no-color`
 - `--no-banner`
-- `--no-spinner`
-- `--compact`
 - `--quiet`
 - `--verbose`
-- `--theme default|toxic|mono`
 
 In CI, spinners and banners are automatically disabled. With `--json` and `--sarif`, stdout contains only valid machine-readable output. The edgy tone applies only to the Console Reporter.
 
-Exit codes:
-
-- `0`: no findings at or above the configured `fail-on` severity
-- `1`: at least one finding at or above the configured `fail-on` severity
-- `2`: tool/runtime error
-
-Severity levels are `critical`, `high`, `medium`, `low`, and `info`.
-
 ## GitHub Actions
 
 ```yaml
@@ -121,13 +107,13 @@ jobs:
                   node-version: 20
                   cache: npm
             - run: npm ci
-            - run: node ./bin/itworksbut.js scan --fail-on high
+            - run: npx itworksbut scan --fail-on high
 ```
 
 For GitHub Code Scanning-style output:
 
 ```sh
-node ./bin/itworksbut.js scan --sarif > itworksbut.sarif
+itworksbut scan --sarif > itworksbut.sarif
 ```
 
 ## Configuration
@@ -171,16 +157,16 @@ release/**
 
 ```text
 ✖  CRITICAL  It works, but your .env is tracked.
-   Check: env.env-file-tracked
-   File:  .env
-   Why:   .env appears to be tracked by git. Secrets may be exposed.
-   Fix:   Remove it from git index, rotate secrets, and commit .env.example.
+   ✔ Check: env.env-file-tracked
+   📁 File:  .env
+   🤔 Why:   .env appears to be tracked by git. Secrets may be exposed.
+   🤖 prompt:   You are a senior security engineer working in this repository. Fix the ItWorksBut finding env.env-file-tracked at .env. Treat this as a concrete finding. Problem: .env appears to be tracked by git. Secrets may be exposed. Required change: Remove tracked env files from git, add safe examples such as .env.example, and make sure any exposed credentials are treated as compromised. Do not print, log, or preserve raw secret values; use placeholders only. Keep existing behavior intact where possible, add or update focused tests when useful, and do not silence the check unless the underlying risk is actually fixed.
 
 ▲  HIGH  It works, but your SQL query is one template string away from pain.
-   Check: database.raw-sql-interpolation
-   File:  src/db.js:12
-   Why:   Possible SQL injection risk: raw SQL appears to be built with template string interpolation.
-   Fix:   Use parameterized queries, prepared statements, or ORM query builders instead of interpolating values into SQL strings.
+   ✔ Check: database.raw-sql-interpolation
+   📁 File:  src/db.js:12
+   🤔 Why:   Possible SQL injection risk: raw SQL appears to be built with template string interpolation.
+   🤖 prompt:   You are a senior security engineer working in this repository. Fix the ItWorksBut finding database.raw-sql-interpolation at src/db.js:12. This finding is heuristic, so inspect the code first and only change behavior when the risk is real. Problem: Possible SQL injection risk: raw SQL appears to be built with template string interpolation. Required change: Replace SQL string interpolation or concatenation with parameterized queries, prepared statements, or a safe ORM query builder. Keep existing behavior intact where possible, add or update focused tests when useful, and do not silence the check unless the underlying risk is actually fixed.
 
 SUMMARY
 - ship status: DO NOT SHIP

package/bin/itworksbut.js

@@ -1,63 +1,68 @@
 #!/usr/bin/env node
 
-import { parseArgs } from "../src/cli/parseArgs.js";
-import { printUsage, printRuntimeError } from "../src/cli/output.js";
-import { createScanSpinner, normalizeTheme, printIntro } from "../src/cli/terminal.js";
-import { scanProject } from "../src/core/scanner.js";
-import { getExitCode } from "../src/core/findings.js";
-import { reportConsole } from "../src/reporters/consoleReporter.js";
-import { reportJson } from "../src/reporters/jsonReporter.js";
-import { reportSarif } from "../src/reporters/sarifReporter.js";
+import { parseArgs } from '../src/cli/parseArgs.js';
+import { printUsage, printRuntimeError, printVersion } from '../src/cli/output.js';
+import { createScanSpinner, printIntro } from '../src/cli/terminal.js';
+import { packageInfo } from '../src/core/packageInfo.js';
+import { scanProject } from '../src/core/scanner.js';
+import { getExitCode } from '../src/core/findings.js';
+import { reportConsole } from '../src/reporters/consoleReporter.js';
+import { reportJson } from '../src/reporters/jsonReporter.js';
+import { reportSarif } from '../src/reporters/sarifReporter.js';
 
 async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  args.theme = normalizeTheme(args.theme);
-
-  if (args.help) {
-    printUsage();
-    return 0;
-  }
-
-  if (args.command !== "scan") {
-    printUsage();
-    return 2;
-  }
-
-  printIntro(args);
-
-  const spinner = createScanSpinner(args);
-  if (spinner) spinner.start();
-
-  let result;
-  try {
-    result = await scanProject({
-      rootPath: args.path,
-      configPath: args.config,
-      failOn: args.failOn,
-      verbose: args.verbose
-    });
-    if (spinner) spinner.succeed("Scan complete. Now the receipts.");
-  } catch (error) {
-    if (spinner) spinner.fail("Scan stopped before the receipts were printed.");
-    throw error;
-  }
-
-  if (args.sarif) {
-    process.stdout.write(`${JSON.stringify(reportSarif(result), null, 2)}\n`);
-  } else if (args.json) {
-    process.stdout.write(`${JSON.stringify(reportJson(result), null, 2)}\n`);
-  } else {
-    reportConsole(result, args);
-  }
-
-  return getExitCode(result.findings, result.config.failOn);
+    const args = parseArgs(process.argv.slice(2));
+
+    if (args.help) {
+        printUsage();
+        return 0;
+    }
+
+    if (args.version) {
+        printVersion(`It Works But… version ${packageInfo.version}`);
+        return 0;
+    }
+
+    if (args.command !== 'scan') {
+        printUsage();
+        return 2;
+    }
+
+    printIntro(args);
+
+    const spinner = createScanSpinner(args);
+    if (spinner) spinner.start();
+
+    let result;
+    try {
+        result = await scanProject({
+            rootPath: args.path,
+            configPath: args.config,
+            failOn: args.failOn,
+            verbose: args.verbose,
+        });
+        if (spinner) spinner.succeed('Scan complete. Now the receipts.');
+    } catch (error) {
+        if (spinner) spinner.fail('Scan stopped before the receipts were printed.');
+        throw error;
+    }
+
+    if (args.sarif) {
+        process.stdout.write(`${JSON.stringify(reportSarif(result), null, 2)}\n`);
+    } else if (args.json) {
+        process.stdout.write(`${JSON.stringify(reportJson(result), null, 2)}\n`);
+    } else {
+        reportConsole(result, args);
+    }
+
+    return getExitCode(result.findings, result.config.failOn);
 }
 
 main()
-  .then((code) => {
-    process.exitCode = code;
-  })
-  .catch((error) => {
-    printRuntimeError(error);
-    process.exitCode = 2;
-  });
+    .then(code => {
+        process.exitCode = code;
+    })
+    .catch(error => {
+        printRuntimeError(error);
+        process.exitCode = 2;
+    });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "itworksbut",
-    "version": "0.1.1",
+    "version": "0.2.0",
     "description": "Static CI checks for common security, repo, dependency, build, and deployment risks in JavaScript vibe coding projects.",
     "type": "module",
     "bin": {

package/src/checks/node/express-json-limit-missing.js

@@ -18,11 +18,11 @@ export default {
       const args = match.match[1] || "";
       if (/\blimit\s*:/.test(args)) continue;
       findings.push({
-        message: "express.json() appears to be used without an explicit request body size limit.",
+        message: "Express JSON body parsing appears to be used without an explicit request body size limit.",
         file: match.file,
         line: match.line,
         column: match.column,
-        recommendation: "Set a conservative limit, for example express.json({ limit: '100kb' }), and tune it per route when needed."
+        recommendation: "Set a conservative JSON body parser limit such as 100kb, and tune it per route when needed."
       });
     }
     return findings;

package/src/cli/output.js

@@ -1,3 +1,5 @@
+import gradient from 'gradient-string';
+
 export function printUsage() {
   process.stdout.write(`ItWorksBut
 
@@ -14,15 +16,21 @@ Options:
   --sarif             Print SARIF for GitHub Code Scanning.
   --no-color          Disable color styling.
   --no-banner         Disable the intro banner.
-  --no-spinner        Disable scan spinner.
-  --compact           Print one-line findings.
   --quiet             Print only the summary.
-  --theme <theme>     Console theme: default, toxic, mono.
   --verbose           Include scanner warnings and extra metadata.
+  --version, -v       Print the ItWorksBut version.
   --help              Show this help.
 `);
 }
 
+export function printVersion(version) {
+  try {
+    process.stdout.write(`${gradient.rainbow(version)}\n`);
+  } catch {
+    process.stdout.write(`${version}\n`);
+  }
+}
+
 export function printRuntimeError(error) {
   const message = error instanceof Error ? error.message : String(error);
   process.stderr.write(`ItWorksBut runtime error: ${message}\n`);

package/src/cli/parseArgs.js

@@ -1,5 +1,5 @@
-const FLAG_WITH_VALUE = new Set(["--fail-on", "--config", "--path", "--theme"]);
-const BOOLEAN_FLAGS = new Set(["--json", "--sarif", "--verbose", "--help", "-h", "--no-color", "--no-banner", "--no-spinner", "--compact", "--quiet"]);
+const FLAG_WITH_VALUE = new Set(["--fail-on", "--config", "--path"]);
+const BOOLEAN_FLAGS = new Set(["--json", "--sarif", "--verbose", "--help", "-h", "--version", "-v", "--no-color", "--no-banner", "--quiet"]);
 
 export function parseArgs(argv) {
   const args = {
@@ -12,11 +12,9 @@ export function parseArgs(argv) {
     verbose: false,
     noColor: false,
     noBanner: false,
-    noSpinner: false,
-    compact: false,
     quiet: false,
-    theme: "default",
-    help: false
+    help: false,
+    version: false
   };
 
   const tokens = [...argv];
@@ -45,13 +43,12 @@ export function parseArgs(argv) {
 
     if (BOOLEAN_FLAGS.has(token)) {
       if (token === "--help" || token === "-h") args.help = true;
+      if (token === "--version" || token === "-v") args.version = true;
       if (token === "--json") args.json = true;
       if (token === "--sarif") args.sarif = true;
       if (token === "--verbose") args.verbose = true;
       if (token === "--no-color") args.noColor = true;
       if (token === "--no-banner") args.noBanner = true;
-      if (token === "--no-spinner") args.noSpinner = true;
-      if (token === "--compact") args.compact = true;
       if (token === "--quiet") args.quiet = true;
       continue;
     }
@@ -70,6 +67,5 @@ 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 === "--theme") args.theme = value;
   else throw new Error(`Unknown argument: ${flag}`);
 }

package/src/cli/terminal.js

@@ -4,8 +4,6 @@ import figlet from "figlet";
 import gradient from "gradient-string";
 import ora from "ora";
 
-const THEMES = new Set(["default", "toxic", "mono"]);
-
 const SPINNER_TEXT = {
   git: "Checking git hygiene",
   env: "Sniffing for secrets",
@@ -20,21 +18,12 @@ const SPINNER_TEXT = {
   default: "Looking for things that work but should not ship"
 };
 
-export function normalizeTheme(theme) {
-  const normalized = String(theme || "default").toLowerCase();
-  if (!THEMES.has(normalized)) {
-    throw new Error(`Invalid theme "${theme}". Expected one of: default, toxic, mono`);
-  }
-  return normalized;
-}
-
 export function isFancyOutputEnabled(options = {}, env = process.env, stdout = process.stdout) {
-  return Boolean(stdout.isTTY) && !env.CI && !options.json && !options.sarif && !options.noColor && normalizeTheme(options.theme) !== "mono";
+  return Boolean(stdout.isTTY) && !env.CI && !options.json && !options.sarif && !options.noColor;
 }
 
 export function isColorEnabled(options = {}, env = process.env, stdout = process.stdout) {
   if (options.noColor || options.json || options.sarif) return false;
-  if (normalizeTheme(options.theme) === "mono") return false;
   if (env.FORCE_COLOR && env.FORCE_COLOR !== "0") return true;
   if (env.CI) return false;
   return Boolean(stdout.isTTY);
@@ -51,7 +40,6 @@ export function shouldUseSpinner(options = {}, env = process.env, stdout = proce
     !env.CI &&
     !options.json &&
     !options.sarif &&
-    !options.noSpinner &&
     !options.quiet
   );
 }
@@ -61,7 +49,7 @@ export function createScanSpinner(options = {}) {
   return ora({
     text: SPINNER_TEXT.default,
     stream: process.stderr,
-    color: normalizeTheme(options.theme) === "toxic" ? "green" : "cyan"
+    color: "cyan"
   });
 }
 
@@ -70,14 +58,9 @@ export function printIntro(options = {}) {
     return;
   }
 
-  const theme = normalizeTheme(options.theme);
   const colors = getChalk(options);
-  const renderTheme = options.noColor ? "mono" : theme;
-  const title = renderTitle(renderTheme);
-  const claim =
-    theme === "toxic"
-      ? `${colors.bold("Green builds. Red flags.")}\n${colors.green("Let's see what breaks before production.")}`
-      : `${colors.bold("AI-built? Nice.")}\n${colors.yellow("Now let's see what breaks before production.")}`;
+  const title = renderTitle(options.noColor);
+  const claim = `${colors.bold("AI-built? Nice.")}\n${colors.yellow("Now let's see what breaks before production.")}`;
 
   process.stdout.write(`${title}\n`);
   process.stdout.write(
@@ -85,12 +68,12 @@ export function printIntro(options = {}) {
       padding: 1,
       margin: 1,
       borderStyle: "round",
-      borderColor: renderTheme === "mono" ? undefined : renderTheme === "toxic" ? "green" : "cyan"
+      borderColor: options.noColor ? undefined : "cyan"
     })}\n`
   );
 }
 
-function renderTitle(theme) {
+function renderTitle(noColor) {
   let title = "ItWorksBut";
   try {
     title = figlet.textSync("ItWorksBut", {
@@ -103,8 +86,7 @@ function renderTitle(theme) {
   }
 
   try {
-    if (theme === "mono") return title;
-    if (theme === "toxic") return gradient(["#faff00", "#39ff14", "#00f5ff"])(title);
+    if (noColor) return title;
     return gradient.rainbow(title);
   } catch {
     return title;

package/src/core/packageInfo.js

@@ -0,0 +1,11 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
+
+export const packageInfo = {
+  name: packageJson.name,
+  version: packageJson.version
+};

package/src/core/scanner.js

@@ -1,6 +1,7 @@
 import checks from "../checks/index.js";
 import { createContext } from "./context.js";
 import { normalizeFinding, severityRank } from "./findings.js";
+import { packageInfo } from "./packageInfo.js";
 
 export async function scanProject(options = {}) {
   const startedAt = new Date();
@@ -43,7 +44,7 @@ export async function scanProject(options = {}) {
     config: context.config,
     meta: {
       tool: "ItWorksBut",
-      version: "0.1.0",
+      version: packageInfo.version,
       rootPath: context.rootPath,
       packageManager: context.packageManager,
       gitAvailable: context.gitAvailable,

package/src/reporters/consoleReporter.js

@@ -1,107 +1,112 @@
-import { SEVERITIES } from "../core/config.js";
-import { countBySeverity, getExitCode } from "../core/findings.js";
-import { isFancyOutputEnabled, getChalk } from "../cli/terminal.js";
-import { formatSeverity, getConsoleFindingTitle, getShipStatus, renderSummaryBox, renderSummaryTable } from "./consoleStyle.js";
+import { SEVERITIES } from '../core/config.js';
+import { countBySeverity, getExitCode } from '../core/findings.js';
+import { isFancyOutputEnabled, getChalk } from '../cli/terminal.js';
+import {
+    formatSeverity,
+    getConsoleFindingTitle,
+    getFixPrompt,
+    getShipStatus,
+    renderSummaryBox,
+    renderSummaryTable,
+} from './consoleStyle.js';
 
 export function reportConsole(result, options = {}) {
-  const { findings, warnings, config, meta } = result;
-  const counts = countBySeverity(findings);
-  const colors = getChalk(options);
-  const rich = isFancyOutputEnabled(options);
+    const { findings, warnings, config, meta } = result;
+    const counts = countBySeverity(findings);
+    const colors = getChalk(options);
+    const rich = isFancyOutputEnabled(options);
 
-  if (!options.quiet && !rich) {
-    process.stdout.write(`${colors.bold("ItWorksBut receipts")}\n\n`);
-  }
-
-  if (!options.quiet && findings.length === 0) {
-    process.stdout.write(`${colors.green ? colors.green("Suspiciously clean. No findings.") : "Suspiciously clean. No findings."}\n\n`);
-  } else if (!options.quiet) {
-    for (const severity of SEVERITIES) {
-      const group = findings.filter((finding) => finding.severity === severity);
-      if (group.length === 0) continue;
+    if (!options.quiet && !rich) {
+        process.stdout.write(`${colors.bold('ItWorksBut receipts')}\n\n`);
+    }
 
-      for (const finding of group) {
-        writeFinding(finding, options);
-      }
-      process.stdout.write("\n");
+    if (!options.quiet && findings.length === 0) {
+        process.stdout.write(
+            `${colors.green ? colors.green('Suspiciously clean. No findings.') : 'Suspiciously clean. No findings.'}\n\n`,
+        );
+    } else if (!options.quiet) {
+        for (const severity of SEVERITIES) {
+            const group = findings.filter(finding => finding.severity === severity);
+            if (group.length === 0) continue;
+
+            for (const finding of group) {
+                writeFinding(finding, options);
+            }
+            process.stdout.write('\n');
+        }
     }
-  }
 
-  if (options.verbose && warnings.length > 0) {
-    process.stdout.write("WARNINGS\n");
-    for (const warning of warnings) {
-      process.stdout.write(`- [${warning.checkId}] ${warning.message}\n`);
+    if (options.verbose && warnings.length > 0) {
+        process.stdout.write('WARNINGS\n');
+        for (const warning of warnings) {
+            process.stdout.write(`- [${warning.checkId}] ${warning.message}\n`);
+        }
+        process.stdout.write('\n');
     }
-    process.stdout.write("\n");
-  }
 
-  const exitCode = getExitCode(findings, config.failOn);
-  writeSummary({ counts, total: findings.length, failOn: config.failOn, exitCode }, options);
+    const exitCode = getExitCode(findings, config.failOn);
+    writeSummary({ counts, total: findings.length, failOn: config.failOn, exitCode }, options);
 
-  if (options.verbose) {
-    process.stdout.write(`- files scanned: ${meta.filesScanned}\n`);
-    process.stdout.write(`- text files scanned: ${meta.textFilesScanned}\n`);
-    process.stdout.write(`- git available: ${meta.gitAvailable}\n`);
-    process.stdout.write(`- warnings: ${warnings.length}\n`);
-  }
+    if (options.verbose) {
+        process.stdout.write(`- files scanned: ${meta.filesScanned}\n`);
+        process.stdout.write(`- text files scanned: ${meta.textFilesScanned}\n`);
+        process.stdout.write(`- git available: ${meta.gitAvailable}\n`);
+        process.stdout.write(`- warnings: ${warnings.length}\n`);
+    }
 }
 
 function writeFinding(finding, options) {
-  const colors = getChalk(options);
-  const severity = formatSeverity(finding.severity, options);
-  const title = getConsoleFindingTitle(finding);
-  const location = finding.file ? (finding.line ? `${finding.file}:${finding.line}` : finding.file) : "";
-
-  if (options.compact) {
-    const where = location ? `${location} - ` : "";
-    process.stdout.write(`${severity.compactText} ${finding.checkId} ${where}${title}\n`);
-    return;
-  }
-
-  process.stdout.write(`${severity.text}  ${colors.bold(title)}${finding.heuristic ? colors.gray(" (heuristic)") : ""}\n`);
-  process.stdout.write(`   Check: ${finding.checkId}\n`);
-  if (location) process.stdout.write(`   File:  ${location}\n`);
-  process.stdout.write(`   Why:   ${finding.message}\n`);
-  if (finding.recommendation) process.stdout.write(`   Fix:   ${finding.recommendation}\n`);
-
-  if (options.verbose) {
-    process.stdout.write(`   Category: ${finding.category || "unknown"}\n`);
-    if (finding.tags?.length) process.stdout.write(`   Tags:     ${finding.tags.join(", ")}\n`);
-    if (finding.line) process.stdout.write(`   Line:     ${finding.line}\n`);
-    const evidence = safeEvidence(finding);
-    if (evidence) process.stdout.write(`   Evidence: ${evidence}\n`);
-  }
+    const colors = getChalk(options);
+    const severity = formatSeverity(finding.severity, options);
+    const title = getConsoleFindingTitle(finding);
+    const location = finding.file ? (finding.line ? `${finding.file}:${finding.line}` : finding.file) : '';
+
+    process.stdout.write(
+        `${severity.text}  ${colors.bold(title)}${finding.heuristic ? colors.gray(' (heuristic)') : ''}\n`,
+    );
+    process.stdout.write(`   ✔ Check: ${finding.checkId}\n`);
+    if (location) process.stdout.write(`   📁 File:  ${location}\n`);
+    process.stdout.write(`   🤔 Why:   ${finding.message}\n`);
+    process.stdout.write(`   🤖 Prompt:   ${getFixPrompt(finding)}\n`);
+
+    if (options.verbose) {
+        process.stdout.write(`   Category: ${finding.category || 'unknown'}\n`);
+        if (finding.tags?.length) process.stdout.write(`   Tags:     ${finding.tags.join(', ')}\n`);
+        if (finding.line) process.stdout.write(`   Line:     ${finding.line}\n`);
+        const evidence = safeEvidence(finding);
+        if (evidence) process.stdout.write(`   Evidence: ${evidence}\n`);
+    }
 
-  process.stdout.write("\n");
+    process.stdout.write('\n');
 }
 
 function writeSummary({ counts, total, failOn, exitCode }, options) {
-  const colors = getChalk(options);
-  const ship = getShipStatus(counts);
-
-  if (isFancyOutputEnabled(options)) {
-    process.stdout.write(`${renderSummaryBox(counts, options)}\n`);
-    process.stdout.write(`${renderSummaryTable(counts, options)}\n`);
-    process.stdout.write(`\nFail-on: ${failOn} | Exit decision: ${exitCode}\n`);
-    return;
-  }
+    const colors = getChalk(options);
+    const ship = getShipStatus(counts);
+
+    if (isFancyOutputEnabled(options)) {
+        process.stdout.write(`${renderSummaryBox(counts, options)}\n`);
+        process.stdout.write(`${renderSummaryTable(counts, options)}\n`);
+        process.stdout.write(`\nFail-on: ${failOn} | Exit decision: ${exitCode}\n`);
+        return;
+    }
 
-  process.stdout.write("SUMMARY\n");
-  process.stdout.write(`- ship status: ${colors.bold(ship.status)}\n`);
-  process.stdout.write(`- ${ship.tone}\n`);
-  process.stdout.write(`- total findings: ${total}\n`);
-  for (const severity of SEVERITIES) {
-    process.stdout.write(`- ${severity}: ${counts[severity]}\n`);
-  }
-  process.stdout.write(`- fail-on: ${failOn}\n`);
-  process.stdout.write(`- exit decision: ${exitCode}\n`);
+    process.stdout.write('SUMMARY\n');
+    process.stdout.write(`- ship status: ${colors.bold(ship.status)}\n`);
+    process.stdout.write(`- ${ship.tone}\n`);
+    process.stdout.write(`- total findings: ${total}\n`);
+    for (const severity of SEVERITIES) {
+        process.stdout.write(`- ${severity}: ${counts[severity]}\n`);
+    }
+    process.stdout.write(`- fail-on: ${failOn}\n`);
+    process.stdout.write(`- exit decision: ${exitCode}\n`);
 }
 
 function safeEvidence(finding) {
-  const metadata = finding.metadata || {};
-  if (metadata.secretType) return `secret type: ${metadata.secretType}; value redacted`;
-  if (metadata.pattern) return `pattern: ${metadata.pattern}`;
-  if (metadata.routePath) return `route: ${metadata.routePath}`;
-  if (metadata.envName) return `environment variable name: ${metadata.envName}`;
-  return "";
+    const metadata = finding.metadata || {};
+    if (metadata.secretType) return `secret type: ${metadata.secretType}; value redacted`;
+    if (metadata.pattern) return `pattern: ${metadata.pattern}`;
+    if (metadata.routePath) return `route: ${metadata.routePath}`;
+    if (metadata.envName) return `environment variable name: ${metadata.envName}`;
+    return '';
 }

package/src/reporters/consoleStyle.js

@@ -1,155 +1,260 @@
-import boxen from "boxen";
-import Table from "cli-table3";
-import { SEVERITIES } from "../core/config.js";
-import { getChalk, normalizeTheme } from "../cli/terminal.js";
+import boxen from 'boxen';
+import Table from 'cli-table3';
+import { SEVERITIES } from '../core/config.js';
+import { getChalk } from '../cli/terminal.js';
 
 const EDGY_TITLES = {
-  "env.env-file-tracked": "It works, but your .env is tracked.",
-  "env.possible-secret-in-code": "It works, but your repo may be leaking secrets.",
-  "env.frontend-secret-exposure": "It works, but your frontend env variable smells like a backend secret.",
-  "git.gitignore-missing": "It works, but your repo forgot what not to commit.",
-  "git.gitignore-incomplete": "It works, but your .gitignore has holes.",
-  "git.ignored-files-tracked": "It works, but Git is already tracking files you meant to ignore.",
-  "dependencies.lockfile-missing": "It works on your machine, but your dependency tree is not locked.",
-  "dependencies.multiple-lockfiles": "It works, but your package managers are fighting.",
-  "ci.no-ci-config": "It works, but nobody checks it before it ships.",
-  "ci.npm-install-instead-of-npm-ci": "It works, but your CI is installing instead of reproducing.",
-  "ci.no-test-step": "It works, but your CI is basically decorative.",
-  "node.express-json-limit-missing": "It works, but your API accepts oversized bodies.",
-  "node.rate-limit-missing": "It works, but your endpoints have no brakes.",
-  "node.helmet-missing": "It works, but your HTTP headers are underdressed.",
-  "node.cors-wildcard": "It works, but CORS is holding the door open.",
-  "web.dangerous-inner-html": "It works, but your frontend is injecting HTML with sharp edges.",
-  "api.missing-auth-on-routes": "It works, but this API route appears to trust strangers.",
-  "api.idor-risk": "It works, but this ID lookup may belong to someone else.",
-  "database.raw-sql-interpolation": "It works, but your SQL query is one template string away from pain.",
-  "database.no-migrations": "It works, but your database schema has no paper trail.",
-  "electron.node-integration-enabled": "It works, but Electron is holding the Node.js door open.",
-  "electron.context-isolation-disabled": "It works, but your renderer and backend are sharing a room.",
-  "tauri.dangerous-allowlist-or-capabilities": "It works, but your Tauri permissions look too generous."
+    'env.env-file-tracked': 'It works, but your .env is tracked.',
+    'env.possible-secret-in-code': 'It works, but your repo may be leaking secrets.',
+    'env.frontend-secret-exposure': 'It works, but your frontend env variable smells like a backend secret.',
+    'git.gitignore-missing': 'It works, but your repo forgot what not to commit.',
+    'git.gitignore-incomplete': 'It works, but your .gitignore has holes.',
+    'git.ignored-files-tracked': 'It works, but Git is already tracking files you meant to ignore.',
+    'dependencies.lockfile-missing': 'It works on your machine, but your dependency tree is not locked.',
+    'dependencies.multiple-lockfiles': 'It works, but your package managers are fighting.',
+    'ci.no-ci-config': 'It works, but nobody checks it before it ships.',
+    'ci.npm-install-instead-of-npm-ci': 'It works, but your CI is installing instead of reproducing.',
+    'ci.no-test-step': 'It works, but your CI is basically decorative.',
+    'node.express-json-limit-missing': 'It works, but your API accepts oversized bodies.',
+    'node.rate-limit-missing': 'It works, but your endpoints have no brakes.',
+    'node.helmet-missing': 'It works, but your HTTP headers are underdressed.',
+    'node.cors-wildcard': 'It works, but CORS is holding the door open.',
+    'web.dangerous-inner-html': 'It works, but your frontend is injecting HTML with sharp edges.',
+    'api.missing-auth-on-routes': 'It works, but this API route appears to trust strangers.',
+    'api.idor-risk': 'It works, but this ID lookup may belong to someone else.',
+    'database.raw-sql-interpolation': 'It works, but your SQL query is one template string away from pain.',
+    'database.no-migrations': 'It works, but your database schema has no paper trail.',
+    'electron.node-integration-enabled': 'It works, but Electron is holding the Node.js door open.',
+    'electron.context-isolation-disabled': 'It works, but your renderer and backend are sharing a room.',
+    'tauri.dangerous-allowlist-or-capabilities': 'It works, but your Tauri permissions look too generous.',
 };
 
 const SEVERITY_META = {
-  critical: { symbol: "✖", label: "CRITICAL" },
-  high: { symbol: "▲", label: "HIGH" },
-  medium: { symbol: "◆", label: "MEDIUM" },
-  low: { symbol: "•", label: "LOW" },
-  info: { symbol: "i", label: "INFO" }
+    critical: { symbol: '✖', label: 'CRITICAL' },
+    high: { symbol: '▲', label: 'HIGH' },
+    medium: { symbol: '◆', label: 'MEDIUM' },
+    low: { symbol: '•', label: 'LOW' },
+    info: { symbol: 'i', label: 'INFO' },
+};
+
+const FIX_PROMPT_ACTIONS = {
+    'env.env-file-tracked':
+        'Remove tracked env files from git, add safe examples such as .env.example, and make sure any exposed credentials are treated as compromised.',
+    'env.possible-secret-in-code':
+        'Move hardcoded secret material into a runtime secret store or CI secret, replace committed values with placeholders, and avoid printing secret values anywhere.',
+    'env.frontend-secret-exposure':
+        'Move secret-like frontend environment variables to server-side code and keep only intentionally public values behind public prefixes.',
+    'git.gitignore-missing':
+        'Add a project-appropriate .gitignore for dependencies, local env files, build output, logs, databases, OS files, and coverage artifacts.',
+    'git.gitignore-incomplete':
+        'Update .gitignore with the missing high-risk patterns without removing existing project-specific ignores.',
+    'git.ignored-files-tracked':
+        'Stop tracking generated or local-only files that match ignore rules and preserve the files locally when appropriate.',
+    'dependencies.lockfile-missing':
+        'Generate and commit exactly one package-manager lockfile for the package manager used by the project.',
+    'dependencies.multiple-lockfiles':
+        'Keep the lockfile for the package manager the project actually uses and remove competing lockfiles.',
+    'dependencies.install-scripts-risk':
+        'Review install lifecycle scripts, remove them if unnecessary, or document and constrain them so CI installs stay predictable.',
+    'dependencies.audit-script-missing':
+        'Add a dependency audit or security script and wire it into CI without breaking existing scripts.',
+    'package.scripts-missing':
+        'Add the missing standard package scripts using the existing tooling and naming conventions in this project.',
+    'ci.no-ci-config': 'Add a CI workflow that installs from the lockfile and runs checks, tests, and build steps.',
+    'ci.npm-install-instead-of-npm-ci':
+        'Replace npm install with npm ci in CI jobs unless the command is intentionally global installation.',
+    'ci.no-build-step': "Add a build step to CI using the project's existing package scripts.",
+    'ci.no-test-step': "Add a test step to CI using the project's existing test command.",
+    'node.express-json-limit-missing':
+        'Add explicit body size limits to express.json middleware and keep route behavior intact.',
+    'node.rate-limit-missing':
+        'Add appropriate rate limiting for API routes, especially authentication and write endpoints.',
+    'node.helmet-missing':
+        'Install and apply Helmet or equivalent security headers early in the Express middleware stack.',
+    'node.cors-wildcard':
+        'Restrict CORS origins to trusted application origins and avoid wildcard or credentials-unsafe configurations.',
+    'web.client-side-auth-only':
+        'Move authorization enforcement to server-side API or route handlers and keep frontend checks as UI-only hints.',
+    'web.dangerous-inner-html':
+        'Remove direct HTML injection or add proven sanitization at the trust boundary before rendering.',
+    'web.missing-output-sanitization': 'Escape or sanitize user-controlled output before it reaches HTML responses.',
+    'api.missing-auth-on-routes':
+        'Add explicit authentication and authorization to the route, or document why the route is intentionally public.',
+    'api.idor-risk':
+        'Scope object access by authenticated user, owner, tenant, account, or organization in addition to object id.',
+    'database.raw-sql-interpolation':
+        'Replace SQL string interpolation or concatenation with parameterized queries, prepared statements, or a safe ORM query builder.',
+    'database.no-migrations': 'Add versioned database migrations that match the detected ORM or database stack.',
+    'electron.node-integration-enabled':
+        'Set nodeIntegration to false and expose only narrowly scoped APIs through preload.',
+    'electron.context-isolation-disabled':
+        'Enable contextIsolation and review preload boundaries for renderer-to-main communication.',
+    'tauri.dangerous-allowlist-or-capabilities':
+        'Tighten Tauri allowlists, capabilities, scopes, shell access, filesystem access, remote URLs, and CSP.',
 };
 
 export function getConsoleFindingTitle(finding) {
-  if (EDGY_TITLES[finding.checkId]) return EDGY_TITLES[finding.checkId];
-  if (finding.heuristic) return `It works, but this pattern may be risky: ${finding.title || finding.checkId}.`;
-  return `It works, but ${lowercaseFirst(finding.title || finding.message || finding.checkId)}.`;
+    if (EDGY_TITLES[finding.checkId]) return EDGY_TITLES[finding.checkId];
+    if (finding.heuristic) return `It works, but this pattern may be risky: ${finding.title || finding.checkId}.`;
+    return `It works, but ${lowercaseFirst(finding.title || finding.message || finding.checkId)}.`;
+}
+
+export function getFixPrompt(finding) {
+    const location = finding.file
+        ? `${finding.file}${finding.line ? `:${finding.line}` : ''}`
+        : 'the affected project files';
+    const action =
+        FIX_PROMPT_ACTIONS[finding.checkId] ||
+        finding.recommendation ||
+        'Fix the underlying issue without suppressing the scanner.';
+    const heuristic = finding.heuristic
+        ? 'This finding is heuristic, so inspect the code first and only change behavior when the risk is real.'
+        : 'Treat this as a concrete finding.';
+    const secretSafety = isSecretFinding(finding)
+        ? 'Do not print, log, or preserve raw secret values; use placeholders only.'
+        : '';
+    const recommendation = finding.recommendation ? `Existing recommendation: ${finding.recommendation}` : '';
+
+    return collapseWhitespace(
+        [
+            'You are a senior security engineer working in this repository.',
+            `Fix the ItWorksBut finding ${finding.checkId} at ${location}.`,
+            heuristic,
+            `Problem: ${finding.message}`,
+            `Required change: ${action}`,
+            recommendation,
+            secretSafety,
+            'Keep existing behavior intact where possible, add or update focused tests when useful, and do not silence the check unless the underlying risk is actually fixed.',
+        ]
+            .filter(Boolean)
+            .join(' '),
+    );
 }
 
 export function formatSeverity(severity, options = {}) {
-  const colors = getChalk(options);
-  const meta = SEVERITY_META[severity] || SEVERITY_META.info;
-  const raw = `${meta.symbol}  ${meta.label}`;
+    const colors = getChalk(options);
+    const meta = SEVERITY_META[severity] || SEVERITY_META.info;
+    const raw = `${meta.symbol}  ${meta.label}`;
+
+    if (options.noColor) {
+        return {
+            ...meta,
+            text: colors.bold(raw),
+            shortText: colors.bold(`${meta.symbol} ${meta.label}`),
+        };
+    }
+
+    const stylers = {
+        critical: value => colors.bgRed.white.bold(value),
+        high: value => colors.red.bold(value),
+        medium: value => colors.yellow.bold(value),
+        low: value => colors.blue(value),
+        info: value => colors.gray(value),
+    };
 
-  if (normalizeTheme(options.theme) === "mono") {
+    const style = stylers[severity] || stylers.info;
     return {
-      ...meta,
-      text: colors.bold(raw),
-      compactText: colors.bold(`${meta.symbol} ${meta.label}`)
+        ...meta,
+        text: style(raw),
+        shortText: style(`${meta.symbol} ${meta.label}`),
     };
-  }
-
-  const stylers = {
-    critical: (value) => colors.bgRed.white.bold(value),
-    high: (value) => colors.red.bold(value),
-    medium: (value) => colors.yellow.bold(value),
-    low: (value) => colors.blue(value),
-    info: (value) => colors.gray(value)
-  };
-
-  const style = stylers[severity] || stylers.info;
-  return {
-    ...meta,
-    text: style(raw),
-    compactText: style(`${meta.symbol} ${meta.label}`)
-  };
 }
 
 export function getShipStatus(counts) {
-  if (counts.critical > 0) {
-    return {
-      status: "DO NOT SHIP",
-      tone: "Fix the red stuff before production.",
-      severity: "critical"
-    };
-  }
-  if (counts.high > 0) {
-    return {
-      status: "FIX BEFORE SHIP",
-      tone: "Close the obvious holes before shipping.",
-      severity: "high"
-    };
-  }
-  if (counts.medium > 0) {
+    if (counts.critical > 0) {
+        return {
+            status: 'DO NOT SHIP',
+            tone: 'Fix the red stuff before production.',
+            severity: 'critical',
+        };
+    }
+    if (counts.high > 0) {
+        return {
+            status: 'FIX BEFORE SHIP',
+            tone: "Just copy the text from '🤖 Prompt:' and shove it into your AI.",
+            severity: 'high',
+        };
+    }
+    if (counts.medium > 0) {
+        return {
+            status: 'SHIP WITH CAUTION',
+            tone: 'You can ship, but future-you will ask questions.',
+            severity: 'medium',
+        };
+    }
     return {
-      status: "SHIP WITH CAUTION",
-      tone: "You can ship, but future-you will ask questions.",
-      severity: "medium"
+        status: 'SHIP IT, BUT STAY PARANOID',
+        tone: 'Suspiciously clean. Ship it, but stay paranoid.',
+        severity: 'info',
     };
-  }
-  return {
-    status: "SHIP IT, BUT STAY PARANOID",
-    tone: "Suspiciously clean. Ship it, but stay paranoid.",
-    severity: "info"
-  };
 }
 
 export function renderSummaryBox(counts, options = {}) {
-  const colors = getChalk(options);
-  const ship = getShipStatus(counts);
-  const severity = formatSeverity(ship.severity, options);
-  const content = [
-    colors.bold("It works, but..."),
-    "",
-    `Ship status: ${severity.label === "INFO" ? colors.bold(ship.status) : severityColor(ship.status, ship.severity, colors)}`,
-    `Critical: ${counts.critical}`,
-    `High:     ${counts.high}`,
-    `Medium:   ${counts.medium}`,
-    "",
-    ship.tone
-  ].join("\n");
-
-  return boxen(content, {
-    padding: 1,
-    margin: 1,
-    borderStyle: "round",
-    borderColor: ship.severity === "critical" || ship.severity === "high" ? "red" : ship.severity === "medium" ? "yellow" : "green"
-  });
+    const colors = getChalk(options);
+    const ship = getShipStatus(counts);
+    const severity = formatSeverity(ship.severity, options);
+    const content = [
+        colors.bold('It works, but...'),
+        '',
+        `Ship status: ${severity.label === 'INFO' ? colors.bold(ship.status) : severityColor(ship.status, ship.severity, colors)}`,
+        `Critical: ${counts.critical}`,
+        `High:     ${counts.high}`,
+        `Medium:   ${counts.medium}`,
+        '',
+        ship.tone,
+    ].join('\n');
+
+    return boxen(content, {
+        padding: 1,
+        margin: 1,
+        borderStyle: 'round',
+        borderColor:
+            ship.severity === 'critical' || ship.severity === 'high'
+                ? 'red'
+                : ship.severity === 'medium'
+                  ? 'yellow'
+                  : 'green',
+    });
 }
 
 export function renderSummaryTable(counts, options = {}) {
-  const table = new Table({
-    head: ["Severity", "Count"],
-    style: {
-      head: [],
-      border: []
-    }
-  });
+    const table = new Table({
+        head: ['Severity', 'Count'],
+        style: {
+            head: [],
+            border: [],
+        },
+    });
 
-  for (const severity of SEVERITIES) {
-    const formatted = formatSeverity(severity, options);
-    table.push([formatted.compactText, counts[severity]]);
-  }
+    for (const severity of SEVERITIES) {
+        const formatted = formatSeverity(severity, options);
+        table.push([formatted.shortText, counts[severity]]);
+    }
 
-  return table.toString();
+    return table.toString();
 }
 
 function severityColor(value, severity, colors) {
-  if (severity === "critical") return colors.bgRed.white.bold(value);
-  if (severity === "high") return colors.red.bold(value);
-  if (severity === "medium") return colors.yellow.bold(value);
-  return colors.bold(value);
+    if (severity === 'critical') return colors.bgRed.white.bold(value);
+    if (severity === 'high') return colors.red.bold(value);
+    if (severity === 'medium') return colors.yellow.bold(value);
+    return colors.bold(value);
 }
 
 function lowercaseFirst(value) {
-  if (!value) return value;
-  const normalized = String(value).replace(/\.$/, "");
-  return `${normalized.charAt(0).toLowerCase()}${normalized.slice(1)}`;
+    if (!value) return value;
+    const normalized = String(value).replace(/\.$/, '');
+    return `${normalized.charAt(0).toLowerCase()}${normalized.slice(1)}`;
+}
+
+function isSecretFinding(finding) {
+    return (
+        finding.category === 'env' ||
+        finding.tags?.some(tag => /secret|token|credential/i.test(tag)) ||
+        Boolean(finding.metadata?.secretType)
+    );
+}
+
+function collapseWhitespace(value) {
+    return String(value).replace(/\s+/g, ' ').trim();
 }