From afcff7eea0b79334e184c5a5f04f5fe771843ea7 Mon Sep 17 00:00:00 2001
From: Paul Bakaus <paul.bakaus@gmail.com>
Date: Thu, 19 Mar 2026 00:27:14 -0700
Subject: [PATCH] Add impeccable CLI with detect subcommand

Usage: npx impeccable detect [file-or-dir-or-url...]

Subcommand structure designed for future expansion. The detect
subcommand delegates to the existing detection engine with all
its modes (jsdom, regex, Puppeteer).

- bin/impeccable.mjs: CLI entry point with bun shebang
- package.json: bin field added
- Export detectCli (main) from detection script
- Updated help text to show impeccable detect usage
- Updated CLAUDE.md and README.md with CLI docs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                                     | 16 +++++++
 README.md                                     | 13 ++++++
 bin/impeccable.mjs                            | 43 +++++++++++++++++++
 package.json                                  |  3 ++
 .../critique/scripts/detect-antipatterns.mjs  | 16 ++++---
 5 files changed, 84 insertions(+), 7 deletions(-)
 create mode 100755 bin/impeccable.mjs

diff --git a/CLAUDE.md b/CLAUDE.md
index 33de089a2..4c4112753 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -42,6 +42,22 @@ Source files use placeholders that get replaced per-provider:
 - `{{config_file}}` - Config file name (CLAUDE.md, .cursorrules, etc.)
 - `{{ask_instruction}}` - How to ask user questions
 
+## CLI
+
+Impeccable includes a CLI for running anti-pattern detection outside of AI harnesses:
+
+```bash
+bun bin/impeccable.mjs detect [file-or-dir-or-url...]   # detect anti-patterns
+bun bin/impeccable.mjs detect --fast --json src/         # regex-only, JSON output
+bun bin/impeccable.mjs --help                            # show help
+```
+
+The detection script is at `source/skills/critique/scripts/detect-antipatterns.mjs`. It auto-detects browser vs Node and works as both:
+- **CLI/Node**: jsdom for HTML, regex for CSS/JSX/TSX, Puppeteer for URLs
+- **Browser**: visual overlays injected via `<script src="/js/detect-antipatterns-browser.js">`
+
+Build the browser script: `node scripts/build-browser-detector.js`
+
 ## Versioning
 
 When bumping the version, update **all** of these locations to keep them in sync:
diff --git a/README.md b/README.md
index 37c942024..db6d411b7 100644
--- a/README.md
+++ b/README.md
@@ -145,6 +145,19 @@ Most commands accept an optional argument to focus on a specific area:
 
 **Note:** Codex CLI uses a different syntax: `/prompts:audit`, `/prompts:polish`, etc.
 
+## CLI
+
+Impeccable includes a standalone CLI for detecting anti-patterns without an AI harness:
+
+```bash
+npx impeccable detect src/                   # scan a directory
+npx impeccable detect index.html             # scan an HTML file
+npx impeccable detect https://example.com    # scan a URL (Puppeteer)
+npx impeccable detect --fast --json .        # regex-only, JSON output
+```
+
+The detector catches 25 issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
+
 ## Supported Tools
 
 - [Cursor](https://cursor.com)
diff --git a/bin/impeccable.mjs b/bin/impeccable.mjs
new file mode 100755
index 000000000..5703363eb
--- /dev/null
+++ b/bin/impeccable.mjs
@@ -0,0 +1,43 @@
+#!/usr/bin/env bun
+
+/**
+ * Impeccable CLI
+ *
+ * Usage:
+ *   npx impeccable detect [file-or-dir-or-url...]
+ *   npx impeccable detect --fast --json src/
+ *   npx impeccable --help
+ */
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(`Usage: impeccable <command> [options]
+
+Commands:
+  detect [file-or-dir-or-url...]   Scan for UI anti-patterns and design quality issues
+
+Options:
+  --help    Show this help message
+
+Run 'impeccable detect --help' for detection-specific options.`);
+  process.exit(0);
+}
+
+if (command === '--version' || command === '-v') {
+  const pkg = await import('../package.json', { with: { type: 'json' } });
+  console.log(pkg.default.version);
+  process.exit(0);
+}
+
+if (command === 'detect') {
+  // Remove 'detect' from argv so the detection script sees the right args
+  process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
+  const { detectCli } = await import('../source/skills/critique/scripts/detect-antipatterns.mjs');
+  await detectCli();
+} else {
+  console.error(`Unknown command: ${command}`);
+  console.error(`Run 'impeccable --help' for available commands.`);
+  process.exit(1);
+}
diff --git a/package.json b/package.json
index c199a4e8d..8943b9df5 100644
--- a/package.json
+++ b/package.json
@@ -2,6 +2,9 @@
   "name": "impeccable",
   "version": "1.5.1",
   "author": "Paul Bakaus",
+  "bin": {
+    "impeccable": "./bin/impeccable.mjs"
+  },
   "dependencies": {
     "archiver": "^7.0.1",
     "motion": "^12.38.0",
diff --git a/source/skills/critique/scripts/detect-antipatterns.mjs b/source/skills/critique/scripts/detect-antipatterns.mjs
index b6dbcef46..f76f1a8d8 100644
--- a/source/skills/critique/scripts/detect-antipatterns.mjs
+++ b/source/skills/critique/scripts/detect-antipatterns.mjs
@@ -1909,9 +1909,9 @@ async function handleStdin() {
 // ---------------------------------------------------------------------------
 
 function printUsage() {
-  console.log(`Usage: node detect-antipatterns.mjs [options] [file-or-dir-or-url...]
+  console.log(`Usage: impeccable detect [options] [file-or-dir-or-url...]
 
-Scan files or URLs for known UI anti-patterns.
+Scan files or URLs for UI anti-patterns and design quality issues.
 
 Options:
   --fast    Regex-only mode (skip jsdom, faster but misses linked stylesheets)
@@ -1925,10 +1925,10 @@ Detection modes:
   --fast         Forces regex for all files
 
 Examples:
-  node detect-antipatterns.mjs src/
-  node detect-antipatterns.mjs index.html
-  node detect-antipatterns.mjs https://example.com
-  node detect-antipatterns.mjs --fast --json .`);
+  impeccable detect src/
+  impeccable detect index.html
+  impeccable detect https://example.com
+  impeccable detect --fast --json .`);
 }
 
 async function main() {
@@ -1992,7 +1992,8 @@ async function main() {
 // ---------------------------------------------------------------------------
 
 if (!IS_BROWSER) {
-  const isMainModule = process.argv[1]?.endsWith('detect-antipatterns.mjs');
+  const isMainModule = process.argv[1]?.endsWith('detect-antipatterns.mjs') ||
+    process.argv[1]?.endsWith('detect-antipatterns.mjs/');
   if (isMainModule) main();
 }
 
@@ -2006,6 +2007,7 @@ export {
   checkElementBorders, checkElementMotion, checkElementGlow, checkPageTypography, checkPageLayout, isNeutralColor, isFullPage,
   detectHtml, detectUrl, detectText,
   walkDir, formatFindings, SCANNABLE_EXTENSIONS, SKIP_DIRS,
+  main as detectCli,
 };
 
 // @browser-strip-end