impeccable 2.0.1 → 2.0.4

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.bak.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable
2
2
 
3
- The vocabulary you didn't know you needed. 1 skill, 20 commands, and curated anti-patterns for impeccable frontend design.
3
+ The vocabulary you didn't know you needed. 1 skill, 22 commands, and curated anti-patterns for impeccable frontend design.
4
4
 
5
5
  > **Quick start:** Visit [impeccable.style](https://impeccable.style) to download ready-to-use bundles.
6
6
 
@@ -11,31 +11,31 @@ Anthropic created [frontend-design](https://github.com/anthropics/skills/tree/ma
11
11
  Every LLM learned from the same generic templates. Without guidance, you get the same predictable mistakes: Inter font, purple gradients, cards nested in cards, gray text on colored backgrounds.
12
12
 
13
13
  Impeccable fights that bias with:
14
- - **An expanded skill** with 7 domain-specific reference files ([view source](source/skills/frontend-design/))
15
- - **20 steering commands** to audit, review, polish, distill, animate, and more
14
+ - **An expanded skill** with 7 domain-specific reference files ([view source](source/skills/impeccable/))
15
+ - **22 steering commands** to audit, review, polish, distill, animate, and more
16
16
  - **Curated anti-patterns** that explicitly tell the AI what NOT to do
17
17
 
18
18
  ## What's Included
19
19
 
20
- ### The Skill: frontend-design
20
+ ### The Skill: impeccable
21
21
 
22
- A comprehensive design skill with 7 domain-specific references ([view skill](source/skills/frontend-design/SKILL.md)):
22
+ A comprehensive design skill with 7 domain-specific references ([view skill](source/skills/impeccable/SKILL.md)):
23
23
 
24
24
  | Reference | Covers |
25
25
  |-----------|--------|
26
- | [typography](source/skills/frontend-design/reference/typography.md) | Type systems, font pairing, modular scales, OpenType |
27
- | [color-and-contrast](source/skills/frontend-design/reference/color-and-contrast.md) | OKLCH, tinted neutrals, dark mode, accessibility |
28
- | [spatial-design](source/skills/frontend-design/reference/spatial-design.md) | Spacing systems, grids, visual hierarchy |
29
- | [motion-design](source/skills/frontend-design/reference/motion-design.md) | Easing curves, staggering, reduced motion |
30
- | [interaction-design](source/skills/frontend-design/reference/interaction-design.md) | Forms, focus states, loading patterns |
31
- | [responsive-design](source/skills/frontend-design/reference/responsive-design.md) | Mobile-first, fluid design, container queries |
32
- | [ux-writing](source/skills/frontend-design/reference/ux-writing.md) | Button labels, error messages, empty states |
26
+ | [typography](source/skills/impeccable/reference/typography.md) | Type systems, font pairing, modular scales, OpenType |
27
+ | [color-and-contrast](source/skills/impeccable/reference/color-and-contrast.md) | OKLCH, tinted neutrals, dark mode, accessibility |
28
+ | [spatial-design](source/skills/impeccable/reference/spatial-design.md) | Spacing systems, grids, visual hierarchy |
29
+ | [motion-design](source/skills/impeccable/reference/motion-design.md) | Easing curves, staggering, reduced motion |
30
+ | [interaction-design](source/skills/impeccable/reference/interaction-design.md) | Forms, focus states, loading patterns |
31
+ | [responsive-design](source/skills/impeccable/reference/responsive-design.md) | Mobile-first, fluid design, container queries |
32
+ | [ux-writing](source/skills/impeccable/reference/ux-writing.md) | Button labels, error messages, empty states |
33
33
 
34
- ### 20 Commands
34
+ ### 22 Commands
35
35
 
36
36
  | Command | What it does |
37
37
  |---------|--------------|
38
- | `/teach-impeccable` | One-time setup: gather design context, save to config |
38
+ | `/impeccable teach` | One-time setup: gather design context, save to config |
39
39
  | `/audit` | Run technical quality checks (a11y, performance, responsive) |
40
40
  | `/critique` | UX design review: hierarchy, clarity, emotional resonance |
41
41
  | `/normalize` | Align with design system standards |
@@ -177,6 +177,15 @@ cp -r dist/trae/.trae/skills/* ~/.trae/skills/
177
177
  >
178
178
  > After copying, restart Trae IDE to activate the skills.
179
179
 
180
+ **Rovo Dev:**
181
+ ```bash
182
+ # Project-specific
183
+ cp -r dist/rovo-dev/.rovodev your-project/
184
+
185
+ # Or global (applies to all projects)
186
+ cp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/
187
+ ```
188
+
180
189
  ## Usage
181
190
 
182
191
  Once installed, use commands in your AI harness:
@@ -202,13 +211,13 @@ Most commands accept an optional argument to focus on a specific area:
202
211
  Impeccable includes a standalone CLI for detecting anti-patterns without an AI harness:
203
212
 
204
213
  ```bash
205
- bun bin/impeccable.mjs detect src/ # scan a directory
206
- bun bin/impeccable.mjs detect index.html # scan an HTML file
207
- bun bin/impeccable.mjs detect https://example.com # scan a URL (Puppeteer)
208
- bun bin/impeccable.mjs detect --fast --json . # regex-only, JSON output
214
+ npx impeccable detect src/ # scan a directory
215
+ npx impeccable detect index.html # scan an HTML file
216
+ npx impeccable detect https://example.com # scan a URL (Puppeteer)
217
+ npx impeccable detect --fast --json . # regex-only, JSON output
209
218
  ```
210
219
 
211
- The detector catches 25 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).
220
+ The detector catches 24 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).
212
221
 
213
222
  ## Supported Tools
214
223
 
@@ -221,6 +230,7 @@ The detector catches 25 issues across AI slop (side-tab borders, purple gradient
221
230
  - [VS Code Copilot](https://code.visualstudio.com)
222
231
  - [Kiro](https://kiro.dev)
223
232
  - [Trae](https://trae.ai)
233
+ - [Rovo Dev](https://www.atlassian.com/software/rovo)
224
234
 
225
235
  ## Contributing
226
236
 
@@ -230,7 +240,7 @@ See [DEVELOP.md](DEVELOP.md) for contributor guidelines and build instructions.
230
240
 
231
241
  Apache 2.0. See [LICENSE](LICENSE).
232
242
 
233
- The frontend-design skill builds on [Anthropic's original](https://github.com/anthropics/skills/tree/main/skills/frontend-design). See [NOTICE.md](NOTICE.md) for attribution.
243
+ The impeccable skill builds on [Anthropic's original frontend-design skill](https://github.com/anthropics/skills/tree/main/skills/frontend-design). See [NOTICE.md](NOTICE.md) for attribution.
234
244
 
235
245
  ---
236
246
 
package/README.md CHANGED
@@ -5,7 +5,16 @@ Detect UI anti-patterns and design quality issues from the command line. Scans H
5
5
  ## Quick Start
6
6
 
7
7
  ```bash
8
- # Scan files or directories
8
+ # Install skills into your AI harness (Claude, Cursor, Gemini, etc.)
9
+ npx impeccable skills install
10
+
11
+ # Update skills to the latest version
12
+ npx impeccable skills update
13
+
14
+ # List all available commands
15
+ npx impeccable skills help
16
+
17
+ # Scan files or directories for anti-patterns
9
18
  npx impeccable detect src/
10
19
 
11
20
  # Scan a live URL (requires Puppeteer)
package/README.npm.md CHANGED
@@ -5,7 +5,16 @@ Detect UI anti-patterns and design quality issues from the command line. Scans H
5
5
  ## Quick Start
6
6
 
7
7
  ```bash
8
- # Scan files or directories
8
+ # Install skills into your AI harness (Claude, Cursor, Gemini, etc.)
9
+ npx impeccable skills install
10
+
11
+ # Update skills to the latest version
12
+ npx impeccable skills update
13
+
14
+ # List all available commands
15
+ npx impeccable skills help
16
+
17
+ # Scan files or directories for anti-patterns
9
18
  npx impeccable detect src/
10
19
 
11
20
  # Scan a live URL (requires Puppeteer)
@@ -0,0 +1,514 @@
1
+ /**
2
+ * `impeccable skills` subcommand
3
+ *
4
+ * Usage:
5
+ * impeccable skills help Show all available skills and commands
6
+ * impeccable skills install Install skills via npx skills add
7
+ * impeccable skills update Update skills to latest version
8
+ */
9
+
10
+ import { execSync } from 'node:child_process';
11
+ import { existsSync, readFileSync, readdirSync, statSync, lstatSync, symlinkSync, readlinkSync, unlinkSync, mkdirSync, writeFileSync, rmSync, renameSync, createWriteStream } from 'node:fs';
12
+ import { join, resolve, dirname } from 'node:path';
13
+ import { createInterface } from 'node:readline';
14
+ import { fileURLToPath } from 'node:url';
15
+ import { get } from 'node:https';
16
+ import { tmpdir } from 'node:os';
17
+
18
+ const __dirname = dirname(fileURLToPath(import.meta.url));
19
+ const API_BASE = 'https://impeccable.style';
20
+
21
+ // Provider folder names in project roots
22
+ const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.codex', '.agents', '.kiro', '.opencode', '.pi', '.trae', '.trae-cn'];
23
+
24
+ function ask(question) {
25
+ const rl = createInterface({ input: process.stdin, output: process.stdout });
26
+ return new Promise(r => rl.question(question, ans => { rl.close(); r(ans.trim().toLowerCase()); }));
27
+ }
28
+
29
+ // ─── skills help ──────────────────────────────────────────────────────────────
30
+
31
+ async function showHelp() {
32
+ let commands;
33
+ try {
34
+ const res = await fetch(`${API_BASE}/api/commands`);
35
+ commands = await res.json();
36
+ } catch {
37
+ console.error('Could not fetch command list from impeccable.style. Check your network connection.');
38
+ process.exit(1);
39
+ }
40
+
41
+ const pad = (s, n) => s + ' '.repeat(Math.max(0, n - s.length));
42
+
43
+ console.log('\n Impeccable Skills & Commands\n');
44
+ console.log(' Install: npx impeccable skills install');
45
+ console.log(' Update: npx impeccable skills update');
46
+ console.log(' Docs: https://impeccable.style/cheatsheet\n');
47
+ console.log(` ${pad('Command', 22)} Description`);
48
+ console.log(` ${'-'.repeat(22)} ${'-'.repeat(52)}`);
49
+
50
+ for (const cmd of commands.sort((a, b) => a.id.localeCompare(b.id))) {
51
+ // Trim description to fit terminal
52
+ const desc = cmd.description.length > 72
53
+ ? cmd.description.substring(0, 69) + '...'
54
+ : cmd.description;
55
+ console.log(` ${pad('/' + cmd.id, 22)} ${desc}`);
56
+ }
57
+ console.log(`\n ${commands.length} commands available. Run /<command> in your AI harness.\n`);
58
+ }
59
+
60
+ // ─── skills install ───────────────────────────────────────────────────────────
61
+
62
+ // Check if impeccable skills are already present in any provider folder
63
+ function isAlreadyInstalled(root) {
64
+ for (const d of PROVIDER_DIRS) {
65
+ const skillsDir = join(root, d, 'skills');
66
+ if (!existsSync(skillsDir)) continue;
67
+ try {
68
+ const entries = readdirSync(skillsDir);
69
+ // Look for 'impeccable' skill (or prefixed variant, or legacy 'teach-impeccable')
70
+ if (entries.some(e =>
71
+ e === 'impeccable' || e.endsWith('-impeccable') ||
72
+ e === 'teach-impeccable' || e.endsWith('-teach-impeccable')
73
+ )) {
74
+ return d;
75
+ }
76
+ } catch {}
77
+ }
78
+ return null;
79
+ }
80
+
81
+ function escapeRegex(str) {
82
+ return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
83
+ }
84
+
85
+ function prefixSkillContent(content, prefix, allSkillNames) {
86
+ // Prefix the name in frontmatter
87
+ let result = content.replace(/^name:\s*(.+)$/m, (_, name) => `name: ${prefix}${name.trim()}`);
88
+
89
+ // Prefix cross-references: /skillname -> /prefix-skillname
90
+ const sorted = [...allSkillNames].sort((a, b) => b.length - a.length);
91
+ for (const name of sorted) {
92
+ // Command invocations: /skillname
93
+ result = result.replace(
94
+ new RegExp(`/(?=${escapeRegex(name)}(?:[^a-zA-Z0-9_-]|$))`, 'g'),
95
+ `/${prefix}`
96
+ );
97
+ // Prose references: "the skillname skill"
98
+ result = result.replace(
99
+ new RegExp(`(the) ${escapeRegex(name)} skill`, 'gi'),
100
+ (_, article) => `${article} ${prefix}${name} skill`
101
+ );
102
+ }
103
+ return result;
104
+ }
105
+
106
+ function isSkillDir(skillsDir, name) {
107
+ // Skill entries can be real directories or symlinks to directories (npx skills uses symlinks)
108
+ const full = join(skillsDir, name);
109
+ try {
110
+ return statSync(full).isDirectory() && existsSync(join(full, 'SKILL.md'));
111
+ } catch { return false; }
112
+ }
113
+
114
+ function isRealSkillDir(skillsDir, name) {
115
+ // Only real directories, not symlinks -- renaming the real dir renames the symlink targets too
116
+ const full = join(skillsDir, name);
117
+ try {
118
+ const lstat = lstatSync(full);
119
+ return lstat.isDirectory() && !lstat.isSymbolicLink() && existsSync(join(full, 'SKILL.md'));
120
+ } catch { return false; }
121
+ }
122
+
123
+ function renameSkillsWithPrefix(root, prefix) {
124
+ // First pass: collect all skill names across all providers (use first provider found)
125
+ let allSkillNames = [];
126
+ for (const d of PROVIDER_DIRS) {
127
+ const skillsDir = join(root, d, 'skills');
128
+ if (!existsSync(skillsDir)) continue;
129
+ const entries = readdirSync(skillsDir);
130
+ allSkillNames = entries.filter(name => isSkillDir(skillsDir, name));
131
+ if (allSkillNames.length > 0) break;
132
+ }
133
+
134
+ // Second pass: rename real dirs and update their content
135
+ let count = 0;
136
+ for (const d of PROVIDER_DIRS) {
137
+ const skillsDir = join(root, d, 'skills');
138
+ if (!existsSync(skillsDir)) continue;
139
+ try {
140
+ const entries = readdirSync(skillsDir);
141
+ for (const name of entries) {
142
+ if (name.startsWith(prefix)) continue;
143
+ if (!isRealSkillDir(skillsDir, name)) continue;
144
+
145
+ const src = join(skillsDir, name);
146
+ const dest = join(skillsDir, prefix + name);
147
+
148
+ renameSync(src, dest);
149
+
150
+ // Prefix frontmatter name + all cross-references in SKILL.md
151
+ let content = readFileSync(join(dest, 'SKILL.md'), 'utf8');
152
+ content = prefixSkillContent(content, prefix, allSkillNames);
153
+ writeFileSync(join(dest, 'SKILL.md'), content);
154
+ count++;
155
+ }
156
+ } catch {}
157
+ }
158
+
159
+ // Third pass: fix symlinks that now point to renamed targets (npx skills uses these)
160
+ for (const d of PROVIDER_DIRS) {
161
+ const skillsDir = join(root, d, 'skills');
162
+ if (!existsSync(skillsDir)) continue;
163
+ try {
164
+ const entries = readdirSync(skillsDir);
165
+ for (const name of entries) {
166
+ if (name.startsWith(prefix)) continue;
167
+ const full = join(skillsDir, name);
168
+ try {
169
+ if (!lstatSync(full).isSymbolicLink()) continue;
170
+ const target = readlinkSync(full);
171
+ const newTarget = target.replace(new RegExp(`/${escapeRegex(name)}$`), `/${prefix}${name}`);
172
+ unlinkSync(full);
173
+ symlinkSync(newTarget, join(skillsDir, prefix + name));
174
+ } catch {}
175
+ }
176
+ } catch {}
177
+ }
178
+
179
+ return count;
180
+ }
181
+
182
+ async function install(flags) {
183
+ const force = flags.includes('--force');
184
+ const yes = flags.includes('-y') || flags.includes('--yes');
185
+ const prefixFlag = flags.find(f => f.startsWith('--prefix='));
186
+ const root = findProjectRoot();
187
+ const existing = isAlreadyInstalled(root);
188
+
189
+ if (existing && !force) {
190
+ console.log(`Impeccable skills are already installed (found in ${existing}/).`);
191
+ console.log('Run with --force to reinstall.\n');
192
+ process.exit(0);
193
+ }
194
+
195
+ console.log('Installing impeccable skills via npx skills...\n');
196
+ try {
197
+ execSync(`npx skills add pbakaus/impeccable${yes ? ' -y' : ''}`, { stdio: 'inherit' });
198
+ } catch (e) {
199
+ process.exit(e.status ?? 1);
200
+ }
201
+
202
+ // Ask about prefixing (skip in CI mode unless --prefix= is set)
203
+ let prefix = '';
204
+ if (prefixFlag) {
205
+ prefix = prefixFlag.split('=')[1] || 'i-';
206
+ } else if (!yes) {
207
+ console.log();
208
+ const wantPrefix = await ask('Prefix commands to avoid conflicts? e.g. /i-audit instead of /audit (y/N) ');
209
+ if (wantPrefix === 'y' || wantPrefix === 'yes') {
210
+ const custom = await ask('Prefix (default: i-): ');
211
+ prefix = custom || 'i-';
212
+ }
213
+ }
214
+
215
+ if (prefix) {
216
+ const count = renameSkillsWithPrefix(root, prefix);
217
+ if (count > 0) {
218
+ console.log(`\nRenamed ${count} skills with "${prefix}" prefix.`);
219
+ console.log(`Commands are now available as /${prefix}<command> (e.g. /${prefix}audit).`);
220
+ }
221
+ }
222
+
223
+ console.log(`\nDone! Run /${prefix}impeccable teach in your AI harness to set up design context.\n`);
224
+ }
225
+
226
+ /** Detect prefix by looking for the 'impeccable' skill (or legacy 'teach-impeccable') */
227
+ function detectPrefix(root) {
228
+ for (const d of PROVIDER_DIRS) {
229
+ const skillsDir = join(root, d, 'skills');
230
+ if (!existsSync(skillsDir)) continue;
231
+ for (const name of readdirSync(skillsDir)) {
232
+ if (name === 'impeccable') return '';
233
+ if (name.endsWith('-impeccable') && name !== 'teach-impeccable') return name.slice(0, -'impeccable'.length);
234
+ // Legacy fallback
235
+ if (name === 'teach-impeccable') return '';
236
+ if (name.endsWith('-teach-impeccable')) return name.slice(0, -'teach-impeccable'.length);
237
+ }
238
+ }
239
+ return '';
240
+ }
241
+
242
+ /** Undo prefixing: rename folders back and strip prefix from SKILL.md content */
243
+ function undoPrefix(root, prefix) {
244
+ if (!prefix) return;
245
+ // Collect the unprefixed names (strip our prefix)
246
+ let allPrefixedNames = [];
247
+ for (const d of PROVIDER_DIRS) {
248
+ const skillsDir = join(root, d, 'skills');
249
+ if (!existsSync(skillsDir)) continue;
250
+ allPrefixedNames = readdirSync(skillsDir).filter(n => n.startsWith(prefix) && isRealSkillDir(skillsDir, n));
251
+ if (allPrefixedNames.length > 0) break;
252
+ }
253
+ const unprefixedNames = allPrefixedNames.map(n => n.slice(prefix.length));
254
+
255
+ for (const d of PROVIDER_DIRS) {
256
+ const skillsDir = join(root, d, 'skills');
257
+ if (!existsSync(skillsDir)) continue;
258
+ for (const name of readdirSync(skillsDir)) {
259
+ if (!name.startsWith(prefix)) continue;
260
+ const unprefixed = name.slice(prefix.length);
261
+ const src = join(skillsDir, name);
262
+ const dest = join(skillsDir, unprefixed);
263
+
264
+ if (lstatSync(src).isSymbolicLink()) {
265
+ const target = readlinkSync(src);
266
+ const newTarget = target.replace(`/${name}`, `/${unprefixed}`);
267
+ unlinkSync(src);
268
+ symlinkSync(newTarget, dest);
269
+ } else {
270
+ renameSync(src, dest);
271
+ // Strip prefix from SKILL.md content
272
+ const skillMd = join(dest, 'SKILL.md');
273
+ if (existsSync(skillMd)) {
274
+ let content = readFileSync(skillMd, 'utf8');
275
+ // Reverse the prefixing: replace prefixed names with unprefixed
276
+ content = content.replace(new RegExp(`^name:\\s*${escapeRegex(prefix)}`, 'm'), 'name: ');
277
+ const sorted = [...allPrefixedNames].sort((a, b) => b.length - a.length);
278
+ for (const pName of sorted) {
279
+ const uName = pName.slice(prefix.length);
280
+ content = content.replace(new RegExp(`/${escapeRegex(pName)}(?=[^a-zA-Z0-9_-]|$)`, 'g'), `/${uName}`);
281
+ content = content.replace(new RegExp(`(the) ${escapeRegex(pName)} skill`, 'gi'), `$1 ${uName} skill`);
282
+ }
283
+ writeFileSync(skillMd, content);
284
+ }
285
+ }
286
+ }
287
+ }
288
+ }
289
+
290
+ // ─── skills update ────────────────────────────────────────────────────────────
291
+
292
+ function findProjectRoot() {
293
+ let dir = process.cwd();
294
+ while (dir !== dirname(dir)) {
295
+ if (existsSync(join(dir, '.git'))) return dir;
296
+ dir = dirname(dir);
297
+ }
298
+ return process.cwd();
299
+ }
300
+
301
+ function findInstalledProviders(root) {
302
+ const found = [];
303
+ for (const d of PROVIDER_DIRS) {
304
+ const skillsDir = join(root, d, 'skills');
305
+ if (!existsSync(skillsDir)) continue;
306
+ try {
307
+ const entries = readdirSync(skillsDir);
308
+ if (entries.some(name => isSkillDir(skillsDir, name))) found.push(d);
309
+ } catch {}
310
+ }
311
+ return found;
312
+ }
313
+
314
+ function getModifiedSkillFiles(root, providerDirs) {
315
+ // Use git to check if any skill files have local modifications
316
+ const modified = [];
317
+ try {
318
+ const status = execSync('git status --porcelain', { cwd: root, encoding: 'utf8' });
319
+ for (const line of status.split('\n')) {
320
+ if (!line.trim()) continue;
321
+ const file = line.substring(3);
322
+ for (const d of providerDirs) {
323
+ if (file.startsWith(`${d}/skills/`)) {
324
+ const flag = line.substring(0, 2).trim();
325
+ modified.push({ file, flag });
326
+ }
327
+ }
328
+ }
329
+ } catch {
330
+ // Not a git repo or git not available
331
+ }
332
+ return modified;
333
+ }
334
+
335
+ function downloadFile(url, dest) {
336
+ return new Promise((resolve, reject) => {
337
+ const file = createWriteStream(dest);
338
+ get(url, (res) => {
339
+ if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
340
+ // Follow redirect
341
+ get(res.headers.location, (res2) => {
342
+ res2.pipe(file);
343
+ file.on('finish', () => { file.close(); resolve(); });
344
+ }).on('error', reject);
345
+ return;
346
+ }
347
+ if (res.statusCode !== 200) {
348
+ reject(new Error(`HTTP ${res.statusCode}`));
349
+ return;
350
+ }
351
+ res.pipe(file);
352
+ file.on('finish', () => { file.close(); resolve(); });
353
+ }).on('error', reject);
354
+ });
355
+ }
356
+
357
+ async function update(flags = []) {
358
+ const yes = flags.includes('-y') || flags.includes('--yes');
359
+ // Try npx skills update first
360
+ console.log('Checking for skills manager...');
361
+ let noLockFile = true;
362
+ try {
363
+ const output = execSync('npx skills check', { encoding: 'utf8', timeout: 15000 });
364
+ noLockFile = output.includes('No skills tracked');
365
+ } catch {
366
+ // npx skills not available or errored
367
+ }
368
+
369
+ if (!noLockFile) {
370
+ const root = findProjectRoot();
371
+ const prefix = detectPrefix(root);
372
+
373
+ // Temporarily undo prefix so npx skills can find its tracked skill names
374
+ if (prefix) {
375
+ console.log(`Detected "${prefix}" prefix, temporarily reverting for update...`);
376
+ undoPrefix(root, prefix);
377
+ }
378
+
379
+ console.log('Updating via npx skills...\n');
380
+ try {
381
+ execSync('npx skills update', { stdio: 'inherit' });
382
+ } catch (e) {
383
+ // Re-apply prefix even if update fails
384
+ if (prefix) renameSkillsWithPrefix(root, prefix);
385
+ process.exit(e.status ?? 1);
386
+ }
387
+
388
+ // Re-apply prefix after update
389
+ if (prefix) {
390
+ const count = renameSkillsWithPrefix(root, prefix);
391
+ console.log(`\nRe-applied "${prefix}" prefix to ${count} skills.`);
392
+ }
393
+ process.exit(0);
394
+ }
395
+
396
+ // Fallback: manual update by downloading the universal bundle
397
+ console.log('Skills not managed by npx skills. Using direct download.\n');
398
+
399
+ const root = findProjectRoot();
400
+ const providers = findInstalledProviders(root);
401
+
402
+ if (providers.length === 0) {
403
+ console.log('No impeccable skill folders found in this project.');
404
+ console.log('Run `npx impeccable skills install` to install first.');
405
+ process.exit(1);
406
+ }
407
+
408
+ console.log(`Found impeccable skills in: ${providers.join(', ')}`);
409
+
410
+ // Check for local modifications
411
+ const modified = getModifiedSkillFiles(root, providers);
412
+ if (modified.length > 0) {
413
+ console.log(`\n Warning: ${modified.length} skill file(s) have local changes:\n`);
414
+ for (const m of modified.slice(0, 10)) {
415
+ console.log(` ${m.flag} ${m.file}`);
416
+ }
417
+ if (modified.length > 10) console.log(` ... and ${modified.length - 10} more`);
418
+ console.log();
419
+ if (!yes) {
420
+ const ans = await ask(' Overwrite local changes? (y/N) ');
421
+ if (ans !== 'y' && ans !== 'yes') {
422
+ console.log('Aborted.');
423
+ process.exit(0);
424
+ }
425
+ }
426
+ } else if (!yes) {
427
+ const ans = await ask(`Update skills in ${providers.length} provider folder(s)? (Y/n) `);
428
+ if (ans === 'n' || ans === 'no') {
429
+ console.log('Aborted.');
430
+ process.exit(0);
431
+ }
432
+ }
433
+
434
+ // Download universal bundle
435
+ const tmpZip = join(tmpdir(), `impeccable-update-${Date.now()}.zip`);
436
+ console.log('\nDownloading latest skills...');
437
+ try {
438
+ await downloadFile(`${API_BASE}/api/download/bundle/universal`, tmpZip);
439
+ } catch (e) {
440
+ console.error(`Download failed: ${e.message}`);
441
+ process.exit(1);
442
+ }
443
+
444
+ // Extract and copy to each provider folder
445
+ let unzip;
446
+ try {
447
+ // Use built-in decompress if available (Node 22+), otherwise shell unzip
448
+ const tmpDir = join(tmpdir(), `impeccable-update-${Date.now()}`);
449
+ mkdirSync(tmpDir, { recursive: true });
450
+ execSync(`unzip -qo "${tmpZip}" -d "${tmpDir}"`, { encoding: 'utf8' });
451
+
452
+ // The universal bundle has provider folders at the top level
453
+ let updated = 0;
454
+ for (const provider of providers) {
455
+ const srcDir = join(tmpDir, provider, 'skills');
456
+ const destDir = join(root, provider, 'skills');
457
+ if (!existsSync(srcDir)) continue;
458
+
459
+ // Copy each skill folder
460
+ const skills = readdirSync(srcDir, { withFileTypes: true });
461
+ for (const skill of skills) {
462
+ if (!skill.isDirectory()) continue;
463
+ const src = join(srcDir, skill.name);
464
+ const dest = join(destDir, skill.name);
465
+ // Remove old and copy new
466
+ if (existsSync(dest)) rmSync(dest, { recursive: true });
467
+ copyDirSync(src, dest);
468
+ updated++;
469
+ }
470
+ }
471
+
472
+ // Cleanup
473
+ rmSync(tmpDir, { recursive: true, force: true });
474
+ rmSync(tmpZip, { force: true });
475
+
476
+ console.log(`Updated ${updated} skills across ${providers.length} provider(s).`);
477
+ console.log('Done!\n');
478
+ } catch (e) {
479
+ console.error(`Extract failed: ${e.message}`);
480
+ rmSync(tmpZip, { force: true });
481
+ process.exit(1);
482
+ }
483
+ }
484
+
485
+ function copyDirSync(src, dest) {
486
+ mkdirSync(dest, { recursive: true });
487
+ for (const entry of readdirSync(src, { withFileTypes: true })) {
488
+ const s = join(src, entry.name);
489
+ const d = join(dest, entry.name);
490
+ if (entry.isDirectory()) {
491
+ copyDirSync(s, d);
492
+ } else {
493
+ writeFileSync(d, readFileSync(s));
494
+ }
495
+ }
496
+ }
497
+
498
+ // ─── Router ───────────────────────────────────────────────────────────────────
499
+
500
+ export async function run(args) {
501
+ const sub = args[0];
502
+
503
+ if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
504
+ await showHelp();
505
+ } else if (sub === 'install') {
506
+ await install(args.slice(1));
507
+ } else if (sub === 'update') {
508
+ await update(args.slice(1));
509
+ } else {
510
+ console.error(`Unknown skills command: ${sub}`);
511
+ console.error(`Run 'impeccable skills --help' for available commands.`);
512
+ process.exit(1);
513
+ }
514
+ }