heyspex 0.2.1 → 0.2.3

package/scripts/dev-server-status.mjs

@@ -37,7 +37,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import http from 'node:http';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+import { isMainModule } from './lib/shared-path-helpers.mjs';
 
 // The runnable form of a HeySpex command on THIS machine — `hs …` when the bin
 // is on PATH, else an absolute-path `node "<install>/bin/hs.mjs" …`. Never an
@@ -722,7 +723,7 @@ export function summarizeStatus(status) {
 
 // ---- CLI entrypoint --------------------------------------------------------
 
-const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly = isMainModule(import.meta.url);
 if (invokedDirectly) {
   const asJson = process.argv.includes('--json');
   getDevServerStatus()

package/scripts/dev-server-stop.mjs

@@ -23,7 +23,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+import { isMainModule } from './lib/shared-path-helpers.mjs';
 
 import { getDevServerStatus, summarizeStatus } from './dev-server-status.mjs';
 
@@ -276,7 +277,7 @@ export async function stopDevServer({ vaultRoot, forcePorts = false, dryRun = fa
   };
 }
 
-const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly = isMainModule(import.meta.url);
 if (invokedDirectly) {
   const asJson = process.argv.includes('--json');
   const dryRun = process.argv.includes('--dry-run');

package/scripts/hs-capture-cli.mjs

@@ -22,7 +22,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { randomUUID } from "node:crypto";
-import { pathToFileURL } from "node:url";
+import { isMainModule } from "./lib/shared-path-helpers.mjs";
 
 import { resolveConsoleUrl, DEFAULT_CONSOLE_URL } from "./lib/console-url-resolver.mjs";
 import { heyspexHome } from "./lib/heyspex-home.mjs";
@@ -318,7 +318,7 @@ async function main() {
 // Guard so this module can be `import`ed (e.g. by hs-capture-cli.test.mjs)
 // without running main() — bin/hs.mjs spawns this file as a child process
 // with the file path as argv[1], so this only fires under that spawn.
-if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+if (isMainModule(import.meta.url)) {
   main().catch((err) => {
     process.stderr.write(`hs capture: ${err.message}\n`);
     process.exit(1);

package/scripts/hs-settings.mjs

@@ -25,7 +25,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
-import { pathToFileURL } from 'node:url';
+import { isMainModule } from './lib/shared-path-helpers.mjs';
 
 import {
   listConfigLeaves,
@@ -328,7 +328,7 @@ function main(argv) {
 // helpers (buildListEntries, isHeyspexPlatformVault, …).
 const isMain = (() => {
   try {
-    return import.meta.url === pathToFileURL(process.argv[1] ?? '').href;
+    return isMainModule(import.meta.url);
   } catch {
     return false;
   }

package/scripts/hs-view.mjs

@@ -23,7 +23,8 @@
  */
 import { spawn } from 'node:child_process';
 import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+import { isMainModule } from './lib/shared-path-helpers.mjs';
 
 import { getDevServerStatus } from './dev-server-status.mjs';
 import { resolveConsoleUrl, DEFAULT_CONSOLE_URL } from './lib/console-url-resolver.mjs';
@@ -488,7 +489,7 @@ async function main() {
 
 // Run only as the CLI entry point. Without this guard, importing the module —
 // which is how `resolveWindowWidth` is tested — would spawn a browser window.
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+if (isMainModule(import.meta.url)) {
   main().catch((err) => {
     process.stderr.write(`hs view: ${err?.message || err}\n`);
     process.exitCode = 1;

package/scripts/install-copilot-hooks.mjs

@@ -0,0 +1,318 @@
+// `hs setup copilot` -- install HeySpex into GitHub Copilot CLI / cloud agent.
+//
+// Works from the published npm package only (node_modules/heyspex, or
+// `npx heyspex setup copilot`) and from a platform checkout. The package root
+// is resolved from THIS file's location, never from the cwd.
+//
+// Usage:
+//   node scripts/install-copilot-hooks.mjs            # PLUGIN route (default)
+//   node scripts/install-copilot-hooks.mjs --hooks    # HOOKS route: .github/hooks/heyspex.json
+//   node scripts/install-copilot-hooks.mjs --check    # report active route; exit 1 if misconfigured
+//   node scripts/install-copilot-hooks.mjs --uninstall
+//   node scripts/install-copilot-hooks.mjs --print    # agent-facing instructions to stdout
+//   --target <dir>   repo to set up (default: cwd's repo root, walking up to .git / heyspex.yaml)
+//   --json           (with --check) machine-readable report
+//
+// Single-source rule: the plugin OR the repo hooks file, never both (every hook would fire twice).
+//
+// Exit codes:
+//   0  success / nothing to do
+//   1  failure: no Copilot CLI found (nothing installed), plugin route could not complete, --check found a problem, unexpected error
+//   2  refused: --hooks while the heyspex plugin is installed for Copilot, or bad arguments
+//
+// Never prints a stack trace; every path ends with a next step.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { detectDoubleFire, invokedDirectly, renderGithubHooksText } from './lib/customer-kit.mjs';
+import { COPILOT_PREREQUISITE, copilotHomeDir, parsePluginList, resolveCopilotCli } from './lib/copilot-cli.mjs';
+
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const HOOKS_REL = ['.github', 'hooks', 'heyspex.json'];
+const FALLBACK = { marketplace: 'heyspex-marketplace', plugin: 'heyspex' };
+
+const fsDeps = {
+  readFile: (p) => {
+    try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
+  },
+  listDir: (p) => {
+    try { return fs.readdirSync(p); } catch { return []; }
+  },
+};
+
+/** Tiny .mjs twin of install.ts resolvePluginSpec: names come from the package's marketplace.json. */
+export function resolvePluginSpec(platformRoot) {
+  const manifest = path.join(platformRoot, '.claude-plugin', 'marketplace.json');
+  const raw = fsDeps.readFile(manifest);
+  const out = { manifest, present: raw !== null, marketplace: FALLBACK.marketplace, plugin: FALLBACK.plugin };
+  if (raw !== null) {
+    try {
+      const j = JSON.parse(raw);
+      if (typeof j.name === 'string' && j.name.trim()) out.marketplace = j.name.trim();
+      const p = Array.isArray(j.plugins) ? j.plugins.find((x) => typeof x?.name === 'string' && x.name.trim()) : null;
+      if (p) out.plugin = p.name.trim();
+    } catch { /* keep fallback names */ }
+  }
+  out.spec = `${out.plugin}@${out.marketplace}`;
+  return out;
+}
+
+/** Walk up from `start` to the nearest dir holding .git or heyspex.yaml; else `start`. */
+export function findRepoRoot(start) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'heyspex.yaml'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) return path.resolve(start);
+    dir = up;
+  }
+}
+
+function parseArgs(argv) {
+  const a = { hooks: false, check: false, uninstall: false, print: false, json: false, target: null, bad: null };
+  for (let i = 0; i < argv.length; i++) {
+    const x = argv[i];
+    if (x === '--hooks') a.hooks = true;
+    else if (x === '--check') a.check = true;
+    else if (x === '--uninstall') a.uninstall = true;
+    else if (x === '--print') a.print = true;
+    else if (x === '--json') a.json = true;
+    else if (x === '--target') {
+      a.target = argv[++i] ?? null;
+      if (!a.target) a.bad = '--target needs a directory';
+    } else if (x.startsWith('--target=')) a.target = x.slice(9);
+    else a.bad = `unknown argument ${x}`;
+  }
+  return a;
+}
+
+/**
+ * Run the resolved Copilot CLI (PATH first, then the Copilot app's bundled copy, see lib/copilot-cli.mjs).
+ * A `.cmd`/`.bat` shim on Windows needs a shell; a real `copilot.exe` is spawned directly.
+ */
+function copilotRun(cli, args) {
+  if (!cli) return { status: 127, out: '', missing: true };
+  try {
+    const shim = process.platform === 'win32' && /\.(cmd|bat)$/i.test(cli.path);
+    const quote = (x) => (/[\s&()^]/.test(x) ? `"${x}"` : x);
+    const r = spawnSync(shim ? quote(cli.path) : cli.path, shim ? args.map(quote) : args, { encoding: 'utf8', shell: shim, timeout: 120000, env: process.env });
+    return { status: r.error ? 127 : (r.status ?? 1), out: `${r.stdout ?? ''}${r.stderr ?? ''}`, missing: !!r.error };
+  } catch {
+    return { status: 127, out: '', missing: true };
+  }
+}
+
+/** Resolve the CLI once and confirm it runs; returns { path, source, version? } or null. */
+function locateCopilot() {
+  const cli = resolveCopilotCli();
+  if (!cli) return null;
+  const r = copilotRun(cli, ['--version']);
+  return !r.missing && r.status === 0 ? cli : null;
+}
+
+const describeCli = (cli) => (cli ? `${cli.path} (${cli.source === 'app' ? 'Copilot app' : 'PATH'})` : 'not found');
+
+const q = (s) => `'${s.replace(/'/g, "''")}'`;
+const nextCommand = () => 'npx heyspex setup copilot';
+
+/** Is the heyspex plugin installed for Copilot? Combines detectDoubleFire evidence with `copilot plugin list`. */
+function pluginEvidence(targetRoot, cli) {
+  const copilotHome = copilotHomeDir();
+  const df = detectDoubleFire({ targetRoot, home: os.homedir(), copilotHome, deps: fsDeps });
+  // Only Copilot-side evidence counts: a Claude Code plugin install (~/.claude) is not a Copilot install.
+  const evidence = df.plugin === true ? df.evidence.filter((e) => e.includes(copilotHome)) : [];
+  let plugin = evidence.length > 0;
+  if (cli) {
+    const r = copilotRun(cli, ['plugin', 'list']);
+    const listed = parsePluginList(r.out);
+    if (r.status === 0 && listed.enabled) {
+      plugin = true;
+      evidence.push('`copilot plugin list` names heyspex');
+    }
+  }
+  return { plugin, evidence };
+}
+
+/** Parse the hooks file; ours = every command row is a HeySpex row. */
+function hooksFileState(target) {
+  const file = path.join(target, ...HOOKS_REL);
+  const raw = fsDeps.readFile(file);
+  if (raw === null) return { file, exists: false, ours: false, current: false };
+  let ours = false;
+  try {
+    const j = JSON.parse(raw);
+    const cmds = Object.values(j?.hooks ?? {}).flat().map((r) => r?.bash ?? r?.command).filter((c) => typeof c === 'string');
+    ours = cmds.length > 0 && cmds.every((c) => /claude-hooks\/_run\.mjs/.test(c));
+  } catch { /* foreign / unparseable */ }
+  return { file, exists: true, ours, current: raw.replace(/\r\n/g, '\n') === renderGithubHooksText() };
+}
+
+function manualCommands(spec) {
+  return [
+    `copilot plugin marketplace add ${q(PACKAGE_ROOT)}`,
+    `copilot plugin install ${spec}`,
+  ];
+}
+
+function doPrint(out) {
+  out(`Next: run \`${nextCommand()}\` (plugin) or \`${nextCommand()} --hooks\` (cloud agent) in this repo, then /restart.`);
+  const doc = fsDeps.readFile(path.join(PACKAGE_ROOT, 'docs', 'copilot-plugin-install.md'));
+  if (doc !== null) { out(''); out(doc.replace(/\s+$/, '')); return 0; }
+  const spec = resolvePluginSpec(PACKAGE_ROOT);
+  out('');
+  out('# Installing HeySpex in GitHub Copilot CLI (built-in fallback; docs/copilot-plugin-install.md not found)');
+  out('Run these, in order, and stop at the first failure:');
+  for (const c of manualCommands(spec.spec)) out(`  ${c}`);
+  out('  npx hs doctor');
+  return 0;
+}
+
+function doCheck(a, target, out) {
+  const spec = resolvePluginSpec(PACKAGE_ROOT);
+  const cli = locateCopilot();
+  const ev = pluginEvidence(target, cli);
+  const hooks = hooksFileState(target);
+  const route = ev.plugin && hooks.exists ? 'both' : ev.plugin ? 'plugin' : hooks.exists ? 'hooks' : 'none';
+  const problems = [];
+  if (route === 'both') problems.push('double-fire: the plugin AND .github/hooks/heyspex.json are active, so every hook runs twice. Run `npx heyspex setup copilot --uninstall` (hooks file) or `copilot plugin uninstall heyspex`.');
+  if (!spec.present) problems.push(`marketplace manifest missing: ${spec.manifest}`);
+  if (route === 'hooks' && !hooks.ours) problems.push('.github/hooks/heyspex.json is not a HeySpex file');
+  if (route === 'hooks' && hooks.ours && !hooks.current) problems.push('.github/hooks/heyspex.json is stale; re-run `npx heyspex setup copilot --hooks`');
+  if (route === 'none') problems.push(`no route active; run \`${nextCommand()}\` (plugin) or \`${nextCommand()} --hooks\``);
+  if (!cli && route === 'none') problems.push(`Copilot CLI not found (not on PATH, no Copilot app copy). ${COPILOT_PREREQUISITE}`);
+  const report = { route, plugin: ev.plugin, pluginEvidence: ev.evidence, hooksFile: hooks.exists, hooksFilePath: hooks.file, hooksCurrent: hooks.current, marketplaceManifest: spec.present, marketplacePath: spec.manifest, copilotCli: cli, copilotHome: copilotHomeDir(), problems };
+  if (a.json) out(JSON.stringify(report, null, 2));
+  else {
+    out(`hs setup copilot --check (target ${target})`);
+    out(`  route: ${route}${route === 'hooks' ? ' (hooks route: .github/hooks/heyspex.json)' : route === 'plugin' ? ' (plugin route)' : ''}`);
+    out(`  plugin installed: ${ev.plugin ? 'yes' : 'no'}${ev.evidence.length ? ` (${ev.evidence.join('; ')})` : ''}`);
+    out(`  hooks file: ${hooks.exists ? `present${hooks.ours ? '' : ' (not HeySpex)'}${hooks.current ? ', current' : ', stale'}` : 'absent'}`);
+    out(`  marketplace manifest in package: ${spec.present ? 'present' : 'MISSING'}`);
+    out(`  copilot CLI: ${describeCli(cli)}`);
+    if (process.env.COPILOT_HOME) out(`  COPILOT_HOME: ${copilotHomeDir()}`);
+    for (const p of problems) out(`  PROBLEM: ${p}`);
+    if (!problems.length) out('  ok');
+  }
+  return problems.length ? 1 : 0;
+}
+
+function doHooks(target, out, err) {
+  const ev = pluginEvidence(target, locateCopilot());
+  if (ev.plugin) {
+    err(`hs setup copilot --hooks refused: the heyspex plugin is already installed for Copilot (${ev.evidence.join('; ')}).`);
+    err('Plugin OR hooks, never both (every hook would fire twice). Remove the plugin first: `copilot plugin uninstall heyspex`.');
+    return 2;
+  }
+  const hooks = hooksFileState(target);
+  if (hooks.exists && !hooks.ours) {
+    err(`hs setup copilot --hooks refused: ${hooks.file} exists and is not a HeySpex file; not overwriting it.`);
+    return 2;
+  }
+  if (hooks.exists && hooks.current) {
+    out(`already current: ${hooks.file}`);
+  } else {
+    fs.mkdirSync(path.dirname(hooks.file), { recursive: true });
+    fs.writeFileSync(hooks.file, renderGithubHooksText(), 'utf8');
+    out(`${hooks.exists ? 'updated' : 'wrote'} ${hooks.file}`);
+  }
+  out('Commit .github/hooks/heyspex.json so the Copilot cloud agent and teammates get it. Commands resolve node_modules/heyspex first and exit 0 when it is absent.');
+  out('Next: `npx heyspex doctor`, then /restart in your Copilot session.');
+  return 0;
+}
+
+function doPlugin(target, out, err) {
+  const spec = resolvePluginSpec(PACKAGE_ROOT);
+  if (!spec.present) {
+    err(`hs setup copilot: marketplace manifest not found at ${spec.manifest}`);
+    err('The heyspex package looks incomplete. Reinstall it: `npm install heyspex@latest`, then re-run.');
+    return 1;
+  }
+  const hooks = hooksFileState(target);
+  if (hooks.exists) {
+    out(`WARNING: ${hooks.file} already exists. Plugin OR hooks, never both (every hook would fire twice). Remove it with \`npx heyspex setup copilot --uninstall\` after the plugin is installed.`);
+  }
+  const cmds = manualCommands(spec.spec);
+  const cli = locateCopilot();
+  if (!cli) {
+    err('hs setup copilot: GitHub Copilot CLI not found (not on PATH, and no Copilot app copy under %LOCALAPPDATA%\\github-copilot-sdk\\cli). Nothing was installed.');
+    err(COPILOT_PREREQUISITE);
+    err('Then re-run `npx heyspex setup copilot`, or run these two commands by hand:');
+    for (const c of cmds) err(`  ${c}`);
+    return 1;
+  }
+  out(`using Copilot CLI: ${describeCli(cli)}`);
+  const add = copilotRun(cli, ['plugin', 'marketplace', 'add', PACKAGE_ROOT]);
+  if (add.status !== 0 && !/already/i.test(add.out)) {
+    err(`copilot plugin marketplace add failed:\n${add.out.trim().slice(-600)}`);
+    err('Run these by hand and report the output:');
+    for (const c of cmds) err(`  ${c}`);
+    return 1;
+  }
+  const inst = copilotRun(cli, ['plugin', 'install', spec.spec]);
+  if (inst.status !== 0 && !/already/i.test(inst.out)) {
+    err(`copilot plugin install failed:\n${inst.out.trim().slice(-600)}`);
+    err('Run this by hand and report the output:');
+    err(`  ${cmds[1]}`);
+    return 1;
+  }
+  out(`installed ${spec.spec} (marketplace from ${PACKAGE_ROOT})`);
+  out('Next: /restart in Copilot, then `copilot plugin list` and `npx heyspex doctor`.');
+  return 0;
+}
+
+function doUninstall(target, out, err) {
+  const hooks = hooksFileState(target);
+  if (!hooks.exists) out(`no hooks file at ${hooks.file}`);
+  else if (!hooks.ours) out(`left ${hooks.file} alone: it is not a HeySpex-only file`);
+  else { fs.rmSync(hooks.file, { force: true }); out(`removed ${hooks.file}`); }
+  const cmd = 'copilot plugin uninstall heyspex';
+  const cli = locateCopilot();
+  if (cli) {
+    const r = copilotRun(cli, ['plugin', 'uninstall', 'heyspex']);
+    out(r.status === 0 ? `ran \`${cmd}\` via ${describeCli(cli)}` : `\`${cmd}\` did not complete (it may not be installed): ${r.out.trim().slice(-200)}`);
+    // A plugin loaded from a local marketplace is only DISABLED by `plugin uninstall` (it stays
+    // in `plugin list`), so drop the marketplace we registered too.
+    const mk = copilotRun(cli, ['plugin', 'marketplace', 'remove', resolvePluginSpec(PACKAGE_ROOT).marketplace]);
+    if (mk.status === 0) out(`removed marketplace ${resolvePluginSpec(PACKAGE_ROOT).marketplace}`);
+    return 0;
+  }
+  // No CLI: only an error when a plugin install is actually on record and could not be removed.
+  if (pluginEvidence(target, null).plugin) {
+    err(`hs setup copilot --uninstall: the heyspex plugin is installed for Copilot but no Copilot CLI was found to remove it. ${COPILOT_PREREQUISITE}`);
+    err(`Then run: ${cmd}`);
+    return 1;
+  }
+  out(`no heyspex plugin found for Copilot; nothing more to remove (to be sure, run: ${cmd})`);
+  return 0;
+}
+
+export function main(argv = process.argv.slice(2), io = {}) {
+  const out = io.out ?? ((s) => process.stdout.write(`${s}\n`));
+  const err = io.err ?? ((s) => process.stderr.write(`${s}\n`));
+  try {
+    const a = parseArgs(argv);
+    if (a.bad) {
+      err(`hs setup copilot: ${a.bad}`);
+      err('usage: hs setup copilot [--hooks] [--check [--json]] [--uninstall] [--print] [--target <dir>]');
+      return 2;
+    }
+    if (a.print) return doPrint(out);
+    const target = a.target ? path.resolve(a.target) : findRepoRoot(process.env.HS_SETUP_TARGET?.trim() || process.cwd());
+    if (a.check) return doCheck(a, target, out);
+    if (a.uninstall) return doUninstall(target, out, err);
+    if (a.hooks) return doHooks(target, out, err);
+    return doPlugin(target, out, err);
+  } catch (e) {
+    err(`hs setup copilot: unexpected failure: ${e?.message ?? e}`);
+    err('Manual fallback: copilot plugin marketplace add <node_modules/heyspex>; copilot plugin install heyspex@heyspex-marketplace');
+    return 1;
+  }
+}
+
+if (invokedDirectly(import.meta.url, 'install-copilot-hooks.mjs')) {
+  process.exit(main());
+}

package/scripts/lib/copilot-cli.mjs

@@ -0,0 +1,108 @@
+// copilot-cli.mjs - find the GitHub Copilot CLI and its settings dir (HS-GLR5).
+//
+// `copilot` is not always on PATH: the Copilot Windows app ships the real CLI at
+// %LOCALAPPDATA%\github-copilot-sdk\cli\<version>\copilot.exe (the version folder changes on
+// every app update) and never adds it to PATH. Resolution order:
+//   1. `copilot` on PATH (npm -g @github/copilot, winget, brew ...)
+//   2. Windows only: the NEWEST %LOCALAPPDATA%\github-copilot-sdk\cli\<version>\copilot.exe
+// (macOS / Linux have no confirmed app-bundled location, so PATH is the only route there.)
+//
+// Pure + injectable (exists / listDir / env / platform) so it is unit-testable without a Copilot.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** What a user should install when no Copilot CLI can be found. Shown by setup, --check and the docs. */
+export const COPILOT_PREREQUISITE =
+  'GitHub Copilot CLI is required: install the GitHub Copilot app (auto-detected), or `npm install -g @github/copilot`, or `winget install GitHub.Copilot`.';
+
+const realDeps = {
+  exists: (p) => {
+    try { return fs.statSync(p).isFile(); } catch { return false; }
+  },
+  listDir: (p) => {
+    try { return fs.readdirSync(p); } catch { return []; }
+  },
+};
+
+/**
+ * Compare two Copilot version-folder names like `1.0.99-2` numerically, never lexically
+ * (`1.0.100` > `1.0.99`, `1.0.99-10` > `1.0.99-2`). A missing `-N` suffix counts as 0.
+ * Returns negative / 0 / positive like Array.sort.
+ */
+export function compareCopilotVersions(a, b) {
+  const parts = (v) => {
+    const [core, ...rest] = String(v).split('-');
+    const nums = core.split('.').map((x) => Number.parseInt(x, 10)).map((n) => (Number.isFinite(n) ? n : 0));
+    const suffix = Number.parseInt(rest.join('-'), 10);
+    return [...nums, Number.isFinite(suffix) ? suffix : 0];
+  };
+  const pa = parts(a);
+  const pb = parts(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+/** First `copilot` executable found on PATH, or null. Windows also tries .exe / .cmd / .bat. */
+export function findCopilotOnPath({ env = process.env, platform = process.platform, exists = realDeps.exists } = {}) {
+  const pathVar = env.PATH ?? env.Path ?? env.path ?? '';
+  const names = platform === 'win32' ? ['copilot.exe', 'copilot.cmd', 'copilot.bat'] : ['copilot'];
+  for (const dir of pathVar.split(path.delimiter).map((d) => d.trim().replace(/^"|"$/g, '')).filter(Boolean)) {
+    for (const n of names) {
+      const full = path.join(dir, n);
+      if (exists(full)) return full;
+    }
+  }
+  return null;
+}
+
+/** Newest app-bundled CLI under `<localAppData>\github-copilot-sdk\cli\<version>\copilot.exe`, or null. */
+export function findAppBundledCopilot({ localAppData, exists = realDeps.exists, listDir = realDeps.listDir } = {}) {
+  if (!localAppData) return null;
+  const root = path.join(localAppData, 'github-copilot-sdk', 'cli');
+  const versions = listDir(root)
+    .filter((v) => exists(path.join(root, v, 'copilot.exe')))
+    .sort(compareCopilotVersions);
+  const newest = versions.at(-1);
+  return newest ? { path: path.join(root, newest, 'copilot.exe'), version: newest } : null;
+}
+
+/**
+ * Resolve the Copilot CLI. Returns `{ path, source: 'path' | 'app', version? }` or null.
+ */
+export function resolveCopilotCli(opts = {}) {
+  const env = opts.env ?? process.env;
+  const platform = opts.platform ?? process.platform;
+  const exists = opts.exists ?? realDeps.exists;
+  const listDir = opts.listDir ?? realDeps.listDir;
+  const onPath = findCopilotOnPath({ env, platform, exists });
+  if (onPath) return { path: onPath, source: 'path' };
+  if (platform === 'win32') {
+    const app = findAppBundledCopilot({ localAppData: env.LOCALAPPDATA, exists, listDir });
+    if (app) return { ...app, source: 'app' };
+  }
+  return null;
+}
+
+/**
+ * Read `copilot plugin list` output for the heyspex plugin. A plugin loaded from a local
+ * marketplace is only DISABLED by `copilot plugin uninstall` and stays in the list marked
+ * `(disabled)`, so "listed" is not "installed": returns `{ listed, enabled }`.
+ */
+export function parsePluginList(out) {
+  const lines = String(out ?? '').split(/\r?\n/).filter((l) => /heyspex@/i.test(l));
+  return { listed: lines.length > 0, enabled: lines.some((l) => !/\(disabled\)|\[disabled\]/i.test(l)) };
+}
+
+/**
+ * Copilot's settings/state dir: `COPILOT_HOME` when set (Copilot's own override, see
+ * `copilot help environment`), else `<home>/.copilot`.
+ */
+export function copilotHomeDir({ env = process.env, home = os.homedir() } = {}) {
+  const override = typeof env.COPILOT_HOME === 'string' ? env.COPILOT_HOME.trim() : '';
+  return override ? path.resolve(override) : path.join(home, '.copilot');
+}