nexarch 0.13.0 → 0.13.2

package/dist/commands/ingest-infra.js

@@ -1,10 +1,13 @@
-import { readFileSync, existsSync, readdirSync } from "fs";
+import { readFileSync, existsSync, readdirSync, statSync } from "fs";
 import { execFileSync } from "child_process";
-import { resolve } from "path";
+import { join, resolve } from "path";
 import { callMcpTool } from "../lib/mcp.js";
-import { parseTerraformStateBuffer, projectTerraformState, inferEnvironmentFromTags, environmentSubtypeFor, } from "../lib/terraform-projection.js";
+import { parseIacStateBuffer, projectIacState, inferEnvironmentFromTags, environmentSubtypeFor, } from "../lib/iac-projection.js";
 import { loadIacCatalogue, describeCatalogue } from "../lib/iac-catalogue.js";
-import { discoverRootModules, environmentFromPath } from "../lib/terraform-detect.js";
+import { discoverRootModules, environmentFromPath } from "../lib/iac-detect.js";
+import { iacToolOrThrow } from "../lib/iac-tool.js";
+import { detectAnsibleProject, environmentFromInventoryPath } from "../lib/ansible-detect.js";
+import { parseAnsibleInventory, projectAnsibleInventory } from "../lib/ansible-projection.js";
 const ENTITY_BATCH = 50;
 /**
  * Terraform provider prefix -> the platform it provisions.
@@ -45,6 +48,16 @@ function detectPlatform(resourceTypes) {
     const [topPrefix] = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
     return PROVIDER_PLATFORMS.find((p) => p.prefix === topPrefix) ?? null;
 }
+/**
+ * "provisioned" or "configured", by tool.
+ *
+ * The same distinction `mode: "declared"` carries in the data, said in the
+ * prose a human reads on the entity. Ansible did not provision a machine it
+ * only installed packages on, and the description should not claim it did.
+ */
+function pastVerbFor(tool) {
+    return tool.provisions ? "provisioned" : "configured";
+}
 function readResult(raw) {
     return JSON.parse(raw.content?.[0]?.text ?? "{}");
 }
@@ -62,12 +75,16 @@ function parseArgs(args) {
         return index >= 0 && args[index + 1] ? args[index + 1] : null;
     };
     return {
-        statePath: get("--state"),
+        // `--inventory` is the same thing said in Ansible's vocabulary. A reader
+        // holding an inventory file should not have to work out that we call it
+        // state.
+        statePath: get("--state") ?? get("--inventory"),
         environmentOverride: get("--environment"),
         dir: get("--dir") ?? process.cwd(),
         projectRef: get("--project-ref"),
         dryRun: args.includes("--dry-run"),
         asJson: args.includes("--json"),
+        tool: get("--tool"),
     };
 }
 /**
@@ -80,13 +97,14 @@ function parseArgs(args) {
  * an agent, and an agent can act on a list of commands but not on a request to
  * choose.
  */
-function resolveRootModule(dir) {
-    const hasLocalTerraform = existsSync(dir) && readdirSync(dir).some((entry) => entry.endsWith(".tf"));
-    if (hasLocalTerraform)
+function resolveRootModule(dir, tool) {
+    // Both tools read .tf; OpenTofu also reads .tofu, which Terraform will not.
+    const hasLocalConfig = existsSync(dir) && readdirSync(dir).some((entry) => entry.endsWith(".tf") || entry.endsWith(".tofu"));
+    if (hasLocalConfig)
         return { dir, note: null };
     const roots = discoverRootModules(dir);
     if (roots.length === 1) {
-        return { dir: roots[0].dir, note: `no Terraform in the working directory; using the only root module found, ${roots[0].relative}` };
+        return { dir: roots[0].dir, note: `no infrastructure code in the working directory; using the only root module found, ${roots[0].relative}` };
     }
     if (roots.length > 1) {
         // Annotations go on their own line: the caller is usually an agent, and a
@@ -94,37 +112,37 @@ function resolveRootModule(dir) {
         const lines = roots.flatMap((root) => {
             const notes = [
                 root.environmentHint ? `${root.environmentHint} environment` : "shared stack",
-                root.initialised ? "initialised" : "run `terraform init` here first",
+                root.initialised ? "initialised" : `run \`${tool.executable} init\` here first`,
             ].join(", ");
             return [`    # ${root.relative} — ${notes}`, `    nexarch ingest-infra --dir ${root.relative}`];
         });
         throw new Error([
-            `This repository has ${roots.length} root modules, each with its own state.`,
-            `  Every root module is a separate estate, so ingest them one at a time:`,
+            `This repository has ${roots.length} ${tool.unitNoun}s, each with its own estate.`,
+            `  Each is a separate estate, so ingest them one at a time:`,
             ...lines,
         ].join("\n"));
     }
     throw new Error([
-        `No Terraform root module found at or below ${dir}.`,
+        `No ${tool.unitNoun} found at or below ${dir}.`,
         `  Run this inside the repository that provisions the estate, or pass --dir <path> or --state <file>.`,
     ].join("\n"));
 }
-/** Reads state from a file, or asks Terraform for it when running inside the repo. */
-function loadState(statePath, dir) {
+/** Reads state from a file, or asks the IaC tool for it when running inside the repo. */
+function loadState(statePath, dir, tool) {
     if (statePath) {
         const full = resolve(statePath);
         if (!existsSync(full))
             throw new Error(`State file not found: ${full}`);
-        return { document: parseTerraformStateBuffer(readFileSync(full)), source: full };
+        return { document: parseIacStateBuffer(readFileSync(full)), source: full };
     }
     try {
-        const stdout = execFileSync("terraform", ["show", "-json"], {
+        const stdout = execFileSync(tool.executable, [...tool.estateArgs], {
             cwd: dir,
             maxBuffer: 256 * 1024 * 1024,
             encoding: "buffer",
             stdio: ["ignore", "pipe", "pipe"],
         });
-        return { document: parseTerraformStateBuffer(stdout), source: "terraform show -json" };
+        return { document: parseIacStateBuffer(stdout), source: `${tool.executable} ${tool.estateArgs.join(" ")}` };
     }
     catch (error) {
         // `error.message` is only ever "Command failed: terraform show -json",
@@ -146,12 +164,12 @@ function loadState(statePath, dir) {
             .slice(0, 8)
             .map((line) => `  ${line.trim()}`)
             .join("\n");
-        throw new Error(`Could not read Terraform state in ${dir}.\n` +
-            `  Run inside the infrastructure repo with terraform available, or pass --state <file>.\n` +
-            `\n  terraform said:\n${detail}`);
+        throw new Error(`Could not read ${tool.displayName} state in ${dir}.\n` +
+            `  Run inside the infrastructure repo with ${tool.executable} available, or pass --state <file>.\n` +
+            `\n  ${tool.displayName} said:\n${detail}`);
     }
 }
-function resolveEnvironment(projection, override, dir, rootModuleDir) {
+function resolveEnvironment(projection, override, dir, rootModuleDir, tool) {
     if (override)
         return { environment: override.trim().toLowerCase(), how: "--environment flag" };
     // A root module living in environments/prod states which estate is being read
@@ -164,10 +182,15 @@ function resolveEnvironment(projection, override, dir, rootModuleDir) {
     if (inferred && inferred.confidence >= 0.6) {
         return { environment: inferred.environment, how: `inferred from resource tags (${Math.round(inferred.confidence * 100)}% agreement)` };
     }
+    // Guarded, not attempted-and-caught: Ansible has no workspace concept, and
+    // shelling out to a binary that will never answer the question is a second's
+    // wait and a misleading "not available" in the logs.
     try {
-        const workspace = execFileSync("terraform", ["workspace", "show"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        if (!tool.hasWorkspaces)
+            throw new Error("no workspaces");
+        const workspace = execFileSync(tool.executable, ["workspace", "show"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
         if (workspace && workspace !== "default")
-            return { environment: workspace.toLowerCase(), how: "terraform workspace" };
+            return { environment: workspace.toLowerCase(), how: `${tool.id} workspace` };
     }
     catch {
         // Terraform not available; fall through to the error below.
@@ -185,7 +208,7 @@ function resolveEnvironment(projection, override, dir, rootModuleDir) {
     else if (projection.stats.resourcesProjected > 0)
         detail.push("none carried an environment or env tag");
     throw new Error(`Could not determine the environment — ${detail.join("; ")}.\n` +
-        `  Fix by tagging resources with \`environment\`, selecting a named Terraform workspace, or passing --environment <name>.`);
+        `  Fix by tagging resources with \`environment\`, selecting a named ${tool.displayName} workspace, or passing --environment <name>.`);
 }
 /** Last non-empty segment of a cloud resource path (ARM id, ARN, self-link) — that resource's name. */
 function lastPathSegment(armId) {
@@ -194,7 +217,7 @@ function lastPathSegment(armId) {
 }
 /** Builds the entity and relationship payloads for the existing upsert contract. */
 export function buildIngestPayload(params) {
-    const { projection, environment, platformRef, platformName, catalogue } = params;
+    const { projection, environment, platformRef, platformName, catalogue, tool } = params;
     const environmentRef = `environment:${slug(environment)}`;
     const entities = [
         {
@@ -202,15 +225,15 @@ export function buildIngestPayload(params) {
             entityTypeCode: "platform",
             name: platformName,
             description: `Cloud platform hosting the ${environment} environment.`,
-            attributes: { source: "terraform_ingest" },
+            attributes: { source: "iac_ingest", iac_tool: tool.id },
         },
         {
             entityRef: environmentRef,
             entityTypeCode: "environment",
             entitySubtypeCode: environmentSubtypeFor(environment),
             name: environment,
-            description: `The ${environment} environment, as provisioned by Terraform.`,
-            attributes: { source: "terraform_ingest", terraform_version: projection.terraformVersion },
+            description: `The ${environment} environment, as ${pastVerbFor(tool)} by ${tool.displayName}.`,
+            attributes: { source: "iac_ingest", iac_tool: tool.id, iac_tool_version: projection.iacToolVersion },
         },
     ];
     const relationships = [
@@ -242,12 +265,13 @@ export function buildIngestPayload(params) {
             entityTypeCode: resource.entityTypeCode,
             ...(resource.entitySubtypeCode ? { entitySubtypeCode: resource.entitySubtypeCode } : {}),
             name: resource.name ?? resource.address,
-            description: `${resource.role.replace(/_/g, " ")} provisioned by Terraform (${resource.resourceType}) in ${environment}.`,
+            description: `${resource.role.replace(/_/g, " ")} ${pastVerbFor(tool)} by ${tool.displayName} (${resource.resourceType}) in ${environment}.`,
             attributes: {
-                source: "terraform_ingest",
-                terraform_address: resource.address,
-                terraform_type: resource.resourceType,
-                terraform_mode: resource.mode,
+                source: "iac_ingest",
+                iac_tool: tool.id,
+                iac_resource_address: resource.address,
+                iac_resource_type: resource.resourceType,
+                iac_resource_mode: resource.mode,
                 infrastructure_role: resource.role,
                 environment,
                 ...resource.attributes,
@@ -371,7 +395,7 @@ export function buildIngestPayload(params) {
             entityTypeCode: canonicalTypeCode,
             name: canonicalTechnologyName(canonicalRef),
             description: "Cloud service referenced by infrastructure ingestion.",
-            attributes: { source: "terraform_ingest", canonical: true },
+            attributes: { source: "iac_ingest", iac_tool: tool.id, canonical: true },
         });
         // A managed service belongs to the cloud that offers it. Only from a
         // platform_component: part_of does not accept a technology_component
@@ -398,36 +422,136 @@ function chunk(items, size) {
         out.push(items.slice(i, i + size));
     return out;
 }
-export async function ingestInfra(args) {
-    const { statePath, environmentOverride, dir, projectRef, dryRun, asJson } = parseArgs(args);
-    // Only resolve a root module when Terraform must be run; an explicit --state
+/** Exact MCP inputs used for infrastructure writes; kept inspectable for contract tests. */
+export function buildIngestUpsertPayloads(params) {
+    const { entities, relationships, agentContext, policyContext } = params;
+    return {
+        entityPayloads: chunk(entities, ENTITY_BATCH).map((entities) => ({ entities, agentContext, policyContext })),
+        relationshipPayloads: chunk(relationships, ENTITY_BATCH).map((relationships) => ({ relationships, agentContext, policyContext })),
+    };
+}
+/**
+ * Reads the estate the way this tool exposes it.
+ *
+ * The two shapes are genuinely different, which is the whole finding of stage 4:
+ * Terraform dumps state that is then matched against the resource catalogue,
+ * while Ansible enumerates an inventory that has no catalogue at all -- a host
+ * is a host. Branching here rather than inside the projector keeps each path
+ * readable, and keeps the catalogue fetch off the Ansible path where it would
+ * be a wasted round trip.
+ */
+async function readEstate(params) {
+    const { tool, dir, statePath, asJson } = params;
+    if (tool.id === "ansible") {
+        const { inventory, source, inventoryPath } = loadAnsibleInventory(statePath, dir, tool);
+        return {
+            projection: projectAnsibleInventory({ inventory, environment: "unknown" }),
+            source,
+            workingDir: dir,
+            environmentHint: inventoryPath ? environmentFromInventoryPath(inventoryPath) : null,
+            catalogue: [],
+        };
+    }
+    // Only resolve a root module when the tool must be run; an explicit --state
     // file is authoritative and needs no repository at all.
     let workingDir = dir;
     if (!statePath) {
-        const resolved = resolveRootModule(dir);
+        const resolved = resolveRootModule(dir, tool);
         workingDir = resolved.dir;
         if (resolved.note && !asJson)
             console.log(`  ${resolved.note}`);
     }
-    const { document, source } = loadState(statePath, workingDir);
+    const { document, source } = loadState(statePath, workingDir, tool);
     // Fetched once and used for both projection and payload: two different
     // catalogues within one ingest would produce entities whose attributes and
     // whose type mapping disagreed about what a resource is.
     const catalogueResult = await loadIacCatalogue();
     if (!asJson)
         console.log(`  ${describeCatalogue(catalogueResult)}`);
-    const catalogue = catalogueResult.entries;
-    const projection = projectTerraformState({ document, catalogue, environment: "unknown" });
-    // Terraform emits a valid but empty document when it cannot see state, which
+    return {
+        projection: projectIacState({ document, catalogue: catalogueResult.entries, environment: "unknown" }),
+        source,
+        workingDir,
+        environmentHint: null,
+        catalogue: catalogueResult.entries,
+    };
+}
+/**
+ * Reads an inventory, either from a path or by asking Ansible to enumerate one.
+ *
+ * A path is parsed directly rather than passed to `ansible-inventory -i`: it
+ * makes the common case work without Ansible installed at all, and the parser
+ * handles the same JSON, YAML and INI that Ansible itself accepts.
+ */
+function loadAnsibleInventory(inventoryPath, dir, tool) {
+    if (inventoryPath) {
+        const full = resolve(inventoryPath);
+        if (!existsSync(full))
+            throw new Error(`Inventory not found: ${full}`);
+        return { inventory: parseAnsibleInventory(readFileSync(full, "utf8")), source: full, inventoryPath };
+    }
+    // No path given: let the repository's own layout choose, so the environment
+    // can be read off it. One inventory is unambiguous; several are not, and
+    // guessing which environment to ingest is exactly the guess not to make.
+    const detection = detectAnsibleProject(dir);
+    if (detection.inventoryFiles.length === 1) {
+        const relative = detection.inventoryFiles[0];
+        const full = join(dir, relative);
+        if (existsSync(full) && statSync(full).isFile()) {
+            return { inventory: parseAnsibleInventory(readFileSync(full, "utf8")), source: full, inventoryPath: relative };
+        }
+    }
+    if (detection.inventoryFiles.length > 1) {
+        const lines = detection.inventoryFiles.map((file) => `    nexarch ingest-infra --inventory ${file}`);
+        throw new Error([
+            `This repository has ${detection.inventoryFiles.length} inventories, each describing its own estate.`,
+            `  Ingest them one at a time:`,
+            ...lines,
+        ].join("\n"));
+    }
+    try {
+        const stdout = execFileSync(tool.executable, [...tool.estateArgs], {
+            cwd: dir,
+            maxBuffer: 256 * 1024 * 1024,
+            encoding: "buffer",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return {
+            inventory: parseAnsibleInventory(stdout.toString("utf8")),
+            source: `${tool.executable} ${tool.estateArgs.join(" ")}`,
+            inventoryPath: null,
+        };
+    }
+    catch (error) {
+        const detail = String(error.stderr ?? "").trim() || error.message;
+        throw new Error(`Could not read an Ansible inventory in ${dir}.\n` +
+            `  Pass --inventory <file>, or run this where \`${tool.executable}\` can see one.\n` +
+            `\n  ${tool.executable} said:\n    ${detail.split("\n").slice(0, 6).join("\n    ")}`);
+    }
+}
+export async function ingestInfra(args) {
+    const { statePath, environmentOverride, dir, projectRef, dryRun, asJson, tool: requestedTool } = parseArgs(args);
+    const tool = iacToolOrThrow(dir, requestedTool);
+    const { projection, source, workingDir, environmentHint, catalogue } = await readEstate({ tool, dir, statePath, asJson });
+    // Both tools emit a valid but empty document when they cannot see state,
     // is a different problem from anything downstream and deserves its own
     // message rather than surfacing later as a confusing tagging complaint.
+    // An empty estate needs the diagnosis that fits the tool. Telling someone
+    // holding an inventory to run `terraform init` is worse than saying nothing.
+    if (projection.stats.resourcesSeen === 0 && !tool.provisions) {
+        throw new Error(`No hosts found in the ${tool.unitNoun} (read from ${source}).\n` +
+            `  An inventory with no hosts describes no estate. Establish which, in this order:\n` +
+            `    1. run \`${tool.executable} ${tool.estateArgs.join(" ")}\` here — empty output confirms it\n` +
+            `    2. check the inventory is the one you meant, with --inventory <file>\n` +
+            `    3. a dynamic inventory plugin may need credentials this shell does not have`);
+    }
     if (projection.stats.resourcesSeen === 0) {
-        throw new Error(`No resources found in Terraform state (read from ${source}).\n` +
-            `  Terraform ran but reported an empty state. Establish which, in this order:\n` +
-            `    1. run \`terraform state list\` in ${workingDir} — empty output confirms there is no state here\n` +
-            `    2. if there is no .terraform directory, run \`terraform init\`, then retry\n` +
-            `    3. run \`terraform workspace list\` and select the one that was applied\n` +
-            `    4. if this repository has several root modules, ingest each separately with --dir\n` +
+        throw new Error(`No resources found in ${tool.displayName} state (read from ${source}).\n` +
+            `  ${tool.displayName} ran but reported an empty state. Establish which, in this order:\n` +
+            `    1. run \`${tool.executable} state list\` in ${workingDir} — empty output confirms there is no state here\n` +
+            `    2. if there is no .terraform directory, run \`${tool.executable} init\`, then retry\n` +
+            `    3. run \`${tool.executable} workspace list\` and select the one that was applied\n` +
+            `    4. if this repository has several ${tool.unitNoun}s, ingest each separately with --dir\n` +
             `  The estate may also simply not have been applied yet.`);
     }
     // Nothing recognised is a coverage problem, and has to be said before the
@@ -436,7 +560,9 @@ export async function ingestInfra(args) {
     // environment — 0 of those carried any tags", which sends the reader off to
     // tag resources that would still not be ingested afterwards. The environment
     // is the next question only once there is something to attach it to.
-    if (projection.stats.resourcesProjected === 0) {
+    // Ansible has no resource catalogue: every host is projected by definition,
+    // so a catalogue-coverage complaint here would be nonsense.
+    if (tool.provisions && projection.stats.resourcesProjected === 0) {
         const seen = projection.unknownTypes
             .slice(0, 12)
             .map((entry) => `    ${String(entry.count).padStart(3)}  ${entry.resourceType}`)
@@ -446,7 +572,9 @@ export async function ingestInfra(args) {
             `\n  Resource types found here:\n${seen}\n` +
             `\n  These need adding to the platform catalogue before this root can be ingested.`);
     }
-    const { environment, how } = resolveEnvironment(projection, environmentOverride, workingDir, statePath ? null : workingDir);
+    const { environment, how } = environmentHint && !environmentOverride
+        ? { environment: environmentHint, how: `${tool.unitNoun} path` }
+        : resolveEnvironment(projection, environmentOverride, workingDir, statePath ? null : workingDir, tool);
     projection.environment = environment;
     // Detected from what is actually in state, not assumed: an estate is read
     // once and the provider it is on follows from that, the same way the
@@ -458,8 +586,12 @@ export async function ingestInfra(args) {
         ...projection.resources.map((r) => r.resourceType),
         ...projection.unknownTypes.map((u) => u.resourceType),
     ]);
-    let platformRef = detectedPlatform?.fallbackRef ?? "platform:unknown";
-    let platformName = detectedPlatform?.fallbackName ?? "Unrecognised cloud platform";
+    // A tool that does not provision genuinely does not know what the hosts run
+    // on -- an inventory says `web-01`, not whether it is EC2 or a machine under
+    // someone's desk. "Unrecognised cloud platform" would be a worse answer than
+    // naming what we do know, which is that these are hosts we configure.
+    let platformRef = detectedPlatform?.fallbackRef ?? (tool.provisions ? "platform:unknown" : "platform:managed_hosts");
+    let platformName = detectedPlatform?.fallbackName ?? (tool.provisions ? "Unrecognised cloud platform" : "Managed hosts");
     if (!dryRun && detectedPlatform) {
         try {
             const raw = await callMcpTool("nexarch_resolve_reference", { names: detectedPlatform.resolveNames });
@@ -494,13 +626,13 @@ export async function ingestInfra(args) {
             // Coverage reporting must never fail an ingest: the estate is the point.
         }
     }
-    const { entities, relationships } = buildIngestPayload({ projection, environment, platformRef, platformName, catalogue });
+    const { entities, relationships } = buildIngestPayload({ projection, environment, platformRef, platformName, catalogue, tool });
     const report = {
         ok: true,
         source,
         environment,
         environmentSource: how,
-        terraformVersion: projection.terraformVersion,
+        iacToolVersion: projection.iacToolVersion,
         resourcesSeen: projection.stats.resourcesSeen,
         resourcesProjected: projection.stats.resourcesProjected,
         attributesDropped: {
@@ -536,13 +668,14 @@ export async function ingestInfra(args) {
         provider: "n/a",
     };
     const policyContext = { policyBundleHash, alignmentSummary: { score: 1, violations: [], waivers: [] } };
+    const upsertPayloads = buildIngestUpsertPayloads({ entities, relationships, agentContext, policyContext });
     let failed = 0;
-    for (const batch of chunk(entities, ENTITY_BATCH)) {
-        const raw = await callMcpTool("nexarch_upsert_entities", { entities: batch, agentContext, policyContext });
+    for (const payload of upsertPayloads.entityPayloads) {
+        const raw = await callMcpTool("nexarch_upsert_entities", payload);
         failed += (readResult(raw).summary?.failed ?? 0);
     }
-    for (const batch of chunk(relationships, ENTITY_BATCH)) {
-        const raw = await callMcpTool("nexarch_upsert_relationships", { relationships: batch, agentContext, policyContext });
+    for (const payload of upsertPayloads.relationshipPayloads) {
+        const raw = await callMcpTool("nexarch_upsert_relationships", payload);
         failed += (readResult(raw).summary?.failed ?? 0);
     }
     report.written = { entities: entities.length, relationships: relationships.length, failed };
@@ -554,9 +687,9 @@ export async function ingestInfra(args) {
 function printHuman(report, entityCount, relationshipCount) {
     const dropped = report.attributesDropped;
     console.log(`\nInfrastructure ingest — ${report.environment} (${report.environmentSource})`);
-    console.log(`  Source: ${report.source}${report.terraformVersion ? ` · terraform ${report.terraformVersion}` : ""}`);
+    console.log(`  Source: ${report.source}${report.iacToolVersion ? ` · ${report.iacTool} ${report.iacToolVersion}` : ""}`);
     console.log(`  Projected ${report.resourcesProjected} of ${report.resourcesSeen} resources to the contract surface.`);
-    console.log(`  Dropped ${dropped.notAllowlisted} attributes not on the allowlist, ${dropped.flaggedSensitive} flagged sensitive by Terraform.`);
+    console.log(`  Dropped ${dropped.notAllowlisted} attributes not on the allowlist, ${dropped.flaggedSensitive} flagged sensitive by the tool.`);
     const unknown = report.unknownTypes;
     if (unknown.length > 0) {
         console.log(`\n  Not yet in the catalogue (reported so coverage can grow):`);

package/dist/commands/init-agent.js

@@ -607,11 +607,17 @@ function injectInitProjectReportingContract(path) {
         "completed task — it is a description of a task you have not finished.",
         "",
         "For an infrastructure repository, `nextSteps` holds one `ingest-infra` command per",
-        "Terraform root module. Until they run, the graph knows the repository exists but",
-        "nothing it provisions.",
+        "unit of estate — a Terraform or OpenTofu root module, each with its own state.",
+        "Until they run, the graph knows the repository exists but nothing it provisions.",
+        "",
+        "**One exception: a possible duplicate.** If init-project returns `status: \"review_required\"`",
+        "or prints `STOP — POSSIBLE DUPLICATE`, an application already in the workspace looks like",
+        "one it would register, and it wrote nothing. Tell the human which one you think matches and",
+        "why, wait for their answer, then re-run init-project with the command for their choice",
+        "(`decision.commands` in the output). Only then continue with enrichment.",
         "",
         "Stop early only when a step genuinely cannot run — missing cloud credentials, a root",
-        "module that needs `terraform init`, or an environment you should not touch without",
+        "module that has not been initialised, or an environment you should not touch without",
         "asking. When that happens, say which step stopped you and why, then ask. Do not",
         "silently return a skeleton.",
         "",

package/dist/commands/init-project-infra.js

@@ -1,9 +1,10 @@
 import { basename } from "path";
 import { createInterface } from "readline";
 import { callMcpTool } from "../lib/mcp.js";
-import { detectInfrastructureProject, ciSnippetFor } from "../lib/terraform-detect.js";
-import { environmentSubtypeFor } from "../lib/terraform-projection.js";
+import { detectInfrastructureProject, ciSnippetFor } from "../lib/iac-detect.js";
+import { environmentSubtypeFor } from "../lib/iac-projection.js";
 import { ingestInfra } from "./ingest-infra.js";
+import { iacToolOrThrow } from "../lib/iac-tool.js";
 function readResult(raw) {
     return JSON.parse(raw.content?.[0]?.text ?? "{}");
 }
@@ -35,22 +36,22 @@ async function confirm(question) {
  * and an agent reporting "skeleton_only" and stopping, which is exactly what
  * happened when the handoff lived only in prose at the end of a real run.
  */
-function nextStepsFor(projectRef, detection) {
+function nextStepsFor(projectRef, detection, toolId) {
     return detection.rootModules.map((root) => ({
         rootModule: root.relative,
         environment: root.environmentHint,
         initialised: root.initialised,
-        command: `nexarch ingest-infra --dir ${root.relative} --project-ref ${projectRef}`,
+        command: `nexarch ingest-infra --dir ${root.relative} --project-ref ${projectRef} --tool ${toolId}`,
     }));
 }
 /** Prints the per-root ingest commands, the part that actually populates the graph. */
-function printNextSteps(steps, registered) {
+function printNextSteps(steps, registered, executable) {
     if (steps.length === 0)
         return;
     console.log(`\n${registered ? "Registered" : "Would register"} the repository — the estate itself is not in the graph yet.`);
     console.log(`Each of the ${steps.length} root modules holds its own state and needs its own ingest:\n`);
     for (const step of steps) {
-        const notes = [step.environment ? `${step.environment} environment` : "shared stack", step.initialised ? "initialised" : "run `terraform init` here first"].join(", ");
+        const notes = [step.environment ? `${step.environment} environment` : "shared stack", step.initialised ? "initialised" : `run \`${executable} init\` here first`].join(", ");
         console.log(`    # ${step.rootModule} — ${notes}`);
         console.log(`    ${step.command}`);
     }
@@ -64,9 +65,9 @@ function printNextSteps(steps, registered) {
  * made — not even the policy read, since a dry run should be inert.
  */
 function reportDryRun(params) {
-    const { asJson, projectRef, detection, entities, relationships } = params;
+    const { asJson, projectRef, detection, toolId, entities, relationships } = params;
     const isLibrary = detection.repoKind === "module_library";
-    const nextSteps = isLibrary ? [] : nextStepsFor(projectRef, detection);
+    const nextSteps = isLibrary ? [] : nextStepsFor(projectRef, detection, toolId);
     if (asJson) {
         process.stdout.write(`${JSON.stringify({
             ok: true,
@@ -107,11 +108,12 @@ function reportDryRun(params) {
     // The dry run used to stop here, which made registration look like the whole
     // job: a reader saw four entities and no hint that seven ingest runs were the
     // actual work. A preview has to preview the handoff too.
-    printNextSteps(nextSteps, false);
+    printNextSteps(nextSteps, false, params.executable);
     console.log(`\nNothing was written. Re-run without --dry-run to register, then run the commands above.`);
 }
 export async function runInfrastructureOnboarding(options, detection) {
-    const { dir, nameOverride, asJson, nonInteractive, skipIngest, dryRun } = options;
+    const { dir, nameOverride, asJson, nonInteractive, skipIngest, dryRun, tool: requestedTool } = options;
+    const tool = iacToolOrThrow(dir, requestedTool);
     const displayName = nameOverride ?? basename(dir);
     const projectRef = `project:${slugify(displayName)}`;
     if (!asJson) {
@@ -125,7 +127,7 @@ export async function runInfrastructureOnboarding(options, detection) {
     // at registration is what stops the project being an orphan: without it the
     // graph holds a node that provisions nothing, and no reader can get from an
     // environment back to the code that defines it. The root module paths carry
-    // this before any state is read, so it costs no Terraform run.
+    // this before any state is read, so it costs no run of the IaC tool.
     const environments = [...new Set(detection.rootModules.map((root) => root.environmentHint).filter((hint) => Boolean(hint)))];
     const entities = [
         {
@@ -138,14 +140,14 @@ export async function runInfrastructureOnboarding(options, detection) {
             description: `Infrastructure-as-code repository provisioning the estate (${detection.signals.join(", ")}).`,
             attributes: {
                 source: "nexarch_cli_init_project",
-                iac_tool: "terraform",
-                terraform_file_count: detection.terraformFileCount,
+                iac_tool: tool.id,
+                iac_file_count: detection.iacFileCount,
                 has_remote_backend: detection.hasRemoteBackend,
                 root_module_count: detection.rootModules.length,
                 repo_kind: detection.repoKind,
                 ...(detection.publishedModules.length > 0 ? { published_modules: detection.publishedModules.slice(0, 40) } : {}),
                 ...(detection.ciSystem ? { ci_system: detection.ciSystem } : {}),
-                ...(detection.moduleDirectories.length > 0 ? { terraform_modules: detection.moduleDirectories.slice(0, 25) } : {}),
+                ...(detection.moduleDirectories.length > 0 ? { iac_modules: detection.moduleDirectories.slice(0, 25) } : {}),
             },
         },
         ...environments.map((environment) => ({
@@ -154,7 +156,7 @@ export async function runInfrastructureOnboarding(options, detection) {
             entitySubtypeCode: environmentSubtypeFor(environment),
             name: environment,
             description: `Environment defined by the ${displayName} infrastructure repository.`,
-            attributes: { source: "nexarch_cli_init_project", iac_tool: "terraform" },
+            attributes: { source: "nexarch_cli_init_project", iac_tool: tool.id },
         })),
     ];
     const relationships = environments.map((environment) => ({
@@ -164,7 +166,7 @@ export async function runInfrastructureOnboarding(options, detection) {
         attributes: { source: "nexarch_cli_init_project" },
     }));
     if (dryRun) {
-        reportDryRun({ asJson, projectRef, detection, entities, relationships });
+        reportDryRun({ asJson, projectRef, detection, toolId: tool.id, executable: tool.executable, entities, relationships });
         return;
     }
     const policiesRaw = await callMcpTool("nexarch_get_applied_policies", {});
@@ -198,9 +200,9 @@ export async function runInfrastructureOnboarding(options, detection) {
     // failure — is what lets an agent finish the job unaided.
     const roots = detection.rootModules;
     const isLibrary = detection.repoKind === "module_library";
-    const nextSteps = isLibrary ? [] : nextStepsFor(projectRef, detection);
+    const nextSteps = isLibrary ? [] : nextStepsFor(projectRef, detection, tool.id);
     if (!asJson && !isLibrary && roots.length > 1)
-        printNextSteps(nextSteps, true);
+        printNextSteps(nextSteps, true, tool.executable);
     if (!asJson && isLibrary) {
         console.log(`\nThis repository publishes reusable modules; it does not provision an estate.`);
         console.log(`There is no state to read, so there is nothing to ingest — and that is the`);
@@ -217,7 +219,7 @@ export async function runInfrastructureOnboarding(options, detection) {
         const shouldIngest = nonInteractive ? false : await confirm("\nRead the current state and populate the graph now?");
         if (shouldIngest) {
             try {
-                await ingestInfra(["--dir", dir, "--project-ref", projectRef]);
+                await ingestInfra(["--dir", dir, "--project-ref", projectRef, "--tool", tool.id]);
                 ingested = true;
             }
             catch (error) {
@@ -232,7 +234,7 @@ export async function runInfrastructureOnboarding(options, detection) {
     // come from the command that did the work, not from a convention it half
     // remembers.
     const outstanding = isLibrary ? [] : ingested ? nextSteps.filter((step) => step.rootModule !== "." && roots.length > 1) : nextSteps;
-    const { file, snippet } = ciSnippetFor(detection.ciSystem, detection.ciFile);
+    const { file, snippet } = ciSnippetFor(detection.ciSystem, detection.ciFile, tool.executable);
     if (asJson) {
         process.stdout.write(`${JSON.stringify({
             ok: true,