heyspex 0.2.1 → 0.2.2

package/bin/hs.mjs

@@ -60,6 +60,7 @@ const PKG_ROOT = path.resolve(__dirname, "..");
 export const SPAWN_TARGETS = {
   "setup:claude": { path: "scripts/install-claude-code-hooks.mjs" },
   "setup:cursor": { path: "scripts/install-cursor-hooks.mjs" },
+  "setup:copilot": { path: "scripts/install-copilot-hooks.mjs" },
   "skills:sync": {
     path: "scripts/sync-skills.mjs",
     devOnly: true,
@@ -565,7 +566,7 @@ function usage() {
       "  hs gateway validate [slug] [--json]        Validate user-authored gateway skills (.heyspex/skills/user/)",
       "  hs mode on|off|status|toggle               Master switch: HeySpex layer on or off (restart Claude Code)",
       "  hs dev [mode:local|mode:cloud|mode:prod]   Dev/prod mode + local/cloud reliance (status when bare)",
-      "  hs setup claude|cursor [--check|--uninstall]  Install agent lifecycle hooks",
+      "  hs setup claude|cursor|copilot [--check|--uninstall]  Install agent lifecycle hooks (copilot also: --print, --hooks)",
       "  hs skills sync|check                       Propagate skills to Cursor/Codex/Claude (cwd-safe)",
       "  hs skills add <module-path> --name <n> --trigger </slash> [--export <n>] [--description <t>]  Register a skill (extension seam)",
       "  hs skills remove <name>                    Remove a customer-registered skill",
@@ -1070,20 +1071,33 @@ function main(argv) {
     const SPAWN_KEYS = {
       claude: "setup:claude",
       cursor: "setup:cursor",
+      copilot: "setup:copilot",
     };
     if (!agent || !Object.hasOwn(SPAWN_KEYS, agent)) {
       process.stderr.write(
-        `hs setup: expected \`claude\` or \`cursor\` (got \`${command ?? ""}\`)\n` +
+        `hs setup: expected \`claude\`, \`cursor\` or \`copilot\` (got \`${command ?? ""}\`)\n` +
           "  hs setup claude [--check|--uninstall]   Claude Code lifecycle hooks\n" +
-          "  hs setup cursor [--check|--uninstall]   Cursor CLI lifecycle hooks\n",
+          "  hs setup cursor [--check|--uninstall]   Cursor CLI lifecycle hooks\n" +
+          "  hs setup copilot [--check|--uninstall|--print|--hooks]   GitHub Copilot (plugin; --hooks for the cloud agent)\n",
       );
       process.exit(2);
     }
     const setupFlags = rest.filter(
       (a) => a === "--check" || a === "--uninstall",
     );
+    if (agent === "copilot") {
+      // Copilot takes more flags: --print, --hooks, --json, --target <dir>.
+      setupFlags.length = 0;
+      for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (["--check", "--uninstall", "--print", "--hooks", "--json"].includes(a)) setupFlags.push(a);
+        else if (a === "--target" && rest[i + 1]) setupFlags.push(a, rest[++i]);
+        else if (a.startsWith("--target=")) setupFlags.push(a);
+      }
+    }
     const script = spawnTargetPath(SPAWN_KEYS[agent]);
-    const target = vaultRoot || process.cwd();
+    // Copilot sets up the repo you are standing in, never the (possibly sibling) vault root.
+    const target = agent === "copilot" ? process.cwd() : vaultRoot || process.cwd();
     const child = spawn(process.execPath, [script, ...setupFlags], {
       cwd: target,
       stdio: "inherit",

package/docs/copilot-plugin-install.md

@@ -11,6 +11,21 @@ Source of truth for the Copilot commands and file layout:
 Hook behaviour under Copilot: <https://docs.github.com/en/copilot/reference/hooks-configuration>.
 Both pages were read on 2026-10-16. The plugin itself is documented in `node_modules/heyspex/plugins/heyspex/README.md`.
 
+## 0. The short version
+
+From the root of your repo, after `npm install heyspex`:
+
+```bash
+npx heyspex setup copilot            # plugin route (Copilot CLI): registers the marketplace and installs the plugin
+npx heyspex setup copilot --hooks    # hooks route (Copilot cloud agent / no plugin): writes .github/hooks/heyspex.json
+npx heyspex setup copilot --check    # which route is active; warns if both are
+npx heyspex setup copilot --uninstall
+```
+
+To have an agent do it, paste it the output of `npx heyspex setup copilot --print` (this document,
+preceded by the exact next command). If `copilot` is not on PATH, the plugin route prints the two
+commands to run instead. Pick ONE route, never both. The manual commands below remain the fallback.
+
 ## 1. Prerequisites
 
 The heyspex-app repository is not required and is not available to customers. Everything below
@@ -42,10 +57,10 @@ every hook runs twice. Choose one.
 package and installs the plugin:
 
 ```bash
-npx hs install --target . --copilot-plugin-apply
+npx heyspex setup copilot
 ```
 
-Without `npx hs`, the equivalent Copilot commands are:
+(`npx hs install --target . --copilot-plugin-apply` does the same.) By hand, the equivalent Copilot commands are:
 
 ```bash
 copilot plugin marketplace add ./node_modules/heyspex
@@ -63,10 +78,10 @@ copilot plugin list
 so a checkout without `npm install` is never blocked.
 
 ```bash
-npx hs install --target . --copilot-hooks
+npx heyspex setup copilot --hooks
 ```
 
-If you pass `--copilot-hooks` together with `--copilot-plugin[-apply]`, the installer warns and
+(`npx hs install --target . --copilot-hooks` does the same.) `setup copilot --hooks` refuses when the plugin is already installed. If you pass `--copilot-hooks` together with `--copilot-plugin[-apply]`, the installer warns and
 skips the hooks file.
 
 Then restart the Copilot session (`/restart`) so hooks load, and verify:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heyspex",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "HeySpex CLI + MCP server — connect Claude Code, Cursor, and any MCP client to your HeySpex spec vault",
   "keywords": [
     "heyspex",
@@ -72,6 +72,7 @@
     "LICENSE",
     "scripts/install-claude-code-hooks.mjs",
     "scripts/install-cursor-hooks.mjs",
+    "scripts/install-copilot-hooks.mjs",
     "scripts/lib/customer-kit.mjs",
     "scripts/lib/hook-dispositions.mjs",
     "scripts/lib/template-pin.mjs",

package/plugins/heyspex/README.md

@@ -37,12 +37,15 @@ plugin source `./plugins/heyspex`), the hooks and the MCP server. From the root
 ```bash
 npm install heyspex                      # or: npm install ./heyspex-<version>.tgz
 npx hs login
-npx hs install --target . --plugin-apply            # Claude Code
-npx hs install --target . --copilot-plugin-apply    # GitHub Copilot CLI (plugin) ...
-npx hs install --target . --copilot-hooks           # ... OR repo hooks in .github/hooks, never both
+npx heyspex setup copilot                # GitHub Copilot CLI: plugin route ...
+npx heyspex setup copilot --hooks        # ... OR cloud agent: .github/hooks/heyspex.json, never both
+npx heyspex setup copilot --print        # paste this to your agent: next command + the full guide
+npx hs install --target . --plugin-apply # Claude Code
 ```
 
-By hand: `claude plugin marketplace add ./node_modules/heyspex` /
+`setup copilot --check` shows which route is active; `--uninstall` removes the hooks file and prints `copilot plugin uninstall heyspex`.
+
+Fallback, by hand: `claude plugin marketplace add ./node_modules/heyspex` /
 `copilot plugin marketplace add ./node_modules/heyspex`, then `... plugin install heyspex@heyspex-marketplace`.
 Restart the session (`/restart` in Copilot), then check `copilot plugin list` and `npx hs doctor`.
 Full walkthrough: `node_modules/heyspex/docs/copilot-plugin-install.md`. The sections below describe the same plugin from the

package/scripts/install-copilot-hooks.mjs

@@ -0,0 +1,288 @@
+// `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 / `copilot` missing (commands printed for the user to run)
+//   1  failure: 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';
+
+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;
+}
+
+function copilotRun(args) {
+  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 });
+    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;
+}
+
+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 });
+  // 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)) : [];
+  let plugin = evidence.length > 0;
+  if (copilotAvailable) {
+    const r = copilotRun(['plugin', 'list']);
+    if (r.status === 0 && /heyspex/i.test(r.out)) {
+      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 hasCopilot = copilotOnPath();
+  const ev = pluginEvidence(target, hasCopilot);
+  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\``);
+  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 (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 on PATH: ${hasCopilot ? 'yes' : 'no'}`);
+    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, copilotOnPath());
+  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);
+  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 add = copilotRun(['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]);
+  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) {
+  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}`);
+  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);
+    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());
+}