nexarch 0.1.18 → 0.1.19

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.18";
+const CLI_VERSION = "0.1.19";
 const AGENT_ENTITY_TYPE = "agent";
 const TECH_COMPONENT_ENTITY_TYPE = "technology_component";
 function parseFlag(args, flag) {

package/dist/commands/init-project.js

@@ -437,28 +437,37 @@ STEP 1 — Read the project README / docs and build your understanding of:
   • What is the high-level architecture?
   • Any notable technical decisions or constraints?
 
-STEP 2 — Call nexarch_upsert_entities to enrich the project entity:
-  • externalKey: "${projectExternalKey}"
-  • name: (proper product/project name from the README)
-  • description: (2–4 sentence summary of what it does and why)
-  • Preserve existing attributes, add any business context attributes you find.
-  • entityTypeCode: "${entityTypeOverride}"${entityTypeOverride === "application" ? '\n  • entitySubtypeCode: "app_custom_built"' : ""}
+STEP 2 — Enrich the project entity. Run this command with the description you've written:
+
+  npx nexarch update-entity \\
+    --key "${projectExternalKey}" \\
+    --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? ' \\\n    --subtype "app_custom_built"' : ""} \\
+    --name "<proper product name from README>" \\
+    --description "<2–4 sentence summary of what it does and why>"
 ${subPackages.length > 0 ? `
-STEP 3 — Register each sub-application as its own entity:
-  The scanner found ${subPackages.length} workspace package(s). For each one, call
-  nexarch_upsert_entities then nexarch_upsert_relationships to wire it to the parent.
+STEP 3 — Register each sub-application as its own entity.
+  The scanner found ${subPackages.length} workspace package(s). For each one, read its
+  README / package.json description, then run:
 
   Sub-packages detected:
 ${subPackages.map((sp) => `    • ${sp.name}  (${sp.relativePath})`).join("\n")}
 
-  For each sub-package:
-    • Read its own README / package.json description if present
-    • entityTypeCode: "application", entitySubtypeCode: "app_custom_built"
-    • externalKey: "application:<slug>"  (slugify the package name)
-    • description: what this specific sub-app does
-    • Relationship: fromEntityExternalKey = "<sub-app key>",
-                    toEntityExternalKey   = "${projectExternalKey}",
-                    relationshipTypeCode  = "part_of"
-` : ""}
-Once enrichment is complete, run \`nexarch graph snapshot\` to capture the updated state.`);
+  For each sub-package run:
+
+  npx nexarch update-entity \\
+    --key "application:<slugified-package-name>" \\
+    --entity-type "application" \\
+    --subtype "app_custom_built" \\
+    --name "<sub-app name>" \\
+    --description "<what this sub-app does>"
+
+  Then wire it to the parent project:
+
+  npx nexarch add-relationship \\
+    --from "application:<slugified-package-name>" \\
+    --to "${projectExternalKey}" \\
+    --type "part_of"
+
+  (Note: add-relationship is coming soon — skip if not yet available)
+` : ""}`);
 }

package/dist/commands/update-entity.js

@@ -0,0 +1,84 @@
+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 value = args[idx + 1];
+    if (!value || value.startsWith("--"))
+        return null;
+    return value;
+}
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+export async function updateEntity(args) {
+    const asJson = parseFlag(args, "--json");
+    const externalKey = parseOptionValue(args, "--key");
+    const name = parseOptionValue(args, "--name");
+    const description = parseOptionValue(args, "--description");
+    const entityTypeCode = parseOptionValue(args, "--entity-type") ?? "application";
+    const entitySubtypeCode = parseOptionValue(args, "--subtype");
+    if (!externalKey) {
+        console.error("error: --key <externalKey> is required");
+        process.exit(1);
+    }
+    if (!name && !description) {
+        console.error("error: at least one of --name or --description is required");
+        process.exit(1);
+    }
+    const creds = requireCredentials();
+    const mcpOpts = { companyId: creds.companyId };
+    const policiesRaw = await callMcpTool("nexarch_get_applied_policies", {}, mcpOpts);
+    const policies = parseToolText(policiesRaw);
+    const policyBundleHash = policies.policyBundleHash ?? null;
+    const nowIso = new Date().toISOString();
+    const agentContext = {
+        agentId: "nexarch-cli:update-entity",
+        agentRunId: `update-entity-${Date.now()}`,
+        observedAt: nowIso,
+        source: "nexarch-cli",
+        model: "n/a",
+        provider: "n/a",
+    };
+    const policyContext = policyBundleHash
+        ? { policyBundleHash, alignmentSummary: { score: 1, violations: [], waivers: [] } }
+        : undefined;
+    const entity = {
+        externalKey,
+        entityTypeCode,
+        confidence: 1,
+    };
+    if (name)
+        entity.name = name;
+    if (description)
+        entity.description = description;
+    if (entitySubtypeCode)
+        entity.entitySubtypeCode = entitySubtypeCode;
+    const raw = await callMcpTool("nexarch_upsert_entities", { entities: [entity], agentContext, policyContext }, mcpOpts);
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        if (Number(result.summary?.failed ?? 0) > 0)
+            process.exitCode = 1;
+        return;
+    }
+    const succeeded = result.summary?.succeeded ?? 0;
+    const failed = result.summary?.failed ?? 0;
+    if (failed > 0) {
+        console.error(`Failed to update entity: ${externalKey}`);
+        for (const err of result.errors ?? []) {
+            console.error(`  ${err.externalKey}: ${err.error} — ${err.message}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (!asJson) {
+        console.log(`Updated ${succeeded} entity: ${externalKey}`);
+    }
+}

package/dist/index.js

@@ -11,6 +11,7 @@ import { mcpProxy } from "./commands/mcp-proxy.js";
 import { initAgent } from "./commands/init-agent.js";
 import { agentIdentify } from "./commands/agent-identify.js";
 import { initProject } from "./commands/init-project.js";
+import { updateEntity } from "./commands/update-entity.js";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -22,6 +23,7 @@ const commands = {
     "init-agent": initAgent,
     "agent-identify": agentIdentify,
     "init-project": initProject,
+    "update-entity": updateEntity,
 };
 async function main() {
     if (command === "agent") {
@@ -78,9 +80,19 @@ Usage:
                       names as reference candidates.
                       Options: --dir <path>  (default: cwd)
                                --name <name>  override project name
-                               --entity-type <code>  (default: service)
+                               --entity-type <code>  (default: application)
                                --dry-run  preview without writing
                                --json
+  nexarch update-entity
+                      Update the name and/or description of an existing graph entity.
+                      Use this after init-project to enrich the entity with meaningful
+                      content from the project README or docs.
+                      Options: --key <externalKey>  (required)
+                               --name <name>
+                               --description <text>
+                               --entity-type <code>  (default: application)
+                               --subtype <code>
+                               --json
     `);
         process.exit(command ? 1 : 0);
     }

package/package.json

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