PUBLISHING.md

Publishing

This package is authored as a Deno package and published to npm from a tarball generated by deno pack.

The release source of truth is deno.json.

Do not edit or add a root package.json for publishing. deno pack does not read the repo package.json; it reads name, version, and exports from deno.json, transpiles the exported TypeScript modules to JavaScript, generates .d.ts files, and writes a generated package.json inside the npm tarball.

deno pack omits the repository field from the generated package.json, but npm provenance verification requires it to match the publishing repository. The pack and pack:release tasks run scripts/postpack.ts after deno pack to patch the generated package.json inside the tarball with the repository (and description) from deno.json.

Prerequisites

Publishing is configured through npm Trusted Publishing with GitHub Actions. There is no NPM_TOKEN secret.

The npm package settings for @resolute/std must have this trusted publisher:

• Provider: GitHub Actions
• Repository: resolute/std
• Workflow filename: npm-publish.yml
• Allowed action: npm publish

The GitHub workflow publishes only when a GitHub Release is published. It checks that the release tag exactly matches the version in deno.json.

Release Checklist

Start from a clean, current master checkout:

git switch master
git pull --ff-only
git status --short

Stop if git status --short prints anything. Do not release from a dirty worktree.

Choose the next semver version. Check npm first so you do not reuse an already published version:

npm view @resolute/std version

Bump deno.json with Deno:

deno bump-version patch

Use minor or major instead of patch when that is the correct semver bump. After the bump, confirm the version:

deno eval "console.log(JSON.parse(Deno.readTextFileSync('deno.json')).version)"

Run the full release verification locally:

deno fmt --check deno.json .gitignore *.ts dom/*.ts
deno lint
deno task check
deno task test
deno task clean
deno task pack

Inspect the generated npm tarball:

tar -tzf resolute-std-*.tgz
! tar -tzf resolute-std-*.tgz | grep -E '(^|/)(promise-alt|node_modules|coverage)/'
! tar -tzf resolute-std-*.tgz | grep -E '(^|/)[^/]+\.ts$' | grep -v '\.d\.ts$'
! tar -tzf resolute-std-*.tgz | grep -E '\.(cjs|mjs|map)$'

The tarball should contain generated .js, generated .d.ts, README.md, and the generated package/package.json. It should not contain source .ts files, CommonJS files, source maps, tests, coverage, node_modules, or promise-alt.

Clean generated artifacts before committing:

deno task clean
git status --short

Only intentional source/config/doc changes should remain.

Commit the release changes:

VERSION="$(deno eval "console.log(JSON.parse(Deno.readTextFileSync('deno.json')).version)")"
git add .
git commit -m "Release v${VERSION}"

Create an annotated tag that exactly matches v${VERSION}:

git tag -a "v${VERSION}" -m "v${VERSION}"

Push the commit and tag:

git push origin master
git push origin "v${VERSION}"

Create the GitHub Release from that exact tag:

gh release create "v${VERSION}" --verify-tag --title "v${VERSION}" --notes ""

Publishing the GitHub Release triggers .github/workflows/npm-publish.yml. That workflow:

1. Checks out the repository.
2. Installs Deno and Node.
3. Verifies the tag name is exactly v${deno.json.version}.
4. Runs deno task pack:release.
5. Runs npm publish ./*.tgz --access public --provenance.

Provenance is always enforced; there is no option to publish without it. If the workflow fails, fix the problem and re-run it manually from the Actions tab (workflow_dispatch) with the release tag as input.

If the release workflow fails before the npm publish step, fix the problem, delete the failed GitHub Release if needed, move or recreate the tag only if the release commit changed, and publish the GitHub Release again.

If the workflow reaches npm publish and npm accepts the package, that version is immutable. Do not reuse that version. If a fix is needed, bump to a new version and repeat this checklist.

Manual Dry Run

To preview the tarball without publishing:

deno task pack
npm publish --dry-run ./resolute-std-*.tgz
deno task clean

npm publish --dry-run may still contact npm and may fail if the local version already exists. That is useful signal: published npm versions cannot be overwritten.