===============
LIBRARY RULES
===============
From library maintainers:
- anvil is a GitHub Action, not an npm package. Consumers reference it via uses: forgesworn/anvil/.github/workflows/release.yml@v0
- The composite action (uses: forgesworn/anvil@v0) omits the reproducible-build gate. Use the reusable workflow for full protection.
- Node version must ship npm >= 11.5.x for OIDC trusted publishing. Node 22 LTS is too old.
- Trusted publishing must be configured on npmjs.com pointing at the consumer's repo and workflow file, not at forgesworn/anvil.

### Build-a Job Steps

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Details the sequence of steps executed in the 'build-a' job, including setup, verification checks, testing, and artifact recording.

```bash
verify-action-pins -- scan `.github/workflows/*.yml` for `uses:`
   lines that aren't 40-char SHA pinned. Warn-only by default; promote
   to hard-fail with `strict-action-pins: true`
```

```bash
npm ci
```

```bash
npm run build --if-present
```

```bash
verify-tag -- git tag matches `package.json` version
```

```bash
verify-bump -- (only when `version-strategy: verify`) parses
   conventional commits and fails if the manual bump is smaller than
   what the commit history implies
```

```bash
run-tests -- full test suite (`npm test` by default)
```

```bash
verify-vectors -- your configured frozen-vector command (skipped
   if not set; any library with deterministic test vectors should set this)
```

```bash
verify-audit -- `npm audit --omit=dev` -- runtime deps only
```

```bash
verify-exports -- every subpath in `package.json` "exports" exists
    on disk
```

```bash
verify-secrets -- grep `dist/` (and any paths in `"files"`) for
    forbidden filenames and secret markers
```

```bash
record-tarball -- derive `SOURCE_DATE_EPOCH` from `git log`,
    normalise mtimes across the working tree, `npm pack` into a known
    location, parse the `--json` output for filename and sha512
    integrity, hash with sha256, write `tarball.meta` and upload it
    along with the `.tgz` as an artifact
```

--------------------------------

### Setup Reusable Release Workflow

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Integrate the Anvil reusable workflow into your repository by creating a `.github/workflows/release.yml` file. This workflow handles the release process when a GitHub release is published.

```yaml
name: release
on:
  release:
    types: [published]
permissions:
  contents: write   # update Release bodies + upload tarball asset
  id-token: write   # OIDC trusted publishing to npm
jobs:
  release:
    uses: forgesworn/anvil/.github/workflows/release.yml@v0
```

--------------------------------

### Configure reproducibility-mode in GitHub Actions

Source: https://github.com/forgesworn/anvil/blob/main/docs/design/reproducible-build.md

Example configuration for the reusable workflow to enable warning mode during migration.

```yaml
with:
  vector-test-command: npm run test:vectors
  reproducibility-mode: warn   # log mismatches without blocking
```

--------------------------------

### Setup Auto Release Workflow

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Configure the `.github/workflows/auto-release.yml` to automatically parse conventional commits, bump versions, update changelogs, tag, and dispatch the release workflow. This workflow runs on pushes to the main branch.

```yaml
name: auto-release
on:
  push:
    branches: [main]
permissions:
  contents: write
  actions: write            # required to dispatch release.yml
jobs:
  auto-release:
    uses: forgesworn/anvil/.github/workflows/auto-release.yml@v0
```

--------------------------------

### Package.json Exports Configuration Example

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

This JSON structure defines the 'exports' field in package.json, specifying entry points for different module formats and environments. It also includes legacy 'main' and 'types' fields. Ensure all listed paths exist after the build process.

```json
{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./utils": {
      "import": "./dist/utils.mjs",
      "require": "./dist/utils.cjs"
    }
  },
  "main": "./dist/index.cjs",
  "types": "./dist/index.d.ts"
}
```

--------------------------------

### Use Release Workflow with JSR Token Secret

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Example of how to use the release workflow and pass the JSR_TOKEN secret. Ensure the JSR_TOKEN is configured in your repository's secrets.

```yaml
jobs:
  release:
    uses: forgesworn/anvil/.github/workflows/release.yml@v0
    secrets:
      JSR_TOKEN: ${{ secrets.JSR_TOKEN }}
```

--------------------------------

### Build-b Job Steps

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Outlines the steps for the 'build-b' job, which runs in parallel with 'build-a' and produces a byte-identical tarball.

```bash
checkout, setup,
`npm ci`, build, record-tarball, upload. Same `SOURCE_DATE_EPOCH`,
same normalised mtimes, same pack -- the resulting tarball must be
byte-identical.
```

--------------------------------

### Essential package.json Configuration

Source: https://github.com/forgesworn/anvil/blob/main/examples/ts-library/README.md

Key fields for publishing include an explicit `files` array for predictable scan roots, `publishConfig.provenance: true` for SLSA provenance signing, and a separate `test:vectors` script for the frozen-vector gate.

```json
{
  "name": "my-library",
  "version": "1.0.0",
  "files": [
    "dist",
    "src",
    "README.md",
    "CHANGELOG.md",
    "LICENCE"
  ],
  "publishConfig": {
    "provenance": true
  },
  "scripts": {
    "build": "tsc",
    "test": "vitest run",
    "test:vectors": "vitest run test/vectors.test.ts"
  }
}
```

--------------------------------

### Fetch package attestations via API

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

Retrieve the Sigstore bundle and SLSA predicate for a specific package version.

```sh
# Fetch attestations for a specific version
curl -s https://registry.npmjs.org/-/npm/v1/attestations/my-package@1.2.0 | jq .
```

--------------------------------

### Publish Job Steps

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Details the actions performed in the 'publish' job, including publishing to npm and JSR, and updating GitHub releases.

```bash
publish-npm -- idempotent `npm publish --access public` via OIDC,
publishing the **exact** tarball downloaded above (so the bytes on
the registry are the bytes the reproduce gate signed off on).
Provenance is driven by `package.json` `publishConfig.provenance: true`
rather than a CLI flag (npm 11.6+ short-circuits to `ENEEDAUTH`
when `--provenance` is passed explicitly). On a clean re-run the
registry's `dist.integrity` is compared to the recorded integrity: match -> silent skip, mismatch -> loud failure (registry tarball
substitution alarm).
```

```bash
publish-jsr -- only if `jsr.json` exists in your repo
```

```bash
update-release -- updates the GitHub Release body from the
matching `CHANGELOG.md` section, appends an *Artefact integrity*
block containing tarball filename, size, sha256, sha512, and a
`curl | shasum` recipe consumers can run to verify the registry
tarball matches; uploads the canonical `.tgz` as a GitHub Release
asset so consumers have two independent sources for the bytes; and
if the reproduce job ran and matched, prepends a "Reproducible
build" line above the integrity block.
```

--------------------------------

### Manual npm Publish for New Packages

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Perform a one-time manual publish for a new package before configuring trusted publishing. Requires a granular access token scoped to publish.

```sh
# From your workstation, with a granular access token scoped to publish
npm publish --access public
```

--------------------------------

### Verify Version Strategy Configuration

Source: https://github.com/forgesworn/anvil/blob/main/README.md

To use the 'verify' version strategy, set the `version-strategy` input to 'verify'. This ensures that the release bump is not smaller than what conventional commits imply.

```yaml
    with:
      version-strategy: verify
```

--------------------------------

### Composite Action vs. Reusable Workflow

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Explains the difference between the reusable workflow and the composite action, highlighting the absence of the 'reproduce' job in the composite action.

```text
The composite action (`action.yml`) does **not** include the
reproduce job -- composite actions are flat lists of steps inside one
job and cannot define a multi-job DAG. The composite remains as an
escape hatch for power users who need custom job structure; it ships
with a strictly weaker guarantee (single-runner integrity anchor only, no reproducibility check). Use the reusable workflow as the default.
```

--------------------------------

### Configure package.json for provenance

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

Enable SLSA provenance by setting the provenance property in the publishConfig object. Do not use the --provenance CLI flag as it causes authentication errors in newer npm versions.

```json
{
  "publishConfig": {
    "provenance": true
  }
}
```

--------------------------------

### Configure release workflow

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-release-please.md

The new release workflow for running gates and publishing to npm.

```yaml
name: release
on:
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      tag:
        description: Release tag to publish
        type: string
        required: true
permissions:
  contents: write
  id-token: write
jobs:
  release:
    uses: forgesworn/anvil/.github/workflows/release.yml@v0
    with:
      tag: ${{ inputs.tag || '' }}
```

--------------------------------

### Configure reproducibility warning mode

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-v0.3.md

Set the reproducibility-mode to warn to allow releases to proceed even if the build comparison fails.

```yaml
jobs:
  release:
    uses: forgesworn/anvil/.github/workflows/release.yml@v0.4.0
    with:
      vector-test-command: npm run test:vectors
      reproducibility-mode: warn
```

--------------------------------

### Verify package signatures via CLI

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

Check that packages in node_modules have valid registry signatures and provenance attestations.

```sh
npm audit signatures
```

--------------------------------

### Reproduce Job Functionality

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Describes the 'reproduce' job's role in comparing tarball artifacts from 'build-a' and 'build-b' to ensure byte-for-byte identity.

```bash
compare-tarball-meta, which exits 0 if the sha256s match. Under the default
`reproducibility-mode: strict` a mismatch is a hard failure and the
release is blocked. Under `reproducibility-mode: warn` the mismatch
is logged and the publish proceeds. Under `reproducibility-mode: off`
the second build and the comparison are skipped entirely (v0.3
single-runner behaviour).
```

--------------------------------

### Define the release workflow

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-semantic-release.md

Create this file in .github/workflows/release.yml to trigger the release process on GitHub Release publication.

```yaml
name: release

on:
  release:
    types: [published]

permissions:
  contents: write
  id-token: write

jobs:
  release:
    uses: forgesworn/anvil/.github/workflows/release.yml@v0
    with:
      vector-test-command: npm run test:vectors
```

--------------------------------

### Configure esbuild for reproducible source maps

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-v0.3.md

Set sourceRoot to a relative path to avoid host-specific absolute paths in source maps.

```js
{
  sourcemap: true,
  sourceRoot: '.',
  // OR set `sources` to be relative
}
```

--------------------------------

### Anvil Workflow DAG Visualization

Source: https://github.com/forgesworn/anvil/blob/main/README.md

This diagram illustrates the job dependencies within the Anvil reusable workflow. It shows the 'build-a' and 'build-b' jobs feeding into the 'reproduce' job, which then leads to the 'publish' job.

```text
   build-a ──────┐
   (full gates +  │
    record)       ├──> reproduce ──> publish
   build-b ──────┘    (compare      (publish-npm,
   (build +           sha256s)       publish-jsr,
    record)                          update-release)
```

--------------------------------

### Local Workflow Changes for Publishing

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-np.md

Illustrates the shift in local actions required for publishing. Instead of running 'np', you manually update version, changelog, commit, tag, and push before creating a GitHub release.

```sh
# locally
vim package.json          # bump version
vim CHANGELOG.md          # write entry
git add -A && git commit -m "chore(release): 1.2.0"
git tag v1.2.0 && git push --tags
# on GitHub: create Release for v1.2.0
# CI takes over: gates, reproducible build, OIDC publish, provenance
```

--------------------------------

### Remove release-please configuration files

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-release-please.md

Command to remove legacy release-please configuration files.

```sh
git rm release-please-config.json .release-please-manifest.json
```

--------------------------------

### Configure Vector Test Command

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Optionally, configure a command to run vector tests as part of the release process. This is useful for libraries with frozen test vectors.

```yaml
    with:
      vector-test-command: npm run test:vectors
```

--------------------------------

### JSR Configuration for Dual Publishing

Source: https://github.com/forgesworn/anvil/blob/main/examples/ts-library/README.md

To publish to JSR alongside npm, include a `jsr.json` file with matching version and scope. A `JSR_TOKEN` repository secret is required as JSR does not yet support OIDC trusted publishing.

```json
{
  "name": "@my-scope/my-library",
  "version": "1.0.0",
  "exports": "./src/index.ts"
}
```

--------------------------------

### Compare Registry and GitHub Release Tarballs

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

Compares the SHA256 hashes of tarballs from the npm registry and GitHub releases to ensure they match.

```bash
# From npm registry
npm_sha=$(curl -sL https://registry.npmjs.org/my-package/-/my-package-1.2.0.tgz | shasum -a 256 | cut -d' ' -f1)
# From GitHub Releases
gh_sha=$(curl -sL https://github.com/owner/repo/releases/download/v1.2.0/my-package-1.2.0.tgz | shasum -a 256 | cut -d' ' -f1)
[[ "$npm_sha" == "$gh_sha" ]] && echo "Match" || echo "MISMATCH"
```

--------------------------------

### Configure vector-test-command

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

Enables the frozen-vector gate by specifying a command to run against reference values. The gate is skipped if this input is left empty.

```yaml
uses: forgesworn/anvil/.github/workflows/release.yml@v0
with:
  vector-test-command: npm run test:vectors
```

--------------------------------

### Update package.json for provenance

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-release-please.md

Add the publishConfig block to enable provenance in package.json.

```json
"publishConfig": {
  "provenance": true
}
```

--------------------------------

### Configure Release Workflow for Auto Release

Source: https://github.com/forgesworn/anvil/blob/main/README.md

The `release.yml` workflow needs to be configured to accept triggers from the `auto-release.yml` workflow via `workflow_dispatch`. This allows the automated process to initiate the release.

```yaml
name: release
on:
  release:
    types: [published]       # manual flow: you create the Release
  workflow_dispatch:         # auto flow: auto-release dispatches
    inputs:
      tag:
        description: Release tag to publish
        type: string
        required: true
permissions:
  contents: write
  id-token: write
jobs:
  release:
    uses: forgesworn/anvil/.github/workflows/release.yml@v0
    with:
      tag: ${{ inputs.tag || '' }}
      vector-test-command: npm run test:vectors   # optional
```

--------------------------------

### Add auto-release and manual trigger configuration

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-changesets.md

Optional configuration for automatic versioning from conventional commits and manual workflow dispatch.

```yaml
# Add to .github/workflows/release.yml triggers:
on:
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      tag:
        description: Release tag to publish
        type: string
        required: true
# And pass tag through in the job:
jobs:
  release:
    uses: forgesworn/anvil/.github/workflows/release.yml@v0
    with:
      tag: ${{ inputs.tag || '' }}
```

```yaml
# .github/workflows/auto-release.yml
name: auto-release

on:
  push:
    branches: [main]

permissions:
  contents: write
  actions: write

jobs:
  auto-release:
    uses: forgesworn/anvil/.github/workflows/auto-release.yml@v0
```

--------------------------------

### Release Workflow Configuration

Source: https://github.com/forgesworn/anvil/blob/main/docs/design/chained-workflows.md

This is the consumer-side configuration for the release workflow. It supports both manual release publishing via the 'release' event and automated triggering via 'workflow_dispatch' with a required 'tag' input. It requires permissions for contents and OIDC tokens.

```yaml
# .github/workflows/release.yml
name: release
on:
  release:
    types: [published]       # manual flow: human creates Release
  workflow_dispatch:         # auto flow: auto-release dispatches
    inputs:
      tag:
        description: Release tag to publish (e.g. v1.2.3)
        type: string
        required: true
permissions:
  contents: write
  id-token: write
jobs:
  release:
    uses: forgesworn/anvil/.github/workflows/release.yml@v0
    with:
      tag: ${{ inputs.tag || '' }}
      vector-test-command: npm run test:vectors  # optional

```

--------------------------------

### Replace release-please workflow

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-release-please.md

The existing release-please workflow configuration to be replaced.

```yaml
name: release-please
on:
  push:
    branches: [main]
jobs:
  release-please:
    uses: googleapis/release-please-action@v4
    # ... followed by a conditional npm publish step
```

--------------------------------

### Record tarball metadata for reproducibility

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

Derive source date epoch, normalize file timestamps, and extract package metadata for integrity verification.

```bash
# Derive SOURCE_DATE_EPOCH from git commit time
SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"
export SOURCE_DATE_EPOCH

# Normalise all file mtimes for reproducibility
find . -exec touch -t "$(date -d "@$SOURCE_DATE_EPOCH" '+%Y%m%d%H%M.%S')" {} +

# Pack and extract metadata
pack_json="$(npm pack --pack-destination "$meta_dir" --json)"
filename="$(printf '%s' "$pack_json" | jq -r '.[0].filename')"
integrity="$(printf '%s' "$pack_json" | jq -r '.[0].integrity')"
size="$(printf '%s' "$pack_json" | jq -r '.[0].size')"
```

--------------------------------

### Add Auto-Release Workflow

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-release-it.md

If you need automatic versioning and changelog generation, add this workflow. It triggers on pushes to the main branch and can dispatch the release workflow. Requires `workflow_dispatch` additions to `release.yml`.

```yaml
# .github/workflows/auto-release.yml
name: auto-release

on:
  push:
    branches: [main]

permissions:
  contents: write
  actions: write

jobs:
  auto-release:
    uses: forgesworn/anvil/.github/workflows/auto-release.yml@v0
```

--------------------------------

### Configure CI to Verify Version Bumps

Source: https://github.com/forgesworn/anvil/blob/main/examples/ts-library/README.md

Set `version-strategy: verify` in your release workflow to ensure CI flags manual version bumps that are smaller than implied by commit history. This provides a middle ground between full manual control and automatic releases.

```yaml
jobs:
  release:
    uses: forgesworn/anvil/.github/workflows/release.yml@v0
    with:
      tag: ${{ inputs.tag || '' }}
      version-strategy: verify
```

--------------------------------

### Configure strict-action-pins

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

Controls whether unpinned action references block the release process. Set to false during initial adoption and true for production enforcement.

```yaml
uses: forgesworn/anvil/.github/workflows/release.yml@v0
with:
  strict-action-pins: true    # fail on unpinned refs (default)
```

```yaml
with:
  strict-action-pins: false   # warn only, do not block release
```

--------------------------------

### Required release.yml for Manual and Auto Flows

Source: https://github.com/forgesworn/anvil/blob/main/examples/ts-library/README.md

This workflow is required for both manual and auto release modes. It handles gates and publishing. Configure `vector-test-command` if your library does not have frozen test vectors.

```yaml
name: release
on:
  release:
    types: [published]       # manual flow
  workflow_dispatch:         # auto flow dispatches here
    inputs:
      tag:
        description: Release tag to publish
        type: string
        required: true

permissions:
  contents: write
  id-token: write

jobs:
  release:
    uses: forgesworn/anvil/.github/workflows/release.yml@v0
    with:
      tag: ${{ inputs.tag || '' }}
      vector-test-command: npm run test:vectors
```

--------------------------------

### Add release workflow

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-changesets.md

Create a caller workflow for the anvil release process.

```yaml
name: release

on:
  release:
    types: [published]

permissions:
  contents: write
  id-token: write

jobs:
  release:
    uses: forgesworn/anvil/.github/workflows/release.yml@v0
```

--------------------------------

### Verify Tarball Integrity

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

Commands to verify that the downloaded npm tarball matches the expected SHA256 hash.

```bash
curl -sLO https://registry.npmjs.org/my-package/-/my-package-1.2.0.tgz
shasum -a 256 my-package-1.2.0.tgz
# Compare output with sha256 in the GitHub Release "Artefact integrity" block
```

--------------------------------

### Sort glob results explicitly

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-v0.3.md

Ensure deterministic build order by sorting file lists generated by glob patterns.

```js
const files = glob.sync('src/**/*.ts').sort();
```

--------------------------------

### Configure npm PublishConfig Provenance

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-release-it.md

Ensure that `publishConfig.provenance` is set to `true` in your `package.json`. This is required for publishing with OIDC and SLSA provenance.

```json
"publishConfig": {
  "provenance": true
}

```

--------------------------------

### Search for non-deterministic timestamps

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-v0.3.md

Use grep to identify potential runtime-evaluated timestamps in your source code.

```sh
grep -rn 'Date\.now\|__BUILD_TIMESTAMP__\|__BUILD_DATE__' src/
```

--------------------------------

### Add frozen-vector test script

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-semantic-release.md

Add the test:vectors script to package.json if your library uses frozen test vectors.

```diff
   "scripts": {
     "test": "vitest run",
+    "test:vectors": "vitest run test/vectors.test.ts",
```

--------------------------------

### Configure rollup for reproducible source maps

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-v0.3.md

Use sourcemapPathTransform to ensure source map paths remain relative.

```js
output: {
  sourcemap: true,
  sourcemapPathTransform: (relativePath) => relativePath,
}
```

--------------------------------

### Dispatch Release Workflow

Source: https://github.com/forgesworn/anvil/blob/main/docs/design/chained-workflows.md

Use this command to trigger the release workflow from another workflow. It leverages `workflow_dispatch` which is an explicit exception to GitHub's anti-recursion rule, thus not requiring a PAT.

```sh
gh workflow run release.yml -f tag=v1.2.3
```

--------------------------------

### Auto-Release Workflow Configuration

Source: https://github.com/forgesworn/anvil/blob/main/docs/design/chained-workflows.md

This is the consumer-side configuration for the auto-release workflow. It requires permissions to write contents and actions, and it uses the anvil repository's auto-release workflow.

```yaml
# .github/workflows/auto-release.yml
name: auto-release
on:
  push:
    branches: [main]
permissions:
  contents: write
  actions: write            # required to dispatch
jobs:
  auto-release:
    uses: forgesworn/anvil/.github/workflows/auto-release.yml@v0

```

--------------------------------

### Configure auto-release workflow

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-release-please.md

The new auto-release workflow for parsing commits and triggering releases.

```yaml
name: auto-release
on:
  push:
    branches: [main]
permissions:
  contents: write
  actions: write
jobs:
  auto-release:
    uses: forgesworn/anvil/.github/workflows/auto-release.yml@v0
```

--------------------------------

### Optional auto-release.yml for Auto Mode

Source: https://github.com/forgesworn/anvil/blob/main/examples/ts-library/README.md

This optional workflow enables automatic releases triggered by pushes to the main branch. It requires permissions to write to actions to dispatch the `release.yml` workflow.

```yaml
name: auto-release
on:
  push:
    branches: [main]

permissions:
  contents: write
  actions: write            # required to dispatch release.yml

jobs:
  auto-release:
    uses: forgesworn/anvil/.github/workflows/auto-release.yml@v0
```

--------------------------------

### Verify Artefact Integrity

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Displays the expected format for artefact integrity verification and the corresponding shell commands to validate a downloaded tarball.

```text
file:      noble-hashes-1.4.2.tgz
size:      87234 bytes
sha256:    9a5ec1...e7c1
sha512-...
```

```sh
curl -sLO https://registry.npmjs.org/noble-hashes/-/noble-hashes-1.4.2.tgz
shasum -a 256 noble-hashes-1.4.2.tgz
```

--------------------------------

### Anvil Workflow Configuration for npm Audit

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

This YAML snippet shows how to configure the 'audit-level' input for the Anvil release workflow. It specifies that only moderate severity advisories and above should block the release.

```yaml
uses: forgesworn/anvil/.github/workflows/release.yml@v0
with:
  audit-level: moderate   # only block on moderate or above
```

--------------------------------

### Verify Exports Script Command

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

This shell command is used by the verify-exports.sh script to check the existence of files declared in package.json's exports and legacy entry points. It uses 'jq' to parse the package.json and verifies each file path.

```shell
jq -r '.. | select(type=="string") | select(startswith("./"))' package.json | sort -u
```

--------------------------------

### Clean up package.json dependencies and scripts

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-changesets.md

Remove changeset-related devDependencies and scripts from package.json.

```diff
  "devDependencies": {
-   "@changesets/cli": "^2.30.0",
-   "@changesets/changelog-github": "^0.5.0",
```

```diff
  "scripts": {
-   "changeset": "changeset",
-   "release": "changeset publish",
-   "version": "changeset version",
```

--------------------------------

### Changelog Format

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Details on how the Forgesworn Anvil project parses changelogs, including matching version headings and handling different heading levels and formats.

```APIDOC
## CHANGELOG format

The extractor is intentionally loose. Your CHANGELOG section is found by matching the first Markdown heading (H1, H2, or H3) that contains:

- The version string (e.g. `1.4.4`), **and**
- A dotted numeric pattern the extractor recognises as a version heading

Capture continues until the next version heading. Non-version headings like `### Features` or `### Bug Fixes` are passed through as content. This means you can freely mix heading levels -- `semantic-release`'s "H1 for minors, H2 for patches" quirk works fine.

If you use [Keep a Changelog](https://keepachangelog.com) format, that works too. No strict format is enforced.
```

--------------------------------

### Runtime npm Audit Command

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

This command runs 'npm audit' to check for security vulnerabilities in production dependencies. The '--omit=dev' flag excludes development dependencies, and '--audit-level' sets the minimum severity level for advisories to be reported.

```shell
npm audit --omit=dev --audit-level=$level
```

--------------------------------

### Remove release-it Configuration File

Source: https://github.com/forgesworn/anvil/blob/main/docs/migration-from-release-it.md

Delete the existing release-it configuration file from your project's root directory. This command works for JSON, YAML, or TOML configuration files.

```sh
git rm .release-it.json   # or .release-it.yaml, .release-it.toml
```

--------------------------------

### Release Workflow Inputs

Source: https://github.com/forgesworn/anvil/blob/main/README.md

Inputs accepted by the release.yml workflow for the Forgesworn Anvil project. These inputs control various aspects of the release process, such as Node version, registry URL, test commands, and versioning strategy.

```APIDOC
## Inputs for release.yml

All inputs in the table below belong to `release.yml`. `auto-release.yml` only handles the parse-bump-tag-dispatch side; it accepts a small set of its own inputs (`release-branch`, `release-workflow`, `package-json`, `changelog-file`, `dry-run`) and otherwise stays out of release-time configuration — that lives on `release.yml` because the `workflow_dispatch` bridge fires `release.yml` as the entry-point workflow.

| Input | Default | Description |
|---|---|---|
| `node-version` | `24.11.0` | Node version used for npm operations (must ship with npm >= 11.5.1 for OIDC trusted publishing) |
| `registry-url` | `https://registry.npmjs.org` | npm registry |
| `test-command` | `npm test` | Full test suite command |
| `vector-test-command` | *(empty)* | Frozen-vector gate command |
| `changelog-file` | `CHANGELOG.md` | Path to CHANGELOG |
| `package-json` | `package.json` | Path to package.json |
| `audit-level` | `low` | `npm audit` severity floor |
| `version-strategy` | `manual` | `release.yml` only. One of `manual`, `verify`. `manual` is the default: you bump, you tag, the action publishes. `verify` parses conventional commits and fails if your bump is smaller than what the commits imply. For fully automatic versioning, use the companion `auto-release.yml` workflow instead. |
| `strict-action-pins` | `true` | If `true` (the default), **verify-action-pins** fails the release on any unpinned `uses:` reference in `.github/workflows`. Set to `false` for warn-only mode. `forgesworn/anvil` is exempt by name. |
| `reproducibility-mode` | `strict` | Reusable workflow only. One of `strict`, `warn`, `off`. `strict` blocks the release if the two parallel builds produce different sha256s. `warn` logs the mismatch but publishes. `off` skips the second build entirely (v0.3 single-runner behaviour). The composite action silently ignores this input (it cannot run the two-build DAG; see "Advanced: composite action directly"). |
| `tag` | *(empty)* | `release.yml` only. Explicit release tag (e.g. `v1.2.3`). Used by `auto-release.yml`'s chained publish job to pass the freshly-created tag. Empty defaults to `github.event.release.tag_name`, preserving the legacy release-event trigger path. |
| `dry-run` | `false` | Skip real publish (for smoke-testing) |
| `debug` | `false` | If `true`, run a diagnostic step before publish that dumps npm version, redacted `.npmrc`, OIDC env vars, and `npm config list`. Flip this on when debugging trusted-publisher errors -- see "Trusted publisher caveat". Does not print token values. |
```

--------------------------------

### Set OIDC permissions in GitHub Actions

Source: https://github.com/forgesworn/anvil/blob/main/docs/pre-publish-gates.md

Required permissions for the caller workflow to enable OIDC trusted publishing and provenance signing.

```yaml
permissions:
  contents: write   # update Release bodies + upload tarball asset
  id-token: write   # OIDC trusted publishing + provenance signing
```