archgraph-argo 0.10.52 → 0.12.0

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

@@ -1,7 +1,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const readline = require('node:readline');
-const { AsyncLocalStorage } = require('node:async_hooks');
+const { AsyncLocalStorage } = require('node:async_hooks');
+const { spawnSync } = require('node:child_process');
 
 const validatorMcp = require('./validator-mcp-server.js');
 const systemArchitectureMcp = require('./systemarchitecture-mcp-server.js');
@@ -395,7 +396,8 @@ async function callTool(name, args = {}, progressToken = null, dependencies = un
       mcp: report.mcp,
       systemArchitecture: report.systemArchitecture,
       subdiagramViews: report.subdiagramViews,
-      neo4j: report.neo4j,
+      neo4j: report.neo4j,
+      qeaFullProjection: workspace.qeaFullProjection,
       semanticLifecycle: report.semanticLifecycle,
       semanticState: report.semanticLifecycle && report.semanticLifecycle.state,
       alignment: report.semanticLifecycle && report.semanticLifecycle.alignment,
@@ -418,6 +420,48 @@ async function withCanonicalSemanticInitTestComposition(composition, callback) {
   return canonicalSemanticInitStorage.run(Object.freeze({ ...composition }), callback);
 }
 
+function resolveQeaProjectionTarget(workspaceRoot) {
+  try {
+    if (!workspaceRoot || !fs.existsSync(workspaceRoot)) { return null; }
+    const pick = (p) => (p && fs.existsSync(p) ? path.resolve(p) : null);
+    const qeaPath = pick(process.env.ARGO_EA_QEA);
+    if (qeaPath) { return { qeaPath, workspaceRoot }; }
+    let qeas = [];
+    try { qeas = fs.readdirSync(workspaceRoot).filter((n) => n.toLowerCase().endsWith('.qea')); } catch { /* ignore */ }
+    if (qeas.length === 1) { return { qeaPath: path.resolve(workspaceRoot, qeas[0]), workspaceRoot }; }
+    console.log('[ea-qea] init projection target: none' + (qeas.length > 1 ? ' (' + qeas.length + ' *.qea found; expected exactly one or ARGO_EA_QEA)' : '') + ' in ' + workspaceRoot);
+    return null;
+  } catch (error) {
+    console.log('[ea-qea] init projection target resolution failed: ' + String(error && error.message ? error.message : error));
+    return null;
+  }
+}
+
+// argo init .qea FULL projection (mirrors Neo4j initial full sync): wipes the whole target
+// .qea then rebuilds it purely from the canonical graph. Non-fatal by contract.
+function runQeaFullProjection(workspaceRoot, graphTargetPath) {
+  const target = resolveQeaProjectionTarget(workspaceRoot);
+  const script = path.join(__dirname, 'ea-qea-sync.js');
+  if (!target || !fs.existsSync(script)) {
+    return { status: 'noop', reason: !target ? 'no .qea target (env ARGO_EA_QEA or exactly one root *.qea)' : 'argo/scripts/ea-qea-sync.js missing' };
+  }
+  const snapshotDir = path.join(workspaceRoot, '.argo', 'temp', 'qea-backups');
+  const args = [script, '--mode', 'full', '--graph', graphTargetPath, '--qea', target.qeaPath, '--snapshot-dir', snapshotDir];
+  const started = Date.now();
+  try {
+    const res = spawnSync(process.execPath, args, { cwd: workspaceRoot, encoding: 'utf8', windowsHide: true, timeout: 120000 });
+    const ok = res.status === 0;
+    return {
+      status: ok ? 'ok' : 'failed',
+      qea: target.qeaPath,
+      ms: Date.now() - started,
+      ...(ok ? {} : { error: String((res.stderr || '').slice(0, 600) || ('exit ' + res.status)) }),
+    };
+  } catch (error) {
+    return { status: 'failed', qea: target.qeaPath, ms: Date.now() - started, error: String(error && error.message ? error.message : error) };
+  }
+}
+
 async function initializeWorkspace(workspaceRoot) {
   const workspaceName = path.basename(workspaceRoot);
   const createdFiles = [];
@@ -454,8 +498,17 @@ async function initializeWorkspace(workspaceRoot) {
     }
   }
 
+  // WP2791: init .qea FULL projection (parallel to Neo4j initial full sync in the harness
+  // report). Non-fatal: a qea failure must never fail workspace init.
+  let qeaFullProjection = null;
+  try {
+    qeaFullProjection = runQeaFullProjection(workspaceRoot, graphTargetPath);
+  } catch (error) {
+    qeaFullProjection = { status: 'failed', error: String(error && error.message ? error.message : error) };
+  }
   return {
-    workspaceRoot,
+    workspaceRoot,
+    qeaFullProjection,
     targetFeapName,
     createdFiles,
     updatedFiles,

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

@@ -0,0 +1,688 @@
+'use strict';
+
+// EA .qea (SQLite) direct projection library — WP2791.
+// Zero third-party deps: node:sqlite (DatabaseSync, Node >=22/24), node:crypto, node:fs.
+// Mirrors the ArchiMate->EA mapping conventions of eatool/EA-jsscript/import-from-kg.js
+// (Object_Type base + Stereotype archimate name + Alias/ea_guid anchors + schema_view_id
+// StyleEx token) while writing through SQLite directly (no EA COM required).
+//
+// Concurrency model:
+//   - PRAGMA busy_timeout = 15000 set on every connection; write phases wrapped in short
+//     transactions with a bounded busy retry. Keep EA's own SQLite handle open is fine —
+//     SQLite only locks during active transactions, an idle open connection does not block.
+//   - Rows are matched by Alias (schema id) / deterministic ea_guid, update-in-place only;
+//     existing t_diagramobjects/t_diagramlinks geometry is NEVER updated or deleted, only
+//     missing members are INSERTed.
+
+const { DatabaseSync } = require('node:sqlite');
+const DEBUG = !!process.env.EA_QEA_DEBUG;
+const crypto = require('node:crypto');
+
+const SYNC_PACKAGE_NAME = 'ArchGraph Sync';
+const DIAGRAM_TYPE = 'Logical';
+const META_TABLE = 'kg_sync_meta'; // {kind,key,sha,payload} — Node export/reconcile store
+const BUSY_TIMEOUT_MS = 15000;
+const CHUNK = 200;
+
+// ---------------------------------------------------------------------------
+// ArchiMate -> EA mapping (mirrors import-from-kg.js)
+// ---------------------------------------------------------------------------
+function normalizeName(value) {
+  const text = String(value === null || value === undefined ? '' : value);
+  return text.replace(/^ArchiMate[_\s-]*/i, '');
+}
+function alnum(value) {
+  return String(value === null || value === undefined ? '' : value)
+    .replace(/&/g, '')
+    .replace(/[^A-Za-z0-9]/g, '');
+}
+function elementStereotype(type) {
+  const norm = alnum(normalizeName(type));
+  if (norm === '') { return ''; }
+  if (norm === 'SystemSoftware') { return 'ArchiMate_SystemSoftware'; }
+  if (norm === 'Constraint') { return 'ArchiMate_Constraint'; }
+  return norm;
+}
+const ACTIVITY_ALNUM = new Set([
+  'BusinessEvent', 'BusinessProcess', 'BusinessFunction', 'BusinessInteraction',
+  'BusinessService', 'ApplicationEvent', 'ApplicationProcess', 'ApplicationFunction',
+  'ApplicationInteraction', 'ApplicationService', 'TechnologyEvent',
+  'TechnologyProcess', 'TechnologyFunction', 'TechnologyInteraction',
+  'TechnologyService', 'ValueStream',
+]);
+function elementObjectType(type) {
+  const norm = alnum(normalizeName(type));
+  if (norm === 'ApplicationComponent') { return 'Component'; }
+  if (ACTIVITY_ALNUM.has(norm)) { return 'Activity'; }
+  if (norm === 'Junction' || norm === 'AndJunction' || norm === 'OrJunction') { return 'StateNode'; }
+  return 'Class';
+}
+function canonicalArchimateType(type) {
+  const norm = alnum(normalizeName(type));
+  return norm; // full ArchiMate name e.g. BusinessActor is carried by Stereotype column
+}
+function relStereotype(type) {
+  return alnum(normalizeName(type));
+}
+function relationshipMap(type) {
+  const norm = alnum(normalizeName(type));
+  const meta = { connectorType: 'Association', directed: false };
+  switch (norm) {
+    case 'Composition':
+    case 'Aggregation':
+      meta.connectorType = 'Association';
+      break;
+    case 'Specialization':
+      meta.connectorType = 'Generalization';
+      meta.directed = true;
+      break;
+    case 'Realization':
+    case 'Access':
+      meta.connectorType = 'Dependency';
+      meta.directed = true;
+      break;
+    case 'Serving':
+    case 'Assignment':
+      meta.connectorType = 'Association';
+      meta.directed = true;
+      break;
+    case 'Association':
+      meta.connectorType = 'Association';
+      break;
+    case 'Triggering':
+    case 'Flow':
+    case 'Influence':
+      meta.connectorType = 'ControlFlow';
+      meta.directed = true;
+      break;
+    default:
+      meta.connectorType = 'Association';
+      break;
+  }
+  return meta;
+}
+function safeName(name, fallbackId) {
+  const n = String(name === null || name === undefined ? '' : name).trim();
+  return n !== '' ? n : String(fallbackId === null || fallbackId === undefined ? '' : fallbackId);
+}
+function deterministicGuid(seed) {
+  const h = crypto.createHash('sha1').update(String(seed)).digest('hex');
+  return '{' + h.slice(0, 8) + '-' + h.slice(8, 12) + '-' + h.slice(12, 16) + '-' + h.slice(16, 20) + '-' + h.slice(20, 32) + '}';
+}
+function sha1(text) {
+  return crypto.createHash('sha1').update(String(text)).digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// sqlite helpers
+// ---------------------------------------------------------------------------
+function openQea(file) {
+  const db = new DatabaseSync(file);
+  db.exec('PRAGMA busy_timeout=' + BUSY_TIMEOUT_MS);
+  db.exec('PRAGMA foreign_keys=OFF');
+  return db;
+}
+function columnNames(db, table) {
+  const rows = db.prepare('PRAGMA table_info(' + table + ')').all();
+  return rows.map((r) => r.name);
+}
+function ensureMetaTable(db) {
+  db.exec('CREATE TABLE IF NOT EXISTS ' + META_TABLE + ' (kind TEXT NOT NULL, key TEXT NOT NULL, sha TEXT, payload TEXT, PRIMARY KEY(kind,key))');
+}
+// multi-row INSERT with positional placeholders, chunked
+function insertMany(db, table, columns, rows) {
+  let inserted = 0;
+  if (!rows || rows.length === 0) { return 0; }
+  for (let i = 0; i < rows.length; i += CHUNK) {
+    const chunk = rows.slice(i, i + CHUNK);
+    const colSql = columns.join(', ');
+    const valueSql = chunk.map(() => '(' + columns.map(() => '?').join(', ') + ')').join(', ');
+    const sql = 'INSERT INTO ' + table + ' (' + colSql + ') VALUES ' + valueSql;
+    const params = [];
+    for (const r of chunk) { for (const c of columns) { params.push(r[c]); } }
+    db.prepare(sql).run(...params);
+    inserted += chunk.length;
+  }
+  return inserted;
+}
+function updateRow(db, table, setColumns, whereColumn, id, values) {
+  const setSql = setColumns.map((c) => c + '=?').join(', ');
+  db.prepare('UPDATE ' + table + ' SET ' + setSql + ' WHERE ' + whereColumn + '=?')
+    .run(...setColumns.map((c) => values[c]), id);
+}
+function upsertMeta(db, kind, key, node) {
+  const payload = JSON.stringify(node);
+  const sh = sha1(payload);
+  db.prepare('INSERT INTO ' + META_TABLE + ' (kind,key,sha,payload) VALUES (?,?,?,?) ON CONFLICT(kind,key) DO UPDATE SET sha=excluded.sha, payload=excluded.payload')
+    .run(kind, String(key), sh, payload);
+  return sh;
+}
+function readMetaKind(db, kind) {
+  const rows = db.prepare('SELECT key, payload FROM ' + META_TABLE + ' WHERE kind=? ORDER BY key').all(kind);
+  const out = [];
+  for (const r of rows) { try { out.push(JSON.parse(r.payload)); } catch { /* skip corrupt */ } }
+  return out;
+}
+// mark checkpoints
+function nowMs() { return Date.now(); }
+
+// ---------------------------------------------------------------------------
+// Package anchoring
+// ---------------------------------------------------------------------------
+function resolveSyncPackage(db, dryRun) {
+  let roots = db.prepare('SELECT Package_ID FROM t_package WHERE Parent_ID=0 ORDER BY Package_ID').all();
+  if (roots.length === 0) { roots = db.prepare('SELECT Package_ID FROM t_package ORDER BY Package_ID LIMIT 1').all(); }
+  const rootId = Number(roots[0].Package_ID);
+  let existing = db.prepare('SELECT Package_ID, Name FROM t_package WHERE Parent_ID=? AND Name=?').get(rootId, SYNC_PACKAGE_NAME);
+  if (existing) { return { rootId, packageId: Number(existing.Package_ID), created: false }; }
+  if (dryRun) { return { rootId, packageId: 0, created: true }; }
+  const guid = deterministicGuid('pkg:' + SYNC_PACKAGE_NAME);
+  const r = db.prepare('INSERT INTO t_package (Name, Parent_ID, ea_guid, Notes) VALUES (?,?,?,?)').run(SYNC_PACKAGE_NAME, rootId, guid, '');
+  return { rootId, packageId: Number(r.lastInsertRowid), created: true };
+}
+function parseStyleToken(styleEx, key) {
+  const text = String(styleEx === null || styleEx === undefined ? '' : styleEx);
+  const re = new RegExp('(^|;|\\s)' + key + '=([^;]*)', 'i');
+  const m = re.exec(text);
+  return m ? m[2] : '';
+}
+
+// ---------------------------------------------------------------------------
+// Core sync
+// ---------------------------------------------------------------------------
+// opts: { dryRun, allowDelete, snapshotDir }
+function syncGraphToQea(graph, qeaPath, opts) {
+  const o = opts || {};
+  const stages = {};
+  const stats = {
+    added: { elements: 0, relationships: 0, diagrams: 0, diagramObjects: 0, diagramLinks: 0 },
+    updated: { elements: 0, relationships: 0, diagrams: 0 },
+    skipped: { elements: 0, relationships: 0, diagrams: 0 },
+    deleteCandidates: 0, deleted: 0,
+  };
+  const t0 = nowMs();
+  const db = openQea(qeaPath);
+  try {
+    ensureMetaTable(db);
+    if (!o.dryRun) { db.exec('BEGIN IMMEDIATE'); }
+    stages.package = nowMs();
+
+    const syncPkg = resolveSyncPackage(db, o.dryRun);
+    const syncId = syncPkg.packageId;
+    stats.syncPackageId = syncId;
+
+    // --- elements ---------------------------------------------------------
+    const elemById = new Map();
+    for (const e of graph.elements || []) { if (e && e.id !== undefined && e.id !== null) { elemById.set(String(e.id), e); } }
+    const existingElems = db.prepare(
+      'SELECT Object_ID, Alias, ea_guid, Object_Type, Name, Stereotype, Note, Status, Package_ID, ParentID FROM t_object WHERE Package_ID=?').all(syncId);
+    const elemByAlias = new Map();
+    const elemByGuid = new Map();
+    for (const row of existingElems) {
+      if (row.Alias) { elemByAlias.set(String(row.Alias), row); }
+      if (row.ea_guid) { elemByGuid.set(String(row.ea_guid), row); }
+    }
+    const newElems = [];
+    const parentOf = {};
+    for (const e of graph.elements || []) {
+      if (!e || e.id === undefined || e.id === null) { continue; }
+      const alias = String(e.id);
+      const guid = deterministicGuid('el:' + alias);
+      const existing = elemByAlias.get(alias) || elemByGuid.get(guid) || null;
+      const parentId = e.parent !== undefined && e.parent !== null && String(e.parent) !== '0' && elemById.has(String(e.parent)) ? parentOf[String(e.parent)] || 0 : 0;
+      const intended = {
+        Object_Type: elementObjectType(e.type),
+        Name: safeName(e.name, alias),
+        Stereotype: elementStereotype(e.type),
+        Note: String(e.description === null || e.description === undefined ? '' : e.description),
+        Status: String(e.status === null || e.status === undefined ? 'Proposed' : e.status),
+        ParentID: parentId || 0,
+      };
+      if (existing) {
+        const changed = intended.Object_Type !== existing.Object_Type || intended.Name !== existing.Name ||
+          (intended.Stereotype || '') !== (existing.Stereotype || '') || intended.Note !== (existing.Note || '') ||
+          (intended.Status || '') !== (existing.Status || '') || Number(intended.ParentID) !== Number(existing.ParentID || 0);
+        if (changed && !o.dryRun) {
+          updateRow(db, 't_object', ['Name', 'Stereotype', 'Note', 'Status', 'ParentID'], 'Object_ID', Number(existing.Object_ID), intended);
+        }
+        stats[changed ? 'updated' : 'skipped'].elements++;
+        parentOf[alias] = Number(existing.Object_ID);
+      } else {
+        newElems.push({ ...intended, Alias: alias, ea_guid: guid, Package_ID: syncId });
+        stats.added.elements++;
+      }
+    }
+    // batch insert new elements (ParentID refined below) then read ids
+    if (newElems.length > 0) {
+      if (!o.dryRun) {
+        insertMany(db, 't_object', ['Object_Type', 'Name', 'Stereotype', 'Note', 'Status', 'Alias', 'ea_guid', 'Package_ID', 'ParentID'], newElems);
+      }
+      for (const row of newElems) { parentOf[row.Alias] = row.Alias; } // placeholder; resolved by readback
+    }
+    // resolve real Object_ID for new elements + parents
+    const aliasToId = new Map();
+    if (!o.dryRun) {
+      const aliases = newElems.map((r) => r.Alias);
+      const readback = [];
+      for (let i = 0; i < aliases.length; i += 200) {
+        const part = aliases.slice(i, i + 200);
+        const marks = part.map(() => '?').join(',');
+        const rows = db.prepare('SELECT Object_ID, Alias FROM t_object WHERE Alias IN (' + marks + ')').all(...part);
+        readback.push(...rows);
+      }
+      for (const r of readback) { aliasToId.set(String(r.Alias), Number(r.Object_ID)); }
+    } else {
+      for (const r of newElems) { aliasToId.set(r.Alias, -1); }
+    }
+    // second pass: set ParentID where the parent is a new element
+    if (newElems.length > 0 && !o.dryRun) {
+      for (const e of graph.elements || []) {
+        if (!e || e.id === undefined || e.id === null) { continue; }
+        const alias = String(e.id);
+        const pid = aliasToId.get(alias);
+        if (pid === undefined) { continue; }
+        const parentNode = e.parent !== undefined && e.parent !== null && elemById.get(String(e.parent)) ? elemById.get(String(e.parent)) : null;
+        if (!parentNode) { continue; }
+        const parentRowId = (function () {
+          const a = String(e.parent);
+          const ex = elemByAlias.get(a) || elemByGuid.get(deterministicGuid('el:' + a));
+          if (ex) { return Number(ex.Object_ID); }
+          return aliasToId.get(a);
+        })();
+        if (parentRowId && Number(parentRowId) !== pid) {
+          db.prepare('UPDATE t_object SET ParentID=? WHERE Object_ID=?').run(Number(parentRowId), pid);
+        }
+      }
+    }
+    stages.elements = nowMs();
+
+    // element anchors + meta (idempotent, fingerprint-skipped)
+    let tagStats = { propsNew: 0, propsSkip: 0 };
+    if (!o.dryRun) {
+      // minimal EA-facing anchors for compatibility with the legacy object-model exporter
+      const anchorRows = [];
+      const elemIdByAliasFinal = new Map();
+      for (const ex of existingElems) { elemIdByAliasFinal.set(String(ex.Alias), Number(ex.Object_ID)); }
+      for (const [a, id] of aliasToId) { elemIdByAliasFinal.set(a, id); }
+      const toTag = [];
+      for (const e of graph.elements || []) {
+        if (!e || e.id === undefined || e.id === null) { continue; }
+        const id = elemIdByAliasFinal.get(String(e.id));
+        if (id === undefined) { continue; }
+        toTag.push({ id: Number(id), e });
+      }
+      const metaNew = [];
+      const propsToWrite = [];
+      for (const t of toTag) {
+        const sh = upsertMeta(db, 'element', t.e.id, t.e);
+        metaNew.push(1);
+        propsToWrite.push([t.id, 'schema_id', t.e.id]);
+        propsToWrite.push([t.id, 'archimate_type', canonicalArchimateType(t.e.type)]);
+      }
+      if (propsToWrite.length > 0) {
+        const existingProps = new Set();
+        for (let i = 0; i < propsToWrite.length; i += 200) {
+          const part = propsToWrite.slice(i, i + 200);
+          const ids = new Set(part.map((p) => p[0]));
+          const marks = Array.from(ids).map(() => '?').join(',');
+          const rows = db.prepare('SELECT Object_ID, Property FROM t_objectproperties WHERE Object_ID IN (' + marks + ')').all(...Array.from(ids));
+          for (const r of rows) { existingProps.add(Number(r.Object_ID) + '|' + r.Property); }
+        }
+        const newProps = propsToWrite.filter((p) => !existingProps.has(p[0] + '|' + p[1]));
+        if (newProps.length > 0) {
+          insertMany(db, 't_objectproperties', ['Object_ID', 'Property', 'Value', 'Notes'], newProps.map((p) => ({ Object_ID: p[0], Property: p[1], Value: p[2], Notes: '' })));
+          tagStats.propsNew += newProps.length;
+        }
+        tagStats.propsSkip = propsToWrite.length - newProps.length;
+      }
+    }
+    stages.elemTags = nowMs();
+
+    // --- relationships -----------------------------------------------------
+    const elemIdByAliasAll = new Map();
+    for (const ex of existingElems) { if (ex.Alias) { elemIdByAliasAll.set(String(ex.Alias), Number(ex.Object_ID)); } }
+    if (!o.dryRun) { for (const [a, id] of aliasToId) { elemIdByAliasAll.set(a, id); } }
+    const relByGuid = new Map();
+    const existingRels = db.prepare('SELECT Connector_ID, ea_guid, Name, Connector_Type, Stereotype, Notes, Direction, Start_Object_ID, End_Object_ID FROM t_connector').all();
+    for (const r of existingRels) { if (r.ea_guid) { relByGuid.set(String(r.ea_guid), r); } }
+    const newRels = [];
+    for (const rel of graph.relationships || []) {
+      if (!rel || rel.id === undefined || rel.id === null) { continue; }
+      const alias = String(rel.id);
+      const guid = deterministicGuid('rel:' + alias);
+      const start = elemIdByAliasAll.get(String(rel.source_id));
+      const end = elemIdByAliasAll.get(String(rel.target_id));
+      if (start === undefined || end === undefined) { continue; }
+      const map = relationshipMap(rel.type);
+      const direction = map.directed ? 'Source -> Destination' : '';
+      const existing = relByGuid.get(guid);
+      const intended = {
+        Name: safeName(rel.name, alias),
+        Connector_Type: map.connectorType,
+        Stereotype: relStereotype(rel.type),
+        Notes: String(rel.description === null || rel.description === undefined ? '' : rel.description),
+        Direction: direction,
+        Start_Object_ID: Number(start),
+        End_Object_ID: Number(end),
+      };
+      if (existing) {
+        const changed = intended.Name !== (existing.Name || '') || (intended.Connector_Type || '') !== (existing.Connector_Type || '') ||
+          (intended.Stereotype || '') !== (existing.Stereotype || '') || intended.Notes !== (existing.Notes || '') ||
+          intended.Direction !== (existing.Direction || '') || Number(intended.Start_Object_ID) !== Number(existing.Start_Object_ID || 0) ||
+          Number(intended.End_Object_ID) !== Number(existing.End_Object_ID || 0);
+        if (changed && !o.dryRun) {
+          updateRow(db, 't_connector', ['Name', 'Connector_Type', 'Stereotype', 'Notes', 'Direction', 'Start_Object_ID', 'End_Object_ID'], 'Connector_ID', Number(existing.Connector_ID), intended);
+        }
+        stats[changed ? 'updated' : 'skipped'].relationships++;
+      } else {
+        newRels.push({ ...intended, ea_guid: guid, _alias: alias });
+        stats.added.relationships++;
+      }
+    }
+    const relAliasToId = new Map();
+    if (!o.dryRun) {
+      if (newRels.length > 0) {
+        insertMany(db, 't_connector', ['Name', 'Connector_Type', 'Stereotype', 'Notes', 'Direction', 'Start_Object_ID', 'End_Object_ID', 'ea_guid'], newRels);
+      }
+      for (let i = 0; i < newRels.length; i += 200) {
+        const part = newRels.slice(i, i + 200);
+        const marks = part.map(() => '?').join(',');
+        const rows = db.prepare('SELECT Connector_ID, ea_guid FROM t_connector WHERE ea_guid IN (' + marks + ')').all(...part.map((r) => r.ea_guid));
+        for (const r of rows) { const pr = part.find((x) => x.ea_guid === r.ea_guid); if (pr) { relAliasToId.set(pr._alias, Number(r.Connector_ID)); } }
+      }
+    } else {
+      for (const r of newRels) { relAliasToId.set(r._alias, -1); }
+    }
+    stages.relationships = nowMs();
+
+    // connector anchors + meta
+    if (!o.dryRun) {
+      for (const rel of graph.relationships || []) {
+        if (!rel || rel.id === undefined || rel.id === null) { continue; }
+        const id = relAliasToId.get(String(rel.id));
+        if (id === undefined || id < 0) { continue; }
+        upsertMeta(db, 'relationship', rel.id, rel);
+        const existingCt = db.prepare('SELECT PropertyID FROM t_connectortag WHERE ElementID=? AND Property=?').get(Number(id), 'schema_id');
+        if (!existingCt) {
+          db.prepare('INSERT INTO t_connectortag (ElementID, Property, VALUE, NOTES) VALUES (?,?,?,?)')
+            .run(Number(id), 'schema_id', rel.id, '');
+          db.prepare('INSERT INTO t_connectortag (ElementID, Property, VALUE, NOTES) VALUES (?,?,?,?)')
+            .run(Number(id), 'archimate_relationship_type', canonicalArchimateType(rel.type), '');
+        }
+      }
+    }
+    stages.relTags = nowMs();
+
+    // --- views/diagrams ----------------------------------------------------
+    const existingDiags = db.prepare('SELECT Diagram_ID, Package_ID, Name, StyleEx, ea_guid FROM t_diagram WHERE Package_ID=?').all(syncId);
+    const diagByView = new Map();
+    for (const d of existingDiags) {
+      const v = parseStyleToken(d.StyleEx, 'schema_view_id');
+      if (v) { diagByView.set(v, d); }
+    }
+    const newDiags = [];
+    for (const view of graph.views || []) {
+      if (!view || view.view_id === undefined || view.view_id === null) { continue; }
+      const viewId = String(view.view_id);
+      const styleEx = 'schema_view_id=' + viewId + ';';
+      const parentObjectId = (function () {
+        if (view.parent_element_id !== undefined && view.parent_element_id !== null && view.parent_element_id !== '') {
+          const pid = elemIdByAliasAll.get(String(view.parent_element_id));
+          if (pid !== undefined) { return pid; }
+        }
+        return 0;
+      })();
+      const existing = diagByView.get(viewId);
+      const intended = {
+        Name: safeName(view.view_name, viewId),
+        Diagram_Type: DIAGRAM_TYPE,
+        Package_ID: syncId,
+        ParentID: parentObjectId,
+        Notes: '', // EA .qea 不保留多段 Notes；视图内容经 kg_sync_meta 保真
+        StyleEx: styleEx,
+      };
+      if (existing) {
+        const changed = intended.Name !== (existing.Name || '');
+        if (DEBUG && changed) { console.error('DEBUG diagram chg', viewId, JSON.stringify({n:[intended.Name,(existing.Name||'')], notes:[intended.Notes,(existing.Notes||'')]})); }
+        if (changed && !o.dryRun) {
+          updateRow(db, 't_diagram', ['Name'], 'Diagram_ID', Number(existing.Diagram_ID), intended);
+        }
+        stats[changed ? 'updated' : 'skipped'].diagrams++;
+      } else {
+        newDiags.push({ ...intended, ea_guid: deterministicGuid('diag:' + viewId) });
+        stats.added.diagrams++;
+      }
+    }
+    const diagAliasToId = new Map();
+    if (!o.dryRun) {
+      if (newDiags.length > 0) {
+        insertMany(db, 't_diagram', ['Name', 'Diagram_Type', 'Package_ID', 'ParentID', 'StyleEx', 'ea_guid'], newDiags);
+      }
+      for (let i = 0; i < newDiags.length; i += 200) {
+        const part = newDiags.slice(i, i + 200);
+        const marks = part.map(() => '?').join(',');
+        const rows = db.prepare('SELECT Diagram_ID, StyleEx FROM t_diagram WHERE StyleEx IN (' + marks + ')').all(...part.map((d) => d.StyleEx));
+        for (const r of rows) {
+          const v = parseStyleToken(r.StyleEx, 'schema_view_id');
+          if (v) { diagAliasToId.set(v, Number(r.Diagram_ID)); }
+        }
+      }
+    } else {
+      for (const d of newDiags) { diagAliasToId.set(parseStyleToken(d.StyleEx, 'schema_view_id'), -1); }
+    }
+    // view meta
+    if (!o.dryRun) {
+      for (const view of graph.views || []) {
+        if (view && view.view_id !== undefined && view.view_id !== null) { upsertMeta(db, 'view', view.view_id, view); }
+      }
+    }
+    // memberships: only INSERT missing; never touch existing geometry
+    for (const view of graph.views || []) {
+      if (!view || view.view_id === undefined || view.view_id === null) { continue; }
+      const viewId = String(view.view_id);
+      let dId = diagByView.get(viewId);
+      if (!dId) { dId = diagAliasToId.get(viewId); }
+      if (!dId) { continue; }
+      const diagramId = Number(dId.Diagram_ID !== undefined ? dId.Diagram_ID : dId);
+      const placedObjs = new Set();
+      const objs = db.prepare('SELECT Object_ID FROM t_diagramobjects WHERE Diagram_ID=?').all(diagramId);
+      for (const r of objs) { placedObjs.add(Number(r.Object_ID)); }
+      const nextSeq = objs.length;
+      const newObjs = [];
+      const incl = view.included_elements || [];
+      let seq = nextSeq;
+      for (const elId of incl) {
+        const oid = elemIdByAliasAll.get(String(elId));
+        if (oid === undefined) { continue; }
+        if (placedObjs.has(Number(oid))) { continue; }
+        const col = seq % 6;
+        const row = Math.floor(seq / 6);
+        newObjs.push({
+          Diagram_ID: diagramId, Object_ID: Number(oid),
+          RectLeft: 40 + col * 260, RectTop: 40 + row * 160,
+          RectRight: 40 + col * 260 + 180, RectBottom: 40 + row * 160 + 90,
+          Sequence: seq,
+        });
+        seq++;
+      }
+      if (newObjs.length > 0 && !o.dryRun) {
+        insertMany(db, 't_diagramobjects', ['Diagram_ID', 'Object_ID', 'RectLeft', 'RectTop', 'RectRight', 'RectBottom', 'Sequence'], newObjs);
+      }
+      stats.added.diagramObjects += newObjs.length;
+
+      const placedLinks = new Set();
+      const links = db.prepare('SELECT ConnectorID FROM t_diagramlinks WHERE DiagramID=?').all(diagramId);
+      for (const r of links) { placedLinks.add(Number(r.ConnectorID)); }
+      const newLinks = [];
+      for (const relId of view.included_relationships || []) {
+        const cid = relAliasToId.get(String(relId));
+        if (cid === undefined || cid < 0) { continue; }
+        if (placedLinks.has(Number(cid))) { continue; }
+        newLinks.push({ DiagramID: diagramId, ConnectorID: Number(cid), Style: '', Geometry: '' });
+      }
+      if (newLinks.length > 0 && !o.dryRun) {
+        insertMany(db, 't_diagramlinks', ['DiagramID', 'ConnectorID', 'Style', 'Geometry'], newLinks);
+      }
+      stats.added.diagramLinks += newLinks.length;
+    }
+    stages.members = nowMs();
+
+    // --- deletion reconcile (opt-in) ---------------------------------------
+    const keepAliases = new Set();
+    for (const e of graph.elements || []) { if (e && e.id !== undefined) { keepAliases.add(String(e.id)); } }
+    for (const rel of graph.relationships || []) { if (rel && rel.id !== undefined) { keepAliases.add(String(rel.id)); } }
+    const candidates = [];
+    for (const row of existingElems) {
+      if (row.Alias && !keepAliases.has(String(row.Alias))) { candidates.push({ type: 'element', id: Number(row.Object_ID), alias: row.Alias }); }
+    }
+    for (const row of existingRels) {
+      if (row.Alias && !keepAliases.has(String(row.Alias))) { candidates.push({ type: 'relationship', id: Number(row.Connector_ID), alias: row.Alias }); }
+    }
+    stats.deleteCandidates = candidates.length;
+    if (candidates.length > 0 && o.allowDelete && !o.dryRun) {
+      for (const c of candidates) {
+        if (c.type === 'relationship') {
+          db.prepare('DELETE FROM t_connector WHERE Connector_ID=?').run(c.id);
+        } else {
+          db.prepare('DELETE FROM t_diagramobjects WHERE Object_ID=?').run(c.id);
+          db.prepare('DELETE FROM t_objectproperties WHERE Object_ID=?').run(c.id);
+          db.prepare('DELETE FROM t_object WHERE Object_ID=?').run(c.id);
+        }
+        stats.deleted++;
+      }
+    }
+    stages.deletes = nowMs();
+    if (!o.dryRun) { db.exec('COMMIT'); }
+  } finally {
+    try { db.close(); } catch { /* ignore */ }
+  }
+  stats.ms = {
+    total: nowMs() - t0,
+    package: stages.package - t0,
+    elements: stages.elements - stages.package,
+    elemTags: stages.elemTags - stages.elements,
+    relationships: stages.relationships - stages.elemTags,
+    relTags: stages.relTags - stages.relationships,
+    views: stages.members - stages.relTags,
+    members: stages.members - stages.relTags,
+  };
+  return { ok: true, syncPackageId: stats.syncPackageId, stats };
+}
+
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Full projection (whole-file rebuild, decision qea-full-wholefile-argo-scripts-no-config):
+// wipe ALL existing content in the target .qea (every user table row, incl. kg_sync_meta),
+// re-seed the minimal root package, then rebuild the whole .qea purely from the canonical
+// graph. EA is treated as a projection: after full there is nothing but canonical content.
+// ---------------------------------------------------------------------------
+function wipeAllContent(db) {
+  const rows = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").all();
+  const cleared = {};
+  for (const r of rows) {
+    try {
+      const before = db.prepare('SELECT COUNT(*) AS c FROM "' + r.name + '"').get().c;
+      db.exec('DELETE FROM "' + r.name + '"');
+      cleared[r.name] = before;
+    } catch { /* skip locked/system tables */ }
+  }
+  try { db.exec('DELETE FROM sqlite_sequence'); } catch { /* ignore */ }
+  return cleared;
+}
+function ensureRootPackage(db) {
+  const roots = db.prepare('SELECT Package_ID FROM t_package WHERE Parent_ID=0 ORDER BY Package_ID').all();
+  if (roots.length > 0) { return Number(roots[0].Package_ID); }
+  const r = db.prepare('INSERT INTO t_package (Name, Parent_ID, ea_guid) VALUES (?,?,?)').run('Model', 0, deterministicGuid('pkg:Model'));
+  return Number(r.lastInsertRowid);
+}
+function verifyQeaCanonical(graph, qeaPath) {
+  let roundtrip = null;
+  try { roundtrip = require('../../tests/_ea-roundtrip-lib.js'); } catch { roundtrip = null; }
+  const exp = exportQeaToGraph(qeaPath);
+  const counts = {
+    elements: exp.elements.length, relationships: exp.relationships.length, views: exp.views.length,
+    sourceElements: (graph.elements || []).length,
+    sourceRelationships: (graph.relationships || []).length,
+    sourceViews: (graph.views || []).length,
+  };
+  let equal = counts.elements === counts.sourceElements && counts.relationships === counts.sourceRelationships && counts.views === counts.sourceViews;
+  let diffs = null;
+  if (roundtrip && typeof roundtrip.compareRoundtrip === 'function') {
+    const rep = roundtrip.compareRoundtrip(graph, exp, {});
+    equal = rep.equal;
+    diffs = { missing: rep.missingInExport.length, extra: rep.extraInExport.length, valueDiffs: rep.valueDiffs.length };
+  }
+  return { consistent: equal, diffs, counts };
+}
+function fullProjection(graph, qeaPath, opts) {
+  const o = opts || {};
+  const t0 = nowMs();
+  let wiped = null;
+  let db = null;
+  try {
+    db = openQea(qeaPath);
+    ensureMetaTable(db);
+    db.exec('BEGIN IMMEDIATE');
+    wiped = wipeAllContent(db);
+    ensureRootPackage(db);
+    db.exec('COMMIT');
+  } finally {
+    if (db) { try { db.close(); } catch { /* ignore */ } }
+  }
+  const sync = syncGraphToQea(graph, qeaPath, { dryRun: o.dryRun, allowDelete: false });
+  const verification = o.verify === false ? null : verifyQeaCanonical(graph, qeaPath);
+  return { ok: true, wiped, sync: sync.stats, verification, ms: { total: nowMs() - t0 } };
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+function exportQeaToGraph(qeaPath) {
+  const db = openQea(qeaPath);
+  try {
+    ensureMetaTable(db);
+    const elements = readMetaKind(db, 'element').filter((e) => e && e.id !== undefined);
+    const relationships = readMetaKind(db, 'relationship').filter((r) => r && r.id !== undefined);
+    const views = readMetaKind(db, 'view').filter((v) => v && v.view_id !== undefined);
+    return { name: 'ArchGraph (from archgraph.qea)', description: '', elements, relationships, views };
+  } finally {
+    db.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// snapshot
+// ---------------------------------------------------------------------------
+function snapshotQea(qeaPath, snapshotDir) {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  if (!fs.existsSync(qeaPath)) { return null; }
+  const dir = snapshotDir || path.dirname(qeaPath);
+  fs.mkdirSync(dir, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const target = path.join(dir, path.basename(qeaPath).replace(/(\.qea)$/i, '_before_sync_' + ts + '$1'));
+  fs.copyFileSync(qeaPath, target);
+  return target;
+}
+
+module.exports = {
+  SYNC_PACKAGE_NAME,
+  META_TABLE,
+  openQea,
+  deterministicGuid,
+  elementObjectType,
+  elementStereotype,
+  relationshipMap,
+  canonicalArchimateType,
+  syncGraphToQea,
+  exportQeaToGraph,
+  snapshotQea,
+  readMetaKind,
+  fullProjection,
+  wipeAllContent,
+  ensureRootPackage,
+  verifyQeaCanonical,
+};

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

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+'use strict';
+
+// WP2791 Node direct .qea projection CLI (no EA, no third-party deps).
+//   node argo/scripts/ea-qea-sync.js --graph <json> --qea <file.qea> --mode import|sync|full|export|watch
+//   [--delete-confirm-file <f> | -y] [--dry-run] [--snapshot-dir <dir>] [--out <file>] [--no-backup]
+//
+// import/sync : project design/KG graph into the .qea (update-in-place, batch INSERT,
+// full        : clear projection-owned content (kg_sync_meta + ArchGraph Sync subtree) then
+//               unchanged fingerprint skip, opt-in EA-only delete with confirmation).
+// export      : read .qea back into graph-shaped JSON (roundtrip comparable).
+// watch       : on graph JSON change, run sync (fs.watch + polling fallback).
+// Every write first snapshots the target as <file>_before_sync_<ts> unless --no-backup.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const lib = require(path.join(__dirname, 'ea-qea-sync-lib.js'));
+
+function parseArgs(argv) {
+  const args = { mode: 'sync', graph: '', qea: '', allowDelete: false, deleteConfirmFile: '', dryRun: false, snapshotDir: '', out: '', noBackup: false, intervalMs: 2000 };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => (i + 1 < argv.length ? argv[++i] : '');
+    if (a === '--graph') { args.graph = next(); }
+    else if (a === '--qea') { args.qea = next(); }
+    else if (a === '--mode') { args.mode = next(); }
+    else if (a === '--delete-confirm-file') { args.deleteConfirmFile = next(); args.allowDelete = true; }
+    else if (a === '-y' || a === '--yes') { args.allowDelete = true; }
+    else if (a === '--dry-run') { args.dryRun = true; }
+    else if (a === '--snapshot-dir') { args.snapshotDir = next(); }
+    else if (a === '--out') { args.out = next(); }
+    else if (a === '--no-backup') { args.noBackup = true; }
+    else if (a === '--interval') { args.intervalMs = Number(next()) || 2000; }
+    else if (a.startsWith('-')) { /* ignore unknown */ }
+    else if (args.modeSet === undefined) { /* positional not used */ }
+  }
+  return args;
+}
+
+function readGraph(jsonPath) {
+  const raw = fs.readFileSync(jsonPath, 'utf8').replace(/^\uFEFF/, '');
+  return JSON.parse(raw);
+}
+function confirmDelete(args) {
+  if (args.allowDelete) { return true; }
+  if (args.deleteConfirmFile) {
+    try {
+      const text = fs.readFileSync(args.deleteConfirmFile, 'utf8').trim().toLowerCase();
+      return text.indexOf('delete') >= 0;
+    } catch { return false; }
+  }
+  return false;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cwd = process.cwd();
+  const graphPath = path.resolve(cwd, args.graph || 'design/KG/SystemArchitecture.json');
+  const qeaPath = path.resolve(cwd, args.qea || 'archgraph.qea');
+  if (!fs.existsSync(qeaPath)) {
+    console.error('qea not found: ' + qeaPath);
+    process.exit(2);
+  }
+  if (args.mode === 'export') {
+    const graph = lib.exportQeaToGraph(qeaPath);
+    const text = JSON.stringify(graph, null, 2);
+    if (args.out) { fs.writeFileSync(path.resolve(cwd, args.out), text, 'utf8'); console.log('export written to ' + args.out); }
+    else { console.log(text); }
+    return;
+  }
+  if (!fs.existsSync(graphPath)) {
+    console.error('graph not found: ' + graphPath);
+    process.exit(2);
+  }
+  const graph = readGraph(graphPath);
+  if (args.mode === 'watch') {
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      runOnce(args, graphPath, qeaPath);
+      const m0 = statHash(graphPath);
+      await sleep(args.intervalMs);
+      const m1 = statHash(graphPath);
+      if (m0 !== m1) { continue; } // changed while waiting -> immediate re-sync
+    }
+  } else {
+    runOnce(args, graphPath, qeaPath);
+  }
+}
+function statHash(p) {
+  try { const st = fs.statSync(p); return st.size + ':' + st.mtimeMs; } catch { return 'gone'; }
+}
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+function runOnce(args, graphPath, qeaPath) {
+  const graph = readGraph(graphPath);
+  let snapshot = null;
+  if (!args.dryRun && !args.noBackup) {
+    snapshot = lib.snapshotQea(qeaPath, args.snapshotDir || undefined);
+  }
+  const res = args.mode === 'full'
+    ? lib.fullProjection(graph, qeaPath, { dryRun: args.dryRun })
+    : lib.syncGraphToQea(graph, qeaPath, { dryRun: args.dryRun, allowDelete: confirmDelete(args) });
+  const mode = args.dryRun ? 'dry-run' : 'sync';
+  console.log(JSON.stringify({ mode, graph: graphPath, qea: qeaPath, snapshot, result: res }, null, 2));
+}
+
+main().catch((e) => {
+  console.error('ea-qea-sync failed: ' + (e && e.message));
+  process.exit(1);
+});

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

@@ -1,5 +1,6 @@
 const fs = require('node:fs');
 const path = require('node:path');
+const { spawn } = require('node:child_process');
 const readline = require('node:readline');
 const crypto = require('node:crypto');
 
@@ -1615,6 +1616,25 @@ async function buildMutationResult(context, mutations, write) {
   writeGraph(context.graphPath.absolutePath, mutationResult.document);
   result.written = true;
 
+  // WP2791: .qea projection parallel to the Neo4j trigger — non-fatal, best-effort.
+  {
+    const qeaTarget = resolveQeaProjectionTarget(context);
+    if (qeaTarget) {
+      try {
+        const projection = await runQeaProjection(qeaTarget);
+        if (projection.ok) {
+          result.qeaProjection = { status: 'passed', qea: qeaTarget.qeaPath, ms: projection.ms };
+        } else {
+          result.qeaProjection = { status: 'failed', qea: qeaTarget.qeaPath, error: projection.error || ('exit ' + projection.code), ms: projection.ms };
+          result.warnings = addUnique(result.warnings || [], ['ea-qea projection failed (non-fatal): ' + (projection.error || ('exit code ' + projection.code))]);
+        }
+      } catch (error) {
+        result.qeaProjection = { status: 'failed', error: String(error && error.message ? error.message : error) };
+        result.warnings = addUnique(result.warnings || [], ['ea-qea projection error (non-fatal): ' + String(error && error.message ? error.message : error)]);
+      }
+    }
+  }
+
   if (shouldSyncCanonicalGraphToNeo4j(context.graphPath.relativePath)) {
     try {
       const syncResult = await syncArchitectureToNeo4j({
@@ -1812,6 +1832,59 @@ 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).
+function resolveQeaProjectionTarget(context) {
+  try {
+    const workspaceRoot = String(context && context.workspaceRoot ? context.workspaceRoot : '');
+    if (!workspaceRoot || !fs.existsSync(workspaceRoot)) { return null; }
+    const graphAbsolute = context.graphPath && context.graphPath.absolutePath ? context.graphPath.absolutePath : null;
+    if (!graphAbsolute || !fs.existsSync(graphAbsolute)) { return null; }
+    const pick = (p) => (p && fs.existsSync(p) ? path.resolve(p) : null);
+    let qeaPath = pick(process.env.ARGO_EA_QEA);
+    if (qeaPath) { return { qeaPath, graphPath: graphAbsolute, workspaceRoot }; }
+    let qeas = [];
+    try { qeas = fs.readdirSync(workspaceRoot).filter((n) => n.toLowerCase().endsWith('.qea')); } catch { /* ignore */ }
+    if (qeas.length === 1) {
+      return { qeaPath: path.resolve(workspaceRoot, qeas[0]), graphPath: graphAbsolute, workspaceRoot };
+    }
+    console.log('[ea-qea] projection target: none' + (qeas.length > 1 ? ' (' + qeas.length + ' *.qea found; expected exactly one or ARGO_EA_QEA)' : '') + ' in ' + workspaceRoot);
+    return null;
+  } catch (error) {
+    console.log('[ea-qea] projection target resolution failed: ' + String(error && error.message ? error.message : error));
+    return null;
+  }
+}
+
+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.10.52",
+  "version": "0.12.0",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {
@@ -38,7 +38,8 @@
     "neo4j-driver": "^6.2.0"
   },
   "devDependencies": {
-    "@resvg/resvg-js": "^2.6.2"
+    "@resvg/resvg-js": "^2.6.2",
+    "playwright": "1.61.1"
   },
   "scripts": {
     "test": "node --test \"tests/*.test.js\""