@entro314labs/release-kit 2.1.0 → 2.2.0

package/README.md

@@ -65,45 +65,70 @@ Released v2.5.0
 
 ## 📦 Install
 
-**As a devDependency** — the normal choice. Updates arrive through your package manager.
+Pick by what the project is, not by preference.
+
+### Node projects — devDependency
+
+Pins the version, so every machine and CI run behave identically.
 
 ```sh
 pnpm add -D @entro314labs/release-kit
 ```
 
 ```json
-{
-  "scripts": {
-    "release": "release-kit"
-  }
-}
+{ "scripts": { "release": "release-kit" } }
+```
+
+### Non-Node projects — global install
+
+A Rust, Python or Go repository has no manifest to hang a devDependency on, so install it
+once and use it everywhere.
+
+```sh
+npm i -g @entro314labs/release-kit
+release-kit minor
 ```
 
-**Without installing** — for a one-off release, or a project you do not want to add a
-dependency to:
+### CI, any language — pinned npx
+
+No global state to drift, no install step, and the version is explicit in the command.
 
 ```sh
-npx @entro314labs/release-kit --dry-run
+npx @entro314labs/release-kit@2.1.0 minor --yes
 ```
 
-**Vendored** — for a project that should not depend on the registry it is about to publish
-to, or one that needs releases to work offline. `--sync` copies the file into
-`scripts/release.mjs`:
+### Vendored — no registry at release time
+
+For a project that should not depend on the registry it is about to publish to, or that
+needs releases to work offline. The file is self-contained, so a copy is a complete install.
 
 ```sh
-npx @entro314labs/release-kit --sync .
+npx @entro314labs/release-kit --sync .        # writes scripts/release.mjs
 ```
 
 ```json
-{
-  "scripts": {
-    "release": "node scripts/release.mjs"
-  }
-}
+{ "scripts": { "release": "node scripts/release.mjs" } }
 ```
 
-All three run the same file. Zero-config works on the conventions below; add a
-[`release.config.json`](#️-configuration) only for what differs.
+### Piped — nothing installed at all
+
+`release.mjs` runs straight from stdin, arguments and all. Useful for a one-off release on a
+machine you do not want to install anything on.
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/entro314-labs/release-kit/v2.1.0/release.mjs \
+  | node - minor --yes
+```
+
+Pin the URL to a tag, never `main`: piping an unpinned remote script into an interpreter
+means whatever is at that URL runs against your repository and your credentials. `--sync` is
+the one thing that does not work this way — copying itself needs a file on disk.
+
+> **All five paths run the same file and need Node 18+.** That includes the Rust, Python and
+> Go projects: `release-kit` is a Node program regardless of what it is releasing.
+
+Zero-config works on the conventions below; add a [`release.config.json`](#️-configuration)
+only for what differs.
 
 ## ⚡ Usage
 
@@ -224,6 +249,7 @@ rather than stopping at the first problem.
 - The remote exists, is reachable, and the branch is not behind it
 - The tag is free — or already exists at `HEAD`, in which case it is reused
 - `gh` is installed and authenticated
+- Commit and tag signing can actually sign, when `commit.gpgsign` or `tag.gpgsign` is on
 - The publishing CLI is authenticated, and the version is not already on the registry
 - Configured release assets exist
 - A changelog section for the version exists _(a warning, not a failure — it falls back
@@ -320,6 +346,23 @@ name, `%d` npm dist-tag. In the `publish` command line the substituted values ar
 shell-quoted, so a version carrying shell metacharacters is passed through as one literal
 argument.
 
+### Signing
+
+Signing is git's, not this tool's: commits and tags are made with plain `git commit` and
+`git tag`, so they are signed exactly when `commit.gpgsign` and `tag.gpgsign` say to, with
+whatever key `user.signingkey` resolves to. There is no key handling here to get wrong.
+
+What it does add is a preflight check, because an unusable key otherwise fails at the commit
+step with the version already written. For CI, where a signing key usually is not present,
+disable signing for that run rather than configuring keys:
+
+```sh
+git -c commit.gpgsign=false -c tag.gpgsign=false release-kit minor --yes
+```
+
+For commits to show as **Verified** on GitHub, the SSH key must be registered as a _signing_
+key in your account, which is a separate list from authentication keys.
+
 ### Publishing and authentication
 
 The registry preflight (`whoami`, the already-published lookup) runs with whichever CLI the
@@ -445,7 +488,8 @@ including a directory that is not a repository.
 
 ## 📋 Requirements
 
-- Node 18+ (uses `node:readline/promises` and `Array.prototype.at`)
+- **Node 18+ — including for Rust, Python and Go projects.** `release-kit` is a Node
+  program whatever it releases; there is no standalone binary.
 - `git`
 - `gh`, authenticated — only when creating GitHub releases
 - Whatever the `publish` command needs — for the default, a live `npm login` session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Single-file, zero-dependency release mechanism for JS/TS/Node projects: version bump, changelog roll, commit, annotated tag, push, publish, GitHub release",
   "keywords": [
     "changelog",

package/release.mjs

@@ -33,7 +33,7 @@
 
 import { execFileSync, execSync } from 'node:child_process'
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
+import { homedir, tmpdir } from 'node:os'
 import { basename, join, relative, resolve, sep } from 'node:path'
 import { createInterface } from 'node:readline/promises'
 
@@ -762,6 +762,15 @@ if (flag('--help') || flag('-h')) {
 // --sync copies this file into other projects and exits; it touches no git state.
 if (flag('--sync')) {
   const self = new URL(import.meta.url).pathname
+  // Piped from stdin (`curl … | node -`) there is no file to copy: import.meta.url points
+  // at a synthetic [eval] path. Say so instead of failing on a missing file.
+  if (!existsSync(self)) {
+    abort(
+      '--sync copies this script from disk, and it was piped from stdin so there is no ' +
+        'file to copy.\n  Run it from an installed copy instead: ' +
+        'npx @entro314labs/release-kit --sync <dir>',
+    )
+  }
   const targets = argv.slice(argv.indexOf('--sync') + 1).filter((a) => !a.startsWith('-'))
   if (!targets.length) abort('--sync needs at least one project directory')
 
@@ -1122,6 +1131,30 @@ if (!succeeds('git', ['remote', 'get-url', config.remote])) {
   }
 }
 
+// Signing is configured per repository and inherited, never managed here — git already
+// owns that. But a signing setup that cannot produce a signature fails at the commit step,
+// after the version has been written, so it is worth catching before anything mutates.
+const signsSomething = ['commit', 'version', 'changelog', 'tag'].some(runs)
+const signingKeys = ['commit.gpgsign', 'tag.gpgsign'].filter(
+  (key) => tryRead('git', ['config', '--get', key]) === 'true',
+)
+if (signsSomething && signingKeys.length) {
+  const format = tryRead('git', ['config', '--get', 'gpg.format']) || 'openpgp'
+  const signingKey = tryRead('git', ['config', '--get', 'user.signingkey'])
+  const keyPath = signingKey?.replace(/^~/, homedir())
+  if (!signingKey) {
+    fail(`${signingKeys.join(' and ')} enabled but user.signingkey is not set`)
+  } else if (format === 'ssh' && /^[~/.]/.test(signingKey) && !existsSync(keyPath)) {
+    fail(
+      `signing key ${signingKey} does not exist.\n` +
+        '       Point user.signingkey at a key that is present, or disable signing for this ' +
+        'run with `git -c commit.gpgsign=false -c tag.gpgsign=false`.',
+    )
+  } else {
+    ok(`signing commits and tags (${format})`)
+  }
+}
+
 const head = tryRead('git', ['rev-parse', 'HEAD'])
 const taggedCommit = tryRead('git', ['rev-list', '-n', '1', tag])
 if (!runs('tag')) {