@mnci/cli 1.14.0 → 1.15.0

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:
 

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
@@ -2053,7 +2050,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 +2274,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 +2308,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 +2338,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 +2346,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 +2384,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 +2401,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 +2422,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 +2479,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 +2505,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)"