@sasjs/release 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 SASjs
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# @sasjs/release
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Simple and safe release management. Releases from conventional commits, for any host. Zero dependencies, one file.
+
+The version is the git tag. Nothing writes a version into `package.json`, nothing commits, nothing pushes to a branch: the tag names the commit that was merged, and the release notes are the commits it covers. GitHub, Gitea, GitLab and a laptop all run the same command.
+
+```bash
+npx @sasjs/release --dry-run          # what it would tag, and the notes
+npx @sasjs/release --tag --push-tag   # cut it
+npx @sasjs/release --tag --host gitlab --release
+```
+
+## Why not a release toolchain
+
+`semantic-release` and `release-please` arrive with a few hundred packages, a plugin per job, and advisories that no one can fix (their copies of `npm`, `glob` and `undici` are bundled inside the tool). This is ~450 lines and installs nothing, so there is nothing to audit and nothing to upgrade. It also does not need a `gh` CLI, `curl`, `jq` or `tea`: the host calls are plain `fetch`.
+
+### What it deliberately does not do
+
+There is no release commit, so **no changelog file is written and `package.json` is not bumped in git**. Both of those mean a runner pushing to the default branch, which means a token with bypass on a protected branch, which is the permission that is hardest to justify and easiest to get wrong.
+
+- **The changelog is the release page.** It is generated from the commits the tag covers, on every run, from git alone.
+- If a file is wanted anyway, it does not have to be in git: attach the notes as an asset (`--notes-file NOTES.md --asset NOTES.md`), or generate the file at docs-build time from `git log <prev>..<tag>` - the same data, no write.
+- **`package.json` is stamped in the publishing job, not in the repository**: `npm version "${TAG#v}" --no-git-tag-version` before `npm publish`. The tarball carries the right version and nothing is committed.
+- The committed `package.json` therefore says `0.0.0` - meaning unset, not stale. A version there would be a claim the repository cannot keep true, since updating it is the commit this design refuses. `prepublishOnly` refuses to publish while the version is still `0.0.0`, so a hand-run publish fails loudly instead of putting `0.0.0` on the registry.
+- Consequence: installing **from git** (`npm i github:sasjs/release`) or packing outside CI gives `0.0.0`. Install from the registry, or use the action at a pinned commit, which is what a consumer wants anyway.
+
+Two things it does that the toolchain cannot:
+
+- **A failed release is re-runnable.** If a run dies after the tag is cut - the push rejected, the API down, the runner killed - re-running with the same flags finishes it. The tag is reused instead of refused, and the notes are rebuilt from the commits the tag covers.
+- **Nothing lands on your default branch.** No release commit, no `package.json` bump, no second push for the tag, so no protected-branch or app-token dance.
+
+## Options
+
+| Option | Meaning |
+| --- | --- |
+| `--repo-dir <path>` | repository to work in (default: cwd) |
+| `--tag-prefix <p>` | prefix before the version in the tag (default `v`) |
+| `--since <ref>` | count commits after this ref (default: newest prefixed tag) |
+| `--paths <a,b>` | only commits touching these paths - monorepos |
+| `--level <l>` | force `patch`, `minor` or `major` instead of classifying |
+| `--prerelease <id>` | cut `<version>-<id>.1`, or continue the last one (`beta.2` -> `beta.3`) |
+| `--dry-run` | say what it would do; write nothing, send nothing |
+| `--notes-file <path>` | write the release notes here |
+| `--output <path>` | append `released`, `version`, `tag`, `level` as `key=value` |
+| `--tag` | create the annotated tag (reused when it already names HEAD) |
+| `--push-tag` | push the tag to `origin` |
+| `--host <h>` | `none` (default), `github`, `gitea`, `gitlab` |
+| `--release` | create the release on the host |
+| `--repo <owner/name>` | repository on the host (default: from the git remote) |
+| `--api-url <url>` | host API base, for a self-hosted instance |
+| `--token-env <NAME>` | environment variable holding the token |
+| `--asset <path>` | file to attach (repeatable; GitHub and Gitea upload it) |
+| `--asset-link <n=url>` | link to attach (repeatable; the only asset shape GitLab has) |
+
+Exit codes: `0` released or nothing to release, `2` usage, git or host error.
+
+The result is printed as `key=value` lines, so a pipeline can feed it to whatever variable protocol it has - `$GITHUB_OUTPUT`, `$GITHUB_ENV`, a dotenv artifact, nothing at all - with `--output`.
+
+## Permissions
+
+The whole release is one credential: a token that may write contents on the repository. No branch is written, nothing is committed, and no workflow-file change is involved.
+
+| What | Permission | Why it is needed |
+| --- | --- | --- |
+| Create the release | `contents: write` (GitHub, Gitea), Developer or the job token (GitLab) | creating a release is a write on the repository |
+| Create the tag | the same grant | the forge creates the tag from `target_commitish` (GitHub, Gitea) or `ref` (GitLab), so the job needs no git credentials and does not run `git push` |
+| Upload assets | the same grant | attached to the release |
+| `npm publish` with OIDC | `id-token: write` | stays in the calling workflow, so provenance names the package's own repository |
+
+A release therefore needs **one** call and no checkout credentials at all:
+
+```bash
+# the host creates the tag at this commit and the release in one call
+npx @sasjs/release --host github --release
+```
+
+`--tag --push-tag` exists for the case where the tag must exist before the release does - building artefacts from it in a later job, for instance - and it costs a git credential. The minimal path does not use it.
+
+A `permissions` block that grants `contents: write` to the release job is the same grant the release toolchain already asks for; what is lost is the app token that exists only to push a release commit.
+
+## The version rule
+
+`feat` is a minor, `fix`/`perf`/`refactor` a patch, `!` or a `BREAKING CHANGE:` footer a major - except before 1.0.0, where a breaking change is the minor. Anything else (`docs:`, `chore:`, `ci:`) is not a release, and if nothing classifies the tool says so and exits 0. `--level` covers a repository whose history is not conventionally formatted.
+
+## GitHub
+
+The repository ships a composite action, so a workflow is a step rather than a script:
+
+```yaml
+permissions:
+  contents: write # the tag and the release
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@<sha>
+        with:
+          fetch-depth: 0 # the range is classified from tags; a shallow clone sees one commit
+      - uses: sasjs/release@<sha>
+        with:
+          args: --tag --push-tag --host github --release
+        env:
+          GH_TOKEN: ${{ github.token }}
+```
+
+`fetch-depth: 0` is not optional: with a shallow clone there are no tags, every commit looks unreleased, and the version is invented.
+
+## Gitea
+
+Gitea Actions runs the same action, but the token and API base come from Gitea:
+
+```yaml
+- uses: sasjs/release@<sha>
+  with:
+    args: --tag --push-tag --host gitea --release --api-url ${{ gitea.server_url }}/api/v1
+  env:
+    GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+```
+
+A tag created by the Actions user does not fire `on: push: tags` on Gitea, so any workflow that should react to a release (docs, a demo site) has to be dispatched from the same job.
+
+## GitLab
+
+No action syntax, so call the package directly. On a self-hosted instance, point `--api-url` at it:
+
+```yaml
+release:
+  image: node:22
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  script:
+    - npx --yes @sasjs/release --host gitlab --release
+        --api-url "$CI_API_V4_URL" --repo "$CI_PROJECT_PATH"
+        --token-env CI_JOB_TOKEN --output release.env
+        --asset-link "app.zip=$CI_PROJECT_URL/-/jobs/artifacts/$CI_COMMIT_SHA/download?job=build"
+  artifacts:
+    reports:
+      dotenv: release.env
+  variables:
+    GIT_DEPTH: '0' # GitLab clones 20 commits deep by default
+```
+
+GitLab releases carry links rather than uploaded files, which is what `--asset-link` is for; the usual link is the job artifact of the build that just ran. GitLab does not accept `Authorization: Bearer`, so the token goes in `PRIVATE-TOKEN`, or in `JOB-TOKEN` when it is `$CI_JOB_TOKEN` - which needs no personal token at all. `--token-header` overrides the choice.
+
+## Adapters
+
+`publish()` has one small function per host, because the shapes genuinely differ:
+
+- **GitHub** - `POST /repos/{repo}/releases`, then each asset to the `upload_url` in the response (with the `{?name,label}` template stripped).
+- **Gitea** - `POST {api}/repos/{repo}/releases`, multipart to `.../releases/{id}/assets`, and a `PATCH` for the body, because Gitea stores what it is given.
+- **GitLab** - `POST {api}/projects/{path}/releases` with `ref` (the tag is created from it when missing), then `.../releases/{tag}/assets/links` per link.
+
+A new host is one function plus an entry in `HOSTS`.
+
+## Development
+
+```bash
+npm test   # node --test: 22 tests, fixture repositories and a stub host
+```
+
+The fixtures are real git repositories built per test, so the bump rules, the tag prefix, the path filter, prereleases and the re-run path are exercised against git rather than a mock. The host adapters are exercised against a stub HTTP server that records the requests.

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@sasjs/release",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Host-neutral releases from conventional commits: version, notes, tag, release. Zero dependencies.",
+  "license": "ISC",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "sasjs-release": "./release.mjs"
+  },
+  "files": [
+    "release.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node -e \"const v=require('./package.json').version; if (v === '0.0.0') { console.error('refusing to publish 0.0.0: the version is stamped from the tag (npm version <tag> --no-git-tag-version)'); process.exit(1) }\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sasjs/release.git"
+  },
+  "keywords": [
+    "release",
+    "semantic-release",
+    "conventional-commits",
+    "sasjs"
+  ],
+  "private": false
+}

package/release.mjs

@@ -0,0 +1,500 @@
+#!/usr/bin/env node
+/**
+ * Decide and cut a release from conventional commits.
+ *
+ * The version is the git tag. Nothing in this script writes a version into
+ * package.json, commits, or pushes to a branch: the tag names the commit that
+ * was merged, and the release notes are the commits it covers. That removes the
+ * release commit, the branch push and the retry-outs that come with it.
+ *
+ * Host-neutral by construction: the git side (classify, version, notes, tag)
+ * needs nothing but git, and the release side talks to an API over plain
+ * https, so GitHub, Gitea, GitLab and anything with the same shape work
+ * without a CLI installed. `--host none` does the git work only.
+ *
+ *     sasjs-release --dry-run
+ *     sasjs-release --tag --push-tag --host github --release
+ *     sasjs-release --tag --host gitlab --release --asset-link "app.zip=$URL"
+ *
+ * Exit 0: released, or nothing to release (`released=false` in --output).
+ * Exit 2: usage, git or host error; nothing is tagged when this is returned
+ * before the tag step, and the tag alone exists when it is returned after.
+ */
+import { execFileSync } from 'node:child_process'
+import { readFileSync, writeFileSync, appendFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+const LEVELS = { major: 3, minor: 2, patch: 1 }
+
+const HELP = `sasjs-release - releases from conventional commits
+
+  --repo-dir <path>      repository to work in (default: cwd)
+  --tag-prefix <p>       prefix before the version in the tag (default: v)
+  --since <ref>          count commits after this ref (default: newest prefixed tag)
+  --paths <a,b>          only commits touching these paths (monorepos)
+  --level <l>            force patch|minor|major instead of classifying
+  --prerelease <id>      cut <version>-<id>.1 (or continue the last one)
+  --dry-run              say what it would do; write nothing, send nothing
+  --notes-file <path>    write the release notes here
+  --output <path>        append key=value lines: released, version, tag, level
+  --tag                  create the annotated tag (reused if it is already here)
+  --push-tag             push the tag to origin
+  --host <h>             none|github|gitea|gitlab (default: none)
+  --release              create the host release (github/gitea/gitlab)
+  --repo <owner/name>    repository on the host (default: from the remote)
+  --api-url <url>        host API base (default: per host)
+  --token-env <NAME>     environment variable holding the token
+  --token-header <h>     which header carries it (default: per host)
+  --asset <path>         file to upload to the release (repeatable)
+  --asset-link <n=url>   link to attach to the release (repeatable)
+  --title <text>         release title (default: the tag)
+  --help                 this text
+`
+
+const flag = (name) => process.argv.includes(`--${name}`)
+
+const arg = (name, fallback = '') => {
+  const at = process.argv.indexOf(`--${name}`)
+  if (at === -1) return fallback
+  const value = process.argv[at + 1]
+  if (value === undefined || value.startsWith('--')) fail(`--${name} needs a value`)
+  return value
+}
+
+const args = (name) =>
+  process.argv.reduce((all, token, index) => {
+    if (token === `--${name}`) {
+      const value = process.argv[index + 1]
+      if (value === undefined || value.startsWith('--'))
+        fail(`--${name} needs a value`)
+      all.push(value)
+    }
+    return all
+  }, [])
+
+function fail(message) {
+  console.error(`sasjs-release: ${message}`)
+  process.exit(2)
+}
+
+// stderr is captured rather than inherited: several probes (a missing `origin`,
+// an absent tag) are expected to fail, and their noise is not a finding
+const git = (cwd, ...argv) =>
+  execFileSync('git', argv, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim()
+
+const attempt = (fn) => {
+  try {
+    return fn()
+  } catch {
+    return ''
+  }
+}
+
+/** The commit range to classify: after the newest tag carrying our prefix. */
+const latestTag = (cwd, prefix) =>
+  attempt(() =>
+    git(cwd, 'describe', '--tags', '--abbrev=0', '--match', `${prefix}[0-9]*`)
+  )
+
+/** Subject and body per commit, newest last. NUL and 0x01 separate the fields. */
+function commits(cwd, from, paths, to = 'HEAD') {
+  const range = from ? `${from}..${to}` : to
+  const raw = attempt(() =>
+    git(cwd, 'log', range, '--pretty=format:%s%x00%b%x01', '--', ...paths)
+  )
+  if (!raw) return []
+  return raw
+    .split('\x01')
+    .filter(Boolean)
+    .map((entry) => {
+      const [subject, body = ''] = entry.split('\x00')
+      return { subject: subject.trim(), body: body.trim() }
+    })
+}
+
+const SUBJECT = /^([a-z]+)(\([^)]*\))?(!)?:\s*(.+)$/i
+const TYPES = { feat: 'feat', fix: 'fix', perf: 'perf', refactor: 'refactor' }
+const TITLES = {
+  breaking: 'BREAKING CHANGES',
+  feat: 'Features',
+  fix: 'Bug Fixes',
+  perf: 'Performance',
+  refactor: 'Refactors'
+}
+
+function classify({ subject, body }) {
+  const match = subject.match(SUBJECT)
+  if (!match) return { type: 'other', breaking: false, text: subject }
+  const [, type, , bang, text] = match
+  return {
+    type: type.toLowerCase(),
+    breaking: Boolean(bang) || /^BREAKING[ -]CHANGE:/m.test(body),
+    text: text.trim()
+  }
+}
+
+/** The stable part of a tag's version, so a prerelease base still bumps. */
+const stable = (version) => version.split('-')[0]
+
+function bump(base, level) {
+  const [major, minor, patch] = stable(base).split('.').map(Number)
+  if (level === 'major') return `${major + 1}.0.0`
+  if (level === 'minor') return `${major}.${minor + 1}.0`
+  return `${major}.${minor}.${patch + 1}`
+}
+
+/**
+ * A prerelease continues the last prerelease of the same base version, so
+ * re-running before the stable cut moves beta.1 -> beta.2 rather than
+ * producing a second beta.1.
+ */
+function bumpPrerelease(base, id, previous) {
+  base = stable(base)
+  if (previous) {
+    const match = previous.match(/^(\d+)\.(\d+)\.(\d+)-([^.]+)\.(\d+)$/)
+    if (match) {
+      const [, major, minor, patch, previousId, n] = match
+      const at = `${major}.${minor}.${patch}`
+      const next = Number(n) + 1
+      if (at === base && previousId === id) return `${base}-${id}.${next}`
+      return `${base}-${id}.1`
+    }
+  }
+  return `${base}-${id}.1`
+}
+
+/** https://host/owner/repo from any remote form, so notes can link to diffs. */
+function remoteUrl(cwd) {
+  const raw = attempt(() => git(cwd, 'remote', 'get-url', 'origin'))
+  if (!raw) return ''
+  const match = raw.match(/^(?:[\w-]+:\/\/)?(?:[^@/]+@)?([^:/]+)[:/](.+?)(?:\.git)?$/)
+  if (!match) return ''
+  const [, host, path] = match
+  return `https://${host}/${path.replace(/\.git$/, '')}`
+}
+
+function notes(version, parsed, previous, repo, date) {
+  const link = repo
+    ? previous
+      ? `${repo}/compare/${previous}...v${version}`
+      : `${repo}/releases/tag/v${version}`
+    : ''
+  const groups = { breaking: [], feat: [], fix: [], perf: [], refactor: [] }
+  for (const commit of parsed) {
+    if (commit.breaking) groups.breaking.push(commit)
+    if (commit.type in TYPES) groups[commit.type].push(commit)
+  }
+
+  const heading = link ? `## [${version}](${link})` : `## ${version}`
+  const lines = [`${heading}${date ? ` (${date})` : ''}`, '']
+  for (const key of Object.keys(TITLES)) {
+    if (!groups[key].length) continue
+    lines.push(`### ${TITLES[key]}`, '')
+    for (const commit of groups[key]) lines.push(`* ${commit.text}`)
+    lines.push('')
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Multipart without dependencies: node's own FormData and Blob, so an asset
+ * upload needs no curl on the runner and no library in the tree.
+ */
+async function upload(url, headers, file, field) {
+  const body = new FormData()
+  const bytes = readFileSync(file)
+  body.append(field, new Blob([bytes]), basename(file))
+  const response = await request(url, { method: 'POST', headers, body })
+  return response
+}
+
+/**
+ * Each forge spells its credential differently, and getting this wrong is a
+ * 401 that looks like a permissions problem: GitHub and Gitea take an
+ * Authorization scheme, GitLab takes its own header and rejects Bearer. A
+ * GitLab job token works too - it needs no personal token at all.
+ */
+function authHeaders(host, token, header) {
+  if (!token) return {}
+  if (host === 'gitlab')
+    return { [header || (process.env.CI_JOB_TOKEN === token ? 'job-token' : 'private-token')]: token }
+  return { authorization: host === 'gitea' ? `token ${token}` : `Bearer ${token}` }
+}
+
+async function request(url, { method = 'GET', headers = {}, body, json } = {}) {
+  headers = { accept: 'application/json', ...headers }
+  if (json !== undefined) headers['content-type'] = 'application/json'
+
+  const response = await fetch(url, {
+    method,
+    headers,
+    body: json !== undefined ? JSON.stringify(json) : body
+  })
+
+  const text = await response.text()
+  if (!response.ok)
+    fail(`${method} ${url} answered ${response.status}: ${text.slice(0, 500)}`)
+  return text ? JSON.parse(text) : {}
+}
+
+const HOSTS = {
+  github: {
+    api: 'https://api.github.com',
+    token: 'GH_TOKEN'
+  },
+  gitea: {
+    api: '',
+    token: 'GITEA_TOKEN'
+  },
+  gitlab: {
+    api: 'https://gitlab.com/api/v4',
+    token: 'GITLAB_TOKEN'
+  }
+}
+
+/**
+ * Create (or find) the release and attach what was asked for. Each host is a
+ * small function because the shapes genuinely differ: GitHub needs a separate
+ * upload endpoint, Gitea posts multipart to its own asset URL, and GitLab has
+ * no asset upload at all - a release carries links, which is why --asset-link
+ * exists.
+ */
+async function publish({ host, api, token, header, repo, tag, body, title, files, links, commit }) {
+  const headers = authHeaders(host, token, header)
+  const encoded = repo.replace('/', '%2F')
+
+  if (host === 'github') {
+    const base = api || HOSTS.github.api
+    // target_commitish is what makes the tag exist at all: the API creates it
+    // when tag_name is new, so the job needs no git credentials and never
+    // pushes to the repository. Unused when the tag is already there.
+    const release = await request(`${base}/repos/${repo}/releases`, {
+      method: 'POST',
+      headers,
+      json: { tag_name: tag, target_commitish: commit, name: title, body }
+    })
+    for (const file of files) {
+      const url = String(release.upload_url).replace(/\{.*$/, '')
+      await upload(`${url}?name=${encodeURIComponent(basename(file))}`, headers, file, 'file')
+    }
+    return release
+  }
+
+  if (host === 'gitea') {
+    if (!api) fail('--host gitea needs --api-url (https://your-host/api/v1)')
+    const release = await request(`${api}/repos/${repo}/releases`, {
+      method: 'POST',
+      headers,
+      json: { tag_name: tag, target_commitish: commit, name: title, body, draft: false }
+    })
+    for (const file of files) {
+      await upload(
+        `${api}/repos/${repo}/releases/${release.id}/assets?name=${encodeURIComponent(basename(file))}`,
+        headers,
+        file,
+        'attachment'
+      )
+    }
+    if (body !== release.body) {
+      await request(`${api}/repos/${repo}/releases/${release.id}`, {
+        method: 'PATCH',
+        headers,
+        json: { body }
+      })
+    }
+    return release
+  }
+
+  if (host === 'gitlab') {
+    const base = api || HOSTS.gitlab.api
+    // GitLab is the same shape: `ref` is what creates the tag when tag_name is
+    // new, and without it the call fails on a tag that does not exist yet.
+    const release = await request(`${base}/projects/${encoded}/releases`, {
+      method: 'POST',
+      headers,
+      json: { name: title, tag_name: tag, ref: commit, description: body }
+    })
+    for (const link of links) {
+      await request(`${base}/projects/${encoded}/releases/${encodeURIComponent(tag)}/assets/links`, {
+        method: 'POST',
+        headers,
+        json: { name: link.name, url: link.url }
+      })
+    }
+    return release
+  }
+
+  fail(`unknown --host ${host}`)
+}
+
+async function main() {
+  if (flag('help')) {
+    console.log(HELP)
+    return
+  }
+
+  const cwd = arg('repo-dir', process.cwd())
+  const prefix = arg('tag-prefix', 'v')
+  const dry = flag('dry-run')
+  const host = arg('host', 'none')
+  const prerelease = arg('prerelease')
+  const forcedLevel = arg('level')
+  const paths = arg('paths') ? arg('paths').split(',').filter(Boolean) : []
+
+  if (forcedLevel && !(forcedLevel in LEVELS)) fail('--level must be patch, minor or major')
+  if (host !== 'none' && !(host in HOSTS)) fail('--host must be none, github, gitea or gitlab')
+
+  const since = arg('since')
+  // an unresolvable --since used to read as "nothing to release", which is the
+  // worst possible answer: a shallow clone or a typo would silently ship no
+  // release. Name the ref instead.
+  if (since && !attempt(() => git(cwd, 'rev-parse', '-q', '--verify', `${since}^{commit}`)))
+    fail(`--since ${since} is not a commit in this repository (a shallow clone needs a full fetch)`)
+
+  const previous = since || latestTag(cwd, prefix)
+  const head = git(cwd, 'rev-parse', 'HEAD')
+  const atHead = (ref) =>
+    Boolean(ref) && attempt(() => git(cwd, 'rev-parse', '-q', '--verify', `${ref}^{commit}`)) === head
+
+  const parsed = commits(cwd, arg('since') ? arg('since') : previous, paths).map(classify)
+  const releasable = parsed.filter((c) => c.breaking || c.type in TYPES)
+
+  /**
+   * A run can end after the tag is cut - the push rejected, the release API
+   * down, the runner killed - and the tag then names the commit while nothing
+   * else exists. `--tag`, `--push-tag` and `--release` are all idempotent, so
+   * that state is finished rather than reported as "nothing to release", which
+   * is what makes a failure re-runnable instead of a hand repair.
+   */
+  const finishing =
+    !releasable.length &&
+    !forcedLevel &&
+    (flag('tag') || flag('push-tag') || flag('release')) &&
+    atHead(previous)
+
+  if (!releasable.length && !forcedLevel && !finishing) {
+    console.log(`nothing to release since ${previous || 'the first commit'}`)
+    output({ released: false })
+    return
+  }
+
+  const base = previous.replace(new RegExp(`^${prefix}`), '') || '0.0.0'
+  // A breaking change is a major, except before 1.0.0 where it is the minor -
+  // the convention every pre-1.0 tool in this space follows.
+  const level =
+    forcedLevel ||
+    (releasable.some((c) => c.breaking)
+      ? Number(base.split('.')[0]) === 0
+        ? 'minor'
+        : 'major'
+      : releasable.some((c) => c.type === 'feat')
+        ? 'minor'
+        : 'patch')
+
+  // A tag that is already a prerelease names a version that has not shipped,
+  // so the target does not move again: beta.2 plus a fix is beta.3, not
+  // 1.8.1-beta.1.
+  const inPrerelease = /^\d+\.\d+\.\d+-[^.]+\.\d+$/.test(base)
+  const target = inPrerelease ? stable(base) : bump(base, level)
+  const version = finishing
+    ? base
+    : prerelease
+      ? bumpPrerelease(target, prerelease, base)
+      : target
+  const tag = finishing ? previous : `${prefix}${version}`
+  const remote = remoteUrl(cwd)
+  const repo = arg('repo') || (remote.match(/https:\/\/[^/]+\/(.+)$/) || [])[1] || ''
+  // the notes for a finished tag are the commits it covers, not the (empty)
+  // ones after it
+  const covered = finishing
+    ? {
+        from: attempt(() => git(cwd, 'describe', '--tags', '--abbrev=0', '--match', `${prefix}[0-9]*`, `${previous}^`)),
+        commits: commits(cwd, attempt(() => git(cwd, 'describe', '--tags', '--abbrev=0', '--match', `${prefix}[0-9]*`, `${previous}^`)), [], previous).map(classify)
+      }
+    : { from: previous, commits: parsed }
+
+  const body = notes(
+    version,
+    covered.commits,
+    covered.from,
+    remote,
+    new Date().toISOString().slice(0, 10)
+  )
+
+  if (finishing)
+    console.log(`${tag} already names HEAD: finishing that release`)
+  else
+    console.log(`${level} release: ${previous || 'none'} -> ${tag} (${releasable.length} commits)`)
+  console.log(body)
+
+  if (dry) {
+    console.log('--dry-run: nothing tagged, nothing sent')
+    output({ released: false, version, tag, level })
+    return
+  }
+
+  const notesFile = arg('notes-file')
+  if (notesFile) writeFileSync(notesFile, `${body}\n`)
+  output({ released: true, version, tag, level })
+
+  if (flag('tag')) {
+    // Reuse a tag that already points at HEAD: a run that failed after the tag
+    // was cut can be finished by re-running, which a release tool that refuses
+    // an existing tag cannot do.
+    const existing = attempt(() => git(cwd, 'rev-parse', '-q', '--verify', `${tag}^{commit}`))
+    if (existing && existing === head) console.log(`tag ${tag} already names HEAD`)
+    else if (existing) fail(`tag ${tag} exists and names ${existing}, not HEAD`)
+    else
+      git(
+        cwd,
+        '-c', 'user.name=sasjs',
+        '-c', 'user.email=sasjs@4gl.io',
+        'tag', '-a', tag, '-m', tag
+      )
+  }
+
+  if (flag('push-tag')) git(cwd, 'push', 'origin', tag)
+
+  if (flag('release')) {
+    if (host === 'none') fail('--release needs --host')
+    const token = process.env[arg('token-env', HOSTS[host].token)]
+    if (!token) fail(`no token: set ${arg('token-env', HOSTS[host].token)}`)
+    const links = args('asset-link').map((pair) => {
+      const at = pair.indexOf('=')
+      if (at === -1) fail('--asset-link needs name=url')
+      return { name: pair.slice(0, at), url: pair.slice(at + 1) }
+    })
+    await publish({
+      host,
+      api: arg('api-url'),
+      token,
+      header: arg('token-header'),
+      repo,
+      tag,
+      body,
+      title: arg('title', tag),
+      files: args('asset'),
+      links,
+      commit: head
+    })
+    console.log(`released ${tag} on ${host}`)
+  }
+}
+
+/**
+ * The result, on stdout and - when asked - as key=value lines a workflow can
+ * feed to whatever protocol it has (GITHUB_OUTPUT, GITHUB_ENV, a dotenv
+ * artifact, or nothing at all).
+ */
+function output(values) {
+  const lines = Object.entries(values).map(([key, value]) => `${key}=${value}`)
+  for (const line of lines) console.log(line)
+  const path = arg('output')
+  if (path) appendFileSync(path, `${lines.join('\n')}\n`)
+}
+
+try {
+  await main()
+} catch (error) {
+  fail(error.stderr ? String(error.stderr).trim() : error.message)
+}