nexarch 0.1.28 → 0.1.30

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

package/dist/commands/init-project.js

@@ -249,7 +249,6 @@ function scanProject(dir) {
             const relativePath = pkgPath.replace(dir + "/", "").replace("/package.json", "");
             const packageName = pkg.name ?? relativePath;
             const { entityType, subtype } = classifySubPackage(pkgPath, relativePath);
-            const externalKey = `${entityType}:${slugify(packageName)}`;
             subPackages.push({
                 name: packageName,
                 relativePath,
@@ -257,7 +256,7 @@ function scanProject(dir) {
                 depNames: deps,
                 entityType,
                 subtype,
-                externalKey,
+                externalKey: "", // computed after scan once projectSlug is known
             });
         }
         for (const dep of deps)
@@ -315,6 +314,15 @@ export async function initProject(args) {
     const displayName = nameOverride ?? projectName;
     const projectSlug = slugify(displayName);
     const projectExternalKey = `${entityTypeOverride}:${projectSlug}`;
+    // Compute sub-package external keys now that projectSlug is known.
+    // Unscoped names (no "/") get prefixed with the project slug to avoid ambiguous keys
+    // like "application:crawler" — they become "application:whatsontap-crawler" instead,
+    // matching what the enrichment agent would naturally choose.
+    for (const sp of subPackages) {
+        const nameSlug = slugify(sp.name);
+        const needsPrefix = !sp.name.includes("/") && !nameSlug.startsWith(projectSlug);
+        sp.externalKey = `${sp.entityType}:${needsPrefix ? `${projectSlug}-${nameSlug}` : nameSlug}`;
+    }
     if (!asJson) {
         console.log(`  Project : ${displayName} (${entityTypeOverride})`);
         console.log(`  Packages: ${packageJsonCount} package.json file(s)`);
@@ -532,11 +540,13 @@ ${subPackages.map((sp) => `    • ${sp.name}  (${sp.relativePath})`).join("\n")
     (FROM = ${projectExternalKey}, TO = the library)
 
   ⚠️  WIRE DEPENDENCIES TO THE SUB-APP THAT DECLARES THEM, NOT TO THE PARENT.
-  After registering each sub-app/library entity, wire its npm dependencies to IT:
-    npx nexarch add-relationship \\
-      --from "<sub-app-or-library-key>" \\
-      --to "<resolved-tech-ref>" \\
-      --type "depends_on"
+  After registering each sub-app/library entity, wire its npm dependencies to IT.
+
+  RELATIONSHIP TYPE RULES:
+    application  → technology_component  : --type "depends_on"
+    technology_component → technology_component : --type "uses"   (NOT depends_on)
+    any → platform / platform_component  : --type "uses"
+    any → model                          : --type "uses_model"
 
   Pre-resolved dependencies per sub-package (wire these after registering each entity):
 ${subPackages.map((sp) => {
@@ -545,9 +555,47 @@ ${subPackages.map((sp) => {
                 .filter((r) => !!r?.canonicalExternalRef);
             if (resolved.length === 0)
                 return `    • ${sp.name}: (no pre-resolved deps — check package.json manually)`;
-            const lines = resolved.map((r) => `        --to "${r.canonicalExternalRef}"  # ${r.canonicalName}`);
-            return `    • ${sp.name} (<sub-app-key> depends_on):\n${lines.join("\n")}`;
+            const lines = resolved.map((r) => {
+                const relType = pickRelationshipType(r.entityTypeCode, sp.entityType);
+                return `        --to "${r.canonicalExternalRef}"  --type "${relType}"  # ${r.canonicalName}`;
+            });
+            return `    • ${sp.name} (--from "${sp.externalKey}"):\n${lines.join("\n")}`;
         }).join("\n\n")}
+`;
+        const finalStep = subPackages.length > 0 ? "STEP 4" : "STEP 3";
+        const gapCheckSection = `
+${finalStep} — Identify architecturally significant components not auto-detected.
+
+  The mechanical scan only finds npm packages, env var names, and a few config files.
+  It systematically misses hosting platforms, managed infrastructure, SaaS integrations,
+  and external APIs that are only mentioned in README or deployment config.
+
+  Review what you've read and ask yourself: are there any of the following that are
+  clearly part of this system's architecture but weren't auto-detected?
+
+    • Hosting / deployment platforms  (Vercel, Railway, Fly.io, AWS, GCP, Azure…)
+    • Managed data services           (Neon, PlanetScale, Supabase, Upstash, Atlas…)
+    • Auth / identity providers       (Clerk, Auth0, WorkOS, Okta…)
+    • External SaaS integrations      (Stripe, Resend, SendGrid, Twilio, Sentry…)
+    • CDN / storage / queues          (Cloudflare, S3, CloudFront, SQS, Redis…)
+    • CI/CD platforms                 (GitHub Actions, GitLab CI, CircleCI…)
+
+  ONLY register entries you are highly confident about — i.e. explicitly mentioned in
+  the README, a config file, or a deployment manifest. Do not guess.
+
+  For each one you identify:
+
+  1. Resolve it to a canonical reference:
+     npx nexarch resolve-names --names "<platform name>"
+
+  2. If resolved, wire the relationship from the relevant entity:
+     npx nexarch add-relationship \\
+       --from "${projectExternalKey}" \\
+       --to "<resolved-ref>" \\
+       --type "uses"
+
+  3. 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 `
 ╔══════════════════════════════════════════════════════════════════╗
@@ -574,7 +622,7 @@ STEP 2 — Enrich the project entity. Run this command with the description you'
     --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>"
-${subPkgSection}`;
+${subPkgSection}${gapCheckSection}`;
     }
     const enrichmentTask = {
         instructions: buildEnrichmentInstructions(),

package/dist/commands/resolve-names.js

@@ -0,0 +1,52 @@
+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 resolveNames(args) {
+    const asJson = parseFlag(args, "--json");
+    const namesRaw = parseOptionValue(args, "--names");
+    if (!namesRaw) {
+        console.error("error: --names <comma-separated list> is required");
+        process.exit(1);
+    }
+    const names = namesRaw
+        .split(",")
+        .map((n) => n.trim())
+        .filter(Boolean);
+    if (names.length === 0) {
+        console.error("error: --names must contain at least one name");
+        process.exit(1);
+    }
+    const creds = requireCredentials();
+    const mcpOpts = { companyId: creds.companyId };
+    const raw = await callMcpTool("nexarch_resolve_reference", { names, companyId: creds.companyId }, mcpOpts);
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    for (const entry of result.resolved ?? []) {
+        if (entry.resolved) {
+            console.log(`✓ ${entry.input} → ${entry.canonicalExternalRef}  (${entry.entityTypeCode}${entry.entitySubtypeCode ? `/${entry.entitySubtypeCode}` : ""})  "${entry.canonicalName}"`);
+        }
+        else {
+            console.log(`✗ ${entry.input} — not found in reference library`);
+        }
+    }
+    console.log(`\n${result.totalResolved}/${result.totalRequested} resolved`);
+}

package/dist/index.js

@@ -14,6 +14,7 @@ import { initProject } from "./commands/init-project.js";
 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";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -28,6 +29,7 @@ const commands = {
     "update-entity": updateEntity,
     "add-relationship": addRelationship,
     "register-alias": registerAlias,
+    "resolve-names": resolveNames,
 };
 async function main() {
     if (command === "agent") {
@@ -114,6 +116,13 @@ Usage:
                                --subtype <code>
                                --description <text>
                                --json
+  nexarch resolve-names
+                      Look up one or more raw names (package names, platform
+                      names) against the global reference library and return
+                      their canonical external keys. Useful for gap-check
+                      results before calling add-relationship.
+                      Options: --names <csv>  (required, e.g. "vercel,neon")
+                               --json
     `);
         process.exit(command ? 1 : 0);
     }

package/package.json

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