ArtPlayer/scripts/release/README.md

Preparing exact npm candidate files

Read-only registry inspection

yarn release:registry accepts the same five required arguments as release:verify-bundle below. It first runs that full verifier against a clean repository and fresh gates, reads public npm metadata, then runs the verifier again. It cannot inspect an unready bundle by trusting its downloaded report. No package is built, published or retagged; no new dependency is required.

registry.ts owns bounded public GET requests (15 seconds including response body, 10 MiB maximum, redirects disabled) and pure per-package classification. registry-check.ts binds those observations to the verifier before and after network activity. check-release-registry.mjs owns CLI inputs and exit status. The registry origin is fixed and no npmrc or authentication token is loaded.

State	Meaning and eventual recovery action
not-observed	Package/version was not found; do not claim the name/version is publishable. A removed historical version may be permanently unavailable.
already-present	Registry SHA-512 equals the verified candidate and selected tag already points there. Do not republish.
tag-change-required	SHA-512 matches, but the tag differs or is missing. Keep the tarball; any tag change needs separately authorized promotion/recovery. This can include moving a newer tag backwards.
conflict	Different/missing integrity or retained unpublish history. Stop the batch; never overwrite, unpublish or invent a replacement version.

The output preserves each package decision for a partially completed batch, timestamps and response digests. Conflicts exit 1 after printing the report; HTTP/schema/transport/local-verification failures exit 1 without a successful report. A zero exit means observations were collected without known conflicts, not release approval. Every report has publicationAuthorized: false and workflowProvenanceVerified: false. Registry tarballs are not downloaded by this metadata check. Registry state can change immediately; CI-03 still needs trusted workflow/artifact provenance, permission checks, exact-byte publication, explicit tag control and readback at authorized use time. Never execute a saved report as a command list or let it waive current release gates.

release-registry.test.mjs covers partial batches, conflicts, unpublish markers, malformed data, bounded transport, stale local gates/content and CLI rejection. Its injected complete ledgers are synthetic, not acceptance for real packages. It runs through test:release-bundle and the existing test:baseline glob. The new TypeScript modules are included in typecheck:release and root lint.

Sources checked 2026-09-16: npm publish and npm registry API.

Run from the repository root with the pinned Node and Yarn:

yarn release:preflight --packages artplayer,artplayer-plugin-chapter
yarn release:bundle --packages artplayer,artplayer-plugin-chapter --tag next
yarn typecheck:release
yarn test:release-bundle

For a downloaded copy of an already prepared bundle, use:

yarn release:verify-bundle --directory refactor/.cache/downloaded-bundle --packages artplayer,artplayer-plugin-chapter --tag next --source-commit <expected-40-hex-commit> --manifest-sha256 <independent-64-hex-digest>

Get the expected commit, batch, tag and manifest digest from the trusted handoff, not from the downloaded bundle itself. Passing a digest copied from an untrusted manifest does not establish authenticity. The workflow that establishes this handoff is still CI-03 work; this command only verifies local contents and gates.

release:bundle does not build, pack, install, contact npm or publish. It is a handoff step for candidates already recorded in refactor/release-ledger.json. Both commands currently refuse release acceptance because the repository still has unfinished candidate, review, device and other required gates. Synthetic test reports are not evidence that an ArtPlayer package is ready to publish.

Responsibilities

• ../package-archive.mjs checks actual tar entry types and paths for both package installation checks and candidate registration. It accepts Yarn's directory entries without a trailing slash while rejecting links, special files, duplicate members and paths outside package/. The legacy package-check.mjs export forwards to this helper for existing scripts.

• ../prepare-release.mjs is the Node entry and failure exit-code boundary.

• prepare.ts parses the explicit package batch/tag, requires the canonical Node/Yarn, and checks clean Git state before both ledger reads. Ignored generated files may exist; staged, unstaged and untracked source changes are rejected.

• bundle.ts consumes the repository ledger, checks the batch, copies exact tarball bytes and writes a hash-bound manifest. Its injected inspector is an internal test seam; the CLI never trusts a supplied JSON report as approval.

• bundle.ts also owns the shared batch rules and manifest description, so preparation and verification agree on the same versioned handoff format.

• verify.ts compares every downloaded file with independent expectations and two fresh ledger reads. It checks registered candidate bytes and SHA-512, strict manifest metadata, preflight contents and the exact file roster, then rechecks the downloaded files before returning. It performs no writes.

• ../verify-release.mjs is the verification CLI. It requires explicit arguments, canonical Node/Yarn and clean Git state on both fresh ledger reads. A downloaded JSON report cannot be injected as the inspector through the CLI.

• ../../refactor/scripts/release-ledger.mjs remains the source of candidate, input fingerprint, review, risk, source/license, device, rollback and CI checks. Do not introduce another manually maintained green-status list here.

The narrow report interfaces describe the fields consumed by preparation. The original report is preserved in full. The candidate assertion after batch validation is the only non-null assertion; an absent or invalid candidate must be rejected before any output directory is created.

Output and failure behavior

An accepted run creates a fresh refactor/.cache/npm-bundle-*/ directory with the existing tarballs, preflight.json and manifest.json. No existing output is overwritten. The manifest binds package names, versions, per-package source commits, source fingerprints, SHA-256, SHA-512 integrity, batch source commit, toolchain/lock information and the complete preflight report's hash.

The second ledger read must equal the first; candidates and copied files are checked again. The manifest completion marker is written last. On failure, only the verified temporary directory is removed. Redirected paths are rejected; if cleanup also fails, both errors and the retained directory are reported. A leftover directory without a manifest is not a successful handoff.

Allowed tags are explicitly next, alpha, beta, rc and latest; there is no implicit default, and prereleases cannot use latest. Registry metadata is fixed to the public npm registry. Site distributions cannot enter this npm bundle. These are preparation-tool constraints, not changes to any player package API.

Trust boundary and remaining workflow work

Every output retains publicationAuthorized: false. A manifest and its hashes provide content binding, not authenticity or publishing permission. CI-03 still needs trusted workflow/run artifact provenance, registry occupancy checks, exact tarball publication without lifecycle rebuilding, permission/OIDC configuration, partial-failure recovery and post-publication readback. Neither this script nor its tests enables a GitHub workflow, creates a token, or authorizes publication.

The future publisher must validate downloaded contents and fresh release evidence; it must not trust an artifact solely because it has this manifest shape. Do not add a rebuild fallback to preparation or publishing when an artifact is missing.

CI-NPM-02 supplies that content-validation step. A successful verification still returns workflowProvenanceVerified: false, registryOccupancyVerified: false and publicationAuthorized: false. It neither contacts GitHub/npm nor executes package lifecycle scripts. CI-03 must separately verify the repository/workflow, run, attempt, source commit and artifact identity using trusted remote metadata, and check registry occupancy immediately before an authorized publication. The verifier does not preserve a publishable approval across later file changes; the future publisher must revalidate and consume those same bytes at use time.

Restore the registered candidate files and required evidence to their ledger locations before verification. The downloaded preflight must equal the newly computed report, including toolchain and file hashes. A different environment, missing ignored evidence, changed files or new blockers can therefore reject an otherwise intact historical download. Keep and diagnose that rejection; do not edit the downloaded report to make it pass or rebuild a replacement. Extra files, directories, symlinks/junctions and redirected parent paths are rejected. Failed verification leaves the downloaded evidence intact.

release-bundle.test.mjs uses small real tar archives with explicitly synthetic ledger reports for byte-copy/failure tests, and temporary real Git repositories for the clean-source guard. It covers stale inputs, changed outputs, missing gates, site confusion, selection/tag errors, outside paths/junctions, partial cleanup and original exception retention. These tests run in test:baseline; strict TypeScript checking runs in ci:check, and the TS source is in root lint. release-verify.test.mjs additionally tests downloaded copies, self-consistent manifest/preflight forgeries, stale fresh gates, changed registered/downloaded tarballs, missing/extra members, redirected paths and mid-verification changes. Successful synthetic tests are not actual ArtPlayer candidate acceptance.