heyspex 0.2.0 → 0.2.2

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

package/scripts/lib/console-url-resolver.mjs

@@ -54,6 +54,7 @@
  * isn't installed in their execution context. Stays SYNCHRONOUS and does zero
  * network I/O: it runs on every console request.
  */
+import { heyspexHome } from './heyspex-home.mjs';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -120,7 +121,7 @@ function warnStaleLoopbackCredentialsOnce(credentialsUrl, derivedUrl, { log }) {
  * consumers (some of which run standalone, outside the npm workspace's
  * hoisted `node_modules`) can call it with zero new dependencies.
  */
-export function readCredentialsConsoleUrl({ homeDir = homedir(), readFile = defaultReadFile } = {}) {
+export function readCredentialsConsoleUrl({ homeDir = heyspexHome(), readFile = defaultReadFile } = {}) {
   try {
     const raw = readFile(join(homeDir, '.heyspex', 'credentials.yaml'));
     const match = String(raw ?? '').match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
@@ -241,7 +242,7 @@ function resolveModeEnvelope({ env, homeDir }) {
 export function resolveConsoleUrl({
   repoRoot,
   env = process.env,
-  homeDir = homedir(),
+  homeDir = heyspexHome(),
   strict = false,
   devMode,
   log = (line) => process.stderr.write(line),