nexarch 0.1.3 → 0.1.5

package/README.md

@@ -19,6 +19,7 @@ npx nexarch setup
 | `nexarch setup` | Auto-configure detected MCP clients |
 | `nexarch mcp-config [client]` | Print config block for manual setup (`claude-desktop`, `cursor`, `windsurf`) |
 | `nexarch mcp-proxy` | stdio→HTTP bridge used internally by MCP clients |
+| `nexarch init-agent [--json] [--strict]` | Run onboarding handshake checks (initialize, tools, policy bootstrap, ingest contract) |
 
 ## Requirements
 

package/dist/commands/init-agent.js

@@ -0,0 +1,86 @@
+import { callMcpTool, mcpInitialize, mcpListTools } from "../lib/mcp.js";
+function parseFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+export async function initAgent(args) {
+    const asJson = parseFlag(args, "--json");
+    const strict = parseFlag(args, "--strict");
+    const checks = [];
+    const init = await mcpInitialize();
+    checks.push({
+        name: "mcp.initialize",
+        ok: true,
+        detail: `${init.serverInfo?.name ?? "unknown"}@${init.serverInfo?.version ?? "unknown"}`,
+    });
+    const tools = await mcpListTools();
+    const toolNames = new Set(tools.map((t) => t.name));
+    const required = [
+        "nexarch_get_applied_policies",
+        "nexarch_get_ingest_contract",
+        "nexarch_upsert_entities",
+        "nexarch_upsert_relationships",
+    ];
+    const missing = required.filter((name) => !toolNames.has(name));
+    checks.push({
+        name: "mcp.tools.list",
+        ok: missing.length === 0,
+        detail: missing.length ? `missing: ${missing.join(", ")}` : `required tools present (${required.length})`,
+    });
+    const policiesRaw = await callMcpTool("nexarch_get_applied_policies", {});
+    const policies = parseToolText(policiesRaw);
+    checks.push({
+        name: "governance.bootstrap",
+        ok: Boolean(policies.policyBundleHash),
+        detail: policies.policyBundleHash
+            ? `policyBundleHash=${policies.policyBundleHash.slice(0, 12)}… policyCount=${policies.policyCount ?? 0}`
+            : "missing policyBundleHash",
+    });
+    const contractRaw = await callMcpTool("nexarch_get_ingest_contract", {});
+    const contract = parseToolText(contractRaw);
+    checks.push({
+        name: "ingest.contract",
+        ok: Boolean(contract.contractVersion),
+        detail: `version=${contract.contractVersion ?? "unknown"}; entities=${contract.ontology?.entityCodes?.length ?? 0}; relationships=${contract.ontology?.relationshipCodes?.length ?? 0}`,
+    });
+    const allPassed = checks.every((c) => c.ok);
+    if (asJson) {
+        const output = {
+            ok: strict ? allPassed : true,
+            passed: allPassed,
+            strict,
+            checks,
+            summary: {
+                total: checks.length,
+                ok: checks.filter((c) => c.ok).length,
+                failed: checks.filter((c) => !c.ok).length,
+            },
+            policyBundleHash: policies.policyBundleHash ?? null,
+            contractVersion: contract.contractVersion ?? null,
+        };
+        process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+        if (strict && !allPassed)
+            process.exitCode = 1;
+        return;
+    }
+    console.log("Running agent onboarding handshake…\n");
+    for (const check of checks) {
+        console.log(`${check.ok ? "✓" : "✗"} ${check.name}`);
+        if (check.detail)
+            console.log(`    ${check.detail}`);
+    }
+    console.log("");
+    if (allPassed) {
+        console.log("✅ Agent handshake completed. Ready for policy-aware ingest.");
+    }
+    else {
+        console.log("⚠ Handshake completed with issues.");
+        if (strict) {
+            console.log("Strict mode enabled, exiting non-zero.");
+            process.exitCode = 1;
+        }
+    }
+}

package/dist/commands/login.js

@@ -29,7 +29,9 @@ function openBrowser(url) {
     const [cmd, args] = process.platform === "darwin"
         ? ["open", [url]]
         : process.platform === "win32"
-            ? ["cmd", ["/c", "start", "", url]]
+            // Avoid cmd parsing issues with '&' in query strings (e.g. OAuth state).
+            // rundll32 reliably opens the full URL without truncating parameters.
+            ? ["rundll32", ["url.dll,FileProtocolHandler", url]]
             : ["xdg-open", [url]];
     execFile(cmd, args, (err) => {
         if (err) {

package/dist/index.js

@@ -5,6 +5,7 @@ import { status } from "./commands/status.js";
 import { setup } from "./commands/setup.js";
 import { mcpConfig } from "./commands/mcp-config.js";
 import { mcpProxy } from "./commands/mcp-proxy.js";
+import { initAgent } from "./commands/init-agent.js";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -13,6 +14,7 @@ const commands = {
     setup,
     "mcp-config": mcpConfig,
     "mcp-proxy": mcpProxy,
+    "init-agent": initAgent,
 };
 async function main() {
     const handler = commands[command ?? ""];
@@ -27,6 +29,7 @@ Usage:
   nexarch setup         Auto-configure your MCP client (Claude Desktop, Cursor, etc.)
   nexarch mcp-config    Print MCP server config block for manual setup
   nexarch mcp-proxy     Run as stdio MCP proxy (used by MCP clients)
+  nexarch init-agent    Run onboarding handshake checks (tools/policies/contract)
     `);
         process.exit(command ? 1 : 0);
     }

package/dist/lib/mcp.js

@@ -2,13 +2,13 @@ import https from "https";
 import { requireCredentials } from "./credentials.js";
 const MCP_GATEWAY_URL = "https://mcp.nexarch.ai";
 const REQUEST_TIMEOUT_MS = 30 * 1000;
-export async function callMcpTool(toolName, toolArgs = {}) {
+async function callMcpRpc(method, params = {}) {
     const creds = requireCredentials();
     const body = JSON.stringify({
         jsonrpc: "2.0",
         id: 1,
-        method: "tools/call",
-        params: { name: toolName, arguments: toolArgs },
+        method,
+        params,
     });
     return new Promise((resolve, reject) => {
         const url = new URL("/mcp", MCP_GATEWAY_URL);
@@ -19,7 +19,7 @@ export async function callMcpTool(toolName, toolArgs = {}) {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                "Authorization": `Bearer ${creds.token}`,
+                Authorization: `Bearer ${creds.token}`,
                 "x-company-id": creds.companyId,
                 "Content-Length": Buffer.byteLength(body),
             },
@@ -34,7 +34,7 @@ export async function callMcpTool(toolName, toolArgs = {}) {
                     if (json.error) {
                         reject(new Error(json.error.message));
                     }
-                    else if (json.result) {
+                    else if (json.result !== undefined) {
                         resolve(json.result);
                     }
                     else {
@@ -54,6 +54,20 @@ export async function callMcpTool(toolName, toolArgs = {}) {
         req.end();
     });
 }
+export async function callMcpTool(toolName, toolArgs = {}) {
+    return callMcpRpc("tools/call", { name: toolName, arguments: toolArgs });
+}
+export async function mcpInitialize() {
+    return callMcpRpc("initialize", {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "nexarch-cli", version: "0.1.4" },
+    });
+}
+export async function mcpListTools() {
+    const result = await callMcpRpc("tools/list", {});
+    return result.tools ?? [];
+}
 export async function forwardToGateway(token, companyId, body) {
     return new Promise((resolve, reject) => {
         const url = new URL("/mcp", MCP_GATEWAY_URL);
@@ -64,7 +78,7 @@ export async function forwardToGateway(token, companyId, body) {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                "Authorization": `Bearer ${token}`,
+                Authorization: `Bearer ${token}`,
                 "x-company-id": companyId,
                 "Content-Length": Buffer.byteLength(body),
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Connect AI coding tools to your Nexarch architecture workspace",
   "keywords": [
     "nexarch",