sysprom 1.12.0 → 1.13.1

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

@@ -46,7 +46,7 @@ export const addCommand = {
         const { doc } = loaded;
         const type = args.nodeType;
         if (!NodeType.is(type)) {
-            console.error(`Unknown node type: ${type}`);
+            console.error(`Unknown node type: "${type}". Valid types: ${NodeType.options.join(", ")}`);
             process.exit(1);
         }
         const id = opts.id ?? nextIdOp({ doc, type });
@@ -57,7 +57,7 @@ export const addCommand = {
         }
         if (opts.status) {
             if (!NodeStatus.is(opts.status)) {
-                console.error(`Unknown status: ${opts.status}`);
+                console.error(`Unknown status: "${opts.status}". Valid statuses: ${NodeStatus.options.join(", ")}`);
                 process.exit(1);
             }
             node.status = opts.status;

package/dist/src/cli/define-command.js

@@ -101,12 +101,14 @@ export function buildCommander(def, parent) {
                     continue;
                 const desc = fieldDescription(field);
                 const choices = fieldChoices(field);
+                const optional = fieldIsOptional(field);
                 const flagName = camelToKebab(key);
                 if (choices) {
-                    cmd.addArgument(new Argument(`<${flagName}>`, desc).choices(choices));
+                    const arg = new Argument(optional ? `[${flagName}]` : `<${flagName}>`, desc).choices(choices);
+                    cmd.addArgument(arg);
                 }
                 else {
-                    cmd.argument(`<${flagName}>`, desc);
+                    cmd.argument(optional ? `[${flagName}]` : `<${flagName}>`, desc);
                 }
             }
         }

package/dist/src/cli/program.js

@@ -1,6 +1,31 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import packageJson from "../../package.json" with { type: "json" };
 import { buildCommander } from "./define-command.js";
+let cachedVersion;
+function getVersion() {
+    if (cachedVersion === undefined) {
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        // Works from both src/cli/ (../../) and dist/src/cli/ (../../../)
+        const candidates = [
+            resolve(__dirname, "../../package.json"),
+            resolve(__dirname, "../../../package.json"),
+        ];
+        const pkgPath = candidates.find((p) => existsSync(p) && !p.includes("/dist/"));
+        if (!pkgPath)
+            throw new Error("Could not find sysprom package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        if (typeof pkg !== "object" ||
+            pkg === null ||
+            !("version" in pkg) ||
+            typeof pkg.version !== "string") {
+            throw new Error("Invalid package.json: missing version field");
+        }
+        cachedVersion = pkg.version;
+    }
+    return cachedVersion;
+}
 import { validateCommand } from "./commands/validate.js";
 import { statsCommand } from "./commands/stats.js";
 import { json2mdCommand } from "./commands/json2md.js";
@@ -22,7 +47,11 @@ export const program = new Command();
 program
     .name("sysprom")
     .description("System Provenance Model CLI — record where every part of a system came from")
-    .version(packageJson.version)
+    .option("-V, --version", "output the version number")
+    .on("option:version", () => {
+    console.log(getVersion());
+    process.exit(0);
+})
     .showHelpAfterError(true);
 export const commands = [
     validateCommand,

package/dist/src/mcp/server.js

@@ -3,7 +3,7 @@ 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 { NodeType, 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({
@@ -146,31 +146,9 @@ server.registerTool("add-node", {
     }),
 }, ({ 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);
+    const nodeType = NodeType.safeParse(type);
     if (!nodeType.success) {
-        throw new Error(`Invalid node type: ${type}`);
+        throw new Error(`Invalid node type: "${type}". Valid types: ${NodeType.options.join(", ")}`);
     }
     const nodeId = id ?? nextIdOp({ doc, type: nodeType.data });
     const updated = addNodeOp({
@@ -280,7 +258,7 @@ server.registerTool("add-relationship", {
     const { doc } = loadDocument(path);
     const relType = RelationshipType.safeParse(type);
     if (!relType.success) {
-        throw new Error(`Invalid relationship type: ${type}`);
+        throw new Error(`Invalid relationship type: "${type}". Valid types: ${RelationshipType.options.join(", ")}`);
     }
     const updated = addRelationshipOp({
         doc,
@@ -315,7 +293,7 @@ server.registerTool("remove-relationship", {
     const { doc } = loadDocument(path);
     const relType = RelationshipType.safeParse(type);
     if (!relType.success) {
-        throw new Error(`Invalid relationship type: ${type}`);
+        throw new Error(`Invalid relationship type: "${type}". Valid types: ${RelationshipType.options.join(", ")}`);
     }
     const result = removeRelationshipOp({
         doc,

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

@@ -7,25 +7,25 @@ const operationType = z.enum(["add", "update", "remove", "link"]);
 function parseNodeType(s) {
     const result = NodeType.safeParse(s);
     if (!result.success)
-        throw new Error(`Unknown node type: ${s}`);
+        throw new Error(`Unknown node type: "${s}". Valid types: ${NodeType.options.join(", ")}`);
     return result.data;
 }
 function parseRelType(s) {
     const result = RelationshipType.safeParse(s);
     if (!result.success)
-        throw new Error(`Unknown relationship type: ${s}`);
+        throw new Error(`Unknown relationship type: "${s}". Valid types: ${RelationshipType.options.join(", ")}`);
     return result.data;
 }
 function parseNodeStatus(s) {
     const result = NodeStatus.safeParse(s);
     if (!result.success)
-        throw new Error(`Unknown node status: ${s}`);
+        throw new Error(`Unknown node status: "${s}". Valid statuses: ${NodeStatus.options.join(", ")}`);
     return result.data;
 }
 function parseExtRefRole(s) {
     const result = ExternalReferenceRole.safeParse(s);
     if (!result.success)
-        throw new Error(`Unknown external reference role: ${s}`);
+        throw new Error(`Unknown external reference role: "${s}". Valid roles: ${ExternalReferenceRole.options.join(", ")}`);
     return result.data;
 }
 // ---------------------------------------------------------------------------
@@ -286,7 +286,7 @@ function parseNodeFromSection(section) {
             const rawType = parts[0];
             const parsed = operationType.safeParse(rawType);
             if (!parsed.success) {
-                throw new Error(`Unknown operation type: ${rawType}`);
+                throw new Error(`Unknown operation type: "${rawType}". Valid types: ${operationType.options.join(", ")}`);
             }
             const type = parsed.data;
             const rest = parts.slice(1);

package/dist/src/operations/add-relationship.js

@@ -1,7 +1,7 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument, Relationship } from "../schema.js";
-import { isValidEndpointPair } from "../endpoint-types.js";
+import { isValidEndpointPair, RELATIONSHIP_ENDPOINT_TYPES, } from "../endpoint-types.js";
 /**
  * Add a relationship to a SysProM document. Returns a new document with the relationship appended.
  * @throws {Error} If either endpoint node does not exist, endpoint types are invalid, or the relationship is a duplicate.
@@ -26,7 +26,8 @@ export const addRelationshipOp = defineOperation({
         }
         // Validate endpoint types for this relationship
         if (!isValidEndpointPair(rel.type, fromNode.type, toNode.type)) {
-            throw new Error(`Invalid endpoint types for ${rel.type}: ${fromNode.type} → ${toNode.type}`);
+            const endpoints = RELATIONSHIP_ENDPOINT_TYPES[rel.type];
+            throw new Error(`Invalid endpoint types for ${rel.type}: ${fromNode.type} → ${toNode.type}. Valid: [${endpoints.from.join(", ")}] → [${endpoints.to.join(", ")}]`);
         }
         // Check for duplicate relationship
         const isDuplicate = (doc.relationships ?? []).some((r) => r.from === rel.from && r.to === rel.to && r.type === rel.type);

package/dist/src/operations/update-node.js

@@ -1,6 +1,6 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
-import { SysProMDocument, Node } from "../schema.js";
+import { SysProMDocument, NodeBase } from "../schema.js";
 /**
  * Update specified fields on a node, merging the provided fields into the existing node.
  * @throws {Error} If the node ID is not found.
@@ -11,7 +11,7 @@ export const updateNodeOp = defineOperation({
     input: z.object({
         doc: SysProMDocument,
         id: z.string(),
-        fields: Node.partial(),
+        fields: NodeBase.partial(),
     }),
     output: SysProMDocument,
     fn({ doc, id, fields }) {

package/dist/src/operations/validate.js

@@ -1,7 +1,7 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument } from "../schema.js";
-import { isValidEndpointPair } from "../endpoint-types.js";
+import { isValidEndpointPair, RELATIONSHIP_ENDPOINT_TYPES, } from "../endpoint-types.js";
 /** Zod schema for the result of validating a SysProM document. */
 export const ValidationResult = z.object({
     valid: z.boolean(),
@@ -67,7 +67,8 @@ export const validateOp = defineOperation({
             if (fromNode &&
                 toNode &&
                 !isValidEndpointPair(r.type, fromNode.type, toNode.type)) {
-                issues.push(`Invalid endpoint types for ${r.type}: ${fromNode.type} → ${toNode.type} (${r.from} → ${r.to})`);
+                const endpoints = RELATIONSHIP_ENDPOINT_TYPES[r.type];
+                issues.push(`Invalid endpoint types for ${r.type}: ${fromNode.type} → ${toNode.type} (${r.from} → ${r.to}). Valid: [${endpoints.from.join(", ")}] → [${endpoints.to.join(", ")}]`);
             }
         }
         // Operational relationships to retired nodes

package/dist/src/schema.d.ts

@@ -412,6 +412,144 @@ declare const SysProMDocumentSchema: z.ZodObject<{
         };
     }>>;
 }, z.core.$strip>;
+/** Base node object schema without ID-prefix refinement. Supports .partial(). */
+export declare const NodeBase: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        intent: "intent";
+        concept: "concept";
+        capability: "capability";
+        element: "element";
+        realisation: "realisation";
+        invariant: "invariant";
+        principle: "principle";
+        policy: "policy";
+        protocol: "protocol";
+        stage: "stage";
+        role: "role";
+        gate: "gate";
+        mode: "mode";
+        artefact: "artefact";
+        artefact_flow: "artefact_flow";
+        decision: "decision";
+        change: "change";
+        view: "view";
+        milestone: "milestone";
+        version: "version";
+    }> & {
+        is(value: unknown): value is "intent" | "concept" | "capability" | "element" | "realisation" | "invariant" | "principle" | "policy" | "protocol" | "stage" | "role" | "gate" | "mode" | "artefact" | "artefact_flow" | "decision" | "change" | "view" | "milestone" | "version";
+    };
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+        is(value: unknown): value is string | string[];
+    }>;
+    status: z.ZodOptional<z.ZodEnum<{
+        deprecated: "deprecated";
+        proposed: "proposed";
+        accepted: "accepted";
+        active: "active";
+        implemented: "implemented";
+        adopted: "adopted";
+        defined: "defined";
+        introduced: "introduced";
+        in_progress: "in_progress";
+        complete: "complete";
+        consolidated: "consolidated";
+        experimental: "experimental";
+        retired: "retired";
+        superseded: "superseded";
+        abandoned: "abandoned";
+        deferred: "deferred";
+    }> & {
+        is(value: unknown): value is "deprecated" | "proposed" | "accepted" | "active" | "implemented" | "adopted" | "defined" | "introduced" | "in_progress" | "complete" | "consolidated" | "experimental" | "retired" | "superseded" | "abandoned" | "deferred";
+    }>;
+    lifecycle: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
+    context: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+        is(value: unknown): value is string | string[];
+    }>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+            is(value: unknown): value is string | string[];
+        };
+    }, z.core.$loose> & {
+        is(value: unknown): value is {
+            [x: string]: unknown;
+            id: string;
+            description: string | string[];
+        };
+    }>>;
+    selected: z.ZodOptional<z.ZodString>;
+    rationale: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+        is(value: unknown): value is string | string[];
+    }>;
+    scope: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    operations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            link: "link";
+            add: "add";
+            update: "update";
+            remove: "remove";
+        }>;
+        target: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+            is(value: unknown): value is string | string[];
+        }>;
+    }, z.core.$loose> & {
+        is(value: unknown): value is {
+            [x: string]: unknown;
+            type: "link" | "add" | "update" | "remove";
+            target?: string | undefined;
+            description?: string | string[] | undefined;
+        };
+    }>>;
+    plan: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+            is(value: unknown): value is string | string[];
+        };
+        done: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    }, z.core.$loose> & {
+        is(value: unknown): value is {
+            [x: string]: unknown;
+            description: string | string[];
+            done?: boolean | undefined;
+        };
+    }>>;
+    propagation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    includes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    input: z.ZodOptional<z.ZodString>;
+    output: z.ZodOptional<z.ZodString>;
+    external_references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            output: "output";
+            input: "input";
+            context: "context";
+            evidence: "evidence";
+            source: "source";
+            standard: "standard";
+            prior_art: "prior_art";
+        }> & {
+            is(value: unknown): value is "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
+        };
+        identifier: z.ZodString;
+        description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+            is(value: unknown): value is string | string[];
+        }>;
+        node_id: z.ZodOptional<z.ZodString>;
+        internalised: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+            is(value: unknown): value is string | string[];
+        }>;
+    }, z.core.$strip> & {
+        is(value: unknown): value is {
+            role: "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
+            identifier: string;
+            description?: string | string[] | undefined;
+            node_id?: string | undefined;
+            internalised?: string | string[] | undefined;
+        };
+    }>>;
+    readonly subsystem: z.ZodOptional<typeof SysProMDocumentSchema>;
+}, z.core.$loose>;
 declare const NodeSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{

package/dist/src/schema.js

@@ -250,7 +250,8 @@ const SysProMDocumentSchema = z
     title: "SysProM: System Provenance Model",
     description: "JSON Schema for SysProM — a recursive, decision-driven model for recording system provenance.",
 });
-const NodeSchema = z
+/** Base node object schema without ID-prefix refinement. Supports .partial(). */
+export const NodeBase = z
     .looseObject({
     id: z.string().describe("Unique identifier for this node."),
     type: NodeType,
@@ -308,6 +309,19 @@ const NodeSchema = z
     },
 })
     .describe("A uniquely identifiable entity within the system.");
+const NodeSchema = NodeBase.superRefine((node, ctx) => {
+    const prefix = NODE_ID_PREFIX[node.type];
+    if (!prefix)
+        return; // Unknown type — skip validation
+    const pattern = new RegExp(`^${prefix}\\d+(-[A-Z][A-Z0-9_]*)*$`);
+    if (!pattern.test(node.id)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["id"],
+            message: `Node ID "${node.id}" does not match required pattern for type "${node.type}": expected ${prefix}<number> with optional -SUFFIX segments (e.g. ${prefix}1, ${prefix}1-MY-LABEL)`,
+        });
+    }
+});
 // Attach .is() type guards after both schemas are declared
 /**
  * Zod schema for a complete SysProM document — the root container holding
@@ -344,13 +358,13 @@ export const NODE_FILE_MAP = {
 };
 /** Conventional ID prefix for each node type. */
 export const NODE_ID_PREFIX = {
-    intent: "I",
-    concept: "CN",
-    capability: "CP",
-    element: "EL",
-    realisation: "R",
+    intent: "INT",
+    concept: "CON",
+    capability: "CAP",
+    element: "ELEM",
+    realisation: "REAL",
     invariant: "INV",
-    principle: "PR",
+    principle: "PRIN",
     policy: "POL",
     protocol: "PROT",
     stage: "STG",
@@ -358,11 +372,11 @@ export const NODE_ID_PREFIX = {
     gate: "GATE",
     mode: "MODE",
     artefact: "ART",
-    artefact_flow: "AF",
-    decision: "D",
-    change: "CH",
-    view: "V",
-    milestone: "MS",
+    artefact_flow: "FLOW",
+    decision: "DEC",
+    change: "CHG",
+    view: "VIEW",
+    milestone: "MILE",
     version: "VER",
 };
 // ---------------------------------------------------------------------------

package/package.json

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