itworksbut 0.1.1 → 0.3.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.
 
-It only reads files and reports findings. It does not call external APIs, does not send telemetry, and does not modify the scanned project.
+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 unless you explicitly ask it to write `todo.md` with `--todo`.
 
 ## 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,84 +25,77 @@ 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 --todo
+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.
+- `--todo`: Write an AI-ready `todo.md` into the scanned project with prioritized findings, fix prompts, and acceptance criteria.
+- `--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:
+To create a fix list for a coding agent:
 
-- `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
+```sh
+itworksbut scan --todo
+```
 
-Severity levels are `critical`, `high`, `medium`, `low`, and `info`.
+This writes `todo.md` to the scanned project. The file is ordered by severity and includes agent rules, exact fix prompts, locations, recommendations, and final verification checkboxes.
 
 ## GitHub Actions
 
@@ -121,13 +117,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
@@ -169,20 +165,21 @@ release/**
 
 ## Example Output
 
-```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.
-
-▲  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.
+![screenshot of an example output](/assets/medium_problems.webp)
+✖ 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.
+🤖 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.
+🤖 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
 - Fix the red stuff before production.
 - total findings: 2
@@ -193,6 +190,7 @@ SUMMARY
 - info: 0
 - fail-on: high
 - exit decision: 1
+
 ```
 
 Secret-like findings never print the full secret value. Findings report the file, line, and secret type where possible.
@@ -239,3 +237,4 @@ Each check is a plain ESM module with an `id`, metadata, and async `run(context)
 ItWorksBut is a static heuristic scanner, not a pentest, SAST replacement, dependency vulnerability database, or runtime security monitor. Findings intentionally use wording such as "possible", "potential", and "appears to" when a check is heuristic.
 
 Use it as a CI guardrail for common project hygiene and security mistakes. For production systems, combine it with code review, tests, dependency scanning, secrets scanning, threat modeling, and focused security assessment.
+```

package/bin/itworksbut.js

@@ -1,63 +1,72 @@
 #!/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';
+import { writeTodoReport } from '../src/reporters/todoReporter.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 if (args.todo) {
+        const filePath = await writeTodoReport(result);
+        if (!args.quiet) process.stdout.write(`Wrote AI todo file: ${filePath}\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.3.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
 
@@ -12,17 +14,24 @@ Options:
                      Levels: critical, high, medium, low, info. Default: low.
   --json              Print machine-readable JSON.
   --sarif             Print SARIF for GitHub Code Scanning.
+  --todo              Write an AI-ready todo.md to the scanned project.
   --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", "--todo", "--verbose", "--help", "-h", "--version", "-v", "--no-color", "--no-banner", "--quiet"]);
 
 export function parseArgs(argv) {
   const args = {
@@ -9,14 +9,13 @@ export function parseArgs(argv) {
     failOn: undefined,
     json: false,
     sarif: false,
+    todo: false,
     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 +44,13 @@ 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 === "--todo") args.todo = 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;
     }
@@ -59,8 +58,8 @@ export function parseArgs(argv) {
     throw new Error(`Unknown argument: ${token}`);
   }
 
-  if (args.json && args.sarif) {
-    throw new Error("Use only one output format: --json or --sarif");
+  if ([args.json, args.sarif, args.todo].filter(Boolean).length > 1) {
+    throw new Error("Use only one output format: --json, --sarif, or --todo");
   }
 
   return args;
@@ -70,6 +69,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.todo && !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 (options.noColor || options.json || options.sarif || options.todo) return false;
   if (env.FORCE_COLOR && env.FORCE_COLOR !== "0") return true;
   if (env.CI) return false;
   return Boolean(stdout.isTTY);
@@ -51,7 +40,7 @@ export function shouldUseSpinner(options = {}, env = process.env, stdout = proce
     !env.CI &&
     !options.json &&
     !options.sarif &&
-    !options.noSpinner &&
+    !options.todo &&
     !options.quiet
   );
 }
@@ -61,23 +50,18 @@ export function createScanSpinner(options = {}) {
   return ora({
     text: SPINNER_TEXT.default,
     stream: process.stderr,
-    color: normalizeTheme(options.theme) === "toxic" ? "green" : "cyan"
+    color: "cyan"
   });
 }
 
 export function printIntro(options = {}) {
-  if (options.json || options.sarif || options.noBanner || options.quiet || process.env.CI || !process.stdout.isTTY) {
+  if (options.json || options.sarif || options.todo || options.noBanner || options.quiet || process.env.CI || !process.stdout.isTTY) {
     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 +69,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 +87,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,