mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-12 06:06:37 +03:00
672517f76e
* docs: add PRD for design detector hook integration Plans a PostToolUse hook for Claude Code and Codex that runs the existing design detector after every relevant file write and feeds findings back to the agent as advisory system-reminder context. No implementation in this commit; covers UX, technical design, build pipeline changes, distribution, coverage tradeoffs, and rollout. Co-authored-by: Cursor <cursoragent@cursor.com> * docs: revise hook PRD with best-practices review Folds in the P0/P1/P2 findings from an online best-practices critique against the official Claude Code and Codex hook references plus 10+ 2026 community guides and similar prior-art tools (claw-hooks, claude-code-hooks-mastery). Key changes: - Exec form everywhere (Codex snippet was shell form), with Windows rationale. - Default timeout dropped from 10s to 5s. - Re-entrancy guard (CLAUDE_HOOK_DEPTH) and per-file edit counter. - Session-scoped finding dedup promoted from open question to v1. - Per-language inline-ignore syntax map (HTML/JSX/CSS/JS). - Hard-skip rules for sensitive paths and generated/lock files. - Honest framing about Claude Code lacking per-plugin hook disable. - Honest framing about Bash-written files being invisible in v1. - Codex Windows-not-supported call-out, feature flag note, trust ceremony detail. - Optional NDJSON audit log via IMPECCABLE_HOOK_LOG. - Findings cap lowered 8 → 5 with attention-budget rationale. - Versioned envelope ([impeccable@1]) on rendered template. - Expanded test plan, decision log, and stdin payload appendix. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(hooks): ship the design detector hook for Claude Code and Codex Implements docs/hooks-prd.md: a PostToolUse hook that runs the impeccable design detector after every Edit/Write/MultiEdit on a UI file and pushes findings into the agent's next-turn context as a short system reminder. Silent on clean files. Never blocks an edit. Why this matters: today, design slop (side-tab borders, gradient text, purple/cyan palettes, bounce easing, etc.) only gets caught when a human notices or someone explicitly runs /impeccable audit. The hook closes the loop at the moment slop is written. What ships in v1 - skill/scripts/hook.mjs: PostToolUse entry. Reads stdin, runs the detector in-process (no `npx impeccable` cold start), emits hookSpecificOutput.additionalContext when fresh findings exist. - skill/scripts/hook-lib.mjs: extracted helpers (config, cache, filter, render, audit log, runHook orchestrator). 100% unit-testable. - skill/scripts/hook-session-start.mjs: SessionStart greeting, gated by a project-scannable probe + 30-day throttle. - skill/scripts/hook-admin.mjs: backs /impeccable hooks on/off/status/ignore-rule/ignore-file/reset. Hardening built in - Re-entrancy guard (IMPECCABLE_HOOK_DEPTH) so the hook can never recursively spawn itself. - Hard-skip regexes for sensitive paths (.env, .pem, id_rsa, secrets, credentials, .git) and generated/lock/build output. These fire before the file is even read; cannot be turned off via config. - Path-traversal check on the inbound file_path. - Session-scoped dedup keyed by (session, file, rule, line) so the same finding never lands in context twice. Prevents the ~12.5K wasted tokens per chatty session called out in the PRD. - Per-(session, file) edit counter with a one-shot suppression notice on the 7th edit, silent after. - Fail-open contract: every error path returns exit 0 with no stdout. Optional NDJSON audit log via IMPECCABLE_HOOK_LOG. Three kill switches (precedence high to low): 1. IMPECCABLE_HOOK_DISABLED env var (1/true/yes/on, case-insensitive) 2. .impeccable/hook.json `enabled: false` 3. /impeccable hooks off slash command (writes the JSON) Inline ignores are language-aware. `// impeccable: ignore <rule>` for JS/TS, `<!-- impeccable: ignore <rule> -->` for HTML/Vue/Svelte/Astro, `{/* impeccable: ignore <rule> */}` for JSX/TSX, `/* impeccable: ignore <rule> */` for CSS. `*` matches any rule. Directive applies to the next non-blank line. Same shape as ESLint, Stylelint, Biome. Build pipeline - scripts/lib/transformers/hooks.js: per-provider hooks.json builders, plus the slim .codex-plugin/plugin.json manifest. - providers.js: emitHooks: 'claude' for claude-code, emitHooks: 'codex' for codex and agents. Codex also emits emitCodexPlugin. - factory.js: emits hooks/hooks.json next to the skills tree. - build.js: syncs hooks/ into harness roots and into the slim plugin/ subtree; writes .codex-plugin/plugin.json. Build is idempotent (verified: 98 staged files unchanged across two runs). Claude Code wiring uses exec form (command + args) and the ${CLAUDE_PLUGIN_ROOT} placeholder. Matcher: Edit|Write|MultiEdit. `if:` glob filters to UI extensions before spawning Node. PostToolUse timeout 5s, SessionStart timeout 3s. Codex wiring uses ${PLUGIN_ROOT} (Codex's native placeholder), matcher Edit|Write|apply_patch, no `if:` analog (the script does the extension filter). macOS and Linux only; hooks are disabled on Windows in current Codex builds. The trust ceremony and feature flag are documented in README.md. Routing - /impeccable hooks lives outside the 23-command router table on purpose: it is plumbing, not a design skill. The hidden routing slot is added to SKILL.md alongside pin/unpin so the LLM knows to dispatch it. The 23-command count and all stale-count validators remain happy. Tests - tests/hook.test.mjs: 38 unit tests covering env parsing, config load + defaults + malformed, cache round-trip + GC, ignoreRules/minSeverity/inline ignores (all four languages), globbing with **/*/{a,b}, render template with cap + clamp + 0-line prefix drop, audit log NDJSON, payload event-name parameterization, re-entrancy, kill switches, sensitive-path + generated-path + traversal skips, allowlist filter, config ignoreFiles, edit counter cycle including the 7th-edit notice, MultiEdit and apply_patch payload shapes, detector throw swallow, malformed stdin, missing file race. - tests/hook-build.test.mjs: 18 integration tests covering hook manifest shape (matcher, timeouts, exec form, if: glob, placeholders), Codex differences (${PLUGIN_ROOT}, no if:, no SessionStart), Codex plugin manifest (no inline hooks field to avoid the duplicate-file error), routing across the hooksJsonFor table, and presence of all three committed artifacts plus the bundled detector the runtime relative-import path depends on. Full suite: 175 bun tests + 186 node tests, all green. Docs - README.md: new "Design hook" section explaining default behavior, per-project / global / inline disable paths, the JSON schema knobs, the audit log debug flag, and the slop / a11y coverage split. - HARNESSES.md: flips the `hooks` row for Codex from No -> Yes (Claude was already Yes), adds a per-harness hook-surface table with the manifest location and matcher each provider uses. Open questions from the PRD intentionally deferred to v2: Bash-write blind spot, effort-aware suppression, Stop-hook session summary, per-rule severity, async hook mode. None block v1. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix Codex hook scanning: apply_patch paths and co-located stylesheets Parse file targets from Codex apply_patch command bodies, co-scan imported and sibling CSS when UI components are edited, drop the git-sweep PostToolUse group, and align Codex SessionStart manifest and trust docs with the official hooks spec. Co-authored-by: Cursor <cursoragent@cursor.com> * Gitignore hook session cache and drop local test HTML Hook dedup/throttle state in .impeccable/hook.cache.json is per-project runtime data like other .impeccable/ sidecars. Remove an untracked bad-nested-flexbox scratch page from site/public/. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix Claude Code hook: drop Edit-only if filter so Write/MultiEdit fire Claude's if permission rule binds to one tool name, so Edit(*.{…}) never spawned the hook on Write or MultiEdit despite the matcher listing them. Extension filtering now lives in hook-lib on both Claude and Codex. Co-authored-by: Cursor <cursoragent@cursor.com> * Surface Cursor design findings via stop-hook followup Replace dropped postToolUse additional_context with afterFileEdit recording and a one-shot stop followup_message so anti-pattern nudges reach the agent. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix design hook packaging and scans * Fix Cursor hook pending bucket fallback * Fix Sass hook scan coverage * Fix Cursor hook review findings * Fix session start dead hook normalization * Fix hook config and relative scan paths * Remove SessionStart design hook * Remove redundant afterFileEdit normalization * Fix Cursor suppression and module style scans * Fix sensitive path hook filter * Fix disabled Cursor stop hook emission * Refresh hook harness artifacts * Fix Cursor hook manifest install * Add hook ignore-value support * Ignore hook runtime files locally * Fix Codex plugin hook packaging * fix: address PR review bot findings Block numeric hook depth counters from re-entering. Avoid following stylesheet imports from traversal-looking hook targets. * fix: gate ignore-value suggestions by supported rules Only render exact ignore-value commands when the same finding can be suppressed by ignoreValues. * Package Codex plugin as hook-only * Remove Codex plugin packaging * Recover hook install probe plumbing * Remove Codex hook packaging follow-up doc * Remove extra hook docs and skill wording changes * Install real design hooks via skills CLI * Add provider hook smoke runner * Fix Cursor hook delivery with preToolUse gate * Simplify Cursor hook install to preToolUse * Clarify confirmed hook exceptions * Persist hook ignores in shared config * Guard font hook exceptions * Fix hook install after main rebase * Fix hook scan target handling * fix: address hook review findings * Address hook review feedback * Stabilize DeepSeek insert live fixture * Fix Cursor hook Python shell write bypass --------- Co-authored-by: Cursor <cursoragent@cursor.com>
111 lines
3.9 KiB
JSON
111 lines
3.9 KiB
JSON
{
|
|
"name": "impeccable",
|
|
"version": "2.3.2",
|
|
"author": "Paul Bakaus",
|
|
"description": "Design skills, commands, and anti-pattern detection for AI coding agents",
|
|
"keywords": [
|
|
"design",
|
|
"frontend",
|
|
"ux",
|
|
"skills",
|
|
"ai",
|
|
"anti-patterns",
|
|
"lint",
|
|
"accessibility",
|
|
"css",
|
|
"html",
|
|
"detection",
|
|
"ci-cd"
|
|
],
|
|
"license": "Apache-2.0",
|
|
"homepage": "https://impeccable.style",
|
|
"repository": {
|
|
"type": "git",
|
|
"url": "git+https://github.com/pbakaus/impeccable.git"
|
|
},
|
|
"engines": {
|
|
"node": ">=24"
|
|
},
|
|
"type": "module",
|
|
"bin": {
|
|
"impeccable": "cli/bin/cli.js"
|
|
},
|
|
"main": "./cli/engine/detect-antipatterns.mjs",
|
|
"exports": {
|
|
".": "./cli/engine/detect-antipatterns.mjs",
|
|
"./browser": "./cli/engine/detect-antipatterns-browser.js"
|
|
},
|
|
"files": [
|
|
"cli/",
|
|
"LICENSE"
|
|
],
|
|
"scripts": {
|
|
"build:skills": "bun run scripts/build.js --skip-root-sync",
|
|
"build:skills:release": "bun run scripts/build.js",
|
|
"build:site": "npx astro build",
|
|
"build": "bun run build:skills && bun run build:site && cp -R dist build/_data/dist",
|
|
"build:release": "bun run build:skills:release && bun run build:site && cp -R dist build/_data/dist",
|
|
"build:browser": "node scripts/build-browser-detector.js",
|
|
"build:extension": "node scripts/build-extension.js",
|
|
"clean": "rm -rf dist build",
|
|
"rebuild": "bun run clean && bun run build",
|
|
"rebuild:release": "bun run clean && bun run build:release",
|
|
"dev": "bun run scripts/gen-dev-api.mjs && npx astro dev",
|
|
"preview": "bun run build && npx astro preview",
|
|
"deploy": "bun run build && wrangler pages deploy build/",
|
|
"test": "node scripts/run-tests.mjs default",
|
|
"test:core": "node scripts/run-tests.mjs core",
|
|
"test:detector": "node scripts/run-tests.mjs detector",
|
|
"test:framework": "node scripts/run-tests.mjs framework",
|
|
"test:live": "node scripts/run-tests.mjs live",
|
|
"test:cli-e2e": "node scripts/run-tests.mjs cli-e2e",
|
|
"test:cli-remote-e2e": "node scripts/run-tests.mjs cli-remote-e2e",
|
|
"test:live-e2e": "node scripts/run-tests.mjs live-e2e",
|
|
"test:live-e2e-accept-cleanup": "node scripts/run-tests.mjs live-e2e-accept-cleanup",
|
|
"test:live-e2e-agent": "node scripts/run-tests.mjs live-e2e-agent",
|
|
"test:skill-behavior": "node scripts/run-tests.mjs skill-behavior",
|
|
"test:live-svelte-adapter-deepseek": "node scripts/run-tests.mjs live-svelte-adapter-deepseek",
|
|
"smoke:hooks": "node scripts/smoke-provider-hooks.mjs",
|
|
"bench:detector": "node scripts/benchmark-detector.mjs",
|
|
"bench:detector:browser": "node scripts/benchmark-detector.mjs --browser",
|
|
"audit": "bun audit --audit-level=moderate",
|
|
"prepack": "cp README.md README.repo.md && cp README.npm.md README.md",
|
|
"postpack": "cp README.repo.md README.md && rm README.repo.md",
|
|
"release:skill": "node scripts/release.mjs skill",
|
|
"release:cli": "node scripts/release.mjs cli",
|
|
"release:ext": "node scripts/release.mjs extension",
|
|
"screenshot": "bun run scripts/screenshot-antipatterns.js",
|
|
"og-image": "bun run scripts/generate-og-image.js"
|
|
},
|
|
"dependencies": {
|
|
"css-select": "^7.0.0",
|
|
"css-tree": "^3.2.1",
|
|
"domutils": "^4.0.2",
|
|
"extract-zip": "^2.0.1",
|
|
"htmlparser2": "^12.0.0",
|
|
"marked": "^18.0.5"
|
|
},
|
|
"optionalDependencies": {
|
|
"puppeteer": "^25.1.0"
|
|
},
|
|
"devDependencies": {
|
|
"@ai-sdk/anthropic": "^3.0.71",
|
|
"@ai-sdk/google": "^3.0.75",
|
|
"@ai-sdk/openai": "^3.0.53",
|
|
"@anthropic-ai/claude-agent-sdk": "^0.3.165",
|
|
"@anthropic-ai/sdk": "^0.102.0",
|
|
"@google/genai": "^2.8.0",
|
|
"@paper-design/shaders": "^0.0.76",
|
|
"ai": "^6.0.168",
|
|
"archiver": "^8.0.0",
|
|
"astro": "^6.2.1",
|
|
"fontkit": "^2.0.4",
|
|
"modern-screenshot": "^4.7.0",
|
|
"motion": "^12.38.0",
|
|
"opentype.js": "^2.0.0",
|
|
"playwright": "^1.59.1",
|
|
"wrangler": "^4.85.0",
|
|
"zod": "^4.3.6"
|
|
}
|
|
}
|