impeccable 3.0.1 → 3.0.2

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 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 41 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
3
+ Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 44 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
- 41 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 44 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 41 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
3
+ Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 44 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
- 41 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 44 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 41 deterministic detector rules for AI-generated frontend design.
3
+ Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 44 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
- - **41 deterministic detector rules** plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.
16
+ - **44 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
 
@@ -31,7 +31,7 @@ Start every new project with:
31
31
  /impeccable init
32
32
  ```
33
33
 
34
- `init` asks whether the surface is brand (marketing, landing, portfolio) or product (app UI, dashboard, tool), then writes project context that every later command reads.
34
+ `init` asks whether the surface is brand (marketing, landing, portfolio) or product (app UI, dashboard, tool), then writes design context that every later command reads.
35
35
 
36
36
  ### 23 Commands
37
37
 
@@ -270,12 +270,14 @@ Installed hook surfaces:
270
270
 
271
271
  The installer preserves unrelated hook entries and settings. If a hook manifest is malformed, install/update aborts by default; rerun with `--force` to back up the malformed file as `.bak` and replace it.
272
272
 
273
- On an interactive `install`/`update`, Impeccable explains the hook and offers to install it (default yes). Your choice is remembered per-developer in the gitignored `.impeccable/config.local.json`, so you are not asked again; `--no-hooks` skips it for that run without recording anything. Hook settings (enable/ignore rules, etc.) live under the `hook` key of `.impeccable/config.json`, managed with `/impeccable hooks`.
273
+ On an interactive `install`/`update`, Impeccable explains the hook and offers to install it (default yes). Your choice is remembered per-developer in the gitignored `.impeccable/config.local.json`, so you are not asked again; `--no-hooks` skips it for that run without recording anything. Hook lifecycle settings live under the `hook` key of `.impeccable/config.json`; detector ignores live under `detector`, shared by `/impeccable hooks` and `npx impeccable detect`.
274
274
 
275
275
  For debugging, set `hook.auditLog` in `.impeccable/config.json` to a path (or the legacy `IMPECCABLE_HOOK_LOG` env var) to write one NDJSON line per hook invocation. Leave it unset for normal use.
276
276
 
277
277
  Codex requires one platform step that Impeccable cannot safely skip: open `/hooks` after install or update and approve the project hook. There is no Codex marketplace/plugin install flow for this hook.
278
278
 
279
+ Full hook docs: [impeccable.style/docs/hooks](https://impeccable.style/docs/hooks).
280
+
279
281
  Manual copy commands are fallback/debug instructions. The normal path is:
280
282
 
281
283
  ```bash
@@ -291,10 +293,18 @@ Impeccable includes a standalone CLI for detecting anti-patterns without an AI h
291
293
  npx impeccable detect src/ # scan a directory
292
294
  npx impeccable detect index.html # scan an HTML file
293
295
  npx impeccable detect https://example.com # scan a URL (Puppeteer)
294
- npx impeccable detect --fast --json . # regex-only, JSON output
296
+ npx impeccable detect --json . # CI-friendly JSON output
297
+ npx impeccable detect --no-config src/ # raw scan, ignoring project config/context
298
+ npx impeccable ignores list # show detector ignores
299
+ npx impeccable ignores add-file "src/legacy/**"
300
+ npx impeccable ignores add-value overused-font Inter --reason "Brand font"
295
301
  ```
296
302
 
297
- The detector catches 41 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).
303
+ The detector catches 44 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).
304
+
305
+ 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.
306
+
307
+ Full detector docs: [impeccable.style/docs/detector](https://impeccable.style/docs/detector).
298
308
 
299
309
  ## Supported Tools
300
310
 
package/cli/bin/cli.js CHANGED
@@ -5,6 +5,7 @@
5
5
  *
6
6
  * Usage:
7
7
  * npx impeccable detect [file-or-dir-or-url...]
8
+ * npx impeccable ignores <list|add-file|add-value|remove-...>
8
9
  * npx impeccable help|install|update
9
10
  * npx impeccable --help
10
11
  */
@@ -25,6 +26,7 @@ async function main() {
25
26
 
26
27
  Commands:
27
28
  detect [file-or-dir-or-url...] Scan for UI anti-patterns and design quality issues
29
+ ignores Manage detector ignore rules, files, and values
28
30
  help List all available skills and commands
29
31
  install Install impeccable skills into your project or global harness
30
32
  link Symlink skills from a local checkout or submodule
@@ -50,6 +52,9 @@ Compatibility:
50
52
  process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
51
53
  const { detectCli } = await import('../engine/detect-antipatterns.mjs');
52
54
  await detectCli();
55
+ } else if (command === 'ignores' || command === 'ignore') {
56
+ const { run } = await import('./commands/ignores.mjs');
57
+ await run(args.slice(1));
53
58
  } else if (command === 'skills') {
54
59
  const { run } = await import('./commands/skills.mjs');
55
60
  await run(args.slice(1));
@@ -0,0 +1,330 @@
1
+ import path from 'node:path';
2
+
3
+ import {
4
+ getConfigPath,
5
+ getLocalConfigPath,
6
+ normalizeIgnoreValue,
7
+ readDetectionConfig,
8
+ readRawDetectionConfig,
9
+ writeDetectionConfig,
10
+ } from '../../lib/impeccable-config.mjs';
11
+
12
+ const ACTION_ALIASES = new Map([
13
+ ['status', 'list'],
14
+ ['ls', 'list'],
15
+ ['list', 'list'],
16
+ ['add-rule', 'add-rule'],
17
+ ['ignore-rule', 'add-rule'],
18
+ ['add-file', 'add-file'],
19
+ ['ignore-file', 'add-file'],
20
+ ['add-value', 'add-value'],
21
+ ['ignore-value', 'add-value'],
22
+ ['update-value', 'add-value'],
23
+ ['remove-rule', 'remove-rule'],
24
+ ['rm-rule', 'remove-rule'],
25
+ ['remove-file', 'remove-file'],
26
+ ['rm-file', 'remove-file'],
27
+ ['remove-value', 'remove-value'],
28
+ ['rm-value', 'remove-value'],
29
+ ['clear', 'clear'],
30
+ ]);
31
+
32
+ function printUsage() {
33
+ console.log(`Usage: impeccable ignores <action> [options]
34
+
35
+ Manage detector ignores in .impeccable config.
36
+
37
+ Actions:
38
+ list Show merged, shared, and local ignores
39
+ add-rule <rule> [--all-values] Ignore a rule
40
+ add-file <glob> Ignore files by glob
41
+ add-value <rule> <value> Ignore one rule/value pair
42
+ remove-rule <rule> Remove a rule ignore
43
+ remove-file <glob> Remove a file ignore
44
+ remove-value <rule> <value> Remove a rule/value ignore
45
+ clear Clear detector ignores in the selected scope
46
+
47
+ Scope:
48
+ --shared Write .impeccable/config.json (default)
49
+ --local Write .impeccable/config.local.json
50
+ --all For remove/clear, apply to shared and local
51
+
52
+ Value options:
53
+ --file <glob> Scope add-value/remove-value to a file glob
54
+ --reason <text> Store or update a reason on add-value
55
+
56
+ Examples:
57
+ impeccable ignores add-file "src/legacy/**"
58
+ impeccable ignores add-value overused-font Inter --reason "Brand font"
59
+ impeccable ignores add-value design-system-color "*" --file "src/demo.css"
60
+ impeccable ignores remove-value overused-font Inter`);
61
+ }
62
+
63
+ function parseScope(args, { allowAll = false } = {}) {
64
+ const rest = [];
65
+ let local = false;
66
+ let shared = false;
67
+ let all = false;
68
+ for (const arg of args) {
69
+ if (arg === '--local') local = true;
70
+ else if (arg === '--shared') shared = true;
71
+ else if (arg === '--all') all = true;
72
+ else rest.push(arg);
73
+ }
74
+ if ([local, shared, all].filter(Boolean).length > 1) {
75
+ throw new Error(`Pass only one scope flag: --shared${allowAll ? ', --local, or --all' : ' or --local'}`);
76
+ }
77
+ if (all && !allowAll) throw new Error('--all is only supported for remove and clear actions');
78
+ return { local, all, rest };
79
+ }
80
+
81
+ function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
82
+ const positionals = [];
83
+ const files = [];
84
+ let reason = '';
85
+
86
+ for (let i = 0; i < args.length; i++) {
87
+ const arg = String(args[i] || '');
88
+ if (arg === '--reason') {
89
+ const chunks = [];
90
+ while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) chunks.push(args[++i]);
91
+ reason = chunks.join(' ').trim();
92
+ } else if (arg.startsWith('--reason=')) {
93
+ reason = arg.slice('--reason='.length).trim();
94
+ } else if (arg === '--file' || arg === '--files') {
95
+ if (i + 1 >= args.length) throw new Error(`${arg} requires a glob`);
96
+ files.push(String(args[++i]).trim());
97
+ } else if (arg.startsWith('--file=')) {
98
+ files.push(arg.slice('--file='.length).trim());
99
+ } else if (arg.startsWith('--files=')) {
100
+ files.push(arg.slice('--files='.length).trim());
101
+ } else if (arg.startsWith('--')) {
102
+ throw new Error(`Unknown add-value flag: ${arg}`);
103
+ } else {
104
+ positionals.push(arg);
105
+ }
106
+ }
107
+
108
+ const [rule, ...valueParts] = positionals;
109
+ const value = normalizeIgnoreValue(valueParts.join(' '));
110
+ if (!rule || !value) throw new Error('Pass a rule id and value, e.g. impeccable ignores add-value overused-font Inter');
111
+ const scopedFiles = Array.from(new Set(files.filter(Boolean)));
112
+ if (value === '*' && scopedFiles.length === 0 && !allowUnscopedWildcard) {
113
+ throw new Error('Wildcard value ignores must be scoped with --file <glob>.');
114
+ }
115
+ return {
116
+ rule: String(rule).trim().toLowerCase(),
117
+ value,
118
+ files: scopedFiles,
119
+ reason,
120
+ };
121
+ }
122
+
123
+ function formatValues(values) {
124
+ if (!values.length) return '(none)';
125
+ return values
126
+ .map((entry) => {
127
+ const fileSuffix = Array.isArray(entry.files) && entry.files.length
128
+ ? ` [${entry.files.join(', ')}]`
129
+ : '';
130
+ const reasonSuffix = entry.reason ? ` - ${entry.reason}` : '';
131
+ return `${entry.rule}=${entry.value}${fileSuffix}${reasonSuffix}`;
132
+ })
133
+ .join(', ');
134
+ }
135
+
136
+ function formatConfig(label, config) {
137
+ return [
138
+ `${label}:`,
139
+ ` ignoreRules: ${config.ignoreRules.length ? config.ignoreRules.join(', ') : '(none)'}`,
140
+ ` ignoreFiles: ${config.ignoreFiles.length ? config.ignoreFiles.join(', ') : '(none)'}`,
141
+ ` ignoreValues: ${formatValues(config.ignoreValues)}`,
142
+ ` designSystem: ${config.designSystem?.enabled === false ? 'disabled' : 'enabled'}`,
143
+ ].join('\n');
144
+ }
145
+
146
+ function list(cwd) {
147
+ const merged = readDetectionConfig(cwd);
148
+ const shared = readRawDetectionConfig(cwd);
149
+ const local = readRawDetectionConfig(cwd, { local: true });
150
+ return [
151
+ 'Impeccable detector ignores',
152
+ ` shared file: ${path.relative(cwd, getConfigPath(cwd)) || getConfigPath(cwd)}`,
153
+ ` local file: ${path.relative(cwd, getLocalConfigPath(cwd)) || getLocalConfigPath(cwd)}`,
154
+ '',
155
+ formatConfig('Merged', merged),
156
+ '',
157
+ formatConfig('Shared', shared),
158
+ '',
159
+ formatConfig('Local', local),
160
+ ].join('\n');
161
+ }
162
+
163
+ function readScopeConfig(cwd, local) {
164
+ return readRawDetectionConfig(cwd, { local });
165
+ }
166
+
167
+ function writeScopeConfig(cwd, config, local) {
168
+ return writeDetectionConfig(cwd, config, { local });
169
+ }
170
+
171
+ function parseRuleArgs(args) {
172
+ const positionals = [];
173
+ let allValues = false;
174
+
175
+ for (let i = 0; i < args.length; i++) {
176
+ const arg = String(args[i] || '');
177
+ if (arg === '--all-values') {
178
+ allValues = true;
179
+ } else if (arg === '--reason') {
180
+ while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
181
+ } else if (arg.startsWith('--reason=')) {
182
+ // Accepted for symmetry with add-value; ignoreRules stores ids only.
183
+ } else if (arg.startsWith('--')) {
184
+ throw new Error(`Unknown add-rule flag: ${arg}`);
185
+ } else {
186
+ positionals.push(arg);
187
+ }
188
+ }
189
+
190
+ return {
191
+ rule: String(positionals[0] || '').trim().toLowerCase(),
192
+ allValues,
193
+ };
194
+ }
195
+
196
+ function addRule(cwd, args) {
197
+ const { local, rest } = parseScope(args);
198
+ const { rule, allValues } = parseRuleArgs(rest);
199
+ if (!rule) throw new Error('Pass a rule id, e.g. impeccable ignores add-rule side-tab');
200
+ if (rule === 'overused-font' && !allValues) {
201
+ throw new Error('overused-font is value-specific by default. Use add-value overused-font <font>, or add-rule overused-font --all-values for broad suppression.');
202
+ }
203
+ const config = readScopeConfig(cwd, local);
204
+ if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
205
+ const target = writeScopeConfig(cwd, config, local);
206
+ return `Added ${rule} to ${local ? 'local' : 'shared'} detector ignoreRules (${path.relative(cwd, target) || target}).`;
207
+ }
208
+
209
+ function addFile(cwd, args) {
210
+ const { local, rest } = parseScope(args);
211
+ const glob = String(rest[0] || '').trim();
212
+ if (!glob) throw new Error('Pass a glob, e.g. impeccable ignores add-file "src/legacy/**"');
213
+ const config = readScopeConfig(cwd, local);
214
+ if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
215
+ const target = writeScopeConfig(cwd, config, local);
216
+ return `Added ${glob} to ${local ? 'local' : 'shared'} detector ignoreFiles (${path.relative(cwd, target) || target}).`;
217
+ }
218
+
219
+ function addValue(cwd, args) {
220
+ const { local, rest } = parseScope(args);
221
+ const parsed = parseValueArgs(rest);
222
+ const config = readScopeConfig(cwd, local);
223
+ const key = ignoreValueKey(parsed);
224
+ const existing = config.ignoreValues.find((entry) => ignoreValueKey(entry) === key);
225
+ if (existing) {
226
+ if (parsed.reason) existing.reason = parsed.reason;
227
+ if (parsed.files.length) existing.files = parsed.files;
228
+ } else {
229
+ const entry = {
230
+ rule: parsed.rule,
231
+ value: parsed.value,
232
+ createdAt: new Date().toISOString(),
233
+ };
234
+ if (parsed.files.length) entry.files = parsed.files;
235
+ if (parsed.reason) entry.reason = parsed.reason;
236
+ config.ignoreValues.push(entry);
237
+ }
238
+ const target = writeScopeConfig(cwd, config, local);
239
+ return `Added ${parsed.rule}=${parsed.value} to ${local ? 'local' : 'shared'} detector ignoreValues (${path.relative(cwd, target) || target}).`;
240
+ }
241
+
242
+ function removeFromScopes(cwd, args, remover) {
243
+ const { local, all, rest } = parseScope(args, { allowAll: true });
244
+ const scopes = all ? [false, true] : [local];
245
+ const removed = [];
246
+ for (const isLocal of scopes) {
247
+ const config = readScopeConfig(cwd, isLocal);
248
+ const count = remover(config, rest);
249
+ if (count > 0) {
250
+ const target = writeScopeConfig(cwd, config, isLocal);
251
+ removed.push(`${count} from ${isLocal ? 'local' : 'shared'} (${path.relative(cwd, target) || target})`);
252
+ }
253
+ }
254
+ return removed.length ? `Removed ${removed.join(', ')}.` : 'No matching detector ignore found.';
255
+ }
256
+
257
+ function removeRule(cwd, args) {
258
+ return removeFromScopes(cwd, args, (config, rest) => {
259
+ const rule = String(rest[0] || '').trim().toLowerCase();
260
+ if (!rule) throw new Error('Pass a rule id, e.g. impeccable ignores remove-rule side-tab');
261
+ const before = config.ignoreRules.length;
262
+ config.ignoreRules = config.ignoreRules.filter((entry) => entry !== rule);
263
+ return before - config.ignoreRules.length;
264
+ });
265
+ }
266
+
267
+ function removeFile(cwd, args) {
268
+ return removeFromScopes(cwd, args, (config, rest) => {
269
+ const glob = String(rest[0] || '').trim();
270
+ if (!glob) throw new Error('Pass a glob, e.g. impeccable ignores remove-file "src/legacy/**"');
271
+ const before = config.ignoreFiles.length;
272
+ config.ignoreFiles = config.ignoreFiles.filter((entry) => entry !== glob);
273
+ return before - config.ignoreFiles.length;
274
+ });
275
+ }
276
+
277
+ function removeValue(cwd, args) {
278
+ return removeFromScopes(cwd, args, (config, rest) => {
279
+ const parsed = parseValueArgs(rest, { allowUnscopedWildcard: true });
280
+ const key = ignoreValueKey(parsed);
281
+ const before = config.ignoreValues.length;
282
+ config.ignoreValues = config.ignoreValues.filter((entry) => ignoreValueKey(entry) !== key);
283
+ return before - config.ignoreValues.length;
284
+ });
285
+ }
286
+
287
+ function clear(cwd, args) {
288
+ const { local, all, rest } = parseScope(args, { allowAll: true });
289
+ if (rest.length > 0) throw new Error('clear does not take positional arguments');
290
+ const scopes = all ? [false, true] : [local];
291
+ for (const isLocal of scopes) {
292
+ const config = readScopeConfig(cwd, isLocal);
293
+ config.ignoreRules = [];
294
+ config.ignoreFiles = [];
295
+ config.ignoreValues = [];
296
+ writeScopeConfig(cwd, config, isLocal);
297
+ }
298
+ return `Cleared detector ignores in ${all ? 'shared and local config' : local ? 'local config' : 'shared config'}.`;
299
+ }
300
+
301
+ function ignoreValueKey(entry) {
302
+ const files = Array.isArray(entry.files) && entry.files.length ? entry.files.join('\x1f') : '';
303
+ return `${String(entry.rule || '').trim().toLowerCase()}\0${normalizeIgnoreValue(entry.value)}\0${files}`;
304
+ }
305
+
306
+ export async function run(args = [], opts = {}) {
307
+ const cwd = opts.cwd || process.cwd();
308
+ const actionArg = args[0] || 'list';
309
+ if (actionArg === '--help' || actionArg === '-h') {
310
+ printUsage();
311
+ return;
312
+ }
313
+ const action = ACTION_ALIASES.get(String(actionArg).toLowerCase());
314
+ if (!action) {
315
+ throw new Error(`Unknown ignores action: ${actionArg}. Run "impeccable ignores --help".`);
316
+ }
317
+ const rest = args.slice(1);
318
+ let out;
319
+ switch (action) {
320
+ case 'list': out = list(cwd); break;
321
+ case 'add-rule': out = addRule(cwd, rest); break;
322
+ case 'add-file': out = addFile(cwd, rest); break;
323
+ case 'add-value': out = addValue(cwd, rest); break;
324
+ case 'remove-rule': out = removeRule(cwd, rest); break;
325
+ case 'remove-file': out = removeFile(cwd, rest); break;
326
+ case 'remove-value': out = removeValue(cwd, rest); break;
327
+ case 'clear': out = clear(cwd, rest); break;
328
+ }
329
+ if (out) console.log(out);
330
+ }
@@ -10,13 +10,13 @@
10
10
 
11
11
  import { execSync } from 'node:child_process';
12
12
  import { existsSync, readFileSync, readdirSync, statSync, lstatSync, unlinkSync, mkdirSync, writeFileSync, rmSync, renameSync, createWriteStream, realpathSync, symlinkSync, readlinkSync, cpSync } from 'node:fs';
13
- import { join, resolve, dirname, relative, isAbsolute } from 'node:path';
13
+ import { join, resolve, dirname, relative, isAbsolute, sep } from 'node:path';
14
14
  import { createInterface, emitKeypressEvents } from 'node:readline';
15
15
  import { fileURLToPath } from 'node:url';
16
16
  import { get } from 'node:https';
17
17
  import { createHash } from 'node:crypto';
18
18
  import { tmpdir, homedir } from 'node:os';
19
- import extract from 'extract-zip';
19
+ import { unzipSync } from 'fflate';
20
20
  import { getHookConsent, setHookConsent } from '../../lib/impeccable-config.mjs';
21
21
 
22
22
  const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -436,6 +436,37 @@ function hashSkillsDir(skillsDir) {
436
436
  return entries.join(',');
437
437
  }
438
438
 
439
+ /**
440
+ * Extract every entry of a zip archive into `targetDir`.
441
+ *
442
+ * This replaces `extract-zip`, whose `yauzl`/`fd-slicer` read stack stalls on
443
+ * Node v24.16.0 / v26.1.0+ (nodejs/node#63487): `pause()`/`resume()` became
444
+ * no-ops on destroyed streams, so extraction stops after a handful of entries,
445
+ * its promise never settles, and -- because nothing else keeps the event loop
446
+ * alive -- the CLI exits 0 with no error, silently installing nothing.
447
+ *
448
+ * `fflate` decompresses from an in-memory buffer and never touches the fs
449
+ * stream path, so it is immune to that regression on every Node version. It is
450
+ * pure JS with zero dependencies, which keeps the Windows fix from #198 intact
451
+ * (no `unzip` binary required). We write the entries to disk ourselves, which
452
+ * lets us guard against zip-slip (`../` entries escaping `targetDir`).
453
+ */
454
+ async function extractZip(zipPath, targetDir) {
455
+ const entries = unzipSync(readFileSync(zipPath));
456
+ const root = resolve(targetDir);
457
+ for (const [entryPath, bytes] of Object.entries(entries)) {
458
+ // Directory entries arrive as zero-length names ending in `/`; the files
459
+ // beneath them create their parents via mkdirSync below.
460
+ if (entryPath.endsWith('/')) continue;
461
+ const dest = resolve(root, entryPath);
462
+ if (dest !== root && !dest.startsWith(root + sep)) {
463
+ throw new Error(`Refusing to extract entry outside target dir: ${entryPath}`);
464
+ }
465
+ mkdirSync(dirname(dest), { recursive: true });
466
+ writeFileSync(dest, bytes);
467
+ }
468
+ }
469
+
439
470
  /**
440
471
  * Download the universal bundle to a temp dir and return its path.
441
472
  * Caller is responsible for cleanup.
@@ -448,7 +479,7 @@ async function downloadAndExtractBundle() {
448
479
  const tmpDir = join(tmpdir(), `impeccable-update-${Date.now()}`);
449
480
  await downloadFile(`${API_BASE}/api/download/bundle/universal`, tmpZip);
450
481
  mkdirSync(tmpDir, { recursive: true });
451
- await extract(tmpZip, { dir: tmpDir });
482
+ await extractZip(tmpZip, tmpDir);
452
483
  rmSync(tmpZip, { force: true });
453
484
  return tmpDir;
454
485
  }
@@ -467,7 +498,7 @@ async function copyOrExtractLocalBundle(sourceValue) {
467
498
  return tmpDir;
468
499
  }
469
500
 
470
- await extract(source, { dir: tmpDir });
501
+ await extractZip(source, tmpDir);
471
502
  return tmpDir;
472
503
  }
473
504
 
@@ -1701,6 +1732,7 @@ export {
1701
1732
  copyProviderSkills,
1702
1733
  decideHookInstall,
1703
1734
  expectedHookDests,
1735
+ extractZip,
1704
1736
  formatInstallDetectionLines,
1705
1737
  linkProviderSkills,
1706
1738
  mergeHookManifests,