@mnci/cli 4.8.1 → 4.9.0

package/README.md

@@ -909,7 +909,9 @@ as `${{ secrets.PAT }}` — GitHub has no "variable group" concept, so unlike
 Azure this needs no CLI-collected name, just a secret you create once in the
 repo settings. Either way it's mapped as `env` on the npm steps and read by
 the root `.npmrc`'s `_password` block — the PAT value never lands in a file.
-No `npmAuthenticate@0` task (it would overwrite the hand-set password).
+No `npmAuthenticate@0` task in this mode (it would overwrite the hand-set password).
+For an Azure feed there is a second mode that needs no PAT at all — see
+[the alternative on Azure](#the-alternative-on-azure-build-identity-auth-no-pat-at-all).
 
 #### Why `_password` and never `_authToken` — read this before "fixing" it
 
@@ -945,18 +947,23 @@ credentials by URL prefix and walks only *up* a path, so an entry on
 
 #### The alternative on Azure: build-identity auth, no PAT at all
 
-mnci does not generate this, but it is the better setup for an Azure Artifacts feed
-in the **same organisation** as the pipeline, and it is what a real workspace uses
-today. `npmAuthenticate@0` injects the build service identity's token — which *is*
+`--npm-auth build-identity` (on `mnci new` and `mnci upgrade`) is the better setup for
+an Azure Artifacts feed in the **same organisation** as the pipeline.
+`npmAuthenticate@0` injects the build service identity's token — which *is*
 Entra-issued, so it satisfies the Bearer scheme the feed advertises — and there is no
 secret to store, encode, rotate or let expire.
 
-To switch a generated workspace over by hand:
+```bash
+mnci upgrade --npm-auth build-identity   # switch an existing workspace
+mnci upgrade --npm-auth pat              # and back
+```
+
+It changes two files together, which is the point of doing it through mnci rather than
+by hand:
 
-1. Delete the credential lines from the root `.npmrc`, keeping only the
-   `@scope:registry=` routing line. (`mnci upgrade` will rewrite them back — see the
-   caveat below.)
-2. Add this step **before** `npm ci` in `azure-pipelines.yml`:
+1. `.npmrc` keeps only the `@scope:registry=` routing line. No credentials.
+2. `azure-pipelines.yml` runs this step **before** `npm ci`, and `npm ci` no longer
+   gets a `PAT` mapping it would never read:
 
 ```yaml
 - task: npmAuthenticate@0
@@ -965,6 +972,17 @@ To switch a generated workspace over by hand:
     workingFile: .npmrc
 ```
 
+The choice is persisted in `nx.json`'s `mnci` block, so a plain `mnci upgrade` keeps it.
+A workspace that added the task by hand before this option existed needs no flag either:
+`mnci upgrade` sees `npmAuthenticate@0` in its pipeline and keeps that mode, rather than
+regenerating the pipeline without it and writing a PAT block the feed rejects. An explicit
+`--npm-auth pat` always wins over that detection. `mnci doctor` fails a workspace whose
+two halves disagree — a credential-free `.npmrc` with no task publishes nothing (installs
+still pass, so CI stays green until the release step's 401), and a PAT block *plus* the
+task appends a second credential to a file that already has one.
+
+The remaining manual step is the grant:
+
 3. Grant the build identity **Feed Publisher (Contributor)** on the feed (Artifacts →
    Feed Settings → Permissions). Which identity depends on the job authorization
    scope: `<Project> Build Service (<org>)` when scoped to the project (the default),
@@ -972,11 +990,14 @@ To switch a generated workspace over by hand:
    401 is the tell that the wrong identity is in play.
 
 Caveats, stated rather than glossed. This is **Azure-only** — GitHub Actions has no
-equivalent task, so a `--ci=github` or `--ci=both` workspace still needs the PAT.
+equivalent task, so `--ci github` and `--ci both` are **refused** with `build-identity`
+(the credential-free `.npmrc` would authenticate nowhere on the GitHub side), and so is
+public npm, which has no identity to borrow. Those workspaces keep the PAT.
 Local development then needs `npx vsts-npm-auth -config .npmrc` (Windows) or a
-hand-added credential, since developers no longer inherit one from the file.
-And `mnci upgrade` rewrites `.npmrc`, so it will restore the PAT block — `git diff`
-before committing an upgrade, which the upgrade docs already tell you to do.
+hand-added credential, since developers no longer inherit one from the file — the
+generated `.npmrc` says so in its own comments. Python and NuGet publishing are
+unchanged: they read the raw PAT from the variable group, so that group is still needed
+for a workspace that publishes either.
 
 #### Diagnosing an auth failure
 

package/dist/cli.js

@@ -303,13 +303,34 @@ var TS_COMPILER_DEPENDENCIES = {
   "@typescript/native": "npm:typescript@^7.0.2",
   "typescript": "npm:@typescript/typescript6@^6.0.2"
 };
+var NPM_AUTH_MODES = ["pat", "build-identity"];
+function resolveNpmAuth(requested, registry, ci, fallback) {
+  if (requested !== void 0 && !NPM_AUTH_MODES.includes(requested)) {
+    throw new Error(`--npm-auth must be one of: ${NPM_AUTH_MODES.join(", ")} (got '${requested}').`);
+  }
+  const mode = requested ?? fallback;
+  if (mode !== "build-identity") {
+    return mode;
+  }
+  if (registry.kind !== "azure-artifacts") {
+    throw new Error(
+      "--npm-auth build-identity needs an Azure Artifacts feed: public npm has no build identity to borrow. Use --registry azure-artifacts, or drop the flag."
+    );
+  }
+  if (ci !== "azure") {
+    throw new Error(
+      `--npm-auth build-identity needs --ci azure (this workspace is '${ci}'): it is npmAuthenticate@0, an Azure Pipelines task, and GitHub Actions has no equivalent. Use --npm-auth pat, or drop the GitHub pipeline.`
+    );
+  }
+  return mode;
+}
 function registryUrl(registry) {
   if (registry.kind === "azure-artifacts") {
     return `https://pkgs.dev.azure.com/${registry.organization}/${registry.project}/_packaging/${registry.artifactsFeed}/npm/registry/`;
   }
   return void 0;
 }
-function npmrcContent(registry, scope) {
+function npmrcContent(registry, scope, npmAuth = "pat") {
   if (registry.kind === "npm") {
     return `; Publish authentication for the public npm registry.
 ;
@@ -343,6 +364,38 @@ function npmrcContent(registry, scope) {
 `;
   }
   const feedUrl = registryUrl(registry);
+  if (npmAuth === "build-identity") {
+    return `; Publish + resolution routing for this workspace's own scope.
+;
+; '${scope}:registry' sends BOTH resolution and 'npm publish' of ${scope}/* to the
+; feed: npm prefers a scope's registry over the global one when publishing a
+; scoped package, so a ${scope}/* package cannot reach npmjs.org by accident.
+;
+; Only the scope is routed, on purpose. A global 'registry=' would send every
+; install through the feed as well, so 'npm ci' would need feed auth just to fetch
+; public packages.
+${scope}:registry=${feedUrl}
+
+; NO credentials are written here. The 'npmAuthenticate@0' task in
+; azure-pipelines.yml injects them into this file at build time, using the build
+; service identity - so there is no PAT to store, rotate or encode.
+;
+; That is forced by what the feed accepts. An unauthenticated PUT to the publish
+; endpoint answers with:
+;   www-authenticate: Bearer authorization_uri=https://login.windows.net/<tenant>,
+;                     Basic realm="...", TFS-Federated
+; so its Bearer scheme wants an ENTRA ID access token, which is what the task
+; supplies. A PAT is not one: npm sends _authToken verbatim as a Bearer header, so
+; a PAT there is rejected with "Unable to authenticate, your authentication token
+; seems to be invalid". A PAT can only authenticate through the Basic scheme
+; (username + base64 _password), which is what 'mnci upgrade --npm-auth pat' writes.
+;
+; The cost is local: nothing in this file authenticates a developer's machine, so
+; publishing or installing a private package by hand needs
+; 'npx vsts-npm-auth -config .npmrc' (Windows) or a credential you add yourself.
+; Building and testing never authenticate.
+`;
+  }
   const feedKey = feedUrl.replace(/^https:/, "");
   const feedShortKey = feedKey.replace("npm/registry/", "npm/");
   return `; Publish + resolution routing for this workspace's own scope.
@@ -440,8 +493,26 @@ function withPythonGraphPlugin(nxJson, pluginInstalled) {
   }
   return { ...nxJson, plugins: [...plugins, PYTHON_GRAPH_PLUGIN] };
 }
+function isMergeableObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function preservingUnknownKeys(existing, owned) {
+  if (!isMergeableObject(existing)) {
+    return owned;
+  }
+  const merged = { ...existing };
+  for (const [key, value] of Object.entries(owned)) {
+    const previous = merged[key];
+    merged[key] = isMergeableObject(value) && isMergeableObject(previous) ? preservingUnknownKeys(previous, value) : value;
+  }
+  return merged;
+}
 function withReleaseConfig(nxJson, ci) {
-  return { ...nxJson, defaultBase: "main", release: releaseConfig(ci) };
+  return {
+    ...nxJson,
+    defaultBase: "main",
+    release: preservingUnknownKeys(nxJson.release, releaseConfig(ci))
+  };
 }
 var COMMITLINT_CONFIG = `export default { extends: ['@commitlint/config-conventional'] }
 `;
@@ -588,6 +659,8 @@ var ESLINT_BLOCK_INVENTORY = `// WHAT IS IN HERE. Each line is one config block,
 //   mnci/html                     @html-eslint/eslint-plugin
 //   mnci/tests                    *.spec/*.test relaxations \u2014 eslint-plugin-jest
 //                                 (Vitest's globals too; the two stacks share them)
+//   mnci/tests/mock-aware         specs in a project: eslint-plugin-jest's unbound-method,
+//                                 which knows expect(mock.method) has no this to lose
 //   mnci/nx-dependency-checks     @nx/eslint-plugin, on publishable packages' manifests
 //   mnci/standard                 JavaScript Standard Style as ESLint rules \u2014 the
 //                                 whole formatting opinion, a faithful port of
@@ -834,7 +907,10 @@ function mnciConfig(options) {
     agent: options.agent,
     variableGroup: options.variableGroup,
     ci: options.ci,
-    stack: { testRunner: options.stack.testRunner }
+    stack: { testRunner: options.stack.testRunner },
+    // Only when chosen: a workspace on the default keeps the block it always had,
+    // so an upgrade does not add a field nobody asked for.
+    ...options.npmAuth !== void 0 && { npmAuth: options.npmAuth }
   };
 }
 function readMnciConfig(workspaceRoot) {
@@ -970,9 +1046,24 @@ function npmAuthEnvVariable(registryKind, variableReference) {
 function poolBlock(agent) {
   return /^(?:ubuntu|windows|macos)-/i.test(agent) ? `  vmImage: ${agent}` : `  name: ${agent}`;
 }
-function azurePipelinesYaml(agent, variableGroup, pythonPublishUrl2, registryKind = "azure-artifacts", nugetFeedUrl2) {
+function azurePipelinesYaml(agent, variableGroup, pythonPublishUrl2, registryKind = "azure-artifacts", nugetFeedUrl2, npmAuth = "pat") {
   const onMain = "and(succeeded(), in(variables['Build.Reason'], 'IndividualCI', 'BatchedCI'), eq(variables['Build.SourceBranchName'], 'main'))";
   const [npmAuthName, npmAuthValue] = npmAuthEnvVariable(registryKind, (name) => `$(${name})`);
+  const buildIdentity = npmAuth === "build-identity" && registryKind === "azure-artifacts";
+  const npmAuthenticateStep = buildIdentity ? `  # Injects feed credentials into .npmrc using the BUILD SERVICE IDENTITY, so no
+  # PAT is stored, rotated or encoded anywhere. This is what the feed accepts: its
+  # publish endpoint advertises a Bearer scheme bound to login.windows.net, which
+  # wants an Entra ID access token, and a PAT is not one. Must run before 'npm ci'.
+  # Needs the build identity to be a Feed Publisher (Contributor) on the feed.
+  - task: npmAuthenticate@0
+    displayName: Authenticate npm against the feed (build identity, no PAT)
+    inputs:
+      workingFile: .npmrc
+
+` : "";
+  const npmCiEnv = buildIdentity ? "" : `
+    env:
+      ${npmAuthName}: ${npmAuthValue}`;
   return `name: monorepo-ci-$(Date:yyyyMMdd)$(Rev:.r)
 
 # Generated by MoNecromanCI. Deliberately thin: Nx builds, 'nx release'
@@ -1089,10 +1180,8 @@ steps:
         npm | "$(Agent.OS)"
       path: $(npm_config_cache)
 
-  - script: npm ci
-    displayName: Install dependencies
-    env:
-      ${npmAuthName}: ${npmAuthValue}
+${npmAuthenticateStep}  - script: npm ci
+    displayName: Install dependencies${npmCiEnv}
 
   # Fails ONLY on an advisory that has a published fix, at moderate or above;
   # anything upstream has not fixed is printed and passes. See NPM_AUDIT_STEP's
@@ -1754,7 +1843,10 @@ function applyOverlay(workspaceRoot, options, onProgress = () => {
   onProgress(
     `.npmrc \u2014 ${options.registry.kind === "azure-artifacts" ? "Azure Artifacts feed routing and credentials" : "public npm registry auth"}`
   );
-  writeFileEnsured((0, import_node_path2.join)(workspaceRoot, ".npmrc"), npmrcContent(options.registry, options.scope));
+  writeFileEnsured(
+    (0, import_node_path2.join)(workspaceRoot, ".npmrc"),
+    npmrcContent(options.registry, options.scope, options.npmAuth)
+  );
   onProgress("commitlint.config.mjs and .husky/commit-msg \u2014 conventional commit enforcement");
   writeFileEnsured((0, import_node_path2.join)(workspaceRoot, "commitlint.config.mjs"), COMMITLINT_CONFIG);
   const hookPath = (0, import_node_path2.join)(workspaceRoot, ".husky/commit-msg");
@@ -1797,7 +1889,14 @@ function applyOverlay(workspaceRoot, options, onProgress = () => {
     onProgress("azure-pipelines.yml \u2014 build, verify, pack and release");
     writeFileEnsured(
       (0, import_node_path2.join)(workspaceRoot, "azure-pipelines.yml"),
-      azurePipelinesYaml(options.agent, options.variableGroup, publishUrl, options.registry.kind, nugetUrl)
+      azurePipelinesYaml(
+        options.agent,
+        options.variableGroup,
+        publishUrl,
+        options.registry.kind,
+        nugetUrl,
+        options.npmAuth
+      )
     );
   }
   if (options.ci === "github" || options.ci === "both") {
@@ -4750,6 +4849,37 @@ function checkNpmrcCredentialResolves(workspaceRoot, environment = process.env)
     remedy: "nothing, for installing or building \u2014 this only affects authenticated commands. To publish or deprecate by hand, run it from outside this workspace, or export a real token first. If it still fails there, `npm whoami` \u2014 an expired token gives the same 404"
   };
 }
+function checkNpmAuthMatchesPipeline(workspaceRoot, registry) {
+  const npmrcPath = (0, import_node_path19.join)(workspaceRoot, ".npmrc");
+  const pipelinePath = (0, import_node_path19.join)(workspaceRoot, "azure-pipelines.yml");
+  if (registry?.kind !== "azure-artifacts" || !fileExists(npmrcPath) || !fileExists(pipelinePath)) {
+    return void 0;
+  }
+  const holdsCredentials = (0, import_node_fs12.readFileSync)(npmrcPath, "utf8").split("\n").filter((line) => !line.trimStart().startsWith(";") && !line.trimStart().startsWith("#")).some((line) => /(?:_authToken|_password|_auth)\s*=/u.test(line));
+  const runsTask = (0, import_node_fs12.readFileSync)(pipelinePath, "utf8").includes("npmAuthenticate@0");
+  if (!holdsCredentials && !runsTask) {
+    return {
+      check: "npm auth: .npmrc and azure-pipelines.yml agree",
+      ok: false,
+      detail: ".npmrc carries no credentials and azure-pipelines.yml does not run npmAuthenticate@0, so nothing authenticates the feed \u2014 installs still pass, and the release step fails with a 401",
+      remedy: "run `mnci upgrade --npm-auth build-identity` to add the task, or `mnci upgrade --npm-auth pat` to write the PAT block back"
+    };
+  }
+  if (holdsCredentials && runsTask) {
+    return {
+      check: "npm auth: .npmrc and azure-pipelines.yml agree",
+      ok: false,
+      detail: ".npmrc holds a credential block AND azure-pipelines.yml runs npmAuthenticate@0, which appends a second credential to a file that already has one",
+      remedy: "run `mnci upgrade --npm-auth build-identity` to drop the PAT block, or `mnci upgrade --npm-auth pat` to drop the task"
+    };
+  }
+  return {
+    check: "npm auth: .npmrc and azure-pipelines.yml agree",
+    ok: true,
+    detail: "",
+    remedy: ""
+  };
+}
 var NPM_TOKEN_PREFIX = "npm_";
 var LEGACY_NPM_TOKEN = /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu;
 function npmjsCredentialShape(credentials, environment) {
@@ -4954,6 +5084,7 @@ function collectFindings(workspaceRoot) {
     checkResolvedEslint(workspaceRoot),
     checkNpmrc(workspaceRoot, nxJson.mnci?.registry, nxJson.mnci?.scope),
     checkNpmrcCredentialResolves(workspaceRoot),
+    checkNpmAuthMatchesPipeline(workspaceRoot, nxJson.mnci?.registry),
     checkNoRootRuntimeDependencies(workspaceRoot),
     ...checkRollupSourceMaps(workspaceRoot),
     ...checkDeclarationSpecifiers(workspaceRoot),
@@ -5110,6 +5241,7 @@ async function runNew(name, options) {
     "ubuntu-latest"
   ));
   const variableGroup = ci === "github" ? options.variableGroup ?? "Build" : options.variableGroup ?? (options.yes ? "Build" : await promptText("Azure DevOps variable group holding the npm PAT", "Build"));
+  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_fs14.mkdtempSync)((0, import_node_path21.join)((0, import_node_os.tmpdir)(), "mnci-new-"));
@@ -5140,7 +5272,7 @@ async function runNew(name, options) {
   );
   applyOverlay(
     workspaceRoot,
-    { workspaceName, scope, registry, agent, variableGroup, ci, stack },
+    { workspaceName, scope, registry, agent, variableGroup, ci, stack, ...npmAuth && { npmAuth } },
     logger.detail
   );
   (0, import_node_fs14.rmSync)((0, import_node_path21.join)(workspaceRoot, "node_modules"), { recursive: true, force: true });
@@ -5218,6 +5350,13 @@ function resolveWorkspaceName(workspaceRoot, persisted) {
   }
   return (0, import_node_path22.basename)(workspaceRoot);
 }
+function detectNpmAuth(workspaceRoot) {
+  try {
+    return (0, import_node_fs15.readFileSync)((0, import_node_path22.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) {
@@ -5237,6 +5376,11 @@ function resolveOverlayOptions(workspaceRoot, options, persisted) {
     );
   }
   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(
@@ -5250,7 +5394,8 @@ function resolveOverlayOptions(workspaceRoot, options, persisted) {
     agent,
     variableGroup,
     ci,
-    stack: { testRunner }
+    stack: { testRunner },
+    ...npmAuth && { npmAuth }
   };
 }
 function runUpgrade(workspaceRoot, options) {
@@ -5386,7 +5531,10 @@ function buildProgram(cliVersion) {
   program.command("new").argument("[name]", "workspace name").description("Create a new monorepo (Nx TS preset + release/pipeline overlay)").option("-y, --yes", "accept defaults for anything not passed as a flag").option("--scope <scope>", "npm scope for publishable packages (e.g. @demo)").option("--registry <kind>", "azure-artifacts | npm").option("--organization <name>", "Azure DevOps organization").option("--project <name>", "Azure DevOps project").option("--artifacts-feed <name>", "Azure Artifacts feed").option(
     "--agent <pool>",
     "CI build agent: a vmImage (e.g. ubuntu-latest) or self-hosted pool name"
-  ).option("--variable-group <name>", "Azure DevOps variable group holding the npm PAT").option("--ci <provider>", "CI provider: azure | github | both").option("--test-runner <runner>", "unit-test runner: jest | vitest").option("--nx-cloud", "connect the workspace to Nx Cloud (remote caching + CI insights)").option(
+  ).option("--variable-group <name>", "Azure DevOps variable group holding the npm PAT").option(
+    "--npm-auth <mode>",
+    "how npm authenticates to an Azure Artifacts feed: pat (default) | build-identity (npmAuthenticate@0, no PAT; --ci azure only)"
+  ).option("--ci <provider>", "CI provider: azure | github | both").option("--test-runner <runner>", "unit-test runner: jest | vitest").option("--nx-cloud", "connect the workspace to Nx Cloud (remote caching + CI insights)").option(
     "--into <dir>",
     "bootstrap into an existing directory (a fresh clone holding only .git); the directory name is the workspace name unless one is given"
   ).action(async (name, options) => {
@@ -5394,7 +5542,10 @@ function buildProgram(cliVersion) {
   });
   program.command("upgrade").description(
     "Re-apply the latest MoNecromanCI overlay to this workspace (release config, pipeline, npmrc, commitlint, husky hook, curated scripts)"
-  ).option("--scope <scope>", "npm scope for publishable packages (overrides the persisted value)").option("--registry <kind>", "azure-artifacts | npm (overrides the persisted value)").option("--organization <name>", "Azure DevOps organization").option("--project <name>", "Azure DevOps project").option("--artifacts-feed <name>", "Azure Artifacts feed").option("--agent <pool>", "CI build agent (overrides the persisted value)").option("--variable-group <name>", "Azure DevOps variable group holding the npm PAT").option("--ci <provider>", "CI provider: azure | github | both (overrides the persisted value)").option(
+  ).option("--scope <scope>", "npm scope for publishable packages (overrides the persisted value)").option("--registry <kind>", "azure-artifacts | npm (overrides the persisted value)").option("--organization <name>", "Azure DevOps organization").option("--project <name>", "Azure DevOps project").option("--artifacts-feed <name>", "Azure Artifacts feed").option("--agent <pool>", "CI build agent (overrides the persisted value)").option("--variable-group <name>", "Azure DevOps variable group holding the npm PAT").option(
+    "--npm-auth <mode>",
+    "how npm authenticates to an Azure Artifacts feed: pat (default) | build-identity (npmAuthenticate@0, no PAT; --ci azure only)"
+  ).option("--ci <provider>", "CI provider: azure | github | both (overrides the persisted value)").option(
     "--test-runner <runner>",
     "unit-test runner: jest | vitest (overrides the persisted value)"
   ).action((options) => {