feat: add issue filing guidance to error messages

Added issue filing guidance to both CLI and MCP error messages to help
users report unexpected errors or bad UX.

Changes:

- Added formatCliError() helper in CLI shared.ts that formats error messages
  with GitHub issue URL for non-user errors
- Updated program.ts to include global error handlers for uncaught exceptions
  and unhandled promise rejections
- Enhanced wrapError() in MCP server with issue filing guidance for
  unexpected errors (controlled by isUserError parameter)
- All unexpected errors now suggest filing an issue at:
  https://github.com/ExaDev/SysProM/issues/new

User errors (e.g. invalid input, missing files) don't include the issue
filing guidance, only genuine unexpected errors do.

Author: Mearman

src/cli/program.ts

@@ -3,6 +3,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { buildCommander } from "./define-command.js";
+import { formatCliError } from "./shared.js";
 import type { CommandDef } from "./define-command.js";
 
 let cachedVersion: string | undefined;
@@ -94,3 +95,15 @@ program
 	.action(async () => {
 		await import("../mcp/server.js");
 	});
+
+// Global error handlers for uncaught exceptions
+process.on("uncaughtException", (error) => {
+	console.error(formatCliError(error, false));
+	process.exit(1);
+});
+
+process.on("unhandledRejection", (reason) => {
+	const error = reason instanceof Error ? reason : new Error(String(reason));
+	console.error(formatCliError(error, false));
+	process.exit(1);
+});

src/cli/shared.ts

@@ -251,3 +251,31 @@ export function persistDoc(
 		}
 	}
 }
+
+// ---------------------------------------------------------------------------
+// Error formatting and reporting
+// ---------------------------------------------------------------------------
+
+const ISSUE_URL = "https://github.com/ExaDev/SysProM/issues/new";
+
+/**
+ * Format an error message for CLI output with issue filing guidance.
+ * If the error appears to be unexpected (not a user error), suggests filing an issue.
+ * @param error - The error to format
+ * @param isUserError - Whether this is a user error (e.g. invalid input); if false, suggests filing an issue
+ * @returns Formatted error message
+ * @example
+ * ```ts
+ * try { ... } catch (err: unknown) {
+ *   console.error(formatCliError(err, false)); // Not a user error - suggest issue
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export function formatCliError(error: unknown, isUserError = false): string {
+	const message = error instanceof Error ? error.message : String(error);
+	if (isUserError) {
+		return message;
+	}
+	return `${message}\n\nIf this was unexpected or bad UX, please file an issue:\n${ISSUE_URL}`;
+}

src/mcp/server.ts

@@ -27,22 +27,28 @@ import {
 
 /**
  * Wrap an error with a descriptive prefix and attach the original as cause.
+ * Adds issue filing guidance for unexpected errors.
  * @param prefix - The error prefix (e.g., "Failed to add node")
  * @param error - The caught error
+ * @param isUserError - Whether this is a user error; if false, suggests filing an issue
  * @example
  * ```ts
  * try {
  *   someOperation();
  * } catch (error) {
- *   wrapError("Failed to do X", error);
+ *   wrapError("Failed to do X", error, false); // Not a user error - suggest issue
  * }
  * ```
  */
-function wrapError(prefix: string, error: unknown): never {
-	throw new Error(
-		`${prefix}: ${error instanceof Error ? error.message : String(error)}`,
-		{ cause: error },
-	);
+function wrapError(prefix: string, error: unknown, isUserError = false): never {
+	const message = error instanceof Error ? error.message : String(error);
+	const fullMessage = `${prefix}: ${message}`;
+	const issueUrl = "https://github.com/ExaDev/SysProM/issues/new";
+	const errorMsg = isUserError
+		? fullMessage
+		: `${fullMessage}\n\nIf this was unexpected or bad UX, please file an issue: ${issueUrl}`;
+
+	throw new Error(errorMsg, { cause: error });
 }
 
 // Create MCP server instance