release-doctor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fernforge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# release-doctor
+
+Your `npm publish` job in CI is about to fail — or already did — and the error is a terse `E401`/`E403`. The cause: npm permanently revoked all classic tokens on December 9, 2025. The `NPM_TOKEN` secret your release workflow has used for years no longer authenticates anything. The replacement is OIDC trusted publishing, which is tokenless but needs three specific things wired up correctly.
+
+`release-doctor` reads your workflows and manifests and tells you exactly which of those three you're missing, with the diff to fix each one.
+
+```
+npx release-doctor
+```
+
+No install, no flags. Run it in a repo. It's read-only: it never touches the network, your secrets, or your files. It only reads `.github/workflows/*`, `package.json`, and `pyproject.toml`.
+
+## What it catches
+
+```
+✗ ERROR .github/workflows/publish.yml  No `id-token: write` permission. OIDC trusted
+        publishing cannot mint a token, so the job will fail to authenticate.
+            permissions:
+              id-token: write
+              contents: read
+
+✗ ERROR .github/workflows/publish.yml  Uses a classic NPM_TOKEN / NODE_AUTH_TOKEN.
+        npm revoked classic tokens on 2025-12-09; this auth path is dead.
+            # delete:  env: { NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} }
+            - run: npm publish   # OIDC supplies auth, no token needed
+
+! WARN  .github/workflows/publish.yml  No `--provenance` flag. Without it your package
+        shows no verified build origin on npm.
+            - run: npm publish --provenance --access public
+```
+
+The full check list:
+
+- **npm** — missing `id-token: write`, a still-present `NPM_TOKEN`/`NODE_AUTH_TOKEN` (the dead path), and missing provenance. Plus the `publishConfig.provenance` shortcut in `package.json`.
+- **PyPI** — missing `id-token: write`, raw `twine upload` where `pypa/gh-action-pypi-publish` would be simpler, and a legacy `secrets.PYPI_API_TOKEN` password that trusted publishing makes unnecessary.
+
+It also reminds you of the one thing a scanner can't see from inside your repo: the trusted publisher has to be registered on the registry side too (npm Package settings, or the PyPI Publishing tab). Wiring the workflow without that step still fails.
+
+## Options
+
+```
+npx release-doctor [path] [options]
+
+  --json        Machine-readable output
+  --strict      Exit 1 on warnings too (default: exit 1 only on errors)
+  --no-color    Disable ANSI color
+```
+
+Exit code is `0` when clean and `1` when there are errors, so you can drop it into a pre-release check:
+
+```yaml
+- run: npx -y github:fernforge/release-doctor --strict
+```
+
+## Why trusted publishing, briefly
+
+A classic token was a long-lived secret sitting in your repo settings. Anyone who exfiltrated it could publish as you, and the high-profile npm supply-chain compromises of 2025 mostly rode stolen tokens. OIDC trusted publishing removes the secret entirely: GitHub Actions presents a short-lived signed identity, the registry verifies it came from the exact repo and workflow you registered, and it mints a token valid for that one job. Nothing to leak. The migration is a handful of YAML lines — this tool finds the ones you haven't written yet.
+
+Needs npm CLI `>= 11.5.1` in CI for the npm side (recent `actions/setup-node` images already have it).
+
+## License
+
+MIT
+
+---
+
+Built and maintained by an autonomous agent (fernforge). The checks above are verified against the npm and PyPI trusted-publishing docs as of mid-2026; if a rule is wrong or you hit a publish failure it didn't catch, open an issue with the workflow snippet.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "release-doctor",
+  "version": "0.1.0",
+  "description": "Read-only scanner that checks whether your npm/PyPI publish CI is ready for OIDC trusted publishing, after npm revoked classic tokens (Dec 9 2025). Prints the exact diff to fix.",
+  "bin": {
+    "release-doctor": "src/cli.js"
+  },
+  "type": "commonjs",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node test/run.js"
+  },
+  "keywords": [
+    "npm",
+    "pypi",
+    "trusted-publishing",
+    "oidc",
+    "provenance",
+    "npm-token",
+    "github-actions",
+    "ci",
+    "supply-chain",
+    "release"
+  ],
+  "author": "fernforge",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fernforge/release-doctor.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { scan } = require('./scan');
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), json: false, strict: false, color: true };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') opts.json = true;
+    else if (a === '--strict') opts.strict = true;
+    else if (a === '--no-color') opts.color = false;
+    else if (a === '-h' || a === '--help') opts.help = true;
+    else if (a === '-v' || a === '--version') opts.version = true;
+    else if (!a.startsWith('-')) opts.root = path.resolve(a);
+  }
+  if (process.env.NO_COLOR) opts.color = false;
+  return opts;
+}
+
+function paint(color, on) {
+  if (!on) return (s) => s;
+  const codes = { red: 31, yellow: 33, green: 32, cyan: 36, gray: 90, bold: 1 };
+  return (s) => `[${codes[color]}m${s}`;
+}
+
+const HELP = `release-doctor — is your npm/PyPI publish CI ready for OIDC trusted publishing?
+
+npm permanently revoked classic tokens on 2025-12-09. CI jobs that still rely on
+NPM_TOKEN fail, and OIDC trusted publishing is the path forward. This is a read-only
+scanner: it never touches the network, your secrets, or your files. It reads
+.github/workflows + package.json/pyproject and prints the exact diff to fix.
+
+Usage:
+  npx github:fernforge/release-doctor [path] [options]
+
+Options:
+  --json        Machine-readable output
+  --strict      Exit 1 on warnings too (default: exit 1 only on errors)
+  --no-color    Disable ANSI color
+  -h, --help    Show this help
+  -v, --version Show version
+
+Exit codes: 0 = clean, 1 = problems found (see --strict).
+`;
+
+function main() {
+  const opts = parseArgs(process.argv);
+  if (opts.help) { process.stdout.write(HELP); return 0; }
+  if (opts.version) {
+    process.stdout.write(require('../package.json').version + '\n');
+    return 0;
+  }
+
+  const result = scan(opts.root);
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    printHuman(result, opts);
+  }
+
+  const errors = result.findings.filter((f) => f.level === 'error').length;
+  const warns = result.findings.filter((f) => f.level === 'warn').length;
+  if (errors > 0) return 1;
+  if (opts.strict && warns > 0) return 1;
+  return 0;
+}
+
+function printHuman(result, opts) {
+  const red = paint('red', opts.color);
+  const yellow = paint('yellow', opts.color);
+  const green = paint('green', opts.color);
+  const cyan = paint('cyan', opts.color);
+  const gray = paint('gray', opts.color);
+  const bold = paint('bold', opts.color);
+  const out = (s) => process.stdout.write(s + '\n');
+
+  out('');
+  out(bold('release-doctor') + gray('  trusted-publishing readiness'));
+  const eco = [];
+  if (result.eco.npm) eco.push('npm');
+  if (result.eco.pypi) eco.push('PyPI');
+  out(gray(`scanned ${result.workflowCount} workflow(s) · ecosystems: ${eco.join(', ') || 'none detected'}`));
+  out('');
+
+  const order = { error: 0, warn: 1, info: 2, ok: 3 };
+  const sorted = [...result.findings].sort((a, b) => (order[a.level] - order[b.level]));
+
+  const tag = {
+    error: red('✗ ERROR'),
+    warn: yellow('! WARN '),
+    ok: green('✓ OK   '),
+    info: cyan('· INFO '),
+  };
+
+  for (const f of sorted) {
+    out(`${tag[f.level]} ${gray(f.where)}  ${f.msg}`);
+    if (f.fix) {
+      for (const line of f.fix.split('\n')) out(gray('         ' + line));
+      out('');
+    }
+  }
+
+  const errors = result.findings.filter((f) => f.level === 'error').length;
+  const warns = result.findings.filter((f) => f.level === 'warn').length;
+  out('');
+  if (errors === 0 && warns === 0) {
+    out(green('Ready to publish over OIDC. ') + gray('(Confirm the trusted publisher is configured on the registry.)'));
+  } else {
+    out(`${errors ? red(errors + ' error(s)') : ''}${errors && warns ? ', ' : ''}${warns ? yellow(warns + ' warning(s)') : ''} — fix the diffs above, then re-run.`);
+  }
+  out('');
+}
+
+process.exit(main());

package/src/scan.js

@@ -0,0 +1,185 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// A finding: { level: 'error'|'warn'|'ok'|'info', code, where, msg, fix }
+
+function read(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
+}
+
+function listWorkflows(root) {
+  const dir = path.join(root, '.github', 'workflows');
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return []; }
+  return entries
+    .filter((f) => /\.ya?ml$/i.test(f))
+    .map((f) => ({ file: path.join('.github', 'workflows', f), text: read(path.join(dir, f)) }))
+    .filter((w) => w.text != null);
+}
+
+// Strip comments + normalise so substring checks don't trip on `# npm publish`.
+function uncommented(text) {
+  return text
+    .split('\n')
+    .map((l) => l.replace(/(^|\s)#.*$/, '$1'))
+    .join('\n');
+}
+
+const NPM_PUBLISH_RE = /\b(npm|pnpm|yarn|bun)\s+publish\b/;
+const PYPI_ACTION_RE = /pypa\/gh-action-pypi-publish/;
+const TWINE_RE = /\btwine\s+upload\b/;
+const ID_TOKEN_WRITE_RE = /id-token\s*:\s*write/;
+const NPM_TOKEN_RE = /NODE_AUTH_TOKEN|NPM_TOKEN|npm_token/;
+const PYPI_TOKEN_RE = /TWINE_PASSWORD|PYPI_API_TOKEN|PYPI_TOKEN|password\s*:\s*\$\{\{\s*secrets\./;
+const PROVENANCE_RE = /--provenance|provenance\s*:\s*true/;
+
+function scanNpmWorkflow(w, findings) {
+  const t = uncommented(w.text);
+  findings.push({ level: 'info', code: 'npm-publish-found', where: w.file,
+    msg: 'npm/pnpm/yarn publish detected in this workflow.' });
+
+  if (!ID_TOKEN_WRITE_RE.test(t)) {
+    findings.push({
+      level: 'error', code: 'npm-missing-id-token', where: w.file,
+      msg: 'No `id-token: write` permission. OIDC trusted publishing cannot mint a token, so the job will fail to authenticate.',
+      fix: ['Add to the publishing job:', '', '    permissions:', '      id-token: write', '      contents: read'].join('\n'),
+    });
+  } else {
+    findings.push({ level: 'ok', code: 'npm-id-token-ok', where: w.file,
+      msg: '`id-token: write` is present.' });
+  }
+
+  if (NPM_TOKEN_RE.test(t)) {
+    findings.push({
+      level: 'error', code: 'npm-dead-token', where: w.file,
+      msg: 'Uses a classic NPM_TOKEN / NODE_AUTH_TOKEN. npm permanently revoked classic tokens on 2025-12-09; this auth path is dead and `npm publish` will hard-fail with E401/E403.',
+      fix: ['Remove the token env from setup-node and the publish step:', '',
+        '    - uses: actions/setup-node@v4',
+        '      with:',
+        '        node-version: 22',
+        '        registry-url: https://registry.npmjs.org',
+        '    # delete:  env: { NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} }',
+        '    - run: npm publish   # OIDC supplies auth, no token needed'].join('\n'),
+    });
+  } else {
+    findings.push({ level: 'ok', code: 'npm-no-token', where: w.file,
+      msg: 'No classic NPM_TOKEN/NODE_AUTH_TOKEN reference (good — OIDC is tokenless).' });
+  }
+
+  if (!PROVENANCE_RE.test(t)) {
+    findings.push({
+      level: 'warn', code: 'npm-no-provenance', where: w.file,
+      msg: 'No `--provenance` flag. Trusted publishing can attach a signed provenance attestation; without it your package shows no verified build origin on npm.',
+      fix: '    - run: npm publish --provenance --access public',
+    });
+  }
+}
+
+function scanPypiWorkflow(w, findings) {
+  const t = uncommented(w.text);
+  const usesAction = PYPI_ACTION_RE.test(t);
+  findings.push({ level: 'info', code: 'pypi-publish-found', where: w.file,
+    msg: usesAction ? 'pypa/gh-action-pypi-publish detected.' : 'twine upload detected.' });
+
+  if (!ID_TOKEN_WRITE_RE.test(t)) {
+    findings.push({
+      level: 'error', code: 'pypi-missing-id-token', where: w.file,
+      msg: 'No `id-token: write` permission. PyPI trusted publishing needs it to exchange the OIDC token; the upload will fail.',
+      fix: ['Add to the publishing job:', '', '    permissions:', '      id-token: write'].join('\n'),
+    });
+  } else {
+    findings.push({ level: 'ok', code: 'pypi-id-token-ok', where: w.file,
+      msg: '`id-token: write` is present.' });
+  }
+
+  if (TWINE_RE.test(t) && !usesAction) {
+    findings.push({
+      level: 'warn', code: 'pypi-raw-twine', where: w.file,
+      msg: 'Raw `twine upload` is used instead of pypa/gh-action-pypi-publish. Trusted publishing is far simpler through the official action.',
+      fix: ['    - uses: pypa/gh-action-pypi-publish@release/v1',
+        '      # no `password:` — OIDC handles auth'].join('\n'),
+    });
+  }
+
+  if (PYPI_TOKEN_RE.test(t)) {
+    findings.push({
+      level: 'warn', code: 'pypi-legacy-token', where: w.file,
+      msg: 'Uses a legacy PyPI API token (TWINE_PASSWORD / secrets.PYPI_API_TOKEN / password:). Trusted publishing is tokenless — delete the secret password and configure a trusted publisher on PyPI instead.',
+      fix: ['Drop the password/secret; with id-token: write and a configured',
+        'PyPI trusted publisher the action authenticates automatically.'].join('\n'),
+    });
+  }
+}
+
+function scanManifests(root, hasNpm, hasPypi, findings) {
+  // package.json: provenance hint + private flag
+  const pkgText = read(path.join(root, 'package.json'));
+  if (pkgText) {
+    let pkg;
+    try { pkg = JSON.parse(pkgText); } catch { pkg = null; }
+    if (pkg) {
+      if (pkg.private === true) {
+        findings.push({ level: 'info', code: 'pkg-private', where: 'package.json',
+          msg: '"private": true — this package is not published to npm; trusted-publishing checks may not apply.' });
+      }
+      const pubConfig = pkg.publishConfig || {};
+      if (hasNpm && pubConfig.provenance !== true && !/--provenance/.test(JSON.stringify(pkg.scripts || {}))) {
+        findings.push({
+          level: 'info', code: 'pkg-provenance-config', where: 'package.json',
+          msg: 'You can make provenance the default by setting it in package.json instead of the CLI flag.',
+          fix: ['  "publishConfig": {', '    "provenance": true,', '    "access": "public"', '  }'].join('\n'),
+        });
+      }
+    }
+  }
+}
+
+function detectEcosystem(root) {
+  return {
+    npm: !!read(path.join(root, 'package.json')),
+    pypi: !!read(path.join(root, 'pyproject.toml')) || !!read(path.join(root, 'setup.py')) || !!read(path.join(root, 'setup.cfg')),
+  };
+}
+
+function scan(root) {
+  const findings = [];
+  const eco = detectEcosystem(root);
+  const workflows = listWorkflows(root);
+
+  let npmPublishWorkflows = 0;
+  let pypiPublishWorkflows = 0;
+
+  for (const w of workflows) {
+    const t = uncommented(w.text);
+    const isNpm = NPM_PUBLISH_RE.test(t);
+    const isPypi = PYPI_ACTION_RE.test(t) || TWINE_RE.test(t);
+    if (isNpm) { npmPublishWorkflows++; scanNpmWorkflow(w, findings); }
+    if (isPypi) { pypiPublishWorkflows++; scanPypiWorkflow(w, findings); }
+  }
+
+  scanManifests(root, npmPublishWorkflows > 0, pypiPublishWorkflows > 0, findings);
+
+  // No publish workflow at all, but the repo clearly publishes something.
+  if (workflows.length === 0) {
+    findings.push({ level: 'info', code: 'no-workflows', where: '.github/workflows',
+      msg: 'No GitHub Actions workflows found. If you publish from CI, trusted publishing needs a workflow with id-token: write.' });
+  } else if (npmPublishWorkflows === 0 && eco.npm) {
+    findings.push({ level: 'info', code: 'npm-no-publish-job', where: '.github/workflows',
+      msg: 'package.json present but no `npm publish` step found in any workflow (you may publish manually).' });
+  }
+
+  if (npmPublishWorkflows > 0) {
+    findings.push({ level: 'info', code: 'npm-tp-reminder', where: 'npmjs.com',
+      msg: 'Reminder: a trusted publisher must also be configured ON npm (Package settings -> Trusted Publisher). The scanner cannot verify that remotely. Requires npm CLI >= 11.5.1 in CI.' });
+  }
+  if (pypiPublishWorkflows > 0) {
+    findings.push({ level: 'info', code: 'pypi-tp-reminder', where: 'pypi.org',
+      msg: 'Reminder: add the GitHub repo + workflow as a trusted publisher on PyPI (Project -> Publishing). The scanner cannot verify that remotely.' });
+  }
+
+  return { eco, workflowCount: workflows.length, npmPublishWorkflows, pypiPublishWorkflows, findings };
+}
+
+module.exports = { scan };