heyspex 0.2.6 → 0.2.7

package/scripts/lib/companion-install.mjs

@@ -0,0 +1,768 @@
+/**
+ * `npx heyspex companion install` and the installed-mode Companion
+ * ([[HS-056P-EH9T-EPIC-npx-heyspex-companion-install-front-door]], research
+ * [[HS-AUY9-EH9T-RES-spexcompanion-windows-installer]]).
+ *
+ * `npm install heyspex` stays install-script-free (HS-6UWZ). This module is the
+ * explicit, user-run step after it:
+ *
+ *   1. platform gate   Windows x64 only; anywhere else a notice, exit 0, no fetch
+ *   2. resolve latest  the published manifest (schema owned by HS-CA6B:
+ *                      {version,url,sha256,size,signed,gpuPackage}), read tolerantly
+ *   3. download        SpexCompanionSetup.exe to a temp folder, hashing as it streams
+ *   4. verify          SHA-256 (+ size) against the manifest, THEN the Authenticode
+ *                      signature (Get-AuthenticodeSignature via powershell
+ *                      -NoProfile): status Valid and the expected publisher. A hash
+ *                      from the same server only catches corruption; the signature
+ *                      is what catches a tampered manifest.
+ *   5. launch          interactive wizard by default; --quiet passes the silent
+ *                      flags; waits and passes on the setup's exit code
+ *
+ * Installed mode (no companion/ source beside the package): detect a Companion
+ * the setup installed (HKCU uninstall entry, else %LOCALAPPDATA%\HeySpex\Companion)
+ * and drive that exe for `hs companion start|stop|status`; when none is
+ * installed, offer the install instead of a dead end.
+ *
+ * Every side effect (platform, env, fetch, registry, fs probes, powershell,
+ * spawn) is injectable, so the tests run a local HTTP fixture, a fake exe and a
+ * mocked signature check -- nothing here ever needs a real installer.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/** Where `hs` looks for the latest release when nothing overrides it. */
+export const DEFAULT_MANIFEST_URL = "https://app.heyspex.com/downloads/heyspex-companion-latest.json";
+
+/**
+ * The Authenticode publisher (certificate subject CN) a setup must be signed
+ * by. HS-CA6B owns the signing identity; until it names the validated
+ * organisation this is the product name, and HEYSPEX_COMPANION_PUBLISHER
+ * overrides it on a machine (never the manifest -- a tampered manifest must not
+ * be able to name its own publisher).
+ */
+export const DEFAULT_EXPECTED_PUBLISHER = "HeySpex";
+
+/**
+ * Silent flags for --quiet. A WiX Burn bundle takes the standard /quiet and
+ * /norestart switches; the setup's own public properties (HS-G9YI) go after
+ * `--` on the command line, or come from the manifest's `quietArgs`.
+ */
+export const DEFAULT_QUIET_ARGS = Object.freeze(["/quiet", "/norestart"]);
+
+/** Exe names an installed Companion may carry (HS-JAX3 owns the layout). */
+export const INSTALLED_EXE_NAMES = Object.freeze(["HeySpex.Companion.Host.exe", "SpexCompanion.exe"]);
+
+export const UNINSTALL_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall";
+const DISPLAY_NAME_RE = /spex\s*companion|heyspex\s+companion/i;
+
+export const INSTALL_COMMAND = "npx heyspex companion install";
+
+/**
+ * What `hs companion install` says when there is no published installer yet:
+ * the release manifest is missing (HTTP 404) or names no SpexCompanionSetup.exe.
+ * Exit 1, never a crash ([[HS-5HM6-EH9T-DIAG-companion-install-dry-run-native]]).
+ */
+export const NO_INSTALLER_PUBLISHED_MESSAGE =
+  "hs companion install: no SpexCompanion installer has been published yet -- the Windows installer is coming (HS-4GXH).";
+
+const SHA256_RE = /^[0-9a-f]{64}$/;
+
+// ---------------------------------------------------------------------------
+// Text
+
+/** The notice every non-Windows (or non-x64) platform gets instead of a download. */
+export function renderWindowsOnlyNotice() {
+  return [
+    "SpexCompanion is Windows-only (x64). The heyspex CLI, MCP and hooks work on this OS without it.",
+    "Without it: run `npx hs pull --apply` to bring cloud-written specs down (the Companion's",
+    "automatic vault mirror), and SpexVoice / SpexCrawl research gather are not available.",
+  ].join("\n");
+}
+
+/**
+ * What `hs companion <sub>` prints from an installed package when no Companion
+ * is installed -- the install offer that replaced "not distributed through the
+ * npm package yet".
+ * @param {string} sub
+ * @param {{ platform?: string, arch?: string }} [opts]
+ */
+export function renderCompanionInstallOffer(sub, { platform = process.platform, arch = process.arch } = {}) {
+  if (!isSupportedPlatform(platform, arch)) {
+    return `hs companion ${sub}: ${renderWindowsOnlyNotice()}`;
+  }
+  return [
+    `hs companion ${sub}: SpexCompanion (the desktop tray app) is not installed on this machine.`,
+    "",
+    "Install it with:",
+    `  ${INSTALL_COMMAND}            (opens the Windows setup wizard)`,
+    `  ${INSTALL_COMMAND} --quiet    (silent install with the default choices)`,
+    "",
+    "It downloads the signed SpexCompanionSetup.exe, checks its SHA-256 and signature, then",
+    "runs it. No admin rights are needed. Until then: `npx hs pull --apply` brings cloud-written",
+    "specs down; `hs companion settings ...` (console-backed) works without it.",
+  ].join("\n");
+}
+
+export function renderInstallHelp() {
+  return [
+    "Usage:",
+    `  ${INSTALL_COMMAND} [--quiet] [--dry-run] [--force] [--manifest <url|path>] [--keep] [-- <setup args>]`,
+    "",
+    "Downloads the signed SpexCompanionSetup.exe named by the latest-release manifest, checks",
+    "its SHA-256 and its Authenticode signature (status Valid, expected publisher), then runs",
+    "it. Windows x64 only; on other platforms it prints a notice and downloads nothing.",
+    "",
+    "  --quiet               Silent install with the default choices (passes /quiet /norestart)",
+    "  --dry-run             Resolve, download and verify, but never launch the setup",
+    "  --force               Reinstall even when the installed version is current",
+    "  --manifest <url|path> Read this manifest instead of the published one",
+    "                        (env: HEYSPEX_COMPANION_MANIFEST_URL)",
+    "  --keep                Keep the downloaded setup file afterwards",
+    "  -- <setup args>       Passed to the setup unchanged (e.g. its public properties)",
+    "",
+    "Expected publisher: HEYSPEX_COMPANION_PUBLISHER overrides the default certificate CN.",
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+
+export function isSupportedPlatform(platform = process.platform, arch = process.arch) {
+  return platform === "win32" && arch === "x64";
+}
+
+/** Numeric dotted-version compare: <0, 0, >0. Non-numeric parts compare as 0. */
+export function compareVersions(a, b) {
+  const pa = String(a ?? "").replace(/^v/i, "").split(/[.+-]/).map((x) => Number.parseInt(x, 10) || 0);
+  const pb = String(b ?? "").replace(/^v/i, "").split(/[.+-]/).map((x) => Number.parseInt(x, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length, 3); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d) return d;
+  }
+  return 0;
+}
+
+/**
+ * Parse `hs companion install` argv.
+ * @returns {{ quiet:boolean, dryRun:boolean, force:boolean, keep:boolean, help:boolean, manifest:string|null, setupArgs:string[], error?:string }}
+ */
+export function parseInstallArgs(argv) {
+  const out = { quiet: false, dryRun: false, force: false, keep: false, help: false, manifest: null, setupArgs: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      out.setupArgs = argv.slice(i + 1);
+      break;
+    }
+    if (a === "--quiet" || a === "-q" || a === "--silent") out.quiet = true;
+    else if (a === "--dry-run") out.dryRun = true;
+    else if (a === "--force") out.force = true;
+    else if (a === "--keep") out.keep = true;
+    else if (a === "--help" || a === "-h" || a === "help") out.help = true;
+    else if (a === "--manifest") {
+      const v = argv[++i];
+      if (!v) return { ...out, error: "--manifest needs a url or path" };
+      out.manifest = v;
+    } else if (a.startsWith("--manifest=")) out.manifest = a.slice("--manifest=".length);
+    else return { ...out, error: `unknown argument ${a}` };
+  }
+  return out;
+}
+
+function pick(obj, ...keys) {
+  for (const k of keys) {
+    if (obj && obj[k] !== undefined && obj[k] !== null) return obj[k];
+  }
+  return undefined;
+}
+
+function looksLikeExeUrl(u) {
+  if (typeof u !== "string" || !u) return false;
+  try {
+    return /\.exe$/i.test(new URL(u, "http://x/").pathname);
+  } catch {
+    return false;
+  }
+}
+
+/** The manifest object that describes the installer, wherever HS-CA6B put it. */
+function findInstallerEntry(m) {
+  if (!m || typeof m !== "object") return null;
+  const candidates = [
+    m.installer,
+    m.windows_installer,
+    m.windowsInstaller,
+    m.companion_installer,
+    m.setup,
+    m.windows_companion?.installer,
+    m.windows_companion?.setup,
+    m.windows_companion,
+    m.windows,
+    m,
+  ];
+  for (const c of candidates) {
+    if (c && typeof c === "object" && looksLikeExeUrl(pick(c, "url", "download_url", "downloadUrl"))) return c;
+  }
+  return null;
+}
+
+function normalizeGpuPackage(g, baseUrl) {
+  if (!g || typeof g !== "object") return null;
+  const url = pick(g, "url", "download_url", "downloadUrl");
+  const sha = pick(g, "sha256", "sha_256", "checksum");
+  return {
+    version: pick(g, "version") ?? null,
+    url: typeof url === "string" ? safeResolve(url, baseUrl) : null,
+    sha256: typeof sha === "string" ? sha.toLowerCase() : null,
+    size: Number(pick(g, "size", "bytes", "size_bytes")) || null,
+  };
+}
+
+function safeResolve(u, base) {
+  try {
+    return new URL(u, base).href;
+  } catch {
+    return u;
+  }
+}
+
+/**
+ * Normalise the published manifest into one installer description. Tolerant
+ * of where the entry sits and of key spellings (size|bytes, sha256|sha_256,
+ * url|download_url); strict about what makes it safe to run.
+ * @param {unknown} manifest parsed JSON
+ * @param {string} manifestUrl the URL it came from (relative urls resolve against it)
+ * @returns {{ ok: true, installer: { version: string|null, url: string, sha256: string, size: number|null, signed: boolean|null, filename: string, quietArgs: string[]|null, gpuPackage: object|null } } | { ok: false, error: string }}
+ */
+export function parseInstallerManifest(manifest, manifestUrl) {
+  const e = findInstallerEntry(manifest);
+  if (!e) {
+    return {
+      ok: false,
+      error:
+        "the release manifest has no SpexCompanionSetup.exe entry yet -- the signed Windows setup " +
+        "has not been published (release pipeline HS-CA6B).",
+    };
+  }
+  const rawUrl = pick(e, "url", "download_url", "downloadUrl");
+  const url = safeResolve(rawUrl, manifestUrl);
+  let proto;
+  try {
+    proto = new URL(url).protocol;
+  } catch {
+    return { ok: false, error: `installer url is not a valid URL: ${rawUrl}` };
+  }
+  const allowHttp = proto === "http:" && isLoopbackUrl(url);
+  if (proto !== "https:" && proto !== "file:" && !allowHttp) {
+    return { ok: false, error: `installer url must be https (got ${proto}//): ${url}` };
+  }
+  const sha = String(pick(e, "sha256", "sha_256", "sha256sum", "checksum") ?? "").trim().toLowerCase().replace(/^sha256:/, "");
+  if (!SHA256_RE.test(sha)) {
+    return { ok: false, error: "installer entry has no valid sha256 (64 hex characters); refusing to download." };
+  }
+  const sizeRaw = pick(e, "size", "bytes", "size_bytes", "sizeBytes");
+  const size = sizeRaw === undefined ? null : Number(sizeRaw);
+  const signedRaw = pick(e, "signed", "authenticode");
+  const quietRaw = pick(e, "quietArgs", "quiet_args", "silentArgs", "silent_args");
+  const quietArgs = Array.isArray(quietRaw) && quietRaw.every((x) => typeof x === "string") ? [...quietRaw] : null;
+  let filename = pick(e, "filename", "file");
+  if (typeof filename !== "string" || !filename) {
+    filename = decodeURIComponent(new URL(url).pathname.split("/").pop() || "SpexCompanionSetup.exe");
+  }
+  filename = path.basename(filename.replace(/\\/g, "/"));
+  if (!/\.exe$/i.test(filename)) filename = "SpexCompanionSetup.exe";
+  return {
+    ok: true,
+    installer: {
+      version: pick(e, "version") != null ? String(pick(e, "version")) : manifest?.version != null && e === manifest ? String(manifest.version) : null,
+      url,
+      sha256: sha,
+      size: Number.isFinite(size) && size > 0 ? size : null,
+      signed: typeof signedRaw === "boolean" ? signedRaw : signedRaw && typeof signedRaw === "object" ? true : null,
+      filename,
+      quietArgs,
+      gpuPackage: normalizeGpuPackage(pick(e, "gpuPackage", "gpu_package", "gpu"), url),
+    },
+  };
+}
+
+function isLoopbackUrl(u) {
+  try {
+    const h = new URL(u).hostname;
+    return h === "127.0.0.1" || h === "localhost" || h === "[::1]";
+  } catch {
+    return false;
+  }
+}
+
+/** The CN out of an X.500 subject ("CN=HeySpex, O=HeySpex, C=US"). */
+export function subjectCommonName(subject) {
+  if (typeof subject !== "string") return null;
+  const m = subject.match(/(?:^|,\s*)CN=(?:"((?:[^"]|"")*)"|([^,]*))/i);
+  if (!m) return null;
+  return (m[1] !== undefined ? m[1].replace(/""/g, '"') : m[2]).trim();
+}
+
+/**
+ * Decide a signature verdict. Pure.
+ * @param {{ status?: string, subject?: string|null, message?: string }|null} sig
+ * @param {string} expectedPublisher compared case-insensitively against the subject CN
+ */
+export function judgeSignature(sig, expectedPublisher) {
+  if (!sig || typeof sig !== "object") return { ok: false, reason: "signature check returned nothing" };
+  if (sig.status !== "Valid") {
+    return { ok: false, reason: `Authenticode status is ${sig.status || "unknown"}${sig.message ? ` (${sig.message})` : ""}` };
+  }
+  const cn = subjectCommonName(sig.subject);
+  if (!cn || cn.toLowerCase() !== String(expectedPublisher).trim().toLowerCase()) {
+    return { ok: false, reason: `signed by "${cn ?? sig.subject ?? "unknown"}", expected publisher "${expectedPublisher}"` };
+  }
+  return { ok: true, publisher: cn, subject: sig.subject };
+}
+
+/** Setup argv for a launch. */
+export function buildSetupArgs({ quiet = false, quietArgs = null, setupArgs = [] } = {}) {
+  const base = quiet ? [...(quietArgs ?? DEFAULT_QUIET_ARGS)] : [];
+  return [...base, ...setupArgs];
+}
+
+/** Map a Burn / Windows Installer exit code to an outcome. */
+export function describeSetupExit(code) {
+  if (code === 0) return { ok: true, text: "SpexCompanion setup finished." };
+  if (code === 3010 || code === 1641) return { ok: true, text: "SpexCompanion setup finished; Windows asks for a restart to complete it." };
+  if (code === 1602 || code === 1223) return { ok: false, text: "SpexCompanion setup was cancelled." };
+  return { ok: false, text: `SpexCompanion setup exited with code ${code}.` };
+}
+
+/** Parse `reg query <UNINSTALL_KEY> /s` output into the SpexCompanion entry, if any. */
+export function parseUninstallRegQuery(text) {
+  if (typeof text !== "string" || !text) return null;
+  const blocks = text.split(/\r?\n(?=HKEY_)/);
+  for (const block of blocks) {
+    const values = {};
+    for (const line of block.split(/\r?\n/)) {
+      const m = line.match(/^\s+(\S[^\t]*?)\s{2,}(REG_\w+)\s{2,}(.*)$/) || line.match(/^\s+(\S+)\s+(REG_\w+)\s+(.*)$/);
+      if (m) values[m[1].trim()] = m[3].trim();
+    }
+    if (values.DisplayName && DISPLAY_NAME_RE.test(values.DisplayName)) {
+      return {
+        key: block.split(/\r?\n/)[0].trim(),
+        displayName: values.DisplayName,
+        version: values.DisplayVersion || null,
+        installLocation: values.InstallLocation ? values.InstallLocation.replace(/^"|"$/g, "") : null,
+        displayIcon: values.DisplayIcon ? values.DisplayIcon.replace(/^"|"$/g, "").replace(/,\d+$/, "") : null,
+      };
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Installed-mode detection
+
+function defaultRegQuery() {
+  const r = spawnSync("reg", ["query", UNINSTALL_KEY, "/s"], { encoding: "utf8", windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
+  return r.status === 0 ? r.stdout : "";
+}
+
+/** %LOCALAPPDATA%\HeySpex\Companion (null when LOCALAPPDATA is unknown). */
+export function defaultInstallDir(env = process.env) {
+  const base = env.LOCALAPPDATA || (env.USERPROFILE ? path.win32.join(env.USERPROFILE, "AppData", "Local") : null);
+  return base ? path.win32.join(base, "HeySpex", "Companion") : null;
+}
+
+/**
+ * Find a SpexCompanion installed by the setup. Registry first (it carries the
+ * version), then the default install folder.
+ * @param {{ platform?: string, env?: NodeJS.ProcessEnv, regQuery?: () => string, exists?: (p: string) => boolean }} [deps]
+ * @returns {{ installed: boolean, exePath?: string, installDir?: string, version?: string|null, source?: "registry"|"folder" }}
+ */
+export function detectInstalledCompanion({ platform = process.platform, env = process.env, regQuery = defaultRegQuery, exists = existsSync } = {}) {
+  if (platform !== "win32") return { installed: false };
+  let reg = null;
+  try {
+    reg = parseUninstallRegQuery(regQuery());
+  } catch {
+    reg = null;
+  }
+  const dirs = [];
+  if (reg?.installLocation) dirs.push(reg.installLocation);
+  const def = defaultInstallDir(env);
+  if (def) dirs.push(def);
+  if (reg?.displayIcon && /\.exe$/i.test(reg.displayIcon) && exists(reg.displayIcon) && INSTALLED_EXE_NAMES.some((n) => n.toLowerCase() === path.win32.basename(reg.displayIcon).toLowerCase())) {
+    return { installed: true, exePath: reg.displayIcon, installDir: path.win32.dirname(reg.displayIcon), version: reg.version, source: "registry" };
+  }
+  for (const dir of dirs) {
+    for (const name of INSTALLED_EXE_NAMES) {
+      const exePath = path.win32.join(dir, name);
+      if (exists(exePath)) {
+        return { installed: true, exePath, installDir: dir, version: reg?.version ?? null, source: reg ? "registry" : "folder" };
+      }
+    }
+  }
+  return { installed: false, registryEntry: reg ?? undefined };
+}
+
+// ---------------------------------------------------------------------------
+// Effects (default implementations; all injectable)
+
+/** Load the manifest from an http(s) URL, a file: URL or a local path. */
+export async function loadManifest(source, { fetchImpl = globalThis.fetch } = {}) {
+  if (/^https?:\/\//i.test(source)) {
+    const res = await fetchImpl(source, { headers: { accept: "application/json" } });
+    if (!res.ok) {
+      // Release the unread body so the pooled socket closes now, not at exit.
+      try {
+        await res.body?.cancel?.();
+      } catch {
+        /* already closed */
+      }
+      const e = new Error(`manifest fetch failed: HTTP ${res.status} from ${source}`);
+      e.status = res.status;
+      throw e;
+    }
+    return { json: await res.json(), url: source };
+  }
+  const file = /^file:/i.test(source) ? fileURLToPath(source) : path.resolve(source);
+  return { json: JSON.parse(readFileSync(file, "utf8")), url: pathToFileURL(file).href };
+}
+
+/**
+ * Stream `url` to `dest`, hashing as it goes. Returns { sha256, bytes }.
+ * @param {(p: { received: number, total: number|null }) => void} [onProgress]
+ */
+export async function downloadWithHash(url, dest, { fetchImpl = globalThis.fetch, onProgress } = {}) {
+  mkdirSync(path.dirname(dest), { recursive: true });
+  const hash = createHash("sha256");
+  let received = 0;
+  let source;
+  let total = null;
+  if (/^file:/i.test(url)) {
+    const file = fileURLToPath(url);
+    total = statSync(file).size;
+    source = createReadStream(file);
+  } else {
+    const res = await fetchImpl(url);
+    if (!res.ok || !res.body) throw new Error(`download failed: HTTP ${res.status} from ${url}`);
+    total = Number(res.headers?.get?.("content-length")) || null;
+    source = Readable.fromWeb(res.body);
+  }
+  source.on("data", (chunk) => {
+    hash.update(chunk);
+    received += chunk.length;
+    onProgress?.({ received, total });
+  });
+  await pipeline(source, createWriteStream(dest));
+  return { sha256: hash.digest("hex"), bytes: received };
+}
+
+export const SIGNATURE_PS =
+  "$ErrorActionPreference = 'Stop'; " +
+  "$s = Get-AuthenticodeSignature -LiteralPath $env:HEYSPEX_SIG_PATH; " +
+  "[pscustomobject]@{ " +
+  "status = $s.Status.ToString(); " +
+  "subject = $(if ($s.SignerCertificate) { $s.SignerCertificate.Subject } else { $null }); " +
+  "message = $s.StatusMessage; " +
+  "timestamped = [bool]$s.TimeStamperCertificate " +
+  "} | ConvertTo-Json -Compress";
+
+/** process.env minus PSModulePath (any casing). */
+export function withoutPsModulePath(env) {
+  const copy = { ...env };
+  for (const k of Object.keys(copy)) if (k.toLowerCase() === "psmodulepath") delete copy[k];
+  return copy;
+}
+
+/**
+ * Get-AuthenticodeSignature via Windows PowerShell. The path travels in an env
+ * var, never interpolated into the command.
+ * @returns {{ status: string, subject: string|null, message?: string, timestamped?: boolean }}
+ */
+export function readAuthenticodeSignature(file, { spawnSyncImpl = spawnSync, powershell = "powershell.exe" } = {}) {
+  const r = spawnSyncImpl(powershell, ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", SIGNATURE_PS], {
+    encoding: "utf8",
+    windowsHide: true,
+    // A PSModulePath inherited from PowerShell 7 makes Windows PowerShell 5.1
+    // load the wrong Microsoft.PowerShell.Security and the cmdlet fails to load.
+    env: { ...withoutPsModulePath(process.env), HEYSPEX_SIG_PATH: file },
+  });
+  if (r.error) return { status: "CheckFailed", subject: null, message: r.error.message };
+  const line = String(r.stdout || "").trim().split(/\r?\n/).filter(Boolean).pop();
+  try {
+    return JSON.parse(line);
+  } catch {
+    return { status: "CheckFailed", subject: null, message: (r.stderr || "no output").trim().slice(0, 300) };
+  }
+}
+
+/** Run the setup, wait, resolve its exit code. */
+export function launchSetup(exe, args, { spawnImpl = spawn } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(exe, args, { stdio: "inherit", windowsHide: false });
+    child.on("error", reject);
+    child.on("exit", (code, signal) => resolve(signal ? 1 : (code ?? 0)));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+
+/**
+ * `hs companion install`. Returns the process exit code; prints via out/err.
+ * @param {string[]} argv
+ * @param {object} [deps]
+ */
+export async function runCompanionInstall(argv, deps = {}) {
+  const {
+    platform = process.platform,
+    arch = process.arch,
+    env = process.env,
+    out = (s) => process.stdout.write(`${s}\n`),
+    err = (s) => process.stderr.write(`${s}\n`),
+    fetchImpl = globalThis.fetch,
+    tmpDir = os.tmpdir(),
+    detect = () => detectInstalledCompanion({ platform, env }),
+    readSignature = (file) => readAuthenticodeSignature(file),
+    launch = (exe, args) => launchSetup(exe, args),
+    progress = null,
+  } = deps;
+
+  const args = parseInstallArgs(argv);
+  if (args.error) {
+    err(`hs companion install: ${args.error}\n\n${renderInstallHelp()}`);
+    return 2;
+  }
+  if (args.help) {
+    out(renderInstallHelp());
+    return 0;
+  }
+  if (!isSupportedPlatform(platform, arch)) {
+    out(renderWindowsOnlyNotice());
+    return 0;
+  }
+
+  const installed = detect();
+  if (installed.installed) {
+    out(`Installed: SpexCompanion ${installed.version ?? "(version unknown)"} at ${installed.exePath}`);
+  }
+
+  const manifestSource = args.manifest || env.HEYSPEX_COMPANION_MANIFEST_URL || DEFAULT_MANIFEST_URL;
+  let manifest;
+  try {
+    manifest = await loadManifest(manifestSource, { fetchImpl });
+  } catch (e) {
+    if (e?.status === 404 || e?.code === "ENOENT") {
+      err(NO_INSTALLER_PUBLISHED_MESSAGE);
+      err(`    (release manifest not found: ${manifestSource})`);
+      return 1;
+    }
+    err(`hs companion install: could not read the release manifest (${manifestSource}): ${e.message}`);
+    return 1;
+  }
+  if (!findInstallerEntry(manifest.json)) {
+    err(NO_INSTALLER_PUBLISHED_MESSAGE);
+    err(`    (the release manifest names no SpexCompanionSetup.exe: ${manifestSource})`);
+    return 1;
+  }
+  const parsed = parseInstallerManifest(manifest.json, manifest.url);
+  if (!parsed.ok) {
+    err(`hs companion install: ${parsed.error}`);
+    return 1;
+  }
+  const inst = parsed.installer;
+  if (inst.signed === false) {
+    err("hs companion install: the manifest marks this setup as unsigned; refusing to run an unsigned installer.");
+    return 1;
+  }
+  out(`Latest: SpexCompanion ${inst.version ?? "(version unknown)"} -- ${inst.url}`);
+
+  if (installed.installed && installed.version && inst.version && !args.force && !args.dryRun && compareVersions(installed.version, inst.version) >= 0) {
+    out(`SpexCompanion is up to date (${installed.version}). Use --force to reinstall.`);
+    return 0;
+  }
+  if (installed.installed && installed.version && inst.version && compareVersions(installed.version, inst.version) < 0) {
+    out(`Upgrade available: ${installed.version} -> ${inst.version}.`);
+  }
+
+  const dir = path.join(tmpDir, `heyspex-companion-setup-${inst.version ?? "latest"}-${process.pid}`);
+  const dest = path.join(dir, inst.filename);
+  const cleanup = () => {
+    if (!args.keep) rmSync(dir, { recursive: true, force: true });
+  };
+
+  let got;
+  try {
+    out(`Downloading ${inst.filename}${inst.size ? ` (${(inst.size / 1048576).toFixed(1)} MB)` : ""} ...`);
+    got = await downloadWithHash(inst.url, dest, { fetchImpl, onProgress: progress ?? undefined });
+  } catch (e) {
+    cleanup();
+    err(`hs companion install: ${e.message}`);
+    return 1;
+  }
+  if (got.sha256 !== inst.sha256) {
+    rmSync(dir, { recursive: true, force: true });
+    err(`hs companion install: SHA-256 mismatch -- expected ${inst.sha256}, got ${got.sha256}. The download was deleted; nothing was run.`);
+    return 1;
+  }
+  if (inst.size && got.bytes !== inst.size) {
+    rmSync(dir, { recursive: true, force: true });
+    err(`hs companion install: size mismatch -- expected ${inst.size} bytes, got ${got.bytes}. The download was deleted; nothing was run.`);
+    return 1;
+  }
+  out(`SHA-256 ok (${got.sha256}).`);
+
+  const expected = (env.HEYSPEX_COMPANION_PUBLISHER || DEFAULT_EXPECTED_PUBLISHER).trim();
+  let sig;
+  try {
+    sig = await readSignature(dest);
+  } catch (e) {
+    sig = { status: "CheckFailed", subject: null, message: e.message };
+  }
+  const verdict = judgeSignature(sig, expected);
+  if (!verdict.ok) {
+    rmSync(dir, { recursive: true, force: true });
+    err(`hs companion install: signature check failed -- ${verdict.reason}. The download was deleted; nothing was run.`);
+    return 1;
+  }
+  out(`Signature ok: Valid, publisher "${verdict.publisher}".`);
+
+  const setupArgs = buildSetupArgs({ quiet: args.quiet, quietArgs: inst.quietArgs, setupArgs: args.setupArgs });
+  if (args.dryRun) {
+    out(`Dry run: would run ${dest}${setupArgs.length ? ` ${setupArgs.join(" ")}` : ""} -- not launched.`);
+    if (args.keep) out(`Kept: ${dest}`);
+    cleanup();
+    return 0;
+  }
+
+  out(args.quiet ? "Installing SpexCompanion silently ..." : "Opening the SpexCompanion setup wizard ...");
+  let code;
+  try {
+    code = await launch(dest, setupArgs);
+  } catch (e) {
+    cleanup();
+    err(`hs companion install: could not start the setup: ${e.message}`);
+    return 1;
+  }
+  cleanup();
+  const d = describeSetupExit(code);
+  (d.ok ? out : err)(d.text);
+  if (d.ok) out("Start it any time with `npx hs companion start`.");
+  return d.ok ? 0 : code || 1;
+}
+
+// ---------------------------------------------------------------------------
+// Installed-mode host verbs
+
+function defaultIsRunning(imageName) {
+  const r = spawnSync("tasklist", ["/FI", `IMAGENAME eq ${imageName}`, "/NH", "/FO", "CSV"], { encoding: "utf8", windowsHide: true });
+  return r.status === 0 && r.stdout.toLowerCase().includes(`"${imageName.toLowerCase()}"`);
+}
+
+function defaultStartDetached(exe) {
+  const child = spawn(exe, [], { detached: true, stdio: "ignore", cwd: path.win32.dirname(exe), windowsHide: false });
+  child.unref();
+  return child.pid;
+}
+
+function defaultStop(imageName) {
+  const r = spawnSync("taskkill", ["/IM", imageName], { encoding: "utf8", windowsHide: true });
+  return r.status === 0;
+}
+
+/**
+ * `hs companion start|stop|status|build` when the package has no companion/
+ * source. Returns the exit code.
+ */
+export function runInstalledCompanionHost(sub, deps = {}) {
+  const {
+    platform = process.platform,
+    arch = process.arch,
+    env = process.env,
+    out = (s) => process.stdout.write(`${s}\n`),
+    err = (s) => process.stderr.write(`${s}\n`),
+    detect = () => detectInstalledCompanion({ platform, env }),
+    isRunning = defaultIsRunning,
+    startDetached = defaultStartDetached,
+    stop = defaultStop,
+  } = deps;
+
+  if (!isSupportedPlatform(platform, arch)) {
+    err(`hs companion ${sub}: ${renderWindowsOnlyNotice()}`);
+    return 1;
+  }
+  if (sub === "build") {
+    err("hs companion build: building the Companion needs a HeySpex source checkout. From the npm package, install the released build with `npx heyspex companion install`.");
+    return 1;
+  }
+  const found = detect();
+  if (!found.installed) {
+    err(renderCompanionInstallOffer(sub, { platform, arch }));
+    return 1;
+  }
+  const image = path.win32.basename(found.exePath);
+  const label = `SpexCompanion ${found.version ?? "(version unknown)"} at ${found.exePath}`;
+  if (sub === "status") {
+    out(`${label}: ${isRunning(image) ? "running" : "not running"}.`);
+    return 0;
+  }
+  if (sub === "stop") {
+    if (!isRunning(image)) {
+      out("SpexCompanion is not running.");
+      return 0;
+    }
+    if (stop(image)) {
+      out("SpexCompanion asked to exit.");
+      return 0;
+    }
+    err(`hs companion stop: could not stop ${image}; quit it from the tray icon.`);
+    return 1;
+  }
+  // start
+  if (isRunning(image)) {
+    out(`${label}: already running.`);
+    return 0;
+  }
+  try {
+    const pid = startDetached(found.exePath);
+    out(`Started ${label}${pid ? ` (pid ${pid})` : ""}.`);
+    return 0;
+  } catch (e) {
+    err(`hs companion start: could not start ${found.exePath}: ${e.message}`);
+    return 1;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Doctor row
+
+/**
+ * The published-install `hs doctor` Companion row. Never `fail`: the
+ * Companion is optional, so missing is a warn with the install offer.
+ */
+export function companionDoctorRow({ platform = process.platform, arch = process.arch, detect } = {}) {
+  if (!isSupportedPlatform(platform, arch)) {
+    return { id: "companion", label: "SpexCompanion", status: "ok", detail: "skipped -- SpexCompanion is Windows-only (x64); not needed on this OS" };
+  }
+  let found;
+  try {
+    found = (detect ?? (() => detectInstalledCompanion({ platform })))();
+  } catch (e) {
+    return { id: "companion", label: "SpexCompanion", status: "warn", detail: `could not check for an installed Companion: ${e.message}` };
+  }
+  if (found.installed) {
+    return { id: "companion", label: "SpexCompanion", status: "ok", detail: `installed ${found.version ?? "(version unknown)"} at ${found.exePath}` };
+  }
+  return {
+    id: "companion",
+    label: "SpexCompanion",
+    status: "warn",
+    detail: "not installed (optional: vault mirror, SpexVoice, SpexCrawl gather)",
+    human: `Install it with \`${INSTALL_COMMAND}\` (signed Windows setup, no admin needed).`,
+  };
+}