heyspex 0.1.0 → 0.2.0

package/scripts/lib/hs-command.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * hs-command.mjs — the ONE resolver for "how do you actually run a HeySpex
+ * command on THIS machine"
+ * ([[HS-I6HT-EKYU-DIAG-every-message-tells-the-user-to-run-hs]]).
+ *
+ * THE DEFECT THIS EXISTS TO KILL. Every place that told a human what to run
+ * hard-coded `hs login`. On the owner's own machine that command does not
+ * exist — `which hs` finds nothing in Git Bash and `Get-Command hs` returns
+ * nothing in PowerShell, because the package declares the `hs` bin but
+ * nothing has ever linked it globally. The product printed advice that could
+ * not be carried out, which is the same shape as the console-unreachable
+ * message that sent agents off to start a local dev server.
+ *
+ * THE FIX IS THE MESSAGE, NOT THE PATH (decided 2026-08-23, see the diagnose).
+ * Linking `hs` globally would point one command name at whatever branch
+ * happens to be checked out, and would do nothing at all for a customer who
+ * never links it — so it fixes one machine and leaves the product defect
+ * standing. Instead: every message asks THIS module for the runnable form and
+ * prints that.
+ *
+ *   `hs` resolves on PATH   → `hs login`
+ *   it does not             → `node "C:\path\to\checkout\bin\hs.mjs" login`
+ *
+ * NEVER PRINT AN `npx` FORM. THIS IS MEASURED, NOT ASSUMED — do not
+ * re-derive it. The tempting fallback is `npx hs login`, and inside a
+ * checkout it even works, which is exactly what makes it a trap. It fails
+ * for the reader because **`npx` resolves from the reader's CURRENT WORKING
+ * DIRECTORY, not from wherever the message was printed.** A human reads an
+ * error in one window and pastes the command into whatever terminal is open,
+ * which is usually not the checkout — the owner did precisely that today,
+ * typing `hs login` at a shell sitting in his home folder. Measured
+ * 2026-08-23 from a directory outside the repo:
+ *
+ *   npx --no -- hs --version
+ *     → npm error npx canceled due to missing packages: ["hs@2.0.1"]
+ *   npx --no -- heyspex --version
+ *     → npm error 404 Not Found - GET https://registry.npmjs.org/heyspex
+ *
+ * So `npx hs` offers to install an unrelated public package (and WITHOUT
+ * `--no` it simply installs it), and `npx heyspex` cannot work either because
+ * this package is not published publicly. That is the same trap
+ * [[never-print-npx-hs-it-installs-a]] recorded on 2026-08-12 — note that
+ * lesson predates a rename and still calls the package `workflow-pm`; the
+ * name is now `heyspex`, and neither name is a safe npx target.
+ *
+ * THE ABSOLUTE-PATH RULE. When `hs` is not on PATH we print an absolute-path
+ * invocation of THIS install's dispatcher: `node <abs>/bin/hs.mjs <args>`.
+ * The path is resolved from THIS MODULE'S OWN LOCATION (`import.meta.url`),
+ * never from `process.cwd()`, so the printed command runs from any folder,
+ * touches no registry, and cannot resolve to somebody else's package. The
+ * reader provably has this install, because this install is what printed the
+ * message. It is also the form the lesson itself blesses: a repo-local
+ * dispatcher is valid precisely when the checkout exists — which is the case
+ * here and was NOT the case in the fresh-machine join scenario that lesson
+ * was written about. Do NOT reuse this helper to build text handed to a
+ * machine that has no HeySpex yet; that path is a public join URL, not a
+ * command line.
+ *
+ * SYNCHRONOUS, CACHED, NEVER THROWS. The lookup is a plain scan of `PATH`
+ * with `fs.existsSync` — no `child_process`, so it costs microseconds and is
+ * safe to call while building an error string. The answer is cached after
+ * the first call (PATH does not change inside a process). Every failure mode
+ * degrades to the absolute-path dispatcher form rather than throwing,
+ * because the caller is usually already in the middle of reporting a
+ * different failure.
+ *
+ * SHELL-INDEPENDENT. Node sees the Windows-form `PATH` (`C:\…;C:\…`) whether
+ * it was launched from Git Bash, PowerShell, or cmd — the MSYS layer
+ * converts it back on the way into a native binary — so one `path.delimiter`
+ * split gives the same answer in all three. On Windows the scan accepts the
+ * extensionless shim (what Git Bash runs), every `PATHEXT` variant (what cmd
+ * runs), and `.ps1` (what PowerShell runs); `npm link` writes all of them
+ * together, so any one of them proves the command is live. The dispatcher
+ * path is always double-quoted on Windows — see `shellQuote` for the
+ * measurement, and note that a BARE backslash path is broken in Git Bash
+ * specifically, which is the shell coding agents use.
+ *
+ * Plain Node ESM, zero deps beyond `node:fs`/`node:path`/`node:url`, and —
+ * deliberately — ZERO imports of other repo files. `console-url-resolver.mjs`
+ * grew a static import of `dev-mode.mjs` on 2026-08-23 and broke a clean
+ * install of the published package (module-not-found on load) until the file
+ * was added to the package list. If this module ever gains a repo import,
+ * run `node scripts/verify-mcp-package.mjs` before calling the work done.
+ */
+import { existsSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** The command name the package declares (`bin.hs` in package.json). */
+export const HS_BIN_NAME = 'hs';
+
+/**
+ * Absolute path to THIS install's CLI dispatcher, resolved from this
+ * module's own location — `<root>/scripts/lib/hs-command.mjs` → up three →
+ * `<root>`, then `bin/hs.mjs`. That layout holds in a checkout AND in the
+ * published package (both `bin/hs.mjs` and `scripts/lib/hs-command.mjs` are
+ * in the package's `files` list). Never derived from `process.cwd()`.
+ */
+export const HS_DISPATCHER_PATH = (() => {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url)); // <root>/scripts/lib
+    return join(dirname(dirname(here)), 'bin', 'hs.mjs');
+  } catch {
+    return null;
+  }
+})();
+
+/**
+ * Quote the dispatcher path for pasting into a shell.
+ *
+ * MEASURED 2026-08-23 from the home folder, running the printed string
+ * verbatim in each shell:
+ *
+ *   node C:\…\bin\hs.mjs      Git Bash ✗   PowerShell ✓   cmd ✓
+ *   node "C:\…\bin\hs.mjs"    Git Bash ✓   PowerShell ✓   cmd ✓
+ *
+ * Git Bash eats the backslashes as escapes when the path is bare, and Git
+ * Bash is the shell coding agents run commands in — so an unquoted Windows
+ * path would re-create the exact defect this module exists to kill, for the
+ * agent audience. Any path carrying a backslash or whitespace is therefore
+ * always double-quoted; a clean POSIX path is left bare.
+ */
+function shellQuote(p) {
+  return /[\\\s]/.test(p) ? `"${p}"` : p;
+}
+
+/**
+ * What a message prints in front of a subcommand when `hs` is NOT on PATH:
+ * `node <abs>/bin/hs.mjs`. Falls back to the bare name only if this module
+ * cannot locate itself at all (should be impossible; never throw).
+ */
+export const HS_DISPATCHER_PREFIX = HS_DISPATCHER_PATH
+  ? `node ${shellQuote(HS_DISPATCHER_PATH)}`
+  : HS_BIN_NAME;
+
+/**
+ * Windows-only extensions to try on top of the bare name. `PATHEXT` covers
+ * cmd/PowerShell's own list; we add the extensionless shim (Git Bash runs
+ * it) and `.ps1` (PowerShell runs it, and it is absent from the default
+ * `PATHEXT`).
+ */
+function candidateNames(name, env) {
+  if (process.platform !== 'win32') return [name];
+  // Lower-cased on purpose: npm writes `hs.cmd` / `hs.ps1` in lower case, and
+  // the Windows filesystem is case-insensitive, so one spelling is enough.
+  const pathext = (env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+    .split(';')
+    .map((e) => e.trim().toLowerCase())
+    .filter(Boolean);
+  const extensions = [...new Set([...pathext, '.ps1'])];
+  return [name, ...extensions.map((ext) => name + ext)];
+}
+
+/**
+ * Is `name` an executable somewhere on `PATH`? Pure `fs.existsSync` — no
+ * subprocess. Returns the absolute path of the first hit, or `null`.
+ *
+ * Injectable `env` and `exists` so tests can describe a machine instead of
+ * depending on the one they run on.
+ */
+export function findOnPath(name, { env = process.env, exists = existsSync } = {}) {
+  try {
+    const raw = env.PATH ?? env.Path ?? env.path ?? '';
+    for (const dir of String(raw).split(delimiter)) {
+      const trimmed = dir.trim().replace(/^"(.*)"$/, '$1');
+      if (!trimmed) continue;
+      for (const candidate of candidateNames(name, env)) {
+        const full = join(trimmed, candidate);
+        try {
+          if (exists(full)) return full;
+        } catch {
+          // An unreadable or denied PATH entry is not a match — keep scanning.
+        }
+      }
+    }
+  } catch {
+    // A malformed PATH is treated as "not found", never as a crash.
+  }
+  return null;
+}
+
+let cached = null;
+
+/**
+ * Test/CI escape hatch: force the "is `hs` on PATH" answer WITHOUT touching
+ * PATH itself, so a fixture recorded on one machine's PATH state stays
+ * reproducible on another's. THE DEFECT THIS EXISTS TO KILL: a golden
+ * recorded when `hs` was not linked started failing the moment `npm link`
+ * put it on this developer's PATH — the resolver was correct, the fixture
+ * was silently machine-dependent. Recognized values (read via
+ * `describeHsCommand`'s `env`, or `process.env` when none is injected):
+ *
+ *   "1"  → force on-PATH   (prefix = `hs`, as a linked install would show)
+ *   "0"  → force NOT on PATH (prefix = the absolute dispatcher form)
+ *   anything else (including unset) → the real PATH scan decides, unchanged
+ *
+ * Never set by product code — only test/CI fixtures reach for this, and
+ * only to PIN a canonical form, never to fake a real machine's state for a
+ * human-facing message.
+ */
+export const HS_ON_PATH_OVERRIDE_ENV = 'HEYSPEX_HS_ON_PATH';
+
+function onPathOverride(env) {
+  const raw = String(env?.[HS_ON_PATH_OVERRIDE_ENV] ?? '');
+  if (raw === '1') return true;
+  if (raw === '0') return false;
+  return undefined;
+}
+
+/**
+ * Describe how HeySpex commands run on this machine.
+ *
+ * @returns {{ onPath: boolean, prefix: string, resolvedPath: string|null,
+ *            dispatcherPath: string|null }}
+ *   `prefix` is what a message should put in front of a subcommand — `"hs"`
+ *   when the bin is on PATH, else `node <abs>/bin/hs.mjs`.
+ */
+export function describeHsCommand({ env, exists, useCache = true } = {}) {
+  const injected = env !== undefined || exists !== undefined;
+  const effectiveEnv = env ?? process.env;
+
+  const override = onPathOverride(effectiveEnv);
+  if (override !== undefined) {
+    // The override wins outright — it is never merged with a real PATH scan,
+    // and it is never cached (it's a cheap string compare, and caching it
+    // would let one test's override leak into the next call).
+    return {
+      onPath: override,
+      prefix: override ? HS_BIN_NAME : HS_DISPATCHER_PREFIX,
+      resolvedPath: null,
+      dispatcherPath: HS_DISPATCHER_PATH,
+    };
+  }
+
+  if (useCache && !injected && cached) return cached;
+
+  const resolvedPath = findOnPath(HS_BIN_NAME, {
+    env: env ?? process.env,
+    exists: exists ?? existsSync,
+  });
+  const answer = {
+    onPath: resolvedPath !== null,
+    prefix: resolvedPath !== null ? HS_BIN_NAME : HS_DISPATCHER_PREFIX,
+    resolvedPath,
+    dispatcherPath: HS_DISPATCHER_PATH,
+  };
+  if (useCache && !injected) cached = answer;
+  return answer;
+}
+
+/**
+ * The runnable form of a HeySpex command, ready to paste into a message.
+ *
+ *   hsCommand('login')  → 'hs login'
+ *                       or 'node "C:\dev-projects\workflow-protocol\bin\hs.mjs" login'
+ *   hsCommand()         → 'hs'  or  'node "…\bin\hs.mjs"'
+ *
+ * Never throws: an unexpected failure yields the absolute-path dispatcher
+ * form, which runs from any working directory on a machine that has this
+ * install.
+ */
+export function hsCommand(args = '', options = {}) {
+  let prefix = HS_DISPATCHER_PREFIX;
+  try {
+    prefix = describeHsCommand(options).prefix;
+  } catch {
+    // Fall through to the dispatcher form — a message must never fail to render.
+  }
+  const tail = String(args ?? '').trim();
+  return tail ? `${prefix} ${tail}` : prefix;
+}
+
+/** Test seam: forget the cached PATH lookup. */
+export function resetHsCommandCache() {
+  cached = null;
+}