sysprom 1.17.0 → 1.18.0

package/README.md

@@ -23,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
@@ -41,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.
 
@@ -82,7 +131,7 @@ Add the following to your MCP client's configuration (e.g. `.cursor/mcp.json`, `
     }
   }
 }
-```
+````
 
 Or via the CLI subcommand (equivalent):
 
@@ -92,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.
 
@@ -116,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
@@ -172,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?
@@ -323,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
@@ -345,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/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);
         }
     },

package/dist/src/cli/commands/init.d.ts

@@ -10,5 +10,5 @@ declare const optsSchema: z.ZodObject<{
         dir: "dir";
     }>>;
 }, z.core.$strict>;
-export declare const initCommand: CommandDef<z.ZodObject<z.ZodRawShape>, typeof optsSchema>;
+export declare const initCommand: CommandDef<z.ZodObject, typeof optsSchema>;
 export {};

package/dist/src/cli/commands/json2md.d.ts

@@ -4,6 +4,35 @@ declare const optsSchema: z.ZodObject<{
     input: z.ZodString;
     output: z.ZodString;
     singleFile: z.ZodOptional<z.ZodBoolean>;
+    embedDiagrams: z.ZodOptional<z.ZodBoolean>;
+    labelMode: z.ZodOptional<z.ZodEnum<{
+        friendly: "friendly";
+        compact: "compact";
+    }>>;
+    relationshipLayout: z.ZodOptional<z.ZodEnum<{
+        TD: "TD";
+        BT: "BT";
+        RL: "RL";
+        LR: "LR";
+    }>>;
+    refinementLayout: z.ZodOptional<z.ZodEnum<{
+        TD: "TD";
+        BT: "BT";
+        RL: "RL";
+        LR: "LR";
+    }>>;
+    decisionLayout: z.ZodOptional<z.ZodEnum<{
+        TD: "TD";
+        BT: "BT";
+        RL: "RL";
+        LR: "LR";
+    }>>;
+    dependencyLayout: z.ZodOptional<z.ZodEnum<{
+        TD: "TD";
+        BT: "BT";
+        RL: "RL";
+        LR: "LR";
+    }>>;
 }, z.core.$strict>;
-export declare const json2mdCommand: CommandDef<z.ZodObject<z.ZodRawShape>, typeof optsSchema>;
+export declare const json2mdCommand: CommandDef<z.ZodObject, typeof optsSchema>;
 export {};

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

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import * as z from "zod";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -12,6 +13,30 @@ const optsSchema = z
         .boolean()
         .optional()
         .describe("Force single-file output format"),
+    embedDiagrams: z
+        .boolean()
+        .optional()
+        .describe("Embed Mermaid diagrams in the output"),
+    labelMode: z
+        .enum(["friendly", "compact"])
+        .optional()
+        .describe("Node label mode for embedded diagrams"),
+    relationshipLayout: z
+        .enum(["LR", "TD", "RL", "BT"])
+        .optional()
+        .describe("Override layout for relationship diagrams"),
+    refinementLayout: z
+        .enum(["LR", "TD", "RL", "BT"])
+        .optional()
+        .describe("Override layout for refinement diagrams"),
+    decisionLayout: z
+        .enum(["LR", "TD", "RL", "BT"])
+        .optional()
+        .describe("Override layout for decision diagrams"),
+    dependencyLayout: z
+        .enum(["LR", "TD", "RL", "BT"])
+        .optional()
+        .describe("Override layout for dependency diagrams"),
 })
     .strict();
 export const json2mdCommand = {
@@ -23,6 +48,7 @@ export const json2mdCommand = {
         const inputPath = resolve(opts.input);
         const outputPath = resolve(opts.output);
         const raw = JSON.parse(readFileSync(inputPath, "utf8"));
+        // Use the attached type guard for clearer intent and narrower runtime checks
         if (!SysProMDocument.is(raw)) {
             const result = SysProMDocument.safeParse(raw);
             if (!result.success) {
@@ -36,7 +62,22 @@ export const json2mdCommand = {
         const form = opts.singleFile || outputPath.endsWith(".md")
             ? "single-file"
             : "multi-doc";
-        jsonToMarkdown(raw, outputPath, { form });
+        // Forward per-diagram layout overrides via environment-like flags.
+        // We accept flags on the command line for common diagram layouts but also
+        // preserve sensible per-diagram defaults in jsonToMarkdown when not set.
+        // For now we expose a single --label-mode flag and keep per-diagram layout
+        // defaults internal; a future enhancement could expose per-diagram
+        // flags such as --relationship-layout, --dependency-layout, etc.
+        jsonToMarkdown(raw, outputPath, {
+            form,
+            embedDiagrams: opts.embedDiagrams,
+            // forward labelMode for embedded diagrams (default friendly)
+            labelMode: opts.labelMode ?? "friendly",
+            relationshipLayout: opts.relationshipLayout,
+            refinementLayout: opts.refinementLayout,
+            decisionLayout: opts.decisionLayout,
+            dependencyLayout: opts.dependencyLayout,
+        });
         if (form === "single-file") {
             console.log(`Written to ${outputPath}`);
         }

package/dist/src/cli/commands/md2json.d.ts

@@ -4,5 +4,5 @@ declare const optsSchema: z.ZodObject<{
     input: z.ZodString;
     output: z.ZodString;
 }, z.core.$strict>;
-export declare const md2jsonCommand: CommandDef<z.ZodObject<z.ZodRawShape>, typeof optsSchema>;
+export declare const md2jsonCommand: CommandDef<z.ZodObject, typeof optsSchema>;
 export {};

package/dist/src/cli/commands/sync.d.ts

@@ -23,5 +23,5 @@ declare const syncOpts: z.ZodObject<{
     dryRun: z.ZodOptional<z.ZodBoolean>;
     report: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
-export declare const syncCommandDef: CommandDef<z.ZodObject<z.ZodRawShape>, typeof syncOpts>;
+export declare const syncCommandDef: CommandDef<z.ZodObject, typeof syncOpts>;
 export {};

package/dist/src/cli/define-command.d.ts

@@ -1,7 +1,7 @@
 import * as z from "zod";
 import { Command } from "commander";
 /** Definition of a CLI command — name, description, Zod schemas for args/opts, optional subcommands, and action handler. */
-export interface CommandDef<TArgs extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOpts extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> {
+export interface CommandDef<TArgs extends z.ZodObject = z.ZodObject, TOpts extends z.ZodObject = z.ZodObject> {
     name: string;
     description: string;
     args?: TArgs;