nexarch 0.13.1 → 0.13.2

package/dist/commands/init-agent.js

@@ -610,6 +610,12 @@ function injectInitProjectReportingContract(path) {
         "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 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",

package/dist/commands/init-project.js

@@ -1238,6 +1238,108 @@ 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.
  *
@@ -1440,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)`);
@@ -1542,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.");
     }
@@ -1575,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;
@@ -1598,15 +1742,19 @@ 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 }] };
                 }
             }
         }
@@ -1629,18 +1777,69 @@ export async function initProject(args) {
         // 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,
+        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,
         });
-        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(", ")}]`);
+        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,
@@ -1760,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,
@@ -1969,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) {
@@ -2145,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: {
@@ -2276,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}`);
@@ -2300,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) {
@@ -2460,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,7 +166,12 @@ 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",