fix(scripts): surface the real launch error in check-changelog's run()

When a command check-changelog runs can't even launch (e.g. git-cliff not on
PATH), spawnSync returns status:null with the actual ENOENT/EACCES reason on
result.error. run() read only result.stderr/stdout and fell back to a generic
"<label> failed" string, discarding result.error and wasting debugging time.

Surface result.error.message (labeled) when status is null and no output is
available, keeping the existing stderr/stdout and generic-fallback paths
unchanged. run() gains injectable spawn/onFailure params (defaults preserve
CLI behavior) and the module's execution is guarded behind an entrypoint
check so the function can be unit-tested without running the checks.

Adds test/unit/check-changelog-script.test.ts covering the real-ENOENT
launch failure plus the stderr, generic-fallback, and success paths.

Closes #7772

Author: tech0328

scripts/check-changelog.mjs

@@ -2,73 +2,88 @@
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { pathToFileURL } from "node:url";
 import { spawnSync } from "node:child_process";
 
-const requestedChecks = new Set(process.argv.slice(2));
-const validArgs = new Set(["--root", "--mcp"]);
-const invalidArgs = [...requestedChecks].filter((arg) => !validArgs.has(arg));
+function main() {
+  const requestedChecks = new Set(process.argv.slice(2));
+  const validArgs = new Set(["--root", "--mcp"]);
+  const invalidArgs = [...requestedChecks].filter((arg) => !validArgs.has(arg));
 
-if (invalidArgs.length > 0) {
-  console.error(`Unknown changelog check option: ${invalidArgs.join(", ")}`);
-  process.exit(1);
-}
+  if (invalidArgs.length > 0) {
+    console.error(`Unknown changelog check option: ${invalidArgs.join(", ")}`);
+    process.exit(1);
+  }
 
-const tempDir = mkdtempSync(join(tmpdir(), "loopover-changelog-"));
+  const tempDir = mkdtempSync(join(tmpdir(), "loopover-changelog-"));
 
-try {
-  const checks = [
-    {
-      label: "root changelog",
-      output: "CHANGELOG.md",
-      command: "npm run changelog:root",
-      selector: "--root",
-      runner: () => {
-        const generatedPath = join(tempDir, "CHANGELOG.md");
-        run(["git-cliff", "--config", "cliff.toml", "--output", generatedPath], "root changelog");
-        return generatedPath;
+  try {
+    const checks = [
+      {
+        label: "root changelog",
+        output: "CHANGELOG.md",
+        command: "npm run changelog:root",
+        selector: "--root",
+        runner: () => {
+          const generatedPath = join(tempDir, "CHANGELOG.md");
+          run(["git-cliff", "--config", "cliff.toml", "--output", generatedPath], "root changelog");
+          return generatedPath;
+        },
       },
-    },
-    {
-      label: "MCP package changelog",
-      output: "packages/loopover-mcp/CHANGELOG.md",
-      command: "npm run changelog:mcp",
-      selector: "--mcp",
-      runner: () => {
-        const generatedPath = join(tempDir, "MCP_CHANGELOG.md");
-        const version = JSON.parse(readFileSync("packages/loopover-mcp/package.json", "utf8")).version;
-        writeFileSync(generatedPath, readFileSync("packages/loopover-mcp/CHANGELOG.md", "utf8"));
-        run(["node", "scripts/generate-mcp-changelog.mjs", "--output", generatedPath, "--version", version], "MCP package changelog");
-        return generatedPath;
+      {
+        label: "MCP package changelog",
+        output: "packages/loopover-mcp/CHANGELOG.md",
+        command: "npm run changelog:mcp",
+        selector: "--mcp",
+        runner: () => {
+          const generatedPath = join(tempDir, "MCP_CHANGELOG.md");
+          const version = JSON.parse(readFileSync("packages/loopover-mcp/package.json", "utf8")).version;
+          writeFileSync(generatedPath, readFileSync("packages/loopover-mcp/CHANGELOG.md", "utf8"));
+          run(["node", "scripts/generate-mcp-changelog.mjs", "--output", generatedPath, "--version", version], "MCP package changelog");
+          return generatedPath;
+        },
       },
-    },
-  ].filter((check) => requestedChecks.size === 0 || requestedChecks.has(check.selector));
+    ].filter((check) => requestedChecks.size === 0 || requestedChecks.has(check.selector));
 
-  const failures = [];
-  for (const check of checks) {
-    const generatedPath = check.runner();
-    const expected = readFileSync(generatedPath, "utf8");
-    const actual = readFileSync(check.output, "utf8");
-    if (normalize(actual) !== normalize(expected)) failures.push(`${check.output} is stale; run ${check.command}.`);
-  }
+    const failures = [];
+    for (const check of checks) {
+      const generatedPath = check.runner();
+      const expected = readFileSync(generatedPath, "utf8");
+      const actual = readFileSync(check.output, "utf8");
+      if (normalize(actual) !== normalize(expected)) failures.push(`${check.output} is stale; run ${check.command}.`);
+    }
 
-  if (failures.length > 0) {
-    console.error(failures.join("\n"));
-    process.exit(1);
-  }
+    if (failures.length > 0) {
+      console.error(failures.join("\n"));
+      process.exit(1);
+    }
 
-  console.log(`${checks.map((check) => check.output).join(", ")} current`);
-} finally {
-  rmSync(tempDir, { recursive: true, force: true });
+    console.log(`${checks.map((check) => check.output).join(", ")} current`);
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
 }
 
-function run(command, label) {
-  const result = spawnSync(command[0], command.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+/** Run a command, failing the process with its real output on a non-zero status. `spawn` and `onFailure` are
+ *  injectable purely for testability; every real caller uses the defaults. When the command cannot even
+ *  launch (`status` is null, e.g. the binary is not on PATH), `result.error` holds the actual ENOENT/EACCES
+ *  reason -- surface its message (#7772) instead of the generic `${label} failed`, which wastes debugging time. */
+export function run(command, label, { spawn = spawnSync, onFailure = defaultOnFailure } = {}) {
+  const result = spawn(command[0], command.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
   if (result.status !== 0) {
-    process.stderr.write(result.stderr || result.stdout || `${label} failed`);
-    process.exit(result.status ?? 1);
+    const message = result.stderr || result.stdout || (result.error ? `${label}: ${result.error.message}\n` : `${label} failed`);
+    onFailure(message, result.status ?? 1);
   }
 }
 
+function defaultOnFailure(message, code) {
+  process.stderr.write(message);
+  process.exit(code);
+}
+
 function normalize(value) {
   return value.replace(/\r\n/g, "\n").trimEnd();
 }
+
+/* v8 ignore next -- entrypoint guard: runs the checks only as a CLI, so importing `run` for tests is a no-op. */
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main();

test/unit/check-changelog-script.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from "vitest";
+// @ts-expect-error -- plain .mjs script with no type declarations
+import { run } from "../../scripts/check-changelog.mjs";
+
+/**
+ * #7772: when a command can't even launch (binary missing from PATH), spawnSync returns `status: null` with
+ * the real ENOENT/EACCES reason on `result.error`. `run()` used to fall back to a generic `"<label> failed"`
+ * string, discarding that reason. It now surfaces `result.error.message`, so a misconfigured dependency
+ * produces an actionable error instead of a mystery.
+ */
+describe("check-changelog run() launch-failure reporting (#7772)", () => {
+  it("surfaces the real spawn error when the command cannot launch (real ENOENT)", () => {
+    let captured = "";
+    let exitCode: number | undefined;
+    run(["loopover-definitely-not-a-real-binary-xyz"], "root changelog", {
+      onFailure: (message: string, code: number) => {
+        captured = message;
+        exitCode = code;
+      },
+    });
+
+    // The message carries the actual reason (spawn ENOENT ...), labeled -- not the generic "... failed".
+    expect(captured).toContain("root changelog");
+    expect(captured).toMatch(/ENOENT|spawn/);
+    expect(captured).not.toBe("root changelog failed");
+    expect(exitCode).toBe(1);
+  });
+
+  it("still falls back to the generic label when there is no error and no output (nonzero exit only)", () => {
+    // A command that ran but exited non-zero with empty streams and no launch error -> generic fallback.
+    const spawn = vi.fn(() => ({ status: 2, stdout: "", stderr: "", error: undefined }));
+    let captured = "";
+    let exitCode: number | undefined;
+    run(["anything"], "MCP package changelog", {
+      spawn: spawn as unknown as typeof import("node:child_process").spawnSync,
+      onFailure: (message: string, code: number) => {
+        captured = message;
+        exitCode = code;
+      },
+    });
+
+    expect(captured).toBe("MCP package changelog failed");
+    expect(exitCode).toBe(2);
+  });
+
+  it("prefers real stderr/stdout output over the launch-error fallback", () => {
+    const spawn = vi.fn(() => ({ status: 1, stdout: "", stderr: "cliff: bad config\n", error: undefined }));
+    let captured = "";
+    run(["git-cliff"], "root changelog", {
+      spawn: spawn as unknown as typeof import("node:child_process").spawnSync,
+      onFailure: (message: string) => {
+        captured = message;
+      },
+    });
+
+    expect(captured).toBe("cliff: bad config\n");
+  });
+
+  it("does nothing on success (status 0)", () => {
+    const spawn = vi.fn(() => ({ status: 0, stdout: "", stderr: "", error: undefined }));
+    const onFailure = vi.fn();
+    run(["git-cliff"], "root changelog", {
+      spawn: spawn as unknown as typeof import("node:child_process").spawnSync,
+      onFailure,
+    });
+
+    expect(onFailure).not.toHaveBeenCalled();
+  });
+});