impeccable 2.1.9 → 2.3.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.repo.md +27 -11
- package/cli/bin/commands/skills.mjs +176 -7
- package/cli/engine/browser/injected/index.mjs +1725 -0
- package/cli/engine/cli/main.mjs +238 -0
- package/cli/engine/detect-antipatterns-browser.js +1576 -206
- package/cli/engine/detect-antipatterns.mjs +32 -4332
- package/cli/engine/engines/browser/detect-url.mjs +252 -0
- package/cli/engine/engines/regex/detect-text.mjs +535 -0
- package/cli/engine/engines/static-html/css-cascade.mjs +986 -0
- package/cli/engine/engines/static-html/detect-html.mjs +208 -0
- package/cli/engine/engines/visual/screenshot-contrast.mjs +189 -0
- package/cli/engine/findings.mjs +12 -0
- package/cli/engine/node/file-system.mjs +198 -0
- package/cli/engine/profile/profiler.mjs +166 -0
- package/cli/engine/registry/antipatterns.mjs +419 -0
- package/cli/engine/rules/checks.mjs +2316 -0
- package/cli/engine/shared/color.mjs +124 -0
- package/cli/engine/shared/constants.mjs +101 -0
- package/cli/engine/shared/page.mjs +7 -0
- package/package.json +16 -5
package/README.repo.md
CHANGED
|
@@ -19,7 +19,7 @@ Impeccable adds:
|
|
|
19
19
|
|
|
20
20
|
### The Skill: impeccable
|
|
21
21
|
|
|
22
|
-
A comprehensive design skill with 7 domain-specific references ([view skill](skill/SKILL.md)):
|
|
22
|
+
A comprehensive design skill with 7 domain-specific references ([view skill](skill/SKILL.src.md)):
|
|
23
23
|
|
|
24
24
|
| Reference | Covers |
|
|
25
25
|
|-----------|--------|
|
|
@@ -38,7 +38,7 @@ All commands are accessed through `/impeccable`:
|
|
|
38
38
|
| Command | What it does |
|
|
39
39
|
|---------|--------------|
|
|
40
40
|
| `/impeccable craft` | Full shape-then-build flow with visual iteration |
|
|
41
|
-
| `/impeccable
|
|
41
|
+
| `/impeccable init` | One-time setup: gather design context, write PRODUCT.md and DESIGN.md, configure live mode, recommend next steps |
|
|
42
42
|
| `/impeccable document` | Generate root DESIGN.md from existing project code |
|
|
43
43
|
| `/impeccable extract` | Pull reusable components and tokens into the design system |
|
|
44
44
|
| `/impeccable shape` | Plan UX/UI before writing code |
|
|
@@ -93,11 +93,23 @@ Visit [impeccable.style](https://impeccable.style#casestudies) to see before/aft
|
|
|
93
93
|
|
|
94
94
|
## Installation
|
|
95
95
|
|
|
96
|
-
### Option 1:
|
|
96
|
+
### Option 1: CLI installer (Recommended)
|
|
97
|
+
|
|
98
|
+
From the root of your project, run:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
npx impeccable skills install
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
This auto-detects your harness and writes the build compiled for it to the right location (`.claude/skills/`, `.cursor/skills/`, etc.). Works with Cursor, Claude Code, Gemini CLI, Codex CLI, and every other supported tool. Reload your harness afterward.
|
|
105
|
+
|
|
106
|
+
Claude Code users can alternatively install the plugin with `/plugin marketplace add pbakaus/impeccable`. The general-purpose `npx skills add pbakaus/impeccable` also works, though it installs one shared build for all harnesses rather than the one compiled for yours.
|
|
107
|
+
|
|
108
|
+
### Option 2: Download from Website
|
|
97
109
|
|
|
98
110
|
Visit [impeccable.style](https://impeccable.style), download the ZIP for your tool, and extract to your project.
|
|
99
111
|
|
|
100
|
-
### Option
|
|
112
|
+
### Option 3: Copy from Repository
|
|
101
113
|
|
|
102
114
|
**Cursor:**
|
|
103
115
|
```bash
|
|
@@ -195,22 +207,26 @@ cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/
|
|
|
195
207
|
|
|
196
208
|
## Usage
|
|
197
209
|
|
|
198
|
-
Once installed,
|
|
210
|
+
Once installed, every command runs through the single `/impeccable` skill:
|
|
199
211
|
|
|
200
212
|
```
|
|
201
|
-
/audit
|
|
202
|
-
/
|
|
203
|
-
/
|
|
204
|
-
/
|
|
213
|
+
/impeccable audit # Find issues
|
|
214
|
+
/impeccable polish # Final cleanup
|
|
215
|
+
/impeccable distill # Remove complexity
|
|
216
|
+
/impeccable critique # Full design review
|
|
205
217
|
```
|
|
206
218
|
|
|
219
|
+
Type `/impeccable` alone to see the full command list.
|
|
220
|
+
|
|
207
221
|
Most commands accept an optional argument to focus on a specific area:
|
|
208
222
|
|
|
209
223
|
```
|
|
210
|
-
/audit header
|
|
211
|
-
/polish checkout
|
|
224
|
+
/impeccable audit the header
|
|
225
|
+
/impeccable polish the checkout form
|
|
212
226
|
```
|
|
213
227
|
|
|
228
|
+
If you reach for one command often, pin it with `/impeccable pin audit` to get `/audit` as a standalone shortcut.
|
|
229
|
+
|
|
214
230
|
**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.
|
|
215
231
|
|
|
216
232
|
## CLI
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Usage:
|
|
5
5
|
* impeccable skills help Show all available skills and commands
|
|
6
|
-
* impeccable skills install Install skills
|
|
6
|
+
* impeccable skills install Install compiled skills from the universal bundle
|
|
7
7
|
* impeccable skills update Update skills to latest version
|
|
8
8
|
*/
|
|
9
9
|
|
|
@@ -14,7 +14,7 @@ import { createInterface } from 'node:readline';
|
|
|
14
14
|
import { fileURLToPath } from 'node:url';
|
|
15
15
|
import { get } from 'node:https';
|
|
16
16
|
import { createHash } from 'node:crypto';
|
|
17
|
-
import { tmpdir } from 'node:os';
|
|
17
|
+
import { tmpdir, homedir } from 'node:os';
|
|
18
18
|
|
|
19
19
|
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
20
20
|
const API_BASE = 'https://impeccable.style';
|
|
@@ -22,6 +22,23 @@ const API_BASE = 'https://impeccable.style';
|
|
|
22
22
|
// Provider folder names in project roots
|
|
23
23
|
const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn'];
|
|
24
24
|
|
|
25
|
+
// When a project has no harness folder yet, infer the target from globally
|
|
26
|
+
// installed harnesses (~/.claude, ~/.codex, ...). Codex reads skills from
|
|
27
|
+
// .agents/skills, so ~/.codex maps to the .agents bundle variant.
|
|
28
|
+
const GLOBAL_HARNESS_HINTS = [
|
|
29
|
+
{ home: '.claude', provider: '.claude' },
|
|
30
|
+
{ home: '.codex', provider: '.agents' },
|
|
31
|
+
{ home: '.cursor', provider: '.cursor' },
|
|
32
|
+
{ home: '.gemini', provider: '.gemini' },
|
|
33
|
+
{ home: '.kiro', provider: '.kiro' },
|
|
34
|
+
{ home: '.opencode', provider: '.opencode' },
|
|
35
|
+
{ home: '.qoder', provider: '.qoder' },
|
|
36
|
+
];
|
|
37
|
+
|
|
38
|
+
// Last-resort default when nothing is detected: Claude Code + the universal
|
|
39
|
+
// (.agents, also Codex) folder, which covers the most common setups.
|
|
40
|
+
const DEFAULT_TARGETS = ['.claude', '.agents'];
|
|
41
|
+
|
|
25
42
|
function ask(question) {
|
|
26
43
|
const rl = createInterface({ input: process.stdin, output: process.stdout });
|
|
27
44
|
return new Promise(r => rl.question(question, ans => { rl.close(); r(ans.trim().toLowerCase()); }));
|
|
@@ -321,10 +338,101 @@ function renameSkillsWithPrefix(root, prefix) {
|
|
|
321
338
|
return count;
|
|
322
339
|
}
|
|
323
340
|
|
|
341
|
+
/**
|
|
342
|
+
* Decide which provider folders to install into.
|
|
343
|
+
* 1. An explicit --providers=.claude,.cursor list wins.
|
|
344
|
+
* 2. Otherwise, harness folders already present in the project.
|
|
345
|
+
* 3. Otherwise, infer from globally installed harnesses (~/.claude, ~/.codex).
|
|
346
|
+
* 4. Otherwise, a sensible default (.claude + .agents).
|
|
347
|
+
*/
|
|
348
|
+
function resolveInstallTargets(root, providersValue) {
|
|
349
|
+
if (providersValue) {
|
|
350
|
+
const wanted = providersValue
|
|
351
|
+
.split(',')
|
|
352
|
+
.map(s => s.trim())
|
|
353
|
+
.filter(Boolean)
|
|
354
|
+
.map(s => (s.startsWith('.') ? s : `.${s}`))
|
|
355
|
+
.filter(p => PROVIDER_DIRS.includes(p));
|
|
356
|
+
return [...new Set(wanted)];
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
const inProject = PROVIDER_DIRS.filter(d => existsSync(join(root, d)));
|
|
360
|
+
if (inProject.length > 0) return inProject;
|
|
361
|
+
|
|
362
|
+
const home = homedir();
|
|
363
|
+
const inferred = [];
|
|
364
|
+
for (const { home: h, provider } of GLOBAL_HARNESS_HINTS) {
|
|
365
|
+
if (existsSync(join(home, h)) && !inferred.includes(provider)) inferred.push(provider);
|
|
366
|
+
}
|
|
367
|
+
if (inferred.length > 0) return inferred;
|
|
368
|
+
|
|
369
|
+
return [...DEFAULT_TARGETS];
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
/**
|
|
373
|
+
* Copy each target provider's compiled skill variant from an extracted bundle
|
|
374
|
+
* into the project. Writes real directories (copy, never symlink) so every
|
|
375
|
+
* harness keeps the build that was compiled for it. Returns skills written.
|
|
376
|
+
*/
|
|
377
|
+
function copyProviderSkills(bundleDir, root, targets) {
|
|
378
|
+
let written = 0;
|
|
379
|
+
for (const provider of targets) {
|
|
380
|
+
const srcDir = join(bundleDir, provider, 'skills');
|
|
381
|
+
if (!existsSync(srcDir)) continue;
|
|
382
|
+
const localSkillsDir = join(root, provider, 'skills');
|
|
383
|
+
// A previous `npx skills` install may have left this provider's skills dir
|
|
384
|
+
// as a symlink to another provider's canonical copy. Drop the link so we
|
|
385
|
+
// write a real, provider-specific directory instead of writing through it.
|
|
386
|
+
try {
|
|
387
|
+
if (lstatSync(localSkillsDir).isSymbolicLink()) unlinkSync(localSkillsDir);
|
|
388
|
+
} catch {}
|
|
389
|
+
for (const skill of readdirSync(srcDir, { withFileTypes: true })) {
|
|
390
|
+
if (!skill.isDirectory()) continue;
|
|
391
|
+
const src = join(srcDir, skill.name);
|
|
392
|
+
const dest = join(localSkillsDir, skill.name);
|
|
393
|
+
rmSync(dest, { recursive: true, force: true });
|
|
394
|
+
copyDirSync(src, dest);
|
|
395
|
+
written++;
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
return written;
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
/**
|
|
402
|
+
* Codex reads custom subagents from `.codex/agents/*.toml`, a sibling of the
|
|
403
|
+
* skill dir that the skills/ copy never touches. Treat it as a sidecar: only
|
|
404
|
+
* write it for projects that actually use Codex, so a pure Claude project
|
|
405
|
+
* doesn't get a stray `.codex/` folder. Codex-likely = the .agents (Codex
|
|
406
|
+
* skills) variant is a target, or a global ~/.codex install exists.
|
|
407
|
+
*/
|
|
408
|
+
function isCodexLikely(targets) {
|
|
409
|
+
return targets.includes('.agents') || existsSync(join(homedir(), '.codex'));
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
/**
|
|
413
|
+
* Copy the Codex subagent definitions from the bundle's top-level `.codex/agents`
|
|
414
|
+
* into the project's `.codex/agents`. Returns the number of files written (0 when
|
|
415
|
+
* the bundle has none).
|
|
416
|
+
*/
|
|
417
|
+
function installCodexAgents(bundleDir, root) {
|
|
418
|
+
const srcDir = join(bundleDir, '.codex', 'agents');
|
|
419
|
+
if (!existsSync(srcDir)) return 0;
|
|
420
|
+
const destDir = join(root, '.codex', 'agents');
|
|
421
|
+
let written = 0;
|
|
422
|
+
for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
|
|
423
|
+
if (!entry.isFile()) continue;
|
|
424
|
+
mkdirSync(destDir, { recursive: true });
|
|
425
|
+
writeFileSync(join(destDir, entry.name), readFileSync(join(srcDir, entry.name)));
|
|
426
|
+
written++;
|
|
427
|
+
}
|
|
428
|
+
return written;
|
|
429
|
+
}
|
|
430
|
+
|
|
324
431
|
async function install(flags) {
|
|
325
432
|
const force = flags.includes('--force');
|
|
326
433
|
const yes = flags.includes('-y') || flags.includes('--yes');
|
|
327
434
|
const prefixFlag = flags.find(f => f.startsWith('--prefix='));
|
|
435
|
+
const providersFlag = flags.find(f => f.startsWith('--providers='));
|
|
328
436
|
const root = findProjectRoot();
|
|
329
437
|
const existing = isAlreadyInstalled(root);
|
|
330
438
|
|
|
@@ -334,13 +442,60 @@ async function install(flags) {
|
|
|
334
442
|
process.exit(0);
|
|
335
443
|
}
|
|
336
444
|
|
|
337
|
-
|
|
445
|
+
// Decide which harness folders to install into, then copy each harness's own
|
|
446
|
+
// compiled variant from the universal bundle. We deliberately do NOT shell out
|
|
447
|
+
// to `npx skills add`: its name-based discovery can install the uncompiled
|
|
448
|
+
// source, and its symlink default points every harness at one shared variant.
|
|
449
|
+
// Copying per-provider variants is the only correct install for this skill.
|
|
450
|
+
const targets = resolveInstallTargets(root, providersFlag ? providersFlag.split('=')[1] : null);
|
|
451
|
+
if (targets.length === 0) {
|
|
452
|
+
console.error('Could not determine a target harness folder.');
|
|
453
|
+
console.error('Pass one explicitly, e.g. --providers=.claude,.cursor');
|
|
454
|
+
process.exit(1);
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
if (!yes) {
|
|
458
|
+
console.log(`Target harness folder(s): ${targets.join(', ')}`);
|
|
459
|
+
const ans = await ask(`Install impeccable skills into ${targets.length} folder(s)? (Y/n) `);
|
|
460
|
+
if (ans === 'n' || ans === 'no') {
|
|
461
|
+
console.log('Aborted. Re-run with --providers=<dirs> to choose explicitly (e.g. --providers=.claude,.cursor).');
|
|
462
|
+
process.exit(0);
|
|
463
|
+
}
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
console.log('\nDownloading impeccable skills...');
|
|
467
|
+
let bundleDir;
|
|
338
468
|
try {
|
|
339
|
-
|
|
469
|
+
bundleDir = await downloadAndExtractBundle();
|
|
340
470
|
} catch (e) {
|
|
341
|
-
|
|
471
|
+
console.error(`Download failed: ${e.message}`);
|
|
472
|
+
process.exit(1);
|
|
342
473
|
}
|
|
343
474
|
|
|
475
|
+
let written = 0;
|
|
476
|
+
let codexAgents = 0;
|
|
477
|
+
try {
|
|
478
|
+
written = copyProviderSkills(bundleDir, root, targets);
|
|
479
|
+
// Codex users also need the asset-producer subagent, which lives in
|
|
480
|
+
// .codex/agents/ (a sibling of the skill dir, not part of skills/). Do this
|
|
481
|
+
// before the bundle is cleaned up below. Best-effort: never fail the install.
|
|
482
|
+
if (isCodexLikely(targets)) {
|
|
483
|
+
try { codexAgents = installCodexAgents(bundleDir, root); } catch {}
|
|
484
|
+
}
|
|
485
|
+
} catch (e) {
|
|
486
|
+
rmSync(bundleDir, { recursive: true, force: true });
|
|
487
|
+
console.error(`Install failed: ${e.message}`);
|
|
488
|
+
process.exit(1);
|
|
489
|
+
}
|
|
490
|
+
rmSync(bundleDir, { recursive: true, force: true });
|
|
491
|
+
|
|
492
|
+
if (written === 0) {
|
|
493
|
+
console.error(`Nothing was installed: the bundle had no variants for ${targets.join(', ')}.`);
|
|
494
|
+
process.exit(1);
|
|
495
|
+
}
|
|
496
|
+
console.log(`Installed impeccable into: ${targets.join(', ')}`);
|
|
497
|
+
if (codexAgents > 0) console.log(`Installed ${codexAgents} Codex subagent(s) into .codex/agents/`);
|
|
498
|
+
|
|
344
499
|
// Ask about prefixing (skip in CI mode unless --prefix= is set)
|
|
345
500
|
let prefix = '';
|
|
346
501
|
if (prefixFlag) {
|
|
@@ -374,7 +529,7 @@ async function install(flags) {
|
|
|
374
529
|
// Cleanup script not available -- skip
|
|
375
530
|
}
|
|
376
531
|
|
|
377
|
-
console.log(`\nDone! Run /${prefix}impeccable
|
|
532
|
+
console.log(`\nDone! Run /${prefix}impeccable init in your AI harness to set up design context.\n`);
|
|
378
533
|
}
|
|
379
534
|
|
|
380
535
|
/** Detect prefix by looking for the 'impeccable' skill (or legacy 'teach-impeccable') */
|
|
@@ -548,9 +703,18 @@ async function update(flags = []) {
|
|
|
548
703
|
|
|
549
704
|
// Compare local vs remote -- skip if already up to date
|
|
550
705
|
if (isUpToDate(root, providers, tmpDir)) {
|
|
706
|
+
// Skills match, but the Codex subagent sidecar may still be missing (e.g.
|
|
707
|
+
// an `npx skills add` install that only carried skills/). Heal it before
|
|
708
|
+
// declaring nothing to do.
|
|
709
|
+
let healed = 0;
|
|
710
|
+
if (isCodexLikely(providers)
|
|
711
|
+
&& !existsSync(join(root, '.codex', 'agents', 'impeccable_asset_producer.toml'))) {
|
|
712
|
+
try { healed = installCodexAgents(tmpDir, root); } catch {}
|
|
713
|
+
}
|
|
551
714
|
rmSync(tmpDir, { recursive: true, force: true });
|
|
552
715
|
const v = getSkillsVersion(root);
|
|
553
|
-
console.log(`
|
|
716
|
+
if (healed > 0) console.log(`Installed ${healed} Codex subagent(s) into .codex/agents/`);
|
|
717
|
+
console.log(`Skills are up to date${v ? ` (v${v})` : ''}.${healed > 0 ? '' : ' Nothing to do.'}`);
|
|
554
718
|
process.exit(0);
|
|
555
719
|
}
|
|
556
720
|
|
|
@@ -587,6 +751,11 @@ async function update(flags = []) {
|
|
|
587
751
|
}
|
|
588
752
|
}
|
|
589
753
|
|
|
754
|
+
// Refresh the Codex subagent sidecar (.codex/agents/) alongside the skills.
|
|
755
|
+
if (isCodexLikely(providers)) {
|
|
756
|
+
try { installCodexAgents(tmpDir, root); } catch {}
|
|
757
|
+
}
|
|
758
|
+
|
|
590
759
|
rmSync(tmpDir, { recursive: true, force: true });
|
|
591
760
|
|
|
592
761
|
// Re-apply prefix if detected
|