sysprom 1.6.0 → 1.7.1

package/dist/src/endpoint-types.d.ts

@@ -12,9 +12,13 @@ export declare const RELATIONSHIP_ENDPOINT_TYPES: Record<RelationshipType, {
 }>;
 /**
  * Check if a relationship type is valid for the given endpoint node types.
- * @param relType The relationship type
- * @param fromType The source node type
- * @param toType The target node type
+ * @param relType - The relationship type
+ * @param fromType - The source node type
+ * @param toType - The target node type
  * @returns true if the endpoint types are valid for this relationship
+ * @example
+ * ```ts
+ * isValidEndpointPair("refines", "intent", "concept") // true
+ * ```
  */
 export declare function isValidEndpointPair(relType: RelationshipType, fromType: NodeType, toType: NodeType): boolean;

package/dist/src/endpoint-types.js

@@ -288,16 +288,16 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
 };
 /**
  * Check if a relationship type is valid for the given endpoint node types.
- * @param relType The relationship type
- * @param fromType The source node type
- * @param toType The target node type
+ * @param relType - The relationship type
+ * @param fromType - The source node type
+ * @param toType - The target node type
  * @returns true if the endpoint types are valid for this relationship
+ * @example
+ * ```ts
+ * isValidEndpointPair("refines", "intent", "concept") // true
+ * ```
  */
 export function isValidEndpointPair(relType, fromType, toType) {
     const endpoints = RELATIONSHIP_ENDPOINT_TYPES[relType];
-    if (!endpoints) {
-        // Unknown relationship type — should be caught by schema validation
-        return false;
-    }
-    return (endpoints.from.includes(fromType) && endpoints.to.includes(toType));
+    return endpoints.from.includes(fromType) && endpoints.to.includes(toType);
 }

package/dist/src/mcp/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./server.js";

package/dist/src/mcp/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// @fileoverview MCP server entry point - runs the SysProM MCP server
+import "./server.js";

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/mcp/server.js

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as z from "zod";
+import { loadDocument } from "../io.js";
+import { RelationshipType } from "../schema.js";
+import { validateOp, statsOp, queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, nextIdOp, } from "../operations/index.js";
+// Create MCP server instance
+const server = new McpServer({
+    name: "sysprom-mcp",
+    version: "1.0.0",
+});
+// Register validate tool
+server.registerTool("validate", {
+    description: "Validate a SysProM document and return any validation issues",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+    }),
+}, ({ path }) => {
+    const { doc } = loadDocument(path);
+    const result = validateOp({ doc });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// Register stats tool
+server.registerTool("stats", {
+    description: "Get statistics about a SysProM document",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+    }),
+}, ({ path }) => {
+    const { doc } = loadDocument(path);
+    const result = statsOp({ doc });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// Register query-nodes tool
+server.registerTool("query-nodes", {
+    description: "Query nodes by type, status, or other criteria",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+        type: z.string().optional().describe("Filter by node type"),
+        status: z.string().optional().describe("Filter by node status"),
+    }),
+}, ({ path, type, status }) => {
+    const { doc } = loadDocument(path);
+    const results = queryNodesOp({
+        doc,
+        type,
+        status,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(results, null, 2),
+            },
+        ],
+    };
+});
+// Register query-node tool
+server.registerTool("query-node", {
+    description: "Get a specific node by ID",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+        id: z.string().describe("Node ID"),
+    }),
+}, ({ path, id }) => {
+    const { doc } = loadDocument(path);
+    const result = queryNodeOp({ doc, id });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// Register query-relationships tool
+server.registerTool("query-relationships", {
+    description: "Query relationships by source, target, or type",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+        from: z.string().optional().describe("Filter by source node ID"),
+        to: z.string().optional().describe("Filter by target node ID"),
+        type: z.string().optional().describe("Filter by relationship type"),
+    }),
+}, ({ path, from, to, type }) => {
+    const { doc } = loadDocument(path);
+    const results = queryRelationshipsOp({
+        doc,
+        from,
+        to,
+        type,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(results, null, 2),
+            },
+        ],
+    };
+});
+// Register trace tool
+server.registerTool("trace", {
+    description: "Trace impacts from a node through the graph",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+        from: z.string().describe("Starting node ID"),
+    }),
+}, ({ path, from }) => {
+    const { doc } = loadDocument(path);
+    const result = traceFromNodeOp({ doc, startId: from });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// Register add-node tool
+server.registerTool("add-node", {
+    description: "Add a new node to the SysProM document",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+        type: z.string().describe("Node type"),
+        id: z.string().optional().describe("Node ID (auto-generated if omitted)"),
+        name: z.string().describe("Node name"),
+        description: z.string().optional().describe("Node description"),
+    }),
+}, ({ path, type, id, name, description }) => {
+    const { doc } = loadDocument(path);
+    const nodeType = z
+        .enum([
+        "intent",
+        "concept",
+        "capability",
+        "element",
+        "realisation",
+        "invariant",
+        "principle",
+        "policy",
+        "protocol",
+        "stage",
+        "role",
+        "gate",
+        "mode",
+        "artefact",
+        "artefact_flow",
+        "decision",
+        "change",
+        "view",
+        "version",
+    ])
+        .safeParse(type);
+    if (!nodeType.success) {
+        throw new Error(`Invalid node type: ${type}`);
+    }
+    const nodeId = id ?? nextIdOp({ doc, type: nodeType.data });
+    const updated = addNodeOp({
+        doc,
+        node: {
+            id: nodeId,
+            type: nodeType.data,
+            name,
+            ...(description && { description }),
+        },
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    message: "Node added",
+                    id: nodeId,
+                    nodeCount: updated.nodes.length,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// Register remove-node tool
+server.registerTool("remove-node", {
+    description: "Remove a node from the SysProM document",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+        id: z.string().describe("Node ID"),
+    }),
+}, ({ path, id }) => {
+    const { doc } = loadDocument(path);
+    const result = removeNodeOp({ doc, id });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    message: `Node ${id} removed`,
+                    nodeCount: result.doc.nodes.length,
+                    warnings: result.warnings,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// Register update-node tool
+server.registerTool("update-node", {
+    description: "Update node properties",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+        id: z.string().describe("Node ID"),
+        fields: z.record(z.string(), z.unknown()).describe("Fields to update"),
+    }),
+}, ({ path, id, fields }) => {
+    const { doc } = 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 ([
+            "name",
+            "description",
+            "status",
+            "context",
+            "options",
+            "selected",
+            "rationale",
+            "scope",
+            "operations",
+            "plan",
+            "propagation",
+            "includes",
+            "input",
+            "output",
+            "external_references",
+        ].includes(key)) {
+            acc[key] = value;
+        }
+        return acc;
+    }, {});
+    const updated = updateNodeOp({
+        doc,
+        id,
+        fields: validFields,
+    });
+    const node = updated.nodes.find((n) => n.id === id);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ message: "Node updated", node }, null, 2),
+            },
+        ],
+    };
+});
+// Register add-relationship tool
+server.registerTool("add-relationship", {
+    description: "Add a relationship between two nodes",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+        from: z.string().describe("Source node ID"),
+        to: z.string().describe("Target node ID"),
+        type: z.string().describe("Relationship type"),
+    }),
+}, ({ path, from, to, type }) => {
+    const { doc } = loadDocument(path);
+    const relType = RelationshipType.safeParse(type);
+    if (!relType.success) {
+        throw new Error(`Invalid relationship type: ${type}`);
+    }
+    const updated = addRelationshipOp({
+        doc,
+        rel: {
+            from,
+            to,
+            type: relType.data,
+        },
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    message: "Relationship added",
+                    relationshipCount: (updated.relationships ?? []).length,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// Register remove-relationship tool
+server.registerTool("remove-relationship", {
+    description: "Remove a relationship between two nodes",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+        from: z.string().describe("Source node ID"),
+        to: z.string().describe("Target node ID"),
+        type: z.string().describe("Relationship type"),
+    }),
+}, ({ path, from, to, type }) => {
+    const { doc } = loadDocument(path);
+    const relType = RelationshipType.safeParse(type);
+    if (!relType.success) {
+        throw new Error(`Invalid relationship type: ${type}`);
+    }
+    const result = removeRelationshipOp({
+        doc,
+        from,
+        to,
+        type: relType.data,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    message: "Relationship removed",
+                    relationshipCount: (result.doc.relationships ?? []).length,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("SysProM MCP server running...");
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error("Server error:", message);
+    process.exit(1);
+});

package/dist/src/md-to-json.js

@@ -35,7 +35,15 @@ function parseText(raw) {
     const lines = raw.split("\n");
     return lines.length === 1 ? lines[0] : lines;
 }
-/** Separate $schema from front matter so it becomes a top-level document key. */
+/**
+ * Separate $schema from front matter so it becomes a top-level document key.
+ * @param front - The front matter object
+ * @returns An object with extracted schema and remaining metadata
+ * @example
+ * ```ts
+ * const { schema, metadata } = extractSchema({ $schema: "...", foo: "bar" });
+ * ```
+ */
 function extractSchema(front) {
     const schema = typeof front.$schema === "string" ? front.$schema : undefined;
     const metadata = { ...front };

package/dist/src/sync.d.ts

@@ -12,15 +12,18 @@ export interface DetectionResult {
 /**
  * Detect whether JSON and/or Markdown have changed.
  * Strategy:
- * 1. Parse both JSON and Markdown to document objects
- * 2. If documents are identical → no change
- * 3. If documents differ:
- *    - Use file modification times to determine which was edited more recently
- *    - The newer file is considered the "changed" one
- *    - If modification times are very close (< 100ms), treat as conflict
- *
- * @param jsonPath Path to JSON file
- * @param mdPath Path to Markdown file (single or multi-doc)
+ * 1. Parse both JSON and Markdown to document objects.
+ * 2. If documents are identical, no change.
+ * 3. If documents differ, use file modification times to determine which was
+ *    edited more recently. The newer file is considered the "changed" one.
+ *    If modification times are very close (< 100ms), treat as conflict.
+ * @param jsonPath - Path to JSON file
+ * @param mdPath - Path to Markdown file (single or multi-doc)
  * @returns Detection result with jsonChanged, mdChanged, and conflict flags
+ * @example
+ * ```ts
+ * const result = detectChanges("doc.spm.json", "doc.spm.md");
+ * if (result.conflict) throw new Error("Both files changed");
+ * ```
  */
 export declare function detectChanges(jsonPath: string, mdPath: string): DetectionResult;

package/dist/src/sync.js

@@ -5,31 +5,38 @@ import { SysProMDocument } from "./schema.js";
 /**
  * Compute a normalised hash of a document for comparison.
  * Uses canonical JSON representation.
- * @param doc The SysProM document
+ * @param doc - The SysProM document
  * @returns SHA256 hash of the canonicalised document
+ * @example
+ * ```ts
+ * const hash = normaliseHash({ nodes: [], relationships: [] });
+ * ```
  */
 function normaliseHash(doc) {
-    const sorted = JSON.stringify(doc, Object.keys(doc).sort());
+    const keys = doc && typeof doc === "object" ? Object.keys(doc).sort() : [];
+    const sorted = JSON.stringify(doc, keys);
     return createHash("sha256").update(sorted).digest("hex");
 }
 /**
  * Detect whether JSON and/or Markdown have changed.
  * Strategy:
- * 1. Parse both JSON and Markdown to document objects
- * 2. If documents are identical → no change
- * 3. If documents differ:
- *    - Use file modification times to determine which was edited more recently
- *    - The newer file is considered the "changed" one
- *    - If modification times are very close (< 100ms), treat as conflict
- *
- * @param jsonPath Path to JSON file
- * @param mdPath Path to Markdown file (single or multi-doc)
+ * 1. Parse both JSON and Markdown to document objects.
+ * 2. If documents are identical, no change.
+ * 3. If documents differ, use file modification times to determine which was
+ *    edited more recently. The newer file is considered the "changed" one.
+ *    If modification times are very close (< 100ms), treat as conflict.
+ * @param jsonPath - Path to JSON file
+ * @param mdPath - Path to Markdown file (single or multi-doc)
  * @returns Detection result with jsonChanged, mdChanged, and conflict flags
+ * @example
+ * ```ts
+ * const result = detectChanges("doc.spm.json", "doc.spm.md");
+ * if (result.conflict) throw new Error("Both files changed");
+ * ```
  */
 export function detectChanges(jsonPath, mdPath) {
     // Read files
     const jsonContent = readFileSync(jsonPath, "utf8");
-    const mdContent = readFileSync(mdPath, "utf8");
     // Parse JSON
     const jsonDoc = JSON.parse(jsonContent);
     if (!SysProMDocument.is(jsonDoc)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sysprom",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "SysProM — System Provenance Model CLI and library",
   "author": "ExaDev",
   "homepage": "https://exadev.github.io/SysProM",
@@ -35,7 +35,8 @@
   ],
   "bin": {
     "sysprom": "dist/src/cli/index.js",
-    "spm": "dist/src/cli/index.js"
+    "spm": "dist/src/cli/index.js",
+    "sysprom-mcp": "dist/src/mcp/index.js"
   },
   "scripts": {
     "build": "turbo run _build",
@@ -59,6 +60,7 @@
     "prepare": "husky"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
     "commander": "14.0.3",
     "picocolors": "1.1.1",
     "zod": "4.3.6"
@@ -66,6 +68,7 @@
   "devDependencies": {
     "@commitlint/cli": "20.5.0",
     "@commitlint/config-conventional": "20.5.0",
+    "@eslint-community/eslint-plugin-eslint-comments": "4.7.1",
     "@eslint/js": "10.0.1",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",