heyspex 0.2.2 → 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

@@ -16,8 +16,8 @@
 // Single-source rule: the plugin OR the repo hooks file, never both (every hook would fire twice).
 //
 // Exit codes:
-//   0  success / nothing to do / `copilot` missing (commands printed for the user to run)
-//   1  failure: plugin route could not complete, --check found a problem, unexpected error
+//   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.
@@ -29,6 +29,7 @@ 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'];
@@ -89,35 +90,46 @@ function parseArgs(argv) {
   return a;
 }
 
-function copilotRun(args) {
+/**
+ * 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 {
-    // Windows needs a shell to resolve copilot.cmd; args are constants or the package path, so quote the latter.
-    const win = process.platform === 'win32';
-    const argv = win ? args.map((x) => (/[\s&()^]/.test(x) ? `"${x}"` : x)) : args;
-    const r = spawnSync('copilot', argv, { encoding: 'utf8', shell: win, timeout: 120000 });
+    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 };
   }
 }
 
-function copilotOnPath() {
-  const r = copilotRun(['--version']);
-  return !r.missing && r.status === 0;
+/** 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, copilotAvailable) {
-  const df = detectDoubleFire({ targetRoot, home: os.homedir(), deps: fsDeps });
+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) => /[/\\]\.copilot[/\\]/.test(e)) : [];
+  const evidence = df.plugin === true ? df.evidence.filter((e) => e.includes(copilotHome)) : [];
   let plugin = evidence.length > 0;
-  if (copilotAvailable) {
-    const r = copilotRun(['plugin', 'list']);
-    if (r.status === 0 && /heyspex/i.test(r.out)) {
+  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');
     }
@@ -161,8 +173,8 @@ function doPrint(out) {
 
 function doCheck(a, target, out) {
   const spec = resolvePluginSpec(PACKAGE_ROOT);
-  const hasCopilot = copilotOnPath();
-  const ev = pluginEvidence(target, hasCopilot);
+  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 = [];
@@ -171,7 +183,8 @@ function doCheck(a, target, out) {
   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\``);
-  const report = { route, plugin: ev.plugin, pluginEvidence: ev.evidence, hooksFile: hooks.exists, hooksFilePath: hooks.file, hooksCurrent: hooks.current, marketplaceManifest: spec.present, marketplacePath: spec.manifest, copilotOnPath: hasCopilot, problems };
+  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})`);
@@ -179,7 +192,8 @@ function doCheck(a, target, out) {
     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 on PATH: ${hasCopilot ? 'yes' : 'no'}`);
+    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');
   }
@@ -187,7 +201,7 @@ function doCheck(a, target, out) {
 }
 
 function doHooks(target, out, err) {
-  const ev = pluginEvidence(target, copilotOnPath());
+  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`.');
@@ -222,20 +236,23 @@ function doPlugin(target, out, err) {
     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);
-  if (!copilotOnPath()) {
-    out('`copilot` is not on PATH. Install GitHub Copilot CLI, then run these two commands:');
-    for (const c of cmds) out(`  ${c}`);
-    out('Then /restart in Copilot and verify with `copilot plugin list` and `npx heyspex doctor`.');
-    return 0;
+  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;
   }
-  const add = copilotRun(['plugin', 'marketplace', 'add', PACKAGE_ROOT]);
+  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(['plugin', 'install', spec.spec]);
+  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:');
@@ -247,16 +264,29 @@ function doPlugin(target, out, err) {
   return 0;
 }
 
-function doUninstall(target, out) {
+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';
-  if (copilotOnPath()) {
-    const r = copilotRun(['plugin', 'uninstall', 'heyspex']);
-    out(r.status === 0 ? `ran \`${cmd}\`` : `\`${cmd}\` did not complete (it may not be installed): ${r.out.trim().slice(-200)}`);
-  } else out(`To remove the plugin, run: ${cmd}`);
+  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;
 }
 
@@ -273,7 +303,7 @@ export function main(argv = process.argv.slice(2), io = {}) {
     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);
+    if (a.uninstall) return doUninstall(target, out, err);
     if (a.hooks) return doHooks(target, out, err);
     return doPlugin(target, out, err);
   } catch (e) {

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');
+}