archgraph-argo 0.1.0

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

@@ -0,0 +1,377 @@
+const { execFile, spawn } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline');
+const { promisify } = require('node:util');
+
+const execFileAsync = promisify(execFile);
+
+const {
+  getArgoRoot,
+  getWorkspaceRoot,
+} = require('./argo-paths.js');
+
+const HANDOFF_STAGES = ['intent-to-implementation', 'implementation-to-coding'];
+const DEFAULT_TRACE_PROPOSAL_PATH = 'design/KG/ImplementationToIntentTraceProposal.json';
+const DEFAULT_ARCHITECTURE_GRAPH_PATH = 'design/KG/SystemArchitecture.json';
+
+const SCRIPT_CANDIDATES = {
+  validateSystemArchitecture: [
+    'scripts/validateSystemArchitecture.js',
+  ],
+  validateStageHandoff: [
+    'scripts/validateStageHandoff.js',
+  ],
+  validateTraceProposal: [
+    'scripts/validateTraceProposal.js',
+  ],
+  runArchitectureTests: [
+    'scripts/runArchitectureTests.js',
+  ],
+};
+
+const TOOLS = [
+  {
+    name: 'validateSystemArchitecture',
+    description: 'Validate design/KG/SystemArchitecture.json against .argo/schema/SystemArchitecture.schema.json and Argo graph rules.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'validateStageHandoff',
+    description: 'Validate Argo stage handoff JSON. Use stage intent-to-implementation or implementation-to-coding, or omit to validate all supported stages.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        stage: {
+          type: 'string',
+          enum: HANDOFF_STAGES,
+          description: 'Optional handoff stage to validate.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'validateTraceProposal',
+    description: 'Validate ImplementationToIntentTraceProposal JSON against .argo/schema/ImplementationToIntentTraceProposal.schema.json and repository path references.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        proposalPath: {
+          type: 'string',
+          description: `Optional proposal path relative to workspace root. Default: ${DEFAULT_TRACE_PROPOSAL_PATH}`,
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'runArchitectureTests',
+    description: 'Execute explicit architecture testcases from the intent graph and refresh design/KG/test-failure-records.json. This MCP call can exceed client timeouts; if it times out, run the same test runner directly with: node .argo/scripts/runArchitectureTests.js',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        architecturePath: {
+          type: 'string',
+          description: `Optional architecture graph path relative to workspace root. Default: ${DEFAULT_ARCHITECTURE_GRAPH_PATH}`,
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+function resolveWorkspaceRoot() {
+  return getWorkspaceRoot();
+}
+
+function resolveScriptPath(workspaceRoot, candidates) {
+  const argoRoot = getArgoRoot();
+  for (const relativePath of candidates) {
+    const absolutePath = path.join(argoRoot, relativePath);
+    if (fs.existsSync(absolutePath)) {
+      return { absolutePath, relativePath };
+    }
+  }
+
+  for (const relativePath of candidates) {
+    const absolutePath = path.join(workspaceRoot, '.argo', relativePath);
+    if (fs.existsSync(absolutePath)) {
+      return { absolutePath, relativePath };
+    }
+  }
+
+  throw new Error(`Unable to locate validator script. Checked: ${candidates.join(', ')}`);
+}
+
+async function runValidatorScriptStreaming(workspaceRoot, scriptKey, args, progressToken) {
+  const { absolutePath, relativePath } = resolveScriptPath(workspaceRoot, SCRIPT_CANDIDATES[scriptKey]);
+  const command = process.execPath;
+  const commandArgs = [absolutePath, ...args];
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, commandArgs, {
+      cwd: workspaceRoot,
+      env: {
+        ...process.env,
+        ARGO_REPO_ROOT: workspaceRoot,
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    const stdoutLines = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
+
+    stdoutLines.on('line', (line) => {
+      stdout += line + '\n';
+
+      const progressMatch = line.match(/^\[PROGRESS\]\s*(.+)$/);
+      if (progressMatch) {
+        try {
+          const payload = JSON.parse(progressMatch[1]);
+          send({
+            jsonrpc: '2.0',
+            method: 'notifications/progress',
+            params: {
+              progressToken,
+              progress: payload.passedCount !== undefined
+                ? payload.passedCount
+                : payload.index + 1,
+              total: payload.total,
+              message: `${payload.testcaseName || '(unnamed)'}: ${payload.status}`,
+            },
+          });
+        } catch (_) {
+          // ignore malformed progress lines
+        }
+      }
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('error', (error) => {
+      reject(error);
+    });
+
+    child.on('close', (exitCode) => {
+      const code = exitCode === null ? 1 : exitCode;
+      const passed = code === 0;
+      resolve({
+        status: passed ? 'passed' : 'failed',
+        exitCode: code,
+        workspaceRoot,
+        scriptPath: relativePath,
+        command: [command, ...commandArgs],
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+      });
+    });
+  });
+}
+
+async function runValidatorScript(workspaceRoot, scriptKey, args = []) {
+  const { absolutePath, relativePath } = resolveScriptPath(workspaceRoot, SCRIPT_CANDIDATES[scriptKey]);
+  const command = process.execPath;
+  const commandArgs = [absolutePath, ...args];
+
+  try {
+    const { stdout, stderr } = await execFileAsync(command, commandArgs, {
+      cwd: workspaceRoot,
+      env: {
+        ...process.env,
+        ARGO_REPO_ROOT: workspaceRoot,
+      },
+      maxBuffer: 10 * 1024 * 1024,
+    });
+
+    return {
+      status: 'passed',
+      exitCode: 0,
+      workspaceRoot,
+      scriptPath: relativePath,
+      command: [command, ...commandArgs],
+      stdout: stdout.trim(),
+      stderr: stderr.trim(),
+    };
+  } catch (error) {
+    return {
+      status: 'failed',
+      exitCode: typeof error.code === 'number' ? error.code : 1,
+      workspaceRoot,
+      scriptPath: relativePath,
+      command: [command, ...commandArgs],
+      stdout: String(error.stdout || '').trim(),
+      stderr: String(error.stderr || error.message || error).trim(),
+    };
+  }
+}
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function toolResult(payload) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+    isError: payload.status === 'failed',
+  };
+}
+
+async function callTool(name, args, progressToken = null) {
+  const workspaceRoot = resolveWorkspaceRoot();
+
+  if (name === 'validateSystemArchitecture') {
+    return toolResult(await runValidatorScript(workspaceRoot, 'validateSystemArchitecture'));
+  }
+
+  if (name === 'validateStageHandoff') {
+    const stage = args && args.stage;
+    if (stage && !HANDOFF_STAGES.includes(stage)) {
+      throw new Error(`Unsupported handoff stage '${stage}'. Expected one of: ${HANDOFF_STAGES.join(', ')}`);
+    }
+    return toolResult(await runValidatorScript(workspaceRoot, 'validateStageHandoff', stage ? [stage] : []));
+  }
+
+  if (name === 'validateTraceProposal') {
+    const proposalPath = (args && args.proposalPath) || DEFAULT_TRACE_PROPOSAL_PATH;
+    return toolResult(await runValidatorScript(workspaceRoot, 'validateTraceProposal', [proposalPath]));
+  }
+
+  if (name === 'runArchitectureTests') {
+    const architecturePath = (args && args.architecturePath) || DEFAULT_ARCHITECTURE_GRAPH_PATH;
+    if (progressToken) {
+      return toolResult(await runValidatorScriptStreaming(workspaceRoot, 'runArchitectureTests', [architecturePath], progressToken));
+    }
+    return toolResult(await runValidatorScript(workspaceRoot, 'runArchitectureTests', [architecturePath]));
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+async function handleRequest(request) {
+  const { id, method, params } = request;
+
+  if (method === 'initialize') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: {
+          tools: {},
+        },
+        serverInfo: {
+          name: 'argo',
+          version: '1.0.0',
+        },
+      },
+    };
+  }
+
+  if (method === 'notifications/initialized') {
+    return null;
+  }
+
+  if (method === 'tools/list') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        tools: TOOLS,
+      },
+    };
+  }
+
+  if (method === 'tools/call') {
+    try {
+      const result = await callTool(params.name, params.arguments || {});
+      return {
+        jsonrpc: '2.0',
+        id,
+        result,
+      };
+    } catch (error) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [
+            {
+              type: 'text',
+              text: String(error && error.stack ? error.stack : error),
+            },
+          ],
+          isError: true,
+        },
+      };
+    }
+  }
+
+  if (method === 'ping') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {},
+    };
+  }
+
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code: -32601,
+      message: `Method not found: ${method}`,
+    },
+  };
+}
+
+async function main() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    crlfDelay: Infinity,
+  });
+
+  for await (const line of rl) {
+    if (!line.trim()) {
+      continue;
+    }
+
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    const response = await handleRequest(request);
+    if (response) {
+      send(response);
+    }
+  }
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  TOOLS,
+  callTool,
+  main,
+};

package/argo/skills/argo-init/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: argo-init
+description: "检查全局 ARGO MCP 是否正常，并完成 NEO4J 初始同步与语义生命周期初始化。Use when the user asks to verify Argo MCP readiness and perform or verify the canonical JSON-to-Neo4j initial sync plus semantic lifecycle init. Keywords: ARGO INIT, harness init, MCP health check, Neo4j initial sync, semantic lifecycle."
+argument-hint: scope-or-mode
+disable-model-invocation: true
+---
+
+# ARGO INIT
+
+`argo-init` 负责检查全局安装的 `argo` MCP 是否正常、完成或验证 canonical intent graph 的 Neo4j 初始同步，并在非 `--check-only` 模式下执行 canonical semantic lifecycle init。它不再负责调用旧的工作区 bootstrap / `initializeWorkspace` 工具。
+
+- `argo` MCP 服务器（全局 `.argo` 安装）能正常初始化、列出关键工具并响应 `ping`。
+- `design/KG/SystemArchitecture.json` 可通过 `argo` MCP 正常读取和校验。
+- 本机 Neo4j 连接可用。
+- canonical intent graph 至少完成一次 JSON -> Neo4j 初始同步，并通过一致性校验。
+- 非 `--check-only` 模式会在结构同步后执行语义生命周期：双 gate 未开启时记录 pending/disabled；双 gate 开启时执行全量 embedding backfill 与 readiness 对齐。
+
+## Rules
+
+- **MUST** 优先运行全局 harness 原生命令（当前工作目录须为目标仓库根）：`node "$env:USERPROFILE\.argo\scripts\ensureArgoHarnessEnvironment.js"`。
+- **MUST** 将该命令返回的 JSON 结果作为最终判断依据，而不是凭主观描述报告环境状态。
+- **MUST** 报告 `argo` MCP 是否通过、Neo4j 是否通过、初始同步是否完成、以及 `semanticLifecycle` 当前状态。
+- **MUST** 在脚本失败时直接转述失败阶段、错误摘要和报告路径，不要改用含糊描述。
+- **MUST NOT** 读取、打印或复述 `.env` 中的 secret 值；排查时只允许报告 key 是否存在、文件是否位于 git 仓库内、以及 ACL 主体。
+- **MUST NOT** 绕开脚本分别手工执行一堆无关命令来替代初始化工作流，除非你是在排查脚本自身失败。
+
+## Workflow
+
+### 1. Run ARGO HARNESS Init
+
+在目标仓库根目录执行（harness 通过 `ARGO_REPO_ROOT` / `WORKSPACE_FOLDER` / `cwd` 解析工作区）：
+
+```powershell
+$env:ARGO_REPO_ROOT = (Get-Location).Path
+node "$env:USERPROFILE\.argo\scripts\ensureArgoHarnessEnvironment.js"
+```
+
+只读检查（不修改工作区、不执行初始同步）：
+
+```powershell
+$env:ARGO_REPO_ROOT = (Get-Location).Path
+node "$env:USERPROFILE\.argo\scripts\ensureArgoHarnessEnvironment.js" --check-only
+```
+
+若通过 `ARGO_ENV_FILE` 指定了秘密文件，请先设置该变量再运行。
+
+### 2. Interpret The Report
+
+读取脚本输出的 JSON，并关注 `mcp`、`systemArchitecture`、`neo4j`、`semanticLifecycle`、`reportPath`。
+
+- `status=ok`：环境已就绪或已确认健康。
+- `status=failed`：指出失败阶段：
+  - Argo MCP protocol health
+  - canonical SystemArchitecture validation
+  - Neo4j connectivity
+  - Neo4j initial sync / verification
+  - semantic lifecycle init / readiness alignment
+
+### 3. Handle Secret File Blockers
+
+全局 `.env` 默认位于 `$env:USERPROFILE\.argo\.env`（可用 `ARGO_ENV_FILE` 覆盖）。安全诊断（不打印 secret 值）：
+
+```powershell
+icacls "$env:USERPROFILE\.argo\.env"
+```
+
+处理规则：
+
+- `SECRET_FILE_ACL_UNSAFE`: 收紧 Windows ACL，只保留当前用户、Administrators、SYSTEM。
+- `SECRET_FILE_REPARSE_PROHIBITED`: 将 `.env` 替换为普通文件（去掉符号链接/重解析点）。
+- `SECRET_FILE_PATH_PROHIBITED`: 修正 `ARGO_ENV_FILE` 与安装根 `.env` 不一致的路径。
+- git 跟踪/忽略类错误（`SECRET_FILE_TRACKED` / `SECRET_FILE_NOT_IGNORED`）只在 `.env` 位于 git 仓库内时出现；全局 `.env` 位于仓库外时天然不适用。
+
+Windows ACL 修复：
+
+```powershell
+$identity = whoami
+icacls "$env:USERPROFILE\.argo\.env" /inheritance:r /grant:r "${identity}:F" "BUILTIN\Administrators:F" "NT AUTHORITY\SYSTEM:F" /remove:g "BUILTIN\Users" "Everyone" "Authenticated Users" "NT AUTHORITY\Authenticated Users"
+```
+
+修复后必须重跑 init。
+
+### 4. Report Concisely
+
+输出应直接说明：
+
+- `argo` MCP 是否正常
+- `SystemArchitecture.json` 是否正常
+- Neo4j 是否连通
+- 是否完成了一次初始同步
+- 语义生命周期状态、alignment、是否因 `--check-only` 跳过
+- 报告文件位置
+
+## Output
+
+输出必须包含：
+
+### 1. Environment Status
+- overall status: ok / failed
+- whether Argo MCP health passed
+- whether Neo4j health passed
+
+### 2. Sync Status
+- whether initial sync was executed
+- whether verification matched JSON and Neo4j
+- current counts summary when available
+
+### 3. Semantic Lifecycle Status
+- whether semantic lifecycle init ran, skipped, or failed
+- state/alignment/readiness summary when available

package/bin/argo-deploy.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const script = path.join(__dirname, '..', 'install-argo.ps1');
+const shell = process.platform === 'win32' ? 'powershell' : 'pwsh';
+const args = ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', script, ...process.argv.slice(2)];
+
+const result = spawnSync(shell, args, { stdio: 'inherit' });
+process.exit(result.status === null ? 1 : result.status);

package/install-argo.ps1

@@ -0,0 +1,112 @@
+#Requires -Version 5.1
+param(
+    [string]$ArgoRoot = "$env:USERPROFILE\.argo",
+    [string]$SkillsRoot = "$env:USERPROFILE\.copilot\skills",
+    [string]$PromptsRoot = "$env:APPDATA\Code\User\prompts",
+    [switch]$SkipEnv,
+    [switch]$SkipDeps
+)
+
+$ErrorActionPreference = 'Stop'
+$repoRoot = $PSScriptRoot
+$argoDir = Join-Path $repoRoot 'argo'
+
+function Copy-Tree {
+    param([string]$Source, [string]$Destination)
+    New-Item -ItemType Directory -Force -Path $Destination | Out-Null
+    Copy-Item -Recurse -Force -Path (Join-Path $Source '*') -Destination $Destination
+}
+
+Write-Host '==> Deploying Argo toolchain'
+
+$schemaSrc = Join-Path $argoDir 'schema'
+$schemaDest = Join-Path $ArgoRoot 'schema'
+Write-Host "[1/4] argo\schema -> $schemaDest"
+Copy-Tree -Source $schemaSrc -Destination $schemaDest
+
+$scriptsSrc = Join-Path $argoDir 'scripts'
+$scriptsDest = Join-Path $ArgoRoot 'scripts'
+Write-Host "[2/4] argo\scripts -> $scriptsDest"
+Copy-Tree -Source $scriptsSrc -Destination $scriptsDest
+
+$skillSrc = Join-Path (Join-Path $argoDir 'skills') 'argo-init'
+$skillDest = Join-Path $SkillsRoot 'argo-init'
+Write-Host "[3/4] argo\skills\argo-init -> $skillDest"
+Copy-Tree -Source $skillSrc -Destination $skillDest
+
+$ruleSrc = Join-Path (Join-Path $argoDir 'rules') 'intent-architecture-global-rule.md'
+$ruleDest = Join-Path $PromptsRoot 'intent-architecture-global-rule.md'
+Write-Host "[4/4] argo\rules\intent-architecture-global-rule.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 "[5/5] argo\package.json -> $depsDest"
+Copy-Item -Force -Path $depsSrc -Destination $depsDest
+
+if ($SkipDeps) {
+    Write-Host 'Skipped dependency install (-SkipDeps).'
+} elseif (Get-Command npm -ErrorAction SilentlyContinue) {
+    Write-Host "==> Installing Node dependencies in $ArgoRoot"
+    $vendorDir = Join-Path $PSScriptRoot 'vendor'
+    Push-Location $ArgoRoot
+    try {
+        $vendorTgzs = @(Get-ChildItem -Path $vendorDir -Filter '*.tgz' -ErrorAction SilentlyContinue)
+        if ($vendorTgzs.Count -gt 0) {
+            foreach ($tgz in $vendorTgzs) {
+                Write-Host "  installing bundled $($tgz.Name)"
+                npm install --no-save --omit=dev --no-audit --no-fund $tgz.FullName
+                if ($LASTEXITCODE -ne 0) {
+                    throw "npm install $($tgz.Name) failed with exit code $LASTEXITCODE"
+                }
+            }
+        } else {
+            npm install --omit=dev --no-audit --no-fund
+            if ($LASTEXITCODE -ne 0) {
+                throw "npm install failed with exit code $LASTEXITCODE"
+            }
+        }
+    } finally {
+        Pop-Location
+    }
+} else {
+    Write-Warning 'npm was not found on PATH; skipped dependency install.'
+}
+
+if ($SkipEnv) {
+    Write-Host 'Skipped .env generation (-SkipEnv).'
+} else {
+    Write-Host ''
+    Write-Host '==> Configure .env (press Enter to leave a value empty and fill it later)'
+    $envKeys = @(
+        'ARGO_EMBEDDING_BASE_URL',
+        'ARGO_EMBEDDING_MODEL',
+        'ARGO_EMBEDDING_PROVIDER',
+        'ARGO_EMBEDDING_MODEL_VERSION',
+        'ARGO_EMBEDDING_DIMENSIONS',
+        'ARGO_NEO4J_DATABASE_URL',
+        'ARGO_NEO4J_DATABASE_USERNAME',
+        'ARGO_NEO4J_DATABASE_PASSWORD',
+        'QWEN_KEY',
+        'ARGO_LIVE_PROVIDER_E2E',
+        'ARGO_W31_LIVE_MUTATION_VECTOR_E2E'
+    )
+
+    $lines = @('# Argo live-provider and Neo4j configuration.')
+    foreach ($key in $envKeys) {
+        $value = Read-Host $key
+        $lines += "$key=$value"
+    }
+
+    $envPath = Join-Path $ArgoRoot '.env'
+    [System.IO.File]::WriteAllLines(
+        $envPath,
+        $lines,
+        (New-Object System.Text.UTF8Encoding $false)
+    )
+    Write-Host "Wrote $envPath"
+}
+
+Write-Host ''
+Write-Host 'Argo deployment complete.'

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "archgraph-argo",
+  "version": "0.1.0",
+  "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
+  "license": "MIT",
+  "bin": {
+    "argo-deploy": "bin/argo-deploy.js"
+  },
+  "files": [
+    "argo/scripts",
+    "argo/schema",
+    "argo/skills/argo-init",
+    "argo/rules",
+    "argo/package.json",
+    "vendor",
+    "install-argo.ps1",
+    "bin"
+  ],
+  "devDependencies": {
+    "neo4j-driver": "^6.2.0"
+  },
+  "scripts": {
+    "test": "node --test \"tests/*.test.js\""
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}