nexarch 0.6.2 → 0.6.4

package/dist/commands/check-in.js

@@ -1,5 +1,5 @@
 import process from "process";
-import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 import { requireCredentials } from "../lib/credentials.js";
@@ -35,66 +35,6 @@ function loadIdentity() {
         return { agentKey: null, projectKeys: [] };
     }
 }
-function safeReadText(path, maxChars = 6000) {
-    if (!existsSync(path))
-        return null;
-    try {
-        return readFileSync(path, "utf8").slice(0, maxChars);
-    }
-    catch {
-        return null;
-    }
-}
-function collectEvidenceFromRepo() {
-    const cwd = process.cwd();
-    const readme = safeReadText(join(cwd, "README.md"), 8000)
-        ?? safeReadText(join(cwd, "readme.md"), 8000)
-        ?? undefined;
-    const packageJson = safeReadText(join(cwd, "package.json"), 5000);
-    const notes = [];
-    if (packageJson)
-        notes.push("package.json detected");
-    const files = [];
-    if (packageJson)
-        files.push({ path: "package.json", content: packageJson });
-    const srcDir = join(cwd, "src");
-    if (existsSync(srcDir)) {
-        try {
-            const entries = readdirSync(srcDir)
-                .filter((name) => /\.(ts|tsx|js|jsx)$/i.test(name))
-                .slice(0, 8);
-            for (const name of entries) {
-                const full = join(srcDir, name);
-                try {
-                    if (!statSync(full).isFile())
-                        continue;
-                    const content = safeReadText(full, 4000);
-                    if (content)
-                        files.push({ path: `src/${name}`, content });
-                }
-                catch {
-                    // ignore per-file failures
-                }
-            }
-            if (entries.length > 0)
-                notes.push(`included ${entries.length} source file snippet(s)`);
-        }
-        catch {
-            // ignore directory read issues
-        }
-    }
-    const summary = [
-        `cwd=${cwd}`,
-        readme ? "README included" : "README missing",
-        files.length > 0 ? `evidence files=${files.length}` : "no evidence files collected",
-    ].join("; ");
-    return {
-        summary,
-        ...(readme ? { readme } : {}),
-        ...(notes.length ? { notes: notes.join("; ") } : {}),
-        ...(files.length ? { files } : {}),
-    };
-}
 export async function checkIn(args) {
     const asJson = parseFlag(args, "--json");
     const agentKeyArg = parseOptionValue(args, "--agent-key");
@@ -102,7 +42,6 @@ export async function checkIn(args) {
     const creds = requireCredentials();
     const identity = loadIdentity();
     const agentKey = agentKeyArg ?? identity.agentKey;
-    // Use --project flag as a single override, otherwise send all stored keys
     const resolvedProjectKeys = projectKey ? [projectKey] : identity.projectKeys;
     if (!agentKey) {
         if (asJson) {
@@ -113,46 +52,46 @@ export async function checkIn(args) {
         }
         return;
     }
-    const mcpOpts = { companyId: creds.companyId };
-    const evidence = collectEvidenceFromRepo();
     const raw = await callMcpTool("nexarch_claim_command", {
         agentKey,
         ...(resolvedProjectKeys.length > 0 ? { projectKeys: resolvedProjectKeys } : {}),
-        evidence,
         companyId: creds.companyId,
-    }, mcpOpts);
+    }, { companyId: creds.companyId });
     const result = parseToolText(raw);
     if (asJson) {
         process.stdout.write(JSON.stringify(result) + "\n");
         return;
     }
-    if (!result.command) {
-        console.log("No pending commands. Nothing to do.");
+    const commands = result.commands ?? [];
+    if (commands.length === 0) {
+        console.log("No pending application-target commands found.");
         return;
     }
-    const cmd = result.command;
-    console.log(`\n╔══════════════════════════════════════════════════════════════════╗`);
-    console.log(`║  COMMAND QUEUED — action required                                ║`);
-    console.log(`╚══════════════════════════════════════════════════════════════════╝`);
-    console.log(`\nCommand ID : ${cmd.id}`);
-    console.log(`Type       : ${cmd.command_type}`);
-    console.log(`Target     : ${cmd.target_entity_key ?? "(any)"}`);
-    console.log(`Priority   : ${cmd.priority}`);
-    if (cmd.resolved_runtime_handler)
-        console.log(`Runtime    : ${cmd.resolved_runtime_handler}`);
-    if (cmd.command_type_version != null)
-        console.log(`Type ver   : ${cmd.command_type_version}`);
-    if (Object.keys(cmd.command_params).length > 0) {
-        console.log(`Params     : ${JSON.stringify(cmd.command_params)}`);
+    console.log("\nPending application-target commands (preview only; nothing claimed):");
+    for (const cmd of commands) {
+        const claimable = cmd.claimable ? "yes" : "no";
+        const reason = cmd.claimReason ?? (cmd.claimable ? "in_project_scope" : "missing_project_scope");
+        console.log(`\n- ID         : ${cmd.id}`);
+        console.log(`  Type       : ${cmd.command_type}`);
+        console.log(`  Target     : ${cmd.target_entity_key ?? "(none)"}`);
+        console.log(`  Priority   : ${cmd.priority}`);
+        console.log(`  Claimable  : ${claimable} (${reason})`);
+        if (cmd.command_type_version != null)
+            console.log(`  Type ver   : ${cmd.command_type_version}`);
+        if (cmd.resolved_runtime_handler)
+            console.log(`  Runtime    : ${cmd.resolved_runtime_handler}`);
+        if (cmd.claimable) {
+            console.log(`  Claim cmd  : npx nexarch command-claim --id "${cmd.id}"${cmd.target_entity_key ? ` --project "${cmd.target_entity_key}"` : ""}`);
+        }
     }
-    if (cmd.resolved_playbook_text?.trim()) {
-        console.log(`\nPlaybook:\n${cmd.resolved_playbook_text}`);
+    console.log("\nCurrent project scope:");
+    if (resolvedProjectKeys.length === 0) {
+        console.log("  (none) — use --project <application:key> to scope claims");
     }
-    if (cmd.instructions) {
-        console.log(`\nInstructions:\n${cmd.instructions}`);
+    else {
+        for (const key of resolvedProjectKeys)
+            console.log(`  - ${key}`);
     }
-    console.log(`\nWhen done, run:`);
-    console.log(`  npx nexarch command-done --id "${cmd.id}" --summary "..."`);
-    console.log(`\nIf it fails, run:`);
-    console.log(`  npx nexarch command-fail --id "${cmd.id}" --error "..."`);
+    console.log("\nTo validate an application target is accessible in Nexarch before claiming:");
+    console.log("  npx nexarch policy-controls --entity <application:key> --json");
 }

package/dist/commands/command-claim.js

@@ -0,0 +1,97 @@
+import process from "process";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+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);
+}
+function loadIdentity() {
+    const identityPath = join(homedir(), ".nexarch", "identity.json");
+    if (!existsSync(identityPath))
+        return { agentKey: null, projectKeys: [] };
+    try {
+        const data = JSON.parse(readFileSync(identityPath, "utf8"));
+        return {
+            agentKey: data.agentKey ?? null,
+            projectKeys: Array.isArray(data.projectKeys) ? data.projectKeys : [],
+        };
+    }
+    catch {
+        return { agentKey: null, projectKeys: [] };
+    }
+}
+export async function commandClaim(args) {
+    const asJson = parseFlag(args, "--json");
+    const id = parseOptionValue(args, "--id");
+    const agentKeyArg = parseOptionValue(args, "--agent-key");
+    const projectKey = parseOptionValue(args, "--project");
+    if (!id) {
+        console.error("error: --id <commandId> is required");
+        process.exit(1);
+    }
+    const creds = requireCredentials();
+    const identity = loadIdentity();
+    const agentKey = agentKeyArg ?? identity.agentKey;
+    const resolvedProjectKeys = projectKey ? [projectKey] : identity.projectKeys;
+    if (!agentKey) {
+        console.error("error: no agent key found. Pass --agent-key or run nexarch init-agent first.");
+        process.exit(1);
+    }
+    const raw = await callMcpTool("nexarch_claim_command_by_id", {
+        commandId: id,
+        agentKey,
+        ...(resolvedProjectKeys.length > 0 ? { projectKeys: resolvedProjectKeys } : {}),
+        companyId: creds.companyId,
+    }, { companyId: creds.companyId });
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(JSON.stringify(result) + "\n");
+        return;
+    }
+    if (!result.command) {
+        console.log(`Command ${id} was not claimed.`);
+        if (result.reason)
+            console.log(`Reason: ${result.reason}`);
+        return;
+    }
+    const cmd = result.command;
+    console.log(`\n╔══════════════════════════════════════════════════════════════════╗`);
+    console.log(`║  COMMAND CLAIMED — action required                               ║`);
+    console.log(`╚══════════════════════════════════════════════════════════════════╝`);
+    console.log(`\nCommand ID : ${cmd.id}`);
+    console.log(`Type       : ${cmd.command_type}`);
+    console.log(`Target     : ${cmd.target_entity_key ?? "(any)"}`);
+    console.log(`Priority   : ${cmd.priority}`);
+    if (cmd.resolved_runtime_handler)
+        console.log(`Runtime    : ${cmd.resolved_runtime_handler}`);
+    if (cmd.command_type_version != null)
+        console.log(`Type ver   : ${cmd.command_type_version}`);
+    if (Object.keys(cmd.command_params).length > 0) {
+        console.log(`Params     : ${JSON.stringify(cmd.command_params)}`);
+    }
+    if (cmd.resolved_playbook_text?.trim()) {
+        console.log(`\nPlaybook:\n${cmd.resolved_playbook_text}`);
+    }
+    if (cmd.instructions) {
+        console.log(`\nInstructions:\n${cmd.instructions}`);
+    }
+    console.log(`\nWhen done, run:`);
+    console.log(`  npx nexarch command-done --id "${cmd.id}" --summary "..."`);
+    console.log(`\nIf it fails, run:`);
+    console.log(`  npx nexarch command-fail --id "${cmd.id}" --error "..."`);
+}

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

@@ -0,0 +1,138 @@
+import process from "process";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+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);
+}
+function loadIdentityAgentKey() {
+    const identityPath = join(homedir(), ".nexarch", "identity.json");
+    if (!existsSync(identityPath))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(identityPath, "utf8"));
+        return data.agentKey ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function parseFindingToken(token) {
+    const [policyControlId, policyRuleId, resultRaw, rationaleRaw, missingRaw] = token.split("|");
+    const result = (resultRaw ?? "").trim().toLowerCase();
+    if (!policyControlId?.trim() || !policyRuleId?.trim() || !result) {
+        throw new Error("Each --finding must be: <policyControlId>|<policyRuleId>|<pass|partial|fail>|<rationale>|<missing1;missing2>");
+    }
+    if (result !== "pass" && result !== "partial" && result !== "fail") {
+        throw new Error(`Invalid finding result '${resultRaw}'. Use pass|partial|fail.`);
+    }
+    return {
+        policyControlId: policyControlId.trim(),
+        policyRuleId: policyRuleId.trim(),
+        result,
+        ...(rationaleRaw?.trim() ? { rationale: rationaleRaw.trim() } : {}),
+        ...(missingRaw?.trim() ? { missingRequirements: missingRaw.split(";").map((m) => m.trim()).filter(Boolean) } : {}),
+    };
+}
+function parseFindings(args) {
+    const findingsJson = parseOptionValue(args, "--findings-json");
+    if (findingsJson) {
+        let parsed;
+        try {
+            parsed = JSON.parse(findingsJson);
+        }
+        catch {
+            throw new Error("--findings-json must be valid JSON array");
+        }
+        if (!Array.isArray(parsed) || parsed.length === 0) {
+            throw new Error("--findings-json must be a non-empty JSON array");
+        }
+        return parsed.map((item) => {
+            const value = item;
+            const result = String(value.result ?? "").toLowerCase();
+            if (!value.policyControlId || !value.policyRuleId || !result) {
+                throw new Error("Each finding must include policyControlId, policyRuleId, result");
+            }
+            if (result !== "pass" && result !== "partial" && result !== "fail") {
+                throw new Error(`Invalid finding result '${String(value.result)}'. Use pass|partial|fail.`);
+            }
+            return {
+                policyControlId: String(value.policyControlId),
+                policyRuleId: String(value.policyRuleId),
+                result,
+                ...(value.rationale ? { rationale: String(value.rationale) } : {}),
+                ...(Array.isArray(value.missingRequirements) ? { missingRequirements: value.missingRequirements.map(String) } : {}),
+            };
+        });
+    }
+    const tokens = parseMultiOptionValues(args, "--finding");
+    if (tokens.length === 0) {
+        throw new Error("Provide findings via --finding (repeatable) or --findings-json '<json-array>'");
+    }
+    return tokens.map(parseFindingToken);
+}
+export async function policyAuditSubmit(args) {
+    const asJson = parseFlag(args, "--json");
+    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();
+    if (!commandId) {
+        console.error("error: --command-id <uuid> is required");
+        process.exit(1);
+    }
+    if (!applicationEntityKey) {
+        console.error("error: --application-key <externalKey> is required (e.g. application:bad-driving)");
+        process.exit(1);
+    }
+    const findings = parseFindings(args);
+    const creds = requireCredentials();
+    const raw = await callMcpTool("nexarch_submit_policy_audit", {
+        commandId,
+        applicationEntityKey,
+        ...(agentKey ? { agentKey } : {}),
+        findings,
+        companyId: creds.companyId,
+    }, { companyId: creds.companyId });
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(JSON.stringify(result) + "\n");
+        return;
+    }
+    if (!result.ok) {
+        console.error(`Policy audit submit failed${result.error ? `: ${result.error}` : ""}`);
+        process.exit(1);
+    }
+    console.log(`Policy audit submitted for ${applicationEntityKey}.`);
+    if (result.runId)
+        console.log(`Run ID: ${result.runId}`);
+    if (result.summary) {
+        console.log(`Summary: ${result.summary.passCount ?? 0} pass, ${result.summary.partialCount ?? 0} partial, ${result.summary.failCount ?? 0} fail`);
+    }
+}

package/dist/commands/policy-controls.js

@@ -0,0 +1,52 @@
+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 policyControls(args) {
+    const asJson = parseFlag(args, "--json");
+    const entity = parseOptionValue(args, "--entity") ?? parseOptionValue(args, "--application-key");
+    if (!entity) {
+        console.error("error: --entity <externalKey> is required (e.g. application:bad-driving)");
+        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 (asJson) {
+        process.stdout.write(JSON.stringify(result) + "\n");
+        return;
+    }
+    if (!result.found) {
+        console.log(`Entity not found: ${entity}`);
+        return;
+    }
+    console.log(`Policy controls for ${result.entityExternalKey ?? entity}`);
+    console.log(`Controls: ${result.controlCount ?? 0}`);
+    for (const control of result.controls ?? []) {
+        const rules = control.rules ?? [];
+        console.log(`\n- ${control.name} (${control.id})`);
+        if (rules.length === 0) {
+            console.log("  (no rules)");
+            continue;
+        }
+        for (const rule of rules) {
+            const level = rule.requirementLevel ? ` [${rule.requirementLevel}]` : "";
+            console.log(`  • ${rule.name} (${rule.id})${level}`);
+        }
+    }
+}

package/dist/index.js

@@ -15,6 +15,9 @@ import { resolveNames } from "./commands/resolve-names.js";
 import { checkIn } from "./commands/check-in.js";
 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 { policyAuditSubmit } from "./commands/policy-audit-submit.js";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -33,6 +36,9 @@ const commands = {
     "check-in": checkIn,
     "command-done": commandDone,
     "command-fail": commandFail,
+    "command-claim": commandClaim,
+    "policy-controls": policyControls,
+    "policy-audit-submit": policyAuditSubmit,
 };
 async function main() {
     if (command === "agent") {
@@ -113,12 +119,18 @@ Usage:
                       results before calling add-relationship.
                       Options: --names <csv>  (required, e.g. "vercel,neon")
                                --json
-  nexarch check-in    Poll the command queue and claim the next pending command
-                      for this agent. Reads agent key from ~/.nexarch/identity.json
+  nexarch check-in    Preview pending application-target commands for this agent scope
+                      without claiming. Reads agent key from ~/.nexarch/identity.json
                       (written by init-agent) or via --agent-key.
                       Options: --agent-key <key>   override stored agent key
                                --project <key>     application entity key
                                --json
+  nexarch command-claim
+                      Explicitly claim a pending command by ID.
+                      Options: --id <commandId>    (required)
+                               --agent-key <key>   override stored agent key
+                               --project <key>     application entity key
+                               --json
   nexarch command-done
                       Mark a claimed command as completed.
                       Options: --id <commandId>    (required)
@@ -129,6 +141,18 @@ Usage:
                       Options: --id <commandId>    (required)
                                --error <message>   (required)
                                --json
+  nexarch policy-controls
+                      Fetch policy controls/rules assigned to an entity (for policy audits).
+                      Options: --entity <externalKey>  (required, e.g. application:bad-driving)
+                               --json
+  nexarch policy-audit-submit
+                      Submit structured policy findings (writes policy_audit_finding rows).
+                      Options: --command-id <id>        (required)
+                               --application-key <key>  (required)
+                               --agent-key <key>        (optional; defaults from identity)
+                               --finding <controlId|ruleId|result|rationale|missing1;missing2> (repeatable)
+                               --findings-json <json-array>
+                               --json
     `);
         process.exit(command ? 1 : 0);
     }

package/package.json

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