feat(vale): fetch, verify, and publish the Vale platform packages

[thecodedrift]

Stack (root → tip):

• feat(vale): add the six Vale platform packages and pinned manifest #72
  • ➡️ feat(vale): fetch, verify, and publish the Vale platform packages #86 (you are here)
    • docs(openspec): archive add-vale-binary-packages and land the cli pin #91

Unit 2 of the add-vale-binary-packages stack. Unit 1 (#72) added six empty packages and the pinned manifest; this adds the pipeline that fills and publishes them, along with the scripts it runs and their tests. Unit 3, the CLI's optionalDependencies pin, is not here and cannot be written until these names exist on npm.

Two phases, because the trust boundary is code review

detect runs on a weekly schedule with no npm credential and no OIDC identity. It compares the latest upstream Vale release against the version pinned in .github/scripts/vale-manifest.json, and when upstream is ahead it opens a pull request updating that version and all six SHA256 digests, taken from upstream's own vale_<version>_checksums.txt. It publishes nothing.

publish runs on the push to main that merges that pull request, once a human has read the digests.

The split is what makes the automation trustworthy. A single job that discovered a digest and then verified its downloads against the digest it had just discovered would verify nothing at all: whatever it downloaded would match, because the digest came from the same fetch. Separating discovery from verification puts a review in between, so nothing publishes on bytes nobody signed off on, and nobody has to notice a Vale release for the process to run.

What bounds a run

The upstream-version comparison, and only that. The "is this version already on npm?" check release.yml uses cannot work here. Every publish stamps <valeVersion>-<yyyymmddhhmmss>, a version npm has never seen, so such a check would answer "not published" on every single run and could never suppress anything. The comparison against upstream is the only thing that can say "nothing to do."

Why prepare and publish are separate jobs

prepare downloads third-party bytes off the internet. It holds contents: read, no environment, and no id-token, so it cannot publish or mint a token regardless of what it downloads. It verifies every archive against the committed digest and aborts the run on a mismatch before anything is unpacked, then hands over npm pack tarballs.

The credentialed publish job therefore only ever handles bytes that already matched a reviewed digest and are already sealed into a tarball. It does not even check out the repository.

Why packing comes before the artifact upload

actions/upload-artifact does not preserve file modes, and the Vale executable has to reach npm with its executable bit set. npm pack records modes inside the .tgz, so packing first and shipping the tarball through the artifact keeps 0755 intact end to end.

Before this can merge

1. The six package names do not exist on npm yet. An npm trusted publisher is registered per package, and there is nothing to bind until the name exists, so the first publish of each name is a deliberate one-time manual step by a maintainer. The exact procedure is in the workflow file's header comment. Publish the packed tarball, not the package directory: the committed package.json carries the placeholder version 0.0.0 and no binary, so a bare npm publish from a package directory would burn the name on an empty 0.0.0.
2. Register the trusted publisher for each of the six names on npmjs.com, bound to the npm-production environment. There is no fallback token path in this workflow on purpose.
3. After merge, run the workflow manually with phase: publish to exercise the OIDC path end to end.

Merging neither PR in this stack publishes anything

The publish phase triggers on a push to main that touches .github/scripts/vale-manifest.json. Unit 1 adds that manifest but no workflow to fire on it, and this PR adds the workflow but does not touch the manifest. The path filter never matches on either merge. The first publish is always deliberate, whether that is the manual bootstrap or a workflow_dispatch.

Known inherited limitation: the detect PR needs a manual check re-run

The detect phase opens its pull request with GITHUB_TOKEN, and GitHub does not fire workflows on events raised by that token. So Validate will not start on a detect PR, and a maintainer has to re-run checks by hand before merging.

This is the same step the changesets "Version Packages" PR already needs. Verified: Validate on #65 ran with run_attempt: 2, re-run manually before it merged. It is a limitation inherited from how GitHub scopes GITHUB_TOKEN, not a defect in this workflow.

Stack

Forward-merging, per the proposal's delivery table. Unit 1 is repository-only and publishes nothing. Unit 2 publishes packages no consumer references yet. Unit 3 pins packages that by then exist.

This PR is a draft because it is the tip of the stack until unit 3 exists, and the OpenSpec archive gate would otherwise ask it to archive a change that is not finished. It also must not merge before the npm bootstrap above.

skip-changeset is correct here for the same reason it is on #72: the six packages are in the changesets ignore list, and packages/cli is untouched. Unit 3 is where a changeset belongs, since that is where a published CLI actually changes.

Refs OSS-22

[Copilot]

Pull request overview

Adds the automated “detect upstream → review manifest diff → publish verified binaries” pipeline for the six @taskless/vale-<platform> packages, including the zero-dependency release logic + tests, and a new GitHub Actions workflow that implements the two-phase trust boundary described in the PR.

Changes:

• Adds .github/workflows/vale-binaries.yml with separate detect, credential-free prepare, and credentialed publish jobs.
• Introduces pure release logic (vale-release.cjs) plus unit tests, and I/O entrypoints (vale-detect.cjs, vale-prepare.cjs) to fetch/verify/stamp/pack.
• Updates .gitignore to exclude local pack output in .vale-dist/.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
openspec/changes/add-vale-binary-packages/tasks.md	Marks tasks for fetch/verify/stamp/workflow and quality gates as completed.
.gitignore	Ignores .vale-dist/ output from local npm pack runs.
.github/workflows/vale-binaries.yml	New two-phase workflow: detect upstream release → prepare verified tarballs → publish via OIDC trusted publishing.
.github/scripts/vale-release.test.cjs	Unit tests covering stamping/versioning, manifest rewrite planning, checksum parsing, and digest assertion logic.
.github/scripts/vale-release.cjs	Pure, dependency-free release logic (version parsing/stamping, manifest validation, digest comparison, detect planning).
.github/scripts/vale-prepare.cjs	Fetch/verify/unpack/stamp/pack script used by the credential-free prepare job (and for manual bootstrap).
.github/scripts/vale-detect.cjs	Detect script that reads upstream latest release + checksums and rewrites the pinned manifest for review.