impeccable 3.1.0 → 3.2.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 +3 -3
- package/README.npm.md +3 -3
- package/README.repo.md +64 -7
- package/cli/bin/commands/skills.mjs +169 -77
- package/cli/engine/cli/main.mjs +31 -0
- package/cli/engine/design-system.mjs +64 -0
- package/cli/engine/detect-antipatterns-browser.js +115 -8
- package/cli/engine/engines/regex/detect-text.mjs +13 -8
- package/cli/engine/registry/antipatterns.mjs +66 -0
- package/cli/engine/rules/checks.mjs +40 -8
- package/cli/engine/shared/fonts.mjs +30 -0
- package/cli/lib/impeccable-config.mjs +4 -2
- package/package.json +9 -9
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 46 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
|
+
46 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
|
|
78
|
+
- Node.js 22.12+
|
|
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 46 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
|
+
46 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
|
|
78
|
+
- Node.js 22.12+
|
|
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 46 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
|
+
- **46 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
|
|
|
@@ -91,7 +91,7 @@ The skill includes explicit guidance on what to avoid:
|
|
|
91
91
|
|
|
92
92
|
## See It In Action
|
|
93
93
|
|
|
94
|
-
Visit [
|
|
94
|
+
Visit [the Neo Mirai case study](https://impeccable.style/cases/neo-mirai) to see a before/after case study of a real project transformed with Impeccable commands.
|
|
95
95
|
|
|
96
96
|
## Installation
|
|
97
97
|
|
|
@@ -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 Codex, it also installs the provider-native hook manifest for the current project. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, and every other supported tool. Reload your harness afterward.
|
|
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 Codex, 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
|
|
|
@@ -133,11 +133,27 @@ git submodule update --remote .impeccable
|
|
|
133
133
|
npx impeccable link --source=.impeccable --providers=claude,cursor
|
|
134
134
|
```
|
|
135
135
|
|
|
136
|
-
### Option 3:
|
|
136
|
+
### Option 3: Plugin install
|
|
137
|
+
|
|
138
|
+
**Claude Code:**
|
|
139
|
+
```bash
|
|
140
|
+
/plugin marketplace add pbakaus/impeccable
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
> Claude Code only. After adding the marketplace, open `/plugin` and install Impeccable from the list.
|
|
144
|
+
|
|
145
|
+
**Grok Build:**
|
|
146
|
+
```bash
|
|
147
|
+
grok plugin install pbakaus/impeccable --trust
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
> Grok Build only. Then run `/impeccable init` in a Grok session.
|
|
151
|
+
|
|
152
|
+
### Option 4: Download from Website
|
|
137
153
|
|
|
138
154
|
Visit [impeccable.style](https://impeccable.style), download the ZIP for your tool, and extract to your project.
|
|
139
155
|
|
|
140
|
-
### Option
|
|
156
|
+
### Option 5: Copy from Repository
|
|
141
157
|
|
|
142
158
|
**Cursor:**
|
|
143
159
|
```bash
|
|
@@ -258,6 +274,46 @@ If you reach for one command often, pin it with `/impeccable pin audit` to get `
|
|
|
258
274
|
|
|
259
275
|
**Note:** Codex uses skills here, not `/prompts:` commands. Open `/skills` or type `$impeccable`. Repo-local installs live in `.agents/skills/`; user-wide installs live in `~/.agents/skills/`. GitHub Copilot uses `.github/skills/`. Restart the tool if a newly installed skill does not appear.
|
|
260
276
|
|
|
277
|
+
## Keeping `.impeccable` out of git
|
|
278
|
+
|
|
279
|
+
As you run commands, Impeccable writes working files under `.impeccable/`: critique and polish screenshots, live-mode session and preview state, runtime caches, and per-developer config. Most of it is ephemeral and should not be committed, while a few files are shared project artifacts that belong in the repo. Add this block to your project's `.gitignore`:
|
|
280
|
+
|
|
281
|
+
```gitignore
|
|
282
|
+
# impeccable-ignore-start
|
|
283
|
+
# Ephemeral output, runtime state, and per-dev overrides.
|
|
284
|
+
# Unanchored: .impeccable may sit at the repo root or under a nested
|
|
285
|
+
# workspace (apps/web/.impeccable/...); anchored patterns would miss it.
|
|
286
|
+
# Shared artifacts stay tracked: config.json, live/config.json,
|
|
287
|
+
# design.json, critique/*.md.
|
|
288
|
+
.impeccable/config.local.json
|
|
289
|
+
.impeccable/hook.cache.json
|
|
290
|
+
.impeccable/hook.pending.json
|
|
291
|
+
.impeccable/*.png
|
|
292
|
+
.impeccable/live/server.json
|
|
293
|
+
.impeccable/live/sessions/
|
|
294
|
+
.impeccable/live/previews/
|
|
295
|
+
.impeccable/live/annotations/
|
|
296
|
+
.impeccable/live/cache/
|
|
297
|
+
.impeccable/live/manual-edit-apply-transaction.json
|
|
298
|
+
.impeccable/live/manual-edit-events.jsonl
|
|
299
|
+
.impeccable/live/manual-edit-evidence/
|
|
300
|
+
.impeccable/live/pending-manual-edits.json
|
|
301
|
+
.impeccable/live/deferred-svelte-component-accepts.json
|
|
302
|
+
.impeccable/live/*.png
|
|
303
|
+
# impeccable-ignore-end
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
The block is wrapped in `# impeccable-ignore-start` / `# impeccable-ignore-end` markers so you can recognize and refresh it later. Patterns are unanchored on purpose: in a monorepo the active project (and its `.impeccable/` directory) often lives under a nested workspace path like `apps/web/`, and a root-anchored pattern would miss it.
|
|
307
|
+
|
|
308
|
+
**Keep these tracked** (they are shared project artifacts, do not add them to `.gitignore`):
|
|
309
|
+
|
|
310
|
+
- `.impeccable/config.json` (unified shared config)
|
|
311
|
+
- `.impeccable/live/config.json` (live-mode framework wiring)
|
|
312
|
+
- `.impeccable/design.json` (shared design spec)
|
|
313
|
+
- `.impeccable/critique/*.md` (review reports)
|
|
314
|
+
|
|
315
|
+
If an ephemeral file (a screenshot, `config.local.json`) was committed before you added the block, `.gitignore` will not untrack it automatically. Run `git rm --cached <path>` to stop tracking it without deleting your local copy.
|
|
316
|
+
|
|
261
317
|
## Design hook
|
|
262
318
|
|
|
263
319
|
On Claude Code, GitHub Copilot, Codex, and Cursor, `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, and Codex surface findings after the edit. Cursor blocks bad proposed writes before they land.
|
|
@@ -301,7 +357,7 @@ npx impeccable ignores add-file "src/legacy/**"
|
|
|
301
357
|
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
|
|
302
358
|
```
|
|
303
359
|
|
|
304
|
-
The detector catches
|
|
360
|
+
The detector catches 46 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).
|
|
305
361
|
|
|
306
362
|
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.
|
|
307
363
|
|
|
@@ -316,6 +372,7 @@ Full detector docs: [impeccable.style/docs/detector](https://impeccable.style/do
|
|
|
316
372
|
- [GitHub Copilot](https://github.com/features/copilot)
|
|
317
373
|
- [Gemini CLI](https://github.com/google-gemini/gemini-cli)
|
|
318
374
|
- [Codex CLI](https://github.com/openai/codex)
|
|
375
|
+
- [Grok Build](https://x.ai/cli)
|
|
319
376
|
- [OpenCode](https://opencode.ai)
|
|
320
377
|
- [Pi](https://pi.dev)
|
|
321
378
|
- [Kiro](https://kiro.dev)
|
|
@@ -59,6 +59,13 @@ const PROVIDER_DISPLAY = {
|
|
|
59
59
|
};
|
|
60
60
|
const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev'];
|
|
61
61
|
|
|
62
|
+
// Providers whose GLOBAL (home) skills dir is not `<provider>/skills`.
|
|
63
|
+
// Pi discovers global skills from ~/.pi/agent/skills/; project scope
|
|
64
|
+
// stays .pi/skills/. See issue #327.
|
|
65
|
+
const HOME_SKILLS_DIR_OVERRIDES = {
|
|
66
|
+
'.pi': join('.pi', 'agent', 'skills'),
|
|
67
|
+
};
|
|
68
|
+
|
|
62
69
|
// When a project has no harness folder yet, infer the target from globally
|
|
63
70
|
// installed harnesses (~/.claude, ~/.codex, ...). Codex reads skills from
|
|
64
71
|
// .agents/skills, so ~/.codex maps to the .agents bundle variant.
|
|
@@ -69,6 +76,7 @@ const GLOBAL_HARNESS_HINTS = [
|
|
|
69
76
|
{ home: '.gemini', provider: '.gemini' },
|
|
70
77
|
{ home: '.kiro', provider: '.kiro' },
|
|
71
78
|
{ home: '.opencode', provider: '.opencode' },
|
|
79
|
+
{ home: '.pi', provider: '.pi' },
|
|
72
80
|
{ home: '.qoder', provider: '.qoder' },
|
|
73
81
|
{ home: '.rovodev', provider: '.rovodev' },
|
|
74
82
|
];
|
|
@@ -111,6 +119,45 @@ const PROVIDER_HOOK_ARTIFACTS = {
|
|
|
111
119
|
],
|
|
112
120
|
};
|
|
113
121
|
|
|
122
|
+
function userProviderSkillsDir(home, provider) {
|
|
123
|
+
if (HOME_SKILLS_DIR_OVERRIDES[provider]) return join(home, HOME_SKILLS_DIR_OVERRIDES[provider]);
|
|
124
|
+
return join(home, provider, 'skills');
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
// Compare via realpath: the project root comes from process.cwd() (symlinks
|
|
128
|
+
// resolved) while homedir() reflects $HOME verbatim, so a home dir reached
|
|
129
|
+
// through a symlink (e.g. /tmp -> /private/tmp) would fail a string compare.
|
|
130
|
+
function isHomeDir(root) {
|
|
131
|
+
if (root === homedir()) return true;
|
|
132
|
+
try {
|
|
133
|
+
return realpathSync(root) === realpathSync(homedir());
|
|
134
|
+
} catch {
|
|
135
|
+
return false;
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
// Every layout a provider's installed skills can live in under `root`.
|
|
140
|
+
// `scope` narrows the answer when the caller knows which install it is
|
|
141
|
+
// acting on: 'user' means the provider's global layout, 'project' means
|
|
142
|
+
// `<provider>/skills`. Without a scope (update/check, where installs of
|
|
143
|
+
// either kind may live under `root`) both layouts are candidates when
|
|
144
|
+
// `root` is the home dir, since an overridden provider (Pi) keeps its
|
|
145
|
+
// global skills elsewhere while a repo rooted at ~ still uses the project
|
|
146
|
+
// layout. Scoping matters for the same reason: a project-scope install in
|
|
147
|
+
// a home-rooted repo must not be conflated with an existing global one.
|
|
148
|
+
function providerSkillsDirCandidates(root, provider, scope) {
|
|
149
|
+
if (scope === 'user') return [userProviderSkillsDir(root, provider)];
|
|
150
|
+
const dirs = [join(root, provider, 'skills')];
|
|
151
|
+
if (scope !== 'project' && HOME_SKILLS_DIR_OVERRIDES[provider] && isHomeDir(root)) {
|
|
152
|
+
dirs.unshift(userProviderSkillsDir(root, provider));
|
|
153
|
+
}
|
|
154
|
+
return dirs;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
function existingSkillsDirs(root, provider, scope) {
|
|
158
|
+
return providerSkillsDirCandidates(root, provider, scope).filter(existsSync);
|
|
159
|
+
}
|
|
160
|
+
|
|
114
161
|
let pipedAnswers = null;
|
|
115
162
|
class PromptAbortError extends Error {
|
|
116
163
|
constructor() {
|
|
@@ -415,13 +462,15 @@ async function showHelp() {
|
|
|
415
462
|
/**
|
|
416
463
|
* Read the skills version from the impeccable SKILL.md frontmatter.
|
|
417
464
|
*/
|
|
418
|
-
function getSkillsVersion(root) {
|
|
465
|
+
function getSkillsVersion(root, scope) {
|
|
419
466
|
for (const d of PROVIDER_DIRS) {
|
|
420
|
-
const
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
467
|
+
for (const skillsDir of providerSkillsDirCandidates(root, d, scope)) {
|
|
468
|
+
const skillMd = join(skillsDir, 'impeccable', 'SKILL.md');
|
|
469
|
+
if (!existsSync(skillMd)) continue;
|
|
470
|
+
const content = readFileSync(skillMd, 'utf-8');
|
|
471
|
+
const match = content.match(/^version:\s*(.+)$/m);
|
|
472
|
+
if (match) return match[1].trim().replace(/^["']|["']$/g, '');
|
|
473
|
+
}
|
|
425
474
|
}
|
|
426
475
|
return null;
|
|
427
476
|
}
|
|
@@ -535,14 +584,17 @@ function hashSkillFile(filePath) {
|
|
|
535
584
|
* per unique real path. The first provider that maps to a real path
|
|
536
585
|
* wins (so the bundle uses that provider's build).
|
|
537
586
|
*/
|
|
538
|
-
function deduplicateProviders(root, providers) {
|
|
587
|
+
function deduplicateProviders(root, providers, scope) {
|
|
539
588
|
const seen = new Map(); // realPath -> { provider, localSkillsDir }
|
|
540
589
|
for (const provider of providers) {
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
590
|
+
// A provider can hold real installs in more than one layout (a home-rooted
|
|
591
|
+
// repo may carry both ~/.pi/agent/skills and ~/.pi/skills). Keep each as
|
|
592
|
+
// its own entry so update/check touch every tree, not just the first.
|
|
593
|
+
for (const skillsDir of existingSkillsDirs(root, provider, scope)) {
|
|
594
|
+
const real = realpathSync(skillsDir);
|
|
595
|
+
if (!seen.has(real)) {
|
|
596
|
+
seen.set(real, { provider, localSkillsDir: skillsDir });
|
|
597
|
+
}
|
|
546
598
|
}
|
|
547
599
|
}
|
|
548
600
|
return [...seen.values()];
|
|
@@ -556,8 +608,8 @@ function deduplicateProviders(root, providers) {
|
|
|
556
608
|
* SKILL.md, so script-only fixes and removed files are detected.
|
|
557
609
|
* Returns true if every bundle skill matches the local copy.
|
|
558
610
|
*/
|
|
559
|
-
function isUpToDate(root, providers, bundleDir) {
|
|
560
|
-
const unique = deduplicateProviders(root, providers);
|
|
611
|
+
function isUpToDate(root, providers, bundleDir, scope) {
|
|
612
|
+
const unique = deduplicateProviders(root, providers, scope);
|
|
561
613
|
if (unique.length === 0) return false;
|
|
562
614
|
|
|
563
615
|
for (const { provider, localSkillsDir } of unique) {
|
|
@@ -621,20 +673,20 @@ async function check() {
|
|
|
621
673
|
// ─── skills install ───────────────────────────────────────────────────────────
|
|
622
674
|
|
|
623
675
|
// Check if impeccable skills are already present in any provider folder
|
|
624
|
-
function isAlreadyInstalled(root) {
|
|
676
|
+
function isAlreadyInstalled(root, scope) {
|
|
625
677
|
for (const d of PROVIDER_DIRS) {
|
|
626
|
-
const skillsDir
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
}
|
|
637
|
-
}
|
|
678
|
+
for (const skillsDir of existingSkillsDirs(root, d, scope)) {
|
|
679
|
+
try {
|
|
680
|
+
const entries = readdirSync(skillsDir);
|
|
681
|
+
// Look for 'impeccable' skill (or prefixed variant, or legacy 'teach-impeccable')
|
|
682
|
+
if (entries.some(e =>
|
|
683
|
+
e === 'impeccable' || e.endsWith('-impeccable') ||
|
|
684
|
+
e === 'teach-impeccable' || e.endsWith('-teach-impeccable')
|
|
685
|
+
)) {
|
|
686
|
+
return d;
|
|
687
|
+
}
|
|
688
|
+
} catch {}
|
|
689
|
+
}
|
|
638
690
|
}
|
|
639
691
|
return null;
|
|
640
692
|
}
|
|
@@ -678,26 +730,26 @@ function isRealSkillDir(skillsDir, name) {
|
|
|
678
730
|
* by name -- never touches third-party skills that happen to start with `i-`.
|
|
679
731
|
* Returns the number of skills migrated.
|
|
680
732
|
*/
|
|
681
|
-
function migrateUnprefixImpeccable(root) {
|
|
733
|
+
function migrateUnprefixImpeccable(root, scope) {
|
|
682
734
|
let migrated = 0;
|
|
683
735
|
for (const d of PROVIDER_DIRS) {
|
|
684
|
-
const skillsDir
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
}
|
|
736
|
+
for (const skillsDir of existingSkillsDirs(root, d, scope)) {
|
|
737
|
+
let entries;
|
|
738
|
+
try { entries = readdirSync(skillsDir); } catch { continue; }
|
|
739
|
+
for (const name of entries) {
|
|
740
|
+
// A prefixed impeccable skill is `<prefix>impeccable`, not the canonical
|
|
741
|
+
// `impeccable` and not an unrelated legacy skill name.
|
|
742
|
+
if (name === 'impeccable' || name === 'teach-impeccable') continue;
|
|
743
|
+
if (!name.endsWith('-impeccable')) continue;
|
|
744
|
+
if (!isRealSkillDir(skillsDir, name)) continue;
|
|
745
|
+
|
|
746
|
+
const dest = join(skillsDir, 'impeccable');
|
|
747
|
+
try {
|
|
748
|
+
rmSync(dest, { recursive: true, force: true });
|
|
749
|
+
renameSync(join(skillsDir, name), dest);
|
|
750
|
+
migrated++;
|
|
751
|
+
} catch {}
|
|
752
|
+
}
|
|
701
753
|
}
|
|
702
754
|
}
|
|
703
755
|
return migrated;
|
|
@@ -774,7 +826,7 @@ function uniquePaths(paths) {
|
|
|
774
826
|
|
|
775
827
|
function userSkillProbePaths(home, harnessDir, provider) {
|
|
776
828
|
return uniquePaths([
|
|
777
|
-
|
|
829
|
+
userProviderSkillsDir(home, provider),
|
|
778
830
|
join(home, harnessDir, 'skills'),
|
|
779
831
|
]);
|
|
780
832
|
}
|
|
@@ -804,7 +856,7 @@ function collectInstallDetections(root, home = homedir()) {
|
|
|
804
856
|
scope: 'user',
|
|
805
857
|
foundPath,
|
|
806
858
|
installRoot: home,
|
|
807
|
-
installPath:
|
|
859
|
+
installPath: userProviderSkillsDir(home, provider),
|
|
808
860
|
skillProbePaths,
|
|
809
861
|
hasRealSkills: skillProbePaths.some(hasRealSkillEntries),
|
|
810
862
|
reason: 'user harness folder',
|
|
@@ -1010,22 +1062,58 @@ async function chooseInstallPlan(projectRoot, flags, { yes } = {}) {
|
|
|
1010
1062
|
return { targets, scope, installRoot, hookRoot: projectRoot, detections };
|
|
1011
1063
|
}
|
|
1012
1064
|
|
|
1065
|
+
/**
|
|
1066
|
+
* Whether `localSkillsDir` is a symlink that points at ANOTHER in-project
|
|
1067
|
+
* provider's skills dir (e.g. `.claude/skills -> ../.agents/skills`, the shape a
|
|
1068
|
+
* prior `npx skills` install can leave behind). Only these get dropped so each
|
|
1069
|
+
* provider can receive its own compiled variant. A symlink to anywhere else -
|
|
1070
|
+
* notably a user's external shared skills dir (`~/.claude/skills ->
|
|
1071
|
+
* ~/.config/agents/skills`) - is preserved and written through. See issue #295.
|
|
1072
|
+
*/
|
|
1073
|
+
function isInProjectProviderLink(localSkillsDir, root, provider) {
|
|
1074
|
+
let target;
|
|
1075
|
+
try {
|
|
1076
|
+
if (!lstatSync(localSkillsDir).isSymbolicLink()) return false;
|
|
1077
|
+
target = readlinkSync(localSkillsDir);
|
|
1078
|
+
} catch {
|
|
1079
|
+
return false; // not a symlink, or unreadable
|
|
1080
|
+
}
|
|
1081
|
+
// Resolve the link's TARGET lexically against the link's own directory. We
|
|
1082
|
+
// deliberately do NOT realpathSync the target:
|
|
1083
|
+
// * it lets a not-yet-created in-project target still match, so a dangling
|
|
1084
|
+
// `.claude/skills -> ../.agents/skills` is still dropped;
|
|
1085
|
+
// * it compares the ACTUAL target, not a shared realpath, so two providers
|
|
1086
|
+
// pointing at the SAME external dir are never misread as in-project.
|
|
1087
|
+
const resolvedTarget = resolve(dirname(localSkillsDir), target);
|
|
1088
|
+
for (const other of PROVIDER_DIRS) {
|
|
1089
|
+
if (other === provider) continue;
|
|
1090
|
+
if (resolvedTarget === join(root, other, 'skills')) return true;
|
|
1091
|
+
}
|
|
1092
|
+
return false;
|
|
1093
|
+
}
|
|
1094
|
+
|
|
1013
1095
|
/**
|
|
1014
1096
|
* Copy each target provider's compiled skill variant from an extracted bundle
|
|
1015
1097
|
* into the project. Writes real directories (copy, never symlink) so every
|
|
1016
1098
|
* harness keeps the build that was compiled for it. Returns skills written.
|
|
1099
|
+
* `scope: 'user'` writes to the provider's global skills layout (see
|
|
1100
|
+
* HOME_SKILLS_DIR_OVERRIDES); anything else writes `<provider>/skills`.
|
|
1017
1101
|
*/
|
|
1018
|
-
function copyProviderSkills(bundleDir, root, targets) {
|
|
1102
|
+
function copyProviderSkills(bundleDir, root, targets, { scope } = {}) {
|
|
1019
1103
|
let written = 0;
|
|
1020
1104
|
for (const provider of targets) {
|
|
1021
1105
|
const srcDir = join(bundleDir, provider, 'skills');
|
|
1022
1106
|
if (existsSync(srcDir)) {
|
|
1023
|
-
const localSkillsDir =
|
|
1107
|
+
const localSkillsDir = scope === 'user'
|
|
1108
|
+
? userProviderSkillsDir(root, provider)
|
|
1109
|
+
: join(root, provider, 'skills');
|
|
1024
1110
|
// A previous `npx skills` install may have left this provider's skills dir
|
|
1025
|
-
// as a symlink to
|
|
1026
|
-
// write a real, provider-specific directory
|
|
1111
|
+
// as a symlink to ANOTHER in-project provider's canonical copy. Drop only
|
|
1112
|
+
// that link so we write a real, provider-specific directory. A user's
|
|
1113
|
+
// external shared-skills symlink (e.g. ~/.claude/skills ->
|
|
1114
|
+
// ~/.config/agents/skills) is preserved and written through. See #295.
|
|
1027
1115
|
try {
|
|
1028
|
-
if (
|
|
1116
|
+
if (isInProjectProviderLink(localSkillsDir, root, provider)) unlinkSync(localSkillsDir);
|
|
1029
1117
|
} catch {}
|
|
1030
1118
|
for (const skill of readdirSync(srcDir, { withFileTypes: true })) {
|
|
1031
1119
|
if (!skill.isDirectory()) continue;
|
|
@@ -1040,8 +1128,8 @@ function copyProviderSkills(bundleDir, root, targets) {
|
|
|
1040
1128
|
return written;
|
|
1041
1129
|
}
|
|
1042
1130
|
|
|
1043
|
-
function refreshProviderSkills(bundleDir, root, providers) {
|
|
1044
|
-
const unique = deduplicateProviders(root, providers);
|
|
1131
|
+
function refreshProviderSkills(bundleDir, root, providers, scope) {
|
|
1132
|
+
const unique = deduplicateProviders(root, providers, scope);
|
|
1045
1133
|
let updated = 0;
|
|
1046
1134
|
for (const { provider, localSkillsDir } of unique) {
|
|
1047
1135
|
const srcDir = join(bundleDir, provider, 'skills');
|
|
@@ -1500,13 +1588,13 @@ async function install(flags) {
|
|
|
1500
1588
|
}
|
|
1501
1589
|
|
|
1502
1590
|
const { targets, installRoot, hookRoot, scope } = plan;
|
|
1503
|
-
const existing = isAlreadyInstalled(installRoot);
|
|
1591
|
+
const existing = isAlreadyInstalled(installRoot, scope);
|
|
1504
1592
|
|
|
1505
1593
|
if (existing && !force) {
|
|
1506
1594
|
console.log(`Impeccable skills are already installed (found in ${existing}/).`);
|
|
1507
|
-
const installedTargets = findInstalledProviders(installRoot);
|
|
1595
|
+
const installedTargets = findInstalledProviders(installRoot, scope);
|
|
1508
1596
|
const selectedInstalledTargets = targets.filter(provider => installedTargets.includes(provider));
|
|
1509
|
-
const linkedTargets = findLinkedProviders(installRoot, selectedInstalledTargets);
|
|
1597
|
+
const linkedTargets = findLinkedProviders(installRoot, selectedInstalledTargets, scope);
|
|
1510
1598
|
const copyTargets = selectedInstalledTargets.filter(provider => !linkedTargets.includes(provider));
|
|
1511
1599
|
const hookTargets = selectedInstalledTargets;
|
|
1512
1600
|
const wantHooks = installHooks && await decideHookInstall(hookRoot, hookTargets, { yes });
|
|
@@ -1533,10 +1621,10 @@ async function install(flags) {
|
|
|
1533
1621
|
}
|
|
1534
1622
|
}
|
|
1535
1623
|
|
|
1536
|
-
if (!updateCheckSkipped && copyTargets.length > 0 && !isUpToDate(installRoot, copyTargets, bundleDir)) {
|
|
1537
|
-
migrateUnprefixImpeccable(installRoot);
|
|
1538
|
-
updated = refreshProviderSkills(bundleDir, installRoot, copyTargets);
|
|
1539
|
-
const v = getSkillsVersion(installRoot);
|
|
1624
|
+
if (!updateCheckSkipped && copyTargets.length > 0 && !isUpToDate(installRoot, copyTargets, bundleDir, scope)) {
|
|
1625
|
+
migrateUnprefixImpeccable(installRoot, scope);
|
|
1626
|
+
updated = refreshProviderSkills(bundleDir, installRoot, copyTargets, scope);
|
|
1627
|
+
const v = getSkillsVersion(installRoot, scope);
|
|
1540
1628
|
console.log(`Updated ${updated} skill(s)${v ? ` to v${v}` : ''}.`);
|
|
1541
1629
|
}
|
|
1542
1630
|
|
|
@@ -1549,7 +1637,7 @@ async function install(flags) {
|
|
|
1549
1637
|
console.log('Existing skills were left unchanged.');
|
|
1550
1638
|
console.log('Run with --force to reinstall.\n');
|
|
1551
1639
|
} else if (updated === 0 && writtenHookTargets.length === 0) {
|
|
1552
|
-
const v = getSkillsVersion(installRoot);
|
|
1640
|
+
const v = getSkillsVersion(installRoot, scope);
|
|
1553
1641
|
console.log(`Skills are up to date${v ? ` (v${v})` : ''}.`);
|
|
1554
1642
|
console.log('Run with --force to reinstall.\n');
|
|
1555
1643
|
} else {
|
|
@@ -1588,12 +1676,12 @@ async function install(flags) {
|
|
|
1588
1676
|
|
|
1589
1677
|
// Retire any old `i-`-prefixed install so the fresh copy lands on the
|
|
1590
1678
|
// canonical `impeccable` dir instead of orphaning the prefixed one.
|
|
1591
|
-
migrateUnprefixImpeccable(installRoot);
|
|
1679
|
+
migrateUnprefixImpeccable(installRoot, scope);
|
|
1592
1680
|
|
|
1593
1681
|
let written = 0;
|
|
1594
1682
|
let hookTargets = [];
|
|
1595
1683
|
try {
|
|
1596
|
-
written = copyProviderSkills(bundleDir, installRoot, targets);
|
|
1684
|
+
written = copyProviderSkills(bundleDir, installRoot, targets, { scope });
|
|
1597
1685
|
hookTargets = wantHooks ? copyProviderHooks(bundleDir, hookRoot, targets, { force, skillRoot: installRoot }) : [];
|
|
1598
1686
|
} catch (e) {
|
|
1599
1687
|
rmSync(bundleDir, { recursive: true, force: true });
|
|
@@ -1623,27 +1711,31 @@ function findProjectRoot() {
|
|
|
1623
1711
|
return process.cwd();
|
|
1624
1712
|
}
|
|
1625
1713
|
|
|
1626
|
-
function findInstalledProviders(root) {
|
|
1714
|
+
function findInstalledProviders(root, scope) {
|
|
1627
1715
|
const found = [];
|
|
1628
1716
|
for (const d of PROVIDER_DIRS) {
|
|
1629
|
-
const skillsDir
|
|
1630
|
-
|
|
1631
|
-
|
|
1632
|
-
|
|
1633
|
-
|
|
1634
|
-
|
|
1717
|
+
for (const skillsDir of existingSkillsDirs(root, d, scope)) {
|
|
1718
|
+
try {
|
|
1719
|
+
const entries = readdirSync(skillsDir);
|
|
1720
|
+
if (entries.some(name => isSkillDir(skillsDir, name))) {
|
|
1721
|
+
found.push(d);
|
|
1722
|
+
break;
|
|
1723
|
+
}
|
|
1724
|
+
} catch {}
|
|
1725
|
+
}
|
|
1635
1726
|
}
|
|
1636
1727
|
return found;
|
|
1637
1728
|
}
|
|
1638
1729
|
|
|
1639
|
-
function findLinkedProviders(root, providers) {
|
|
1730
|
+
function findLinkedProviders(root, providers, scope) {
|
|
1640
1731
|
return providers.filter(provider => {
|
|
1641
|
-
const
|
|
1642
|
-
|
|
1643
|
-
|
|
1644
|
-
|
|
1645
|
-
|
|
1732
|
+
for (const skillsDir of providerSkillsDirCandidates(root, provider, scope)) {
|
|
1733
|
+
const skillDir = join(skillsDir, 'impeccable');
|
|
1734
|
+
try {
|
|
1735
|
+
if (lstatSync(skillDir).isSymbolicLink()) return true;
|
|
1736
|
+
} catch {}
|
|
1646
1737
|
}
|
|
1738
|
+
return false;
|
|
1647
1739
|
});
|
|
1648
1740
|
}
|
|
1649
1741
|
|
package/cli/engine/cli/main.mjs
CHANGED
|
@@ -2,6 +2,7 @@ import fs from 'node:fs';
|
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
|
|
4
4
|
import { loadDesignSystemForCwd } from '../design-system.mjs';
|
|
5
|
+
import { RULE_SCOPES, filterByScopes } from '../registry/antipatterns.mjs';
|
|
5
6
|
import { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs';
|
|
6
7
|
import { detectHtml } from '../engines/static-html/detect-html.mjs';
|
|
7
8
|
import { detectText } from '../engines/regex/detect-text.mjs';
|
|
@@ -93,6 +94,8 @@ Options:
|
|
|
93
94
|
--quiet In text mode, only print the final findings count
|
|
94
95
|
--gpt Also report GPT-specific provider tells (off by default)
|
|
95
96
|
--gemini Also report Gemini-specific provider tells (off by default)
|
|
97
|
+
--scope <name> Only report rules in the given design domain
|
|
98
|
+
(type, layout). Comma-separated.
|
|
96
99
|
--no-config Do not apply project config, detector ignores, inline
|
|
97
100
|
ignore comments, or DESIGN.md
|
|
98
101
|
--no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
|
|
@@ -151,6 +154,33 @@ async function detectCli() {
|
|
|
151
154
|
const providers = [];
|
|
152
155
|
if (args.includes('--gpt')) providers.push('gpt');
|
|
153
156
|
if (args.includes('--gemini')) providers.push('gemini');
|
|
157
|
+
const scopes = [];
|
|
158
|
+
for (let i = 0; i < args.length; i++) {
|
|
159
|
+
if (args[i] !== '--scope' && !args[i].startsWith('--scope=')) continue;
|
|
160
|
+
const inline = args[i].startsWith('--scope=');
|
|
161
|
+
const value = inline ? args[i].slice('--scope='.length) : args[i + 1];
|
|
162
|
+
const parsed = (value && !value.startsWith('--'))
|
|
163
|
+
? value.split(',').map(s => s.trim()).filter(Boolean)
|
|
164
|
+
: [];
|
|
165
|
+
// A bare `--scope` would otherwise fall out of `targets` and scan unscoped;
|
|
166
|
+
// fail loudly so a mistyped pre-scan never runs the wrong rule set.
|
|
167
|
+
if (parsed.length === 0) {
|
|
168
|
+
process.stderr.write(
|
|
169
|
+
`Error: --scope requires a value. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
|
|
170
|
+
);
|
|
171
|
+
process.exit(1);
|
|
172
|
+
}
|
|
173
|
+
scopes.push(...parsed);
|
|
174
|
+
args.splice(i, inline ? 1 : 2);
|
|
175
|
+
i -= 1;
|
|
176
|
+
}
|
|
177
|
+
const unknownScopes = scopes.filter(s => !RULE_SCOPES.has(s));
|
|
178
|
+
if (unknownScopes.length > 0) {
|
|
179
|
+
process.stderr.write(
|
|
180
|
+
`Error: unknown --scope value(s): ${unknownScopes.join(', ')}. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
|
|
181
|
+
);
|
|
182
|
+
process.exit(1);
|
|
183
|
+
}
|
|
154
184
|
const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
|
|
155
185
|
const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
|
|
156
186
|
// Inline `impeccable-disable*` waivers are part of the scanned file, so they
|
|
@@ -276,6 +306,7 @@ async function detectCli() {
|
|
|
276
306
|
}
|
|
277
307
|
|
|
278
308
|
allFindings = filterDetectionFindings(allFindings, detectionConfig);
|
|
309
|
+
allFindings = filterByScopes(allFindings, scopes);
|
|
279
310
|
|
|
280
311
|
if (allFindings.length > 0) {
|
|
281
312
|
if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
|