nexarch 0.1.25 → 0.1.29

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.25";
+const CLI_VERSION = "0.1.29";
 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)
@@ -282,14 +281,19 @@ function scanProject(dir) {
     return { projectName, packageJsonCount: pkgPaths.length, detectedNames: Array.from(names), rootDepNames, subPackages };
 }
 // ─── Relationship type selection ──────────────────────────────────────────────
-function pickRelationshipType(entityTypeCode) {
-    switch (entityTypeCode) {
+function pickRelationshipType(toEntityTypeCode, fromEntityTypeCode = "application") {
+    switch (toEntityTypeCode) {
         case "model":
             return "uses_model";
         case "platform":
         case "platform_component":
         case "skill":
             return "uses";
+        case "technology_component":
+            // tech→tech depends_on is not allowed by ontology; use "uses" instead
+            if (fromEntityTypeCode === "technology_component")
+                return "uses";
+            return "depends_on";
         default:
             return "depends_on";
     }
@@ -310,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)`);
@@ -454,7 +467,7 @@ export async function initProject(args) {
             const r = resolvedByInput.get(depName);
             if (!r?.canonicalExternalRef || !r.entityTypeCode)
                 continue;
-            addRel(pickRelationshipType(r.entityTypeCode), sp.externalKey, r.canonicalExternalRef);
+            addRel(pickRelationshipType(r.entityTypeCode, sp.entityType), sp.externalKey, r.canonicalExternalRef);
         }
     }
     if (!asJson)
@@ -468,64 +481,11 @@ export async function initProject(args) {
         const relsRaw = await callMcpTool("nexarch_upsert_relationships", { relationships, agentContext, policyContext }, mcpOpts);
         relsResult = parseToolText(relsRaw);
     }
-    const output = {
-        ok: Number(entitiesResult.summary?.failed ?? 0) === 0,
-        project: { name: displayName, externalKey: projectExternalKey, entityType: entityTypeOverride },
-        entities: entitiesResult.summary ?? {},
-        relationships: relsResult?.summary ?? { requested: 0, succeeded: 0, failed: 0 },
-        resolved: resolvedItems.length,
-        unresolved: unresolvedItems.length,
-        unresolvedSample: unresolvedItems.slice(0, 10).map((r) => r.input),
-        entityErrors: entitiesResult.errors ?? [],
-        relationshipErrors: relsResult?.errors ?? [],
-    };
-    if (asJson) {
-        process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
-        if (!output.ok)
-            process.exitCode = 1;
-        return;
-    }
-    console.log(`\nDone.`);
-    console.log(`  Entities     : ${output.entities.succeeded ?? 0} written, ${output.entities.failed ?? 0} failed`);
-    console.log(`  Relationships: ${output.relationships.succeeded ?? 0} written`);
-    if (unresolvedItems.length > 0) {
-        console.log(`  Candidates   : ${unresolvedItems.length} added to reference candidates`);
-    }
-    if (output.entityErrors.length > 0) {
-        console.log("\nEntity errors:");
-        for (const err of output.entityErrors) {
-            console.log(`  ${err.externalKey}: ${err.error} — ${err.message}`);
-        }
-    }
-    // ─── Enrichment task ────────────────────────────────────────────────────────
+    // Build structured enrichment task (included in JSON output and printed in human mode)
     const readmeHints = ["README.md", "README.mdx", "docs/README.md", "docs/index.md"]
         .filter((f) => existsSync(join(dir, f)));
-    console.log(`
-╔══════════════════════════════════════════════════════════════════╗
-║  ENRICHMENT TASK — action required                               ║
-╚══════════════════════════════════════════════════════════════════╝
-
-The mechanical scan has written a skeleton graph entry for this project.
-You now need to enrich it with meaningful content.
-
-PROJECT ENTITY  : ${projectExternalKey}
-PROJECT DIR     : ${dir}
-${readmeHints.length > 0 ? `README FILES    : ${readmeHints.join(", ")}` : "README FILES    : (none found — check docs/)"}
-
-STEP 1 — Read the project README / docs and build your understanding of:
-  • What does this project do? (business purpose, key features)
-  • Who are the users?
-  • What is the high-level architecture?
-  • Any notable technical decisions or constraints?
-
-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 ? `
+    function buildEnrichmentInstructions() {
+        const subPkgSection = subPackages.length === 0 ? "" : `
 STEP 3 — Classify and register each sub-package as its own entity.
   The scanner found ${subPackages.length} workspace package(s):
 
@@ -580,21 +540,143 @@ ${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) => {
-        const resolved = sp.depNames
-            .map((d) => resolvedByInput.get(d))
-            .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")}`;
-    }).join("\n\n")}
-` : ""}`);
+            const resolved = sp.depNames
+                .map((d) => resolvedByInput.get(d))
+                .filter((r) => !!r?.canonicalExternalRef);
+            if (resolved.length === 0)
+                return `    • ${sp.name}: (no pre-resolved deps — check package.json manually)`;
+            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 `
+╔══════════════════════════════════════════════════════════════════╗
+║  ENRICHMENT TASK — action required                               ║
+╚══════════════════════════════════════════════════════════════════╝
+
+The mechanical scan has written a skeleton graph entry for this project.
+You now need to enrich it with meaningful content.
+
+PROJECT ENTITY  : ${projectExternalKey}
+PROJECT DIR     : ${dir}
+${readmeHints.length > 0 ? `README FILES    : ${readmeHints.join(", ")}` : "README FILES    : (none found — check docs/)"}
+
+STEP 1 — Read the project README / docs and build your understanding of:
+  • What does this project do? (business purpose, key features)
+  • Who are the users?
+  • What is the high-level architecture?
+  • Any notable technical decisions or constraints?
+
+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>"
+${subPkgSection}${gapCheckSection}`;
+    }
+    const enrichmentTask = {
+        instructions: buildEnrichmentInstructions(),
+        projectEntity: {
+            externalKey: projectExternalKey,
+            entityType: entityTypeOverride,
+            readmeFiles: readmeHints,
+        },
+        subPackages: subPackages.map((sp) => {
+            const resolvedDeps = sp.depNames
+                .map((d) => resolvedByInput.get(d))
+                .filter((r) => !!r?.canonicalExternalRef)
+                .map((r) => ({ canonicalExternalRef: r.canonicalExternalRef, canonicalName: r.canonicalName, entityTypeCode: r.entityTypeCode }));
+            return {
+                name: sp.name,
+                relativePath: sp.relativePath,
+                externalKey: sp.externalKey,
+                inferredEntityType: sp.entityType,
+                inferredSubtype: sp.subtype,
+                resolvedDeps,
+                unresolvedDeps: sp.depNames.filter((d) => !resolvedByInput.has(d)),
+            };
+        }),
+    };
+    const output = {
+        ok: Number(entitiesResult.summary?.failed ?? 0) === 0,
+        project: { name: displayName, externalKey: projectExternalKey, entityType: entityTypeOverride },
+        entities: entitiesResult.summary ?? {},
+        relationships: relsResult?.summary ?? { requested: 0, succeeded: 0, failed: 0 },
+        resolved: resolvedItems.length,
+        unresolved: unresolvedItems.length,
+        unresolvedSample: unresolvedItems.slice(0, 10).map((r) => r.input),
+        entityErrors: entitiesResult.errors ?? [],
+        relationshipErrors: relsResult?.errors ?? [],
+        enrichmentTask,
+    };
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+        if (!output.ok)
+            process.exitCode = 1;
+        return;
+    }
+    console.log(`\nDone.`);
+    console.log(`  Entities     : ${output.entities.succeeded ?? 0} written, ${output.entities.failed ?? 0} failed`);
+    console.log(`  Relationships: ${output.relationships.succeeded ?? 0} written`);
+    if (unresolvedItems.length > 0) {
+        console.log(`  Candidates   : ${unresolvedItems.length} added to reference candidates`);
+    }
+    if (output.entityErrors.length > 0) {
+        console.log("\nEntity errors:");
+        for (const err of output.entityErrors) {
+            console.log(`  ${err.externalKey}: ${err.error} — ${err.message}`);
+        }
+    }
+    // ─── Enrichment task ────────────────────────────────────────────────────────
+    console.log(enrichmentTask.instructions);
 }

package/package.json

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