feat(cli): add commands to manage external references

Add update add-ref and update remove-ref subcommands to add or remove
external references on nodes. External references link nodes to source
documents, ADRs, standards, code files, and other resources outside the
SysProM graph.

Resolves issue #22

Author: Mearman

src/cli/commands/update.ts

@@ -1,11 +1,17 @@
 import * as z from "zod";
 import type { CommandDef } from "../define-command.js";
-import { RelationshipType, NodeStatus } from "../../schema.js";
+import {
+	RelationshipType,
+	NodeStatus,
+	ExternalReferenceRole,
+} from "../../schema.js";
 import {
 	updateNodeOp,
 	addRelationshipOp,
 	removeRelationshipOp,
 	updateMetadataOp,
+	addExternalReferenceOp,
+	removeExternalReferenceOp,
 } from "../../operations/index.js";
 import { mutationOpts, loadDoc, persistDoc } from "../shared.js";
 
@@ -96,6 +102,27 @@ const metaOpts = mutationOpts.extend({
 		.describe("metadata field updates (key=value format)"),
 });
 
+const addRefArgs = z.object({
+	id: z.string().describe("node ID to add reference to"),
+});
+const addRefOpts = mutationOpts.extend({
+	role: ExternalReferenceRole.describe("reference role"),
+	identifier: z
+		.string()
+		.describe("reference identifier (URI, file path, etc.)"),
+	description: z
+		.string()
+		.optional()
+		.describe("optional description of the reference"),
+});
+
+const removeRefArgs = z.object({
+	id: z.string().describe("node ID to remove reference from"),
+});
+const removeRefOpts = mutationOpts.extend({
+	identifier: z.string().describe("identifier of the reference to remove"),
+});
+
 // ---------------------------------------------------------------------------
 // Subcommands
 // ---------------------------------------------------------------------------
@@ -266,6 +293,84 @@ const metaSubcommand: CommandDef = {
 	},
 };
 
+const addRefSubcommand: CommandDef = {
+	name: "add-ref",
+	description: addExternalReferenceOp.def.description,
+	apiLink: addExternalReferenceOp.def.name,
+	args: addRefArgs,
+	opts: addRefOpts,
+	action(rawArgs: unknown, rawOpts: unknown) {
+		const args = addRefArgs.parse(rawArgs);
+		const opts = addRefOpts.parse(rawOpts);
+		const loaded = loadDoc(opts.path);
+		const { doc } = loaded;
+
+		const newDoc = addExternalReferenceOp({
+			doc,
+			nodeId: args.id,
+			role: opts.role,
+			identifier: opts.identifier,
+			description: opts.description,
+		});
+
+		persistDoc(newDoc, loaded, opts);
+
+		if (opts.json) {
+			const node = newDoc.nodes.find((n) => n.id === args.id);
+			const ref = node?.external_references?.find(
+				(r) => r.identifier === opts.identifier,
+			);
+			console.log(JSON.stringify(ref, null, 2));
+		} else {
+			console.log(
+				`${opts.dryRun ? "[dry-run] Would add" : "Added"} external reference to ${args.id}: ${opts.role} → ${opts.identifier}`,
+			);
+		}
+	},
+};
+
+const removeRefSubcommand: CommandDef = {
+	name: "remove-ref",
+	description: removeExternalReferenceOp.def.description,
+	apiLink: removeExternalReferenceOp.def.name,
+	args: removeRefArgs,
+	opts: removeRefOpts,
+	action(rawArgs: unknown, rawOpts: unknown) {
+		const args = removeRefArgs.parse(rawArgs);
+		const opts = removeRefOpts.parse(rawOpts);
+		const loaded = loadDoc(opts.path);
+		const { doc } = loaded;
+
+		removeExternalReferenceOp({
+			doc,
+			nodeId: args.id,
+			identifier: opts.identifier,
+		});
+
+		const newDoc = removeExternalReferenceOp({
+			doc,
+			nodeId: args.id,
+			identifier: opts.identifier,
+		});
+
+		persistDoc(newDoc, loaded, opts);
+
+		if (opts.json) {
+			console.log(
+				JSON.stringify(
+					{ nodeId: args.id, identifier: opts.identifier },
+					null,
+					2,
+				),
+			);
+		} else {
+			console.log(
+				`${opts.dryRun ? "[dry-run] Would remove" : "Removed"} external reference from ${args.id}: ${opts.identifier}`,
+			);
+		}
+	},
+};
+
 // ---------------------------------------------------------------------------
 // Main command
 // ---------------------------------------------------------------------------
@@ -277,6 +382,8 @@ export const updateCommand: CommandDef = {
 		nodeSubcommand,
 		addRelSubcommand,
 		removeRelSubcommand,
+		addRefSubcommand,
+		removeRefSubcommand,
 		metaSubcommand,
 	],
 };

src/operations/add-external-reference.ts

@@ -0,0 +1,57 @@
+import * as z from "zod";
+import { defineOperation } from "./define-operation.js";
+import {
+	SysProMDocument,
+	ExternalReference,
+	ExternalReferenceRole,
+} from "../schema.js";
+
+/**
+ * Add an external reference to a node.
+ *
+ * External references link nodes to source documents, ADRs, standards, code files,
+ * and other resources outside the SysProM graph.
+ */
+export const addExternalReferenceOp = defineOperation({
+	name: "add-external-reference",
+	description: "Add an external reference to a node",
+	input: z.object({
+		doc: SysProMDocument,
+		nodeId: z.string().describe("The node to add the reference to"),
+		role: ExternalReferenceRole.describe(
+			"Reference role (e.g. source, output, evidence, standard)",
+		),
+		identifier: z
+			.string()
+			.describe("Reference identifier (URI, file path, etc.)"),
+		description: z
+			.string()
+			.optional()
+			.describe("Optional description of the reference"),
+	}),
+	output: SysProMDocument,
+	fn: (input) => {
+		const node = input.doc.nodes.find((n) => n.id === input.nodeId);
+		if (!node) {
+			throw new Error(`Node not found: ${input.nodeId}`);
+		}
+
+		const newRef: ExternalReference = {
+			role: input.role,
+			identifier: input.identifier,
+			...(input.description && { description: input.description }),
+		};
+
+		const updatedNode = {
+			...node,
+			external_references: [...(node.external_references ?? []), newRef],
+		};
+
+		return {
+			...input.doc,
+			nodes: input.doc.nodes.map((n) =>
+				n.id === input.nodeId ? updatedNode : n,
+			),
+		};
+	},
+});

src/operations/index.ts

@@ -11,6 +11,8 @@ export { updateNodeOp } from "./update-node.js";
 export { addRelationshipOp } from "./add-relationship.js";
 export { removeRelationshipOp } from "./remove-relationship.js";
 export { updateMetadataOp } from "./update-metadata.js";
+export { addExternalReferenceOp } from "./add-external-reference.js";
+export { removeExternalReferenceOp } from "./remove-external-reference.js";
 export { nextIdOp } from "./next-id.js";
 export { initDocumentOp } from "./init-document.js";
 export { planInitOp } from "./plan-init.js";

src/operations/remove-external-reference.ts

@@ -0,0 +1,47 @@
+import * as z from "zod";
+import { defineOperation } from "./define-operation.js";
+import { SysProMDocument } from "../schema.js";
+
+/**
+ * Remove an external reference from a node by its identifier.
+ */
+export const removeExternalReferenceOp = defineOperation({
+	name: "remove-external-reference",
+	description: "Remove an external reference from a node",
+	input: z.object({
+		doc: SysProMDocument,
+		nodeId: z.string().describe("The node to remove the reference from"),
+		identifier: z
+			.string()
+			.describe("The identifier of the reference to remove"),
+	}),
+	output: SysProMDocument,
+	fn: (input) => {
+		const node = input.doc.nodes.find((n) => n.id === input.nodeId);
+		if (!node) {
+			throw new Error(`Node not found: ${input.nodeId}`);
+		}
+
+		const refs = node.external_references ?? [];
+		const found = refs.some((r) => r.identifier === input.identifier);
+		if (!found) {
+			throw new Error(
+				`Reference not found: ${input.identifier} on node ${input.nodeId}`,
+			);
+		}
+
+		const updatedNode = {
+			...node,
+			external_references: refs.filter(
+				(r) => r.identifier !== input.identifier,
+			),
+		};
+
+		return {
+			...input.doc,
+			nodes: input.doc.nodes.map((n) =>
+				n.id === input.nodeId ? updatedNode : n,
+			),
+		};
+	},
+});