sysprom 1.16.0 → 1.17.0

package/README.md

@@ -2,6 +2,8 @@
 
 /sɪs.prɒm/
 
+[![npm](https://img.shields.io/badge/npm-cb3837?logo=npm)](https://www.npmjs.com/package/sysprom)[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github)](https://github.com/ExaDev/SysProM)
+
 A recursive, decision-driven model for recording where every part of a system came from, what decisions shaped it, and how it reached its current form.
 
 ## Install

package/dist/src/cli/commands/add.js

@@ -31,6 +31,49 @@ const optsSchema = mutationOpts.extend({
         .optional()
         .describe("Option in format 'ID:description' or just 'description' (repeatable)"),
 });
+/**
+ * Populate optional node fields from CLI options.
+ * @param node - The node to populate
+ * @param description - Optional description
+ * @param status - Optional (pre-validated) status
+ * @param context - Optional decision context
+ * @param rationale - Optional decision rationale
+ * @param scope - Optional change scope
+ * @param selected - Optional selected option ID
+ * @param options - Optional array of option descriptions
+ * @example
+ * ```ts
+ * const node: Node = { id: "D1", type: "decision", name: "My Decision" };
+ * populateNodeFromOpts(node, desc, status, ctx, rat, scope, sel, opts);
+ * ```
+ */
+function populateNodeFromOpts(node, description, status, context, rationale, scope, selected, options) {
+    if (description)
+        node.description = description;
+    if (status)
+        node.status = status;
+    if (context)
+        node.context = context;
+    if (rationale)
+        node.rationale = rationale;
+    if (scope?.length)
+        node.scope = scope;
+    if (selected)
+        node.selected = selected;
+    if (options?.length) {
+        node.options = options.map((arg, i) => {
+            const colonIdx = arg.indexOf(":");
+            if (colonIdx >= 0) {
+                return {
+                    id: arg.slice(0, colonIdx),
+                    description: arg.slice(colonIdx + 1),
+                };
+            }
+            const letter = String.fromCharCode(65 + i);
+            return { id: `${node.id}-OPT-${letter}`, description: arg };
+        });
+    }
+}
 export const addCommand = {
     name: "add",
     description: addNodeOp.def.description,
@@ -49,45 +92,18 @@ export const addCommand = {
             console.error(`Unknown node type: "${type}". Valid types: ${NodeType.options.join(", ")}`);
             process.exit(1);
         }
+        if (opts.status && !NodeStatus.is(opts.status)) {
+            console.error(`Unknown status: "${opts.status}". Valid statuses: ${NodeStatus.options.join(", ")}`);
+            process.exit(1);
+        }
         const id = opts.id ?? nextIdOp({ doc, type });
-        // Build the node from CLI options
         const node = { id, type, name: opts.name };
-        if (opts.description) {
-            node.description = opts.description;
-        }
-        if (opts.status) {
-            if (!NodeStatus.is(opts.status)) {
-                console.error(`Unknown status: "${opts.status}". Valid statuses: ${NodeStatus.options.join(", ")}`);
-                process.exit(1);
-            }
-            node.status = opts.status;
-        }
-        if (opts.context) {
-            node.context = opts.context;
-        }
-        if (opts.rationale) {
-            node.rationale = opts.rationale;
-        }
-        if (opts.scope && opts.scope.length > 0) {
-            node.scope = opts.scope;
-        }
-        if (opts.selected) {
-            node.selected = opts.selected;
-        }
-        if (opts.option && opts.option.length > 0) {
-            node.options = opts.option.map((arg, i) => {
-                const colonIdx = arg.indexOf(":");
-                if (colonIdx >= 0) {
-                    return {
-                        id: arg.slice(0, colonIdx),
-                        description: arg.slice(colonIdx + 1),
-                    };
-                }
-                // Auto-generate ID: D26-OPT-A, D26-OPT-B, etc.
-                const letter = String.fromCharCode(65 + i); // A, B, C, ...
-                return { id: `${id}-OPT-${letter}`, description: arg };
-            });
+        // Use type guard to narrow status type after validation
+        let status;
+        if (opts.status && NodeStatus.is(opts.status)) {
+            status = opts.status;
         }
+        populateNodeFromOpts(node, opts.description, status, opts.context, opts.rationale, opts.scope, opts.selected, opts.option);
         try {
             const newDoc = addNodeOp({
                 doc,

package/dist/src/cli/commands/infer.js

@@ -5,9 +5,17 @@ import { inferCompletenessOp, inferLifecycleOp, inferImpactOp, inferDerivedOp, }
 // ---------------------------------------------------------------------------
 // Presentation helpers
 // ---------------------------------------------------------------------------
+function getScoreColour(score) {
+    if (score === 1)
+        return pc.green;
+    if (score >= 0.5)
+        return pc.yellow;
+    return pc.red;
+}
 function printCompletenessNode(r) {
-    const scoreColour = r.score === 1 ? pc.green : r.score >= 0.5 ? pc.yellow : pc.red;
-    console.log(`${pc.cyan(r.id.padEnd(12))} ${pc.dim(r.type.padEnd(16))} ${pc.bold(r.name)} ${scoreColour(`[${(r.score * 100).toFixed(0)}%]`)}`);
+    const scoreColour = getScoreColour(r.score);
+    const scoreText = `[${(r.score * 100).toFixed(0)}%]`;
+    console.log(`${pc.cyan(r.id.padEnd(12))} ${pc.dim(r.type.padEnd(16))} ${pc.bold(r.name)} ${scoreColour(scoreText)}`);
     for (const issue of r.issues) {
         console.log(`  ${pc.dim("•")} ${pc.red(issue)}`);
     }
@@ -21,7 +29,8 @@ function printLifecycleNode(r) {
         unknown: pc.dim,
     };
     const colour = phaseColours[r.inferredPhase] ?? pc.dim;
-    console.log(`${pc.cyan(r.id.padEnd(12))} ${pc.dim(r.type.padEnd(16))} ${pc.bold(r.name)} ${colour(`[${r.inferredPhase}]`)} ${pc.dim(r.inferredState)}`);
+    const phaseLabel = colour(`[${r.inferredPhase}]`);
+    console.log(`${pc.cyan(r.id.padEnd(12))} ${pc.dim(r.type.padEnd(16))} ${pc.bold(r.name)} ${phaseLabel} ${pc.dim(r.inferredState)}`);
 }
 function printImpactNode(r) {
     const typeColours = {
@@ -32,7 +41,9 @@ function printImpactNode(r) {
     const colour = typeColours[r.impactType] ?? pc.dim;
     const nodeName = r.node ? r.node.name : "(unknown)";
     const indent = "  ".repeat(r.distance);
-    console.log(`${indent}${pc.cyan(r.id)} ${pc.dim(`(${String(r.distance)})`)} ${colour(`[${r.impactType}]`)} ${pc.bold(nodeName)}`);
+    const distanceLabel = pc.dim(`(${String(r.distance)})`);
+    const typeLabel = colour(`[${r.impactType}]`);
+    console.log(`${indent}${pc.cyan(r.id)} ${distanceLabel} ${typeLabel} ${pc.bold(nodeName)}`);
 }
 function printDerivedRelationship(r) {
     const typeColours = {
@@ -41,7 +52,8 @@ function printDerivedRelationship(r) {
         inverse: pc.green,
     };
     const colour = typeColours[r.derivationType] ?? pc.dim;
-    console.log(`${pc.cyan(r.from.padEnd(12))} ${colour(r.type.padEnd(20))} ${pc.cyan(r.to)} ${pc.dim(`[${r.derivationType}]`)}`);
+    const derivationLabel = pc.dim(`[${r.derivationType}]`);
+    console.log(`${pc.cyan(r.from.padEnd(12))} ${colour(r.type.padEnd(20))} ${pc.cyan(r.to)} ${derivationLabel}`);
 }
 // ---------------------------------------------------------------------------
 // Arg/opt schemas
@@ -79,12 +91,13 @@ const completenessSubcommand = {
             console.log(JSON.stringify(result, null, 2));
         }
         else {
-            console.log(pc.bold("\nCompleteness Analysis\n") +
-                pc.dim(`Average score: ${(result.averageScore * 100).toFixed(1)}% | `) +
-                pc.green(`${String(result.completeNodes)} complete`) +
-                pc.dim(" | ") +
-                pc.red(`${String(result.incompleteNodes)} incomplete`) +
-                "\n");
+            const avgScore = (result.averageScore * 100).toFixed(1);
+            const completeText = pc.green(`${String(result.completeNodes)} complete`);
+            const incompleteText = pc.red(`${String(result.incompleteNodes)} incomplete`);
+            const scorePrefix = pc.dim(`Average score: ${avgScore}% | `);
+            const separator = pc.dim(" | ");
+            const summary = scorePrefix + completeText + separator + incompleteText;
+            console.log(pc.bold("\nCompleteness Analysis\n") + summary + "\n");
             // Show incomplete nodes first
             const incomplete = result.nodes.filter((n) => n.score < 1);
             const complete = result.nodes.filter((n) => n.score === 1);
@@ -111,9 +124,9 @@ const lifecycleSubcommand = {
             console.log(JSON.stringify(result, null, 2));
         }
         else {
-            console.log(pc.bold("\nLifecycle Analysis\n") +
-                pc.dim(`Early: ${String(result.summary.early)} | Middle: ${String(result.summary.middle)} | Late: ${String(result.summary.late)} | Terminal: ${String(result.summary.terminal)} | Unknown: ${String(result.summary.unknown)}`) +
-                "\n");
+            const { early, middle, late, terminal, unknown } = result.summary;
+            const summary = pc.dim(`Early: ${String(early)} | Middle: ${String(middle)} | Late: ${String(late)} | Terminal: ${String(terminal)} | Unknown: ${String(unknown)}`);
+            console.log(pc.bold("\nLifecycle Analysis\n") + summary + "\n");
             for (const n of result.nodes)
                 printLifecycleNode(n);
         }
@@ -149,9 +162,10 @@ const impactSubcommand = {
                 ? ` [depth: ${String(args.maxDepth)}]`
                 : "";
             const filterLabel = args.filter ? ` [filter: ${args.filter}]` : "";
-            console.log(pc.bold(`\nImpact Analysis from ${args.id}${directionLabel}${depthLabel}${filterLabel}\n`) +
-                pc.dim(`Direct: ${String(result.summary.direct)} | Transitive: ${String(result.summary.transitive)} | Potential: ${String(result.summary.potential)} | Total: ${String(result.summary.total)}`) +
-                "\n");
+            const title = `\nImpact Analysis from ${args.id}${directionLabel}${depthLabel}${filterLabel}\n`;
+            const { direct, transitive, potential, total } = result.summary;
+            const summary = pc.dim(`Direct: ${String(direct)} | Transitive: ${String(transitive)} | Potential: ${String(potential)} | Total: ${String(total)}`);
+            console.log(pc.bold(title) + summary + "\n");
             if (result.impactedNodes.length === 0) {
                 console.log(pc.dim("No impacted nodes found"));
             }
@@ -175,9 +189,9 @@ const derivedSubcommand = {
             console.log(JSON.stringify(result, null, 2));
         }
         else {
-            console.log(pc.bold("\nDerived Relationships\n") +
-                pc.dim(`Transitive: ${String(result.summary.transitive)} | Composite: ${String(result.summary.composite)} | Inverse: ${String(result.summary.inverse)} | Total: ${String(result.summary.total)}`) +
-                "\n");
+            const { transitive, composite, inverse, total } = result.summary;
+            const summary = pc.dim(`Transitive: ${String(transitive)} | Composite: ${String(composite)} | Inverse: ${String(inverse)} | Total: ${String(total)}`);
+            console.log(pc.bold("\nDerived Relationships\n") + summary + "\n");
             if (result.derivedRelationships.length === 0) {
                 console.log(pc.dim("No derived relationships found"));
             }
@@ -198,18 +212,23 @@ const allSubcommand = {
         // Completeness
         console.log(pc.bold("\n=== Completeness ===\n"));
         const completeness = inferCompletenessOp({ doc });
-        console.log(pc.dim(`Average score: ${(completeness.averageScore * 100).toFixed(1)}% | `) +
-            pc.green(`${String(completeness.completeNodes)} complete`) +
+        const completeScore = (completeness.averageScore * 100).toFixed(1);
+        const completeText = pc.green(`${String(completeness.completeNodes)} complete`);
+        const incompleteText = pc.red(`${String(completeness.incompleteNodes)} incomplete`);
+        console.log(pc.dim(`Average score: ${completeScore}% | `) +
+            completeText +
             pc.dim(" | ") +
-            pc.red(`${String(completeness.incompleteNodes)} incomplete`));
+            incompleteText);
         // Lifecycle
         console.log(pc.bold("\n=== Lifecycle ===\n"));
         const lifecycle = inferLifecycleOp({ doc });
-        console.log(pc.dim(`Early: ${String(lifecycle.summary.early)} | Middle: ${String(lifecycle.summary.middle)} | Late: ${String(lifecycle.summary.late)} | Terminal: ${String(lifecycle.summary.terminal)} | Unknown: ${String(lifecycle.summary.unknown)}`));
+        const { early, middle, late, terminal, unknown } = lifecycle.summary;
+        console.log(pc.dim(`Early: ${String(early)} | Middle: ${String(middle)} | Late: ${String(late)} | Terminal: ${String(terminal)} | Unknown: ${String(unknown)}`));
         // Derived
         console.log(pc.bold("\n=== Derived Relationships ===\n"));
         const derived = inferDerivedOp({ doc });
-        console.log(pc.dim(`Transitive: ${String(derived.summary.transitive)} | Composite: ${String(derived.summary.composite)} | Inverse: ${String(derived.summary.inverse)} | Total: ${String(derived.summary.total)}`));
+        const { transitive, composite, inverse, total } = derived.summary;
+        console.log(pc.dim(`Transitive: ${String(transitive)} | Composite: ${String(composite)} | Inverse: ${String(inverse)} | Total: ${String(total)}`));
         if (opts.json) {
             console.log(JSON.stringify({
                 completeness,

package/dist/src/cli/commands/query.js

@@ -7,43 +7,41 @@ import { NodeType, NodeStatus } from "../../schema.js";
 // ---------------------------------------------------------------------------
 // Presentation helpers
 // ---------------------------------------------------------------------------
-function printNode(r, verbose) {
-    if (verbose) {
-        console.log(`${pc.cyan(r.id)} — ${pc.bold(r.name)}`);
-        console.log(`  ${pc.dim("Type")}: ${r.type}`);
-        if (r.status)
-            console.log(`  ${pc.dim("Status")}: ${pc.yellow(r.status)}`);
-        if (r.description)
-            console.log(`  ${pc.dim("Description")}: ${textToString(r.description)}`);
-        if (r.context)
-            console.log(`  ${pc.dim("Context")}: ${textToString(r.context)}`);
-        if (r.rationale)
-            console.log(`  ${pc.dim("Rationale")}: ${textToString(r.rationale)}`);
-        if (r.selected)
-            console.log(`  ${pc.dim("Selected")}: ${r.selected}`);
-        if (r.options) {
-            console.log(`  ${pc.dim("Options")}:`);
-            for (const o of r.options)
-                console.log(`    ${o.id}: ${textToString(o.description)}`);
-        }
-        if (r.scope)
-            console.log(`  ${pc.dim("Scope")}: ${r.scope.join(", ")}`);
-        if (r.lifecycle) {
-            const states = Object.entries(r.lifecycle)
-                .map(([k, v]) => `${k}=${String(v)}`)
-                .join(", ");
-            console.log(`  ${pc.dim("Lifecycle")}: ${states}`);
-        }
-        if (r.includes)
-            console.log(`  ${pc.dim("Includes")}: ${r.includes.join(", ")}`);
-        console.log("");
+function printNodeCompact(r) {
+    const desc = r.description
+        ? " — " + textToString(r.description).slice(0, 60)
+        : "";
+    console.log(`${pc.cyan(r.id.padEnd(12))} ${pc.dim(r.type.padEnd(16))} ${pc.bold(r.name)}${desc}`);
+}
+function printNodeVerbose(r) {
+    console.log(`${pc.cyan(r.id)} — ${pc.bold(r.name)}`);
+    console.log(`  ${pc.dim("Type")}: ${r.type}`);
+    if (r.status)
+        console.log(`  ${pc.dim("Status")}: ${pc.yellow(r.status)}`);
+    if (r.description)
+        console.log(`  ${pc.dim("Description")}: ${textToString(r.description)}`);
+    if (r.context)
+        console.log(`  ${pc.dim("Context")}: ${textToString(r.context)}`);
+    if (r.rationale)
+        console.log(`  ${pc.dim("Rationale")}: ${textToString(r.rationale)}`);
+    if (r.selected)
+        console.log(`  ${pc.dim("Selected")}: ${r.selected}`);
+    if (r.options) {
+        console.log(`  ${pc.dim("Options")}:`);
+        for (const o of r.options)
+            console.log(`    ${o.id}: ${textToString(o.description)}`);
     }
-    else {
-        const desc = r.description
-            ? " — " + textToString(r.description).slice(0, 60)
-            : "";
-        console.log(`${pc.cyan(r.id.padEnd(12))} ${pc.dim(r.type.padEnd(16))} ${pc.bold(r.name)}${desc}`);
+    if (r.scope)
+        console.log(`  ${pc.dim("Scope")}: ${r.scope.join(", ")}`);
+    if (r.lifecycle) {
+        const states = Object.entries(r.lifecycle)
+            .map(([k, v]) => `${k}=${String(v)}`)
+            .join(", ");
+        console.log(`  ${pc.dim("Lifecycle")}: ${states}`);
     }
+    if (r.includes)
+        console.log(`  ${pc.dim("Includes")}: ${r.includes.join(", ")}`);
+    console.log("");
 }
 function isTraceTreeNode(value) {
     if (typeof value !== "object" || value === null)
@@ -103,7 +101,7 @@ const nodesSubcommand = {
         }
         else {
             for (const n of nodes)
-                printNode(n, false);
+                printNodeCompact(n);
             console.log(`\n${String(nodes.length)} node(s)`);
         }
     },
@@ -127,7 +125,7 @@ const nodeSubcommand = {
             console.log(JSON.stringify(result.node, null, 2));
         }
         else {
-            printNode(result.node, true);
+            printNodeVerbose(result.node);
             if (result.outgoing.length > 0) {
                 console.log(`${pc.dim("Outgoing relationships")}:`);
                 for (const r of result.outgoing)

package/dist/src/cli/commands/speckit.js

@@ -18,6 +18,82 @@ function detectFormat(outputPath) {
     }
     return "json"; // default
 }
+/**
+ * Validate that both paths exist, exits with error if not.
+ * @param inputPath - Path to SysProM document
+ * @param specKitDir - Path to Spec-Kit directory
+ * @example
+ * ```ts
+ * validatePaths(inputPath, specKitDir);
+ * ```
+ */
+function validatePaths(inputPath, specKitDir) {
+    if (!existsSync(inputPath)) {
+        console.error(`Error: Input file does not exist: ${inputPath}`);
+        process.exit(1);
+    }
+    if (!existsSync(specKitDir)) {
+        console.error(`Error: Spec-Kit directory does not exist: ${specKitDir}`);
+        process.exit(1);
+    }
+}
+/**
+ * Search up to 5 parent directories for Spec-Kit constitution file.
+ * @param specKitDir - Path to Spec-Kit directory to start search from
+ * @returns Path to constitution file if found, undefined otherwise
+ * @example
+ * ```ts
+ * const path = findConstitutionPath(specKitDir);
+ * ```
+ */
+function findConstitutionPath(specKitDir) {
+    let searchDir = dirname(specKitDir);
+    for (let i = 0; i < 5; i++) {
+        const project = detectSpecKitProject(searchDir);
+        if (project.constitutionPath)
+            return project.constitutionPath;
+        const parent = dirname(searchDir);
+        if (parent === searchDir)
+            break;
+        searchDir = parent;
+    }
+    return undefined;
+}
+/**
+ * Print diff results in human-readable format.
+ * @param diff - The diff structure containing added, modified, and removed nodes
+ * @example
+ * ```ts
+ * printDiffResults(diff);
+ * ```
+ */
+function printDiffResults(diff) {
+    console.log(`Diff between SysProM document and Spec-Kit directory:`);
+    if (diff.added.length === 0 &&
+        diff.modified.length === 0 &&
+        diff.removed.length === 0) {
+        console.log(`  (no changes)`);
+        return;
+    }
+    if (diff.added.length > 0) {
+        console.log(`  Added: ${String(diff.added.length)} node(s)`);
+        for (const node of diff.added) {
+            console.log(`    - ${node.id}: ${node.name}`);
+        }
+    }
+    if (diff.modified.length > 0) {
+        console.log(`  Modified: ${String(diff.modified.length)} node(s)`);
+        for (const { old } of diff.modified) {
+            console.log(`    - ${old.id}: ${old.name}`);
+        }
+    }
+    if (diff.removed.length > 0) {
+        console.log(`  Removed: ${String(diff.removed.length)} node(s)`);
+        for (const node of diff.removed) {
+            console.log(`    - ${node.id}: ${node.name}`);
+        }
+    }
+}
 function compareDocuments(oldDoc, newDoc) {
     const oldNodes = new Map(oldDoc.nodes.map((n) => [n.id, n]));
     const newNodes = new Map(newDoc.nodes.map((n) => [n.id, n]));
@@ -134,32 +210,10 @@ const syncSubcommand = {
     action(_args, opts) {
         const inputPath = resolve(opts.input);
         const specKitDir = resolve(opts.speckitDir);
-        if (!existsSync(inputPath)) {
-            console.error(`Error: Input file does not exist: ${inputPath}`);
-            process.exit(1);
-        }
-        if (!existsSync(specKitDir)) {
-            console.error(`Error: Spec-Kit directory does not exist: ${specKitDir}`);
-            process.exit(1);
-        }
-        // Determine the prefix: use flag if provided, otherwise use directory name
+        validatePaths(inputPath, specKitDir);
         const idPrefix = opts.prefix ?? specKitDir.split("/").pop() ?? "FEAT";
-        // Load SysProM document
         const { doc: syspromDoc, format } = loadDocument(inputPath);
-        // Find constitution file
-        let constitutionPath;
-        let searchDir = dirname(specKitDir);
-        for (let i = 0; i < 5; i++) {
-            const project = detectSpecKitProject(searchDir);
-            if (project.constitutionPath) {
-                constitutionPath = project.constitutionPath;
-                break;
-            }
-            const parent = dirname(searchDir);
-            if (parent === searchDir)
-                break;
-            searchDir = parent;
-        }
+        const constitutionPath = findConstitutionPath(specKitDir);
         // Parse Spec-Kit feature
         const specKitDoc = parseSpecKitFeature(specKitDir, idPrefix, constitutionPath);
         // Compare documents
@@ -232,63 +286,13 @@ const diffSubcommand = {
     action(_args, opts) {
         const inputPath = resolve(opts.input);
         const specKitDir = resolve(opts.speckitDir);
-        if (!existsSync(inputPath)) {
-            console.error(`Error: Input file does not exist: ${inputPath}`);
-            process.exit(1);
-        }
-        if (!existsSync(specKitDir)) {
-            console.error(`Error: Spec-Kit directory does not exist: ${specKitDir}`);
-            process.exit(1);
-        }
-        // Determine the prefix: use flag if provided, otherwise use directory name
+        validatePaths(inputPath, specKitDir);
         const idPrefix = opts.prefix ?? specKitDir.split("/").pop() ?? "FEAT";
-        // Load SysProM document
         const { doc: syspromDoc } = loadDocument(inputPath);
-        // Find constitution file
-        let constitutionPath;
-        let searchDir = dirname(specKitDir);
-        for (let i = 0; i < 5; i++) {
-            const project = detectSpecKitProject(searchDir);
-            if (project.constitutionPath) {
-                constitutionPath = project.constitutionPath;
-                break;
-            }
-            const parent = dirname(searchDir);
-            if (parent === searchDir)
-                break;
-            searchDir = parent;
-        }
-        // Parse Spec-Kit feature
+        const constitutionPath = findConstitutionPath(specKitDir);
         const specKitDoc = parseSpecKitFeature(specKitDir, idPrefix, constitutionPath);
-        // Compare documents
         const diff = compareDocuments(syspromDoc, specKitDoc);
-        // Print what would change (read-only)
-        console.log(`Diff between SysProM document and Spec-Kit directory:`);
-        if (diff.added.length === 0 &&
-            diff.modified.length === 0 &&
-            diff.removed.length === 0) {
-            console.log(`  (no changes)`);
-        }
-        else {
-            if (diff.added.length > 0) {
-                console.log(`  Added: ${String(diff.added.length)} node(s)`);
-                for (const node of diff.added) {
-                    console.log(`    - ${node.id}: ${node.name}`);
-                }
-            }
-            if (diff.modified.length > 0) {
-                console.log(`  Modified: ${String(diff.modified.length)} node(s)`);
-                for (const { old } of diff.modified) {
-                    console.log(`    - ${old.id}: ${old.name}`);
-                }
-            }
-            if (diff.removed.length > 0) {
-                console.log(`  Removed: ${String(diff.removed.length)} node(s)`);
-                for (const node of diff.removed) {
-                    console.log(`    - ${node.id}: ${node.name}`);
-                }
-            }
-        }
+        printDiffResults(diff);
     },
 };
 // ============================================================================

package/dist/src/cli/commands/stats.js

@@ -12,13 +12,13 @@ export const statsCommand = {
         console.log(`${pc.bold("SysProM Document")}: ${s.title}`);
         console.log("");
         console.log(pc.bold("Nodes by type:"));
-        for (const [type, count] of Object.entries(s.nodesByType).sort()) {
+        for (const [type, count] of Object.entries(s.nodesByType).sort(([a], [b]) => a.localeCompare(b))) {
             console.log(`  ${type.padEnd(20)} ${pc.cyan(String(count))}`);
         }
         console.log(`  ${"TOTAL".padEnd(20)} ${pc.cyan(String(s.totalNodes))}`);
         console.log("");
         console.log(pc.bold("Relationships by type:"));
-        for (const [type, count] of Object.entries(s.relationshipsByType).sort()) {
+        for (const [type, count] of Object.entries(s.relationshipsByType).sort(([a], [b]) => a.localeCompare(b))) {
             console.log(`  ${type.padEnd(20)} ${pc.cyan(String(count))}`);
         }
         console.log(`  ${"TOTAL".padEnd(20)} ${pc.cyan(String(s.totalRelationships))}`);
@@ -30,14 +30,14 @@ export const statsCommand = {
         if (Object.keys(s.decisionLifecycle).length > 0) {
             console.log("");
             console.log(pc.bold("Decision lifecycle:"));
-            for (const [state, count] of Object.entries(s.decisionLifecycle).sort()) {
+            for (const [state, count] of Object.entries(s.decisionLifecycle).sort(([a], [b]) => a.localeCompare(b))) {
                 console.log(`  ${state.padEnd(20)} ${pc.cyan(String(count))}`);
             }
         }
         if (Object.keys(s.changeLifecycle).length > 0) {
             console.log("");
             console.log(pc.bold("Change lifecycle:"));
-            for (const [state, count] of Object.entries(s.changeLifecycle).sort()) {
+            for (const [state, count] of Object.entries(s.changeLifecycle).sort(([a], [b]) => a.localeCompare(b))) {
                 console.log(`  ${state.padEnd(20)} ${pc.cyan(String(count))}`);
             }
         }

package/dist/src/cli/commands/update.js

@@ -6,21 +6,44 @@ import { mutationOpts, loadDoc, persistDoc } from "../shared.js";
 // CLI helper functions
 // ---------------------------------------------------------------------------
 function parseLifecycleValue(rawVal) {
-    if (rawVal === "true") {
+    if (rawVal === "true")
         return true;
-    }
-    if (rawVal === "false") {
+    if (rawVal === "false")
         return false;
-    }
-    if (/^\d{4}-\d{2}-\d{2}/.test(rawVal)) {
-        return rawVal; // ISO date string
-    }
+    if (/^\d{4}-\d{2}-\d{2}/.test(rawVal))
+        return rawVal;
     return rawVal;
 }
 function parseMetaValue(val) {
     const numVal = Number(val);
     return Number.isFinite(numVal) && val === String(numVal) ? numVal : val;
 }
+/**
+ * Parse lifecycle field updates from key=value format.
+ * @param nodeLifecycle - Optional existing lifecycle object from the node
+ * @param lifecycleArgs - Array of key=value strings to parse
+ * @returns Lifecycle object with parsed values, or null if no args
+ * @example
+ * ```ts
+ * const lifecycle = parseLifecycleFields(node.lifecycle, ["created=2026-01-01"]);
+ * ```
+ */
+function parseLifecycleFields(nodeLifecycle, lifecycleArgs) {
+    if (!lifecycleArgs.length)
+        return null;
+    const lifecycle = { ...nodeLifecycle };
+    for (const kv of lifecycleArgs) {
+        const eqIdx = kv.indexOf("=");
+        if (eqIdx < 0) {
+            console.error(`Invalid --lifecycle format: ${kv} (expected key=value)`);
+            process.exit(1);
+        }
+        const key = kv.slice(0, eqIdx);
+        const rawVal = kv.slice(eqIdx + 1);
+        lifecycle[key] = parseLifecycleValue(rawVal);
+    }
+    return lifecycle;
+}
 // ---------------------------------------------------------------------------
 // Arg/opt schemas
 // ---------------------------------------------------------------------------
@@ -80,19 +103,9 @@ const nodeSubcommand = {
             fields.context = opts.context;
         if (opts.rationale !== undefined)
             fields.rationale = opts.rationale;
-        if (opts.lifecycle && opts.lifecycle.length > 0) {
-            const lifecycle = { ...node.lifecycle };
-            for (const kv of opts.lifecycle) {
-                const eqIdx = kv.indexOf("=");
-                if (eqIdx < 0) {
-                    console.error(`Invalid --lifecycle format: ${kv} (expected key=value)`);
-                    process.exit(1);
-                }
-                const key = kv.slice(0, eqIdx);
-                const rawVal = kv.slice(eqIdx + 1);
-                lifecycle[key] = parseLifecycleValue(rawVal);
-            }
-            fields.lifecycle = lifecycle;
+        const lifecycleFields = parseLifecycleFields(node.lifecycle, opts.lifecycle ?? []);
+        if (lifecycleFields) {
+            fields.lifecycle = lifecycleFields;
         }
         if (Object.keys(fields).length === 0) {
             console.error("No fields specified to update.");

package/dist/src/io.js

@@ -12,6 +12,22 @@ function detectFormat(input) {
         return "json";
     return "single-md";
 }
+/**
+ * Wrap an error with a descriptive prefix and attach the original as cause.
+ * @param prefix - The error prefix (e.g., "Failed to parse JSON")
+ * @param error - The caught error
+ * @example
+ * ```ts
+ * try {
+ *   const data = JSON.parse(content);
+ * } catch (error) {
+ *   wrapError("Failed to parse JSON", error);
+ * }
+ * ```
+ */
+function wrapError(prefix, error) {
+    throw new Error(`${prefix}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+}
 /**
  * Load a SysProM document from a file (JSON or Markdown).
  * @param input - File path or directory to load from.
@@ -23,25 +39,60 @@ function detectFormat(input) {
  */
 export function loadDocument(input) {
     const path = resolve(input);
+    // Validate file/directory exists
+    try {
+        statSync(path);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            wrapError(`Document not found at ${path}. Create one first with init-document`, error);
+        }
+        throw error;
+    }
     const format = detectFormat(path);
     let doc;
     switch (format) {
         case "json": {
-            const raw = JSON.parse(readFileSync(path, "utf8"));
-            const result = SysProMDocument.safeParse(raw);
-            if (!result.success) {
-                throw new Error(`Invalid SysProM document:\n${result.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n")}`);
+            try {
+                const content = readFileSync(path, "utf8");
+                let raw;
+                try {
+                    raw = JSON.parse(content);
+                }
+                catch (error) {
+                    wrapError("Failed to parse JSON", error);
+                }
+                const result = SysProMDocument.safeParse(raw);
+                if (!result.success) {
+                    const issues = result.error.issues
+                        .map((i) => `  ${i.path.join(".")}: ${i.message}`)
+                        .join("\n");
+                    throw new Error(`Invalid SysProM document:\n${issues}`);
+                }
+                doc = result.data;
+            }
+            catch (error) {
+                wrapError("Failed to load JSON document", error);
             }
-            doc = result.data;
             break;
         }
         case "single-md": {
-            const content = readFileSync(path, "utf8");
-            doc = markdownSingleToJson(content);
+            try {
+                const content = readFileSync(path, "utf8");
+                doc = markdownSingleToJson(content);
+            }
+            catch (error) {
+                wrapError("Failed to load Markdown document", error);
+            }
             break;
         }
         case "multi-md": {
-            doc = markdownMultiDocToJson(path);
+            try {
+                doc = markdownMultiDocToJson(path);
+            }
+            catch (error) {
+                wrapError("Failed to load Markdown documents", error);
+            }
             break;
         }
     }

package/dist/src/mcp/server.js

@@ -5,11 +5,76 @@ import * as z from "zod";
 import { loadDocument, saveDocument } from "../io.js";
 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.
+ * @param prefix - The error prefix (e.g., "Failed to add node")
+ * @param error - The caught error
+ * @example
+ * ```ts
+ * try {
+ *   someOperation();
+ * } catch (error) {
+ *   wrapError("Failed to do X", error);
+ * }
+ * ```
+ */
+function wrapError(prefix, error) {
+    throw new Error(`${prefix}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+}
 // Create MCP server instance
 const server = new McpServer({
     name: "sysprom-mcp",
     version: "1.0.0",
 });
+// Register init-document tool
+server.registerTool("init-document", {
+    description: "Initialise a new SysProM document with metadata and empty structure",
+    inputSchema: z.object({
+        path: z
+            .string()
+            .describe("Output path for the document (must end in .json)"),
+        title: z.string().describe("Document title"),
+        description: z.string().optional().describe("Document description"),
+        scope: z.string().optional().describe("Document scope"),
+    }),
+}, ({ path, title, description, scope }) => {
+    try {
+        const now = new Date().toISOString().split("T")[0];
+        const doc = {
+            $schema: "https://sysprom.org/schema.json",
+            metadata: {
+                title,
+                ...(description && { description }),
+                ...(scope && { scope }),
+                version: "1.0.0",
+                created: now,
+            },
+            nodes: [],
+            relationships: [],
+        };
+        try {
+            saveDocument(doc, "json", path);
+        }
+        catch (error) {
+            wrapError("Failed to save document", error);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: "Document initialised",
+                        path,
+                        title,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        wrapError("init-document", error);
+    }
+});
 // Register validate tool
 server.registerTool("validate", {
     description: "Validate a SysProM document and return any validation issues",
@@ -145,34 +210,50 @@ server.registerTool("add-node", {
         description: z.string().optional().describe("Node description"),
     }),
 }, ({ path, type, id, name, description }) => {
-    const loaded = loadDocument(path);
-    const nodeType = NodeType.safeParse(type);
-    if (!nodeType.success) {
-        throw new Error(`Invalid node type: "${type}". Valid types: ${NodeType.options.join(", ")}`);
-    }
-    const nodeId = id ?? nextIdOp({ doc: loaded.doc, type: nodeType.data });
-    const updated = addNodeOp({
-        doc: loaded.doc,
-        node: {
-            id: nodeId,
-            type: nodeType.data,
-            name,
-            ...(description && { description }),
-        },
-    });
-    saveDocument(updated, loaded.format, loaded.path);
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({
-                    message: "Node added",
+    try {
+        const loaded = loadDocument(path);
+        const nodeType = NodeType.safeParse(type);
+        if (!nodeType.success) {
+            throw new Error(`Invalid node type: "${type}". Valid types: ${NodeType.options.join(", ")}`);
+        }
+        const nodeId = id ?? nextIdOp({ doc: loaded.doc, type: nodeType.data });
+        let updated;
+        try {
+            updated = addNodeOp({
+                doc: loaded.doc,
+                node: {
                     id: nodeId,
-                    nodeCount: updated.nodes.length,
-                }, null, 2),
-            },
-        ],
-    };
+                    type: nodeType.data,
+                    name,
+                    ...(description && { description }),
+                },
+            });
+        }
+        catch (error) {
+            wrapError("Failed to add node", error);
+        }
+        try {
+            saveDocument(updated, loaded.format, loaded.path);
+        }
+        catch (error) {
+            throw new Error(`Failed to save document: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: "Node added",
+                        id: nodeId,
+                        nodeCount: updated.nodes.length,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        wrapError("add-node", error);
+    }
 });
 // Register remove-node tool
 server.registerTool("remove-node", {
@@ -182,21 +263,37 @@ server.registerTool("remove-node", {
         id: z.string().describe("Node ID"),
     }),
 }, ({ path, id }) => {
-    const loaded = loadDocument(path);
-    const result = removeNodeOp({ doc: loaded.doc, id });
-    saveDocument(result.doc, loaded.format, loaded.path);
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({
-                    message: `Node ${id} removed`,
-                    nodeCount: result.doc.nodes.length,
-                    warnings: result.warnings,
-                }, null, 2),
-            },
-        ],
-    };
+    try {
+        const loaded = loadDocument(path);
+        let result;
+        try {
+            result = removeNodeOp({ doc: loaded.doc, id });
+        }
+        catch (error) {
+            wrapError("Failed to remove node", error);
+        }
+        try {
+            saveDocument(result.doc, loaded.format, loaded.path);
+        }
+        catch (error) {
+            throw new Error(`Failed to save document: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: `Node ${id} removed`,
+                        nodeCount: result.doc.nodes.length,
+                        warnings: result.warnings,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        wrapError("remove-node", error);
+    }
 });
 // Register update-node tool
 server.registerTool("update-node", {
@@ -207,11 +304,10 @@ server.registerTool("update-node", {
         fields: z.record(z.string(), z.unknown()).describe("Fields to update"),
     }),
 }, ({ path, id, fields }) => {
-    const loaded = loadDocument(path);
-    // Validate fields are valid node property updates
-    const validFields = Object.entries(fields).reduce((acc, [key, value]) => {
-        // Allow common node fields; unknown fields are silently ignored
-        if ([
+    try {
+        const loaded = loadDocument(path);
+        // Track which fields are valid
+        const allowedFields = [
             "name",
             "description",
             "status",
@@ -227,26 +323,55 @@ server.registerTool("update-node", {
             "input",
             "output",
             "external_references",
-        ].includes(key)) {
-            acc[key] = value;
+        ];
+        const droppedFields = [];
+        const validFields = Object.entries(fields).reduce((acc, [key, value]) => {
+            if (allowedFields.includes(key)) {
+                acc[key] = value;
+            }
+            else {
+                droppedFields.push(key);
+            }
+            return acc;
+        }, {});
+        let updated;
+        try {
+            updated = updateNodeOp({
+                doc: loaded.doc,
+                id,
+                fields: validFields,
+            });
         }
-        return acc;
-    }, {});
-    const updated = updateNodeOp({
-        doc: loaded.doc,
-        id,
-        fields: validFields,
-    });
-    saveDocument(updated, loaded.format, loaded.path);
-    const node = updated.nodes.find((n) => n.id === id);
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({ message: "Node updated", node }, null, 2),
-            },
-        ],
-    };
+        catch (error) {
+            wrapError("Failed to update node", error);
+        }
+        try {
+            saveDocument(updated, loaded.format, loaded.path);
+        }
+        catch (error) {
+            throw new Error(`Failed to save document: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        const node = updated.nodes.find((n) => n.id === id);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: "Node updated",
+                        node,
+                        ...(droppedFields.length > 0 && {
+                            warnings: [
+                                `These fields are not updateable and were ignored: ${droppedFields.join(", ")}`,
+                            ],
+                        }),
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        wrapError("update-node", error);
+    }
 });
 // Register add-relationship tool
 server.registerTool("add-relationship", {
@@ -258,31 +383,47 @@ server.registerTool("add-relationship", {
         type: z.string().describe("Relationship type"),
     }),
 }, ({ path, from, to, type }) => {
-    const loaded = loadDocument(path);
-    const relType = RelationshipType.safeParse(type);
-    if (!relType.success) {
-        throw new Error(`Invalid relationship type: "${type}". Valid types: ${RelationshipType.options.join(", ")}`);
+    try {
+        const loaded = loadDocument(path);
+        const relType = RelationshipType.safeParse(type);
+        if (!relType.success) {
+            throw new Error(`Invalid relationship type: "${type}". Valid types: ${RelationshipType.options.join(", ")}`);
+        }
+        let updated;
+        try {
+            updated = addRelationshipOp({
+                doc: loaded.doc,
+                rel: {
+                    from,
+                    to,
+                    type: relType.data,
+                },
+            });
+        }
+        catch (error) {
+            wrapError("Failed to add relationship", error);
+        }
+        try {
+            saveDocument(updated, loaded.format, loaded.path);
+        }
+        catch (error) {
+            throw new Error(`Failed to save document: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: "Relationship added",
+                        relationshipCount: (updated.relationships ?? []).length,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        wrapError("add-relationship", error);
     }
-    const updated = addRelationshipOp({
-        doc: loaded.doc,
-        rel: {
-            from,
-            to,
-            type: relType.data,
-        },
-    });
-    saveDocument(updated, loaded.format, loaded.path);
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({
-                    message: "Relationship added",
-                    relationshipCount: (updated.relationships ?? []).length,
-                }, null, 2),
-            },
-        ],
-    };
 });
 // Register remove-relationship tool
 server.registerTool("remove-relationship", {
@@ -294,29 +435,45 @@ server.registerTool("remove-relationship", {
         type: z.string().describe("Relationship type"),
     }),
 }, ({ path, from, to, type }) => {
-    const loaded = loadDocument(path);
-    const relType = RelationshipType.safeParse(type);
-    if (!relType.success) {
-        throw new Error(`Invalid relationship type: "${type}". Valid types: ${RelationshipType.options.join(", ")}`);
+    try {
+        const loaded = loadDocument(path);
+        const relType = RelationshipType.safeParse(type);
+        if (!relType.success) {
+            throw new Error(`Invalid relationship type: "${type}". Valid types: ${RelationshipType.options.join(", ")}`);
+        }
+        let result;
+        try {
+            result = removeRelationshipOp({
+                doc: loaded.doc,
+                from,
+                to,
+                type: relType.data,
+            });
+        }
+        catch (error) {
+            wrapError("Failed to remove relationship", error);
+        }
+        try {
+            saveDocument(result.doc, loaded.format, loaded.path);
+        }
+        catch (error) {
+            throw new Error(`Failed to save document: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: "Relationship removed",
+                        relationshipCount: (result.doc.relationships ?? []).length,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        wrapError("remove-relationship", error);
     }
-    const result = removeRelationshipOp({
-        doc: loaded.doc,
-        from,
-        to,
-        type: relType.data,
-    });
-    saveDocument(result.doc, loaded.format, loaded.path);
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({
-                    message: "Relationship removed",
-                    relationshipCount: (result.doc.relationships ?? []).length,
-                }, null, 2),
-            },
-        ],
-    };
 });
 // Register infer-completeness tool
 server.registerTool("infer-completeness", {

package/package.json

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