@hugojosefson/cli 0.11.0 → 0.13.0

package/esm/src/features/changelog-feature.js

@@ -0,0 +1,155 @@
+/** Optional changelog lifecycle that preserves existing release history. */
+import { parseSemver } from "../release/semver.js";
+import { changelogHeadings, changelogLines, } from "../release/changelog-markdown.js";
+const id = "changelog";
+const path = "CHANGELOG.md";
+const subject = { kind: "file", identifier: path };
+export const changelogStarter = "# Changelog\n";
+const resolution = "Automatic repair is unsupported. Make CHANGELOG.md a readable regular file, preserving its history, then inspect it again.";
+async function inspect(context) {
+    const file = await context.files.observe(path);
+    if (file.kind !== "file" && file.kind !== "absent") {
+        throw new Error("CHANGELOG.md is not a readable regular file.");
+    }
+    return file;
+}
+async function detect(context) {
+    try {
+        const file = await inspect(context);
+        let observation = "CHANGELOG.md is absent. Enable --changelog to create it with # Changelog.";
+        if (file.kind === "file") {
+            const headings = changelogHeadings(file.content).filter((heading) => heading.level === 2);
+            const releaseText = headings.flatMap((heading, index) => parseSemver(heading.title)
+                ? [file.content.slice(heading.offset, headings[index + 1]?.offset)]
+                : []).join("\n");
+            const content = changelogLines(releaseText).map((line) => line.text).join("\n");
+            const flat = /^[-*] [a-z][a-z0-9-]*(?:\([\w./@ -]+\))?!?: .+/m.test(content);
+            const grouped = /^### (?:BREAKING CHANGE|Features|Fixes|Other)\r?$/m.test(content);
+            observation = flat
+                ? `CHANGELOG.md contains ${grouped ? "mixed flat and grouped" : "flat"} entries. Existing history is preserved. Optional migration preview: hj changelog migrate.`
+                : grouped
+                    ? "CHANGELOG.md contains grouped release sections. Existing history is preserved."
+                    : file.content === changelogStarter
+                        ? "CHANGELOG.md has an empty starter heading, ready for release entries."
+                        : "CHANGELOG.md exists with custom content. Existing history is preserved.";
+        }
+        return {
+            state: file.kind === "file" ? "enabled" : "disabled",
+            evidence: [{
+                    code: "changelog-observed",
+                    kind: id,
+                    subject,
+                    observation,
+                }],
+        };
+    }
+    catch {
+        const issue = {
+            code: "changelog-unreadable",
+            kind: id,
+            subject,
+            observation: "CHANGELOG.md could not be read as a regular file.",
+            resolution,
+        };
+        return { state: "ambiguous", evidence: [issue], issues: [issue] };
+    }
+}
+async function check(context, enabled) {
+    try {
+        const file = await inspect(context);
+        if ((enabled && file.kind === "file") || (!enabled && file.kind === "absent")) {
+            return {
+                result: "no-op",
+                warnings: [],
+                reason: enabled
+                    ? "Existing CHANGELOG.md is preserved."
+                    : "CHANGELOG.md is absent.",
+            };
+        }
+        if (!enabled && file.kind === "file" && file.content !== changelogStarter) {
+            return {
+                result: "blocked",
+                warnings: [],
+                blockers: [{
+                        code: "changelog-history",
+                        subjects: [subject],
+                        message: "CHANGELOG.md contains history or custom content; automatic deletion is unsupported.",
+                        resolution: "Keep the changelog enabled, or archive its contents and remove CHANGELOG.md manually after disabling dependent release publication.",
+                    }],
+            };
+        }
+        return {
+            result: "allowed",
+            warnings: [],
+            preconditions: [{
+                    kind: "file-digest",
+                    path,
+                    digest: file.kind === "file" ? file.digest : undefined,
+                }],
+        };
+    }
+    catch {
+        return {
+            result: "blocked",
+            warnings: [],
+            blockers: [{
+                    code: "changelog-unreadable",
+                    subjects: [subject],
+                    message: "CHANGELOG.md could not be read as a regular file.",
+                    resolution,
+                }],
+        };
+    }
+}
+async function plan(context, enabled, allowed) {
+    const file = await inspect(context);
+    const checked = await check(context, enabled);
+    if (checked.result !== "allowed") {
+        throw new Error("Changelog operation no longer matches its checked state.");
+    }
+    let changes;
+    if (enabled) {
+        changes = [{
+                kind: "write-file",
+                path,
+                content: changelogStarter,
+                expectedDigest: undefined,
+            }];
+    }
+    else {
+        if (file.kind !== "file") {
+            throw new Error("CHANGELOG.md disappeared during planning.");
+        }
+        changes = [{ kind: "remove-file", path, expectedDigest: file.digest }];
+    }
+    return {
+        featureId: id,
+        action: enabled ? "enable" : "disable",
+        summary: enabled
+            ? "Create CHANGELOG.md with # Changelog."
+            : "Remove the empty CHANGELOG.md starter.",
+        warnings: allowed.warnings,
+        preconditions: allowed.preconditions,
+        changes,
+        validations: [{
+                kind: "feature-redetection",
+                featureId: id,
+                expected: enabled ? "enabled" : "disabled",
+            }],
+    };
+}
+/** Presence, rather than a required style, defines a valid changelog. */
+export const changelogFeature = {
+    metadata: {
+        id,
+        name: "Changelog",
+        summary: "Keep release history, with optional migration from flat entries to grouped sections.",
+    },
+    dependencies: { requires: [] },
+    capabilities: { provides: [], requires: [] },
+    detect,
+    checkEnable: (context) => check(context, true),
+    checkDisable: (context) => check(context, false),
+    planEnable: (context, allowed) => plan(context, true, allowed),
+    planDisable: (context, allowed) => plan(context, false, allowed),
+};

package/esm/src/features/github-ci-artifacts.js

@@ -2,6 +2,8 @@
 import { legacyCiCheckCompatibility } from "./github-ci-legacy.js";
 import { workflowDenoVersion } from "./workflow-toolchain.js";
 import { hjPackageReference } from "./hj-package.js";
+import { githubCiRuntimeMatrix, githubCiRuntimeMatrixMarker, } from "./github-ci-runtime-matrix.js";
+import { denoCacheInputs } from "./github-workflow-cache.js";
 import { inspectArtifact } from "../artifacts/inspect-artifact.js";
 import { workflowCliArtifact } from "./workflow-cli.js";
 export const githubCiFeatureId = "github-ci";
@@ -18,6 +20,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: hj-ci-\${{ github.workflow }}-pr-\${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 jobs:
   check:
     runs-on: ubuntu-latest
@@ -28,7 +34,7 @@ jobs:
       - uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5
         with:
           deno-version: ${workflowDenoVersion}
-      - run: deno task all
+${denoCacheInputs}      - run: deno task all
   hj-release-commit-validation:
     runs-on: ubuntu-latest
     permissions:
@@ -41,7 +47,7 @@ jobs:
       - uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5
         with:
           deno-version: ${workflowDenoVersion}
-      - name: Validate release commits
+${denoCacheInputs}      - name: Validate release commits
         env:
           HJ_RELEASE_ROUTE: source-validation
           HJ_SOURCE_BASE_SHA: \${{ github.event.pull_request.base.sha }}
@@ -82,7 +88,7 @@ jobs:
       - uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5
         with:
           deno-version: ${workflowDenoVersion}
-      - name: Update dependencies
+${denoCacheInputs}      - name: Update dependencies
         env:
           GH_TOKEN: \${{ github.token }}
         run: |
@@ -117,6 +123,14 @@ jobs:
     }];
 /** Render the same exact CI variant for local adoption and remote protection. */
 export function renderGithubCiArtifact(artifact, context, observation) {
+    if (artifact.path === githubCiArtifacts[0].path &&
+        observation.kind === "file" &&
+        observation.content.split("\n").includes(githubCiRuntimeMatrixMarker.trimEnd())) {
+        artifact = {
+            ...artifact,
+            content: githubCiRuntimeMatrix(artifact.content),
+        };
+    }
     const migrated = artifact.path === githubCiArtifacts[0].path &&
         observation.kind === "file" &&
         observation.content.includes("# Retains the git-hj-init required test check.");

package/esm/src/features/github-ci-runtime-matrix.js

@@ -0,0 +1,50 @@
+/** @module Explicit managed CI variant for hj's shared runtime suite. */
+import { nativeNpmCacheStep } from "./github-workflow-cache.js";
+export const githubCiRuntimeMatrixMarker = "# hj-ci-runtime-matrix: deno-node-bun-v1\n";
+/** Retain shared setup and release validation while replacing the check job. */
+export function githubCiRuntimeMatrix(content) {
+    const start = content.indexOf("  check:\n");
+    const end = content.indexOf("  hj-release-commit-validation:\n", start);
+    const setup = content.slice(start, end).split("    steps:\n")[1]
+        .split("      - run: deno task all\n")[0];
+    const upload = (label) => `      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: runtime-report-${label}
+          path: .hj/test-results/${label}.json
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 1
+          overwrite: true
+`;
+    const jobs = `  deno:
+    runs-on: ubuntu-latest
+    steps:
+${setup}      - run: deno task ci-deno
+${upload("deno")}  native:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        runtime: [node24, node26, bun]
+    steps:
+${setup}${nativeNpmCacheStep}      - run: deno run --allow-all scripts/run-test-matrix.ts --runtime \${{ matrix.runtime }}
+${upload("\${{ matrix.runtime }}")}  check:
+    if: \${{ always() }}
+    needs: [deno, native]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require successful checks and every runtime
+        env:
+          DENO_RESULT: \${{ needs.deno.result }}
+          NATIVE_RESULT: \${{ needs.native.result }}
+        run: test "$DENO_RESULT" = success && test "$NATIVE_RESULT" = success
+${setup}      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: runtime-report-*
+          path: .hj/test-results
+          merge-multiple: true
+      - name: Compare complete executed inventories
+        run: deno run --allow-read scripts/run-test-matrix.ts --compare-only
+`;
+    return (content.slice(0, start) + jobs + content.slice(end)).replace("name: CI\n", githubCiRuntimeMatrixMarker + "name: CI\n");
+}

package/esm/src/features/github-release-publish-artifacts.js

@@ -1,6 +1,7 @@
 /** @module Exact workflows owned by release-publication features. */
 import { workflowDenoVersion } from "./workflow-toolchain.js";
 import { hjPackageReference } from "./hj-package.js";
+import { denoCacheInputs, nativeNpmCacheStep, } from "./github-workflow-cache.js";
 import { inspectArtifact } from "../artifacts/inspect-artifact.js";
 import { workflowCliArtifact } from "./workflow-cli.js";
 import { publishGithubWorkflow, publishJsrWorkflow, publishNpmWorkflow, publishTagWorkflow, } from "../release/names.js";
@@ -48,7 +49,7 @@ jobs:
       - uses: ${deno}
         with:
           deno-version: ${workflowDenoVersion}
-      - name: Configure Git authentication
+${denoCacheInputs}${nativeNpmCacheStep}      - name: Configure Git authentication
         env:
           GH_TOKEN: \${{ github.token }}
         run: gh auth setup-git
@@ -59,7 +60,7 @@ jobs:
           HJ_RELEASE_TAG: \${{ inputs.tag }}
         run: >-
           deno run --no-lock
-          --allow-env=PATH,GITHUB_OUTPUT,GITHUB_STEP_SUMMARY,HJ_RELEASE_ROUTE,HJ_RELEASE_TAG,ESBUILD_BINARY_PATH,ESBUILD_WORKER_THREADS
+          --allow-env=PATH,GITHUB_REPOSITORY,GITHUB_OUTPUT,GITHUB_STEP_SUMMARY,HJ_RELEASE_ROUTE,HJ_RELEASE_TAG,ESBUILD_BINARY_PATH,ESBUILD_WORKER_THREADS
           --allow-read=.,/tmp/opencode
           --allow-write=deno.json,deno.jsonc,CHANGELOG.md,/tmp/opencode,"\${GITHUB_OUTPUT}","\${GITHUB_STEP_SUMMARY}"
           --allow-run=deno,git
@@ -83,7 +84,7 @@ jobs:
       - uses: ${deno}
         with:
           deno-version: ${workflowDenoVersion}
-      - name: Configure Git authentication
+${denoCacheInputs}      - name: Configure Git authentication
         env:
           GH_TOKEN: \${{ github.token }}
         run: gh auth setup-git
@@ -140,7 +141,7 @@ ${job === "jsr"
       - uses: ${deno}
         with:
           deno-version: ${workflowDenoVersion}
-${job === "npm"
+${denoCacheInputs}${job === "npm"
             ? `      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
         with:
           node-version: "24"

package/esm/src/features/github-release-publish-feature.js

@@ -1,4 +1,5 @@
 /** @module Lifecycle declarations for generated release publication workflows. */
+import { withNpmReadmeBadge } from "./npm-readme-badge.js";
 import { inspectLegacyRelease } from "./github-release-legacy.js";
 import { checkLegacyReleaseMigration, legacyReleaseCompanionPreconditions, legacyReleaseMigrationChanges, legacyReleaseMigrationSummary, } from "./github-release-legacy-migration.js";
 import { jsrPublishCheckArgs } from "./jsr-package-config.js";
@@ -37,6 +38,10 @@ function releaseFeature(id, name, artifact, requires, options = {}) {
 }
 export const githubReleasePublishTagFeature = releaseFeature(githubReleasePublishTagFeatureId, "GitHub release tag publication", publishTagArtifact, [
     { featureId: "git", reason: "Release publication requires Git." },
+    {
+        featureId: "changelog",
+        reason: "Release publication records changes in CHANGELOG.md.",
+    },
     {
         featureId: "github-repo",
         reason: "Release publication requires GitHub.",
@@ -75,10 +80,10 @@ export const githubReleasePublishGithubFeature = releaseFeature(githubReleasePub
         featureId: githubReleasePublishTagFeatureId,
         reason: "GitHub Releases start after a release tag.",
     }]);
-export const githubReleasePublishNpmFeature = releaseFeature(githubReleasePublishNpmFeatureId, "GitHub npm release publication", publishNpmArtifact, [{
+export const githubReleasePublishNpmFeature = withNpmReadmeBadge(releaseFeature(githubReleasePublishNpmFeatureId, "GitHub npm release publication", publishNpmArtifact, [{
         featureId: githubReleasePublishTagFeatureId,
         reason: "npm publication starts after a release tag.",
-    }]);
+    }]));
 export const githubReleasePublisherFeatures = [
     githubReleasePublishJsrFeature,
     githubReleasePublishGithubFeature,

package/esm/src/features/github-workflow-cache.js

@@ -0,0 +1,18 @@
+/** @module Download caches shared by managed CI and release workflows. */
+import { workflowDenoVersion } from "./workflow-toolchain.js";
+// setup-deno adds OS, architecture and job; its fallback also shares across jobs.
+// Package version metadata is deliberately excluded from dependency cache keys.
+export const denoCacheInputs = `          cache: true
+          cache-hash: deno-${workflowDenoVersion}-\${{ hashFiles('**/deno.lock', 'toolchain.json') }}
+`;
+// Frozen npm ci still validates the locks and installs with scripts disabled.
+// Do not cache the build output or node_modules: test preparation clears them.
+export const nativeNpmCacheStep = `      - name: Cache native test npm downloads
+        if: hashFiles('scripts/test-build/dependencies/package-lock.json') != '' && hashFiles('scripts/test-build/tools/package-lock.json') != ''
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.npm
+          key: native-test-npm-\${{ runner.os }}-\${{ runner.arch }}-\${{ hashFiles('scripts/test-build/dependencies/package-lock.json', 'scripts/test-build/tools/package-lock.json', 'toolchain.json') }}
+          restore-keys: |
+            native-test-npm-\${{ runner.os }}-\${{ runner.arch }}-
+`;

package/esm/src/features/npm-readme-badge.js

@@ -0,0 +1,163 @@
+import { validNpmPublishName } from "../package/npm-name.js";
+import { inspectContribution, npmBadgeImages, } from "../readme/contribution-blocks.js";
+import { inspectDenoConfig } from "./deno-config.js";
+import { isObject, isReadmeTask } from "./deno-tasks.js";
+export const npmBadgeOwner = "github-release-publish-npm";
+export function npmBadge(name) {
+    return {
+        id: `${npmBadgeOwner}:badge`,
+        position: "badges",
+        content: `[![npm Version](https://img.shields.io/npm/v/${name})](https://www.npmjs.com/package/${name})`,
+    };
+}
+/** Use the same explicit Deno-config name that publication verifies in its archive. */
+export async function npmBadgeIdentity(context) {
+    const config = await inspectDenoConfig(context);
+    return config.kind === "config" && validNpmPublishName(config.value.name)
+        ? config.value.name
+        : undefined;
+}
+async function inspect(context) {
+    const config = await inspectDenoConfig(context);
+    const tasks = config.kind === "config" && isObject(config.value.tasks)
+        ? config.value.tasks
+        : {};
+    const build = isReadmeTask(tasks.readme);
+    const path = build ? "readme/README.md" : "README.md";
+    const entry = await context.files.observe(path);
+    const name = await npmBadgeIdentity(context);
+    const text = entry.kind === "file" ? entry.content : "";
+    const desired = npmBadge(name ?? "@unknown/package");
+    const owned = await inspectContribution(text, desired);
+    const npmImages = npmBadgeImages(text);
+    const custom = owned === "absent" && npmImages.length > 0;
+    const compatibleCustom = custom && npmImages.length === 1 &&
+        text.includes(desired.content);
+    const kind = entry.kind !== "file" && entry.kind !== "absent"
+        ? "custom"
+        : owned === "duplicate" || npmImages.length > 1
+            ? "duplicate"
+            : custom && !compatibleCustom
+                ? "custom"
+                : compatibleCustom
+                    ? "exact"
+                    : owned;
+    return {
+        path,
+        name,
+        text,
+        kind,
+        owned,
+        compatibleCustom,
+        missingReadme: entry.kind === "absent",
+    };
+}
+function finding(state, path, observation, resolution) {
+    return {
+        state,
+        evidence: [],
+        issues: [{
+                code: "npm-readme-badge",
+                kind: "readme",
+                subject: { kind: "repository-path", identifier: path },
+                observation,
+                resolution,
+            }],
+    };
+}
+/** Keep publication's existing workflow checks and add badge lifecycle ownership. */
+export function withNpmReadmeBadge(workflow) {
+    return {
+        ...workflow,
+        capabilities: {
+            provides: [],
+            requires: [{
+                    capabilityId: "readme",
+                    reason: "npm publication includes a README version badge.",
+                }],
+        },
+        detect: async (context) => {
+            const current = await workflow.detect(context);
+            if (current.state === "ambiguous")
+                return current;
+            const badge = await inspect(context);
+            if (current.state === "disabled") {
+                if (badge.owned === "exact" || badge.owned === "stale") {
+                    return finding("drifted", badge.path, `The npm publication workflow is absent but ${badge.path} retains its owned npm badge.`, `Disable --github-release-publish-npm to remove its owned badge, or enable it with --repair to restore publication.`);
+                }
+                return current;
+            }
+            if (!badge.name) {
+                return finding("ambiguous", "deno.json|deno.jsonc", "Cannot resolve the npm badge target from one explicit scoped Deno package name.", "Set name in exactly one valid deno.json or deno.jsonc to the npm package published by npm-build. The built archive must use the same name.");
+            }
+            if (badge.kind === "custom" || badge.kind === "duplicate") {
+                return finding("ambiguous", badge.path, `${badge.path} contains ${badge.kind === "duplicate" ? "duplicate" : "custom or conflicting"} npm badge content.`, `Preserve custom text, then replace the conflicting badge with ${npmBadge(badge.name).content}, or remove it before enabling npm publication.`);
+            }
+            if (current.state === "drifted")
+                return current;
+            if (badge.kind !== "exact") {
+                return finding("drifted", badge.path, `The npm version badge for ${badge.name} is ${badge.kind === "absent" ? "missing" : "outdated"} in ${badge.path}.`, `Use --repair to ${badge.kind === "absent" ? "add" : "replace"} the owned npm badge in ${badge.path} with ${npmBadge(badge.name).content}${badge.path.startsWith("readme/") ? " and rebuild README.md." : "."}`);
+            }
+            return {
+                state: "enabled",
+                evidence: [...current.evidence, {
+                        code: "npm-readme-badge",
+                        kind: "readme",
+                        subject: { kind: "repository-path", identifier: badge.path },
+                        observation: `${badge.path} links its ${badge.compatibleCustom ? "custom" : "owned"} npm version badge to https://www.npmjs.com/package/${badge.name}.`,
+                    }],
+            };
+        },
+        checkEnable: async (context) => {
+            const check = await workflow.checkEnable(context);
+            if (check.result === "blocked")
+                return check;
+            const badge = await inspect(context);
+            if (!badge.name) {
+                return blocked("Set an explicit scoped npm package name in exactly one deno.json or deno.jsonc before adding its badge.");
+            }
+            if (badge.kind === "custom" || badge.kind === "duplicate") {
+                return blocked(`Resolve custom or duplicate npm badges in ${badge.path}. Keep custom text and use exactly ${npmBadge(badge.name).content}, or remove the conflicting badge. Custom content will not be overwritten.`);
+            }
+            if (badge.missingReadme &&
+                !context.resolvedChanges.some((change) => change.enabled &&
+                    ["readme-static", "readme-build"].includes(change.featureId))) {
+                return blocked(`Select a README provider to create ${badge.path} for the npm badge.`);
+            }
+            if (badge.kind !== "exact" &&
+                (await workflow.detect(context)).state === "enabled" &&
+                !repairing(context)) {
+                return blocked(`Use --repair to ${badge.kind === "absent" ? "add" : "replace"} the npm badge for ${badge.name} in ${badge.path}.`);
+            }
+            return check.result === "no-op" && badge.kind !== "exact"
+                ? { result: "allowed", warnings: [], preconditions: [] }
+                : check;
+        },
+        checkDisable: async (context) => {
+            const check = await workflow.checkDisable(context);
+            if (check.result !== "no-op")
+                return check;
+            const badge = await inspect(context);
+            return badge.owned === "exact" || badge.owned === "stale"
+                ? { result: "allowed", warnings: [], preconditions: [] }
+                : check;
+        },
+    };
+}
+function repairing(context) {
+    return context.repair?.kind === "all-drifted" ||
+        context.repair?.kind === "features" &&
+            context.repair.featureIds.includes(npmBadgeOwner);
+}
+function blocked(message) {
+    return {
+        result: "blocked",
+        warnings: [],
+        blockers: [{
+                code: "npm-readme-badge",
+                message,
+                subjects: [],
+                resolution: "Resolve the stated README badge or package identity before continuing.",
+            }],
+    };
+}

package/esm/src/features/readme-contribution-plans.js

@@ -1,4 +1,5 @@
 /** @module Compose feature-owned README guides against the final feature plans. */
+import { npmBadge, npmBadgeIdentity, npmBadgeOwner, } from "./npm-readme-badge.js";
 import { fileAccess } from "../repository/file-access.js";
 import { fromFileUrl } from "@jsr/std__path";
 import { packageImports, rewritePackageImport, } from "../readme/package-import.js";
@@ -132,9 +133,23 @@ export async function reconcileReadmePlans(context, plans) {
         github,
         cliPermissions,
     });
+    const npmName = await npmBadgeIdentity(projected);
+    if (active(npmBadgeOwner) && npmName)
+        contributions.push(npmBadge(npmName));
+    const preserveNpmBadge = context.resolvedChanges.find((change) => change.featureId === npmBadgeOwner)
+        ?.enabled !== false &&
+        (!npmName || context.detections.get(npmBadgeOwner)?.state === "ambiguous" ||
+            context.detections.get(npmBadgeOwner) === undefined);
     const provider = build ? "readme-build" : "readme-static";
     // Remove unchanged legacy JSR API blocks before the library adds its block.
-    const owners = [provider, "jsr-package", "deno-cli", "deno-lib", "github-ci"];
+    const owners = [
+        provider,
+        "jsr-package",
+        "deno-cli",
+        "deno-lib",
+        npmBadgeOwner,
+        "github-ci",
+    ];
     const appended = [];
     // File/export ownership belongs to JSR publication. README blocks stay with
     // the feature named in their marker so per-feature commits remain possible.
@@ -144,6 +159,8 @@ export async function reconcileReadmePlans(context, plans) {
     for (const owner of owners) {
         if (owner === "github-ci" && preserveCiBadge)
             continue;
+        if (owner === npmBadgeOwner && preserveNpmBadge)
+            continue;
         const before = files.changes.length;
         const current = await files.read(sourcePath);
         if (current === undefined)

package/esm/src/features/workflow-deno.js

@@ -22,6 +22,6 @@ export function workflowDenoArtifact(artifact, context, observation) {
     const version = validateDenoVersion(selected);
     return {
         ...artifact,
-        content: artifact.content.replaceAll(`deno-version: ${workflowDenoVersion}\n`, `deno-version: ${version}\n`),
+        content: artifact.content.replaceAll(`deno-version: ${workflowDenoVersion}\n`, `deno-version: ${version}\n`).replaceAll(`cache-hash: deno-${workflowDenoVersion}-`, `cache-hash: deno-${version}-`),
     };
 }

package/esm/src/package/npm-name.js

@@ -0,0 +1,5 @@
+/** @module Package identity accepted by the native npm publisher. */
+export function validNpmPublishName(value) {
+    return typeof value === "string" &&
+        /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(value);
+}

package/esm/src/readme/contribution-blocks.js

@@ -70,18 +70,24 @@ export async function reconcileBlocks(text, desired, owner) {
         if (item.position === "badges" &&
             (item.id.startsWith("jsr-package")
                 ? text.includes("[![JSR")
-                : text.includes("[![CI]")))
+                : item.id === "github-ci:badge"
+                    ? text.includes("[![CI]")
+                    : npmBadgeImages(text).length > 0))
             continue;
         const block = await wrap(item);
         if (item.position === "badges") {
             const section = text.search(/^## /m);
             const marker = text.indexOf("<!-- hj:readme ");
             let at = Math.min(section < 0 ? text.length : section, marker < 0 ? text.length : marker);
-            if (item.id === "github-ci:badge") {
-                const jsr = [...text.matchAll(pattern)].find((match) => match[1] === "jsr-package:badges");
-                if (jsr)
-                    at = jsr.index + jsr[0].length;
-            }
+            const order = [
+                "jsr-package:badges",
+                "github-release-publish-npm:badge",
+                "github-ci:badge",
+            ];
+            const earlier = [...text.matchAll(pattern)].filter((match) => order.indexOf(match[1]) >= 0 &&
+                order.indexOf(match[1]) < order.indexOf(item.id)).at(-1);
+            if (earlier)
+                at = earlier.index + earlier[0].length;
             text = insert(text, at, block);
         }
         else {
@@ -108,3 +114,24 @@ function insert(text, at, block) {
     const after = text.slice(at);
     return before + "\n\n" + block + (after ? "\n" + after : "");
 }
+/** Inspect one owned contribution without treating edited bodies as generated. */
+export async function inspectContribution(text, desired) {
+    const matches = [...text.matchAll(pattern)].filter((match) => match[1] === desired.id);
+    const markers = text.split(`<!-- hj:readme ${desired.id} `).length - 1;
+    if (markers > 1)
+        return "duplicate";
+    const match = matches[0];
+    if (!match) {
+        return text.includes(`<!-- hj:readme ${desired.id} `) ? "custom" : "absent";
+    }
+    if (await contributionHash(match[3]) !== match[2])
+        return "custom";
+    return await contributionHash(desired.content) === match[2]
+        ? "exact"
+        : "stale";
+}
+/** Recognize npm badge images without claiming ownership of custom Markdown. */
+export function npmBadgeImages(text) {
+    return [...text.matchAll(/!\[([^\]]*)\]\(([^)\n]+)\)/g)].filter((match) => /^npm(?: version)?$/i.test(match[1]) ||
+        match[2].startsWith("https://img.shields.io/npm/v/")).map((match) => match[0]);
+}