nexarch 0.9.21 → 0.9.23

package/dist/commands/init-project.js

@@ -444,7 +444,7 @@ function readRootPackage(pkgPath) {
 // Guess entity type + subtype for a sub-package based on its path and package.json scripts.
 function classifySubPackage(pkgPath, relativePath) {
     const topDir = relativePath.split("/")[0] ?? "";
-    // packages/* → shared library/component
+    // packages/* → shared library/component (no server, not independently deployable)
     if (topDir === "packages") {
         const name = relativePath.split("/")[1] ?? "";
         if (name.includes("ui") || name.includes("components"))
@@ -453,9 +453,31 @@ function classifySubPackage(pkgPath, relativePath) {
             return { entityType: "technology_component", subtype: "tech_library" };
         return { entityType: "technology_component", subtype: "tech_library" };
     }
-    // apps/* → deployable application component under the root application.
+    // Read package.json once for script + bin signals used across all paths below.
+    let scripts = [];
+    let hasBin = false;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        scripts = Object.keys(pkg.scripts ?? {});
+        hasBin = pkg.bin !== undefined && pkg.bin !== null;
+    }
+    catch { }
+    const name = relativePath.toLowerCase();
+    const hasServerScript = scripts.some((s) => ["start", "dev", "serve"].includes(s));
+    const hasBuildScript = scripts.some((s) => s === "build");
+    // A bin entry means it is a CLI application regardless of path.
+    if (hasBin)
+        return { entityType: "application", subtype: "app_cli" };
+    // apps/* — treat as full application when it has its own server/dev script
+    // (independently deployable); fall back to component classification otherwise.
     if (topDir === "apps") {
-        const name = relativePath.toLowerCase();
+        if (hasServerScript) {
+            if (name.includes("worker") || name.includes("job") || name.includes("etl") || name.includes("crawl")) {
+                return { entityType: "application", subtype: "app_integration_service" };
+            }
+            return { entityType: "application", subtype: "app_custom_built" };
+        }
+        // No server script → treat as a component of the parent application.
         if (name.includes("worker"))
             return { entityType: "application_component", subtype: "app_comp_worker" };
         if (name.includes("job"))
@@ -475,20 +497,13 @@ function classifySubPackage(pkgPath, relativePath) {
             return { entityType: "application_component", subtype: "app_comp_api" };
         return { entityType: "application_component", subtype: "app_comp_api" };
     }
-    // src/* → deployable application; check scripts
-    try {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-        const scripts = Object.keys(pkg.scripts ?? {});
-        const hasServer = scripts.some((s) => ["start", "dev", "serve", "build"].includes(s));
-        if (hasServer) {
-            const name = relativePath.toLowerCase();
-            if (name.includes("crawl") || name.includes("worker") || name.includes("job") || name.includes("etl")) {
-                return { entityType: "application", subtype: "app_integration_service" };
-            }
-            return { entityType: "application", subtype: "app_custom_built" };
+    // Root-level or other paths — use script signals to detect standalone applications.
+    if (hasServerScript || hasBuildScript) {
+        if (name.includes("crawl") || name.includes("worker") || name.includes("job") || name.includes("etl")) {
+            return { entityType: "application", subtype: "app_integration_service" };
         }
+        return { entityType: "application", subtype: "app_custom_built" };
     }
-    catch { }
     return { entityType: "technology_component", subtype: "tech_library" };
 }
 // Resolve workspace glob patterns (e.g. "apps/*", "packages/*") to actual directories.
@@ -794,6 +809,14 @@ function scanEcosystems(dir) {
 function isApplicationLikeEntityType(entityType) {
     return entityType === "application" || entityType === "application_component";
 }
+/** Returns the structural relationship that should be wired between the root project and this sub-package. */
+function structuralRelForSubPackage(sp, projectExternalKey) {
+    if (sp.entityType === "application")
+        return { type: "composes", from: projectExternalKey, to: sp.externalKey };
+    if (sp.entityType === "application_component")
+        return { type: "part_of", from: sp.externalKey, to: projectExternalKey };
+    return null;
+}
 function scanProject(dir) {
     const names = new Set();
     let projectName = basename(dir);
@@ -1566,8 +1589,16 @@ export async function initProject(args) {
             pendingSteps.push({
                 step: stepNum++,
                 action: "classify_sub_packages",
-                instruction: `Update each sub-package in classifyPackages with a confirmed entity type, subtype, name, and description.`,
-                command: `nexarch update-entity --key "<subPackageExternalKey>" --entity-type "<entityType>" --subtype "<subtype>" --name "..." --description "..."`,
+                instruction: `For each sub-package in classifyPackages: (1) run update-entity to confirm type/subtype/name/description, then (2) immediately run add-relationship to wire the structural relationship. The external key includes the entity type as a prefix — if you change the entity type, the key changes (e.g. application_component:foo → application:foo). Always run update-entity before add-relationship for each package.`,
+                commandTemplates: {
+                    updateEntity: `nexarch update-entity --key "<subPackageExternalKey>" --entity-type "<entityType>" --subtype "<subtype>" --name "..." --description "..."`,
+                    wireRelationship: `nexarch add-relationship --from "<from>" --to "<to>" --type <composes|part_of>  (see structuralRelationship on each classifyPackages entry)`,
+                },
+                notes: [
+                    "application sub-packages: parent composes sub-app  →  add-relationship --from parent --to sub-app --type composes",
+                    "application_component sub-packages: component part_of parent  →  add-relationship --from sub-pkg --to parent --type part_of",
+                    "Do NOT wire the relationship before the entity exists at the correct key.",
+                ],
             });
         }
         if (entityTypeOverride === "application") {
@@ -1576,8 +1607,8 @@ export async function initProject(args) {
                 action: "discover_functions",
                 instruction: `Review the codebase to identify discrete application functions (what the application does). Examine named modules, route layout, service boundaries, and any architecture documentation. Register functions as application_function entities with subtype core_function (primary business function), supporting_function (auxiliary/enablement), integration_function (external connectivity), or data_function (data processing). Only register functions clearly evidenced by the codebase — do not invent them.`,
                 commandTemplates: {
-                    updateEntity: `nexarch update-entity --key "application_function:${projectSlug}-<function-slug>" --entity-type application_function --subtype core_function --name "..." --description "..."`,
-                    addRelationship: `nexarch add-relationship --from "application_function:${projectSlug}-<function-slug>" --to "${projectExternalKey}" --type part_of`,
+                    updateEntity: `nexarch update-entity --key "application_function:${projectSlug}_<function_slug>" --entity-type application_function --subtype core_function --name "..." --description "..."`,
+                    addRelationship: `nexarch add-relationship --from "application_function:${projectSlug}_<function_slug>" --to "${projectExternalKey}" --type part_of`,
                 },
             });
         }
@@ -1596,8 +1627,8 @@ export async function initProject(args) {
             action: "register_decision_records",
             instruction: `Look for ADRs (docs/adr/, decisions/, ADR-*.md) and register each as a decision_record entity.`,
             commandTemplates: {
-                updateEntity: `nexarch update-entity --key "decision_record:${projectSlug}-<adr-slug>" --entity-type decision_record --subtype decision_architecture --name "..." --attributes-json '{"decision":{"summary":"...","detail":"..."}}'`,
-                addRelationship: `nexarch add-relationship --from "decision_record:${projectSlug}-<adr-slug>" --to "${projectExternalKey}" --type decides`,
+                updateEntity: `nexarch update-entity --key "decision_record:${projectSlug}_<adr_slug>" --entity-type decision_record --subtype decision_architecture --name "..." --attributes-json '{"decision":{"summary":"...","detail":"..."}}'`,
+                addRelationship: `nexarch add-relationship --from "decision_record:${projectSlug}_<adr_slug>" --to "${projectExternalKey}" --type decides`,
             },
         });
         return {
@@ -1624,6 +1655,7 @@ export async function initProject(args) {
                         preWired: preWiredRelationshipKeys.has(relationshipKey),
                     };
                 });
+                const structuralRel = structuralRelForSubPackage(sp, projectExternalKey);
                 return {
                     name: sp.name,
                     relativePath: sp.relativePath,
@@ -1631,6 +1663,9 @@ export async function initProject(args) {
                     heuristicEntityType: sp.entityType,
                     heuristicSubtype: sp.subtype,
                     confidence: subPackageConfidence(sp),
+                    structuralRelationship: structuralRel
+                        ? { ...structuralRel, note: "Wire AFTER update-entity. If entity type changes, update the key prefix in from/to before running add-relationship." }
+                        : null,
                     resolvedDeps,
                     unresolvedDeps: sp.depSpecs.map((d) => d.name).filter((d) => !resolvedByInput.has(d)),
                 };
@@ -1686,6 +1721,10 @@ export async function initProject(args) {
         if (subPackages.length > 0) {
             lines.push("");
             lines.push(`CLASSIFY_THESE (${subPackages.length} sub-package(s) — read each, confirm type, then update):`);
+            lines.push(`  NOTE: The external key includes the entity type as a prefix (e.g. application:foo).`);
+            lines.push(`  If you change the entity type, the key changes too — update-entity will create an entity`);
+            lines.push(`  at the new key. Always wire the structural relationship AFTER the update-entity call,`);
+            lines.push(`  using the confirmed key. Do not wire relationships before the entity exists.`);
             for (const sp of subPackages) {
                 const conf = subPackageConfidence(sp);
                 lines.push(`  ${sp.relativePath}`);
@@ -1695,7 +1734,12 @@ export async function initProject(args) {
                 if (unresolvedDeps.length > 0) {
                     lines.push(`    unresolved deps (${unresolvedDeps.length}): ${unresolvedDeps.slice(0, 5).join(", ")}${unresolvedDeps.length > 5 ? ` … +${unresolvedDeps.length - 5} more` : ""}`);
                 }
-                lines.push(`    → nexarch update-entity --key "${sp.externalKey}" --entity-type "${sp.entityType}" --subtype "${sp.subtype}" --name "..." --description "..."`);
+                lines.push(`    1) nexarch update-entity --key "${sp.externalKey}" --entity-type "${sp.entityType}" --subtype "${sp.subtype}" --name "..." --description "..."`);
+                const rel = structuralRelForSubPackage(sp, projectExternalKey);
+                if (rel) {
+                    lines.push(`    2) nexarch add-relationship --from "${rel.from}" --to "${rel.to}" --type ${rel.type}`);
+                    lines.push(`       (adjust key prefix if you changed the entity type above)`);
+                }
             }
         }
         if (unresolvedItems.length > 0) {
@@ -1724,13 +1768,13 @@ export async function initProject(args) {
             lines.push(`     integration_function (external connectivity), or data_function (data processing).`);
             lines.push(`     Only register functions clearly evidenced by the codebase — do not invent them.`);
             lines.push(`     For each one found:`);
-            lines.push(`       nexarch update-entity --key "application_function:${projectExternalKey.split(":")[1] ?? "project"}-<function-slug>" --entity-type application_function --subtype core_function --name "..." --description "..."`);
-            lines.push(`       nexarch add-relationship --from "application_function:${projectExternalKey.split(":")[1] ?? "project"}-<function-slug>" --to "${projectExternalKey}" --type part_of`);
+            lines.push(`       nexarch update-entity --key "application_function:${projectExternalKey.split(":")[1] ?? "project"}_<function_slug>" --entity-type application_function --subtype core_function --name "..." --description "..."`);
+            lines.push(`       nexarch add-relationship --from "application_function:${projectExternalKey.split(":")[1] ?? "project"}_<function_slug>" --to "${projectExternalKey}" --type part_of`);
         }
         lines.push(`  ${step++}. Scan the READMEs for platforms/SaaS not auto-detected (Vercel, Neon, Stripe, etc.).`);
         lines.push(`       For each found: nexarch resolve-names --names "..." --json  →  nexarch update-entity  →  nexarch add-relationship`);
         lines.push(`  ${step++}. Look for ADRs (docs/adr/, decisions/, ADR-*.md) and register decision_record entities.`);
-        lines.push(`       nexarch update-entity --key "decision_record:${projectExternalKey.split(":")[1] ?? "project"}-<adr-slug>" --entity-type decision_record --subtype decision_architecture --name "..." --attributes-json '{"decision":{"summary":"...","detail":"..."}}'`);
+        lines.push(`       nexarch update-entity --key "decision_record:${projectExternalKey.split(":")[1] ?? "project"}_<adr_slug>" --entity-type decision_record --subtype decision_architecture --name "..." --attributes-json '{"decision":{"summary":"...","detail":"..."}}'`);
         lines.push(`       nexarch add-relationship --from "decision_record:..." --to "${projectExternalKey}" --type decides`);
         lines.push("");
         lines.push("RELATIONSHIP DIRECTION RULES (for sub-packages):");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.9.21",
+  "version": "0.9.23",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",