nexarch 0.13.0 → 0.13.1

package/dist/commands/init-project.js

@@ -5,7 +5,7 @@ import { basename, join, relative, resolve as resolvePath } from "node:path";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
 import { buildVersionAttributes } from "../lib/version-normalization.js";
-import { detectInfrastructureProject } from "../lib/terraform-detect.js";
+import { detectInfrastructureProject } from "../lib/iac-detect.js";
 import { runInfrastructureOnboarding } from "./init-project-infra.js";
 import { detectDataProject } from "../lib/data-project-detect.js";
 import { runDataProjectOnboarding } from "./init-project-data.js";
@@ -1238,6 +1238,63 @@ export function scoreApplicationCandidate(app, projectName, repoUrl, homepageUrl
         return null;
     return { entityRef, name: app.name, score: Math.min(1, score), reasons };
 }
+/**
+ * For each detected name, the entity_refs of what declares it.
+ *
+ * Sent with name resolution so that a name not yet in the catalogue is recorded
+ * against the thing that depends on it. Without it, adding `elkjs` to the
+ * catalogue later added it to every workspace that had seen it -- attached to
+ * nothing, because the sighting only knew the repository, and on a first scan
+ * not even that.
+ *
+ * Only application-like packages are dependents: the re-resolve job writes the
+ * edge directly, and a shared library depending on a technology is not an edge
+ * the ontology draws. A monorepo's root manifest is repository tooling, not a
+ * deployable, so it has no dependent; a single-package repository's root is
+ * the application.
+ */
+export function dependentRefsForNames(params) {
+    const refs = new Map();
+    const declare = (name, ref) => {
+        if (!refs.has(name))
+            refs.set(name, new Set());
+        refs.get(name).add(ref);
+    };
+    for (const sp of params.subPackages) {
+        if (!isApplicationLikeEntityType(sp.entityType) || !sp.externalKey)
+            continue;
+        for (const dep of sp.depSpecs)
+            declare(dep.name, sp.externalKey);
+    }
+    if (params.rootDependentRef) {
+        for (const name of params.rootDepNames)
+            declare(name, params.rootDependentRef);
+    }
+    return Object.fromEntries([...refs].map(([name, set]) => [name, [...set].sort()]));
+}
+/**
+ * Existing applications that resemble a repository, for a monorepo.
+ *
+ * Scored on the repository, not on each deployable: per-deployable name
+ * scoring reports the wrong thing. A CLI whose npm name is the product name
+ * scores as a duplicate of the product's website, and short names like "web"
+ * match anything they happen to be a substring of.
+ *
+ * `ownRefs` are this repository's own deployables. They exist on a re-run and
+ * every one contains the repository name, so without excluding them a second
+ * scan reports the repository as a duplicate of itself.
+ */
+export function similarApplicationsForRepository(apps, params) {
+    return apps
+        .filter((app) => {
+        const ref = app.entityRef ?? app.externalKey;
+        return Boolean(ref) && !params.ownRefs.has(ref);
+    })
+        .map((app) => scoreApplicationCandidate(app, params.repositoryName, params.repoUrl, params.homepageUrl))
+        .filter((match) => Boolean(match))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 5);
+}
 // ─── Main command ─────────────────────────────────────────────────────────────
 export async function initProject(args) {
     const asJson = parseFlag(args, "--json");
@@ -1307,6 +1364,7 @@ export async function initProject(args) {
                     nonInteractive: parseFlag(args, "--non-interactive"),
                     skipIngest: parseFlag(args, "--no-ingest"),
                     dryRun,
+                    tool: parseOptionValue(args, "--tool"),
                 }, infrastructure);
             }
             return;
@@ -1325,6 +1383,7 @@ export async function initProject(args) {
                 nonInteractive: parseFlag(args, "--non-interactive"),
                 skipIngest: parseFlag(args, "--no-ingest"),
                 dryRun,
+                tool: parseOptionValue(args, "--tool"),
             }, infrastructure);
             return;
         }
@@ -1399,11 +1458,17 @@ export async function initProject(args) {
         console.log("\nResolving against reference library…");
     const allResolveResults = [];
     const BATCH_SIZE = 200;
+    const dependentRefsByName = dependentRefsForNames({
+        subPackages,
+        rootDepNames,
+        rootDependentRef: isMonorepo ? null : projectExternalKey,
+    });
     logProgress("resolve.start", `count=${detectedNames.length}, batchSize=${BATCH_SIZE}`);
     for (let i = 0; i < detectedNames.length; i += BATCH_SIZE) {
         const batch = detectedNames.slice(i, i + BATCH_SIZE);
         logProgress("resolve.batch", `${Math.floor(i / BATCH_SIZE) + 1}/${Math.ceil(detectedNames.length / BATCH_SIZE)} size=${batch.length}`);
-        const raw = await callMcpProfiled("nexarch_resolve_reference", { names: batch, companyId: creds.companyId, projectRef: projectEntityKey }, { batchSize: batch.length });
+        const dependentRefs = Object.fromEntries(batch.filter((name) => dependentRefsByName[name]?.length).map((name) => [name, dependentRefsByName[name]]));
+        const raw = await callMcpProfiled("nexarch_resolve_reference", { names: batch, companyId: creds.companyId, projectRef: projectEntityKey, dependentRefs }, { batchSize: batch.length });
         const data = parseToolText(raw);
         allResolveResults.push(...data.results);
     }
@@ -1546,6 +1611,37 @@ export async function initProject(args) {
             }
         }
     }
+    // The branch above is gated on !isMonorepo, so for a monorepo -- including
+    // this repository -- the duplicate check never ran at all. Paul's 16
+    // September test registered web, mcp-gateway and nexarch-cli into a
+    // workspace that already held "nexarch.ai website" from onboarding, and
+    // nothing was flagged: item 17's homepage scoring simply never executed.
+    //
+    // Scored at REPOSITORY level, not per deployable. Name scoring per deployable
+    // is worse than silence here: the CLI's npm name is literally "nexarch", so it
+    // scores 0.5 against the website and would be reported as its duplicate, and
+    // "web" matches only because it is a substring of "website". The repository
+    // name is the honest signal, and which deployable (if any) is the same system
+    // is a judgement for a human -- the step below says so.
+    if (projectConstruct && isMonorepo && !forceCreateApplication) {
+        // This repository's own deployables exist on a re-run, and every one of
+        // them contains the repository name. Without excluding them, a second run
+        // reports the repo as a duplicate of itself.
+        const ownRefs = new Set(subPackages.map((sp) => sp.externalKey));
+        const appsRaw = await callMcpProfiled("nexarch_list_entities", { entityTypeCode: "application", status: "active", limit: 500, companyId: creds.companyId }, { entityTypeCode: "application", limit: 500, phase: "monorepo.similar" });
+        similarApplications = similarApplicationsForRepository(parseToolText(appsRaw).entities ?? [], {
+            repositoryName: displayName,
+            repoUrl,
+            homepageUrl: declaredHomepage,
+            ownRefs,
+        });
+        if (similarApplications.length > 0 && !asJson) {
+            console.log("\nExisting applications resemble this repository — one of its deployables may already be registered:");
+            for (const match of similarApplications) {
+                console.log(`  - ${match.name} (${match.entityRef}) score=${match.score.toFixed(2)} [${match.reasons.join(", ")}]`);
+            }
+        }
+    }
     logProgress(projectConstruct ? "project.target" : "application.target", projectConstruct ? (isMonorepo ? projectEntityKey : `${projectEntityKey} + ${projectExternalKey}`) : projectExternalKey);
     // In refresh mode, snapshot the current graph state for this project before writing,
     // so we can diff what changed and surface stale relationships to the agent.
@@ -1925,13 +2021,36 @@ export async function initProject(args) {
         // this application already exists under another name, everything after this
         // enriches a duplicate. The scan has always computed these matches; until
         // now it printed them only in human mode, so the agent never saw them.
-        if (similarApplications.length > 0) {
+        const matchList = similarApplications
+            .map((m) => `${m.name} (${m.entityRef}, score ${m.score.toFixed(2)}, ${m.reasons.join(", ")})`)
+            .join("; ");
+        if (similarApplications.length > 0 && isMonorepo) {
+            // --application-ref does not apply to a monorepo (the CLI says so above),
+            // so the single-repo remedy would hand the agent a command that does
+            // nothing. The resolution here is a merge, which a human does on the
+            // application page.
+            pendingSteps.push({
+                step: stepNum++,
+                action: "review_similar_applications",
+                instruction: `${similarApplications.length} existing application${similarApplications.length === 1 ? "" : "s"} in this`
+                    + ` workspace resemble${similarApplications.length === 1 ? "s" : ""} this repository: ${matchList}.`
+                    + " One of the deployables just registered may be the same system — for example a web app registered"
+                    + " earlier from its public website. Tell the human which deployable you think matches and why, before"
+                    + " enriching anything. The new deployables are PROPOSED, so nothing is broken yet; if one is a"
+                    + " duplicate, the human merges the two with \"Merge with…\" on the application's page.",
+                notes: [
+                    "Do not report the registration as complete without mentioning these.",
+                    "The match is on the repository, not a specific deployable: say which one you believe it is, and why.",
+                    "A human decides which is the same application — do not merge or decline on your own judgement.",
+                ],
+            });
+        }
+        else if (similarApplications.length > 0) {
             pendingSteps.push({
                 step: stepNum++,
                 action: "review_similar_applications",
                 instruction: `${similarApplications.length} existing application${similarApplications.length === 1 ? "" : "s"} in this`
-                    + ` workspace resemble${similarApplications.length === 1 ? "s" : ""} the one just registered:`
-                    + ` ${similarApplications.map((m) => `${m.name} (${m.entityRef}, score ${m.score.toFixed(2)}, ${m.reasons.join(", ")})`).join("; ")}.`
+                    + ` workspace resemble${similarApplications.length === 1 ? "s" : ""} the one just registered: ${matchList}.`
                     + " Tell the human about these before enriching anything. This registration was created as a"
                     + " PROPOSED application and is not in the canonical graph yet, so nothing is broken — but if one of"
                     + " these is the same application, it should be mapped rather than duplicated.",

package/dist/index.js

@@ -172,6 +172,7 @@ Usage:
                                --batch-size <n>  upsert batch size (default: 10)
                                --profile  include timing/profile data in JSON output
                                --dry-run  preview without writing
+                               --tool <terraform|opentofu>  select the IaC state CLI
                                --json
   nexarch update-project
                       Re-scan a previously registered project directory, refresh

package/dist/lib/ansible-detect.js

@@ -0,0 +1,109 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join, relative, sep } from "path";
+import { environmentFromPath } from "./iac-detect.js";
+const SCAN_DEPTH = 8;
+const IGNORED = new Set([".git", "node_modules", ".venv", "venv", "dist", "build", ".next"]);
+const YAML = /\.ya?ml$/i;
+function walk(dir, depth = 0, files = []) {
+    if (depth > SCAN_DEPTH)
+        return files;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        if (IGNORED.has(entry))
+            continue;
+        const full = join(dir, entry);
+        try {
+            if (statSync(full).isDirectory())
+                walk(full, depth + 1, files);
+            else
+                files.push(full);
+        }
+        catch { /* unreadable paths are not evidence */ }
+    }
+    return files;
+}
+function hasPlaybookShape(file) {
+    if (!YAML.test(file))
+        return false;
+    try {
+        const text = readFileSync(file, "utf8");
+        return /^\s*-?\s*hosts\s*:/m.test(text) && /^\s*(tasks|roles|pre_tasks|post_tasks|handlers)\s*:/m.test(text);
+    }
+    catch {
+        return false;
+    }
+}
+function normalise(repoDir, file) {
+    return relative(repoDir, file).split(sep).join("/");
+}
+/**
+ * The environment an inventory is for, from its path.
+ *
+ * Terraform gets this from a root module directory or a workspace. Ansible has
+ * neither, and this is the gap the plan called out as the hard part: the
+ * environment lives in how the inventory is filed. `inventories/production/hosts`
+ * and `inventory/prod.ini` both say it plainly, so the filename is consulted as
+ * well as the directories -- which is where `environmentFromPath` alone stops,
+ * since a Terraform root module is always a directory.
+ *
+ * The vocabulary is deliberately shared with `environmentFromPath` rather than
+ * copied: two lists of environment names drift, and then the same repository
+ * reports different environments depending on which tool read it.
+ */
+export function environmentFromInventoryPath(relativePath) {
+    const fromDirectories = environmentFromPath(relativePath);
+    if (fromDirectories)
+        return fromDirectories;
+    const base = (relativePath.split("/").at(-1) ?? "").replace(/\.(ini|ya?ml|json)$/i, "");
+    return base ? environmentFromPath(base) : null;
+}
+/**
+ * Detects Ansible from corroborating repository evidence.
+ *
+ * A YAML file containing `hosts:` is not enough: application configuration
+ * regularly has the same vocabulary. Like IaC detection, a playbook needs a
+ * second operational signal (inventory, roles, configuration, or collection)
+ * before it can change onboarding behaviour.
+ */
+export function detectAnsibleProject(repoDir) {
+    const files = walk(repoDir);
+    const relativeFiles = files.map((file) => normalise(repoDir, file));
+    const playbookFiles = files.filter(hasPlaybookShape).map((file) => normalise(repoDir, file)).sort();
+    const inventoryFiles = relativeFiles.filter((file) => {
+        const base = file.split("/").at(-1) ?? "";
+        return /(^|\/)(inventory|inventories)(\/|$)/i.test(file) || /^(hosts|inventory)(\.ini|\.ya?ml)?$/i.test(base);
+    }).sort();
+    const roleDirectories = relativeFiles
+        .filter((file) => /(^|\/)roles\/[^/]+\/(tasks|handlers|defaults|vars)\/main\.ya?ml$/i.test(file))
+        .map((file) => file.replace(/\/(tasks|handlers|defaults|vars)\/main\.ya?ml$/i, ""))
+        .filter((value, index, values) => values.indexOf(value) === index)
+        .sort();
+    const collectionDirectories = relativeFiles
+        .filter((file) => /(^|\/)collections\/requirements\.ya?ml$/i.test(file) || /(^|\/)galaxy\.ya?ml$/i.test(file))
+        .map((file) => file.replace(/\/(requirements|galaxy)\.ya?ml$/i, ""))
+        .filter((value, index, values) => values.indexOf(value) === index)
+        .sort();
+    const hasConfig = existsSync(join(repoDir, "ansible.cfg"));
+    const signals = [];
+    if (playbookFiles.length)
+        signals.push(`${playbookFiles.length} playbook${playbookFiles.length === 1 ? "" : "s"}`);
+    if (inventoryFiles.length)
+        signals.push(`${inventoryFiles.length} inventory file${inventoryFiles.length === 1 ? "" : "s"}`);
+    if (roleDirectories.length)
+        signals.push(`${roleDirectories.length} role${roleDirectories.length === 1 ? "" : "s"}`);
+    if (collectionDirectories.length)
+        signals.push(`${collectionDirectories.length} collection declaration${collectionDirectories.length === 1 ? "" : "s"}`);
+    if (hasConfig)
+        signals.push("ansible.cfg");
+    const environments = [...new Set(inventoryFiles.map(environmentFromInventoryPath).filter((e) => Boolean(e)))].sort();
+    if (environments.length)
+        signals.push(`environments: ${environments.join(", ")}`);
+    const corroborated = inventoryFiles.length > 0 || roleDirectories.length > 0 || collectionDirectories.length > 0 || hasConfig;
+    return { isAnsible: playbookFiles.length > 0 && corroborated, signals, playbookFiles, inventoryFiles, environments, roleDirectories, collectionDirectories };
+}

package/dist/lib/ansible-projection.js

@@ -0,0 +1,150 @@
+import { parse } from "yaml";
+export const DEFAULT_ANSIBLE_HOST_MAPPING = {
+    entityTypeCode: "platform_component",
+    entitySubtypeCode: null,
+    role: "compute_host",
+    resourceType: "ansible_host",
+};
+/** Ansible's own bookkeeping groups: every host is in them, so they classify nothing. */
+const BOOKKEEPING_GROUPS = new Set(["all", "ungrouped"]);
+function hostNamesOf(raw) {
+    const hosts = raw.hosts;
+    const names = Array.isArray(hosts) ? hosts : hosts && typeof hosts === "object" ? Object.keys(hosts) : [];
+    return names.filter((name) => typeof name === "string" && Boolean(name.trim()));
+}
+function childNamesOf(raw) {
+    const children = raw.children;
+    const names = Array.isArray(children) ? children : children && typeof children === "object" ? Object.keys(children) : [];
+    return names.filter((name) => typeof name === "string" && Boolean(name.trim()));
+}
+/**
+ * Resolves group membership, following `children`.
+ *
+ * Nested groups are how real inventories express environment: `prod` holds no
+ * hosts of its own, only `children: [web, db]`. Reading `hosts` alone gives a
+ * host the group it was listed under and loses every ancestor -- which is to
+ * say, it loses the environment, the one thing the group tree is usually for.
+ *
+ * Shared by both parsers on purpose. JSON and INI express the same tree in
+ * different syntax, and resolving it twice is how the two formats come to
+ * disagree about the same estate.
+ *
+ * The seen set is against cycles, which Ansible rejects at runtime but which
+ * can sit in a file and must not hang the scan.
+ */
+function resolveMemberships(tree) {
+    const hostsUnder = (group, seen = new Set()) => {
+        if (seen.has(group))
+            return [];
+        seen.add(group);
+        return [
+            ...(tree.hosts.get(group) ?? []),
+            ...(tree.children.get(group) ?? []).flatMap((child) => hostsUnder(child, seen)),
+        ];
+    };
+    const memberships = new Map();
+    for (const group of new Set([...tree.hosts.keys(), ...tree.children.keys()])) {
+        for (const name of hostsUnder(group)) {
+            const memberOf = memberships.get(name) ?? new Set();
+            if (!BOOKKEEPING_GROUPS.has(group))
+                memberOf.add(group);
+            memberships.set(name, memberOf);
+        }
+    }
+    return [...memberships.entries()]
+        .map(([name, groups]) => ({ name, groups: [...groups].sort() }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function groupsFromObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return [];
+    const tree = { hosts: new Map(), children: new Map() };
+    for (const [group, raw] of Object.entries(value)) {
+        if (group === "_meta" || !raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        tree.hosts.set(group, hostNamesOf(raw));
+        tree.children.set(group, childNamesOf(raw));
+    }
+    return resolveMemberships(tree);
+}
+function parseIni(text) {
+    const tree = { hosts: new Map(), children: new Map() };
+    let group = "ungrouped";
+    // "hosts", "children" or "vars" — an INI section header says which, and a
+    // `:children` section is the nesting the JSON form spells as `children`.
+    let section = "hosts";
+    const push = (map, key, value) => {
+        map.set(key, [...(map.get(key) ?? []), value]);
+    };
+    for (const line of text.split(/\r?\n/)) {
+        const clean = line.replace(/\s[;#].*$/, "").trim();
+        const header = clean.match(/^\[([^\]]+)\]$/);
+        if (header) {
+            const suffix = /:(children|vars)$/.exec(header[1])?.[1];
+            section = suffix === "children" ? "children" : suffix === "vars" ? "vars" : "hosts";
+            group = header[1].replace(/:(children|vars)$/, "");
+            continue;
+        }
+        if (!clean || section === "vars" || clean.startsWith("#") || clean.startsWith(";"))
+            continue;
+        // `web-01 ansible_host=10.0.0.5` is an ordinary host line: inline variables
+        // are how INI inventories are usually written. Skipping every line
+        // containing `=` dropped exactly those hosts, which is most of them. The
+        // `:vars` section is already excluded above, so the only thing that rule
+        // caught was the common case.
+        const name = clean.split(/\s+/)[0];
+        if (!name || name.includes("=") || name.includes(":"))
+            continue;
+        push(section === "children" ? tree.children : tree.hosts, group, name);
+    }
+    return resolveMemberships(tree);
+}
+/** Parses `ansible-inventory --list --export` JSON/YAML, or a conventional INI inventory. */
+export function parseAnsibleInventory(input) {
+    if (input && typeof input === "object")
+        return { hosts: groupsFromObject(input) };
+    const text = input.trim();
+    if (!text)
+        return { hosts: [] };
+    // `{` only. An INI inventory conventionally opens with a group header, so
+    // treating a leading `[` as JSON sent every one of them to JSON.parse and
+    // threw on the most common inventory format there is. A JSON array is not
+    // valid `ansible-inventory --list` output anyway.
+    if (text.startsWith("{"))
+        return { hosts: groupsFromObject(JSON.parse(text)) };
+    if (/^\s*\w[\w-]*\s*:/m.test(text) && !/^\s*\[/m.test(text))
+        return { hosts: groupsFromObject(parse(text)) };
+    return { hosts: parseIni(text) };
+}
+/**
+ * Projects only inventory identity and group membership. In particular,
+ * `_meta.hostvars`, inline `ansible_*` variables, vault values, and connection
+ * settings are intentionally not present in either attributes or tags.
+ */
+export function projectAnsibleInventory(params) {
+    const mapping = params.mapping ?? DEFAULT_ANSIBLE_HOST_MAPPING;
+    const resources = params.inventory.hosts.map((host) => ({
+        address: `ansible:${host.name}`,
+        resourceType: mapping.resourceType,
+        entityTypeCode: mapping.entityTypeCode,
+        entitySubtypeCode: mapping.entitySubtypeCode ?? null,
+        role: mapping.role,
+        // Not "managed". Ansible configures hosts that already exist -- the
+        // inventory is a list of machines someone else provisioned. Recording them
+        // as managed would have the graph claim we created a server we only
+        // installed packages on, and `IacTool.provisions` exists to carry exactly
+        // this distinction.
+        mode: "declared",
+        name: host.name,
+        attributes: { inventory_hostname: host.name, ansible_groups: [...host.groups].sort() },
+        tags: {},
+        identityIds: [],
+    }));
+    return {
+        environment: params.environment,
+        iacToolVersion: null,
+        resources,
+        unknownTypes: [],
+        stats: { resourcesSeen: resources.length, resourcesProjected: resources.length, attributesDroppedNotAllowlisted: 0, attributesDroppedSensitive: 0 },
+    };
+}