itworksbut 0.1.1

package/README.md

@@ -0,0 +1,241 @@
+# ItWorksBut
+
+ItWorksBut is a Node.js CI tool for static checks in JavaScript, Node.js, web, Tauri, and Electron vibe coding projects.
+
+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.
+
+## Installation
+
+```sh
+npx itworksbut scan
+```
+
+### Homebrew
+
+After the formula is committed to the tap, install with:
+
+```sh
+brew tap oliverjessner/tap
+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:
+
+```sh
+npm login
+npm run publish
+```
+
+Do not run `npm publish` directly. The package blocks direct npm publishing so the Homebrew tap cannot be forgotten.
+
+Preview everything without publishing:
+
+```sh
+npm run publish -- --dry-run
+```
+
+By default the script expects the tap checkout at `../homebrew-tap`. Override it when needed:
+
+```sh
+npm run publish -- --tap-path /path/to/homebrew-tap
+```
+
+Use `--no-push` when you want the script to commit the tap formula but leave the push to you.
+
+## Local Usage
+
+```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
+```
+
+`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.
+
+## Terminal Experience
+
+Normal console output is intentionally more opinionated than the machine-readable reporters:
+
+```sh
+node ./bin/itworksbut.js scan --theme toxic
+```
+
+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
+name: ItWorksBut
+
+on:
+    pull_request:
+    push:
+        branches: [main]
+
+jobs:
+    scan:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 20
+                  cache: npm
+            - run: npm ci
+            - run: node ./bin/itworksbut.js scan --fail-on high
+```
+
+For GitHub Code Scanning-style output:
+
+```sh
+node ./bin/itworksbut.js scan --sarif > itworksbut.sarif
+```
+
+## Configuration
+
+Optional `itworksbut.config.json`:
+
+```json
+{
+    "ignore": ["dist/**", "build/**", "node_modules/**"],
+    "failOn": "low",
+    "checks": {
+        "env.env-file-tracked": true,
+        "dependencies.lockfile-missing": true,
+        "node.rate-limit-missing": false
+    }
+}
+```
+
+Checks are enabled by default. Set a check id to `false` to disable it.
+
+This repository also has `itworksbut.self.config.json` for its own CI run. It ignores intentional test fixtures and scanner regex files. Do not use that profile if you want the highest finding rate.
+
+Default ignored paths:
+
+```text
+node_modules/**
+dist/**
+build/**
+.next/**
+.nuxt/**
+coverage/**
+.git/**
+target/**
+src-tauri/target/**
+out/**
+release/**
+.vite/**
+```
+
+## 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.
+
+SUMMARY
+- ship status: DO NOT SHIP
+- Fix the red stuff before production.
+- total findings: 2
+- critical: 1
+- high: 1
+- medium: 0
+- low: 0
+- 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.
+
+## What It Detects
+
+The baseline includes 30 modular checks:
+
+- `git.gitignore-missing`
+- `git.gitignore-incomplete`
+- `git.ignored-files-tracked`
+- `env.env-file-tracked`
+- `env.env-example-missing`
+- `env.possible-secret-in-code`
+- `env.frontend-secret-exposure`
+- `dependencies.lockfile-missing`
+- `dependencies.multiple-lockfiles`
+- `dependencies.install-scripts-risk`
+- `dependencies.audit-script-missing`
+- `package.scripts-missing`
+- `ci.no-ci-config`
+- `ci.npm-install-instead-of-npm-ci`
+- `ci.no-build-step`
+- `ci.no-test-step`
+- `node.express-json-limit-missing`
+- `node.rate-limit-missing`
+- `node.helmet-missing`
+- `node.cors-wildcard`
+- `web.client-side-auth-only`
+- `web.dangerous-inner-html`
+- `web.missing-output-sanitization`
+- `api.missing-auth-on-routes`
+- `api.idor-risk`
+- `database.raw-sql-interpolation`
+- `database.no-migrations`
+- `electron.node-integration-enabled`
+- `electron.context-isolation-disabled`
+- `tauri.dangerous-allowlist-or-capabilities`
+
+Each check is a plain ESM module with an `id`, metadata, and async `run(context)` function. Add new checks under `src/checks/` and register them in `src/checks/index.js`.
+
+## What It Does Not Guarantee
+
+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

@@ -0,0 +1,63 @@
+#!/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";
+
+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);
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error) => {
+    printRuntimeError(error);
+    process.exitCode = 2;
+  });

package/itworksbut.config.json

@@ -0,0 +1,5 @@
+{
+    "ignore": [],
+    "failOn": "low",
+    "checks": {}
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+    "name": "itworksbut",
+    "version": "0.1.1",
+    "description": "Static CI checks for common security, repo, dependency, build, and deployment risks in JavaScript vibe coding projects.",
+    "type": "module",
+    "bin": {
+        "itworksbut": "bin/itworksbut.js"
+    },
+    "files": [
+        "bin",
+        "src",
+        "README.md",
+        "itworksbut.config.json"
+    ],
+    "engines": {
+        "node": ">=20"
+    },
+    "scripts": {
+        "test": "node --test",
+        "build": "node --check ./bin/itworksbut.js",
+        "lint": "node --check ./bin/itworksbut.js",
+        "check": "npm test",
+        "audit": "npm audit",
+        "dev": "node ./bin/itworksbut.js scan --verbose",
+        "publish": "npm login --auth-type=web && node ./scripts/publish.js",
+        "brew:formula": "node ./scripts/publish-brew.js",
+        "prepublishOnly": "node ./scripts/guard-npm-publish.js"
+    },
+    "keywords": [
+        "security",
+        "ci",
+        "static-analysis",
+        "node",
+        "electron",
+        "tauri"
+    ],
+    "license": "MIT",
+    "dependencies": {
+        "boxen": "^8.0.1",
+        "chalk": "^5.6.2",
+        "cli-table3": "^0.6.5",
+        "figlet": "^1.11.0",
+        "gradient-string": "^3.0.0",
+        "ora": "^9.4.0"
+    }
+}

package/src/checks/auth/idor-risk.js

@@ -0,0 +1,45 @@
+import { hasOwnerKeyword, lineFromOffset, readNearby } from "../helpers.js";
+
+const IDOR_PATTERNS = [
+  { regex: /findUnique\s*\(\s*{[\s\S]{0,220}?where\s*:\s*{[\s\S]{0,120}?\bid\b/g, label: "findUnique by id" },
+  { regex: /\bSELECT\b[\s\S]{0,180}?\bWHERE\b[\s\S]{0,80}?\bid\s*=\s*(?:\?|[$:]\w+|\$\{)/gi, label: "SQL lookup by id" },
+  { regex: /["'`]\/api\/[^"'`]*\/:id["'`]/g, label: "API route with :id parameter" }
+];
+
+export default {
+  id: "api.idor-risk",
+  title: "Object lookup by id should be scoped to the authenticated owner",
+  category: "auth",
+  severity: "high",
+  tags: ["api", "auth", "idor", "heuristic"],
+  run: async (context) => {
+    const findings = [];
+
+    for (const file of context.textFiles) {
+      if (!/\.[cm]?[jt]sx?$/.test(file)) continue;
+      const content = await context.readFileSafe(file);
+      if (!content) continue;
+
+      for (const pattern of IDOR_PATTERNS) {
+        pattern.regex.lastIndex = 0;
+        let match;
+        while ((match = pattern.regex.exec(content)) !== null) {
+          const line = lineFromOffset(content, match.index);
+          const nearby = await readNearby(context, file, line, 8);
+          if (hasOwnerKeyword(nearby)) continue;
+
+          findings.push({
+            message: `Potential IDOR risk: ${pattern.label} appears without a nearby owner, tenant, or user scope check.`,
+            file,
+            line,
+            recommendation: "Scope object reads and writes by authenticated user, owner, account, tenant, or organization, not by id alone.",
+            heuristic: true,
+            metadata: { pattern: pattern.label }
+          });
+        }
+      }
+    }
+
+    return findings.slice(0, 100);
+  }
+};

package/src/checks/auth/missing-auth-on-routes.js

@@ -0,0 +1,55 @@
+import { hasAuthKeyword, isServerOrApiFile, readNearby } from '../helpers.js';
+
+const ROUTE_RE = /\b(?:app|router|fastify)\.(get|post|put|patch|delete)\s*\(\s*["'`]([^"'`]+)["'`]/g;
+
+export default {
+    id: 'api.missing-auth-on-routes',
+    title: 'API routes should have explicit authentication',
+    category: 'auth',
+    severity: 'high',
+    tags: ['api', 'auth', 'heuristic'],
+    run: async context => {
+        const findings = [];
+
+        for (const file of context.textFiles) {
+            if (!/\.[cm]?[jt]s$/.test(file) && !isServerOrApiFile(file)) continue;
+            const content = await context.readFileSafe(file);
+            if (!content) continue;
+
+            if ((file.startsWith('pages/api/') || file.startsWith('app/api/')) && !hasAuthKeyword(content)) {
+                findings.push({
+                    message: 'This API route file does not appear to contain an authentication check.',
+                    file,
+                    recommendation:
+                        'Require authentication and authorization in API route handlers. Public routes should be documented explicitly.',
+                    heuristic: true,
+                });
+                continue;
+            }
+
+            const lines = content.split(/\r?\n/);
+            for (let index = 0; index < lines.length; index += 1) {
+                ROUTE_RE.lastIndex = 0;
+                const match = ROUTE_RE.exec(lines[index]);
+                if (!match) continue;
+                const routePath = match[2];
+                if (!routePath.startsWith('/api') && !isServerOrApiFile(file)) continue;
+
+                const nearby = await readNearby(context, file, index + 1, 6);
+                if (hasAuthKeyword(nearby)) continue;
+
+                findings.push({
+                    message: `Possible unauthenticated API route ${routePath} appears without nearby auth middleware or checks.`,
+                    file,
+                    line: index + 1,
+                    recommendation:
+                        'Add explicit authentication middleware/checks near the route, or document why the route is intentionally public.',
+                    heuristic: true,
+                    metadata: { routePath },
+                });
+            }
+        }
+
+        return findings.slice(0, 100);
+    },
+};

package/src/checks/ci/no-build-step.js

@@ -0,0 +1,23 @@
+import { collectCiFiles } from "../helpers.js";
+
+export default {
+  id: "ci.no-build-step",
+  title: "CI should run a build step",
+  category: "ci",
+  severity: "medium",
+  tags: ["ci", "build"],
+  run: async (context) => {
+    const ciFiles = await collectCiFiles(context);
+    if (ciFiles.length === 0) return [];
+
+    const combined = (await Promise.all(ciFiles.map((file) => context.readFileSafe(file)))).filter(Boolean).join("\n");
+    if (/\b(npm|pnpm|yarn)\s+(run\s+)?build\b|bun\s+run\s+build/i.test(combined)) return [];
+
+    return [
+      {
+        message: "CI configuration exists, but no build step was detected.",
+        recommendation: "Run the project build in CI, for example npm run build, before deployment or merge."
+      }
+    ];
+  }
+};

package/src/checks/ci/no-ci-config.js

@@ -0,0 +1,20 @@
+import { collectCiFiles } from "../helpers.js";
+
+export default {
+  id: "ci.no-ci-config",
+  title: "CI configuration should exist",
+  category: "ci",
+  severity: "medium",
+  tags: ["ci", "deployment"],
+  run: async (context) => {
+    const ciFiles = await collectCiFiles(context);
+    if (ciFiles.length > 0) return [];
+
+    return [
+      {
+        message: "No common CI configuration was found.",
+        recommendation: "Add a CI workflow that installs dependencies from the lockfile and runs tests, linting, and builds."
+      }
+    ];
+  }
+};

package/src/checks/ci/no-test-step.js

@@ -0,0 +1,23 @@
+import { collectCiFiles } from "../helpers.js";
+
+export default {
+  id: "ci.no-test-step",
+  title: "CI should run tests",
+  category: "ci",
+  severity: "medium",
+  tags: ["ci", "tests"],
+  run: async (context) => {
+    const ciFiles = await collectCiFiles(context);
+    if (ciFiles.length === 0) return [];
+
+    const combined = (await Promise.all(ciFiles.map((file) => context.readFileSafe(file)))).filter(Boolean).join("\n");
+    if (/\b(npm|pnpm|yarn)\s+(run\s+)?test\b|bun\s+test|vitest|jest|playwright\s+test/i.test(combined)) return [];
+
+    return [
+      {
+        message: "CI configuration exists, but no test step was detected.",
+        recommendation: "Run automated tests in CI, for example npm test, before deployment or merge."
+      }
+    ];
+  }
+};

package/src/checks/ci/npm-install-instead-of-npm-ci.js

@@ -0,0 +1,29 @@
+import { collectCiFiles } from "../helpers.js";
+
+export default {
+  id: "ci.npm-install-instead-of-npm-ci",
+  title: "CI should prefer npm ci over npm install",
+  category: "ci",
+  severity: "medium",
+  tags: ["ci", "dependencies", "reproducibility"],
+  run: async (context) => {
+    const findings = [];
+    for (const file of await collectCiFiles(context)) {
+      const content = await context.readFileSafe(file);
+      if (!content) continue;
+      const lines = content.split(/\r?\n/);
+      for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (/\bnpm\s+install\b/.test(line) && !/\bnpm\s+install\s+(-g|--global)\b/.test(line)) {
+          findings.push({
+            message: "CI appears to use npm install instead of npm ci.",
+            file,
+            line: index + 1,
+            recommendation: "Use npm ci in CI so installs are clean and lockfile-driven."
+          });
+        }
+      }
+    }
+    return findings;
+  }
+};

package/src/checks/database/no-migrations.js

@@ -0,0 +1,33 @@
+const DB_PACKAGES = ["prisma", "@prisma/client", "drizzle-orm", "sequelize", "knex", "sqlite", "sqlite3", "better-sqlite3", "pg", "mysql2"];
+const MIGRATION_PATTERNS = [
+  "prisma/migrations/**",
+  "migrations/**",
+  "db/migrations/**",
+  "src/db/migrations/**",
+  "drizzle/**"
+];
+
+export default {
+  id: "database.no-migrations",
+  title: "Database projects should include migrations",
+  category: "database",
+  severity: "medium",
+  tags: ["database", "deployment"],
+  run: async (context) => {
+    const dbDetected =
+      DB_PACKAGES.some((name) => context.hasDependency(name) || context.hasDevDependency(name)) ||
+      context.allFiles.some((file) => file === "prisma/schema.prisma" || file.endsWith(".sql"));
+
+    if (!dbDetected) return [];
+    const hasMigrations = MIGRATION_PATTERNS.some((pattern) => context.findFiles(pattern).length > 0);
+    if (hasMigrations) return [];
+
+    return [
+      {
+        message: "Database or ORM usage appears to exist, but no migrations directory was found.",
+        recommendation: "Add versioned database migrations and run them through a controlled deployment process.",
+        heuristic: true
+      }
+    ];
+  }
+};

package/src/checks/database/raw-sql-interpolation.js

@@ -0,0 +1,41 @@
+import { lineFromOffset } from "../helpers.js";
+
+const SQL_TEMPLATE_RE = /`[^`]*\b(SELECT|INSERT|UPDATE|DELETE|WITH)\b[^`]*\$\{[^`]*`/gi;
+const SQL_CONCAT_RE = /\b(SELECT|INSERT|UPDATE|DELETE|WITH)\b[^;\n]*(?:["'`]\s*\+|\+\s*["'`])[^;\n]*/gi;
+
+export default {
+  id: "database.raw-sql-interpolation",
+  title: "Raw SQL should not be built with string interpolation",
+  category: "database",
+  severity: "high",
+  tags: ["database", "sql-injection"],
+  run: async (context) => {
+    const findings = [];
+
+    for (const file of context.textFiles) {
+      if (!/\.[cm]?[jt]sx?$/.test(file)) continue;
+      const content = await context.readFileSafe(file);
+      if (!content) continue;
+
+      for (const pattern of [
+        { regex: SQL_TEMPLATE_RE, label: "template string interpolation" },
+        { regex: SQL_CONCAT_RE, label: "string concatenation" }
+      ]) {
+        pattern.regex.lastIndex = 0;
+        let match;
+        while ((match = pattern.regex.exec(content)) !== null) {
+          findings.push({
+            message: `Possible SQL injection risk: raw SQL appears to be built with ${pattern.label}.`,
+            file,
+            line: lineFromOffset(content, match.index),
+            recommendation: "Use parameterized queries, prepared statements, or ORM query builders instead of interpolating values into SQL strings.",
+            heuristic: true,
+            metadata: { pattern: pattern.label }
+          });
+        }
+      }
+    }
+
+    return findings.slice(0, 100);
+  }
+};

package/src/checks/dependencies/audit-script-missing.js

@@ -0,0 +1,23 @@
+export default {
+  id: "dependencies.audit-script-missing",
+  title: "Dependency security audit should be available",
+  category: "dependencies",
+  severity: "low",
+  tags: ["dependencies", "supply-chain", "ci"],
+  run: async (context) => {
+    if (!context.packageJson) return [];
+    const scripts = context.packageJson.scripts || {};
+    const hasAudit = Object.entries(scripts).some(([name, command]) => {
+      return /\b(audit|security|sca|snyk|semgrep)\b/i.test(name) || /\b(npm|pnpm|yarn)\s+audit\b|snyk|semgrep/i.test(String(command));
+    });
+    if (hasAudit) return [];
+
+    return [
+      {
+        message: "package.json does not appear to define an audit or security script.",
+        file: "package.json",
+        recommendation: "Add an npm audit or equivalent SCA/security script and run it in CI."
+      }
+    ];
+  }
+};

package/src/checks/dependencies/install-scripts-risk.js

@@ -0,0 +1,18 @@
+const INSTALL_SCRIPTS = ["preinstall", "install", "postinstall"];
+
+export default {
+  id: "dependencies.install-scripts-risk",
+  title: "Install lifecycle scripts should be reviewed",
+  category: "dependencies",
+  severity: "medium",
+  tags: ["dependencies", "supply-chain", "npm"],
+  run: async (context) => {
+    const scripts = context.packageJson?.scripts || {};
+    return INSTALL_SCRIPTS.filter((scriptName) => scripts[scriptName]).map((scriptName) => ({
+      message: `package.json defines an npm ${scriptName} lifecycle script. This can run during dependency installation.`,
+      file: "package.json",
+      recommendation: "Review whether the install-time script is necessary. In CI, prefer npm ci and consider --ignore-scripts where appropriate.",
+      metadata: { scriptName }
+    }));
+  }
+};