nexarch 0.6.7 → 0.8.1

package/dist/commands/init-project.js

@@ -207,6 +207,63 @@ function parseEnvKeys(content) {
         .filter((key) => /^[A-Z][A-Z0-9_]{2,}$/.test(key))
         .filter((key) => !ENV_KEY_NOISE.test(key));
 }
+function inferEnvServiceNamesFromKey(key) {
+    const upper = key.toUpperCase();
+    const names = new Set();
+    if (upper.includes("ADSENSE")) {
+        names.add("google-adsense");
+        names.add("adsense");
+    }
+    if (upper.includes("VERCEL"))
+        names.add("vercel");
+    if (upper.includes("NEON"))
+        names.add("neon");
+    if (upper.includes("TURBO")) {
+        names.add("turbo");
+        names.add("turborepo");
+    }
+    return Array.from(names);
+}
+function inferEnvServiceNamesFromValue(valueRaw) {
+    const value = valueRaw.replace(/^['"]|['"]$/g, "").toLowerCase();
+    const names = new Set();
+    if (!value)
+        return [];
+    if (value.includes("neon.tech") || value.includes("@neondatabase/"))
+        names.add("neon");
+    if (value.includes("vercel.app") || value.includes("vercel.com"))
+        names.add("vercel");
+    if (value.includes("googleads.g.doubleclick.net") || value.includes("adsense")) {
+        names.add("google-adsense");
+        names.add("adsense");
+    }
+    return Array.from(names);
+}
+function parseEnvSignals(content) {
+    const names = new Set();
+    const keys = parseEnvKeys(content);
+    for (const key of keys) {
+        names.add(key);
+        for (const n of inferEnvServiceNamesFromKey(key))
+            names.add(n);
+    }
+    for (const rawLine of content.split("\n")) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#") || !line.includes("="))
+            continue;
+        const normalized = line.replace(/^export\s+/, "");
+        const eqIdx = normalized.indexOf("=");
+        if (eqIdx < 1)
+            continue;
+        const key = normalized.slice(0, eqIdx).trim();
+        const value = normalized.slice(eqIdx + 1).trim();
+        if (!/^[A-Z][A-Z0-9_]{2,}$/.test(key))
+            continue;
+        for (const n of inferEnvServiceNamesFromValue(value))
+            names.add(n);
+    }
+    return Array.from(names);
+}
 function gitOriginUrl(dir) {
     const configPath = join(dir, ".git", "config");
     if (!existsSync(configPath))
@@ -237,38 +294,80 @@ function detectFromGitConfig(dir) {
     return [];
 }
 function detectFromFilesystem(dir) {
-    const detected = [];
-    // CI/CD
-    if (existsSync(join(dir, ".github", "workflows")))
-        detected.push("github-actions");
-    if (existsSync(join(dir, ".gitlab-ci.yml")))
-        detected.push("gitlab");
-    if (existsSync(join(dir, "Jenkinsfile")))
-        detected.push("jenkins");
-    if (existsSync(join(dir, ".circleci", "config.yml")))
-        detected.push("circleci");
-    // Deployment / hosting
-    if (existsSync(join(dir, "vercel.json")) || existsSync(join(dir, ".vercel")))
-        detected.push("vercel");
-    if (existsSync(join(dir, "netlify.toml")))
-        detected.push("netlify");
-    if (existsSync(join(dir, "fly.toml")))
-        detected.push("fly");
-    if (existsSync(join(dir, "railway.json")) || existsSync(join(dir, "railway.toml")))
-        detected.push("railway");
-    if (existsSync(join(dir, "render.yaml")))
-        detected.push("render");
-    // Containers
-    if (existsSync(join(dir, "Dockerfile")))
-        detected.push("docker");
-    if (existsSync(join(dir, "docker-compose.yml")) || existsSync(join(dir, "docker-compose.yaml")))
-        detected.push("docker");
-    // Infrastructure
-    if (existsSync(join(dir, "terraform")) || existsSync(join(dir, "main.tf")))
-        detected.push("terraform");
-    if (existsSync(join(dir, "pulumi.yaml")))
-        detected.push("pulumi");
-    return detected;
+    const detected = new Set();
+    const markIfExists = (relPath, name) => {
+        if (existsSync(join(dir, relPath)))
+            detected.add(name);
+    };
+    // Root-level checks first (fast path)
+    markIfExists(join(".github", "workflows"), "github-actions");
+    markIfExists(".gitlab-ci.yml", "gitlab");
+    markIfExists("Jenkinsfile", "jenkins");
+    markIfExists(join(".circleci", "config.yml"), "circleci");
+    markIfExists("vercel.json", "vercel");
+    markIfExists(".vercel", "vercel");
+    markIfExists("netlify.toml", "netlify");
+    markIfExists("fly.toml", "fly");
+    markIfExists("railway.json", "railway");
+    markIfExists("railway.toml", "railway");
+    markIfExists("render.yaml", "render");
+    markIfExists("Dockerfile", "docker");
+    markIfExists("docker-compose.yml", "docker");
+    markIfExists("docker-compose.yaml", "docker");
+    markIfExists("terraform", "terraform");
+    markIfExists("main.tf", "terraform");
+    markIfExists("pulumi.yaml", "pulumi");
+    // Monorepo-aware bounded walk for deployment files in sub-app folders.
+    const MAX_DEPTH = 3;
+    const walk = (current, depth) => {
+        if (depth > MAX_DEPTH)
+            return;
+        let entries = [];
+        try {
+            entries = readdirSync(current);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith("."))
+                continue;
+            if (SKIP_DIRS.has(entry))
+                continue;
+            const full = join(current, entry);
+            let isDir = false;
+            try {
+                isDir = statSync(full).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (!isDir)
+                continue;
+            if (existsSync(join(full, "vercel.json")) ||
+                existsSync(join(full, ".vercel")))
+                detected.add("vercel");
+            if (existsSync(join(full, "netlify.toml")))
+                detected.add("netlify");
+            if (existsSync(join(full, "fly.toml")))
+                detected.add("fly");
+            if (existsSync(join(full, "railway.json")) || existsSync(join(full, "railway.toml")))
+                detected.add("railway");
+            if (existsSync(join(full, "render.yaml")))
+                detected.add("render");
+            if (existsSync(join(full, "Dockerfile")))
+                detected.add("docker");
+            if (existsSync(join(full, "docker-compose.yml")) || existsSync(join(full, "docker-compose.yaml")))
+                detected.add("docker");
+            if (existsSync(join(full, "main.tf")))
+                detected.add("terraform");
+            if (existsSync(join(full, "pulumi.yaml")))
+                detected.add("pulumi");
+            walk(full, depth + 1);
+        }
+    };
+    walk(dir, 1);
+    return Array.from(detected);
 }
 const SKIP_DIRS = new Set([
     // JavaScript / Node
@@ -286,14 +385,30 @@ const SKIP_DIRS = new Set([
     // Generic
     "build", ".git", ".cache", "tmp",
 ]);
+const ARCHITECTURAL_DEV_DEP_ALLOWLIST = new Set([
+    "tailwindcss",
+    "turbo",
+    "turborepo",
+    "@vercel/analytics",
+    "@vercel/speed-insights",
+    "@vercel/postgres",
+    "@vercel/blob",
+    "@neondatabase/serverless",
+]);
 function collectPackageDeps(pkgPath) {
     try {
         const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-        // devDependencies are build/test/type tooling — no architectural value
         const merged = {
-            ...pkg.dependencies,
-            ...pkg.peerDependencies,
+            ...(pkg.dependencies ?? {}),
+            ...(pkg.peerDependencies ?? {}),
         };
+        // Include a small set of architecturally significant dev dependencies
+        // (hosting/build/runtime-defining tools) while still filtering test-only noise.
+        for (const [name, versionRaw] of Object.entries(pkg.devDependencies ?? {})) {
+            if (ARCHITECTURAL_DEV_DEP_ALLOWLIST.has(name)) {
+                merged[name] = versionRaw;
+            }
+        }
         return Object.entries(merged).map(([name, versionRaw]) => ({
             name,
             versionRaw: typeof versionRaw === "string" ? versionRaw : null,
@@ -696,12 +811,12 @@ function scanProject(dir) {
         catch { }
     }
     // ── .env files ─────────────────────────────────────────────────────────────
-    for (const envFile of [".env", ".env.example", ".env.local", ".env.runtime"]) {
+    for (const envFile of [".env", ".env.example", ".env.local", ".env.runtime", ".env.production", ".env.development"]) {
         const envPath = join(dir, envFile);
         if (existsSync(envPath)) {
             try {
-                for (const key of parseEnvKeys(readFileSync(envPath, "utf8")))
-                    names.add(key);
+                for (const signal of parseEnvSignals(readFileSync(envPath, "utf8")))
+                    names.add(signal);
             }
             catch { }
         }

package/dist/commands/list-entities.js

@@ -0,0 +1,46 @@
+import process from "process";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+function option(args, key) {
+    const i = args.indexOf(key);
+    if (i === -1)
+        return null;
+    const v = args[i + 1];
+    if (!v || v.startsWith("--"))
+        return null;
+    return v;
+}
+export async function listEntities(args) {
+    const asJson = hasFlag(args, "--json");
+    const entityTypeCode = option(args, "--type") ?? undefined;
+    const status = option(args, "--status") ?? undefined;
+    const query = option(args, "--query") ?? undefined;
+    const limitRaw = option(args, "--limit");
+    const limit = limitRaw ? Number(limitRaw) : undefined;
+    if (limitRaw && (!Number.isInteger(limit) || (limit ?? 0) < 1 || (limit ?? 0) > 500)) {
+        console.error("error: --limit must be an integer between 1 and 500");
+        process.exit(1);
+    }
+    const creds = requireCredentials();
+    const raw = await callMcpTool("nexarch_list_entities", {
+        companyId: creds.companyId,
+        entityTypeCode,
+        status,
+        query,
+        limit,
+    }, { companyId: creds.companyId });
+    const result = JSON.parse(raw.content?.[0]?.text ?? "{}");
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    console.log(`Found ${result.count ?? 0} entities`);
+    for (const e of result.entities ?? []) {
+        const subtype = e.entitySubtypeCode ? `/${e.entitySubtypeCode}` : "";
+        const key = e.externalKey ? ` (${e.externalKey})` : "";
+        console.log(`- ${e.name}${key} [${e.entityTypeCode}${subtype}] status=${e.status}`);
+    }
+}

package/dist/commands/list-relationships.js

@@ -0,0 +1,49 @@
+import process from "process";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+function option(args, key) {
+    const i = args.indexOf(key);
+    if (i === -1)
+        return null;
+    const v = args[i + 1];
+    if (!v || v.startsWith("--"))
+        return null;
+    return v;
+}
+export async function listRelationships(args) {
+    const asJson = hasFlag(args, "--json");
+    const relationshipTypeCode = option(args, "--type") ?? undefined;
+    const status = option(args, "--status") ?? undefined;
+    const fromEntityExternalKey = option(args, "--from") ?? undefined;
+    const toEntityExternalKey = option(args, "--to") ?? undefined;
+    const limitRaw = option(args, "--limit");
+    const limit = limitRaw ? Number(limitRaw) : undefined;
+    if (limitRaw && (!Number.isInteger(limit) || (limit ?? 0) < 1 || (limit ?? 0) > 500)) {
+        console.error("error: --limit must be an integer between 1 and 500");
+        process.exit(1);
+    }
+    const creds = requireCredentials();
+    const raw = await callMcpTool("nexarch_list_relationships", {
+        companyId: creds.companyId,
+        relationshipTypeCode,
+        status,
+        fromEntityExternalKey,
+        toEntityExternalKey,
+        limit,
+    }, { companyId: creds.companyId });
+    const result = JSON.parse(raw.content?.[0]?.text ?? "{}");
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    console.log(`Found ${result.count ?? 0} relationships`);
+    for (const r of result.relationships ?? []) {
+        const subtype = r.relationshipSubtypeCode ? `/${r.relationshipSubtypeCode}` : "";
+        const from = r.fromEntityExternalKey ?? r.fromEntityName ?? "?";
+        const to = r.toEntityExternalKey ?? r.toEntityName ?? "?";
+        console.log(`- ${from} -[${r.relationshipTypeCode}${subtype}|${r.status}]-> ${to}`);
+    }
+}

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/commands/status.js

@@ -31,7 +31,17 @@ export async function status(_args) {
     if (registryInfo) {
         console.log(`\n  Integration registry: v${registryInfo.version} (published ${new Date(registryInfo.publishedAt).toLocaleString()})`);
     }
-    console.log(`\n  Architecture facts:  ${governance.canonicalFactCount}`);
+    const architectureFacts = governance.architectureFactCount ?? governance.canonicalFactCount;
+    console.log(`\n  Architecture facts:  ${architectureFacts}`);
+    if (typeof governance.graphEntityCount === "number" && typeof governance.graphRelationshipCount === "number") {
+        console.log(`  Graph breakdown:     ${governance.graphEntityCount} entities, ${governance.graphRelationshipCount} relationships`);
+    }
+    if (typeof governance.canonicalCoverageOverallPct === "number") {
+        console.log(`  Canonical coverage:  ${governance.canonicalCoverageOverallPct}%`);
+    }
+    if (typeof governance.canonicalRegistryCount === "number") {
+        console.log(`  Canonical registry:  ${governance.canonicalRegistryCount}`);
+    }
     console.log(`  Pending review:      ${governance.reviewQueue.pending_entities} entities, ${governance.reviewQueue.pending_relationships} relationships`);
     if (governance.latestSnapshot) {
         const snapshotDate = new Date(governance.latestSnapshot.created_at).toLocaleDateString();

package/dist/index.js

@@ -12,11 +12,14 @@ import { updateEntity } from "./commands/update-entity.js";
 import { addRelationship } from "./commands/add-relationship.js";
 import { registerAlias } from "./commands/register-alias.js";
 import { resolveNames } from "./commands/resolve-names.js";
+import { listEntities } from "./commands/list-entities.js";
+import { listRelationships } from "./commands/list-relationships.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 { policyAuditTemplate } from "./commands/policy-audit-template.js";
 import { policyAuditSubmit } from "./commands/policy-audit-submit.js";
 const [, , command, ...args] = process.argv;
 const commands = {
@@ -33,11 +36,14 @@ const commands = {
     "add-relationship": addRelationship,
     "register-alias": registerAlias,
     "resolve-names": resolveNames,
+    "list-entities": listEntities,
+    "list-relationships": listRelationships,
     "check-in": checkIn,
     "command-done": commandDone,
     "command-fail": commandFail,
     "command-claim": commandClaim,
     "policy-controls": policyControls,
+    "policy-audit-template": policyAuditTemplate,
     "policy-audit-submit": policyAuditSubmit,
 };
 async function main() {
@@ -119,6 +125,21 @@ Usage:
                       results before calling add-relationship.
                       Options: --names <csv>  (required, e.g. "vercel,neon")
                                --json
+  nexarch list-entities
+                      List entities from the workspace graph.
+                      Options: --type <entityTypeCode>
+                               --status <status>
+                               --query <text>
+                               --limit <1-500>
+                               --json
+  nexarch list-relationships
+                      List relationships from the workspace graph.
+                      Options: --type <relationshipTypeCode>
+                               --status <status>
+                               --from <fromExternalKey>
+                               --to <toExternalKey>
+                               --limit <1-500>
+                               --json
   nexarch check-in    Preview pending application-target commands (no auto-claim).
                       Scope is resolved server-side from active company context.
                       Options: --agent-key <key>   override stored agent key
@@ -143,6 +164,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.7",
+  "version": "0.8.1",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",