mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-12 06:06:37 +03:00
Add automatic design hook install and exceptions (#170)
* 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>
This commit is contained in:
Abdul Wahab
Cursor
@@ -131,7 +131,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
|
||||
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
|
||||
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
|
||||
|
||||
Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
|
||||
Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
|
||||
|
||||
### Routing rules
|
||||
|
||||
@@ -148,7 +148,7 @@ Plus two management commands: `pin <command>` and `unpin <command>`, detailed be
|
||||
**If `scan.targets` is non-empty, run `node .agents/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
|
||||
|
||||
Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
|
||||
2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
|
||||
4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
|
||||
|
||||
@@ -166,4 +166,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
|
||||
node .agents/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
|
||||
```
|
||||
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
|
||||
## Hooks
|
||||
|
||||
`$impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `$impeccable hooks` with any argument.
|
||||
@@ -0,0 +1,82 @@
|
||||
# $impeccable hooks
|
||||
|
||||
Manage the **design detector hook** for the current project.
|
||||
|
||||
The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code and Codex use `PostToolUse` and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless `IMPECCABLE_HOOK_QUIET=1` is set. Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
|
||||
|
||||
This command toggles the hook **per project** by editing `.impeccable/hook.json`. Local-only ignore policy lives in `.impeccable/hook.local.json`, which is gitignored. To disable globally, set `IMPECCABLE_HOOK_DISABLED=1` in your shell environment.
|
||||
|
||||
Supported harnesses: Claude Code (`.claude/settings.json` in the project), Codex (`.codex/hooks.json` in the project), and Cursor (`.cursor/hooks.json` in the project).
|
||||
|
||||
On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
|
||||
|
||||
## Routing
|
||||
|
||||
The first argument is the action. Defaults to `status`.
|
||||
|
||||
| Action | What it does |
|
||||
|---|---|
|
||||
| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
|
||||
| `on` | Set `enabled: true` in `.impeccable/hook.json`. |
|
||||
| `off` | Set `enabled: false` in `.impeccable/hook.json`. |
|
||||
| `ignore-rule <id>` | Append `<id>` to `ignoreRules`; for `overused-font`, requires `--all-values`. |
|
||||
| `ignore-file <glob>` | Append `<glob>` to `ignoreFiles`. |
|
||||
| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/hook.json`. |
|
||||
| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/hook.local.json`. |
|
||||
| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
|
||||
|
||||
## Flow
|
||||
|
||||
1. Resolve the action from the user's argument. If no action was given, default to `status`.
|
||||
2. Invoke the admin script and pass the user's output through verbatim:
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
|
||||
```
|
||||
|
||||
3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `$impeccable hooks on`."
|
||||
4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
|
||||
5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/hook.json`; add `--local` only when the user explicitly asks for a private exception.
|
||||
6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
|
||||
|
||||
## Intentional findings
|
||||
|
||||
The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
|
||||
|
||||
Prefer the narrowest exception:
|
||||
|
||||
- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/hook.json` by default.
|
||||
- For `overused-font`, use `ignore-value` when the user confirms a specific font. Do not use `ignore-rule overused-font` for a specific font.
|
||||
- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
|
||||
- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
|
||||
- Do not add source comments such as `impeccable: ignore`; inline comments pollute code and are not a supported suppression mechanism.
|
||||
|
||||
Example value-specific exception:
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
|
||||
```
|
||||
|
||||
Example whole-rule font exception:
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
|
||||
```
|
||||
|
||||
Example file-scoped exception:
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Never modify `.impeccable/hook.json` or `.impeccable/hook.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent.
|
||||
- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
|
||||
- Cursor can block a proposed write when the detector finds a real issue. Claude Code and Codex do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
|
||||
- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.json`, `.codex/hooks.json`, and `.cursor/hooks.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- If `.impeccable/hook.json` or `.impeccable/hook.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
|
||||
- If the user asks to "disable the hook" globally, suggest both options: `IMPECCABLE_HOOK_DISABLED=1` env var (one-shot, follows the shell), and `$impeccable hooks off` (persistent for this project, committable).
|
||||
@@ -446,7 +446,7 @@ function detectText(content, filePath, options = {}) {
|
||||
|
||||
// Run regex matchers on the full file content (catches Tailwind classes, inline styles)
|
||||
// Enable block context for CSS files where related properties span multiple lines
|
||||
const cssLike = new Set(['.css', '.scss', '.less']);
|
||||
const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
|
||||
findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
|
||||
profile,
|
||||
phase: 'source',
|
||||
|
||||
@@ -11,7 +11,7 @@ const SKIP_DIRS = new Set([
|
||||
]);
|
||||
|
||||
const SCANNABLE_EXTENSIONS = new Set([
|
||||
'.html', '.htm', '.css', '.scss', '.less',
|
||||
'.html', '.htm', '.css', '.scss', '.sass', '.less',
|
||||
'.jsx', '.tsx', '.js', '.ts',
|
||||
'.vue', '.svelte', '.astro',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,300 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* `/impeccable hooks <on|off|status|reset>` — manage the design hook
|
||||
* via .impeccable/hook.json and .impeccable/hook.local.json in the current
|
||||
* project.
|
||||
*
|
||||
* Usage:
|
||||
* node hook-admin.mjs status # print current state
|
||||
* node hook-admin.mjs on # set enabled: true
|
||||
* node hook-admin.mjs off # set enabled: false
|
||||
* node hook-admin.mjs ignore-rule <rule-id> # append to ignoreRules
|
||||
* node hook-admin.mjs ignore-rule overused-font --all-values
|
||||
* node hook-admin.mjs ignore-file <glob> # append to ignoreFiles
|
||||
* node hook-admin.mjs ignore-value <rule> <value> # append to shared ignoreValues
|
||||
* node hook-admin.mjs ignore-value <rule> <value> --local
|
||||
* node hook-admin.mjs reset # remove all config + cache
|
||||
*
|
||||
* Designed to be invoked by the LLM from the reference/hooks.md flow.
|
||||
* Output is human-readable; the harness will pass it back to the user.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
getConfigPath,
|
||||
getLocalConfigPath,
|
||||
getCachePath,
|
||||
getPendingPath,
|
||||
readConfig,
|
||||
DEFAULT_CONFIG,
|
||||
ensureHookGitExcludes,
|
||||
normalizeIgnoreValue,
|
||||
normalizeIgnoreValueEntries,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
|
||||
|
||||
function readRawConfigFile(filePath) {
|
||||
if (!fs.existsSync(filePath)) return { exists: false, malformed: false, raw: null };
|
||||
try {
|
||||
return { exists: true, malformed: false, raw: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
|
||||
} catch {
|
||||
return { exists: true, malformed: true, raw: null };
|
||||
}
|
||||
}
|
||||
|
||||
function readRawConfig(cwd, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
return readRawConfigFile(filePath).raw;
|
||||
}
|
||||
|
||||
function writeConfig(cwd, config, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
if (opts.local) ensureHookGitExcludes(cwd);
|
||||
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
||||
fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
function mergeConfig(existing) {
|
||||
// Persist the full shape so /impeccable hooks edits leave a complete file
|
||||
// for the user to see, not an unhelpful `{"enabled":false}`.
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
return {
|
||||
enabled: base.enabled === false ? false : true,
|
||||
ignoreRules: Array.isArray(base.ignoreRules) ? Array.from(new Set(base.ignoreRules.map(String))) : [],
|
||||
ignoreFiles: Array.isArray(base.ignoreFiles) ? Array.from(new Set(base.ignoreFiles.map(String))) : [],
|
||||
ignoreValues: normalizeIgnoreValueEntries(base.ignoreValues || []),
|
||||
limits: {
|
||||
maxFindings: Number.isFinite(base?.limits?.maxFindings) ? base.limits.maxFindings : DEFAULT_CONFIG.limits.maxFindings,
|
||||
maxChars: Number.isFinite(base?.limits?.maxChars) ? base.limits.maxChars : DEFAULT_CONFIG.limits.maxChars,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function mergeLocalConfig(existing) {
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
const out = {};
|
||||
if (Object.prototype.hasOwnProperty.call(base, 'enabled')) {
|
||||
out.enabled = base.enabled === false ? false : true;
|
||||
}
|
||||
if (Array.isArray(base.ignoreRules)) {
|
||||
out.ignoreRules = Array.from(new Set(base.ignoreRules.map(String)));
|
||||
}
|
||||
if (Array.isArray(base.ignoreFiles)) {
|
||||
out.ignoreFiles = Array.from(new Set(base.ignoreFiles.map(String)));
|
||||
}
|
||||
out.ignoreValues = normalizeIgnoreValueEntries(base.ignoreValues || []);
|
||||
if (base.limits && typeof base.limits === 'object') {
|
||||
const limits = {};
|
||||
if (Number.isFinite(base.limits.maxFindings)) limits.maxFindings = base.limits.maxFindings;
|
||||
if (Number.isFinite(base.limits.maxChars)) limits.maxChars = base.limits.maxChars;
|
||||
if (Object.keys(limits).length) out.limits = limits;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function statusReport(cwd) {
|
||||
const shared = readRawConfigFile(getConfigPath(cwd));
|
||||
const local = readRawConfigFile(getLocalConfigPath(cwd));
|
||||
const cfg = readConfig(cwd);
|
||||
const envKill = process.env.IMPECCABLE_HOOK_DISABLED;
|
||||
const envState = envKill ? `IMPECCABLE_HOOK_DISABLED=${envKill}` : 'unset';
|
||||
const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.impeccable/hook.json';
|
||||
const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.impeccable/hook.local.json';
|
||||
const cachePath = path.relative(cwd, getCachePath(cwd)) || '.impeccable/hook.cache.json';
|
||||
const fileState = (info, relPath, absent) => {
|
||||
if (info.malformed) return `${relPath} (malformed; ignored)`;
|
||||
if (info.exists) return relPath;
|
||||
return `${relPath} (${absent})`;
|
||||
};
|
||||
const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
|
||||
|
||||
const lines = [
|
||||
`Impeccable design hook`,
|
||||
` state: ${cfg.enabled ? 'enabled' : 'disabled'}`,
|
||||
` shared file: ${fileState(shared, cfgPath, 'using defaults; file not present')}`,
|
||||
` local file: ${fileState(local, localPath, 'not present')}`,
|
||||
` ignoreRules: ${cfg.ignoreRules.length ? cfg.ignoreRules.join(', ') : '(none)'}`,
|
||||
` ignoreFiles: ${cfg.ignoreFiles.length ? cfg.ignoreFiles.join(', ') : '(none)'}`,
|
||||
` ignoreValues: ${ignoreValues.length ? ignoreValues.join(', ') : '(none)'}`,
|
||||
` maxFindings: ${cfg.limits.maxFindings}`,
|
||||
` maxChars: ${cfg.limits.maxChars}`,
|
||||
` env override: ${envState}`,
|
||||
` cache file: ${fs.existsSync(getCachePath(cwd)) ? cachePath : `${cachePath} (not present)`}`,
|
||||
];
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function setEnabled(cwd, value) {
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
config.enabled = value;
|
||||
const target = writeConfig(cwd, config);
|
||||
return `Design hook ${value ? 'enabled' : 'disabled'} for this project (wrote ${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function normalizeRuleId(rule) {
|
||||
return String(rule || '').trim().toLowerCase();
|
||||
}
|
||||
|
||||
function parseIgnoreRuleArgs(args) {
|
||||
const positionals = [];
|
||||
let allValues = false;
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = String(args[i] || '');
|
||||
if (arg === '--all-values') {
|
||||
allValues = true;
|
||||
} else if (arg === '--reason') {
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
|
||||
} else if (arg.startsWith('--reason=')) {
|
||||
// Accepted for command symmetry; ignoreRules stores rule ids only.
|
||||
} else if (arg.startsWith('--')) {
|
||||
throw new Error(`Unknown ignore-rule flag: ${arg}`);
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rule: normalizeRuleId(positionals[0]),
|
||||
allValues,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreRule(cwd, args) {
|
||||
const parsed = parseIgnoreRuleArgs(args);
|
||||
const rule = parsed.rule;
|
||||
if (!rule) throw new Error('Pass a rule id, e.g. /impeccable hooks ignore-rule side-tab');
|
||||
if (rule === 'overused-font' && !parsed.allValues) {
|
||||
throw new Error('overused-font is value-specific by default. Use /impeccable hooks ignore-value overused-font <font> for a confirmed font, or /impeccable hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.');
|
||||
}
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${rule}" to ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
|
||||
}
|
||||
|
||||
function addIgnoreFile(cwd, glob) {
|
||||
if (!glob) throw new Error('Pass a glob, e.g. /impeccable hooks ignore-file "src/legacy/**"');
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${glob}" to ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
|
||||
}
|
||||
|
||||
function parseIgnoreValueArgs(args) {
|
||||
const positionals = [];
|
||||
let shared = false;
|
||||
let local = false;
|
||||
let reason = '';
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = args[i];
|
||||
if (arg === '--shared') {
|
||||
shared = true;
|
||||
} else if (arg === '--local') {
|
||||
local = true;
|
||||
} else if (arg === '--reason') {
|
||||
const chunks = [];
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) {
|
||||
chunks.push(args[++i]);
|
||||
}
|
||||
reason = chunks.join(' ').trim();
|
||||
} else if (String(arg).startsWith('--reason=')) {
|
||||
reason = String(arg).slice('--reason='.length).trim();
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
const [rule, ...valueParts] = positionals;
|
||||
return {
|
||||
rule: String(rule || '').trim().toLowerCase(),
|
||||
value: normalizeIgnoreValue(valueParts.join(' ')),
|
||||
shared,
|
||||
local,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreValue(cwd, args) {
|
||||
const parsed = parseIgnoreValueArgs(args);
|
||||
if (!parsed.rule || !parsed.value) {
|
||||
throw new Error('Pass a rule id and value, e.g. /impeccable hooks ignore-value overused-font Inter');
|
||||
}
|
||||
|
||||
if (parsed.shared && parsed.local) {
|
||||
throw new Error('Pass only one scope flag: --shared or --local');
|
||||
}
|
||||
|
||||
const local = parsed.local;
|
||||
const config = local
|
||||
? mergeLocalConfig(readRawConfig(cwd, { local: true }))
|
||||
: mergeConfig(readRawConfig(cwd, { local: false }));
|
||||
const key = `${parsed.rule}\0${parsed.value}`;
|
||||
const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
|
||||
|
||||
if (existing) {
|
||||
if (parsed.reason) existing.reason = parsed.reason;
|
||||
} else {
|
||||
const entry = {
|
||||
rule: parsed.rule,
|
||||
value: parsed.value,
|
||||
createdAt: new Date().toISOString(),
|
||||
};
|
||||
if (parsed.reason) entry.reason = parsed.reason;
|
||||
config.ignoreValues.push(entry);
|
||||
}
|
||||
|
||||
const target = writeConfig(cwd, config, { local });
|
||||
const scope = local ? 'local ignoreValues' : 'shared ignoreValues';
|
||||
return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function reset(cwd) {
|
||||
const removed = [];
|
||||
for (const filePath of [getConfigPath(cwd), getLocalConfigPath(cwd), getCachePath(cwd), getPendingPath(cwd)]) {
|
||||
try {
|
||||
if (fs.existsSync(filePath)) {
|
||||
fs.unlinkSync(filePath);
|
||||
removed.push(path.relative(cwd, filePath) || filePath);
|
||||
}
|
||||
} catch { /* ignore */ }
|
||||
}
|
||||
return removed.length
|
||||
? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
|
||||
: 'No hook config or cache to remove. Already at defaults.';
|
||||
}
|
||||
|
||||
function main() {
|
||||
const [, , actionArg, ...rest] = process.argv;
|
||||
const action = (actionArg || 'status').toLowerCase();
|
||||
const cwd = process.cwd();
|
||||
|
||||
if (!ACTIONS.has(action)) {
|
||||
process.stderr.write(`Unknown action: ${action}\nValid: ${Array.from(ACTIONS).join(', ')}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
let out = '';
|
||||
switch (action) {
|
||||
case 'status': out = statusReport(cwd); break;
|
||||
case 'on': out = setEnabled(cwd, true); break;
|
||||
case 'off': out = setEnabled(cwd, false); break;
|
||||
case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
|
||||
case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
|
||||
case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
|
||||
case 'reset': out = reset(cwd); break;
|
||||
}
|
||||
process.stdout.write(out + '\n');
|
||||
} catch (err) {
|
||||
process.stderr.write(`Error: ${err.message || err}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,408 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — Cursor preToolUse write gate.
|
||||
*
|
||||
* Cursor's stop hook is not consistently dispatched by the headless agent, so
|
||||
* this hook checks proposed Write/Edit content before it lands. It only denies
|
||||
* writes when the real detector finds an issue in the proposed UI content.
|
||||
*
|
||||
* Contract: never break a turn accidentally. On malformed input or internal
|
||||
* errors, allow the tool and exit 0.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
ALLOWED_EXTS,
|
||||
EDIT_COUNT_THRESHOLD,
|
||||
GENERATED_PATH,
|
||||
SENSITIVE_PATH,
|
||||
filterFindings,
|
||||
loadDetector,
|
||||
matchesAnyGlob,
|
||||
persistCache,
|
||||
readCache,
|
||||
readConfig,
|
||||
renderTemplate,
|
||||
resolveProjectCwd,
|
||||
truthy,
|
||||
writeAuditLog,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
function done(payload = null) {
|
||||
if (payload) process.stdout.write(JSON.stringify(payload));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
function allow(extra = {}, payload = {}) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
...extra,
|
||||
});
|
||||
return done({ permission: 'allow', ...payload });
|
||||
}
|
||||
|
||||
function deny(message, audit) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
blocked: true,
|
||||
...audit,
|
||||
});
|
||||
return done({
|
||||
permission: 'deny',
|
||||
user_message: message,
|
||||
agent_message: message,
|
||||
});
|
||||
}
|
||||
|
||||
function toolInput(event) {
|
||||
return event?.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
|
||||
}
|
||||
|
||||
function proposedFilePath(event, cwd) {
|
||||
const input = toolInput(event);
|
||||
const raw = input.file_path || input.path || input.target_file || event?.file_path;
|
||||
const candidate = typeof raw === 'string' && raw.trim()
|
||||
? raw
|
||||
: shellWriteDestination(shellCommand(input));
|
||||
if (typeof candidate !== 'string' || !candidate.trim()) return '';
|
||||
return path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
|
||||
}
|
||||
|
||||
function proposedContent(event, cwd, filePath) {
|
||||
const input = toolInput(event);
|
||||
for (const key of ['content', 'streamContent', 'text']) {
|
||||
if (typeof input[key] === 'string') return input[key];
|
||||
}
|
||||
|
||||
const editProjection = projectedEditContent(input, filePath, cwd);
|
||||
if (editProjection !== undefined) return editProjection;
|
||||
|
||||
if (hasFragmentEditContent(input)) {
|
||||
return { skipped: 'fragment-only-edit' };
|
||||
}
|
||||
|
||||
const shellContent = shellHereDocContent(shellCommand(input));
|
||||
if (shellContent) return shellContent;
|
||||
const copiedContent = shellCopiedFileContent(shellCommand(input), cwd);
|
||||
if (copiedContent) return copiedContent;
|
||||
return '';
|
||||
}
|
||||
|
||||
function hasFragmentEditContent(input) {
|
||||
if (!input || typeof input !== 'object') return false;
|
||||
if (typeof input.new_string === 'string' || typeof input.newString === 'string' || typeof input.new_str === 'string' || typeof input.replacement === 'string') {
|
||||
return true;
|
||||
}
|
||||
return Array.isArray(input.edits) && input.edits.some((edit) => edit && typeof edit === 'object');
|
||||
}
|
||||
|
||||
function projectedEditContent(input, filePath, cwd) {
|
||||
if (!filePath) return undefined;
|
||||
const singleOld = firstString(input, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const singleNew = firstString(input, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (singleOld !== undefined || singleNew !== undefined) {
|
||||
if (singleOld === undefined || singleNew === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
const projected = replaceOnce(original, singleOld, singleNew);
|
||||
return projected === null ? { skipped: 'edit-old-string-missing' } : projected;
|
||||
}
|
||||
|
||||
if (!Array.isArray(input.edits)) return undefined;
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
|
||||
let projected = original;
|
||||
for (const edit of input.edits) {
|
||||
if (!edit || typeof edit !== 'object') return { skipped: 'fragment-only-edit' };
|
||||
const oldString = firstString(edit, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const newString = firstString(edit, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (oldString === undefined || newString === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const next = replaceOnce(projected, oldString, newString);
|
||||
if (next === null) return { skipped: 'edit-old-string-missing' };
|
||||
projected = next;
|
||||
}
|
||||
return projected;
|
||||
}
|
||||
|
||||
function firstString(obj, keys) {
|
||||
for (const key of keys) {
|
||||
if (typeof obj?.[key] === 'string') return obj[key];
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function replaceOnce(original, oldString, newString) {
|
||||
if (oldString === '') return null;
|
||||
const index = original.indexOf(oldString);
|
||||
if (index === -1) return null;
|
||||
return `${original.slice(0, index)}${newString}${original.slice(index + oldString.length)}`;
|
||||
}
|
||||
|
||||
function readExistingProjectFile(filePath, cwd) {
|
||||
if (!isInsideProject(filePath, cwd)) return null;
|
||||
if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
|
||||
try {
|
||||
const stat = fs.statSync(filePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return null;
|
||||
return fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function shellCommand(input) {
|
||||
if (typeof input.command === 'string') return input.command;
|
||||
if (input.args && typeof input.args.command === 'string') return input.args.command;
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellRedirectPath(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const match = command.match(/(?:^|[\s;&|])(?:>>?|1>>?)\s*(?:"([^"]+)"|'([^']+)'|([^<>\s]+))/);
|
||||
return (match?.[1] || match?.[2] || match?.[3] || '').trim();
|
||||
}
|
||||
|
||||
function shellWriteDestination(command) {
|
||||
return shellRedirectPath(command) || shellTeeDestination(command) || shellCopyPaths(command)?.dest || '';
|
||||
}
|
||||
|
||||
function shellTeeDestination(command) {
|
||||
const words = shellWords(command);
|
||||
const teeIndex = words.findIndex((word) => path.basename(word) === 'tee');
|
||||
if (teeIndex === -1) return '';
|
||||
for (const word of words.slice(teeIndex + 1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
return word;
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellCopiedFileContent(command, cwd) {
|
||||
const source = shellCopyPaths(command)?.source;
|
||||
if (!source) return '';
|
||||
const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
|
||||
if (!isInsideProject(sourcePath, cwd)) return '';
|
||||
if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
|
||||
try {
|
||||
const stat = fs.statSync(sourcePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return '';
|
||||
return fs.readFileSync(sourcePath, 'utf-8');
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
function shellCopyPaths(command) {
|
||||
const words = shellWords(command);
|
||||
if (words.length < 3 || path.basename(words[0]) !== 'cp') return null;
|
||||
const args = [];
|
||||
for (const word of words.slice(1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
args.push(word);
|
||||
}
|
||||
if (args.length < 2) return null;
|
||||
return { source: args[args.length - 2], dest: args[args.length - 1] };
|
||||
}
|
||||
|
||||
function shellWords(command) {
|
||||
if (!command || typeof command !== 'string') return [];
|
||||
const words = [];
|
||||
const re = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'|([^\s]+)/g;
|
||||
let match;
|
||||
while ((match = re.exec(command))) {
|
||||
words.push((match[1] ?? match[2] ?? match[3] ?? '').replace(/\\(["'])/g, '$1'));
|
||||
}
|
||||
return words;
|
||||
}
|
||||
|
||||
function shellHereDocContent(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const markerMatch = command.match(/<<-?\s*['"]?([A-Za-z0-9_.-]+)['"]?[^\r\n]*\r?\n/);
|
||||
if (!markerMatch) return '';
|
||||
const marker = markerMatch[1];
|
||||
const start = (markerMatch.index || 0) + markerMatch[0].length;
|
||||
const rest = command.slice(start);
|
||||
const endRe = new RegExp(`\\r?\\n${escapeRegExp(marker)}(?:\\r?\\n|$)`);
|
||||
const end = rest.search(endRe);
|
||||
return end >= 0 ? rest.slice(0, end) : '';
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
function relativePath(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
|
||||
return rel.split(path.sep).join('/');
|
||||
} catch {
|
||||
return filePath;
|
||||
}
|
||||
}
|
||||
|
||||
function isInsideProject(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function cursorBlockMessage(findings, filePath, config, cwd) {
|
||||
const rendered = renderTemplate(findings, filePath, config, { cwd });
|
||||
const blocked = rendered.replace(
|
||||
'[impeccable@1] Required design corrections',
|
||||
'[impeccable@1] Impeccable design hook blocked this write before it landed. Required design corrections',
|
||||
);
|
||||
return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
|
||||
}
|
||||
|
||||
function findingSignature(findings) {
|
||||
return findings
|
||||
.map((finding) => `${finding.antipattern || 'unknown'}:${finding.line || 0}`)
|
||||
.sort()
|
||||
.join('|');
|
||||
}
|
||||
|
||||
function bumpCursorDenial(cache, sessionId, filePath, findings) {
|
||||
const session = cache.sessions[sessionId] || { updatedAt: Date.now(), files: {} };
|
||||
cache.sessions[sessionId] = session;
|
||||
session.updatedAt = Date.now();
|
||||
const fileEntry = session.files[filePath] || { editCount: 0, findings: [] };
|
||||
session.files[filePath] = fileEntry;
|
||||
const key = findingSignature(findings);
|
||||
fileEntry.cursorDenials = fileEntry.cursorDenials && typeof fileEntry.cursorDenials === 'object'
|
||||
? fileEntry.cursorDenials
|
||||
: {};
|
||||
fileEntry.cursorDenials[key] = (fileEntry.cursorDenials[key] || 0) + 1;
|
||||
return { key, count: fileEntry.cursorDenials[key] };
|
||||
}
|
||||
|
||||
async function main() {
|
||||
if (truthy(process.env.IMPECCABLE_HOOK_DISABLED)) {
|
||||
return allow({ skipped: 'env-disabled' });
|
||||
}
|
||||
|
||||
let event = null;
|
||||
try {
|
||||
const raw = await readStdin();
|
||||
if (raw) event = JSON.parse(raw);
|
||||
} catch {
|
||||
return allow({ skipped: 'stdin-malformed' });
|
||||
}
|
||||
|
||||
if (!event || typeof event !== 'object') {
|
||||
return allow({ skipped: 'stdin-empty' });
|
||||
}
|
||||
|
||||
const cwd = resolveProjectCwd(event);
|
||||
const started = Date.now();
|
||||
const filePath = proposedFilePath(event, cwd);
|
||||
const audit = {
|
||||
harness: 'cursor',
|
||||
tool: event.tool_name || null,
|
||||
file: filePath || null,
|
||||
};
|
||||
|
||||
if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
|
||||
if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
|
||||
if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
|
||||
if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
|
||||
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
audit.ext = ext;
|
||||
if (!ALLOWED_EXTS.has(ext)) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
|
||||
|
||||
const contentResult = proposedContent(event, cwd, filePath);
|
||||
if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
|
||||
return allow({ ...audit, skipped: contentResult.skipped, durationMs: Date.now() - started });
|
||||
}
|
||||
const content = typeof contentResult === 'string' ? contentResult : '';
|
||||
if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
|
||||
|
||||
const config = readConfig(cwd);
|
||||
if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
|
||||
|
||||
const rel = relativePath(filePath, cwd);
|
||||
if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
|
||||
return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const detector = await loadDetector();
|
||||
if (!detector || typeof detector.detectText !== 'function') {
|
||||
return allow({ ...audit, skipped: 'detector-missing', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
let findings = [];
|
||||
try {
|
||||
findings = await detector.detectText(content, filePath);
|
||||
} catch {
|
||||
return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const filtered = filterFindings(findings || [], content, ext, config);
|
||||
if (filtered.length === 0) {
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: 0,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
const message = cursorBlockMessage(filtered, filePath, config, cwd);
|
||||
const sessionId = event.session_id || event.conversation_id || 'unknown';
|
||||
const cache = readCache(cwd);
|
||||
const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
|
||||
persistCache(cwd, cache);
|
||||
if (denial.count > EDIT_COUNT_THRESHOLD) {
|
||||
const warning = `${message}\n\nThis is the ${denial.count}th repeated denial for the same file and finding signature, so Impeccable is allowing this write to avoid a loop. Reconsider the issue immediately after the tool runs.`;
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
downgraded: true,
|
||||
chars: warning.length,
|
||||
durationMs: Date.now() - started,
|
||||
}, {
|
||||
user_message: warning,
|
||||
agent_message: warning,
|
||||
});
|
||||
}
|
||||
return deny(message, {
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
chars: message.length,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook-before-edit] ${err}\n`);
|
||||
}
|
||||
done({ permission: 'allow' });
|
||||
});
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — PostToolUse entry point.
|
||||
*
|
||||
* Reads the Claude Code / Codex / Cursor hook event from stdin, runs the design
|
||||
* detector against the touched file, and emits a system reminder via
|
||||
* `hookSpecificOutput.additionalContext` when findings exist.
|
||||
*
|
||||
* Contract: never break a turn. Always exit 0. Clean files emit a small ack
|
||||
* unless quiet mode is enabled.
|
||||
*
|
||||
* Most logic lives in `hook-lib.mjs` so it is unit-testable without a
|
||||
* subprocess. This file is the thin stdin/stdout adapter.
|
||||
*/
|
||||
|
||||
import { runHook, writeAuditLog } from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
async function main() {
|
||||
// Snapshot the inherited env FIRST so the re-entrancy guard checks the
|
||||
// parent's value, not the value we are about to export for any child
|
||||
// processes the hook might ever spawn.
|
||||
const inheritedEnv = { ...process.env };
|
||||
process.env.IMPECCABLE_HOOK_DEPTH = process.env.IMPECCABLE_HOOK_DEPTH || '1';
|
||||
|
||||
let stdinJson = '';
|
||||
try { stdinJson = await readStdin(); } catch { /* fall through */ }
|
||||
|
||||
const result = await runHook({
|
||||
stdinJson,
|
||||
env: inheritedEnv,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
|
||||
writeAuditLog(process.env, result.audit);
|
||||
|
||||
if (result.stdout) process.stdout.write(result.stdout);
|
||||
process.exit(result.exitCode || 0);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
// Last-ditch: never break the agent's turn even if something we did not
|
||||
// anticipate goes wrong. Audit-log the failure if logging is enabled.
|
||||
try {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'PostToolUse',
|
||||
error: String(err && err.message ? err.message : err),
|
||||
});
|
||||
} catch { /* swallow */ }
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook] ${err}\n`);
|
||||
}
|
||||
process.exit(0);
|
||||
});
|
||||
@@ -32,6 +32,8 @@ const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.cache.json',
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/hook.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"description": "Impeccable design detector: runs after Edit/Write/MultiEdit on UI files and surfaces findings as system reminders.",
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|Write|MultiEdit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "node \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\"",
|
||||
"timeout": 5,
|
||||
"statusMessage": "Scanning design"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -126,7 +126,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
|
||||
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
|
||||
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
|
||||
|
||||
Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
|
||||
Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
|
||||
|
||||
### Routing rules
|
||||
|
||||
@@ -143,7 +143,7 @@ Plus two management commands: `pin <command>` and `unpin <command>`, detailed be
|
||||
**If `scan.targets` is non-empty, run `node .claude/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
|
||||
|
||||
Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
|
||||
2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
|
||||
4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
|
||||
|
||||
@@ -161,4 +161,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
|
||||
node .claude/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
|
||||
```
|
||||
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
|
||||
## Hooks
|
||||
|
||||
`/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `/impeccable hooks` with any argument.
|
||||
@@ -0,0 +1,82 @@
|
||||
# /impeccable hooks
|
||||
|
||||
Manage the **design detector hook** for the current project.
|
||||
|
||||
The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code and Codex use `PostToolUse` and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless `IMPECCABLE_HOOK_QUIET=1` is set. Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
|
||||
|
||||
This command toggles the hook **per project** by editing `.impeccable/hook.json`. Local-only ignore policy lives in `.impeccable/hook.local.json`, which is gitignored. To disable globally, set `IMPECCABLE_HOOK_DISABLED=1` in your shell environment.
|
||||
|
||||
Supported harnesses: Claude Code (`.claude/settings.json` in the project), Codex (`.codex/hooks.json` in the project), and Cursor (`.cursor/hooks.json` in the project).
|
||||
|
||||
On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
|
||||
|
||||
## Routing
|
||||
|
||||
The first argument is the action. Defaults to `status`.
|
||||
|
||||
| Action | What it does |
|
||||
|---|---|
|
||||
| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
|
||||
| `on` | Set `enabled: true` in `.impeccable/hook.json`. |
|
||||
| `off` | Set `enabled: false` in `.impeccable/hook.json`. |
|
||||
| `ignore-rule <id>` | Append `<id>` to `ignoreRules`; for `overused-font`, requires `--all-values`. |
|
||||
| `ignore-file <glob>` | Append `<glob>` to `ignoreFiles`. |
|
||||
| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/hook.json`. |
|
||||
| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/hook.local.json`. |
|
||||
| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
|
||||
|
||||
## Flow
|
||||
|
||||
1. Resolve the action from the user's argument. If no action was given, default to `status`.
|
||||
2. Invoke the admin script and pass the user's output through verbatim:
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
|
||||
```
|
||||
|
||||
3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/impeccable hooks on`."
|
||||
4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
|
||||
5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/hook.json`; add `--local` only when the user explicitly asks for a private exception.
|
||||
6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
|
||||
|
||||
## Intentional findings
|
||||
|
||||
The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
|
||||
|
||||
Prefer the narrowest exception:
|
||||
|
||||
- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/hook.json` by default.
|
||||
- For `overused-font`, use `ignore-value` when the user confirms a specific font. Do not use `ignore-rule overused-font` for a specific font.
|
||||
- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
|
||||
- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
|
||||
- Do not add source comments such as `impeccable: ignore`; inline comments pollute code and are not a supported suppression mechanism.
|
||||
|
||||
Example value-specific exception:
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
|
||||
```
|
||||
|
||||
Example whole-rule font exception:
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
|
||||
```
|
||||
|
||||
Example file-scoped exception:
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Never modify `.impeccable/hook.json` or `.impeccable/hook.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent.
|
||||
- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
|
||||
- Cursor can block a proposed write when the detector finds a real issue. Claude Code and Codex do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
|
||||
- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.json`, `.codex/hooks.json`, and `.cursor/hooks.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- If `.impeccable/hook.json` or `.impeccable/hook.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
|
||||
- If the user asks to "disable the hook" globally, suggest both options: `IMPECCABLE_HOOK_DISABLED=1` env var (one-shot, follows the shell), and `/impeccable hooks off` (persistent for this project, committable).
|
||||
@@ -446,7 +446,7 @@ function detectText(content, filePath, options = {}) {
|
||||
|
||||
// Run regex matchers on the full file content (catches Tailwind classes, inline styles)
|
||||
// Enable block context for CSS files where related properties span multiple lines
|
||||
const cssLike = new Set(['.css', '.scss', '.less']);
|
||||
const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
|
||||
findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
|
||||
profile,
|
||||
phase: 'source',
|
||||
|
||||
@@ -11,7 +11,7 @@ const SKIP_DIRS = new Set([
|
||||
]);
|
||||
|
||||
const SCANNABLE_EXTENSIONS = new Set([
|
||||
'.html', '.htm', '.css', '.scss', '.less',
|
||||
'.html', '.htm', '.css', '.scss', '.sass', '.less',
|
||||
'.jsx', '.tsx', '.js', '.ts',
|
||||
'.vue', '.svelte', '.astro',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,300 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* `/impeccable hooks <on|off|status|reset>` — manage the design hook
|
||||
* via .impeccable/hook.json and .impeccable/hook.local.json in the current
|
||||
* project.
|
||||
*
|
||||
* Usage:
|
||||
* node hook-admin.mjs status # print current state
|
||||
* node hook-admin.mjs on # set enabled: true
|
||||
* node hook-admin.mjs off # set enabled: false
|
||||
* node hook-admin.mjs ignore-rule <rule-id> # append to ignoreRules
|
||||
* node hook-admin.mjs ignore-rule overused-font --all-values
|
||||
* node hook-admin.mjs ignore-file <glob> # append to ignoreFiles
|
||||
* node hook-admin.mjs ignore-value <rule> <value> # append to shared ignoreValues
|
||||
* node hook-admin.mjs ignore-value <rule> <value> --local
|
||||
* node hook-admin.mjs reset # remove all config + cache
|
||||
*
|
||||
* Designed to be invoked by the LLM from the reference/hooks.md flow.
|
||||
* Output is human-readable; the harness will pass it back to the user.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
getConfigPath,
|
||||
getLocalConfigPath,
|
||||
getCachePath,
|
||||
getPendingPath,
|
||||
readConfig,
|
||||
DEFAULT_CONFIG,
|
||||
ensureHookGitExcludes,
|
||||
normalizeIgnoreValue,
|
||||
normalizeIgnoreValueEntries,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
|
||||
|
||||
function readRawConfigFile(filePath) {
|
||||
if (!fs.existsSync(filePath)) return { exists: false, malformed: false, raw: null };
|
||||
try {
|
||||
return { exists: true, malformed: false, raw: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
|
||||
} catch {
|
||||
return { exists: true, malformed: true, raw: null };
|
||||
}
|
||||
}
|
||||
|
||||
function readRawConfig(cwd, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
return readRawConfigFile(filePath).raw;
|
||||
}
|
||||
|
||||
function writeConfig(cwd, config, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
if (opts.local) ensureHookGitExcludes(cwd);
|
||||
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
||||
fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
function mergeConfig(existing) {
|
||||
// Persist the full shape so /impeccable hooks edits leave a complete file
|
||||
// for the user to see, not an unhelpful `{"enabled":false}`.
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
return {
|
||||
enabled: base.enabled === false ? false : true,
|
||||
ignoreRules: Array.isArray(base.ignoreRules) ? Array.from(new Set(base.ignoreRules.map(String))) : [],
|
||||
ignoreFiles: Array.isArray(base.ignoreFiles) ? Array.from(new Set(base.ignoreFiles.map(String))) : [],
|
||||
ignoreValues: normalizeIgnoreValueEntries(base.ignoreValues || []),
|
||||
limits: {
|
||||
maxFindings: Number.isFinite(base?.limits?.maxFindings) ? base.limits.maxFindings : DEFAULT_CONFIG.limits.maxFindings,
|
||||
maxChars: Number.isFinite(base?.limits?.maxChars) ? base.limits.maxChars : DEFAULT_CONFIG.limits.maxChars,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function mergeLocalConfig(existing) {
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
const out = {};
|
||||
if (Object.prototype.hasOwnProperty.call(base, 'enabled')) {
|
||||
out.enabled = base.enabled === false ? false : true;
|
||||
}
|
||||
if (Array.isArray(base.ignoreRules)) {
|
||||
out.ignoreRules = Array.from(new Set(base.ignoreRules.map(String)));
|
||||
}
|
||||
if (Array.isArray(base.ignoreFiles)) {
|
||||
out.ignoreFiles = Array.from(new Set(base.ignoreFiles.map(String)));
|
||||
}
|
||||
out.ignoreValues = normalizeIgnoreValueEntries(base.ignoreValues || []);
|
||||
if (base.limits && typeof base.limits === 'object') {
|
||||
const limits = {};
|
||||
if (Number.isFinite(base.limits.maxFindings)) limits.maxFindings = base.limits.maxFindings;
|
||||
if (Number.isFinite(base.limits.maxChars)) limits.maxChars = base.limits.maxChars;
|
||||
if (Object.keys(limits).length) out.limits = limits;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function statusReport(cwd) {
|
||||
const shared = readRawConfigFile(getConfigPath(cwd));
|
||||
const local = readRawConfigFile(getLocalConfigPath(cwd));
|
||||
const cfg = readConfig(cwd);
|
||||
const envKill = process.env.IMPECCABLE_HOOK_DISABLED;
|
||||
const envState = envKill ? `IMPECCABLE_HOOK_DISABLED=${envKill}` : 'unset';
|
||||
const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.impeccable/hook.json';
|
||||
const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.impeccable/hook.local.json';
|
||||
const cachePath = path.relative(cwd, getCachePath(cwd)) || '.impeccable/hook.cache.json';
|
||||
const fileState = (info, relPath, absent) => {
|
||||
if (info.malformed) return `${relPath} (malformed; ignored)`;
|
||||
if (info.exists) return relPath;
|
||||
return `${relPath} (${absent})`;
|
||||
};
|
||||
const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
|
||||
|
||||
const lines = [
|
||||
`Impeccable design hook`,
|
||||
` state: ${cfg.enabled ? 'enabled' : 'disabled'}`,
|
||||
` shared file: ${fileState(shared, cfgPath, 'using defaults; file not present')}`,
|
||||
` local file: ${fileState(local, localPath, 'not present')}`,
|
||||
` ignoreRules: ${cfg.ignoreRules.length ? cfg.ignoreRules.join(', ') : '(none)'}`,
|
||||
` ignoreFiles: ${cfg.ignoreFiles.length ? cfg.ignoreFiles.join(', ') : '(none)'}`,
|
||||
` ignoreValues: ${ignoreValues.length ? ignoreValues.join(', ') : '(none)'}`,
|
||||
` maxFindings: ${cfg.limits.maxFindings}`,
|
||||
` maxChars: ${cfg.limits.maxChars}`,
|
||||
` env override: ${envState}`,
|
||||
` cache file: ${fs.existsSync(getCachePath(cwd)) ? cachePath : `${cachePath} (not present)`}`,
|
||||
];
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function setEnabled(cwd, value) {
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
config.enabled = value;
|
||||
const target = writeConfig(cwd, config);
|
||||
return `Design hook ${value ? 'enabled' : 'disabled'} for this project (wrote ${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function normalizeRuleId(rule) {
|
||||
return String(rule || '').trim().toLowerCase();
|
||||
}
|
||||
|
||||
function parseIgnoreRuleArgs(args) {
|
||||
const positionals = [];
|
||||
let allValues = false;
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = String(args[i] || '');
|
||||
if (arg === '--all-values') {
|
||||
allValues = true;
|
||||
} else if (arg === '--reason') {
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
|
||||
} else if (arg.startsWith('--reason=')) {
|
||||
// Accepted for command symmetry; ignoreRules stores rule ids only.
|
||||
} else if (arg.startsWith('--')) {
|
||||
throw new Error(`Unknown ignore-rule flag: ${arg}`);
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rule: normalizeRuleId(positionals[0]),
|
||||
allValues,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreRule(cwd, args) {
|
||||
const parsed = parseIgnoreRuleArgs(args);
|
||||
const rule = parsed.rule;
|
||||
if (!rule) throw new Error('Pass a rule id, e.g. /impeccable hooks ignore-rule side-tab');
|
||||
if (rule === 'overused-font' && !parsed.allValues) {
|
||||
throw new Error('overused-font is value-specific by default. Use /impeccable hooks ignore-value overused-font <font> for a confirmed font, or /impeccable hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.');
|
||||
}
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${rule}" to ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
|
||||
}
|
||||
|
||||
function addIgnoreFile(cwd, glob) {
|
||||
if (!glob) throw new Error('Pass a glob, e.g. /impeccable hooks ignore-file "src/legacy/**"');
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${glob}" to ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
|
||||
}
|
||||
|
||||
function parseIgnoreValueArgs(args) {
|
||||
const positionals = [];
|
||||
let shared = false;
|
||||
let local = false;
|
||||
let reason = '';
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = args[i];
|
||||
if (arg === '--shared') {
|
||||
shared = true;
|
||||
} else if (arg === '--local') {
|
||||
local = true;
|
||||
} else if (arg === '--reason') {
|
||||
const chunks = [];
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) {
|
||||
chunks.push(args[++i]);
|
||||
}
|
||||
reason = chunks.join(' ').trim();
|
||||
} else if (String(arg).startsWith('--reason=')) {
|
||||
reason = String(arg).slice('--reason='.length).trim();
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
const [rule, ...valueParts] = positionals;
|
||||
return {
|
||||
rule: String(rule || '').trim().toLowerCase(),
|
||||
value: normalizeIgnoreValue(valueParts.join(' ')),
|
||||
shared,
|
||||
local,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreValue(cwd, args) {
|
||||
const parsed = parseIgnoreValueArgs(args);
|
||||
if (!parsed.rule || !parsed.value) {
|
||||
throw new Error('Pass a rule id and value, e.g. /impeccable hooks ignore-value overused-font Inter');
|
||||
}
|
||||
|
||||
if (parsed.shared && parsed.local) {
|
||||
throw new Error('Pass only one scope flag: --shared or --local');
|
||||
}
|
||||
|
||||
const local = parsed.local;
|
||||
const config = local
|
||||
? mergeLocalConfig(readRawConfig(cwd, { local: true }))
|
||||
: mergeConfig(readRawConfig(cwd, { local: false }));
|
||||
const key = `${parsed.rule}\0${parsed.value}`;
|
||||
const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
|
||||
|
||||
if (existing) {
|
||||
if (parsed.reason) existing.reason = parsed.reason;
|
||||
} else {
|
||||
const entry = {
|
||||
rule: parsed.rule,
|
||||
value: parsed.value,
|
||||
createdAt: new Date().toISOString(),
|
||||
};
|
||||
if (parsed.reason) entry.reason = parsed.reason;
|
||||
config.ignoreValues.push(entry);
|
||||
}
|
||||
|
||||
const target = writeConfig(cwd, config, { local });
|
||||
const scope = local ? 'local ignoreValues' : 'shared ignoreValues';
|
||||
return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function reset(cwd) {
|
||||
const removed = [];
|
||||
for (const filePath of [getConfigPath(cwd), getLocalConfigPath(cwd), getCachePath(cwd), getPendingPath(cwd)]) {
|
||||
try {
|
||||
if (fs.existsSync(filePath)) {
|
||||
fs.unlinkSync(filePath);
|
||||
removed.push(path.relative(cwd, filePath) || filePath);
|
||||
}
|
||||
} catch { /* ignore */ }
|
||||
}
|
||||
return removed.length
|
||||
? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
|
||||
: 'No hook config or cache to remove. Already at defaults.';
|
||||
}
|
||||
|
||||
function main() {
|
||||
const [, , actionArg, ...rest] = process.argv;
|
||||
const action = (actionArg || 'status').toLowerCase();
|
||||
const cwd = process.cwd();
|
||||
|
||||
if (!ACTIONS.has(action)) {
|
||||
process.stderr.write(`Unknown action: ${action}\nValid: ${Array.from(ACTIONS).join(', ')}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
let out = '';
|
||||
switch (action) {
|
||||
case 'status': out = statusReport(cwd); break;
|
||||
case 'on': out = setEnabled(cwd, true); break;
|
||||
case 'off': out = setEnabled(cwd, false); break;
|
||||
case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
|
||||
case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
|
||||
case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
|
||||
case 'reset': out = reset(cwd); break;
|
||||
}
|
||||
process.stdout.write(out + '\n');
|
||||
} catch (err) {
|
||||
process.stderr.write(`Error: ${err.message || err}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,408 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — Cursor preToolUse write gate.
|
||||
*
|
||||
* Cursor's stop hook is not consistently dispatched by the headless agent, so
|
||||
* this hook checks proposed Write/Edit content before it lands. It only denies
|
||||
* writes when the real detector finds an issue in the proposed UI content.
|
||||
*
|
||||
* Contract: never break a turn accidentally. On malformed input or internal
|
||||
* errors, allow the tool and exit 0.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
ALLOWED_EXTS,
|
||||
EDIT_COUNT_THRESHOLD,
|
||||
GENERATED_PATH,
|
||||
SENSITIVE_PATH,
|
||||
filterFindings,
|
||||
loadDetector,
|
||||
matchesAnyGlob,
|
||||
persistCache,
|
||||
readCache,
|
||||
readConfig,
|
||||
renderTemplate,
|
||||
resolveProjectCwd,
|
||||
truthy,
|
||||
writeAuditLog,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
function done(payload = null) {
|
||||
if (payload) process.stdout.write(JSON.stringify(payload));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
function allow(extra = {}, payload = {}) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
...extra,
|
||||
});
|
||||
return done({ permission: 'allow', ...payload });
|
||||
}
|
||||
|
||||
function deny(message, audit) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
blocked: true,
|
||||
...audit,
|
||||
});
|
||||
return done({
|
||||
permission: 'deny',
|
||||
user_message: message,
|
||||
agent_message: message,
|
||||
});
|
||||
}
|
||||
|
||||
function toolInput(event) {
|
||||
return event?.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
|
||||
}
|
||||
|
||||
function proposedFilePath(event, cwd) {
|
||||
const input = toolInput(event);
|
||||
const raw = input.file_path || input.path || input.target_file || event?.file_path;
|
||||
const candidate = typeof raw === 'string' && raw.trim()
|
||||
? raw
|
||||
: shellWriteDestination(shellCommand(input));
|
||||
if (typeof candidate !== 'string' || !candidate.trim()) return '';
|
||||
return path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
|
||||
}
|
||||
|
||||
function proposedContent(event, cwd, filePath) {
|
||||
const input = toolInput(event);
|
||||
for (const key of ['content', 'streamContent', 'text']) {
|
||||
if (typeof input[key] === 'string') return input[key];
|
||||
}
|
||||
|
||||
const editProjection = projectedEditContent(input, filePath, cwd);
|
||||
if (editProjection !== undefined) return editProjection;
|
||||
|
||||
if (hasFragmentEditContent(input)) {
|
||||
return { skipped: 'fragment-only-edit' };
|
||||
}
|
||||
|
||||
const shellContent = shellHereDocContent(shellCommand(input));
|
||||
if (shellContent) return shellContent;
|
||||
const copiedContent = shellCopiedFileContent(shellCommand(input), cwd);
|
||||
if (copiedContent) return copiedContent;
|
||||
return '';
|
||||
}
|
||||
|
||||
function hasFragmentEditContent(input) {
|
||||
if (!input || typeof input !== 'object') return false;
|
||||
if (typeof input.new_string === 'string' || typeof input.newString === 'string' || typeof input.new_str === 'string' || typeof input.replacement === 'string') {
|
||||
return true;
|
||||
}
|
||||
return Array.isArray(input.edits) && input.edits.some((edit) => edit && typeof edit === 'object');
|
||||
}
|
||||
|
||||
function projectedEditContent(input, filePath, cwd) {
|
||||
if (!filePath) return undefined;
|
||||
const singleOld = firstString(input, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const singleNew = firstString(input, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (singleOld !== undefined || singleNew !== undefined) {
|
||||
if (singleOld === undefined || singleNew === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
const projected = replaceOnce(original, singleOld, singleNew);
|
||||
return projected === null ? { skipped: 'edit-old-string-missing' } : projected;
|
||||
}
|
||||
|
||||
if (!Array.isArray(input.edits)) return undefined;
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
|
||||
let projected = original;
|
||||
for (const edit of input.edits) {
|
||||
if (!edit || typeof edit !== 'object') return { skipped: 'fragment-only-edit' };
|
||||
const oldString = firstString(edit, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const newString = firstString(edit, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (oldString === undefined || newString === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const next = replaceOnce(projected, oldString, newString);
|
||||
if (next === null) return { skipped: 'edit-old-string-missing' };
|
||||
projected = next;
|
||||
}
|
||||
return projected;
|
||||
}
|
||||
|
||||
function firstString(obj, keys) {
|
||||
for (const key of keys) {
|
||||
if (typeof obj?.[key] === 'string') return obj[key];
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function replaceOnce(original, oldString, newString) {
|
||||
if (oldString === '') return null;
|
||||
const index = original.indexOf(oldString);
|
||||
if (index === -1) return null;
|
||||
return `${original.slice(0, index)}${newString}${original.slice(index + oldString.length)}`;
|
||||
}
|
||||
|
||||
function readExistingProjectFile(filePath, cwd) {
|
||||
if (!isInsideProject(filePath, cwd)) return null;
|
||||
if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
|
||||
try {
|
||||
const stat = fs.statSync(filePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return null;
|
||||
return fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function shellCommand(input) {
|
||||
if (typeof input.command === 'string') return input.command;
|
||||
if (input.args && typeof input.args.command === 'string') return input.args.command;
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellRedirectPath(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const match = command.match(/(?:^|[\s;&|])(?:>>?|1>>?)\s*(?:"([^"]+)"|'([^']+)'|([^<>\s]+))/);
|
||||
return (match?.[1] || match?.[2] || match?.[3] || '').trim();
|
||||
}
|
||||
|
||||
function shellWriteDestination(command) {
|
||||
return shellRedirectPath(command) || shellTeeDestination(command) || shellCopyPaths(command)?.dest || '';
|
||||
}
|
||||
|
||||
function shellTeeDestination(command) {
|
||||
const words = shellWords(command);
|
||||
const teeIndex = words.findIndex((word) => path.basename(word) === 'tee');
|
||||
if (teeIndex === -1) return '';
|
||||
for (const word of words.slice(teeIndex + 1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
return word;
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellCopiedFileContent(command, cwd) {
|
||||
const source = shellCopyPaths(command)?.source;
|
||||
if (!source) return '';
|
||||
const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
|
||||
if (!isInsideProject(sourcePath, cwd)) return '';
|
||||
if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
|
||||
try {
|
||||
const stat = fs.statSync(sourcePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return '';
|
||||
return fs.readFileSync(sourcePath, 'utf-8');
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
function shellCopyPaths(command) {
|
||||
const words = shellWords(command);
|
||||
if (words.length < 3 || path.basename(words[0]) !== 'cp') return null;
|
||||
const args = [];
|
||||
for (const word of words.slice(1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
args.push(word);
|
||||
}
|
||||
if (args.length < 2) return null;
|
||||
return { source: args[args.length - 2], dest: args[args.length - 1] };
|
||||
}
|
||||
|
||||
function shellWords(command) {
|
||||
if (!command || typeof command !== 'string') return [];
|
||||
const words = [];
|
||||
const re = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'|([^\s]+)/g;
|
||||
let match;
|
||||
while ((match = re.exec(command))) {
|
||||
words.push((match[1] ?? match[2] ?? match[3] ?? '').replace(/\\(["'])/g, '$1'));
|
||||
}
|
||||
return words;
|
||||
}
|
||||
|
||||
function shellHereDocContent(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const markerMatch = command.match(/<<-?\s*['"]?([A-Za-z0-9_.-]+)['"]?[^\r\n]*\r?\n/);
|
||||
if (!markerMatch) return '';
|
||||
const marker = markerMatch[1];
|
||||
const start = (markerMatch.index || 0) + markerMatch[0].length;
|
||||
const rest = command.slice(start);
|
||||
const endRe = new RegExp(`\\r?\\n${escapeRegExp(marker)}(?:\\r?\\n|$)`);
|
||||
const end = rest.search(endRe);
|
||||
return end >= 0 ? rest.slice(0, end) : '';
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
function relativePath(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
|
||||
return rel.split(path.sep).join('/');
|
||||
} catch {
|
||||
return filePath;
|
||||
}
|
||||
}
|
||||
|
||||
function isInsideProject(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function cursorBlockMessage(findings, filePath, config, cwd) {
|
||||
const rendered = renderTemplate(findings, filePath, config, { cwd });
|
||||
const blocked = rendered.replace(
|
||||
'[impeccable@1] Required design corrections',
|
||||
'[impeccable@1] Impeccable design hook blocked this write before it landed. Required design corrections',
|
||||
);
|
||||
return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
|
||||
}
|
||||
|
||||
function findingSignature(findings) {
|
||||
return findings
|
||||
.map((finding) => `${finding.antipattern || 'unknown'}:${finding.line || 0}`)
|
||||
.sort()
|
||||
.join('|');
|
||||
}
|
||||
|
||||
function bumpCursorDenial(cache, sessionId, filePath, findings) {
|
||||
const session = cache.sessions[sessionId] || { updatedAt: Date.now(), files: {} };
|
||||
cache.sessions[sessionId] = session;
|
||||
session.updatedAt = Date.now();
|
||||
const fileEntry = session.files[filePath] || { editCount: 0, findings: [] };
|
||||
session.files[filePath] = fileEntry;
|
||||
const key = findingSignature(findings);
|
||||
fileEntry.cursorDenials = fileEntry.cursorDenials && typeof fileEntry.cursorDenials === 'object'
|
||||
? fileEntry.cursorDenials
|
||||
: {};
|
||||
fileEntry.cursorDenials[key] = (fileEntry.cursorDenials[key] || 0) + 1;
|
||||
return { key, count: fileEntry.cursorDenials[key] };
|
||||
}
|
||||
|
||||
async function main() {
|
||||
if (truthy(process.env.IMPECCABLE_HOOK_DISABLED)) {
|
||||
return allow({ skipped: 'env-disabled' });
|
||||
}
|
||||
|
||||
let event = null;
|
||||
try {
|
||||
const raw = await readStdin();
|
||||
if (raw) event = JSON.parse(raw);
|
||||
} catch {
|
||||
return allow({ skipped: 'stdin-malformed' });
|
||||
}
|
||||
|
||||
if (!event || typeof event !== 'object') {
|
||||
return allow({ skipped: 'stdin-empty' });
|
||||
}
|
||||
|
||||
const cwd = resolveProjectCwd(event);
|
||||
const started = Date.now();
|
||||
const filePath = proposedFilePath(event, cwd);
|
||||
const audit = {
|
||||
harness: 'cursor',
|
||||
tool: event.tool_name || null,
|
||||
file: filePath || null,
|
||||
};
|
||||
|
||||
if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
|
||||
if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
|
||||
if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
|
||||
if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
|
||||
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
audit.ext = ext;
|
||||
if (!ALLOWED_EXTS.has(ext)) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
|
||||
|
||||
const contentResult = proposedContent(event, cwd, filePath);
|
||||
if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
|
||||
return allow({ ...audit, skipped: contentResult.skipped, durationMs: Date.now() - started });
|
||||
}
|
||||
const content = typeof contentResult === 'string' ? contentResult : '';
|
||||
if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
|
||||
|
||||
const config = readConfig(cwd);
|
||||
if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
|
||||
|
||||
const rel = relativePath(filePath, cwd);
|
||||
if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
|
||||
return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const detector = await loadDetector();
|
||||
if (!detector || typeof detector.detectText !== 'function') {
|
||||
return allow({ ...audit, skipped: 'detector-missing', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
let findings = [];
|
||||
try {
|
||||
findings = await detector.detectText(content, filePath);
|
||||
} catch {
|
||||
return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const filtered = filterFindings(findings || [], content, ext, config);
|
||||
if (filtered.length === 0) {
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: 0,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
const message = cursorBlockMessage(filtered, filePath, config, cwd);
|
||||
const sessionId = event.session_id || event.conversation_id || 'unknown';
|
||||
const cache = readCache(cwd);
|
||||
const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
|
||||
persistCache(cwd, cache);
|
||||
if (denial.count > EDIT_COUNT_THRESHOLD) {
|
||||
const warning = `${message}\n\nThis is the ${denial.count}th repeated denial for the same file and finding signature, so Impeccable is allowing this write to avoid a loop. Reconsider the issue immediately after the tool runs.`;
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
downgraded: true,
|
||||
chars: warning.length,
|
||||
durationMs: Date.now() - started,
|
||||
}, {
|
||||
user_message: warning,
|
||||
agent_message: warning,
|
||||
});
|
||||
}
|
||||
return deny(message, {
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
chars: message.length,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook-before-edit] ${err}\n`);
|
||||
}
|
||||
done({ permission: 'allow' });
|
||||
});
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — PostToolUse entry point.
|
||||
*
|
||||
* Reads the Claude Code / Codex / Cursor hook event from stdin, runs the design
|
||||
* detector against the touched file, and emits a system reminder via
|
||||
* `hookSpecificOutput.additionalContext` when findings exist.
|
||||
*
|
||||
* Contract: never break a turn. Always exit 0. Clean files emit a small ack
|
||||
* unless quiet mode is enabled.
|
||||
*
|
||||
* Most logic lives in `hook-lib.mjs` so it is unit-testable without a
|
||||
* subprocess. This file is the thin stdin/stdout adapter.
|
||||
*/
|
||||
|
||||
import { runHook, writeAuditLog } from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
async function main() {
|
||||
// Snapshot the inherited env FIRST so the re-entrancy guard checks the
|
||||
// parent's value, not the value we are about to export for any child
|
||||
// processes the hook might ever spawn.
|
||||
const inheritedEnv = { ...process.env };
|
||||
process.env.IMPECCABLE_HOOK_DEPTH = process.env.IMPECCABLE_HOOK_DEPTH || '1';
|
||||
|
||||
let stdinJson = '';
|
||||
try { stdinJson = await readStdin(); } catch { /* fall through */ }
|
||||
|
||||
const result = await runHook({
|
||||
stdinJson,
|
||||
env: inheritedEnv,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
|
||||
writeAuditLog(process.env, result.audit);
|
||||
|
||||
if (result.stdout) process.stdout.write(result.stdout);
|
||||
process.exit(result.exitCode || 0);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
// Last-ditch: never break the agent's turn even if something we did not
|
||||
// anticipate goes wrong. Audit-log the failure if logging is enabled.
|
||||
try {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'PostToolUse',
|
||||
error: String(err && err.message ? err.message : err),
|
||||
});
|
||||
} catch { /* swallow */ }
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook] ${err}\n`);
|
||||
}
|
||||
process.exit(0);
|
||||
});
|
||||
@@ -32,6 +32,8 @@ const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.cache.json',
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/hook.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"description": "Impeccable design detector: runs after Edit/Write/apply_patch on UI files and surfaces findings as system reminders.",
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|Write|apply_patch",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "node \"$(git rev-parse --show-toplevel)/.agents/skills/impeccable/scripts/hook.mjs\"",
|
||||
"timeout": 5,
|
||||
"statusMessage": "Scanning design"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"version": 1,
|
||||
"hooks": {
|
||||
"preToolUse": [
|
||||
{
|
||||
"command": "node \".cursor/skills/impeccable/scripts/hook-before-edit.mjs\"",
|
||||
"timeout": 5
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -122,7 +122,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
|
||||
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
|
||||
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
|
||||
|
||||
Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
|
||||
Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
|
||||
|
||||
### Routing rules
|
||||
|
||||
@@ -139,7 +139,7 @@ Plus two management commands: `pin <command>` and `unpin <command>`, detailed be
|
||||
**If `scan.targets` is non-empty, run `node .cursor/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
|
||||
|
||||
Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
|
||||
2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
|
||||
4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
|
||||
|
||||
@@ -157,4 +157,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
|
||||
node .cursor/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
|
||||
```
|
||||
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
|
||||
## Hooks
|
||||
|
||||
`/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `/impeccable hooks` with any argument.
|
||||
@@ -0,0 +1,82 @@
|
||||
# /impeccable hooks
|
||||
|
||||
Manage the **design detector hook** for the current project.
|
||||
|
||||
The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code and Codex use `PostToolUse` and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless `IMPECCABLE_HOOK_QUIET=1` is set. Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
|
||||
|
||||
This command toggles the hook **per project** by editing `.impeccable/hook.json`. Local-only ignore policy lives in `.impeccable/hook.local.json`, which is gitignored. To disable globally, set `IMPECCABLE_HOOK_DISABLED=1` in your shell environment.
|
||||
|
||||
Supported harnesses: Claude Code (`.claude/settings.json` in the project), Codex (`.codex/hooks.json` in the project), and Cursor (`.cursor/hooks.json` in the project).
|
||||
|
||||
On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
|
||||
|
||||
## Routing
|
||||
|
||||
The first argument is the action. Defaults to `status`.
|
||||
|
||||
| Action | What it does |
|
||||
|---|---|
|
||||
| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
|
||||
| `on` | Set `enabled: true` in `.impeccable/hook.json`. |
|
||||
| `off` | Set `enabled: false` in `.impeccable/hook.json`. |
|
||||
| `ignore-rule <id>` | Append `<id>` to `ignoreRules`; for `overused-font`, requires `--all-values`. |
|
||||
| `ignore-file <glob>` | Append `<glob>` to `ignoreFiles`. |
|
||||
| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/hook.json`. |
|
||||
| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/hook.local.json`. |
|
||||
| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
|
||||
|
||||
## Flow
|
||||
|
||||
1. Resolve the action from the user's argument. If no action was given, default to `status`.
|
||||
2. Invoke the admin script and pass the user's output through verbatim:
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
|
||||
```
|
||||
|
||||
3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/impeccable hooks on`."
|
||||
4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
|
||||
5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/hook.json`; add `--local` only when the user explicitly asks for a private exception.
|
||||
6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
|
||||
|
||||
## Intentional findings
|
||||
|
||||
The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
|
||||
|
||||
Prefer the narrowest exception:
|
||||
|
||||
- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/hook.json` by default.
|
||||
- For `overused-font`, use `ignore-value` when the user confirms a specific font. Do not use `ignore-rule overused-font` for a specific font.
|
||||
- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
|
||||
- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
|
||||
- Do not add source comments such as `impeccable: ignore`; inline comments pollute code and are not a supported suppression mechanism.
|
||||
|
||||
Example value-specific exception:
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
|
||||
```
|
||||
|
||||
Example whole-rule font exception:
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
|
||||
```
|
||||
|
||||
Example file-scoped exception:
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Never modify `.impeccable/hook.json` or `.impeccable/hook.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent.
|
||||
- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
|
||||
- Cursor can block a proposed write when the detector finds a real issue. Claude Code and Codex do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
|
||||
- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.json`, `.codex/hooks.json`, and `.cursor/hooks.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- If `.impeccable/hook.json` or `.impeccable/hook.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
|
||||
- If the user asks to "disable the hook" globally, suggest both options: `IMPECCABLE_HOOK_DISABLED=1` env var (one-shot, follows the shell), and `/impeccable hooks off` (persistent for this project, committable).
|
||||
@@ -446,7 +446,7 @@ function detectText(content, filePath, options = {}) {
|
||||
|
||||
// Run regex matchers on the full file content (catches Tailwind classes, inline styles)
|
||||
// Enable block context for CSS files where related properties span multiple lines
|
||||
const cssLike = new Set(['.css', '.scss', '.less']);
|
||||
const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
|
||||
findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
|
||||
profile,
|
||||
phase: 'source',
|
||||
|
||||
@@ -11,7 +11,7 @@ const SKIP_DIRS = new Set([
|
||||
]);
|
||||
|
||||
const SCANNABLE_EXTENSIONS = new Set([
|
||||
'.html', '.htm', '.css', '.scss', '.less',
|
||||
'.html', '.htm', '.css', '.scss', '.sass', '.less',
|
||||
'.jsx', '.tsx', '.js', '.ts',
|
||||
'.vue', '.svelte', '.astro',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,300 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* `/impeccable hooks <on|off|status|reset>` — manage the design hook
|
||||
* via .impeccable/hook.json and .impeccable/hook.local.json in the current
|
||||
* project.
|
||||
*
|
||||
* Usage:
|
||||
* node hook-admin.mjs status # print current state
|
||||
* node hook-admin.mjs on # set enabled: true
|
||||
* node hook-admin.mjs off # set enabled: false
|
||||
* node hook-admin.mjs ignore-rule <rule-id> # append to ignoreRules
|
||||
* node hook-admin.mjs ignore-rule overused-font --all-values
|
||||
* node hook-admin.mjs ignore-file <glob> # append to ignoreFiles
|
||||
* node hook-admin.mjs ignore-value <rule> <value> # append to shared ignoreValues
|
||||
* node hook-admin.mjs ignore-value <rule> <value> --local
|
||||
* node hook-admin.mjs reset # remove all config + cache
|
||||
*
|
||||
* Designed to be invoked by the LLM from the reference/hooks.md flow.
|
||||
* Output is human-readable; the harness will pass it back to the user.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
getConfigPath,
|
||||
getLocalConfigPath,
|
||||
getCachePath,
|
||||
getPendingPath,
|
||||
readConfig,
|
||||
DEFAULT_CONFIG,
|
||||
ensureHookGitExcludes,
|
||||
normalizeIgnoreValue,
|
||||
normalizeIgnoreValueEntries,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
|
||||
|
||||
function readRawConfigFile(filePath) {
|
||||
if (!fs.existsSync(filePath)) return { exists: false, malformed: false, raw: null };
|
||||
try {
|
||||
return { exists: true, malformed: false, raw: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
|
||||
} catch {
|
||||
return { exists: true, malformed: true, raw: null };
|
||||
}
|
||||
}
|
||||
|
||||
function readRawConfig(cwd, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
return readRawConfigFile(filePath).raw;
|
||||
}
|
||||
|
||||
function writeConfig(cwd, config, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
if (opts.local) ensureHookGitExcludes(cwd);
|
||||
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
||||
fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
function mergeConfig(existing) {
|
||||
// Persist the full shape so /impeccable hooks edits leave a complete file
|
||||
// for the user to see, not an unhelpful `{"enabled":false}`.
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
return {
|
||||
enabled: base.enabled === false ? false : true,
|
||||
ignoreRules: Array.isArray(base.ignoreRules) ? Array.from(new Set(base.ignoreRules.map(String))) : [],
|
||||
ignoreFiles: Array.isArray(base.ignoreFiles) ? Array.from(new Set(base.ignoreFiles.map(String))) : [],
|
||||
ignoreValues: normalizeIgnoreValueEntries(base.ignoreValues || []),
|
||||
limits: {
|
||||
maxFindings: Number.isFinite(base?.limits?.maxFindings) ? base.limits.maxFindings : DEFAULT_CONFIG.limits.maxFindings,
|
||||
maxChars: Number.isFinite(base?.limits?.maxChars) ? base.limits.maxChars : DEFAULT_CONFIG.limits.maxChars,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function mergeLocalConfig(existing) {
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
const out = {};
|
||||
if (Object.prototype.hasOwnProperty.call(base, 'enabled')) {
|
||||
out.enabled = base.enabled === false ? false : true;
|
||||
}
|
||||
if (Array.isArray(base.ignoreRules)) {
|
||||
out.ignoreRules = Array.from(new Set(base.ignoreRules.map(String)));
|
||||
}
|
||||
if (Array.isArray(base.ignoreFiles)) {
|
||||
out.ignoreFiles = Array.from(new Set(base.ignoreFiles.map(String)));
|
||||
}
|
||||
out.ignoreValues = normalizeIgnoreValueEntries(base.ignoreValues || []);
|
||||
if (base.limits && typeof base.limits === 'object') {
|
||||
const limits = {};
|
||||
if (Number.isFinite(base.limits.maxFindings)) limits.maxFindings = base.limits.maxFindings;
|
||||
if (Number.isFinite(base.limits.maxChars)) limits.maxChars = base.limits.maxChars;
|
||||
if (Object.keys(limits).length) out.limits = limits;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function statusReport(cwd) {
|
||||
const shared = readRawConfigFile(getConfigPath(cwd));
|
||||
const local = readRawConfigFile(getLocalConfigPath(cwd));
|
||||
const cfg = readConfig(cwd);
|
||||
const envKill = process.env.IMPECCABLE_HOOK_DISABLED;
|
||||
const envState = envKill ? `IMPECCABLE_HOOK_DISABLED=${envKill}` : 'unset';
|
||||
const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.impeccable/hook.json';
|
||||
const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.impeccable/hook.local.json';
|
||||
const cachePath = path.relative(cwd, getCachePath(cwd)) || '.impeccable/hook.cache.json';
|
||||
const fileState = (info, relPath, absent) => {
|
||||
if (info.malformed) return `${relPath} (malformed; ignored)`;
|
||||
if (info.exists) return relPath;
|
||||
return `${relPath} (${absent})`;
|
||||
};
|
||||
const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
|
||||
|
||||
const lines = [
|
||||
`Impeccable design hook`,
|
||||
` state: ${cfg.enabled ? 'enabled' : 'disabled'}`,
|
||||
` shared file: ${fileState(shared, cfgPath, 'using defaults; file not present')}`,
|
||||
` local file: ${fileState(local, localPath, 'not present')}`,
|
||||
` ignoreRules: ${cfg.ignoreRules.length ? cfg.ignoreRules.join(', ') : '(none)'}`,
|
||||
` ignoreFiles: ${cfg.ignoreFiles.length ? cfg.ignoreFiles.join(', ') : '(none)'}`,
|
||||
` ignoreValues: ${ignoreValues.length ? ignoreValues.join(', ') : '(none)'}`,
|
||||
` maxFindings: ${cfg.limits.maxFindings}`,
|
||||
` maxChars: ${cfg.limits.maxChars}`,
|
||||
` env override: ${envState}`,
|
||||
` cache file: ${fs.existsSync(getCachePath(cwd)) ? cachePath : `${cachePath} (not present)`}`,
|
||||
];
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function setEnabled(cwd, value) {
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
config.enabled = value;
|
||||
const target = writeConfig(cwd, config);
|
||||
return `Design hook ${value ? 'enabled' : 'disabled'} for this project (wrote ${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function normalizeRuleId(rule) {
|
||||
return String(rule || '').trim().toLowerCase();
|
||||
}
|
||||
|
||||
function parseIgnoreRuleArgs(args) {
|
||||
const positionals = [];
|
||||
let allValues = false;
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = String(args[i] || '');
|
||||
if (arg === '--all-values') {
|
||||
allValues = true;
|
||||
} else if (arg === '--reason') {
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
|
||||
} else if (arg.startsWith('--reason=')) {
|
||||
// Accepted for command symmetry; ignoreRules stores rule ids only.
|
||||
} else if (arg.startsWith('--')) {
|
||||
throw new Error(`Unknown ignore-rule flag: ${arg}`);
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rule: normalizeRuleId(positionals[0]),
|
||||
allValues,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreRule(cwd, args) {
|
||||
const parsed = parseIgnoreRuleArgs(args);
|
||||
const rule = parsed.rule;
|
||||
if (!rule) throw new Error('Pass a rule id, e.g. /impeccable hooks ignore-rule side-tab');
|
||||
if (rule === 'overused-font' && !parsed.allValues) {
|
||||
throw new Error('overused-font is value-specific by default. Use /impeccable hooks ignore-value overused-font <font> for a confirmed font, or /impeccable hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.');
|
||||
}
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${rule}" to ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
|
||||
}
|
||||
|
||||
function addIgnoreFile(cwd, glob) {
|
||||
if (!glob) throw new Error('Pass a glob, e.g. /impeccable hooks ignore-file "src/legacy/**"');
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${glob}" to ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
|
||||
}
|
||||
|
||||
function parseIgnoreValueArgs(args) {
|
||||
const positionals = [];
|
||||
let shared = false;
|
||||
let local = false;
|
||||
let reason = '';
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = args[i];
|
||||
if (arg === '--shared') {
|
||||
shared = true;
|
||||
} else if (arg === '--local') {
|
||||
local = true;
|
||||
} else if (arg === '--reason') {
|
||||
const chunks = [];
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) {
|
||||
chunks.push(args[++i]);
|
||||
}
|
||||
reason = chunks.join(' ').trim();
|
||||
} else if (String(arg).startsWith('--reason=')) {
|
||||
reason = String(arg).slice('--reason='.length).trim();
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
const [rule, ...valueParts] = positionals;
|
||||
return {
|
||||
rule: String(rule || '').trim().toLowerCase(),
|
||||
value: normalizeIgnoreValue(valueParts.join(' ')),
|
||||
shared,
|
||||
local,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreValue(cwd, args) {
|
||||
const parsed = parseIgnoreValueArgs(args);
|
||||
if (!parsed.rule || !parsed.value) {
|
||||
throw new Error('Pass a rule id and value, e.g. /impeccable hooks ignore-value overused-font Inter');
|
||||
}
|
||||
|
||||
if (parsed.shared && parsed.local) {
|
||||
throw new Error('Pass only one scope flag: --shared or --local');
|
||||
}
|
||||
|
||||
const local = parsed.local;
|
||||
const config = local
|
||||
? mergeLocalConfig(readRawConfig(cwd, { local: true }))
|
||||
: mergeConfig(readRawConfig(cwd, { local: false }));
|
||||
const key = `${parsed.rule}\0${parsed.value}`;
|
||||
const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
|
||||
|
||||
if (existing) {
|
||||
if (parsed.reason) existing.reason = parsed.reason;
|
||||
} else {
|
||||
const entry = {
|
||||
rule: parsed.rule,
|
||||
value: parsed.value,
|
||||
createdAt: new Date().toISOString(),
|
||||
};
|
||||
if (parsed.reason) entry.reason = parsed.reason;
|
||||
config.ignoreValues.push(entry);
|
||||
}
|
||||
|
||||
const target = writeConfig(cwd, config, { local });
|
||||
const scope = local ? 'local ignoreValues' : 'shared ignoreValues';
|
||||
return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function reset(cwd) {
|
||||
const removed = [];
|
||||
for (const filePath of [getConfigPath(cwd), getLocalConfigPath(cwd), getCachePath(cwd), getPendingPath(cwd)]) {
|
||||
try {
|
||||
if (fs.existsSync(filePath)) {
|
||||
fs.unlinkSync(filePath);
|
||||
removed.push(path.relative(cwd, filePath) || filePath);
|
||||
}
|
||||
} catch { /* ignore */ }
|
||||
}
|
||||
return removed.length
|
||||
? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
|
||||
: 'No hook config or cache to remove. Already at defaults.';
|
||||
}
|
||||
|
||||
function main() {
|
||||
const [, , actionArg, ...rest] = process.argv;
|
||||
const action = (actionArg || 'status').toLowerCase();
|
||||
const cwd = process.cwd();
|
||||
|
||||
if (!ACTIONS.has(action)) {
|
||||
process.stderr.write(`Unknown action: ${action}\nValid: ${Array.from(ACTIONS).join(', ')}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
let out = '';
|
||||
switch (action) {
|
||||
case 'status': out = statusReport(cwd); break;
|
||||
case 'on': out = setEnabled(cwd, true); break;
|
||||
case 'off': out = setEnabled(cwd, false); break;
|
||||
case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
|
||||
case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
|
||||
case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
|
||||
case 'reset': out = reset(cwd); break;
|
||||
}
|
||||
process.stdout.write(out + '\n');
|
||||
} catch (err) {
|
||||
process.stderr.write(`Error: ${err.message || err}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,408 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — Cursor preToolUse write gate.
|
||||
*
|
||||
* Cursor's stop hook is not consistently dispatched by the headless agent, so
|
||||
* this hook checks proposed Write/Edit content before it lands. It only denies
|
||||
* writes when the real detector finds an issue in the proposed UI content.
|
||||
*
|
||||
* Contract: never break a turn accidentally. On malformed input or internal
|
||||
* errors, allow the tool and exit 0.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
ALLOWED_EXTS,
|
||||
EDIT_COUNT_THRESHOLD,
|
||||
GENERATED_PATH,
|
||||
SENSITIVE_PATH,
|
||||
filterFindings,
|
||||
loadDetector,
|
||||
matchesAnyGlob,
|
||||
persistCache,
|
||||
readCache,
|
||||
readConfig,
|
||||
renderTemplate,
|
||||
resolveProjectCwd,
|
||||
truthy,
|
||||
writeAuditLog,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
function done(payload = null) {
|
||||
if (payload) process.stdout.write(JSON.stringify(payload));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
function allow(extra = {}, payload = {}) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
...extra,
|
||||
});
|
||||
return done({ permission: 'allow', ...payload });
|
||||
}
|
||||
|
||||
function deny(message, audit) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
blocked: true,
|
||||
...audit,
|
||||
});
|
||||
return done({
|
||||
permission: 'deny',
|
||||
user_message: message,
|
||||
agent_message: message,
|
||||
});
|
||||
}
|
||||
|
||||
function toolInput(event) {
|
||||
return event?.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
|
||||
}
|
||||
|
||||
function proposedFilePath(event, cwd) {
|
||||
const input = toolInput(event);
|
||||
const raw = input.file_path || input.path || input.target_file || event?.file_path;
|
||||
const candidate = typeof raw === 'string' && raw.trim()
|
||||
? raw
|
||||
: shellWriteDestination(shellCommand(input));
|
||||
if (typeof candidate !== 'string' || !candidate.trim()) return '';
|
||||
return path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
|
||||
}
|
||||
|
||||
function proposedContent(event, cwd, filePath) {
|
||||
const input = toolInput(event);
|
||||
for (const key of ['content', 'streamContent', 'text']) {
|
||||
if (typeof input[key] === 'string') return input[key];
|
||||
}
|
||||
|
||||
const editProjection = projectedEditContent(input, filePath, cwd);
|
||||
if (editProjection !== undefined) return editProjection;
|
||||
|
||||
if (hasFragmentEditContent(input)) {
|
||||
return { skipped: 'fragment-only-edit' };
|
||||
}
|
||||
|
||||
const shellContent = shellHereDocContent(shellCommand(input));
|
||||
if (shellContent) return shellContent;
|
||||
const copiedContent = shellCopiedFileContent(shellCommand(input), cwd);
|
||||
if (copiedContent) return copiedContent;
|
||||
return '';
|
||||
}
|
||||
|
||||
function hasFragmentEditContent(input) {
|
||||
if (!input || typeof input !== 'object') return false;
|
||||
if (typeof input.new_string === 'string' || typeof input.newString === 'string' || typeof input.new_str === 'string' || typeof input.replacement === 'string') {
|
||||
return true;
|
||||
}
|
||||
return Array.isArray(input.edits) && input.edits.some((edit) => edit && typeof edit === 'object');
|
||||
}
|
||||
|
||||
function projectedEditContent(input, filePath, cwd) {
|
||||
if (!filePath) return undefined;
|
||||
const singleOld = firstString(input, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const singleNew = firstString(input, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (singleOld !== undefined || singleNew !== undefined) {
|
||||
if (singleOld === undefined || singleNew === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
const projected = replaceOnce(original, singleOld, singleNew);
|
||||
return projected === null ? { skipped: 'edit-old-string-missing' } : projected;
|
||||
}
|
||||
|
||||
if (!Array.isArray(input.edits)) return undefined;
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
|
||||
let projected = original;
|
||||
for (const edit of input.edits) {
|
||||
if (!edit || typeof edit !== 'object') return { skipped: 'fragment-only-edit' };
|
||||
const oldString = firstString(edit, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const newString = firstString(edit, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (oldString === undefined || newString === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const next = replaceOnce(projected, oldString, newString);
|
||||
if (next === null) return { skipped: 'edit-old-string-missing' };
|
||||
projected = next;
|
||||
}
|
||||
return projected;
|
||||
}
|
||||
|
||||
function firstString(obj, keys) {
|
||||
for (const key of keys) {
|
||||
if (typeof obj?.[key] === 'string') return obj[key];
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function replaceOnce(original, oldString, newString) {
|
||||
if (oldString === '') return null;
|
||||
const index = original.indexOf(oldString);
|
||||
if (index === -1) return null;
|
||||
return `${original.slice(0, index)}${newString}${original.slice(index + oldString.length)}`;
|
||||
}
|
||||
|
||||
function readExistingProjectFile(filePath, cwd) {
|
||||
if (!isInsideProject(filePath, cwd)) return null;
|
||||
if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
|
||||
try {
|
||||
const stat = fs.statSync(filePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return null;
|
||||
return fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function shellCommand(input) {
|
||||
if (typeof input.command === 'string') return input.command;
|
||||
if (input.args && typeof input.args.command === 'string') return input.args.command;
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellRedirectPath(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const match = command.match(/(?:^|[\s;&|])(?:>>?|1>>?)\s*(?:"([^"]+)"|'([^']+)'|([^<>\s]+))/);
|
||||
return (match?.[1] || match?.[2] || match?.[3] || '').trim();
|
||||
}
|
||||
|
||||
function shellWriteDestination(command) {
|
||||
return shellRedirectPath(command) || shellTeeDestination(command) || shellCopyPaths(command)?.dest || '';
|
||||
}
|
||||
|
||||
function shellTeeDestination(command) {
|
||||
const words = shellWords(command);
|
||||
const teeIndex = words.findIndex((word) => path.basename(word) === 'tee');
|
||||
if (teeIndex === -1) return '';
|
||||
for (const word of words.slice(teeIndex + 1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
return word;
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellCopiedFileContent(command, cwd) {
|
||||
const source = shellCopyPaths(command)?.source;
|
||||
if (!source) return '';
|
||||
const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
|
||||
if (!isInsideProject(sourcePath, cwd)) return '';
|
||||
if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
|
||||
try {
|
||||
const stat = fs.statSync(sourcePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return '';
|
||||
return fs.readFileSync(sourcePath, 'utf-8');
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
function shellCopyPaths(command) {
|
||||
const words = shellWords(command);
|
||||
if (words.length < 3 || path.basename(words[0]) !== 'cp') return null;
|
||||
const args = [];
|
||||
for (const word of words.slice(1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
args.push(word);
|
||||
}
|
||||
if (args.length < 2) return null;
|
||||
return { source: args[args.length - 2], dest: args[args.length - 1] };
|
||||
}
|
||||
|
||||
function shellWords(command) {
|
||||
if (!command || typeof command !== 'string') return [];
|
||||
const words = [];
|
||||
const re = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'|([^\s]+)/g;
|
||||
let match;
|
||||
while ((match = re.exec(command))) {
|
||||
words.push((match[1] ?? match[2] ?? match[3] ?? '').replace(/\\(["'])/g, '$1'));
|
||||
}
|
||||
return words;
|
||||
}
|
||||
|
||||
function shellHereDocContent(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const markerMatch = command.match(/<<-?\s*['"]?([A-Za-z0-9_.-]+)['"]?[^\r\n]*\r?\n/);
|
||||
if (!markerMatch) return '';
|
||||
const marker = markerMatch[1];
|
||||
const start = (markerMatch.index || 0) + markerMatch[0].length;
|
||||
const rest = command.slice(start);
|
||||
const endRe = new RegExp(`\\r?\\n${escapeRegExp(marker)}(?:\\r?\\n|$)`);
|
||||
const end = rest.search(endRe);
|
||||
return end >= 0 ? rest.slice(0, end) : '';
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
function relativePath(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
|
||||
return rel.split(path.sep).join('/');
|
||||
} catch {
|
||||
return filePath;
|
||||
}
|
||||
}
|
||||
|
||||
function isInsideProject(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function cursorBlockMessage(findings, filePath, config, cwd) {
|
||||
const rendered = renderTemplate(findings, filePath, config, { cwd });
|
||||
const blocked = rendered.replace(
|
||||
'[impeccable@1] Required design corrections',
|
||||
'[impeccable@1] Impeccable design hook blocked this write before it landed. Required design corrections',
|
||||
);
|
||||
return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
|
||||
}
|
||||
|
||||
function findingSignature(findings) {
|
||||
return findings
|
||||
.map((finding) => `${finding.antipattern || 'unknown'}:${finding.line || 0}`)
|
||||
.sort()
|
||||
.join('|');
|
||||
}
|
||||
|
||||
function bumpCursorDenial(cache, sessionId, filePath, findings) {
|
||||
const session = cache.sessions[sessionId] || { updatedAt: Date.now(), files: {} };
|
||||
cache.sessions[sessionId] = session;
|
||||
session.updatedAt = Date.now();
|
||||
const fileEntry = session.files[filePath] || { editCount: 0, findings: [] };
|
||||
session.files[filePath] = fileEntry;
|
||||
const key = findingSignature(findings);
|
||||
fileEntry.cursorDenials = fileEntry.cursorDenials && typeof fileEntry.cursorDenials === 'object'
|
||||
? fileEntry.cursorDenials
|
||||
: {};
|
||||
fileEntry.cursorDenials[key] = (fileEntry.cursorDenials[key] || 0) + 1;
|
||||
return { key, count: fileEntry.cursorDenials[key] };
|
||||
}
|
||||
|
||||
async function main() {
|
||||
if (truthy(process.env.IMPECCABLE_HOOK_DISABLED)) {
|
||||
return allow({ skipped: 'env-disabled' });
|
||||
}
|
||||
|
||||
let event = null;
|
||||
try {
|
||||
const raw = await readStdin();
|
||||
if (raw) event = JSON.parse(raw);
|
||||
} catch {
|
||||
return allow({ skipped: 'stdin-malformed' });
|
||||
}
|
||||
|
||||
if (!event || typeof event !== 'object') {
|
||||
return allow({ skipped: 'stdin-empty' });
|
||||
}
|
||||
|
||||
const cwd = resolveProjectCwd(event);
|
||||
const started = Date.now();
|
||||
const filePath = proposedFilePath(event, cwd);
|
||||
const audit = {
|
||||
harness: 'cursor',
|
||||
tool: event.tool_name || null,
|
||||
file: filePath || null,
|
||||
};
|
||||
|
||||
if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
|
||||
if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
|
||||
if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
|
||||
if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
|
||||
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
audit.ext = ext;
|
||||
if (!ALLOWED_EXTS.has(ext)) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
|
||||
|
||||
const contentResult = proposedContent(event, cwd, filePath);
|
||||
if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
|
||||
return allow({ ...audit, skipped: contentResult.skipped, durationMs: Date.now() - started });
|
||||
}
|
||||
const content = typeof contentResult === 'string' ? contentResult : '';
|
||||
if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
|
||||
|
||||
const config = readConfig(cwd);
|
||||
if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
|
||||
|
||||
const rel = relativePath(filePath, cwd);
|
||||
if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
|
||||
return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const detector = await loadDetector();
|
||||
if (!detector || typeof detector.detectText !== 'function') {
|
||||
return allow({ ...audit, skipped: 'detector-missing', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
let findings = [];
|
||||
try {
|
||||
findings = await detector.detectText(content, filePath);
|
||||
} catch {
|
||||
return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const filtered = filterFindings(findings || [], content, ext, config);
|
||||
if (filtered.length === 0) {
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: 0,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
const message = cursorBlockMessage(filtered, filePath, config, cwd);
|
||||
const sessionId = event.session_id || event.conversation_id || 'unknown';
|
||||
const cache = readCache(cwd);
|
||||
const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
|
||||
persistCache(cwd, cache);
|
||||
if (denial.count > EDIT_COUNT_THRESHOLD) {
|
||||
const warning = `${message}\n\nThis is the ${denial.count}th repeated denial for the same file and finding signature, so Impeccable is allowing this write to avoid a loop. Reconsider the issue immediately after the tool runs.`;
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
downgraded: true,
|
||||
chars: warning.length,
|
||||
durationMs: Date.now() - started,
|
||||
}, {
|
||||
user_message: warning,
|
||||
agent_message: warning,
|
||||
});
|
||||
}
|
||||
return deny(message, {
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
chars: message.length,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook-before-edit] ${err}\n`);
|
||||
}
|
||||
done({ permission: 'allow' });
|
||||
});
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — PostToolUse entry point.
|
||||
*
|
||||
* Reads the Claude Code / Codex / Cursor hook event from stdin, runs the design
|
||||
* detector against the touched file, and emits a system reminder via
|
||||
* `hookSpecificOutput.additionalContext` when findings exist.
|
||||
*
|
||||
* Contract: never break a turn. Always exit 0. Clean files emit a small ack
|
||||
* unless quiet mode is enabled.
|
||||
*
|
||||
* Most logic lives in `hook-lib.mjs` so it is unit-testable without a
|
||||
* subprocess. This file is the thin stdin/stdout adapter.
|
||||
*/
|
||||
|
||||
import { runHook, writeAuditLog } from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
async function main() {
|
||||
// Snapshot the inherited env FIRST so the re-entrancy guard checks the
|
||||
// parent's value, not the value we are about to export for any child
|
||||
// processes the hook might ever spawn.
|
||||
const inheritedEnv = { ...process.env };
|
||||
process.env.IMPECCABLE_HOOK_DEPTH = process.env.IMPECCABLE_HOOK_DEPTH || '1';
|
||||
|
||||
let stdinJson = '';
|
||||
try { stdinJson = await readStdin(); } catch { /* fall through */ }
|
||||
|
||||
const result = await runHook({
|
||||
stdinJson,
|
||||
env: inheritedEnv,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
|
||||
writeAuditLog(process.env, result.audit);
|
||||
|
||||
if (result.stdout) process.stdout.write(result.stdout);
|
||||
process.exit(result.exitCode || 0);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
// Last-ditch: never break the agent's turn even if something we did not
|
||||
// anticipate goes wrong. Audit-log the failure if logging is enabled.
|
||||
try {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'PostToolUse',
|
||||
error: String(err && err.message ? err.message : err),
|
||||
});
|
||||
} catch { /* swallow */ }
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook] ${err}\n`);
|
||||
}
|
||||
process.exit(0);
|
||||
});
|
||||
@@ -32,6 +32,8 @@ const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.cache.json',
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/hook.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
|
||||
@@ -123,7 +123,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
|
||||
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
|
||||
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
|
||||
|
||||
Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
|
||||
Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
|
||||
|
||||
### Routing rules
|
||||
|
||||
@@ -140,7 +140,7 @@ Plus two management commands: `pin <command>` and `unpin <command>`, detailed be
|
||||
**If `scan.targets` is non-empty, run `node .gemini/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
|
||||
|
||||
Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
|
||||
2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
|
||||
4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
|
||||
|
||||
@@ -158,4 +158,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
|
||||
node .gemini/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
|
||||
```
|
||||
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
|
||||
## Hooks
|
||||
|
||||
`/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `/impeccable hooks` with any argument.
|
||||
@@ -0,0 +1,82 @@
|
||||
# /impeccable hooks
|
||||
|
||||
Manage the **design detector hook** for the current project.
|
||||
|
||||
The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code and Codex use `PostToolUse` and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless `IMPECCABLE_HOOK_QUIET=1` is set. Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
|
||||
|
||||
This command toggles the hook **per project** by editing `.impeccable/hook.json`. Local-only ignore policy lives in `.impeccable/hook.local.json`, which is gitignored. To disable globally, set `IMPECCABLE_HOOK_DISABLED=1` in your shell environment.
|
||||
|
||||
Supported harnesses: Claude Code (`.claude/settings.json` in the project), Codex (`.codex/hooks.json` in the project), and Cursor (`.cursor/hooks.json` in the project).
|
||||
|
||||
On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
|
||||
|
||||
## Routing
|
||||
|
||||
The first argument is the action. Defaults to `status`.
|
||||
|
||||
| Action | What it does |
|
||||
|---|---|
|
||||
| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
|
||||
| `on` | Set `enabled: true` in `.impeccable/hook.json`. |
|
||||
| `off` | Set `enabled: false` in `.impeccable/hook.json`. |
|
||||
| `ignore-rule <id>` | Append `<id>` to `ignoreRules`; for `overused-font`, requires `--all-values`. |
|
||||
| `ignore-file <glob>` | Append `<glob>` to `ignoreFiles`. |
|
||||
| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/hook.json`. |
|
||||
| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/hook.local.json`. |
|
||||
| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
|
||||
|
||||
## Flow
|
||||
|
||||
1. Resolve the action from the user's argument. If no action was given, default to `status`.
|
||||
2. Invoke the admin script and pass the user's output through verbatim:
|
||||
|
||||
```bash
|
||||
node .gemini/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
|
||||
```
|
||||
|
||||
3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/impeccable hooks on`."
|
||||
4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
|
||||
5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/hook.json`; add `--local` only when the user explicitly asks for a private exception.
|
||||
6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
|
||||
|
||||
## Intentional findings
|
||||
|
||||
The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
|
||||
|
||||
Prefer the narrowest exception:
|
||||
|
||||
- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/hook.json` by default.
|
||||
- For `overused-font`, use `ignore-value` when the user confirms a specific font. Do not use `ignore-rule overused-font` for a specific font.
|
||||
- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
|
||||
- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
|
||||
- Do not add source comments such as `impeccable: ignore`; inline comments pollute code and are not a supported suppression mechanism.
|
||||
|
||||
Example value-specific exception:
|
||||
|
||||
```bash
|
||||
node .gemini/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
|
||||
```
|
||||
|
||||
Example whole-rule font exception:
|
||||
|
||||
```bash
|
||||
node .gemini/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
|
||||
```
|
||||
|
||||
Example file-scoped exception:
|
||||
|
||||
```bash
|
||||
node .gemini/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Never modify `.impeccable/hook.json` or `.impeccable/hook.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent.
|
||||
- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
|
||||
- Cursor can block a proposed write when the detector finds a real issue. Claude Code and Codex do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
|
||||
- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.json`, `.codex/hooks.json`, and `.cursor/hooks.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- If `.impeccable/hook.json` or `.impeccable/hook.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
|
||||
- If the user asks to "disable the hook" globally, suggest both options: `IMPECCABLE_HOOK_DISABLED=1` env var (one-shot, follows the shell), and `/impeccable hooks off` (persistent for this project, committable).
|
||||
@@ -446,7 +446,7 @@ function detectText(content, filePath, options = {}) {
|
||||
|
||||
// Run regex matchers on the full file content (catches Tailwind classes, inline styles)
|
||||
// Enable block context for CSS files where related properties span multiple lines
|
||||
const cssLike = new Set(['.css', '.scss', '.less']);
|
||||
const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
|
||||
findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
|
||||
profile,
|
||||
phase: 'source',
|
||||
|
||||
@@ -11,7 +11,7 @@ const SKIP_DIRS = new Set([
|
||||
]);
|
||||
|
||||
const SCANNABLE_EXTENSIONS = new Set([
|
||||
'.html', '.htm', '.css', '.scss', '.less',
|
||||
'.html', '.htm', '.css', '.scss', '.sass', '.less',
|
||||
'.jsx', '.tsx', '.js', '.ts',
|
||||
'.vue', '.svelte', '.astro',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,300 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* `/impeccable hooks <on|off|status|reset>` — manage the design hook
|
||||
* via .impeccable/hook.json and .impeccable/hook.local.json in the current
|
||||
* project.
|
||||
*
|
||||
* Usage:
|
||||
* node hook-admin.mjs status # print current state
|
||||
* node hook-admin.mjs on # set enabled: true
|
||||
* node hook-admin.mjs off # set enabled: false
|
||||
* node hook-admin.mjs ignore-rule <rule-id> # append to ignoreRules
|
||||
* node hook-admin.mjs ignore-rule overused-font --all-values
|
||||
* node hook-admin.mjs ignore-file <glob> # append to ignoreFiles
|
||||
* node hook-admin.mjs ignore-value <rule> <value> # append to shared ignoreValues
|
||||
* node hook-admin.mjs ignore-value <rule> <value> --local
|
||||
* node hook-admin.mjs reset # remove all config + cache
|
||||
*
|
||||
* Designed to be invoked by the LLM from the reference/hooks.md flow.
|
||||
* Output is human-readable; the harness will pass it back to the user.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
getConfigPath,
|
||||
getLocalConfigPath,
|
||||
getCachePath,
|
||||
getPendingPath,
|
||||
readConfig,
|
||||
DEFAULT_CONFIG,
|
||||
ensureHookGitExcludes,
|
||||
normalizeIgnoreValue,
|
||||
normalizeIgnoreValueEntries,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
|
||||
|
||||
function readRawConfigFile(filePath) {
|
||||
if (!fs.existsSync(filePath)) return { exists: false, malformed: false, raw: null };
|
||||
try {
|
||||
return { exists: true, malformed: false, raw: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
|
||||
} catch {
|
||||
return { exists: true, malformed: true, raw: null };
|
||||
}
|
||||
}
|
||||
|
||||
function readRawConfig(cwd, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
return readRawConfigFile(filePath).raw;
|
||||
}
|
||||
|
||||
function writeConfig(cwd, config, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
if (opts.local) ensureHookGitExcludes(cwd);
|
||||
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
||||
fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
function mergeConfig(existing) {
|
||||
// Persist the full shape so /impeccable hooks edits leave a complete file
|
||||
// for the user to see, not an unhelpful `{"enabled":false}`.
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
return {
|
||||
enabled: base.enabled === false ? false : true,
|
||||
ignoreRules: Array.isArray(base.ignoreRules) ? Array.from(new Set(base.ignoreRules.map(String))) : [],
|
||||
ignoreFiles: Array.isArray(base.ignoreFiles) ? Array.from(new Set(base.ignoreFiles.map(String))) : [],
|
||||
ignoreValues: normalizeIgnoreValueEntries(base.ignoreValues || []),
|
||||
limits: {
|
||||
maxFindings: Number.isFinite(base?.limits?.maxFindings) ? base.limits.maxFindings : DEFAULT_CONFIG.limits.maxFindings,
|
||||
maxChars: Number.isFinite(base?.limits?.maxChars) ? base.limits.maxChars : DEFAULT_CONFIG.limits.maxChars,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function mergeLocalConfig(existing) {
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
const out = {};
|
||||
if (Object.prototype.hasOwnProperty.call(base, 'enabled')) {
|
||||
out.enabled = base.enabled === false ? false : true;
|
||||
}
|
||||
if (Array.isArray(base.ignoreRules)) {
|
||||
out.ignoreRules = Array.from(new Set(base.ignoreRules.map(String)));
|
||||
}
|
||||
if (Array.isArray(base.ignoreFiles)) {
|
||||
out.ignoreFiles = Array.from(new Set(base.ignoreFiles.map(String)));
|
||||
}
|
||||
out.ignoreValues = normalizeIgnoreValueEntries(base.ignoreValues || []);
|
||||
if (base.limits && typeof base.limits === 'object') {
|
||||
const limits = {};
|
||||
if (Number.isFinite(base.limits.maxFindings)) limits.maxFindings = base.limits.maxFindings;
|
||||
if (Number.isFinite(base.limits.maxChars)) limits.maxChars = base.limits.maxChars;
|
||||
if (Object.keys(limits).length) out.limits = limits;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function statusReport(cwd) {
|
||||
const shared = readRawConfigFile(getConfigPath(cwd));
|
||||
const local = readRawConfigFile(getLocalConfigPath(cwd));
|
||||
const cfg = readConfig(cwd);
|
||||
const envKill = process.env.IMPECCABLE_HOOK_DISABLED;
|
||||
const envState = envKill ? `IMPECCABLE_HOOK_DISABLED=${envKill}` : 'unset';
|
||||
const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.impeccable/hook.json';
|
||||
const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.impeccable/hook.local.json';
|
||||
const cachePath = path.relative(cwd, getCachePath(cwd)) || '.impeccable/hook.cache.json';
|
||||
const fileState = (info, relPath, absent) => {
|
||||
if (info.malformed) return `${relPath} (malformed; ignored)`;
|
||||
if (info.exists) return relPath;
|
||||
return `${relPath} (${absent})`;
|
||||
};
|
||||
const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
|
||||
|
||||
const lines = [
|
||||
`Impeccable design hook`,
|
||||
` state: ${cfg.enabled ? 'enabled' : 'disabled'}`,
|
||||
` shared file: ${fileState(shared, cfgPath, 'using defaults; file not present')}`,
|
||||
` local file: ${fileState(local, localPath, 'not present')}`,
|
||||
` ignoreRules: ${cfg.ignoreRules.length ? cfg.ignoreRules.join(', ') : '(none)'}`,
|
||||
` ignoreFiles: ${cfg.ignoreFiles.length ? cfg.ignoreFiles.join(', ') : '(none)'}`,
|
||||
` ignoreValues: ${ignoreValues.length ? ignoreValues.join(', ') : '(none)'}`,
|
||||
` maxFindings: ${cfg.limits.maxFindings}`,
|
||||
` maxChars: ${cfg.limits.maxChars}`,
|
||||
` env override: ${envState}`,
|
||||
` cache file: ${fs.existsSync(getCachePath(cwd)) ? cachePath : `${cachePath} (not present)`}`,
|
||||
];
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function setEnabled(cwd, value) {
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
config.enabled = value;
|
||||
const target = writeConfig(cwd, config);
|
||||
return `Design hook ${value ? 'enabled' : 'disabled'} for this project (wrote ${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function normalizeRuleId(rule) {
|
||||
return String(rule || '').trim().toLowerCase();
|
||||
}
|
||||
|
||||
function parseIgnoreRuleArgs(args) {
|
||||
const positionals = [];
|
||||
let allValues = false;
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = String(args[i] || '');
|
||||
if (arg === '--all-values') {
|
||||
allValues = true;
|
||||
} else if (arg === '--reason') {
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
|
||||
} else if (arg.startsWith('--reason=')) {
|
||||
// Accepted for command symmetry; ignoreRules stores rule ids only.
|
||||
} else if (arg.startsWith('--')) {
|
||||
throw new Error(`Unknown ignore-rule flag: ${arg}`);
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rule: normalizeRuleId(positionals[0]),
|
||||
allValues,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreRule(cwd, args) {
|
||||
const parsed = parseIgnoreRuleArgs(args);
|
||||
const rule = parsed.rule;
|
||||
if (!rule) throw new Error('Pass a rule id, e.g. /impeccable hooks ignore-rule side-tab');
|
||||
if (rule === 'overused-font' && !parsed.allValues) {
|
||||
throw new Error('overused-font is value-specific by default. Use /impeccable hooks ignore-value overused-font <font> for a confirmed font, or /impeccable hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.');
|
||||
}
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${rule}" to ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
|
||||
}
|
||||
|
||||
function addIgnoreFile(cwd, glob) {
|
||||
if (!glob) throw new Error('Pass a glob, e.g. /impeccable hooks ignore-file "src/legacy/**"');
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${glob}" to ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
|
||||
}
|
||||
|
||||
function parseIgnoreValueArgs(args) {
|
||||
const positionals = [];
|
||||
let shared = false;
|
||||
let local = false;
|
||||
let reason = '';
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = args[i];
|
||||
if (arg === '--shared') {
|
||||
shared = true;
|
||||
} else if (arg === '--local') {
|
||||
local = true;
|
||||
} else if (arg === '--reason') {
|
||||
const chunks = [];
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) {
|
||||
chunks.push(args[++i]);
|
||||
}
|
||||
reason = chunks.join(' ').trim();
|
||||
} else if (String(arg).startsWith('--reason=')) {
|
||||
reason = String(arg).slice('--reason='.length).trim();
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
const [rule, ...valueParts] = positionals;
|
||||
return {
|
||||
rule: String(rule || '').trim().toLowerCase(),
|
||||
value: normalizeIgnoreValue(valueParts.join(' ')),
|
||||
shared,
|
||||
local,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreValue(cwd, args) {
|
||||
const parsed = parseIgnoreValueArgs(args);
|
||||
if (!parsed.rule || !parsed.value) {
|
||||
throw new Error('Pass a rule id and value, e.g. /impeccable hooks ignore-value overused-font Inter');
|
||||
}
|
||||
|
||||
if (parsed.shared && parsed.local) {
|
||||
throw new Error('Pass only one scope flag: --shared or --local');
|
||||
}
|
||||
|
||||
const local = parsed.local;
|
||||
const config = local
|
||||
? mergeLocalConfig(readRawConfig(cwd, { local: true }))
|
||||
: mergeConfig(readRawConfig(cwd, { local: false }));
|
||||
const key = `${parsed.rule}\0${parsed.value}`;
|
||||
const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
|
||||
|
||||
if (existing) {
|
||||
if (parsed.reason) existing.reason = parsed.reason;
|
||||
} else {
|
||||
const entry = {
|
||||
rule: parsed.rule,
|
||||
value: parsed.value,
|
||||
createdAt: new Date().toISOString(),
|
||||
};
|
||||
if (parsed.reason) entry.reason = parsed.reason;
|
||||
config.ignoreValues.push(entry);
|
||||
}
|
||||
|
||||
const target = writeConfig(cwd, config, { local });
|
||||
const scope = local ? 'local ignoreValues' : 'shared ignoreValues';
|
||||
return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function reset(cwd) {
|
||||
const removed = [];
|
||||
for (const filePath of [getConfigPath(cwd), getLocalConfigPath(cwd), getCachePath(cwd), getPendingPath(cwd)]) {
|
||||
try {
|
||||
if (fs.existsSync(filePath)) {
|
||||
fs.unlinkSync(filePath);
|
||||
removed.push(path.relative(cwd, filePath) || filePath);
|
||||
}
|
||||
} catch { /* ignore */ }
|
||||
}
|
||||
return removed.length
|
||||
? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
|
||||
: 'No hook config or cache to remove. Already at defaults.';
|
||||
}
|
||||
|
||||
function main() {
|
||||
const [, , actionArg, ...rest] = process.argv;
|
||||
const action = (actionArg || 'status').toLowerCase();
|
||||
const cwd = process.cwd();
|
||||
|
||||
if (!ACTIONS.has(action)) {
|
||||
process.stderr.write(`Unknown action: ${action}\nValid: ${Array.from(ACTIONS).join(', ')}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
let out = '';
|
||||
switch (action) {
|
||||
case 'status': out = statusReport(cwd); break;
|
||||
case 'on': out = setEnabled(cwd, true); break;
|
||||
case 'off': out = setEnabled(cwd, false); break;
|
||||
case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
|
||||
case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
|
||||
case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
|
||||
case 'reset': out = reset(cwd); break;
|
||||
}
|
||||
process.stdout.write(out + '\n');
|
||||
} catch (err) {
|
||||
process.stderr.write(`Error: ${err.message || err}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,408 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — Cursor preToolUse write gate.
|
||||
*
|
||||
* Cursor's stop hook is not consistently dispatched by the headless agent, so
|
||||
* this hook checks proposed Write/Edit content before it lands. It only denies
|
||||
* writes when the real detector finds an issue in the proposed UI content.
|
||||
*
|
||||
* Contract: never break a turn accidentally. On malformed input or internal
|
||||
* errors, allow the tool and exit 0.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
ALLOWED_EXTS,
|
||||
EDIT_COUNT_THRESHOLD,
|
||||
GENERATED_PATH,
|
||||
SENSITIVE_PATH,
|
||||
filterFindings,
|
||||
loadDetector,
|
||||
matchesAnyGlob,
|
||||
persistCache,
|
||||
readCache,
|
||||
readConfig,
|
||||
renderTemplate,
|
||||
resolveProjectCwd,
|
||||
truthy,
|
||||
writeAuditLog,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
function done(payload = null) {
|
||||
if (payload) process.stdout.write(JSON.stringify(payload));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
function allow(extra = {}, payload = {}) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
...extra,
|
||||
});
|
||||
return done({ permission: 'allow', ...payload });
|
||||
}
|
||||
|
||||
function deny(message, audit) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
blocked: true,
|
||||
...audit,
|
||||
});
|
||||
return done({
|
||||
permission: 'deny',
|
||||
user_message: message,
|
||||
agent_message: message,
|
||||
});
|
||||
}
|
||||
|
||||
function toolInput(event) {
|
||||
return event?.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
|
||||
}
|
||||
|
||||
function proposedFilePath(event, cwd) {
|
||||
const input = toolInput(event);
|
||||
const raw = input.file_path || input.path || input.target_file || event?.file_path;
|
||||
const candidate = typeof raw === 'string' && raw.trim()
|
||||
? raw
|
||||
: shellWriteDestination(shellCommand(input));
|
||||
if (typeof candidate !== 'string' || !candidate.trim()) return '';
|
||||
return path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
|
||||
}
|
||||
|
||||
function proposedContent(event, cwd, filePath) {
|
||||
const input = toolInput(event);
|
||||
for (const key of ['content', 'streamContent', 'text']) {
|
||||
if (typeof input[key] === 'string') return input[key];
|
||||
}
|
||||
|
||||
const editProjection = projectedEditContent(input, filePath, cwd);
|
||||
if (editProjection !== undefined) return editProjection;
|
||||
|
||||
if (hasFragmentEditContent(input)) {
|
||||
return { skipped: 'fragment-only-edit' };
|
||||
}
|
||||
|
||||
const shellContent = shellHereDocContent(shellCommand(input));
|
||||
if (shellContent) return shellContent;
|
||||
const copiedContent = shellCopiedFileContent(shellCommand(input), cwd);
|
||||
if (copiedContent) return copiedContent;
|
||||
return '';
|
||||
}
|
||||
|
||||
function hasFragmentEditContent(input) {
|
||||
if (!input || typeof input !== 'object') return false;
|
||||
if (typeof input.new_string === 'string' || typeof input.newString === 'string' || typeof input.new_str === 'string' || typeof input.replacement === 'string') {
|
||||
return true;
|
||||
}
|
||||
return Array.isArray(input.edits) && input.edits.some((edit) => edit && typeof edit === 'object');
|
||||
}
|
||||
|
||||
function projectedEditContent(input, filePath, cwd) {
|
||||
if (!filePath) return undefined;
|
||||
const singleOld = firstString(input, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const singleNew = firstString(input, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (singleOld !== undefined || singleNew !== undefined) {
|
||||
if (singleOld === undefined || singleNew === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
const projected = replaceOnce(original, singleOld, singleNew);
|
||||
return projected === null ? { skipped: 'edit-old-string-missing' } : projected;
|
||||
}
|
||||
|
||||
if (!Array.isArray(input.edits)) return undefined;
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
|
||||
let projected = original;
|
||||
for (const edit of input.edits) {
|
||||
if (!edit || typeof edit !== 'object') return { skipped: 'fragment-only-edit' };
|
||||
const oldString = firstString(edit, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const newString = firstString(edit, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (oldString === undefined || newString === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const next = replaceOnce(projected, oldString, newString);
|
||||
if (next === null) return { skipped: 'edit-old-string-missing' };
|
||||
projected = next;
|
||||
}
|
||||
return projected;
|
||||
}
|
||||
|
||||
function firstString(obj, keys) {
|
||||
for (const key of keys) {
|
||||
if (typeof obj?.[key] === 'string') return obj[key];
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function replaceOnce(original, oldString, newString) {
|
||||
if (oldString === '') return null;
|
||||
const index = original.indexOf(oldString);
|
||||
if (index === -1) return null;
|
||||
return `${original.slice(0, index)}${newString}${original.slice(index + oldString.length)}`;
|
||||
}
|
||||
|
||||
function readExistingProjectFile(filePath, cwd) {
|
||||
if (!isInsideProject(filePath, cwd)) return null;
|
||||
if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
|
||||
try {
|
||||
const stat = fs.statSync(filePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return null;
|
||||
return fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function shellCommand(input) {
|
||||
if (typeof input.command === 'string') return input.command;
|
||||
if (input.args && typeof input.args.command === 'string') return input.args.command;
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellRedirectPath(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const match = command.match(/(?:^|[\s;&|])(?:>>?|1>>?)\s*(?:"([^"]+)"|'([^']+)'|([^<>\s]+))/);
|
||||
return (match?.[1] || match?.[2] || match?.[3] || '').trim();
|
||||
}
|
||||
|
||||
function shellWriteDestination(command) {
|
||||
return shellRedirectPath(command) || shellTeeDestination(command) || shellCopyPaths(command)?.dest || '';
|
||||
}
|
||||
|
||||
function shellTeeDestination(command) {
|
||||
const words = shellWords(command);
|
||||
const teeIndex = words.findIndex((word) => path.basename(word) === 'tee');
|
||||
if (teeIndex === -1) return '';
|
||||
for (const word of words.slice(teeIndex + 1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
return word;
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellCopiedFileContent(command, cwd) {
|
||||
const source = shellCopyPaths(command)?.source;
|
||||
if (!source) return '';
|
||||
const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
|
||||
if (!isInsideProject(sourcePath, cwd)) return '';
|
||||
if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
|
||||
try {
|
||||
const stat = fs.statSync(sourcePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return '';
|
||||
return fs.readFileSync(sourcePath, 'utf-8');
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
function shellCopyPaths(command) {
|
||||
const words = shellWords(command);
|
||||
if (words.length < 3 || path.basename(words[0]) !== 'cp') return null;
|
||||
const args = [];
|
||||
for (const word of words.slice(1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
args.push(word);
|
||||
}
|
||||
if (args.length < 2) return null;
|
||||
return { source: args[args.length - 2], dest: args[args.length - 1] };
|
||||
}
|
||||
|
||||
function shellWords(command) {
|
||||
if (!command || typeof command !== 'string') return [];
|
||||
const words = [];
|
||||
const re = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'|([^\s]+)/g;
|
||||
let match;
|
||||
while ((match = re.exec(command))) {
|
||||
words.push((match[1] ?? match[2] ?? match[3] ?? '').replace(/\\(["'])/g, '$1'));
|
||||
}
|
||||
return words;
|
||||
}
|
||||
|
||||
function shellHereDocContent(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const markerMatch = command.match(/<<-?\s*['"]?([A-Za-z0-9_.-]+)['"]?[^\r\n]*\r?\n/);
|
||||
if (!markerMatch) return '';
|
||||
const marker = markerMatch[1];
|
||||
const start = (markerMatch.index || 0) + markerMatch[0].length;
|
||||
const rest = command.slice(start);
|
||||
const endRe = new RegExp(`\\r?\\n${escapeRegExp(marker)}(?:\\r?\\n|$)`);
|
||||
const end = rest.search(endRe);
|
||||
return end >= 0 ? rest.slice(0, end) : '';
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
function relativePath(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
|
||||
return rel.split(path.sep).join('/');
|
||||
} catch {
|
||||
return filePath;
|
||||
}
|
||||
}
|
||||
|
||||
function isInsideProject(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function cursorBlockMessage(findings, filePath, config, cwd) {
|
||||
const rendered = renderTemplate(findings, filePath, config, { cwd });
|
||||
const blocked = rendered.replace(
|
||||
'[impeccable@1] Required design corrections',
|
||||
'[impeccable@1] Impeccable design hook blocked this write before it landed. Required design corrections',
|
||||
);
|
||||
return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
|
||||
}
|
||||
|
||||
function findingSignature(findings) {
|
||||
return findings
|
||||
.map((finding) => `${finding.antipattern || 'unknown'}:${finding.line || 0}`)
|
||||
.sort()
|
||||
.join('|');
|
||||
}
|
||||
|
||||
function bumpCursorDenial(cache, sessionId, filePath, findings) {
|
||||
const session = cache.sessions[sessionId] || { updatedAt: Date.now(), files: {} };
|
||||
cache.sessions[sessionId] = session;
|
||||
session.updatedAt = Date.now();
|
||||
const fileEntry = session.files[filePath] || { editCount: 0, findings: [] };
|
||||
session.files[filePath] = fileEntry;
|
||||
const key = findingSignature(findings);
|
||||
fileEntry.cursorDenials = fileEntry.cursorDenials && typeof fileEntry.cursorDenials === 'object'
|
||||
? fileEntry.cursorDenials
|
||||
: {};
|
||||
fileEntry.cursorDenials[key] = (fileEntry.cursorDenials[key] || 0) + 1;
|
||||
return { key, count: fileEntry.cursorDenials[key] };
|
||||
}
|
||||
|
||||
async function main() {
|
||||
if (truthy(process.env.IMPECCABLE_HOOK_DISABLED)) {
|
||||
return allow({ skipped: 'env-disabled' });
|
||||
}
|
||||
|
||||
let event = null;
|
||||
try {
|
||||
const raw = await readStdin();
|
||||
if (raw) event = JSON.parse(raw);
|
||||
} catch {
|
||||
return allow({ skipped: 'stdin-malformed' });
|
||||
}
|
||||
|
||||
if (!event || typeof event !== 'object') {
|
||||
return allow({ skipped: 'stdin-empty' });
|
||||
}
|
||||
|
||||
const cwd = resolveProjectCwd(event);
|
||||
const started = Date.now();
|
||||
const filePath = proposedFilePath(event, cwd);
|
||||
const audit = {
|
||||
harness: 'cursor',
|
||||
tool: event.tool_name || null,
|
||||
file: filePath || null,
|
||||
};
|
||||
|
||||
if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
|
||||
if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
|
||||
if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
|
||||
if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
|
||||
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
audit.ext = ext;
|
||||
if (!ALLOWED_EXTS.has(ext)) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
|
||||
|
||||
const contentResult = proposedContent(event, cwd, filePath);
|
||||
if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
|
||||
return allow({ ...audit, skipped: contentResult.skipped, durationMs: Date.now() - started });
|
||||
}
|
||||
const content = typeof contentResult === 'string' ? contentResult : '';
|
||||
if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
|
||||
|
||||
const config = readConfig(cwd);
|
||||
if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
|
||||
|
||||
const rel = relativePath(filePath, cwd);
|
||||
if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
|
||||
return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const detector = await loadDetector();
|
||||
if (!detector || typeof detector.detectText !== 'function') {
|
||||
return allow({ ...audit, skipped: 'detector-missing', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
let findings = [];
|
||||
try {
|
||||
findings = await detector.detectText(content, filePath);
|
||||
} catch {
|
||||
return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const filtered = filterFindings(findings || [], content, ext, config);
|
||||
if (filtered.length === 0) {
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: 0,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
const message = cursorBlockMessage(filtered, filePath, config, cwd);
|
||||
const sessionId = event.session_id || event.conversation_id || 'unknown';
|
||||
const cache = readCache(cwd);
|
||||
const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
|
||||
persistCache(cwd, cache);
|
||||
if (denial.count > EDIT_COUNT_THRESHOLD) {
|
||||
const warning = `${message}\n\nThis is the ${denial.count}th repeated denial for the same file and finding signature, so Impeccable is allowing this write to avoid a loop. Reconsider the issue immediately after the tool runs.`;
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
downgraded: true,
|
||||
chars: warning.length,
|
||||
durationMs: Date.now() - started,
|
||||
}, {
|
||||
user_message: warning,
|
||||
agent_message: warning,
|
||||
});
|
||||
}
|
||||
return deny(message, {
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
chars: message.length,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook-before-edit] ${err}\n`);
|
||||
}
|
||||
done({ permission: 'allow' });
|
||||
});
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — PostToolUse entry point.
|
||||
*
|
||||
* Reads the Claude Code / Codex / Cursor hook event from stdin, runs the design
|
||||
* detector against the touched file, and emits a system reminder via
|
||||
* `hookSpecificOutput.additionalContext` when findings exist.
|
||||
*
|
||||
* Contract: never break a turn. Always exit 0. Clean files emit a small ack
|
||||
* unless quiet mode is enabled.
|
||||
*
|
||||
* Most logic lives in `hook-lib.mjs` so it is unit-testable without a
|
||||
* subprocess. This file is the thin stdin/stdout adapter.
|
||||
*/
|
||||
|
||||
import { runHook, writeAuditLog } from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
async function main() {
|
||||
// Snapshot the inherited env FIRST so the re-entrancy guard checks the
|
||||
// parent's value, not the value we are about to export for any child
|
||||
// processes the hook might ever spawn.
|
||||
const inheritedEnv = { ...process.env };
|
||||
process.env.IMPECCABLE_HOOK_DEPTH = process.env.IMPECCABLE_HOOK_DEPTH || '1';
|
||||
|
||||
let stdinJson = '';
|
||||
try { stdinJson = await readStdin(); } catch { /* fall through */ }
|
||||
|
||||
const result = await runHook({
|
||||
stdinJson,
|
||||
env: inheritedEnv,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
|
||||
writeAuditLog(process.env, result.audit);
|
||||
|
||||
if (result.stdout) process.stdout.write(result.stdout);
|
||||
process.exit(result.exitCode || 0);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
// Last-ditch: never break the agent's turn even if something we did not
|
||||
// anticipate goes wrong. Audit-log the failure if logging is enabled.
|
||||
try {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'PostToolUse',
|
||||
error: String(err && err.message ? err.message : err),
|
||||
});
|
||||
} catch { /* swallow */ }
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook] ${err}\n`);
|
||||
}
|
||||
process.exit(0);
|
||||
});
|
||||
@@ -32,6 +32,8 @@ const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.cache.json',
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/hook.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
|
||||
@@ -124,7 +124,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
|
||||
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
|
||||
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
|
||||
|
||||
Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
|
||||
Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
|
||||
|
||||
### Routing rules
|
||||
|
||||
@@ -141,7 +141,7 @@ Plus two management commands: `pin <command>` and `unpin <command>`, detailed be
|
||||
**If `scan.targets` is non-empty, run `node .github/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
|
||||
|
||||
Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
|
||||
2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
|
||||
4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
|
||||
|
||||
@@ -159,4 +159,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
|
||||
node .github/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
|
||||
```
|
||||
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
|
||||
## Hooks
|
||||
|
||||
`/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `/impeccable hooks` with any argument.
|
||||
@@ -0,0 +1,82 @@
|
||||
# /impeccable hooks
|
||||
|
||||
Manage the **design detector hook** for the current project.
|
||||
|
||||
The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code and Codex use `PostToolUse` and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless `IMPECCABLE_HOOK_QUIET=1` is set. Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
|
||||
|
||||
This command toggles the hook **per project** by editing `.impeccable/hook.json`. Local-only ignore policy lives in `.impeccable/hook.local.json`, which is gitignored. To disable globally, set `IMPECCABLE_HOOK_DISABLED=1` in your shell environment.
|
||||
|
||||
Supported harnesses: Claude Code (`.claude/settings.json` in the project), Codex (`.codex/hooks.json` in the project), and Cursor (`.cursor/hooks.json` in the project).
|
||||
|
||||
On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
|
||||
|
||||
## Routing
|
||||
|
||||
The first argument is the action. Defaults to `status`.
|
||||
|
||||
| Action | What it does |
|
||||
|---|---|
|
||||
| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
|
||||
| `on` | Set `enabled: true` in `.impeccable/hook.json`. |
|
||||
| `off` | Set `enabled: false` in `.impeccable/hook.json`. |
|
||||
| `ignore-rule <id>` | Append `<id>` to `ignoreRules`; for `overused-font`, requires `--all-values`. |
|
||||
| `ignore-file <glob>` | Append `<glob>` to `ignoreFiles`. |
|
||||
| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/hook.json`. |
|
||||
| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/hook.local.json`. |
|
||||
| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
|
||||
|
||||
## Flow
|
||||
|
||||
1. Resolve the action from the user's argument. If no action was given, default to `status`.
|
||||
2. Invoke the admin script and pass the user's output through verbatim:
|
||||
|
||||
```bash
|
||||
node .github/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
|
||||
```
|
||||
|
||||
3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/impeccable hooks on`."
|
||||
4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
|
||||
5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/hook.json`; add `--local` only when the user explicitly asks for a private exception.
|
||||
6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
|
||||
|
||||
## Intentional findings
|
||||
|
||||
The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
|
||||
|
||||
Prefer the narrowest exception:
|
||||
|
||||
- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/hook.json` by default.
|
||||
- For `overused-font`, use `ignore-value` when the user confirms a specific font. Do not use `ignore-rule overused-font` for a specific font.
|
||||
- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
|
||||
- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
|
||||
- Do not add source comments such as `impeccable: ignore`; inline comments pollute code and are not a supported suppression mechanism.
|
||||
|
||||
Example value-specific exception:
|
||||
|
||||
```bash
|
||||
node .github/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
|
||||
```
|
||||
|
||||
Example whole-rule font exception:
|
||||
|
||||
```bash
|
||||
node .github/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
|
||||
```
|
||||
|
||||
Example file-scoped exception:
|
||||
|
||||
```bash
|
||||
node .github/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Never modify `.impeccable/hook.json` or `.impeccable/hook.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent.
|
||||
- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
|
||||
- Cursor can block a proposed write when the detector finds a real issue. Claude Code and Codex do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
|
||||
- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.json`, `.codex/hooks.json`, and `.cursor/hooks.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- If `.impeccable/hook.json` or `.impeccable/hook.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
|
||||
- If the user asks to "disable the hook" globally, suggest both options: `IMPECCABLE_HOOK_DISABLED=1` env var (one-shot, follows the shell), and `/impeccable hooks off` (persistent for this project, committable).
|
||||
@@ -446,7 +446,7 @@ function detectText(content, filePath, options = {}) {
|
||||
|
||||
// Run regex matchers on the full file content (catches Tailwind classes, inline styles)
|
||||
// Enable block context for CSS files where related properties span multiple lines
|
||||
const cssLike = new Set(['.css', '.scss', '.less']);
|
||||
const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
|
||||
findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
|
||||
profile,
|
||||
phase: 'source',
|
||||
|
||||
@@ -11,7 +11,7 @@ const SKIP_DIRS = new Set([
|
||||
]);
|
||||
|
||||
const SCANNABLE_EXTENSIONS = new Set([
|
||||
'.html', '.htm', '.css', '.scss', '.less',
|
||||
'.html', '.htm', '.css', '.scss', '.sass', '.less',
|
||||
'.jsx', '.tsx', '.js', '.ts',
|
||||
'.vue', '.svelte', '.astro',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,300 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* `/impeccable hooks <on|off|status|reset>` — manage the design hook
|
||||
* via .impeccable/hook.json and .impeccable/hook.local.json in the current
|
||||
* project.
|
||||
*
|
||||
* Usage:
|
||||
* node hook-admin.mjs status # print current state
|
||||
* node hook-admin.mjs on # set enabled: true
|
||||
* node hook-admin.mjs off # set enabled: false
|
||||
* node hook-admin.mjs ignore-rule <rule-id> # append to ignoreRules
|
||||
* node hook-admin.mjs ignore-rule overused-font --all-values
|
||||
* node hook-admin.mjs ignore-file <glob> # append to ignoreFiles
|
||||
* node hook-admin.mjs ignore-value <rule> <value> # append to shared ignoreValues
|
||||
* node hook-admin.mjs ignore-value <rule> <value> --local
|
||||
* node hook-admin.mjs reset # remove all config + cache
|
||||
*
|
||||
* Designed to be invoked by the LLM from the reference/hooks.md flow.
|
||||
* Output is human-readable; the harness will pass it back to the user.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
getConfigPath,
|
||||
getLocalConfigPath,
|
||||
getCachePath,
|
||||
getPendingPath,
|
||||
readConfig,
|
||||
DEFAULT_CONFIG,
|
||||
ensureHookGitExcludes,
|
||||
normalizeIgnoreValue,
|
||||
normalizeIgnoreValueEntries,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
|
||||
|
||||
function readRawConfigFile(filePath) {
|
||||
if (!fs.existsSync(filePath)) return { exists: false, malformed: false, raw: null };
|
||||
try {
|
||||
return { exists: true, malformed: false, raw: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
|
||||
} catch {
|
||||
return { exists: true, malformed: true, raw: null };
|
||||
}
|
||||
}
|
||||
|
||||
function readRawConfig(cwd, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
return readRawConfigFile(filePath).raw;
|
||||
}
|
||||
|
||||
function writeConfig(cwd, config, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
if (opts.local) ensureHookGitExcludes(cwd);
|
||||
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
||||
fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
function mergeConfig(existing) {
|
||||
// Persist the full shape so /impeccable hooks edits leave a complete file
|
||||
// for the user to see, not an unhelpful `{"enabled":false}`.
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
return {
|
||||
enabled: base.enabled === false ? false : true,
|
||||
ignoreRules: Array.isArray(base.ignoreRules) ? Array.from(new Set(base.ignoreRules.map(String))) : [],
|
||||
ignoreFiles: Array.isArray(base.ignoreFiles) ? Array.from(new Set(base.ignoreFiles.map(String))) : [],
|
||||
ignoreValues: normalizeIgnoreValueEntries(base.ignoreValues || []),
|
||||
limits: {
|
||||
maxFindings: Number.isFinite(base?.limits?.maxFindings) ? base.limits.maxFindings : DEFAULT_CONFIG.limits.maxFindings,
|
||||
maxChars: Number.isFinite(base?.limits?.maxChars) ? base.limits.maxChars : DEFAULT_CONFIG.limits.maxChars,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function mergeLocalConfig(existing) {
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
const out = {};
|
||||
if (Object.prototype.hasOwnProperty.call(base, 'enabled')) {
|
||||
out.enabled = base.enabled === false ? false : true;
|
||||
}
|
||||
if (Array.isArray(base.ignoreRules)) {
|
||||
out.ignoreRules = Array.from(new Set(base.ignoreRules.map(String)));
|
||||
}
|
||||
if (Array.isArray(base.ignoreFiles)) {
|
||||
out.ignoreFiles = Array.from(new Set(base.ignoreFiles.map(String)));
|
||||
}
|
||||
out.ignoreValues = normalizeIgnoreValueEntries(base.ignoreValues || []);
|
||||
if (base.limits && typeof base.limits === 'object') {
|
||||
const limits = {};
|
||||
if (Number.isFinite(base.limits.maxFindings)) limits.maxFindings = base.limits.maxFindings;
|
||||
if (Number.isFinite(base.limits.maxChars)) limits.maxChars = base.limits.maxChars;
|
||||
if (Object.keys(limits).length) out.limits = limits;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function statusReport(cwd) {
|
||||
const shared = readRawConfigFile(getConfigPath(cwd));
|
||||
const local = readRawConfigFile(getLocalConfigPath(cwd));
|
||||
const cfg = readConfig(cwd);
|
||||
const envKill = process.env.IMPECCABLE_HOOK_DISABLED;
|
||||
const envState = envKill ? `IMPECCABLE_HOOK_DISABLED=${envKill}` : 'unset';
|
||||
const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.impeccable/hook.json';
|
||||
const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.impeccable/hook.local.json';
|
||||
const cachePath = path.relative(cwd, getCachePath(cwd)) || '.impeccable/hook.cache.json';
|
||||
const fileState = (info, relPath, absent) => {
|
||||
if (info.malformed) return `${relPath} (malformed; ignored)`;
|
||||
if (info.exists) return relPath;
|
||||
return `${relPath} (${absent})`;
|
||||
};
|
||||
const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
|
||||
|
||||
const lines = [
|
||||
`Impeccable design hook`,
|
||||
` state: ${cfg.enabled ? 'enabled' : 'disabled'}`,
|
||||
` shared file: ${fileState(shared, cfgPath, 'using defaults; file not present')}`,
|
||||
` local file: ${fileState(local, localPath, 'not present')}`,
|
||||
` ignoreRules: ${cfg.ignoreRules.length ? cfg.ignoreRules.join(', ') : '(none)'}`,
|
||||
` ignoreFiles: ${cfg.ignoreFiles.length ? cfg.ignoreFiles.join(', ') : '(none)'}`,
|
||||
` ignoreValues: ${ignoreValues.length ? ignoreValues.join(', ') : '(none)'}`,
|
||||
` maxFindings: ${cfg.limits.maxFindings}`,
|
||||
` maxChars: ${cfg.limits.maxChars}`,
|
||||
` env override: ${envState}`,
|
||||
` cache file: ${fs.existsSync(getCachePath(cwd)) ? cachePath : `${cachePath} (not present)`}`,
|
||||
];
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function setEnabled(cwd, value) {
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
config.enabled = value;
|
||||
const target = writeConfig(cwd, config);
|
||||
return `Design hook ${value ? 'enabled' : 'disabled'} for this project (wrote ${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function normalizeRuleId(rule) {
|
||||
return String(rule || '').trim().toLowerCase();
|
||||
}
|
||||
|
||||
function parseIgnoreRuleArgs(args) {
|
||||
const positionals = [];
|
||||
let allValues = false;
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = String(args[i] || '');
|
||||
if (arg === '--all-values') {
|
||||
allValues = true;
|
||||
} else if (arg === '--reason') {
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
|
||||
} else if (arg.startsWith('--reason=')) {
|
||||
// Accepted for command symmetry; ignoreRules stores rule ids only.
|
||||
} else if (arg.startsWith('--')) {
|
||||
throw new Error(`Unknown ignore-rule flag: ${arg}`);
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rule: normalizeRuleId(positionals[0]),
|
||||
allValues,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreRule(cwd, args) {
|
||||
const parsed = parseIgnoreRuleArgs(args);
|
||||
const rule = parsed.rule;
|
||||
if (!rule) throw new Error('Pass a rule id, e.g. /impeccable hooks ignore-rule side-tab');
|
||||
if (rule === 'overused-font' && !parsed.allValues) {
|
||||
throw new Error('overused-font is value-specific by default. Use /impeccable hooks ignore-value overused-font <font> for a confirmed font, or /impeccable hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.');
|
||||
}
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${rule}" to ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
|
||||
}
|
||||
|
||||
function addIgnoreFile(cwd, glob) {
|
||||
if (!glob) throw new Error('Pass a glob, e.g. /impeccable hooks ignore-file "src/legacy/**"');
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${glob}" to ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
|
||||
}
|
||||
|
||||
function parseIgnoreValueArgs(args) {
|
||||
const positionals = [];
|
||||
let shared = false;
|
||||
let local = false;
|
||||
let reason = '';
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = args[i];
|
||||
if (arg === '--shared') {
|
||||
shared = true;
|
||||
} else if (arg === '--local') {
|
||||
local = true;
|
||||
} else if (arg === '--reason') {
|
||||
const chunks = [];
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) {
|
||||
chunks.push(args[++i]);
|
||||
}
|
||||
reason = chunks.join(' ').trim();
|
||||
} else if (String(arg).startsWith('--reason=')) {
|
||||
reason = String(arg).slice('--reason='.length).trim();
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
const [rule, ...valueParts] = positionals;
|
||||
return {
|
||||
rule: String(rule || '').trim().toLowerCase(),
|
||||
value: normalizeIgnoreValue(valueParts.join(' ')),
|
||||
shared,
|
||||
local,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreValue(cwd, args) {
|
||||
const parsed = parseIgnoreValueArgs(args);
|
||||
if (!parsed.rule || !parsed.value) {
|
||||
throw new Error('Pass a rule id and value, e.g. /impeccable hooks ignore-value overused-font Inter');
|
||||
}
|
||||
|
||||
if (parsed.shared && parsed.local) {
|
||||
throw new Error('Pass only one scope flag: --shared or --local');
|
||||
}
|
||||
|
||||
const local = parsed.local;
|
||||
const config = local
|
||||
? mergeLocalConfig(readRawConfig(cwd, { local: true }))
|
||||
: mergeConfig(readRawConfig(cwd, { local: false }));
|
||||
const key = `${parsed.rule}\0${parsed.value}`;
|
||||
const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
|
||||
|
||||
if (existing) {
|
||||
if (parsed.reason) existing.reason = parsed.reason;
|
||||
} else {
|
||||
const entry = {
|
||||
rule: parsed.rule,
|
||||
value: parsed.value,
|
||||
createdAt: new Date().toISOString(),
|
||||
};
|
||||
if (parsed.reason) entry.reason = parsed.reason;
|
||||
config.ignoreValues.push(entry);
|
||||
}
|
||||
|
||||
const target = writeConfig(cwd, config, { local });
|
||||
const scope = local ? 'local ignoreValues' : 'shared ignoreValues';
|
||||
return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function reset(cwd) {
|
||||
const removed = [];
|
||||
for (const filePath of [getConfigPath(cwd), getLocalConfigPath(cwd), getCachePath(cwd), getPendingPath(cwd)]) {
|
||||
try {
|
||||
if (fs.existsSync(filePath)) {
|
||||
fs.unlinkSync(filePath);
|
||||
removed.push(path.relative(cwd, filePath) || filePath);
|
||||
}
|
||||
} catch { /* ignore */ }
|
||||
}
|
||||
return removed.length
|
||||
? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
|
||||
: 'No hook config or cache to remove. Already at defaults.';
|
||||
}
|
||||
|
||||
function main() {
|
||||
const [, , actionArg, ...rest] = process.argv;
|
||||
const action = (actionArg || 'status').toLowerCase();
|
||||
const cwd = process.cwd();
|
||||
|
||||
if (!ACTIONS.has(action)) {
|
||||
process.stderr.write(`Unknown action: ${action}\nValid: ${Array.from(ACTIONS).join(', ')}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
let out = '';
|
||||
switch (action) {
|
||||
case 'status': out = statusReport(cwd); break;
|
||||
case 'on': out = setEnabled(cwd, true); break;
|
||||
case 'off': out = setEnabled(cwd, false); break;
|
||||
case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
|
||||
case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
|
||||
case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
|
||||
case 'reset': out = reset(cwd); break;
|
||||
}
|
||||
process.stdout.write(out + '\n');
|
||||
} catch (err) {
|
||||
process.stderr.write(`Error: ${err.message || err}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,408 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — Cursor preToolUse write gate.
|
||||
*
|
||||
* Cursor's stop hook is not consistently dispatched by the headless agent, so
|
||||
* this hook checks proposed Write/Edit content before it lands. It only denies
|
||||
* writes when the real detector finds an issue in the proposed UI content.
|
||||
*
|
||||
* Contract: never break a turn accidentally. On malformed input or internal
|
||||
* errors, allow the tool and exit 0.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
ALLOWED_EXTS,
|
||||
EDIT_COUNT_THRESHOLD,
|
||||
GENERATED_PATH,
|
||||
SENSITIVE_PATH,
|
||||
filterFindings,
|
||||
loadDetector,
|
||||
matchesAnyGlob,
|
||||
persistCache,
|
||||
readCache,
|
||||
readConfig,
|
||||
renderTemplate,
|
||||
resolveProjectCwd,
|
||||
truthy,
|
||||
writeAuditLog,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
function done(payload = null) {
|
||||
if (payload) process.stdout.write(JSON.stringify(payload));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
function allow(extra = {}, payload = {}) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
...extra,
|
||||
});
|
||||
return done({ permission: 'allow', ...payload });
|
||||
}
|
||||
|
||||
function deny(message, audit) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
blocked: true,
|
||||
...audit,
|
||||
});
|
||||
return done({
|
||||
permission: 'deny',
|
||||
user_message: message,
|
||||
agent_message: message,
|
||||
});
|
||||
}
|
||||
|
||||
function toolInput(event) {
|
||||
return event?.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
|
||||
}
|
||||
|
||||
function proposedFilePath(event, cwd) {
|
||||
const input = toolInput(event);
|
||||
const raw = input.file_path || input.path || input.target_file || event?.file_path;
|
||||
const candidate = typeof raw === 'string' && raw.trim()
|
||||
? raw
|
||||
: shellWriteDestination(shellCommand(input));
|
||||
if (typeof candidate !== 'string' || !candidate.trim()) return '';
|
||||
return path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
|
||||
}
|
||||
|
||||
function proposedContent(event, cwd, filePath) {
|
||||
const input = toolInput(event);
|
||||
for (const key of ['content', 'streamContent', 'text']) {
|
||||
if (typeof input[key] === 'string') return input[key];
|
||||
}
|
||||
|
||||
const editProjection = projectedEditContent(input, filePath, cwd);
|
||||
if (editProjection !== undefined) return editProjection;
|
||||
|
||||
if (hasFragmentEditContent(input)) {
|
||||
return { skipped: 'fragment-only-edit' };
|
||||
}
|
||||
|
||||
const shellContent = shellHereDocContent(shellCommand(input));
|
||||
if (shellContent) return shellContent;
|
||||
const copiedContent = shellCopiedFileContent(shellCommand(input), cwd);
|
||||
if (copiedContent) return copiedContent;
|
||||
return '';
|
||||
}
|
||||
|
||||
function hasFragmentEditContent(input) {
|
||||
if (!input || typeof input !== 'object') return false;
|
||||
if (typeof input.new_string === 'string' || typeof input.newString === 'string' || typeof input.new_str === 'string' || typeof input.replacement === 'string') {
|
||||
return true;
|
||||
}
|
||||
return Array.isArray(input.edits) && input.edits.some((edit) => edit && typeof edit === 'object');
|
||||
}
|
||||
|
||||
function projectedEditContent(input, filePath, cwd) {
|
||||
if (!filePath) return undefined;
|
||||
const singleOld = firstString(input, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const singleNew = firstString(input, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (singleOld !== undefined || singleNew !== undefined) {
|
||||
if (singleOld === undefined || singleNew === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
const projected = replaceOnce(original, singleOld, singleNew);
|
||||
return projected === null ? { skipped: 'edit-old-string-missing' } : projected;
|
||||
}
|
||||
|
||||
if (!Array.isArray(input.edits)) return undefined;
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
|
||||
let projected = original;
|
||||
for (const edit of input.edits) {
|
||||
if (!edit || typeof edit !== 'object') return { skipped: 'fragment-only-edit' };
|
||||
const oldString = firstString(edit, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const newString = firstString(edit, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (oldString === undefined || newString === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const next = replaceOnce(projected, oldString, newString);
|
||||
if (next === null) return { skipped: 'edit-old-string-missing' };
|
||||
projected = next;
|
||||
}
|
||||
return projected;
|
||||
}
|
||||
|
||||
function firstString(obj, keys) {
|
||||
for (const key of keys) {
|
||||
if (typeof obj?.[key] === 'string') return obj[key];
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function replaceOnce(original, oldString, newString) {
|
||||
if (oldString === '') return null;
|
||||
const index = original.indexOf(oldString);
|
||||
if (index === -1) return null;
|
||||
return `${original.slice(0, index)}${newString}${original.slice(index + oldString.length)}`;
|
||||
}
|
||||
|
||||
function readExistingProjectFile(filePath, cwd) {
|
||||
if (!isInsideProject(filePath, cwd)) return null;
|
||||
if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
|
||||
try {
|
||||
const stat = fs.statSync(filePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return null;
|
||||
return fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function shellCommand(input) {
|
||||
if (typeof input.command === 'string') return input.command;
|
||||
if (input.args && typeof input.args.command === 'string') return input.args.command;
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellRedirectPath(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const match = command.match(/(?:^|[\s;&|])(?:>>?|1>>?)\s*(?:"([^"]+)"|'([^']+)'|([^<>\s]+))/);
|
||||
return (match?.[1] || match?.[2] || match?.[3] || '').trim();
|
||||
}
|
||||
|
||||
function shellWriteDestination(command) {
|
||||
return shellRedirectPath(command) || shellTeeDestination(command) || shellCopyPaths(command)?.dest || '';
|
||||
}
|
||||
|
||||
function shellTeeDestination(command) {
|
||||
const words = shellWords(command);
|
||||
const teeIndex = words.findIndex((word) => path.basename(word) === 'tee');
|
||||
if (teeIndex === -1) return '';
|
||||
for (const word of words.slice(teeIndex + 1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
return word;
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellCopiedFileContent(command, cwd) {
|
||||
const source = shellCopyPaths(command)?.source;
|
||||
if (!source) return '';
|
||||
const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
|
||||
if (!isInsideProject(sourcePath, cwd)) return '';
|
||||
if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
|
||||
try {
|
||||
const stat = fs.statSync(sourcePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return '';
|
||||
return fs.readFileSync(sourcePath, 'utf-8');
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
function shellCopyPaths(command) {
|
||||
const words = shellWords(command);
|
||||
if (words.length < 3 || path.basename(words[0]) !== 'cp') return null;
|
||||
const args = [];
|
||||
for (const word of words.slice(1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
args.push(word);
|
||||
}
|
||||
if (args.length < 2) return null;
|
||||
return { source: args[args.length - 2], dest: args[args.length - 1] };
|
||||
}
|
||||
|
||||
function shellWords(command) {
|
||||
if (!command || typeof command !== 'string') return [];
|
||||
const words = [];
|
||||
const re = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'|([^\s]+)/g;
|
||||
let match;
|
||||
while ((match = re.exec(command))) {
|
||||
words.push((match[1] ?? match[2] ?? match[3] ?? '').replace(/\\(["'])/g, '$1'));
|
||||
}
|
||||
return words;
|
||||
}
|
||||
|
||||
function shellHereDocContent(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const markerMatch = command.match(/<<-?\s*['"]?([A-Za-z0-9_.-]+)['"]?[^\r\n]*\r?\n/);
|
||||
if (!markerMatch) return '';
|
||||
const marker = markerMatch[1];
|
||||
const start = (markerMatch.index || 0) + markerMatch[0].length;
|
||||
const rest = command.slice(start);
|
||||
const endRe = new RegExp(`\\r?\\n${escapeRegExp(marker)}(?:\\r?\\n|$)`);
|
||||
const end = rest.search(endRe);
|
||||
return end >= 0 ? rest.slice(0, end) : '';
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
function relativePath(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
|
||||
return rel.split(path.sep).join('/');
|
||||
} catch {
|
||||
return filePath;
|
||||
}
|
||||
}
|
||||
|
||||
function isInsideProject(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function cursorBlockMessage(findings, filePath, config, cwd) {
|
||||
const rendered = renderTemplate(findings, filePath, config, { cwd });
|
||||
const blocked = rendered.replace(
|
||||
'[impeccable@1] Required design corrections',
|
||||
'[impeccable@1] Impeccable design hook blocked this write before it landed. Required design corrections',
|
||||
);
|
||||
return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
|
||||
}
|
||||
|
||||
function findingSignature(findings) {
|
||||
return findings
|
||||
.map((finding) => `${finding.antipattern || 'unknown'}:${finding.line || 0}`)
|
||||
.sort()
|
||||
.join('|');
|
||||
}
|
||||
|
||||
function bumpCursorDenial(cache, sessionId, filePath, findings) {
|
||||
const session = cache.sessions[sessionId] || { updatedAt: Date.now(), files: {} };
|
||||
cache.sessions[sessionId] = session;
|
||||
session.updatedAt = Date.now();
|
||||
const fileEntry = session.files[filePath] || { editCount: 0, findings: [] };
|
||||
session.files[filePath] = fileEntry;
|
||||
const key = findingSignature(findings);
|
||||
fileEntry.cursorDenials = fileEntry.cursorDenials && typeof fileEntry.cursorDenials === 'object'
|
||||
? fileEntry.cursorDenials
|
||||
: {};
|
||||
fileEntry.cursorDenials[key] = (fileEntry.cursorDenials[key] || 0) + 1;
|
||||
return { key, count: fileEntry.cursorDenials[key] };
|
||||
}
|
||||
|
||||
async function main() {
|
||||
if (truthy(process.env.IMPECCABLE_HOOK_DISABLED)) {
|
||||
return allow({ skipped: 'env-disabled' });
|
||||
}
|
||||
|
||||
let event = null;
|
||||
try {
|
||||
const raw = await readStdin();
|
||||
if (raw) event = JSON.parse(raw);
|
||||
} catch {
|
||||
return allow({ skipped: 'stdin-malformed' });
|
||||
}
|
||||
|
||||
if (!event || typeof event !== 'object') {
|
||||
return allow({ skipped: 'stdin-empty' });
|
||||
}
|
||||
|
||||
const cwd = resolveProjectCwd(event);
|
||||
const started = Date.now();
|
||||
const filePath = proposedFilePath(event, cwd);
|
||||
const audit = {
|
||||
harness: 'cursor',
|
||||
tool: event.tool_name || null,
|
||||
file: filePath || null,
|
||||
};
|
||||
|
||||
if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
|
||||
if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
|
||||
if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
|
||||
if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
|
||||
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
audit.ext = ext;
|
||||
if (!ALLOWED_EXTS.has(ext)) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
|
||||
|
||||
const contentResult = proposedContent(event, cwd, filePath);
|
||||
if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
|
||||
return allow({ ...audit, skipped: contentResult.skipped, durationMs: Date.now() - started });
|
||||
}
|
||||
const content = typeof contentResult === 'string' ? contentResult : '';
|
||||
if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
|
||||
|
||||
const config = readConfig(cwd);
|
||||
if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
|
||||
|
||||
const rel = relativePath(filePath, cwd);
|
||||
if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
|
||||
return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const detector = await loadDetector();
|
||||
if (!detector || typeof detector.detectText !== 'function') {
|
||||
return allow({ ...audit, skipped: 'detector-missing', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
let findings = [];
|
||||
try {
|
||||
findings = await detector.detectText(content, filePath);
|
||||
} catch {
|
||||
return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const filtered = filterFindings(findings || [], content, ext, config);
|
||||
if (filtered.length === 0) {
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: 0,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
const message = cursorBlockMessage(filtered, filePath, config, cwd);
|
||||
const sessionId = event.session_id || event.conversation_id || 'unknown';
|
||||
const cache = readCache(cwd);
|
||||
const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
|
||||
persistCache(cwd, cache);
|
||||
if (denial.count > EDIT_COUNT_THRESHOLD) {
|
||||
const warning = `${message}\n\nThis is the ${denial.count}th repeated denial for the same file and finding signature, so Impeccable is allowing this write to avoid a loop. Reconsider the issue immediately after the tool runs.`;
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
downgraded: true,
|
||||
chars: warning.length,
|
||||
durationMs: Date.now() - started,
|
||||
}, {
|
||||
user_message: warning,
|
||||
agent_message: warning,
|
||||
});
|
||||
}
|
||||
return deny(message, {
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
chars: message.length,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook-before-edit] ${err}\n`);
|
||||
}
|
||||
done({ permission: 'allow' });
|
||||
});
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — PostToolUse entry point.
|
||||
*
|
||||
* Reads the Claude Code / Codex / Cursor hook event from stdin, runs the design
|
||||
* detector against the touched file, and emits a system reminder via
|
||||
* `hookSpecificOutput.additionalContext` when findings exist.
|
||||
*
|
||||
* Contract: never break a turn. Always exit 0. Clean files emit a small ack
|
||||
* unless quiet mode is enabled.
|
||||
*
|
||||
* Most logic lives in `hook-lib.mjs` so it is unit-testable without a
|
||||
* subprocess. This file is the thin stdin/stdout adapter.
|
||||
*/
|
||||
|
||||
import { runHook, writeAuditLog } from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
async function main() {
|
||||
// Snapshot the inherited env FIRST so the re-entrancy guard checks the
|
||||
// parent's value, not the value we are about to export for any child
|
||||
// processes the hook might ever spawn.
|
||||
const inheritedEnv = { ...process.env };
|
||||
process.env.IMPECCABLE_HOOK_DEPTH = process.env.IMPECCABLE_HOOK_DEPTH || '1';
|
||||
|
||||
let stdinJson = '';
|
||||
try { stdinJson = await readStdin(); } catch { /* fall through */ }
|
||||
|
||||
const result = await runHook({
|
||||
stdinJson,
|
||||
env: inheritedEnv,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
|
||||
writeAuditLog(process.env, result.audit);
|
||||
|
||||
if (result.stdout) process.stdout.write(result.stdout);
|
||||
process.exit(result.exitCode || 0);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
// Last-ditch: never break the agent's turn even if something we did not
|
||||
// anticipate goes wrong. Audit-log the failure if logging is enabled.
|
||||
try {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'PostToolUse',
|
||||
error: String(err && err.message ? err.message : err),
|
||||
});
|
||||
} catch { /* swallow */ }
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook] ${err}\n`);
|
||||
}
|
||||
process.exit(0);
|
||||
});
|
||||
@@ -32,6 +32,8 @@ const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.cache.json',
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/hook.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
|
||||
+8
-3
@@ -51,6 +51,10 @@ Thumbs.db
|
||||
.impeccable/live/pending-manual-edits.json
|
||||
.impeccable/live/deferred-svelte-component-accepts.json
|
||||
.impeccable/history/
|
||||
.impeccable/hook.local.json
|
||||
.impeccable/hook.pending.json
|
||||
.impeccable/provider-smoke/
|
||||
src/__impeccable_provider_smoke_*.html
|
||||
# Per-run critique snapshots are local artifacts. ignore.md (also under
|
||||
# this dir) carries deferrals the user may want to share, so it's
|
||||
# explicitly re-included below.
|
||||
@@ -106,10 +110,11 @@ site/public/js/generated/
|
||||
# time, and they enable clean submodule use. Run `bun run build` to refresh
|
||||
# them after editing skill/.
|
||||
#
|
||||
# Codex CLI consumes `.agents/skills/`; the asset-producer subagent now ships
|
||||
# nested inside that skill (agents/*.toml), auto-discovered on install, so
|
||||
# nothing under `.codex/` is tracked.
|
||||
# Codex CLI consumes `.agents/skills/`; the asset-producer subagent ships
|
||||
# nested inside that skill (agents/*.toml), auto-discovered on install.
|
||||
# The project-local hook manifest is the one tracked `.codex/` artifact.
|
||||
.codex/*
|
||||
!.codex/hooks.json
|
||||
.astro/
|
||||
|
||||
# Local-only scratch for exploratory scripts, parked pages, and unused asset candidates.
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"enabled": true,
|
||||
"ignoreRules": [],
|
||||
"ignoreFiles": [
|
||||
"tests/fixtures/**",
|
||||
"site/pages/slop/**"
|
||||
],
|
||||
"ignoreValues": [],
|
||||
"limits": {
|
||||
"maxFindings": 5,
|
||||
"maxChars": 8000
|
||||
}
|
||||
}
|
||||
@@ -122,7 +122,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
|
||||
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
|
||||
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
|
||||
|
||||
Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
|
||||
Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
|
||||
|
||||
### Routing rules
|
||||
|
||||
@@ -139,7 +139,7 @@ Plus two management commands: `pin <command>` and `unpin <command>`, detailed be
|
||||
**If `scan.targets` is non-empty, run `node .kiro/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
|
||||
|
||||
Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
|
||||
2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
|
||||
4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
|
||||
|
||||
@@ -157,4 +157,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
|
||||
node .kiro/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
|
||||
```
|
||||
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
|
||||
## Hooks
|
||||
|
||||
`/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `/impeccable hooks` with any argument.
|
||||
@@ -0,0 +1,82 @@
|
||||
# /impeccable hooks
|
||||
|
||||
Manage the **design detector hook** for the current project.
|
||||
|
||||
The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code and Codex use `PostToolUse` and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless `IMPECCABLE_HOOK_QUIET=1` is set. Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
|
||||
|
||||
This command toggles the hook **per project** by editing `.impeccable/hook.json`. Local-only ignore policy lives in `.impeccable/hook.local.json`, which is gitignored. To disable globally, set `IMPECCABLE_HOOK_DISABLED=1` in your shell environment.
|
||||
|
||||
Supported harnesses: Claude Code (`.claude/settings.json` in the project), Codex (`.codex/hooks.json` in the project), and Cursor (`.cursor/hooks.json` in the project).
|
||||
|
||||
On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
|
||||
|
||||
## Routing
|
||||
|
||||
The first argument is the action. Defaults to `status`.
|
||||
|
||||
| Action | What it does |
|
||||
|---|---|
|
||||
| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
|
||||
| `on` | Set `enabled: true` in `.impeccable/hook.json`. |
|
||||
| `off` | Set `enabled: false` in `.impeccable/hook.json`. |
|
||||
| `ignore-rule <id>` | Append `<id>` to `ignoreRules`; for `overused-font`, requires `--all-values`. |
|
||||
| `ignore-file <glob>` | Append `<glob>` to `ignoreFiles`. |
|
||||
| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/hook.json`. |
|
||||
| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/hook.local.json`. |
|
||||
| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
|
||||
|
||||
## Flow
|
||||
|
||||
1. Resolve the action from the user's argument. If no action was given, default to `status`.
|
||||
2. Invoke the admin script and pass the user's output through verbatim:
|
||||
|
||||
```bash
|
||||
node .kiro/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
|
||||
```
|
||||
|
||||
3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/impeccable hooks on`."
|
||||
4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
|
||||
5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/hook.json`; add `--local` only when the user explicitly asks for a private exception.
|
||||
6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
|
||||
|
||||
## Intentional findings
|
||||
|
||||
The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
|
||||
|
||||
Prefer the narrowest exception:
|
||||
|
||||
- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/hook.json` by default.
|
||||
- For `overused-font`, use `ignore-value` when the user confirms a specific font. Do not use `ignore-rule overused-font` for a specific font.
|
||||
- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
|
||||
- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
|
||||
- Do not add source comments such as `impeccable: ignore`; inline comments pollute code and are not a supported suppression mechanism.
|
||||
|
||||
Example value-specific exception:
|
||||
|
||||
```bash
|
||||
node .kiro/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
|
||||
```
|
||||
|
||||
Example whole-rule font exception:
|
||||
|
||||
```bash
|
||||
node .kiro/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
|
||||
```
|
||||
|
||||
Example file-scoped exception:
|
||||
|
||||
```bash
|
||||
node .kiro/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Never modify `.impeccable/hook.json` or `.impeccable/hook.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent.
|
||||
- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
|
||||
- Cursor can block a proposed write when the detector finds a real issue. Claude Code and Codex do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
|
||||
- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.json`, `.codex/hooks.json`, and `.cursor/hooks.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- If `.impeccable/hook.json` or `.impeccable/hook.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
|
||||
- If the user asks to "disable the hook" globally, suggest both options: `IMPECCABLE_HOOK_DISABLED=1` env var (one-shot, follows the shell), and `/impeccable hooks off` (persistent for this project, committable).
|
||||
@@ -446,7 +446,7 @@ function detectText(content, filePath, options = {}) {
|
||||
|
||||
// Run regex matchers on the full file content (catches Tailwind classes, inline styles)
|
||||
// Enable block context for CSS files where related properties span multiple lines
|
||||
const cssLike = new Set(['.css', '.scss', '.less']);
|
||||
const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
|
||||
findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
|
||||
profile,
|
||||
phase: 'source',
|
||||
|
||||
@@ -11,7 +11,7 @@ const SKIP_DIRS = new Set([
|
||||
]);
|
||||
|
||||
const SCANNABLE_EXTENSIONS = new Set([
|
||||
'.html', '.htm', '.css', '.scss', '.less',
|
||||
'.html', '.htm', '.css', '.scss', '.sass', '.less',
|
||||
'.jsx', '.tsx', '.js', '.ts',
|
||||
'.vue', '.svelte', '.astro',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,300 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* `/impeccable hooks <on|off|status|reset>` — manage the design hook
|
||||
* via .impeccable/hook.json and .impeccable/hook.local.json in the current
|
||||
* project.
|
||||
*
|
||||
* Usage:
|
||||
* node hook-admin.mjs status # print current state
|
||||
* node hook-admin.mjs on # set enabled: true
|
||||
* node hook-admin.mjs off # set enabled: false
|
||||
* node hook-admin.mjs ignore-rule <rule-id> # append to ignoreRules
|
||||
* node hook-admin.mjs ignore-rule overused-font --all-values
|
||||
* node hook-admin.mjs ignore-file <glob> # append to ignoreFiles
|
||||
* node hook-admin.mjs ignore-value <rule> <value> # append to shared ignoreValues
|
||||
* node hook-admin.mjs ignore-value <rule> <value> --local
|
||||
* node hook-admin.mjs reset # remove all config + cache
|
||||
*
|
||||
* Designed to be invoked by the LLM from the reference/hooks.md flow.
|
||||
* Output is human-readable; the harness will pass it back to the user.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
getConfigPath,
|
||||
getLocalConfigPath,
|
||||
getCachePath,
|
||||
getPendingPath,
|
||||
readConfig,
|
||||
DEFAULT_CONFIG,
|
||||
ensureHookGitExcludes,
|
||||
normalizeIgnoreValue,
|
||||
normalizeIgnoreValueEntries,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
|
||||
|
||||
function readRawConfigFile(filePath) {
|
||||
if (!fs.existsSync(filePath)) return { exists: false, malformed: false, raw: null };
|
||||
try {
|
||||
return { exists: true, malformed: false, raw: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
|
||||
} catch {
|
||||
return { exists: true, malformed: true, raw: null };
|
||||
}
|
||||
}
|
||||
|
||||
function readRawConfig(cwd, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
return readRawConfigFile(filePath).raw;
|
||||
}
|
||||
|
||||
function writeConfig(cwd, config, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
if (opts.local) ensureHookGitExcludes(cwd);
|
||||
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
||||
fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
function mergeConfig(existing) {
|
||||
// Persist the full shape so /impeccable hooks edits leave a complete file
|
||||
// for the user to see, not an unhelpful `{"enabled":false}`.
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
return {
|
||||
enabled: base.enabled === false ? false : true,
|
||||
ignoreRules: Array.isArray(base.ignoreRules) ? Array.from(new Set(base.ignoreRules.map(String))) : [],
|
||||
ignoreFiles: Array.isArray(base.ignoreFiles) ? Array.from(new Set(base.ignoreFiles.map(String))) : [],
|
||||
ignoreValues: normalizeIgnoreValueEntries(base.ignoreValues || []),
|
||||
limits: {
|
||||
maxFindings: Number.isFinite(base?.limits?.maxFindings) ? base.limits.maxFindings : DEFAULT_CONFIG.limits.maxFindings,
|
||||
maxChars: Number.isFinite(base?.limits?.maxChars) ? base.limits.maxChars : DEFAULT_CONFIG.limits.maxChars,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function mergeLocalConfig(existing) {
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
const out = {};
|
||||
if (Object.prototype.hasOwnProperty.call(base, 'enabled')) {
|
||||
out.enabled = base.enabled === false ? false : true;
|
||||
}
|
||||
if (Array.isArray(base.ignoreRules)) {
|
||||
out.ignoreRules = Array.from(new Set(base.ignoreRules.map(String)));
|
||||
}
|
||||
if (Array.isArray(base.ignoreFiles)) {
|
||||
out.ignoreFiles = Array.from(new Set(base.ignoreFiles.map(String)));
|
||||
}
|
||||
out.ignoreValues = normalizeIgnoreValueEntries(base.ignoreValues || []);
|
||||
if (base.limits && typeof base.limits === 'object') {
|
||||
const limits = {};
|
||||
if (Number.isFinite(base.limits.maxFindings)) limits.maxFindings = base.limits.maxFindings;
|
||||
if (Number.isFinite(base.limits.maxChars)) limits.maxChars = base.limits.maxChars;
|
||||
if (Object.keys(limits).length) out.limits = limits;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function statusReport(cwd) {
|
||||
const shared = readRawConfigFile(getConfigPath(cwd));
|
||||
const local = readRawConfigFile(getLocalConfigPath(cwd));
|
||||
const cfg = readConfig(cwd);
|
||||
const envKill = process.env.IMPECCABLE_HOOK_DISABLED;
|
||||
const envState = envKill ? `IMPECCABLE_HOOK_DISABLED=${envKill}` : 'unset';
|
||||
const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.impeccable/hook.json';
|
||||
const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.impeccable/hook.local.json';
|
||||
const cachePath = path.relative(cwd, getCachePath(cwd)) || '.impeccable/hook.cache.json';
|
||||
const fileState = (info, relPath, absent) => {
|
||||
if (info.malformed) return `${relPath} (malformed; ignored)`;
|
||||
if (info.exists) return relPath;
|
||||
return `${relPath} (${absent})`;
|
||||
};
|
||||
const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
|
||||
|
||||
const lines = [
|
||||
`Impeccable design hook`,
|
||||
` state: ${cfg.enabled ? 'enabled' : 'disabled'}`,
|
||||
` shared file: ${fileState(shared, cfgPath, 'using defaults; file not present')}`,
|
||||
` local file: ${fileState(local, localPath, 'not present')}`,
|
||||
` ignoreRules: ${cfg.ignoreRules.length ? cfg.ignoreRules.join(', ') : '(none)'}`,
|
||||
` ignoreFiles: ${cfg.ignoreFiles.length ? cfg.ignoreFiles.join(', ') : '(none)'}`,
|
||||
` ignoreValues: ${ignoreValues.length ? ignoreValues.join(', ') : '(none)'}`,
|
||||
` maxFindings: ${cfg.limits.maxFindings}`,
|
||||
` maxChars: ${cfg.limits.maxChars}`,
|
||||
` env override: ${envState}`,
|
||||
` cache file: ${fs.existsSync(getCachePath(cwd)) ? cachePath : `${cachePath} (not present)`}`,
|
||||
];
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function setEnabled(cwd, value) {
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
config.enabled = value;
|
||||
const target = writeConfig(cwd, config);
|
||||
return `Design hook ${value ? 'enabled' : 'disabled'} for this project (wrote ${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function normalizeRuleId(rule) {
|
||||
return String(rule || '').trim().toLowerCase();
|
||||
}
|
||||
|
||||
function parseIgnoreRuleArgs(args) {
|
||||
const positionals = [];
|
||||
let allValues = false;
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = String(args[i] || '');
|
||||
if (arg === '--all-values') {
|
||||
allValues = true;
|
||||
} else if (arg === '--reason') {
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
|
||||
} else if (arg.startsWith('--reason=')) {
|
||||
// Accepted for command symmetry; ignoreRules stores rule ids only.
|
||||
} else if (arg.startsWith('--')) {
|
||||
throw new Error(`Unknown ignore-rule flag: ${arg}`);
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rule: normalizeRuleId(positionals[0]),
|
||||
allValues,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreRule(cwd, args) {
|
||||
const parsed = parseIgnoreRuleArgs(args);
|
||||
const rule = parsed.rule;
|
||||
if (!rule) throw new Error('Pass a rule id, e.g. /impeccable hooks ignore-rule side-tab');
|
||||
if (rule === 'overused-font' && !parsed.allValues) {
|
||||
throw new Error('overused-font is value-specific by default. Use /impeccable hooks ignore-value overused-font <font> for a confirmed font, or /impeccable hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.');
|
||||
}
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${rule}" to ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
|
||||
}
|
||||
|
||||
function addIgnoreFile(cwd, glob) {
|
||||
if (!glob) throw new Error('Pass a glob, e.g. /impeccable hooks ignore-file "src/legacy/**"');
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${glob}" to ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
|
||||
}
|
||||
|
||||
function parseIgnoreValueArgs(args) {
|
||||
const positionals = [];
|
||||
let shared = false;
|
||||
let local = false;
|
||||
let reason = '';
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = args[i];
|
||||
if (arg === '--shared') {
|
||||
shared = true;
|
||||
} else if (arg === '--local') {
|
||||
local = true;
|
||||
} else if (arg === '--reason') {
|
||||
const chunks = [];
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) {
|
||||
chunks.push(args[++i]);
|
||||
}
|
||||
reason = chunks.join(' ').trim();
|
||||
} else if (String(arg).startsWith('--reason=')) {
|
||||
reason = String(arg).slice('--reason='.length).trim();
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
const [rule, ...valueParts] = positionals;
|
||||
return {
|
||||
rule: String(rule || '').trim().toLowerCase(),
|
||||
value: normalizeIgnoreValue(valueParts.join(' ')),
|
||||
shared,
|
||||
local,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreValue(cwd, args) {
|
||||
const parsed = parseIgnoreValueArgs(args);
|
||||
if (!parsed.rule || !parsed.value) {
|
||||
throw new Error('Pass a rule id and value, e.g. /impeccable hooks ignore-value overused-font Inter');
|
||||
}
|
||||
|
||||
if (parsed.shared && parsed.local) {
|
||||
throw new Error('Pass only one scope flag: --shared or --local');
|
||||
}
|
||||
|
||||
const local = parsed.local;
|
||||
const config = local
|
||||
? mergeLocalConfig(readRawConfig(cwd, { local: true }))
|
||||
: mergeConfig(readRawConfig(cwd, { local: false }));
|
||||
const key = `${parsed.rule}\0${parsed.value}`;
|
||||
const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
|
||||
|
||||
if (existing) {
|
||||
if (parsed.reason) existing.reason = parsed.reason;
|
||||
} else {
|
||||
const entry = {
|
||||
rule: parsed.rule,
|
||||
value: parsed.value,
|
||||
createdAt: new Date().toISOString(),
|
||||
};
|
||||
if (parsed.reason) entry.reason = parsed.reason;
|
||||
config.ignoreValues.push(entry);
|
||||
}
|
||||
|
||||
const target = writeConfig(cwd, config, { local });
|
||||
const scope = local ? 'local ignoreValues' : 'shared ignoreValues';
|
||||
return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function reset(cwd) {
|
||||
const removed = [];
|
||||
for (const filePath of [getConfigPath(cwd), getLocalConfigPath(cwd), getCachePath(cwd), getPendingPath(cwd)]) {
|
||||
try {
|
||||
if (fs.existsSync(filePath)) {
|
||||
fs.unlinkSync(filePath);
|
||||
removed.push(path.relative(cwd, filePath) || filePath);
|
||||
}
|
||||
} catch { /* ignore */ }
|
||||
}
|
||||
return removed.length
|
||||
? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
|
||||
: 'No hook config or cache to remove. Already at defaults.';
|
||||
}
|
||||
|
||||
function main() {
|
||||
const [, , actionArg, ...rest] = process.argv;
|
||||
const action = (actionArg || 'status').toLowerCase();
|
||||
const cwd = process.cwd();
|
||||
|
||||
if (!ACTIONS.has(action)) {
|
||||
process.stderr.write(`Unknown action: ${action}\nValid: ${Array.from(ACTIONS).join(', ')}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
let out = '';
|
||||
switch (action) {
|
||||
case 'status': out = statusReport(cwd); break;
|
||||
case 'on': out = setEnabled(cwd, true); break;
|
||||
case 'off': out = setEnabled(cwd, false); break;
|
||||
case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
|
||||
case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
|
||||
case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
|
||||
case 'reset': out = reset(cwd); break;
|
||||
}
|
||||
process.stdout.write(out + '\n');
|
||||
} catch (err) {
|
||||
process.stderr.write(`Error: ${err.message || err}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,408 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — Cursor preToolUse write gate.
|
||||
*
|
||||
* Cursor's stop hook is not consistently dispatched by the headless agent, so
|
||||
* this hook checks proposed Write/Edit content before it lands. It only denies
|
||||
* writes when the real detector finds an issue in the proposed UI content.
|
||||
*
|
||||
* Contract: never break a turn accidentally. On malformed input or internal
|
||||
* errors, allow the tool and exit 0.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
ALLOWED_EXTS,
|
||||
EDIT_COUNT_THRESHOLD,
|
||||
GENERATED_PATH,
|
||||
SENSITIVE_PATH,
|
||||
filterFindings,
|
||||
loadDetector,
|
||||
matchesAnyGlob,
|
||||
persistCache,
|
||||
readCache,
|
||||
readConfig,
|
||||
renderTemplate,
|
||||
resolveProjectCwd,
|
||||
truthy,
|
||||
writeAuditLog,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
function done(payload = null) {
|
||||
if (payload) process.stdout.write(JSON.stringify(payload));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
function allow(extra = {}, payload = {}) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
...extra,
|
||||
});
|
||||
return done({ permission: 'allow', ...payload });
|
||||
}
|
||||
|
||||
function deny(message, audit) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
blocked: true,
|
||||
...audit,
|
||||
});
|
||||
return done({
|
||||
permission: 'deny',
|
||||
user_message: message,
|
||||
agent_message: message,
|
||||
});
|
||||
}
|
||||
|
||||
function toolInput(event) {
|
||||
return event?.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
|
||||
}
|
||||
|
||||
function proposedFilePath(event, cwd) {
|
||||
const input = toolInput(event);
|
||||
const raw = input.file_path || input.path || input.target_file || event?.file_path;
|
||||
const candidate = typeof raw === 'string' && raw.trim()
|
||||
? raw
|
||||
: shellWriteDestination(shellCommand(input));
|
||||
if (typeof candidate !== 'string' || !candidate.trim()) return '';
|
||||
return path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
|
||||
}
|
||||
|
||||
function proposedContent(event, cwd, filePath) {
|
||||
const input = toolInput(event);
|
||||
for (const key of ['content', 'streamContent', 'text']) {
|
||||
if (typeof input[key] === 'string') return input[key];
|
||||
}
|
||||
|
||||
const editProjection = projectedEditContent(input, filePath, cwd);
|
||||
if (editProjection !== undefined) return editProjection;
|
||||
|
||||
if (hasFragmentEditContent(input)) {
|
||||
return { skipped: 'fragment-only-edit' };
|
||||
}
|
||||
|
||||
const shellContent = shellHereDocContent(shellCommand(input));
|
||||
if (shellContent) return shellContent;
|
||||
const copiedContent = shellCopiedFileContent(shellCommand(input), cwd);
|
||||
if (copiedContent) return copiedContent;
|
||||
return '';
|
||||
}
|
||||
|
||||
function hasFragmentEditContent(input) {
|
||||
if (!input || typeof input !== 'object') return false;
|
||||
if (typeof input.new_string === 'string' || typeof input.newString === 'string' || typeof input.new_str === 'string' || typeof input.replacement === 'string') {
|
||||
return true;
|
||||
}
|
||||
return Array.isArray(input.edits) && input.edits.some((edit) => edit && typeof edit === 'object');
|
||||
}
|
||||
|
||||
function projectedEditContent(input, filePath, cwd) {
|
||||
if (!filePath) return undefined;
|
||||
const singleOld = firstString(input, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const singleNew = firstString(input, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (singleOld !== undefined || singleNew !== undefined) {
|
||||
if (singleOld === undefined || singleNew === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
const projected = replaceOnce(original, singleOld, singleNew);
|
||||
return projected === null ? { skipped: 'edit-old-string-missing' } : projected;
|
||||
}
|
||||
|
||||
if (!Array.isArray(input.edits)) return undefined;
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
|
||||
let projected = original;
|
||||
for (const edit of input.edits) {
|
||||
if (!edit || typeof edit !== 'object') return { skipped: 'fragment-only-edit' };
|
||||
const oldString = firstString(edit, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const newString = firstString(edit, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (oldString === undefined || newString === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const next = replaceOnce(projected, oldString, newString);
|
||||
if (next === null) return { skipped: 'edit-old-string-missing' };
|
||||
projected = next;
|
||||
}
|
||||
return projected;
|
||||
}
|
||||
|
||||
function firstString(obj, keys) {
|
||||
for (const key of keys) {
|
||||
if (typeof obj?.[key] === 'string') return obj[key];
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function replaceOnce(original, oldString, newString) {
|
||||
if (oldString === '') return null;
|
||||
const index = original.indexOf(oldString);
|
||||
if (index === -1) return null;
|
||||
return `${original.slice(0, index)}${newString}${original.slice(index + oldString.length)}`;
|
||||
}
|
||||
|
||||
function readExistingProjectFile(filePath, cwd) {
|
||||
if (!isInsideProject(filePath, cwd)) return null;
|
||||
if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
|
||||
try {
|
||||
const stat = fs.statSync(filePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return null;
|
||||
return fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function shellCommand(input) {
|
||||
if (typeof input.command === 'string') return input.command;
|
||||
if (input.args && typeof input.args.command === 'string') return input.args.command;
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellRedirectPath(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const match = command.match(/(?:^|[\s;&|])(?:>>?|1>>?)\s*(?:"([^"]+)"|'([^']+)'|([^<>\s]+))/);
|
||||
return (match?.[1] || match?.[2] || match?.[3] || '').trim();
|
||||
}
|
||||
|
||||
function shellWriteDestination(command) {
|
||||
return shellRedirectPath(command) || shellTeeDestination(command) || shellCopyPaths(command)?.dest || '';
|
||||
}
|
||||
|
||||
function shellTeeDestination(command) {
|
||||
const words = shellWords(command);
|
||||
const teeIndex = words.findIndex((word) => path.basename(word) === 'tee');
|
||||
if (teeIndex === -1) return '';
|
||||
for (const word of words.slice(teeIndex + 1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
return word;
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellCopiedFileContent(command, cwd) {
|
||||
const source = shellCopyPaths(command)?.source;
|
||||
if (!source) return '';
|
||||
const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
|
||||
if (!isInsideProject(sourcePath, cwd)) return '';
|
||||
if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
|
||||
try {
|
||||
const stat = fs.statSync(sourcePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return '';
|
||||
return fs.readFileSync(sourcePath, 'utf-8');
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
function shellCopyPaths(command) {
|
||||
const words = shellWords(command);
|
||||
if (words.length < 3 || path.basename(words[0]) !== 'cp') return null;
|
||||
const args = [];
|
||||
for (const word of words.slice(1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
args.push(word);
|
||||
}
|
||||
if (args.length < 2) return null;
|
||||
return { source: args[args.length - 2], dest: args[args.length - 1] };
|
||||
}
|
||||
|
||||
function shellWords(command) {
|
||||
if (!command || typeof command !== 'string') return [];
|
||||
const words = [];
|
||||
const re = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'|([^\s]+)/g;
|
||||
let match;
|
||||
while ((match = re.exec(command))) {
|
||||
words.push((match[1] ?? match[2] ?? match[3] ?? '').replace(/\\(["'])/g, '$1'));
|
||||
}
|
||||
return words;
|
||||
}
|
||||
|
||||
function shellHereDocContent(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const markerMatch = command.match(/<<-?\s*['"]?([A-Za-z0-9_.-]+)['"]?[^\r\n]*\r?\n/);
|
||||
if (!markerMatch) return '';
|
||||
const marker = markerMatch[1];
|
||||
const start = (markerMatch.index || 0) + markerMatch[0].length;
|
||||
const rest = command.slice(start);
|
||||
const endRe = new RegExp(`\\r?\\n${escapeRegExp(marker)}(?:\\r?\\n|$)`);
|
||||
const end = rest.search(endRe);
|
||||
return end >= 0 ? rest.slice(0, end) : '';
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
function relativePath(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
|
||||
return rel.split(path.sep).join('/');
|
||||
} catch {
|
||||
return filePath;
|
||||
}
|
||||
}
|
||||
|
||||
function isInsideProject(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function cursorBlockMessage(findings, filePath, config, cwd) {
|
||||
const rendered = renderTemplate(findings, filePath, config, { cwd });
|
||||
const blocked = rendered.replace(
|
||||
'[impeccable@1] Required design corrections',
|
||||
'[impeccable@1] Impeccable design hook blocked this write before it landed. Required design corrections',
|
||||
);
|
||||
return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
|
||||
}
|
||||
|
||||
function findingSignature(findings) {
|
||||
return findings
|
||||
.map((finding) => `${finding.antipattern || 'unknown'}:${finding.line || 0}`)
|
||||
.sort()
|
||||
.join('|');
|
||||
}
|
||||
|
||||
function bumpCursorDenial(cache, sessionId, filePath, findings) {
|
||||
const session = cache.sessions[sessionId] || { updatedAt: Date.now(), files: {} };
|
||||
cache.sessions[sessionId] = session;
|
||||
session.updatedAt = Date.now();
|
||||
const fileEntry = session.files[filePath] || { editCount: 0, findings: [] };
|
||||
session.files[filePath] = fileEntry;
|
||||
const key = findingSignature(findings);
|
||||
fileEntry.cursorDenials = fileEntry.cursorDenials && typeof fileEntry.cursorDenials === 'object'
|
||||
? fileEntry.cursorDenials
|
||||
: {};
|
||||
fileEntry.cursorDenials[key] = (fileEntry.cursorDenials[key] || 0) + 1;
|
||||
return { key, count: fileEntry.cursorDenials[key] };
|
||||
}
|
||||
|
||||
async function main() {
|
||||
if (truthy(process.env.IMPECCABLE_HOOK_DISABLED)) {
|
||||
return allow({ skipped: 'env-disabled' });
|
||||
}
|
||||
|
||||
let event = null;
|
||||
try {
|
||||
const raw = await readStdin();
|
||||
if (raw) event = JSON.parse(raw);
|
||||
} catch {
|
||||
return allow({ skipped: 'stdin-malformed' });
|
||||
}
|
||||
|
||||
if (!event || typeof event !== 'object') {
|
||||
return allow({ skipped: 'stdin-empty' });
|
||||
}
|
||||
|
||||
const cwd = resolveProjectCwd(event);
|
||||
const started = Date.now();
|
||||
const filePath = proposedFilePath(event, cwd);
|
||||
const audit = {
|
||||
harness: 'cursor',
|
||||
tool: event.tool_name || null,
|
||||
file: filePath || null,
|
||||
};
|
||||
|
||||
if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
|
||||
if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
|
||||
if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
|
||||
if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
|
||||
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
audit.ext = ext;
|
||||
if (!ALLOWED_EXTS.has(ext)) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
|
||||
|
||||
const contentResult = proposedContent(event, cwd, filePath);
|
||||
if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
|
||||
return allow({ ...audit, skipped: contentResult.skipped, durationMs: Date.now() - started });
|
||||
}
|
||||
const content = typeof contentResult === 'string' ? contentResult : '';
|
||||
if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
|
||||
|
||||
const config = readConfig(cwd);
|
||||
if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
|
||||
|
||||
const rel = relativePath(filePath, cwd);
|
||||
if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
|
||||
return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const detector = await loadDetector();
|
||||
if (!detector || typeof detector.detectText !== 'function') {
|
||||
return allow({ ...audit, skipped: 'detector-missing', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
let findings = [];
|
||||
try {
|
||||
findings = await detector.detectText(content, filePath);
|
||||
} catch {
|
||||
return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const filtered = filterFindings(findings || [], content, ext, config);
|
||||
if (filtered.length === 0) {
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: 0,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
const message = cursorBlockMessage(filtered, filePath, config, cwd);
|
||||
const sessionId = event.session_id || event.conversation_id || 'unknown';
|
||||
const cache = readCache(cwd);
|
||||
const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
|
||||
persistCache(cwd, cache);
|
||||
if (denial.count > EDIT_COUNT_THRESHOLD) {
|
||||
const warning = `${message}\n\nThis is the ${denial.count}th repeated denial for the same file and finding signature, so Impeccable is allowing this write to avoid a loop. Reconsider the issue immediately after the tool runs.`;
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
downgraded: true,
|
||||
chars: warning.length,
|
||||
durationMs: Date.now() - started,
|
||||
}, {
|
||||
user_message: warning,
|
||||
agent_message: warning,
|
||||
});
|
||||
}
|
||||
return deny(message, {
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
chars: message.length,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook-before-edit] ${err}\n`);
|
||||
}
|
||||
done({ permission: 'allow' });
|
||||
});
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — PostToolUse entry point.
|
||||
*
|
||||
* Reads the Claude Code / Codex / Cursor hook event from stdin, runs the design
|
||||
* detector against the touched file, and emits a system reminder via
|
||||
* `hookSpecificOutput.additionalContext` when findings exist.
|
||||
*
|
||||
* Contract: never break a turn. Always exit 0. Clean files emit a small ack
|
||||
* unless quiet mode is enabled.
|
||||
*
|
||||
* Most logic lives in `hook-lib.mjs` so it is unit-testable without a
|
||||
* subprocess. This file is the thin stdin/stdout adapter.
|
||||
*/
|
||||
|
||||
import { runHook, writeAuditLog } from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
async function main() {
|
||||
// Snapshot the inherited env FIRST so the re-entrancy guard checks the
|
||||
// parent's value, not the value we are about to export for any child
|
||||
// processes the hook might ever spawn.
|
||||
const inheritedEnv = { ...process.env };
|
||||
process.env.IMPECCABLE_HOOK_DEPTH = process.env.IMPECCABLE_HOOK_DEPTH || '1';
|
||||
|
||||
let stdinJson = '';
|
||||
try { stdinJson = await readStdin(); } catch { /* fall through */ }
|
||||
|
||||
const result = await runHook({
|
||||
stdinJson,
|
||||
env: inheritedEnv,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
|
||||
writeAuditLog(process.env, result.audit);
|
||||
|
||||
if (result.stdout) process.stdout.write(result.stdout);
|
||||
process.exit(result.exitCode || 0);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
// Last-ditch: never break the agent's turn even if something we did not
|
||||
// anticipate goes wrong. Audit-log the failure if logging is enabled.
|
||||
try {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'PostToolUse',
|
||||
error: String(err && err.message ? err.message : err),
|
||||
});
|
||||
} catch { /* swallow */ }
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook] ${err}\n`);
|
||||
}
|
||||
process.exit(0);
|
||||
});
|
||||
@@ -32,6 +32,8 @@ const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.cache.json',
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/hook.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
|
||||
@@ -126,7 +126,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
|
||||
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
|
||||
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
|
||||
|
||||
Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
|
||||
Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
|
||||
|
||||
### Routing rules
|
||||
|
||||
@@ -143,7 +143,7 @@ Plus two management commands: `pin <command>` and `unpin <command>`, detailed be
|
||||
**If `scan.targets` is non-empty, run `node .opencode/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
|
||||
|
||||
Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
|
||||
2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
|
||||
4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
|
||||
|
||||
@@ -161,4 +161,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
|
||||
node .opencode/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
|
||||
```
|
||||
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
|
||||
## Hooks
|
||||
|
||||
`/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `/impeccable hooks` with any argument.
|
||||
@@ -0,0 +1,82 @@
|
||||
# /impeccable hooks
|
||||
|
||||
Manage the **design detector hook** for the current project.
|
||||
|
||||
The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code and Codex use `PostToolUse` and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless `IMPECCABLE_HOOK_QUIET=1` is set. Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
|
||||
|
||||
This command toggles the hook **per project** by editing `.impeccable/hook.json`. Local-only ignore policy lives in `.impeccable/hook.local.json`, which is gitignored. To disable globally, set `IMPECCABLE_HOOK_DISABLED=1` in your shell environment.
|
||||
|
||||
Supported harnesses: Claude Code (`.claude/settings.json` in the project), Codex (`.codex/hooks.json` in the project), and Cursor (`.cursor/hooks.json` in the project).
|
||||
|
||||
On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
|
||||
|
||||
## Routing
|
||||
|
||||
The first argument is the action. Defaults to `status`.
|
||||
|
||||
| Action | What it does |
|
||||
|---|---|
|
||||
| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
|
||||
| `on` | Set `enabled: true` in `.impeccable/hook.json`. |
|
||||
| `off` | Set `enabled: false` in `.impeccable/hook.json`. |
|
||||
| `ignore-rule <id>` | Append `<id>` to `ignoreRules`; for `overused-font`, requires `--all-values`. |
|
||||
| `ignore-file <glob>` | Append `<glob>` to `ignoreFiles`. |
|
||||
| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/hook.json`. |
|
||||
| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/hook.local.json`. |
|
||||
| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
|
||||
|
||||
## Flow
|
||||
|
||||
1. Resolve the action from the user's argument. If no action was given, default to `status`.
|
||||
2. Invoke the admin script and pass the user's output through verbatim:
|
||||
|
||||
```bash
|
||||
node .opencode/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
|
||||
```
|
||||
|
||||
3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/impeccable hooks on`."
|
||||
4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
|
||||
5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/hook.json`; add `--local` only when the user explicitly asks for a private exception.
|
||||
6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
|
||||
|
||||
## Intentional findings
|
||||
|
||||
The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
|
||||
|
||||
Prefer the narrowest exception:
|
||||
|
||||
- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/hook.json` by default.
|
||||
- For `overused-font`, use `ignore-value` when the user confirms a specific font. Do not use `ignore-rule overused-font` for a specific font.
|
||||
- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
|
||||
- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
|
||||
- Do not add source comments such as `impeccable: ignore`; inline comments pollute code and are not a supported suppression mechanism.
|
||||
|
||||
Example value-specific exception:
|
||||
|
||||
```bash
|
||||
node .opencode/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
|
||||
```
|
||||
|
||||
Example whole-rule font exception:
|
||||
|
||||
```bash
|
||||
node .opencode/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
|
||||
```
|
||||
|
||||
Example file-scoped exception:
|
||||
|
||||
```bash
|
||||
node .opencode/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Never modify `.impeccable/hook.json` or `.impeccable/hook.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent.
|
||||
- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
|
||||
- Cursor can block a proposed write when the detector finds a real issue. Claude Code and Codex do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
|
||||
- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.json`, `.codex/hooks.json`, and `.cursor/hooks.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- If `.impeccable/hook.json` or `.impeccable/hook.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
|
||||
- If the user asks to "disable the hook" globally, suggest both options: `IMPECCABLE_HOOK_DISABLED=1` env var (one-shot, follows the shell), and `/impeccable hooks off` (persistent for this project, committable).
|
||||
@@ -446,7 +446,7 @@ function detectText(content, filePath, options = {}) {
|
||||
|
||||
// Run regex matchers on the full file content (catches Tailwind classes, inline styles)
|
||||
// Enable block context for CSS files where related properties span multiple lines
|
||||
const cssLike = new Set(['.css', '.scss', '.less']);
|
||||
const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
|
||||
findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
|
||||
profile,
|
||||
phase: 'source',
|
||||
|
||||
@@ -11,7 +11,7 @@ const SKIP_DIRS = new Set([
|
||||
]);
|
||||
|
||||
const SCANNABLE_EXTENSIONS = new Set([
|
||||
'.html', '.htm', '.css', '.scss', '.less',
|
||||
'.html', '.htm', '.css', '.scss', '.sass', '.less',
|
||||
'.jsx', '.tsx', '.js', '.ts',
|
||||
'.vue', '.svelte', '.astro',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,300 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* `/impeccable hooks <on|off|status|reset>` — manage the design hook
|
||||
* via .impeccable/hook.json and .impeccable/hook.local.json in the current
|
||||
* project.
|
||||
*
|
||||
* Usage:
|
||||
* node hook-admin.mjs status # print current state
|
||||
* node hook-admin.mjs on # set enabled: true
|
||||
* node hook-admin.mjs off # set enabled: false
|
||||
* node hook-admin.mjs ignore-rule <rule-id> # append to ignoreRules
|
||||
* node hook-admin.mjs ignore-rule overused-font --all-values
|
||||
* node hook-admin.mjs ignore-file <glob> # append to ignoreFiles
|
||||
* node hook-admin.mjs ignore-value <rule> <value> # append to shared ignoreValues
|
||||
* node hook-admin.mjs ignore-value <rule> <value> --local
|
||||
* node hook-admin.mjs reset # remove all config + cache
|
||||
*
|
||||
* Designed to be invoked by the LLM from the reference/hooks.md flow.
|
||||
* Output is human-readable; the harness will pass it back to the user.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
getConfigPath,
|
||||
getLocalConfigPath,
|
||||
getCachePath,
|
||||
getPendingPath,
|
||||
readConfig,
|
||||
DEFAULT_CONFIG,
|
||||
ensureHookGitExcludes,
|
||||
normalizeIgnoreValue,
|
||||
normalizeIgnoreValueEntries,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
|
||||
|
||||
function readRawConfigFile(filePath) {
|
||||
if (!fs.existsSync(filePath)) return { exists: false, malformed: false, raw: null };
|
||||
try {
|
||||
return { exists: true, malformed: false, raw: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
|
||||
} catch {
|
||||
return { exists: true, malformed: true, raw: null };
|
||||
}
|
||||
}
|
||||
|
||||
function readRawConfig(cwd, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
return readRawConfigFile(filePath).raw;
|
||||
}
|
||||
|
||||
function writeConfig(cwd, config, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
if (opts.local) ensureHookGitExcludes(cwd);
|
||||
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
||||
fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
function mergeConfig(existing) {
|
||||
// Persist the full shape so /impeccable hooks edits leave a complete file
|
||||
// for the user to see, not an unhelpful `{"enabled":false}`.
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
return {
|
||||
enabled: base.enabled === false ? false : true,
|
||||
ignoreRules: Array.isArray(base.ignoreRules) ? Array.from(new Set(base.ignoreRules.map(String))) : [],
|
||||
ignoreFiles: Array.isArray(base.ignoreFiles) ? Array.from(new Set(base.ignoreFiles.map(String))) : [],
|
||||
ignoreValues: normalizeIgnoreValueEntries(base.ignoreValues || []),
|
||||
limits: {
|
||||
maxFindings: Number.isFinite(base?.limits?.maxFindings) ? base.limits.maxFindings : DEFAULT_CONFIG.limits.maxFindings,
|
||||
maxChars: Number.isFinite(base?.limits?.maxChars) ? base.limits.maxChars : DEFAULT_CONFIG.limits.maxChars,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function mergeLocalConfig(existing) {
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
const out = {};
|
||||
if (Object.prototype.hasOwnProperty.call(base, 'enabled')) {
|
||||
out.enabled = base.enabled === false ? false : true;
|
||||
}
|
||||
if (Array.isArray(base.ignoreRules)) {
|
||||
out.ignoreRules = Array.from(new Set(base.ignoreRules.map(String)));
|
||||
}
|
||||
if (Array.isArray(base.ignoreFiles)) {
|
||||
out.ignoreFiles = Array.from(new Set(base.ignoreFiles.map(String)));
|
||||
}
|
||||
out.ignoreValues = normalizeIgnoreValueEntries(base.ignoreValues || []);
|
||||
if (base.limits && typeof base.limits === 'object') {
|
||||
const limits = {};
|
||||
if (Number.isFinite(base.limits.maxFindings)) limits.maxFindings = base.limits.maxFindings;
|
||||
if (Number.isFinite(base.limits.maxChars)) limits.maxChars = base.limits.maxChars;
|
||||
if (Object.keys(limits).length) out.limits = limits;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function statusReport(cwd) {
|
||||
const shared = readRawConfigFile(getConfigPath(cwd));
|
||||
const local = readRawConfigFile(getLocalConfigPath(cwd));
|
||||
const cfg = readConfig(cwd);
|
||||
const envKill = process.env.IMPECCABLE_HOOK_DISABLED;
|
||||
const envState = envKill ? `IMPECCABLE_HOOK_DISABLED=${envKill}` : 'unset';
|
||||
const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.impeccable/hook.json';
|
||||
const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.impeccable/hook.local.json';
|
||||
const cachePath = path.relative(cwd, getCachePath(cwd)) || '.impeccable/hook.cache.json';
|
||||
const fileState = (info, relPath, absent) => {
|
||||
if (info.malformed) return `${relPath} (malformed; ignored)`;
|
||||
if (info.exists) return relPath;
|
||||
return `${relPath} (${absent})`;
|
||||
};
|
||||
const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
|
||||
|
||||
const lines = [
|
||||
`Impeccable design hook`,
|
||||
` state: ${cfg.enabled ? 'enabled' : 'disabled'}`,
|
||||
` shared file: ${fileState(shared, cfgPath, 'using defaults; file not present')}`,
|
||||
` local file: ${fileState(local, localPath, 'not present')}`,
|
||||
` ignoreRules: ${cfg.ignoreRules.length ? cfg.ignoreRules.join(', ') : '(none)'}`,
|
||||
` ignoreFiles: ${cfg.ignoreFiles.length ? cfg.ignoreFiles.join(', ') : '(none)'}`,
|
||||
` ignoreValues: ${ignoreValues.length ? ignoreValues.join(', ') : '(none)'}`,
|
||||
` maxFindings: ${cfg.limits.maxFindings}`,
|
||||
` maxChars: ${cfg.limits.maxChars}`,
|
||||
` env override: ${envState}`,
|
||||
` cache file: ${fs.existsSync(getCachePath(cwd)) ? cachePath : `${cachePath} (not present)`}`,
|
||||
];
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function setEnabled(cwd, value) {
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
config.enabled = value;
|
||||
const target = writeConfig(cwd, config);
|
||||
return `Design hook ${value ? 'enabled' : 'disabled'} for this project (wrote ${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function normalizeRuleId(rule) {
|
||||
return String(rule || '').trim().toLowerCase();
|
||||
}
|
||||
|
||||
function parseIgnoreRuleArgs(args) {
|
||||
const positionals = [];
|
||||
let allValues = false;
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = String(args[i] || '');
|
||||
if (arg === '--all-values') {
|
||||
allValues = true;
|
||||
} else if (arg === '--reason') {
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
|
||||
} else if (arg.startsWith('--reason=')) {
|
||||
// Accepted for command symmetry; ignoreRules stores rule ids only.
|
||||
} else if (arg.startsWith('--')) {
|
||||
throw new Error(`Unknown ignore-rule flag: ${arg}`);
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rule: normalizeRuleId(positionals[0]),
|
||||
allValues,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreRule(cwd, args) {
|
||||
const parsed = parseIgnoreRuleArgs(args);
|
||||
const rule = parsed.rule;
|
||||
if (!rule) throw new Error('Pass a rule id, e.g. /impeccable hooks ignore-rule side-tab');
|
||||
if (rule === 'overused-font' && !parsed.allValues) {
|
||||
throw new Error('overused-font is value-specific by default. Use /impeccable hooks ignore-value overused-font <font> for a confirmed font, or /impeccable hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.');
|
||||
}
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${rule}" to ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
|
||||
}
|
||||
|
||||
function addIgnoreFile(cwd, glob) {
|
||||
if (!glob) throw new Error('Pass a glob, e.g. /impeccable hooks ignore-file "src/legacy/**"');
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${glob}" to ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
|
||||
}
|
||||
|
||||
function parseIgnoreValueArgs(args) {
|
||||
const positionals = [];
|
||||
let shared = false;
|
||||
let local = false;
|
||||
let reason = '';
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = args[i];
|
||||
if (arg === '--shared') {
|
||||
shared = true;
|
||||
} else if (arg === '--local') {
|
||||
local = true;
|
||||
} else if (arg === '--reason') {
|
||||
const chunks = [];
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) {
|
||||
chunks.push(args[++i]);
|
||||
}
|
||||
reason = chunks.join(' ').trim();
|
||||
} else if (String(arg).startsWith('--reason=')) {
|
||||
reason = String(arg).slice('--reason='.length).trim();
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
const [rule, ...valueParts] = positionals;
|
||||
return {
|
||||
rule: String(rule || '').trim().toLowerCase(),
|
||||
value: normalizeIgnoreValue(valueParts.join(' ')),
|
||||
shared,
|
||||
local,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreValue(cwd, args) {
|
||||
const parsed = parseIgnoreValueArgs(args);
|
||||
if (!parsed.rule || !parsed.value) {
|
||||
throw new Error('Pass a rule id and value, e.g. /impeccable hooks ignore-value overused-font Inter');
|
||||
}
|
||||
|
||||
if (parsed.shared && parsed.local) {
|
||||
throw new Error('Pass only one scope flag: --shared or --local');
|
||||
}
|
||||
|
||||
const local = parsed.local;
|
||||
const config = local
|
||||
? mergeLocalConfig(readRawConfig(cwd, { local: true }))
|
||||
: mergeConfig(readRawConfig(cwd, { local: false }));
|
||||
const key = `${parsed.rule}\0${parsed.value}`;
|
||||
const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
|
||||
|
||||
if (existing) {
|
||||
if (parsed.reason) existing.reason = parsed.reason;
|
||||
} else {
|
||||
const entry = {
|
||||
rule: parsed.rule,
|
||||
value: parsed.value,
|
||||
createdAt: new Date().toISOString(),
|
||||
};
|
||||
if (parsed.reason) entry.reason = parsed.reason;
|
||||
config.ignoreValues.push(entry);
|
||||
}
|
||||
|
||||
const target = writeConfig(cwd, config, { local });
|
||||
const scope = local ? 'local ignoreValues' : 'shared ignoreValues';
|
||||
return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function reset(cwd) {
|
||||
const removed = [];
|
||||
for (const filePath of [getConfigPath(cwd), getLocalConfigPath(cwd), getCachePath(cwd), getPendingPath(cwd)]) {
|
||||
try {
|
||||
if (fs.existsSync(filePath)) {
|
||||
fs.unlinkSync(filePath);
|
||||
removed.push(path.relative(cwd, filePath) || filePath);
|
||||
}
|
||||
} catch { /* ignore */ }
|
||||
}
|
||||
return removed.length
|
||||
? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
|
||||
: 'No hook config or cache to remove. Already at defaults.';
|
||||
}
|
||||
|
||||
function main() {
|
||||
const [, , actionArg, ...rest] = process.argv;
|
||||
const action = (actionArg || 'status').toLowerCase();
|
||||
const cwd = process.cwd();
|
||||
|
||||
if (!ACTIONS.has(action)) {
|
||||
process.stderr.write(`Unknown action: ${action}\nValid: ${Array.from(ACTIONS).join(', ')}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
let out = '';
|
||||
switch (action) {
|
||||
case 'status': out = statusReport(cwd); break;
|
||||
case 'on': out = setEnabled(cwd, true); break;
|
||||
case 'off': out = setEnabled(cwd, false); break;
|
||||
case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
|
||||
case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
|
||||
case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
|
||||
case 'reset': out = reset(cwd); break;
|
||||
}
|
||||
process.stdout.write(out + '\n');
|
||||
} catch (err) {
|
||||
process.stderr.write(`Error: ${err.message || err}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,408 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — Cursor preToolUse write gate.
|
||||
*
|
||||
* Cursor's stop hook is not consistently dispatched by the headless agent, so
|
||||
* this hook checks proposed Write/Edit content before it lands. It only denies
|
||||
* writes when the real detector finds an issue in the proposed UI content.
|
||||
*
|
||||
* Contract: never break a turn accidentally. On malformed input or internal
|
||||
* errors, allow the tool and exit 0.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
ALLOWED_EXTS,
|
||||
EDIT_COUNT_THRESHOLD,
|
||||
GENERATED_PATH,
|
||||
SENSITIVE_PATH,
|
||||
filterFindings,
|
||||
loadDetector,
|
||||
matchesAnyGlob,
|
||||
persistCache,
|
||||
readCache,
|
||||
readConfig,
|
||||
renderTemplate,
|
||||
resolveProjectCwd,
|
||||
truthy,
|
||||
writeAuditLog,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
function done(payload = null) {
|
||||
if (payload) process.stdout.write(JSON.stringify(payload));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
function allow(extra = {}, payload = {}) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
...extra,
|
||||
});
|
||||
return done({ permission: 'allow', ...payload });
|
||||
}
|
||||
|
||||
function deny(message, audit) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
blocked: true,
|
||||
...audit,
|
||||
});
|
||||
return done({
|
||||
permission: 'deny',
|
||||
user_message: message,
|
||||
agent_message: message,
|
||||
});
|
||||
}
|
||||
|
||||
function toolInput(event) {
|
||||
return event?.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
|
||||
}
|
||||
|
||||
function proposedFilePath(event, cwd) {
|
||||
const input = toolInput(event);
|
||||
const raw = input.file_path || input.path || input.target_file || event?.file_path;
|
||||
const candidate = typeof raw === 'string' && raw.trim()
|
||||
? raw
|
||||
: shellWriteDestination(shellCommand(input));
|
||||
if (typeof candidate !== 'string' || !candidate.trim()) return '';
|
||||
return path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
|
||||
}
|
||||
|
||||
function proposedContent(event, cwd, filePath) {
|
||||
const input = toolInput(event);
|
||||
for (const key of ['content', 'streamContent', 'text']) {
|
||||
if (typeof input[key] === 'string') return input[key];
|
||||
}
|
||||
|
||||
const editProjection = projectedEditContent(input, filePath, cwd);
|
||||
if (editProjection !== undefined) return editProjection;
|
||||
|
||||
if (hasFragmentEditContent(input)) {
|
||||
return { skipped: 'fragment-only-edit' };
|
||||
}
|
||||
|
||||
const shellContent = shellHereDocContent(shellCommand(input));
|
||||
if (shellContent) return shellContent;
|
||||
const copiedContent = shellCopiedFileContent(shellCommand(input), cwd);
|
||||
if (copiedContent) return copiedContent;
|
||||
return '';
|
||||
}
|
||||
|
||||
function hasFragmentEditContent(input) {
|
||||
if (!input || typeof input !== 'object') return false;
|
||||
if (typeof input.new_string === 'string' || typeof input.newString === 'string' || typeof input.new_str === 'string' || typeof input.replacement === 'string') {
|
||||
return true;
|
||||
}
|
||||
return Array.isArray(input.edits) && input.edits.some((edit) => edit && typeof edit === 'object');
|
||||
}
|
||||
|
||||
function projectedEditContent(input, filePath, cwd) {
|
||||
if (!filePath) return undefined;
|
||||
const singleOld = firstString(input, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const singleNew = firstString(input, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (singleOld !== undefined || singleNew !== undefined) {
|
||||
if (singleOld === undefined || singleNew === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
const projected = replaceOnce(original, singleOld, singleNew);
|
||||
return projected === null ? { skipped: 'edit-old-string-missing' } : projected;
|
||||
}
|
||||
|
||||
if (!Array.isArray(input.edits)) return undefined;
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
|
||||
let projected = original;
|
||||
for (const edit of input.edits) {
|
||||
if (!edit || typeof edit !== 'object') return { skipped: 'fragment-only-edit' };
|
||||
const oldString = firstString(edit, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const newString = firstString(edit, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (oldString === undefined || newString === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const next = replaceOnce(projected, oldString, newString);
|
||||
if (next === null) return { skipped: 'edit-old-string-missing' };
|
||||
projected = next;
|
||||
}
|
||||
return projected;
|
||||
}
|
||||
|
||||
function firstString(obj, keys) {
|
||||
for (const key of keys) {
|
||||
if (typeof obj?.[key] === 'string') return obj[key];
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function replaceOnce(original, oldString, newString) {
|
||||
if (oldString === '') return null;
|
||||
const index = original.indexOf(oldString);
|
||||
if (index === -1) return null;
|
||||
return `${original.slice(0, index)}${newString}${original.slice(index + oldString.length)}`;
|
||||
}
|
||||
|
||||
function readExistingProjectFile(filePath, cwd) {
|
||||
if (!isInsideProject(filePath, cwd)) return null;
|
||||
if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
|
||||
try {
|
||||
const stat = fs.statSync(filePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return null;
|
||||
return fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function shellCommand(input) {
|
||||
if (typeof input.command === 'string') return input.command;
|
||||
if (input.args && typeof input.args.command === 'string') return input.args.command;
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellRedirectPath(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const match = command.match(/(?:^|[\s;&|])(?:>>?|1>>?)\s*(?:"([^"]+)"|'([^']+)'|([^<>\s]+))/);
|
||||
return (match?.[1] || match?.[2] || match?.[3] || '').trim();
|
||||
}
|
||||
|
||||
function shellWriteDestination(command) {
|
||||
return shellRedirectPath(command) || shellTeeDestination(command) || shellCopyPaths(command)?.dest || '';
|
||||
}
|
||||
|
||||
function shellTeeDestination(command) {
|
||||
const words = shellWords(command);
|
||||
const teeIndex = words.findIndex((word) => path.basename(word) === 'tee');
|
||||
if (teeIndex === -1) return '';
|
||||
for (const word of words.slice(teeIndex + 1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
return word;
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellCopiedFileContent(command, cwd) {
|
||||
const source = shellCopyPaths(command)?.source;
|
||||
if (!source) return '';
|
||||
const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
|
||||
if (!isInsideProject(sourcePath, cwd)) return '';
|
||||
if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
|
||||
try {
|
||||
const stat = fs.statSync(sourcePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return '';
|
||||
return fs.readFileSync(sourcePath, 'utf-8');
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
function shellCopyPaths(command) {
|
||||
const words = shellWords(command);
|
||||
if (words.length < 3 || path.basename(words[0]) !== 'cp') return null;
|
||||
const args = [];
|
||||
for (const word of words.slice(1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
args.push(word);
|
||||
}
|
||||
if (args.length < 2) return null;
|
||||
return { source: args[args.length - 2], dest: args[args.length - 1] };
|
||||
}
|
||||
|
||||
function shellWords(command) {
|
||||
if (!command || typeof command !== 'string') return [];
|
||||
const words = [];
|
||||
const re = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'|([^\s]+)/g;
|
||||
let match;
|
||||
while ((match = re.exec(command))) {
|
||||
words.push((match[1] ?? match[2] ?? match[3] ?? '').replace(/\\(["'])/g, '$1'));
|
||||
}
|
||||
return words;
|
||||
}
|
||||
|
||||
function shellHereDocContent(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const markerMatch = command.match(/<<-?\s*['"]?([A-Za-z0-9_.-]+)['"]?[^\r\n]*\r?\n/);
|
||||
if (!markerMatch) return '';
|
||||
const marker = markerMatch[1];
|
||||
const start = (markerMatch.index || 0) + markerMatch[0].length;
|
||||
const rest = command.slice(start);
|
||||
const endRe = new RegExp(`\\r?\\n${escapeRegExp(marker)}(?:\\r?\\n|$)`);
|
||||
const end = rest.search(endRe);
|
||||
return end >= 0 ? rest.slice(0, end) : '';
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
function relativePath(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
|
||||
return rel.split(path.sep).join('/');
|
||||
} catch {
|
||||
return filePath;
|
||||
}
|
||||
}
|
||||
|
||||
function isInsideProject(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function cursorBlockMessage(findings, filePath, config, cwd) {
|
||||
const rendered = renderTemplate(findings, filePath, config, { cwd });
|
||||
const blocked = rendered.replace(
|
||||
'[impeccable@1] Required design corrections',
|
||||
'[impeccable@1] Impeccable design hook blocked this write before it landed. Required design corrections',
|
||||
);
|
||||
return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
|
||||
}
|
||||
|
||||
function findingSignature(findings) {
|
||||
return findings
|
||||
.map((finding) => `${finding.antipattern || 'unknown'}:${finding.line || 0}`)
|
||||
.sort()
|
||||
.join('|');
|
||||
}
|
||||
|
||||
function bumpCursorDenial(cache, sessionId, filePath, findings) {
|
||||
const session = cache.sessions[sessionId] || { updatedAt: Date.now(), files: {} };
|
||||
cache.sessions[sessionId] = session;
|
||||
session.updatedAt = Date.now();
|
||||
const fileEntry = session.files[filePath] || { editCount: 0, findings: [] };
|
||||
session.files[filePath] = fileEntry;
|
||||
const key = findingSignature(findings);
|
||||
fileEntry.cursorDenials = fileEntry.cursorDenials && typeof fileEntry.cursorDenials === 'object'
|
||||
? fileEntry.cursorDenials
|
||||
: {};
|
||||
fileEntry.cursorDenials[key] = (fileEntry.cursorDenials[key] || 0) + 1;
|
||||
return { key, count: fileEntry.cursorDenials[key] };
|
||||
}
|
||||
|
||||
async function main() {
|
||||
if (truthy(process.env.IMPECCABLE_HOOK_DISABLED)) {
|
||||
return allow({ skipped: 'env-disabled' });
|
||||
}
|
||||
|
||||
let event = null;
|
||||
try {
|
||||
const raw = await readStdin();
|
||||
if (raw) event = JSON.parse(raw);
|
||||
} catch {
|
||||
return allow({ skipped: 'stdin-malformed' });
|
||||
}
|
||||
|
||||
if (!event || typeof event !== 'object') {
|
||||
return allow({ skipped: 'stdin-empty' });
|
||||
}
|
||||
|
||||
const cwd = resolveProjectCwd(event);
|
||||
const started = Date.now();
|
||||
const filePath = proposedFilePath(event, cwd);
|
||||
const audit = {
|
||||
harness: 'cursor',
|
||||
tool: event.tool_name || null,
|
||||
file: filePath || null,
|
||||
};
|
||||
|
||||
if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
|
||||
if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
|
||||
if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
|
||||
if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
|
||||
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
audit.ext = ext;
|
||||
if (!ALLOWED_EXTS.has(ext)) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
|
||||
|
||||
const contentResult = proposedContent(event, cwd, filePath);
|
||||
if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
|
||||
return allow({ ...audit, skipped: contentResult.skipped, durationMs: Date.now() - started });
|
||||
}
|
||||
const content = typeof contentResult === 'string' ? contentResult : '';
|
||||
if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
|
||||
|
||||
const config = readConfig(cwd);
|
||||
if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
|
||||
|
||||
const rel = relativePath(filePath, cwd);
|
||||
if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
|
||||
return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const detector = await loadDetector();
|
||||
if (!detector || typeof detector.detectText !== 'function') {
|
||||
return allow({ ...audit, skipped: 'detector-missing', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
let findings = [];
|
||||
try {
|
||||
findings = await detector.detectText(content, filePath);
|
||||
} catch {
|
||||
return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const filtered = filterFindings(findings || [], content, ext, config);
|
||||
if (filtered.length === 0) {
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: 0,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
const message = cursorBlockMessage(filtered, filePath, config, cwd);
|
||||
const sessionId = event.session_id || event.conversation_id || 'unknown';
|
||||
const cache = readCache(cwd);
|
||||
const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
|
||||
persistCache(cwd, cache);
|
||||
if (denial.count > EDIT_COUNT_THRESHOLD) {
|
||||
const warning = `${message}\n\nThis is the ${denial.count}th repeated denial for the same file and finding signature, so Impeccable is allowing this write to avoid a loop. Reconsider the issue immediately after the tool runs.`;
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
downgraded: true,
|
||||
chars: warning.length,
|
||||
durationMs: Date.now() - started,
|
||||
}, {
|
||||
user_message: warning,
|
||||
agent_message: warning,
|
||||
});
|
||||
}
|
||||
return deny(message, {
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
chars: message.length,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook-before-edit] ${err}\n`);
|
||||
}
|
||||
done({ permission: 'allow' });
|
||||
});
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — PostToolUse entry point.
|
||||
*
|
||||
* Reads the Claude Code / Codex / Cursor hook event from stdin, runs the design
|
||||
* detector against the touched file, and emits a system reminder via
|
||||
* `hookSpecificOutput.additionalContext` when findings exist.
|
||||
*
|
||||
* Contract: never break a turn. Always exit 0. Clean files emit a small ack
|
||||
* unless quiet mode is enabled.
|
||||
*
|
||||
* Most logic lives in `hook-lib.mjs` so it is unit-testable without a
|
||||
* subprocess. This file is the thin stdin/stdout adapter.
|
||||
*/
|
||||
|
||||
import { runHook, writeAuditLog } from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
async function main() {
|
||||
// Snapshot the inherited env FIRST so the re-entrancy guard checks the
|
||||
// parent's value, not the value we are about to export for any child
|
||||
// processes the hook might ever spawn.
|
||||
const inheritedEnv = { ...process.env };
|
||||
process.env.IMPECCABLE_HOOK_DEPTH = process.env.IMPECCABLE_HOOK_DEPTH || '1';
|
||||
|
||||
let stdinJson = '';
|
||||
try { stdinJson = await readStdin(); } catch { /* fall through */ }
|
||||
|
||||
const result = await runHook({
|
||||
stdinJson,
|
||||
env: inheritedEnv,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
|
||||
writeAuditLog(process.env, result.audit);
|
||||
|
||||
if (result.stdout) process.stdout.write(result.stdout);
|
||||
process.exit(result.exitCode || 0);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
// Last-ditch: never break the agent's turn even if something we did not
|
||||
// anticipate goes wrong. Audit-log the failure if logging is enabled.
|
||||
try {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'PostToolUse',
|
||||
error: String(err && err.message ? err.message : err),
|
||||
});
|
||||
} catch { /* swallow */ }
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook] ${err}\n`);
|
||||
}
|
||||
process.exit(0);
|
||||
});
|
||||
@@ -32,6 +32,8 @@ const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.cache.json',
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/hook.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
|
||||
@@ -124,7 +124,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
|
||||
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
|
||||
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
|
||||
|
||||
Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
|
||||
Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
|
||||
|
||||
### Routing rules
|
||||
|
||||
@@ -141,7 +141,7 @@ Plus two management commands: `pin <command>` and `unpin <command>`, detailed be
|
||||
**If `scan.targets` is non-empty, run `node .pi/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
|
||||
|
||||
Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
|
||||
2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
|
||||
4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
|
||||
|
||||
@@ -159,4 +159,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
|
||||
node .pi/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
|
||||
```
|
||||
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
|
||||
## Hooks
|
||||
|
||||
`/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `/impeccable hooks` with any argument.
|
||||
@@ -0,0 +1,82 @@
|
||||
# /impeccable hooks
|
||||
|
||||
Manage the **design detector hook** for the current project.
|
||||
|
||||
The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code and Codex use `PostToolUse` and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless `IMPECCABLE_HOOK_QUIET=1` is set. Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
|
||||
|
||||
This command toggles the hook **per project** by editing `.impeccable/hook.json`. Local-only ignore policy lives in `.impeccable/hook.local.json`, which is gitignored. To disable globally, set `IMPECCABLE_HOOK_DISABLED=1` in your shell environment.
|
||||
|
||||
Supported harnesses: Claude Code (`.claude/settings.json` in the project), Codex (`.codex/hooks.json` in the project), and Cursor (`.cursor/hooks.json` in the project).
|
||||
|
||||
On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
|
||||
|
||||
## Routing
|
||||
|
||||
The first argument is the action. Defaults to `status`.
|
||||
|
||||
| Action | What it does |
|
||||
|---|---|
|
||||
| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
|
||||
| `on` | Set `enabled: true` in `.impeccable/hook.json`. |
|
||||
| `off` | Set `enabled: false` in `.impeccable/hook.json`. |
|
||||
| `ignore-rule <id>` | Append `<id>` to `ignoreRules`; for `overused-font`, requires `--all-values`. |
|
||||
| `ignore-file <glob>` | Append `<glob>` to `ignoreFiles`. |
|
||||
| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/hook.json`. |
|
||||
| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/hook.local.json`. |
|
||||
| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
|
||||
|
||||
## Flow
|
||||
|
||||
1. Resolve the action from the user's argument. If no action was given, default to `status`.
|
||||
2. Invoke the admin script and pass the user's output through verbatim:
|
||||
|
||||
```bash
|
||||
node .pi/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
|
||||
```
|
||||
|
||||
3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/impeccable hooks on`."
|
||||
4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
|
||||
5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/hook.json`; add `--local` only when the user explicitly asks for a private exception.
|
||||
6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
|
||||
|
||||
## Intentional findings
|
||||
|
||||
The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
|
||||
|
||||
Prefer the narrowest exception:
|
||||
|
||||
- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/hook.json` by default.
|
||||
- For `overused-font`, use `ignore-value` when the user confirms a specific font. Do not use `ignore-rule overused-font` for a specific font.
|
||||
- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
|
||||
- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
|
||||
- Do not add source comments such as `impeccable: ignore`; inline comments pollute code and are not a supported suppression mechanism.
|
||||
|
||||
Example value-specific exception:
|
||||
|
||||
```bash
|
||||
node .pi/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
|
||||
```
|
||||
|
||||
Example whole-rule font exception:
|
||||
|
||||
```bash
|
||||
node .pi/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
|
||||
```
|
||||
|
||||
Example file-scoped exception:
|
||||
|
||||
```bash
|
||||
node .pi/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Never modify `.impeccable/hook.json` or `.impeccable/hook.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent.
|
||||
- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
|
||||
- Cursor can block a proposed write when the detector finds a real issue. Claude Code and Codex do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
|
||||
- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.json`, `.codex/hooks.json`, and `.cursor/hooks.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- If `.impeccable/hook.json` or `.impeccable/hook.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
|
||||
- If the user asks to "disable the hook" globally, suggest both options: `IMPECCABLE_HOOK_DISABLED=1` env var (one-shot, follows the shell), and `/impeccable hooks off` (persistent for this project, committable).
|
||||
@@ -446,7 +446,7 @@ function detectText(content, filePath, options = {}) {
|
||||
|
||||
// Run regex matchers on the full file content (catches Tailwind classes, inline styles)
|
||||
// Enable block context for CSS files where related properties span multiple lines
|
||||
const cssLike = new Set(['.css', '.scss', '.less']);
|
||||
const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
|
||||
findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
|
||||
profile,
|
||||
phase: 'source',
|
||||
|
||||
@@ -11,7 +11,7 @@ const SKIP_DIRS = new Set([
|
||||
]);
|
||||
|
||||
const SCANNABLE_EXTENSIONS = new Set([
|
||||
'.html', '.htm', '.css', '.scss', '.less',
|
||||
'.html', '.htm', '.css', '.scss', '.sass', '.less',
|
||||
'.jsx', '.tsx', '.js', '.ts',
|
||||
'.vue', '.svelte', '.astro',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,300 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* `/impeccable hooks <on|off|status|reset>` — manage the design hook
|
||||
* via .impeccable/hook.json and .impeccable/hook.local.json in the current
|
||||
* project.
|
||||
*
|
||||
* Usage:
|
||||
* node hook-admin.mjs status # print current state
|
||||
* node hook-admin.mjs on # set enabled: true
|
||||
* node hook-admin.mjs off # set enabled: false
|
||||
* node hook-admin.mjs ignore-rule <rule-id> # append to ignoreRules
|
||||
* node hook-admin.mjs ignore-rule overused-font --all-values
|
||||
* node hook-admin.mjs ignore-file <glob> # append to ignoreFiles
|
||||
* node hook-admin.mjs ignore-value <rule> <value> # append to shared ignoreValues
|
||||
* node hook-admin.mjs ignore-value <rule> <value> --local
|
||||
* node hook-admin.mjs reset # remove all config + cache
|
||||
*
|
||||
* Designed to be invoked by the LLM from the reference/hooks.md flow.
|
||||
* Output is human-readable; the harness will pass it back to the user.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
getConfigPath,
|
||||
getLocalConfigPath,
|
||||
getCachePath,
|
||||
getPendingPath,
|
||||
readConfig,
|
||||
DEFAULT_CONFIG,
|
||||
ensureHookGitExcludes,
|
||||
normalizeIgnoreValue,
|
||||
normalizeIgnoreValueEntries,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
|
||||
|
||||
function readRawConfigFile(filePath) {
|
||||
if (!fs.existsSync(filePath)) return { exists: false, malformed: false, raw: null };
|
||||
try {
|
||||
return { exists: true, malformed: false, raw: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
|
||||
} catch {
|
||||
return { exists: true, malformed: true, raw: null };
|
||||
}
|
||||
}
|
||||
|
||||
function readRawConfig(cwd, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
return readRawConfigFile(filePath).raw;
|
||||
}
|
||||
|
||||
function writeConfig(cwd, config, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
if (opts.local) ensureHookGitExcludes(cwd);
|
||||
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
||||
fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
function mergeConfig(existing) {
|
||||
// Persist the full shape so /impeccable hooks edits leave a complete file
|
||||
// for the user to see, not an unhelpful `{"enabled":false}`.
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
return {
|
||||
enabled: base.enabled === false ? false : true,
|
||||
ignoreRules: Array.isArray(base.ignoreRules) ? Array.from(new Set(base.ignoreRules.map(String))) : [],
|
||||
ignoreFiles: Array.isArray(base.ignoreFiles) ? Array.from(new Set(base.ignoreFiles.map(String))) : [],
|
||||
ignoreValues: normalizeIgnoreValueEntries(base.ignoreValues || []),
|
||||
limits: {
|
||||
maxFindings: Number.isFinite(base?.limits?.maxFindings) ? base.limits.maxFindings : DEFAULT_CONFIG.limits.maxFindings,
|
||||
maxChars: Number.isFinite(base?.limits?.maxChars) ? base.limits.maxChars : DEFAULT_CONFIG.limits.maxChars,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function mergeLocalConfig(existing) {
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
const out = {};
|
||||
if (Object.prototype.hasOwnProperty.call(base, 'enabled')) {
|
||||
out.enabled = base.enabled === false ? false : true;
|
||||
}
|
||||
if (Array.isArray(base.ignoreRules)) {
|
||||
out.ignoreRules = Array.from(new Set(base.ignoreRules.map(String)));
|
||||
}
|
||||
if (Array.isArray(base.ignoreFiles)) {
|
||||
out.ignoreFiles = Array.from(new Set(base.ignoreFiles.map(String)));
|
||||
}
|
||||
out.ignoreValues = normalizeIgnoreValueEntries(base.ignoreValues || []);
|
||||
if (base.limits && typeof base.limits === 'object') {
|
||||
const limits = {};
|
||||
if (Number.isFinite(base.limits.maxFindings)) limits.maxFindings = base.limits.maxFindings;
|
||||
if (Number.isFinite(base.limits.maxChars)) limits.maxChars = base.limits.maxChars;
|
||||
if (Object.keys(limits).length) out.limits = limits;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function statusReport(cwd) {
|
||||
const shared = readRawConfigFile(getConfigPath(cwd));
|
||||
const local = readRawConfigFile(getLocalConfigPath(cwd));
|
||||
const cfg = readConfig(cwd);
|
||||
const envKill = process.env.IMPECCABLE_HOOK_DISABLED;
|
||||
const envState = envKill ? `IMPECCABLE_HOOK_DISABLED=${envKill}` : 'unset';
|
||||
const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.impeccable/hook.json';
|
||||
const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.impeccable/hook.local.json';
|
||||
const cachePath = path.relative(cwd, getCachePath(cwd)) || '.impeccable/hook.cache.json';
|
||||
const fileState = (info, relPath, absent) => {
|
||||
if (info.malformed) return `${relPath} (malformed; ignored)`;
|
||||
if (info.exists) return relPath;
|
||||
return `${relPath} (${absent})`;
|
||||
};
|
||||
const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
|
||||
|
||||
const lines = [
|
||||
`Impeccable design hook`,
|
||||
` state: ${cfg.enabled ? 'enabled' : 'disabled'}`,
|
||||
` shared file: ${fileState(shared, cfgPath, 'using defaults; file not present')}`,
|
||||
` local file: ${fileState(local, localPath, 'not present')}`,
|
||||
` ignoreRules: ${cfg.ignoreRules.length ? cfg.ignoreRules.join(', ') : '(none)'}`,
|
||||
` ignoreFiles: ${cfg.ignoreFiles.length ? cfg.ignoreFiles.join(', ') : '(none)'}`,
|
||||
` ignoreValues: ${ignoreValues.length ? ignoreValues.join(', ') : '(none)'}`,
|
||||
` maxFindings: ${cfg.limits.maxFindings}`,
|
||||
` maxChars: ${cfg.limits.maxChars}`,
|
||||
` env override: ${envState}`,
|
||||
` cache file: ${fs.existsSync(getCachePath(cwd)) ? cachePath : `${cachePath} (not present)`}`,
|
||||
];
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function setEnabled(cwd, value) {
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
config.enabled = value;
|
||||
const target = writeConfig(cwd, config);
|
||||
return `Design hook ${value ? 'enabled' : 'disabled'} for this project (wrote ${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function normalizeRuleId(rule) {
|
||||
return String(rule || '').trim().toLowerCase();
|
||||
}
|
||||
|
||||
function parseIgnoreRuleArgs(args) {
|
||||
const positionals = [];
|
||||
let allValues = false;
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = String(args[i] || '');
|
||||
if (arg === '--all-values') {
|
||||
allValues = true;
|
||||
} else if (arg === '--reason') {
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
|
||||
} else if (arg.startsWith('--reason=')) {
|
||||
// Accepted for command symmetry; ignoreRules stores rule ids only.
|
||||
} else if (arg.startsWith('--')) {
|
||||
throw new Error(`Unknown ignore-rule flag: ${arg}`);
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rule: normalizeRuleId(positionals[0]),
|
||||
allValues,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreRule(cwd, args) {
|
||||
const parsed = parseIgnoreRuleArgs(args);
|
||||
const rule = parsed.rule;
|
||||
if (!rule) throw new Error('Pass a rule id, e.g. /impeccable hooks ignore-rule side-tab');
|
||||
if (rule === 'overused-font' && !parsed.allValues) {
|
||||
throw new Error('overused-font is value-specific by default. Use /impeccable hooks ignore-value overused-font <font> for a confirmed font, or /impeccable hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.');
|
||||
}
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${rule}" to ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
|
||||
}
|
||||
|
||||
function addIgnoreFile(cwd, glob) {
|
||||
if (!glob) throw new Error('Pass a glob, e.g. /impeccable hooks ignore-file "src/legacy/**"');
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${glob}" to ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
|
||||
}
|
||||
|
||||
function parseIgnoreValueArgs(args) {
|
||||
const positionals = [];
|
||||
let shared = false;
|
||||
let local = false;
|
||||
let reason = '';
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = args[i];
|
||||
if (arg === '--shared') {
|
||||
shared = true;
|
||||
} else if (arg === '--local') {
|
||||
local = true;
|
||||
} else if (arg === '--reason') {
|
||||
const chunks = [];
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) {
|
||||
chunks.push(args[++i]);
|
||||
}
|
||||
reason = chunks.join(' ').trim();
|
||||
} else if (String(arg).startsWith('--reason=')) {
|
||||
reason = String(arg).slice('--reason='.length).trim();
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
const [rule, ...valueParts] = positionals;
|
||||
return {
|
||||
rule: String(rule || '').trim().toLowerCase(),
|
||||
value: normalizeIgnoreValue(valueParts.join(' ')),
|
||||
shared,
|
||||
local,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreValue(cwd, args) {
|
||||
const parsed = parseIgnoreValueArgs(args);
|
||||
if (!parsed.rule || !parsed.value) {
|
||||
throw new Error('Pass a rule id and value, e.g. /impeccable hooks ignore-value overused-font Inter');
|
||||
}
|
||||
|
||||
if (parsed.shared && parsed.local) {
|
||||
throw new Error('Pass only one scope flag: --shared or --local');
|
||||
}
|
||||
|
||||
const local = parsed.local;
|
||||
const config = local
|
||||
? mergeLocalConfig(readRawConfig(cwd, { local: true }))
|
||||
: mergeConfig(readRawConfig(cwd, { local: false }));
|
||||
const key = `${parsed.rule}\0${parsed.value}`;
|
||||
const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
|
||||
|
||||
if (existing) {
|
||||
if (parsed.reason) existing.reason = parsed.reason;
|
||||
} else {
|
||||
const entry = {
|
||||
rule: parsed.rule,
|
||||
value: parsed.value,
|
||||
createdAt: new Date().toISOString(),
|
||||
};
|
||||
if (parsed.reason) entry.reason = parsed.reason;
|
||||
config.ignoreValues.push(entry);
|
||||
}
|
||||
|
||||
const target = writeConfig(cwd, config, { local });
|
||||
const scope = local ? 'local ignoreValues' : 'shared ignoreValues';
|
||||
return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function reset(cwd) {
|
||||
const removed = [];
|
||||
for (const filePath of [getConfigPath(cwd), getLocalConfigPath(cwd), getCachePath(cwd), getPendingPath(cwd)]) {
|
||||
try {
|
||||
if (fs.existsSync(filePath)) {
|
||||
fs.unlinkSync(filePath);
|
||||
removed.push(path.relative(cwd, filePath) || filePath);
|
||||
}
|
||||
} catch { /* ignore */ }
|
||||
}
|
||||
return removed.length
|
||||
? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
|
||||
: 'No hook config or cache to remove. Already at defaults.';
|
||||
}
|
||||
|
||||
function main() {
|
||||
const [, , actionArg, ...rest] = process.argv;
|
||||
const action = (actionArg || 'status').toLowerCase();
|
||||
const cwd = process.cwd();
|
||||
|
||||
if (!ACTIONS.has(action)) {
|
||||
process.stderr.write(`Unknown action: ${action}\nValid: ${Array.from(ACTIONS).join(', ')}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
let out = '';
|
||||
switch (action) {
|
||||
case 'status': out = statusReport(cwd); break;
|
||||
case 'on': out = setEnabled(cwd, true); break;
|
||||
case 'off': out = setEnabled(cwd, false); break;
|
||||
case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
|
||||
case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
|
||||
case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
|
||||
case 'reset': out = reset(cwd); break;
|
||||
}
|
||||
process.stdout.write(out + '\n');
|
||||
} catch (err) {
|
||||
process.stderr.write(`Error: ${err.message || err}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,408 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — Cursor preToolUse write gate.
|
||||
*
|
||||
* Cursor's stop hook is not consistently dispatched by the headless agent, so
|
||||
* this hook checks proposed Write/Edit content before it lands. It only denies
|
||||
* writes when the real detector finds an issue in the proposed UI content.
|
||||
*
|
||||
* Contract: never break a turn accidentally. On malformed input or internal
|
||||
* errors, allow the tool and exit 0.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
ALLOWED_EXTS,
|
||||
EDIT_COUNT_THRESHOLD,
|
||||
GENERATED_PATH,
|
||||
SENSITIVE_PATH,
|
||||
filterFindings,
|
||||
loadDetector,
|
||||
matchesAnyGlob,
|
||||
persistCache,
|
||||
readCache,
|
||||
readConfig,
|
||||
renderTemplate,
|
||||
resolveProjectCwd,
|
||||
truthy,
|
||||
writeAuditLog,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
function done(payload = null) {
|
||||
if (payload) process.stdout.write(JSON.stringify(payload));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
function allow(extra = {}, payload = {}) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
...extra,
|
||||
});
|
||||
return done({ permission: 'allow', ...payload });
|
||||
}
|
||||
|
||||
function deny(message, audit) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
blocked: true,
|
||||
...audit,
|
||||
});
|
||||
return done({
|
||||
permission: 'deny',
|
||||
user_message: message,
|
||||
agent_message: message,
|
||||
});
|
||||
}
|
||||
|
||||
function toolInput(event) {
|
||||
return event?.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
|
||||
}
|
||||
|
||||
function proposedFilePath(event, cwd) {
|
||||
const input = toolInput(event);
|
||||
const raw = input.file_path || input.path || input.target_file || event?.file_path;
|
||||
const candidate = typeof raw === 'string' && raw.trim()
|
||||
? raw
|
||||
: shellWriteDestination(shellCommand(input));
|
||||
if (typeof candidate !== 'string' || !candidate.trim()) return '';
|
||||
return path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
|
||||
}
|
||||
|
||||
function proposedContent(event, cwd, filePath) {
|
||||
const input = toolInput(event);
|
||||
for (const key of ['content', 'streamContent', 'text']) {
|
||||
if (typeof input[key] === 'string') return input[key];
|
||||
}
|
||||
|
||||
const editProjection = projectedEditContent(input, filePath, cwd);
|
||||
if (editProjection !== undefined) return editProjection;
|
||||
|
||||
if (hasFragmentEditContent(input)) {
|
||||
return { skipped: 'fragment-only-edit' };
|
||||
}
|
||||
|
||||
const shellContent = shellHereDocContent(shellCommand(input));
|
||||
if (shellContent) return shellContent;
|
||||
const copiedContent = shellCopiedFileContent(shellCommand(input), cwd);
|
||||
if (copiedContent) return copiedContent;
|
||||
return '';
|
||||
}
|
||||
|
||||
function hasFragmentEditContent(input) {
|
||||
if (!input || typeof input !== 'object') return false;
|
||||
if (typeof input.new_string === 'string' || typeof input.newString === 'string' || typeof input.new_str === 'string' || typeof input.replacement === 'string') {
|
||||
return true;
|
||||
}
|
||||
return Array.isArray(input.edits) && input.edits.some((edit) => edit && typeof edit === 'object');
|
||||
}
|
||||
|
||||
function projectedEditContent(input, filePath, cwd) {
|
||||
if (!filePath) return undefined;
|
||||
const singleOld = firstString(input, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const singleNew = firstString(input, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (singleOld !== undefined || singleNew !== undefined) {
|
||||
if (singleOld === undefined || singleNew === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
const projected = replaceOnce(original, singleOld, singleNew);
|
||||
return projected === null ? { skipped: 'edit-old-string-missing' } : projected;
|
||||
}
|
||||
|
||||
if (!Array.isArray(input.edits)) return undefined;
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
|
||||
let projected = original;
|
||||
for (const edit of input.edits) {
|
||||
if (!edit || typeof edit !== 'object') return { skipped: 'fragment-only-edit' };
|
||||
const oldString = firstString(edit, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const newString = firstString(edit, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (oldString === undefined || newString === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const next = replaceOnce(projected, oldString, newString);
|
||||
if (next === null) return { skipped: 'edit-old-string-missing' };
|
||||
projected = next;
|
||||
}
|
||||
return projected;
|
||||
}
|
||||
|
||||
function firstString(obj, keys) {
|
||||
for (const key of keys) {
|
||||
if (typeof obj?.[key] === 'string') return obj[key];
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function replaceOnce(original, oldString, newString) {
|
||||
if (oldString === '') return null;
|
||||
const index = original.indexOf(oldString);
|
||||
if (index === -1) return null;
|
||||
return `${original.slice(0, index)}${newString}${original.slice(index + oldString.length)}`;
|
||||
}
|
||||
|
||||
function readExistingProjectFile(filePath, cwd) {
|
||||
if (!isInsideProject(filePath, cwd)) return null;
|
||||
if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
|
||||
try {
|
||||
const stat = fs.statSync(filePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return null;
|
||||
return fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function shellCommand(input) {
|
||||
if (typeof input.command === 'string') return input.command;
|
||||
if (input.args && typeof input.args.command === 'string') return input.args.command;
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellRedirectPath(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const match = command.match(/(?:^|[\s;&|])(?:>>?|1>>?)\s*(?:"([^"]+)"|'([^']+)'|([^<>\s]+))/);
|
||||
return (match?.[1] || match?.[2] || match?.[3] || '').trim();
|
||||
}
|
||||
|
||||
function shellWriteDestination(command) {
|
||||
return shellRedirectPath(command) || shellTeeDestination(command) || shellCopyPaths(command)?.dest || '';
|
||||
}
|
||||
|
||||
function shellTeeDestination(command) {
|
||||
const words = shellWords(command);
|
||||
const teeIndex = words.findIndex((word) => path.basename(word) === 'tee');
|
||||
if (teeIndex === -1) return '';
|
||||
for (const word of words.slice(teeIndex + 1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
return word;
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellCopiedFileContent(command, cwd) {
|
||||
const source = shellCopyPaths(command)?.source;
|
||||
if (!source) return '';
|
||||
const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
|
||||
if (!isInsideProject(sourcePath, cwd)) return '';
|
||||
if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
|
||||
try {
|
||||
const stat = fs.statSync(sourcePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return '';
|
||||
return fs.readFileSync(sourcePath, 'utf-8');
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
function shellCopyPaths(command) {
|
||||
const words = shellWords(command);
|
||||
if (words.length < 3 || path.basename(words[0]) !== 'cp') return null;
|
||||
const args = [];
|
||||
for (const word of words.slice(1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
args.push(word);
|
||||
}
|
||||
if (args.length < 2) return null;
|
||||
return { source: args[args.length - 2], dest: args[args.length - 1] };
|
||||
}
|
||||
|
||||
function shellWords(command) {
|
||||
if (!command || typeof command !== 'string') return [];
|
||||
const words = [];
|
||||
const re = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'|([^\s]+)/g;
|
||||
let match;
|
||||
while ((match = re.exec(command))) {
|
||||
words.push((match[1] ?? match[2] ?? match[3] ?? '').replace(/\\(["'])/g, '$1'));
|
||||
}
|
||||
return words;
|
||||
}
|
||||
|
||||
function shellHereDocContent(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const markerMatch = command.match(/<<-?\s*['"]?([A-Za-z0-9_.-]+)['"]?[^\r\n]*\r?\n/);
|
||||
if (!markerMatch) return '';
|
||||
const marker = markerMatch[1];
|
||||
const start = (markerMatch.index || 0) + markerMatch[0].length;
|
||||
const rest = command.slice(start);
|
||||
const endRe = new RegExp(`\\r?\\n${escapeRegExp(marker)}(?:\\r?\\n|$)`);
|
||||
const end = rest.search(endRe);
|
||||
return end >= 0 ? rest.slice(0, end) : '';
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
function relativePath(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
|
||||
return rel.split(path.sep).join('/');
|
||||
} catch {
|
||||
return filePath;
|
||||
}
|
||||
}
|
||||
|
||||
function isInsideProject(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function cursorBlockMessage(findings, filePath, config, cwd) {
|
||||
const rendered = renderTemplate(findings, filePath, config, { cwd });
|
||||
const blocked = rendered.replace(
|
||||
'[impeccable@1] Required design corrections',
|
||||
'[impeccable@1] Impeccable design hook blocked this write before it landed. Required design corrections',
|
||||
);
|
||||
return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
|
||||
}
|
||||
|
||||
function findingSignature(findings) {
|
||||
return findings
|
||||
.map((finding) => `${finding.antipattern || 'unknown'}:${finding.line || 0}`)
|
||||
.sort()
|
||||
.join('|');
|
||||
}
|
||||
|
||||
function bumpCursorDenial(cache, sessionId, filePath, findings) {
|
||||
const session = cache.sessions[sessionId] || { updatedAt: Date.now(), files: {} };
|
||||
cache.sessions[sessionId] = session;
|
||||
session.updatedAt = Date.now();
|
||||
const fileEntry = session.files[filePath] || { editCount: 0, findings: [] };
|
||||
session.files[filePath] = fileEntry;
|
||||
const key = findingSignature(findings);
|
||||
fileEntry.cursorDenials = fileEntry.cursorDenials && typeof fileEntry.cursorDenials === 'object'
|
||||
? fileEntry.cursorDenials
|
||||
: {};
|
||||
fileEntry.cursorDenials[key] = (fileEntry.cursorDenials[key] || 0) + 1;
|
||||
return { key, count: fileEntry.cursorDenials[key] };
|
||||
}
|
||||
|
||||
async function main() {
|
||||
if (truthy(process.env.IMPECCABLE_HOOK_DISABLED)) {
|
||||
return allow({ skipped: 'env-disabled' });
|
||||
}
|
||||
|
||||
let event = null;
|
||||
try {
|
||||
const raw = await readStdin();
|
||||
if (raw) event = JSON.parse(raw);
|
||||
} catch {
|
||||
return allow({ skipped: 'stdin-malformed' });
|
||||
}
|
||||
|
||||
if (!event || typeof event !== 'object') {
|
||||
return allow({ skipped: 'stdin-empty' });
|
||||
}
|
||||
|
||||
const cwd = resolveProjectCwd(event);
|
||||
const started = Date.now();
|
||||
const filePath = proposedFilePath(event, cwd);
|
||||
const audit = {
|
||||
harness: 'cursor',
|
||||
tool: event.tool_name || null,
|
||||
file: filePath || null,
|
||||
};
|
||||
|
||||
if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
|
||||
if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
|
||||
if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
|
||||
if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
|
||||
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
audit.ext = ext;
|
||||
if (!ALLOWED_EXTS.has(ext)) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
|
||||
|
||||
const contentResult = proposedContent(event, cwd, filePath);
|
||||
if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
|
||||
return allow({ ...audit, skipped: contentResult.skipped, durationMs: Date.now() - started });
|
||||
}
|
||||
const content = typeof contentResult === 'string' ? contentResult : '';
|
||||
if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
|
||||
|
||||
const config = readConfig(cwd);
|
||||
if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
|
||||
|
||||
const rel = relativePath(filePath, cwd);
|
||||
if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
|
||||
return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const detector = await loadDetector();
|
||||
if (!detector || typeof detector.detectText !== 'function') {
|
||||
return allow({ ...audit, skipped: 'detector-missing', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
let findings = [];
|
||||
try {
|
||||
findings = await detector.detectText(content, filePath);
|
||||
} catch {
|
||||
return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const filtered = filterFindings(findings || [], content, ext, config);
|
||||
if (filtered.length === 0) {
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: 0,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
const message = cursorBlockMessage(filtered, filePath, config, cwd);
|
||||
const sessionId = event.session_id || event.conversation_id || 'unknown';
|
||||
const cache = readCache(cwd);
|
||||
const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
|
||||
persistCache(cwd, cache);
|
||||
if (denial.count > EDIT_COUNT_THRESHOLD) {
|
||||
const warning = `${message}\n\nThis is the ${denial.count}th repeated denial for the same file and finding signature, so Impeccable is allowing this write to avoid a loop. Reconsider the issue immediately after the tool runs.`;
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
downgraded: true,
|
||||
chars: warning.length,
|
||||
durationMs: Date.now() - started,
|
||||
}, {
|
||||
user_message: warning,
|
||||
agent_message: warning,
|
||||
});
|
||||
}
|
||||
return deny(message, {
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
chars: message.length,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook-before-edit] ${err}\n`);
|
||||
}
|
||||
done({ permission: 'allow' });
|
||||
});
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — PostToolUse entry point.
|
||||
*
|
||||
* Reads the Claude Code / Codex / Cursor hook event from stdin, runs the design
|
||||
* detector against the touched file, and emits a system reminder via
|
||||
* `hookSpecificOutput.additionalContext` when findings exist.
|
||||
*
|
||||
* Contract: never break a turn. Always exit 0. Clean files emit a small ack
|
||||
* unless quiet mode is enabled.
|
||||
*
|
||||
* Most logic lives in `hook-lib.mjs` so it is unit-testable without a
|
||||
* subprocess. This file is the thin stdin/stdout adapter.
|
||||
*/
|
||||
|
||||
import { runHook, writeAuditLog } from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
async function main() {
|
||||
// Snapshot the inherited env FIRST so the re-entrancy guard checks the
|
||||
// parent's value, not the value we are about to export for any child
|
||||
// processes the hook might ever spawn.
|
||||
const inheritedEnv = { ...process.env };
|
||||
process.env.IMPECCABLE_HOOK_DEPTH = process.env.IMPECCABLE_HOOK_DEPTH || '1';
|
||||
|
||||
let stdinJson = '';
|
||||
try { stdinJson = await readStdin(); } catch { /* fall through */ }
|
||||
|
||||
const result = await runHook({
|
||||
stdinJson,
|
||||
env: inheritedEnv,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
|
||||
writeAuditLog(process.env, result.audit);
|
||||
|
||||
if (result.stdout) process.stdout.write(result.stdout);
|
||||
process.exit(result.exitCode || 0);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
// Last-ditch: never break the agent's turn even if something we did not
|
||||
// anticipate goes wrong. Audit-log the failure if logging is enabled.
|
||||
try {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'PostToolUse',
|
||||
error: String(err && err.message ? err.message : err),
|
||||
});
|
||||
} catch { /* swallow */ }
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook] ${err}\n`);
|
||||
}
|
||||
process.exit(0);
|
||||
});
|
||||
@@ -32,6 +32,8 @@ const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.cache.json',
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/hook.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
|
||||
@@ -126,7 +126,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
|
||||
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
|
||||
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
|
||||
|
||||
Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
|
||||
Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
|
||||
|
||||
### Routing rules
|
||||
|
||||
@@ -143,7 +143,7 @@ Plus two management commands: `pin <command>` and `unpin <command>`, detailed be
|
||||
**If `scan.targets` is non-empty, run `node .qoder/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
|
||||
|
||||
Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
|
||||
2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
|
||||
4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
|
||||
|
||||
@@ -161,4 +161,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
|
||||
node .qoder/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
|
||||
```
|
||||
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
|
||||
## Hooks
|
||||
|
||||
`/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `/impeccable hooks` with any argument.
|
||||
@@ -0,0 +1,82 @@
|
||||
# /impeccable hooks
|
||||
|
||||
Manage the **design detector hook** for the current project.
|
||||
|
||||
The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code and Codex use `PostToolUse` and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless `IMPECCABLE_HOOK_QUIET=1` is set. Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
|
||||
|
||||
This command toggles the hook **per project** by editing `.impeccable/hook.json`. Local-only ignore policy lives in `.impeccable/hook.local.json`, which is gitignored. To disable globally, set `IMPECCABLE_HOOK_DISABLED=1` in your shell environment.
|
||||
|
||||
Supported harnesses: Claude Code (`.claude/settings.json` in the project), Codex (`.codex/hooks.json` in the project), and Cursor (`.cursor/hooks.json` in the project).
|
||||
|
||||
On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
|
||||
|
||||
## Routing
|
||||
|
||||
The first argument is the action. Defaults to `status`.
|
||||
|
||||
| Action | What it does |
|
||||
|---|---|
|
||||
| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
|
||||
| `on` | Set `enabled: true` in `.impeccable/hook.json`. |
|
||||
| `off` | Set `enabled: false` in `.impeccable/hook.json`. |
|
||||
| `ignore-rule <id>` | Append `<id>` to `ignoreRules`; for `overused-font`, requires `--all-values`. |
|
||||
| `ignore-file <glob>` | Append `<glob>` to `ignoreFiles`. |
|
||||
| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/hook.json`. |
|
||||
| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/hook.local.json`. |
|
||||
| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
|
||||
|
||||
## Flow
|
||||
|
||||
1. Resolve the action from the user's argument. If no action was given, default to `status`.
|
||||
2. Invoke the admin script and pass the user's output through verbatim:
|
||||
|
||||
```bash
|
||||
node .qoder/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
|
||||
```
|
||||
|
||||
3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/impeccable hooks on`."
|
||||
4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
|
||||
5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/hook.json`; add `--local` only when the user explicitly asks for a private exception.
|
||||
6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
|
||||
|
||||
## Intentional findings
|
||||
|
||||
The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
|
||||
|
||||
Prefer the narrowest exception:
|
||||
|
||||
- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/hook.json` by default.
|
||||
- For `overused-font`, use `ignore-value` when the user confirms a specific font. Do not use `ignore-rule overused-font` for a specific font.
|
||||
- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
|
||||
- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
|
||||
- Do not add source comments such as `impeccable: ignore`; inline comments pollute code and are not a supported suppression mechanism.
|
||||
|
||||
Example value-specific exception:
|
||||
|
||||
```bash
|
||||
node .qoder/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
|
||||
```
|
||||
|
||||
Example whole-rule font exception:
|
||||
|
||||
```bash
|
||||
node .qoder/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
|
||||
```
|
||||
|
||||
Example file-scoped exception:
|
||||
|
||||
```bash
|
||||
node .qoder/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Never modify `.impeccable/hook.json` or `.impeccable/hook.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent.
|
||||
- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
|
||||
- Cursor can block a proposed write when the detector finds a real issue. Claude Code and Codex do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
|
||||
- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.json`, `.codex/hooks.json`, and `.cursor/hooks.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- If `.impeccable/hook.json` or `.impeccable/hook.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
|
||||
- If the user asks to "disable the hook" globally, suggest both options: `IMPECCABLE_HOOK_DISABLED=1` env var (one-shot, follows the shell), and `/impeccable hooks off` (persistent for this project, committable).
|
||||
@@ -446,7 +446,7 @@ function detectText(content, filePath, options = {}) {
|
||||
|
||||
// Run regex matchers on the full file content (catches Tailwind classes, inline styles)
|
||||
// Enable block context for CSS files where related properties span multiple lines
|
||||
const cssLike = new Set(['.css', '.scss', '.less']);
|
||||
const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
|
||||
findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
|
||||
profile,
|
||||
phase: 'source',
|
||||
|
||||
@@ -11,7 +11,7 @@ const SKIP_DIRS = new Set([
|
||||
]);
|
||||
|
||||
const SCANNABLE_EXTENSIONS = new Set([
|
||||
'.html', '.htm', '.css', '.scss', '.less',
|
||||
'.html', '.htm', '.css', '.scss', '.sass', '.less',
|
||||
'.jsx', '.tsx', '.js', '.ts',
|
||||
'.vue', '.svelte', '.astro',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,300 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* `/impeccable hooks <on|off|status|reset>` — manage the design hook
|
||||
* via .impeccable/hook.json and .impeccable/hook.local.json in the current
|
||||
* project.
|
||||
*
|
||||
* Usage:
|
||||
* node hook-admin.mjs status # print current state
|
||||
* node hook-admin.mjs on # set enabled: true
|
||||
* node hook-admin.mjs off # set enabled: false
|
||||
* node hook-admin.mjs ignore-rule <rule-id> # append to ignoreRules
|
||||
* node hook-admin.mjs ignore-rule overused-font --all-values
|
||||
* node hook-admin.mjs ignore-file <glob> # append to ignoreFiles
|
||||
* node hook-admin.mjs ignore-value <rule> <value> # append to shared ignoreValues
|
||||
* node hook-admin.mjs ignore-value <rule> <value> --local
|
||||
* node hook-admin.mjs reset # remove all config + cache
|
||||
*
|
||||
* Designed to be invoked by the LLM from the reference/hooks.md flow.
|
||||
* Output is human-readable; the harness will pass it back to the user.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
getConfigPath,
|
||||
getLocalConfigPath,
|
||||
getCachePath,
|
||||
getPendingPath,
|
||||
readConfig,
|
||||
DEFAULT_CONFIG,
|
||||
ensureHookGitExcludes,
|
||||
normalizeIgnoreValue,
|
||||
normalizeIgnoreValueEntries,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
|
||||
|
||||
function readRawConfigFile(filePath) {
|
||||
if (!fs.existsSync(filePath)) return { exists: false, malformed: false, raw: null };
|
||||
try {
|
||||
return { exists: true, malformed: false, raw: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
|
||||
} catch {
|
||||
return { exists: true, malformed: true, raw: null };
|
||||
}
|
||||
}
|
||||
|
||||
function readRawConfig(cwd, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
return readRawConfigFile(filePath).raw;
|
||||
}
|
||||
|
||||
function writeConfig(cwd, config, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
if (opts.local) ensureHookGitExcludes(cwd);
|
||||
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
||||
fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
function mergeConfig(existing) {
|
||||
// Persist the full shape so /impeccable hooks edits leave a complete file
|
||||
// for the user to see, not an unhelpful `{"enabled":false}`.
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
return {
|
||||
enabled: base.enabled === false ? false : true,
|
||||
ignoreRules: Array.isArray(base.ignoreRules) ? Array.from(new Set(base.ignoreRules.map(String))) : [],
|
||||
ignoreFiles: Array.isArray(base.ignoreFiles) ? Array.from(new Set(base.ignoreFiles.map(String))) : [],
|
||||
ignoreValues: normalizeIgnoreValueEntries(base.ignoreValues || []),
|
||||
limits: {
|
||||
maxFindings: Number.isFinite(base?.limits?.maxFindings) ? base.limits.maxFindings : DEFAULT_CONFIG.limits.maxFindings,
|
||||
maxChars: Number.isFinite(base?.limits?.maxChars) ? base.limits.maxChars : DEFAULT_CONFIG.limits.maxChars,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function mergeLocalConfig(existing) {
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
const out = {};
|
||||
if (Object.prototype.hasOwnProperty.call(base, 'enabled')) {
|
||||
out.enabled = base.enabled === false ? false : true;
|
||||
}
|
||||
if (Array.isArray(base.ignoreRules)) {
|
||||
out.ignoreRules = Array.from(new Set(base.ignoreRules.map(String)));
|
||||
}
|
||||
if (Array.isArray(base.ignoreFiles)) {
|
||||
out.ignoreFiles = Array.from(new Set(base.ignoreFiles.map(String)));
|
||||
}
|
||||
out.ignoreValues = normalizeIgnoreValueEntries(base.ignoreValues || []);
|
||||
if (base.limits && typeof base.limits === 'object') {
|
||||
const limits = {};
|
||||
if (Number.isFinite(base.limits.maxFindings)) limits.maxFindings = base.limits.maxFindings;
|
||||
if (Number.isFinite(base.limits.maxChars)) limits.maxChars = base.limits.maxChars;
|
||||
if (Object.keys(limits).length) out.limits = limits;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function statusReport(cwd) {
|
||||
const shared = readRawConfigFile(getConfigPath(cwd));
|
||||
const local = readRawConfigFile(getLocalConfigPath(cwd));
|
||||
const cfg = readConfig(cwd);
|
||||
const envKill = process.env.IMPECCABLE_HOOK_DISABLED;
|
||||
const envState = envKill ? `IMPECCABLE_HOOK_DISABLED=${envKill}` : 'unset';
|
||||
const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.impeccable/hook.json';
|
||||
const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.impeccable/hook.local.json';
|
||||
const cachePath = path.relative(cwd, getCachePath(cwd)) || '.impeccable/hook.cache.json';
|
||||
const fileState = (info, relPath, absent) => {
|
||||
if (info.malformed) return `${relPath} (malformed; ignored)`;
|
||||
if (info.exists) return relPath;
|
||||
return `${relPath} (${absent})`;
|
||||
};
|
||||
const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
|
||||
|
||||
const lines = [
|
||||
`Impeccable design hook`,
|
||||
` state: ${cfg.enabled ? 'enabled' : 'disabled'}`,
|
||||
` shared file: ${fileState(shared, cfgPath, 'using defaults; file not present')}`,
|
||||
` local file: ${fileState(local, localPath, 'not present')}`,
|
||||
` ignoreRules: ${cfg.ignoreRules.length ? cfg.ignoreRules.join(', ') : '(none)'}`,
|
||||
` ignoreFiles: ${cfg.ignoreFiles.length ? cfg.ignoreFiles.join(', ') : '(none)'}`,
|
||||
` ignoreValues: ${ignoreValues.length ? ignoreValues.join(', ') : '(none)'}`,
|
||||
` maxFindings: ${cfg.limits.maxFindings}`,
|
||||
` maxChars: ${cfg.limits.maxChars}`,
|
||||
` env override: ${envState}`,
|
||||
` cache file: ${fs.existsSync(getCachePath(cwd)) ? cachePath : `${cachePath} (not present)`}`,
|
||||
];
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function setEnabled(cwd, value) {
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
config.enabled = value;
|
||||
const target = writeConfig(cwd, config);
|
||||
return `Design hook ${value ? 'enabled' : 'disabled'} for this project (wrote ${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function normalizeRuleId(rule) {
|
||||
return String(rule || '').trim().toLowerCase();
|
||||
}
|
||||
|
||||
function parseIgnoreRuleArgs(args) {
|
||||
const positionals = [];
|
||||
let allValues = false;
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = String(args[i] || '');
|
||||
if (arg === '--all-values') {
|
||||
allValues = true;
|
||||
} else if (arg === '--reason') {
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
|
||||
} else if (arg.startsWith('--reason=')) {
|
||||
// Accepted for command symmetry; ignoreRules stores rule ids only.
|
||||
} else if (arg.startsWith('--')) {
|
||||
throw new Error(`Unknown ignore-rule flag: ${arg}`);
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rule: normalizeRuleId(positionals[0]),
|
||||
allValues,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreRule(cwd, args) {
|
||||
const parsed = parseIgnoreRuleArgs(args);
|
||||
const rule = parsed.rule;
|
||||
if (!rule) throw new Error('Pass a rule id, e.g. /impeccable hooks ignore-rule side-tab');
|
||||
if (rule === 'overused-font' && !parsed.allValues) {
|
||||
throw new Error('overused-font is value-specific by default. Use /impeccable hooks ignore-value overused-font <font> for a confirmed font, or /impeccable hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.');
|
||||
}
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${rule}" to ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
|
||||
}
|
||||
|
||||
function addIgnoreFile(cwd, glob) {
|
||||
if (!glob) throw new Error('Pass a glob, e.g. /impeccable hooks ignore-file "src/legacy/**"');
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${glob}" to ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
|
||||
}
|
||||
|
||||
function parseIgnoreValueArgs(args) {
|
||||
const positionals = [];
|
||||
let shared = false;
|
||||
let local = false;
|
||||
let reason = '';
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = args[i];
|
||||
if (arg === '--shared') {
|
||||
shared = true;
|
||||
} else if (arg === '--local') {
|
||||
local = true;
|
||||
} else if (arg === '--reason') {
|
||||
const chunks = [];
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) {
|
||||
chunks.push(args[++i]);
|
||||
}
|
||||
reason = chunks.join(' ').trim();
|
||||
} else if (String(arg).startsWith('--reason=')) {
|
||||
reason = String(arg).slice('--reason='.length).trim();
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
const [rule, ...valueParts] = positionals;
|
||||
return {
|
||||
rule: String(rule || '').trim().toLowerCase(),
|
||||
value: normalizeIgnoreValue(valueParts.join(' ')),
|
||||
shared,
|
||||
local,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreValue(cwd, args) {
|
||||
const parsed = parseIgnoreValueArgs(args);
|
||||
if (!parsed.rule || !parsed.value) {
|
||||
throw new Error('Pass a rule id and value, e.g. /impeccable hooks ignore-value overused-font Inter');
|
||||
}
|
||||
|
||||
if (parsed.shared && parsed.local) {
|
||||
throw new Error('Pass only one scope flag: --shared or --local');
|
||||
}
|
||||
|
||||
const local = parsed.local;
|
||||
const config = local
|
||||
? mergeLocalConfig(readRawConfig(cwd, { local: true }))
|
||||
: mergeConfig(readRawConfig(cwd, { local: false }));
|
||||
const key = `${parsed.rule}\0${parsed.value}`;
|
||||
const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
|
||||
|
||||
if (existing) {
|
||||
if (parsed.reason) existing.reason = parsed.reason;
|
||||
} else {
|
||||
const entry = {
|
||||
rule: parsed.rule,
|
||||
value: parsed.value,
|
||||
createdAt: new Date().toISOString(),
|
||||
};
|
||||
if (parsed.reason) entry.reason = parsed.reason;
|
||||
config.ignoreValues.push(entry);
|
||||
}
|
||||
|
||||
const target = writeConfig(cwd, config, { local });
|
||||
const scope = local ? 'local ignoreValues' : 'shared ignoreValues';
|
||||
return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function reset(cwd) {
|
||||
const removed = [];
|
||||
for (const filePath of [getConfigPath(cwd), getLocalConfigPath(cwd), getCachePath(cwd), getPendingPath(cwd)]) {
|
||||
try {
|
||||
if (fs.existsSync(filePath)) {
|
||||
fs.unlinkSync(filePath);
|
||||
removed.push(path.relative(cwd, filePath) || filePath);
|
||||
}
|
||||
} catch { /* ignore */ }
|
||||
}
|
||||
return removed.length
|
||||
? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
|
||||
: 'No hook config or cache to remove. Already at defaults.';
|
||||
}
|
||||
|
||||
function main() {
|
||||
const [, , actionArg, ...rest] = process.argv;
|
||||
const action = (actionArg || 'status').toLowerCase();
|
||||
const cwd = process.cwd();
|
||||
|
||||
if (!ACTIONS.has(action)) {
|
||||
process.stderr.write(`Unknown action: ${action}\nValid: ${Array.from(ACTIONS).join(', ')}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
let out = '';
|
||||
switch (action) {
|
||||
case 'status': out = statusReport(cwd); break;
|
||||
case 'on': out = setEnabled(cwd, true); break;
|
||||
case 'off': out = setEnabled(cwd, false); break;
|
||||
case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
|
||||
case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
|
||||
case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
|
||||
case 'reset': out = reset(cwd); break;
|
||||
}
|
||||
process.stdout.write(out + '\n');
|
||||
} catch (err) {
|
||||
process.stderr.write(`Error: ${err.message || err}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,408 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — Cursor preToolUse write gate.
|
||||
*
|
||||
* Cursor's stop hook is not consistently dispatched by the headless agent, so
|
||||
* this hook checks proposed Write/Edit content before it lands. It only denies
|
||||
* writes when the real detector finds an issue in the proposed UI content.
|
||||
*
|
||||
* Contract: never break a turn accidentally. On malformed input or internal
|
||||
* errors, allow the tool and exit 0.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
ALLOWED_EXTS,
|
||||
EDIT_COUNT_THRESHOLD,
|
||||
GENERATED_PATH,
|
||||
SENSITIVE_PATH,
|
||||
filterFindings,
|
||||
loadDetector,
|
||||
matchesAnyGlob,
|
||||
persistCache,
|
||||
readCache,
|
||||
readConfig,
|
||||
renderTemplate,
|
||||
resolveProjectCwd,
|
||||
truthy,
|
||||
writeAuditLog,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
function done(payload = null) {
|
||||
if (payload) process.stdout.write(JSON.stringify(payload));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
function allow(extra = {}, payload = {}) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
...extra,
|
||||
});
|
||||
return done({ permission: 'allow', ...payload });
|
||||
}
|
||||
|
||||
function deny(message, audit) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
blocked: true,
|
||||
...audit,
|
||||
});
|
||||
return done({
|
||||
permission: 'deny',
|
||||
user_message: message,
|
||||
agent_message: message,
|
||||
});
|
||||
}
|
||||
|
||||
function toolInput(event) {
|
||||
return event?.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
|
||||
}
|
||||
|
||||
function proposedFilePath(event, cwd) {
|
||||
const input = toolInput(event);
|
||||
const raw = input.file_path || input.path || input.target_file || event?.file_path;
|
||||
const candidate = typeof raw === 'string' && raw.trim()
|
||||
? raw
|
||||
: shellWriteDestination(shellCommand(input));
|
||||
if (typeof candidate !== 'string' || !candidate.trim()) return '';
|
||||
return path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
|
||||
}
|
||||
|
||||
function proposedContent(event, cwd, filePath) {
|
||||
const input = toolInput(event);
|
||||
for (const key of ['content', 'streamContent', 'text']) {
|
||||
if (typeof input[key] === 'string') return input[key];
|
||||
}
|
||||
|
||||
const editProjection = projectedEditContent(input, filePath, cwd);
|
||||
if (editProjection !== undefined) return editProjection;
|
||||
|
||||
if (hasFragmentEditContent(input)) {
|
||||
return { skipped: 'fragment-only-edit' };
|
||||
}
|
||||
|
||||
const shellContent = shellHereDocContent(shellCommand(input));
|
||||
if (shellContent) return shellContent;
|
||||
const copiedContent = shellCopiedFileContent(shellCommand(input), cwd);
|
||||
if (copiedContent) return copiedContent;
|
||||
return '';
|
||||
}
|
||||
|
||||
function hasFragmentEditContent(input) {
|
||||
if (!input || typeof input !== 'object') return false;
|
||||
if (typeof input.new_string === 'string' || typeof input.newString === 'string' || typeof input.new_str === 'string' || typeof input.replacement === 'string') {
|
||||
return true;
|
||||
}
|
||||
return Array.isArray(input.edits) && input.edits.some((edit) => edit && typeof edit === 'object');
|
||||
}
|
||||
|
||||
function projectedEditContent(input, filePath, cwd) {
|
||||
if (!filePath) return undefined;
|
||||
const singleOld = firstString(input, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const singleNew = firstString(input, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (singleOld !== undefined || singleNew !== undefined) {
|
||||
if (singleOld === undefined || singleNew === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
const projected = replaceOnce(original, singleOld, singleNew);
|
||||
return projected === null ? { skipped: 'edit-old-string-missing' } : projected;
|
||||
}
|
||||
|
||||
if (!Array.isArray(input.edits)) return undefined;
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
|
||||
let projected = original;
|
||||
for (const edit of input.edits) {
|
||||
if (!edit || typeof edit !== 'object') return { skipped: 'fragment-only-edit' };
|
||||
const oldString = firstString(edit, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const newString = firstString(edit, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (oldString === undefined || newString === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const next = replaceOnce(projected, oldString, newString);
|
||||
if (next === null) return { skipped: 'edit-old-string-missing' };
|
||||
projected = next;
|
||||
}
|
||||
return projected;
|
||||
}
|
||||
|
||||
function firstString(obj, keys) {
|
||||
for (const key of keys) {
|
||||
if (typeof obj?.[key] === 'string') return obj[key];
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function replaceOnce(original, oldString, newString) {
|
||||
if (oldString === '') return null;
|
||||
const index = original.indexOf(oldString);
|
||||
if (index === -1) return null;
|
||||
return `${original.slice(0, index)}${newString}${original.slice(index + oldString.length)}`;
|
||||
}
|
||||
|
||||
function readExistingProjectFile(filePath, cwd) {
|
||||
if (!isInsideProject(filePath, cwd)) return null;
|
||||
if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
|
||||
try {
|
||||
const stat = fs.statSync(filePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return null;
|
||||
return fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function shellCommand(input) {
|
||||
if (typeof input.command === 'string') return input.command;
|
||||
if (input.args && typeof input.args.command === 'string') return input.args.command;
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellRedirectPath(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const match = command.match(/(?:^|[\s;&|])(?:>>?|1>>?)\s*(?:"([^"]+)"|'([^']+)'|([^<>\s]+))/);
|
||||
return (match?.[1] || match?.[2] || match?.[3] || '').trim();
|
||||
}
|
||||
|
||||
function shellWriteDestination(command) {
|
||||
return shellRedirectPath(command) || shellTeeDestination(command) || shellCopyPaths(command)?.dest || '';
|
||||
}
|
||||
|
||||
function shellTeeDestination(command) {
|
||||
const words = shellWords(command);
|
||||
const teeIndex = words.findIndex((word) => path.basename(word) === 'tee');
|
||||
if (teeIndex === -1) return '';
|
||||
for (const word of words.slice(teeIndex + 1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
return word;
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellCopiedFileContent(command, cwd) {
|
||||
const source = shellCopyPaths(command)?.source;
|
||||
if (!source) return '';
|
||||
const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
|
||||
if (!isInsideProject(sourcePath, cwd)) return '';
|
||||
if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
|
||||
try {
|
||||
const stat = fs.statSync(sourcePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return '';
|
||||
return fs.readFileSync(sourcePath, 'utf-8');
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
function shellCopyPaths(command) {
|
||||
const words = shellWords(command);
|
||||
if (words.length < 3 || path.basename(words[0]) !== 'cp') return null;
|
||||
const args = [];
|
||||
for (const word of words.slice(1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
args.push(word);
|
||||
}
|
||||
if (args.length < 2) return null;
|
||||
return { source: args[args.length - 2], dest: args[args.length - 1] };
|
||||
}
|
||||
|
||||
function shellWords(command) {
|
||||
if (!command || typeof command !== 'string') return [];
|
||||
const words = [];
|
||||
const re = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'|([^\s]+)/g;
|
||||
let match;
|
||||
while ((match = re.exec(command))) {
|
||||
words.push((match[1] ?? match[2] ?? match[3] ?? '').replace(/\\(["'])/g, '$1'));
|
||||
}
|
||||
return words;
|
||||
}
|
||||
|
||||
function shellHereDocContent(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const markerMatch = command.match(/<<-?\s*['"]?([A-Za-z0-9_.-]+)['"]?[^\r\n]*\r?\n/);
|
||||
if (!markerMatch) return '';
|
||||
const marker = markerMatch[1];
|
||||
const start = (markerMatch.index || 0) + markerMatch[0].length;
|
||||
const rest = command.slice(start);
|
||||
const endRe = new RegExp(`\\r?\\n${escapeRegExp(marker)}(?:\\r?\\n|$)`);
|
||||
const end = rest.search(endRe);
|
||||
return end >= 0 ? rest.slice(0, end) : '';
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
function relativePath(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
|
||||
return rel.split(path.sep).join('/');
|
||||
} catch {
|
||||
return filePath;
|
||||
}
|
||||
}
|
||||
|
||||
function isInsideProject(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function cursorBlockMessage(findings, filePath, config, cwd) {
|
||||
const rendered = renderTemplate(findings, filePath, config, { cwd });
|
||||
const blocked = rendered.replace(
|
||||
'[impeccable@1] Required design corrections',
|
||||
'[impeccable@1] Impeccable design hook blocked this write before it landed. Required design corrections',
|
||||
);
|
||||
return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
|
||||
}
|
||||
|
||||
function findingSignature(findings) {
|
||||
return findings
|
||||
.map((finding) => `${finding.antipattern || 'unknown'}:${finding.line || 0}`)
|
||||
.sort()
|
||||
.join('|');
|
||||
}
|
||||
|
||||
function bumpCursorDenial(cache, sessionId, filePath, findings) {
|
||||
const session = cache.sessions[sessionId] || { updatedAt: Date.now(), files: {} };
|
||||
cache.sessions[sessionId] = session;
|
||||
session.updatedAt = Date.now();
|
||||
const fileEntry = session.files[filePath] || { editCount: 0, findings: [] };
|
||||
session.files[filePath] = fileEntry;
|
||||
const key = findingSignature(findings);
|
||||
fileEntry.cursorDenials = fileEntry.cursorDenials && typeof fileEntry.cursorDenials === 'object'
|
||||
? fileEntry.cursorDenials
|
||||
: {};
|
||||
fileEntry.cursorDenials[key] = (fileEntry.cursorDenials[key] || 0) + 1;
|
||||
return { key, count: fileEntry.cursorDenials[key] };
|
||||
}
|
||||
|
||||
async function main() {
|
||||
if (truthy(process.env.IMPECCABLE_HOOK_DISABLED)) {
|
||||
return allow({ skipped: 'env-disabled' });
|
||||
}
|
||||
|
||||
let event = null;
|
||||
try {
|
||||
const raw = await readStdin();
|
||||
if (raw) event = JSON.parse(raw);
|
||||
} catch {
|
||||
return allow({ skipped: 'stdin-malformed' });
|
||||
}
|
||||
|
||||
if (!event || typeof event !== 'object') {
|
||||
return allow({ skipped: 'stdin-empty' });
|
||||
}
|
||||
|
||||
const cwd = resolveProjectCwd(event);
|
||||
const started = Date.now();
|
||||
const filePath = proposedFilePath(event, cwd);
|
||||
const audit = {
|
||||
harness: 'cursor',
|
||||
tool: event.tool_name || null,
|
||||
file: filePath || null,
|
||||
};
|
||||
|
||||
if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
|
||||
if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
|
||||
if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
|
||||
if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
|
||||
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
audit.ext = ext;
|
||||
if (!ALLOWED_EXTS.has(ext)) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
|
||||
|
||||
const contentResult = proposedContent(event, cwd, filePath);
|
||||
if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
|
||||
return allow({ ...audit, skipped: contentResult.skipped, durationMs: Date.now() - started });
|
||||
}
|
||||
const content = typeof contentResult === 'string' ? contentResult : '';
|
||||
if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
|
||||
|
||||
const config = readConfig(cwd);
|
||||
if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
|
||||
|
||||
const rel = relativePath(filePath, cwd);
|
||||
if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
|
||||
return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const detector = await loadDetector();
|
||||
if (!detector || typeof detector.detectText !== 'function') {
|
||||
return allow({ ...audit, skipped: 'detector-missing', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
let findings = [];
|
||||
try {
|
||||
findings = await detector.detectText(content, filePath);
|
||||
} catch {
|
||||
return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const filtered = filterFindings(findings || [], content, ext, config);
|
||||
if (filtered.length === 0) {
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: 0,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
const message = cursorBlockMessage(filtered, filePath, config, cwd);
|
||||
const sessionId = event.session_id || event.conversation_id || 'unknown';
|
||||
const cache = readCache(cwd);
|
||||
const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
|
||||
persistCache(cwd, cache);
|
||||
if (denial.count > EDIT_COUNT_THRESHOLD) {
|
||||
const warning = `${message}\n\nThis is the ${denial.count}th repeated denial for the same file and finding signature, so Impeccable is allowing this write to avoid a loop. Reconsider the issue immediately after the tool runs.`;
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
downgraded: true,
|
||||
chars: warning.length,
|
||||
durationMs: Date.now() - started,
|
||||
}, {
|
||||
user_message: warning,
|
||||
agent_message: warning,
|
||||
});
|
||||
}
|
||||
return deny(message, {
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
chars: message.length,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook-before-edit] ${err}\n`);
|
||||
}
|
||||
done({ permission: 'allow' });
|
||||
});
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — PostToolUse entry point.
|
||||
*
|
||||
* Reads the Claude Code / Codex / Cursor hook event from stdin, runs the design
|
||||
* detector against the touched file, and emits a system reminder via
|
||||
* `hookSpecificOutput.additionalContext` when findings exist.
|
||||
*
|
||||
* Contract: never break a turn. Always exit 0. Clean files emit a small ack
|
||||
* unless quiet mode is enabled.
|
||||
*
|
||||
* Most logic lives in `hook-lib.mjs` so it is unit-testable without a
|
||||
* subprocess. This file is the thin stdin/stdout adapter.
|
||||
*/
|
||||
|
||||
import { runHook, writeAuditLog } from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
async function main() {
|
||||
// Snapshot the inherited env FIRST so the re-entrancy guard checks the
|
||||
// parent's value, not the value we are about to export for any child
|
||||
// processes the hook might ever spawn.
|
||||
const inheritedEnv = { ...process.env };
|
||||
process.env.IMPECCABLE_HOOK_DEPTH = process.env.IMPECCABLE_HOOK_DEPTH || '1';
|
||||
|
||||
let stdinJson = '';
|
||||
try { stdinJson = await readStdin(); } catch { /* fall through */ }
|
||||
|
||||
const result = await runHook({
|
||||
stdinJson,
|
||||
env: inheritedEnv,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
|
||||
writeAuditLog(process.env, result.audit);
|
||||
|
||||
if (result.stdout) process.stdout.write(result.stdout);
|
||||
process.exit(result.exitCode || 0);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
// Last-ditch: never break the agent's turn even if something we did not
|
||||
// anticipate goes wrong. Audit-log the failure if logging is enabled.
|
||||
try {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'PostToolUse',
|
||||
error: String(err && err.message ? err.message : err),
|
||||
});
|
||||
} catch { /* swallow */ }
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook] ${err}\n`);
|
||||
}
|
||||
process.exit(0);
|
||||
});
|
||||
@@ -32,6 +32,8 @@ const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.cache.json',
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/hook.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
|
||||
@@ -126,7 +126,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
|
||||
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
|
||||
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
|
||||
|
||||
Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
|
||||
Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
|
||||
|
||||
### Routing rules
|
||||
|
||||
@@ -143,7 +143,7 @@ Plus two management commands: `pin <command>` and `unpin <command>`, detailed be
|
||||
**If `scan.targets` is non-empty, run `node .rovodev/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
|
||||
|
||||
Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
|
||||
2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
|
||||
4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
|
||||
|
||||
@@ -161,4 +161,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
|
||||
node .rovodev/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
|
||||
```
|
||||
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
|
||||
## Hooks
|
||||
|
||||
`/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `/impeccable hooks` with any argument.
|
||||
@@ -0,0 +1,82 @@
|
||||
# /impeccable hooks
|
||||
|
||||
Manage the **design detector hook** for the current project.
|
||||
|
||||
The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code and Codex use `PostToolUse` and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless `IMPECCABLE_HOOK_QUIET=1` is set. Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
|
||||
|
||||
This command toggles the hook **per project** by editing `.impeccable/hook.json`. Local-only ignore policy lives in `.impeccable/hook.local.json`, which is gitignored. To disable globally, set `IMPECCABLE_HOOK_DISABLED=1` in your shell environment.
|
||||
|
||||
Supported harnesses: Claude Code (`.claude/settings.json` in the project), Codex (`.codex/hooks.json` in the project), and Cursor (`.cursor/hooks.json` in the project).
|
||||
|
||||
On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
|
||||
|
||||
## Routing
|
||||
|
||||
The first argument is the action. Defaults to `status`.
|
||||
|
||||
| Action | What it does |
|
||||
|---|---|
|
||||
| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
|
||||
| `on` | Set `enabled: true` in `.impeccable/hook.json`. |
|
||||
| `off` | Set `enabled: false` in `.impeccable/hook.json`. |
|
||||
| `ignore-rule <id>` | Append `<id>` to `ignoreRules`; for `overused-font`, requires `--all-values`. |
|
||||
| `ignore-file <glob>` | Append `<glob>` to `ignoreFiles`. |
|
||||
| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/hook.json`. |
|
||||
| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/hook.local.json`. |
|
||||
| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
|
||||
|
||||
## Flow
|
||||
|
||||
1. Resolve the action from the user's argument. If no action was given, default to `status`.
|
||||
2. Invoke the admin script and pass the user's output through verbatim:
|
||||
|
||||
```bash
|
||||
node .rovodev/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
|
||||
```
|
||||
|
||||
3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/impeccable hooks on`."
|
||||
4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
|
||||
5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/hook.json`; add `--local` only when the user explicitly asks for a private exception.
|
||||
6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
|
||||
|
||||
## Intentional findings
|
||||
|
||||
The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
|
||||
|
||||
Prefer the narrowest exception:
|
||||
|
||||
- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/hook.json` by default.
|
||||
- For `overused-font`, use `ignore-value` when the user confirms a specific font. Do not use `ignore-rule overused-font` for a specific font.
|
||||
- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
|
||||
- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
|
||||
- Do not add source comments such as `impeccable: ignore`; inline comments pollute code and are not a supported suppression mechanism.
|
||||
|
||||
Example value-specific exception:
|
||||
|
||||
```bash
|
||||
node .rovodev/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
|
||||
```
|
||||
|
||||
Example whole-rule font exception:
|
||||
|
||||
```bash
|
||||
node .rovodev/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
|
||||
```
|
||||
|
||||
Example file-scoped exception:
|
||||
|
||||
```bash
|
||||
node .rovodev/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Never modify `.impeccable/hook.json` or `.impeccable/hook.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent.
|
||||
- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
|
||||
- Cursor can block a proposed write when the detector finds a real issue. Claude Code and Codex do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
|
||||
- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.json`, `.codex/hooks.json`, and `.cursor/hooks.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- If `.impeccable/hook.json` or `.impeccable/hook.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
|
||||
- If the user asks to "disable the hook" globally, suggest both options: `IMPECCABLE_HOOK_DISABLED=1` env var (one-shot, follows the shell), and `/impeccable hooks off` (persistent for this project, committable).
|
||||
@@ -446,7 +446,7 @@ function detectText(content, filePath, options = {}) {
|
||||
|
||||
// Run regex matchers on the full file content (catches Tailwind classes, inline styles)
|
||||
// Enable block context for CSS files where related properties span multiple lines
|
||||
const cssLike = new Set(['.css', '.scss', '.less']);
|
||||
const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
|
||||
findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
|
||||
profile,
|
||||
phase: 'source',
|
||||
|
||||
@@ -11,7 +11,7 @@ const SKIP_DIRS = new Set([
|
||||
]);
|
||||
|
||||
const SCANNABLE_EXTENSIONS = new Set([
|
||||
'.html', '.htm', '.css', '.scss', '.less',
|
||||
'.html', '.htm', '.css', '.scss', '.sass', '.less',
|
||||
'.jsx', '.tsx', '.js', '.ts',
|
||||
'.vue', '.svelte', '.astro',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,300 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* `/impeccable hooks <on|off|status|reset>` — manage the design hook
|
||||
* via .impeccable/hook.json and .impeccable/hook.local.json in the current
|
||||
* project.
|
||||
*
|
||||
* Usage:
|
||||
* node hook-admin.mjs status # print current state
|
||||
* node hook-admin.mjs on # set enabled: true
|
||||
* node hook-admin.mjs off # set enabled: false
|
||||
* node hook-admin.mjs ignore-rule <rule-id> # append to ignoreRules
|
||||
* node hook-admin.mjs ignore-rule overused-font --all-values
|
||||
* node hook-admin.mjs ignore-file <glob> # append to ignoreFiles
|
||||
* node hook-admin.mjs ignore-value <rule> <value> # append to shared ignoreValues
|
||||
* node hook-admin.mjs ignore-value <rule> <value> --local
|
||||
* node hook-admin.mjs reset # remove all config + cache
|
||||
*
|
||||
* Designed to be invoked by the LLM from the reference/hooks.md flow.
|
||||
* Output is human-readable; the harness will pass it back to the user.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
getConfigPath,
|
||||
getLocalConfigPath,
|
||||
getCachePath,
|
||||
getPendingPath,
|
||||
readConfig,
|
||||
DEFAULT_CONFIG,
|
||||
ensureHookGitExcludes,
|
||||
normalizeIgnoreValue,
|
||||
normalizeIgnoreValueEntries,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
|
||||
|
||||
function readRawConfigFile(filePath) {
|
||||
if (!fs.existsSync(filePath)) return { exists: false, malformed: false, raw: null };
|
||||
try {
|
||||
return { exists: true, malformed: false, raw: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
|
||||
} catch {
|
||||
return { exists: true, malformed: true, raw: null };
|
||||
}
|
||||
}
|
||||
|
||||
function readRawConfig(cwd, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
return readRawConfigFile(filePath).raw;
|
||||
}
|
||||
|
||||
function writeConfig(cwd, config, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
if (opts.local) ensureHookGitExcludes(cwd);
|
||||
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
||||
fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
function mergeConfig(existing) {
|
||||
// Persist the full shape so /impeccable hooks edits leave a complete file
|
||||
// for the user to see, not an unhelpful `{"enabled":false}`.
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
return {
|
||||
enabled: base.enabled === false ? false : true,
|
||||
ignoreRules: Array.isArray(base.ignoreRules) ? Array.from(new Set(base.ignoreRules.map(String))) : [],
|
||||
ignoreFiles: Array.isArray(base.ignoreFiles) ? Array.from(new Set(base.ignoreFiles.map(String))) : [],
|
||||
ignoreValues: normalizeIgnoreValueEntries(base.ignoreValues || []),
|
||||
limits: {
|
||||
maxFindings: Number.isFinite(base?.limits?.maxFindings) ? base.limits.maxFindings : DEFAULT_CONFIG.limits.maxFindings,
|
||||
maxChars: Number.isFinite(base?.limits?.maxChars) ? base.limits.maxChars : DEFAULT_CONFIG.limits.maxChars,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function mergeLocalConfig(existing) {
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
const out = {};
|
||||
if (Object.prototype.hasOwnProperty.call(base, 'enabled')) {
|
||||
out.enabled = base.enabled === false ? false : true;
|
||||
}
|
||||
if (Array.isArray(base.ignoreRules)) {
|
||||
out.ignoreRules = Array.from(new Set(base.ignoreRules.map(String)));
|
||||
}
|
||||
if (Array.isArray(base.ignoreFiles)) {
|
||||
out.ignoreFiles = Array.from(new Set(base.ignoreFiles.map(String)));
|
||||
}
|
||||
out.ignoreValues = normalizeIgnoreValueEntries(base.ignoreValues || []);
|
||||
if (base.limits && typeof base.limits === 'object') {
|
||||
const limits = {};
|
||||
if (Number.isFinite(base.limits.maxFindings)) limits.maxFindings = base.limits.maxFindings;
|
||||
if (Number.isFinite(base.limits.maxChars)) limits.maxChars = base.limits.maxChars;
|
||||
if (Object.keys(limits).length) out.limits = limits;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function statusReport(cwd) {
|
||||
const shared = readRawConfigFile(getConfigPath(cwd));
|
||||
const local = readRawConfigFile(getLocalConfigPath(cwd));
|
||||
const cfg = readConfig(cwd);
|
||||
const envKill = process.env.IMPECCABLE_HOOK_DISABLED;
|
||||
const envState = envKill ? `IMPECCABLE_HOOK_DISABLED=${envKill}` : 'unset';
|
||||
const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.impeccable/hook.json';
|
||||
const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.impeccable/hook.local.json';
|
||||
const cachePath = path.relative(cwd, getCachePath(cwd)) || '.impeccable/hook.cache.json';
|
||||
const fileState = (info, relPath, absent) => {
|
||||
if (info.malformed) return `${relPath} (malformed; ignored)`;
|
||||
if (info.exists) return relPath;
|
||||
return `${relPath} (${absent})`;
|
||||
};
|
||||
const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
|
||||
|
||||
const lines = [
|
||||
`Impeccable design hook`,
|
||||
` state: ${cfg.enabled ? 'enabled' : 'disabled'}`,
|
||||
` shared file: ${fileState(shared, cfgPath, 'using defaults; file not present')}`,
|
||||
` local file: ${fileState(local, localPath, 'not present')}`,
|
||||
` ignoreRules: ${cfg.ignoreRules.length ? cfg.ignoreRules.join(', ') : '(none)'}`,
|
||||
` ignoreFiles: ${cfg.ignoreFiles.length ? cfg.ignoreFiles.join(', ') : '(none)'}`,
|
||||
` ignoreValues: ${ignoreValues.length ? ignoreValues.join(', ') : '(none)'}`,
|
||||
` maxFindings: ${cfg.limits.maxFindings}`,
|
||||
` maxChars: ${cfg.limits.maxChars}`,
|
||||
` env override: ${envState}`,
|
||||
` cache file: ${fs.existsSync(getCachePath(cwd)) ? cachePath : `${cachePath} (not present)`}`,
|
||||
];
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function setEnabled(cwd, value) {
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
config.enabled = value;
|
||||
const target = writeConfig(cwd, config);
|
||||
return `Design hook ${value ? 'enabled' : 'disabled'} for this project (wrote ${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function normalizeRuleId(rule) {
|
||||
return String(rule || '').trim().toLowerCase();
|
||||
}
|
||||
|
||||
function parseIgnoreRuleArgs(args) {
|
||||
const positionals = [];
|
||||
let allValues = false;
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = String(args[i] || '');
|
||||
if (arg === '--all-values') {
|
||||
allValues = true;
|
||||
} else if (arg === '--reason') {
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
|
||||
} else if (arg.startsWith('--reason=')) {
|
||||
// Accepted for command symmetry; ignoreRules stores rule ids only.
|
||||
} else if (arg.startsWith('--')) {
|
||||
throw new Error(`Unknown ignore-rule flag: ${arg}`);
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rule: normalizeRuleId(positionals[0]),
|
||||
allValues,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreRule(cwd, args) {
|
||||
const parsed = parseIgnoreRuleArgs(args);
|
||||
const rule = parsed.rule;
|
||||
if (!rule) throw new Error('Pass a rule id, e.g. /impeccable hooks ignore-rule side-tab');
|
||||
if (rule === 'overused-font' && !parsed.allValues) {
|
||||
throw new Error('overused-font is value-specific by default. Use /impeccable hooks ignore-value overused-font <font> for a confirmed font, or /impeccable hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.');
|
||||
}
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${rule}" to ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
|
||||
}
|
||||
|
||||
function addIgnoreFile(cwd, glob) {
|
||||
if (!glob) throw new Error('Pass a glob, e.g. /impeccable hooks ignore-file "src/legacy/**"');
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${glob}" to ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
|
||||
}
|
||||
|
||||
function parseIgnoreValueArgs(args) {
|
||||
const positionals = [];
|
||||
let shared = false;
|
||||
let local = false;
|
||||
let reason = '';
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = args[i];
|
||||
if (arg === '--shared') {
|
||||
shared = true;
|
||||
} else if (arg === '--local') {
|
||||
local = true;
|
||||
} else if (arg === '--reason') {
|
||||
const chunks = [];
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) {
|
||||
chunks.push(args[++i]);
|
||||
}
|
||||
reason = chunks.join(' ').trim();
|
||||
} else if (String(arg).startsWith('--reason=')) {
|
||||
reason = String(arg).slice('--reason='.length).trim();
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
const [rule, ...valueParts] = positionals;
|
||||
return {
|
||||
rule: String(rule || '').trim().toLowerCase(),
|
||||
value: normalizeIgnoreValue(valueParts.join(' ')),
|
||||
shared,
|
||||
local,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreValue(cwd, args) {
|
||||
const parsed = parseIgnoreValueArgs(args);
|
||||
if (!parsed.rule || !parsed.value) {
|
||||
throw new Error('Pass a rule id and value, e.g. /impeccable hooks ignore-value overused-font Inter');
|
||||
}
|
||||
|
||||
if (parsed.shared && parsed.local) {
|
||||
throw new Error('Pass only one scope flag: --shared or --local');
|
||||
}
|
||||
|
||||
const local = parsed.local;
|
||||
const config = local
|
||||
? mergeLocalConfig(readRawConfig(cwd, { local: true }))
|
||||
: mergeConfig(readRawConfig(cwd, { local: false }));
|
||||
const key = `${parsed.rule}\0${parsed.value}`;
|
||||
const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
|
||||
|
||||
if (existing) {
|
||||
if (parsed.reason) existing.reason = parsed.reason;
|
||||
} else {
|
||||
const entry = {
|
||||
rule: parsed.rule,
|
||||
value: parsed.value,
|
||||
createdAt: new Date().toISOString(),
|
||||
};
|
||||
if (parsed.reason) entry.reason = parsed.reason;
|
||||
config.ignoreValues.push(entry);
|
||||
}
|
||||
|
||||
const target = writeConfig(cwd, config, { local });
|
||||
const scope = local ? 'local ignoreValues' : 'shared ignoreValues';
|
||||
return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function reset(cwd) {
|
||||
const removed = [];
|
||||
for (const filePath of [getConfigPath(cwd), getLocalConfigPath(cwd), getCachePath(cwd), getPendingPath(cwd)]) {
|
||||
try {
|
||||
if (fs.existsSync(filePath)) {
|
||||
fs.unlinkSync(filePath);
|
||||
removed.push(path.relative(cwd, filePath) || filePath);
|
||||
}
|
||||
} catch { /* ignore */ }
|
||||
}
|
||||
return removed.length
|
||||
? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
|
||||
: 'No hook config or cache to remove. Already at defaults.';
|
||||
}
|
||||
|
||||
function main() {
|
||||
const [, , actionArg, ...rest] = process.argv;
|
||||
const action = (actionArg || 'status').toLowerCase();
|
||||
const cwd = process.cwd();
|
||||
|
||||
if (!ACTIONS.has(action)) {
|
||||
process.stderr.write(`Unknown action: ${action}\nValid: ${Array.from(ACTIONS).join(', ')}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
let out = '';
|
||||
switch (action) {
|
||||
case 'status': out = statusReport(cwd); break;
|
||||
case 'on': out = setEnabled(cwd, true); break;
|
||||
case 'off': out = setEnabled(cwd, false); break;
|
||||
case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
|
||||
case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
|
||||
case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
|
||||
case 'reset': out = reset(cwd); break;
|
||||
}
|
||||
process.stdout.write(out + '\n');
|
||||
} catch (err) {
|
||||
process.stderr.write(`Error: ${err.message || err}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,408 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — Cursor preToolUse write gate.
|
||||
*
|
||||
* Cursor's stop hook is not consistently dispatched by the headless agent, so
|
||||
* this hook checks proposed Write/Edit content before it lands. It only denies
|
||||
* writes when the real detector finds an issue in the proposed UI content.
|
||||
*
|
||||
* Contract: never break a turn accidentally. On malformed input or internal
|
||||
* errors, allow the tool and exit 0.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
ALLOWED_EXTS,
|
||||
EDIT_COUNT_THRESHOLD,
|
||||
GENERATED_PATH,
|
||||
SENSITIVE_PATH,
|
||||
filterFindings,
|
||||
loadDetector,
|
||||
matchesAnyGlob,
|
||||
persistCache,
|
||||
readCache,
|
||||
readConfig,
|
||||
renderTemplate,
|
||||
resolveProjectCwd,
|
||||
truthy,
|
||||
writeAuditLog,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
function done(payload = null) {
|
||||
if (payload) process.stdout.write(JSON.stringify(payload));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
function allow(extra = {}, payload = {}) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
...extra,
|
||||
});
|
||||
return done({ permission: 'allow', ...payload });
|
||||
}
|
||||
|
||||
function deny(message, audit) {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'preToolUse',
|
||||
blocked: true,
|
||||
...audit,
|
||||
});
|
||||
return done({
|
||||
permission: 'deny',
|
||||
user_message: message,
|
||||
agent_message: message,
|
||||
});
|
||||
}
|
||||
|
||||
function toolInput(event) {
|
||||
return event?.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
|
||||
}
|
||||
|
||||
function proposedFilePath(event, cwd) {
|
||||
const input = toolInput(event);
|
||||
const raw = input.file_path || input.path || input.target_file || event?.file_path;
|
||||
const candidate = typeof raw === 'string' && raw.trim()
|
||||
? raw
|
||||
: shellWriteDestination(shellCommand(input));
|
||||
if (typeof candidate !== 'string' || !candidate.trim()) return '';
|
||||
return path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
|
||||
}
|
||||
|
||||
function proposedContent(event, cwd, filePath) {
|
||||
const input = toolInput(event);
|
||||
for (const key of ['content', 'streamContent', 'text']) {
|
||||
if (typeof input[key] === 'string') return input[key];
|
||||
}
|
||||
|
||||
const editProjection = projectedEditContent(input, filePath, cwd);
|
||||
if (editProjection !== undefined) return editProjection;
|
||||
|
||||
if (hasFragmentEditContent(input)) {
|
||||
return { skipped: 'fragment-only-edit' };
|
||||
}
|
||||
|
||||
const shellContent = shellHereDocContent(shellCommand(input));
|
||||
if (shellContent) return shellContent;
|
||||
const copiedContent = shellCopiedFileContent(shellCommand(input), cwd);
|
||||
if (copiedContent) return copiedContent;
|
||||
return '';
|
||||
}
|
||||
|
||||
function hasFragmentEditContent(input) {
|
||||
if (!input || typeof input !== 'object') return false;
|
||||
if (typeof input.new_string === 'string' || typeof input.newString === 'string' || typeof input.new_str === 'string' || typeof input.replacement === 'string') {
|
||||
return true;
|
||||
}
|
||||
return Array.isArray(input.edits) && input.edits.some((edit) => edit && typeof edit === 'object');
|
||||
}
|
||||
|
||||
function projectedEditContent(input, filePath, cwd) {
|
||||
if (!filePath) return undefined;
|
||||
const singleOld = firstString(input, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const singleNew = firstString(input, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (singleOld !== undefined || singleNew !== undefined) {
|
||||
if (singleOld === undefined || singleNew === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
const projected = replaceOnce(original, singleOld, singleNew);
|
||||
return projected === null ? { skipped: 'edit-old-string-missing' } : projected;
|
||||
}
|
||||
|
||||
if (!Array.isArray(input.edits)) return undefined;
|
||||
const original = readExistingProjectFile(filePath, cwd);
|
||||
if (original === null) return { skipped: 'edit-original-unreadable' };
|
||||
|
||||
let projected = original;
|
||||
for (const edit of input.edits) {
|
||||
if (!edit || typeof edit !== 'object') return { skipped: 'fragment-only-edit' };
|
||||
const oldString = firstString(edit, ['old_string', 'oldString', 'old_str', 'target']);
|
||||
const newString = firstString(edit, ['new_string', 'newString', 'new_str', 'replacement']);
|
||||
if (oldString === undefined || newString === undefined) return { skipped: 'fragment-only-edit' };
|
||||
const next = replaceOnce(projected, oldString, newString);
|
||||
if (next === null) return { skipped: 'edit-old-string-missing' };
|
||||
projected = next;
|
||||
}
|
||||
return projected;
|
||||
}
|
||||
|
||||
function firstString(obj, keys) {
|
||||
for (const key of keys) {
|
||||
if (typeof obj?.[key] === 'string') return obj[key];
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function replaceOnce(original, oldString, newString) {
|
||||
if (oldString === '') return null;
|
||||
const index = original.indexOf(oldString);
|
||||
if (index === -1) return null;
|
||||
return `${original.slice(0, index)}${newString}${original.slice(index + oldString.length)}`;
|
||||
}
|
||||
|
||||
function readExistingProjectFile(filePath, cwd) {
|
||||
if (!isInsideProject(filePath, cwd)) return null;
|
||||
if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
|
||||
try {
|
||||
const stat = fs.statSync(filePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return null;
|
||||
return fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function shellCommand(input) {
|
||||
if (typeof input.command === 'string') return input.command;
|
||||
if (input.args && typeof input.args.command === 'string') return input.args.command;
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellRedirectPath(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const match = command.match(/(?:^|[\s;&|])(?:>>?|1>>?)\s*(?:"([^"]+)"|'([^']+)'|([^<>\s]+))/);
|
||||
return (match?.[1] || match?.[2] || match?.[3] || '').trim();
|
||||
}
|
||||
|
||||
function shellWriteDestination(command) {
|
||||
return shellRedirectPath(command) || shellTeeDestination(command) || shellCopyPaths(command)?.dest || '';
|
||||
}
|
||||
|
||||
function shellTeeDestination(command) {
|
||||
const words = shellWords(command);
|
||||
const teeIndex = words.findIndex((word) => path.basename(word) === 'tee');
|
||||
if (teeIndex === -1) return '';
|
||||
for (const word of words.slice(teeIndex + 1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
return word;
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
function shellCopiedFileContent(command, cwd) {
|
||||
const source = shellCopyPaths(command)?.source;
|
||||
if (!source) return '';
|
||||
const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
|
||||
if (!isInsideProject(sourcePath, cwd)) return '';
|
||||
if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
|
||||
try {
|
||||
const stat = fs.statSync(sourcePath);
|
||||
if (!stat.isFile() || stat.size > 1024 * 1024) return '';
|
||||
return fs.readFileSync(sourcePath, 'utf-8');
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
function shellCopyPaths(command) {
|
||||
const words = shellWords(command);
|
||||
if (words.length < 3 || path.basename(words[0]) !== 'cp') return null;
|
||||
const args = [];
|
||||
for (const word of words.slice(1)) {
|
||||
if (['&&', '||', ';', '|'].includes(word)) break;
|
||||
if (word === '--') continue;
|
||||
if (word.startsWith('-')) continue;
|
||||
args.push(word);
|
||||
}
|
||||
if (args.length < 2) return null;
|
||||
return { source: args[args.length - 2], dest: args[args.length - 1] };
|
||||
}
|
||||
|
||||
function shellWords(command) {
|
||||
if (!command || typeof command !== 'string') return [];
|
||||
const words = [];
|
||||
const re = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'|([^\s]+)/g;
|
||||
let match;
|
||||
while ((match = re.exec(command))) {
|
||||
words.push((match[1] ?? match[2] ?? match[3] ?? '').replace(/\\(["'])/g, '$1'));
|
||||
}
|
||||
return words;
|
||||
}
|
||||
|
||||
function shellHereDocContent(command) {
|
||||
if (!command || typeof command !== 'string') return '';
|
||||
const markerMatch = command.match(/<<-?\s*['"]?([A-Za-z0-9_.-]+)['"]?[^\r\n]*\r?\n/);
|
||||
if (!markerMatch) return '';
|
||||
const marker = markerMatch[1];
|
||||
const start = (markerMatch.index || 0) + markerMatch[0].length;
|
||||
const rest = command.slice(start);
|
||||
const endRe = new RegExp(`\\r?\\n${escapeRegExp(marker)}(?:\\r?\\n|$)`);
|
||||
const end = rest.search(endRe);
|
||||
return end >= 0 ? rest.slice(0, end) : '';
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
function relativePath(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
|
||||
return rel.split(path.sep).join('/');
|
||||
} catch {
|
||||
return filePath;
|
||||
}
|
||||
}
|
||||
|
||||
function isInsideProject(filePath, cwd) {
|
||||
try {
|
||||
const rel = path.relative(cwd, filePath);
|
||||
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function cursorBlockMessage(findings, filePath, config, cwd) {
|
||||
const rendered = renderTemplate(findings, filePath, config, { cwd });
|
||||
const blocked = rendered.replace(
|
||||
'[impeccable@1] Required design corrections',
|
||||
'[impeccable@1] Impeccable design hook blocked this write before it landed. Required design corrections',
|
||||
);
|
||||
return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
|
||||
}
|
||||
|
||||
function findingSignature(findings) {
|
||||
return findings
|
||||
.map((finding) => `${finding.antipattern || 'unknown'}:${finding.line || 0}`)
|
||||
.sort()
|
||||
.join('|');
|
||||
}
|
||||
|
||||
function bumpCursorDenial(cache, sessionId, filePath, findings) {
|
||||
const session = cache.sessions[sessionId] || { updatedAt: Date.now(), files: {} };
|
||||
cache.sessions[sessionId] = session;
|
||||
session.updatedAt = Date.now();
|
||||
const fileEntry = session.files[filePath] || { editCount: 0, findings: [] };
|
||||
session.files[filePath] = fileEntry;
|
||||
const key = findingSignature(findings);
|
||||
fileEntry.cursorDenials = fileEntry.cursorDenials && typeof fileEntry.cursorDenials === 'object'
|
||||
? fileEntry.cursorDenials
|
||||
: {};
|
||||
fileEntry.cursorDenials[key] = (fileEntry.cursorDenials[key] || 0) + 1;
|
||||
return { key, count: fileEntry.cursorDenials[key] };
|
||||
}
|
||||
|
||||
async function main() {
|
||||
if (truthy(process.env.IMPECCABLE_HOOK_DISABLED)) {
|
||||
return allow({ skipped: 'env-disabled' });
|
||||
}
|
||||
|
||||
let event = null;
|
||||
try {
|
||||
const raw = await readStdin();
|
||||
if (raw) event = JSON.parse(raw);
|
||||
} catch {
|
||||
return allow({ skipped: 'stdin-malformed' });
|
||||
}
|
||||
|
||||
if (!event || typeof event !== 'object') {
|
||||
return allow({ skipped: 'stdin-empty' });
|
||||
}
|
||||
|
||||
const cwd = resolveProjectCwd(event);
|
||||
const started = Date.now();
|
||||
const filePath = proposedFilePath(event, cwd);
|
||||
const audit = {
|
||||
harness: 'cursor',
|
||||
tool: event.tool_name || null,
|
||||
file: filePath || null,
|
||||
};
|
||||
|
||||
if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
|
||||
if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
|
||||
if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
|
||||
if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
|
||||
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
audit.ext = ext;
|
||||
if (!ALLOWED_EXTS.has(ext)) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
|
||||
|
||||
const contentResult = proposedContent(event, cwd, filePath);
|
||||
if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
|
||||
return allow({ ...audit, skipped: contentResult.skipped, durationMs: Date.now() - started });
|
||||
}
|
||||
const content = typeof contentResult === 'string' ? contentResult : '';
|
||||
if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
|
||||
|
||||
const config = readConfig(cwd);
|
||||
if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
|
||||
|
||||
const rel = relativePath(filePath, cwd);
|
||||
if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
|
||||
return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const detector = await loadDetector();
|
||||
if (!detector || typeof detector.detectText !== 'function') {
|
||||
return allow({ ...audit, skipped: 'detector-missing', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
let findings = [];
|
||||
try {
|
||||
findings = await detector.detectText(content, filePath);
|
||||
} catch {
|
||||
return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
const filtered = filterFindings(findings || [], content, ext, config);
|
||||
if (filtered.length === 0) {
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: 0,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
const message = cursorBlockMessage(filtered, filePath, config, cwd);
|
||||
const sessionId = event.session_id || event.conversation_id || 'unknown';
|
||||
const cache = readCache(cwd);
|
||||
const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
|
||||
persistCache(cwd, cache);
|
||||
if (denial.count > EDIT_COUNT_THRESHOLD) {
|
||||
const warning = `${message}\n\nThis is the ${denial.count}th repeated denial for the same file and finding signature, so Impeccable is allowing this write to avoid a loop. Reconsider the issue immediately after the tool runs.`;
|
||||
return allow({
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
downgraded: true,
|
||||
chars: warning.length,
|
||||
durationMs: Date.now() - started,
|
||||
}, {
|
||||
user_message: warning,
|
||||
agent_message: warning,
|
||||
});
|
||||
}
|
||||
return deny(message, {
|
||||
...audit,
|
||||
findings: (findings || []).length,
|
||||
blockedFindings: filtered.length,
|
||||
cursorDenialKey: denial.key,
|
||||
cursorDenialCount: denial.count,
|
||||
chars: message.length,
|
||||
durationMs: Date.now() - started,
|
||||
});
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook-before-edit] ${err}\n`);
|
||||
}
|
||||
done({ permission: 'allow' });
|
||||
});
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Impeccable design hook — PostToolUse entry point.
|
||||
*
|
||||
* Reads the Claude Code / Codex / Cursor hook event from stdin, runs the design
|
||||
* detector against the touched file, and emits a system reminder via
|
||||
* `hookSpecificOutput.additionalContext` when findings exist.
|
||||
*
|
||||
* Contract: never break a turn. Always exit 0. Clean files emit a small ack
|
||||
* unless quiet mode is enabled.
|
||||
*
|
||||
* Most logic lives in `hook-lib.mjs` so it is unit-testable without a
|
||||
* subprocess. This file is the thin stdin/stdout adapter.
|
||||
*/
|
||||
|
||||
import { runHook, writeAuditLog } from './hook-lib.mjs';
|
||||
|
||||
async function readStdin() {
|
||||
if (process.stdin.isTTY) return '';
|
||||
const chunks = [];
|
||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
||||
return Buffer.concat(chunks).toString('utf-8');
|
||||
}
|
||||
|
||||
async function main() {
|
||||
// Snapshot the inherited env FIRST so the re-entrancy guard checks the
|
||||
// parent's value, not the value we are about to export for any child
|
||||
// processes the hook might ever spawn.
|
||||
const inheritedEnv = { ...process.env };
|
||||
process.env.IMPECCABLE_HOOK_DEPTH = process.env.IMPECCABLE_HOOK_DEPTH || '1';
|
||||
|
||||
let stdinJson = '';
|
||||
try { stdinJson = await readStdin(); } catch { /* fall through */ }
|
||||
|
||||
const result = await runHook({
|
||||
stdinJson,
|
||||
env: inheritedEnv,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
|
||||
writeAuditLog(process.env, result.audit);
|
||||
|
||||
if (result.stdout) process.stdout.write(result.stdout);
|
||||
process.exit(result.exitCode || 0);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
// Last-ditch: never break the agent's turn even if something we did not
|
||||
// anticipate goes wrong. Audit-log the failure if logging is enabled.
|
||||
try {
|
||||
writeAuditLog(process.env, {
|
||||
ts: new Date().toISOString(),
|
||||
event: 'PostToolUse',
|
||||
error: String(err && err.message ? err.message : err),
|
||||
});
|
||||
} catch { /* swallow */ }
|
||||
if (process.env.IMPECCABLE_HOOK_DEBUG) {
|
||||
process.stderr.write(`[impeccable-hook] ${err}\n`);
|
||||
}
|
||||
process.exit(0);
|
||||
});
|
||||
@@ -32,6 +32,8 @@ const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.cache.json',
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/hook.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
|
||||
@@ -124,7 +124,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
|
||||
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
|
||||
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
|
||||
|
||||
Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
|
||||
Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
|
||||
|
||||
### Routing rules
|
||||
|
||||
@@ -141,7 +141,7 @@ Plus two management commands: `pin <command>` and `unpin <command>`, detailed be
|
||||
**If `scan.targets` is non-empty, run `node .trae-cn/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
|
||||
|
||||
Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
|
||||
2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
|
||||
3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
|
||||
4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
|
||||
|
||||
@@ -159,4 +159,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
|
||||
node .trae-cn/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
|
||||
```
|
||||
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
|
||||
|
||||
## Hooks
|
||||
|
||||
`/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `/impeccable hooks` with any argument.
|
||||
@@ -0,0 +1,82 @@
|
||||
# /impeccable hooks
|
||||
|
||||
Manage the **design detector hook** for the current project.
|
||||
|
||||
The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code and Codex use `PostToolUse` and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless `IMPECCABLE_HOOK_QUIET=1` is set. Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
|
||||
|
||||
This command toggles the hook **per project** by editing `.impeccable/hook.json`. Local-only ignore policy lives in `.impeccable/hook.local.json`, which is gitignored. To disable globally, set `IMPECCABLE_HOOK_DISABLED=1` in your shell environment.
|
||||
|
||||
Supported harnesses: Claude Code (`.claude/settings.json` in the project), Codex (`.codex/hooks.json` in the project), and Cursor (`.cursor/hooks.json` in the project).
|
||||
|
||||
On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
|
||||
|
||||
## Routing
|
||||
|
||||
The first argument is the action. Defaults to `status`.
|
||||
|
||||
| Action | What it does |
|
||||
|---|---|
|
||||
| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
|
||||
| `on` | Set `enabled: true` in `.impeccable/hook.json`. |
|
||||
| `off` | Set `enabled: false` in `.impeccable/hook.json`. |
|
||||
| `ignore-rule <id>` | Append `<id>` to `ignoreRules`; for `overused-font`, requires `--all-values`. |
|
||||
| `ignore-file <glob>` | Append `<glob>` to `ignoreFiles`. |
|
||||
| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/hook.json`. |
|
||||
| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/hook.local.json`. |
|
||||
| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
|
||||
|
||||
## Flow
|
||||
|
||||
1. Resolve the action from the user's argument. If no action was given, default to `status`.
|
||||
2. Invoke the admin script and pass the user's output through verbatim:
|
||||
|
||||
```bash
|
||||
node .trae-cn/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
|
||||
```
|
||||
|
||||
3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/impeccable hooks on`."
|
||||
4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
|
||||
5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/hook.json`; add `--local` only when the user explicitly asks for a private exception.
|
||||
6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
|
||||
|
||||
## Intentional findings
|
||||
|
||||
The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
|
||||
|
||||
Prefer the narrowest exception:
|
||||
|
||||
- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/hook.json` by default.
|
||||
- For `overused-font`, use `ignore-value` when the user confirms a specific font. Do not use `ignore-rule overused-font` for a specific font.
|
||||
- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
|
||||
- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
|
||||
- Do not add source comments such as `impeccable: ignore`; inline comments pollute code and are not a supported suppression mechanism.
|
||||
|
||||
Example value-specific exception:
|
||||
|
||||
```bash
|
||||
node .trae-cn/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
|
||||
```
|
||||
|
||||
Example whole-rule font exception:
|
||||
|
||||
```bash
|
||||
node .trae-cn/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
|
||||
```
|
||||
|
||||
Example file-scoped exception:
|
||||
|
||||
```bash
|
||||
node .trae-cn/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Never modify `.impeccable/hook.json` or `.impeccable/hook.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent.
|
||||
- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
|
||||
- Cursor can block a proposed write when the detector finds a real issue. Claude Code and Codex do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
|
||||
- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.json`, `.codex/hooks.json`, and `.cursor/hooks.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- If `.impeccable/hook.json` or `.impeccable/hook.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
|
||||
- If the user asks to "disable the hook" globally, suggest both options: `IMPECCABLE_HOOK_DISABLED=1` env var (one-shot, follows the shell), and `/impeccable hooks off` (persistent for this project, committable).
|
||||
@@ -446,7 +446,7 @@ function detectText(content, filePath, options = {}) {
|
||||
|
||||
// Run regex matchers on the full file content (catches Tailwind classes, inline styles)
|
||||
// Enable block context for CSS files where related properties span multiple lines
|
||||
const cssLike = new Set(['.css', '.scss', '.less']);
|
||||
const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
|
||||
findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
|
||||
profile,
|
||||
phase: 'source',
|
||||
|
||||
@@ -11,7 +11,7 @@ const SKIP_DIRS = new Set([
|
||||
]);
|
||||
|
||||
const SCANNABLE_EXTENSIONS = new Set([
|
||||
'.html', '.htm', '.css', '.scss', '.less',
|
||||
'.html', '.htm', '.css', '.scss', '.sass', '.less',
|
||||
'.jsx', '.tsx', '.js', '.ts',
|
||||
'.vue', '.svelte', '.astro',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,300 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* `/impeccable hooks <on|off|status|reset>` — manage the design hook
|
||||
* via .impeccable/hook.json and .impeccable/hook.local.json in the current
|
||||
* project.
|
||||
*
|
||||
* Usage:
|
||||
* node hook-admin.mjs status # print current state
|
||||
* node hook-admin.mjs on # set enabled: true
|
||||
* node hook-admin.mjs off # set enabled: false
|
||||
* node hook-admin.mjs ignore-rule <rule-id> # append to ignoreRules
|
||||
* node hook-admin.mjs ignore-rule overused-font --all-values
|
||||
* node hook-admin.mjs ignore-file <glob> # append to ignoreFiles
|
||||
* node hook-admin.mjs ignore-value <rule> <value> # append to shared ignoreValues
|
||||
* node hook-admin.mjs ignore-value <rule> <value> --local
|
||||
* node hook-admin.mjs reset # remove all config + cache
|
||||
*
|
||||
* Designed to be invoked by the LLM from the reference/hooks.md flow.
|
||||
* Output is human-readable; the harness will pass it back to the user.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
getConfigPath,
|
||||
getLocalConfigPath,
|
||||
getCachePath,
|
||||
getPendingPath,
|
||||
readConfig,
|
||||
DEFAULT_CONFIG,
|
||||
ensureHookGitExcludes,
|
||||
normalizeIgnoreValue,
|
||||
normalizeIgnoreValueEntries,
|
||||
} from './hook-lib.mjs';
|
||||
|
||||
const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
|
||||
|
||||
function readRawConfigFile(filePath) {
|
||||
if (!fs.existsSync(filePath)) return { exists: false, malformed: false, raw: null };
|
||||
try {
|
||||
return { exists: true, malformed: false, raw: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
|
||||
} catch {
|
||||
return { exists: true, malformed: true, raw: null };
|
||||
}
|
||||
}
|
||||
|
||||
function readRawConfig(cwd, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
return readRawConfigFile(filePath).raw;
|
||||
}
|
||||
|
||||
function writeConfig(cwd, config, opts = {}) {
|
||||
const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
|
||||
if (opts.local) ensureHookGitExcludes(cwd);
|
||||
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
||||
fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
|
||||
return filePath;
|
||||
}
|
||||
|
||||
function mergeConfig(existing) {
|
||||
// Persist the full shape so /impeccable hooks edits leave a complete file
|
||||
// for the user to see, not an unhelpful `{"enabled":false}`.
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
return {
|
||||
enabled: base.enabled === false ? false : true,
|
||||
ignoreRules: Array.isArray(base.ignoreRules) ? Array.from(new Set(base.ignoreRules.map(String))) : [],
|
||||
ignoreFiles: Array.isArray(base.ignoreFiles) ? Array.from(new Set(base.ignoreFiles.map(String))) : [],
|
||||
ignoreValues: normalizeIgnoreValueEntries(base.ignoreValues || []),
|
||||
limits: {
|
||||
maxFindings: Number.isFinite(base?.limits?.maxFindings) ? base.limits.maxFindings : DEFAULT_CONFIG.limits.maxFindings,
|
||||
maxChars: Number.isFinite(base?.limits?.maxChars) ? base.limits.maxChars : DEFAULT_CONFIG.limits.maxChars,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function mergeLocalConfig(existing) {
|
||||
const base = existing && typeof existing === 'object' ? existing : {};
|
||||
const out = {};
|
||||
if (Object.prototype.hasOwnProperty.call(base, 'enabled')) {
|
||||
out.enabled = base.enabled === false ? false : true;
|
||||
}
|
||||
if (Array.isArray(base.ignoreRules)) {
|
||||
out.ignoreRules = Array.from(new Set(base.ignoreRules.map(String)));
|
||||
}
|
||||
if (Array.isArray(base.ignoreFiles)) {
|
||||
out.ignoreFiles = Array.from(new Set(base.ignoreFiles.map(String)));
|
||||
}
|
||||
out.ignoreValues = normalizeIgnoreValueEntries(base.ignoreValues || []);
|
||||
if (base.limits && typeof base.limits === 'object') {
|
||||
const limits = {};
|
||||
if (Number.isFinite(base.limits.maxFindings)) limits.maxFindings = base.limits.maxFindings;
|
||||
if (Number.isFinite(base.limits.maxChars)) limits.maxChars = base.limits.maxChars;
|
||||
if (Object.keys(limits).length) out.limits = limits;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function statusReport(cwd) {
|
||||
const shared = readRawConfigFile(getConfigPath(cwd));
|
||||
const local = readRawConfigFile(getLocalConfigPath(cwd));
|
||||
const cfg = readConfig(cwd);
|
||||
const envKill = process.env.IMPECCABLE_HOOK_DISABLED;
|
||||
const envState = envKill ? `IMPECCABLE_HOOK_DISABLED=${envKill}` : 'unset';
|
||||
const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.impeccable/hook.json';
|
||||
const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.impeccable/hook.local.json';
|
||||
const cachePath = path.relative(cwd, getCachePath(cwd)) || '.impeccable/hook.cache.json';
|
||||
const fileState = (info, relPath, absent) => {
|
||||
if (info.malformed) return `${relPath} (malformed; ignored)`;
|
||||
if (info.exists) return relPath;
|
||||
return `${relPath} (${absent})`;
|
||||
};
|
||||
const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
|
||||
|
||||
const lines = [
|
||||
`Impeccable design hook`,
|
||||
` state: ${cfg.enabled ? 'enabled' : 'disabled'}`,
|
||||
` shared file: ${fileState(shared, cfgPath, 'using defaults; file not present')}`,
|
||||
` local file: ${fileState(local, localPath, 'not present')}`,
|
||||
` ignoreRules: ${cfg.ignoreRules.length ? cfg.ignoreRules.join(', ') : '(none)'}`,
|
||||
` ignoreFiles: ${cfg.ignoreFiles.length ? cfg.ignoreFiles.join(', ') : '(none)'}`,
|
||||
` ignoreValues: ${ignoreValues.length ? ignoreValues.join(', ') : '(none)'}`,
|
||||
` maxFindings: ${cfg.limits.maxFindings}`,
|
||||
` maxChars: ${cfg.limits.maxChars}`,
|
||||
` env override: ${envState}`,
|
||||
` cache file: ${fs.existsSync(getCachePath(cwd)) ? cachePath : `${cachePath} (not present)`}`,
|
||||
];
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function setEnabled(cwd, value) {
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
config.enabled = value;
|
||||
const target = writeConfig(cwd, config);
|
||||
return `Design hook ${value ? 'enabled' : 'disabled'} for this project (wrote ${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function normalizeRuleId(rule) {
|
||||
return String(rule || '').trim().toLowerCase();
|
||||
}
|
||||
|
||||
function parseIgnoreRuleArgs(args) {
|
||||
const positionals = [];
|
||||
let allValues = false;
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = String(args[i] || '');
|
||||
if (arg === '--all-values') {
|
||||
allValues = true;
|
||||
} else if (arg === '--reason') {
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
|
||||
} else if (arg.startsWith('--reason=')) {
|
||||
// Accepted for command symmetry; ignoreRules stores rule ids only.
|
||||
} else if (arg.startsWith('--')) {
|
||||
throw new Error(`Unknown ignore-rule flag: ${arg}`);
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rule: normalizeRuleId(positionals[0]),
|
||||
allValues,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreRule(cwd, args) {
|
||||
const parsed = parseIgnoreRuleArgs(args);
|
||||
const rule = parsed.rule;
|
||||
if (!rule) throw new Error('Pass a rule id, e.g. /impeccable hooks ignore-rule side-tab');
|
||||
if (rule === 'overused-font' && !parsed.allValues) {
|
||||
throw new Error('overused-font is value-specific by default. Use /impeccable hooks ignore-value overused-font <font> for a confirmed font, or /impeccable hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.');
|
||||
}
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${rule}" to ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
|
||||
}
|
||||
|
||||
function addIgnoreFile(cwd, glob) {
|
||||
if (!glob) throw new Error('Pass a glob, e.g. /impeccable hooks ignore-file "src/legacy/**"');
|
||||
const config = mergeConfig(readRawConfig(cwd));
|
||||
if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
|
||||
writeConfig(cwd, config);
|
||||
return `Added "${glob}" to ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
|
||||
}
|
||||
|
||||
function parseIgnoreValueArgs(args) {
|
||||
const positionals = [];
|
||||
let shared = false;
|
||||
let local = false;
|
||||
let reason = '';
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const arg = args[i];
|
||||
if (arg === '--shared') {
|
||||
shared = true;
|
||||
} else if (arg === '--local') {
|
||||
local = true;
|
||||
} else if (arg === '--reason') {
|
||||
const chunks = [];
|
||||
while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) {
|
||||
chunks.push(args[++i]);
|
||||
}
|
||||
reason = chunks.join(' ').trim();
|
||||
} else if (String(arg).startsWith('--reason=')) {
|
||||
reason = String(arg).slice('--reason='.length).trim();
|
||||
} else {
|
||||
positionals.push(arg);
|
||||
}
|
||||
}
|
||||
|
||||
const [rule, ...valueParts] = positionals;
|
||||
return {
|
||||
rule: String(rule || '').trim().toLowerCase(),
|
||||
value: normalizeIgnoreValue(valueParts.join(' ')),
|
||||
shared,
|
||||
local,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
|
||||
function addIgnoreValue(cwd, args) {
|
||||
const parsed = parseIgnoreValueArgs(args);
|
||||
if (!parsed.rule || !parsed.value) {
|
||||
throw new Error('Pass a rule id and value, e.g. /impeccable hooks ignore-value overused-font Inter');
|
||||
}
|
||||
|
||||
if (parsed.shared && parsed.local) {
|
||||
throw new Error('Pass only one scope flag: --shared or --local');
|
||||
}
|
||||
|
||||
const local = parsed.local;
|
||||
const config = local
|
||||
? mergeLocalConfig(readRawConfig(cwd, { local: true }))
|
||||
: mergeConfig(readRawConfig(cwd, { local: false }));
|
||||
const key = `${parsed.rule}\0${parsed.value}`;
|
||||
const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
|
||||
|
||||
if (existing) {
|
||||
if (parsed.reason) existing.reason = parsed.reason;
|
||||
} else {
|
||||
const entry = {
|
||||
rule: parsed.rule,
|
||||
value: parsed.value,
|
||||
createdAt: new Date().toISOString(),
|
||||
};
|
||||
if (parsed.reason) entry.reason = parsed.reason;
|
||||
config.ignoreValues.push(entry);
|
||||
}
|
||||
|
||||
const target = writeConfig(cwd, config, { local });
|
||||
const scope = local ? 'local ignoreValues' : 'shared ignoreValues';
|
||||
return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
|
||||
}
|
||||
|
||||
function reset(cwd) {
|
||||
const removed = [];
|
||||
for (const filePath of [getConfigPath(cwd), getLocalConfigPath(cwd), getCachePath(cwd), getPendingPath(cwd)]) {
|
||||
try {
|
||||
if (fs.existsSync(filePath)) {
|
||||
fs.unlinkSync(filePath);
|
||||
removed.push(path.relative(cwd, filePath) || filePath);
|
||||
}
|
||||
} catch { /* ignore */ }
|
||||
}
|
||||
return removed.length
|
||||
? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
|
||||
: 'No hook config or cache to remove. Already at defaults.';
|
||||
}
|
||||
|
||||
function main() {
|
||||
const [, , actionArg, ...rest] = process.argv;
|
||||
const action = (actionArg || 'status').toLowerCase();
|
||||
const cwd = process.cwd();
|
||||
|
||||
if (!ACTIONS.has(action)) {
|
||||
process.stderr.write(`Unknown action: ${action}\nValid: ${Array.from(ACTIONS).join(', ')}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
let out = '';
|
||||
switch (action) {
|
||||
case 'status': out = statusReport(cwd); break;
|
||||
case 'on': out = setEnabled(cwd, true); break;
|
||||
case 'off': out = setEnabled(cwd, false); break;
|
||||
case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
|
||||
case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
|
||||
case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
|
||||
case 'reset': out = reset(cwd); break;
|
||||
}
|
||||
process.stdout.write(out + '\n');
|
||||
} catch (err) {
|
||||
process.stderr.write(`Error: ${err.message || err}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user