fix(release): keep npm channels monotonic

.github/workflows/release-cli-stage.yml

@@ -95,6 +95,7 @@ jobs:
           retention-days: 30
       - name: Record the post-staging approval step
         env:
+          RELEASE_DIST_TAG: ${{ steps.release.outputs.dist_tag }}
           RELEASE_VERSION: ${{ steps.release.outputs.version }}
           RELEASE_RUN_ID: ${{ github.run_id }}
           RELEASE_RUN_ATTEMPT: ${{ github.run_attempt }}
@@ -108,6 +109,12 @@ jobs:
             echo "- stage run ID: \`$RELEASE_RUN_ID\`"
             echo "- stage run attempt: \`$RELEASE_RUN_ATTEMPT\`"
             echo "- version: \`$RELEASE_VERSION\`"
+            if [[ "$RELEASE_DIST_TAG" == "latest" ]]; then
+              echo
+              echo "Before finalizing this stable release, inspect npm dist-tags. If \`next\` is older than \`latest\`, authenticate interactively with npm and run:"
+              echo
+              echo "\`npm dist-tag add \"maka-agent@$RELEASE_VERSION\" next --registry https://registry.npmjs.org/\`"
+            fi
           } >> "$GITHUB_STEP_SUMMARY"
       - name: Submit the candidate to npm staging
         env:

docs/cli-npm-release.md

@@ -9,7 +9,9 @@ validated by the Stage workflow.
 ## Release invariants
 
 - Dispatch release workflows only from `main`.
-- Publish prereleases under `next` and stable versions under `latest`.
+- Publish prereleases under `next` and stable versions under `latest`. `next` must never resolve to
+  a version older than `latest`; when no newer prerelease exists, both tags point to the stable
+  version.
 - Use the Git tag `cli-v<version>`; CLI releases never replace the Desktop GitHub Latest release.
 - Do not run `npm publish`. GitHub Actions may only run `npm stage publish`; a human package
   maintainer approves the staged package with npm 2FA.
@@ -118,14 +120,32 @@ npm stage approve "$stage_id" --registry https://registry.npmjs.org/
 The same review and approval can be performed from the package's **Staged Packages** page on
 npmjs.com.
 
+For a stable release, inspect the public tags after approval:
+
+```sh
+version=0.1.0
+npm view maka-agent dist-tags --json --registry https://registry.npmjs.org/
+```
+
+If `next` is absent or older than `latest`, authenticate interactively as an npm package owner and
+advance it to the new stable version before running Finalize:
+
+```sh
+npm dist-tag add "maka-agent@$version" next --registry https://registry.npmjs.org/
+```
+
+Do not change `next` when it already points to a newer version such as `0.2.0-beta.1`. This step is
+intentionally manual: npm Trusted Publishing authenticates `npm publish` and `npm stage publish`,
+not dist-tag mutations, and the release workflows must not gain a long-lived npm token.
+
 ## Finalize the public release
 
 After npm reports the version as public:
 
 1. Open **Actions → Finalize CLI npm release → Run workflow** on `main`.
 2. Enter the successful Stage run ID, its exact run attempt, and the version.
-3. Let the inspection job verify the public tarball bytes, checksum, inventory, dist-tag, npm
-   signature, and Trusted Publishing provenance.
+3. Let the inspection job verify the public tarball bytes, checksum, inventory, npm signature,
+   Trusted Publishing provenance, the release dist-tag, and that `next` is not older than `latest`.
 4. Review and approve the `npm-release` Environment deployment for the Git tag and GitHub Release.
 5. Confirm the workflow created `cli-v<version>` at the Stage source commit. A prerelease must be
    marked prerelease; no CLI release may become the repository's GitHub Latest release.

docs/cli-npm-release.zh-CN.md

@@ -8,7 +8,8 @@
 ## 发布不变量
 
 - 只从 `main` dispatch 发布 workflow；
-- 预发布版本使用 `next`，稳定版本使用 `latest`；
+- 预发布版本使用 `next`，稳定版本使用 `latest`；`next` 不得指向比 `latest` 更旧的版本；没有
+  更新的预发布版本时，两个 tag 都指向稳定版；
 - Git tag 使用 `cli-v<version>`；CLI release 不得替换 Desktop 的 GitHub Latest release；
 - 不运行 `npm publish`。GitHub Actions 只能运行 `npm stage publish`，由人工 package
   maintainer 使用 npm 2FA 批准 staged package；
@@ -114,14 +115,32 @@ npm stage approve "$stage_id" --registry https://registry.npmjs.org/
 
 也可以在 npmjs.com package 的 **Staged Packages** 页面完成相同的检查和批准。
 
+稳定版获得批准后，检查公共 dist-tags：
+
+```sh
+version=0.1.0
+npm view maka-agent dist-tags --json --registry https://registry.npmjs.org/
+```
+
+如果 `next` 不存在或比 `latest` 更旧，使用 npm package owner 身份进行交互式认证，并在运行
+Finalize 前将其推进到新的稳定版：
+
+```sh
+npm dist-tag add "maka-agent@$version" next --registry https://registry.npmjs.org/
+```
+
+如果 `next` 已经指向 `0.2.0-beta.1` 之类的更新版本，则不要修改。此步骤有意保留为人工操作：
+npm Trusted Publishing 只认证 `npm publish` 和 `npm stage publish`，不认证 dist-tag 变更，而
+release workflow 不得获得长期 npm token。
+
 ## Finalize 公共发布
 
 npm 显示该版本已经公开后：
 
 1. 在 `main` 上打开 **Actions → Finalize CLI npm release → Run workflow**；
 2. 输入成功 Stage 的 run ID、精确 run attempt 和 version；
-3. 让 inspection job 验证公共 tarball 字节、checksum、inventory、dist-tag、npm signature 和
-   Trusted Publishing provenance；
+3. 让 inspection job 验证公共 tarball 字节、checksum、inventory、npm signature、Trusted
+   Publishing provenance、发布 dist-tag，并确认 `next` 不比 `latest` 更旧；
 4. 审查并批准用于 Git tag 和 GitHub Release 的 `npm-release` Environment deployment；
 5. 确认 workflow 在 Stage source commit 上创建了 `cli-v<version>`。预发布版本必须标记为
    prerelease；任何 CLI release 都不得成为仓库的 GitHub Latest release。

scripts/release-cli-publication.mjs

@@ -22,30 +22,35 @@ const RELEASE_RECORD_KEYS = [
 ];
 
 export function parseCliReleaseVersion(version) {
-  if (typeof version !== 'string') throw new Error('Expected a valid CLI release version');
-  const match =
-    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/u.exec(
-      version,
-    );
-  if (!match) throw new Error(`Expected a valid CLI release version; found ${version}`);
-  const prerelease = match[4];
-  if (
-    prerelease
-      ?.split('.')
-      .some(
-        (identifier) => /^\d+$/u.test(identifier) && identifier.length > 1 && identifier[0] === '0',
-      )
-  ) {
-    throw new Error(`Expected a valid CLI release version; found ${version}`);
-  }
+  const { prerelease } = parseReleaseSemver(version);
   return {
     version,
-    distTag: prerelease ? 'next' : 'latest',
+    distTag: prerelease.length > 0 ? 'next' : 'latest',
     gitTag: `cli-v${version}`,
     tarball: `${PACKAGE_NAME}-${version}.tgz`,
   };
 }
 
+export function validateRegistryChannels({ releaseVersion, releaseDistTag, distTags }) {
+  if (!distTags || typeof distTags !== 'object' || Array.isArray(distTags)) {
+    throw new Error('Registry package metadata has no valid dist-tags');
+  }
+  if (distTags[releaseDistTag] !== releaseVersion) {
+    throw new Error(`Registry dist-tag ${releaseDistTag} does not point to ${releaseVersion}`);
+  }
+
+  const latest = distTags.latest;
+  const next = distTags.next;
+  if (releaseDistTag === 'latest' && typeof next !== 'string') {
+    throw channelLagError({ releaseVersion, releaseDistTag, latest, next });
+  }
+  if (typeof latest === 'string' && typeof next === 'string') {
+    if (compareReleaseSemver(next, latest) < 0) {
+      throw channelLagError({ releaseVersion, releaseDistTag, latest, next });
+    }
+  }
+}
+
 export function prepareStageRelease({
   repoRoot,
   releaseDirectory,
@@ -122,14 +127,21 @@ export async function fetchRegistryRelease({
 }) {
   const record = loadReleaseRecord(releaseDirectory);
   const versionUrl = `${REGISTRY_ORIGIN}/${PACKAGE_NAME}/${encodeURIComponent(record.version)}`;
-  const metadata = await fetchJson(fetchImpl, versionUrl, 'package version metadata');
+  const metadata = await fetchJson(
+    fetchImpl,
+    versionUrl,
+    'package version metadata',
+    'application/json',
+  );
   if (metadata.name !== PACKAGE_NAME || metadata.version !== record.version) {
     throw new Error('Registry package identity does not match the staged release');
   }
   const tags = await fetchJson(fetchImpl, `${REGISTRY_ORIGIN}/${PACKAGE_NAME}`, 'package metadata');
-  if (tags['dist-tags']?.[record.distTag] !== record.version) {
-    throw new Error(`Registry dist-tag ${record.distTag} does not point to ${record.version}`);
-  }
+  validateRegistryChannels({
+    releaseVersion: record.version,
+    releaseDistTag: record.distTag,
+    distTags: tags['dist-tags'],
+  });
   const tarballUrl = parseRegistryTarballUrl(metadata.dist?.tarball, record.tarball);
   const response = await fetchImpl(tarballUrl, { redirect: 'error' });
   if (!response.ok) {
@@ -304,9 +316,69 @@ function validateSourceIdentity({ sourceSha, runId, runAttempt, repository, work
   }
 }
 
-async function fetchJson(fetchImpl, url, label) {
+function parseReleaseSemver(version) {
+  if (typeof version !== 'string') throw new Error('Expected a valid CLI release version');
+  const match =
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/u.exec(
+      version,
+    );
+  if (!match) throw new Error(`Expected a valid CLI release version; found ${version}`);
+  const prerelease = match[4]?.split('.') ?? [];
+  if (
+    prerelease.some(
+      (identifier) => /^\d+$/u.test(identifier) && identifier.length > 1 && identifier[0] === '0',
+    )
+  ) {
+    throw new Error(`Expected a valid CLI release version; found ${version}`);
+  }
+  return {
+    core: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])],
+    prerelease,
+  };
+}
+
+function compareReleaseSemver(left, right) {
+  const a = parseReleaseSemver(left);
+  const b = parseReleaseSemver(right);
+  for (let index = 0; index < a.core.length; index += 1) {
+    if (a.core[index] < b.core[index]) return -1;
+    if (a.core[index] > b.core[index]) return 1;
+  }
+  if (a.prerelease.length === 0) return b.prerelease.length === 0 ? 0 : 1;
+  if (b.prerelease.length === 0) return -1;
+  for (let index = 0; index < Math.max(a.prerelease.length, b.prerelease.length); index += 1) {
+    const leftIdentifier = a.prerelease[index];
+    const rightIdentifier = b.prerelease[index];
+    if (leftIdentifier === undefined) return -1;
+    if (rightIdentifier === undefined) return 1;
+    if (leftIdentifier === rightIdentifier) continue;
+    const leftNumeric = /^\d+$/u.test(leftIdentifier);
+    const rightNumeric = /^\d+$/u.test(rightIdentifier);
+    if (leftNumeric && rightNumeric) {
+      return BigInt(leftIdentifier) < BigInt(rightIdentifier) ? -1 : 1;
+    }
+    if (leftNumeric) return -1;
+    if (rightNumeric) return 1;
+    return leftIdentifier < rightIdentifier ? -1 : 1;
+  }
+  return 0;
+}
+
+function channelLagError({ releaseVersion, releaseDistTag, latest, next }) {
+  const current = typeof next === 'string' ? next : 'missing';
+  if (releaseDistTag === 'next') {
+    return new Error(
+      `Registry next dist-tag (${current}) is behind latest (${latest}); prerelease ${releaseVersion} cannot advance the next channel`,
+    );
+  }
+  return new Error(
+    `Registry next dist-tag (${current}) is behind the latest release. Before finalizing, authenticate interactively with npm and run: npm dist-tag add "${PACKAGE_NAME}@${releaseVersion}" next --registry ${REGISTRY_ORIGIN}/`,
+  );
+}
+
+async function fetchJson(fetchImpl, url, label, accept = 'application/vnd.npm.install-v1+json') {
   const response = await fetchImpl(url, {
-    headers: { accept: 'application/vnd.npm.install-v1+json' },
+    headers: { accept },
     redirect: 'error',
   });
   if (!response.ok)

scripts/release-cli-publication.test.mjs

@@ -11,6 +11,7 @@ import {
   prepareSignatureAuditTree,
   prepareStageRelease,
   validateGitHubRelease,
+  validateRegistryChannels,
   validateSignatureAudit,
   validateStageRun,
 } from './release-cli-publication.mjs';
@@ -31,6 +32,47 @@ test('release versions map prereleases and stable versions to distinct channels'
   }
 });
 
+test('release channels never leave next behind latest', () => {
+  for (const next of ['0.1.0', '0.2.0-beta.1']) {
+    assert.doesNotThrow(() =>
+      validateRegistryChannels({
+        releaseVersion: '0.1.0',
+        releaseDistTag: 'latest',
+        distTags: { latest: '0.1.0', next },
+      }),
+    );
+  }
+
+  for (const next of [undefined, '0.1.0-beta.1']) {
+    assert.throws(
+      () =>
+        validateRegistryChannels({
+          releaseVersion: '0.1.0',
+          releaseDistTag: 'latest',
+          distTags: { latest: '0.1.0', ...(next ? { next } : {}) },
+        }),
+      /npm dist-tag add "maka-agent@0\.1\.0" next/u,
+    );
+  }
+
+  assert.doesNotThrow(() =>
+    validateRegistryChannels({
+      releaseVersion: '0.2.0-beta.1',
+      releaseDistTag: 'next',
+      distTags: { latest: '0.1.0', next: '0.2.0-beta.1' },
+    }),
+  );
+  assert.throws(
+    () =>
+      validateRegistryChannels({
+        releaseVersion: '0.1.0-beta.2',
+        releaseDistTag: 'next',
+        distTags: { latest: '0.1.0', next: '0.1.0-beta.2' },
+      }),
+    /cannot advance the next channel/u,
+  );
+});
+
 test('stage records bind the checked candidate to one source workflow run', () => {
   const fixture = createCandidate();
   const prepared = prepareStageRelease({
@@ -167,8 +209,8 @@ test('registry downloads stop reading as soon as the tarball exceeds its bound',
   const fallback = registryFetch({ fixture });
   const tarballUrl = `https://registry.npmjs.org/maka-agent/-/${fixture.tarball}`;
   let pulls = 0;
-  const fetchImpl = async (input) => {
-    if (String(input) !== tarballUrl) return fallback(input);
+  const fetchImpl = async (input, options) => {
+    if (String(input) !== tarballUrl) return fallback(input, options);
     return new Response(
       new ReadableStream({
         pull(controller) {
@@ -393,16 +435,18 @@ function registryFetch({ fixture, bytes = fixture.bytes }) {
   const integrity = `sha512-${digest('sha512', bytes, 'base64')}`;
   const shasum = digest('sha1', bytes, 'hex');
   const tarballUrl = `https://registry.npmjs.org/maka-agent/-/${fixture.tarball}`;
-  return async (input) => {
+  return async (input, options = {}) => {
     const url = String(input);
     if (url === `https://registry.npmjs.org/maka-agent/${fixture.version}`) {
+      assert.equal(options.headers?.accept, 'application/json');
       return Response.json({
         name: 'maka-agent',
         version: fixture.version,
         dist: { tarball: tarballUrl, integrity, shasum },
       });
     }
     if (url === 'https://registry.npmjs.org/maka-agent') {
+      assert.equal(options.headers?.accept, 'application/vnd.npm.install-v1+json');
       return Response.json({ 'dist-tags': { next: fixture.version } });
     }
     if (url === tarballUrl) return new Response(bytes);

scripts/release-cli-workflow-policy.test.mjs

@@ -36,6 +36,9 @@ test('stage consumes the validated artifact and makes provenance staging the fin
     /artifact-ids: \$\{\{ needs\.validate\.outputs\.release_candidate_artifact_id \}\}/u,
   );
   assert.match(workflow, /RELEASE_RUN_ATTEMPT/u);
+  const guidance = namedStep(steps, 'Record the post-staging approval step');
+  assert.match(guidance, /if \[\[ "\$RELEASE_DIST_TAG" == "latest" \]\]/u);
+  assert.match(guidance, /npm dist-tag add/u);
   const submit = namedStep(steps, 'Submit the candidate to npm staging');
   assert.equal(steps.at(-1), submit);
   assert.match(submit, /npm stage publish/u);