feat(nx-npm-access): add npm-fix target — auto-remediation, not just checks

Previously the plugin only registered the read-only `npm-check` target.
Add a sibling `npm-fix` target that runs the same script with `--fix` and
applies safe, idempotent remediations:

  1. package.json patch — sets `publishConfig.access = "public"` in place
     when it is missing or wrong. Offline, no auth required.
  2. `npm access set status=public <pkg>` — only for packages already on
     npm whose remote visibility drifted to private.
  3. `npm access set mfa=<target> <pkg>` — only when `--mfa=<target>` is
     explicitly passed (e.g. `--mfa=none` before moving a package to
     OIDC trusted publishing).

Trusted publisher (OIDC) registration is deliberately NOT automated — npm
v11 still ships no CLI for it. The script keeps printing the settings
URL for manual UI work, which is the same behaviour as `npm-check`.

Every mutation is recorded in a new `fixes: string[]` field on the
structured JSON report, so a CI step can diff "what changed".

Usage:

    bunx nx run-many -t npm-fix                       # fix everywhere
    bunx nx run adt-cli:npm-fix --args="--mfa=none"   # per package

The targets now pass `forwardAllArgs: true` so ad-hoc flags (e.g.
`--mfa=...`, `--quiet`) reach the script via nx `--args=...`.

Plugin options renamed: `targetName` → `checkTargetName`, plus a new
`fixTargetName` (defaults preserve backwards-compatible target names).

Locally verified end-to-end on `@abapify/adt-locks` (the only package
still missing `publishConfig.access`): `--fix` successfully patched the
manifest; the local change was reverted from the commit since applying
the actual fix to adt-locks is a separate, intentional action the user
should run via `nx run adt-locks:npm-fix`.

Author: ThePlenkov

tools/nx-npm-access/README.md

@@ -1,27 +1,48 @@
 # @abapify/nx-npm-access
 
-Internal Nx plugin that adds an `npm-check` target to every publishable
-`packages/*` workspace package. The target verifies that a package is
-ready to be published from CI before a release is attempted.
+Internal Nx plugin that registers two targets on every publishable
+`packages/*` workspace package:
+
+- `npm-check` — read-only readiness probe (`npm view`, `npm access get`).
+- `npm-fix` — safe auto-remediation (patches `package.json`, runs
+  `npm access set status=public`, optionally `npm access set mfa=...`).
 
 ## Usage
 
 ```bash
-# Check every publishable package at once:
+# Read-only — run this as a CI gate before `nx release publish`:
 bunx nx run-many -t npm-check
 
-# Check a single package:
+# Apply safe fixes across the whole workspace (requires `npm login` or an
+# authenticated OIDC context for the `npm access set` calls):
+bunx nx run-many -t npm-fix
+
+# Target one package:
 bunx nx run adt-cli:npm-check
+bunx nx run adt-cli:npm-fix
 
-# Silence the success lines in CI, keep only problems:
-bunx nx run-many -t npm-check --parallel=8 --output-style=stream | \
-  grep -E '^(✗|  problems|__NPM_CHECK_JSON__)'
+# Extra flags are forwarded through nx:
+bunx nx run adt-cli:npm-fix --args="--mfa=none"
 ```
 
-The target exits non-zero when a package has `publishConfig.access` missing,
-when `npm view` fails unexpectedly, or when required metadata (name,
-version) is absent. **First publish** (package not yet on npm) is NOT an
-error — it is reported as `NOT on npm — first publish`.
+`npm-check` exits non-zero when a package has `publishConfig.access`
+missing, when `npm view` fails unexpectedly, or when required metadata
+(name, version) is absent. **First publish** (package not yet on npm) is
+NOT an error — it is reported as `NOT on npm — first publish`.
+
+`npm-fix` does the same checks and additionally applies:
+
+1. **package.json patch** — sets `publishConfig.access = "public"` in
+   place when missing or wrong. Safe, offline, idempotent.
+2. **`npm access set status=public <pkg>`** — only for packages already
+   on npm whose remote visibility drifted to `private`.
+3. **`npm access set mfa=<target> <pkg>`** — only when `--mfa=<target>`
+   is passed (e.g. `--mfa=none` before switching a package to OIDC
+   trusted publishing).
+
+Trusted publisher (OIDC) registration is **not automated** — npm v11
+ships no CLI for it. The script prints a ready-to-click settings URL
+instead.
 
 ## What is actually checked
 
@@ -62,13 +83,14 @@ Registered in the root `nx.json` under `plugins`:
 ```
 
 The plugin's `createNodesV2` matches `packages/*/package.json`, reads each
-manifest, skips packages with `"private": true`, and attaches an
-`npm-check` target that invokes `src/check.ts` via `bun` (same runtime
-used everywhere else in the monorepo — no separate `.mjs` build step).
+manifest, skips packages with `"private": true`, and attaches both the
+`npm-check` and `npm-fix` targets. Both invoke `src/check.ts` via `bun`
+(same runtime used everywhere else in the monorepo — no build step).
 
 Options (all optional, set via `nx.json` plugin options):
 
-| option       | default                         | purpose                                    |
-| ------------ | ------------------------------- | ------------------------------------------ |
-| `targetName` | `"npm-check"`                   | Name of the target registered per package. |
-| `registry`   | `"https://registry.npmjs.org/"` | Registry probed by the script.             |
+| option            | default                         | purpose                                          |
+| ----------------- | ------------------------------- | ------------------------------------------------ |
+| `checkTargetName` | `"npm-check"`                   | Name of the read-only target registered per pkg. |
+| `fixTargetName`   | `"npm-fix"`                     | Name of the auto-remediating target.             |
+| `registry`        | `"https://registry.npmjs.org/"` | Registry probed by the script.                   |

tools/nx-npm-access/src/check.ts

@@ -5,7 +5,7 @@
 // published from CI. Run per-package via Nx (`nx run <pkg>:npm-check`) or for
 // all publishable packages at once (`nx run-many -t npm-check`).
 //
-// Checks performed (all read-only, no network writes):
+// Checks performed (all read-only by default, no network writes):
 //   1. package.json hygiene — name, version, publishConfig.access, exports.
 //   2. Does the package exist on npm? (new packages report "first publish").
 //   3. `npm access get status` — current public/private visibility on npm.
@@ -15,6 +15,17 @@
 //      the OIDC trusted publisher for this package can be verified. npm has
 //      no stable CLI for listing trusted publishers yet (as of npm 11).
 //
+// With `--fix` the script also applies safe remediations:
+//   - patches `publishConfig.access = "public"` into package.json if missing;
+//   - runs `npm access set status=public <pkg>` on published packages whose
+//     remote visibility drifted to `private`;
+//   - runs `npm access set mfa=none <pkg>` (only if `--mfa=none` is passed)
+//     — required for OIDC trusted publishing without interactive 2FA.
+// Every mutation is logged to the structured report under `fixes`.
+//
+// Trusted publisher registration (OIDC) still has no CLI, so the script only
+// prints the UI link — it does NOT try to automate that step.
+//
 // The script exits with code 0 when the package is "ready to publish from
 // CI", 1 otherwise. Errors are printed to stderr; the structured report is
 // emitted to stdout as a single JSON line, prefixed with a human summary.
@@ -23,7 +34,7 @@
 // `@abapify:registry=https://npm.pkg.github.com/`, the script passes
 // `--<scope>:registry=<registry>` on every npm invocation.
 
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
@@ -49,7 +60,9 @@ interface Report {
   access: string | null;
   registry: string;
   scope: string | null;
+  mode: 'check' | 'fix';
   checks: Record<string, unknown>;
+  fixes: string[];
   readyForCi: boolean;
   problems: string[];
 }
@@ -59,8 +72,14 @@ const getFlag = (name: string, def: string): string => {
   const hit = args.find((a) => a.startsWith(`--${name}=`));
   return hit ? hit.slice(name.length + 3) : def;
 };
+const hasFlag = (name: string): boolean => args.includes(`--${name}`);
+
 const registry = getFlag('registry', 'https://registry.npmjs.org/');
-const quiet = args.includes('--quiet');
+const quiet = hasFlag('quiet');
+const fix = hasFlag('fix');
+// Optional MFA setting applied only in fix mode. Useful before switching to
+// OIDC trusted publishing (`--mfa=none`). Omit to leave MFA untouched.
+const mfaTarget = getFlag('mfa', '');
 
 const pkgPath = join(process.cwd(), 'package.json');
 if (!existsSync(pkgPath)) {
@@ -126,20 +145,38 @@ const report: Report = {
   access: pkg.publishConfig?.access ?? null,
   registry,
   scope,
+  mode: fix ? 'fix' : 'check',
   checks: {},
+  fixes: [],
   readyForCi: false,
   problems: [],
 };
 
-// 1. package.json hygiene
+// 1. package.json hygiene — and patch in --fix mode.
 if (!name) report.problems.push('package.json: missing "name"');
 if (!pkg.version) report.problems.push('package.json: missing "version"');
-if (!pkg.publishConfig || pkg.publishConfig.access !== 'public') {
-  report.problems.push(
-    'package.json: publishConfig.access should be "public" (scoped packages default to restricted on npm; CI publishes would 402 Payment Required)',
-  );
+
+const needsPublishConfigFix =
+  !pkg.publishConfig || pkg.publishConfig.access !== 'public';
+if (needsPublishConfigFix) {
+  if (fix) {
+    const patched: Pkg = {
+      ...pkg,
+      publishConfig: { ...(pkg.publishConfig ?? {}), access: 'public' },
+    };
+    // Preserve trailing newline + 2-space indent to match the rest of the
+    // monorepo's package.json style (Prettier will normalise anyway).
+    writeFileSync(pkgPath, JSON.stringify(patched, null, 2) + '\n', 'utf-8');
+    report.fixes.push('package.json: set publishConfig.access = "public"');
+    report.access = 'public';
+  } else {
+    report.problems.push(
+      'package.json: publishConfig.access should be "public" (scoped packages default to restricted on npm; CI publishes would 402 Payment Required) — re-run with `--fix` to patch',
+    );
+  }
 }
 if (pkg.files === undefined) {
+  // Not auto-fixable: the correct files list is package-specific.
   report.problems.push(
     'package.json: "files" not declared — publish will include everything (incl. node_modules, dist build artefacts, tests). Add a narrow allowlist (e.g. ["dist", "README.md"]).',
   );
@@ -188,6 +225,41 @@ if (report.checks.exists === true && name) {
   } else {
     report.checks.collaborators = `ERR: ${collabs.stderr.split('\n')[0] ?? collabs.code}`;
   }
+
+  // --fix: flip visibility to public if npm reports it as private.
+  if (fix) {
+    const currentStatus =
+      typeof report.checks.accessStatus === 'object' &&
+      report.checks.accessStatus !== null
+        ? (report.checks.accessStatus as Record<string, string>)[name]
+        : typeof report.checks.accessStatus === 'string'
+          ? report.checks.accessStatus
+          : undefined;
+    if (currentStatus && currentStatus !== 'public') {
+      const setPub = npm(['access', 'set', 'status=public', name]);
+      if (setPub.code === 0) {
+        report.fixes.push(`npm access set status=public ${name}`);
+        report.checks.accessStatus = 'public';
+      } else {
+        report.problems.push(
+          `npm access set status=public failed: ${setPub.stderr.split('\n')[0] ?? 'no stderr'} — needs login (\`npm login\`) or OIDC env`,
+        );
+      }
+    }
+
+    // Optional: align MFA policy (e.g. `--mfa=none` for OIDC trusted pub).
+    if (mfaTarget) {
+      const setMfa = npm(['access', 'set', `mfa=${mfaTarget}`, name]);
+      if (setMfa.code === 0) {
+        report.fixes.push(`npm access set mfa=${mfaTarget} ${name}`);
+        report.checks.mfa = mfaTarget;
+      } else {
+        report.problems.push(
+          `npm access set mfa=${mfaTarget} failed: ${setMfa.stderr.split('\n')[0] ?? 'no stderr'}`,
+        );
+      }
+    }
+  }
 }
 
 // 5. trusted publisher hint (npm has no stable CLI for listing these yet)
@@ -215,13 +287,18 @@ const existsTag =
     : report.checks.exists === false
       ? 'NOT on npm — first publish'
       : 'npm state unknown';
+const fixesSummary =
+  report.fixes.length > 0
+    ? `\n  fixes applied:\n    + ${report.fixes.join('\n    + ')}`
+    : '';
 const problemsSummary =
   report.problems.length > 0
     ? `\n  problems:\n    - ${report.problems.join('\n    - ')}`
     : '';
 
+const modeTag = fix ? ' [fix]' : '';
 console.log(
-  `${symbol} ${name}@${pkg.version} (${existsTag})${problemsSummary}`,
+  `${symbol} ${name}@${pkg.version}${modeTag} (${existsTag})${fixesSummary}${problemsSummary}`,
 );
 // Structured line for aggregation:
 console.log(`__NPM_CHECK_JSON__ ${JSON.stringify(report)}`);

tools/nx-npm-access/src/plugin.ts

@@ -4,10 +4,18 @@ import { existsSync, readFileSync } from 'node:fs';
 
 interface NxNpmAccessOptions {
   /**
-   * Target name registered on each publishable package.
+   * Target name registered on each publishable package for the read-only
+   * readiness check.
    * @default "npm-check"
    */
-  targetName?: string;
+  checkTargetName?: string;
+  /**
+   * Target name registered on each publishable package for the
+   * auto-remediating fix (patches `publishConfig.access` locally and runs
+   * `npm access set` remotely).
+   * @default "npm-fix"
+   */
+  fixTargetName?: string;
   /**
    * npm registry used for access probes. Defaults to the public registry.
    * The script also overrides scope-level registry pins via
@@ -47,10 +55,13 @@ function shouldSkipPath(projectRoot: string): boolean {
 export const createNodesV2: CreateNodesV2<NxNpmAccessOptions> = [
   '**/package.json',
   (configFiles, options = {}) => {
-    const targetName = options.targetName ?? 'npm-check';
+    const checkTargetName = options.checkTargetName ?? 'npm-check';
+    const fixTargetName = options.fixTargetName ?? 'npm-fix';
     const registry = options.registry ?? 'https://registry.npmjs.org/';
 
     const scriptPath = join(__dirname, 'check.ts');
+    const scriptArg = JSON.stringify(scriptPath);
+    const baseCmd = `bun ${scriptArg} --registry=${registry}`;
 
     return configFiles
       .map((configFile) => {
@@ -83,27 +94,30 @@ export const createNodesV2: CreateNodesV2<NxNpmAccessOptions> = [
           return null;
         }
 
-        log(`register ${targetName} for ${pkg.name}`);
+        log(`register ${checkTargetName} + ${fixTargetName} for ${pkg.name}`);
 
-        const target = {
+        // Shared shape: cwd + no arg forwarding, no cache (network-dependent).
+        const makeTarget = (extraArg: string | null) => ({
           executor: 'nx:run-commands' as const,
           options: {
-            command: `bun ${JSON.stringify(scriptPath)} --registry=${registry}`,
+            command: extraArg ? `${baseCmd} ${extraArg}` : baseCmd,
             cwd: projectRoot,
-            // Prevents nx from swallowing stderr from npm.
-            forwardAllArgs: false,
+            // Prevents nx from swallowing stderr from npm, and lets the user
+            // pass extra flags (e.g. `--args="--mfa=none"`) through nx.
+            forwardAllArgs: true,
           },
           cache: false,
           inputs: [`{projectRoot}/package.json`],
-        };
+        });
 
         return [
           configFile,
           {
             projects: {
               [projectRoot]: {
                 targets: {
-                  [targetName]: target,
+                  [checkTargetName]: makeTarget(null),
+                  [fixTargetName]: makeTarget('--fix'),
                 },
               },
             },