nexarch 0.13.0 → 0.13.2

package/dist/lib/iac-projection.js

@@ -0,0 +1,231 @@
+/**
+ * Terraform state projector (ADR: infrastructure-as-code ingestion, v1).
+ *
+ * Turns `terraform show -json` into the small, safe projection that ingestion
+ * is allowed to send. This is the security-critical component of the feature:
+ * state files carry generated passwords, storage keys, connection strings and
+ * certificate material in clear text, verified against a real estate.
+ *
+ * Two independent gates, both deny-by-default:
+ *
+ *   1. The catalogue names, per resource type, the attributes that may be read.
+ *      Anything not named is dropped. The catalogue is reference data served by
+ *      the platform, not a list baked into this CLI, so support for a new Azure
+ *      service is a data change rather than a release.
+ *
+ *   2. Terraform's own `sensitive_values` map is consulted for every attribute
+ *      that survives gate 1, and anything flagged there is dropped even when the
+ *      catalogue names it. A mistake in the curated list is therefore not on its
+ *      own sufficient to leak a secret.
+ *
+ * Values are additionally restricted to scalars and shallow string arrays.
+ * Nested blocks are never emitted wholesale: a container app's `secret` block or
+ * an env var's `value` can hold credentials, so structure is only ever read by a
+ * named extractor that has been reviewed for that purpose.
+ */
+/**
+ * Parses a state document from raw bytes.
+ *
+ * PowerShell's `>` redirection writes UTF-16 with a BOM, which is what a Windows
+ * user gets from `terraform show -json > state.json` and what a naive reader
+ * chokes on. Both endiannesses and plain UTF-8 are accepted.
+ */
+export function parseIacStateBuffer(buffer) {
+    let text;
+    if (buffer[0] === 0xff && buffer[1] === 0xfe)
+        text = buffer.toString("utf16le");
+    else if (buffer[0] === 0xfe && buffer[1] === 0xff)
+        text = Buffer.from(buffer).swap16().toString("utf16le");
+    else
+        text = buffer.toString("utf8");
+    return JSON.parse(text.replace(/^/, ""));
+}
+/**
+ * Infers the environment from resource tags.
+ *
+ * Estates that tag at all tag consistently — the first real one carried
+ * `environment` on every resource — so the dominant value of a conventional tag
+ * key beats asking a human to pass a flag correctly in a pipeline. Returns null
+ * when there is no clear winner, leaving the caller to fall back to the
+ * Terraform workspace or an explicit flag.
+ */
+export function inferEnvironmentFromTags(resources) {
+    const TAG_KEYS = ["environment", "env", "Environment", "Env"];
+    const counts = new Map();
+    for (const resource of resources) {
+        for (const key of TAG_KEYS) {
+            const value = resource.tags[key];
+            if (typeof value !== "string" || !value.trim())
+                continue;
+            const normalised = value.trim().toLowerCase();
+            counts.set(normalised, (counts.get(normalised) ?? 0) + 1);
+            break;
+        }
+    }
+    if (counts.size === 0)
+        return null;
+    const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+    const [environment, hits] = ranked[0];
+    const total = ranked.reduce((sum, [, n]) => sum + n, 0);
+    return { environment, confidence: hits / total };
+}
+/** Maps a free-text environment name onto an ontology environment subtype. */
+export function environmentSubtypeFor(environment) {
+    const name = environment.trim().toLowerCase();
+    if (/^(prod|production|live)$/.test(name))
+        return "env_production";
+    if (/^(stag|staging|preprod|pre-prod|uat)$/.test(name))
+        return "env_staging";
+    if (/^(test|qa|sit)$/.test(name))
+        return "env_test";
+    if (/^(dr|failover)$/.test(name))
+        return "env_dr";
+    return "env_development";
+}
+/** Longest value we will carry for any single attribute. */
+const MAX_VALUE_LENGTH = 400;
+const MAX_ARRAY_ITEMS = 12;
+function flattenResources(module, out = []) {
+    if (!module)
+        return out;
+    for (const resource of module.resources ?? [])
+        out.push(resource);
+    for (const child of module.child_modules ?? [])
+        flattenResources(child, out);
+    return out;
+}
+/**
+ * True when Terraform flagged this attribute as sensitive. The map mirrors the
+ * shape of `values`, so a `true` anywhere beneath the attribute — an env var's
+ * value inside a container template, for instance — disqualifies the whole
+ * attribute rather than just the leaf.
+ */
+function isSensitive(sensitiveValues, attribute) {
+    if (!sensitiveValues || typeof sensitiveValues !== "object" || Array.isArray(sensitiveValues))
+        return false;
+    const flag = sensitiveValues[attribute];
+    if (flag === undefined)
+        return false;
+    if (flag === true)
+        return true;
+    return JSON.stringify(flag).includes("true");
+}
+/** Scalars and shallow string arrays only; anything structural is refused. */
+function safeValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "boolean" || typeof value === "number")
+        return value;
+    if (typeof value === "string")
+        return value.length > MAX_VALUE_LENGTH ? value.slice(0, MAX_VALUE_LENGTH) : value;
+    if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+        return value.slice(0, MAX_ARRAY_ITEMS).map((item) => item.slice(0, MAX_VALUE_LENGTH));
+    }
+    return null;
+}
+/**
+ * Tags carry the binding convention, so they are read — but a tag whose value
+ * Terraform flagged, or which does not look like a label, is left behind.
+ */
+function projectTags(values, sensitiveValues) {
+    if (isSensitive(sensitiveValues, "tags"))
+        return {};
+    const raw = values.tags;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const tags = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value !== "string")
+            continue;
+        if (value.length > 200)
+            continue;
+        tags[key] = value;
+    }
+    return tags;
+}
+/**
+ * User-assigned identity references. Reviewed extractor: identity ids are
+ * resource paths, never credentials, and they are how a workload is tied to the
+ * role assignments that define what it may reach.
+ */
+function projectIdentityIds(values) {
+    const identity = values.identity;
+    if (!Array.isArray(identity))
+        return [];
+    const ids = [];
+    for (const block of identity) {
+        if (!block || typeof block !== "object")
+            continue;
+        const identityIds = block.identity_ids;
+        if (!Array.isArray(identityIds))
+            continue;
+        for (const id of identityIds)
+            if (typeof id === "string")
+                ids.push(id);
+    }
+    return ids.slice(0, MAX_ARRAY_ITEMS);
+}
+export function projectIacState(params) {
+    const { document, catalogue, environment } = params;
+    const byType = new Map(catalogue.map((entry) => [entry.resourceType, entry]));
+    const resources = flattenResources(document.values?.root_module);
+    const projected = [];
+    const unknown = new Map();
+    let attributesDroppedNotAllowlisted = 0;
+    let attributesDroppedSensitive = 0;
+    for (const resource of resources) {
+        const resourceType = typeof resource.type === "string" ? resource.type : "";
+        if (!resourceType)
+            continue;
+        const entry = byType.get(resourceType);
+        if (!entry) {
+            unknown.set(resourceType, (unknown.get(resourceType) ?? 0) + 1);
+            continue;
+        }
+        const values = (resource.values && typeof resource.values === "object" ? resource.values : {});
+        const sensitiveValues = resource.sensitive_values;
+        const attributes = {};
+        for (const [key, value] of Object.entries(values)) {
+            if (!entry.attributes.includes(key)) {
+                attributesDroppedNotAllowlisted += 1;
+                continue;
+            }
+            if (isSensitive(sensitiveValues, key)) {
+                attributesDroppedSensitive += 1;
+                continue;
+            }
+            const safe = safeValue(value);
+            if (safe === null) {
+                attributesDroppedNotAllowlisted += 1;
+                continue;
+            }
+            attributes[key] = safe;
+        }
+        projected.push({
+            address: typeof resource.address === "string" ? resource.address : `${resourceType}.${resource.name ?? "unknown"}`,
+            resourceType,
+            entityTypeCode: entry.entityTypeCode,
+            entitySubtypeCode: entry.entitySubtypeCode ?? null,
+            role: entry.role,
+            mode: typeof resource.mode === "string" ? resource.mode : "managed",
+            name: typeof values[entry.nameAttribute ?? "name"] === "string" ? values[entry.nameAttribute ?? "name"] : null,
+            attributes,
+            tags: projectTags(values, sensitiveValues),
+            identityIds: projectIdentityIds(values),
+        });
+    }
+    return {
+        environment,
+        iacToolVersion: typeof document.terraform_version === "string" ? document.terraform_version : null,
+        resources: projected,
+        unknownTypes: [...unknown.entries()]
+            .map(([resourceType, count]) => ({ resourceType, count }))
+            .sort((a, b) => b.count - a.count),
+        stats: {
+            resourcesSeen: resources.length,
+            resourcesProjected: projected.length,
+            attributesDroppedNotAllowlisted,
+            attributesDroppedSensitive,
+        },
+    };
+}

package/dist/lib/iac-tool.js

@@ -0,0 +1,138 @@
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import { detectAnsibleProject } from "./ansible-detect.js";
+const HASHICORP_SHAPED = {
+    estateArgs: ["show", "-json"],
+    unitNoun: "root module",
+    hasWorkspaces: true,
+    provisions: true,
+};
+export const IAC_TOOLS = [
+    { id: "terraform", displayName: "Terraform", executable: "terraform", applyExecutable: "terraform", aliases: ["terraform"], ...HASHICORP_SHAPED },
+    { id: "opentofu", displayName: "OpenTofu", executable: "tofu", applyExecutable: "tofu", aliases: ["opentofu", "tofu"], ...HASHICORP_SHAPED },
+    {
+        id: "ansible",
+        displayName: "Ansible",
+        executable: "ansible-inventory",
+        // --export resolves group and host variables the way a playbook run would
+        // see them, rather than printing the raw file.
+        estateArgs: ["--list", "--export"],
+        applyExecutable: "ansible-playbook",
+        unitNoun: "inventory",
+        hasWorkspaces: false,
+        provisions: false,
+        aliases: ["ansible"],
+    },
+];
+export function getIacTool(value) {
+    if (!value)
+        return null;
+    const normalised = value.trim().toLowerCase();
+    return IAC_TOOLS.find((tool) => tool.aliases.includes(normalised)) ?? null;
+}
+const IGNORED = new Set(["node_modules", ".git", ".terraform", "dist", "build", ".next"]);
+/**
+ * Files that say how the estate is *run*. Deliberately not `.tf` or `.hcl`:
+ * OpenTofu reads the same HCL and kept the `terraform { ... }` block name, so
+ * every OpenTofu repository on earth contains the word "terraform" in its
+ * configuration. Treating that as evidence of the Terraform CLI made a real
+ * OpenTofu estate -- `terraform {}` block, `tofu apply` in CI -- come back
+ * ambiguous, which then threw, so the one case this feature exists for could
+ * not be ingested without passing --tool by hand.
+ */
+const AUTOMATION_FILE = /\.(ya?ml|json|sh|bash|ps1|tfvars)$|^(Makefile|Taskfile\.ya?ml|justfile)$/i;
+/** `.tofu` is OpenTofu-only: it is the extension Terraform will not read. */
+const TOFU_SOURCE_FILE = /\.tofu$/i;
+/**
+ * A CLI invocation, not a mention. `terraform apply`, `tofu init`, `tofu -chdir`.
+ * The subcommand list is what automation actually runs; "terraform" alone in a
+ * comment, a module source or an HCL block is not evidence of either binary.
+ */
+// Built with String.raw, not a plain template literal: in a plain one the
+// backslash escapes are consumed by the string before the regex ever sees
+// them, which is how the first version of these came to match nothing at all
+// and report every repository as "defaulted".
+const SUBCOMMANDS = "init|plan|apply|show|destroy|validate|state|workspace|output|fmt|refresh|import|providers|-chdir";
+const TERRAFORM_COMMAND = new RegExp(String.raw `(?:^|[^\w./-])terraform\s+(?:${SUBCOMMANDS})\b`, "im");
+const TOFU_COMMAND = new RegExp(String.raw `(?:^|[^\w./-])tofu\s+(?:${SUBCOMMANDS})\b`, "im");
+function collectEvidence(dir, depth = 0, found = { terraform: false, opentofu: false }) {
+    if (depth > 4 || (found.terraform && found.opentofu))
+        return found;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return found;
+    }
+    for (const entry of entries) {
+        if (IGNORED.has(entry))
+            continue;
+        const full = join(dir, entry);
+        try {
+            if (statSync(full).isDirectory()) {
+                collectEvidence(full, depth + 1, found);
+            }
+            else if (TOFU_SOURCE_FILE.test(entry)) {
+                found.opentofu = true;
+            }
+            else if (AUTOMATION_FILE.test(entry)) {
+                // One file at a time: the first version pushed every file's full
+                // contents into an array before matching, which on a large estate is
+                // the whole repository held in memory to answer a yes/no.
+                const text = readFileSync(full, "utf8");
+                if (!found.opentofu && TOFU_COMMAND.test(text))
+                    found.opentofu = true;
+                if (!found.terraform && TERRAFORM_COMMAND.test(text))
+                    found.terraform = true;
+            }
+        }
+        catch { /* unreadable configuration is not evidence */ }
+        if (found.terraform && found.opentofu)
+            return found;
+    }
+    return found;
+}
+/**
+ * Detects the IaC tool from how the repository is actually driven — the
+ * commands its automation runs, `.tofu` files, which only OpenTofu reads, and
+ * Ansible's own repository shape.
+ *
+ * Terraform and OpenTofu together is genuinely ambiguous: they are the same
+ * tool twice, so one estate cannot be read by guessing which. **Terraform and
+ * Ansible together is not** — it is the most ordinary infrastructure repository
+ * there is, one tool provisioning and the other configuring, and they describe
+ * different things. So the provisioning tool wins and the signals say the
+ * inventory is there to be ingested too, rather than refusing a layout that is
+ * completely normal.
+ */
+export function detectIacTool(dir, requestedTool) {
+    if (requestedTool) {
+        const tool = getIacTool(requestedTool);
+        if (!tool)
+            throw new Error(`Unknown IaC tool "${requestedTool}". Use terraform, opentofu or ansible.`);
+        return { status: "detected", tool, signals: [`--tool ${tool.id}`] };
+    }
+    const { terraform, opentofu } = collectEvidence(dir);
+    const ansible = detectAnsibleProject(dir);
+    const alsoAnsible = ansible.isAnsible ? ["Ansible is here too — ingest its inventory with --tool ansible"] : [];
+    if (terraform && opentofu) {
+        return { status: "ambiguous", tool: null, signals: ["both `terraform` and `tofu` commands are run by this repository", ...alsoAnsible] };
+    }
+    if (opentofu)
+        return { status: "detected", tool: IAC_TOOLS[1], signals: ["`tofu` commands or .tofu files", ...alsoAnsible] };
+    if (terraform)
+        return { status: "detected", tool: IAC_TOOLS[0], signals: ["`terraform` commands", ...alsoAnsible] };
+    if (ansible.isAnsible) {
+        const tool = IAC_TOOLS.find((candidate) => candidate.id === "ansible");
+        return { status: "detected", tool, signals: ansible.signals };
+    }
+    return { status: "defaulted", tool: IAC_TOOLS[0], signals: ["no IaC CLI named in automation; defaulting to Terraform"] };
+}
+export function iacToolOrThrow(dir, requestedTool) {
+    const detection = detectIacTool(dir, requestedTool);
+    if (detection.status === "ambiguous") {
+        throw new Error("Both Terraform and OpenTofu were detected. Select the state CLI explicitly with --tool terraform or --tool opentofu.");
+    }
+    return detection.tool;
+}

package/dist/lib/skills.js

@@ -317,22 +317,44 @@ say so rather than skipping it or inventing a target.
 `;
 const FEEDBACK_SKILL_BODY = `---
 name: nexarch-feedback
-description: Report a Nexarch tool problem or misleading graph answer. Use after a blocked tool error that required a workaround, a graph answer that was wrong or unhelpful enough to mislead, or an ambiguous repository agent instruction that contradicts tool behaviour. Requires the Nexarch MCP tools (nexarch_*).
+description: Offer to report a Nexarch problem the moment you notice it, rather than waiting to be asked. Use when a Nexarch tool error blocked work and needed a workaround, when a graph answer was wrong or misleading, or when a repository agent instruction contradicts what the tools actually do. Ask the human before sending. Requires the Nexarch MCP tools (nexarch_*).
 ---
 
 # Nexarch Feedback
 
-Call \`nexarch_submit_feedback\` when a Nexarch tool error blocked the task and
-you had to work around it; when a graph answer was wrong or unhelpful enough to
-mislead; or when an instruction in the repository's agent files was ambiguous
-or contradicted what the tools actually do.
+These are worth reporting to Nexarch: a Nexarch tool error that blocked the task
+and made you work around it; a graph answer that was wrong or unhelpful enough
+to mislead; an instruction in the repository's agent files that was ambiguous or
+contradicted what the tools actually do.
 
-Make each report useful: write one concrete sentence, name the tool or surface
-involved, and say what you expected instead. Include reproduction detail when
-it clarifies the problem.
+## Offer to report it when it happens
 
-Do **not** report a refused write when governance was working as designed, or
-your own malformed call. Fix the call or follow the governance response instead.
+When you notice one, raise it with the human in the next thing you say to them
+— not in a closing summary or a list of open items at the end of the task. Say
+in a sentence or two what looked wrong, and ask whether they would like you to
+report it to Nexarch.
+
+- If they say yes, call \`nexarch_submit_feedback\` and tell them the feedback id
+  you got back.
+- If they say no, drop it and do not offer again for the same problem.
+- Do not send a report without their yes, unless they have already told you in
+  this session to report problems without asking.
+
+If you find yourself writing "this may be a Nexarch bug", that is the moment to
+offer.
+
+## Make each report useful
+
+Write one concrete sentence, name the tool or surface involved, and say what
+you expected instead. Include reproduction detail when it clarifies the
+problem. Never include secrets, credentials or customer data.
+
+## Do not offer to report
+
+A refused write when governance was working as designed, or your own malformed
+call. Fix the call or follow the governance response instead. Work that is
+waiting on a human decision, such as a proposed application awaiting
+activation, is the process working, not a fault.
 `;
 export const SKILLS = [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",
@@ -26,7 +26,7 @@
     "prepublishOnly": "tsc",
     "dev": "tsx src/index.ts",
     "typecheck": "tsc --noEmit",
-    "test": "tsx scripts/test-mcp-proxy-response.ts && tsx scripts/test-trust-reattest.ts && tsx scripts/test-similar-applications.ts"
+    "test": "tsx scripts/test-mcp-proxy-response.ts && tsx scripts/test-trust-reattest.ts && tsx scripts/test-similar-applications.ts && tsx scripts/test-iac-tool.ts && tsx scripts/test-ansible.ts && tsx scripts/test-reference-sightings.ts"
   },
   "devDependencies": {
     "@types/node": "^22",