nexarch 0.1.31 → 0.1.33

package/dist/commands/add-relationship.js

@@ -17,6 +17,29 @@ function parseToolText(result) {
     const text = result.content?.[0]?.text ?? "{}";
     return JSON.parse(text);
 }
+async function tryCreateStubEntity(externalKey, mcpOpts, agentContext, policyContext) {
+    // Only auto-create global reference entities — company entities must be created explicitly
+    if (!externalKey.startsWith("global:"))
+        return false;
+    // Derive a normalised alias from the external key (e.g. "global:platform:vercel" → "vercel")
+    const parts = externalKey.split(":");
+    const alias = parts[parts.length - 1];
+    const resolveRaw = await callMcpTool("nexarch_resolve_reference", { names: [alias], companyId: mcpOpts.companyId }, mcpOpts);
+    const resolveResult = parseToolText(resolveRaw);
+    const match = resolveResult.results?.find((r) => r.resolved && r.canonicalExternalRef === externalKey);
+    if (!match)
+        return false;
+    const entity = {
+        externalKey,
+        entityTypeCode: match.entityTypeCode,
+        name: match.canonicalName,
+        confidence: 1,
+    };
+    if (match.entitySubtypeCode)
+        entity.entitySubtypeCode = match.entitySubtypeCode;
+    await callMcpTool("nexarch_upsert_entities", { entities: [entity], agentContext, policyContext }, mcpOpts);
+    return true;
+}
 export async function addRelationship(args) {
     const asJson = parseFlag(args, "--json");
     const fromKey = parseOptionValue(args, "--from");
@@ -58,8 +81,33 @@ export async function addRelationship(args) {
         toEntityExternalKey: toKey,
         confidence: 1,
     };
-    const raw = await callMcpTool("nexarch_upsert_relationships", { relationships: [relationship], agentContext, policyContext }, mcpOpts);
-    const result = parseToolText(raw);
+    let raw = await callMcpTool("nexarch_upsert_relationships", { relationships: [relationship], agentContext, policyContext }, mcpOpts);
+    let result = parseToolText(raw);
+    // Auto-create global reference stubs if endpoints are missing, then retry once
+    const missingEndpoint = result.errors?.some((e) => e.error === "RELATIONSHIP_ENDPOINT_NOT_FOUND");
+    if (missingEndpoint) {
+        const failedFromKeys = result.errors
+            ?.filter((e) => e.error === "RELATIONSHIP_ENDPOINT_NOT_FOUND" && e.fromEntityExternalKey)
+            .map((e) => e.fromEntityExternalKey);
+        const failedToKeys = result.errors
+            ?.filter((e) => e.error === "RELATIONSHIP_ENDPOINT_NOT_FOUND" && e.toEntityExternalKey)
+            .map((e) => e.toEntityExternalKey);
+        const keysToCreate = [...new Set([...(failedFromKeys ?? []), ...(failedToKeys ?? [])])];
+        // If no specific endpoint keys returned, fall back to trying both
+        if (keysToCreate.length === 0) {
+            keysToCreate.push(fromKey, toKey);
+        }
+        let createdAny = false;
+        for (const key of keysToCreate) {
+            const created = await tryCreateStubEntity(key, mcpOpts, agentContext, policyContext);
+            if (created)
+                createdAny = true;
+        }
+        if (createdAny) {
+            raw = await callMcpTool("nexarch_upsert_relationships", { relationships: [relationship], agentContext, policyContext }, mcpOpts);
+            result = parseToolText(raw);
+        }
+    }
     if (asJson) {
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
         if (Number(result.summary?.failed ?? 0) > 0)

package/dist/commands/check-in.js

@@ -0,0 +1,97 @@
+import process from "process";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+function parseFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseOptionValue(args, option) {
+    const idx = args.indexOf(option);
+    if (idx === -1)
+        return null;
+    const v = args[idx + 1];
+    if (!v || v.startsWith("--"))
+        return null;
+    return v;
+}
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+function loadStoredAgentKey() {
+    const identityPath = join(homedir(), ".nexarch", "identity.json");
+    if (!existsSync(identityPath))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(identityPath, "utf8"));
+        return data.agentKey ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+const COMMAND_TYPE_HINTS = {
+    update_project: "Re-scan the project with `npx nexarch init-project` to update the architecture graph.",
+    drift_audit: "Compare the current codebase to the architecture graph and report any drift or missing entities.",
+    access_audit: "Audit which agents and users have access to this application and report findings.",
+    gap_check: "Run a gap analysis: identify architecturally significant platforms or infrastructure not yet in the graph.",
+    policy_check: "Use nexarch_get_entity_policy_controls with the target entity key to fetch the policy controls linked to this application, evaluate the application against each control, and report findings. If no controls are returned, inform the user that policy_control entities must be linked to the application via 'governs' relationships in the workspace.",
+    enrich_entity: "Update the entity description, subtype, and metadata using information from the README or codebase.",
+    register_aliases: "Find internal package names that are unresolved and register them as company aliases.",
+    custom: "Execute the custom instructions provided.",
+};
+export async function checkIn(args) {
+    const asJson = parseFlag(args, "--json");
+    const agentKeyArg = parseOptionValue(args, "--agent-key");
+    const projectKey = parseOptionValue(args, "--project");
+    const creds = requireCredentials();
+    const agentKey = agentKeyArg ?? loadStoredAgentKey();
+    if (!agentKey) {
+        if (asJson) {
+            process.stdout.write(JSON.stringify({ command: null, reason: "no-agent-key" }) + "\n");
+        }
+        else {
+            console.log("No agent key found. Pass --agent-key or run nexarch init-agent first.");
+        }
+        return;
+    }
+    const mcpOpts = { companyId: creds.companyId };
+    const raw = await callMcpTool("nexarch_claim_command", {
+        agentKey,
+        ...(projectKey ? { projectKey } : {}),
+        companyId: creds.companyId,
+    }, mcpOpts);
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(JSON.stringify(result) + "\n");
+        return;
+    }
+    if (!result.command) {
+        console.log("No pending commands. Nothing to do.");
+        return;
+    }
+    const cmd = result.command;
+    const hint = COMMAND_TYPE_HINTS[cmd.command_type] ?? "";
+    console.log(`\n╔══════════════════════════════════════════════════════════════════╗`);
+    console.log(`║  COMMAND QUEUED — action required                                ║`);
+    console.log(`╚══════════════════════════════════════════════════════════════════╝`);
+    console.log(`\nCommand ID : ${cmd.id}`);
+    console.log(`Type       : ${cmd.command_type}`);
+    console.log(`Target     : ${cmd.target_entity_key ?? "(any)"}`);
+    console.log(`Priority   : ${cmd.priority}`);
+    if (Object.keys(cmd.command_params).length > 0) {
+        console.log(`Params     : ${JSON.stringify(cmd.command_params)}`);
+    }
+    if (hint) {
+        console.log(`\n${hint}`);
+    }
+    if (cmd.instructions) {
+        console.log(`\nInstructions:\n${cmd.instructions}`);
+    }
+    console.log(`\nWhen done, run:`);
+    console.log(`  npx nexarch command-done --id "${cmd.id}" --summary "..."`);
+    console.log(`\nIf it fails, run:`);
+    console.log(`  npx nexarch command-fail --id "${cmd.id}" --error "..."`);
+}

package/dist/commands/command-done.js

@@ -0,0 +1,37 @@
+import process from "process";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+function parseFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseOptionValue(args, option) {
+    const idx = args.indexOf(option);
+    if (idx === -1)
+        return null;
+    const v = args[idx + 1];
+    if (!v || v.startsWith("--"))
+        return null;
+    return v;
+}
+function parseToolText(result) {
+    return JSON.parse(result.content?.[0]?.text ?? "{}");
+}
+export async function commandDone(args) {
+    const asJson = parseFlag(args, "--json");
+    const id = parseOptionValue(args, "--id");
+    const summary = parseOptionValue(args, "--summary");
+    if (!id) {
+        console.error("error: --id <commandId> is required");
+        process.exit(1);
+    }
+    const creds = requireCredentials();
+    const raw = await callMcpTool("nexarch_complete_command", { commandId: id, ...(summary ? { summary } : {}), companyId: creds.companyId }, { companyId: creds.companyId });
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(JSON.stringify(result) + "\n");
+        return;
+    }
+    console.log(`Command ${id} marked completed.`);
+    if (summary)
+        console.log(`Summary: ${summary}`);
+}

package/dist/commands/command-fail.js

@@ -0,0 +1,44 @@
+import process from "process";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+function parseFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseOptionValue(args, option) {
+    const idx = args.indexOf(option);
+    if (idx === -1)
+        return null;
+    const v = args[idx + 1];
+    if (!v || v.startsWith("--"))
+        return null;
+    return v;
+}
+function parseToolText(result) {
+    return JSON.parse(result.content?.[0]?.text ?? "{}");
+}
+export async function commandFail(args) {
+    const asJson = parseFlag(args, "--json");
+    const id = parseOptionValue(args, "--id");
+    const error = parseOptionValue(args, "--error");
+    if (!id) {
+        console.error("error: --id <commandId> is required");
+        process.exit(1);
+    }
+    if (!error) {
+        console.error("error: --error <message> is required");
+        process.exit(1);
+    }
+    const creds = requireCredentials();
+    const raw = await callMcpTool("nexarch_fail_command", { commandId: id, errorMessage: error, companyId: creds.companyId }, { companyId: creds.companyId });
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(JSON.stringify(result) + "\n");
+        return;
+    }
+    if (result.retrying) {
+        console.log(`Command ${id} failed — will be retried.`);
+    }
+    else {
+        console.log(`Command ${id} marked failed.`);
+    }
+}

package/dist/commands/init-agent.js

@@ -4,7 +4,7 @@ import { join } from "path";
 import process from "process";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool, mcpInitialize, mcpListTools } from "../lib/mcp.js";
-const CLI_VERSION = "0.1.31";
+const CLI_VERSION = "0.1.33";
 const AGENT_ENTITY_TYPE = "agent";
 const TECH_COMPONENT_ENTITY_TYPE = "technology_component";
 function parseFlag(args, flag) {
@@ -572,6 +572,15 @@ export async function initAgent(args) {
     let bootstrapFilePath = null;
     let agentConfigResults = [];
     if (registration.ok) {
+        try {
+            // Save identity so check-in can find the agent key
+            const identityDir = join(homedir(), ".nexarch");
+            mkdirSync(identityDir, { recursive: true });
+            writeFileSync(join(identityDir, "identity.json"), JSON.stringify({ agentKey: `agent:${agentId}` }, null, 2), { mode: 0o600 });
+        }
+        catch {
+            // non-fatal
+        }
         try {
             bootstrapFilePath = writeAgentBootstrap({
                 agentId,

package/dist/commands/init-project.js

@@ -585,16 +585,22 @@ ${finalStep} — Identify architecturally significant components not auto-detect
   For each one you identify:
 
   1. Resolve it to a canonical reference:
-     npx nexarch resolve-names --names "<platform name>"
+     npx nexarch resolve-names --names "<platform name>" --json
 
-  2. If resolved, wire the relationship from the relevant entity:
+  2. If resolved, instantiate the entity in the graph (REQUIRED before add-relationship):
+     npx nexarch update-entity \\
+       --key "<resolved-ref>" \\
+       --entity-type "<entityTypeCode from resolve-names>" \\
+       --name "<canonicalName from resolve-names>"
+
+  3. Wire the relationship:
      npx nexarch add-relationship \\
        --from "${projectExternalKey}" \\
        --to "<resolved-ref>" \\
        --type "runs_on"    # for platforms (Vercel, Neon, etc.)
        # use --type "depends_on" for external APIs/SaaS (Stripe, Resend, etc.)
 
-  3. If unresolved (not in the reference library), skip it for now — it will appear
+  4. If unresolved (not in the reference library), skip it for now — it will appear
      as a reference candidate on the next scan once you register an alias for it.
 `;
         return `

package/dist/index.js

@@ -15,6 +15,9 @@ import { updateEntity } from "./commands/update-entity.js";
 import { addRelationship } from "./commands/add-relationship.js";
 import { registerAlias } from "./commands/register-alias.js";
 import { resolveNames } from "./commands/resolve-names.js";
+import { checkIn } from "./commands/check-in.js";
+import { commandDone } from "./commands/command-done.js";
+import { commandFail } from "./commands/command-fail.js";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -30,6 +33,9 @@ const commands = {
     "add-relationship": addRelationship,
     "register-alias": registerAlias,
     "resolve-names": resolveNames,
+    "check-in": checkIn,
+    "command-done": commandDone,
+    "command-fail": commandFail,
 };
 async function main() {
     if (command === "agent") {
@@ -123,6 +129,22 @@ Usage:
                       results before calling add-relationship.
                       Options: --names <csv>  (required, e.g. "vercel,neon")
                                --json
+  nexarch check-in    Poll the command queue and claim the next pending command
+                      for this agent. Reads agent key from ~/.nexarch/identity.json
+                      (written by init-agent) or via --agent-key.
+                      Options: --agent-key <key>   override stored agent key
+                               --project <key>     application entity key
+                               --json
+  nexarch command-done
+                      Mark a claimed command as completed.
+                      Options: --id <commandId>    (required)
+                               --summary <text>    short summary of what was done
+                               --json
+  nexarch command-fail
+                      Mark a claimed command as failed.
+                      Options: --id <commandId>    (required)
+                               --error <message>   (required)
+                               --json
     `);
         process.exit(command ? 1 : 0);
     }

package/package.json

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