impeccable 3.5.0 → 3.6.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.
@@ -9,11 +9,12 @@
9
9
  */
10
10
 
11
11
  import { execSync } from 'node:child_process';
12
- import { existsSync, readFileSync, readdirSync, statSync, lstatSync, unlinkSync, mkdirSync, writeFileSync, rmSync, rmdirSync, renameSync, createWriteStream, realpathSync, symlinkSync, readlinkSync, cpSync } from 'node:fs';
13
- import { join, resolve, dirname, relative, isAbsolute, sep } from 'node:path';
12
+ import { existsSync, readFileSync, readdirSync, statSync, accessSync, constants, lstatSync, unlinkSync, mkdirSync, mkdtempSync, writeFileSync, rmSync, rmdirSync, renameSync, createWriteStream, realpathSync, symlinkSync, readlinkSync, cpSync } from 'node:fs';
13
+ import { join, resolve, dirname, relative, isAbsolute, sep, delimiter } from 'node:path';
14
14
  import { createInterface, emitKeypressEvents } from 'node:readline';
15
+ import { Readable } from 'node:stream';
16
+ import { pipeline } from 'node:stream/promises';
15
17
  import { fileURLToPath } from 'node:url';
16
- import { get } from 'node:https';
17
18
  import { createHash } from 'node:crypto';
18
19
  import { tmpdir, homedir } from 'node:os';
19
20
  import { unzipSync } from 'fflate';
@@ -23,9 +24,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
23
24
  const API_BASE = 'https://impeccable.style';
24
25
 
25
26
  // Provider folder names in project roots
26
- const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.grok', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn', '.rovodev', '.vibe'];
27
+ const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.agent', '.github', '.grok', '.hermes', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn', '.rovodev', '.vibe', '.veto'];
27
28
  const PROVIDER_ALIASES = {
29
+ agent: '.agent',
28
30
  agents: '.agents',
31
+ antigravity: '.agent',
29
32
  claude: '.claude',
30
33
  'claude-code': '.claude',
31
34
  codex: '.agents',
@@ -35,6 +38,7 @@ const PROVIDER_ALIASES = {
35
38
  github: '.github',
36
39
  grok: '.grok',
37
40
  'grok-build': '.grok',
41
+ hermes: '.hermes',
38
42
  xai: '.grok',
39
43
  kiro: '.kiro',
40
44
  opencode: '.opencode',
@@ -45,15 +49,18 @@ const PROVIDER_ALIASES = {
45
49
  trae: '.trae',
46
50
  'trae-cn': '.trae-cn',
47
51
  vibe: '.vibe',
52
+ veto: '.veto',
48
53
  };
49
54
 
50
55
  const PROVIDER_DISPLAY = {
56
+ '.agent': { name: 'Antigravity', input: 'antigravity' },
51
57
  '.agents': { name: 'Codex CLI', input: 'codex' },
52
58
  '.claude': { name: 'Claude Code', input: 'claude' },
53
59
  '.cursor': { name: 'Cursor', input: 'cursor' },
54
60
  '.gemini': { name: 'Gemini CLI', input: 'gemini' },
55
61
  '.github': { name: 'GitHub Copilot', input: 'github' },
56
62
  '.grok': { name: 'Grok Build', input: 'grok' },
63
+ '.hermes': { name: 'Hermes Agent', input: 'hermes' },
57
64
  '.kiro': { name: 'Kiro', input: 'kiro' },
58
65
  '.opencode': { name: 'OpenCode', input: 'opencode' },
59
66
  '.pi': { name: 'Pi Coding Agent', input: 'pi' },
@@ -62,8 +69,9 @@ const PROVIDER_DISPLAY = {
62
69
  '.trae': { name: 'Trae', input: 'trae' },
63
70
  '.trae-cn': { name: 'Trae CN', input: 'trae-cn' },
64
71
  '.vibe': { name: 'Mistral Vibe', input: 'vibe' },
72
+ '.veto': { name: 'Veto', input: 'veto' },
65
73
  };
66
- const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'grok', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev', 'vibe'];
74
+ const PROVIDER_INPUT_ORDER = ['antigravity', 'claude', 'codex', 'cursor', 'gemini', 'github', 'grok', 'hermes', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev', 'vibe', 'veto'];
67
75
 
68
76
  // OpenCode reads global skills from its config directory, not ~/.opencode:
69
77
  // $OPENCODE_CONFIG_DIR, else $XDG_CONFIG_HOME/opencode, else
@@ -75,11 +83,52 @@ function opencodeGlobalConfigDir(home) {
75
83
  return join(home, '.config', 'opencode');
76
84
  }
77
85
 
86
+ // Hermes reads skills from `$HERMES_HOME/skills/`, where $HERMES_HOME defaults
87
+ // to `~/.hermes` but is also set to a profile path (e.g.
88
+ // `~/.hermes/profiles/forge`) when a non-default profile is active. Reading
89
+ // the env var matters here at install time: writing to `~/.hermes/skills/`
90
+ // from a profile-scoped Hermes invocation would land in the wrong profile
91
+ // (the same cross-profile data-corruption class that the active_profile
92
+ // fallback warning in hermes_constants.py exists to detect). Used by
93
+ // HOME_SKILLS_DIR_OVERRIDES['.hermes'] only; GLOBAL_HARNESS_HINTS reads the
94
+ // fixed `~/.hermes` location so detection doesn't leak the developer's real
95
+ // HERMES_HOME into test output (test isolation).
96
+ //
97
+ // Ignore $HERMES_HOME when it doesn't sit under `home` (the caller-supplied
98
+ // home dir, which tests inject via HOME=/tmp/...). Without this guard, an
99
+ // inherited $HERMES_HOME=/home/<dev>/.hermes from the developer's shell leaks
100
+ // into test output even when the test sets HOME=/tmp/imp-home-xxx: tests
101
+ // expect ~/.hermes to live under their tmp home, not under the dev's real
102
+ // home. The check uses `resolve()` on both sides so a symlinked test home
103
+ // (e.g. /tmp -> /private/tmp on macOS) still compares correctly.
104
+ function hermesGlobalHome(home) {
105
+ const envHome = process.env.HERMES_HOME;
106
+ if (envHome) {
107
+ try {
108
+ const resolvedEnv = resolve(envHome);
109
+ const resolvedHome = resolve(home);
110
+ // Honor HERMES_HOME only when it lives under the active home (real
111
+ // ~/.hermes or ~/.hermes/profiles/<name>). Cross-home inheritance is
112
+ // treated as not-set, so a test running under HOME=/tmp/... doesn't
113
+ // pick up the developer's real ~/.hermes.
114
+ if (resolvedEnv === resolvedHome || resolvedEnv.startsWith(resolvedHome + sep)) {
115
+ return resolvedEnv;
116
+ }
117
+ } catch {
118
+ // fall through to default
119
+ }
120
+ }
121
+ return join(home, '.hermes');
122
+ }
123
+
78
124
  // Providers whose GLOBAL (home) skills dir is not `<provider>/skills`,
79
125
  // as a function of the home dir. Pi discovers global skills from
80
126
  // ~/.pi/agent/skills/ (issue #327); OpenCode from its config dir (issue
81
- // #406). Project scope stays `<provider>/skills` for both.
127
+ // #406); Hermes from $HERMES_HOME. Project scope stays `<provider>/skills`
128
+ // for all three.
82
129
  const HOME_SKILLS_DIR_OVERRIDES = {
130
+ '.agent': (home) => join(home, '.gemini', 'config', 'skills'),
131
+ '.hermes': (home) => join(hermesGlobalHome(home), 'skills'),
83
132
  '.pi': (home) => join(home, '.pi', 'agent', 'skills'),
84
133
  '.opencode': (home) => join(opencodeGlobalConfigDir(home), 'skills'),
85
134
  };
@@ -87,12 +136,27 @@ const HOME_SKILLS_DIR_OVERRIDES = {
87
136
  // When a project has no harness folder yet, infer the target from globally
88
137
  // installed harnesses (~/.claude, ~/.codex, ...). Codex reads skills from
89
138
  // .agents/skills, so ~/.codex maps to the .agents bundle variant.
139
+ //
140
+ // Hermes auto-detection uses the fixed `~/.hermes` location only. When a
141
+ // non-default Hermes profile is active (HERMES_HOME points to a profile path),
142
+ // the user is expected to be inside a Hermes invocation and can pass
143
+ // --providers=hermes explicitly. Auto-detection from a non-default HERMES_HOME
144
+ // would also defeat test isolation (tests inject HOME; HERMES_HOME leaks from
145
+ // the parent process and would surface the developer's real ~/.hermes in
146
+ // detection output). The install path honors $HERMES_HOME; detection does not.
90
147
  const GLOBAL_HARNESS_HINTS = [
148
+ { home: '.agent', provider: '.agent' },
149
+ // Antigravity nests under ~/.gemini/ too, so any of these also trips the
150
+ // .gemini hint above (harmless double-detection — both get pre-selected).
151
+ { home: '.gemini/antigravity', provider: '.agent' },
152
+ { home: '.gemini/antigravity-cli', provider: '.agent' },
153
+ { home: '.gemini/antigravity-ide', provider: '.agent' },
91
154
  { home: '.claude', provider: '.claude' },
92
155
  { home: '.codex', provider: '.agents' },
93
156
  { home: '.cursor', provider: '.cursor' },
94
157
  { home: '.gemini', provider: '.gemini' },
95
158
  { home: '.grok', provider: '.grok' },
159
+ { home: '.hermes', provider: '.hermes' },
96
160
  { home: '.kiro', provider: '.kiro' },
97
161
  { home: '.opencode', provider: '.opencode' },
98
162
  // OpenCode's real global config dir (issue #406); the ~/.opencode entry
@@ -102,6 +166,10 @@ const GLOBAL_HARNESS_HINTS = [
102
166
  { home: '.qoder', provider: '.qoder' },
103
167
  { home: '.rovodev', provider: '.rovodev' },
104
168
  { home: '.vibe', provider: '.vibe' },
169
+ // Veto is a CLI harness whose managed skill directory is ~/.veto/skills.
170
+ // Require its managed state directory as well as the executable so an
171
+ // unrelated `veto` binary on PATH does not change project install defaults.
172
+ { command: 'veto', provider: '.veto' },
105
173
  ];
106
174
 
107
175
  // Last-resort default when nothing is detected: Claude Code + the universal
@@ -561,13 +629,17 @@ async function downloadAndExtractBundle() {
561
629
  const localBundle = process.env.IMPECCABLE_BUNDLE_PATH;
562
630
  if (localBundle) return copyOrExtractLocalBundle(localBundle);
563
631
 
564
- const tmpZip = join(tmpdir(), `impeccable-update-${Date.now()}.zip`);
565
- const tmpDir = join(tmpdir(), `impeccable-update-${Date.now()}`);
566
- await downloadFile(`${API_BASE}/api/download/bundle/universal`, tmpZip);
567
- mkdirSync(tmpDir, { recursive: true });
568
- await extractZip(tmpZip, tmpDir);
569
- rmSync(tmpZip, { force: true });
570
- return tmpDir;
632
+ const staging = mkdtempSync(join(tmpdir(), 'impeccable-update-'));
633
+ const tmpZip = join(staging, 'bundle.zip');
634
+ try {
635
+ await downloadFile(`${API_BASE}/api/download/bundle/universal`, tmpZip);
636
+ await extractZip(tmpZip, staging);
637
+ rmSync(tmpZip, { force: true });
638
+ return staging;
639
+ } catch (e) {
640
+ rmSync(staging, { recursive: true, force: true });
641
+ throw e;
642
+ }
571
643
  }
572
644
 
573
645
  async function copyOrExtractLocalBundle(sourceValue) {
@@ -576,16 +648,18 @@ async function copyOrExtractLocalBundle(sourceValue) {
576
648
  throw new Error(`Local bundle not found: ${source}`);
577
649
  }
578
650
 
579
- const tmpDir = join(tmpdir(), `impeccable-local-bundle-${process.pid}-${Date.now()}`);
580
- mkdirSync(tmpDir, { recursive: true });
581
-
582
- if (statSync(source).isDirectory()) {
583
- cpSync(source, tmpDir, { recursive: true });
584
- return tmpDir;
651
+ const staging = mkdtempSync(join(tmpdir(), 'impeccable-local-bundle-'));
652
+ try {
653
+ if (statSync(source).isDirectory()) {
654
+ cpSync(source, staging, { recursive: true });
655
+ } else {
656
+ await extractZip(source, staging);
657
+ }
658
+ return staging;
659
+ } catch (e) {
660
+ rmSync(staging, { recursive: true, force: true });
661
+ throw e;
585
662
  }
586
-
587
- await extractZip(source, tmpDir);
588
- return tmpDir;
589
663
  }
590
664
 
591
665
  /**
@@ -598,7 +672,7 @@ async function copyOrExtractLocalBundle(sourceValue) {
598
672
  */
599
673
  function normalizeForHash(content) {
600
674
  return content
601
- .replace(/\.(claude|cursor|agents|github|gemini|codex|grok|kiro|opencode|pi|qoder|trae|trae-cn|rovodev|vibe)\/skills\//g, '.PROVIDER/skills/');
675
+ .replace(/\.(claude|cursor|agents|agent|github|gemini|codex|grok|hermes|kiro|opencode|pi|qoder|trae|trae-cn|rovodev|vibe|veto)\/skills\//g, '.PROVIDER/skills/');
602
676
  }
603
677
 
604
678
  function hashSkillFile(filePath) {
@@ -638,7 +712,7 @@ function deduplicateProviders(root, providers, scope) {
638
712
  * SKILL.md, so script-only fixes and removed files are detected.
639
713
  * Returns true if every bundle skill matches the local copy.
640
714
  */
641
- function isUpToDate(root, providers, bundleDir, scope) {
715
+ function isUpToDate(root, providers, bundleDir, scope, agentScope = scope) {
642
716
  const unique = deduplicateProviders(root, providers, scope);
643
717
  if (unique.length === 0) return false;
644
718
 
@@ -663,6 +737,8 @@ function isUpToDate(root, providers, bundleDir, scope) {
663
737
  if (bundleHash !== localHash) return false;
664
738
  }
665
739
  }
740
+
741
+ if (!providerAgentsUpToDate(bundleDir, root, provider, agentScope)) return false;
666
742
  }
667
743
  return true;
668
744
  }
@@ -684,7 +760,8 @@ async function check() {
684
760
  console.log('Checking for updates...\n');
685
761
  try {
686
762
  const bundleDir = await downloadAndExtractBundle();
687
- const upToDate = isUpToDate(root, providers, bundleDir);
763
+ const agentScope = isHomeDir(root) ? 'user' : undefined;
764
+ const upToDate = isUpToDate(root, providers, bundleDir, undefined, agentScope);
688
765
  rmSync(bundleDir, { recursive: true, force: true });
689
766
 
690
767
  if (upToDate) {
@@ -861,6 +938,25 @@ function userSkillProbePaths(home, harnessDir, provider) {
861
938
  ]);
862
939
  }
863
940
 
941
+ function commandOnPath(command) {
942
+ const candidates = process.platform === 'win32'
943
+ ? [`${command}.exe`, `${command}.cmd`, `${command}.bat`]
944
+ : [command];
945
+ for (const directory of String(process.env.PATH || '').split(delimiter)) {
946
+ if (!directory) continue;
947
+ for (const candidate of candidates) {
948
+ const path = resolve(directory, candidate);
949
+ try {
950
+ if (statSync(path).isFile()) {
951
+ accessSync(path, constants.X_OK);
952
+ return path;
953
+ }
954
+ } catch {}
955
+ }
956
+ }
957
+ return null;
958
+ }
959
+
864
960
  function collectInstallDetections(root, home = homedir()) {
865
961
  const detections = [];
866
962
  for (const provider of PROVIDER_DIRS) {
@@ -881,9 +977,14 @@ function collectInstallDetections(root, home = homedir()) {
881
977
  const { provider } = hint;
882
978
  // A hint is either a fixed dir under home or a resolver for harnesses
883
979
  // whose location depends on the environment (OpenCode's config dir).
884
- const foundPath = hint.resolve ? hint.resolve(home) : join(home, hint.home);
885
- if (!existsSync(foundPath)) continue;
886
- const skillProbePaths = hint.resolve
980
+ const foundPath = hint.command
981
+ ? commandOnPath(hint.command)
982
+ : hint.resolve ? hint.resolve(home) : join(home, hint.home);
983
+ if (!foundPath || (!hint.command && !existsSync(foundPath))) continue;
984
+ if (hint.command && !existsSync(join(home, '.veto'))) continue;
985
+ const skillProbePaths = hint.command
986
+ ? [userProviderSkillsDir(home, provider)]
987
+ : hint.resolve
887
988
  ? uniquePaths([userProviderSkillsDir(home, provider), join(foundPath, 'skills')])
888
989
  : userSkillProbePaths(home, hint.home, provider);
889
990
  detections.push({
@@ -894,7 +995,7 @@ function collectInstallDetections(root, home = homedir()) {
894
995
  installPath: userProviderSkillsDir(home, provider),
895
996
  skillProbePaths,
896
997
  hasRealSkills: skillProbePaths.some(hasRealSkillEntries),
897
- reason: 'user harness folder',
998
+ reason: hint.command ? 'CLI on PATH' : 'user harness folder',
898
999
  });
899
1000
  }
900
1001
  return detections;
@@ -1088,13 +1189,13 @@ async function chooseInstallScope(projectRoot, targets, detections, { yes, scope
1088
1189
  async function chooseInstallPlan(projectRoot, flags, { yes } = {}) {
1089
1190
  const providersValue = getFlagValue(flags, '--providers');
1090
1191
  const scopeValue = getInstallScopeValue(flags);
1091
- const { targets, detections } = await chooseInstallProviders(projectRoot, providersValue, { yes });
1192
+ const { targets, detections, explicit } = await chooseInstallProviders(projectRoot, providersValue, { yes });
1092
1193
  if (targets.length === 0) {
1093
1194
  throw new Error('Could not determine a target harness folder.');
1094
1195
  }
1095
1196
  const scope = await chooseInstallScope(projectRoot, targets, detections, { yes, scopeValue });
1096
1197
  const installRoot = installRootForScope(scope, projectRoot);
1097
- return { targets, scope, installRoot, hookRoot: projectRoot, detections };
1198
+ return { targets, scope, installRoot, hookRoot: projectRoot, detections, explicit };
1098
1199
  }
1099
1200
 
1100
1201
  /**
@@ -1190,7 +1291,9 @@ function copyProviderSkills(bundleDir, root, targets, { scope } = {}) {
1190
1291
  }
1191
1292
 
1192
1293
  // Native subagent definitions that ship in the bundle next to a provider's
1193
- // skills. GitHub Copilot's live at `.github/agents/impeccable-*.agent.md`:
1294
+ // skills. Claude Code's live at `.claude/agents/impeccable-*.md`; project
1295
+ // agents take precedence over user agents. GitHub Copilot's live at
1296
+ // `.github/agents/impeccable-*.agent.md`:
1194
1297
  // project installs commit them at `<repo>/.github/agents/`, user-level
1195
1298
  // installs go to `~/.copilot/agents/` (Copilot's user-scope dir, NOT
1196
1299
  // `~/.github/`). On a name conflict Copilot lets the user-level file shadow
@@ -1200,6 +1303,11 @@ function copyProviderSkills(bundleDir, root, targets, { scope } = {}) {
1200
1303
  // `~/.cursor/agents/`; project agents take precedence there, so no shadow
1201
1304
  // warning is needed.
1202
1305
  const PROVIDER_AGENT_ARTIFACTS = {
1306
+ '.claude': {
1307
+ ext: '.md',
1308
+ userDir: home => join(home, '.claude', 'agents'),
1309
+ userShadowsProject: false,
1310
+ },
1203
1311
  '.github': {
1204
1312
  ext: '.agent.md',
1205
1313
  userDir: home => join(home, '.copilot', 'agents'),
@@ -1212,6 +1320,23 @@ const PROVIDER_AGENT_ARTIFACTS = {
1212
1320
  },
1213
1321
  };
1214
1322
 
1323
+ function providerAgentsUpToDate(bundleDir, root, provider, scope) {
1324
+ const artifact = PROVIDER_AGENT_ARTIFACTS[provider];
1325
+ if (!artifact) return true;
1326
+ const srcDir = join(bundleDir, provider, 'agents');
1327
+ if (!existsSync(srcDir)) return true;
1328
+
1329
+ const destDir = scope === 'user'
1330
+ ? artifact.userDir(root)
1331
+ : join(root, provider, 'agents');
1332
+ const agentFiles = readdirSync(srcDir).filter(name => name.endsWith(artifact.ext));
1333
+ return agentFiles.every(name => {
1334
+ const localPath = join(destDir, name);
1335
+ return existsSync(localPath)
1336
+ && hashSkillFile(join(srcDir, name)) === hashSkillFile(localPath);
1337
+ });
1338
+ }
1339
+
1215
1340
  function copyProviderAgents(bundleDir, root, providers, { scope, home = homedir() } = {}) {
1216
1341
  const targets = Array.isArray(providers) ? providers : [providers];
1217
1342
  const results = [];
@@ -1314,7 +1439,7 @@ function hookScriptPathForProvider(skillRoot, provider) {
1314
1439
  if (provider === '.cursor') {
1315
1440
  return join(skillRoot, provider, 'skills', 'impeccable', 'scripts', 'hook-before-edit.mjs');
1316
1441
  }
1317
- if (provider === '.claude' || provider === '.agents') {
1442
+ if (provider === '.claude' || provider === '.agents' || provider === '.grok') {
1318
1443
  return join(skillRoot, provider, 'skills', 'impeccable', 'scripts', 'hook.mjs');
1319
1444
  }
1320
1445
  return null;
@@ -1328,8 +1453,53 @@ function hookScriptPathForProvider(skillRoot, provider) {
1328
1453
  // code when the file exists, so Claude's exit-2 blocking signal still reaches
1329
1454
  // the agent. POSIX-shell form, consistent with the project's other hook
1330
1455
  // commands (e.g. the GitHub manifest's `$(git rev-parse ...)`).
1331
- function guardHookCommand(quotedPath) {
1332
- return `[ ! -f ${quotedPath} ] || node ${quotedPath}`;
1456
+ //
1457
+ // On Windows that guard is a hard failure, not a degraded one (issue #452).
1458
+ // Codex runs hook commands through COMSPEC (`cmd.exe /C`), where `[` is not a
1459
+ // command: the guard errors noisily and `||` then runs node even when the file
1460
+ // is missing, trading the silent no-op for a MODULE_NOT_FOUND crash. Two
1461
+ // remedies, by provider:
1462
+ //
1463
+ // * Codex manifests support a `commandWindows` sibling that Codex 0.146.0+
1464
+ // selects on Windows (`command_windows.unwrap_or(command)` in its hook
1465
+ // discovery). rewriteHookCommandsForSkillRoot adds it with a cmd.exe
1466
+ // `if exist` guard (form contributed and Windows-tested by @PatrickSys in
1467
+ // issue #452; `exit /b` forwards node's errorlevel), so the same
1468
+ // .codex/hooks.json is correct on every OS no matter where it was
1469
+ // written, and `command` stays the plain POSIX guard.
1470
+ // * Claude and Cursor manifests have no per-platform field, so a Windows
1471
+ // install moves the existence check into node itself: a `node -e` wrapper
1472
+ // that exits 0 when the target is missing and otherwise re-spawns node on
1473
+ // it with inherited stdio, forwarding the hook's exit code. Cursor's
1474
+ // hooks.json is committable and can be consumed on a teammate's POSIX
1475
+ // machine, so the wrapper has to hold there too: it uses only characters
1476
+ // that survive PowerShell, cmd.exe (issue #445: shims re-parse through
1477
+ // `cmd /C`, which claims < > | & ^ % !), and sh double-quoting alike,
1478
+ // with single quotes for the inner string literals.
1479
+ const WIN32_HOOK_GUARD_SCRIPT = "const p=process.argv[1];const f=require('fs');if(f.existsSync(p)){const r=require('child_process').spawnSync(process.execPath,[p],{stdio:'inherit'});process.exit(r.status===null?1:r.status);}";
1480
+
1481
+ // POSIX single-quote escaping. JSON.stringify is not shell quoting: inside
1482
+ // double quotes /bin/sh still expands $(...), backticks, and ${}, and this
1483
+ // string is baked into a hook manifest the harness re-executes on every edit,
1484
+ // so an install path embedding $(...) would run it repeatedly (issue #476).
1485
+ // Windows command forms keep double quotes: cmd.exe treats ' as a literal
1486
+ // character and performs no command substitution.
1487
+ function shSingleQuote(value) {
1488
+ return `'${String(value).replace(/'/g, `'\\''`)}'`;
1489
+ }
1490
+
1491
+ function windowsHookCommand(quotedPath) {
1492
+ return `if exist ${quotedPath} (node ${quotedPath} & exit /b)`;
1493
+ }
1494
+
1495
+ // `quotedPath` carries one pre-quoted form per target shell: { posix, win32 }.
1496
+ function guardHookCommand(quotedPath, provider) {
1497
+ // `.agents` (Codex) keeps the POSIX form unconditionally: its Windows
1498
+ // consumers read the commandWindows sibling instead.
1499
+ if (provider !== '.agents' && process.platform === 'win32') {
1500
+ return `node -e "${WIN32_HOOK_GUARD_SCRIPT}" ${quotedPath.win32}`;
1501
+ }
1502
+ return `[ ! -f ${quotedPath.posix} ] || node ${quotedPath.posix}`;
1333
1503
  }
1334
1504
 
1335
1505
  // Transform bundled hook commands for the actual install target:
@@ -1340,25 +1510,30 @@ function guardHookCommand(quotedPath) {
1340
1510
  // when a project hook points at a skill installed elsewhere (--scope=global).
1341
1511
  // * otherwise — keep the bundle's own ${CLAUDE_PROJECT_DIR}-relative path,
1342
1512
  // which correctly resolves for a project-scoped install.
1343
- // Either way the command is wrapped with the missing-file guard.
1513
+ // Either way the command goes through guardHookCommand (POSIX shell guard, or
1514
+ // the shell-agnostic node -e guard when installing on Windows), and Codex hook
1515
+ // entries additionally get a `commandWindows` sibling for cmd.exe.
1344
1516
  function rewriteHookCommandsForSkillRoot(value, provider, { skillRoot, absolute }) {
1345
1517
  const hookScript = hookScriptPathForProvider(skillRoot, provider);
1346
- // Providers we don't own a `node "PATH"` command hook for (.github, .grok)
1347
- // carry their own portable command forms; leave them untouched.
1518
+ // Providers we don't own a `node "PATH"` command hook for (.github) carry
1519
+ // their own portable command forms; leave them untouched.
1348
1520
  if (!hookScript) return value;
1349
1521
 
1522
+ // Project-scope installs derive the provider's own project-relative path
1523
+ // rather than trusting the bundle token, which for Codex points at
1524
+ // `.codex/skills/...` while the CLI installs the skill at `.agents/skills/`.
1525
+ // The absolute path comes from the install root (project dir or $HOME), so
1526
+ // its POSIX form gets real single-quote escaping (issue #476). The relative
1527
+ // form is a per-provider constant and stays double-quoted, because Claude's
1528
+ // ${CLAUDE_PROJECT_DIR} token must keep expanding at hook time.
1529
+ const relPath = hookScriptRelPathForProvider(provider);
1530
+ const quotedPath = absolute
1531
+ ? { posix: shSingleQuote(hookScript), win32: JSON.stringify(hookScript) }
1532
+ : { posix: JSON.stringify(relPath), win32: JSON.stringify(relPath) };
1533
+
1350
1534
  if (typeof value === 'string') {
1351
1535
  if (!valueHasImpeccableHookMarker(value)) return value;
1352
- let quotedPath;
1353
- if (absolute) {
1354
- quotedPath = JSON.stringify(hookScript);
1355
- } else {
1356
- // Project-scope install: derive the provider's own project-relative path
1357
- // rather than trusting the bundle token, which for Codex points at
1358
- // `.codex/skills/...` while the CLI installs the skill at `.agents/skills/`.
1359
- quotedPath = JSON.stringify(hookScriptRelPathForProvider(provider));
1360
- }
1361
- return guardHookCommand(quotedPath);
1536
+ return guardHookCommand(quotedPath, provider);
1362
1537
  }
1363
1538
  if (Array.isArray(value)) {
1364
1539
  return value.map(item => rewriteHookCommandsForSkillRoot(item, provider, { skillRoot, absolute }));
@@ -1368,6 +1543,9 @@ function rewriteHookCommandsForSkillRoot(value, provider, { skillRoot, absolute
1368
1543
  for (const [key, child] of Object.entries(value)) {
1369
1544
  next[key] = rewriteHookCommandsForSkillRoot(child, provider, { skillRoot, absolute });
1370
1545
  }
1546
+ if (provider === '.agents' && typeof value.command === 'string' && valueHasImpeccableHookMarker(value.command)) {
1547
+ next.commandWindows = windowsHookCommand(quotedPath.win32);
1548
+ }
1371
1549
  return next;
1372
1550
  }
1373
1551
  return value;
@@ -1420,7 +1598,8 @@ function hookInstalledForProvider(root, provider) {
1420
1598
 
1421
1599
  function valueHasImpeccableHookMarker(value) {
1422
1600
  if (typeof value === 'string') {
1423
- return IMPECCABLE_HOOK_COMMAND_MARKERS.some(marker => value.includes(marker));
1601
+ const normalized = value.replace(/\\/g, '/');
1602
+ return IMPECCABLE_HOOK_COMMAND_MARKERS.some(marker => normalized.includes(marker));
1424
1603
  }
1425
1604
  if (Array.isArray(value)) return value.some(valueHasImpeccableHookMarker);
1426
1605
  if (value && typeof value === 'object') {
@@ -1763,16 +1942,23 @@ async function install(flags) {
1763
1942
  process.exit(1);
1764
1943
  }
1765
1944
 
1766
- const { targets, installRoot, hookRoot, scope } = plan;
1945
+ const { targets, installRoot, hookRoot, scope, explicit } = plan;
1767
1946
  const existing = isAlreadyInstalled(installRoot, scope);
1768
-
1769
- if (existing && !force) {
1947
+ const installedTargets = existing ? findInstalledProviders(installRoot, scope) : [];
1948
+ // An explicit --providers list is a per-target request: a selected provider
1949
+ // with no install yet gets a fresh install instead of tripping the global
1950
+ // "already installed" early exit (issue #500). When every selected provider
1951
+ // is missing, skip the update branch entirely and take the fresh-install path.
1952
+ const missingSelectedTargets = (existing && !force && explicit)
1953
+ ? targets.filter(provider => !installedTargets.includes(provider))
1954
+ : [];
1955
+
1956
+ if (existing && !force && missingSelectedTargets.length < targets.length) {
1770
1957
  console.log(`Impeccable skills are already installed (found in ${existing}/).`);
1771
- const installedTargets = findInstalledProviders(installRoot, scope);
1772
1958
  const selectedInstalledTargets = targets.filter(provider => installedTargets.includes(provider));
1773
1959
  const linkedTargets = findLinkedProviders(installRoot, selectedInstalledTargets, scope);
1774
1960
  const copyTargets = selectedInstalledTargets.filter(provider => !linkedTargets.includes(provider));
1775
- const hookTargets = selectedInstalledTargets;
1961
+ const hookTargets = [...selectedInstalledTargets, ...missingSelectedTargets];
1776
1962
  const wantHooks = installHooks && await decideHookInstall(hookRoot, hookTargets, { yes });
1777
1963
  let bundleDir;
1778
1964
  try {
@@ -1787,11 +1973,11 @@ async function install(flags) {
1787
1973
  ? hookTargets.filter(provider => !hookInstalledForProvider(hookRoot, provider))
1788
1974
  : [];
1789
1975
  let updateCheckSkipped = false;
1790
- if (copyTargets.length > 0 || missingHookTargets.length > 0) {
1976
+ if (copyTargets.length > 0 || missingHookTargets.length > 0 || missingSelectedTargets.length > 0) {
1791
1977
  try {
1792
1978
  bundleDir = await downloadAndExtractBundle();
1793
1979
  } catch (e) {
1794
- if (missingHookTargets.length > 0) throw e;
1980
+ if (missingHookTargets.length > 0 || missingSelectedTargets.length > 0) throw e;
1795
1981
  updateCheckSkipped = true;
1796
1982
  console.log(`Could not check for skill updates: ${e.message}`);
1797
1983
  }
@@ -1805,6 +1991,17 @@ async function install(flags) {
1805
1991
  console.log(`Updated ${updated} skill(s)${v ? ` to v${v}` : ''}.`);
1806
1992
  }
1807
1993
 
1994
+ let freshWritten = 0;
1995
+ if (!updateCheckSkipped && missingSelectedTargets.length > 0) {
1996
+ freshWritten = copyProviderSkills(bundleDir, installRoot, missingSelectedTargets, { scope });
1997
+ if (freshWritten === 0) {
1998
+ console.error(`Nothing was installed: the bundle had no variants for ${missingSelectedTargets.join(', ')}.`);
1999
+ process.exit(1);
2000
+ }
2001
+ console.log(`Installed impeccable into: ${missingSelectedTargets.join(', ')} (${scope === 'user' ? 'global' : 'project'})`);
2002
+ reportProviderAgents(copyProviderAgents(bundleDir, installRoot, missingSelectedTargets, { scope }));
2003
+ }
2004
+
1808
2005
  const writtenHookTargets = missingHookTargets.length > 0
1809
2006
  ? copyProviderHooks(bundleDir, hookRoot, missingHookTargets, { skillRoot: installRoot })
1810
2007
  : [];
@@ -1813,7 +2010,7 @@ async function install(flags) {
1813
2010
  if (updateCheckSkipped) {
1814
2011
  console.log('Existing skills were left unchanged.');
1815
2012
  console.log('Run with --force to reinstall.\n');
1816
- } else if (updated === 0 && writtenHookTargets.length === 0) {
2013
+ } else if (updated === 0 && writtenHookTargets.length === 0 && freshWritten === 0) {
1817
2014
  const v = getSkillsVersion(installRoot, scope);
1818
2015
  console.log(`Skills are up to date${v ? ` (v${v})` : ''}.`);
1819
2016
  console.log('Run with --force to reinstall.\n');
@@ -1877,7 +2074,7 @@ async function install(flags) {
1877
2074
  reportProviderAgents(agentResults);
1878
2075
  if (hookTargets.length > 0) console.log(`Installed hooks into: ${hookTargets.join(', ')}`);
1879
2076
 
1880
- console.log('\nDone! Run /impeccable init in your AI harness to set up design context.\n');
2077
+ console.log('\nDone! Now type /impeccable init in your AI coding agent\'s chat (not in this terminal) to set up design context.\n');
1881
2078
  }
1882
2079
 
1883
2080
  // ─── skills update ────────────────────────────────────────────────────────────
@@ -1940,7 +2137,9 @@ function resolveUpdateTarget({ projectRoot, home, explicitScope }) {
1940
2137
  const homeRooted = isHomeDir(projectRoot);
1941
2138
  if (homeRooted && !explicitScope) {
1942
2139
  const providers = findInstalledProviders(home);
1943
- return providers.length ? { root: home, scope: undefined, providers, scopeLabel: 'user level' } : null;
2140
+ return providers.length
2141
+ ? { root: home, scope: undefined, agentScope: 'user', providers, scopeLabel: 'user level' }
2142
+ : null;
1944
2143
  }
1945
2144
 
1946
2145
  const projectProviders = homeRooted ? [] : findImpeccableProviders(projectRoot, 'project');
@@ -2001,26 +2200,35 @@ function getModifiedSkillFiles(root, providerDirs) {
2001
2200
  return modified;
2002
2201
  }
2003
2202
 
2004
- function downloadFile(url, dest) {
2005
- return new Promise((resolve, reject) => {
2006
- const file = createWriteStream(dest);
2007
- get(url, (res) => {
2008
- if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
2009
- // Follow redirect
2010
- get(res.headers.location, (res2) => {
2011
- res2.pipe(file);
2012
- file.on('finish', () => { file.close(); resolve(); });
2013
- }).on('error', reject);
2014
- return;
2015
- }
2016
- if (res.statusCode !== 200) {
2017
- reject(new Error(`HTTP ${res.statusCode}`));
2018
- return;
2019
- }
2020
- res.pipe(file);
2021
- file.on('finish', () => { file.close(); resolve(); });
2022
- }).on('error', reject);
2023
- });
2203
+ async function downloadFile(url, dest, { fetchImpl = globalThis.fetch } = {}) {
2204
+ let current = url;
2205
+ let hopsLeft = 5;
2206
+ while (true) {
2207
+ const parsed = new URL(current);
2208
+ if (parsed.protocol !== 'https:') {
2209
+ throw new Error('Refusing non-HTTPS URL');
2210
+ }
2211
+ const res = await fetchImpl(current, { redirect: 'manual' });
2212
+ if (res.status >= 300 && res.status < 400) {
2213
+ const location = res.headers.get('location');
2214
+ if (!location) throw new Error(`HTTP ${res.status}`);
2215
+ if (hopsLeft <= 0) throw new Error('Too many redirects');
2216
+ hopsLeft -= 1;
2217
+ current = new URL(location, current).href;
2218
+ continue;
2219
+ }
2220
+ if (res.status !== 200) {
2221
+ throw new Error(`HTTP ${res.status}`);
2222
+ }
2223
+ if (!res.body) throw new Error('Empty response body');
2224
+ try {
2225
+ await pipeline(Readable.fromWeb(res.body), createWriteStream(dest, { flags: 'wx' }));
2226
+ } catch (e) {
2227
+ if (e.code !== 'EEXIST') rmSync(dest, { force: true });
2228
+ throw e;
2229
+ }
2230
+ return;
2231
+ }
2024
2232
  }
2025
2233
 
2026
2234
  async function update(flags = []) {
@@ -2071,7 +2279,7 @@ async function update(flags = []) {
2071
2279
  : { root: projectRoot, scope: 'project', providers: target.projectProviders, scopeLabel: 'this project' };
2072
2280
  }
2073
2281
 
2074
- const { root, scope } = target;
2282
+ const { root, scope, agentScope = scope } = target;
2075
2283
  console.log(`Updating the ${target.scopeLabel} install: ${formatPathForDisplay(root)} (${target.providers.join(', ')})`);
2076
2284
  const providers = target.providers;
2077
2285
  const linkedProviders = findLinkedProviders(root, providers, scope);
@@ -2095,7 +2303,7 @@ async function update(flags = []) {
2095
2303
  }
2096
2304
 
2097
2305
  // Compare local vs remote -- skip if already up to date
2098
- if (isUpToDate(root, copyProviders, tmpDir, scope)) {
2306
+ if (isUpToDate(root, copyProviders, tmpDir, scope, agentScope)) {
2099
2307
  try {
2100
2308
  const wantHooks = installHooks && await decideHookInstall(root, copyProviders, { yes });
2101
2309
  const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, copyProviders, { force }) : [];
@@ -2131,7 +2339,7 @@ async function update(flags = []) {
2131
2339
  if (migrated > 0) console.log('Migrated a prefixed install back to /impeccable (the i- prefix is no longer used).');
2132
2340
 
2133
2341
  const updated = refreshProviderSkills(tmpDir, root, copyProviders, scope);
2134
- reportProviderAgents(copyProviderAgents(tmpDir, root, copyProviders, { scope }));
2342
+ reportProviderAgents(copyProviderAgents(tmpDir, root, copyProviders, { scope: agentScope }));
2135
2343
  const wantHooks = installHooks && await decideHookInstall(root, providers, { yes });
2136
2344
  const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, providers, { force }) : [];
2137
2345
 
@@ -2170,9 +2378,13 @@ export {
2170
2378
  copyProviderHooks,
2171
2379
  copyProviderSkills,
2172
2380
  decideHookInstall,
2381
+ downloadAndExtractBundle,
2382
+ downloadFile,
2173
2383
  expectedHookDests,
2174
2384
  extractZip,
2175
2385
  formatInstallDetectionLines,
2386
+ hermesGlobalHome,
2387
+ HOME_SKILLS_DIR_OVERRIDES,
2176
2388
  linkProviderSkills,
2177
2389
  mergeHookManifests,
2178
2390
  migrateUnprefixImpeccable,