impeccable 3.5.0 → 3.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -3
- package/README.npm.md +3 -3
- package/README.repo.md +26 -3
- package/cli/bin/cli.js +6 -0
- package/cli/bin/commands/skills.mjs +162 -28
- package/cli/engine/browser/injected/index.mjs +56 -6
- package/cli/engine/design-system.mjs +140 -2
- package/cli/engine/detect-antipatterns-browser.js +1003 -556
- package/cli/engine/detect-antipatterns.mjs +1 -0
- package/cli/engine/engines/regex/detect-text.mjs +426 -23
- package/cli/engine/engines/static-html/css-cascade.mjs +6 -0
- package/cli/engine/engines/static-html/detect-html.mjs +28 -2
- package/cli/engine/node/file-system.mjs +23 -22
- package/cli/engine/rules/checks.mjs +297 -341
- package/cli/engine/shared/color.mjs +466 -2
- package/cli/lib/download-providers.js +7 -0
- package/cli/lib/impeccable-config.mjs +41 -59
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Impeccable CLI
|
|
2
2
|
|
|
3
|
-
Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for
|
|
3
|
+
Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 59 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
|
|
4
4
|
|
|
5
5
|
## Quick Start
|
|
6
6
|
|
|
@@ -56,7 +56,7 @@ npx impeccable detect --fast src/
|
|
|
56
56
|
|
|
57
57
|
**Quality**: tiny body text, cramped padding, long line lengths, small touch targets
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
59 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
|
|
60
60
|
|
|
61
61
|
## Exit Codes
|
|
62
62
|
|
|
@@ -75,7 +75,7 @@ impeccable detect [options] [file-or-dir-or-url...]
|
|
|
75
75
|
|
|
76
76
|
## Requirements
|
|
77
77
|
|
|
78
|
-
- Node.js 22.
|
|
78
|
+
- Node.js 22.18+
|
|
79
79
|
- `jsdom` (included as dependency, used for HTML scanning)
|
|
80
80
|
- `puppeteer` (optional, only needed for URL scanning)
|
|
81
81
|
|
package/README.npm.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Impeccable CLI
|
|
2
2
|
|
|
3
|
-
Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for
|
|
3
|
+
Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 59 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
|
|
4
4
|
|
|
5
5
|
## Quick Start
|
|
6
6
|
|
|
@@ -56,7 +56,7 @@ npx impeccable detect --fast src/
|
|
|
56
56
|
|
|
57
57
|
**Quality**: tiny body text, cramped padding, long line lengths, small touch targets
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
59 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
|
|
60
60
|
|
|
61
61
|
## Exit Codes
|
|
62
62
|
|
|
@@ -75,7 +75,7 @@ impeccable detect [options] [file-or-dir-or-url...]
|
|
|
75
75
|
|
|
76
76
|
## Requirements
|
|
77
77
|
|
|
78
|
-
- Node.js 22.
|
|
78
|
+
- Node.js 22.18+
|
|
79
79
|
- `jsdom` (included as dependency, used for HTML scanning)
|
|
80
80
|
- `puppeteer` (optional, only needed for URL scanning)
|
|
81
81
|
|
package/README.repo.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Impeccable
|
|
2
2
|
|
|
3
|
-
Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and
|
|
3
|
+
Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 59 deterministic detector rules for AI-generated frontend design.
|
|
4
4
|
|
|
5
5
|
> **Quick start:** From your project root, run `npx impeccable install`, then run `/impeccable init` inside your AI coding tool. Full docs: [impeccable.style](https://impeccable.style).
|
|
6
6
|
|
|
@@ -13,7 +13,7 @@ Every model trained on the same SaaS templates. Skip the guidance and you get th
|
|
|
13
13
|
Impeccable adds:
|
|
14
14
|
- **One setup flow.** `/impeccable init` writes `PRODUCT.md` and offers `DESIGN.md`, so later commands know the audience, brand/product lane, voice, anti-references, colors, type, and components.
|
|
15
15
|
- **23 commands.** A shared design vocabulary with your AI: `polish`, `audit`, `critique`, `distill`, `animate`, `bolder`, `quieter`, and more.
|
|
16
|
-
- **
|
|
16
|
+
- **59 deterministic detector rules** plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.
|
|
17
17
|
|
|
18
18
|
## What's Included
|
|
19
19
|
|
|
@@ -270,6 +270,16 @@ cp -r dist/grok/.grok/skills/* ~/.grok/skills/
|
|
|
270
270
|
|
|
271
271
|
> Prefer `npx impeccable install --providers=grok` or `grok plugin install pbakaus/impeccable#plugin --trust` so the design hook installs too. Project hooks need `/hooks-trust` (or `--trust`) once per folder.
|
|
272
272
|
|
|
273
|
+
**Google Antigravity:**
|
|
274
|
+
```bash
|
|
275
|
+
# Project-specific
|
|
276
|
+
cp -r dist/antigravity/.agent your-project/
|
|
277
|
+
|
|
278
|
+
# Or global (applies to all projects)
|
|
279
|
+
mkdir -p ~/.gemini/config/skills
|
|
280
|
+
cp -r dist/antigravity/.agent/skills/* ~/.gemini/config/skills/
|
|
281
|
+
```
|
|
282
|
+
|
|
273
283
|
## Usage
|
|
274
284
|
|
|
275
285
|
Once installed, every command runs through the single `/impeccable` skill:
|
|
@@ -351,6 +361,18 @@ On an interactive `install`/`update`, Impeccable explains the hook and offers to
|
|
|
351
361
|
|
|
352
362
|
For debugging, set `hook.auditLog` in `.impeccable/config.json` to a path (or the legacy `IMPECCABLE_HOOK_LOG` env var) to write one NDJSON line per hook invocation. Leave it unset for normal use.
|
|
353
363
|
|
|
364
|
+
## Build path: comp-first or code-first
|
|
365
|
+
|
|
366
|
+
When a new surface gets designed, Impeccable either generates a full-fidelity comp first and builds to match it, or builds straight in code with the ambition written into the direction contract and checked at the finish. Comp-first composes bolder and takes longer; code-first is leaner and faster. `/impeccable init` asks once and records the answer as `buildPath` in `.impeccable/config.json`:
|
|
367
|
+
|
|
368
|
+
```json
|
|
369
|
+
{ "buildPath": "comp" }
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
The values are `comp` and `code`, and nothing else is read. Set it in the gitignored `.impeccable/config.local.json` to override the team's committed value on one machine, which is what you want when your harness has no image generation. In a monorepo, commit it once at the repo root and any workspace that wants something else sets its own. The choice appears at all only where image generation is available, since without it there is nothing to comp.
|
|
373
|
+
|
|
374
|
+
You do not have to re-run `init` to set it on a project that predates the setting, and you do not have to edit the file by hand either. Whatever is recorded is a default rather than a lock: every decision page carries a footer toggle, and flipping it binds that session only. Flip it on a project that has recorded nothing and Impeccable asks once, after the round, whether to keep it, then writes your answer. That is the whole migration path for an existing project: use the toggle when the default is wrong, and answer the question that follows.
|
|
375
|
+
|
|
354
376
|
Codex requires one platform step that Impeccable cannot safely skip: open `/hooks` after install or update and approve the project hook. There is no Codex marketplace/plugin install flow for this hook.
|
|
355
377
|
|
|
356
378
|
Full hook docs: [impeccable.style/docs/hooks](https://impeccable.style/docs/hooks).
|
|
@@ -377,7 +399,7 @@ npx impeccable ignores add-file "src/legacy/**"
|
|
|
377
399
|
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
|
|
378
400
|
```
|
|
379
401
|
|
|
380
|
-
The detector catches
|
|
402
|
+
The detector catches 59 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
|
|
381
403
|
|
|
382
404
|
By default, `detect` respects the same `.impeccable/config.json` and `.impeccable/config.local.json` detector config as the design hook: `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`. Hook lifecycle settings such as `hook.enabled` only affect automatic hook execution.
|
|
383
405
|
|
|
@@ -400,6 +422,7 @@ Full detector docs: [impeccable.style/docs/detector](https://impeccable.style/do
|
|
|
400
422
|
- [Rovo Dev](https://www.atlassian.com/software/rovo)
|
|
401
423
|
- [Qoder](https://qoder.com)
|
|
402
424
|
- [Mistral Vibe](https://docs.mistral.ai/vibe/code/overview)
|
|
425
|
+
- [Google Antigravity](https://antigravity.google)
|
|
403
426
|
|
|
404
427
|
## Community & Ecosystem
|
|
405
428
|
|
package/cli/bin/cli.js
CHANGED
|
@@ -77,6 +77,12 @@ Compatibility:
|
|
|
77
77
|
process.argv = [process.argv[0], process.argv[1], ...args];
|
|
78
78
|
const { detectCli } = await import('../engine/detect-antipatterns.mjs');
|
|
79
79
|
await detectCli();
|
|
80
|
+
} else if (command === 'init') {
|
|
81
|
+
// The follow-up mistake from issue #472: `/impeccable init` belongs in an AI
|
|
82
|
+
// coding agent's chat, and a user who typed it into their shell is likely to
|
|
83
|
+
// retry it here as `npx impeccable init`.
|
|
84
|
+
console.error(`"init" is not a CLI command. Type /impeccable init in your AI coding agent's chat (Claude Code, Cursor, Codex, ...), not in this terminal.`);
|
|
85
|
+
process.exit(1);
|
|
80
86
|
} else {
|
|
81
87
|
// An unknown bareword: a mistyped command (or an old cached version run
|
|
82
88
|
// against newer docs). Fail loudly instead of silently statting it as a path.
|
|
@@ -23,9 +23,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
|
23
23
|
const API_BASE = 'https://impeccable.style';
|
|
24
24
|
|
|
25
25
|
// Provider folder names in project roots
|
|
26
|
-
const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.grok', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn', '.rovodev', '.vibe'];
|
|
26
|
+
const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.agent', '.github', '.grok', '.hermes', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn', '.rovodev', '.vibe'];
|
|
27
27
|
const PROVIDER_ALIASES = {
|
|
28
|
+
agent: '.agent',
|
|
28
29
|
agents: '.agents',
|
|
30
|
+
antigravity: '.agent',
|
|
29
31
|
claude: '.claude',
|
|
30
32
|
'claude-code': '.claude',
|
|
31
33
|
codex: '.agents',
|
|
@@ -35,6 +37,7 @@ const PROVIDER_ALIASES = {
|
|
|
35
37
|
github: '.github',
|
|
36
38
|
grok: '.grok',
|
|
37
39
|
'grok-build': '.grok',
|
|
40
|
+
hermes: '.hermes',
|
|
38
41
|
xai: '.grok',
|
|
39
42
|
kiro: '.kiro',
|
|
40
43
|
opencode: '.opencode',
|
|
@@ -48,12 +51,14 @@ const PROVIDER_ALIASES = {
|
|
|
48
51
|
};
|
|
49
52
|
|
|
50
53
|
const PROVIDER_DISPLAY = {
|
|
54
|
+
'.agent': { name: 'Antigravity', input: 'antigravity' },
|
|
51
55
|
'.agents': { name: 'Codex CLI', input: 'codex' },
|
|
52
56
|
'.claude': { name: 'Claude Code', input: 'claude' },
|
|
53
57
|
'.cursor': { name: 'Cursor', input: 'cursor' },
|
|
54
58
|
'.gemini': { name: 'Gemini CLI', input: 'gemini' },
|
|
55
59
|
'.github': { name: 'GitHub Copilot', input: 'github' },
|
|
56
60
|
'.grok': { name: 'Grok Build', input: 'grok' },
|
|
61
|
+
'.hermes': { name: 'Hermes Agent', input: 'hermes' },
|
|
57
62
|
'.kiro': { name: 'Kiro', input: 'kiro' },
|
|
58
63
|
'.opencode': { name: 'OpenCode', input: 'opencode' },
|
|
59
64
|
'.pi': { name: 'Pi Coding Agent', input: 'pi' },
|
|
@@ -63,7 +68,7 @@ const PROVIDER_DISPLAY = {
|
|
|
63
68
|
'.trae-cn': { name: 'Trae CN', input: 'trae-cn' },
|
|
64
69
|
'.vibe': { name: 'Mistral Vibe', input: 'vibe' },
|
|
65
70
|
};
|
|
66
|
-
const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'grok', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev', 'vibe'];
|
|
71
|
+
const PROVIDER_INPUT_ORDER = ['antigravity', 'claude', 'codex', 'cursor', 'gemini', 'github', 'grok', 'hermes', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev', 'vibe'];
|
|
67
72
|
|
|
68
73
|
// OpenCode reads global skills from its config directory, not ~/.opencode:
|
|
69
74
|
// $OPENCODE_CONFIG_DIR, else $XDG_CONFIG_HOME/opencode, else
|
|
@@ -75,11 +80,52 @@ function opencodeGlobalConfigDir(home) {
|
|
|
75
80
|
return join(home, '.config', 'opencode');
|
|
76
81
|
}
|
|
77
82
|
|
|
83
|
+
// Hermes reads skills from `$HERMES_HOME/skills/`, where $HERMES_HOME defaults
|
|
84
|
+
// to `~/.hermes` but is also set to a profile path (e.g.
|
|
85
|
+
// `~/.hermes/profiles/forge`) when a non-default profile is active. Reading
|
|
86
|
+
// the env var matters here at install time: writing to `~/.hermes/skills/`
|
|
87
|
+
// from a profile-scoped Hermes invocation would land in the wrong profile
|
|
88
|
+
// (the same cross-profile data-corruption class that the active_profile
|
|
89
|
+
// fallback warning in hermes_constants.py exists to detect). Used by
|
|
90
|
+
// HOME_SKILLS_DIR_OVERRIDES['.hermes'] only; GLOBAL_HARNESS_HINTS reads the
|
|
91
|
+
// fixed `~/.hermes` location so detection doesn't leak the developer's real
|
|
92
|
+
// HERMES_HOME into test output (test isolation).
|
|
93
|
+
//
|
|
94
|
+
// Ignore $HERMES_HOME when it doesn't sit under `home` (the caller-supplied
|
|
95
|
+
// home dir, which tests inject via HOME=/tmp/...). Without this guard, an
|
|
96
|
+
// inherited $HERMES_HOME=/home/<dev>/.hermes from the developer's shell leaks
|
|
97
|
+
// into test output even when the test sets HOME=/tmp/imp-home-xxx: tests
|
|
98
|
+
// expect ~/.hermes to live under their tmp home, not under the dev's real
|
|
99
|
+
// home. The check uses `resolve()` on both sides so a symlinked test home
|
|
100
|
+
// (e.g. /tmp -> /private/tmp on macOS) still compares correctly.
|
|
101
|
+
function hermesGlobalHome(home) {
|
|
102
|
+
const envHome = process.env.HERMES_HOME;
|
|
103
|
+
if (envHome) {
|
|
104
|
+
try {
|
|
105
|
+
const resolvedEnv = resolve(envHome);
|
|
106
|
+
const resolvedHome = resolve(home);
|
|
107
|
+
// Honor HERMES_HOME only when it lives under the active home (real
|
|
108
|
+
// ~/.hermes or ~/.hermes/profiles/<name>). Cross-home inheritance is
|
|
109
|
+
// treated as not-set, so a test running under HOME=/tmp/... doesn't
|
|
110
|
+
// pick up the developer's real ~/.hermes.
|
|
111
|
+
if (resolvedEnv === resolvedHome || resolvedEnv.startsWith(resolvedHome + sep)) {
|
|
112
|
+
return resolvedEnv;
|
|
113
|
+
}
|
|
114
|
+
} catch {
|
|
115
|
+
// fall through to default
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
return join(home, '.hermes');
|
|
119
|
+
}
|
|
120
|
+
|
|
78
121
|
// Providers whose GLOBAL (home) skills dir is not `<provider>/skills`,
|
|
79
122
|
// as a function of the home dir. Pi discovers global skills from
|
|
80
123
|
// ~/.pi/agent/skills/ (issue #327); OpenCode from its config dir (issue
|
|
81
|
-
// #406). Project scope stays `<provider>/skills`
|
|
124
|
+
// #406); Hermes from $HERMES_HOME. Project scope stays `<provider>/skills`
|
|
125
|
+
// for all three.
|
|
82
126
|
const HOME_SKILLS_DIR_OVERRIDES = {
|
|
127
|
+
'.agent': (home) => join(home, '.gemini', 'config', 'skills'),
|
|
128
|
+
'.hermes': (home) => join(hermesGlobalHome(home), 'skills'),
|
|
83
129
|
'.pi': (home) => join(home, '.pi', 'agent', 'skills'),
|
|
84
130
|
'.opencode': (home) => join(opencodeGlobalConfigDir(home), 'skills'),
|
|
85
131
|
};
|
|
@@ -87,12 +133,27 @@ const HOME_SKILLS_DIR_OVERRIDES = {
|
|
|
87
133
|
// When a project has no harness folder yet, infer the target from globally
|
|
88
134
|
// installed harnesses (~/.claude, ~/.codex, ...). Codex reads skills from
|
|
89
135
|
// .agents/skills, so ~/.codex maps to the .agents bundle variant.
|
|
136
|
+
//
|
|
137
|
+
// Hermes auto-detection uses the fixed `~/.hermes` location only. When a
|
|
138
|
+
// non-default Hermes profile is active (HERMES_HOME points to a profile path),
|
|
139
|
+
// the user is expected to be inside a Hermes invocation and can pass
|
|
140
|
+
// --providers=hermes explicitly. Auto-detection from a non-default HERMES_HOME
|
|
141
|
+
// would also defeat test isolation (tests inject HOME; HERMES_HOME leaks from
|
|
142
|
+
// the parent process and would surface the developer's real ~/.hermes in
|
|
143
|
+
// detection output). The install path honors $HERMES_HOME; detection does not.
|
|
90
144
|
const GLOBAL_HARNESS_HINTS = [
|
|
145
|
+
{ home: '.agent', provider: '.agent' },
|
|
146
|
+
// Antigravity nests under ~/.gemini/ too, so any of these also trips the
|
|
147
|
+
// .gemini hint above (harmless double-detection — both get pre-selected).
|
|
148
|
+
{ home: '.gemini/antigravity', provider: '.agent' },
|
|
149
|
+
{ home: '.gemini/antigravity-cli', provider: '.agent' },
|
|
150
|
+
{ home: '.gemini/antigravity-ide', provider: '.agent' },
|
|
91
151
|
{ home: '.claude', provider: '.claude' },
|
|
92
152
|
{ home: '.codex', provider: '.agents' },
|
|
93
153
|
{ home: '.cursor', provider: '.cursor' },
|
|
94
154
|
{ home: '.gemini', provider: '.gemini' },
|
|
95
155
|
{ home: '.grok', provider: '.grok' },
|
|
156
|
+
{ home: '.hermes', provider: '.hermes' },
|
|
96
157
|
{ home: '.kiro', provider: '.kiro' },
|
|
97
158
|
{ home: '.opencode', provider: '.opencode' },
|
|
98
159
|
// OpenCode's real global config dir (issue #406); the ~/.opencode entry
|
|
@@ -598,7 +659,7 @@ async function copyOrExtractLocalBundle(sourceValue) {
|
|
|
598
659
|
*/
|
|
599
660
|
function normalizeForHash(content) {
|
|
600
661
|
return content
|
|
601
|
-
.replace(/\.(claude|cursor|agents|github|gemini|codex|grok|kiro|opencode|pi|qoder|trae|trae-cn|rovodev|vibe)\/skills\//g, '.PROVIDER/skills/');
|
|
662
|
+
.replace(/\.(claude|cursor|agents|agent|github|gemini|codex|grok|hermes|kiro|opencode|pi|qoder|trae|trae-cn|rovodev|vibe)\/skills\//g, '.PROVIDER/skills/');
|
|
602
663
|
}
|
|
603
664
|
|
|
604
665
|
function hashSkillFile(filePath) {
|
|
@@ -1088,13 +1149,13 @@ async function chooseInstallScope(projectRoot, targets, detections, { yes, scope
|
|
|
1088
1149
|
async function chooseInstallPlan(projectRoot, flags, { yes } = {}) {
|
|
1089
1150
|
const providersValue = getFlagValue(flags, '--providers');
|
|
1090
1151
|
const scopeValue = getInstallScopeValue(flags);
|
|
1091
|
-
const { targets, detections } = await chooseInstallProviders(projectRoot, providersValue, { yes });
|
|
1152
|
+
const { targets, detections, explicit } = await chooseInstallProviders(projectRoot, providersValue, { yes });
|
|
1092
1153
|
if (targets.length === 0) {
|
|
1093
1154
|
throw new Error('Could not determine a target harness folder.');
|
|
1094
1155
|
}
|
|
1095
1156
|
const scope = await chooseInstallScope(projectRoot, targets, detections, { yes, scopeValue });
|
|
1096
1157
|
const installRoot = installRootForScope(scope, projectRoot);
|
|
1097
|
-
return { targets, scope, installRoot, hookRoot: projectRoot, detections };
|
|
1158
|
+
return { targets, scope, installRoot, hookRoot: projectRoot, detections, explicit };
|
|
1098
1159
|
}
|
|
1099
1160
|
|
|
1100
1161
|
/**
|
|
@@ -1328,8 +1389,53 @@ function hookScriptPathForProvider(skillRoot, provider) {
|
|
|
1328
1389
|
// code when the file exists, so Claude's exit-2 blocking signal still reaches
|
|
1329
1390
|
// the agent. POSIX-shell form, consistent with the project's other hook
|
|
1330
1391
|
// commands (e.g. the GitHub manifest's `$(git rev-parse ...)`).
|
|
1331
|
-
|
|
1332
|
-
|
|
1392
|
+
//
|
|
1393
|
+
// On Windows that guard is a hard failure, not a degraded one (issue #452).
|
|
1394
|
+
// Codex runs hook commands through COMSPEC (`cmd.exe /C`), where `[` is not a
|
|
1395
|
+
// command: the guard errors noisily and `||` then runs node even when the file
|
|
1396
|
+
// is missing, trading the silent no-op for a MODULE_NOT_FOUND crash. Two
|
|
1397
|
+
// remedies, by provider:
|
|
1398
|
+
//
|
|
1399
|
+
// * Codex manifests support a `commandWindows` sibling that Codex 0.146.0+
|
|
1400
|
+
// selects on Windows (`command_windows.unwrap_or(command)` in its hook
|
|
1401
|
+
// discovery). rewriteHookCommandsForSkillRoot adds it with a cmd.exe
|
|
1402
|
+
// `if exist` guard (form contributed and Windows-tested by @PatrickSys in
|
|
1403
|
+
// issue #452; `exit /b` forwards node's errorlevel), so the same
|
|
1404
|
+
// .codex/hooks.json is correct on every OS no matter where it was
|
|
1405
|
+
// written, and `command` stays the plain POSIX guard.
|
|
1406
|
+
// * Claude and Cursor manifests have no per-platform field, so a Windows
|
|
1407
|
+
// install moves the existence check into node itself: a `node -e` wrapper
|
|
1408
|
+
// that exits 0 when the target is missing and otherwise re-spawns node on
|
|
1409
|
+
// it with inherited stdio, forwarding the hook's exit code. Cursor's
|
|
1410
|
+
// hooks.json is committable and can be consumed on a teammate's POSIX
|
|
1411
|
+
// machine, so the wrapper has to hold there too: it uses only characters
|
|
1412
|
+
// that survive PowerShell, cmd.exe (issue #445: shims re-parse through
|
|
1413
|
+
// `cmd /C`, which claims < > | & ^ % !), and sh double-quoting alike,
|
|
1414
|
+
// with single quotes for the inner string literals.
|
|
1415
|
+
const WIN32_HOOK_GUARD_SCRIPT = "const p=process.argv[1];const f=require('fs');if(f.existsSync(p)){const r=require('child_process').spawnSync(process.execPath,[p],{stdio:'inherit'});process.exit(r.status===null?1:r.status);}";
|
|
1416
|
+
|
|
1417
|
+
// POSIX single-quote escaping. JSON.stringify is not shell quoting: inside
|
|
1418
|
+
// double quotes /bin/sh still expands $(...), backticks, and ${}, and this
|
|
1419
|
+
// string is baked into a hook manifest the harness re-executes on every edit,
|
|
1420
|
+
// so an install path embedding $(...) would run it repeatedly (issue #476).
|
|
1421
|
+
// Windows command forms keep double quotes: cmd.exe treats ' as a literal
|
|
1422
|
+
// character and performs no command substitution.
|
|
1423
|
+
function shSingleQuote(value) {
|
|
1424
|
+
return `'${String(value).replace(/'/g, `'\\''`)}'`;
|
|
1425
|
+
}
|
|
1426
|
+
|
|
1427
|
+
function windowsHookCommand(quotedPath) {
|
|
1428
|
+
return `if exist ${quotedPath} (node ${quotedPath} & exit /b)`;
|
|
1429
|
+
}
|
|
1430
|
+
|
|
1431
|
+
// `quotedPath` carries one pre-quoted form per target shell: { posix, win32 }.
|
|
1432
|
+
function guardHookCommand(quotedPath, provider) {
|
|
1433
|
+
// `.agents` (Codex) keeps the POSIX form unconditionally: its Windows
|
|
1434
|
+
// consumers read the commandWindows sibling instead.
|
|
1435
|
+
if (provider !== '.agents' && process.platform === 'win32') {
|
|
1436
|
+
return `node -e "${WIN32_HOOK_GUARD_SCRIPT}" ${quotedPath.win32}`;
|
|
1437
|
+
}
|
|
1438
|
+
return `[ ! -f ${quotedPath.posix} ] || node ${quotedPath.posix}`;
|
|
1333
1439
|
}
|
|
1334
1440
|
|
|
1335
1441
|
// Transform bundled hook commands for the actual install target:
|
|
@@ -1340,25 +1446,30 @@ function guardHookCommand(quotedPath) {
|
|
|
1340
1446
|
// when a project hook points at a skill installed elsewhere (--scope=global).
|
|
1341
1447
|
// * otherwise — keep the bundle's own ${CLAUDE_PROJECT_DIR}-relative path,
|
|
1342
1448
|
// which correctly resolves for a project-scoped install.
|
|
1343
|
-
// Either way the command
|
|
1449
|
+
// Either way the command goes through guardHookCommand (POSIX shell guard, or
|
|
1450
|
+
// the shell-agnostic node -e guard when installing on Windows), and Codex hook
|
|
1451
|
+
// entries additionally get a `commandWindows` sibling for cmd.exe.
|
|
1344
1452
|
function rewriteHookCommandsForSkillRoot(value, provider, { skillRoot, absolute }) {
|
|
1345
1453
|
const hookScript = hookScriptPathForProvider(skillRoot, provider);
|
|
1346
1454
|
// Providers we don't own a `node "PATH"` command hook for (.github, .grok)
|
|
1347
1455
|
// carry their own portable command forms; leave them untouched.
|
|
1348
1456
|
if (!hookScript) return value;
|
|
1349
1457
|
|
|
1458
|
+
// Project-scope installs derive the provider's own project-relative path
|
|
1459
|
+
// rather than trusting the bundle token, which for Codex points at
|
|
1460
|
+
// `.codex/skills/...` while the CLI installs the skill at `.agents/skills/`.
|
|
1461
|
+
// The absolute path comes from the install root (project dir or $HOME), so
|
|
1462
|
+
// its POSIX form gets real single-quote escaping (issue #476). The relative
|
|
1463
|
+
// form is a per-provider constant and stays double-quoted, because Claude's
|
|
1464
|
+
// ${CLAUDE_PROJECT_DIR} token must keep expanding at hook time.
|
|
1465
|
+
const relPath = hookScriptRelPathForProvider(provider);
|
|
1466
|
+
const quotedPath = absolute
|
|
1467
|
+
? { posix: shSingleQuote(hookScript), win32: JSON.stringify(hookScript) }
|
|
1468
|
+
: { posix: JSON.stringify(relPath), win32: JSON.stringify(relPath) };
|
|
1469
|
+
|
|
1350
1470
|
if (typeof value === 'string') {
|
|
1351
1471
|
if (!valueHasImpeccableHookMarker(value)) return value;
|
|
1352
|
-
|
|
1353
|
-
if (absolute) {
|
|
1354
|
-
quotedPath = JSON.stringify(hookScript);
|
|
1355
|
-
} else {
|
|
1356
|
-
// Project-scope install: derive the provider's own project-relative path
|
|
1357
|
-
// rather than trusting the bundle token, which for Codex points at
|
|
1358
|
-
// `.codex/skills/...` while the CLI installs the skill at `.agents/skills/`.
|
|
1359
|
-
quotedPath = JSON.stringify(hookScriptRelPathForProvider(provider));
|
|
1360
|
-
}
|
|
1361
|
-
return guardHookCommand(quotedPath);
|
|
1472
|
+
return guardHookCommand(quotedPath, provider);
|
|
1362
1473
|
}
|
|
1363
1474
|
if (Array.isArray(value)) {
|
|
1364
1475
|
return value.map(item => rewriteHookCommandsForSkillRoot(item, provider, { skillRoot, absolute }));
|
|
@@ -1368,6 +1479,9 @@ function rewriteHookCommandsForSkillRoot(value, provider, { skillRoot, absolute
|
|
|
1368
1479
|
for (const [key, child] of Object.entries(value)) {
|
|
1369
1480
|
next[key] = rewriteHookCommandsForSkillRoot(child, provider, { skillRoot, absolute });
|
|
1370
1481
|
}
|
|
1482
|
+
if (provider === '.agents' && typeof value.command === 'string' && valueHasImpeccableHookMarker(value.command)) {
|
|
1483
|
+
next.commandWindows = windowsHookCommand(quotedPath.win32);
|
|
1484
|
+
}
|
|
1371
1485
|
return next;
|
|
1372
1486
|
}
|
|
1373
1487
|
return value;
|
|
@@ -1763,16 +1877,23 @@ async function install(flags) {
|
|
|
1763
1877
|
process.exit(1);
|
|
1764
1878
|
}
|
|
1765
1879
|
|
|
1766
|
-
const { targets, installRoot, hookRoot, scope } = plan;
|
|
1880
|
+
const { targets, installRoot, hookRoot, scope, explicit } = plan;
|
|
1767
1881
|
const existing = isAlreadyInstalled(installRoot, scope);
|
|
1768
|
-
|
|
1769
|
-
|
|
1882
|
+
const installedTargets = existing ? findInstalledProviders(installRoot, scope) : [];
|
|
1883
|
+
// An explicit --providers list is a per-target request: a selected provider
|
|
1884
|
+
// with no install yet gets a fresh install instead of tripping the global
|
|
1885
|
+
// "already installed" early exit (issue #500). When every selected provider
|
|
1886
|
+
// is missing, skip the update branch entirely and take the fresh-install path.
|
|
1887
|
+
const missingSelectedTargets = (existing && !force && explicit)
|
|
1888
|
+
? targets.filter(provider => !installedTargets.includes(provider))
|
|
1889
|
+
: [];
|
|
1890
|
+
|
|
1891
|
+
if (existing && !force && missingSelectedTargets.length < targets.length) {
|
|
1770
1892
|
console.log(`Impeccable skills are already installed (found in ${existing}/).`);
|
|
1771
|
-
const installedTargets = findInstalledProviders(installRoot, scope);
|
|
1772
1893
|
const selectedInstalledTargets = targets.filter(provider => installedTargets.includes(provider));
|
|
1773
1894
|
const linkedTargets = findLinkedProviders(installRoot, selectedInstalledTargets, scope);
|
|
1774
1895
|
const copyTargets = selectedInstalledTargets.filter(provider => !linkedTargets.includes(provider));
|
|
1775
|
-
const hookTargets = selectedInstalledTargets;
|
|
1896
|
+
const hookTargets = [...selectedInstalledTargets, ...missingSelectedTargets];
|
|
1776
1897
|
const wantHooks = installHooks && await decideHookInstall(hookRoot, hookTargets, { yes });
|
|
1777
1898
|
let bundleDir;
|
|
1778
1899
|
try {
|
|
@@ -1787,11 +1908,11 @@ async function install(flags) {
|
|
|
1787
1908
|
? hookTargets.filter(provider => !hookInstalledForProvider(hookRoot, provider))
|
|
1788
1909
|
: [];
|
|
1789
1910
|
let updateCheckSkipped = false;
|
|
1790
|
-
if (copyTargets.length > 0 || missingHookTargets.length > 0) {
|
|
1911
|
+
if (copyTargets.length > 0 || missingHookTargets.length > 0 || missingSelectedTargets.length > 0) {
|
|
1791
1912
|
try {
|
|
1792
1913
|
bundleDir = await downloadAndExtractBundle();
|
|
1793
1914
|
} catch (e) {
|
|
1794
|
-
if (missingHookTargets.length > 0) throw e;
|
|
1915
|
+
if (missingHookTargets.length > 0 || missingSelectedTargets.length > 0) throw e;
|
|
1795
1916
|
updateCheckSkipped = true;
|
|
1796
1917
|
console.log(`Could not check for skill updates: ${e.message}`);
|
|
1797
1918
|
}
|
|
@@ -1805,6 +1926,17 @@ async function install(flags) {
|
|
|
1805
1926
|
console.log(`Updated ${updated} skill(s)${v ? ` to v${v}` : ''}.`);
|
|
1806
1927
|
}
|
|
1807
1928
|
|
|
1929
|
+
let freshWritten = 0;
|
|
1930
|
+
if (!updateCheckSkipped && missingSelectedTargets.length > 0) {
|
|
1931
|
+
freshWritten = copyProviderSkills(bundleDir, installRoot, missingSelectedTargets, { scope });
|
|
1932
|
+
if (freshWritten === 0) {
|
|
1933
|
+
console.error(`Nothing was installed: the bundle had no variants for ${missingSelectedTargets.join(', ')}.`);
|
|
1934
|
+
process.exit(1);
|
|
1935
|
+
}
|
|
1936
|
+
console.log(`Installed impeccable into: ${missingSelectedTargets.join(', ')} (${scope === 'user' ? 'global' : 'project'})`);
|
|
1937
|
+
reportProviderAgents(copyProviderAgents(bundleDir, installRoot, missingSelectedTargets, { scope }));
|
|
1938
|
+
}
|
|
1939
|
+
|
|
1808
1940
|
const writtenHookTargets = missingHookTargets.length > 0
|
|
1809
1941
|
? copyProviderHooks(bundleDir, hookRoot, missingHookTargets, { skillRoot: installRoot })
|
|
1810
1942
|
: [];
|
|
@@ -1813,7 +1945,7 @@ async function install(flags) {
|
|
|
1813
1945
|
if (updateCheckSkipped) {
|
|
1814
1946
|
console.log('Existing skills were left unchanged.');
|
|
1815
1947
|
console.log('Run with --force to reinstall.\n');
|
|
1816
|
-
} else if (updated === 0 && writtenHookTargets.length === 0) {
|
|
1948
|
+
} else if (updated === 0 && writtenHookTargets.length === 0 && freshWritten === 0) {
|
|
1817
1949
|
const v = getSkillsVersion(installRoot, scope);
|
|
1818
1950
|
console.log(`Skills are up to date${v ? ` (v${v})` : ''}.`);
|
|
1819
1951
|
console.log('Run with --force to reinstall.\n');
|
|
@@ -1877,7 +2009,7 @@ async function install(flags) {
|
|
|
1877
2009
|
reportProviderAgents(agentResults);
|
|
1878
2010
|
if (hookTargets.length > 0) console.log(`Installed hooks into: ${hookTargets.join(', ')}`);
|
|
1879
2011
|
|
|
1880
|
-
console.log('\nDone!
|
|
2012
|
+
console.log('\nDone! Now type /impeccable init in your AI coding agent\'s chat (not in this terminal) to set up design context.\n');
|
|
1881
2013
|
}
|
|
1882
2014
|
|
|
1883
2015
|
// ─── skills update ────────────────────────────────────────────────────────────
|
|
@@ -2173,6 +2305,8 @@ export {
|
|
|
2173
2305
|
expectedHookDests,
|
|
2174
2306
|
extractZip,
|
|
2175
2307
|
formatInstallDetectionLines,
|
|
2308
|
+
hermesGlobalHome,
|
|
2309
|
+
HOME_SKILLS_DIR_OVERRIDES,
|
|
2176
2310
|
linkProviderSkills,
|
|
2177
2311
|
mergeHookManifests,
|
|
2178
2312
|
migrateUnprefixImpeccable,
|
|
@@ -683,6 +683,10 @@ if (IS_BROWSER) {
|
|
|
683
683
|
|
|
684
684
|
const reasons = collectVisualContrastReasons(el, style);
|
|
685
685
|
if (reasons.length === 0) continue;
|
|
686
|
+
// Image-only mode filters here, inside the cap: gradient/opacity/filter
|
|
687
|
+
// candidates earlier in DOM order must not consume the budget and
|
|
688
|
+
// starve the url()-backed texts this mode exists to sample.
|
|
689
|
+
if (options.imageOnly && !reasons.includes('image background')) continue;
|
|
686
690
|
|
|
687
691
|
const textColor = parseRgb(style.color);
|
|
688
692
|
const fontSize = parseFloat(style.fontSize) || 16;
|
|
@@ -1175,6 +1179,7 @@ if (IS_BROWSER) {
|
|
|
1175
1179
|
}
|
|
1176
1180
|
|
|
1177
1181
|
async function analyzeVisualContrast(options = {}) {
|
|
1182
|
+
// imageOnly is enforced inside the collector, before the candidate cap.
|
|
1178
1183
|
const candidates = collectVisualContrastCandidates(options);
|
|
1179
1184
|
const results = [];
|
|
1180
1185
|
const shouldScrollOffscreen = options.scrollOffscreen === true;
|
|
@@ -1260,9 +1265,16 @@ if (IS_BROWSER) {
|
|
|
1260
1265
|
|
|
1261
1266
|
function addBrowserFindings(groupMap, el, findings) {
|
|
1262
1267
|
if (!findings || findings.length === 0) return;
|
|
1268
|
+
// Element-scoped waivers: a data-impeccable-ignore ancestor suppresses
|
|
1269
|
+
// matching findings for its whole subtree. Applied at this choke point so
|
|
1270
|
+
// every per-element attribution (checks, layout, occlusion, rhythm)
|
|
1271
|
+
// honors it; page-level findings attributed to <body> pass through
|
|
1272
|
+
// untouched, since body has no ignoring ancestor.
|
|
1273
|
+
const kept = findings.filter(f => !scopedIgnoreActive(el, f.type));
|
|
1274
|
+
if (kept.length === 0) return;
|
|
1263
1275
|
const existing = groupMap.get(el);
|
|
1264
|
-
if (existing) existing.push(...
|
|
1265
|
-
else groupMap.set(el, [...
|
|
1276
|
+
if (existing) existing.push(...kept);
|
|
1277
|
+
else groupMap.set(el, [...kept]);
|
|
1266
1278
|
}
|
|
1267
1279
|
|
|
1268
1280
|
function browserFindingsFromMap(groupMap) {
|
|
@@ -1620,9 +1632,27 @@ if (IS_BROWSER) {
|
|
|
1620
1632
|
for (const node of docClone.querySelectorAll('[id^="impeccable-live-"]')) {
|
|
1621
1633
|
node.remove();
|
|
1622
1634
|
}
|
|
1623
|
-
|
|
1624
|
-
|
|
1625
|
-
|
|
1635
|
+
// Regex findings that name a live selector resolve against the real DOM:
|
|
1636
|
+
// pseudo-element/class segments are stripped (the host element is the
|
|
1637
|
+
// anchor), a selector that matches nothing on this page drops the finding
|
|
1638
|
+
// (the CSS ships here, but the pattern never renders — the live DOM is
|
|
1639
|
+
// ground truth in the browser), and a match under a data-impeccable-ignore
|
|
1640
|
+
// ancestor is waived. Selector-less findings stay page-level.
|
|
1641
|
+
const scopedHtmlFindings = checkHtmlPatterns(docClone.outerHTML).filter(f => {
|
|
1642
|
+
if (!f.selector) return true;
|
|
1643
|
+
const query = String(f.selector).replace(/::?[a-zA-Z-]+(\([^)]*\))?/g, '').trim().replace(/,\s*(?=,|$)/g, '');
|
|
1644
|
+
if (!query || /^[,\s]*$/.test(query)) return true;
|
|
1645
|
+
let matches;
|
|
1646
|
+
try {
|
|
1647
|
+
matches = document.querySelectorAll(query);
|
|
1648
|
+
} catch {
|
|
1649
|
+
return true;
|
|
1650
|
+
}
|
|
1651
|
+
if (matches.length === 0) return false;
|
|
1652
|
+
return [...matches].some(el => !scopedIgnoreActive(el, f.id));
|
|
1653
|
+
});
|
|
1654
|
+
if (scopedHtmlFindings.length > 0) {
|
|
1655
|
+
const mapped = scopedHtmlFindings.map(f => {
|
|
1626
1656
|
const item = { type: f.id, detail: f.snippet };
|
|
1627
1657
|
if (f.severity) {
|
|
1628
1658
|
item.severity = f.severity;
|
|
@@ -1652,8 +1682,27 @@ if (IS_BROWSER) {
|
|
|
1652
1682
|
};
|
|
1653
1683
|
}
|
|
1654
1684
|
|
|
1685
|
+
// Visual contrast has three modes. Explicit true runs the full sampled
|
|
1686
|
+
// pass; explicit false disables it entirely (the deterministic-only mode
|
|
1687
|
+
// the test suites use). Unset — the default overlay run — samples ONLY
|
|
1688
|
+
// image-backed text: the one class the analytic walk deliberately skips,
|
|
1689
|
+
// because a url() layer's pixels are unknowable without looking. In-page
|
|
1690
|
+
// sampling draws the source image alone to a canvas (glyph ink never
|
|
1691
|
+
// pollutes it), and a cross-origin image without CORS reports unresolved
|
|
1692
|
+
// instead of guessing.
|
|
1693
|
+
function visualContrastMode(options = {}) {
|
|
1694
|
+
const explicit = typeof options.visualContrast === 'boolean'
|
|
1695
|
+
? options.visualContrast
|
|
1696
|
+
: typeof window.__IMPECCABLE_CONFIG__?.visualContrast === 'boolean'
|
|
1697
|
+
? window.__IMPECCABLE_CONFIG__.visualContrast
|
|
1698
|
+
: null;
|
|
1699
|
+
if (explicit === true) return 'full';
|
|
1700
|
+
if (explicit === false) return false;
|
|
1701
|
+
return 'image-only';
|
|
1702
|
+
}
|
|
1703
|
+
|
|
1655
1704
|
function shouldRunVisualContrast(options = {}) {
|
|
1656
|
-
return options
|
|
1705
|
+
return visualContrastMode(options) !== false;
|
|
1657
1706
|
}
|
|
1658
1707
|
|
|
1659
1708
|
function visualContrastOptions(options = {}) {
|
|
@@ -1830,6 +1879,7 @@ if (IS_BROWSER) {
|
|
|
1830
1879
|
return [];
|
|
1831
1880
|
}
|
|
1832
1881
|
const resolvedOptions = visualContrastOptions(options);
|
|
1882
|
+
if (visualContrastMode(options) === 'image-only') resolvedOptions.imageOnly = true;
|
|
1833
1883
|
const analyses = await analyzeVisualContrast(resolvedOptions);
|
|
1834
1884
|
if (runtime.generation && runtime.generation !== scanGeneration) return analyses;
|
|
1835
1885
|
lastVisualContrastAnalyses = analyses;
|