@mnci/cli 4.0.0 → 4.0.1

package/README.md

@@ -119,6 +119,39 @@ accordingly, `start` marked `isBackground` since it runs a process that
 doesn't exit on its own. Re-running `add` for the same project name
 overwrites its own scripts/tasks rather than duplicating them.
 
+#### Run and Debug: the `launch` section
+
+Tasks are reachable **only** through Terminal → Run Task. The **Run and Debug**
+panel reads a separate `launch` section, so a workspace with tasks alone offers
+nothing in the dropdown people actually open. Every generated workspace therefore
+also gets four launch configurations, one per verify target:
+
+| configuration | runs |
+| --- | --- |
+| `mnci: build` | `npm run build` |
+| `mnci: test` | `npm run test` |
+| `mnci: lint` | `npm run lint` |
+| `mnci: typecheck` | `npm run typecheck` |
+
+Three details are load-bearing rather than incidental:
+
+- **`type: node-terminal`, not `node`.** `nx run-many` executes every target in a
+  **child** process. A plain `node` launch attaches to the Nx parent alone, so a
+  breakpoint inside a spec never binds; `node-terminal` runs the command in VS
+  Code's JS Debug Terminal, which instruments children as they spawn. It also avoids
+  a second trap — a `node` launch defaults to `internalConsole`, which renders none
+  of Nx's progress output, so a build there looks like it has hung.
+- **They drive `npm run <script>`, never a path into `node_modules`.** The obvious
+  `program: node_modules/nx/bin/nx.js` is wrong: Nx ships its bin at
+  `dist/bin/nx.js`, and that path moves between versions. Driving the root script
+  tracks whatever it does, so a change to the scripts reaches these for free.
+- **`cwd` is `${workspaceFolder:<name>}`, scoped by folder name.** A bare
+  `${workspaceFolder}` is ambiguous the moment a second folder joins the workspace,
+  and VS Code then refuses to resolve it — breaking all four at once.
+
+Your own configurations are safe: `mnci upgrade` replaces only the entries named
+`mnci: *` and carries every other one through untouched.
+
 `:start` resolves differently per kind — an existing generator target where
 one already exists, a small `nx:run-commands` target mnci writes where none
 did:
@@ -191,6 +224,12 @@ back and carried through unchanged**. Those tasks are per-project state written
 `mnci add`, not overlay-owned, so regenerating them wholesale would wipe every
 project's build/qa/start entry on upgrade.
 
+The `launch` array is handled differently again — **merged, not carried through**.
+mnci owns the four `mnci: *` configurations and replaces them, while any
+configuration you added yourself survives. The asymmetry is deliberate: tasks are
+written by `mnci add` and the overlay has no idea which projects exist, whereas the
+launch entries are entirely overlay-authored and should track an upgrade.
+
 `upgrade` also **deletes** things, which is stronger than the overwriting it
 has always done — one more reason to run `git diff` first, as the command's own
 output tells you to:
@@ -508,6 +547,95 @@ 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).
 
+#### Why `_password` and never `_authToken` — read this before "fixing" it
+
+Basic auth here is not a legacy choice. Azure Artifacts answers an unauthenticated
+`PUT` to its npm publish endpoint with:
+
+```
+www-authenticate: Bearer authorization_uri=https://login.windows.net/<tenant>,
+                  Basic realm="...", TFS-Federated
+```
+
+`authorization_uri` pointing at `login.windows.net` means its **Bearer scheme expects
+an Entra ID access token**. A PAT is not one. npm sends `_authToken` *verbatim* as a
+Bearer header (it base64-decodes only `_password`), so a PAT placed there is rejected
+with:
+
+```
+npm publish error:
+Unable to authenticate, your authentication token seems to be invalid.
+```
+
+**A PAT can only authenticate through the Basic scheme**, which is
+`username` + base64 `_password`. That is what this file emits.
+
+The trap worth knowing: a PAT *is* accepted as a Bearer token by the Packaging REST
+API (`https://feeds.dev.azure.com/<org>/<proj>/_apis/packaging/feeds` returns 200),
+so testing there looks like proof and is not. **Measure the endpoint the code
+actually calls.** An `_authToken` change was shipped and reverted on exactly this.
+
+Both feed path forms are keyed (`…/npm/registry/` and `…/npm/`) because npm matches
+credentials by URL prefix and walks only *up* a path, so an entry on
+`/npm/registry/` is never found for a request to `/npm/`.
+
+#### 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*
+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:
+
+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`:
+
+```yaml
+- task: npmAuthenticate@0
+  displayName: Authenticate npm against the feed (build identity, no PAT)
+  inputs:
+    workingFile: .npmrc
+```
+
+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),
+   or `Project Collection Build Service (<org>)` when not. A **403** rather than a
+   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.
+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.
+
+#### Diagnosing an auth failure
+
+The error text distinguishes the two schemes, and that is the fastest signal:
+
+| message | meaning |
+| --- | --- |
+| `E401 Incorrect or missing password` | Basic auth was used and rejected — check the base64 `_password` value |
+| `Unable to authenticate, your authentication token seems to be invalid` | a token went out as Bearer and was rejected — a PAT cannot go here |
+| `E403` | the credential is valid but lacks publish rights on the feed |
+
+Two things are easy to get wrong when chasing this:
+
+- **`nx release` publishes from the workspace root, not from each project.**
+  `@nx/js`'s `runPublish` uses `cwd: context.root` and passes `packageRoot` only as
+  the directory argument, so a missing per-package `.npmrc` is never the cause.
+- **npm resolves `_authToken` before `username`/`_password` for a given registry
+  key** (`hasAuth` in `npm-registry-fetch/lib/auth.js`), and *key* precedence is
+  decided before *file* precedence. So a stale `_authToken` in a persistent build
+  agent's user-level `.npmrc` outranks the project-level `_password` and the
+  workspace's own credential never reaches the wire. Check
+  `npm config get userconfig` on the agent before blaming the secret.
+
 On Azure, two one-time grants are required (project admin): **Contribute** on
 the repo for the _Project Collection Build Service_ account (tag push), and
 **publish** rights on the feed for the PAT's owner. On GitHub, the workflow's

package/dist/cli.js

@@ -1275,6 +1275,7 @@ function npmrcContent(registry, scope) {
   }
   const feedUrl = registryUrl(registry);
   const feedKey = feedUrl.replace(/^https:/, "");
+  const feedShortKey = feedKey.replace("npm/registry/", "npm/");
   return `; Publish + resolution routing for this workspace's own scope.
 ;
 ; '${scope}:registry' sends BOTH resolution and 'npm publish' of ${scope}/* to the
@@ -1290,9 +1291,24 @@ ${scope}:registry=${feedUrl}
 ; instructions give you, which is exactly what _password expects, so it is used
 ; as-is. (twine wants the RAW token; the CI release step decodes it there.)
 ; Azure ignores the username, and npm requires an email it never uses.
+;
+; NOT _authToken, and that is measured rather than assumed. The feed answers an
+; unauthenticated PUT to the publish endpoint 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, NOT a PAT. 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
+; authenticates through the Basic scheme, which is username/_password. Note the
+; Packaging REST API DOES accept a PAT as Bearer - do not generalise from it.
+;
+; Both path forms are keyed because npm walks only UP a URL when matching.
 ${feedKey}:username=AzureArtifacts
 ${feedKey}:_password=\${PAT}
 ${feedKey}:email=npm-requires-this-and-never-uses-it
+${feedShortKey}:username=AzureArtifacts
+${feedShortKey}:_password=\${PAT}
+${feedShortKey}:email=npm-requires-this-and-never-uses-it
 `;
 }
 function releaseConfig(ci) {
@@ -1433,6 +1449,9 @@ var ESLINT_PEER_OVERRIDES = {
   // even a trade, just a version nobody had bumped yet.
   postcss: { nanoid: "^3.3.18" }
 };
+var SECURITY_OVERRIDES = {
+  "brace-expansion@4.0.0 - 5.0.8": "^5.0.9"
+};
 function eslintToolchainDependencies(nxVersion) {
   return {
     eslint: ESLINT_VERSION,
@@ -1588,7 +1607,27 @@ function vscodeSettings() {
     )
   };
 }
-function vscodeWorkspace(workspaceName, existingTasks) {
+var LAUNCH_CONFIG_PREFIX = "mnci: ";
+var LAUNCH_CONFIGURATIONS = ["build", "test", "lint", "typecheck"];
+function launchConfigurations(workspaceName) {
+  return LAUNCH_CONFIGURATIONS.map((script, index) => ({
+    type: "node-terminal",
+    request: "launch",
+    name: `${LAUNCH_CONFIG_PREFIX}${script}`,
+    command: `npm run ${script}`,
+    // Scoped by folder name rather than a bare ${workspaceFolder}: that variable is
+    // ambiguous once a second folder is added to the workspace, and VS Code then
+    // refuses to resolve it.
+    cwd: `\${workspaceFolder:${workspaceName}}`,
+    // One shared group keeps the four together in the dropdown; a per-entry group
+    // would make four groups of one. `order` holds them in verify order.
+    presentation: { group: "mnci", order: index + 1 }
+  }));
+}
+function vscodeWorkspace(workspaceName, existingTasks, existingLaunch) {
+  const userConfigurations = (existingLaunch?.configurations ?? []).filter(
+    (configuration) => !String(configuration.name ?? "").startsWith(LAUNCH_CONFIG_PREFIX)
+  );
   return JSON.stringify(
     {
       folders: [{ path: ".", name: workspaceName }],
@@ -1597,6 +1636,10 @@ function vscodeWorkspace(workspaceName, existingTasks) {
       tasks: {
         version: existingTasks?.version ?? "2.0.0",
         tasks: existingTasks?.tasks ?? []
+      },
+      launch: {
+        version: existingLaunch?.version ?? "0.2.0",
+        configurations: [...launchConfigurations(workspaceName), ...userConfigurations]
       }
     },
     null,
@@ -1720,15 +1763,40 @@ trigger:
   # reason: two concurrent 'nx release' runs would race to create the same tag.
   batch: true
   branches:
-    include: [main]
-
-# Note: cancelling a superseded PR validation run is NOT a YAML setting on Azure
-# \u2014 it lives in the branch policy ("Build validation -> automatically cancel").
-# Nothing here can express it, so it is left to whoever configures the policy
-# rather than faked with a batch setting that would only delay PR runs.
-pr:
-  branches:
-    include: [main]
+    include:
+      - main
+      # EVERY other branch too, and that breadth is a correction rather than
+      # generosity. On Azure Repos Git a YAML 'pr:' block does nothing at all
+      # (see the note below), so a CI trigger is the only pre-merge
+      # verification this file can switch on by itself. Listing main alone \u2014
+      # which is what this pipeline used to do, next to a 'pr:' block that
+      # looked like it covered the rest \u2014 means a workspace verifies NOTHING
+      # until a change has already reached the branch it was supposed to
+      # protect.
+      #
+      # Release stays gated on main (the 'condition:' on every release step
+      # below), so a topic-branch run installs, audits, syncs, formats,
+      # verifies and packs, and publishes nothing.
+      - '*'
+
+# PR validation is deliberately NOT configured here, because on Azure Repos Git
+# it CANNOT be: "For an Azure Repos Git repo, you cannot configure a PR trigger
+# in the YAML file. You need to use branch policies." A 'pr:' block here is not
+# an error \u2014 it is silently ignored, which is worse, because the file then
+# documents a gate that does not exist. (The same block IS honoured for GitHub
+# and Bitbucket repos, which is why .github/workflows/ci.yml keeps its
+# 'pull_request:' trigger.)
+#
+# To get PR validation, configure it once in the UI: Project Settings ->
+# Repositories -> <repo> -> Policies -> <branch> -> Build Validation, pointing
+# at this pipeline. That is also the only thing that sets
+# System.PullRequest.TargetBranch, which the verify step below reads to scope
+# itself to affected projects \u2014 without a policy that variable is never set and
+# the step verifies every project instead. Correct either way, just slower.
+#
+# Cancelling a superseded PR run lives in that same policy ("automatically
+# cancel"), and likewise has no YAML expression.
+pr: none
 
 pool:
 ${poolBlock(agent)}
@@ -2186,7 +2254,8 @@ function applyOverlay(workspaceRoot, options) {
   });
   const overrides = {
     ...manifest.overrides,
-    ...ESLINT_PEER_OVERRIDES
+    ...ESLINT_PEER_OVERRIDES,
+    ...SECURITY_OVERRIDES
   };
   const existingNx = manifest.nx;
   const nx = {
@@ -2226,7 +2295,7 @@ function applyOverlay(workspaceRoot, options) {
   const existing = readCodeWorkspace(codeWorkspacePath);
   writeFileEnsured(
     codeWorkspacePath,
-    vscodeWorkspace(options.workspaceName, existing?.tasks)
+    vscodeWorkspace(options.workspaceName, existing?.tasks, existing?.launch)
   );
   if (options.workspaceName !== "undefined") {
     (0, import_node_fs6.rmSync)((0, import_node_path11.join)(workspaceRoot, "undefined.code-workspace"), { force: true });
@@ -2249,11 +2318,14 @@ function applyOverlay(workspaceRoot, options) {
 
 // src/commands/doctor.ts
 var SUPPORTED_ESLINT_MAJOR = ESLINT_VERSION.replace(/^\D*/, "").split(".", 1)[0];
+function toPosix(path) {
+  return path.replaceAll("\\", "/");
+}
 function checkEslintConfigs(workspaceRoot) {
   const rootConfigs = (0, import_node_fs7.globSync)("eslint.config.{js,mjs,cjs,ts,mts,cts}", { cwd: workspaceRoot });
   const projectConfigs = (0, import_node_fs7.globSync)("{apps,libs,packages}/*/eslint.config.{js,mjs,cjs,ts,mts,cts}", {
     cwd: workspaceRoot
-  });
+  }).map((config) => toPosix(config));
   return [
     {
       check: "root ESLint config",
@@ -2348,7 +2420,7 @@ function checkVersionActions(workspaceRoot) {
   const candidates = [
     ...(0, import_node_fs7.globSync)("packages/*/pubspec.yaml", { cwd: workspaceRoot }),
     ...(0, import_node_fs7.globSync)("python-packages/*/pyproject.toml", { cwd: workspaceRoot })
-  ];
+  ].map((manifest) => toPosix(manifest));
   return candidates.flatMap((manifest) => {
     const projectRoot = manifest.slice(0, manifest.lastIndexOf("/"));
     const projectJsonPath = (0, import_node_path12.join)(workspaceRoot, projectRoot, "project.json");
@@ -2368,6 +2440,63 @@ function checkVersionActions(workspaceRoot) {
     ];
   });
 }
+var TARGET_FILE_OPTIONS = ["main", "tsConfig", "packageJson"];
+function declaredTargets(workspaceRoot, projectRoot) {
+  const sources = [];
+  for (const [file, extract] of [
+    ["project.json", (json) => json["targets"]],
+    [
+      "package.json",
+      (json) => json["nx"]?.["targets"]
+    ]
+  ]) {
+    try {
+      const targets = extract(
+        readJson((0, import_node_path12.join)(workspaceRoot, projectRoot, file))
+      );
+      if (targets && typeof targets === "object") {
+        sources.push({
+          source: `${projectRoot}/${file}`,
+          targets
+        });
+      }
+    } catch {
+    }
+  }
+  return sources;
+}
+function checkTargetFilesExist(workspaceRoot) {
+  const projectRoots = new Set(
+    [
+      ...(0, import_node_fs7.globSync)("{apps,libs,packages}/*/project.json", { cwd: workspaceRoot }),
+      ...(0, import_node_fs7.globSync)("{apps,libs,packages}/*/package.json", { cwd: workspaceRoot })
+    ].map((manifest) => toPosix(manifest).split("/").slice(0, 2).join("/"))
+  );
+  return [...projectRoots].flatMap(
+    (projectRoot) => declaredTargets(workspaceRoot, projectRoot).flatMap(
+      ({ source, targets }) => Object.entries(targets).flatMap(
+        ([targetName, target]) => checkOneTargetsFiles(workspaceRoot, source, targetName, target)
+      )
+    )
+  );
+}
+function checkOneTargetsFiles(workspaceRoot, source, targetName, target) {
+  return TARGET_FILE_OPTIONS.flatMap((option) => {
+    const value = target?.options?.[option];
+    const checkable = typeof value === "string" && !value.includes("{");
+    if (!checkable || fileExists((0, import_node_path12.join)(workspaceRoot, value))) {
+      return [];
+    }
+    return [
+      {
+        check: `${source} \u2192 ${targetName}.${option} points at a real file`,
+        ok: false,
+        detail: `${value} does not exist \u2014 the target fails as if the compiler were misconfigured`,
+        remedy: `create ${value}, or correct ${option} in ${source}`
+      }
+    ];
+  });
+}
 function checkSync(workspaceRoot) {
   return {
     check: "TypeScript project references synced",
@@ -2391,6 +2520,7 @@ function collectFindings(workspaceRoot) {
     checkResolvedEslint(workspaceRoot),
     checkNpmrc(workspaceRoot, nxJson.mnci?.registry, nxJson.mnci?.scope),
     ...checkVersionActions(workspaceRoot),
+    ...checkTargetFilesExist(workspaceRoot),
     checkSync(workspaceRoot)
   ].filter((finding) => finding !== void 0);
 }