AGENT SKILL

release-and-publish

Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 8
Forks
2

01 前言 Front Matter

name
release-and-publish
description
Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.
when_to_use
NpmRegistry, PackagePublish, NpmExecutor, npm publish from CI, GitHub Packages vs npm registry, ReleaseAgeGate, VersioningStrategy, ReleaseTag, TrackingTag, macOS npm cache EACCES

02 资源文件 3

03 SKILL.md 正文

Release and publish

Cutting and publishing a release from Effect v4 spans three packages: @effected/npm reads and writes to a registry, @effected/workspaces decides what versions and tags a release needs, @effected/github cuts the tag and the release. General Effect v4 rules — service shapes, layer composition, Schema.Class, testing idioms — live in effect-v4-services-layers, effect-v4-schema, effect-v4-testing, effected-packages; this skill states only what these packages do for a release pipeline.

What you have

Construct Import Reach for it when
NpmRegistry import { NpmRegistry } from "@effected/npm" Reading a package's published versions, dist-tags or publish times
PackagePublish @effected/npm Setting up auth, packing a tarball, or publishing it
NpmExecutor @effected/npm Choosing between the ambient npm and a pinned dlx-fetched one
classifyRegistry @effected/npm Deciding whether a registry is public npm, GitHub Packages, JSR or custom
ReleaseAgeGate @effected/pnpm Holding a version back until it has aged past a minimum
VersioningStrategy, ReleaseTag import { VersioningStrategy } from "@effected/workspaces" Classifying a workspace's release shape and formatting its tags
TrackingTag @effected/workspaces Deriving the floating v1/v1.2 GitHub Actions distribution aliases
PublishabilityDetector @effected/workspaces Wiring or overriding which packages publish, and to where
GitTag, GitHubRelease import { GitTag, GitHubRelease } from "@effected/github" Cutting the actual git tag and GitHub release — see github-api

Standards

  • Treat the registry as a per-call argument, never a layer-baked one. A single program can legitimately probe two registries for one package — don't collapse NpmRegistry to a fixed registry at construction.
  • Route a 404 through Option.none(), never through stderr-wording matching. Absence is decided on response status structurally, so it survives an npm version bump that reworded its error text.
  • Compare integrity as the typed brand it is, not a bare string. A string-equals comparison between an SRI hash and something that merely looks like one is a defect waiting on a format change.
  • Send the auth token to a caller-supplied npmrc path, never argv. Masking the token in a CI log is the caller's job — PackagePublish has no opinion about log output and no ActionOutputs edge to have one.
  • Never swap pack's two digests. integrity compares against the registry's own SRI hash; sha256Hex — read back off the packed tarball, not derived from npm's report — is the attestation subject. They are both strings; getting them backwards is silent.
  • Let dlx fail typed when there's no project-local launcher — never let it silently fall back to the ambient npm. A silent fallback would reintroduce exactly the OIDC-publishing failure the pinned version exists to avoid.
  • Match a registry's subdomain with a leading dot. A bare suffix match would classify a look-alike hostname as the public registry, and that classification gates both token-sending and --provenance.
  • Clamp a release-age gate only through ReleaseAgeGate.combine, never in isolation. combine is the single authority: strictest age wins, exclude sets union — route every contribution through it, even a lone one, so the clamping logic stays in one place.
  • Give PublishabilityDetector no ambient default. Every composite that decides workspace versioning requires it explicitly in R — ship named policies (.layerNpm, .layerNone) rather than letting a merge silently pick a default no type error would catch.
  • Prefer GitTag.upsert/GitHubRelease.create over a hand-rolled exists-then-create sequence when cutting a release — see github-api.

Footguns

  • GitHub's macOS runner images ship a partly root-owned npm cache, and npm pack hard-fails against it with an unrecoverable permission error. This is deterministic on every macOS run until the cache is redirected — not a flaky retry candidate. The redirect must be visible at the publish call site — an explicit cache-directory option passed alongside the pack/publish call itself — never an invisible environment variable set once, far from the call it protects. See references/publish-pipeline.md.
  • The scoped/unscoped v prefix asymmetry in ReleaseTag is deliberate, reproducing production byte for byte — don't "normalize" it to look more consistent.
  • Tracking tags (v1, v1.2) derive nothing for a prerelease by default — re-pointing owner/repo@v1 at a beta with no signal would ship it to every consumer depending on the newest stable 1.x.
  • ReleaseAgeGate's glob dialect is pnpm's *-crosses-/ matcher, not @effected/glob's minimatch dialect — routing exclude patterns through the wrong engine silently changes which packages a gate exempts.
  • A lane prerelease publishes under latest unless --tag is passed. Under pnpm-native release planning a lane builds X.Y.Z-<lane>.N, but a prerelease segment does not choose a dist-tag. Pass the tag at the publish call (the lane's name is the natural one) or every consumer on latest receives it; the planner (@effected/changesets) plans versions and never picks a tag.
  • NpmRegistry.layerTest() with no overrides dies loudly by design on the first read — reach for NpmRegistry.layerSeeded({ registries: {} }) when a test wants a real, working empty registry instead. Every read of it answers Option.none(), as a 404 does, including versions, distTags and publishTimes.

Additional resources

  • references/publish-pipeline.md — the full NpmRegistry/PackagePublish/NpmExecutor surface, registry classification, and the macOS npm-cache hazard in detail. Load when: reading the registry, packing/publishing a tarball, or debugging a publish step that only fails on macOS.
  • references/versioning-strategies.md — VersioningStrategy, ReleaseTag formatting, TrackingTag derivation, and PublishabilityDetector's no-ambient-default rule. Load when: classifying a workspace's release shape or formatting/deriving tags.
  • references/tags-and-gates.md — the ReleaseAgeGate clamping and exclude-matching rules, plus the GitTag/GitHubRelease call sequence for cutting a release. Load when: gating a resolver against too-young releases, or cutting the tag and release once a version is chosen.

Elsewhere

  • @effected/commands' Run and LocalExec in full (the combinators PackagePublish runs through, the argv-prefix table) → running-commands-and-tools.
  • GitBranch/GitTag/GitHubRelease's full member catalogue, GitHubError classification, pagination, retry policy → github-api.
  • GitHub App authentication and token lifecycle → github-app-tokens.
  • Sigstore signing and CycloneDX SBOM generation over PackedTarball's sha256Hex → supply-chain-attestation.
  • Action.run's ActionServices and why a publish layer's R collapses to just LocalExec inside an action → actions-runtime.
  • The scripted-spawner and seeded-registry test harnesses this surface is built to be testable against → testing-actions.

04 同仓库更多 Skills

spencerbeggs
spencerbeggs/effected

testing-actions

Use when writing or reviewing tests for @effected/github-actions, @effected/github, @effected/sbom or @effected/commands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre/main/post lifecycle through Action.run, or debugging why a test hits the real network or hangs.

★ 8
spencerbeggs
spencerbeggs/effected

supply-chain-attestation

Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.

★ 8
spencerbeggs
spencerbeggs/effected

structuring-an-action

Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.

★ 8
spencerbeggs
spencerbeggs/effected

running-commands-and-tools

Use when running a subprocess in Effect v4, spawning a command, capturing stdout/stderr/exit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.

★ 8
spencerbeggs
spencerbeggs/effected

hardening-a-parser-port

Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.

★ 8
spencerbeggs
spencerbeggs/effected

github-app-tokens

Use when a GitHub credential needs to come into existence, live somewhere, and die — constructing a client from a plain token or a GitHub App, or wiring GitHubToken's provision/read/clientLayer/dispose lifecycle across an Action's pre/main/post phases.

★ 8