refactor(scripts): replace process.exit() with ExitError + runMain handler (#739) (#740)

Part 1 of 2 of the n/no-process-exit cleanup (umbrella #738): convert every
process.exit() call in standalone scripts/** CLIs to the rule-compliant pattern.

- New shared helper scripts/lib/cli-exit.cjs: ExitError(code,message) + runMain()
  which translates a thrown ExitError / returned number into process.exitCode
  (never process.exit()), flushing output and still firing process.on('exit').
- main()-based entrypoints: throw new ExitError(code) for errors, return <code>
  for verdicts; invoked via runMain(main). Child exit codes preserved via return.
- top-level-only scripts: imperative body extracted into main() so mid-flow
  aborts (throw ExitError) actually halt; pure consts/helpers stay at module scope.
- diff-touches-shipped-paths.cjs: stdin event handling restructured to an async
  read so the whole flow runs under runMain; uncaughtException/unhandledRejection
  nets replaced by an in-band catch that preserves EXIT_ERROR=2.

Exit codes verified unchanged for every converted script (success/error/help and
the 0/1/2 semantic codes in diff-touches). Rule stays warn here; flipped to error
in part 2 (#738) once gsd-core/bin/** is also clean.

Refs #739

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

scripts/lib/cli-exit.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * Error that carries a process exit code. CLI logic throws this instead of
+ * calling process.exit() (banned by n/no-process-exit); runMain() translates it
+ * into process.exitCode at the entrypoint.
+ *
+ * @param {number} code  exit code (default 1)
+ * @param {string} [message]  optional human message; when set and code != 0 it is
+ *   written to stderr by runMain before the process exits.
+ */
+class ExitError extends Error {
+  constructor(code = 1, message) {
+    super(message === undefined ? `process exit ${code}` : message);
+    this.name = 'ExitError';
+    this.code = code;
+    // Whether runMain should print this.message to stderr (only when a real
+    // message was provided, not the synthetic default).
+    this.hasUserMessage = message !== undefined;
+  }
+}
+
+/**
+ * Run a CLI main function and translate its outcome into process.exitCode
+ * (never process.exit(), so n/no-process-exit stays satisfied). Supports sync or
+ * async main.
+ *   - main returns a number  -> process.exitCode = that number
+ *   - main throws/rejects ExitError -> process.exitCode = err.code, and if
+ *       err.hasUserMessage && err.code !== 0, err.message is written to stderr
+ *   - main throws/rejects anything else -> the stack is written to stderr and
+ *       process.exitCode = 1
+ * Letting the event loop drain (vs process.exit) means buffered stdout/stderr is
+ * flushed and process.on('exit') cleanup handlers still fire.
+ *
+ * @param {() => (number|void|Promise<number|void>)} main
+ */
+function runMain(main) {
+  Promise.resolve()
+    .then(() => main())
+    .then((code) => {
+      if (typeof code === 'number') process.exitCode = code;
+    })
+    .catch((err) => {
+      if (err instanceof ExitError) {
+        if (err.hasUserMessage && err.code !== 0) {
+          process.stderr.write(`${err.message}\n`);
+        }
+        process.exitCode = err.code;
+        return;
+      }
+      process.stderr.write(`${err && err.stack ? err.stack : String(err)}\n`);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = { ExitError, runMain };