nexarch 0.1.20 → 0.1.22

package/dist/commands/add-relationship.js

@@ -0,0 +1,80 @@
+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 addRelationship(args) {
+    const asJson = parseFlag(args, "--json");
+    const fromKey = parseOptionValue(args, "--from");
+    const toKey = parseOptionValue(args, "--to");
+    const relType = parseOptionValue(args, "--type");
+    if (!fromKey) {
+        console.error("error: --from <externalKey> is required");
+        process.exit(1);
+    }
+    if (!toKey) {
+        console.error("error: --to <externalKey> is required");
+        process.exit(1);
+    }
+    if (!relType) {
+        console.error("error: --type <relationshipTypeCode> 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:add-relationship",
+        agentRunId: `add-relationship-${Date.now()}`,
+        repoRef: fromKey,
+        observedAt: nowIso,
+        source: "nexarch-cli",
+        model: "n/a",
+        provider: "n/a",
+    };
+    const policyContext = policyBundleHash
+        ? { policyBundleHash, alignmentSummary: { score: 1, violations: [], waivers: [] } }
+        : undefined;
+    const relationship = {
+        relationshipTypeCode: relType,
+        fromEntityExternalKey: fromKey,
+        toEntityExternalKey: toKey,
+        confidence: 1,
+    };
+    const raw = await callMcpTool("nexarch_upsert_relationships", { relationships: [relationship], 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 add relationship: ${fromKey} -[${relType}]-> ${toKey}`);
+        for (const err of result.errors ?? []) {
+            console.error(`  ${err.error} — ${err.message}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`Added ${succeeded} relationship: ${fromKey} -[${relType}]-> ${toKey}`);
+}

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

package/dist/commands/init-project.js

@@ -445,29 +445,41 @@ STEP 2 — Enrich the project entity. Run this command with the description you'
     --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, read its
-  README / package.json description, then run:
+STEP 3 — Classify and register each sub-package as its own entity.
+  The scanner found ${subPackages.length} workspace package(s):
 
-  Sub-packages detected:
 ${subPackages.map((sp) => `    • ${sp.name}  (${sp.relativePath})`).join("\n")}
 
-  For each sub-package run:
+  For each one, READ its package.json and any README to understand what it actually is,
+  then choose the correct entity type and subtype before running update-entity:
 
-  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>"
+  CLASSIFICATION GUIDE — pick the best fit:
+    Deployable web app (has a dev/start/build script, runs in a browser or as a server)
+      → --entity-type application --subtype app_web
+    Deployable background service, worker, or data pipeline (runs as a process, no UI)
+      → --entity-type application --subtype app_custom_built  (or app_integration_service for crawlers/ETL)
+    Shared internal library or package (imported by other packages, not deployed on its own)
+      → --entity-type technology_component --subtype tech_library
+    Shared UI component library
+      → --entity-type technology_component --subtype tech_framework
+    Type definitions or utility package with no runtime
+      → --entity-type technology_component --subtype tech_library
+
+  For each sub-package, run:
 
-  Then wire it to the parent project:
+  npx nexarch update-entity \\
+    --key "<entity-type>:<slugified-package-name>" \\
+    --entity-type "<chosen entity type>" \\
+    --subtype "<chosen subtype>" \\
+    --name "<human readable name>" \\
+    --description "<what this package does and its role in the project>"
 
-  npx nexarch add-relationship \\
-    --from "application:<slugified-package-name>" \\
-    --to "${projectExternalKey}" \\
-    --type "part_of"
+  Then wire it to the parent project using the appropriate relationship:
+    • Deployable apps  → relationship type: part_of
+    • Shared libraries → relationship type: depends_on  (parent depends on the library)
 
-  (Note: add-relationship is coming soon — skip if not yet available)
+  Relationship type reference:
+    part_of      — deployable sub-app is structurally part of the parent product
+    depends_on   — parent product depends on a shared library at runtime
 ` : ""}`);
 }

package/dist/index.js

@@ -12,6 +12,7 @@ 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";
+import { addRelationship } from "./commands/add-relationship.js";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -24,6 +25,7 @@ const commands = {
     "agent-identify": agentIdentify,
     "init-project": initProject,
     "update-entity": updateEntity,
+    "add-relationship": addRelationship,
 };
 async function main() {
     if (command === "agent") {
@@ -93,6 +95,12 @@ Usage:
                                --entity-type <code>  (default: application)
                                --subtype <code>
                                --json
+  nexarch add-relationship
+                      Add a relationship between two existing graph entities.
+                      Options: --from <externalKey>  (required)
+                               --to <externalKey>    (required)
+                               --type <code>         (required, e.g. part_of, depends_on)
+                               --json
     `);
         process.exit(command ? 1 : 0);
     }

package/package.json

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