@mnci/cli 4.43.0 → 4.45.0

package/dist/cli.js

@@ -8485,9 +8485,387 @@ function runDoctor(workspaceRoot, options = {}) {
   process.exitCode = 1;
 }
 
-// src/repository-adoption/inspect-repository.use-case.ts
+// src/repository-adoption/adopt-overlay.use-case.ts
+var import_node_fs32 = require("fs");
+var import_node_path37 = require("path");
+
+// src/workspace-upgrade/upgrade-workspace.use-case.ts
 var import_node_fs31 = require("fs");
 var import_node_path36 = require("path");
+function resolveRegistry(options, persisted) {
+  if (options.registry === "azure-artifacts" || options.organization && options.artifactsFeed) {
+    const persistedAzure = persisted?.kind === "azure-artifacts" ? persisted : void 0;
+    const organization = options.organization ?? persistedAzure?.organization;
+    const project = options.project ?? persistedAzure?.project;
+    const artifactsFeed = options.artifactsFeed ?? persistedAzure?.artifactsFeed;
+    if (!organization || !project || !artifactsFeed) {
+      throw new Error(
+        "Azure Artifacts registry needs --organization, --project and --artifacts-feed (none found in nx.json's persisted config either)."
+      );
+    }
+    return { kind: "azure-artifacts", organization, project, artifactsFeed };
+  }
+  if (options.registry === "npm") {
+    return { kind: "npm" };
+  }
+  if (persisted) {
+    return persisted;
+  }
+  throw new Error(
+    "No registry found in nx.json's persisted config. Pass --registry npm or --registry azure-artifacts (with --organization/--project/--artifacts-feed)."
+  );
+}
+function resolveWorkspaceName(workspaceRoot, persisted) {
+  if (persisted.workspaceName) {
+    return persisted.workspaceName;
+  }
+  try {
+    const existing = (0, import_node_fs31.readdirSync)(workspaceRoot).find(
+      (file) => file.endsWith(".code-workspace") && file !== "undefined.code-workspace"
+    );
+    if (existing) {
+      return existing.replace(/\.code-workspace$/, "");
+    }
+  } catch {
+  }
+  return (0, import_node_path36.basename)(workspaceRoot);
+}
+function detectNpmAuth(workspaceRoot) {
+  try {
+    return (0, import_node_fs31.readFileSync)((0, import_node_path36.join)(workspaceRoot, "azure-pipelines.yml"), "utf8").includes("npmAuthenticate@0") ? "build-identity" : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolveOverlayOptions(workspaceRoot, options, persisted) {
+  const scope = options.scope ?? persisted.scope;
+  if (!scope) {
+    throw new Error("No npm scope found in nx.json's persisted config. Pass --scope explicitly.");
+  }
+  const registry = resolveRegistry(options, persisted.registry);
+  const ci = options.ci ?? persisted.ci;
+  if (!ci) {
+    throw new Error(
+      "No CI provider found in nx.json's persisted config. Pass --ci azure|github|both explicitly."
+    );
+  }
+  const agent = options.agent ?? persisted.agent;
+  if (!agent) {
+    throw new Error(
+      "No CI build agent found in nx.json's persisted config. Pass --agent explicitly."
+    );
+  }
+  const variableGroup = options.variableGroup ?? persisted.variableGroup ?? "Build";
+  const detected = ci === "azure" && persisted.npmAuth === void 0 && options.npmAuth === void 0 ? detectNpmAuth(workspaceRoot) : void 0;
+  if (detected) {
+    logger.detail("keeping build-identity npm auth: azure-pipelines.yml already runs npmAuthenticate@0");
+  }
+  const npmAuth = resolveNpmAuth(options.npmAuth, registry, ci, persisted.npmAuth ?? detected);
+  const testRunner = options.testRunner ?? persisted.stack?.testRunner;
+  if (!testRunner) {
+    throw new Error(
+      "No testRunner found in nx.json's persisted config. Pass --test-runner explicitly."
+    );
+  }
+  return {
+    workspaceName: resolveWorkspaceName(workspaceRoot, persisted),
+    scope,
+    registry,
+    agent,
+    variableGroup,
+    ci,
+    stack: { testRunner },
+    ...npmAuth && { npmAuth }
+  };
+}
+function runUpgrade(workspaceRoot, options) {
+  if (!fileExists((0, import_node_path36.join)(workspaceRoot, "nx.json"))) {
+    throw new Error(
+      `No nx.json found in ${workspaceRoot} \u2014 this does not look like an Nx workspace. Run 'mnci upgrade' from the workspace root.`
+    );
+  }
+  const persisted = readMnciConfig(workspaceRoot);
+  const resolved = resolveOverlayOptions(workspaceRoot, options, persisted);
+  logger.step("Re-applying the MoNecromanCI overlay");
+  applyOverlay(workspaceRoot, resolved, logger.detail);
+  const repaired = repairRollupSourceMaps(workspaceRoot);
+  if (repaired.length > 0) {
+    logger.step("Enabling source maps in rollup configs (breakpoints in .ts files)");
+    for (const path of repaired) {
+      logger.detail(`updated ${path}`);
+    }
+  }
+  const repairedManifests = repairPublishableManifests(workspaceRoot);
+  if (repairedManifests.length > 0) {
+    logger.step("Repointing `types` at the real declaration file");
+    for (const path of repairedManifests) {
+      logger.detail(`updated ${path}`);
+    }
+  }
+  const lockfile = pruneStaleLocalRegistry(workspaceRoot);
+  if (lockfile.stale) {
+    logger.step("Dropping the unused local registry (verdaccio) from package-lock.json");
+    if (lockfile.status !== 0) {
+      logger.warn("npm could not re-resolve the lockfile; run `npm install --package-lock-only` once you are online.");
+    }
+  }
+  const goApps = addGoPlatformTargets(workspaceRoot);
+  if (goApps.length > 0) {
+    logger.step("Adding the six-platform build to Go apps (build-all, package-all)");
+    for (const path of goApps) {
+      logger.detail(`updated ${path}`);
+    }
+  }
+  const pinnedExtensions = pinVscodeExtensionProjectNames(workspaceRoot);
+  if (pinnedExtensions.length > 0) {
+    logger.step("Pinning the Nx project name of VS Code extensions (nx.name)");
+    for (const path of pinnedExtensions) {
+      logger.detail(`updated ${path}`);
+    }
+  }
+  if (refreshVscodeExtensionScript(workspaceRoot)) {
+    logger.step("Updating the VS Code extension packaging script");
+    logger.detail(`updated ${VSCODE_EXTENSION_SCRIPT_PATH}`);
+  }
+  if (refreshGoReleaseScript(workspaceRoot)) {
+    logger.step("Updating the releasable Go app script");
+    logger.detail(`updated ${GO_RELEASE_SCRIPT_PATH}`);
+  }
+  if (hasGoProject(workspaceRoot) && registerNxGoPlugin(workspaceRoot)) {
+    logger.step("Registering the Go plugin in nx.json, so Nx can see which Go project imports which");
+    logger.detail("updated nx.json");
+  }
+  const addedDtsPlugins = addMissingDeclarationSpecifierPlugins(workspaceRoot);
+  if (addedDtsPlugins.length > 0) {
+    logger.step("Adding the declaration-specifier plugin to rollup configs that lacked it");
+    for (const path of addedDtsPlugins) {
+      logger.detail(`updated ${path}`);
+    }
+  }
+  const upgradedDtsPlugins = upgradeDeclarationSpecifierPlugins(workspaceRoot);
+  if (upgradedDtsPlugins.length > 0) {
+    logger.step("Upgrading declaration specifiers to resolve under nodenext");
+    for (const path of upgradedDtsPlugins) {
+      logger.detail(`updated ${path}`);
+    }
+  }
+  logger.step(
+    "Formatting the workspace (eslint --fix) \u2014 the slowest step, minutes on a large workspace"
+  );
+  runFormatter(workspaceRoot);
+  const nxJson = readJson((0, import_node_path36.join)(workspaceRoot, "nx.json"));
+  const stranded = locateStrandedReleaseTags(workspaceRoot, nxJson.release?.releaseTag?.pattern);
+  for (const entry of stranded) {
+    logger.warn(`${entry.project} has release tags only under ${entry.oldTag}: nx release would restart it from its disk version. Run \`git tag ${entry.newTag} ${entry.oldTag}^{commit}\` before the next release (\`mnci doctor\` lists them all).`);
+  }
+  logger.success("Done. Review the changes with `git diff` before committing.");
+  logger.info("Run `npm install` and commit package-lock.json too: the overlay may have added or moved a dependency, and CI installs with `npm ci`, which refuses a stale lockfile.");
+}
+
+// src/repository-adoption/clean-working-tree.validator.ts
+function requireCleanWorkingTree(repositoryRoot, capture = runCapture) {
+  if (capture("git", ["rev-parse", "--is-inside-work-tree"], repositoryRoot).status !== 0) {
+    throw new Error("This directory is not a git repository. Every adoption step is one diff to review, so it needs git.");
+  }
+  if (capture("git", ["status", "--porcelain"], repositoryRoot).stdout.trim() !== "") {
+    throw new Error("The working tree has uncommitted changes. Commit or stash them, so this step is one diff you can review or discard.");
+  }
+}
+
+// src/repository-adoption/adopt-overlay.use-case.ts
+function detectCiProvider(repositoryRoot) {
+  const azure = (0, import_node_fs32.existsSync)((0, import_node_path37.join)(repositoryRoot, "azure-pipelines.yml"));
+  const workflows = (0, import_node_path37.join)(repositoryRoot, ".github", "workflows");
+  const github = (0, import_node_fs32.existsSync)(workflows) && (0, import_node_fs32.readdirSync)(workflows).some((file) => /\.ya?ml$/.test(file));
+  if (azure && github) {
+    return "both";
+  }
+  if (azure) {
+    return "azure";
+  }
+  return github ? "github" : void 0;
+}
+function detectTestRunner(repositoryRoot) {
+  const manifestPath = (0, import_node_path37.join)(repositoryRoot, "package.json");
+  if (!fileExists(manifestPath)) {
+    return void 0;
+  }
+  const manifest = readJson(manifestPath);
+  const declared = new Set(Object.keys({ ...manifest.dependencies, ...manifest.devDependencies }));
+  if (declared.has("vitest")) {
+    return "vitest";
+  }
+  return declared.has("jest") ? "jest" : void 0;
+}
+function adoptOverlay(repositoryRoot, options, dependencies = {}) {
+  requireCleanWorkingTree(repositoryRoot, dependencies.capture ?? runCapture);
+  if (!fileExists((0, import_node_path37.join)(repositoryRoot, "nx.json"))) {
+    throw new Error("There is no nx.json, so Nx is not set up here. Set it up first (`npx nx@latest init`); adopt does not install Nx yet.");
+  }
+  const persisted = readMnciConfig(repositoryRoot);
+  const filled = {
+    ...options,
+    ci: options.ci ?? (persisted.ci === void 0 ? detectCiProvider(repositoryRoot) : void 0),
+    testRunner: options.testRunner ?? (persisted.stack?.testRunner === void 0 ? detectTestRunner(repositoryRoot) : void 0)
+  };
+  (dependencies.upgrade ?? runUpgrade)(repositoryRoot, filled);
+}
+
+// src/repository-adoption/adopt-toolchain.use-case.ts
+var import_node_path39 = require("path");
+
+// src/repository-adoption/align-nx-family.algorithm.ts
+var VERSION = /^[\^~]?(\d+)\.(\d+)\.(\d+)$/;
+function isNxFamily(name) {
+  return name === "nx" || name.startsWith("@nx/");
+}
+function compare(left, right) {
+  const a = left.split(".").map(Number);
+  const b = right.split(".").map(Number);
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2] || 0;
+}
+function chooseNxVersion(declared, published, requested) {
+  const current = Object.entries(declared).filter(([name]) => isNxFamily(name)).map(([, range]) => VERSION.exec(range)).filter((match) => match !== null).map((match) => `${match[1]}.${match[2]}.${match[3]}`);
+  if (current.length === 0) {
+    return void 0;
+  }
+  if (requested !== void 0) {
+    return requested;
+  }
+  const newest = current.toSorted((a, b) => compare(a, b)).at(-1);
+  const major = newest.split(".", 1)[0];
+  const candidates = published.filter((version) => /^\d+\.\d+\.\d+$/.test(version) && version.split(".", 1)[0] === major);
+  return candidates.toSorted((a, b) => compare(a, b)).at(-1);
+}
+function alignNxFamily(dependencies, version) {
+  const changed = [];
+  const aligned = Object.fromEntries(Object.entries(dependencies).map(([name, range]) => {
+    if (range !== version && isNxFamily(name)) {
+      changed.push(name);
+      return [name, version];
+    }
+    return [name, range];
+  }));
+  return { dependencies: aligned, changed };
+}
+
+// src/repository-adoption/retire-tooling.use-case.ts
+var import_node_fs33 = require("fs");
+var import_node_path38 = require("path");
+var RETIRED_COMMAND = /\b(?:prettier|oxfmt|oxlint)\b/;
+function retireTooling(repositoryRoot) {
+  const removed = [];
+  for (const file of RETIRED_FORMATTER_FILES) {
+    if (!fileExists((0, import_node_path38.join)(repositoryRoot, file))) {
+      continue;
+    }
+    (0, import_node_fs33.rmSync)((0, import_node_path38.join)(repositoryRoot, file), { force: true });
+    removed.push(file);
+  }
+  const hadRegistry = fileExists((0, import_node_path38.join)(repositoryRoot, ".verdaccio"));
+  removeLocalRegistryScaffolding(repositoryRoot);
+  if (hadRegistry) {
+    removed.push(".verdaccio, its dependency and the local-registry target");
+  }
+  const manifestPath = (0, import_node_path38.join)(repositoryRoot, "package.json");
+  if (!fileExists(manifestPath)) {
+    return removed;
+  }
+  const manifest = readJson(manifestPath);
+  for (const key of ["dependencies", "devDependencies"]) {
+    const before = manifest[key];
+    if (before === void 0) {
+      continue;
+    }
+    const after = withoutRetiredFormatterDependencies(before);
+    const kept = new Set(Object.keys(after));
+    const dropped = Object.keys(before).filter((name) => !kept.has(name));
+    removed.push(...dropped.map((name) => `${key}: ${name}`));
+    manifest[key] = after;
+  }
+  const scripts = Object.entries(manifest.scripts ?? {});
+  for (const [name, command] of scripts) {
+    if (!RETIRED_COMMAND.test(command)) {
+      continue;
+    }
+    Reflect.deleteProperty(manifest.scripts, name);
+    removed.push(`script: ${name} (${command})`);
+  }
+  writeFileEnsured(manifestPath, toJson(manifest));
+  return removed;
+}
+
+// src/repository-adoption/adopt-toolchain.use-case.ts
+var MAX_AUDIT_FIX_PASSES = 4;
+function publishedNxVersions(repositoryRoot, capture) {
+  const answer = capture("npm", ["view", "nx", "versions", "--json"], repositoryRoot);
+  try {
+    const parsed = JSON.parse(answer.stdout);
+    return Array.isArray(parsed) ? parsed.filter((version) => typeof version === "string") : [];
+  } catch {
+    return [];
+  }
+}
+function adoptToolchain(repositoryRoot, options = {}, dependencies = {}) {
+  const run = dependencies.run ?? runShell;
+  const capture = dependencies.capture ?? runCapture;
+  const audit = dependencies.audit ?? ((root) => runAudit(root));
+  const log = dependencies.log ?? ((message) => {
+    console.log(message);
+  });
+  requireCleanWorkingTree(repositoryRoot, capture);
+  const manifestPath = (0, import_node_path39.join)(repositoryRoot, "package.json");
+  if (!fileExists(manifestPath)) {
+    throw new Error("No package.json at the repository root.");
+  }
+  log("Removing retired tooling");
+  const removed = retireTooling(repositoryRoot);
+  const manifest = readJson(manifestPath);
+  const version = chooseNxVersion({ ...manifest.dependencies, ...manifest.devDependencies }, publishedNxVersions(repositoryRoot, capture), options.nxVersion);
+  const names = [];
+  if (version !== void 0) {
+    for (const key of ["dependencies", "devDependencies"]) {
+      if (manifest[key] === void 0) {
+        continue;
+      }
+      const result = alignNxFamily(manifest[key], version);
+      manifest[key] = result.dependencies;
+      names.push(...result.changed);
+    }
+    writeFileEnsured(manifestPath, toJson(manifest));
+  }
+  log("Installing, so the lockfile follows the manifest");
+  run("npm", ["install", "--ignore-scripts", "--no-audit", "--no-fund"], repositoryRoot);
+  pruneStaleLocalRegistry(repositoryRoot);
+  let auditFixes = 0;
+  let passes = audit(repositoryRoot) === 0;
+  while (!passes && auditFixes < MAX_AUDIT_FIX_PASSES) {
+    auditFixes += 1;
+    log(`npm audit fix, pass ${auditFixes}`);
+    run("npm", ["audit", "fix", "--no-fund"], repositoryRoot);
+    passes = audit(repositoryRoot) === 0;
+  }
+  return { removed, aligned: { names, version }, auditFixes, auditPasses: passes };
+}
+
+// src/repository-adoption/create-baseline-tags.use-case.ts
+function createBaselineTags(repositoryRoot, stranded) {
+  const result = { created: [], existing: [], failed: [] };
+  for (const entry of stranded) {
+    const present = runCapture("git", ["rev-parse", "--verify", "--quiet", `refs/tags/${entry.newTag}`], repositoryRoot);
+    if (present.status === 0) {
+      result.existing.push(entry.newTag);
+      continue;
+    }
+    const made = runCapture("git", ["tag", entry.newTag, `${entry.oldTag}^{commit}`], repositoryRoot);
+    (made.status === 0 ? result.created : result.failed).push(entry.newTag);
+  }
+  return result;
+}
+
+// src/repository-adoption/inspect-repository.use-case.ts
+var import_node_fs34 = require("fs");
+var import_node_path40 = require("path");
 var LOCKFILES = [
   ["package-lock.json", "npm"],
   ["pnpm-lock.yaml", "pnpm"],
@@ -8508,25 +8886,25 @@ function inspectRepository(repositoryRoot) {
   const isGitRepo = inside.status === 0 && inside.stdout.trim() === "true";
   const dirty = isGitRepo && runCapture("git", ["status", "--porcelain"], repositoryRoot).stdout.trim() !== "";
   const tags = isGitRepo ? runCapture("git", ["tag", "--list"], repositoryRoot).stdout.split(/\r?\n/).filter(Boolean) : [];
-  const manifestPath = (0, import_node_path36.join)(repositoryRoot, "package.json");
+  const manifestPath = (0, import_node_path40.join)(repositoryRoot, "package.json");
   const manifest = fileExists(manifestPath) ? readJson(manifestPath) : {};
-  const nxJsonPath = (0, import_node_path36.join)(repositoryRoot, "nx.json");
+  const nxJsonPath = (0, import_node_path40.join)(repositoryRoot, "nx.json");
   const nxJson = fileExists(nxJsonPath) ? readJson(nxJsonPath) : {};
   const ci = [];
   const pipelines = [];
-  if ((0, import_node_fs31.existsSync)((0, import_node_path36.join)(repositoryRoot, "azure-pipelines.yml"))) {
+  if ((0, import_node_fs34.existsSync)((0, import_node_path40.join)(repositoryRoot, "azure-pipelines.yml"))) {
     ci.push("azure");
-    pipelines.push((0, import_node_path36.join)(repositoryRoot, "azure-pipelines.yml"));
+    pipelines.push((0, import_node_path40.join)(repositoryRoot, "azure-pipelines.yml"));
   }
-  const workflows = (0, import_node_path36.join)(repositoryRoot, ".github", "workflows");
-  if ((0, import_node_fs31.existsSync)(workflows)) {
-    const files = (0, import_node_fs31.readdirSync)(workflows).filter((file) => /\.ya?ml$/.test(file));
+  const workflows = (0, import_node_path40.join)(repositoryRoot, ".github", "workflows");
+  if ((0, import_node_fs34.existsSync)(workflows)) {
+    const files = (0, import_node_fs34.readdirSync)(workflows).filter((file) => /\.ya?ml$/.test(file));
     if (files.length > 0) {
       ci.push("github");
-      pipelines.push(...files.map((file) => (0, import_node_path36.join)(workflows, file)));
+      pipelines.push(...files.map((file) => (0, import_node_path40.join)(workflows, file)));
     }
   }
-  const rootFiles = (0, import_node_fs31.readdirSync)(repositoryRoot);
+  const rootFiles = (0, import_node_fs34.readdirSync)(repositoryRoot);
   return {
     isGitRepo,
     dirty,
@@ -8537,7 +8915,7 @@ function inspectRepository(repositoryRoot) {
     tagCount: tags.length,
     strandedTags: isGitRepo ? locateStrandedReleaseTags(repositoryRoot, nxJson.release?.releaseTag?.pattern) : [],
     ci,
-    pipelineUsesMnci: pipelines.some((file) => /\bmnci ci\b/.test((0, import_node_fs31.readFileSync)(file, "utf8"))),
+    pipelineUsesMnci: pipelines.some((file) => /\bmnci ci\b/.test((0, import_node_fs34.readFileSync)(file, "utf8"))),
     retiredTooling: [.../* @__PURE__ */ new Set([...rootFiles.filter((file) => RETIRED_FILE_PATTERN.test(file) || file === ".verdaccio"), ...retiredNamesIn(manifest)])],
     personalFiles: PERSONAL_FILES.filter((file) => rootFiles.includes(file))
   };
@@ -8567,7 +8945,7 @@ function judgeAdoption(facts) {
     warning("nx.json already carries an mnci block, so this is an mnci workspace", "use `mnci upgrade`; adopt is for repositories mnci has not touched");
   }
   if (facts.nxVersion === void 0) {
-    warning("Nx is not installed", "the toolchain step installs the Nx family at the version mnci supports (#380)");
+    warning("Nx is not installed", "set Nx up first (`npx nx@latest init`); adopt does not install it yet, and the toolchain and overlay steps need an nx.json");
   }
   if (facts.strandedTags.length > 0) {
     warning(
@@ -8594,6 +8972,18 @@ function reportAdoption(repositoryRoot) {
 }
 function runAdopt(repositoryRoot, options = {}) {
   const report = reportAdoption(repositoryRoot);
+  if (options.overlay === true) {
+    runOverlay(repositoryRoot, options);
+    return;
+  }
+  if (options.toolchain === true) {
+    runToolchain(repositoryRoot, options);
+    return;
+  }
+  if (options.tags === true) {
+    runBaselineTags(repositoryRoot, report);
+    return;
+  }
   if (!report.ready) {
     process.exitCode = 1;
   }
@@ -8618,6 +9008,69 @@ function runAdopt(repositoryRoot, options = {}) {
     logger.error("Adoption is blocked. Clear the blockers above and run the report again.");
   }
 }
+function runBaselineTags(repositoryRoot, report) {
+  if (!report.facts.isGitRepo) {
+    logger.error("This directory is not a git repository, so there are no tags to baseline.");
+    process.exitCode = 1;
+    return;
+  }
+  const { strandedTags } = report.facts;
+  if (strandedTags.length === 0) {
+    logger.success("No project has release tags stranded under an old name. Nothing to baseline.");
+    return;
+  }
+  const result = createBaselineTags(repositoryRoot, strandedTags);
+  for (const tag of result.created) {
+    logger.success(`created ${tag}`);
+  }
+  for (const tag of result.existing) {
+    logger.info(`${tag} already exists, left alone`);
+  }
+  for (const tag of result.failed) {
+    logger.error(`could not create ${tag}: its old tag does not resolve to a commit`);
+  }
+  if (result.failed.length > 0) {
+    process.exitCode = 1;
+  }
+  if (result.created.length > 0) {
+    logger.info(`Local only. Publish them when you are ready: git push origin ${result.created.map((tag) => JSON.stringify(tag)).join(" ")}`);
+    logger.info("A tag made under the new name at a LOWER version (for example @scope/x@0.0.5) stays; the baseline outranks it, and removing it from the remote is your call.");
+  }
+}
+function runToolchain(repositoryRoot, options) {
+  try {
+    const result = adoptToolchain(repositoryRoot, { nxVersion: options.nx }, { log: (message) => {
+      logger.step(message);
+    } });
+    for (const line of result.removed) {
+      logger.info(`removed ${line}`);
+    }
+    if (result.aligned.version === void 0) {
+      logger.info("Nx is not declared at the root, so there is no family to align.");
+    } else {
+      logger.info(`Nx family at ${result.aligned.version}${result.aligned.names.length > 0 ? ` (moved: ${result.aligned.names.join(", ")})` : " (already aligned)"}`);
+    }
+    if (result.auditPasses) {
+      logger.success(`The audit gate passes${result.auditFixes > 0 ? ` after ${result.auditFixes} npm audit fix pass(es)` : ""}. Review with \`git diff\` and commit package.json and package-lock.json.`);
+    } else {
+      logger.error("The audit gate still fails after npm audit fix. Run `mnci ci audit` to see what is left; a targeted overrides entry is the usual answer.");
+      process.exitCode = 1;
+    }
+  } catch (error) {
+    logger.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}
+function runOverlay(repositoryRoot, options) {
+  try {
+    adoptOverlay(repositoryRoot, options);
+    logger.info("Steps of your old pipeline that mnci does not recognise are in its slots (# mnci:slot); anything it could not carry over was listed above.");
+    logger.info("Run `mnci doctor` to confirm the verify phase is active, then review with `git diff`.");
+  } catch (error) {
+    logger.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}
 
 // src/command-catalog/command-groups.config.ts
 var COMMAND_GROUPS = {
@@ -8690,11 +9143,11 @@ function runCommands(program, options) {
 }
 
 // src/workspace-info/list-projects.use-case.ts
-var import_node_path37 = require("path");
+var import_node_path41 = require("path");
 var TYPE_TAG_PREFIX = "type:";
 function listProjects(workspaceRoot) {
   return locateProjects(workspaceRoot).map((location) => {
-    const projectJsonPath = (0, import_node_path37.join)(workspaceRoot, location.dir, "project.json");
+    const projectJsonPath = (0, import_node_path41.join)(workspaceRoot, location.dir, "project.json");
     const project = fileExists(projectJsonPath) ? readJson(projectJsonPath) : {};
     const typeTag = (project.tags ?? []).find((tag) => tag.startsWith(TYPE_TAG_PREFIX));
     return {
@@ -8707,7 +9160,7 @@ function listProjects(workspaceRoot) {
   }).toSorted((a, b) => a.dir.localeCompare(b.dir));
 }
 function runProjects(workspaceRoot, options) {
-  if (!fileExists((0, import_node_path37.join)(workspaceRoot, "nx.json"))) {
+  if (!fileExists((0, import_node_path41.join)(workspaceRoot, "nx.json"))) {
     throw new Error("No nx.json found here. Run `projects` from the workspace root.");
   }
   const projects = listProjects(workspaceRoot);
@@ -8721,11 +9174,11 @@ function runProjects(workspaceRoot, options) {
 }
 
 // src/workspace-info/read-workspace-info.use-case.ts
-var import_node_path39 = require("path");
+var import_node_path43 = require("path");
 
 // src/cli-version/check-for-update.use-case.ts
-var import_node_fs32 = require("fs");
-var import_node_path38 = require("path");
+var import_node_fs35 = require("fs");
+var import_node_path42 = require("path");
 var import_cross_spawn3 = __toESM(require("cross-spawn"));
 var PACKAGE_NAME2 = "@mnci/cli";
 var REGISTRY_TIMEOUT_MS = 2e3;
@@ -8784,8 +9237,8 @@ function releaseTriple(version) {
 }
 function readCliVersion(packageDirectory) {
   try {
-    const manifestPath = (0, import_node_path38.join)(packageDirectory, "..", "package.json");
-    const manifest = JSON.parse((0, import_node_fs32.readFileSync)(manifestPath, "utf8"));
+    const manifestPath = (0, import_node_path42.join)(packageDirectory, "..", "package.json");
+    const manifest = JSON.parse((0, import_node_fs35.readFileSync)(manifestPath, "utf8"));
     return manifest.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -8795,7 +9248,7 @@ function readCliVersion(packageDirectory) {
 // src/workspace-info/read-workspace-info.use-case.ts
 function readWorkspaceInfo(workspaceRoot, cliVersion) {
   const latest = fetchLatestVersion() ?? null;
-  const isWorkspace = fileExists((0, import_node_path39.join)(workspaceRoot, "nx.json"));
+  const isWorkspace = fileExists((0, import_node_path43.join)(workspaceRoot, "nx.json"));
   return {
     cli: {
       version: cliVersion,
@@ -8816,8 +9269,8 @@ function runInfo(workspaceRoot, cliVersion, options) {
 }
 
 // src/workspace-creation/adopt-directory.use-case.ts
-var import_node_fs33 = require("fs");
-var import_node_path40 = require("path");
+var import_node_fs36 = require("fs");
+var import_node_path44 = require("path");
 var NEVER_COPIED = /* @__PURE__ */ new Set([".git", "node_modules"]);
 var AGENT_AND_CI_ENTRIES = [
   "AGENTS.md",
@@ -8848,13 +9301,13 @@ var PREFLIGHT_BLOCKERS = [
   "packages"
 ];
 function assertAdoptableDirectory(target) {
-  if (!(0, import_node_fs33.existsSync)(target)) {
+  if (!(0, import_node_fs36.existsSync)(target)) {
     throw new Error(`--into '${target}' does not exist. Create or clone it first.`);
   }
-  if (!(0, import_node_fs33.statSync)(target).isDirectory()) {
+  if (!(0, import_node_fs36.statSync)(target).isDirectory()) {
     throw new Error(`--into '${target}' is not a directory.`);
   }
-  const blockers = PREFLIGHT_BLOCKERS.filter((entry) => (0, import_node_fs33.existsSync)((0, import_node_path40.join)(target, entry)));
+  const blockers = PREFLIGHT_BLOCKERS.filter((entry) => (0, import_node_fs36.existsSync)((0, import_node_path44.join)(target, entry)));
   if (blockers.length > 0) {
     throw new Error(
       `--into '${target}' already holds ${blockers.join(", ")}, so it is a project already. Use \`mnci upgrade\` to re-apply the overlay to an existing workspace, or point --into at an empty checkout.`
@@ -8862,15 +9315,15 @@ function assertAdoptableDirectory(target) {
   }
 }
 function mergeGitignore(generatedFile, targetFile) {
-  const existing = (0, import_node_fs33.readFileSync)(targetFile, "utf8");
+  const existing = (0, import_node_fs36.readFileSync)(targetFile, "utf8");
   const present = new Set(existing.split("\n").map((line) => line.trim()));
-  const additions = (0, import_node_fs33.readFileSync)(generatedFile, "utf8").split("\n").map((line) => line.trimEnd()).filter((line) => {
+  const additions = (0, import_node_fs36.readFileSync)(generatedFile, "utf8").split("\n").map((line) => line.trimEnd()).filter((line) => {
     const trimmed = line.trim();
     return trimmed !== "" && !trimmed.startsWith("#") && !present.has(trimmed);
   });
   if (additions.length === 0) return false;
   const separator = existing.endsWith("\n") ? "" : "\n";
-  (0, import_node_fs33.writeFileSync)(
+  (0, import_node_fs36.writeFileSync)(
     targetFile,
     `${existing}${separator}
 # Added by mnci (Nx workspace)
@@ -8880,9 +9333,9 @@ ${additions.join("\n")}
   return true;
 }
 function adoptGeneratedWorkspace(generatedRoot, target) {
-  const entries = (0, import_node_fs33.readdirSync)(generatedRoot).filter((entry) => !NEVER_COPIED.has(entry));
+  const entries = (0, import_node_fs36.readdirSync)(generatedRoot).filter((entry) => !NEVER_COPIED.has(entry));
   const collisions = entries.filter(
-    (entry) => (0, import_node_fs33.existsSync)((0, import_node_path40.join)(target, entry)) && !EXISTING_WINS.has(entry) && entry !== ".gitignore"
+    (entry) => (0, import_node_fs36.existsSync)((0, import_node_path44.join)(target, entry)) && !EXISTING_WINS.has(entry) && entry !== ".gitignore"
   );
   if (collisions.length > 0) {
     throw new Error(
@@ -8891,28 +9344,28 @@ function adoptGeneratedWorkspace(generatedRoot, target) {
   }
   const result = { copied: [], kept: [], mergedGitignore: false };
   for (const entry of entries) {
-    const from = (0, import_node_path40.join)(generatedRoot, entry);
-    const to = (0, import_node_path40.join)(target, entry);
-    if (entry === ".gitignore" && (0, import_node_fs33.existsSync)(to)) {
+    const from = (0, import_node_path44.join)(generatedRoot, entry);
+    const to = (0, import_node_path44.join)(target, entry);
+    if (entry === ".gitignore" && (0, import_node_fs36.existsSync)(to)) {
       result.mergedGitignore = mergeGitignore(from, to);
       result.kept.push(entry);
       continue;
     }
-    if ((0, import_node_fs33.existsSync)(to)) {
+    if ((0, import_node_fs36.existsSync)(to)) {
       result.kept.push(entry);
       continue;
     }
-    (0, import_node_fs33.cpSync)(from, to, { recursive: true });
+    (0, import_node_fs36.cpSync)(from, to, { recursive: true });
     result.copied.push(entry);
   }
-  (0, import_node_fs33.rmSync)(generatedRoot, { recursive: true, force: true });
+  (0, import_node_fs36.rmSync)(generatedRoot, { recursive: true, force: true });
   return result;
 }
 
 // src/workspace-creation/create-workspace.use-case.ts
-var import_node_fs34 = require("fs");
+var import_node_fs37 = require("fs");
 var import_node_os2 = require("os");
-var import_node_path41 = require("path");
+var import_node_path45 = require("path");
 function nxCloudProviderValue(ci) {
   return ci === "azure" ? "azure" : "github";
 }
@@ -8937,7 +9390,7 @@ async function resolveCi(options) {
   return await promptCi();
 }
 var REGISTRY_KINDS = /* @__PURE__ */ new Set(["azure-artifacts", "npm"]);
-async function resolveRegistry(options) {
+async function resolveRegistry2(options) {
   if (options.registry !== void 0 && !REGISTRY_KINDS.has(options.registry)) {
     throw new Error(`Invalid --registry '${options.registry}'. Valid values: azure-artifacts, npm.`);
   }
@@ -8955,12 +9408,12 @@ async function resolveRegistry(options) {
   return await promptRegistry();
 }
 async function runNew(name, options) {
-  const adoptTarget = options.into === void 0 ? void 0 : (0, import_node_path41.resolve)(process.cwd(), options.into);
+  const adoptTarget = options.into === void 0 ? void 0 : (0, import_node_path45.resolve)(process.cwd(), options.into);
   if (adoptTarget !== void 0) assertAdoptableDirectory(adoptTarget);
-  const workspaceName = name ?? (adoptTarget === void 0 ? await promptText("Workspace name") : (0, import_node_path41.basename)(adoptTarget));
+  const workspaceName = name ?? (adoptTarget === void 0 ? await promptText("Workspace name") : (0, import_node_path45.basename)(adoptTarget));
   assertValidProjectName(workspaceName, "Workspace name");
   const scope = options.scope ?? (options.yes ? `@${workspaceName}` : await promptText("npm scope for publishable packages", `@${workspaceName}`));
-  const registry = await resolveRegistry(options);
+  const registry = await resolveRegistry2(options);
   const ci = await resolveCi(options);
   const agent = options.agent ?? (options.yes ? "ubuntu-latest" : await promptText(
     "CI build agent/runner (vmImage, GitHub Actions runner label, or self-hosted pool name)",
@@ -8970,8 +9423,8 @@ async function runNew(name, options) {
   const npmAuth = resolveNpmAuth(options.npmAuth, registry, ci);
   const stack = await resolveStack(options);
   const nxCloud = options.nxCloud ?? (options.yes ? false : await promptNxCloud());
-  const stagingParent = adoptTarget === void 0 ? process.cwd() : (0, import_node_fs34.mkdtempSync)((0, import_node_path41.join)((0, import_node_os2.tmpdir)(), "mnci-new-"));
-  let workspaceRoot = (0, import_node_path41.join)(stagingParent, workspaceName);
+  const stagingParent = adoptTarget === void 0 ? process.cwd() : (0, import_node_fs37.mkdtempSync)((0, import_node_path45.join)((0, import_node_os2.tmpdir)(), "mnci-new-"));
+  let workspaceRoot = (0, import_node_path45.join)(stagingParent, workspaceName);
   try {
     logger.step(`Creating Nx workspace '${workspaceName}' (preset: ts)`);
     runNpx(
@@ -8994,7 +9447,7 @@ async function runNew(name, options) {
       workspaceRoot = adoptTarget;
     }
   } finally {
-    if (adoptTarget !== void 0) (0, import_node_fs34.rmSync)(stagingParent, { recursive: true, force: true });
+    if (adoptTarget !== void 0) (0, import_node_fs37.rmSync)(stagingParent, { recursive: true, force: true });
   }
   logger.step(
     "Applying MoNecromanCI overlay (VS Code workspace, release config, .npmrc, commitlint, pipeline, stack)"
@@ -9004,8 +9457,8 @@ async function runNew(name, options) {
     { workspaceName, scope, registry, agent, variableGroup, ci, stack, ...npmAuth && { npmAuth } },
     logger.detail
   );
-  (0, import_node_fs34.rmSync)((0, import_node_path41.join)(workspaceRoot, "node_modules"), { recursive: true, force: true });
-  (0, import_node_fs34.rmSync)((0, import_node_path41.join)(workspaceRoot, "package-lock.json"), { force: true });
+  (0, import_node_fs37.rmSync)((0, import_node_path45.join)(workspaceRoot, "node_modules"), { recursive: true, force: true });
+  (0, import_node_fs37.rmSync)((0, import_node_path45.join)(workspaceRoot, "package-lock.json"), { force: true });
   logger.step("Installing the toolchain (commitlint + husky + linting/formatting)");
   const installStatus = runShell(
     "npm",
@@ -9043,185 +9496,10 @@ function projectKindHintLines(kinds = PROJECT_KINDS) {
 }
 
 // src/workspace-creation/interactive-wizard.use-case.ts
-var import_node_path43 = require("path");
+var import_node_path46 = require("path");
 var import_prompts4 = require("@inquirer/prompts");
-
-// src/workspace-upgrade/upgrade-workspace.use-case.ts
-var import_node_fs35 = require("fs");
-var import_node_path42 = require("path");
-function resolveRegistry2(options, persisted) {
-  if (options.registry === "azure-artifacts" || options.organization && options.artifactsFeed) {
-    const persistedAzure = persisted?.kind === "azure-artifacts" ? persisted : void 0;
-    const organization = options.organization ?? persistedAzure?.organization;
-    const project = options.project ?? persistedAzure?.project;
-    const artifactsFeed = options.artifactsFeed ?? persistedAzure?.artifactsFeed;
-    if (!organization || !project || !artifactsFeed) {
-      throw new Error(
-        "Azure Artifacts registry needs --organization, --project and --artifacts-feed (none found in nx.json's persisted config either)."
-      );
-    }
-    return { kind: "azure-artifacts", organization, project, artifactsFeed };
-  }
-  if (options.registry === "npm") {
-    return { kind: "npm" };
-  }
-  if (persisted) {
-    return persisted;
-  }
-  throw new Error(
-    "No registry found in nx.json's persisted config. Pass --registry npm or --registry azure-artifacts (with --organization/--project/--artifacts-feed)."
-  );
-}
-function resolveWorkspaceName(workspaceRoot, persisted) {
-  if (persisted.workspaceName) {
-    return persisted.workspaceName;
-  }
-  try {
-    const existing = (0, import_node_fs35.readdirSync)(workspaceRoot).find(
-      (file) => file.endsWith(".code-workspace") && file !== "undefined.code-workspace"
-    );
-    if (existing) {
-      return existing.replace(/\.code-workspace$/, "");
-    }
-  } catch {
-  }
-  return (0, import_node_path42.basename)(workspaceRoot);
-}
-function detectNpmAuth(workspaceRoot) {
-  try {
-    return (0, import_node_fs35.readFileSync)((0, import_node_path42.join)(workspaceRoot, "azure-pipelines.yml"), "utf8").includes("npmAuthenticate@0") ? "build-identity" : void 0;
-  } catch {
-    return void 0;
-  }
-}
-function resolveOverlayOptions(workspaceRoot, options, persisted) {
-  const scope = options.scope ?? persisted.scope;
-  if (!scope) {
-    throw new Error("No npm scope found in nx.json's persisted config. Pass --scope explicitly.");
-  }
-  const registry = resolveRegistry2(options, persisted.registry);
-  const ci = options.ci ?? persisted.ci;
-  if (!ci) {
-    throw new Error(
-      "No CI provider found in nx.json's persisted config. Pass --ci azure|github|both explicitly."
-    );
-  }
-  const agent = options.agent ?? persisted.agent;
-  if (!agent) {
-    throw new Error(
-      "No CI build agent found in nx.json's persisted config. Pass --agent explicitly."
-    );
-  }
-  const variableGroup = options.variableGroup ?? persisted.variableGroup ?? "Build";
-  const detected = ci === "azure" && persisted.npmAuth === void 0 && options.npmAuth === void 0 ? detectNpmAuth(workspaceRoot) : void 0;
-  if (detected) {
-    logger.detail("keeping build-identity npm auth: azure-pipelines.yml already runs npmAuthenticate@0");
-  }
-  const npmAuth = resolveNpmAuth(options.npmAuth, registry, ci, persisted.npmAuth ?? detected);
-  const testRunner = options.testRunner ?? persisted.stack?.testRunner;
-  if (!testRunner) {
-    throw new Error(
-      "No testRunner found in nx.json's persisted config. Pass --test-runner explicitly."
-    );
-  }
-  return {
-    workspaceName: resolveWorkspaceName(workspaceRoot, persisted),
-    scope,
-    registry,
-    agent,
-    variableGroup,
-    ci,
-    stack: { testRunner },
-    ...npmAuth && { npmAuth }
-  };
-}
-function runUpgrade(workspaceRoot, options) {
-  if (!fileExists((0, import_node_path42.join)(workspaceRoot, "nx.json"))) {
-    throw new Error(
-      `No nx.json found in ${workspaceRoot} \u2014 this does not look like an Nx workspace. Run 'mnci upgrade' from the workspace root.`
-    );
-  }
-  const persisted = readMnciConfig(workspaceRoot);
-  const resolved = resolveOverlayOptions(workspaceRoot, options, persisted);
-  logger.step("Re-applying the MoNecromanCI overlay");
-  applyOverlay(workspaceRoot, resolved, logger.detail);
-  const repaired = repairRollupSourceMaps(workspaceRoot);
-  if (repaired.length > 0) {
-    logger.step("Enabling source maps in rollup configs (breakpoints in .ts files)");
-    for (const path of repaired) {
-      logger.detail(`updated ${path}`);
-    }
-  }
-  const repairedManifests = repairPublishableManifests(workspaceRoot);
-  if (repairedManifests.length > 0) {
-    logger.step("Repointing `types` at the real declaration file");
-    for (const path of repairedManifests) {
-      logger.detail(`updated ${path}`);
-    }
-  }
-  const lockfile = pruneStaleLocalRegistry(workspaceRoot);
-  if (lockfile.stale) {
-    logger.step("Dropping the unused local registry (verdaccio) from package-lock.json");
-    if (lockfile.status !== 0) {
-      logger.warn("npm could not re-resolve the lockfile; run `npm install --package-lock-only` once you are online.");
-    }
-  }
-  const goApps = addGoPlatformTargets(workspaceRoot);
-  if (goApps.length > 0) {
-    logger.step("Adding the six-platform build to Go apps (build-all, package-all)");
-    for (const path of goApps) {
-      logger.detail(`updated ${path}`);
-    }
-  }
-  const pinnedExtensions = pinVscodeExtensionProjectNames(workspaceRoot);
-  if (pinnedExtensions.length > 0) {
-    logger.step("Pinning the Nx project name of VS Code extensions (nx.name)");
-    for (const path of pinnedExtensions) {
-      logger.detail(`updated ${path}`);
-    }
-  }
-  if (refreshVscodeExtensionScript(workspaceRoot)) {
-    logger.step("Updating the VS Code extension packaging script");
-    logger.detail(`updated ${VSCODE_EXTENSION_SCRIPT_PATH}`);
-  }
-  if (refreshGoReleaseScript(workspaceRoot)) {
-    logger.step("Updating the releasable Go app script");
-    logger.detail(`updated ${GO_RELEASE_SCRIPT_PATH}`);
-  }
-  if (hasGoProject(workspaceRoot) && registerNxGoPlugin(workspaceRoot)) {
-    logger.step("Registering the Go plugin in nx.json, so Nx can see which Go project imports which");
-    logger.detail("updated nx.json");
-  }
-  const addedDtsPlugins = addMissingDeclarationSpecifierPlugins(workspaceRoot);
-  if (addedDtsPlugins.length > 0) {
-    logger.step("Adding the declaration-specifier plugin to rollup configs that lacked it");
-    for (const path of addedDtsPlugins) {
-      logger.detail(`updated ${path}`);
-    }
-  }
-  const upgradedDtsPlugins = upgradeDeclarationSpecifierPlugins(workspaceRoot);
-  if (upgradedDtsPlugins.length > 0) {
-    logger.step("Upgrading declaration specifiers to resolve under nodenext");
-    for (const path of upgradedDtsPlugins) {
-      logger.detail(`updated ${path}`);
-    }
-  }
-  logger.step(
-    "Formatting the workspace (eslint --fix) \u2014 the slowest step, minutes on a large workspace"
-  );
-  runFormatter(workspaceRoot);
-  const nxJson = readJson((0, import_node_path42.join)(workspaceRoot, "nx.json"));
-  const stranded = locateStrandedReleaseTags(workspaceRoot, nxJson.release?.releaseTag?.pattern);
-  for (const entry of stranded) {
-    logger.warn(`${entry.project} has release tags only under ${entry.oldTag}: nx release would restart it from its disk version. Run \`git tag ${entry.newTag} ${entry.oldTag}^{commit}\` before the next release (\`mnci doctor\` lists them all).`);
-  }
-  logger.success("Done. Review the changes with `git diff` before committing.");
-  logger.info("Run `npm install` and commit package-lock.json too: the overlay may have added or moved a dependency, and CI installs with `npm ci`, which refuses a stale lockfile.");
-}
-
-// src/workspace-creation/interactive-wizard.use-case.ts
 async function runInteractive() {
-  const inWorkspace = fileExists((0, import_node_path43.join)(process.cwd(), "nx.json"));
+  const inWorkspace = fileExists((0, import_node_path46.join)(process.cwd(), "nx.json"));
   const choiceNew = { name: "Create a new monorepo", value: "new" };
   const choiceAdd = { name: "Add a project to this workspace", value: "add" };
   const choiceUpgrade = {
@@ -9273,7 +9551,7 @@ function buildProgram(cliVersion) {
   ).option("--json", "print the findings as one JSON document, each with its remedy").action((options) => {
     runDoctor(process.cwd(), options);
   });
-  program.command("adopt").description("Read an existing repository and report what bringing it under mnci would involve: blockers, warnings and the step that clears each. Read-only; exits non-zero when something blocks").option("--json", "print the report as one JSON document").action((options) => {
+  program.command("adopt").description("Read an existing repository and report what bringing it under mnci would involve: blockers, warnings and the step that clears each. Read-only unless a step flag is given; exits non-zero when something blocks").option("--json", "print the report as one JSON document").option("--tags", "create, locally, the baseline tag each project whose release tags are stranded under an old name needs; nothing is pushed").option("--toolchain", "retire old formatter and registry tooling, align the Nx family to one version and run npm audit fix until the audit gate passes; needs a clean git tree and leaves the changes uncommitted").option("--nx <version>", "the Nx version --toolchain aligns to (default: the newest published in the major already in use)").option("--overlay", "apply the mnci overlay (release config, pipeline, npmrc, commitlint, scripts) with the flags mnci upgrade takes; the pipeline keeps the steps mnci does not recognise in its slots; needs a clean git tree and an nx.json").option("--scope <scope>", "npm scope for publishable packages (--overlay)").option("--registry <kind>", "azure-artifacts | npm (--overlay)").option("--organization <name>", "Azure DevOps organization (--overlay)").option("--project <name>", "Azure DevOps project (--overlay)").option("--artifacts-feed <name>", "Azure Artifacts feed (--overlay)").option("--agent <pool>", "CI build agent (--overlay)").option("--variable-group <name>", "Azure DevOps variable group holding the npm PAT (--overlay)").option("--npm-auth <mode>", "pat (default) | build-identity (--overlay, --ci azure only)").option("--ci <provider>", "azure | github | both (--overlay; default: what the repository already has)").option("--test-runner <runner>", "jest | vitest (--overlay; default: what the repository already declares)").action((options) => {
     runAdopt(process.cwd(), options);
   });
   program.command("ci").addArgument(new import_commander.Argument("<phase>", "which phase of the pipeline to run").choices(CI_PHASES)).description(