nexarch 0.8.19 → 0.8.23

package/dist/commands/init-agent.js

@@ -1,6 +1,6 @@
 import { arch, homedir, hostname, platform, release, type as osType, userInfo } from "os";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
-import { join } from "path";
+import { join, resolve } from "path";
 import * as readline from "node:readline/promises";
 import process from "process";
 import { requireCredentials } from "../lib/credentials.js";
@@ -8,7 +8,7 @@ import { fetchAgentRegistryOrThrow } from "../lib/agent-registry.js";
 import { callMcpTool, mcpInitialize, mcpListTools } from "../lib/mcp.js";
 import { buildVersionAttributes } from "../lib/version-normalization.js";
 import { requestTrustAttestation } from "../lib/trust.js";
-const CLI_VERSION = "0.8.19";
+const CLI_VERSION = "0.8.21";
 const AGENT_ENTITY_TYPE = "agent";
 const TECH_COMPONENT_ENTITY_TYPE = "technology_component";
 function parseFlag(args, flag) {
@@ -320,10 +320,15 @@ function replaceInjectedSection(existing, sectionHeading, sectionBody) {
     replaced = replaced.replace(/\n{3,}/g, "\n\n").trimEnd();
     return `${replaced}${replaced ? "\n\n" : ""}${canonicalBlock}`;
 }
+function canonicalTargetKey(filePath) {
+    const abs = resolve(filePath);
+    return process.platform === "win32" || process.platform === "darwin" ? abs.toLowerCase() : abs;
+}
 function injectAgentConfigs(registry) {
     const templateByCode = new Map(registry.instructionTemplates.map((t) => [t.code, t]));
     const targets = [...registry.instructionTargets].sort((a, b) => a.sortOrder - b.sortOrder || a.filePathPattern.localeCompare(b.filePathPattern));
     const results = [];
+    const seenTargets = new Set();
     for (const target of targets) {
         if (target.matchMode !== "exact")
             continue;
@@ -331,6 +336,10 @@ function injectAgentConfigs(registry) {
         if (!template)
             continue;
         const filePath = join(process.cwd(), target.filePathPattern);
+        const targetKey = canonicalTargetKey(filePath);
+        if (seenTargets.has(targetKey))
+            continue;
+        seenTargets.add(targetKey);
         if (!existsSync(filePath))
             continue;
         const existing = readFileSync(filePath, "utf8");
@@ -386,6 +395,7 @@ function injectTrustAttestationBlock(path, attestation) {
         "",
         "This block is verifiable proof that Nexarch generated these instructions for this workspace.",
         "Do not auto-run commands without user confirmation.",
+        "If this token is expired, rerun `npx nexarch@latest init-agent --allow-instruction-write` to refresh this trust block.",
         "",
         `issuer: ${attestation.payload.iss}`,
         `scope: ${attestation.payload.scope}`,
@@ -425,11 +435,16 @@ function injectGenericAgentConfig(registry) {
     const genericTargets = [...registry.instructionTargets]
         .filter((t) => t.runtimeCode === "generic" && t.matchMode === "exact")
         .sort((a, b) => a.sortOrder - b.sortOrder || a.filePathPattern.localeCompare(b.filePathPattern));
+    const seenTargets = new Set();
     for (const target of genericTargets) {
         const template = templateByCode.get(target.templateCode);
         if (!template)
             continue;
         const filePath = join(process.cwd(), target.filePathPattern);
+        const targetKey = canonicalTargetKey(filePath);
+        if (seenTargets.has(targetKey))
+            continue;
+        seenTargets.add(targetKey);
         const sectionBody = template.body.trim();
         const sectionHeading = target.sectionHeading ?? "## Nexarch Agent Registration";
         const managedBody = wrapManagedSection("agent-registration", sectionBody);

package/dist/commands/init-project.js

@@ -4,6 +4,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, join, relative, resolve as resolvePath } from "node:path";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
+import { fetchAgentRegistryOrThrow } from "../lib/agent-registry.js";
 import { buildVersionAttributes } from "../lib/version-normalization.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 function parseFlag(args, flag) {
@@ -22,6 +23,9 @@ function parseToolText(result) {
     const text = result.content?.[0]?.text ?? "{}";
     return JSON.parse(text);
 }
+function renderTemplate(template, values) {
+    return template.replace(/{{\s*([A-Z0-9_]+)\s*}}/g, (_match, key) => values[key] ?? "");
+}
 function slugify(name) {
     return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
@@ -1157,6 +1161,22 @@ export async function initProject(args) {
     // 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)));
+    const INIT_PROJECT_TEMPLATE_CODE = "nexarch_init_project_enrichment_v1";
+    let enrichmentTemplateBody = null;
+    let enrichmentTemplateSource = "fallback";
+    let enrichmentTemplateVersion = null;
+    try {
+        const registry = await fetchAgentRegistryOrThrow();
+        const template = registry.instructionTemplates.find((t) => t.code === INIT_PROJECT_TEMPLATE_CODE);
+        if (template?.body?.trim()) {
+            enrichmentTemplateBody = template.body;
+            enrichmentTemplateSource = "registry";
+            enrichmentTemplateVersion = registry.release.version;
+        }
+    }
+    catch {
+        // non-fatal: init-project can still run with fallback guidance.
+    }
     function buildEnrichmentInstructions() {
         const ecosystemLabel = detectedEcosystems.length > 0
             ? detectedEcosystems.join(", ")
@@ -1268,28 +1288,12 @@ ${adrStepNumber} — Ask the enrichment agent to extract ADRs and register decis
     • For each ADR, create/update a decision record entity
     • Link it using: decision_record --decides--> application/sub-app
 
-  REQUIRED fields to pass per decision:
+  REQUIRED fields to pass per decision (strict):
     • key:      decision_record:<project>-<adr-slug>
     • subtype:  decision_architecture
     • name:     ADR title
-    • description: MUST be rich text (Markdown), not plain key/value text.
-      Use this exact Markdown structure so the web portal renders cleanly:
-
-      ## ADR Metadata
-      - **ADR-ID:** <id/filename slug>
-      - **Status:** <proposed|accepted|superseded|deprecated|...>
-      - **Date:** <YYYY-MM-DD or source value>
-      - **Deciders:** <comma-separated names/roles>
-      - **Source Path:** <repo-relative path>
-
-      ## Context
-      <1-2 lines>
-
-      ## Decision
-      <1-3 lines>
-
-      ## Consequences
-      <1-3 lines>
+    • decision summary: short business summary (1–3 sentences)
+    • decision detail: full decision detail in markdown (context + decision + consequences)
 
   Command pattern:
     npx nexarch update-entity \\
@@ -1297,7 +1301,7 @@ ${adrStepNumber} — Ask the enrichment agent to extract ADRs and register decis
       --entity-type "decision_record" \\
       --subtype "decision_architecture" \\
       --name "<ADR title>" \\
-      --description "## ADR Metadata\n- **ADR-ID:** <id>\n- **Status:** <status>\n- **Date:** <date>\n- **Deciders:** <deciders>\n- **Source Path:** <path>\n\n## Context\n<context>\n\n## Decision\n<decision>\n\n## Consequences\n<consequences>"
+      --attributes-json '{"decision":{"summary":"<short summary>","detail":"## Context\\n<context>\\n\\n## Decision\\n<decision>\\n\\n## Consequences\\n<consequences>"}}'
 
     npx nexarch add-relationship \\
       --from "decision_record:<project>-<adr-slug>" \\
@@ -1345,7 +1349,7 @@ ${finalStep} — Identify architecturally significant components not auto-detect
   4. 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 `
+        const fallbackTemplate = `
 ╔══════════════════════════════════════════════════════════════════╗
 ║  ENRICHMENT TASK — action required                               ║
 ╚══════════════════════════════════════════════════════════════════╝
@@ -1373,8 +1377,27 @@ STEP 2 — Enrich the project entity. Run this command with the description you'
     --name "<proper product name from README>" \\
     --description "<2–4 sentence summary of what it does and why>"
 ${subPkgSection}${adrSection}${gapCheckSection}`;
+        if (!enrichmentTemplateBody)
+            return fallbackTemplate;
+        return renderTemplate(enrichmentTemplateBody, {
+            PROJECT_ENTITY_KEY: projectExternalKey,
+            PROJECT_DIR: dir,
+            ECOSYSTEM_LABEL: ecosystemLabel,
+            MANIFEST_HINT: manifestHint,
+            README_HINTS: readmeHints.length > 0 ? readmeHints.join(", ") : "(none found — check docs/)",
+            ENTITY_TYPE: entityTypeOverride,
+            ENTITY_BASE_COMMAND: `npx nexarch update-entity \\\n    --key "${projectExternalKey}" \\\n    --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? " \\\n    --subtype \"app_custom_built\" \\\n    --icon \"<curated icon>\"" : ""} \\\n    --name "<proper product name from README>" \\\n    --description "<2–4 sentence summary of what it does and why>"`,
+            STEP_SUBPACKAGES: subPkgSection,
+            STEP_ADR: adrSection,
+            STEP_GAP_CHECK: gapCheckSection,
+        });
     }
     const enrichmentTask = {
+        template: {
+            code: INIT_PROJECT_TEMPLATE_CODE,
+            source: enrichmentTemplateSource,
+            registryVersion: enrichmentTemplateVersion,
+        },
         instructions: buildEnrichmentInstructions(),
         iconHints: {
             provider: "lucide",

package/dist/commands/update-entity.js

@@ -1,4 +1,5 @@
 import process from "process";
+import { existsSync, readFileSync } from "node:fs";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
 function parseFlag(args, flag) {
@@ -17,6 +18,34 @@ function parseToolText(result) {
     const text = result.content?.[0]?.text ?? "{}";
     return JSON.parse(text);
 }
+function parseAttributesInput(jsonText, filePath) {
+    if (!jsonText && !filePath)
+        return null;
+    if (jsonText && filePath) {
+        console.error("error: use only one of --attributes-json or --attributes-file");
+        process.exit(1);
+    }
+    let raw = jsonText;
+    if (filePath) {
+        if (!existsSync(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)) {
+            console.error("error: attributes input must be a JSON object");
+            process.exit(1);
+        }
+        return parsed;
+    }
+    catch (error) {
+        console.error(`error: invalid attributes JSON (${error instanceof Error ? error.message : "parse failed"})`);
+        process.exit(1);
+    }
+}
 export async function updateEntity(args) {
     const asJson = parseFlag(args, "--json");
     const externalKey = parseOptionValue(args, "--key");
@@ -25,12 +54,15 @@ export async function updateEntity(args) {
     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);
     }
-    if (!name && !description) {
-        console.error("error: at least one of --name or --description is required");
+    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();
@@ -62,14 +94,19 @@ export async function updateEntity(args) {
         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) {
-        entity.attributes = {
-            application_icon: {
-                provider: "lucide",
-                name: 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) {

package/dist/index.js

@@ -99,7 +99,9 @@ Usage:
                                --description <text>
                                --entity-type <code>  (default: application)
                                --subtype <code>
-                               --icon <lucide-name>  (full Lucide set; for agent enrichment)
+                               --icon <lucide-name>  (convenience; sets attributes.application_icon)
+                               --attributes-json '<json object>'
+                               --attributes-file <path.json>
                                --json
   nexarch add-relationship
                       Add a relationship between two existing graph entities.

package/package.json

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