nexarch 0.13.0 → 0.13.2

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,165 @@ export function scoreApplicationCandidate(app, projectName, repoUrl, homepageUrl
         return null;
     return { entityRef, name: app.name, score: Math.min(1, score), reasons };
 }
+/** Every `--map-deployable` value, in order. The flag may be repeated. */
+export function parseDeployableMappings(args) {
+    const mappings = [];
+    for (let i = 0; i < args.length; i += 1) {
+        if (args[i] !== "--map-deployable")
+            continue;
+        const value = args[i + 1] ?? "";
+        const eq = value.indexOf("=");
+        mappings.push(eq > 0 ? { deployable: value.slice(0, eq).trim(), entityRef: value.slice(eq + 1).trim() } : { deployable: value, entityRef: "" });
+    }
+    return mappings;
+}
+/**
+ * Points deployables at applications that already exist.
+ *
+ * A deployable is named by its directory (`web`) or its path (`apps/web`). The
+ * errors are returned rather than thrown so the caller can refuse before
+ * writing anything, naming every problem at once.
+ */
+export function applyDeployableMappings(subPackages, mappings) {
+    const errors = [];
+    for (const mapping of mappings) {
+        if (!mapping.deployable || !mapping.entityRef.startsWith("application:")) {
+            errors.push(`--map-deployable expects <deployable>=application:<ref>, got "${mapping.deployable}${mapping.entityRef ? `=${mapping.entityRef}` : ""}".`);
+            continue;
+        }
+        const target = subPackages.find((sp) => isApplicationLikeEntityType(sp.entityType)
+            && (sp.relativePath === mapping.deployable || basename(sp.relativePath) === mapping.deployable));
+        if (!target) {
+            const known = subPackages.filter((sp) => isApplicationLikeEntityType(sp.entityType)).map((sp) => sp.relativePath);
+            errors.push(`--map-deployable: no deployable called "${mapping.deployable}". This repository has: ${known.join(", ") || "none"}.`);
+            continue;
+        }
+        target.mappedFrom = target.mappedFrom ?? target.externalKey;
+        target.externalKey = mapping.entityRef;
+        target.mappedBy = "flag";
+    }
+    return errors;
+}
+/**
+ * Whether to register, or stop and ask first.
+ *
+ * Paul's decision (16 September): when an application already in the workspace
+ * resembles what a scan is about to register, the scan writes NOTHING and asks.
+ * ADR 8d had made the default "create a proposed application and flag it", and
+ * even once agents were told to stop, the proposed duplicate already existed.
+ *
+ * Only a NEW application can be a duplicate. On a re-run everything already
+ * registered was decided the first time, so asking again every run would be
+ * noise -- and the matches are dropped rather than reported, for the same
+ * reason. `--create-application` is the human having decided.
+ */
+export function registrationGate(params) {
+    if (params.createAnyway || params.newApplicationRefs.length === 0)
+        return { stop: false, similar: [] };
+    return { stop: params.similar.length > 0, similar: params.similar };
+}
+/**
+ * The registration status an agent acts on.
+ *
+ * A possible duplicate outranks everything. In 0.13.1 the output said "Do not
+ * pause or ask for confirmation between steps" in the same object whose first
+ * step said "tell the human before enriching anything", and CLAUDE.md's
+ * completion contract says stopping early is not a finished task. Told twice to
+ * keep going and once to stop, an agent kept going and enriched the duplicate
+ * -- on Paul's 16 September re-run, which the similarity check had correctly
+ * flagged.
+ */
+export function enrichmentStatusFor(params) {
+    if (params.similarApplicationCount > 0)
+        return "review_required";
+    if (params.refreshMode && params.nothingWritten && params.preservedEntityCount > 0)
+        return "review_enrichment";
+    return "enrichment_required";
+}
+export const REVIEW_REQUIRED_NOTE = "STOP. Nothing was written. Existing applications in this workspace resemble what this scan would register"
+    + " (see similarApplications). Tell the human, say which one you think is the same system and why, and wait for"
+    + " their answer. Then re-run init-project with the command in `decision.commands` that matches their choice.";
+/**
+ * The possible-duplicate warning for the text directive, first thing in it.
+ *
+ * The directive goes to stderr precisely so an agent sees it without parsing
+ * JSON, and it used to carry no duplicate warning at all -- the only one was a
+ * JSON field under a note saying not to pause.
+ */
+export function possibleDuplicateDirective(matches, isMonorepo) {
+    if (matches.length === 0)
+        return [];
+    return [
+        "",
+        "STOP — POSSIBLE DUPLICATE. Nothing was written.",
+        "Existing applications in this workspace resemble what this scan would register:",
+        ...matches.map((m) => `  ${m.name} (${m.entityRef}) score ${m.score.toFixed(2)} [${m.reasons.join(", ")}]`),
+        isMonorepo
+            ? "Tell the human which deployable you think is the same system, and why. Then re-run with their choice:"
+            : "Tell the human which one you think is the same application, and why. Then re-run with their choice:",
+        isMonorepo
+            ? "  same system      npx nexarch@latest init-project --dir . --map-deployable <deployable>=<entityRef>"
+            : "  same application npx nexarch@latest init-project --dir . --application-ref <entityRef>",
+        "  all different    npx nexarch@latest init-project --dir . --create-application",
+    ];
+}
+/**
+ * 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 +1466,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 +1485,7 @@ export async function initProject(args) {
                 nonInteractive: parseFlag(args, "--non-interactive"),
                 skipIngest: parseFlag(args, "--no-ingest"),
                 dryRun,
+                tool: parseOptionValue(args, "--tool"),
             }, infrastructure);
             return;
         }
@@ -1381,6 +1542,42 @@ export async function initProject(args) {
         seenSubSlugs.add(dirSlug);
         sp.externalKey = `${sp.entityType}:${projectDirSlug}_${dirSlug}`;
     }
+    // Refuse bad mappings before anything is written, naming every problem.
+    const deployableMappings = parseDeployableMappings(args);
+    if (deployableMappings.length > 0) {
+        const mappingErrors = isMonorepo
+            ? applyDeployableMappings(subPackages, deployableMappings)
+            : ["--map-deployable applies to a repository with several deployables. For a single-package repository use --application-ref."];
+        if (mappingErrors.length > 0)
+            throw new Error(mappingErrors.join("\n"));
+    }
+    // A merge leaves the losing application's ref behind as an alias of the
+    // survivor. Without honouring it, the next scan of the repository would
+    // re-create the application a human had just merged away. Looked up with
+    // recordUnresolved: false -- an unmapped "application:acme_web" is not a
+    // technology to put in front of catalogue reviewers.
+    if (projectConstruct && isMonorepo && !forceCreateApplication) {
+        const unmapped = subPackages.filter((sp) => isApplicationLikeEntityType(sp.entityType) && !sp.mappedFrom);
+        if (unmapped.length > 0) {
+            try {
+                const aliasRaw = await callMcpProfiled("nexarch_resolve_reference", { names: unmapped.map((sp) => sp.externalKey), companyId: creds.companyId, recordUnresolved: false }, { phase: "deployable.alias" });
+                for (const hit of parseToolText(aliasRaw).results ?? []) {
+                    const sp = unmapped.find((candidate) => candidate.externalKey === hit.input);
+                    const ref = hit.canonicalExternalRef;
+                    if (!sp || !hit.resolved || hit.entityTypeCode !== "application" || !ref?.startsWith("application:") || ref === sp.externalKey)
+                        continue;
+                    sp.mappedFrom = sp.externalKey;
+                    sp.externalKey = ref;
+                    sp.mappedBy = "alias";
+                    if (!asJson)
+                        console.log(`  Mapped  : ${sp.relativePath} → ${ref} (${hit.canonicalName ?? "existing application"}), from an earlier merge`);
+                }
+            }
+            catch {
+                // Best effort. If the lookup fails, the duplicate check below still runs.
+            }
+        }
+    }
     if (!asJson) {
         console.log(`  Project : ${displayName} (${entityTypeOverride})`);
         console.log(`  Packages: ${packageJsonCount} package.json file(s)`);
@@ -1399,11 +1596,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);
     }
@@ -1477,6 +1680,10 @@ export async function initProject(args) {
     const sourceProvider = detectedRepo?.provider ?? "unknown";
     const declaredHomepage = readDeclaredHomepage(dir);
     let similarApplications = [];
+    // Set when the scan must stop and ask instead of registering anything.
+    let stopForReview = null;
+    // Names of applications already in the workspace, by ref, for mapped deployables.
+    const existingApplicationNames = new Map();
     if (projectConstruct && isMonorepo && (applicationRefOverride || forceCreateApplication) && !asJson) {
         console.log("\nNote: monorepo detected — no root application is created (ADR 8a); --application-ref/--create-application apply only to single-package repositories.");
     }
@@ -1510,16 +1717,18 @@ export async function initProject(args) {
         if (!applicationRefOverride && projectExternalKey === `${entityTypeOverride}:${projectSlug}`) {
             const appsRaw = await callMcpProfiled("nexarch_list_entities", { entityTypeCode: "application", status: "active", limit: 500, companyId: creds.companyId }, { entityTypeCode: "application", limit: 500 });
             const appsData = parseToolText(appsRaw);
-            const apps = (appsData.entities ?? []).filter((e) => (e.entityRef ?? e.externalKey));
+            const listed = (appsData.entities ?? []).filter((e) => (e.entityRef ?? e.externalKey));
+            // This repository's own application, on a re-run, matches its own name
+            // exactly. Now that a match stops the scan, that would stop every re-run.
+            const alreadyRegistered = listed.some((e) => (e.entityRef ?? e.externalKey) === projectExternalKey);
+            const apps = listed.filter((e) => (e.entityRef ?? e.externalKey) !== projectExternalKey);
             if (apps.length > 0) {
                 const matches = apps
                     .map((a) => scoreApplicationCandidate(a, displayName, repoUrl, declaredHomepage))
                     .filter((m) => Boolean(m))
                     .sort((a, b) => b.score - a.score);
-                // Captured for the JSON output. Until this existed the branch below was
-                // guarded by `!asJson`, so an agent -- which always runs --json -- got a
-                // result with no hint that a similar application already existed, and
-                // reported the new proposal as if nothing resembled it.
+                // Captured for the JSON output, not only printed: an agent always runs
+                // --json, and a match it never sees is a match nobody acts on.
                 similarApplications = matches.slice(0, 5);
                 const suggested = matches.length > 0 ? matches[0] : null;
                 const highConfidence = suggested && suggested.score >= 0.85;
@@ -1533,19 +1742,105 @@ export async function initProject(args) {
                 // remains available via --application-ref and --auto-map-application.
                 if (autoMapApplication && highConfidence) {
                     projectExternalKey = suggested.entityRef;
+                    similarApplications = [];
                     if (!asJson)
                         console.log(`\nAuto-mapped to existing application: ${suggested.name} (${projectExternalKey})`);
                 }
-                else if (matches.length > 0 && !asJson) {
-                    console.log("\nSimilar existing applications found (registering a new proposed application anyway — the reviewer sees these again at activation):");
-                    for (const m of matches.slice(0, 5)) {
-                        console.log(`  - ${m.name} (${m.entityRef}) score=${m.score.toFixed(2)} [${m.reasons.join(", ")}]`);
-                    }
-                    console.log("  To map to one instead, re-run with: --application-ref <entityRef>");
+                else {
+                    const gate = registrationGate({
+                        similar: similarApplications,
+                        newApplicationRefs: alreadyRegistered ? [] : [projectExternalKey],
+                        createAnyway: false,
+                    });
+                    similarApplications = gate.similar;
+                    if (gate.stop)
+                        stopForReview = { newApplications: [{ deployable: basename(dir), entityRef: projectExternalKey }] };
                 }
             }
         }
     }
+    // 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" });
+        const listed = parseToolText(appsRaw).entities ?? [];
+        for (const entity of listed) {
+            const ref = entity.entityRef ?? entity.externalKey;
+            if (ref)
+                existingApplicationNames.set(ref, entity.name);
+        }
+        // A mapped deployable writes no stub of its own, so a mapping to an
+        // application that is not there would leave its relationships pointing at
+        // nothing. Refuse before writing.
+        const badTargets = subPackages.filter((sp) => sp.mappedBy === "flag" && !existingApplicationNames.has(sp.externalKey));
+        if (badTargets.length > 0) {
+            throw new Error(badTargets
+                .map((sp) => `--map-deployable: ${sp.externalKey} is not an active application in this workspace (mapping ${sp.relativePath}).`)
+                .join("\n"));
+        }
+        const newDeployables = subPackages.filter((sp) => isApplicationLikeEntityType(sp.entityType) && !existingApplicationNames.has(sp.externalKey));
+        const gate = registrationGate({
+            similar: similarApplicationsForRepository(listed, { repositoryName: displayName, repoUrl, homepageUrl: declaredHomepage, ownRefs }),
+            newApplicationRefs: newDeployables.map((sp) => sp.externalKey),
+            createAnyway: false,
+        });
+        similarApplications = gate.similar;
+        if (gate.stop) {
+            stopForReview = {
+                newApplications: newDeployables.map((sp) => ({ deployable: basename(sp.relativePath), entityRef: sp.externalKey })),
+            };
+        }
+    }
+    // Paul's decision: a possible duplicate stops the scan before it writes
+    // anything. Resolution has already run (it only reads, and logs names not in
+    // the catalogue); nothing below this point has.
+    if (stopForReview) {
+        const directive = possibleDuplicateDirective(similarApplications, isMonorepo);
+        const commands = isMonorepo
+            ? {
+                sameSystem: "npx nexarch@latest init-project --dir . --map-deployable <deployable>=<entityRef>",
+                allDifferent: "npx nexarch@latest init-project --dir . --create-application",
+            }
+            : {
+                sameApplication: "npx nexarch@latest init-project --dir . --application-ref <entityRef>",
+                allDifferent: "npx nexarch@latest init-project --dir . --create-application",
+            };
+        if (asJson) {
+            process.stdout.write(`${JSON.stringify({
+                ok: true,
+                status: "review_required",
+                wrote: false,
+                project: projectConstruct
+                    ? { name: projectDirName, externalKey: projectEntityKey, entityType: "project", subtype: isMonorepo ? "project_monorepo" : "project_repository" }
+                    : { name: displayName, externalKey: projectExternalKey, entityType: entityTypeOverride },
+                similarApplications,
+                newApplications: stopForReview.newApplications,
+                decision: { note: REVIEW_REQUIRED_NOTE, commands },
+            }, null, 2)}\n`);
+            process.stderr.write(`${directive.join("\n")}\n`);
+        }
+        else {
+            console.log(directive.join("\n"));
+            console.log("\nWould have registered:");
+            for (const app of stopForReview.newApplications)
+                console.log(`  ${app.deployable}  →  ${app.entityRef}`);
+        }
+        return;
+    }
     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.
@@ -1664,6 +1959,10 @@ export async function initProject(args) {
         if (seenSubKeys.has(sp.externalKey))
             continue;
         seenSubKeys.add(sp.externalKey);
+        // The application already exists and a human may have named and described
+        // it. Its relationships below still use its ref.
+        if (sp.mappedFrom)
+            continue;
         const dirDisplayName = basename(sp.relativePath);
         entities.push({
             externalKey: sp.externalKey,
@@ -1873,6 +2172,25 @@ export async function initProject(args) {
             // ability to resolve via tier 2; the scan itself already succeeded.
         }
     }
+    // Remember an explicit --map-deployable, so the next scan does not ask again.
+    // A merge registers the same alias; this is the same decision made up front.
+    for (const sp of subPackages) {
+        if (sp.mappedBy !== "flag" || !sp.mappedFrom)
+            continue;
+        try {
+            await callMcpTool("nexarch_register_alias", {
+                alias: sp.mappedFrom,
+                canonicalExternalKey: sp.externalKey,
+                canonicalName: existingApplicationNames.get(sp.externalKey) ?? sp.externalKey,
+                entityTypeCode: "application",
+                description: `Registered by init-project: the ${sp.relativePath} deployable is this application.`,
+                companyId: creds.companyId,
+            }, { companyId: creds.companyId });
+        }
+        catch {
+            // Non-fatal: without it the next scan asks again, which is safe.
+        }
+    }
     // Upsert relationships (chunked)
     let relsResult = null;
     if (relationships.length > 0) {
@@ -1925,13 +2243,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" : ""} 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" : ""} 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: ${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.",
@@ -2026,16 +2367,21 @@ export async function initProject(args) {
         });
         const preservedEntities = entitiesResult.preserved ?? [];
         const nothingWritten = (entitiesResult.summary?.succeeded ?? 0) === 0;
-        const status = refreshMode && nothingWritten && preservedEntities.length > 0
-            ? "review_enrichment"
-            : "enrichment_required";
+        const status = enrichmentStatusFor({
+            similarApplicationCount: similarApplications.length,
+            refreshMode,
+            nothingWritten,
+            preservedEntityCount: preservedEntities.length,
+        });
         return {
             status,
-            note: status === "review_enrichment"
-                ? "No new skeletons were written — all entities were already enriched and preserved. Review the preservedEntities list and confirm scan values match. Update with nexarch update-entity only if something has genuinely changed."
-                : refreshMode
-                    ? "Execute ALL pendingSteps. In refresh mode, compare graphState vs scanState to identify gaps — do not blindly remove relationships the scanner missed; the scanner cannot detect platforms, integrations, data assets, or application_functions."
-                    : "Execute ALL pendingSteps before reporting the project as registered. Do not pause or ask for confirmation between steps.",
+            note: status === "review_required"
+                ? REVIEW_REQUIRED_NOTE
+                : status === "review_enrichment"
+                    ? "No new skeletons were written — all entities were already enriched and preserved. Review the preservedEntities list and confirm scan values match. Update with nexarch update-entity only if something has genuinely changed."
+                    : refreshMode
+                        ? "Execute ALL pendingSteps. In refresh mode, compare graphState vs scanState to identify gaps — do not blindly remove relationships the scanner missed; the scanner cannot detect platforms, integrations, data assets, or application_functions."
+                        : "Execute ALL pendingSteps before reporting the project as registered. Do not pause or ask for confirmation between steps.",
             ...(refreshMode && preservedEntities.length > 0
                 ? {
                     preservedEntities: {
@@ -2157,6 +2503,7 @@ export async function initProject(args) {
             lines.push("init-project wrote a skeleton. The steps below complete the registration.");
             lines.push("Until they are done, this project is registered as a skeleton only.");
         }
+        lines.push(...possibleDuplicateDirective(similarApplications, isMonorepo));
         lines.push("");
         lines.push(`PROJECT : ${projectConstruct ? `${projectEntityKey} (${isMonorepo ? "monorepo" : "repository"})` : projectExternalKey}`);
         lines.push(`DIR     : ${dir}`);
@@ -2181,6 +2528,12 @@ export async function initProject(args) {
                 const conf = subPackageConfidence(sp);
                 lines.push(`  ${sp.relativePath}`);
                 lines.push(`    key      : ${sp.externalKey}`);
+                if (sp.mappedFrom) {
+                    // "Confirm type, then update" is right for a new skeleton and wrong
+                    // here: this is an application a human already registered and named.
+                    lines.push(`    MAPPED   : this deployable is the existing application ${sp.externalKey}${sp.mappedBy === "alias" ? " (from an earlier merge)" : ""}.`);
+                    lines.push("               Add what the code shows; do not rename it or replace its description.");
+                }
                 lines.push(`    inferred : ${sp.entityType} / ${sp.subtype}  (confidence ${conf.toFixed(2)})`);
                 const unresolvedDeps = sp.depSpecs.map((d) => d.name).filter((d) => !resolvedByInput.has(d));
                 if (unresolvedDeps.length > 0) {
@@ -2341,7 +2694,11 @@ export async function initProject(args) {
     const preservedCount = output.entities.preserved ?? 0;
     console.log(`  Entities     : ${output.entities.succeeded ?? 0} written, ${preservedCount > 0 ? `${preservedCount} preserved (enriched), ` : ""}${output.entities.failed ?? 0} failed`);
     console.log(`  Relationships: ${output.relationships.succeeded ?? 0} written`);
-    console.log(`  Status       : ${output.status === "review_enrichment" ? "all enriched; review preserved entities" : "skeleton created; enrichment pending"}`);
+    console.log(`  Status       : ${output.status === "review_required"
+        ? "possible duplicate; ask before enriching"
+        : output.status === "review_enrichment"
+            ? "all enriched; review preserved entities"
+            : "skeleton created; enrichment pending"}`);
     if (output.metrics.relationshipsSkippedAsDuplicate > 0) {
         console.log(`  Deduped rels : ${output.metrics.relationshipsSkippedAsDuplicate} skipped as duplicates before upsert`);
     }

package/dist/index.js

@@ -166,12 +166,18 @@ Usage:
                                --name <name>  override project name
                                --entity-type <code>  (default: application)
                                --application-ref <entityRef>  force mapping target
-                               --create-application  force new application entity
+                               --map-deployable <dir>=<entityRef>  a monorepo deployable is an
+                                   existing application (repeatable)
+                               --create-application  register even if similar applications exist
+                      If an application already in the workspace resembles one this
+                      would register, nothing is written: it reports the matches and
+                      the command for each choice.
                                --auto-map-application  auto-map only when high confidence
                                --non-interactive  deprecated (mapping no longer prompts)
                                --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