Retry npm release verification on registry lag

Author: xiwuqi

CHANGELOG.md

@@ -4,8 +4,7 @@ All notable changes to ContextForge will be documented in this file.
 
 ## Unreleased
 
-- No unreleased changes tracked yet.
-- The `0.1.0` entry below reflects the prepared release contents. GitHub Release creation and npm publish still happen only after the maintainer dispatches the release workflow successfully.
+- Release automation now retries npm version verification for several minutes after publish so registry propagation delays do not immediately fail the workflow.
 
 ## 0.1.0
 

docs/maintainers/npm-publish-guide.md

@@ -30,6 +30,8 @@ If trusted publishing is not available yet:
 
 The workflow will then publish using token auth instead of trusted publishing.
 
+After a successful publish response, the workflow also retries npm visibility checks for a short window so normal registry propagation delays do not immediately mark the release as failed.
+
 For the first live public release, keep these workflow inputs:
 
 - `version = 0.1.0`

docs/maintainers/release-automation.md

@@ -17,7 +17,8 @@ When configured correctly, the workflow:
 5. optionally syncs GitHub repository metadata from `.github/release/repo-metadata.json`
 6. optionally creates the GitHub Release and uploads the tarball plus checksums
 7. optionally publishes the generated tarball to npm
-8. verifies the release state and prints a compact summary
+8. retries npm visibility checks for a short propagation window after publish
+9. verifies the release state and prints a compact summary
 
 ## Workflow inputs
 
@@ -47,6 +48,12 @@ Secrets:
 - `NPM_TOKEN` only if npm trusted publishing is not configured
 - the public npm package identifier should match `package.json`, currently `@xiwuqi/contextforge`
 
+## npm verification behavior
+
+After `npm publish`, the workflow retries `npm view` verification for a few minutes before failing.
+
+This is intentional because npm registry propagation can lag behind a successful publish response.
+
 ## Source of truth files
 
 - `package.json` for the version

scripts/lib/release-automation.mjs

@@ -1,6 +1,8 @@
 import path from 'node:path';
 
 export const DEFAULT_REPO_METADATA_PATH = '.github/release/repo-metadata.json';
+export const NPM_PUBLISH_VERIFY_MAX_ATTEMPTS = 15;
+export const NPM_PUBLISH_VERIFY_DELAY_MS = 20_000;
 
 export function parseRepoMetadataConfig(raw) {
   let parsed = raw;
@@ -213,6 +215,38 @@ export function buildReleaseSuccessSummary({
   return `${lines.join('\n')}\n`;
 }
 
+export function parseNpmViewVersion(stdout) {
+  const trimmed = stdout.trim();
+  if (trimmed.length === 0) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed);
+    return typeof parsed === 'string' ? parsed : null;
+  } catch {
+    return trimmed.replace(/^"|"$/g, '');
+  }
+}
+
+export function isNpmViewNotFound(stdout = '', stderr = '') {
+  const message = `${stdout}\n${stderr}`.trim().toLowerCase();
+  return message.includes('not found') || message.includes('e404');
+}
+
+export function classifyNpmViewVersionResult({ exitCode, stdout = '', stderr = '', expectedVersion }) {
+  const actualVersion = exitCode === 0 ? parseNpmViewVersion(stdout) : null;
+  const matchesExpectedVersion = actualVersion === expectedVersion;
+  const retryable =
+    (exitCode !== 0 && isNpmViewNotFound(stdout, stderr)) || (exitCode === 0 && !matchesExpectedVersion);
+
+  return {
+    actualVersion,
+    matchesExpectedVersion,
+    retryable,
+  };
+}
+
 export function parseBooleanInput(value, defaultValue = false) {
   if (typeof value === 'boolean') {
     return value;

scripts/release-automation.mjs

@@ -6,14 +6,19 @@ import { constants as fsConstants } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import {
+  NPM_PUBLISH_VERIFY_DELAY_MS,
+  NPM_PUBLISH_VERIFY_MAX_ATTEMPTS,
   DEFAULT_REPO_METADATA_PATH,
+  classifyNpmViewVersionResult,
   buildGhReleaseCreateArgs,
   buildGhRepoEditArgs,
   buildGhTopicsArgs,
   buildNpmPublishArgs,
   buildReleaseSuccessSummary,
   ensureReleaseVersionMatchesPackage,
+  isNpmViewNotFound,
   parseBooleanInput,
+  parseNpmViewVersion,
   parseRepoMetadataConfig,
   relativeRepoPath,
   resolveRepoSlug,
@@ -190,14 +195,11 @@ async function runNpmPublish(options) {
   });
   await runCommand('npm', publishArgs, { cwd: repoRoot, stdio: 'inherit' });
 
-  const verified = await runCommand('npm', ['view', packageIdentifier, 'version', '--json'], {
-    cwd: repoRoot,
-    stdio: 'pipe',
+  await waitForPublishedPackageVersion({
+    packageIdentifier,
+    version,
+    reason: 'npm publish verification',
   });
-  const publishedVersion = parseNpmViewVersion(verified.stdout);
-  if (publishedVersion !== version) {
-    throw new Error(`npm publish verification failed. Expected version "${version}" but found "${publishedVersion}".`);
-  }
 
   console.log(`npm publish verification passed for ${packageIdentifier} on tag "${npmTag}".`);
 }
@@ -240,14 +242,11 @@ async function runVerify(options) {
 
   if (npmPublished) {
     const packageIdentifier = `${packageJson.name}@${version}`;
-    const published = await runCommand('npm', ['view', packageIdentifier, 'version', '--json'], {
-      cwd: repoRoot,
-      stdio: 'pipe',
+    await waitForPublishedPackageVersion({
+      packageIdentifier,
+      version,
+      reason: 'post-release npm verification',
     });
-    const publishedVersion = parseNpmViewVersion(published.stdout);
-    if (publishedVersion !== version) {
-      throw new Error(`Post-release npm verification failed. Expected "${version}" but found "${publishedVersion}".`);
-    }
   }
 
   const summary = buildReleaseSuccessSummary({
@@ -353,18 +352,82 @@ async function readPackageJson() {
   return JSON.parse(await readFile(packageJsonPath, 'utf8'));
 }
 
-function parseNpmViewVersion(stdout) {
-  const trimmed = stdout.trim();
-  if (trimmed.length === 0) {
-    return null;
-  }
+async function waitForPublishedPackageVersion({ packageIdentifier, version, reason }) {
+  let lastResult = null;
 
-  try {
-    const parsed = JSON.parse(trimmed);
-    return typeof parsed === 'string' ? parsed : null;
-  } catch {
-    return trimmed.replace(/^"|"$/g, '');
+  for (let attempt = 1; attempt <= NPM_PUBLISH_VERIFY_MAX_ATTEMPTS; attempt += 1) {
+    const result = await runOptionalCommand('npm', ['view', packageIdentifier, 'version', '--json'], {
+      cwd: repoRoot,
+      stdio: 'pipe',
+    });
+    lastResult = result;
+
+    const classification = classifyNpmViewVersionResult({
+      exitCode: result.code,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      expectedVersion: version,
+    });
+
+    if (classification.matchesExpectedVersion) {
+      return classification.actualVersion;
+    }
+
+    const isLastAttempt = attempt === NPM_PUBLISH_VERIFY_MAX_ATTEMPTS;
+    if (!classification.retryable || isLastAttempt) {
+      throw new Error(
+        buildNpmVerifyFailureMessage({
+          packageIdentifier,
+          version,
+          reason,
+          result,
+          actualVersion: classification.actualVersion,
+        }),
+      );
+    }
+
+    const delaySeconds = Math.floor(NPM_PUBLISH_VERIFY_DELAY_MS / 1000);
+    const notFoundHint = isNpmViewNotFound(result.stdout, result.stderr)
+      ? 'npm registry still reports the package as not found'
+      : `npm registry returned version "${classification.actualVersion ?? 'unknown'}"`;
+    console.log(
+      `${reason} is waiting for npm registry propagation: ${notFoundHint} for ${packageIdentifier} (attempt ${attempt}/${NPM_PUBLISH_VERIFY_MAX_ATTEMPTS}). Retrying in ${delaySeconds}s.`,
+    );
+    await sleep(NPM_PUBLISH_VERIFY_DELAY_MS);
   }
+
+  throw new Error(
+    buildNpmVerifyFailureMessage({
+      packageIdentifier,
+      version,
+      reason,
+      result: lastResult ?? { code: 1, stdout: '', stderr: '' },
+      actualVersion: null,
+    }),
+  );
+}
+
+function buildNpmVerifyFailureMessage({ packageIdentifier, version, reason, result, actualVersion }) {
+  const detail =
+    actualVersion !== null
+      ? `Expected version "${version}" but found "${actualVersion}".`
+      : isNpmViewNotFound(result.stdout, result.stderr)
+        ? `npm registry still does not expose ${packageIdentifier} after ${NPM_PUBLISH_VERIFY_MAX_ATTEMPTS} attempts.`
+        : `npm registry lookup for ${packageIdentifier} failed unexpectedly.`;
+
+  return [
+    `${reason} failed for ${packageIdentifier}. ${detail}`,
+    result.stdout.trim() ? `Stdout:\n${result.stdout.trim()}` : '',
+    result.stderr.trim() ? `Stderr:\n${result.stderr.trim()}` : '',
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
 }
 
 function isGhNotFound(stderr) {

tests/unit/release-automation.test.ts

@@ -1,11 +1,16 @@
 import { describe, expect, it } from 'vitest';
 import {
+  NPM_PUBLISH_VERIFY_DELAY_MS,
+  NPM_PUBLISH_VERIFY_MAX_ATTEMPTS,
   buildGhReleaseCreateArgs,
   buildGhRepoEditArgs,
   buildGhTopicsArgs,
   buildNpmPublishArgs,
   buildReleaseSuccessSummary,
+  classifyNpmViewVersionResult,
   ensureReleaseVersionMatchesPackage,
+  isNpmViewNotFound,
+  parseNpmViewVersion,
   parseRepoMetadataConfig,
   resolveRepoSlug,
   validateChangelogForVersion,
@@ -170,4 +175,47 @@ describe('release automation helpers', () => {
     expect(summary).toContain('Metadata sync ran: yes');
     expect(summary).toContain('npm publish ran: yes');
   });
+
+  it('parses npm view output and classifies propagation-delay retries', () => {
+    expect(parseNpmViewVersion('"0.1.0"')).toBe('0.1.0');
+    expect(
+      classifyNpmViewVersionResult({
+        exitCode: 1,
+        stdout: '',
+        stderr: 'npm ERR! 404 Not Found - GET https://registry.npmjs.org/@xiwuqi%2fcontextforge',
+        expectedVersion: '0.1.0',
+      }),
+    ).toEqual({
+      actualVersion: null,
+      matchesExpectedVersion: false,
+      retryable: true,
+    });
+    expect(isNpmViewNotFound('', 'npm ERR! code E404')).toBe(true);
+    expect(
+      classifyNpmViewVersionResult({
+        exitCode: 0,
+        stdout: '"0.0.9"',
+        stderr: '',
+        expectedVersion: '0.1.0',
+      }),
+    ).toEqual({
+      actualVersion: '0.0.9',
+      matchesExpectedVersion: false,
+      retryable: true,
+    });
+    expect(
+      classifyNpmViewVersionResult({
+        exitCode: 0,
+        stdout: '"0.1.0"',
+        stderr: '',
+        expectedVersion: '0.1.0',
+      }),
+    ).toEqual({
+      actualVersion: '0.1.0',
+      matchesExpectedVersion: true,
+      retryable: false,
+    });
+    expect(NPM_PUBLISH_VERIFY_MAX_ATTEMPTS).toBeGreaterThan(1);
+    expect(NPM_PUBLISH_VERIFY_DELAY_MS).toBeGreaterThan(0);
+  });
 });