archgraph-argo 0.10.14 → 0.10.16

package/argo/scripts/argo-mcp-server.js

@@ -65,6 +65,7 @@ const SYSTEM_ARCHITECTURE_TOOL_NAMES = new Set([
   'updateArchitectureView',
   'removeArchitectureView',
   'generateArchitectureDiffPlantuml',
+  'queryNeo4jGraph',
 ]);
 
 const TOOLS = [

package/argo/scripts/neo4j-system-architecture-store.js

@@ -781,9 +781,255 @@ function toNumber(value) {
   return Number(value);
 }
 
+// --- Read-only Cypher query + structural projection schema -------------------
+
+const FORBIDDEN_CYPHER_CLAUSES = Object.freeze([
+  'CREATE',
+  'MERGE',
+  'DELETE',
+  'SET',
+  'REMOVE',
+  'DROP',
+  'LOAD CSV',
+  'FOREACH',
+  'IN TRANSACTIONS',
+]);
+
+function stripCypherNoise(cypher) {
+  let result = String(cypher);
+  // Block comments.
+  result = result.replace(/\/\*[\s\S]*?\*\//g, ' ');
+  // Line comments.
+  result = result.replace(/\/\/[^\r\n]*/g, ' ');
+  // Single-quoted string literals.
+  result = result.replace(/'(?:[^'\\]|\\.)*'/g, ' ');
+  // Double-quoted identifiers/literals.
+  result = result.replace(/"(?:[^"\\]|\\.)*"/g, ' ');
+  // Backtick-escaped identifiers.
+  result = result.replace(/`(?:[^`\\]|\\.)*`/g, ' ');
+  return result;
+}
+
+function assertReadOnlyCypher(cypher) {
+  if (typeof cypher !== 'string' || cypher.trim().length === 0) {
+    const error = new Error('cypher must be a non-empty string');
+    error.category = 'CYPHER_QUERY_REQUIRED';
+    throw error;
+  }
+  if (cypher.length > 20000) {
+    const error = new Error('cypher exceeds the 20000 character limit');
+    error.category = 'CYPHER_QUERY_TOO_LONG';
+    throw error;
+  }
+
+  const normalized = stripCypherNoise(cypher).toUpperCase();
+  const found = FORBIDDEN_CYPHER_CLAUSES.find(clause => {
+    const escaped = clause.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`\\b${escaped}\\b`).test(normalized);
+  });
+  if (found) {
+    const error = new Error(`Cypher write clause '${found}' is not allowed; the Neo4j graph query interface is read-only`);
+    error.category = 'READ_ONLY_CYPHER_REQUIRED';
+    error.clause = found;
+    throw error;
+  }
+  return true;
+}
+
+function serializeNeo4jValue(value) {
+  if (value === null || value === undefined) {
+    return value === undefined ? null : value;
+  }
+  if (typeof value === 'number' || typeof value === 'string' || typeof value === 'boolean') {
+    return value;
+  }
+
+  let neo4j = null;
+  try {
+    neo4j = requireNeo4jDriver();
+  } catch {
+    neo4j = null;
+  }
+
+  if (neo4j && typeof neo4j.isInt === 'function' && neo4j.isInt(value)) {
+    if (typeof value.inSafeRange === 'function' && value.inSafeRange()) {
+      return value.toNumber();
+    }
+    return value.toString();
+  }
+  if (neo4j && typeof neo4j.isNode === 'function' && neo4j.isNode(value)) {
+    return {
+      $node: {
+        identity: value.identity ? String(value.identity) : null,
+        labels: Array.isArray(value.labels) ? value.labels : [],
+        properties: serializeNeo4jValue(value.properties),
+      },
+    };
+  }
+  if (neo4j && typeof neo4j.isRelationship === 'function' && neo4j.isRelationship(value)) {
+    return {
+      $relationship: {
+        identity: value.identity ? String(value.identity) : null,
+        type: value.type,
+        start: value.start ? String(value.start) : null,
+        end: value.end ? String(value.end) : null,
+        properties: serializeNeo4jValue(value.properties),
+      },
+    };
+  }
+  if (neo4j && typeof neo4j.isPath === 'function' && neo4j.isPath(value)) {
+    return {
+      $path: {
+        start: serializeNeo4jValue(value.start),
+        end: serializeNeo4jValue(value.end),
+        length: serializeNeo4jValue(value.length),
+        segments: Array.isArray(value.segments) ? value.segments.map(serializeNeo4jValue) : [],
+      },
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map(serializeNeo4jValue);
+  }
+  if (typeof value === 'object') {
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+      result[key] = serializeNeo4jValue(item);
+    }
+    return result;
+  }
+  return String(value);
+}
+
+function buildNeo4jGraphSchema(architecturePath = DEFAULT_GRAPH_PATH) {
+  return {
+    graphKey: buildGraphKey(architecturePath),
+    nodeLabels: {
+      ArchitectureGraph: {
+        description: 'One node per canonical graph document; identified by graphKey.',
+        properties: [
+          'graphKey',
+          'source_path',
+          'name',
+          'description',
+          'attributes_json',
+          'raw_json',
+          'element_count',
+          'relationship_count',
+          'view_count',
+        ],
+      },
+      Element: {
+        description: 'Canonical architecture elements. Element.type holds the ArchiMate element type.',
+        properties: [
+          'graphKey',
+          'id',
+          'name',
+          'type',
+          'parent',
+          'alias',
+          'classifier',
+          'description',
+          'attributes_json',
+          'subdiagram_views_json',
+          'testcases_json',
+          'raw_json',
+        ],
+      },
+      ArchitectureRelationship: {
+        description: 'Canonical architecture relationships. type holds the ArchiMate relationship type; source_id/target_id reference Element.id.',
+        properties: [
+          'graphKey',
+          'id',
+          'name',
+          'type',
+          'statement',
+          'description',
+          'document',
+          'attributes_json',
+          'source_id',
+          'source_name',
+          'target_id',
+          'target_name',
+          'raw_json',
+        ],
+      },
+      View: {
+        description: 'Canonical views; identified by view_id.',
+        properties: [
+          'graphKey',
+          'view_id',
+          'view_name',
+          'parent_element_id',
+          'parent_element_name',
+          'description',
+          'included_elements_json',
+          'included_relationships_json',
+          'raw_json',
+        ],
+      },
+    },
+    relationshipTypes: {
+      OWNS_ELEMENT: { from: 'ArchitectureGraph', to: 'Element' },
+      OWNS_RELATIONSHIP: { from: 'ArchitectureGraph', to: 'ArchitectureRelationship' },
+      OWNS_VIEW: { from: 'ArchitectureGraph', to: 'View' },
+      RELATIONSHIP_SOURCE: { from: 'ArchitectureRelationship', to: 'Element', description: 'Source endpoint element of a relationship record.' },
+      RELATIONSHIP_TARGET: { from: 'ArchitectureRelationship', to: 'Element', description: 'Target endpoint element of a relationship record.' },
+      ARCHIMATE_RELATES: { from: 'Element', to: 'Element', properties: ['graphKey', 'relationship_id'], description: 'Direct ArchiMate semantic edge between two elements.' },
+      VIEW_OF: { from: 'View', to: 'Element', description: 'Parent element of a sub-view.' },
+      INCLUDES_ELEMENT: { from: 'View', to: 'Element', properties: ['order'] },
+      INCLUDES_RELATIONSHIP: { from: 'View', to: 'ArchitectureRelationship', properties: ['order'] },
+      HAS_SUBDIAGRAM: { from: 'Element', to: 'View' },
+    },
+  };
+}
+
+async function runNeo4jCypherQuery(options = {}) {
+  const architecturePath = options.architecturePath || DEFAULT_GRAPH_PATH;
+  const cypher = options.cypher;
+  assertReadOnlyCypher(cypher);
+
+  const graphKey = buildGraphKey(architecturePath);
+  const config = getNeo4jConfig(options);
+  const driver = options.driver || createDriver(config);
+  const ownDriver = !options.driver;
+  const session = driver.session({ database: config.database });
+
+  try {
+    const result = await session.executeRead(tx => tx.run(cypher, { graphKey }));
+    const records = result.records.map(record => {
+      const entry = {};
+      for (const key of record.keys) {
+        entry[key] = serializeNeo4jValue(record.get(key));
+      }
+      return entry;
+    });
+
+    const summary = result.summary;
+    return {
+      architecturePath,
+      graphKey,
+      records,
+      summary: {
+        queryType: summary ? summary.queryType : null,
+        database: summary && summary.database ? summary.database.name : null,
+        containsUpdates: summary && summary.counters && typeof summary.counters.containsUpdates === 'function'
+          ? summary.counters.containsUpdates()
+          : null,
+      },
+    };
+  } finally {
+    await session.close();
+    if (ownDriver) {
+      await driver.close();
+    }
+  }
+}
+
 module.exports = {
   DEFAULT_GRAPH_PATH,
+  assertReadOnlyCypher,
   buildGraphKey,
+  buildNeo4jGraphSchema,
   createDriver,
   digestCanonicalArchitecture,
   ensureDatabaseExists,
@@ -797,6 +1043,8 @@ module.exports = {
   readNeo4jSyncState,
   recoverNeo4jSyncIfNeeded,
   resolveArchitecturePath,
+  runNeo4jCypherQuery,
+  serializeNeo4jValue,
   syncArchitectureToNeo4j,
   verifyArchitectureSync,
   waitForDatabaseOnline,

package/argo/scripts/systemarchitecture-mcp-server.js

@@ -164,7 +164,10 @@ const {
 } = require('./graph-rag/mutationEmbeddingVectorLifecycle.js');
 const {
   DEFAULT_GRAPH_PATH: NEO4J_DEFAULT_GRAPH_PATH,
+  buildGraphKey,
+  buildNeo4jGraphSchema,
   recoverNeo4jSyncIfNeeded,
+  runNeo4jCypherQuery,
   syncArchitectureToNeo4j,
   verifyArchitectureSync,
 } = require('./neo4j-system-architecture-store.js');
@@ -379,6 +382,19 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'queryNeo4jGraph',
+    description: 'Run a read-only Cypher query against the Neo4j structural projection of the intent architecture, or request the projection schema so an agent can construct its own Cypher. Pass {schema: true} to return node labels, relationship types, property keys, and the legal ArchiMate element/relationship type enums. Pass {cypher: "..."} to execute a read-only query; scope it with {graphKey: $graphKey}. Write clauses (CREATE/MERGE/DELETE/SET/REMOVE/DROP/LOAD CSV/FOREACH/IN TRANSACTIONS) are rejected.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        architecturePath: { type: 'string', description: `Default: ${DEFAULT_GRAPH_PATH}` },
+        cypher: { type: 'string', description: 'Read-only Cypher query to execute. Use $graphKey to scope to the current architecture graph, e.g. MATCH (e:Element {graphKey: $graphKey}) RETURN e.id, e.name.' },
+        schema: { type: 'boolean', description: 'When true, return the Neo4j projection schema instead of running a Cypher query.' },
+      },
+      additionalProperties: false,
+    },
+  },
 ];
 
 // Every tool accepts an optional per-call `workspaceRoot` (absolute path,
@@ -1041,6 +1057,7 @@ function applyMutations(document, mutations) {
       const existingElement = findById(nextDocument.elements, mutation.element.id);
       if (!existingElement) {
         nextDocument.elements.push(clone(mutation.element));
+        syncViewsToElementSubdiagramViews(nextDocument, findById(nextDocument.elements, mutation.element.id));
       }
       for (const view of scopedViews) {
         view.included_elements = addUnique(view.included_elements || [], [mutation.element.id]);
@@ -1065,7 +1082,12 @@ function applyMutations(document, mutations) {
         throw new Error(`Element '${mutation.id}' does not exist`);
       }
       requirePatchDoesNotChangeElementIdentityOrType(mutation.id, mutation.patch);
+      const patchesSubdiagramViews = Object.prototype.hasOwnProperty.call(mutation.patch, 'subdiagram_views');
+      const patchesName = Object.prototype.hasOwnProperty.call(mutation.patch, 'name');
       Object.assign(element, clone(mutation.patch));
+      if (patchesSubdiagramViews || patchesName) {
+        reconcileSubdiagramViewsForElement(nextDocument, element);
+      }
       touchedElementIds.add(element.id);
       mutationSummaries.push({ type: mutation.type, id: element.id });
       continue;
@@ -1077,6 +1099,10 @@ function applyMutations(document, mutations) {
       if (!element) {
         throw new Error(`Element '${mutation.id}' does not exist`);
       }
+      const childViewIds = collectChildViewIds(nextDocument, mutation.id);
+      if (childViewIds.length > 0) {
+        throw new Error(`Element '${mutation.id}' cannot be removed: it still has ${childViewIds.length} sub-view(s) mounted under it (${childViewIds.join(', ')}). Remove or re-parent those sub-views first.`);
+      }
       const scopedViews = mutation.view_ids === undefined
         ? nextDocument.views
         : requireViewScope(nextDocument.views, mutation.view_ids, 'mutation.view_ids');
@@ -1155,13 +1181,25 @@ function applyMutations(document, mutations) {
         throw new Error(`Relationship '${mutation.id}' does not exist`);
       }
       requirePatchDoesNotChangeRelationshipIdentityOrType(mutation.id, mutation.patch);
+      const oldSourceId = relationship.source_id;
+      const oldTargetId = relationship.target_id;
       Object.assign(relationship, clone(mutation.patch));
       for (const view of nextDocument.views) {
-        if ((view.included_relationships || []).includes(relationship.id)) {
-          view.included_elements = addUnique(view.included_elements || [], [
-            relationship.source_id,
-            relationship.target_id,
-          ]);
+        if (!(view.included_relationships || []).includes(relationship.id)) {
+          continue;
+        }
+        view.included_elements = addUnique(view.included_elements || [], [
+          relationship.source_id,
+          relationship.target_id,
+        ]);
+        for (const oldEndpointId of [oldSourceId, oldTargetId]) {
+          if (oldEndpointId === relationship.source_id || oldEndpointId === relationship.target_id) {
+            continue;
+          }
+          if (isElementUsedByRelationship(nextDocument, view, oldEndpointId, relationship.id)) {
+            continue;
+          }
+          view.included_elements = removeEntries(view.included_elements || [], [oldEndpointId]);
         }
       }
       touchedRelationshipIds.add(relationship.id);
@@ -1180,6 +1218,12 @@ function applyMutations(document, mutations) {
         : requireViewScope(nextDocument.views, mutation.view_ids, 'mutation.view_ids');
       for (const view of scopedViews) {
         view.included_relationships = removeEntries(view.included_relationships || [], [mutation.id]);
+        for (const endpointId of [relationship.source_id, relationship.target_id]) {
+          if (isElementUsedByRelationship(nextDocument, view, endpointId, mutation.id)) {
+            continue;
+          }
+          view.included_elements = removeEntries(view.included_elements || [], [endpointId]);
+        }
         touchedViewIds.add(view.view_id);
       }
       const stillIncludedInView = nextDocument.views.some(view => (
@@ -1349,6 +1393,78 @@ function upsertSubdiagramViewIntoElement(document, elementId, view) {
   }
 }
 
+// Forward-sync: make every view listed in `element.subdiagram_views` point back
+// to this element (stealing the view from any previous parent when necessary).
+function syncViewsToElementSubdiagramViews(document, element) {
+  if (!element || !Array.isArray(element.subdiagram_views)) {
+    return;
+  }
+  for (const entry of element.subdiagram_views) {
+    if (!entry || !entry.view_id) {
+      continue;
+    }
+    const view = findView(document.views, entry.view_id);
+    if (!view) {
+      continue;
+    }
+    if (view.parent_element_id && view.parent_element_id !== element.id) {
+      removeSubdiagramViewFromElement(document, view.parent_element_id, view.view_id);
+    }
+    view.parent_element_id = element.id;
+    view.parent_element_name = element.name;
+  }
+}
+
+// Bidirectional sync after an element's subdiagram_views (or name) changed:
+// listed views point back, and views no longer listed stop pointing at this element.
+function reconcileSubdiagramViewsForElement(document, element) {
+  const currentViewIds = new Set(
+    (element.subdiagram_views || [])
+      .filter(entry => entry && entry.view_id)
+      .map(entry => entry.view_id),
+  );
+  syncViewsToElementSubdiagramViews(document, element);
+  for (const view of document.views || []) {
+    if (view && view.parent_element_id === element.id && !currentViewIds.has(view.view_id)) {
+      delete view.parent_element_id;
+      delete view.parent_element_name;
+    }
+  }
+}
+
+function collectChildViewIds(document, elementId) {
+  const viewIds = new Set();
+  const element = findById(document.elements, elementId);
+  if (element && Array.isArray(element.subdiagram_views)) {
+    for (const entry of element.subdiagram_views) {
+      if (entry && entry.view_id) {
+        viewIds.add(entry.view_id);
+      }
+    }
+  }
+  for (const view of document.views || []) {
+    if (view && view.parent_element_id === elementId && view.view_id) {
+      viewIds.add(view.view_id);
+    }
+  }
+  return Array.from(viewIds);
+}
+
+// Whether any relationship in the view (other than exceptRelationshipId) still
+// references elementId as one of its endpoints.
+function isElementUsedByRelationship(document, view, elementId, exceptRelationshipId) {
+  for (const relationshipId of view.included_relationships || []) {
+    if (relationshipId === exceptRelationshipId) {
+      continue;
+    }
+    const relationship = findById(document.relationships, relationshipId);
+    if (relationship && (relationship.source_id === elementId || relationship.target_id === elementId)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function addUnique(existing, additions) {
   const result = Array.isArray(existing) ? [...existing] : [];
   for (const addition of additions) {
@@ -2054,9 +2170,80 @@ async function callTool(name, args = {}, dependencies = undefined) {
     return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'removeView', view_id: args.view_id }], write), context), write);
   }
 
+  if (name === 'queryNeo4jGraph') {
+    return queryNeo4jGraphTool(args);
+  }
+
   throw new Error(`Unknown tool: ${name}`);
 }
 
+async function queryNeo4jGraphTool(args = {}) {
+  const architecturePath = args.architecturePath || DEFAULT_GRAPH_PATH;
+
+  if (args.schema === true) {
+    return queryNeo4jGraphSchemaResult(architecturePath);
+  }
+
+  try {
+    const result = await runNeo4jCypherQuery({
+      architecturePath,
+      cypher: args.cypher,
+    });
+    return toolResult({
+      status: 'passed',
+      architecturePath: result.architecturePath,
+      graphKey: result.graphKey,
+      records: result.records,
+      summary: result.summary,
+    });
+  } catch (error) {
+    return toolResult(queryError(
+      error && error.category ? error.category : 'NEO4J_QUERY_FAILED',
+      String(error && error.message ? error.message : error),
+      {
+        architecturePath,
+        graphKey: buildGraphKey(architecturePath),
+        ...(error && error.clause ? { clause: error.clause } : {}),
+      },
+    ));
+  }
+}
+
+function queryNeo4jGraphSchemaResult(architecturePath) {
+  const schema = buildNeo4jGraphSchema(architecturePath);
+  let typeEnums = {};
+  try {
+    const workspaceRoot = resolveWorkspaceRoot({ architecturePath });
+    const schemaPath = resolveSchemaPath(workspaceRoot);
+    const jsonSchema = readJson(schemaPath.absolutePath, schemaPath.relativePath);
+    typeEnums = {
+      archimateElementTypes: (jsonSchema.$defs.archimateElementType || {}).enum || [],
+      archimateRelationshipTypes: (jsonSchema.$defs.archimateRelationshipType || {}).enum || [],
+    };
+  } catch (error) {
+    typeEnums = {
+      archimateElementTypes: [],
+      archimateRelationshipTypes: [],
+      schemaEnumError: String(error && error.message ? error.message : error),
+    };
+  }
+
+  return toolResult({
+    status: 'passed',
+    architecturePath,
+    graphKey: buildGraphKey(architecturePath),
+    schema: {
+      ...schema,
+      ...typeEnums,
+    },
+    usage: {
+      scopeGraph: 'MATCH (e:Element {graphKey: $graphKey}) ...',
+      exampleAllBusinessActors: "MATCH (e:Element {graphKey: $graphKey}) WHERE e.type = 'Business Actor' RETURN e.id, e.name, e.description",
+      exampleAssignments: "MATCH (a:Element {graphKey: $graphKey, type: 'Business Actor'})-[r:ARCHIMATE_RELATES]->(b:Element {graphKey: $graphKey}) WHERE r.relationship_id IS NOT NULL RETURN a.name, type(r), b.name, r.relationship_id",
+    },
+  });
+}
+
 async function resolveSemanticOperatorJourney(dependencies) {
   return dependencies && dependencies.semanticOperatorJourney
     ? dependencies.semanticOperatorJourney

package/install-argo.ps1

@@ -726,7 +726,7 @@ if ($SkipDsh) {
         Write-DshManagedBlock -Path $patchPath -Block $block -MarkerStart '# BEGIN ArchGraph ARGO deployment' -MarkerEnd '# END ArchGraph ARGO deployment'
     }
 
-    Write-Host "[19/19] argo\agents2 -> $DshHome\.agent-presets\<id> (DeepSeek Harness agent presets)"
+    Write-Host "[19/19] argo\agents5 -> $DshHome\.agent-presets\<id> (DeepSeek Harness agent presets)"
     New-DshAgentPresets -DshHome $DshHome -AgentsSrc (Join-Path $argoDir 'agents')
 
     Write-Host '  Restart `dsh web` to activate the MCP bridge and the wakeup plugin;'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.10.14",
+  "version": "0.10.16",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {