archgraph-argo 0.12.6 → 0.13.0

package/argo/scripts/ea-qea-sync-lib.js

@@ -747,9 +747,46 @@ function fullProjection(graph, qeaPath, opts) {
 // ---------------------------------------------------------------------------
 // Export
 // ---------------------------------------------------------------------------
-// ---------------------------------------------------------------------------
-// Export
-// ---------------------------------------------------------------------------
+// Read the EA diagram GEOMETRY for one KG view from a .qea model (read-only).
+// The view maps to the diagram anchored by the deterministic ea_guid (diag:<viewId>)
+// or the schema_view_id StyleEx token written by the sync. Returns:
+//   - element boxes  = t_diagramobjects rects joined to t_object.Alias (schema id)
+//   - connector lines = t_diagramlinks rows joined to the connector's schema_id tag
+// Returns null when the view has no matching EA diagram. Never writes EA geometry.
+function readViewDiagramGeometry(qeaPath, viewId) {
+  const v = String(viewId === null || viewId === undefined ? '' : viewId).trim();
+  if (v === '') { return null; }
+  const db = openQea(qeaPath);
+  try {
+    ensureMetaTable(db);
+    const guid = deterministicGuid('diag:' + v);
+    const diag = db.prepare('SELECT Diagram_ID FROM t_diagram WHERE ea_guid = ? OR StyleEx LIKE ?')
+      .get(guid, '%schema_view_id=' + v + ';%');
+    if (!diag) { return null; }
+    const diagramId = Number(diag.Diagram_ID);
+    const elements = db.prepare(
+      'SELECT o.Alias AS id, d.RectLeft AS left, d.RectTop AS top, d.RectRight AS right, d.RectBottom AS bottom ' +
+      'FROM t_diagramobjects d JOIN t_object o ON o.Object_ID = d.Object_ID ' +
+      'WHERE d.Diagram_ID = ? AND o.Alias IS NOT NULL AND o.Alias <> ? ' +
+      'ORDER BY d.Sequence'
+    ).all(diagramId, '').map((r) => ({
+      id: String(r.id),
+      left: Number(r.left), top: Number(r.top), right: Number(r.right), bottom: Number(r.bottom),
+    }));
+    const relationships = db.prepare(
+      'SELECT t.VALUE AS id, dl.Geometry AS path ' +
+      'FROM t_diagramlinks dl JOIN t_connectortag t ON t.ElementID = dl.ConnectorID AND t.Property = ? ' +
+      'WHERE dl.DiagramID = ? ORDER BY dl.ConnectorID'
+    ).all('schema_id', diagramId).map((r) => ({
+      id: String(r.id),
+      path: String(r.path === null || r.path === undefined ? '' : r.path),
+    }));
+    return { diagramId, elements, relationships };
+  } finally {
+    try { db.close(); } catch { /* ignore */ }
+  }
+}
+
 function exportQeaToGraph(qeaPath) {
   const db = openQea(qeaPath);
   try {
@@ -789,6 +826,7 @@ module.exports = {
   canonicalArchimateType,
   syncGraphToQea,
   exportQeaToGraph,
+  readViewDiagramGeometry,
   snapshotQea,
   readMetaKind,
   fullProjection,

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

@@ -219,7 +219,7 @@ const TOOLS = [
   },
   {
     name: 'getArchitectureViewContext',
-    description: 'read-only query that resolves one view by view_id into its complete membership: the view object, every member element (from included_elements), every member relationship (from included_relationships), the parent element, and optionally child sub-views declared by member elements. Resolves ids into full canonical objects instead of returning raw id lists.',
+    description: 'read-only query that resolves one view by view_id into its complete membership: the view object, every member element (from included_elements), every member relationship (from included_relationships), the parent element, and optionally child sub-views declared by member elements. Resolves ids into full canonical objects instead of returning raw id lists. Optional includeEaGeometry (default false) additionally returns the EA diagram geometry of the resolved view.',
     inputSchema: viewContextInputSchema(),
   },
   {
@@ -441,6 +441,7 @@ function viewContextInputSchema() {
       view_id: { type: 'string', description: 'The id of the view to resolve.' },
       includeParentElement: { type: 'boolean', description: 'Default: true. Resolve the parent element referenced by the view.' },
       includeChildViews: { type: 'boolean', description: 'Default: false. Include child views declared by member elements through subdiagram_views.' },
+      includeEaGeometry: { type: 'boolean', description: 'Default: false (opt-in). When true, additionally resolve the diagram GEOMETRY (element boxes + connector line paths) for this view from the workspace EA model (.qea) and return it under a `geometry` field aligned by schema id with the resolved members. By default the EA model is never touched and no `geometry` field is returned; a missing EA model/diagram yields geometry.present=false, never an error.' },
     },
     additionalProperties: false,
   };
@@ -678,6 +679,50 @@ function buildIntentElementContext(context, args = {}) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Optional EA diagram GEOMETRY (opt-in, default off)
+// ---------------------------------------------------------------------------
+// getArchitectureViewContext is a canonical-graph read; it never touches the EA
+// model unless the caller explicitly sets includeEaGeometry=true. The workspace's
+// EA model (.qea, the SQLite carrier this toolchain can read) may hold human-laid-out
+// diagram geometry for a view — element boxes (t_diagramobjects rects) and connector
+// line paths (t_diagramlinks). When present it is returned under `geometry`, aligned
+// by schema id with the resolved members, so an image-capable LLM can redraw the view
+// faithfully. Absent model/diagram → present:false (never an error).
+const EA_GEOMETRY_MODEL_EXTENSIONS = new Set(['.qea']);
+function findEaGeometryModelPath(workspaceRoot) {
+  try {
+    const entries = fs.readdirSync(workspaceRoot, { withFileTypes: true });
+    const names = entries
+      .filter((entry) => entry.isFile() && EA_GEOMETRY_MODEL_EXTENSIONS.has(path.extname(entry.name).toLowerCase()))
+      .map((entry) => entry.name)
+      .sort();
+    return names.length > 0 ? path.join(workspaceRoot, names[0]) : null;
+  } catch {
+    return null;
+  }
+}
+function readEaViewGeometry(workspaceRoot, viewId) {
+  // Lazily require the .qea projection lib: it depends on node:sqlite (Node >= 22),
+  // so it is only loaded when geometry is actually requested, never for other calls.
+  let modelRel = null;
+  try {
+    const modelPath = findEaGeometryModelPath(workspaceRoot);
+    if (!modelPath) {
+      return { source: null, present: false, elements: [], relationships: [] };
+    }
+    modelRel = normalizeRelativePath(path.relative(workspaceRoot, modelPath)) || null;
+    const eaQeaLib = require('./ea-qea-sync-lib.js');
+    const geo = eaQeaLib.readViewDiagramGeometry(modelPath, viewId);
+    if (!geo) {
+      return { source: modelRel, present: false, elements: [], relationships: [] };
+    }
+    return { source: modelRel, present: true, elements: geo.elements, relationships: geo.relationships };
+  } catch {
+    return { source: modelRel, present: false, elements: [], relationships: [] };
+  }
+}
+
 function buildViewContext(context, args = {}) {
   const viewId = typeof args.view_id === 'string' ? args.view_id.trim() : '';
   if (!viewId) {
@@ -746,7 +791,7 @@ function buildViewContext(context, args = {}) {
     }
   }
 
-  return {
+  const result = {
     status: 'passed',
     graphPath: context.graphPath.relativePath,
     view: clone(view),
@@ -757,6 +802,10 @@ function buildViewContext(context, args = {}) {
     parentElement,
     childViews,
   };
+  if (args.includeEaGeometry === true) {
+    result.geometry = readEaViewGeometry(context.workspaceRoot, viewId);
+  }
+  return result;
 }
 
 function resolveFocusElement(document, args) {
@@ -1844,11 +1893,11 @@ function summarizeDocument(document) {
   };
 }
 
-// --- WP2791: post-canonical-write .qea projection (parallel to Neo4j sync, non-fatal) ---
-// Target resolution (decision qea-full-wholefile-argo-scripts-no-config): env ARGO_EA_QEA >
-// the single *.qea at the workspace root (0/many -> no-op with an explicit log). NO config file.
-// Projection script runs from argo/scripts (same package as the MCP runtime), so a workspace
-// does not need to ship its own projection script (bundled argo/scripts module).
+// --- WP2791: post-canonical-write .qea projection (parallel to Neo4j sync, non-fatal) ---
+// Target resolution (decision qea-full-wholefile-argo-scripts-no-config): env ARGO_EA_QEA >
+// the single *.qea at the workspace root (0/many -> no-op with an explicit log). NO config file.
+// Projection script runs from argo/scripts (same package as the MCP runtime), so a workspace
+// does not need to ship its own projection script (bundled argo/scripts module).
 function resolveQeaProjectionTarget(context) {
   const none = (reason, hasEaSignals) => ({ target: null, reason, hasEaSignals: !!hasEaSignals });
   try {
@@ -1889,34 +1938,34 @@ function resolveQeaProjectionTarget(context) {
     console.log('[ea-qea] projection target resolution failed: ' + String(error && error.message ? error.message : error));
     return none('EA .qea target resolution failed: ' + String(error && error.message ? error.message : error), true);
   }
-}
-
-function runQeaProjection(target) {
-  return new Promise((resolve) => {
-    const script = path.join(__dirname, 'ea-qea-sync.js');
-    if (!fs.existsSync(script)) {
-      resolve({ ok: false, error: 'argo/scripts/ea-qea-sync.js missing', ms: 0 });
-      return;
-    }
-    const snapshotDir = path.join(target.workspaceRoot, '.argo', 'temp', 'qea-backups');
-    const args = [script, '--mode', 'sync', '--graph', target.graphPath, '--qea', target.qeaPath, '--snapshot-dir', snapshotDir];
-    const started = Date.now();
-    let stderr = '';
-    let child;
-    try {
-      child = spawn(process.execPath, args, { cwd: target.workspaceRoot, windowsHide: true });
-    } catch (error) {
-      resolve({ ok: false, error: String(error && error.message ? error.message : error), ms: Date.now() - started });
-      return;
-    }
-    child.stderr.on('data', (d) => { stderr += String(d); });
-    child.on('error', (err) => resolve({ ok: false, error: String(err && err.message ? err.message : err), ms: Date.now() - started, stderr: stderr.slice(0, 600) }));
-    child.on('close', (code) => {
-      resolve({ ok: code === 0, code, ms: Date.now() - started, stderr: stderr.slice(0, 600) });
-    });
-  });
-}
-
+}
+
+function runQeaProjection(target) {
+  return new Promise((resolve) => {
+    const script = path.join(__dirname, 'ea-qea-sync.js');
+    if (!fs.existsSync(script)) {
+      resolve({ ok: false, error: 'argo/scripts/ea-qea-sync.js missing', ms: 0 });
+      return;
+    }
+    const snapshotDir = path.join(target.workspaceRoot, '.argo', 'temp', 'qea-backups');
+    const args = [script, '--mode', 'sync', '--graph', target.graphPath, '--qea', target.qeaPath, '--snapshot-dir', snapshotDir];
+    const started = Date.now();
+    let stderr = '';
+    let child;
+    try {
+      child = spawn(process.execPath, args, { cwd: target.workspaceRoot, windowsHide: true });
+    } catch (error) {
+      resolve({ ok: false, error: String(error && error.message ? error.message : error), ms: Date.now() - started });
+      return;
+    }
+    child.stderr.on('data', (d) => { stderr += String(d); });
+    child.on('error', (err) => resolve({ ok: false, error: String(err && err.message ? err.message : err), ms: Date.now() - started, stderr: stderr.slice(0, 600) }));
+    child.on('close', (code) => {
+      resolve({ ok: code === 0, code, ms: Date.now() - started, stderr: stderr.slice(0, 600) });
+    });
+  });
+}
+
 function writeGraph(graphPath, document) {
   const tempPath = `${graphPath}.${process.pid}.${Date.now()}.tmp`;
   fs.writeFileSync(tempPath, `${JSON.stringify(document, null, 2)}\n`, 'utf8');

package/package.json

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