sysprom 1.16.1 → 1.18.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
@@ -21,16 +23,60 @@ Both `sysprom` and `spm` are available as commands — use `sysprom` for new pro
 
 ## CLI
 
-```sh
+````sh
 # Convert between formats
 sysprom json2md --input .SysProM.json --output ./.SysProM
 sysprom md2json --input ./.SysProM --output output.SysProM.json
 
+# Diagram and label options
+
+The `graph` and `json2md` commands support options to control diagram layout and node label style used when generating Mermaid/DOT output.
+
+Examples:
+
+```sh
+# Generate a Mermaid graph with friendly labels (default)
+sysprom graph --path .SysProM.json --format mermaid
+
+# Compact node labels (IDs only) instead of `ID: Name`
+sysprom graph --path .SysProM.json --format mermaid --label-mode compact
+
+# Embed diagrams when converting JSON → Markdown, using compact labels
+sysprom json2md --input .SysProM.json --output ./.SysProM --embed-diagrams --label-mode compact
+
+# Control layout direction for graph (LR, TD, RL, BT)
+sysprom graph --path .SysProM.json --format mermaid --layout LR
+````
+
+Notes:
+
+- `--label-mode friendly|compact` controls whether nodes show `ID: Name` (`friendly`) or just `ID` (`compact`).
+- `--layout LR|TD|RL|BT` controls graph direction. `json2md` uses sensible per-diagram defaults (relationship/refinement/decision diagrams default to `TD`, dependency diagrams default to `LR`) but you can override when calling `graph` directly.
+- `--label-mode friendly|compact` controls whether nodes show `ID: Name` (`friendly`) or just `ID` (`compact`).
+- `--layout LR|TD|RL|BT` controls graph direction. `json2md` uses sensible per-diagram defaults (relationship/refinement/decision diagrams default to `TD`, dependency diagrams default to `LR`) but you can override when calling `graph` directly.
+- `json2md` supports per-diagram layout overrides to control each embedded diagram independently:
+  - `--relationship-layout LR|TD|RL|BT` — override the layout used for the Relationship Graph.
+  - `--refinement-layout LR|TD|RL|BT` — override the layout used for the Refinement Chain.
+  - `--decision-layout LR|TD|RL|BT` — override the layout used for the Decision Map.
+  - `--dependency-layout LR|TD|RL|BT` — override the layout used for the Dependency Graph.
+
+Examples:
+
+```sh
+# Embed diagrams in multi-doc output but make dependency graph top-to-bottom (TD)
+sysprom json2md --input .SysProM.json --output ./.SysProM --embed-diagrams --dependency-layout TD
+
+# Override relationship and refinement layouts independently
+sysprom json2md --input .SysProM.json --output ./.SysProM --embed-diagrams --relationship-layout LR --refinement-layout TD
+```
+
 # Validate and summarise (auto-detects .SysProM.json in current directory)
+
 sysprom validate
 sysprom stats
 
 # Query nodes and relationships
+
 sysprom query nodes --type decision
 sysprom query node D1
 sysprom query rels --from D1
@@ -39,27 +85,32 @@ sysprom query timeline
 sysprom query state-at 2026-03-22
 
 # Add nodes (ID auto-generated from type prefix if --id omitted)
+
 sysprom add invariant --name "New Rule" --description "Must hold"
 sysprom add decision --name "Choose X" \
-  --option "OPT-A:Use framework X" --option "OPT-B:Use framework Y" \
-  --selected OPT-A --rationale "Lower migration effort"
+ --option "OPT-A:Use framework X" --option "OPT-B:Use framework Y" \
+ --selected OPT-A --rationale "Lower migration effort"
 
 # Remove nodes
+
 sysprom remove INV23
 
 # Update nodes, relationships, and metadata
+
 sysprom update node D1 --status deprecated
 sysprom update add-rel D1 affects EL5
 sysprom update remove-rel D1 affects EL5
 sysprom update meta --fields version=2
 
 # Inference operations (deterministic graph analysis)
-sysprom infer completeness              # Score node completeness (0-1)
-sysprom infer lifecycle                 # Infer lifecycle phases
-sysprom infer impact I1                 # Trace impact from node
-sysprom infer derived                   # Compute transitive closure
-sysprom infer all                       # Run all analyses
-```
+
+sysprom infer completeness # Score node completeness (0-1)
+sysprom infer lifecycle # Infer lifecycle phases
+sysprom infer impact I1 # Trace impact from node
+sysprom infer derived # Compute transitive closure
+sysprom infer all # Run all analyses
+
+````
 
 All commands auto-detect the document — they search the current directory for `.SysProM.json`, `.SysProM.md`, or `.SysProM/` (in that priority order), then fall back to `.spm.json`, `.spm.md`, or `.spm/`. Use `--path` to specify an explicit path. Note: `spm` is an alias for `sysprom` for backwards compatibility.
 
@@ -80,7 +131,7 @@ Add the following to your MCP client's configuration (e.g. `.cursor/mcp.json`, `
     }
   }
 }
-```
+````
 
 Or via the CLI subcommand (equivalent):
 
@@ -90,23 +141,23 @@ sysprom mcp   # starts the MCP server on stdio
 
 ### Available Tools
 
-| Tool | Description |
-|------|-------------|
-| `validate` | Validate a SysProM document and return issues |
-| `stats` | Return document statistics |
-| `query-nodes` | Query nodes by type, status, or text |
-| `query-node` | Retrieve a single node by ID |
-| `query-relationships` | Query relationships by source, target, or type |
-| `trace` | Trace refinement chains from a node |
-| `add-node` | Add a new node to the document |
-| `remove-node` | Remove a node by ID |
-| `update-node` | Update fields on an existing node |
-| `add-relationship` | Add a relationship between nodes |
-| `remove-relationship` | Remove a relationship |
-| `infer-completeness` | Score node completeness (0-1) based on refinement relationships |
-| `infer-lifecycle` | Infer lifecycle phase from status and lifecycle fields |
-| `infer-impact` | Trace impact propagation from a starting node |
-| `infer-derived` | Compute transitive closure and inverse relationships |
+| Tool                  | Description                                                     |
+| --------------------- | --------------------------------------------------------------- |
+| `validate`            | Validate a SysProM document and return issues                   |
+| `stats`               | Return document statistics                                      |
+| `query-nodes`         | Query nodes by type, status, or text                            |
+| `query-node`          | Retrieve a single node by ID                                    |
+| `query-relationships` | Query relationships by source, target, or type                  |
+| `trace`               | Trace refinement chains from a node                             |
+| `add-node`            | Add a new node to the document                                  |
+| `remove-node`         | Remove a node by ID                                             |
+| `update-node`         | Update fields on an existing node                               |
+| `add-relationship`    | Add a relationship between nodes                                |
+| `remove-relationship` | Remove a relationship                                           |
+| `infer-completeness`  | Score node completeness (0-1) based on refinement relationships |
+| `infer-lifecycle`     | Infer lifecycle phase from status and lifecycle fields          |
+| `infer-impact`        | Trace impact propagation from a starting node                   |
+| `infer-derived`       | Compute transitive closure and inverse relationships            |
 
 All tools accept a `path` parameter to specify the SysProM document location.
 
@@ -114,50 +165,50 @@ All tools accept a `path` parameter to specify the SysProM document location.
 
 ```ts
 import {
-  // Schema and types
-  sysproMDocument,
-  node,
-  nodeType,
-  relationshipType,
-  type SysProMDocument,
-  type Node,
-  type Relationship,
-
-  // Conversion
-  jsonToMarkdown,
-  jsonToMarkdownSingle,
-  jsonToMarkdownMultiDoc,
-  markdownToJson,
-
-  // Validation and query
-  validate,
-  stats,
-  queryNodes,
-  queryNode,
-  queryRelationships,
-  traceFromNode,
-
-  // Mutation
-  addNode,
-  removeNode,
-  updateNode,
-  addRelationship,
-  removeRelationship,
-  updateMetadata,
-
-  // Inference
-  inferCompletenessOp,
-  inferLifecycleOp,
-  inferImpactOp,
-  inferDerivedOp,
-
-  // File I/O
-  loadDocument,
-  saveDocument,
-
-  // Utilities
-  canonicalise,
-  toJSONSchema,
+	// Schema and types
+	sysproMDocument,
+	node,
+	nodeType,
+	relationshipType,
+	type SysProMDocument,
+	type Node,
+	type Relationship,
+
+	// Conversion
+	jsonToMarkdown,
+	jsonToMarkdownSingle,
+	jsonToMarkdownMultiDoc,
+	markdownToJson,
+
+	// Validation and query
+	validate,
+	stats,
+	queryNodes,
+	queryNode,
+	queryRelationships,
+	traceFromNode,
+
+	// Mutation
+	addNode,
+	removeNode,
+	updateNode,
+	addRelationship,
+	removeRelationship,
+	updateMetadata,
+
+	// Inference
+	inferCompletenessOp,
+	inferLifecycleOp,
+	inferImpactOp,
+	inferDerivedOp,
+
+	// File I/O
+	loadDocument,
+	saveDocument,
+
+	// Utilities
+	canonicalise,
+	toJSONSchema,
 } from "sysprom";
 
 // Validate
@@ -170,12 +221,24 @@ const decisions = queryNodes(doc, { type: "decision" });
 const trace = traceFromNode(doc, "I1");
 
 // Mutate
-const updated = addNode(doc, { id: "INV23", type: "invariant", name: "New Rule" });
-const withRel = addRelationship(updated, { from: "D1", to: "INV23", type: "must_preserve" });
+const updated = addNode(doc, {
+	id: "INV23",
+	type: "invariant",
+	name: "New Rule",
+});
+const withRel = addRelationship(updated, {
+	from: "D1",
+	to: "INV23",
+	type: "must_preserve",
+});
 
 // Type guards
-if (sysproMDocument.is(data)) { /* data is SysProMDocument */ }
-if (node.is(thing)) { /* thing is Node */ }
+if (sysproMDocument.is(data)) {
+	/* data is SysProMDocument */
+}
+if (node.is(thing)) {
+	/* thing is Node */
+}
 ```
 
 ## What is SysProM?
@@ -321,21 +384,25 @@ When working on the SysProM repo itself, skills in `.claude/skills/` are auto-di
 ### Skills by Category
 
 **Node Creation (4 skills)**
+
 - `add-decision` — Create decision nodes with context, options, rationale, and invariant links
 - `add-change` — Create change nodes with scope, operations, and task tracking
 - `add-invariant` — Create invariant nodes representing system rules and constraints
 - `add-node` — Generic node creation for any SysProM type
 
 **Node Modification (3 skills)**
+
 - `update-node` — Modify node fields, status, lifecycle, context, or rationale
 - `remove-node` — Delete nodes with safety flags (hard delete, recursive, repair)
 - `rename-node` — Rename node IDs across all references
 
 **Relationships (2 skills)**
+
 - `add-relationship` — Create relationships between nodes with specific types
 - `remove-relationship` — Delete relationships
 
 **Query & Analysis (5 skills)**
+
 - `query-nodes` — Search nodes by type, status, text, or ID
 - `query-relationships` — Query relationships by source, target, or type
 - `trace-node` — Trace refinement chains through abstraction layers
@@ -343,26 +410,31 @@ When working on the SysProM repo itself, skills in `.claude/skills/` are auto-di
 - `stats` — Show document statistics and composition metrics
 
 **Visualisation (1 skill)**
+
 - `graph` — Generate Mermaid or DOT graphs with filtering
 
 **Format Conversion (4 skills)**
+
 - `init-document` — Create new SysProM documents with metadata
 - `json-to-markdown` — Convert JSON to Markdown format
 - `markdown-to-json` — Convert Markdown to JSON format
 - `sync-formats` — Bidirectional sync between JSON and Markdown
 
 **Spec-Kit Integration (4 skills)**
+
 - `speckit-import` — Import Spec-Kit features as SysProM nodes
 - `speckit-export` — Export SysProM nodes to Spec-Kit format
 - `speckit-sync` — Bidirectional sync with Spec-Kit specifications
 - `speckit-diff` — Show differences between SysProM and Spec-Kit
 
 **Task Management (3 skills)**
+
 - `task-list` — List tasks in a change node with progress
 - `task-add` — Add tasks to a change
 - `task-mark-done` — Mark tasks as complete
 
 **Plan Management (2 skills)**
+
 - `plan-init` — Initialise plans with phases and gates
 - `plan-status` — Show plan progress and phase gates
 

package/dist/schema.json

@@ -504,7 +504,8 @@
                             "selects",
                             "requires",
                             "disables",
-                            "influence"
+                            "influence",
+                            "justifies"
                         ],
                         "type": "string"
                     }

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/graph.d.ts

@@ -9,6 +9,21 @@ declare const optsSchema: z.ZodObject<{
         mermaid: "mermaid";
     }>>;
     type: z.ZodOptional<z.ZodString>;
+    nodeTypes: z.ZodOptional<z.ZodString>;
+    nodeIds: z.ZodOptional<z.ZodString>;
+    relTypes: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodEnum<{
+        TD: "TD";
+        BT: "BT";
+        RL: "RL";
+        LR: "LR";
+    }>>;
+    labelMode: z.ZodOptional<z.ZodEnum<{
+        friendly: "friendly";
+        compact: "compact";
+    }>>;
+    cluster: z.ZodOptional<z.ZodBoolean>;
+    connectedOnly: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const graphCommand: CommandDef<typeof noArgs, typeof optsSchema>;
 export {};

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

@@ -1,9 +1,41 @@
+/// <reference types="node" />
 import * as z from "zod";
 import { graphOp } from "../../operations/index.js";
 import { readOpts, loadDoc } from "../shared.js";
 const optsSchema = readOpts.extend({
     format: z.enum(["mermaid", "dot"]).optional().describe("Output format"),
-    type: z.string().optional().describe("Filter by relationship type"),
+    type: z
+        .string()
+        .optional()
+        .describe("Filter by relationship type (backward compatible)"),
+    nodeTypes: z
+        .string()
+        .optional()
+        .describe("Filter by node types (comma-separated)"),
+    nodeIds: z
+        .string()
+        .optional()
+        .describe("Filter by node IDs (comma-separated)"),
+    relTypes: z
+        .string()
+        .optional()
+        .describe("Filter by relationship types (comma-separated)"),
+    layout: z
+        .enum(["LR", "TD", "RL", "BT"])
+        .optional()
+        .describe("Graph layout direction"),
+    labelMode: z
+        .enum(["friendly", "compact"])
+        .optional()
+        .describe('Node label mode: "friendly" shows `id: name`, "compact" shows `id`'),
+    cluster: z
+        .boolean()
+        .optional()
+        .describe("Group nodes by category in subgraphs"),
+    connectedOnly: z
+        .boolean()
+        .optional()
+        .describe("Only show nodes that have relationships"),
 });
 export const graphCommand = {
     name: "graph",
@@ -13,15 +45,32 @@ export const graphCommand = {
     action(_args, opts) {
         try {
             const { doc } = loadDoc(opts.path);
+            const nodeTypes = opts.nodeTypes
+                ? opts.nodeTypes.split(",").map((s) => s.trim())
+                : undefined;
+            const nodeIds = opts.nodeIds
+                ? opts.nodeIds.split(",").map((s) => s.trim())
+                : undefined;
+            const relTypes = opts.relTypes
+                ? opts.relTypes.split(",").map((s) => s.trim())
+                : undefined;
             const output = graphOp({
                 doc,
                 format: opts.format ?? "mermaid",
                 typeFilter: opts.type,
+                nodeTypes,
+                nodeIds,
+                relTypes,
+                layout: opts.layout ?? "TD",
+                cluster: opts.cluster ?? true,
+                labelMode: opts.labelMode ?? "friendly",
+                connectedOnly: opts.connectedOnly ?? false,
             });
             console.log(output);
         }
         catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(message);
             process.exit(1);
         }
     },