@mnci/cli 1.14.0 → 1.15.1

package/README.md

@@ -24,7 +24,7 @@ first-party (or established community) Nx equivalent:
 | Hand-written Azure Function templates      | `@nx/node:application` (plain Node app) + a thin Azure Functions v4 overlay   |
 | doctor/drift sync of tool-owned files      | Nothing to drift: this CLI owns 5 small files, Nx owns the rest               |
 
-## Commands (deliberately just three)
+## Commands (deliberately just four)
 
 ```sh
 mnci new my-repo            # create a monorepo (prompts scope + registry)
@@ -61,8 +61,30 @@ mnci add flutter-internal-lib core # private shared package -> libs/
 
 mnci upgrade                  # re-apply the latest overlay (see below)
 mnci upgrade --agent windows-latest   # ...with an explicit override
+
+mnci doctor                   # check this workspace's invariants (read-only)
 ```
 
+## `mnci doctor`: checking the invariants actually hold
+
+Read-only — it never edits the workspace. Every failing finding names the command
+that fixes it (usually `mnci upgrade`), and it exits non-zero when anything failed,
+so it works as a CI step as well as a local command.
+
+Every check corresponds to an invariant that has **actually** been violated, in
+this repo or in a workspace it generated. None are hypothetical; a check nobody has
+ever needed is noise that trains people to ignore the output.
+
+| Check                                                   | The failure it catches                                                                                                             |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Exactly one root ESLint config, and no per-project ones | The config fragmenting — every `@nx/*` generator writes one, so each project ends up linting against whichever config sits nearest |
+| No stray `.prettierrc`                                  | It outranks `.prettierrc.json`, so the whole formatting opinion is silently discarded while both files look fine                   |
+| `@nx/eslint/plugin` registered in `nx.json`             | Without it `npm run lint` exits 0 while linting nothing                                                                            |
+| The **resolved** `eslint` major                         | A declared range and an installed version are different things — manifests once said `^10` while the pin said 9                    |
+| `.npmrc` matches the recorded registry                  | The two registry kinds get different files; an Azure workspace also needs its scope routed                                         |
+| `versionActions` on publishable Dart/Python packages    | Its absence aborts `nx release` for the **whole** workspace, not just that project                                                 |
+| `nx sync:check`                                         | A stale TypeScript project reference that was never committed                                                                      |
+
 Everything else is plain Nx, surfaced as a small curated set of root scripts —
 each a single cross-platform command:
 
@@ -343,8 +365,12 @@ default `azure`): `azure` writes `azure-pipelines.yml`, `github` writes
 GitHub-hosted repo, or `both` while migrating between the two. Whichever
 provider(s), the pipeline does the **exact same thing**: both files are built
 from the same shared guard scripts (`overlay.ts`'s `PYTHON_INSTALL_GUARD`,
-`PACK_APPS_GUARD`, `releaseGuard`), so they can never drift on what CI
-actually runs — only the provider's own syntax differs.
+`PACK_APPS_GUARD`, `releaseGuard`, `AFFECTED_OR_ALL_GUARD`), so they can never
+drift on what CI actually runs — only the provider's own syntax differs. That
+matters most for the last of those: the two providers detect a pull request
+through different environment variables, so the guard reads both, and a
+provider-specific copy would change _what CI verifies_ rather than merely how it
+is spelled.
 
 The pipeline contains **no bash and no PowerShell**: every step is a built-in
 task/action or a single-line `git`/`npm`/`npx`/`node` command that `cmd.exe`
@@ -372,8 +398,29 @@ vulnerable transitive package) is exactly what this monorepo's own
 attempts automatically.
 
 Then `nx sync:check` (fails fast and clearly if the workspace wasn't
-synced+committed locally — see above), then one `nx run-many -t
-lint,test,build`. Pushes to `main` then:
+synced+committed locally — see above), then `npm run format:check`, then **one
+verify step** running `lint,typecheck,test,build`. `typecheck` is in that list
+because a bundler-built project strips types without reading them, so `build`
+passing proves nothing about type correctness.
+
+That step verifies the **affected** projects on a pull request and **every**
+project on anything else — including a push to `main`, so a release is always
+verified in full. There is deliberately no separate `npm run lint` step: that is
+`nx run-many -t lint`, a strict subset of the list above, and on an
+affected-scoped PR it would re-lint every project and throw the benefit away.
+`format:check` does stay workspace-wide, because `prettier --check .` is one
+invocation over the whole tree rather than a per-project target, so there is
+nothing to narrow.
+
+Every fallback in that step verifies **everything**: no PR target branch, an
+unresolvable merge-base (shallow clone, absent remote branch), any non-PR run.
+That direction is deliberate — resolving the base too wide costs a few minutes,
+while resolving it too narrow means CI runs almost nothing, reports green and has
+verified nothing. The base is a `git merge-base`, not either provider's "base SHA"
+field and not the GitHub-only `nrwl/nx-set-shas`, so one mechanism serves both
+providers and is correct in each by construction.
+
+Pushes to `main` then:
 
 - **Pack all apps** — each app's `package` target zips its build output into
   `dist/drop/<type>-<name>.zip` (e.g. `node-function-app-api.zip`,

package/dist/cli.js

@@ -1234,11 +1234,8 @@ function readWorkspaceStack(workspaceRoot) {
   };
 }
 
-// src/commands/interactive.ts
-var import_node_path14 = require("path");
-var import_prompts8 = require("@inquirer/prompts");
-
-// src/commands/new.ts
+// src/commands/doctor.ts
+var import_node_fs7 = require("fs");
 var import_node_path12 = require("path");
 
 // src/overlay.ts
@@ -1509,6 +1506,8 @@ var FLUTTER_TOOL_PATH_AZURE = `node -e "${FLUTTER_TOOL_PATH_PRELUDE}console.log(
 var FLUTTER_TOOL_PATH_GITHUB = `node -e "${FLUTTER_TOOL_PATH_PRELUDE}if(!process.env.GITHUB_PATH){console.log('Not running in GitHub Actions - skipping.');process.exit(0)}fs.appendFileSync(process.env.GITHUB_PATH,bin+${String.raw`'\n'`})"`;
 var FLUTTER_PUB_GET_GUARD = `node -e "const fs=require('node:fs');if(!fs.existsSync('pubspec.yaml')){console.log('No Flutter projects - skipping.');process.exit(0)}process.exit(require('node:child_process').spawnSync('flutter',['pub','get'],{stdio:'inherit',shell:process.platform==='win32'}).status ?? 1)"`;
 var NPM_AUDIT_STEP = "npm audit --audit-level=high || echo npm audit found vulnerabilities, see log above - non-blocking, run npm audit locally to inspect";
+var VERIFY_TARGETS = "lint,typecheck,test,build";
+var AFFECTED_OR_ALL_GUARD = `node -e "const cp=require('node:child_process');const T='${VERIFY_TARGETS}';const all=()=>process.exit(cp.spawnSync('npx nx run-many -t '+T,{stdio:'inherit',shell:true}).status ?? 1);const ref=process.env.GITHUB_BASE_REF||process.env.SYSTEM_PULLREQUEST_TARGETBRANCH||'';if(!ref){console.log('Not a pull request - verifying EVERY project.');all()}const target=ref.replace('refs/heads/','');const mergeBase=r=>{const o=cp.spawnSync('git',['merge-base',r,'HEAD'],{encoding:'utf8'});return o.status===0?o.stdout.trim():''};let base=mergeBase('origin/'+target);if(!base){console.log('No origin/'+target+' ref - fetching it to resolve a merge-base.');cp.spawnSync('git',['fetch','--no-tags','origin',target],{stdio:'inherit'});base=mergeBase('FETCH_HEAD')}if(!base){console.log('Could not resolve a merge-base with '+target+' - verifying EVERY project.');all()}console.log('Pull request against '+target+' - verifying projects affected since '+base);process.exit(cp.spawnSync('npx nx affected -t '+T+' --base='+base,{stdio:'inherit',shell:true}).status ?? 1)"`;
 var PACK_APPS_GUARD = `node -e "const fs=require('node:fs');fs.mkdirSync('dist/drop',{recursive:true});if(fs.globSync('apps/*/project.json').length===0){console.log('No apps to pack - skipping.');process.exit(0)}process.exit(require('node:child_process').spawnSync('npx nx run-many -t package',{stdio:'inherit',shell:true}).status ?? 1)"`;
 function releaseGuard(pythonPublishEnv) {
   return `node -e "const fs=require('node:fs'),cp=require('node:child_process');const hasNpm=fs.globSync('packages/*/package.json').length>0;const hasPython=fs.globSync('python-packages/*/pyproject.toml').length>0;if(!hasNpm&&!hasPython){console.log('Nothing to release - skipping.');process.exit(0)}const env={...process.env};${pythonPublishEnv}process.exit(cp.spawnSync('npx nx release --yes',{stdio:'inherit',shell:true,env}).status ?? 1)"`;
@@ -1677,27 +1676,28 @@ steps:
   - script: npx nx sync:check
     displayName: Verify the workspace is synced (run 'npx nx sync' locally and commit if this fails)
 
-  # One verify for every run (PR and main). Nx cache makes unchanged test/build
-  # projects instant.
-  - script: npm run lint
-    displayName: Lint
-
   # Prettier owns ALL formatting in this workspace, so it needs a gate of its
   # own: ESLint is configured for correctness only and deliberately reports
   # nothing about formatting. Without this step the entire formatting opinion is
   # advisory, and a workspace drifts out of compliance with no signal anywhere.
+  #
+  # Stays workspace-wide even on a PR, unlike the verify step below: it is one
+  # Prettier invocation over the whole tree, not a per-project Nx target, so
+  # there is nothing to scope down and formatting is never partially checked.
   - script: npm run format:check
     displayName: Check formatting (run 'npm run format' locally to fix)
-  # \`lint\` here also runs any Nx lint targets \`npm run lint\` does not cover \u2014
-  # notably Python's ruff (every Python project owns a hand-authored \`lint\`
-  # target). The JS lint runs twice, but Nx caches the repeat instantly.
+
+  # The one verify step, and deliberately the only one: affected projects on a
+  # pull request, EVERY project on anything else (a push to main included, so a
+  # release is always verified in full). Every fallback \u2014 no target branch, an
+  # unresolvable merge-base \u2014 takes the full path, because a run that verifies
+  # too little still reports green.
   #
-  # \`typecheck\` is load-bearing and not covered by \`build\`: a bundler-built
-  # project (esbuild, swc) strips types without reading them, so a workspace can
-  # build, test and lint green while carrying real type errors. --preset=ts
-  # infers a typecheck target for every project, so this costs one target name.
-  - script: npx nx run-many -t lint,typecheck,test,build
-    displayName: Lint, typecheck, test and build everything
+  # 'npm run lint' is 'nx run-many -t lint', a strict subset of the targets
+  # below, so adding it back as its own step would only duplicate work \u2014 and on
+  # a pull request it would re-lint every project, discarding the point of this.
+  - script: ${AFFECTED_OR_ALL_GUARD}
+    displayName: Verify (affected on a PR, every project on main)
 
   # Pack every app into dist/drop/<type>-<name>.zip via each app's 'package'
   # target. Portable guard: skip cleanly when the workspace has no apps yet.
@@ -1876,29 +1876,31 @@ jobs:
       - run: npx nx sync:check
         name: Verify the workspace is synced (run 'npx nx sync' locally and commit if this fails)
 
-      # One verify for every run (PR and main). Nx cache makes unchanged
-      # test/build projects instant.
-      - run: npm run lint
-        name: Lint
-
       # Prettier owns ALL formatting in this workspace, so it needs a gate of
       # its own: ESLint is configured for correctness only and deliberately
       # reports nothing about formatting. Without this step the entire
       # formatting opinion is advisory, and a workspace drifts out of
       # compliance with no signal anywhere.
+      #
+      # Stays workspace-wide even on a PR, unlike the verify step below: it is
+      # one Prettier invocation over the whole tree, not a per-project Nx
+      # target, so there is nothing to scope down and formatting is never
+      # partially checked.
       - run: npm run format:check
         name: Check formatting (run 'npm run format' locally to fix)
-      # \`lint\` here also runs any Nx lint targets \`npm run lint\` does not cover \u2014
-      # notably Python's ruff (every Python project owns a hand-authored \`lint\`
-      # target). The JS lint runs twice, but Nx caches the repeat instantly.
+
+      # The one verify step, and deliberately the only one: affected projects on
+      # a pull request, EVERY project on anything else (a push to main included,
+      # so a release is always verified in full). Every fallback \u2014 no target
+      # branch, an unresolvable merge-base \u2014 takes the full path, because a run
+      # that verifies too little still reports green.
       #
-      # \`typecheck\` is load-bearing and not covered by \`build\`: a bundler-built
-      # project (esbuild, swc) strips types without reading them, so a workspace
-      # can build, test and lint green while carrying real type errors.
-      # --preset=ts infers a typecheck target for every project, so this costs
-      # one target name.
-      - run: npx nx run-many -t lint,typecheck,test,build
-        name: Lint, typecheck, test and build everything
+      # 'npm run lint' is 'nx run-many -t lint', a strict subset of the targets
+      # below, so adding it back as its own step would only duplicate work \u2014 and
+      # on a pull request it would re-lint every project, discarding the point
+      # of this.
+      - run: ${AFFECTED_OR_ALL_GUARD}
+        name: Verify (affected on a PR, every project on main)
 
       # Pack every app into dist/drop/<type>-<name>.zip via each app's 'package'
       # target. Portable guard: skip cleanly when the workspace has no apps yet.
@@ -2053,7 +2055,166 @@ function applyOverlay(workspaceRoot, options) {
   }
 }
 
+// src/commands/doctor.ts
+var SUPPORTED_ESLINT_MAJOR = ESLINT_VERSION.replace(/^\D*/, "").split(".")[0];
+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
+  });
+  return [
+    {
+      check: "root ESLint config",
+      ok: rootConfigs.length === 1,
+      detail: rootConfigs.length === 0 ? "no eslint.config.* at the workspace root" : `${rootConfigs.length} root configs: ${rootConfigs.join(", ")}`,
+      remedy: "run `mnci upgrade` to rewrite the root config"
+    },
+    {
+      check: "no per-project ESLint configs",
+      ok: projectConfigs.length === 0,
+      detail: `found ${projectConfigs.length}: ${projectConfigs.join(", ")}`,
+      remedy: "run `mnci upgrade`, which sweeps {apps,libs,packages}/*/eslint.config.*"
+    }
+  ];
+}
+function checkPrettierConfig(workspaceRoot) {
+  const strayExists = fileExists((0, import_node_path12.join)(workspaceRoot, ".prettierrc"));
+  return {
+    check: "Prettier config is mnci\u2019s",
+    ok: !strayExists,
+    detail: ".prettierrc exists and outranks .prettierrc.json, so mnci\u2019s config is ignored",
+    remedy: "delete .prettierrc (or run `mnci upgrade`, which deletes it)"
+  };
+}
+function checkEslintPlugin(nxJson) {
+  const plugins = nxJson.plugins ?? [];
+  const registered = plugins.some(
+    (entry) => typeof entry === "string" ? entry === "@nx/eslint/plugin" : entry.plugin === "@nx/eslint/plugin"
+  );
+  return {
+    check: "@nx/eslint/plugin registered",
+    ok: registered,
+    detail: "not in nx.json plugins \u2014 every project silently loses its lint target",
+    remedy: "run `mnci upgrade`"
+  };
+}
+function checkResolvedEslint(workspaceRoot) {
+  const manifestPath = (0, import_node_path12.join)(workspaceRoot, "node_modules/eslint/package.json");
+  if (!fileExists(manifestPath)) {
+    return void 0;
+  }
+  try {
+    const { version } = readJson(manifestPath);
+    const major = version.split(".")[0];
+    return {
+      check: `resolved eslint is ${SUPPORTED_ESLINT_MAJOR}.x`,
+      ok: major === SUPPORTED_ESLINT_MAJOR,
+      detail: `node_modules/eslint is ${version}, but this stack supports ${SUPPORTED_ESLINT_MAJOR}.x (eslint-plugin-react has no release beyond it)`,
+      remedy: `pin eslint to ${ESLINT_VERSION} in every package manifest, then reinstall`
+    };
+  } catch {
+    return void 0;
+  }
+}
+function checkNpmrc(workspaceRoot, registry, scope) {
+  const npmrcPath = (0, import_node_path12.join)(workspaceRoot, ".npmrc");
+  if (!registry || !fileExists(npmrcPath)) {
+    return void 0;
+  }
+  const npmrc = (0, import_node_fs7.readFileSync)(npmrcPath, "utf8");
+  if (registry.kind === "npm") {
+    return {
+      check: ".npmrc authenticates the public registry",
+      ok: npmrc.includes("//registry.npmjs.org/:_authToken="),
+      detail: "no npmjs.org token line \u2014 `npm publish` cannot authenticate",
+      remedy: "run `mnci upgrade`"
+    };
+  }
+  return {
+    check: ".npmrc routes the scope to the feed",
+    ok: scope !== void 0 && npmrc.includes(`${scope}:registry=`),
+    detail: `no '${scope ?? "@scope"}:registry=' line \u2014 a scoped package could publish to npmjs.org instead of the feed`,
+    remedy: "run `mnci upgrade`"
+  };
+}
+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 })
+  ];
+  return candidates.flatMap((manifest) => {
+    const projectRoot = manifest.slice(0, manifest.lastIndexOf("/"));
+    const projectJsonPath = (0, import_node_path12.join)(workspaceRoot, projectRoot, "project.json");
+    let hasOverride = false;
+    try {
+      const projectJson = readJson(projectJsonPath);
+      hasOverride = Boolean(projectJson.release?.version?.versionActions);
+    } catch {
+      hasOverride = false;
+    }
+    return [
+      {
+        check: `${projectRoot} keeps its versionActions override`,
+        ok: hasOverride,
+        detail: "missing \u2014 nx release aborts for the ENTIRE workspace, not just this project",
+        remedy: `add release.version.versionActions to ${projectRoot}/project.json`
+      }
+    ];
+  });
+}
+function checkSync(workspaceRoot) {
+  return {
+    check: "TypeScript project references synced",
+    ok: runShell("npx", ["nx", "sync:check"], workspaceRoot) === 0,
+    detail: "nx sync:check failed \u2014 a stale project reference was never committed",
+    remedy: "run `npx nx sync` and commit the result"
+  };
+}
+function collectFindings(workspaceRoot) {
+  const nxJsonPath = (0, import_node_path12.join)(workspaceRoot, "nx.json");
+  if (!fileExists(nxJsonPath)) {
+    throw new Error(
+      `No nx.json found in ${workspaceRoot} \u2014 run 'mnci doctor' from the workspace root.`
+    );
+  }
+  const nxJson = readJson(nxJsonPath);
+  return [
+    ...checkEslintConfigs(workspaceRoot),
+    checkPrettierConfig(workspaceRoot),
+    checkEslintPlugin(nxJson),
+    checkResolvedEslint(workspaceRoot),
+    checkNpmrc(workspaceRoot, nxJson.mnci?.registry, nxJson.mnci?.scope),
+    ...checkVersionActions(workspaceRoot),
+    checkSync(workspaceRoot)
+  ].filter((finding) => finding !== void 0);
+}
+function runDoctor(workspaceRoot) {
+  const findings = collectFindings(workspaceRoot);
+  const failed = findings.filter((finding) => !finding.ok);
+  for (const finding of findings) {
+    if (finding.ok) {
+      logger.success(finding.check);
+    } else {
+      logger.error(`${finding.check} \u2014 ${finding.detail ?? "failed"}`);
+      if (finding.remedy) {
+        logger.info(`    fix: ${finding.remedy}`);
+      }
+    }
+  }
+  if (failed.length === 0) {
+    logger.success(`All ${findings.length} checks passed.`);
+    return;
+  }
+  logger.error(`${failed.length} of ${findings.length} checks failed.`);
+  process.exitCode = 1;
+}
+
+// src/commands/interactive.ts
+var import_node_path15 = require("path");
+var import_prompts8 = require("@inquirer/prompts");
+
 // src/commands/new.ts
+var import_node_path13 = require("path");
 function nxCloudProviderValue(ci) {
   return ci === "azure" ? "azure" : "github";
 }
@@ -2118,7 +2279,7 @@ async function runNew(name, options) {
     ],
     process.cwd()
   );
-  const workspaceRoot = (0, import_node_path12.join)(process.cwd(), workspaceName);
+  const workspaceRoot = (0, import_node_path13.join)(process.cwd(), workspaceName);
   logger.step(
     "Applying MoNecromanCI overlay (VS Code workspace, release config, .npmrc, commitlint, pipeline, stack)"
   );
@@ -2152,8 +2313,8 @@ async function runNew(name, options) {
 }
 
 // src/commands/upgrade.ts
-var import_node_fs7 = require("fs");
-var import_node_path13 = require("path");
+var import_node_fs8 = require("fs");
+var import_node_path14 = require("path");
 function resolveRegistry2(options, persisted) {
   if (options.registry === "azure-artifacts" || options.organization && options.artifactsFeed) {
     const persistedAzure = persisted?.kind === "azure-artifacts" ? persisted : void 0;
@@ -2182,7 +2343,7 @@ function resolveWorkspaceName(workspaceRoot, persisted) {
     return persisted.workspaceName;
   }
   try {
-    const existing = (0, import_node_fs7.readdirSync)(workspaceRoot).find(
+    const existing = (0, import_node_fs8.readdirSync)(workspaceRoot).find(
       (file) => file.endsWith(".code-workspace") && file !== "undefined.code-workspace"
     );
     if (existing) {
@@ -2190,7 +2351,7 @@ function resolveWorkspaceName(workspaceRoot, persisted) {
     }
   } catch {
   }
-  return (0, import_node_path13.basename)(workspaceRoot);
+  return (0, import_node_path14.basename)(workspaceRoot);
 }
 function resolveOverlayOptions(workspaceRoot, options, persisted) {
   const scope = options.scope ?? persisted.scope;
@@ -2228,7 +2389,7 @@ function resolveOverlayOptions(workspaceRoot, options, persisted) {
   };
 }
 function runUpgrade(workspaceRoot, options) {
-  if (!fileExists((0, import_node_path13.join)(workspaceRoot, "nx.json"))) {
+  if (!fileExists((0, import_node_path14.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.`
     );
@@ -2245,7 +2406,7 @@ function runUpgrade(workspaceRoot, options) {
 
 // src/commands/interactive.ts
 async function runInteractive() {
-  const inWorkspace = fileExists((0, import_node_path14.join)(process.cwd(), "nx.json"));
+  const inWorkspace = fileExists((0, import_node_path15.join)(process.cwd(), "nx.json"));
   const newChoice = { name: "Create a new monorepo", value: "new" };
   const addChoice = { name: "Add a project to this workspace", value: "add" };
   const upgradeChoice = {
@@ -2266,8 +2427,8 @@ async function runInteractive() {
 }
 
 // src/util/versionChecker.ts
-var import_node_fs8 = require("fs");
-var import_node_path15 = require("path");
+var import_node_fs9 = require("fs");
+var import_node_path16 = require("path");
 var import_cross_spawn2 = __toESM(require("cross-spawn"));
 var PACKAGE_NAME = "@mnci/cli";
 var REGISTRY_TIMEOUT_MS = 2e3;
@@ -2323,8 +2484,8 @@ function releaseTriple(version) {
 }
 function readCliVersion(packageDirectory) {
   try {
-    const manifestPath = (0, import_node_path15.join)(packageDirectory, "..", "package.json");
-    const manifest = JSON.parse((0, import_node_fs8.readFileSync)(manifestPath, "utf8"));
+    const manifestPath = (0, import_node_path16.join)(packageDirectory, "..", "package.json");
+    const manifest = JSON.parse((0, import_node_fs9.readFileSync)(manifestPath, "utf8"));
     return manifest.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -2349,6 +2510,11 @@ function buildProgram(cliVersion) {
   ).action((options) => {
     runUpgrade(process.cwd(), options);
   });
+  program.command("doctor").description(
+    "Check this workspace against the invariants mnci maintains (one ESLint config, no stray .prettierrc, the eslint plugin registered, the resolved eslint major, .npmrc vs the recorded registry, versionActions overrides, nx sync) \u2014 read-only; exits non-zero if anything failed"
+  ).action(() => {
+    runDoctor(process.cwd());
+  });
   program.command("add").addArgument(new import_commander.Argument("[kind]", "project kind").choices(PROJECT_KINDS)).argument("[name]", "project name").description("Add a project by delegating to the matching Nx plugin generator").option("--scope <scope>", "npm scope for a publishable lib (defaults to @<workspace name>)").option(
     "--framework <framework>",
     "node-app only: express | fastify | koa | nest | none (default: none)"
@@ -2382,7 +2548,7 @@ async function main() {
   }
 }
 if (require.main === module) {
-  main();
+  void main();
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {