nexarch 0.6.6 → 0.7.1

package/dist/commands/command-done.js

@@ -1,3 +1,4 @@
+import { existsSync, readFileSync } from "fs";
 import process from "process";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
@@ -19,7 +20,16 @@ function parseToolText(result) {
 export async function commandDone(args) {
     const asJson = parseFlag(args, "--json");
     const id = parseOptionValue(args, "--id");
-    const summary = parseOptionValue(args, "--summary");
+    const summaryArg = parseOptionValue(args, "--summary");
+    const summaryFile = parseOptionValue(args, "--summary-file");
+    let summary = summaryArg;
+    if (summaryFile) {
+        if (!existsSync(summaryFile)) {
+            console.error(`error: --summary-file not found: ${summaryFile}`);
+            process.exit(1);
+        }
+        summary = readFileSync(summaryFile, "utf8");
+    }
     if (!id) {
         console.error("error: --id <commandId> is required");
         process.exit(1);

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

@@ -83,18 +83,23 @@ function parseFindings(args) {
         }
         return parsed.map((item) => {
             const value = item;
+            const policyControlId = String(value.policyControlId ?? value.controlId ?? "").trim();
+            const policyRuleId = String(value.policyRuleId ?? value.ruleId ?? "").trim();
             const result = String(value.result ?? "").toLowerCase();
-            if (!value.policyControlId || !value.policyRuleId || !result) {
-                throw new Error("Each finding must include policyControlId, policyRuleId, result");
+            if (!policyControlId || !policyRuleId || !result) {
+                throw new Error("Each finding must include policyControlId, policyRuleId, result. Tip: run 'nexarch policy-controls --entity <application:key> --json' and use the rule IDs from controls[].rules[].id");
             }
             if (result !== "pass" && result !== "partial" && result !== "fail") {
                 throw new Error(`Invalid finding result '${String(value.result)}'. Use pass|partial|fail.`);
             }
+            const rationale = value.rationale
+                ? String(value.rationale)
+                : [value.summary, value.evidence].filter(Boolean).map(String).join("\n\n");
             return {
-                policyControlId: String(value.policyControlId),
-                policyRuleId: String(value.policyRuleId),
+                policyControlId,
+                policyRuleId,
                 result,
-                ...(value.rationale ? { rationale: String(value.rationale) } : {}),
+                ...(rationale ? { rationale } : {}),
                 ...(Array.isArray(value.missingRequirements) ? { missingRequirements: value.missingRequirements.map(String) } : {}),
             };
         });
@@ -107,6 +112,27 @@ function parseFindings(args) {
 }
 export async function policyAuditSubmit(args) {
     const asJson = parseFlag(args, "--json");
+    if (parseFlag(args, "--help") || parseFlag(args, "-h")) {
+        console.log(`
+Usage:
+  nexarch policy-audit-submit --command-id <id> --application-key <key> [options]
+
+Options:
+  --command-id <id>          Required command id
+  --application-key <key>    Required application key (e.g. application:bad-driving)
+  --agent-key <key>          Optional agent key (defaults from identity)
+  --finding <controlId|ruleId|result|rationale|missing1;missing2>   Repeatable
+  --findings-json <json>     JSON array of findings
+  --findings-file <path>     Path to JSON array of findings
+  --json                     Print JSON response
+
+Notes:
+  - Findings are rule-level (policyRuleId is required).
+  - You can submit partial findings multiple times for the same command.
+  - Get valid rule ids with: nexarch policy-controls --entity <application:key> --json
+`);
+        return;
+    }
     const commandId = parseOptionValue(args, "--command-id") ?? parseOptionValue(args, "--id");
     const applicationEntityKey = parseOptionValue(args, "--application-key") ?? parseOptionValue(args, "--entity");
     const agentKey = parseOptionValue(args, "--agent-key") ?? loadIdentityAgentKey();

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

@@ -0,0 +1,95 @@
+import process from "process";
+import { writeFileSync } from "fs";
+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 parseMultiOptionValues(args, option) {
+    const values = [];
+    for (let i = 0; i < args.length; i += 1) {
+        if (args[i] !== option)
+            continue;
+        const v = args[i + 1];
+        if (!v || v.startsWith("--"))
+            continue;
+        values.push(v);
+    }
+    return values;
+}
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+export async function policyAuditTemplate(args) {
+    const asJson = parseFlag(args, "--json");
+    const entity = parseOptionValue(args, "--entity") ?? parseOptionValue(args, "--application-key");
+    const outputPath = parseOptionValue(args, "--out") ?? parseOptionValue(args, "--output");
+    const defaultResult = (parseOptionValue(args, "--default-result") ?? "fail").toLowerCase();
+    const selectedControlIds = new Set(parseMultiOptionValues(args, "--control-id"));
+    if (parseFlag(args, "--help") || parseFlag(args, "-h")) {
+        console.log(`
+Usage:
+  nexarch policy-audit-template --entity <application:key> [options]
+
+Options:
+  --entity <key>                 Required (e.g. application:bad-driving)
+  --control-id <uuid>            Optional repeatable filter (selected controls only)
+  --default-result <value>       pass|partial|fail (default: fail)
+  --output, --out <path.json>    Write findings array to file
+  --json                         Print JSON to stdout
+
+Output shape is ready for:
+  nexarch policy-audit-submit --findings-file <path.json>
+`);
+        return;
+    }
+    if (!entity) {
+        console.error("error: --entity <externalKey> is required (e.g. application:bad-driving)");
+        process.exit(1);
+    }
+    if (!["pass", "partial", "fail"].includes(defaultResult)) {
+        console.error("error: --default-result must be pass|partial|fail");
+        process.exit(1);
+    }
+    const creds = requireCredentials();
+    const raw = await callMcpTool("nexarch_get_entity_policy_controls", { entityExternalKey: entity, companyId: creds.companyId }, { companyId: creds.companyId });
+    const result = parseToolText(raw);
+    if (!result.found) {
+        console.error(`error: entity not found: ${entity}`);
+        process.exit(1);
+    }
+    const findings = (result.controls ?? [])
+        .filter((control) => selectedControlIds.size === 0 || selectedControlIds.has(control.id))
+        .flatMap((control) => (control.rules ?? []).map((rule) => ({
+        policyControlId: control.id,
+        policyRuleId: rule.id,
+        result: defaultResult,
+        rationale: "",
+        missingRequirements: [],
+    })));
+    if (findings.length === 0) {
+        console.error("error: no rules found for selected controls/entity");
+        process.exit(1);
+    }
+    const payload = JSON.stringify(findings, null, 2);
+    if (outputPath) {
+        writeFileSync(outputPath, `${payload}\n`, "utf8");
+        if (!asJson) {
+            console.log(`Template written: ${outputPath}`);
+            console.log(`Findings: ${findings.length}`);
+        }
+    }
+    if (asJson || !outputPath) {
+        process.stdout.write(`${payload}\n`);
+    }
+}

package/dist/index.js

@@ -17,6 +17,7 @@ import { commandDone } from "./commands/command-done.js";
 import { commandFail } from "./commands/command-fail.js";
 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";
 const [, , command, ...args] = process.argv;
 const commands = {
@@ -38,6 +39,7 @@ const commands = {
     "command-fail": commandFail,
     "command-claim": commandClaim,
     "policy-controls": policyControls,
+    "policy-audit-template": policyAuditTemplate,
     "policy-audit-submit": policyAuditSubmit,
 };
 async function main() {
@@ -132,6 +134,7 @@ Usage:
                       Mark a claimed command as completed.
                       Options: --id <commandId>    (required)
                                --summary <text>    short summary of what was done
+                               --summary-file <path.md|txt>
                                --json
   nexarch command-fail
                       Mark a claimed command as failed.
@@ -142,6 +145,13 @@ Usage:
                       Fetch policy controls/rules assigned to an entity (for policy audits).
                       Options: --entity <externalKey>  (required, e.g. application:bad-driving)
                                --json
+  nexarch policy-audit-template
+                      Generate a findings JSON template from policy controls/rules for an entity.
+                      Options: --entity <externalKey>   (required)
+                               --control-id <uuid>      (repeatable; optional filter)
+                               --default-result <pass|partial|fail> (default: fail)
+                               --output <path.json>
+                               --json
   nexarch policy-audit-submit
                       Submit structured policy findings (writes policy_audit_finding rows).
                       Options: --command-id <id>        (required)

package/package.json

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