archgraph-argo 0.10.51 → 0.11.0

package/README.md

@@ -43,11 +43,30 @@ argo-deploy
 
 Done — the ARGO toolchain, skills, and rules are deployed, and the `argo` MCP server is registered automatically in **GitHub Copilot**, **Cursor**, **OpenCode**, **DeepSeek Harness** (dsh), and **OpenClaw**.
 
-> Semantic (Graph RAG) queries also need **Neo4j** and a **vector engine** configured in
-> `~/.argo/.env`; everything else works out of the box.
+### Prerequisites and configuration
+
+Everything works out of the box except **semantic (Graph RAG) queries**, which need:
+
+- **Neo4j graph database** — stores the structural projection of your architecture graph. During
+  `argo-deploy` you configure `ARGO_NEO4J_DATABASE_URL`, `ARGO_NEO4J_DATABASE_USERNAME`, and
+  `ARGO_NEO4J_DATABASE_PASSWORD` in `~/.argo/.env`.
+- **Embedding / vector engine** — powers semantic Graph RAG retrieval. Configure
+  `ARGO_EMBEDDING_BASE_URL`, `ARGO_EMBEDDING_MODEL`, `ARGO_EMBEDDING_PROVIDER`,
+  `ARGO_EMBEDDING_MODEL_VERSION`, `ARGO_EMBEDDING_DIMENSIONS`, plus the API key `QWEN_KEY`.
+
+Where do the values come from? The Neo4j credentials come from the Neo4j instance you own or
+provision (URI, username, password). The embedding configuration and `QWEN_KEY` come from your
+embedding provider's dashboard — for example Alibaba DashScope. `argo-deploy` walks you through the
+prompt (existing non-empty values in `~/.argo/.env` are kept); you can also edit the file afterwards
+and re-run.
 
 ## How to use
 
+**Step 0 — initialize the workspace.** In a fresh project, ask your coding agent to run `argo init`
+(the `initializeWorkspace` MCP call). It creates a starter `design/KG/SystemArchitecture.json` when
+missing, performs the first JSON → Neo4j sync, initializes the semantic (Graph RAG) lifecycle, and
+verifies the architecture. From then on, the intent graph is the source of truth for the project.
+
 After installing, open your project and start a coding agent. It will:
 
 1. locate the architecture element behind the task before changing anything,
@@ -56,6 +75,15 @@ After installing, open your project and start a coding agent. It will:
 
 The intent architecture graph — modelled in **ArchiMate 3.2** — is the single source of truth.
 
+## Community
+
+ArchGraph runs on open co-building. Join the community hub to share, browse and reuse **architecture
+subgraphs** across projects, and follow the governance & contribution guides:
+
+- **Community site** — https://argo.derekworkspacev5.com/archgraph/ (subgraph library, docs, blog)
+- **graph-wiki repository** — https://github.com/derekhu0002/graph-wiki (graph-asset home: contribute
+  a subgraph from your project, or pull one back to reuse)
+
 ## License
 
 [Apache License 2.0](LICENSE)

package/argo/mcp-bridges/graph-mcp-stdio.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+'use strict';
+
+// graph-mcp stdio bridge for hosts that dial remote MCP servers over SSE GET
+// and fail on Streamable HTTP-only endpoints (CURSOR remote url entries GET
+// /mcp -> 404). This bridge translates stdio JSON-RPC lines into POST
+// Streamable HTTP requests against GRAPH_MCP_URL so the remote graph-mcp
+// server loads as an ordinary stdio MCP server.
+//
+// Deployed by install-argo.ps1 to ~/.cursor/mcp-bridges/graph-mcp-stdio.js
+// and registered as:
+//   "graph-mcp": { type: stdio, command: node,
+//                  args: [<bridge path>],
+//                  env: { GRAPH_MCP_URL: "https://.../mcp" } }
+
+const readline = require('node:readline');
+
+const endpoint = process.env.GRAPH_MCP_URL;
+if (!endpoint) {
+  console.error('GRAPH_MCP_URL is required');
+  process.exit(1);
+}
+
+function emit(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function parseSse(body) {
+  const messages = [];
+  // SSE frames are separated by a blank line (\r\n\r\n or \n\n).
+  for (const block of body.split(/\r?\n\r?\n/)) {
+    const data = block
+      .split(/\r?\n/)
+      .filter((line) => line.startsWith('data:'))
+      .map((line) => line.slice(5).trimStart())
+      .join('\n');
+    if (data) {
+      messages.push(JSON.parse(data));
+    }
+  }
+  return messages;
+}
+
+async function forward(message) {
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json, text/event-stream',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(message),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Remote MCP returned HTTP ${response.status}`);
+  }
+
+  // 202 Accepted means the server will stream the result over a separate SSE
+  // connection; there is nothing to return on this POST. Notifications
+  // (id === undefined) carry no response either.
+  if (response.status === 202 || message.id === undefined) return;
+
+  const body = await response.text();
+  const contentType = response.headers.get('content-type') || '';
+  if (contentType.includes('text/event-stream')) {
+    for (const item of parseSse(body)) emit(item);
+    return;
+  }
+  if (body.trim()) emit(JSON.parse(body));
+}
+
+const input = readline.createInterface({
+  input: process.stdin,
+  crlfDelay: Infinity,
+});
+
+input.on('line', (line) => {
+  if (!line.trim()) return;
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch (error) {
+    console.error(`Invalid JSON-RPC input: ${error.message}`);
+    return;
+  }
+
+  forward(message).catch((error) => {
+    if (message.id !== undefined) {
+      emit({
+        jsonrpc: '2.0',
+        id: message.id,
+        error: { code: -32000, message: error.message },
+      });
+    } else {
+      console.error(error.message);
+    }
+  });
+});

package/install-argo.ps1

@@ -5,6 +5,7 @@ param(
     [string]$PromptsRoot = "$env:APPDATA\Code\User\prompts",
     [string]$CursorSkillsRoot = "$env:USERPROFILE\.cursor\skills",
     [string]$CursorMcpPath = "$env:USERPROFILE\.cursor\mcp.json",
+    [string]$CursorMcpBridgesRoot = "$env:USERPROFILE\.cursor\mcp-bridges",
     [string]$OpenCodeSkillsRoot = "$env:USERPROFILE\.config\opencode\skills",
     [string]$OpenCodeAgentsPath = "$env:USERPROFILE\.config\opencode\AGENTS.md",
     [string]$OpenCodeConfigPath = "$env:USERPROFILE\.config\opencode\opencode.json",
@@ -25,7 +26,10 @@ param(
     [string]$OpenClawRepoRoot = '',
     [switch]$SkipOpenClaw,
     [string]$McpPath,
-    [string]$GraphMcpUrl = 'https://argo.derekworkspacev5.com/mcp'
+    [string]$GraphMcpUrl = 'https://argo.derekworkspacev5.com/mcp',
+    [switch]$SkipEaWeb,
+    [int]$EaWebPort = 8787,
+    [string]$EaWebRoot = ''
 )
 
 $ErrorActionPreference = 'Stop'
@@ -736,63 +740,68 @@ Write-Host '==> Deploying Argo toolchain'
 
 $schemaSrc = Join-Path $argoDir 'schema'
 $schemaDest = Join-Path $ArgoRoot 'schema'
-Write-Host "[1/22] argo\schema -> $schemaDest"
+Write-Host "[1/23] argo\schema -> $schemaDest"
 Copy-Tree -Source $schemaSrc -Destination $schemaDest
 
 $scriptsSrc = Join-Path $argoDir 'scripts'
 $scriptsDest = Join-Path $ArgoRoot 'scripts'
-Write-Host "[2/22] argo\scripts -> $scriptsDest"
+Write-Host "[2/23] argo\scripts -> $scriptsDest"
 Copy-Tree -Source $scriptsSrc -Destination $scriptsDest
 
 $defaultsSrc = Join-Path $argoDir 'defaults'
 $defaultsDest = Join-Path $ArgoRoot 'defaults'
-Write-Host "[3/22] argo\defaults -> $defaultsDest"
+Write-Host "[3/23] argo\defaults -> $defaultsDest"
 Copy-Tree -Source $defaultsSrc -Destination $defaultsDest
 
 $skillSrc = Join-Path (Join-Path $argoDir 'skills') 'argo-init'
 $skillDest = Join-Path $SkillsRoot 'argo-init'
-Write-Host "[4/22] argo\skills\argo-init -> $skillDest"
+Write-Host "[4/23] argo\skills\argo-init -> $skillDest"
 Copy-Tree -Source $skillSrc -Destination $skillDest
 
 $ruleSrc = Join-Path (Join-Path $argoDir 'rules') 'archgraph.instructions.md'
 $ruleDest = Join-Path $PromptsRoot 'archgraph.instructions.md'
-Write-Host "[5/22] argo\rules\archgraph.instructions.md -> $ruleDest"
+Write-Host "[5/23] argo\rules\archgraph.instructions.md -> $ruleDest"
 New-Item -ItemType Directory -Force -Path $PromptsRoot | Out-Null
 Copy-Item -Force -Path $ruleSrc -Destination $ruleDest
 
 $depsSrc = Join-Path $argoDir 'package.json'
 $depsDest = Join-Path $ArgoRoot 'package.json'
-Write-Host "[6/22] argo\package.json -> $depsDest"
+Write-Host "[6/23] argo\package.json -> $depsDest"
 Copy-Item -Force -Path $depsSrc -Destination $depsDest
 
 $cursorSkillDest = Join-Path $CursorSkillsRoot 'argo-init'
-Write-Host "[7/22] argo\skills\argo-init -> $cursorSkillDest (Cursor)"
+Write-Host "[7/23] argo\skills\argo-init -> $cursorSkillDest (Cursor)"
 Copy-Tree -Source $skillSrc -Destination $cursorSkillDest
 
+$mcpBridgeSrc = Join-Path $argoDir 'mcp-bridges'
+$mcpBridgeDest = Join-Path $CursorMcpBridgesRoot ''
+Write-Host "  argo\mcp-bridges -> $mcpBridgeDest (Cursor graph-mcp stdio bridge)"
+Copy-Tree -Source $mcpBridgeSrc -Destination $mcpBridgeDest
+
 $openCodeSkillDest = Join-Path $OpenCodeSkillsRoot 'argo-init'
-Write-Host "[8/22] argo\skills\argo-init -> $openCodeSkillDest (OpenCode)"
+Write-Host "[8/23] argo\skills\argo-init -> $openCodeSkillDest (OpenCode)"
 Copy-Tree -Source $skillSrc -Destination $openCodeSkillDest
 
-Write-Host "[9/22] argo\rules\archgraph.instructions.md -> $OpenCodeAgentsPath (OpenCode global AGENTS.md)"
+Write-Host "[9/23] argo\rules\archgraph.instructions.md -> $OpenCodeAgentsPath (OpenCode global AGENTS.md)"
 Add-AgentsRule -AgentsPath $OpenCodeAgentsPath -RulePath $ruleSrc
 
 $agentsSrc = Join-Path $argoDir 'agents'
-Write-Host "[10/22] argo\agents -> $CopilotAgentsRoot (Copilot user-level)"
+Write-Host "[10/23] argo\agents -> $CopilotAgentsRoot (Copilot user-level)"
 Copy-Agents -Source $agentsSrc -Destination $CopilotAgentsRoot
 
-Write-Host "[11/22] argo\agents -> $CursorAgentsRoot (Cursor user-level, converted to .md)"
+Write-Host "[11/23] argo\agents -> $CursorAgentsRoot (Cursor user-level, converted to .md)"
 Copy-Agents -Source $agentsSrc -Destination $CursorAgentsRoot -Target cursor
 
-Write-Host "[12/22] argo\agents -> $OpenCodeAgentsRoot (OpenCode user-level, converted to .md)"
+Write-Host "[12/23] argo\agents -> $OpenCodeAgentsRoot (OpenCode user-level, converted to .md)"
 Copy-Agents -Source $agentsSrc -Destination $OpenCodeAgentsRoot -Target opencode
 
 $pluginsSrc = Join-Path $argoDir 'plugins'
-Write-Host "[13/22] argo\plugins -> $PluginsRoot (Argo opencode plugins)"
+Write-Host "[13/23] argo\plugins -> $PluginsRoot (Argo opencode plugins)"
 Copy-Tree -Source $pluginsSrc -Destination $PluginsRoot
 
 $cursorRuleSrc = Join-Path (Join-Path $argoDir 'rules') 'archgraph.instructions.md'
 $cursorRuleDest = Join-Path $CursorRulesRoot 'archgraph.mdc'
-Write-Host "[14/22] argo\rules\archgraph.instructions.md -> $cursorRuleDest (Cursor global rule, alwaysApply)"
+Write-Host "[14/23] argo\rules\archgraph.instructions.md -> $cursorRuleDest (Cursor global rule, alwaysApply)"
 New-Item -ItemType Directory -Force -Path $CursorRulesRoot | Out-Null
 Convert-RuleFile -SourceFile $cursorRuleSrc -DestinationFile $cursorRuleDest
 
@@ -804,16 +813,16 @@ if ($SkipDsh) {
     $patchPath = Join-Path $DshHome 'cordis.patch.yml'
     $argoServer = (Join-Path $ArgoRoot 'scripts\argo-mcp-server.js').Replace('\', '/')
 
-    Write-Host "[15/22] argo\rules\archgraph.instructions.md -> $DshHome\AGENTS.md (DeepSeek Harness user-global rule, frontmatter stripped)"
+    Write-Host "[15/23] argo\rules\archgraph.instructions.md -> $DshHome\AGENTS.md (DeepSeek Harness user-global rule, frontmatter stripped)"
     Write-DshAgentRule -DshHome $DshHome -RuleText $ruleSrcContent
 
-    Write-Host "[16/22] argo\skills\argo-init -> $dshSkillDest (DeepSeek Harness skill)"
+    Write-Host "[16/23] argo\skills\argo-init -> $dshSkillDest (DeepSeek Harness skill)"
     Copy-Tree -Source (Join-Path $argoDir 'skills\argo-init') -Destination $dshSkillDest
 
-    Write-Host "[17/22] argo\rules\<WakeupGuideline> -> $DshHome\plugins\dsh-argo-wakeup\index.js (DeepSeek Harness wakeup plugin)"
+    Write-Host "[17/23] argo\rules\<WakeupGuideline> -> $DshHome\plugins\dsh-argo-wakeup\index.js (DeepSeek Harness wakeup plugin)"
     $wakeupDshPath = New-DshWakeupPlugin -DshHome $DshHome -RuleText $ruleSrcContent
 
-    Write-Host "[18/22] argo-workspace + argo-wakeup rows -> $patchPath (DeepSeek Harness MCP bridge + wakeup plugin)"
+    Write-Host "[18/23] argo-workspace + argo-wakeup rows -> $patchPath (DeepSeek Harness MCP bridge + wakeup plugin)"
     # The generated dsh-argo-workspace bridge connects directly to the argo
     # server (no dsh-mcp-client row), registers every tool as mcp__argo__* and
     # injects the current session's workspace (SessionHeader.cwd) as the
@@ -844,7 +853,7 @@ if ($SkipDsh) {
         Write-DshManagedBlock -Path $patchPath -Block $block -MarkerStart '# BEGIN ArchGraph ARGO deployment' -MarkerEnd '# END ArchGraph ARGO deployment'
     }
 
-    Write-Host "[19/22] argo\agents -> $DshHome\.agent-presets\<id> (DeepSeek Harness agent presets)"
+    Write-Host "[19/23] argo\agents -> $DshHome\.agent-presets\<id> (DeepSeek Harness agent presets)"
     New-DshAgentPresets -DshHome $DshHome -AgentsSrc (Join-Path $argoDir 'agents')
 
     Write-Host "  note: graph-mcp remote ($GraphMcpUrl) is NOT registered for DeepSeek Harness -"
@@ -865,10 +874,10 @@ if ($SkipOpenClaw) {
     $openClawAgentsDest = Join-Path $OpenClawWorkspace 'AGENTS.md'
 
     Write-Host '==> Deploying OpenClaw integration'
-    Write-Host "[20/22] argo\rules\archgraph.instructions.md -> $openClawAgentsDest (OpenClaw workspace AGENTS.md, frontmatter stripped)"
+    Write-Host "[20/23] argo\rules\archgraph.instructions.md -> $openClawAgentsDest (OpenClaw workspace AGENTS.md, frontmatter stripped)"
     Write-OpenClawAgentRule -OpenClawWorkspace $OpenClawWorkspace -RuleText $ruleSrcContent
 
-    Write-Host "[21/22] argo\skills\argo-init -> $openClawSkillDest (OpenClaw managed skill, all agents)"
+    Write-Host "[21/23] argo\skills\argo-init -> $openClawSkillDest (OpenClaw managed skill, all agents)"
     Copy-Tree -Source (Join-Path $argoDir 'skills\argo-init') -Destination $openClawSkillDest
 
     Write-Host '  OpenClaw injects AGENTS.md into Project Context on every session, so the wakeup'
@@ -973,9 +982,10 @@ if ($SkipMcp) {
     # graph-mcp is a Streamable HTTP remote MCP endpoint. Its config shape is
     # HOST-SPECIFIC (each host's mcp.json schema is different):
     #   - OpenCode  (opencode.json mcp.<name>): {type: remote, url, enabled}
-    #   - Cursor    (mcp.json mcpServers.<name>): {url} — official remote
-    #     entries carry no `type` (type only means "stdio" for local servers);
-    #     Cursor dials url servers over Streamable HTTP.
+    #   - Cursor    (mcp.json mcpServers.<name>): stdio bridge — Cursor dials
+    #     remote url servers over SSE GET /mcp, which the Streamable HTTP
+    #     endpoint answers with 404, so graph-mcp is exposed as a local stdio
+    #     bridge (graph-mcp-stdio.js) that forwards to the remote over POST.
     #   - VS Code   (mcp.json servers.<name>): {type: http, url}
     #   - OpenClaw  (openclaw.json mcp.servers.<name>): {url, transport:
     #     streamable-http} — keyed by transport, not by a type alias.
@@ -986,8 +996,14 @@ if ($SkipMcp) {
         url     = $GraphMcpUrl
         enabled = $true
     }
+    $graphMcpBridgePath = (Join-Path $CursorMcpBridgesRoot 'graph-mcp-stdio.js').Replace('\', '/')
     $graphMcpCursor = [ordered]@{
-        url = $GraphMcpUrl
+        type    = 'stdio'
+        command = 'node'
+        args    = @($graphMcpBridgePath)
+        env     = [ordered]@{
+            GRAPH_MCP_URL = $GraphMcpUrl
+        }
     }
     $graphMcpVSCode = [ordered]@{
         type = 'http'
@@ -1015,6 +1031,7 @@ if ($SkipMcp) {
         args    = @($argoServer)
     }) -ExtraServers ([ordered]@{ 'graph-mcp' = $graphMcpCursor })
     Write-Host "argo MCP config written -> $CursorMcpPath"
+    Write-Host "  graph-mcp registered as stdio bridge -> $graphMcpBridgePath"
 
     Write-Host '==> Registering argo MCP server in OpenCode'
     Write-McpConfig -Path $OpenCodeConfigPath -ServersKey 'mcp' -ServerConfig ([ordered]@{
@@ -1029,7 +1046,7 @@ if ($SkipMcp) {
         # location; -OpenClawRepoRoot overrides it (e.g. for tests or when the
         # installer runs from a non-workspace npm-global package dir).
         $openClawRepoRoot = if ($OpenClawRepoRoot) { $OpenClawRepoRoot } else { $repoRoot }
-        Write-Host "[22/22] argo MCP server -> $(Join-Path $OpenClawHome 'openclaw.json') (OpenClaw mcp.servers.argo, env.ARGO_REPO_ROOT pinned)"
+        Write-Host "[22/23] argo MCP server -> $(Join-Path $OpenClawHome 'openclaw.json') (OpenClaw mcp.servers.argo, env.ARGO_REPO_ROOT pinned)"
         Write-OpenClawMcpConfig -OpenClawHome $OpenClawHome -RepoRoot $openClawRepoRoot -ArgoServer $argoServer -GraphMcpServer $openClawGraphMcpServer
     }
 }
@@ -1041,5 +1058,68 @@ if (Test-Path $wakeupPluginPath) {
     Write-Host "argo-wakeup plugin registered -> $OpenCodeConfigPath"
 }
 
+# EA local web service (WP2786): deploy the two service scripts next to the
+# harness scripts (REPO_ROOT = $ArgoRoot keeps the relative layout intact) plus
+# the web/ statics, then start the service in the background. Re-running the
+# installer is idempotent: an occupied port skips the startup.
+$eaServiceSrc = Join-Path $repoRoot 'scripts\ea-web-service.js'
+$eaLayoutStoreSrc = Join-Path $repoRoot 'scripts\ea-layout-store.js'
+$eaWebSrc = Join-Path $repoRoot 'web'
+Write-Host "[23/23] scripts\ea-web-service.js + scripts\ea-layout-store.js + web -> $ArgoRoot (EA local web service)"
+if ((Test-Path $eaServiceSrc) -and (Test-Path $eaLayoutStoreSrc) -and (Test-Path $eaWebSrc)) {
+    Copy-Item -Force -Path $eaServiceSrc -Destination (Join-Path $scriptsDest 'ea-web-service.js')
+    Copy-Item -Force -Path $eaLayoutStoreSrc -Destination (Join-Path $scriptsDest 'ea-layout-store.js')
+    Copy-Tree -Source $eaWebSrc -Destination (Join-Path $ArgoRoot 'web')
+    Write-Host "  service scripts + web statics deployed -> $scriptsDest / $(Join-Path $ArgoRoot 'web')"
+    if ($SkipEaWeb) {
+        Write-Host '  EA web service startup skipped (-SkipEaWeb)'
+    }
+    else {
+        $eaWebRoot = if ($EaWebRoot) { $EaWebRoot } else { $PWD.Path }
+        $eaPortInUse = $false
+        try {
+            $eaProbe = New-Object System.Net.Sockets.TcpClient
+            $eaProbe.Connect('127.0.0.1', $EaWebPort)
+            $eaPortInUse = $true
+            $eaProbe.Close()
+        }
+        catch {
+            $eaPortInUse = $false
+        }
+        if ($eaPortInUse) {
+            Write-Host "  EA web service already listening on 127.0.0.1:$EaWebPort; startup skipped (idempotent re-deploy)"
+        }
+        else {
+            $nodeCmd = Get-Command node -ErrorAction SilentlyContinue
+            if (-not $nodeCmd) {
+                throw 'EA web service startup failed: node not found on PATH'
+            }
+            $eaServiceDest = Join-Path $scriptsDest 'ea-web-service.js'
+            $eaLogOut = Join-Path $ArgoRoot 'ea-web-service.log'
+            $eaLogErr = Join-Path $ArgoRoot 'ea-web-service.err.log'
+            # Start the service through WMI (Win32_Process.Create) instead of
+            # Start-Process: the process is then created by the WMI service and
+            # inherits NONE of this installer's stdio pipe handles. Inherited
+            # pipes would keep spawnSync-based launchers (argo-deploy bin, tests)
+            # blocked until the service exits. cmd.exe is used only to redirect
+            # the service stdout/stderr into log files.
+            $q = [char]34
+            $eaCmdLine = "cmd.exe /S /c $q$q$($nodeCmd.Source)$q $q$eaServiceDest$q --root $q$eaWebRoot$q --port $EaWebPort > $q$eaLogOut$q 2> $q$eaLogErr$q$q"
+            $eaCreate = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{
+                CommandLine      = $eaCmdLine
+                CurrentDirectory = $ArgoRoot
+            }
+            if ($eaCreate.ReturnValue -ne 0) {
+                throw "EA web service startup failed: Win32_Process.Create ReturnValue $($eaCreate.ReturnValue)"
+            }
+            Write-Host "  EA web service started in background (pid $($eaCreate.ProcessId)): http://127.0.0.1:$EaWebPort (root: $eaWebRoot)"
+            Write-Host "  logs: $eaLogOut / $eaLogErr"
+        }
+    }
+}
+else {
+    Write-Host '  EA web service sources not present in this package; step skipped'
+}
+
 Write-Host ''
 Write-Host 'Argo deployment complete.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.10.51",
+  "version": "0.11.0",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {
@@ -12,9 +12,13 @@
     "argo/defaults",
     "argo/agents",
     "argo/plugins",
+    "argo/mcp-bridges",
     "argo/skills/argo-init",
     "argo/rules",
     "argo/package.json",
+    "scripts/ea-web-service.js",
+    "scripts/ea-layout-store.js",
+    "web",
     "vendor",
     "install-argo.ps1",
     "bin",

package/scripts/ea-layout-store.js

@@ -0,0 +1,242 @@
+'use strict';
+
+/**
+ * 布局侧车（Layout Sidecar，WP2785 M1-S2，2026-09-03 修订：默认按项目隔离，AT-2785-L5）
+ * — 图谱画布坐标独立持久化。
+ *
+ * 零第三方依赖（仅 Node 内置 path/fs/crypto）。与 design/KG/SystemArchitecture.json
+ * 完全物理隔离：坐标不进图谱 JSON、不进 schema；本模块永远不读写图谱文件本身。
+ *
+ * 存储根（按优先级）：
+ * 1. 显式覆盖：createLayoutStore({ layoutRoot }) 选项或 EA_LAYOUT_ROOT 环境变量
+ *    → <layoutRoot>/<projectId>/<view_id>.json（测试 / 自定义集中存储根）。
+ * 2. 默认（无任何覆盖）：按项目隔离
+ *    → <projectRoot>/design/KG/ea-layouts/<view_id>.json（仍是独立文件，
+ *      只落在 ea-layouts/ 子目录，绝不触碰 SystemArchitecture.json 本身）。
+ *
+ * 文件内容：{ version, graphKey, view_id, signature, updatedAt, elements: { <elementId>: {x,y} } }
+ *
+ * 失效键 = 视图成员身份签名（成员身份集合的 sha256，只含身份 id，不含任何内容字段）：
+ * signature = sha256(sorted(included_elements) + sorted(included_relationships))。
+ * 图谱内容级修改（元素 name/description/attributes、关系描述等）不改变成员集合
+ * → signature 不变 → 坐标完全不动；仅成员结构变化触发新成员补位/移除成员清理。
+ *
+ * 合并语义（读取时）：以当前图谱视图成员为准——仍有坐标的现存成员原样保留；
+ * 新成员（无坐标）按确定性算法补位（沿用 buildViewGraph 的圆形布局公式）并写回侧车；
+ * 已不在成员中的坐标清理。
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+
+const LAYOUT_VERSION = 1;
+// 默认按项目隔离时，侧车相对项目根的存放目录。
+const PROJECT_LAYOUT_DIR = path.join('design', 'KG', 'ea-layouts');
+
+/**
+ * 解析显式存储根覆盖：选项 > EA_LAYOUT_ROOT 环境变量。
+ * 返回 null 表示无覆盖 → 使用默认的按项目隔离存储。
+ */
+function resolveLayoutRoot(explicitRoot) {
+  if (explicitRoot) {
+    return path.resolve(explicitRoot);
+  }
+  if (process.env.EA_LAYOUT_ROOT) {
+    return path.resolve(process.env.EA_LAYOUT_ROOT);
+  }
+  return null;
+}
+
+/**
+ * 视图成员身份签名：仅由 included_elements / included_relationships 的身份 id 集合决定，
+ * 与元素/关系的任何内容字段无关。
+ */
+function computeViewSignature(view) {
+  const elements = Array.from(new Set((view && view.included_elements) || [])).sort();
+  const relationships = Array.from(new Set((view && view.included_relationships) || [])).sort();
+  const payload = `${elements.join('\u0001')}\u0000${relationships.join('\u0001')}`;
+  return crypto.createHash('sha256').update(payload).digest('hex');
+}
+
+// 文件名安全化（服务端路由已限制 [A-Za-z0-9._-]，此处为独立模块的防御性兜底）。
+function safeFileName(segment) {
+  return String(segment).replace(/[^A-Za-z0-9._-]/g, '_');
+}
+
+/**
+ * 确定性补位：沿用 buildViewGraph 的圆形布局公式（成员索引 → 圆周位置）。
+ */
+function defaultPosition(index, count) {
+  const angle = (2 * Math.PI * index) / Math.max(count, 1);
+  return {
+    x: Math.round(80 + 160 * Math.cos(angle)),
+    y: Math.round(80 + 160 * Math.sin(angle)),
+  };
+}
+
+function isValidPosition(pos) {
+  return !!pos
+    && typeof pos === 'object'
+    && !Array.isArray(pos)
+    && Number.isFinite(Number(pos.x))
+    && Number.isFinite(Number(pos.y));
+}
+
+function createLayoutStore(options = {}) {
+  // null → 默认按项目隔离存储；否则为显式集中存储根。
+  const explicitRoot = resolveLayoutRoot(options.layoutRoot);
+
+  /**
+   * 目标解析：target = { project?: {id, root, graphPath}, projectId?, graphKey? }。
+   * 显式根模式用 projectId 分桶；默认模式用 project.root 定位项目内 ea-layouts/ 目录。
+   */
+  function resolveTarget(target, viewId) {
+    const t = target || {};
+    const project = t.project || {};
+    const projectId = t.projectId || project.id || null;
+    const graphKey = t.graphKey || project.graphPath || null;
+    if (explicitRoot) {
+      if (!projectId) {
+        throw new Error('layout store: 显式存储根模式下必须提供 projectId（或 project.id）');
+      }
+      return {
+        projectId,
+        graphKey,
+        filePath: path.join(explicitRoot, safeFileName(projectId), `${safeFileName(viewId)}.json`),
+      };
+    }
+    const projectRoot = project.root;
+    if (!projectRoot) {
+      throw new Error('layout store: 默认按项目隔离存储必须提供 project.root');
+    }
+    return {
+      projectId,
+      graphKey,
+      filePath: path.join(path.resolve(projectRoot), PROJECT_LAYOUT_DIR, `${safeFileName(viewId)}.json`),
+    };
+  }
+
+  function filePathFor(target, viewId) {
+    return resolveTarget(target, viewId).filePath;
+  }
+
+  function readRecord(target, viewId) {
+    let text;
+    try {
+      text = fs.readFileSync(filePathFor(target, viewId), 'utf8');
+    } catch {
+      return null;
+    }
+    try {
+      const record = JSON.parse(text);
+      if (!record || typeof record !== 'object' || Array.isArray(record)) {
+        return null;
+      }
+      if (!record.elements || typeof record.elements !== 'object' || Array.isArray(record.elements)) {
+        record.elements = {};
+      }
+      return record;
+    } catch {
+      return null;
+    }
+  }
+
+  function writeRecord(target, viewId, record) {
+    const filePath = filePathFor(target, viewId);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tempPath, JSON.stringify(record, null, 2), 'utf8');
+    fs.renameSync(tempPath, filePath);
+    return filePath;
+  }
+
+  /**
+   * 读取合并后的布局（以当前图谱视图成员为准）。
+   * 有补位/清理/签名变化时写回侧车；纯内容级修改（签名不变）不触发写入。
+   * 入参：{ project?: {id, root, graphPath}, projectId?, graphKey?, view }。
+   * 返回 { signature, elements: { <elementId>: {x,y} } }。
+   */
+  function mergeLayout({ project, projectId, graphKey, view }) {
+    if (!view || typeof view.view_id !== 'string') {
+      throw new Error('mergeLayout: view with view_id is required');
+    }
+    const target = { project, projectId, graphKey };
+    const viewId = view.view_id;
+    const signature = computeViewSignature(view);
+    const record = readRecord(target, viewId);
+    const saved = record ? record.elements : {};
+    const members = Array.isArray(view.included_elements) ? view.included_elements : [];
+    const elements = {};
+    let dirty = !record || record.signature !== signature;
+
+    members.forEach((id, index) => {
+      const pos = saved[id];
+      if (isValidPosition(pos)) {
+        elements[id] = { x: Number(pos.x), y: Number(pos.y) };
+      } else {
+        elements[id] = defaultPosition(index, members.length);
+        dirty = true;
+      }
+    });
+    for (const id of Object.keys(saved)) {
+      if (!members.includes(id)) {
+        dirty = true; // 已不在成员中的坐标：清理
+      }
+    }
+    if (dirty) {
+      writeRecord(target, viewId, {
+        version: LAYOUT_VERSION,
+        graphKey: resolveTarget(target, viewId).graphKey,
+        view_id: viewId,
+        signature,
+        updatedAt: new Date().toISOString(),
+        elements,
+      });
+    }
+    return { signature, elements };
+  }
+
+  /**
+   * 全量写入布局（按当前文档计算签名后原子写入侧车文件）。
+   * 入参：{ project?: {id, root, graphPath}, projectId?, graphKey?, view, elements }；
+   * elements: { <elementId>: {x,y} }；非法坐标抛错（由服务端映射为 400）。
+   */
+  function putLayout({ project, projectId, graphKey, view, elements }) {
+    if (!view || typeof view.view_id !== 'string') {
+      throw new Error('putLayout: view with view_id is required');
+    }
+    if (!elements || typeof elements !== 'object' || Array.isArray(elements)) {
+      throw new Error('body.elements 必须是 { <elementId>: {x,y} } 对象');
+    }
+    const normalized = {};
+    for (const [id, pos] of Object.entries(elements)) {
+      if (!isValidPosition(pos)) {
+        throw new Error(`elements['${id}'] 的坐标必须是有限的 {x,y} 数字`);
+      }
+      normalized[id] = { x: Number(pos.x), y: Number(pos.y) };
+    }
+    const target = { project, projectId, graphKey };
+    const signature = computeViewSignature(view);
+    writeRecord(target, view.view_id, {
+      version: LAYOUT_VERSION,
+      graphKey: resolveTarget(target, view.view_id).graphKey,
+      view_id: view.view_id,
+      signature,
+      updatedAt: new Date().toISOString(),
+      elements: normalized,
+    });
+    return { signature, view_id: view.view_id };
+  }
+
+  return { root: explicitRoot, filePathFor, readRecord, writeRecord, mergeLayout, putLayout };
+}
+
+module.exports = {
+  LAYOUT_VERSION,
+  PROJECT_LAYOUT_DIR,
+  resolveLayoutRoot,
+  computeViewSignature,
+  defaultPosition,
+  createLayoutStore,
+};