sysprom 1.5.0 → 1.7.0

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

@@ -0,0 +1,18 @@
+import type { CommandDef } from "../define-command.js";
+import { type BidirectionalSyncResult, type ConflictStrategy } from "../../operations/index.js";
+interface SyncCommandInput {
+    jsonPath: string;
+    mdPath: string;
+    strategy?: ConflictStrategy;
+    dryRun?: boolean;
+}
+/**
+ * Synchronise JSON and Markdown representations of a SysProM document.
+ * @param input - Configuration for sync operation
+ * @returns Result of the synchronisation
+ * @example
+ * const result = syncCommand({ jsonPath: "doc.spm.json", mdPath: "doc.spm.md" });
+ */
+export declare function syncCommand(input: SyncCommandInput): BidirectionalSyncResult;
+export declare const syncCommandDef: CommandDef;
+export {};

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

@@ -0,0 +1,112 @@
+import * as z from "zod";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { syncDocumentsOp, } from "../../operations/index.js";
+import { detectChanges } from "../../sync.js";
+import { markdownToJson } from "../../md-to-json.js";
+import { jsonToMarkdownSingle } from "../../json-to-md.js";
+import { canonicalise } from "../../canonical-json.js";
+import { SysProMDocument } from "../../schema.js";
+/**
+ * Synchronise JSON and Markdown representations of a SysProM document.
+ * @param input - Configuration for sync operation
+ * @returns Result of the synchronisation
+ * @example
+ * const result = syncCommand({ jsonPath: "doc.spm.json", mdPath: "doc.spm.md" });
+ */
+export function syncCommand(input) {
+    const { jsonPath, mdPath, strategy = "json", dryRun = false } = input;
+    // Read JSON document
+    const jsonContent = readFileSync(jsonPath, "utf8");
+    const jsonDoc = JSON.parse(jsonContent);
+    if (!SysProMDocument.is(jsonDoc)) {
+        throw new Error("JSON file is not a valid SysProM document");
+    }
+    // Parse Markdown to document
+    const mdDoc = markdownToJson(mdPath);
+    // Detect which side changed
+    const changes = detectChanges(jsonPath, mdPath);
+    // Perform sync operation
+    const result = syncDocumentsOp({
+        jsonDoc,
+        mdDoc,
+        jsonChanged: changes.jsonChanged,
+        mdChanged: changes.mdChanged,
+        strategy,
+    });
+    // Write results if not dry-run
+    if (!dryRun) {
+        // Write synced document back to both formats
+        if (result.jsonChanged || result.mdChanged || result.conflict) {
+            // Update JSON
+            writeFileSync(jsonPath, canonicalise(result.synced, { indent: "\t" }) + "\n");
+            // Update Markdown
+            const mdContent = jsonToMarkdownSingle(result.synced);
+            writeFileSync(mdPath, mdContent);
+        }
+    }
+    return result;
+}
+function isArgs(arg) {
+    return (typeof arg === "object" && arg !== null && "input" in arg && "output" in arg);
+}
+function isOpts(opt) {
+    return typeof opt === "object" && opt !== null;
+}
+export const syncCommandDef = {
+    name: "sync",
+    description: "Synchronise JSON and Markdown representations with conflict resolution",
+    apiLink: "syncDocuments",
+    args: z.object({
+        input: z.string().describe("Path to JSON file"),
+        output: z.string().describe("Path to Markdown file"),
+    }),
+    opts: z
+        .object({
+        preferJson: z
+            .boolean()
+            .optional()
+            .describe("Prefer JSON as source of truth in conflicts"),
+        preferMd: z
+            .boolean()
+            .optional()
+            .describe("Prefer Markdown as source of truth in conflicts"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .describe("Preview changes without writing files"),
+        report: z
+            .boolean()
+            .optional()
+            .describe("Report conflicts without resolving"),
+    })
+        .strict(),
+    action(args, opts) {
+        if (!isArgs(args))
+            throw new Error("Invalid args");
+        if (!isOpts(opts))
+            throw new Error("Invalid opts");
+        const jsonPath = resolve(args.input);
+        const mdPath = resolve(args.output);
+        // Determine conflict strategy
+        let strategy = "json";
+        if (opts.preferMd)
+            strategy = "md";
+        if (opts.report)
+            strategy = "report";
+        const result = syncCommand({
+            jsonPath,
+            mdPath,
+            strategy,
+            dryRun: opts.dryRun ?? false,
+        });
+        // Output results
+        console.log(`Sync complete:`);
+        console.log(`  JSON changed: ${String(result.jsonChanged)}`);
+        console.log(`  Markdown changed: ${String(result.mdChanged)}`);
+        console.log(`  Conflict: ${String(result.conflict)}`);
+        if (result.changedNodes.length > 0) {
+            console.log(`  Changed nodes: ${result.changedNodes.join(", ")}`);
+        }
+    },
+};

package/dist/src/cli/program.js

@@ -16,6 +16,7 @@ import { updateCommand } from "./commands/update.js";
 import { speckitCommand } from "./commands/speckit.js";
 import { taskCommand } from "./commands/task.js";
 import { planCommand } from "./commands/plan.js";
+import { syncCommandDef } from "./commands/sync.js";
 const VERSION = "1.0.0";
 export const program = new Command();
 program
@@ -40,6 +41,7 @@ export const commands = [
     speckitCommand,
     taskCommand,
     planCommand,
+    syncCommandDef,
 ];
 for (const cmd of commands) {
     buildCommander(cmd, program);

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

@@ -261,6 +261,7 @@ function generateReadme(doc, fromIdx) {
     const lines = [];
     const title = doc.metadata?.title ?? "SysProM";
     lines.push(renderFrontMatter({
+        ...(doc.$schema ? { $schema: doc.$schema } : {}),
         title,
         doc_type: doc.metadata?.doc_type ?? "sysprom",
         scope: doc.metadata?.scope,
@@ -373,6 +374,7 @@ export function jsonToMarkdownSingle(doc) {
     const lines = [];
     const title = doc.metadata?.title ?? "SysProM";
     lines.push(renderFrontMatter({
+        ...(doc.$schema ? { $schema: doc.$schema } : {}),
         title,
         doc_type: doc.metadata?.doc_type ?? "sysprom",
         scope: doc.metadata?.scope,

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,6 +35,13 @@ 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. */
+function extractSchema(front) {
+    const schema = typeof front.$schema === "string" ? front.$schema : undefined;
+    const metadata = { ...front };
+    delete metadata.$schema;
+    return { schema, metadata };
+}
 function parseFrontMatter(content) {
     if (!content.startsWith("---\n"))
         return { front: {}, body: content };
@@ -44,7 +51,7 @@ function parseFrontMatter(content) {
     const yaml = content.slice(4, end);
     const front = {};
     for (const line of yaml.split("\n")) {
-        const match = /^(\w+):\s*(.+)$/.exec(line);
+        const match = /^([\w$]+):\s*(.+)$/.exec(line);
         if (!match)
             continue;
         const [, key, raw] = match;
@@ -167,9 +174,22 @@ function parseListItems(body, prefix) {
     return items;
 }
 function parseSingleValue(body, prefix) {
-    for (const line of body.split("\n")) {
-        if (line.startsWith(`${prefix}: `)) {
-            return line.slice(prefix.length + 2);
+    const lines = body.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].startsWith(`${prefix}: `)) {
+            const firstLine = lines[i].slice(prefix.length + 2);
+            const continuationLines = [firstLine];
+            for (let j = i + 1; j < lines.length; j++) {
+                const next = lines[j];
+                if (next === "")
+                    break;
+                if (next.startsWith("- ") || next.startsWith("#"))
+                    break;
+                if (/^[A-Z][a-z]+: /.test(next))
+                    break;
+                continuationLines.push(next);
+            }
+            return continuationLines.join("\n");
         }
     }
     return undefined;
@@ -450,14 +470,16 @@ export function markdownSingleToJson(content) {
     const { nodes, rels } = parseDocFile(content, allTypes);
     const tableRels = parseRelationshipTable(body);
     const extRefs = parseExternalReferences(body);
+    const { schema, metadata: metaFront } = extractSchema(front);
     const doc = {
-        metadata: Object.keys(front).length > 0 ? front : undefined,
+        ...(schema ? { $schema: schema } : {}),
+        metadata: Object.keys(metaFront).length > 0 ? metaFront : undefined,
         nodes,
         relationships: [...rels, ...tableRels].length > 0 ? [...rels, ...tableRels] : undefined,
         external_references: extRefs.length > 0 ? extRefs : undefined,
     };
-    if (front.title && typeof front.title === "string") {
-        doc.metadata = { ...front };
+    if (metaFront.title && typeof metaFront.title === "string") {
+        doc.metadata = { ...metaFront };
     }
     return doc;
 }
@@ -532,8 +554,10 @@ export function markdownMultiDocToJson(dir) {
         }
     }
     scanForSubsystems(dir);
+    const { schema, metadata: metaFront } = extractSchema(front);
     const doc = {
-        metadata: Object.keys(front).length > 0 ? front : undefined,
+        ...(schema ? { $schema: schema } : {}),
+        metadata: Object.keys(metaFront).length > 0 ? metaFront : undefined,
         nodes,
         relationships: rels.length > 0 ? rels : undefined,
         external_references: extRefs.length > 0 ? extRefs : undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sysprom",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "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",