@hugojosefson/cli 0.12.0 → 0.13.0

package/README.md

@@ -2,6 +2,6 @@
 
 Repository tools for Linux x64 glibc. Requires Node.js 24+ or Bun 1.4.2+.
 
-Run `npx @hugojosefson/cli --help` or `bunx --bun @hugojosefson/cli --help`. Ordinary commands run natively. Commands that run Deno project tasks need a compatible Deno executable.
+Run `npx @hugojosefson/cli --help` or `bunx --bun --package @hugojosefson/cli hj --help`. Ordinary commands run natively. Commands that run Deno project tasks need a compatible Deno executable.
 
 See https://github.com/hugojosefson/cli for documentation.

package/esm/deno.js

@@ -1,6 +1,6 @@
 export default {
     "name": "@hugojosefson/cli",
-    "version": "0.12.0",
+    "version": "0.13.0",
     "license": "MIT",
     "hj": {
         "commandName": "hj"

package/esm/hj.js

@@ -0,0 +1,19 @@
+#!/bin/sh
+':' //; if node -e 'process.exit((() => {   if (process.versions.deno) return false;   const name = process.versions.bun ? "bun" : "node";   const match = /^(\d+)\.(\d+)\.(\d+)(?:\+[0-9A-Za-z.-]+)?$/.exec(process.versions[name] || "");   if (!match) return false;   const minimum = {"node":[24,0,0],"bun":[1,4,2]}[name];   for (let index = 0; index < 3; index++) {     const actual = Number(match[index + 1]);     if (actual !== minimum[index]) return actual > minimum[index];   }   return true; })() ? 0 : 1)' >/dev/null 2>&1; then exec node "$0" "$@"; fi; if bun -e 'process.exit((() => {   if (process.versions.deno) return false;   const name = process.versions.bun ? "bun" : "node";   const match = /^(\d+)\.(\d+)\.(\d+)(?:\+[0-9A-Za-z.-]+)?$/.exec(process.versions[name] || "");   if (!match) return false;   const minimum = {"node":[24,0,0],"bun":[1,4,2]}[name];   for (let index = 0; index < 3; index++) {     const actual = Number(match[index + 1]);     if (actual !== minimum[index]) return actual > minimum[index];   }   return true; })() ? 0 : 1)' >/dev/null 2>&1; then exec bun "$0" "$@"; fi; printf '%s\n' 'hj requires Node.js >=24.0.0 or Bun >=1.4.2. Install a supported runtime and add it to PATH.' >&2; exit 127
+import process from "node:process";
+if (!(() => {
+  if (process.versions.deno) return false;
+  const name = process.versions.bun ? "bun" : "node";
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:\+[0-9A-Za-z.-]+)?$/.exec(process.versions[name] || "");
+  if (!match) return false;
+  const minimum = {"node":[24,0,0],"bun":[1,4,2]}[name];
+  for (let index = 0; index < 3; index++) {
+    const actual = Number(match[index + 1]);
+    if (actual !== minimum[index]) return actual > minimum[index];
+  }
+  return true;
+})()) {
+  console.error("hj requires Node.js >=24.0.0 or Bun >=1.4.2. Install a supported runtime and add it to PATH.");
+  process.exit(1);
+}
+await import("./src/cli/cli.js");

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";
@@ -79,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/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/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]);
+}

package/esm/src/release/publish-npm.js

@@ -1,4 +1,5 @@
 /** Independent npm publication of a checked, reproducible build artifact. */
+import { validNpmPublishName } from "../package/npm-name.js";
 import * as fs from "node:fs/promises";
 import { isDeepStrictEqual } from "node:util";
 import { confirmPublication, } from "./confirm-publication.js";
@@ -75,8 +76,7 @@ export async function publishNpm(input) {
         throw new TypeError("npm publication requires a clean release checkout.");
     }
     const config = await versionConfig(input.files, release.version);
-    if (typeof config.name !== "string" ||
-        !/^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(config.name)) {
+    if (!validNpmPublishName(config.name)) {
         throw new TypeError("npm publication requires a scoped package name in Deno config.");
     }
     const tasks = object(config.tasks);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hugojosefson/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Repository tools for Deno, Node.js and Bun.",
   "repository": {
     "type": "git",
@@ -8,12 +8,12 @@
   },
   "license": "MIT",
   "bin": {
-    "hj": "./esm/src/cli/cli.js"
+    "hj": "./esm/hj.js"
   },
-  "gitHead": "ec9fb8eafc9ad315cb90c298a84d93f1384d1254",
+  "gitHead": "47f0f3cdb7ded4b6389f41adf02a78e2926d1733",
   "type": "module",
   "engines": {
-    "node": ">=24",
+    "node": ">=24.0.0",
     "bun": ">=1.4.2"
   },
   "os": [
@@ -29,7 +29,7 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "hjNpmArchive": "hugojosefson-cli-0.12.0.tgz",
+  "hjNpmArchive": "hugojosefson-cli-0.13.0.tgz",
   "_generatedBy": "dnt@0.43.2",
   "files": [
     "esm",