@entro314labs/release-kit 2.1.0 → 2.2.1

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" } }
 ```
 
-**Without installing** — for a one-off release, or a project you do not want to add a
-dependency to:
+### 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
-npx @entro314labs/release-kit --dry-run
+npm i -g @entro314labs/release-kit
+release-kit minor
 ```
 
-**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`:
+### 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 --sync .
+npx @entro314labs/release-kit@2.1.0 minor --yes
+```
+
+### 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 .        # writes scripts/release.mjs
 ```
 
 ```json
-{
-  "scripts": {
-    "release": "node scripts/release.mjs"
-  }
-}
+{ "scripts": { "release": "node scripts/release.mjs" } }
+```
+
+### 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
 ```
 
-All three run the same file. Zero-config works on the conventions below; add a
-[`release.config.json`](#️-configuration) only for what differs.
+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,54 @@ 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.
 
+### Continuous integration
+
+Non-interactive by default: the confirmation prompt is skipped when stdin is not a TTY, and
+`gh` picks up `GITHUB_TOKEN` on its own. Pass `--yes` to be explicit.
+
+```yaml
+- uses: actions/checkout@v5
+  with:
+    fetch-depth: 0 # release notes and the last-tag lookup need real history
+- id: release
+  run: npx @entro314labs/release-kit@2.1.0 minor --yes
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+- run: echo "shipped ${{ steps.release.outputs.tag }} ${{ steps.release.outputs.release-url }}"
+```
+
+On success it writes to `$GITHUB_OUTPUT`, so later steps can act on what happened instead of
+re-deriving it: `version`, `tag`, `name`, `dist-tag`, `steps`, `published`, `release-url`.
+Nothing is written on a dry run, and an unwritable `$GITHUB_OUTPUT` never fails a release
+that already completed.
+
+Three things CI does that are worth knowing about:
+
+- **`fetch-depth: 0`.** The default checkout is a shallow clone, which hides the history
+  release notes are drafted from. It still releases correctly, but the notes describe a
+  fraction of the work, so a shallow clone is called out as a warning.
+- **Detached HEAD.** Tag and pull-request checkouts leave no branch to push, which is a
+  preflight failure rather than a confusing push error.
+- **Signing.** Runners have no signing key, so disable it for the run rather than shipping
+  keys around: `git -c commit.gpgsign=false -c tag.gpgsign=false`.
+
+### 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 +519,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.1",
   "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

@@ -32,8 +32,15 @@
  */
 
 import { execFileSync, execSync } from 'node:child_process'
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
 import { basename, join, relative, resolve, sep } from 'node:path'
 import { createInterface } from 'node:readline/promises'
 
@@ -762,6 +769,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')
 
@@ -1097,11 +1113,21 @@ if (runs('commit') && !assistant) {
 }
 
 const branch = tryRead('git', ['rev-parse', '--abbrev-ref', 'HEAD'])
+// A detached HEAD has no branch to push, and reports itself as the literal "HEAD", which
+// would otherwise be compared against config.branch and pushed as a ref of that name.
+const detached = branch === 'HEAD'
 if (!branch) fail('could not read the current branch')
-else if (config.branch && branch !== config.branch) {
+else if (detached) {
+  fail('HEAD is detached — a release needs a branch to push. Check one out first.')
+} else if (config.branch && branch !== config.branch) {
   fail(`on '${branch}', expected '${config.branch}'`)
 } else ok(`on ${branch}`)
 
+// A shallow clone (CI checkouts default to depth 1) hides the history that release notes
+// and the last-tag lookup are derived from. It still releases correctly; the notes just
+// silently describe a fraction of the work, so say so before that happens.
+const shallow = tryRead('git', ['rev-parse', '--is-shallow-repository']) === 'true'
+
 if (!succeeds('git', ['remote', 'get-url', config.remote])) {
   fail(`no '${config.remote}' remote configured`)
 } else {
@@ -1109,7 +1135,7 @@ if (!succeeds('git', ['remote', 'get-url', config.remote])) {
   // Fetch so the tag and behind-remote checks below see the real remote state.
   if (!succeeds('git', ['fetch', '--quiet', '--tags', config.remote])) {
     fail(`could not fetch from ${config.remote}`)
-  } else if (branch) {
+  } else if (branch && !detached) {
     const upstream = `${config.remote}/${branch}`
     if (!succeeds('git', ['rev-parse', '--verify', '--quiet', `refs/remotes/${upstream}`])) {
       note(`${upstream} does not exist yet — the push will create it`)
@@ -1122,6 +1148,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')) {
@@ -1200,6 +1250,12 @@ function draftNotesFor(v) {
   if (!assistant) return null
   const { lastTag, subjects } = commitsSinceLastTag()
   if (!subjects.length) return null
+  if (shallow) {
+    warn(
+      `shallow clone: only ${subjects.length} commit(s) are visible, so the notes will ` +
+        'describe part of the release. Check out with full history (fetch-depth: 0).',
+    )
+  }
   note(`drafting notes from ${subjects.length} commit(s) with ${assistantName}...`)
   return draftReleaseNotes(v, subjects, lastTag)
 }
@@ -1385,6 +1441,41 @@ if (runs('release') && !releaseExists) {
   mutate('gh', args, notes ? { input: `${notes}\n` } : {})
 }
 
+/**
+ * Hand the result back to whatever is orchestrating this. GitHub Actions reads key=value
+ * pairs from $GITHUB_OUTPUT, so a workflow can gate later steps on what actually happened
+ * rather than re-deriving it from the repository.
+ */
+function emitOutputs() {
+  const file = process.env.GITHUB_OUTPUT
+  if (!file || dryRun) return
+  const releaseUrl = runs('release')
+    ? (tryRead('gh', ['release', 'view', tag, '--json', 'url', '--jq', '.url']) ?? '')
+    : ''
+  const outputs = {
+    version,
+    tag,
+    name: projectName,
+    'dist-tag': distTag,
+    steps: STEPS.filter(runs).join(','),
+    published: String(!!publishCommand && !alreadyPublished),
+    'release-url': releaseUrl,
+  }
+  try {
+    appendFileSync(
+      file,
+      `${Object.entries(outputs)
+        .map(([key, value]) => `${key}=${value}`)
+        .join('\n')}\n`,
+    )
+    note(`wrote ${Object.keys(outputs).length} outputs to $GITHUB_OUTPUT`)
+  } catch {
+    // Outputs are a convenience; never fail a completed release over them.
+  }
+}
+
+emitOutputs()
+
 console.log(
   `\n${green(bold(dryRun ? 'Dry run complete — nothing was changed.' : `Released ${tag}`))}`,
 )