impeccable 3.4.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 +234 -29
- package/cli/engine/browser/injected/index.mjs +56 -6
- package/cli/engine/design-system.mjs +140 -2
- package/cli/engine/detect-antipatterns-browser.js +1174 -694
- package/cli/engine/detect-antipatterns.mjs +1 -0
- package/cli/engine/engines/browser/detect-url.mjs +35 -3
- package/cli/engine/engines/regex/detect-text.mjs +431 -45
- package/cli/engine/engines/static-html/css-cascade.mjs +10 -1
- package/cli/engine/engines/static-html/detect-html.mjs +47 -6
- package/cli/engine/node/file-system.mjs +23 -22
- package/cli/engine/registry/antipatterns.mjs +0 -10
- package/cli/engine/rules/checks.mjs +384 -384
- package/cli/engine/shared/color.mjs +466 -2
- package/cli/lib/download-providers.js +7 -0
- package/cli/lib/impeccable-config.mjs +44 -59
- package/package.json +5 -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,22 +51,24 @@ 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
|
-
'.pi': { name: '
|
|
64
|
+
'.pi': { name: 'Pi Coding Agent', input: 'pi' },
|
|
60
65
|
'.qoder': { name: 'Qoder', input: 'qoder' },
|
|
61
66
|
'.rovodev': { name: 'Rovo Dev', input: 'rovo-dev' },
|
|
62
67
|
'.trae': { name: 'Trae', input: 'trae' },
|
|
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
|
/**
|
|
@@ -1189,6 +1250,71 @@ function copyProviderSkills(bundleDir, root, targets, { scope } = {}) {
|
|
|
1189
1250
|
return written;
|
|
1190
1251
|
}
|
|
1191
1252
|
|
|
1253
|
+
// Native subagent definitions that ship in the bundle next to a provider's
|
|
1254
|
+
// skills. GitHub Copilot's live at `.github/agents/impeccable-*.agent.md`:
|
|
1255
|
+
// project installs commit them at `<repo>/.github/agents/`, user-level
|
|
1256
|
+
// installs go to `~/.copilot/agents/` (Copilot's user-scope dir, NOT
|
|
1257
|
+
// `~/.github/`). On a name conflict Copilot lets the user-level file shadow
|
|
1258
|
+
// the project one, so both paths overwrite existing impeccable-* copies and a
|
|
1259
|
+
// project install reports any same-named user-level agents that would shadow
|
|
1260
|
+
// it. Cursor's live at `.cursor/agents/impeccable-*.md`, user scope
|
|
1261
|
+
// `~/.cursor/agents/`; project agents take precedence there, so no shadow
|
|
1262
|
+
// warning is needed.
|
|
1263
|
+
const PROVIDER_AGENT_ARTIFACTS = {
|
|
1264
|
+
'.github': {
|
|
1265
|
+
ext: '.agent.md',
|
|
1266
|
+
userDir: home => join(home, '.copilot', 'agents'),
|
|
1267
|
+
userShadowsProject: true,
|
|
1268
|
+
},
|
|
1269
|
+
'.cursor': {
|
|
1270
|
+
ext: '.md',
|
|
1271
|
+
userDir: home => join(home, '.cursor', 'agents'),
|
|
1272
|
+
userShadowsProject: false,
|
|
1273
|
+
},
|
|
1274
|
+
};
|
|
1275
|
+
|
|
1276
|
+
function copyProviderAgents(bundleDir, root, providers, { scope, home = homedir() } = {}) {
|
|
1277
|
+
const targets = Array.isArray(providers) ? providers : [providers];
|
|
1278
|
+
const results = [];
|
|
1279
|
+
for (const provider of targets) {
|
|
1280
|
+
const artifact = PROVIDER_AGENT_ARTIFACTS[provider];
|
|
1281
|
+
if (!artifact) continue;
|
|
1282
|
+
const srcDir = join(bundleDir, provider, 'agents');
|
|
1283
|
+
if (!existsSync(srcDir)) continue;
|
|
1284
|
+
const agentFiles = readdirSync(srcDir).filter(name => name.endsWith(artifact.ext));
|
|
1285
|
+
if (agentFiles.length === 0) continue;
|
|
1286
|
+
|
|
1287
|
+
const destDir = scope === 'user'
|
|
1288
|
+
? artifact.userDir(root)
|
|
1289
|
+
: join(root, provider, 'agents');
|
|
1290
|
+
mkdirSync(destDir, { recursive: true });
|
|
1291
|
+
for (const name of agentFiles) {
|
|
1292
|
+
writeFileSync(join(destDir, name), readFileSync(join(srcDir, name)));
|
|
1293
|
+
}
|
|
1294
|
+
|
|
1295
|
+
// A project install can be shadowed by same-named agents in the user-level
|
|
1296
|
+
// dir; surface them so the freshly installed project agents actually apply.
|
|
1297
|
+
const userDir = artifact.userDir(home);
|
|
1298
|
+
const shadowed = artifact.userShadowsProject && scope !== 'user'
|
|
1299
|
+
? agentFiles.filter(name => existsSync(join(userDir, name)))
|
|
1300
|
+
: [];
|
|
1301
|
+
|
|
1302
|
+
results.push({ provider, written: agentFiles.length, destDir, userDir, shadowed });
|
|
1303
|
+
}
|
|
1304
|
+
return results;
|
|
1305
|
+
}
|
|
1306
|
+
|
|
1307
|
+
function reportProviderAgents(results) {
|
|
1308
|
+
for (const result of results || []) {
|
|
1309
|
+
if (result.written === 0) continue;
|
|
1310
|
+
console.log(`Installed ${providerDisplayName(result.provider)} agents into: ${formatPathForDisplay(result.destDir)}`);
|
|
1311
|
+
if (result.shadowed.length > 0) {
|
|
1312
|
+
console.warn(`Warning: user-level agents in ${formatPathForDisplay(result.userDir)} shadow the project copies just installed: ${result.shadowed.join(', ')}.`);
|
|
1313
|
+
console.warn('Run `npx impeccable update --user` to refresh them, or remove them so the project agents apply.');
|
|
1314
|
+
}
|
|
1315
|
+
}
|
|
1316
|
+
}
|
|
1317
|
+
|
|
1192
1318
|
function refreshProviderSkills(bundleDir, root, providers, scope) {
|
|
1193
1319
|
const unique = deduplicateProviders(root, providers, scope);
|
|
1194
1320
|
let updated = 0;
|
|
@@ -1263,8 +1389,53 @@ function hookScriptPathForProvider(skillRoot, provider) {
|
|
|
1263
1389
|
// code when the file exists, so Claude's exit-2 blocking signal still reaches
|
|
1264
1390
|
// the agent. POSIX-shell form, consistent with the project's other hook
|
|
1265
1391
|
// commands (e.g. the GitHub manifest's `$(git rev-parse ...)`).
|
|
1266
|
-
|
|
1267
|
-
|
|
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}`;
|
|
1268
1439
|
}
|
|
1269
1440
|
|
|
1270
1441
|
// Transform bundled hook commands for the actual install target:
|
|
@@ -1275,25 +1446,30 @@ function guardHookCommand(quotedPath) {
|
|
|
1275
1446
|
// when a project hook points at a skill installed elsewhere (--scope=global).
|
|
1276
1447
|
// * otherwise — keep the bundle's own ${CLAUDE_PROJECT_DIR}-relative path,
|
|
1277
1448
|
// which correctly resolves for a project-scoped install.
|
|
1278
|
-
// 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.
|
|
1279
1452
|
function rewriteHookCommandsForSkillRoot(value, provider, { skillRoot, absolute }) {
|
|
1280
1453
|
const hookScript = hookScriptPathForProvider(skillRoot, provider);
|
|
1281
1454
|
// Providers we don't own a `node "PATH"` command hook for (.github, .grok)
|
|
1282
1455
|
// carry their own portable command forms; leave them untouched.
|
|
1283
1456
|
if (!hookScript) return value;
|
|
1284
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
|
+
|
|
1285
1470
|
if (typeof value === 'string') {
|
|
1286
1471
|
if (!valueHasImpeccableHookMarker(value)) return value;
|
|
1287
|
-
|
|
1288
|
-
if (absolute) {
|
|
1289
|
-
quotedPath = JSON.stringify(hookScript);
|
|
1290
|
-
} else {
|
|
1291
|
-
// Project-scope install: derive the provider's own project-relative path
|
|
1292
|
-
// rather than trusting the bundle token, which for Codex points at
|
|
1293
|
-
// `.codex/skills/...` while the CLI installs the skill at `.agents/skills/`.
|
|
1294
|
-
quotedPath = JSON.stringify(hookScriptRelPathForProvider(provider));
|
|
1295
|
-
}
|
|
1296
|
-
return guardHookCommand(quotedPath);
|
|
1472
|
+
return guardHookCommand(quotedPath, provider);
|
|
1297
1473
|
}
|
|
1298
1474
|
if (Array.isArray(value)) {
|
|
1299
1475
|
return value.map(item => rewriteHookCommandsForSkillRoot(item, provider, { skillRoot, absolute }));
|
|
@@ -1303,6 +1479,9 @@ function rewriteHookCommandsForSkillRoot(value, provider, { skillRoot, absolute
|
|
|
1303
1479
|
for (const [key, child] of Object.entries(value)) {
|
|
1304
1480
|
next[key] = rewriteHookCommandsForSkillRoot(child, provider, { skillRoot, absolute });
|
|
1305
1481
|
}
|
|
1482
|
+
if (provider === '.agents' && typeof value.command === 'string' && valueHasImpeccableHookMarker(value.command)) {
|
|
1483
|
+
next.commandWindows = windowsHookCommand(quotedPath.win32);
|
|
1484
|
+
}
|
|
1306
1485
|
return next;
|
|
1307
1486
|
}
|
|
1308
1487
|
return value;
|
|
@@ -1698,16 +1877,23 @@ async function install(flags) {
|
|
|
1698
1877
|
process.exit(1);
|
|
1699
1878
|
}
|
|
1700
1879
|
|
|
1701
|
-
const { targets, installRoot, hookRoot, scope } = plan;
|
|
1880
|
+
const { targets, installRoot, hookRoot, scope, explicit } = plan;
|
|
1702
1881
|
const existing = isAlreadyInstalled(installRoot, scope);
|
|
1703
|
-
|
|
1704
|
-
|
|
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) {
|
|
1705
1892
|
console.log(`Impeccable skills are already installed (found in ${existing}/).`);
|
|
1706
|
-
const installedTargets = findInstalledProviders(installRoot, scope);
|
|
1707
1893
|
const selectedInstalledTargets = targets.filter(provider => installedTargets.includes(provider));
|
|
1708
1894
|
const linkedTargets = findLinkedProviders(installRoot, selectedInstalledTargets, scope);
|
|
1709
1895
|
const copyTargets = selectedInstalledTargets.filter(provider => !linkedTargets.includes(provider));
|
|
1710
|
-
const hookTargets = selectedInstalledTargets;
|
|
1896
|
+
const hookTargets = [...selectedInstalledTargets, ...missingSelectedTargets];
|
|
1711
1897
|
const wantHooks = installHooks && await decideHookInstall(hookRoot, hookTargets, { yes });
|
|
1712
1898
|
let bundleDir;
|
|
1713
1899
|
try {
|
|
@@ -1722,11 +1908,11 @@ async function install(flags) {
|
|
|
1722
1908
|
? hookTargets.filter(provider => !hookInstalledForProvider(hookRoot, provider))
|
|
1723
1909
|
: [];
|
|
1724
1910
|
let updateCheckSkipped = false;
|
|
1725
|
-
if (copyTargets.length > 0 || missingHookTargets.length > 0) {
|
|
1911
|
+
if (copyTargets.length > 0 || missingHookTargets.length > 0 || missingSelectedTargets.length > 0) {
|
|
1726
1912
|
try {
|
|
1727
1913
|
bundleDir = await downloadAndExtractBundle();
|
|
1728
1914
|
} catch (e) {
|
|
1729
|
-
if (missingHookTargets.length > 0) throw e;
|
|
1915
|
+
if (missingHookTargets.length > 0 || missingSelectedTargets.length > 0) throw e;
|
|
1730
1916
|
updateCheckSkipped = true;
|
|
1731
1917
|
console.log(`Could not check for skill updates: ${e.message}`);
|
|
1732
1918
|
}
|
|
@@ -1735,10 +1921,22 @@ async function install(flags) {
|
|
|
1735
1921
|
if (!updateCheckSkipped && copyTargets.length > 0 && !isUpToDate(installRoot, copyTargets, bundleDir, scope)) {
|
|
1736
1922
|
migrateUnprefixImpeccable(installRoot, scope);
|
|
1737
1923
|
updated = refreshProviderSkills(bundleDir, installRoot, copyTargets, scope);
|
|
1924
|
+
reportProviderAgents(copyProviderAgents(bundleDir, installRoot, copyTargets, { scope }));
|
|
1738
1925
|
const v = getSkillsVersion(installRoot, scope);
|
|
1739
1926
|
console.log(`Updated ${updated} skill(s)${v ? ` to v${v}` : ''}.`);
|
|
1740
1927
|
}
|
|
1741
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
|
+
|
|
1742
1940
|
const writtenHookTargets = missingHookTargets.length > 0
|
|
1743
1941
|
? copyProviderHooks(bundleDir, hookRoot, missingHookTargets, { skillRoot: installRoot })
|
|
1744
1942
|
: [];
|
|
@@ -1747,7 +1945,7 @@ async function install(flags) {
|
|
|
1747
1945
|
if (updateCheckSkipped) {
|
|
1748
1946
|
console.log('Existing skills were left unchanged.');
|
|
1749
1947
|
console.log('Run with --force to reinstall.\n');
|
|
1750
|
-
} else if (updated === 0 && writtenHookTargets.length === 0) {
|
|
1948
|
+
} else if (updated === 0 && writtenHookTargets.length === 0 && freshWritten === 0) {
|
|
1751
1949
|
const v = getSkillsVersion(installRoot, scope);
|
|
1752
1950
|
console.log(`Skills are up to date${v ? ` (v${v})` : ''}.`);
|
|
1753
1951
|
console.log('Run with --force to reinstall.\n');
|
|
@@ -1791,8 +1989,10 @@ async function install(flags) {
|
|
|
1791
1989
|
|
|
1792
1990
|
let written = 0;
|
|
1793
1991
|
let hookTargets = [];
|
|
1992
|
+
let agentResults = [];
|
|
1794
1993
|
try {
|
|
1795
1994
|
written = copyProviderSkills(bundleDir, installRoot, targets, { scope });
|
|
1995
|
+
agentResults = copyProviderAgents(bundleDir, installRoot, targets, { scope });
|
|
1796
1996
|
hookTargets = wantHooks ? copyProviderHooks(bundleDir, hookRoot, targets, { force, skillRoot: installRoot }) : [];
|
|
1797
1997
|
} catch (e) {
|
|
1798
1998
|
rmSync(bundleDir, { recursive: true, force: true });
|
|
@@ -1806,9 +2006,10 @@ async function install(flags) {
|
|
|
1806
2006
|
process.exit(1);
|
|
1807
2007
|
}
|
|
1808
2008
|
console.log(`Installed impeccable into: ${targets.join(', ')} (${scope === 'user' ? 'global' : 'project'})`);
|
|
2009
|
+
reportProviderAgents(agentResults);
|
|
1809
2010
|
if (hookTargets.length > 0) console.log(`Installed hooks into: ${hookTargets.join(', ')}`);
|
|
1810
2011
|
|
|
1811
|
-
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');
|
|
1812
2013
|
}
|
|
1813
2014
|
|
|
1814
2015
|
// ─── skills update ────────────────────────────────────────────────────────────
|
|
@@ -2062,6 +2263,7 @@ async function update(flags = []) {
|
|
|
2062
2263
|
if (migrated > 0) console.log('Migrated a prefixed install back to /impeccable (the i- prefix is no longer used).');
|
|
2063
2264
|
|
|
2064
2265
|
const updated = refreshProviderSkills(tmpDir, root, copyProviders, scope);
|
|
2266
|
+
reportProviderAgents(copyProviderAgents(tmpDir, root, copyProviders, { scope }));
|
|
2065
2267
|
const wantHooks = installHooks && await decideHookInstall(root, providers, { yes });
|
|
2066
2268
|
const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, providers, { force }) : [];
|
|
2067
2269
|
|
|
@@ -2096,12 +2298,15 @@ function copyDirSync(src, dest) {
|
|
|
2096
2298
|
// reimplementation in a helper script (which is how bugs slip through).
|
|
2097
2299
|
export {
|
|
2098
2300
|
collectInstallDetections,
|
|
2301
|
+
copyProviderAgents,
|
|
2099
2302
|
copyProviderHooks,
|
|
2100
2303
|
copyProviderSkills,
|
|
2101
2304
|
decideHookInstall,
|
|
2102
2305
|
expectedHookDests,
|
|
2103
2306
|
extractZip,
|
|
2104
2307
|
formatInstallDetectionLines,
|
|
2308
|
+
hermesGlobalHome,
|
|
2309
|
+
HOME_SKILLS_DIR_OVERRIDES,
|
|
2105
2310
|
linkProviderSkills,
|
|
2106
2311
|
mergeHookManifests,
|
|
2107
2312
|
migrateUnprefixImpeccable,
|