heyspex 0.2.5 → 0.2.7

package/scripts/lib/customer-kit.mjs

@@ -209,7 +209,7 @@ export const COMMAND_SCOPES = Object.freeze({
   'hs-promote.md': { scope: 'customer', why: 'Capture → research → milestone promotion.' },
   'hs-push.md': { scope: 'customer', why: 'Push an epic plan into the vault.' },
   'hs-qc.md': { scope: 'customer', why: 'Post-plan QC gate.' },
-  'hs-res.md': { scope: 'customer', why: 'Research method entrypoint (SpexCrawl/DeepSeek).' },
+  'hs-res.md': { scope: 'customer', why: 'Research method entrypoint (local Docker Firecrawl search + SpexCrawl/Firecrawl fetch; DeepSeek on the platform).' },
   'hs-resolve.md': { scope: 'customer', why: 'Resolution lane.' },
   'hs-review.md': { scope: 'customer', why: 'Review queue.' },
   'hs-view.md': { scope: 'customer', why: 'Open a console surface.' },
@@ -860,13 +860,15 @@ export function githubHookNames() {
 }
 
 /**
- * The bash command for one hook: resolve the runtime from node_modules/heyspex first, then the checkout's own
- * scripts/, else exit 0 (fail open; Copilot turns any non-zero exit into a deny).
+ * The bash command for one hook: stamp the harness (HS-OMQF: these commands only ever run under Copilot, so
+ * HEYSPEX_HARNESS=copilot unless the developer already set one), resolve the runtime from node_modules/heyspex
+ * first, then the checkout's own scripts/, else exit 0 (fail open; Copilot turns any non-zero exit into a deny).
  * @param {{ hook: string, args?: string[] }} row
  */
 export function githubHookCommand(row) {
   const tail = hookTail(row);
   return (
+    'export HEYSPEX_HARNESS="${HEYSPEX_HARNESS:-copilot}"; ' +
     'R=node_modules/heyspex/scripts/claude-hooks/_run.mjs; ' +
     '[ -f "$R" ] || R=./scripts/claude-hooks/_run.mjs; ' +
     '[ -f "$R" ] || exit 0; ' +
@@ -1326,6 +1328,54 @@ export function auditCustomerKit({ targetRoot, platformRoot, deps = fsDeps }) {
   return report;
 }
 
+// ---------------------------------------------------------------------------
+// Which repo `hs setup <agent>` writes into
+// ---------------------------------------------------------------------------
+
+/**
+ * The project root a setup verb acts on: the nearest directory at/above
+ * `start` holding `.git` or `heyspex.yaml`, else `start` itself. Same walk
+ * `hs setup copilot` uses.
+ * @param {string} start
+ */
+export function findProjectRoot(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;
+  }
+}
+
+/**
+ * True when `platformRoot` is an installed `heyspex` package (under a
+ * node_modules/ folder, or missing the source-checkout-only
+ * scripts/heyspex-doctor.mjs) rather than a HeySpex source checkout.
+ * @param {string} platformRoot
+ * @param {(p: string) => boolean} [exists]
+ */
+export function isInstalledPackageRoot(platformRoot, exists = fs.existsSync) {
+  if (toPosixPath(path.resolve(platformRoot)).includes('/node_modules/')) return true;
+  return !exists(path.join(platformRoot, 'scripts', 'heyspex-doctor.mjs'));
+}
+
+/**
+ * The repo a hook installer (`install-claude-code-hooks.mjs`,
+ * `install-cursor-hooks.mjs`) writes into. An explicit HS_SETUP_TARGET (what
+ * `hs setup` / `hs doctor --fix` pass) wins; with none, a source checkout
+ * targets itself (the dev `npm install` / `npm run hooks:*` path) but an
+ * INSTALLED package targets the customer's project found from cwd -- never
+ * its own package folder under node_modules/.
+ * @param {{ platformRoot: string, env?: Record<string, string | undefined>, cwd?: string, exists?: (p: string) => boolean }} opts
+ */
+export function resolveSetupTarget({ platformRoot, env = process.env, cwd = process.cwd(), exists = fs.existsSync }) {
+  const explicit = env.HS_SETUP_TARGET?.trim();
+  if (explicit) return path.resolve(explicit);
+  if (isInstalledPackageRoot(platformRoot, exists)) return findProjectRoot(cwd);
+  return path.resolve(platformRoot);
+}
+
 // ---------------------------------------------------------------------------
 // CLI: regenerate plugins/heyspex/hooks/hooks.json
 // ---------------------------------------------------------------------------

package/scripts/lib/hs-companion-settings.mjs

@@ -105,6 +105,31 @@ export const COMPANION_ALIASES = {
 
 export const HOST_COMMANDS = ["start", "stop", "status", "build"];
 
+/**
+ * What `hs companion start|stop|status|build` prints when run from an
+ * installed `heyspex` npm package: the tray app's source (companion/) is not
+ * in the tarball, so there is no start.ps1 to run. Says plainly that the
+ * Companion is not distributed through npm yet (a Windows installer is
+ * planned, research HS-AUY9) and what degrades without it, with the
+ * workaround for each. The dev (repo checkout) path never reaches this.
+ * @param {string} sub the host subcommand the caller asked for
+ */
+export function renderCompanionNotDistributed(sub) {
+  return [
+    `hs companion ${sub}: the HeySpex Companion (desktop tray app) is not distributed through the`,
+    "heyspex npm package yet; a Windows installer is planned (research HS-AUY9).",
+    "",
+    "Everything else in this package works without it. What you lose until then:",
+    "  - Automatic vault mirror (cloud <-> disk sync): run `npx hs pull --apply` to bring",
+    "    cloud-written specs down (and `npx hs push --apply` to send local edits up).",
+    "  - SpexVoice (voice capture and spoken commands): not available.",
+    "  - SpexCrawl research gather (/hs-res): its gather jobs need the Companion, so they",
+    "    report SPEXCRAWL_UNAVAILABLE.",
+    "",
+    "`hs companion settings ...` (console-backed) still works.",
+  ].join("\n");
+}
+
 const TRUE_WORDS = new Set(["true", "on", "yes", "1", "enabled"]);
 const FALSE_WORDS = new Set(["false", "off", "no", "0", "disabled"]);
 const NULL_WORDS = new Set(["null", "none"]);
@@ -464,6 +489,7 @@ export function renderHelp(topic = "companion") {
     "  hs companion stop              Quit the tray app",
     "  hs companion status            Is it running?",
     "  hs companion build             dotnet build Debug",
+    "  hs companion install [--quiet] [--dry-run]   Download, verify and run the signed SpexCompanion setup (Windows x64)",
     "",
     ...settingsLines,
     "",