sysprom 1.23.0 → 1.24.0

package/dist/src/cli/program.js

@@ -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";
 let cachedVersion;
 function getVersion() {
     if (cachedVersion === undefined) {
@@ -81,3 +82,13 @@ 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);
+});

package/dist/src/cli/shared.d.ts

@@ -72,3 +72,18 @@ export declare function loadDoc(input?: string): LoadedDoc;
  * ```
  */
 export declare function persistDoc(doc: SysProMDocument, loaded: LoadedDoc, opts: MutationOpts): void;
+/**
+ * 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 declare function formatCliError(error: unknown, isUserError?: boolean): string;

package/dist/src/cli/shared.js

@@ -207,3 +207,28 @@ export function persistDoc(doc, loaded, opts) {
         }
     }
 }
+// ---------------------------------------------------------------------------
+// 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, isUserError = false) {
+    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}`;
+}

package/dist/src/mcp/server.js

@@ -7,19 +7,27 @@ import { NodeType, RelationshipType } from "../schema.js";
 import { validateOp, statsOp, queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, nextIdOp, inferCompletenessOp, inferLifecycleOp, inferImpactOp, impactSummaryOp, inferDerivedOp, } from "../operations/index.js";
 /**
  * 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, error) {
-    throw new Error(`${prefix}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+function wrapError(prefix, error, isUserError = false) {
+    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
 const server = new McpServer({

package/dist/src/operations/graph-shared.js

@@ -105,6 +105,24 @@ const NODE_TYPE_SHAPES = {
 export function mermaidShapeForNode(node) {
     return NODE_TYPE_SHAPES[node.type] ?? "rectangle";
 }
+/**
+ * Escape a Mermaid label by wrapping in quotes if it contains special characters.
+ * Mermaid shape delimiters and other special chars need escaping: ( ) { } [ ] / \
+ * Wrapping in double quotes allows these characters to be rendered as-is.
+ * @param label - The label text to escape
+ * @returns The label, quoted if it contains special characters
+ * @example
+ * escapeMermaidLabel("Firebase (Tenant)") // returns '"Firebase (Tenant)"'
+ */
+function escapeMermaidLabel(label) {
+    // Check if label contains any Mermaid special characters that need escaping
+    const specialChars = ["(", ")", "{", "}", "[", "]", "/", "\\"];
+    if (specialChars.some((char) => label.includes(char))) {
+        // Wrap in double quotes to escape
+        return `"${label}"`;
+    }
+    return label;
+}
 /**
  * Render a Mermaid node definition for a node id/name/shape.
  * @param id - Node id
@@ -116,16 +134,17 @@ export function mermaidShapeForNode(node) {
 export function renderMermaidNode(id, name, shape, mode = "friendly") {
     const safeId = sanitiseMermaidId(id);
     const label = mode === "compact" ? id : `${id}: ${name}`;
+    const escapedLabel = escapeMermaidLabel(label);
     switch (shape) {
         case "rounded":
-            return `${safeId}([${label}])`;
+            return `${safeId}([${escapedLabel}])`;
         case "rhombus":
-            return `${safeId}{{${label}}}`;
+            return `${safeId}{{${escapedLabel}}}`;
         case "parallelogram":
-            return `${safeId}[/${label}/]`;
+            return `${safeId}[/${escapedLabel}/]`;
         case "rectangle":
         default:
-            return `${safeId}[${label}]`;
+            return `${safeId}[${escapedLabel}]`;
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sysprom",
-	"version": "1.23.0",
+	"version": "1.24.0",
 	"description": "SysProM — System Provenance Model CLI and library",
 	"author": "ExaDev",
 	"homepage": "https://exadev.github.io/SysProM",