nexarch 0.9.7 → 0.9.9

package/dist/commands/init-agent.js

@@ -444,6 +444,33 @@ function injectTrustAttestationUnavailableBlock(path, reason) {
     }
     writeFileSync(path, replaced !== existing ? replaced : `${existing}${existing.endsWith("\n") ? "" : "\n"}${managed}\n`, "utf8");
 }
+function injectInitProjectReportingContract(path) {
+    const section = [
+        "## Nexarch Init-Project Reporting Contract",
+        "",
+        "When you run `npx nexarch@latest init-project`, treat it as skeleton registration only.",
+        "Do not claim full completion until enrichment commands are actually executed.",
+        "",
+        "Required final status fields in your reply after init-project:",
+        '- `registration_status`: `"skeleton_only"` or `"enriched"`',
+        '- `enrichment_completed`: `true` or `false`',
+        "",
+        "Hard rule:",
+        '- If `enrichment_completed=false`, you MUST include: `Enrichment pending: run update-entity/enrichment steps.`',
+        '- If `enrichment_completed=false`, NEVER say: "fully registered", "fully done", or equivalent.',
+        '- For enrichment, use explicit per-entity `update-entity` runs (no bulk entity-update shortcut).',
+        "",
+        "You may set `registration_status=\"enriched\"` only after executing enrichment actions (e.g. update-entity for project/sub-packages, aliases, and any chosen gap wiring), with evidence-based per-entity descriptions/subtypes.",
+        "",
+    ].join("\n");
+    const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    const managed = wrapManagedSection("init-project-reporting-contract", section.trim());
+    let replaced = replaceManagedSection(existing, "init-project-reporting-contract", section.trim());
+    if (replaced === existing) {
+        replaced = replaceInjectedSection(existing, "## Nexarch Init-Project Reporting Contract", managed);
+    }
+    writeFileSync(path, replaced !== existing ? replaced : `${existing}${existing.endsWith("\n") ? "" : "\n"}${managed}\n`, "utf8");
+}
 function injectGenericAgentConfig(registry) {
     const templateByCode = new Map(registry.instructionTemplates.map((t) => [t.code, t]));
     const genericTargets = [...registry.instructionTargets]
@@ -1114,6 +1141,7 @@ export async function initAgent(args) {
                         else {
                             injectTrustAttestationUnavailableBlock(r.path, trustAttestation.reason ?? "unknown");
                         }
+                        injectInitProjectReportingContract(r.path);
                     }
                     catch {
                         // non-fatal
@@ -1222,6 +1250,13 @@ export async function initAgent(args) {
                         consentPrompt: "I detected a likely project in this directory. Do you want me to run init-project now?",
                         actionIfApproved: "run_init_project",
                         command: "npx nexarch@latest init-project --dir . --json",
+                        reportingContract: {
+                            requiredFields: ["registration_status", "enrichment_completed"],
+                            allowedRegistrationStatus: ["skeleton_only", "enriched"],
+                            forbiddenWhenEnrichmentPending: ["fully registered", "fully done"],
+                            mandatoryLineWhenEnrichmentPending: "Enrichment pending: run update-entity/enrichment steps.",
+                            enrichmentMode: "per_entity_updates_only",
+                        },
                     }
                     : {
                         detected: false,

package/dist/commands/init-project.js

@@ -1667,6 +1667,11 @@ STEP 1 — Read the project README / docs and build your understanding of:
 
 STEP 2 — Enrich the project entity. Run this command with the description you've written:
 
+  ENRICHMENT QUALITY RULE:
+    • Do enrichment as explicit per-entity updates.
+    • Do NOT shortcut with bulk entity updates for semantic enrichment.
+    • The goal is accurate, evidence-based descriptions/subtypes per entity, not just write throughput.
+
   npx nexarch update-entity \\
     --key "${projectExternalKey}" \\
     --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? " \\\n    --subtype \"app_custom_built\" \\\n    --icon \"<curated icon>\"" : ""} \\

package/dist/commands/update-entity.js

@@ -22,124 +22,52 @@ function parseAttributesInput(jsonText, filePath) {
     if (!jsonText && !filePath)
         return null;
     if (jsonText && filePath) {
-        throw new Error("Use only one of --attributes-json or --attributes-file");
+        console.error("error: use only one of --attributes-json or --attributes-file");
+        process.exit(1);
     }
     let raw = jsonText;
     if (filePath) {
         if (!existsSync(filePath)) {
-            throw new Error(`--attributes-file not found: ${filePath}`);
+            console.error(`error: --attributes-file not found: ${filePath}`);
+            process.exit(1);
         }
         raw = readFileSync(filePath, "utf8");
     }
     try {
         const parsed = JSON.parse(raw ?? "{}");
         if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-            throw new Error("Attributes input must be a JSON object");
+            console.error("error: attributes input must be a JSON object");
+            process.exit(1);
         }
         return parsed;
     }
     catch (error) {
-        throw new Error(`Invalid attributes JSON (${error instanceof Error ? error.message : "parse failed"})`);
+        console.error(`error: invalid attributes JSON (${error instanceof Error ? error.message : "parse failed"})`);
+        process.exit(1);
     }
 }
-function parseEntityBatch(args) {
-    const entitiesFile = parseOptionValue(args, "--entities-file");
-    const entitiesJson = parseOptionValue(args, "--entities-json");
-    if (!entitiesFile && !entitiesJson)
-        return null;
-    if (entitiesFile && entitiesJson)
-        throw new Error("Use only one of --entities-file or --entities-json");
-    let raw = entitiesJson;
-    if (entitiesFile) {
-        if (!existsSync(entitiesFile))
-            throw new Error(`--entities-file not found: ${entitiesFile}`);
-        raw = readFileSync(entitiesFile, "utf8");
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw ?? "[]");
-    }
-    catch {
-        throw new Error(entitiesFile ? "--entities-file must contain valid JSON array" : "--entities-json must be valid JSON array");
-    }
-    if (!Array.isArray(parsed) || parsed.length === 0) {
-        throw new Error("Entities input must be a non-empty JSON array");
-    }
-    return parsed.map((item, index) => {
-        const v = (item ?? {});
-        const externalKey = String(v.externalKey ?? v.key ?? "").trim();
-        if (!externalKey)
-            throw new Error(`Entity #${index + 1} is missing externalKey/key`);
-        const entityTypeCode = String(v.entityTypeCode ?? v.entity_type_code ?? "application").trim() || "application";
-        const entitySubtypeCode = String(v.entitySubtypeCode ?? v.entity_subtype_code ?? "").trim();
-        const out = {
-            externalKey,
-            entityTypeCode,
-            confidence: 1,
-        };
-        if (typeof v.name === "string" && v.name.trim())
-            out.name = v.name.trim();
-        if (typeof v.description === "string" && v.description.trim())
-            out.description = v.description.trim();
-        if (entitySubtypeCode)
-            out.entitySubtypeCode = entitySubtypeCode;
-        const attrs = {
-            ...(v.attributes && typeof v.attributes === "object" && !Array.isArray(v.attributes) ? v.attributes : {}),
-        };
-        if (typeof v.icon === "string" && v.icon.trim()) {
-            attrs.application_icon = { provider: "lucide", name: v.icon.trim() };
-        }
-        if (Object.keys(attrs).length > 0)
-            out.attributes = attrs;
-        if (!out.name && !out.description && !out.attributes) {
-            throw new Error(`Entity #${index + 1} must include at least one of name, description, icon, or attributes`);
-        }
-        return out;
-    });
-}
 export async function updateEntity(args) {
     const asJson = parseFlag(args, "--json");
-    const batchEntities = parseEntityBatch(args);
-    let entities;
-    if (batchEntities) {
-        entities = batchEntities;
+    if (parseOptionValue(args, "--entities-json") || parseOptionValue(args, "--entities-file")) {
+        console.error("error: batch entity updates were removed. Use explicit per-entity update-entity commands for enrichment quality.");
+        process.exit(1);
     }
-    else {
-        const externalKey = parseOptionValue(args, "--key");
-        const name = parseOptionValue(args, "--name");
-        const description = parseOptionValue(args, "--description");
-        const entityTypeCode = parseOptionValue(args, "--entity-type") ?? "application";
-        const entitySubtypeCode = parseOptionValue(args, "--subtype");
-        const iconName = parseOptionValue(args, "--icon");
-        const attributesJson = parseOptionValue(args, "--attributes-json");
-        const attributesFile = parseOptionValue(args, "--attributes-file");
-        if (!externalKey)
-            throw new Error("--key <externalKey> is required (or use --entities-file/--entities-json)");
-        const explicitAttributes = parseAttributesInput(attributesJson, attributesFile);
-        if (!name && !description && !iconName && !explicitAttributes) {
-            throw new Error("Provide at least one of --name, --description, --icon, --attributes-json, or --attributes-file");
-        }
-        const entity = {
-            externalKey,
-            entityTypeCode,
-            confidence: 1,
-        };
-        if (name)
-            entity.name = name;
-        if (description)
-            entity.description = description;
-        if (entitySubtypeCode)
-            entity.entitySubtypeCode = entitySubtypeCode;
-        const attributes = {
-            ...(explicitAttributes ?? {}),
-        };
-        if (iconName) {
-            attributes.application_icon = { provider: "lucide", name: iconName };
-        }
-        if (Object.keys(attributes).length > 0) {
-            entity.attributes = attributes;
-        }
-        entities = [entity];
+    const externalKey = parseOptionValue(args, "--key");
+    const name = parseOptionValue(args, "--name");
+    const description = parseOptionValue(args, "--description");
+    const entityTypeCode = parseOptionValue(args, "--entity-type") ?? "application";
+    const entitySubtypeCode = parseOptionValue(args, "--subtype");
+    const iconName = parseOptionValue(args, "--icon");
+    const attributesJson = parseOptionValue(args, "--attributes-json");
+    const attributesFile = parseOptionValue(args, "--attributes-file");
+    if (!externalKey) {
+        console.error("error: --key <externalKey> is required");
+        process.exit(1);
+    }
+    const explicitAttributes = parseAttributesInput(attributesJson, attributesFile);
+    if (!name && !description && !iconName && !explicitAttributes) {
+        console.error("error: provide at least one of --name, --description, --icon, --attributes-json, or --attributes-file");
+        process.exit(1);
     }
     const creds = requireCredentials();
     const mcpOpts = { companyId: creds.companyId };
@@ -150,7 +78,7 @@ export async function updateEntity(args) {
     const agentContext = {
         agentId: "nexarch-cli:update-entity",
         agentRunId: `update-entity-${Date.now()}`,
-        repoRef: String(entities[0]?.externalKey ?? "batch"),
+        repoRef: externalKey,
         observedAt: nowIso,
         source: "nexarch-cli",
         model: "n/a",
@@ -159,7 +87,31 @@ export async function updateEntity(args) {
     const policyContext = policyBundleHash
         ? { policyBundleHash, alignmentSummary: { score: 1, violations: [], waivers: [] } }
         : undefined;
-    const raw = await callMcpTool("nexarch_upsert_entities", { entities, agentContext, policyContext }, mcpOpts);
+    const entity = {
+        externalKey,
+        entityTypeCode,
+        confidence: 1,
+    };
+    if (name)
+        entity.name = name;
+    if (description)
+        entity.description = description;
+    if (entitySubtypeCode)
+        entity.entitySubtypeCode = entitySubtypeCode;
+    const attributes = {
+        ...(explicitAttributes ?? {}),
+    };
+    // Convenience sugar; still generic because user can fully control payload via --attributes-json/file.
+    if (iconName) {
+        attributes.application_icon = {
+            provider: "lucide",
+            name: iconName,
+        };
+    }
+    if (Object.keys(attributes).length > 0) {
+        entity.attributes = attributes;
+    }
+    const raw = await callMcpTool("nexarch_upsert_entities", { entities: [entity], agentContext, policyContext }, mcpOpts);
     const result = parseToolText(raw);
     if (asJson) {
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
@@ -170,17 +122,14 @@ export async function updateEntity(args) {
     const succeeded = result.summary?.succeeded ?? 0;
     const failed = result.summary?.failed ?? 0;
     if (failed > 0) {
-        console.error(`Failed to update entities (${failed}/${entities.length}).`);
+        console.error(`Failed to update entity: ${externalKey}`);
         for (const err of result.errors ?? []) {
             console.error(`  ${err.externalKey}: ${err.error} — ${err.message}`);
         }
         process.exitCode = 1;
         return;
     }
-    if (entities.length === 1) {
-        console.log(`Updated ${succeeded} entity: ${String(entities[0].externalKey)}`);
-    }
-    else {
-        console.log(`Updated ${succeeded}/${entities.length} entities.`);
+    if (!asJson) {
+        console.log(`Updated ${succeeded} entity: ${externalKey}`);
     }
 }

package/dist/index.js

@@ -99,18 +99,18 @@ Usage:
                                --dry-run  preview without writing
                                --json
   nexarch update-entity
-                      Update existing graph entities (single or batch).
-                      Single options: --key <externalKey>
-                                      --name <name>
-                                      --description <text>
-                                      --entity-type <code>  (default: application)
-                                      --subtype <code>
-                                      --icon <lucide-name>  (sets attributes.application_icon)
-                                      --attributes-json '<json object>'
-                                      --attributes-file <path.json>
-                      Batch options:  --entities-json '<json array>'
-                                      --entities-file <path.json>
-                      --json
+                      Update the name and/or description of an existing graph entity.
+                      Use this after init-project to enrich the entity with meaningful
+                      content from the project README or docs.
+                      Options: --key <externalKey>  (required)
+                               --name <name>
+                               --description <text>
+                               --entity-type <code>  (default: application)
+                               --subtype <code>
+                               --icon <lucide-name>  (convenience; sets attributes.application_icon)
+                               --attributes-json '<json object>'
+                               --attributes-file <path.json>
+                               --json
   nexarch add-relationship
                       Add relationships between existing graph entities (single or batch).
                       Single options: --from <externalKey>

package/package.json

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