impeccable 3.2.1 → 3.3.1
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 +2 -2
- package/README.npm.md +2 -2
- package/README.repo.md +30 -9
- package/cli/bin/commands/ignores.mjs +27 -6
- package/cli/bin/commands/skills.mjs +168 -22
- package/cli/engine/browser/injected/index.mjs +84 -6
- package/cli/engine/cli/main.mjs +143 -26
- package/cli/engine/design-system.mjs +181 -12
- package/cli/engine/detect-antipatterns-browser.js +2877 -138
- package/cli/engine/engines/browser/detect-url.mjs +67 -4
- package/cli/engine/engines/regex/detect-text.mjs +266 -70
- package/cli/engine/engines/static-html/css-cascade.mjs +161 -5
- package/cli/engine/engines/static-html/detect-html.mjs +18 -5
- package/cli/engine/findings.mjs +7 -1
- package/cli/engine/registry/antipatterns.mjs +142 -37
- package/cli/engine/rules/checks.mjs +2706 -127
- package/cli/engine/shared/constants.mjs +11 -0
- package/cli/lib/download-providers.js +2 -0
- package/cli/lib/impeccable-config.mjs +20 -5
- package/package.json +7 -19
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 58 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
|
+
58 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
|
|
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 58 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
|
+
58 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
|
|
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 58 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
|
+
- **58 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
|
|
|
@@ -103,7 +103,7 @@ From the root of your project, run:
|
|
|
103
103
|
npx impeccable install
|
|
104
104
|
```
|
|
105
105
|
|
|
106
|
-
This shows the harness folders it detected (for example `~/.claude`, `~/.codex`, or project-local `.cursor`), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use `--providers=claude,codex,cursor` and `--scope=project|global` to skip those choices in scripts. On Claude Code, Cursor, and
|
|
106
|
+
This shows the harness folders it detected (for example `~/.claude`, `~/.codex`, `~/.grok`, or project-local `.cursor`), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use `--providers=claude,codex,cursor,grok` and `--scope=project|global` to skip those choices in scripts. On Claude Code, Cursor, Codex, GitHub Copilot, and Grok Build, it also installs the provider-native hook manifest for the current project. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, Grok Build, and every other supported tool. Reload your harness afterward.
|
|
107
107
|
|
|
108
108
|
To refresh an existing install, run:
|
|
109
109
|
|
|
@@ -111,7 +111,7 @@ To refresh an existing install, run:
|
|
|
111
111
|
npx impeccable update
|
|
112
112
|
```
|
|
113
113
|
|
|
114
|
-
Codex users should open `/hooks` after install or update and approve the project hook when prompted. Codex tracks trust by hook definition, so updates that change `.codex/hooks.json` can require approval again.
|
|
114
|
+
Codex users should open `/hooks` after install or update and approve the project hook when prompted. Codex tracks trust by hook definition, so updates that change `.codex/hooks.json` can require approval again. Grok Build users need project folder trust (`/hooks-trust` or launch with `--trust`) before `.grok/hooks/` scripts run.
|
|
115
115
|
|
|
116
116
|
### Option 2: Git Submodule
|
|
117
117
|
|
|
@@ -124,7 +124,7 @@ git add .gitmodules .impeccable .claude .cursor
|
|
|
124
124
|
git commit -m "Add Impeccable skills"
|
|
125
125
|
```
|
|
126
126
|
|
|
127
|
-
Use the providers your project needs, for example `claude`, `cursor`, `gemini`, `codex`, `github`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`,
|
|
127
|
+
Use the providers your project needs, for example `claude`, `cursor`, `gemini`, `codex`, `github`, `grok`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`, `rovo-dev`, or `vibe`. The command links individual skill folders from `.impeccable/dist/universal/` and leaves existing real skill directories untouched unless you pass `--force`.
|
|
128
128
|
|
|
129
129
|
To update later:
|
|
130
130
|
|
|
@@ -144,10 +144,10 @@ npx impeccable link --source=.impeccable --providers=claude,cursor
|
|
|
144
144
|
|
|
145
145
|
**Grok Build:**
|
|
146
146
|
```bash
|
|
147
|
-
grok plugin install pbakaus/impeccable --trust
|
|
147
|
+
grok plugin install pbakaus/impeccable#plugin --trust
|
|
148
148
|
```
|
|
149
149
|
|
|
150
|
-
> Grok Build only. Then run `/impeccable init` in a Grok session.
|
|
150
|
+
> Grok Build only. The `#plugin` suffix installs the slim plugin package (skills, agents, and hooks) instead of the full monorepo. Then run `/impeccable init` in a Grok session. Project-scoped installs via `npx impeccable install --providers=grok` also work and write `.grok/skills/` plus `.grok/hooks/impeccable.json`.
|
|
151
151
|
|
|
152
152
|
### Option 4: Download from Website
|
|
153
153
|
|
|
@@ -250,6 +250,26 @@ cp -r dist/qoder/.qoder your-project/
|
|
|
250
250
|
cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/
|
|
251
251
|
```
|
|
252
252
|
|
|
253
|
+
**Mistral Vibe:**
|
|
254
|
+
```bash
|
|
255
|
+
# Project-specific
|
|
256
|
+
cp -r dist/vibe/.vibe your-project/
|
|
257
|
+
|
|
258
|
+
# Or global (applies to all projects)
|
|
259
|
+
cp -r dist/vibe/.vibe/skills/* ~/.vibe/skills/
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
**Grok Build:**
|
|
263
|
+
```bash
|
|
264
|
+
# Project-specific
|
|
265
|
+
cp -r dist/grok/.grok your-project/
|
|
266
|
+
|
|
267
|
+
# Or global (applies to all projects)
|
|
268
|
+
cp -r dist/grok/.grok/skills/* ~/.grok/skills/
|
|
269
|
+
```
|
|
270
|
+
|
|
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
|
+
|
|
253
273
|
## Usage
|
|
254
274
|
|
|
255
275
|
Once installed, every command runs through the single `/impeccable` skill:
|
|
@@ -316,7 +336,7 @@ If an ephemeral file (a screenshot, `config.local.json`) was committed before yo
|
|
|
316
336
|
|
|
317
337
|
## Design hook
|
|
318
338
|
|
|
319
|
-
On Claude Code, GitHub Copilot, Codex, and
|
|
339
|
+
On Claude Code, GitHub Copilot, Codex, Cursor, and Grok Build, `npx impeccable install` and `npx impeccable update` install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code, GitHub Copilot, Codex, and Grok Build surface findings after the edit (and run a deeper pass on Stop where supported). Cursor blocks bad proposed writes before they land.
|
|
320
340
|
|
|
321
341
|
Installed hook surfaces:
|
|
322
342
|
|
|
@@ -357,7 +377,7 @@ npx impeccable ignores add-file "src/legacy/**"
|
|
|
357
377
|
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
|
|
358
378
|
```
|
|
359
379
|
|
|
360
|
-
The detector catches
|
|
380
|
+
The detector catches 49 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).
|
|
361
381
|
|
|
362
382
|
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.
|
|
363
383
|
|
|
@@ -379,6 +399,7 @@ Full detector docs: [impeccable.style/docs/detector](https://impeccable.style/do
|
|
|
379
399
|
- [Trae](https://trae.ai)
|
|
380
400
|
- [Rovo Dev](https://www.atlassian.com/software/rovo)
|
|
381
401
|
- [Qoder](https://qoder.com)
|
|
402
|
+
- [Mistral Vibe](https://docs.mistral.ai/vibe/code/overview)
|
|
382
403
|
|
|
383
404
|
## Community & Ecosystem
|
|
384
405
|
|
|
@@ -78,6 +78,20 @@ function parseScope(args, { allowAll = false } = {}) {
|
|
|
78
78
|
return { local, all, rest };
|
|
79
79
|
}
|
|
80
80
|
|
|
81
|
+
// An empty glob used to be dropped by filter(Boolean), so `--file=` reported
|
|
82
|
+
// success and wrote an entry with no files: the user asked to scope a rule to one
|
|
83
|
+
// file and silently got the project-wide suppression instead. Refuse it.
|
|
84
|
+
function requireGlob(raw, flag) {
|
|
85
|
+
const glob = String(raw ?? '').trim();
|
|
86
|
+
if (!glob) throw new Error(`${flag} requires a non-empty glob`);
|
|
87
|
+
// A following flag is not a glob. `--file --reason "why"` consumed `--reason`
|
|
88
|
+
// as the scope and left the reason text to fold into the value, storing
|
|
89
|
+
// value="* why" files=["--reason"] and reporting success. Same silent-no-op
|
|
90
|
+
// class as an unknown flag folding into the value; refuse it the same way.
|
|
91
|
+
if (glob.startsWith('--')) throw new Error(`${flag} requires a glob, got the flag ${glob}`);
|
|
92
|
+
return glob;
|
|
93
|
+
}
|
|
94
|
+
|
|
81
95
|
function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
|
|
82
96
|
const positionals = [];
|
|
83
97
|
const files = [];
|
|
@@ -93,11 +107,11 @@ function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
|
|
|
93
107
|
reason = arg.slice('--reason='.length).trim();
|
|
94
108
|
} else if (arg === '--file' || arg === '--files') {
|
|
95
109
|
if (i + 1 >= args.length) throw new Error(`${arg} requires a glob`);
|
|
96
|
-
files.push(
|
|
110
|
+
files.push(requireGlob(args[++i], arg));
|
|
97
111
|
} else if (arg.startsWith('--file=')) {
|
|
98
|
-
files.push(arg.slice('--file='.length)
|
|
112
|
+
files.push(requireGlob(arg.slice('--file='.length), '--file'));
|
|
99
113
|
} else if (arg.startsWith('--files=')) {
|
|
100
|
-
files.push(arg.slice('--files='.length)
|
|
114
|
+
files.push(requireGlob(arg.slice('--files='.length), '--files'));
|
|
101
115
|
} else if (arg.startsWith('--')) {
|
|
102
116
|
throw new Error(`Unknown add-value flag: ${arg}`);
|
|
103
117
|
} else {
|
|
@@ -108,7 +122,9 @@ function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
|
|
|
108
122
|
const [rule, ...valueParts] = positionals;
|
|
109
123
|
const value = normalizeIgnoreValue(valueParts.join(' '));
|
|
110
124
|
if (!rule || !value) throw new Error('Pass a rule id and value, e.g. impeccable ignores add-value overused-font Inter');
|
|
111
|
-
|
|
125
|
+
// Sorted: the dedup key compares the files array, so an unsorted scope made
|
|
126
|
+
// `--file b.css --file a.css` a different entry from `--file a.css --file b.css`.
|
|
127
|
+
const scopedFiles = Array.from(new Set(files.filter(Boolean))).sort();
|
|
112
128
|
if (value === '*' && scopedFiles.length === 0 && !allowUnscopedWildcard) {
|
|
113
129
|
throw new Error('Wildcard value ignores must be scoped with --file <glob>.');
|
|
114
130
|
}
|
|
@@ -226,12 +242,14 @@ function addValue(cwd, args) {
|
|
|
226
242
|
if (parsed.reason) existing.reason = parsed.reason;
|
|
227
243
|
if (parsed.files.length) existing.files = parsed.files;
|
|
228
244
|
} else {
|
|
245
|
+
// rule, value, files, createdAt, reason — the same order the normalizers emit,
|
|
246
|
+
// so a fresh entry survives the next write untouched.
|
|
229
247
|
const entry = {
|
|
230
248
|
rule: parsed.rule,
|
|
231
249
|
value: parsed.value,
|
|
232
|
-
createdAt: new Date().toISOString(),
|
|
233
250
|
};
|
|
234
251
|
if (parsed.files.length) entry.files = parsed.files;
|
|
252
|
+
entry.createdAt = new Date().toISOString();
|
|
235
253
|
if (parsed.reason) entry.reason = parsed.reason;
|
|
236
254
|
config.ignoreValues.push(entry);
|
|
237
255
|
}
|
|
@@ -299,7 +317,10 @@ function clear(cwd, args) {
|
|
|
299
317
|
}
|
|
300
318
|
|
|
301
319
|
function ignoreValueKey(entry) {
|
|
302
|
-
|
|
320
|
+
// Sorted: a file scope is a set. Comparing stored order made an on-disk scope
|
|
321
|
+
// miss the sorted argv form, so a re-add duplicated the entry and a remove
|
|
322
|
+
// silently failed. Every key that hashes `files` must sort — there are four.
|
|
323
|
+
const files = Array.isArray(entry.files) && entry.files.length ? [...entry.files].sort().join('\x1f') : '';
|
|
303
324
|
return `${String(entry.rule || '').trim().toLowerCase()}\0${normalizeIgnoreValue(entry.value)}\0${files}`;
|
|
304
325
|
}
|
|
305
326
|
|
|
@@ -23,7 +23,7 @@ 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', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn', '.rovodev'];
|
|
26
|
+
const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.grok', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn', '.rovodev', '.vibe'];
|
|
27
27
|
const PROVIDER_ALIASES = {
|
|
28
28
|
agents: '.agents',
|
|
29
29
|
claude: '.claude',
|
|
@@ -33,6 +33,9 @@ const PROVIDER_ALIASES = {
|
|
|
33
33
|
cursor: '.cursor',
|
|
34
34
|
gemini: '.gemini',
|
|
35
35
|
github: '.github',
|
|
36
|
+
grok: '.grok',
|
|
37
|
+
'grok-build': '.grok',
|
|
38
|
+
xai: '.grok',
|
|
36
39
|
kiro: '.kiro',
|
|
37
40
|
opencode: '.opencode',
|
|
38
41
|
pi: '.pi',
|
|
@@ -41,6 +44,7 @@ const PROVIDER_ALIASES = {
|
|
|
41
44
|
rovodev: '.rovodev',
|
|
42
45
|
trae: '.trae',
|
|
43
46
|
'trae-cn': '.trae-cn',
|
|
47
|
+
vibe: '.vibe',
|
|
44
48
|
};
|
|
45
49
|
|
|
46
50
|
const PROVIDER_DISPLAY = {
|
|
@@ -49,6 +53,7 @@ const PROVIDER_DISPLAY = {
|
|
|
49
53
|
'.cursor': { name: 'Cursor', input: 'cursor' },
|
|
50
54
|
'.gemini': { name: 'Gemini CLI', input: 'gemini' },
|
|
51
55
|
'.github': { name: 'GitHub Copilot', input: 'github' },
|
|
56
|
+
'.grok': { name: 'Grok Build', input: 'grok' },
|
|
52
57
|
'.kiro': { name: 'Kiro', input: 'kiro' },
|
|
53
58
|
'.opencode': { name: 'OpenCode', input: 'opencode' },
|
|
54
59
|
'.pi': { name: 'Project Indigo', input: 'pi' },
|
|
@@ -56,8 +61,9 @@ const PROVIDER_DISPLAY = {
|
|
|
56
61
|
'.rovodev': { name: 'Rovo Dev', input: 'rovo-dev' },
|
|
57
62
|
'.trae': { name: 'Trae', input: 'trae' },
|
|
58
63
|
'.trae-cn': { name: 'Trae CN', input: 'trae-cn' },
|
|
64
|
+
'.vibe': { name: 'Mistral Vibe', input: 'vibe' },
|
|
59
65
|
};
|
|
60
|
-
const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev'];
|
|
66
|
+
const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'grok', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev', 'vibe'];
|
|
61
67
|
|
|
62
68
|
// Providers whose GLOBAL (home) skills dir is not `<provider>/skills`.
|
|
63
69
|
// Pi discovers global skills from ~/.pi/agent/skills/; project scope
|
|
@@ -74,11 +80,13 @@ const GLOBAL_HARNESS_HINTS = [
|
|
|
74
80
|
{ home: '.codex', provider: '.agents' },
|
|
75
81
|
{ home: '.cursor', provider: '.cursor' },
|
|
76
82
|
{ home: '.gemini', provider: '.gemini' },
|
|
83
|
+
{ home: '.grok', provider: '.grok' },
|
|
77
84
|
{ home: '.kiro', provider: '.kiro' },
|
|
78
85
|
{ home: '.opencode', provider: '.opencode' },
|
|
79
86
|
{ home: '.pi', provider: '.pi' },
|
|
80
87
|
{ home: '.qoder', provider: '.qoder' },
|
|
81
88
|
{ home: '.rovodev', provider: '.rovodev' },
|
|
89
|
+
{ home: '.vibe', provider: '.vibe' },
|
|
82
90
|
];
|
|
83
91
|
|
|
84
92
|
// Last-resort default when nothing is detected: Claude Code + the universal
|
|
@@ -117,6 +125,12 @@ const PROVIDER_HOOK_ARTIFACTS = {
|
|
|
117
125
|
'.github': [
|
|
118
126
|
{ sourceProvider: '.github', rel: 'hooks/impeccable.json', destProvider: '.github' },
|
|
119
127
|
],
|
|
128
|
+
// Grok Build discovers project hooks from `.grok/hooks/*.json`. Team-shared
|
|
129
|
+
// by default (commit them if the whole team uses Grok); folder trust is still
|
|
130
|
+
// required via `/hooks-trust` or `--trust` before they run.
|
|
131
|
+
'.grok': [
|
|
132
|
+
{ sourceProvider: '.grok', rel: 'hooks/impeccable.json', destProvider: '.grok' },
|
|
133
|
+
],
|
|
120
134
|
};
|
|
121
135
|
|
|
122
136
|
function userProviderSkillsDir(home, provider) {
|
|
@@ -568,7 +582,7 @@ async function copyOrExtractLocalBundle(sourceValue) {
|
|
|
568
582
|
*/
|
|
569
583
|
function normalizeForHash(content) {
|
|
570
584
|
return content
|
|
571
|
-
.replace(/\.(claude|cursor|agents|github|gemini|codex|kiro|opencode|pi|qoder|trae|trae-cn|rovodev)\/skills\//g, '.PROVIDER/skills/');
|
|
585
|
+
.replace(/\.(claude|cursor|agents|github|gemini|codex|grok|kiro|opencode|pi|qoder|trae|trae-cn|rovodev|vibe)\/skills\//g, '.PROVIDER/skills/');
|
|
572
586
|
}
|
|
573
587
|
|
|
574
588
|
function hashSkillFile(filePath) {
|
|
@@ -1181,21 +1195,52 @@ function hookScriptPathForProvider(skillRoot, provider) {
|
|
|
1181
1195
|
return null;
|
|
1182
1196
|
}
|
|
1183
1197
|
|
|
1184
|
-
|
|
1198
|
+
// Wrap a `node "PATH"` hook command so a missing skill file is a silent no-op
|
|
1199
|
+
// (exit 0) instead of a Node module-resolution crash. hook.mjs promises to
|
|
1200
|
+
// "never break a turn. Always exit 0.", but that only holds once Node can load
|
|
1201
|
+
// the file; a stale/missing path crashes before any of that logic runs. The
|
|
1202
|
+
// `[ ! -f X ] || node X` form (NOT `... || true`) preserves Node's own exit
|
|
1203
|
+
// code when the file exists, so Claude's exit-2 blocking signal still reaches
|
|
1204
|
+
// the agent. POSIX-shell form, consistent with the project's other hook
|
|
1205
|
+
// commands (e.g. the GitHub manifest's `$(git rev-parse ...)`).
|
|
1206
|
+
function guardHookCommand(quotedPath) {
|
|
1207
|
+
return `[ ! -f ${quotedPath} ] || node ${quotedPath}`;
|
|
1208
|
+
}
|
|
1209
|
+
|
|
1210
|
+
// Transform bundled hook commands for the actual install target:
|
|
1211
|
+
// * absolute — rewrite the (marker) command to the resolved absolute skill
|
|
1212
|
+
// path. Required when the manifest is a user/global file (~/.claude/
|
|
1213
|
+
// settings.local.json) that fires in EVERY project, so ${CLAUDE_PROJECT_DIR}
|
|
1214
|
+
// would resolve per-project to dirs without a skill copy (issue #399); also
|
|
1215
|
+
// when a project hook points at a skill installed elsewhere (--scope=global).
|
|
1216
|
+
// * otherwise — keep the bundle's own ${CLAUDE_PROJECT_DIR}-relative path,
|
|
1217
|
+
// which correctly resolves for a project-scoped install.
|
|
1218
|
+
// Either way the command is wrapped with the missing-file guard.
|
|
1219
|
+
function rewriteHookCommandsForSkillRoot(value, provider, { skillRoot, absolute }) {
|
|
1185
1220
|
const hookScript = hookScriptPathForProvider(skillRoot, provider);
|
|
1221
|
+
// Providers we don't own a `node "PATH"` command hook for (.github, .grok)
|
|
1222
|
+
// carry their own portable command forms; leave them untouched.
|
|
1186
1223
|
if (!hookScript) return value;
|
|
1187
1224
|
|
|
1188
1225
|
if (typeof value === 'string') {
|
|
1189
|
-
if (valueHasImpeccableHookMarker(value)) return
|
|
1190
|
-
|
|
1226
|
+
if (!valueHasImpeccableHookMarker(value)) return value;
|
|
1227
|
+
let quotedPath;
|
|
1228
|
+
if (absolute) {
|
|
1229
|
+
quotedPath = JSON.stringify(hookScript);
|
|
1230
|
+
} else {
|
|
1231
|
+
// Preserve the bundle's own path token (e.g. ${CLAUDE_PROJECT_DIR}/...).
|
|
1232
|
+
const match = value.match(/"([^"]+)"/);
|
|
1233
|
+
quotedPath = match ? JSON.stringify(match[1]) : JSON.stringify(hookScript);
|
|
1234
|
+
}
|
|
1235
|
+
return guardHookCommand(quotedPath);
|
|
1191
1236
|
}
|
|
1192
1237
|
if (Array.isArray(value)) {
|
|
1193
|
-
return value.map(item => rewriteHookCommandsForSkillRoot(item, provider, skillRoot));
|
|
1238
|
+
return value.map(item => rewriteHookCommandsForSkillRoot(item, provider, { skillRoot, absolute }));
|
|
1194
1239
|
}
|
|
1195
1240
|
if (value && typeof value === 'object') {
|
|
1196
1241
|
const next = {};
|
|
1197
1242
|
for (const [key, child] of Object.entries(value)) {
|
|
1198
|
-
next[key] = rewriteHookCommandsForSkillRoot(child, provider, skillRoot);
|
|
1243
|
+
next[key] = rewriteHookCommandsForSkillRoot(child, provider, { skillRoot, absolute });
|
|
1199
1244
|
}
|
|
1200
1245
|
return next;
|
|
1201
1246
|
}
|
|
@@ -1377,9 +1422,14 @@ function copyProviderHooks(bundleDir, root, providers, { force = false, skillRoo
|
|
|
1377
1422
|
}
|
|
1378
1423
|
|
|
1379
1424
|
const freshManifest = readJsonFile(src, 'Bundled hook manifest');
|
|
1380
|
-
|
|
1381
|
-
|
|
1382
|
-
|
|
1425
|
+
// Rewrite to an absolute skill path when the skill lives elsewhere than
|
|
1426
|
+
// this manifest's root (--scope=global project hook) OR when the manifest
|
|
1427
|
+
// itself is a user/global file. A global settings file fires in every
|
|
1428
|
+
// project, so ${CLAUDE_PROJECT_DIR} there crashes Node wherever no local
|
|
1429
|
+
// skill copy exists (issue #399); the resolved absolute path is correct
|
|
1430
|
+
// for the one global skill it targets.
|
|
1431
|
+
const absolute = skillRoot !== root || isHomeDir(root);
|
|
1432
|
+
const fresh = rewriteHookCommandsForSkillRoot(freshManifest, provider, { skillRoot, absolute });
|
|
1383
1433
|
let next = fresh;
|
|
1384
1434
|
|
|
1385
1435
|
if (existsSync(dest)) {
|
|
@@ -1727,6 +1777,67 @@ function findInstalledProviders(root, scope) {
|
|
|
1727
1777
|
return found;
|
|
1728
1778
|
}
|
|
1729
1779
|
|
|
1780
|
+
// Like findInstalledProviders, but only counts a provider whose skills dir
|
|
1781
|
+
// actually holds the IMPECCABLE skill (canonical, prefixed, or legacy teach-).
|
|
1782
|
+
// `update` uses this so it never mistakes a repo that vendors OTHER first-party
|
|
1783
|
+
// skills under .claude/skills for an impeccable install and drops a copy in
|
|
1784
|
+
// (issue #399, part 2).
|
|
1785
|
+
function findImpeccableProviders(root, scope) {
|
|
1786
|
+
const found = [];
|
|
1787
|
+
for (const d of PROVIDER_DIRS) {
|
|
1788
|
+
for (const skillsDir of existingSkillsDirs(root, d, scope)) {
|
|
1789
|
+
let entries;
|
|
1790
|
+
try { entries = readdirSync(skillsDir); } catch { continue; }
|
|
1791
|
+
if (entries.some(e =>
|
|
1792
|
+
e === 'impeccable' || e.endsWith('-impeccable') ||
|
|
1793
|
+
e === 'teach-impeccable' || e.endsWith('-teach-impeccable')
|
|
1794
|
+
)) {
|
|
1795
|
+
found.push(d);
|
|
1796
|
+
break;
|
|
1797
|
+
}
|
|
1798
|
+
}
|
|
1799
|
+
}
|
|
1800
|
+
return found;
|
|
1801
|
+
}
|
|
1802
|
+
|
|
1803
|
+
// Resolve which install `skills update` should refresh: project-level (the CWD's
|
|
1804
|
+
// git root) or user-level (~/.claude etc.). Returns a plain descriptor; the
|
|
1805
|
+
// caller handles the interactive both-exist prompt via `ambiguous`.
|
|
1806
|
+
function resolveUpdateTarget({ projectRoot, home, explicitScope }) {
|
|
1807
|
+
// A home-rooted repo (a dotfiles checkout at $HOME) overlaps project and user
|
|
1808
|
+
// installs under one root; keep the historical unscoped scan so overlapping
|
|
1809
|
+
// layouts (e.g. Pi's ~/.pi/skills and ~/.pi/agent/skills) both refresh.
|
|
1810
|
+
const homeRooted = isHomeDir(projectRoot);
|
|
1811
|
+
if (homeRooted && !explicitScope) {
|
|
1812
|
+
const providers = findInstalledProviders(home);
|
|
1813
|
+
return providers.length ? { root: home, scope: undefined, providers, scopeLabel: 'user level' } : null;
|
|
1814
|
+
}
|
|
1815
|
+
|
|
1816
|
+
const projectProviders = homeRooted ? [] : findImpeccableProviders(projectRoot, 'project');
|
|
1817
|
+
const userProviders = findImpeccableProviders(home, 'user');
|
|
1818
|
+
|
|
1819
|
+
if (explicitScope === 'user') {
|
|
1820
|
+
return userProviders.length
|
|
1821
|
+
? { root: home, scope: 'user', providers: userProviders, scopeLabel: 'user level' }
|
|
1822
|
+
: null;
|
|
1823
|
+
}
|
|
1824
|
+
if (explicitScope === 'project') {
|
|
1825
|
+
return projectProviders.length
|
|
1826
|
+
? { root: projectRoot, scope: 'project', providers: projectProviders, scopeLabel: 'this project' }
|
|
1827
|
+
: null;
|
|
1828
|
+
}
|
|
1829
|
+
if (projectProviders.length && userProviders.length) {
|
|
1830
|
+
return { ambiguous: true, projectRoot, home, projectProviders, userProviders };
|
|
1831
|
+
}
|
|
1832
|
+
if (projectProviders.length) {
|
|
1833
|
+
return { root: projectRoot, scope: 'project', providers: projectProviders, scopeLabel: 'this project' };
|
|
1834
|
+
}
|
|
1835
|
+
if (userProviders.length) {
|
|
1836
|
+
return { root: home, scope: 'user', providers: userProviders, scopeLabel: 'user level' };
|
|
1837
|
+
}
|
|
1838
|
+
return null;
|
|
1839
|
+
}
|
|
1840
|
+
|
|
1730
1841
|
function findLinkedProviders(root, providers, scope) {
|
|
1731
1842
|
return providers.filter(provider => {
|
|
1732
1843
|
for (const skillsDir of providerSkillsDirCandidates(root, provider, scope)) {
|
|
@@ -1786,21 +1897,56 @@ async function update(flags = []) {
|
|
|
1786
1897
|
const yes = flags.includes('-y') || flags.includes('--yes');
|
|
1787
1898
|
const force = flags.includes('--force');
|
|
1788
1899
|
const installHooks = !flags.includes('--no-hooks');
|
|
1900
|
+
const scopeValue = getInstallScopeValue(flags);
|
|
1901
|
+
const explicitScope = normalizeInstallScope(scopeValue);
|
|
1902
|
+
if (scopeValue && !explicitScope) {
|
|
1903
|
+
console.error(`Unknown update scope: ${scopeValue}. Use --project or --user.`);
|
|
1904
|
+
process.exit(1);
|
|
1905
|
+
}
|
|
1789
1906
|
|
|
1790
1907
|
// Download the latest skills directly from impeccable.style.
|
|
1791
1908
|
// We skip `npx skills update` because it has a known upstream bug
|
|
1792
1909
|
// (vercel-labs/skills#775) where it can't find the lock file.
|
|
1793
|
-
const
|
|
1794
|
-
const
|
|
1795
|
-
const linkedProviders = findLinkedProviders(root, providers);
|
|
1796
|
-
const copyProviders = providers.filter(provider => !linkedProviders.includes(provider));
|
|
1910
|
+
const projectRoot = findProjectRoot();
|
|
1911
|
+
const home = homedir();
|
|
1797
1912
|
|
|
1798
|
-
|
|
1799
|
-
|
|
1913
|
+
let target = resolveUpdateTarget({ projectRoot, home, explicitScope });
|
|
1914
|
+
if (!target) {
|
|
1915
|
+
if (explicitScope) {
|
|
1916
|
+
const where = explicitScope === 'user' ? `user level (${formatPathForDisplay(home)})` : `this project (${projectRoot})`;
|
|
1917
|
+
console.log(`No impeccable skill folders found at the ${where}.`);
|
|
1918
|
+
} else {
|
|
1919
|
+
console.log('No impeccable skill folders found in this project or at the user level.');
|
|
1920
|
+
}
|
|
1800
1921
|
console.log('Run `npx impeccable install` to install first.');
|
|
1801
1922
|
process.exit(1);
|
|
1802
1923
|
}
|
|
1803
1924
|
|
|
1925
|
+
// Both a project and a user-level install exist and no scope was given. Never
|
|
1926
|
+
// silently pick (issue #399, part 2): prompt when interactive, else default to
|
|
1927
|
+
// the project and say how to target the other.
|
|
1928
|
+
if (target.ambiguous) {
|
|
1929
|
+
console.log('Impeccable is installed both here and at the user level:');
|
|
1930
|
+
console.log(` project ${projectRoot} (${target.projectProviders.join(', ')})`);
|
|
1931
|
+
console.log(` user level ${formatPathForDisplay(home)} (${target.userProviders.join(', ')})`);
|
|
1932
|
+
let pickUser = false;
|
|
1933
|
+
if (!yes && process.stdin.isTTY) {
|
|
1934
|
+
const ans = await ask('Update which? [project]/user: ');
|
|
1935
|
+
pickUser = ['user', 'u', 'global', 'home'].includes(ans);
|
|
1936
|
+
} else {
|
|
1937
|
+
console.log('Defaulting to the project. Re-run with --user to update the user-level install instead.');
|
|
1938
|
+
}
|
|
1939
|
+
target = pickUser
|
|
1940
|
+
? { root: home, scope: 'user', providers: target.userProviders, scopeLabel: 'user level' }
|
|
1941
|
+
: { root: projectRoot, scope: 'project', providers: target.projectProviders, scopeLabel: 'this project' };
|
|
1942
|
+
}
|
|
1943
|
+
|
|
1944
|
+
const { root, scope } = target;
|
|
1945
|
+
console.log(`Updating the ${target.scopeLabel} install: ${formatPathForDisplay(root)} (${target.providers.join(', ')})`);
|
|
1946
|
+
const providers = target.providers;
|
|
1947
|
+
const linkedProviders = findLinkedProviders(root, providers, scope);
|
|
1948
|
+
const copyProviders = providers.filter(provider => !linkedProviders.includes(provider));
|
|
1949
|
+
|
|
1804
1950
|
if (linkedProviders.length > 0) {
|
|
1805
1951
|
console.log(`Linked skills found in: ${linkedProviders.join(', ')}`);
|
|
1806
1952
|
console.log('Update the source checkout with `git submodule update --remote`, then rerun `npx impeccable link --source=.impeccable` if new skills are added.');
|
|
@@ -1819,12 +1965,12 @@ async function update(flags = []) {
|
|
|
1819
1965
|
}
|
|
1820
1966
|
|
|
1821
1967
|
// Compare local vs remote -- skip if already up to date
|
|
1822
|
-
if (isUpToDate(root, copyProviders, tmpDir)) {
|
|
1968
|
+
if (isUpToDate(root, copyProviders, tmpDir, scope)) {
|
|
1823
1969
|
try {
|
|
1824
1970
|
const wantHooks = installHooks && await decideHookInstall(root, copyProviders, { yes });
|
|
1825
1971
|
const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, copyProviders, { force }) : [];
|
|
1826
1972
|
rmSync(tmpDir, { recursive: true, force: true });
|
|
1827
|
-
const v = getSkillsVersion(root);
|
|
1973
|
+
const v = getSkillsVersion(root, scope);
|
|
1828
1974
|
console.log(`Skills are up to date${v ? ` (v${v})` : ''}.`);
|
|
1829
1975
|
if (hookTargets.length > 0) console.log(`Installed hooks into: ${hookTargets.join(', ')}`);
|
|
1830
1976
|
console.log('Nothing else to do.');
|
|
@@ -1851,16 +1997,16 @@ async function update(flags = []) {
|
|
|
1851
1997
|
|
|
1852
1998
|
// Retire any old `i-`-prefixed install up front so the refresh lands on the
|
|
1853
1999
|
// canonical `impeccable` dir rather than orphaning the prefixed copy.
|
|
1854
|
-
const migrated = migrateUnprefixImpeccable(root);
|
|
2000
|
+
const migrated = migrateUnprefixImpeccable(root, scope);
|
|
1855
2001
|
if (migrated > 0) console.log('Migrated a prefixed install back to /impeccable (the i- prefix is no longer used).');
|
|
1856
2002
|
|
|
1857
|
-
const updated = refreshProviderSkills(tmpDir, root, copyProviders);
|
|
2003
|
+
const updated = refreshProviderSkills(tmpDir, root, copyProviders, scope);
|
|
1858
2004
|
const wantHooks = installHooks && await decideHookInstall(root, providers, { yes });
|
|
1859
2005
|
const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, providers, { force }) : [];
|
|
1860
2006
|
|
|
1861
2007
|
rmSync(tmpDir, { recursive: true, force: true });
|
|
1862
2008
|
|
|
1863
|
-
const v = getSkillsVersion(root);
|
|
2009
|
+
const v = getSkillsVersion(root, scope);
|
|
1864
2010
|
console.log(`Updated ${updated} skill(s)${v ? ` to v${v}` : ''}.`);
|
|
1865
2011
|
if (hookTargets.length > 0) console.log(`Installed hooks into: ${hookTargets.join(', ')}`);
|
|
1866
2012
|
console.log('Done!\n');
|