nexarch 0.9.14 → 0.9.16

package/dist/commands/init-project.js

@@ -1515,12 +1515,66 @@ export async function initProject(args) {
     }
     // Build the structured enrichment payload for JSON output.
     function buildEnrichmentPayload() {
+        const projectSlug = projectExternalKey.split(":")[1] ?? "project";
+        // Build the pendingSteps array — mirrors the THEN_RUN section in buildEnrichmentDirective
+        // so agents using --json receive the same mandatory instructions as text-mode agents.
+        const pendingSteps = [];
+        let stepNum = 1;
+        pendingSteps.push({
+            step: stepNum++,
+            action: "enrich_entity",
+            instruction: `Enrich the project entity with a meaningful name, description, subtype, and icon.`,
+            command: `nexarch update-entity --key "${projectExternalKey}" --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? ' --subtype "<subtype>" --icon "<lucide-icon>"' : ""} --name "..." --description "..."`,
+            ...(entityTypeOverride === "application"
+                ? { notes: ["Valid subtypes: app_custom_built  app_saas  app_mobile  app_cli  app_integration_service  app_data_pipeline", "Choose app_custom_built as the default if none of the others clearly apply."] }
+                : {}),
+        });
+        if (subPackages.length > 0) {
+            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 "..."`,
+            });
+        }
+        if (entityTypeOverride === "application") {
+            pendingSteps.push({
+                step: stepNum++,
+                action: "discover_subsystems",
+                instruction: `Review the codebase to identify functional subsystems. Examine the code structure, named modules, route layout, and any architecture documentation. Only register subsystems clearly evidenced by the codebase — do not invent them.`,
+                commandTemplates: {
+                    updateEntity: `nexarch update-entity --key "application_component:${projectSlug}-<subsystem-slug>" --entity-type application_component --subtype app_comp_subsystem --name "..." --description "..."`,
+                    addRelationship: `nexarch add-relationship --from "application_component:${projectSlug}-<subsystem-slug>" --to "${projectExternalKey}" --type part_of`,
+                },
+            });
+        }
+        pendingSteps.push({
+            step: stepNum++,
+            action: "scan_for_undetected_platforms",
+            instruction: `Scan READMEs and docs for platforms or SaaS services not auto-detected (e.g. Vercel, Neon, Stripe). For each found: resolve → update-entity → add-relationship.`,
+            commandTemplates: {
+                resolve: `nexarch resolve-names --names "..." --json`,
+                updateEntity: `nexarch update-entity --key "<canonicalExternalRef>" --entity-type "<entityType>" --name "..."`,
+                addRelationship: `nexarch add-relationship --from "${projectExternalKey}" --to "<canonicalExternalRef>" --type depends_on`,
+            },
+        });
+        pendingSteps.push({
+            step: stepNum++,
+            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`,
+            },
+        });
         return {
             status: "enrichment_required",
+            note: "IMPORTANT: Execute ALL pendingSteps before reporting the project as registered. Do not pause or ask for confirmation between steps.",
             projectEntity: {
                 externalKey: projectExternalKey,
                 entityType: entityTypeOverride,
             },
+            pendingSteps,
             readFiles: readmeHints,
             classifyPackages: subPackages.map((sp) => {
                 const resolvedDeps = sp.depSpecs
@@ -1631,9 +1685,9 @@ export async function initProject(args) {
             lines.push(`  ${step++}. Update each sub-package listed under CLASSIFY_THESE above.`);
         }
         if (entityTypeOverride === "application") {
-            lines.push(`  ${step++}. Identify functional subsystems from the README and architecture docs.`);
-            lines.push(`     Look for named logical areas (e.g. Billing System, Auth Subsystem, Data Layer, API Service Layer).`);
-            lines.push(`     Only register subsystems that are explicitly named or described — do not invent them.`);
+            lines.push(`  ${step++}. Review the codebase to identify functional subsystems.`);
+            lines.push(`     Examine the code structure, named modules, route layout, and any architecture documentation.`);
+            lines.push(`     Only register subsystems clearly evidenced by the codebase — do not invent them.`);
             lines.push(`     For each one found:`);
             lines.push(`       nexarch update-entity --key "application_component:${projectExternalKey.split(":")[1] ?? "project"}-<subsystem-slug>" --entity-type application_component --subtype app_comp_subsystem --name "..." --description "..."`);
             lines.push(`       nexarch add-relationship --from "application_component:${projectExternalKey.split(":")[1] ?? "project"}-<subsystem-slug>" --to "${projectExternalKey}" --type part_of`);
@@ -1705,6 +1759,9 @@ export async function initProject(args) {
     if (asJson) {
         logProgress("complete", `ok=${output.ok}`);
         process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+        // Also write the human-readable directive to stderr so it surfaces in agent terminals
+        // regardless of whether the agent parses enrichmentRequired.pendingSteps from the JSON.
+        process.stderr.write(`\n${buildEnrichmentDirective()}\n`);
         if (!output.ok)
             process.exitCode = 1;
         return;

package/package.json

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