@entro314labs/release-kit 2.2.0 → 2.2.1

package/README.md

@@ -346,6 +346,37 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.2.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,7 +32,14 @@
  */
 
 import { execFileSync, execSync } from 'node:child_process'
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+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'
@@ -1106,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 {
@@ -1118,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`)
@@ -1233,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)
 }
@@ -1418,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}`))}`,
 )