nexarch 0.9.34 → 0.11.0

package/dist/commands/applied-policies.js

@@ -0,0 +1,57 @@
+import process from "process";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+function parseFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseOptionValue(args, option) {
+    const idx = args.indexOf(option);
+    if (idx === -1)
+        return null;
+    const v = args[idx + 1];
+    if (!v || v.startsWith("--"))
+        return null;
+    return v;
+}
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+export async function appliedPolicies(args) {
+    const asJson = parseFlag(args, "--json");
+    const showMarkdown = parseFlag(args, "--markdown");
+    if (parseFlag(args, "--help") || parseFlag(args, "-h")) {
+        console.log(`
+Usage:
+  nexarch applied-policies [--pack <packCode>] [--markdown] [--json]
+
+Options:
+  --pack <code>     Filter to a specific policy pack code
+  --markdown        Include full document markdown in human output
+  --json            Print JSON response (always includes markdown)
+`);
+        return;
+    }
+    const packCode = parseOptionValue(args, "--pack") ?? parseOptionValue(args, "--pack-code");
+    const creds = requireCredentials();
+    const raw = await callMcpTool("nexarch_get_applied_policies", { ...(packCode ? { packCode } : {}) }, { companyId: creds.companyId });
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(JSON.stringify(result) + "\n");
+        return;
+    }
+    console.log(`Applied policies${packCode ? ` (pack: ${packCode})` : ""}`);
+    if (result.policyBundleHash)
+        console.log(`Bundle hash: ${result.policyBundleHash}`);
+    console.log(`Documents: ${result.policyCount ?? 0}`);
+    for (const pack of result.policies ?? []) {
+        console.log(`\n[${pack.packCode}] ${pack.packName} — v${pack.installedVersion}`);
+        for (const doc of pack.documents ?? []) {
+            console.log(`  - ${doc.title} (${doc.code})`);
+            if (showMarkdown && doc.contentMarkdown) {
+                const indented = doc.contentMarkdown.split("\n").map((l) => `      ${l}`).join("\n");
+                console.log(indented);
+            }
+        }
+    }
+}

package/dist/commands/governance-summary.js

@@ -0,0 +1,56 @@
+import process from "process";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+function parseFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+export async function governanceSummary(args) {
+    const asJson = parseFlag(args, "--json");
+    if (parseFlag(args, "--help") || parseFlag(args, "-h")) {
+        console.log(`
+Usage:
+  nexarch governance-summary [--json]
+
+Returns review queue counts, graph stats, and a per-application policy
+audit rollup (latest run status, pass/partial/fail counts).
+`);
+        return;
+    }
+    const creds = requireCredentials();
+    const raw = await callMcpTool("nexarch_get_governance_summary", { companyId: creds.companyId }, { companyId: creds.companyId });
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(JSON.stringify(result) + "\n");
+        return;
+    }
+    console.log("Governance summary");
+    const review = result.reviewQueue ?? {};
+    console.log(`  Review queue: ${review.pending_entities ?? 0} entities, ${review.pending_relationships ?? 0} relationships`);
+    console.log(`  Graph: ${result.graphEntityCount ?? 0} entities, ${result.graphRelationshipCount ?? 0} relationships (${result.architectureFactCount ?? 0} facts)`);
+    console.log(`  Canonical coverage: ${result.canonicalCoverageOverallPct ?? 0}% overall ` +
+        `(entities ${result.canonicalCoverageEntityPct ?? 0}%, relationships ${result.canonicalCoverageRelationshipPct ?? 0}%)`);
+    console.log(`  Canonical registry size: ${result.canonicalRegistryCount ?? 0}`);
+    const audit = result.policyAudit;
+    if (audit) {
+        console.log("\nPolicy audit rollup");
+        console.log(`  Applications: ${audit.totalApplications} (audited ${audit.appsAudited}, missing audit ${audit.appsWithoutAudit})`);
+        console.log(`  With failures: ${audit.appsWithFailures}, with partials only: ${audit.appsWithPartials}, clean: ${audit.appsClean}`);
+        if (audit.applications.length > 0) {
+            console.log("\n  Per application:");
+            for (const app of audit.applications) {
+                if (!app.latestRunId) {
+                    console.log(`    - ${app.applicationName} (${app.applicationEntityRef}): no audit run`);
+                    continue;
+                }
+                console.log(`    - ${app.applicationName} (${app.applicationEntityRef}): ${app.latestRunStatus} — ` +
+                    `${app.passCount ?? 0} pass, ${app.partialCount ?? 0} partial, ${app.failCount ?? 0} fail` +
+                    (app.totalRules ? ` of ${app.totalRules}` : "") +
+                    (app.completedAt ? ` (completed ${app.completedAt})` : ""));
+            }
+        }
+    }
+}

package/dist/commands/init-project.js

@@ -1490,7 +1490,8 @@ export async function initProject(args) {
     // Upsert entities (chunked for progressive feedback)
     const entityChunks = chunkArray(entities, Math.max(1, upsertBatchSize));
     const entitiesResult = {
-        summary: { requested: 0, succeeded: 0, failed: 0 },
+        summary: { requested: 0, succeeded: 0, failed: 0, preserved: 0 },
+        preserved: [],
         errors: [],
     };
     logProgress("upsert.entities.start", `count=${entities.length}, batches=${entityChunks.length}, batchSize=${Math.max(1, upsertBatchSize)}`);
@@ -1511,7 +1512,10 @@ export async function initProject(args) {
         }
         entitiesResult.summary.requested = Number(entitiesResult.summary.requested ?? 0) + Number(chunkResult.summary?.requested ?? chunk.length);
         entitiesResult.summary.succeeded = Number(entitiesResult.summary.succeeded ?? 0) + Number(chunkResult.summary?.succeeded ?? 0);
+        entitiesResult.summary.preserved = Number(entitiesResult.summary.preserved ?? 0) + Number(chunkResult.summary?.preserved ?? 0);
         entitiesResult.summary.failed = Number(entitiesResult.summary.failed ?? 0) + Number(chunkResult.summary?.failed ?? 0);
+        if (chunkResult.preserved?.length)
+            entitiesResult.preserved.push(...chunkResult.preserved);
         if (chunkResult.errors?.length)
             entitiesResult.errors.push(...chunkResult.errors);
         logProgress("upsert.entities.batch.done", `${i + 1}/${entityChunks.length} succeeded=${chunkResult.summary?.succeeded ?? 0}, failed=${chunkResult.summary?.failed ?? 0}`);
@@ -1620,11 +1624,26 @@ export async function initProject(args) {
                 addRelationship: `nexarch add-relationship --from "decision_record:${projectSlug}_<adr_slug>" --to "${projectExternalKey}" --type decides`,
             },
         });
+        const preservedEntities = entitiesResult.preserved ?? [];
+        const nothingWritten = (entitiesResult.summary?.succeeded ?? 0) === 0;
+        const status = refreshMode && nothingWritten && preservedEntities.length > 0
+            ? "review_enrichment"
+            : "enrichment_required";
         return {
-            status: "enrichment_required",
-            note: refreshMode
-                ? "Execute ALL pendingSteps. In refresh mode, compare graphState vs scanState to identify gaps — do not blindly remove relationships the scanner missed; the scanner cannot detect platforms, integrations, data assets, or application_functions."
-                : "Execute ALL pendingSteps before reporting the project as registered. Do not pause or ask for confirmation between steps.",
+            status,
+            note: status === "review_enrichment"
+                ? "No new skeletons were written — all entities were already enriched and preserved. Review the preservedEntities list and confirm scan values match. Update with nexarch update-entity only if something has genuinely changed."
+                : refreshMode
+                    ? "Execute ALL pendingSteps. In refresh mode, compare graphState vs scanState to identify gaps — do not blindly remove relationships the scanner missed; the scanner cannot detect platforms, integrations, data assets, or application_functions."
+                    : "Execute ALL pendingSteps before reporting the project as registered. Do not pause or ask for confirmation between steps.",
+            ...(refreshMode && preservedEntities.length > 0
+                ? {
+                    preservedEntities: {
+                        note: "These entities already have enriched content and were NOT overwritten by the scan. Review the scan values — if anything has genuinely changed, update with nexarch update-entity.",
+                        entities: preservedEntities,
+                    },
+                }
+                : {}),
             projectEntity: {
                 externalKey: projectExternalKey,
                 entityType: entityTypeOverride,
@@ -1709,11 +1728,19 @@ export async function initProject(args) {
     // This is addressed to the *calling agent* (Claude Code, Codex, etc.) and tells it
     // to act inline in this same session — not to queue enrichment for later.
     function buildEnrichmentDirective() {
+        const preservedEntities = entitiesResult.preserved ?? [];
         const lines = [];
-        lines.push("─── ENRICHMENT REQUIRED ─────────────────────────────────────────────────");
-        lines.push("init-project wrote a skeleton. Complete enrichment below — do not ask the");
-        lines.push("user for permission, do not summarise and pause, just execute the steps.");
-        lines.push("Do NOT report the project as registered until enrichment is done.");
+        if (refreshMode) {
+            lines.push("─── REFRESH REVIEW REQUIRED ──────────────────────────────────────────────");
+            lines.push("update-project refreshed the scan. Review enriched entities and complete any");
+            lines.push("new skeletons below — do not ask the user for permission, just execute.");
+        }
+        else {
+            lines.push("─── ENRICHMENT REQUIRED ─────────────────────────────────────────────────");
+            lines.push("init-project wrote a skeleton. Complete enrichment below — do not ask the");
+            lines.push("user for permission, do not summarise and pause, just execute the steps.");
+            lines.push("Do NOT report the project as registered until enrichment is done.");
+        }
         lines.push("");
         lines.push(`PROJECT : ${projectExternalKey}`);
         lines.push(`DIR     : ${dir}`);
@@ -1759,6 +1786,19 @@ export async function initProject(args) {
             if (unresolvedItems.length > 20)
                 lines.push(`  … and ${unresolvedItems.length - 20} more`);
         }
+        if (refreshMode && preservedEntities.length > 0) {
+            lines.push("");
+            lines.push(`ENRICHED (${preservedEntities.length} — already have descriptions; not overwritten by scan):`);
+            lines.push("  Review each entry. If the scan detected a real change, run update-entity manually.");
+            for (const p of preservedEntities) {
+                lines.push(`  ${p.externalKey ?? "?"}`);
+                lines.push(`    current : name="${p.currentValues?.name ?? ""}" subtype="${p.currentValues?.entitySubtypeCode ?? ""}"`);
+                lines.push(`    scan    : name="${p.scanValues?.name ?? ""}" subtype="${p.scanValues?.entitySubtypeCode ?? ""}"`);
+                if (p.currentValues?.name !== p.scanValues?.name || p.currentValues?.entitySubtypeCode !== p.scanValues?.entitySubtypeCode) {
+                    lines.push(`    ⚠ values differ — review and update if the change is real`);
+                }
+            }
+        }
         lines.push("");
         lines.push("THEN_RUN (execute these steps — do not pause or ask for confirmation):");
         let step = 1;
@@ -1808,9 +1848,10 @@ export async function initProject(args) {
         return lines.join("\n");
     }
     const enrichmentRequired = buildEnrichmentPayload();
+    const outputStatus = enrichmentRequired.status;
     const output = {
         ok: Number(entitiesResult.summary?.failed ?? 0) === 0,
-        status: "enrichment_required",
+        status: outputStatus,
         mode: refreshMode ? "refresh" : "init",
         project: { name: displayName, externalKey: projectExternalKey, entityType: entityTypeOverride, detectedEcosystems },
         entities: entitiesResult.summary ?? {},
@@ -1848,9 +1889,10 @@ export async function initProject(args) {
     }
     console.log(`\nDone.`);
     console.log(`  Mode         : ${refreshMode ? "refresh (update-project)" : "init"}`);
-    console.log(`  Entities     : ${output.entities.succeeded ?? 0} written, ${output.entities.failed ?? 0} failed`);
+    const preservedCount = output.entities.preserved ?? 0;
+    console.log(`  Entities     : ${output.entities.succeeded ?? 0} written, ${preservedCount > 0 ? `${preservedCount} preserved (enriched), ` : ""}${output.entities.failed ?? 0} failed`);
     console.log(`  Relationships: ${output.relationships.succeeded ?? 0} written`);
-    console.log("  Status       : skeleton created; enrichment pending");
+    console.log(`  Status       : ${output.status === "review_enrichment" ? "all enriched; review preserved entities" : "skeleton created; enrichment pending"}`);
     if (output.metrics.relationshipsSkippedAsDuplicate > 0) {
         console.log(`  Deduped rels : ${output.metrics.relationshipsSkippedAsDuplicate} skipped as duplicates before upsert`);
     }

package/dist/commands/policy-audit-results.js

@@ -0,0 +1,103 @@
+import process from "process";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+function parseFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseOptionValue(args, option) {
+    const idx = args.indexOf(option);
+    if (idx === -1)
+        return null;
+    const v = args[idx + 1];
+    if (!v || v.startsWith("--"))
+        return null;
+    return v;
+}
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+export async function policyAuditResults(args) {
+    const asJson = parseFlag(args, "--json");
+    if (parseFlag(args, "--help") || parseFlag(args, "-h")) {
+        console.log(`
+Usage:
+  nexarch policy-audit-results --entity <applicationEntityRef> [--limit <1-10>] [--json]
+
+Options:
+  --entity <key>      Required application reference (e.g. application:my-service).
+                      Aliases: --entity-ref, --application-ref, --application-key
+  --limit <n>         Number of most recent runs to return (default 1, max 10)
+  --json              Print JSON response
+`);
+        return;
+    }
+    const entity = parseOptionValue(args, "--entity") ??
+        parseOptionValue(args, "--entity-ref") ??
+        parseOptionValue(args, "--application-ref") ??
+        parseOptionValue(args, "--application-key");
+    if (!entity) {
+        console.error("error: --entity <applicationEntityRef> is required (e.g. application:my-service)");
+        process.exit(1);
+    }
+    const limitRaw = parseOptionValue(args, "--limit");
+    const limit = limitRaw ? Number.parseInt(limitRaw, 10) : null;
+    if (limitRaw && (!Number.isFinite(limit) || (limit ?? 0) < 1)) {
+        console.error("error: --limit must be a positive integer");
+        process.exit(1);
+    }
+    const creds = requireCredentials();
+    const raw = await callMcpTool("nexarch_get_policy_audit_results", {
+        applicationEntityRef: entity,
+        ...(limit ? { limit } : {}),
+        companyId: creds.companyId,
+    }, { companyId: creds.companyId });
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(JSON.stringify(result) + "\n");
+        return;
+    }
+    if (result.ok === false) {
+        console.error(`Policy audit results failed${result.error ? `: ${result.error}` : ""}`);
+        if (result.hint)
+            console.error(result.hint);
+        process.exit(1);
+    }
+    const label = result.applicationName
+        ? `${result.applicationName} (${result.applicationEntityRef ?? entity})`
+        : (result.applicationEntityRef ?? entity);
+    console.log(`Policy audit results for ${label}`);
+    const runs = result.runs ?? [];
+    if (runs.length === 0) {
+        console.log("No audit runs found.");
+        if (result.hint)
+            console.log(result.hint);
+        return;
+    }
+    for (const run of runs) {
+        const summary = run.summary ?? {};
+        console.log(`\nRun ${run.runId} — ${run.status}`);
+        if (run.startedAt)
+            console.log(`  Started:   ${run.startedAt}`);
+        if (run.completedAt)
+            console.log(`  Completed: ${run.completedAt}`);
+        if (summary && (summary.passCount !== undefined || summary.failCount !== undefined)) {
+            console.log(`  Summary:   ${summary.passCount ?? 0} pass, ${summary.partialCount ?? 0} partial, ${summary.failCount ?? 0} fail` +
+                (summary.totalRules !== undefined ? ` (of ${summary.totalRules})` : ""));
+        }
+        for (const control of run.controls ?? []) {
+            console.log(`\n  - ${control.controlName} (${control.controlId})`);
+            for (const rule of control.rules ?? []) {
+                const level = rule.requirementLevel ? ` [${rule.requirementLevel}]` : "";
+                console.log(`    • [${rule.result}] ${rule.ruleName}${level} (${rule.ruleId})`);
+                if (rule.rationale)
+                    console.log(`        ${rule.rationale}`);
+                if (Array.isArray(rule.missingRequirements) && rule.missingRequirements.length > 0) {
+                    for (const m of rule.missingRequirements) {
+                        console.log(`        - missing: ${String(m)}`);
+                    }
+                }
+            }
+        }
+    }
+}

package/dist/index.js

@@ -21,6 +21,9 @@ import { commandClaim } from "./commands/command-claim.js";
 import { policyControls } from "./commands/policy-controls.js";
 import { policyAuditTemplate } from "./commands/policy-audit-template.js";
 import { policyAuditSubmit } from "./commands/policy-audit-submit.js";
+import { policyAuditResults } from "./commands/policy-audit-results.js";
+import { appliedPolicies } from "./commands/applied-policies.js";
+import { governanceSummary } from "./commands/governance-summary.js";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -46,6 +49,9 @@ const commands = {
     "policy-controls": policyControls,
     "policy-audit-template": policyAuditTemplate,
     "policy-audit-submit": policyAuditSubmit,
+    "policy-audit-results": policyAuditResults,
+    "applied-policies": appliedPolicies,
+    "governance-summary": governanceSummary,
 };
 async function main() {
     if (command === "agent") {
@@ -206,6 +212,20 @@ Usage:
                                --findings-json <json-array>
                                --findings-file <path.json>
                                --json
+  nexarch policy-audit-results
+                      Retrieve stored results of previous policy audits for an application.
+                      Options: --entity <applicationEntityRef>  (required)
+                               --limit <1-10>                   (default 1)
+                               --json
+  nexarch applied-policies
+                      List policy documents applied to this company account.
+                      Options: --pack <packCode>  filter to a specific pack
+                               --markdown        include full document markdown
+                               --json
+  nexarch governance-summary
+                      Print review queue, graph stats, and per-application policy
+                      audit rollup (latest run status, pass/partial/fail counts).
+                      Options: --json
     `);
         process.exit(command ? 1 : 0);
     }

package/dist/lib/mcp.js

@@ -1,6 +1,21 @@
 import https from "https";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
 import { requireCredentials } from "./credentials.js";
 const MCP_GATEWAY_URL = "https://mcp.nexarch.ai";
+function readCliVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = join(here, "..", "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const CLI_VERSION = readCliVersion();
 const REQUEST_TIMEOUT_MS = Number.parseInt(process.env.NEXARCH_MCP_TIMEOUT_MS ?? "90000", 10) || 90_000;
 const REQUEST_RETRIES = Math.max(0, Number.parseInt(process.env.NEXARCH_MCP_RETRIES ?? "2", 10) || 2);
 function sleep(ms) {
@@ -97,7 +112,7 @@ export async function mcpInitialize(options = {}) {
     return callMcpRpc("initialize", {
         protocolVersion: "2024-11-05",
         capabilities: {},
-        clientInfo: { name: "nexarch-cli", version: "0.5.12" },
+        clientInfo: { name: "nexarch-cli", version: CLI_VERSION },
     }, options);
 }
 export async function mcpListTools(options = {}) {

package/package.json

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