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 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 60 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
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
- 60 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
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.12+
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 60 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
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
- 60 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
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.12+
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 60 deterministic detector rules for AI-generated frontend design.
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
- - **60 deterministic detector rules** plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.
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 60 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).
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` for both.
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
- function guardHookCommand(quotedPath) {
1332
- return `[ ! -f ${quotedPath} ] || node ${quotedPath}`;
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 is wrapped with the missing-file guard.
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
- let quotedPath;
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
- if (existing && !force) {
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! Run /impeccable init in your AI harness to set up design context.\n');
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(...findings);
1265
- else groupMap.set(el, [...findings]);
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
- const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
1624
- if (htmlPatternFindings.length > 0) {
1625
- const mapped = htmlPatternFindings.map(f => {
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.visualContrast === true || window.__IMPECCABLE_CONFIG__?.visualContrast === true;
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;