mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-21 10:36:27 +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
+167
-1
@@ -14,7 +14,14 @@ import { execSync } from 'child_process';
|
||||
import { mkdtempSync, existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, rmSync, lstatSync, realpathSync, readlinkSync, symlinkSync } from 'fs';
|
||||
import { join } from 'path';
|
||||
import { tmpdir } from 'os';
|
||||
import { migrateUnprefixImpeccable } from '../cli/bin/commands/skills.mjs';
|
||||
import {
|
||||
copyProviderHooks,
|
||||
copyProviderSkills,
|
||||
expectedHookDests,
|
||||
mergeHookManifests,
|
||||
migrateUnprefixImpeccable,
|
||||
resolveInstallTargets,
|
||||
} from '../cli/bin/commands/skills.mjs';
|
||||
|
||||
const CLI = join(import.meta.dir, '..', 'cli', 'bin', 'cli.js');
|
||||
|
||||
@@ -73,6 +80,27 @@ function createFakeUniversalBundle(root, providers = ['.claude', '.agents', '.cu
|
||||
].join('\n'));
|
||||
writeFileSync(join(skillDir, 'scripts', 'context.mjs'), 'console.log("local bundle context");\n');
|
||||
}
|
||||
if (providers.includes('.claude')) {
|
||||
mkdirSync(join(bundleRoot, '.claude'), { recursive: true });
|
||||
writeFileSync(join(bundleRoot, '.claude', 'settings.json'), JSON.stringify({
|
||||
description: 'fresh claude hook',
|
||||
hooks: { PostToolUse: [{ matcher: 'Edit', hooks: [{ type: 'command', command: 'node ".claude/skills/impeccable/scripts/hook.mjs"' }] }] },
|
||||
}, null, 2));
|
||||
}
|
||||
if (providers.includes('.cursor')) {
|
||||
mkdirSync(join(bundleRoot, '.cursor'), { recursive: true });
|
||||
writeFileSync(join(bundleRoot, '.cursor', 'hooks.json'), JSON.stringify({
|
||||
version: 1,
|
||||
hooks: { preToolUse: [{ command: 'node ".cursor/skills/impeccable/scripts/hook-before-edit.mjs"' }] },
|
||||
}, null, 2));
|
||||
}
|
||||
if (providers.includes('.agents')) {
|
||||
mkdirSync(join(bundleRoot, '.codex'), { recursive: true });
|
||||
writeFileSync(join(bundleRoot, '.codex', 'hooks.json'), JSON.stringify({
|
||||
description: 'fresh codex hook',
|
||||
hooks: { PostToolUse: [{ matcher: 'apply_patch', hooks: [{ type: 'command', command: 'node "$(git rev-parse --show-toplevel)/.agents/skills/impeccable/scripts/hook.mjs"' }] }] },
|
||||
}, null, 2));
|
||||
}
|
||||
return bundleRoot;
|
||||
}
|
||||
|
||||
@@ -109,6 +137,7 @@ describe('skills install: already-installed detection', () => {
|
||||
const tmp = mkdtempSync(join(tmpdir(), 'imp-test-'));
|
||||
execSync('git init', { cwd: tmp });
|
||||
createFakeSkills(tmp);
|
||||
writeFileSync(join(tmp, '.claude', 'settings.json'), JSON.stringify({ hooks: {} }));
|
||||
|
||||
const output = run('skills install -y', { cwd: tmp });
|
||||
expect(output).toContain('already installed');
|
||||
@@ -123,12 +152,49 @@ describe('skills install: already-installed detection', () => {
|
||||
const skillDir = join(tmp, '.cursor', 'skills', 'i-impeccable');
|
||||
mkdirSync(skillDir, { recursive: true });
|
||||
writeFileSync(join(skillDir, 'SKILL.md'), '---\nname: i-impeccable\n---\n');
|
||||
writeFileSync(join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ version: 1, hooks: {} }));
|
||||
|
||||
const output = run('skills install -y', { cwd: tmp });
|
||||
expect(output).toContain('already installed');
|
||||
|
||||
rmSync(tmp, { recursive: true, force: true });
|
||||
}, 15000);
|
||||
|
||||
test('repairs missing hook manifests on already-installed projects', () => {
|
||||
const tmp = mkdtempSync(join(tmpdir(), 'imp-test-repair-hooks-'));
|
||||
execSync('git init', { cwd: tmp });
|
||||
createFakeSkills(tmp, ['impeccable'], ['.claude']);
|
||||
const bundleRoot = createFakeUniversalBundle(tmp, ['.claude']);
|
||||
|
||||
const output = run('skills install -y --providers=claude', {
|
||||
cwd: tmp,
|
||||
env: { ...process.env, IMPECCABLE_BUNDLE_PATH: bundleRoot },
|
||||
});
|
||||
|
||||
expect(output).toContain('already installed');
|
||||
expect(output).toContain('Installed hooks into: .claude');
|
||||
expect(existsSync(join(tmp, '.claude', 'settings.json'))).toBe(true);
|
||||
|
||||
rmSync(tmp, { recursive: true, force: true });
|
||||
}, 15000);
|
||||
|
||||
test('--no-hooks does not repair missing hook manifests on already-installed projects', () => {
|
||||
const tmp = mkdtempSync(join(tmpdir(), 'imp-test-no-hooks-repair-'));
|
||||
execSync('git init', { cwd: tmp });
|
||||
createFakeSkills(tmp, ['impeccable'], ['.claude']);
|
||||
const bundleRoot = createFakeUniversalBundle(tmp, ['.claude']);
|
||||
|
||||
const output = run('skills install -y --providers=claude --no-hooks', {
|
||||
cwd: tmp,
|
||||
env: { ...process.env, IMPECCABLE_BUNDLE_PATH: bundleRoot },
|
||||
});
|
||||
|
||||
expect(output).toContain('already installed');
|
||||
expect(output).not.toContain('Installed hooks into');
|
||||
expect(existsSync(join(tmp, '.claude', 'settings.json'))).toBe(false);
|
||||
|
||||
rmSync(tmp, { recursive: true, force: true });
|
||||
}, 15000);
|
||||
});
|
||||
|
||||
// ─── Submodule/link installs ────────────────────────────────────────────────
|
||||
@@ -330,6 +396,30 @@ describe('skills install/update: local universal bundle e2e', () => {
|
||||
expect(readFileSync(join(skillDir, 'SKILL.md'), 'utf8')).toContain(`Local deterministic bundle for ${provider}.`);
|
||||
expect(existsSync(join(skillDir, 'scripts', 'context.mjs'))).toBe(true);
|
||||
}
|
||||
expect(existsSync(join(tmp, '.claude', 'settings.json'))).toBe(true);
|
||||
expect(existsSync(join(tmp, '.cursor', 'hooks.json'))).toBe(true);
|
||||
expect(existsSync(join(tmp, '.codex', 'hooks.json'))).toBe(true);
|
||||
|
||||
rmSync(tmp, { recursive: true, force: true });
|
||||
}, 15000);
|
||||
|
||||
test('--no-hooks installs skills without hook manifests', () => {
|
||||
const tmp = mkdtempSync(join(tmpdir(), 'imp-test-local-no-hooks-'));
|
||||
execSync('git init', { cwd: tmp });
|
||||
const bundleRoot = createFakeUniversalBundle(tmp);
|
||||
|
||||
const output = run('skills install -y --providers=claude,codex,cursor --no-hooks', {
|
||||
cwd: tmp,
|
||||
env: { ...process.env, IMPECCABLE_BUNDLE_PATH: bundleRoot },
|
||||
});
|
||||
expect(output).toContain('Done!');
|
||||
expect(output).not.toContain('Installed hooks into');
|
||||
for (const provider of ['.claude', '.agents', '.cursor']) {
|
||||
expect(existsSync(join(tmp, provider, 'skills', 'impeccable', 'SKILL.md'))).toBe(true);
|
||||
}
|
||||
expect(existsSync(join(tmp, '.claude', 'settings.json'))).toBe(false);
|
||||
expect(existsSync(join(tmp, '.cursor', 'hooks.json'))).toBe(false);
|
||||
expect(existsSync(join(tmp, '.codex', 'hooks.json'))).toBe(false);
|
||||
|
||||
rmSync(tmp, { recursive: true, force: true });
|
||||
}, 15000);
|
||||
@@ -353,6 +443,49 @@ describe('skills install/update: local universal bundle e2e', () => {
|
||||
expect(content).not.toContain('stale: true');
|
||||
expect(content).toContain('version: 9.9.9-local');
|
||||
expect(existsSync(join(skillDir, 'scripts', 'context.mjs'))).toBe(true);
|
||||
expect(existsSync(join(tmp, '.claude', 'settings.json'))).toBe(true);
|
||||
|
||||
rmSync(tmp, { recursive: true, force: true });
|
||||
}, 15000);
|
||||
|
||||
test('skills update --no-hooks refreshes skills without touching malformed hook manifests', () => {
|
||||
const tmp = mkdtempSync(join(tmpdir(), 'imp-test-update-no-hooks-'));
|
||||
execSync('git init', { cwd: tmp });
|
||||
const bundleRoot = createFakeUniversalBundle(tmp, ['.cursor']);
|
||||
|
||||
run('skills install -y --providers=cursor --no-hooks', {
|
||||
cwd: tmp,
|
||||
env: { ...process.env, IMPECCABLE_BUNDLE_PATH: bundleRoot },
|
||||
});
|
||||
mkdirSync(join(tmp, '.cursor'), { recursive: true });
|
||||
writeFileSync(join(tmp, '.cursor', 'hooks.json'), '{ malformed');
|
||||
|
||||
const output = run('skills update -y --no-hooks', {
|
||||
cwd: tmp,
|
||||
env: { ...process.env, IMPECCABLE_BUNDLE_PATH: bundleRoot },
|
||||
});
|
||||
expect(output).toContain('Skills are up to date');
|
||||
expect(readFileSync(join(tmp, '.cursor', 'hooks.json'), 'utf8')).toBe('{ malformed');
|
||||
|
||||
rmSync(tmp, { recursive: true, force: true });
|
||||
}, 15000);
|
||||
|
||||
test('skills update reports malformed hook manifests cleanly on the up-to-date path', () => {
|
||||
const tmp = mkdtempSync(join(tmpdir(), 'imp-test-update-bad-hooks-'));
|
||||
execSync('git init', { cwd: tmp });
|
||||
const bundleRoot = createFakeUniversalBundle(tmp, ['.cursor']);
|
||||
|
||||
run('skills install -y --providers=cursor', {
|
||||
cwd: tmp,
|
||||
env: { ...process.env, IMPECCABLE_BUNDLE_PATH: bundleRoot },
|
||||
});
|
||||
writeFileSync(join(tmp, '.cursor', 'hooks.json'), '{ malformed');
|
||||
|
||||
expect(() => run('skills update -y', {
|
||||
cwd: tmp,
|
||||
env: { ...process.env, IMPECCABLE_BUNDLE_PATH: bundleRoot },
|
||||
stdio: 'pipe',
|
||||
})).toThrow();
|
||||
|
||||
rmSync(tmp, { recursive: true, force: true });
|
||||
}, 15000);
|
||||
@@ -378,6 +511,39 @@ describe('skills install/update: local universal bundle e2e', () => {
|
||||
}, 15000);
|
||||
});
|
||||
|
||||
describe('hook manifest merge helpers', () => {
|
||||
test('mergeHookManifests refreshes fresh description and version while preserving third-party hooks', () => {
|
||||
const merged = mergeHookManifests(
|
||||
{
|
||||
version: 0,
|
||||
description: 'old description',
|
||||
hooks: {
|
||||
preToolUse: [
|
||||
{ command: 'node third-party.mjs' },
|
||||
{ command: 'node .cursor/skills/impeccable/scripts/hook-before-edit.mjs' },
|
||||
],
|
||||
},
|
||||
},
|
||||
{
|
||||
version: 1,
|
||||
description: 'fresh description',
|
||||
hooks: {
|
||||
preToolUse: [
|
||||
{ command: 'node .cursor/skills/impeccable/scripts/hook-before-edit.mjs' },
|
||||
],
|
||||
},
|
||||
},
|
||||
);
|
||||
|
||||
expect(merged.version).toBe(1);
|
||||
expect(merged.description).toBe('fresh description');
|
||||
expect(merged.hooks.preToolUse.map((entry) => entry.command)).toEqual([
|
||||
'node third-party.mjs',
|
||||
'node .cursor/skills/impeccable/scripts/hook-before-edit.mjs',
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── Update fallback (remote direct download smoke) ──────────────────────────
|
||||
|
||||
describeRemote('skills update: refreshes from the production universal bundle', () => {
|
||||
|
||||
Reference in New Issue
Block a user