nexarch 0.1.32 → 0.1.33

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.32";
+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/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.32",
+  "version": "0.1.33",
   "description": "Connect AI coding tools to your Nexarch architecture workspace",
   "keywords": [
     "nexarch",