nexarch 0.12.25 → 0.12.26

package/dist/commands/enroll.js

@@ -2,11 +2,20 @@ import { hostname, platform, arch } from "node:os";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { expandHomePath, supportsAutoWrite, writeClientConfig } from "../lib/client-config-writers.js";
 // Matches www.nexarch.ai — the default production host for the web app that
 // owns /api/agent-enrollments/exchange. Not the same service as
 // mcp.nexarch.ai (the MCP gateway); --host exists because staging and
 // self-hosted deployments serve the exchange route from a different origin.
 const DEFAULT_EXCHANGE_HOST = "https://www.nexarch.ai";
+function renderInstructions(template, manifest, token, mcpEndpoint) {
+    return template
+        .replaceAll("{{envVarBraced}}", `\${${manifest.mcp.auth.environmentVariable}}`)
+        .replaceAll("{{envVar}}", manifest.mcp.auth.environmentVariable)
+        .replaceAll("{{mcpUrl}}", mcpEndpoint)
+        .replaceAll("{{serverKey}}", manifest.mcp.serverName)
+        .replaceAll("{{token}}", token);
+}
 const ERROR_MESSAGES = {
     enrollment_invalid: "The enrollment code is invalid, expired, or already used. Ask whoever created it to issue a new one.",
     enrollment_client_mismatch: "This code was issued for a different client type than the one passed to --client. Check the client code against the one configured when the enrollment was created.",
@@ -39,6 +48,7 @@ function redactedManifest(manifest) {
 export async function enroll(args) {
     const asJson = parseFlag(args, "--json");
     const printToken = parseFlag(args, "--print-token");
+    const skipClientConfig = parseFlag(args, "--skip-client-config");
     const code = parseOptionValue(args, "--code");
     const clientCode = parseOptionValue(args, "--client");
     const clientVersion = parseOptionValue(args, "--client-version");
@@ -69,18 +79,49 @@ export async function enroll(args) {
     const destination = outPath ?? join(homedir(), ".nexarch", "agent-credential.json");
     mkdirSync(dirname(destination), { recursive: true });
     writeFileSync(destination, JSON.stringify(manifest, null, 2), { mode: 0o600 });
+    // The gateway's JSON-RPC endpoint is always {mcp.url}/mcp — mcp.url on the
+    // manifest is the bare origin (e.g. https://mcp.nexarch.ai), matching the
+    // convention nexarch mcp-config already uses for the same gateway.
+    const mcpEndpoint = `${manifest.mcp.url.replace(/\/$/, "")}/mcp`;
+    let wroteClientConfig = false;
+    if (!skipClientConfig && manifest.envFilePath && manifest.mcpConfigPath && supportsAutoWrite(manifest.mcpConfigMergeStrategy)) {
+        writeClientConfig(manifest.mcpConfigMergeStrategy, {
+            envFilePath: expandHomePath(manifest.envFilePath),
+            mcpConfigPath: expandHomePath(manifest.mcpConfigPath),
+            serverKey: manifest.mcp.serverName,
+            envVar: manifest.mcp.auth.environmentVariable,
+            mcpUrl: mcpEndpoint,
+            token: manifest.credential.token,
+        });
+        wroteClientConfig = true;
+    }
     if (asJson) {
         const output = printToken ? manifest : redactedManifest(manifest);
-        process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ ...output, wroteClientConfig }, null, 2)}\n`);
         return;
     }
     console.log(`✓ Enrolled agent ${manifest.agent.ref} in workspace "${manifest.workspace.name}"`);
     console.log(`  Scopes     : ${manifest.credential.scopes.join(", ")}`);
     console.log(`  Expires    : ${manifest.credential.expiresAt ?? "never"}`);
-    console.log(`  MCP server : ${manifest.mcp.url}`);
+    console.log(`  MCP server : ${mcpEndpoint}`);
     console.log(`  Credential : saved to ${destination} (mode 600)`);
-    console.log(`\nExport it as ${manifest.mcp.auth.environmentVariable} in the agent runtime's own environment — read`);
-    console.log(`the token from that file rather than pasting it into a shell command or config file.`);
+    if (wroteClientConfig) {
+        console.log(`\n✓ Wired the connection into ${manifest.envFilePath} and ${manifest.mcpConfigPath}`);
+    }
+    else if (skipClientConfig) {
+        console.log(`\nSkipped client config (--skip-client-config passed).`);
+    }
+    else {
+        console.log(`\nNo known auto-write target for client "${clientCode}" — connect it manually:`);
+    }
+    const shownToken = printToken ? manifest.credential.token : `<see ${destination}>`;
+    if (manifest.connectInstructionsTemplate) {
+        console.log(renderInstructions(manifest.connectInstructionsTemplate, manifest, shownToken, mcpEndpoint));
+    }
+    else if (!wroteClientConfig) {
+        console.log(`Export ${manifest.mcp.auth.environmentVariable}=${shownToken} in the agent runtime's own environment, then`);
+        console.log(`point its MCP client at ${mcpEndpoint} (streamable-http, Authorization: Bearer \${${manifest.mcp.auth.environmentVariable}}).`);
+    }
     if (printToken) {
         console.log(`\nToken: ${manifest.credential.token}`);
     }

package/dist/commands/init-agent.js

@@ -8,7 +8,7 @@ import { requireCredentials } from "../lib/credentials.js";
 import { fetchAgentRegistryOrThrow } from "../lib/agent-registry.js";
 import { callMcpTool, mcpInitialize, mcpListTools } from "../lib/mcp.js";
 import { buildVersionAttributes } from "../lib/version-normalization.js";
-import { requestTrustAttestation } from "../lib/trust.js";
+import { requestTrustAttestation, TRUST_ATTESTATION_SCOPE } from "../lib/trust.js";
 const CLI_VERSION = (() => {
     try {
         const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
@@ -443,6 +443,30 @@ function injectAgentConfigs(registry, runtimeCodes, dryRun) {
     }
     return [];
 }
+/**
+ * Whether the trust attestation already sitting in `path` still holds up: present, unexpired,
+ * and minted under the scope this build of the CLI currently mints under. A registration
+ * section can be byte-identical to the current template (so `injectAgentConfigs` reports
+ * `already_present` and writes nothing) while its neighbouring attestation was minted under an
+ * old scope value or has since expired — that staleness is independent of whether the
+ * registration prose changed, so it needs its own check rather than riding on
+ * `already_present` vs `updated`. See ADR-0112.
+ */
+function isTrustAttestationStale(path) {
+    if (!existsSync(path))
+        return true;
+    const content = readFileSync(path, "utf8");
+    const match = content.match(/<!-- nexarch:trust-attestation:start -->\n([\s\S]*?)\n<!-- nexarch:trust-attestation:end -->/);
+    const body = match ? match[1] : content;
+    const scope = body.match(/^scope:\s*(\S+)\s*$/m)?.[1];
+    const expiresAt = body.match(/^expires_at:\s*(\S+)\s*$/m)?.[1];
+    if (!scope || !expiresAt)
+        return true;
+    if (scope !== TRUST_ATTESTATION_SCOPE)
+        return true;
+    const expiry = Date.parse(expiresAt);
+    return Number.isNaN(expiry) || expiry <= Date.now();
+}
 function injectTrustAttestationBlock(path, attestation) {
     // The fallbacks read this very file, so they have to name it: the block is
     // injected into AGENTS.md and .cursorrules too, where a hardcoded CLAUDE.md
@@ -1258,14 +1282,17 @@ export async function initAgent(args) {
             // the dry-run result is accurate and no second pass is needed.
             agentConfigResults = existingInstructionTargets;
         }
-        // Attest only files actually written (injected/updated) just now. When
-        // consent wasn't granted, nothing was written above — `existingInstructionTargets`
-        // is dry-run data with no corresponding file change — so there is
-        // nothing new to attest. An "already_present" target needs no fresh
-        // attestation either: its content, and whatever attestation it already
-        // carries from a prior run, hasn't changed.
+        // Attest files actually written (injected/updated) just now, plus any
+        // "already_present" target whose existing attestation is itself stale
+        // (missing, expired, or minted under an old scope) — the registration
+        // prose matching the template says nothing about whether the neighbouring
+        // attestation is still current, so that's checked independently rather
+        // than assumed from the write status. See ADR-0112 / isTrustAttestationStale.
+        // When consent wasn't granted, nothing was written above —
+        // `existingInstructionTargets` is dry-run data with no corresponding file
+        // change — so there is nothing to attest.
         const attestationTargets = instructionsWriteAllowed
-            ? agentConfigResults.filter((r) => r.status === "injected" || r.status === "updated")
+            ? agentConfigResults.filter((r) => r.status === "injected" || r.status === "updated" || isTrustAttestationStale(r.path))
             : [];
         if (attestationTargets.length > 0) {
             trustAttestationAttempted = true;
@@ -1338,7 +1365,9 @@ export async function initAgent(args) {
                 : !instructionsWriteAllowed
                     ? "skipped (consent not granted)"
                     : !trustAttestationAttempted
-                        ? "skipped (no instruction target written)"
+                        ? agentConfigResults.length > 0
+                            ? "already current (no refresh needed)"
+                            : "skipped (no instruction target written)"
                         : trustAttestation?.ok
                             ? "minted and injected into instruction file(s)"
                             : `unavailable (${trustAttestation?.reason ?? "unknown"})`,

package/dist/index.js

@@ -108,12 +108,16 @@ Usage:
   nexarch enroll        Bootstrap a headless (browserless) agent with a one-time
                         enrollment code — no login required. Writes the resulting
                         credential to ~/.nexarch/agent-credential.json (mode 600)
-                        rather than printing it.
+                        rather than printing it. For a client with a known config
+                        format (e.g. hermes-agent), also writes the connection
+                        directly into that client's own env/config files; for
+                        anything else, prints instructions instead.
                         Options: --code <code>          (required, starts with nxe_)
                                  --client <code>         (required, e.g. hermes-agent)
                                  --client-version <v>
                                  --host <baseUrl>        (default: https://www.nexarch.ai)
                                  --out <path>            write credential here instead
+                                 --skip-client-config    don't touch the client's own files
                                  --print-token           also print the token to stdout
                                  --json
   nexarch logout        Remove stored credentials

package/dist/lib/client-config-writers.js

@@ -0,0 +1,61 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseDocument } from "yaml";
+export function expandHomePath(path) {
+    if (path.startsWith("~/") || path === "~") {
+        return join(homedir(), path.slice(1));
+    }
+    return path;
+}
+/**
+ * Replaces the line for `key=` if present, otherwise appends it — never
+ * touches any other line, so unrelated vars in an existing .env survive.
+ */
+function upsertEnvVar(filePath, key, value) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const existing = existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
+    const lines = existing.length > 0 ? existing.split(/\r?\n/) : [];
+    const lineIndex = lines.findIndex((line) => line.startsWith(`${key}=`));
+    const newLine = `${key}=${value}`;
+    if (lineIndex >= 0) {
+        lines[lineIndex] = newLine;
+    }
+    else {
+        if (lines.length > 0 && lines[lines.length - 1].trim() !== "")
+            lines.push("");
+        lines.push(newLine);
+    }
+    const out = lines.join("\n").replace(/\n*$/, "\n");
+    writeFileSync(filePath, out, { mode: 0o600 });
+}
+/**
+ * Merges one `mcp_servers.<serverKey>` entry into a YAML document, preserving
+ * every other key, comment, and formatting choice already in the file — this
+ * is someone else's live config, not a file this CLI owns. `${VAR}` in the
+ * Authorization header is left as a literal template string; the client
+ * itself (Hermes) resolves it from its own env at connect time, so the raw
+ * token is never written into this file.
+ */
+function yamlUrlBearerStyle(configPath, serverKey, envVar, mcpUrl) {
+    mkdirSync(dirname(configPath), { recursive: true });
+    const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+    const doc = parseDocument(existing);
+    doc.setIn(["mcp_servers", serverKey, "url"], mcpUrl);
+    doc.setIn(["mcp_servers", serverKey, "headers", "Authorization"], `Bearer \${${envVar}}`);
+    writeFileSync(configPath, doc.toString(), { mode: 0o600 });
+}
+const STRATEGIES = {
+    yaml_url_bearer_style: (t) => yamlUrlBearerStyle(t.mcpConfigPath, t.serverKey, t.envVar, t.mcpUrl),
+};
+export function supportsAutoWrite(mergeStrategy) {
+    return Boolean(mergeStrategy && STRATEGIES[mergeStrategy]);
+}
+/** Throws if mergeStrategy isn't recognized — check supportsAutoWrite first. */
+export function writeClientConfig(mergeStrategy, targets) {
+    const strategy = STRATEGIES[mergeStrategy];
+    if (!strategy)
+        throw new Error(`Unknown mcp_config_merge_strategy: ${mergeStrategy}`);
+    upsertEnvVar(targets.envFilePath, targets.envVar, targets.token);
+    strategy(targets);
+}

package/dist/lib/trust.js

@@ -1,6 +1,9 @@
 import https from "https";
 import { requireCredentials } from "./credentials.js";
 const MCP_GATEWAY_URL = "https://mcp.nexarch.ai";
+/** The scope every attestation is minted under — see ADR-0112. Exported so callers can tell a
+ * stored attestation's scope apart from what would be minted today, without duplicating the literal. */
+export const TRUST_ATTESTATION_SCOPE = "agent_config_write";
 /**
  * `contentHash` (sha256 hex of the exact managed-section text being written)
  * binds the signature to the instructions themselves, not just to the claim
@@ -11,7 +14,7 @@ export async function requestTrustAttestation(agentId, contentHash) {
     const creds = requireCredentials();
     const body = JSON.stringify({
         agentId,
-        scope: "agent_config_write",
+        scope: TRUST_ATTESTATION_SCOPE,
         ...(contentHash ? { contentHash } : {}),
     });
     return new Promise((resolve) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.12.25",
+  "version": "0.12.26",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",
@@ -32,5 +32,8 @@
     "@types/node": "^22",
     "tsx": "^4",
     "typescript": "^5"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
   }
 }