package-registry-manager 0.25.1 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "package-registry-manager",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "Inspect repositories and guide secure package-registry setup",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@link-foundation/gh-manager": "https://codeload.github.com/link-foundation/gh-manager/tar.gz/0b3ceb1590be7eb0340ae088730698b5ae9bebfc",
-    "browser-commander": "^0.34.0",
+    "browser-commander": "^0.34.1",
     "command-stream": "^2.6.0",
     "playwright": "^1.63.0",
     "selenium-webdriver": "^4.50.0"

package/src/cpp-distribution.mjs

@@ -22,9 +22,44 @@ export async function cppDistribution(
     }
   }
   const project =
-    /\bproject\s*\(\s*([\w.-]+)\s+VERSION\s+(\d+(?:\.\d+)+)/i.exec(cmake);
+    /\bproject\s*\(\s*([\w.-]+)\s+VERSION\s+(\d+(?:\.\d+)+|\$\{(\w+)\})/i.exec(
+      cmake,
+    );
   let name = project?.[1];
-  let version = project?.[2];
+  let version = project?.[3] ? null : project?.[2];
+  let versionSource = null;
+  if (project?.[3]) {
+    // `file(READ "${CMAKE_CURRENT_SOURCE_DIR}/VERSION" VAR)` is resolved by
+    // reading that one sibling file; nothing in the CMake file is executed.
+    const read = new RegExp(
+      `\\bfile\\s*\\(\\s*READ\\s+"?\\$\\{CMAKE_CURRENT_(?:SOURCE|LIST)_DIR\\}/([\\w.-]+)"?\\s+${project[3]}\\s*\\)`,
+      "i",
+    ).exec(cmake);
+    const literal = new RegExp(
+      `\\bset\\s*\\(\\s*${project[3]}\\s+"?(\\d+(?:\\.\\d+)+)"?\\s*\\)`,
+      "i",
+    ).exec(cmake);
+    if (read) {
+      try {
+        const value = (
+          await readFile(path.join(path.dirname(manifestPath), read[1]), "utf8")
+        ).trim();
+        if (/^\d+(?:\.\d+)+$/.test(value)) {
+          version = value;
+          versionSource = path.posix.join(
+            path.posix.dirname(manifest),
+            read[1],
+          );
+        }
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+    } else if (literal) {
+      version = literal[1];
+    }
+  }
   const registry =
     filename === "vcpkg.json"
       ? "vcpkg"
@@ -62,9 +97,11 @@ export async function cppDistribution(
     manifest,
     publishable: true,
     distribution: {
-      version_source: project
-        ? path.posix.join(path.posix.dirname(manifest), "CMakeLists.txt")
-        : manifest,
+      version_source:
+        versionSource ??
+        (project
+          ? path.posix.join(path.posix.dirname(manifest), "CMakeLists.txt")
+          : manifest),
       provider_status: "unverified",
       ...(registry === "conan"
         ? {

package/src/credential-requirements.mjs

@@ -0,0 +1,105 @@
+/**
+ * Registries without public OIDC publishing: the exact credential set a
+ * workflow needs, which secrets it already references, and where values may
+ * live. Values are only ever held in memory or written to encrypted GitHub
+ * secrets; nothing here rotates, revokes or deletes an existing credential.
+ */
+export const CREDENTIAL_SETS = Object.freeze({
+  "maven-central": {
+    oidc: "unsupported",
+    oidc_note:
+      "Sonatype Central Portal has no OIDC trusted publishing; publish with a Central user-token pair and a GPG signing key.",
+    namespace: "verified Central Portal namespace matching the groupId",
+    roles: [
+      {
+        role: "central-username",
+        candidates: [
+          "CENTRAL_USERNAME",
+          "MAVEN_CENTRAL_USERNAME",
+          "OSSRH_USERNAME",
+          "SONATYPE_USERNAME",
+          "MAVEN_USERNAME",
+        ],
+        default: "CENTRAL_USERNAME",
+      },
+      {
+        role: "central-token",
+        candidates: [
+          "CENTRAL_TOKEN",
+          "MAVEN_CENTRAL_TOKEN",
+          "MAVEN_CENTRAL_PASSWORD",
+          "OSSRH_TOKEN",
+          "OSSRH_PASSWORD",
+          "SONATYPE_TOKEN",
+          "MAVEN_PASSWORD",
+        ],
+        default: "CENTRAL_TOKEN",
+      },
+      {
+        role: "gpg-private-key",
+        candidates: ["GPG_PRIVATE_KEY", "MAVEN_GPG_PRIVATE_KEY", "SIGNING_KEY"],
+        default: "GPG_PRIVATE_KEY",
+      },
+      {
+        role: "gpg-passphrase",
+        candidates: [
+          "GPG_PASSPHRASE",
+          "MAVEN_GPG_PASSPHRASE",
+          "SIGNING_PASSWORD",
+        ],
+        default: "GPG_PASSPHRASE",
+      },
+    ],
+  },
+  packagist: {
+    oidc: "unsupported",
+    oidc_note:
+      "Public packagist.org has no OIDC publishing (Private Packagist OIDC is a separate product); releases come from tags via the GitHub hook or the update-package API.",
+    roles: [
+      {
+        role: "packagist-username",
+        candidates: ["PACKAGIST_USERNAME"],
+        default: "PACKAGIST_USERNAME",
+        optional: true,
+      },
+      {
+        role: "packagist-api-token",
+        candidates: ["PACKAGIST_TOKEN", "PACKAGIST_API_TOKEN"],
+        default: "PACKAGIST_TOKEN",
+        optional: true,
+      },
+    ],
+  },
+});
+
+const SECRET = /\bsecrets\.([A-Za-z_][A-Za-z0-9_]*)\b/g;
+
+/** Structured requirements resolved against the secrets the workflows read. */
+export function credentialRequirements(registry, workflows = []) {
+  const set = CREDENTIAL_SETS[registry];
+  if (!set) {
+    return null;
+  }
+  const referenced = new Set(
+    workflows.flatMap((workflow) =>
+      [...workflow.contents.replace(/^\s*#.*$/gm, "").matchAll(SECRET)].map(
+        (match) => match[1],
+      ),
+    ),
+  );
+  return {
+    oidc: set.oidc,
+    oidc_note: set.oidc_note,
+    ...(set.namespace ? { namespace: set.namespace } : {}),
+    storage: "memory-or-encrypted-github-secret",
+    secrets: set.roles.map((role) => {
+      const found = role.candidates.find((name) => referenced.has(name));
+      return {
+        role: role.role,
+        secret: found ?? role.default,
+        referenced: Boolean(found),
+        ...(role.optional ? { optional: true } : {}),
+      };
+    }),
+  };
+}

package/src/discovery.mjs

@@ -1,3 +1,4 @@
+import { credentialRequirements } from "./credential-requirements.mjs";
 import { auditConfig, applyAuditConfig } from "./audit-config.mjs";
 import { cppDistribution } from "./cpp-distribution.mjs";
 import { markIdentityConflicts } from "./identity-conflicts.mjs";
@@ -9,6 +10,7 @@ import { packageWorkflows, auditWrappers } from "./package-coverage.mjs";
 import { REGISTRIES } from "./model.mjs";
 import { inspectManifestRepositories } from "./repository-identity.mjs";
 import {
+  RELEASE_EVIDENCE,
   TRUSTED_REGISTRIES,
   detectPublisher,
   tokenSecretWarning,
@@ -198,10 +200,10 @@ export async function inspectRepository(repository, options = {}) {
       }
     }
   }
-  publishers.set(
-    "maven-central",
-    await detectPublisher(root, workflows, "maven-central"),
-  );
+  for (const registry of SCOPED_REGISTRIES) {
+    publishers.set(registry, await detectPublisher(root, workflows, registry));
+  }
+  canonicalComposer(parsed);
   const containerFiles = dockerfiles
     .map((item) => relativePath(root, item))
     .filter((item) => !ignored(item) && kept(item, true));
@@ -237,8 +239,9 @@ export async function inspectRepository(repository, options = {}) {
         )
         .map(async (item) => {
           const scoped =
-            counts.get(item.registry) > 1 &&
-            TRUSTED_REGISTRIES.includes(item.registry)
+            (counts.get(item.registry) > 1 &&
+              TRUSTED_REGISTRIES.includes(item.registry)) ||
+            SCOPED_REGISTRIES.includes(item.registry)
               ? new Map([
                   [
                     item.registry,
@@ -250,10 +253,37 @@ export async function inspectRepository(repository, options = {}) {
                   ],
                 ])
               : publishers;
-          return withPublisher(item, workflows, scoped);
+          return withPublisher(
+            item,
+            workflows,
+            item.publisher_scope
+              ? new Map([
+                  [
+                    item.registry,
+                    await detectPublisher(
+                      root,
+                      packageWorkflows(workflows, {
+                        ...item,
+                        manifest: item.publisher_scope,
+                      }),
+                      item.registry,
+                    ),
+                  ],
+                ])
+              : scoped,
+          );
         }),
     )
   )
+    .filter(
+      (item) =>
+        !internalWorkload(item) ||
+        config.publish?.includes(item.manifest) ||
+        skip(
+          item.manifest,
+          `internal ${internalWorkload(item)} workload: no workflow publishes it and no source decision lists it under "publish"`,
+        ),
+    )
     .concat(
       containerPackages(containerFiles, workflows, coordinates),
       chromePackages,
@@ -306,6 +336,47 @@ function releaseWorkflow(publishers) {
   return null;
 }
 
+/** Registries whose publication evidence is scoped to one manifest. */
+const SCOPED_REGISTRIES = ["maven-central", "packagist", "go-modules", "cmake"];
+
+/** Benchmark/fixture manifests are internal unless a workflow releases them. */
+function internalWorkload(item) {
+  if (item.workflow) {
+    return null;
+  }
+  const segment = item.manifest
+    .split("/")
+    .slice(0, -1)
+    .find((part) => /^(?:bench(?:mark)?(?:es|s)?|perf)$/i.test(part));
+  return segment ? "benchmark" : null;
+}
+
+/**
+ * Packagist reads only the repository-root composer.json, so a same-name
+ * descriptor in a subdirectory is a development copy of that distribution.
+ * The root keeps the copy's declared version and the copy's publishing job.
+ */
+function canonicalComposer(parsed) {
+  const composer = parsed.filter(
+    (item) => item?.registry === "packagist" && !item.discovery_skip,
+  );
+  const root = composer.find((item) => item.manifest === "composer.json");
+  if (!root) {
+    return;
+  }
+  for (const copy of composer.filter(
+    (item) => item !== root && item.name === root.name,
+  )) {
+    copy.discovery_skip = `Packagist reads only the repository-root composer.json; ${copy.manifest} is a development descriptor of ${root.name}`;
+    copy.publishable = false;
+    if (!root.version && copy.version) {
+      root.version = copy.version;
+      root.version_source = copy.manifest;
+    }
+    root.publisher_scope ??= copy.manifest;
+  }
+}
+
 function withPublisher(item, workflows, publishers) {
   const publisher = item.publishable ? publishers.get(item.registry) : null;
   if (!publisher) {
@@ -321,16 +392,32 @@ function withPublisher(item, workflows, publishers) {
   if (publisher.jobs.length > 0) {
     result.workflow_jobs = publisher.jobs;
   }
+  if (publisher.callees?.length) {
+    // Reusable workflows publish under the caller's identity; the callee
+    // jobs are kept so setup and recovery act on the actual publishing job.
+    result.workflow_callees = publisher.callees;
+  }
+  if (publisher.gate) {
+    result.authentication_gate = publisher.gate;
+  }
   if (publisher.environment) {
     result.environment = publisher.environment;
   }
   if (publisher.candidates.length > 1) {
     result.workflow_candidates = publisher.candidates;
   }
+  const credentials = credentialRequirements(item.registry, workflows);
+  if (credentials) {
+    result.credential_requirements = credentials;
+  }
   const secrets = tokenSecrets(workflows, item.registry);
   const warnings = [
     ...publisher.warnings,
-    ...(!publisher.workflow && publisher.candidates.length === 0
+    // Tags and registry hooks release Go modules, Packagist packages and
+    // CMake archives without a workflow, so only evidence is reported.
+    ...(!publisher.workflow &&
+    publisher.candidates.length === 0 &&
+    !RELEASE_EVIDENCE.has(item.registry)
       ? [
           `no workflow publishes ${item.name} to ${item.registry}; CI releases will not reach it`,
         ]
@@ -399,13 +486,22 @@ async function parseManifest(manifestPath, manifest, root) {
         capture(contents, /\bversion\s*=\s*['"]([^'"]+)/),
         manifest,
       );
-    case "go.mod":
-      return packageInfo(
+    case "go.mod": {
+      const item = packageInfo(
         "go-modules",
         capture(contents, /^\s*module\s+(\S+)/m) ?? "unknown-go-module",
-        null,
+        await versionFile(manifestPath),
         manifest,
       );
+      if (item.version) {
+        item.version = `v${item.version.replace(/^v/, "")}`;
+        item.version_source = path.posix.join(
+          path.posix.dirname(manifest),
+          "VERSION",
+        );
+      }
+      return item;
+    }
     case "pom.xml":
       return parseMaven(contents, manifest);
     case "build.gradle":
@@ -541,11 +637,26 @@ function parseDotnet(contents, manifestPath, manifest) {
     xmlTag(contents, "PackageId") ??
       xmlTag(contents, "AssemblyName") ??
       path.basename(manifestPath, path.extname(manifestPath)),
-    xmlTag(contents, "PackageVersion") ?? xmlTag(contents, "Version"),
+    dotnetVersion(contents),
     manifest,
   );
 }
 
+function dotnetVersion(contents) {
+  const literal = (tag) => {
+    const value = xmlTag(contents, tag);
+    return value && !value.includes("$(") ? value : null;
+  };
+  const explicit = literal("PackageVersion") ?? literal("Version");
+  if (explicit) {
+    return explicit;
+  }
+  // MSBuild derives Version from VersionPrefix and VersionSuffix.
+  const prefix = literal("VersionPrefix");
+  const suffix = literal("VersionSuffix");
+  return prefix ? (suffix ? `${prefix}-${suffix}` : prefix) : null;
+}
+
 function parseMaven(contents, manifest) {
   const artifact = xmlTag(contents, "artifactId") ?? "unknown-maven-artifact";
   const group = xmlTag(contents, "groupId");
@@ -623,6 +734,21 @@ function packageInfo(
   return result;
 }
 
+/** A plain sibling VERSION file, as release tooling for Go/C++ often keeps. */
+export async function versionFile(manifestPath) {
+  try {
+    const value = (
+      await readManifest(path.join(path.dirname(manifestPath), "VERSION"))
+    ).trim();
+    return /^v?\d+(?:\.\d+){1,3}(?:[-+][\w.-]+)?$/.test(value) ? value : null;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
 // Editors on Windows may save a byte order mark; npm and Cargo accept it.
 async function readManifest(manifest) {
   return (await readFile(manifest, "utf8")).replace(/^\uFEFF/, "");

package/src/extra-flows.mjs

@@ -1,3 +1,4 @@
+import { credentialRequirements } from "./credential-requirements.mjs";
 import { credentialSteps } from "./credential-cycle.mjs";
 import { tokenSecretSteps } from "./tokens.mjs";
 
@@ -76,20 +77,100 @@ export function tokenFlow(item) {
       ]
     : [];
   if (item.registry === "maven-central") {
+    const group = /^([\w.-]+):/.exec(item.name ?? "")?.[1];
     steps.push({
       id: "verify-namespace",
-      title: "Verify a Central namespace",
+      title: `Verify the Central namespace${group ? ` ${group}` : ""}`,
       kind: "browser",
       description:
-        "Sign in to the Central Portal and verify the namespace used by the package coordinates.",
+        "Sign in to the Central Portal and verify the namespace used by the package coordinates. Publishing stays blocked until the namespace reads back as verified.",
       url: "https://central.sonatype.com/publishing/namespaces",
+      ...(group ? { namespace: group } : {}),
+      state: "manual-prerequisite",
     });
+    return steps.concat(mavenCredentialSteps(item));
   }
   return steps.concat(
     credentialSteps(item.registry, item.token_secrets?.[0] ?? item.registry),
   );
 }
 
+/**
+ * Central publishing needs a provider-specific pair plus signing material; no
+ * OIDC is claimed. Missing secrets are requested, present ones are kept, and
+ * nothing is rotated or revoked.
+ */
+export function mavenCredentialSteps(item) {
+  const requirements =
+    item.credential_requirements ?? credentialRequirements("maven-central");
+  const pick = (...roles) =>
+    requirements.secrets.filter((entry) => roles.includes(entry.role));
+  const describe = (entries) =>
+    entries.map((entry) => entry.secret).join(" + ");
+  const pair = pick("central-username", "central-token");
+  const signing = pick("gpg-private-key", "gpg-passphrase");
+  return [
+    {
+      id: "ensure-central-credential-pair",
+      title: `Ensure the Central user-token pair ${describe(pair)}`,
+      kind: "api",
+      confirm: true,
+      secrets: pair,
+      oidc: "unsupported",
+      description: `${requirements.oidc_note} Generate a Central Portal user token (username + password pair) only when ${describe(pair)} is missing, hold the values in memory, and store them as encrypted GitHub secrets through gh-manager. Existing secrets are kept; nothing is rotated or revoked.`,
+      url: "https://central.sonatype.com/usertoken",
+    },
+    {
+      id: "ensure-signing-key",
+      title: `Ensure the signing prerequisites ${describe(signing)}`,
+      kind: "manual",
+      confirm: true,
+      secrets: signing,
+      state: "manual-prerequisite",
+      description:
+        "Maven Central rejects unsigned artifacts. Provide an armored GPG private key whose public key is on a public keyserver, and its passphrase, as encrypted GitHub secrets; keys are never written to disk or printed.",
+    },
+  ];
+}
+
+/** Public Packagist: tags plus hook or update API; no OIDC, explicit states otherwise. */
+export function packagistSteps(item) {
+  const requirements =
+    item.credential_requirements ?? credentialRequirements("packagist");
+  const api = requirements.secrets;
+  const referenced = api.every((entry) => entry.referenced);
+  return [
+    {
+      id: "verify-packagist-package",
+      title: "Read back the Packagist package and exact stable tag",
+      kind: "check",
+      description: `Read https://repo.packagist.org/p2/${item.name}.json and require the exact stable version ${item.version ?? "(unresolved)"} from a tag; dev branches do not count.`,
+      url: `https://packagist.org/packages/${item.name}`,
+    },
+    {
+      id: "packagist-github-hook",
+      title: "Confirm the Packagist GitHub integration",
+      kind: "manual",
+      state: "manual-prerequisite",
+      description:
+        'Packagist updates on tag pushes through its GitHub hook/app integration. GitHub does not expose that installation to this tool, so confirm it on the package page (no "not auto-updated" warning).',
+      url: `https://packagist.org/packages/${item.name}`,
+    },
+    {
+      id: "packagist-update-api",
+      title: referenced
+        ? `Keep the update-package API path ${api.map((entry) => entry.secret).join(" + ")}`
+        : "Packagist update-package API is not configured",
+      kind: "manual",
+      state: referenced ? "configured" : "unsupported-without-credentials",
+      secrets: api,
+      oidc: "unsupported",
+      description: `${requirements.oidc_note} ${referenced ? "The workflow calls the update-package API; keep both secrets as encrypted GitHub secrets. Nothing is rotated or revoked." : "Rely on the GitHub hook, or add PACKAGIST_USERNAME and PACKAGIST_TOKEN (Packagist profile API token) as encrypted GitHub secrets for the update-package API."}`,
+      url: "https://packagist.org/profile/",
+    },
+  ];
+}
+
 /** NuGet uses explicit account policy and preserves provided fallback credentials. */
 export function nugetFlow(item, context) {
   return [

package/src/nuget-ci.mjs

@@ -3,6 +3,37 @@ import { repositorySlug } from "./repository-identity.mjs";
 import { AUTH_FAILURE_PATTERNS } from "./publishing-policy.mjs";
 import { fileURLToPath } from "node:url";
 
+/** Job names (or reusable-call segments) whose skip would hide the release. */
+export function requiredJobs(pkg = {}) {
+  return [
+    ...(pkg.workflow_jobs ?? []),
+    ...(pkg.workflow_callees ?? []).map((chain) => chain.split(" -> ").at(-1)),
+  ].filter(Boolean);
+}
+
+/**
+ * Failed or cancelled jobs always block. A skipped job blocks only when it is a
+ * required release job (or when the required set is unknown); PR-only reviews
+ * and unchanged-component jobs legitimately skip on a push to main.
+ */
+export function unmetJobs(jobs, required) {
+  const isRequired = (job) =>
+    !required.length ||
+    job.name.split(" / ").some((segment) => required.includes(segment.trim()));
+  const unmet = jobs.filter(
+    (job) =>
+      !["success", "skipped"].includes(job.conclusion) ||
+      (job.conclusion === "skipped" && isRequired(job)),
+  );
+  if (
+    required.length &&
+    !jobs.some((job) => isRequired(job) && job.conclusion === "success")
+  ) {
+    unmet.push({ name: required.join(", "), conclusion: "missing" });
+  }
+  return unmet;
+}
+
 /** Fresh main-revision CI, actual method and exact public consumers are separate gates. */
 export async function verifyNugetRelease(session) {
   const github = session.options.github ?? githubServices(session.options);
@@ -116,7 +147,7 @@ export async function verifyNugetRelease(session) {
     run.status !== "completed" ||
     run.conclusion !== "success" ||
     !jobs.length ||
-    jobs.some((job) => job.conclusion !== "success")
+    unmetJobs(jobs, requiredJobs(session.plan.package)).length
   ) {
     throw new Error(
       `NuGet current-main pipeline has incomplete gates: ${run.html_url}`,

package/src/nuget-migration.mjs

@@ -1,5 +1,99 @@
 import { nugetWorkflowSteps } from "./nuget-workflow.mjs";
 
+export const NUGET_PREREQUISITE_EDIT =
+  "Split the NuGet publish step so one step runs only `dotnet nuget push <artifact glob> --api-key ... --source https://api.nuget.org/v3/index.json` (optionally behind a `should_publish` guard, `${A:-$B}` key selection, a key-presence check and `published=` outputs); pack, tests and any other command must stay in earlier steps.";
+
+function prerequisite(reason) {
+  const error = new Error(
+    `${reason}. Prerequisite edit: ${NUGET_PREREQUISITE_EDIT}`,
+  );
+  error.code = "nuget-prerequisite-edit";
+  error.prerequisite = NUGET_PREREQUISITE_EDIT;
+  return error;
+}
+
+/**
+ * Recognize the guarded multiline push used by links-notation style workflows.
+ * Every line must be the guard, key selection, presence check, notices,
+ * `published=` outputs or one nuget.org push; anything else is not migrated.
+ */
+export function guardedNugetPush(step) {
+  const start = step.findIndex((line) =>
+    /^\s*-?\s*run:\s*\|[-+]?\s*$/.test(line),
+  );
+  if (start < 0) {
+    return null;
+  }
+  const level = step[start].search(/\S/);
+  const body = [];
+  for (const line of step.slice(start + 1)) {
+    if (line.trim() && line.search(/\S/) <= level) {
+      break;
+    }
+    body.push(line.trim());
+  }
+  const joined = body.join("\n").replace(/\\\n\s*/g, " ");
+  const lines = joined
+    .split("\n")
+    .filter((line) => line && !line.startsWith("#"));
+  let guard = null;
+  let push = null;
+  let block = null;
+  for (const line of lines) {
+    const opened =
+      /^if \[ "\$\{\{\s*([\w.-]+)\s*\}\}" != "true" \]; then$/.exec(line);
+    if (opened && !block && !guard) {
+      guard = opened[1];
+      block = "guard";
+      continue;
+    }
+    if (/^if \[ -z "\$\w+" \]; then$/.test(line) && !block) {
+      block = "missing";
+      continue;
+    }
+    if (line === "fi" && block) {
+      block = null;
+      continue;
+    }
+    if (block === "guard" && /^exit 0$/.test(line)) {
+      continue;
+    }
+    if (block === "missing" && /^exit 1$/.test(line)) {
+      continue;
+    }
+    if (
+      /^set -[euxo pipefail]+$/.test(line) ||
+      /^\w+="\$\{\w+:-\$\w+\}"$/.test(line) ||
+      /^echo "[^"`$]*(?:\$\{\{[^}]*\}\}[^"`$]*)*"(?: >> "\$GITHUB_OUTPUT")?$/.test(
+        line,
+      )
+    ) {
+      continue;
+    }
+    const command =
+      /^dotnet nuget push (?:"([^"]+)"|'([^']+)'|(\S+))(.*)$/.exec(line);
+    if (command && !push && !block) {
+      push = command;
+      continue;
+    }
+    throw prerequisite(
+      `NuGet publish script contains an unreviewed command: ${line}`,
+    );
+  }
+  if (!push || block) {
+    throw prerequisite(
+      "NuGet multiline step has no single recognizable artifact push",
+    );
+  }
+  return {
+    guard,
+    glob: push[1] ?? push[2] ?? push[3],
+    options: push[4],
+    start,
+    level,
+  };
+}
+
 /** Preserve validation, build, artifact and step conditions when replacing a direct push. */
 export function convertNugetStep(step, packages, index) {
   if (packages.length !== 1) {
@@ -7,13 +101,17 @@ export function convertNugetStep(step, packages, index) {
       "NuGet migration requires a package-specific publishing step; ambiguous multi-package globs need explicit review",
     );
   }
+  const guarded = guardedNugetPush(step);
+  if (guarded) {
+    return convertGuarded(step, packages, index, guarded);
+  }
   const run = step.find((line) => /^\s*-?\s*run:/.test(line));
   const push =
     /^\s*-?\s*run:\s*dotnet\s+nuget\s+push\s+(?:"([^"\n]+)"|'([^'\n]+)'|([^\s]+))\s*(.*)$/.exec(
       run ?? "",
     );
   if (!push || /[;\n`]|\$\(/.test(push.slice(1).join(""))) {
-    throw new Error(
+    throw prerequisite(
       "NuGet script or multiline push requires a reviewed artifact-only publishing command; validation/build commands cannot be retried",
     );
   }
@@ -96,3 +194,82 @@ export function convertNugetStep(step, packages, index) {
   }
   return lines;
 }
+
+/** Guard -> OIDC login -> controller push of the same artifacts -> original outputs. */
+function convertGuarded(step, packages, index, guarded) {
+  if (
+    /--source\s+(?!["']?https:\/\/api\.nuget\.org\/v3\/index\.json)/.test(
+      guarded.options,
+    )
+  ) {
+    throw prerequisite(
+      "NuGet policy migration requires the explicit nuget.org destination",
+    );
+  }
+  if (!/^[\w./*-]+$/.test(guarded.glob)) {
+    throw prerequisite("NuGet artifact glob must be a literal job-local path");
+  }
+  const prefix = " ".repeat(step[0].search(/\S/));
+  const header = step.slice(0, guarded.start);
+  const name =
+    /-\s*name:\s*(.+)$/.exec(step[0])?.[1] ?? "Publish NuGet package";
+  const id = header
+    .map((line) => /^\s*id:\s*(\S+)/.exec(line)?.[1])
+    .find(Boolean);
+  const condition = header
+    .map((line) => /^\s*if:\s*(.+)$/.exec(line)?.[1])
+    .find(Boolean)
+    ?.replace(/^\$\{\{\s*|\s*\}\}$/g, "");
+  const secrets = [...step.join("\n").matchAll(/secrets\.(\w+)/g)].map(
+    (m) => m[1],
+  );
+  const gates = [condition, guarded.guard && `${guarded.guard} == 'true'`]
+    .filter(Boolean)
+    .map((part) => `(${part})`)
+    .join(" && ");
+  const publishId = `prm_nuget_publish_${index}`;
+  const lines = nugetWorkflowSteps(
+    {
+      ...packages[0],
+      token_secrets: [...secrets, ...(packages[0].token_secrets ?? [])],
+    },
+    { build: false, artifactGlob: guarded.glob },
+  )
+    .map((line) => prefix + line.slice(6))
+    .map((line) =>
+      line.replaceAll("prm_nuget_login", `prm_nuget_login_${index}`),
+    );
+  const loginIf = lines.findIndex((line) => /if: vars.NUGET_USER/.test(line));
+  if (gates) {
+    lines[loginIf] += ` && ${gates}`;
+  }
+  const publish = lines.findIndex((line) =>
+    /- name: Publish validated NuGet/.test(line),
+  );
+  lines.splice(
+    publish + 1,
+    0,
+    `${prefix}  id: ${publishId}`,
+    ...(gates ? [`${prefix}  if: ${gates}`] : []),
+  );
+  const record = [
+    `${prefix}- name: ${name}`,
+    ...(id ? [`${prefix}  id: ${id}`] : []),
+    `${prefix}  if: \${{ !cancelled()${condition ? ` && (${condition})` : ""} }}`,
+    `${prefix}  env:`,
+    `${prefix}    PRM_SHOULD_PUBLISH: ${guarded.guard ? `\${{ ${guarded.guard} }}` : "'true'"}`,
+    `${prefix}    PRM_PUBLISH_OUTCOME: \${{ steps.${publishId}.outcome }}`,
+    `${prefix}  run: |`,
+    `${prefix}    if [ "$PRM_SHOULD_PUBLISH" != "true" ]; then`,
+    `${prefix}      echo "published=skipped" >> "$GITHUB_OUTPUT"`,
+    `${prefix}      exit 0`,
+    `${prefix}    fi`,
+    `${prefix}    if [ "$PRM_PUBLISH_OUTCOME" = "success" ]; then`,
+    `${prefix}      echo "published=true" >> "$GITHUB_OUTPUT"`,
+    `${prefix}    else`,
+    `${prefix}      echo "published=failed" >> "$GITHUB_OUTPUT"`,
+    `${prefix}      exit 1`,
+    `${prefix}    fi`,
+  ];
+  return [...lines, ...record];
+}

package/src/package-coverage.mjs

@@ -16,6 +16,23 @@ export function packageWorkflows(workflows, packageInfo) {
       )
       .filter(Boolean)
       .at(-1);
+  // A step running in a parent directory publishes this package only when
+  // it names it, as in `cargo publish -p name` or a shell function invoked
+  // with the name, or reads its manifest by path.
+  const ancestor = (cwd, child) =>
+    child !== cwd && (cwd === "." || child.startsWith(`${cwd}/`));
+  const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const namesPackage = (text, cwd) => {
+    const relative =
+      cwd === "."
+        ? packageInfo.manifest
+        : packageInfo.manifest.slice(cwd.length + 1);
+    return [packageInfo.name, relative]
+      .filter(Boolean)
+      .some((token) =>
+        new RegExp(`(?<![\\w./-])${escape(token)}(?![\\w-])`).test(text),
+      );
+  };
   return workflows.map((workflow) => {
     const parsed = parseWorkflow(workflow.contents);
     const jobs = parsed.jobs.flatMap((job) => {
@@ -24,11 +41,10 @@ export function packageWorkflows(workflows, packageInfo) {
         const called = job.lines.some((line) =>
           /^\s*uses\s*:\s*["']?\.\/\.github\/workflows\//.test(line),
         );
-        const cwd = working(job.lines) ?? working(parsed.header) ?? ".";
-        return called &&
-          cwd.replace(/^\.\//, "").replace(/\/$/, "") === directory
-          ? [`  ${job.name}:\n${job.lines.join("\n")}`]
-          : [];
+        // A reusable-workflow caller has no steps or working directory of its
+        // own; it carries the OIDC identity of whatever its callee publishes,
+        // and the callee is scoped separately.
+        return called ? [`  ${job.name}:\n${job.lines.join("\n")}`] : [];
       }
       const prefix = job.lines.slice(0, start + 1);
       const blocks = [];
@@ -67,12 +83,20 @@ export function packageWorkflows(workflows, packageInfo) {
           (working(block) ?? cd ?? inferred ?? fallback)
             .replace(/^\.\//, "")
             .replace(/\/$/, "") || ".";
-        return cwd === directory;
+        return (
+          cwd === directory ||
+          (ancestor(cwd, directory) && namesPackage(text, cwd))
+        );
       });
+      // Action-only steps (authentication exchanges such as
+      // crates-io-auth-action) belong to the job that publishes this package.
+      const kept = blocks.filter(
+        (block) =>
+          matching.includes(block) ||
+          !block.some((line) => /^\s*-?\s*run\s*:/.test(line)),
+      );
       return matching.length
-        ? [
-            `  ${job.name}:\n${prefix.join("\n")}\n${matching.flat().join("\n")}`,
-          ]
+        ? [`  ${job.name}:\n${prefix.join("\n")}\n${kept.flat().join("\n")}`]
         : [];
     });
     return {

package/src/plan.mjs

@@ -8,7 +8,7 @@ import {
   pypiFlow,
 } from "./flows.mjs";
 import { credentialPolicy } from "./credential-cycle.mjs";
-import { trustedFlow, tokenFlow } from "./extra-flows.mjs";
+import { packagistSteps, trustedFlow, tokenFlow } from "./extra-flows.mjs";
 import { bootstrapRef } from "./bootstrap-reference.mjs";
 import { pagesSteps } from "./pages.mjs";
 import { planPrerequisites } from "./prerequisites.mjs";
@@ -73,6 +73,22 @@ function buildPlan(inspection, packageInfo, options) {
     };
   }
   const command = (program, args) => ({ program, args });
+  if (
+    (options.migrate || options.addPublishJob) &&
+    packageInfo.publishing_policy === "variable-gated-oidc-with-token-fallback"
+  ) {
+    // The workflow already tries OIDC first and keeps the token fallback; only
+    // the opt-in repository variable is off. Never rewrite the workflow.
+    return basePlan(inspection, packageInfo, [
+      {
+        id: "enable-oidc-variable",
+        title: `Register trust, then set ${packageInfo.authentication_gate?.variable ?? "the OIDC opt-in variable"} to true`,
+        kind: "manual",
+        confirm: true,
+        description: `The workflow exchanges OIDC only when ${packageInfo.authentication_gate?.variable ?? "its repository variable"} is 'true' and otherwise keeps the existing token. Register the trusted publisher for ${packageInfo.workflow ?? "the caller workflow"}, set the variable, and verify the next release selected OIDC; the token fallback is retained.`,
+      },
+    ]);
+  }
   if (
     (options.migrate || options.addPublishJob) &&
     ["crates-io", "npm", "pypi", "nuget"].includes(packageInfo.registry) &&
@@ -159,12 +175,17 @@ function buildPlan(inspection, packageInfo, options) {
           "Strictly validate composer.json before submitting it.",
           command("composer", ["validate", "--strict"]),
         ),
-        browser(
-          "submit-repository",
-          "Submit the repository to Packagist",
-          "Sign in and submit the public VCS repository URL. Packagist reads package versions from tags.",
-          "https://packagist.org/packages/submit",
-        ),
+        ...(packageInfo.exists_on_registry !== true
+          ? [
+              browser(
+                "submit-repository",
+                "Submit the repository to Packagist",
+                "Sign in and submit the public VCS repository URL. Packagist reads package versions from tags.",
+                "https://packagist.org/packages/submit",
+              ),
+            ]
+          : []),
+        ...packagistSteps(packageInfo),
       ];
       break;
     default:

package/src/publication-state.mjs

@@ -67,9 +67,15 @@ export async function versionEvidence(item, document, url, options, getJson) {
       state.latest_version = versions?.at(-1);
       break;
     case "packagist":
+      // p2/<name>.json carries tagged stable releases only (dev branches live
+      // in ~dev.json), so a match is an exact stable tag read back from Packagist.
       versions = document.packages?.[item.name]?.map((value) =>
         value.version.replace(/^v/, ""),
       );
+      state.stable_tag = document.packages?.[item.name]?.find(
+        (value) =>
+          value.version.replace(/^v/, "") === expected?.replace(/^v/, ""),
+      )?.version;
       state.latest_version = document.packages?.[item.name]?.[0]?.version;
       break;
     case "jsr":
@@ -238,6 +244,33 @@ export async function distributionState(item, options, base) {
     } catch {
       /* Non-JSON is unknown. */
     }
+    // Exact module version: the proxy serves @v/<version>.info only once the
+    // tag has been fetched, independent of @latest or a stale list cache.
+    let exact = {};
+    if (item.version && canonicalGoVersion(item.version)) {
+      const evidence = `${base}/${module}/@v/${encodeURIComponent(item.version)}.info`;
+      const info = await read(evidence);
+      let found;
+      try {
+        found = info === null ? null : JSON.parse(info)?.Version;
+      } catch {
+        found = undefined;
+      }
+      exact =
+        found === null
+          ? { version_evidence_url: evidence, manifest_version_exists: false }
+          : found === item.version
+            ? { version_evidence_url: evidence, manifest_version_exists: true }
+            : {
+                version_evidence_url: evidence,
+                version_state: "manifest-version-unknown",
+              };
+      if (exact.manifest_version_exists === false) {
+        exact.version_state = olderVersion(item.version, version)
+          ? "stale-manifest-version"
+          : "manifest-version-absent";
+      }
+    }
     return {
       registry_evidence_url: url,
       ...((!version && !(list === null && latest === null)) ||
@@ -256,6 +289,7 @@ export async function distributionState(item, options, base) {
       ...(validList && tags.length === 0 && version
         ? { version_state: "no-tagged-release" }
         : {}),
+      ...exact,
     };
   }
   return {

package/src/publishers.mjs

@@ -1,4 +1,4 @@
-import { publishingPolicy } from "./publishing-state.mjs";
+import { authenticationFacts, publishingPolicy } from "./publishing-state.mjs";
 import { readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { stripComments, commandPosition } from "./source-code.mjs";
@@ -21,7 +21,10 @@ export const JOB_PATTERNS = new Map([
   ],
   ["jsr", /\bdeno\s+publish\b|\bjsr\s+publish\b/],
   ["docker-hub", /docker\/login-action|\bdocker\s+(?:login|push)\b/],
-  ["maven-central", /\bmvn\s+(?:-\S+\s+)*deploy\b|\bgradle(?:w)?\s+publish\b/],
+  [
+    "maven-central",
+    /(?:\.\/|\b)mvnw?\s+(?:-\S+\s+)*deploy\b|(?:\.\/|\b)gradlew?\s+(?:-\S+\s+)*publish\b/,
+  ],
   ["vscode-marketplace", /\bvsce\s+publish\b/],
   ["open-vsx", /\bovsx\s+publish\b/],
   [
@@ -42,6 +45,20 @@ export const JOB_PATTERNS = new Map([
   ],
 ]);
 
+/**
+ * Registries without an upload command: a release is a tag, a GitHub release
+ * asset or a registry update hook. The evidence is matched anywhere in the
+ * job's executable lines, as the URL is usually an argument.
+ */
+export const RELEASE_EVIDENCE = new Map([
+  ["packagist", /packagist\.org\/api\/(?:update|create)-package/],
+  [
+    "go-modules",
+    /\bgh\s+release\s+create\b|\bgit\s+push\b[^\n]*\btags?\b|proxy\.golang\.org/,
+  ],
+  ["cmake", /\bgh\s+release\s+(?:create|upload)\b/],
+]);
+
 // Scripts usually pass the subcommand as a separate argument, as in
 // `spawnSync("npm", ["publish"])` or `Command::new("cargo")` followed by
 // `.arg("publish")` within the next few lines.
@@ -155,8 +172,25 @@ export async function detectPublisher(root, workflows, registry) {
     ["crates-io", "npm", "pypi", "nuget"].includes(registry) &&
     (result.workflow || result.candidates.length)
   ) {
-    result.policy = await publishingPolicies(root, workflows, registry);
-    if (result.policy !== "oidc-with-token-fallback") {
+    const { policy, gates } = await publishingPolicies(
+      root,
+      workflows,
+      registry,
+    );
+    result.policy = policy;
+    if (gates.length) {
+      result.gate = gates[0].gate;
+      if (gates.some((facts) => facts.passwordAlwaysToken)) {
+        result.warnings.push(
+          `the publish password expression \`vars.${result.gate.variable} == 'true' && '' || secrets.*\` always selects the token ('' is falsy in GitHub expressions); the variable cannot switch to OIDC`,
+        );
+      }
+    }
+    if (result.policy === "variable-gated-oidc-with-token-fallback") {
+      result.warnings.push(
+        `publishing selects OIDC only when the repository variable ${result.gate?.variable ?? "gate"} is 'true' and otherwise uses the token; register the trusted publisher, verify it, then set the variable`,
+      );
+    } else if (result.policy !== "oidc-with-token-fallback") {
       result.warnings.push(
         `publishing authentication is ${result.policy}; migrate to OIDC with token fallback`,
       );
@@ -173,6 +207,7 @@ async function publishingPolicies(root, workflows, registry) {
     ]),
   );
   const policies = [];
+  const gates = [];
   const visit = async (name, callerGrant, seen = new Set()) => {
     if (seen.has(name) || !parsed.has(name)) {
       return;
@@ -196,6 +231,13 @@ async function publishingPolicies(root, workflows, registry) {
       if (called) {
         await visit(called, grant, new Set([...seen, name]));
       } else if (await jobPublishes(root, workflow, job, registry)) {
+        const facts = authenticationFacts(
+          [...workflow.header, ...job.lines].join("\n"),
+          registry,
+        );
+        if (facts.gate) {
+          gates.push(facts);
+        }
         policies.push(
           publishingPolicy(
             [[...workflow.header, ...job.lines].join("\n")],
@@ -212,11 +254,13 @@ async function publishingPolicies(root, workflows, registry) {
     }
   }
   const unique = [...new Set(policies)];
-  return unique.length === 1
-    ? unique[0]
-    : unique.length
-      ? "mixed-authentication"
-      : "authentication-unverified";
+  const policy =
+    unique.length === 1
+      ? unique[0]
+      : unique.length
+        ? "mixed-authentication"
+        : "authentication-unverified";
+  return { policy, gates };
 }
 
 async function detectPublisherDetails(root, workflows, registry) {
@@ -242,6 +286,7 @@ async function detectPublisherDetails(root, workflows, registry) {
         job.lines.find((line) => LOCAL_WORKFLOW.test(line)) ?? "",
       )?.[1];
       const callee = called ? parsedWorkflows.get(called) : null;
+      const chain = [];
       const environments = callee
         ? await calledEnvironments(
             root,
@@ -249,6 +294,7 @@ async function detectPublisherDetails(root, workflows, registry) {
             called,
             registry,
             new Set([workflow.name]),
+            chain,
           )
         : (await jobPublishes(root, parsed, job, registry))
           ? [
@@ -265,6 +311,7 @@ async function detectPublisherDetails(root, workflows, registry) {
         found.push({
           workflow: workflow.name,
           job: job.name,
+          callees: chain,
           idToken:
             grantsIdToken(childBlock(job.lines, indent, "permissions")) ??
             workflowGrant ??
@@ -323,8 +370,10 @@ function described(workflow, found) {
       `the publishing jobs in ${workflow} use different environments (${environments.map((item) => item ?? "none").join(", ")}); pass --environment <name> to choose one`,
     );
   }
+  const callees = [...new Set(jobs.flatMap((item) => item.callees ?? []))];
   return {
     workflow,
+    ...(callees.length ? { callees } : {}),
     jobs: [...new Set(jobs.map((item) => item.job))],
     environment: environments.length === 1 ? environments[0] : null,
     candidates: [],
@@ -372,7 +421,14 @@ export function registryTokenSecrets(registry) {
   return TOKEN_SECRETS.get(registry) ?? [];
 }
 
-async function calledEnvironments(root, workflows, name, registry, visited) {
+async function calledEnvironments(
+  root,
+  workflows,
+  name,
+  registry,
+  visited,
+  chain = [],
+) {
   if (visited.has(name)) {
     return [];
   }
@@ -392,9 +448,12 @@ async function calledEnvironments(root, workflows, name, registry, visited) {
           LOCAL_WORKFLOW.exec(called)[1],
           registry,
           seen,
+          chain,
         )),
       );
     } else if (await jobPublishes(root, parsed, job, registry)) {
+      // Exact reusable-workflow identity: each callee job that publishes.
+      chain.push(`${[...seen].slice(1).join(" -> ")} -> ${job.name}`);
       environments.push(
         environmentName(
           childBlock(job.lines, childIndent(job.lines), "environment"),
@@ -409,6 +468,10 @@ async function calledEnvironments(root, workflows, name, registry, visited) {
 export async function jobPublishes(root, parsed, job, registry) {
   const pattern = JOB_PATTERNS.get(registry);
   const executable = executableLines(job.lines);
+  const evidence = RELEASE_EVIDENCE.get(registry);
+  if (evidence) {
+    return evidence.test(executable.join("\n"));
+  }
   if (publishingLine(executable, pattern)) {
     return true;
   }

package/src/publishing-state.mjs

@@ -40,7 +40,16 @@ export function publishingPolicy(contents, registry, grantOverride) {
         /continue-on-error:\s*true/.test(text)
       : /outcome == 'failure'/.test(text) &&
         /continue-on-error:\s*true/.test(text);
-  if (oidc && token && fallback) {
+  const facts = authenticationFacts(text, registry);
+  if (facts.passwordAlwaysToken) {
+    // `vars.FLAG == 'true' && '' || secrets.TOKEN` always yields the token:
+    // '' is falsy in GitHub expressions, so the flag never selects OIDC.
+    return token ? "token-only" : "authentication-unverified";
+  }
+  if (grant && token && facts.gate && facts.shellFallback) {
+    return "variable-gated-oidc-with-token-fallback";
+  }
+  if ((oidc && token && fallback) || (oidc && token && facts.npmNative)) {
     return "oidc-with-token-fallback";
   }
   return oidc
@@ -49,3 +58,53 @@ export function publishingPolicy(contents, registry, grantOverride) {
       ? "token-only"
       : "authentication-unverified";
 }
+
+/**
+ * Actual credential-selection semantics of a publishing job, kept apart from
+ * publisher registration and historical trusted uploads.
+ */
+export function authenticationFacts(contents, registry) {
+  const text = Array.isArray(contents) ? contents.join("\n") : contents;
+  const facts = {
+    gate: null,
+    shellFallback: false,
+    passwordAlwaysToken: false,
+    npmNative: false,
+  };
+  const steps = text.split(/(?=^[ \t]*- )/m);
+  const auth = steps.find((step) =>
+    registry === "crates-io"
+      ? /crates-io-auth-action@/.test(step)
+      : registry === "nuget"
+        ? /NuGet\/login@/.test(step)
+        : false,
+  );
+  const gate = auth
+    ? /\bif:.*\bvars\.(\w+)\s*==\s*['"]true['"]/.exec(auth)?.[1]
+    : null;
+  if (gate) {
+    facts.gate = { variable: gate, value: "true" };
+  }
+  facts.shellFallback = /\$\{\w*OIDC\w*:-\$\w+\}/.test(text);
+  if (registry === "pypi") {
+    const password = /^\s*password\s*:\s*(.+)$/m.exec(text)?.[1] ?? "";
+    const flag =
+      /vars\.(\w+)\s*==\s*['"]true['"]\s*&&\s*''\s*\|\|\s*secrets\.\w+/.exec(
+        password,
+      );
+    if (flag) {
+      facts.passwordAlwaysToken = true;
+      facts.gate = { variable: flag[1], value: "true", ineffective: true };
+    }
+  }
+  if (registry === "npm") {
+    // npm 11.5.1+ tries the OIDC exchange itself and falls back to the
+    // configured token, so a job with both needs no separate fallback step.
+    facts.npmNative = steps.some(
+      (step) =>
+        /\bnpm\s+publish\b/.test(step) &&
+        /NODE_AUTH_TOKEN\s*:\s*\$\{\{\s*secrets\./.test(step),
+    );
+  }
+  return facts;
+}

package/src/source-code.mjs

@@ -50,7 +50,7 @@ export function stripComments(contents, language = "shell") {
 export function commandPosition(prefix) {
   const segment = prefix.split(/[;&|]/).at(-1).trimStart();
   return (
-    /^(?:(?:npx|bunx|exec|sudo|env|time|command|pnpm\s+exec|yarn|\w+=\S*)\s+)*$/.test(
+    /^(?:(?:if|elif|then|else|do|while|until|!|npx|bunx|exec|sudo|env|time|command|pnpm\s+exec|yarn|\w+=\S*)\s+)*$/.test(
       segment,
     ) ||
     /(?:\$|shell)\s*`\s*$/.test(segment) ||