From 2adda23fc29a0b3462ab48fd765c4ae661c84a93 Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Fri, 13 Nov 2026 15:44:19 -0500 Subject: [PATCH 1/2] Check the release tarball's name against tarballUrl() release.yml now fails before publishing unless the full tarball carries the exact name and tag that prepare.mjs prints for an "install": "tarball" refusal, and SHA256SUMS lists it. Pre-release tags are checked the same way. --- .github/workflows/release.yml | 10 ++++- docs/release.md | 5 ++- scripts/check-release-name.mjs | 48 +++++++++++++++++++++ tests/release-name.test.ts | 78 ++++++++++++++++++++++++++++++++++ tests/tarball.test.ts | 5 ++- 5 files changed, 143 insertions(+), 3 deletions(-) create mode 100644 scripts/check-release-name.mjs create mode 100644 tests/release-name.test.ts diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index db8433e..2752398 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -8,7 +8,9 @@ # ichava-js-icon-components--.tgz one pack, every flavour and export, as the # package @ichava/js-icon-components- # SHA256SUMS over the tarballs -# Each is `npm pack` output, checked by scripts/check-tarball.mjs before upload. +# Each is `npm pack` output, checked by scripts/check-tarball.mjs before upload, and the full +# tarball's name is checked against prepare.mjs's tarballUrl() by scripts/check-release-name.mjs. +# A pre-release tag (vX.Y.Z-rc.N) gets the same tarballs, on a GitHub pre-release. # # A tag is the only legitimate `push` trigger in this ecosystem; everything else # runs on `pull_request`. @@ -214,6 +216,12 @@ jobs: (cd release && sha256sum -- *.tgz > SHA256SUMS) ls -l release + # The full tarball must carry the exact name and tag scripts/prepare.mjs's tarballUrl() + # prints for a `"install": "tarball"` refusal, and SHA256SUMS must list it, or that + # command and the documented install line break. This fails before anything is published. + - name: Check the tarball matches the install URL + run: node scripts/check-release-name.mjs release "$TAG" + - name: Publish uses: softprops/action-gh-release@8a0cd651e5b2365bd640854a3fa5dfc70e4875f3 # v3.0.4 with: diff --git a/docs/release.md b/docs/release.md index a30f0e4..3ed2265 100644 --- a/docs/release.md +++ b/docs/release.md @@ -33,7 +33,10 @@ Each tarball is `npm pack` output, written by `scripts/pack-tarball.mjs` (which tarball its own package name while it packs, then restores `package.json`) and checked by `scripts/check-tarball.mjs` before upload: `dist/` for everything its manifest says was built, a stand-in for the rest, the Elm module and every export of each built pack, the package name its -contents call for, nothing from the development tree, and no dependencies. To rebuild them for a tag, which creates or updates that tag's release +contents call for, nothing from the development tree, and no dependencies. Then +`scripts/check-release-name.mjs` checks the full tarball is named exactly as `tarballUrl()` in +`scripts/prepare.mjs` builds its download URL, and that `SHA256SUMS` lists it; a mismatch fails the +run before anything is published, so the install command `prepare` prints cannot drift from the asset. To rebuild them for a tag, which creates or updates that tag's release only: ```bash diff --git a/scripts/check-release-name.mjs b/scripts/check-release-name.mjs new file mode 100644 index 0000000..cbca999 --- /dev/null +++ b/scripts/check-release-name.mjs @@ -0,0 +1,48 @@ +// @ts-check +/** + * Checks that a release attaches the full tarball under the exact name and tag `prepare` points a + * reader to. `tarballUrl()` in prepare.mjs is what a `"install": "tarball"` refusal prints, and + * the docs install from the same URL, so a release whose tarball is named any other way breaks + * that command for every reader of it. Used by release.yml after packing, and by the tests. + * + * node scripts/check-release-name.mjs + * + * `` is `vX.Y.Z` or `vX.Y.Z-rc.N`; a pre-release tarball carries the pre-release version. + */ +import { existsSync, readdirSync, readFileSync } from 'node:fs'; +import { basename, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { tarballUrl } from './prepare.mjs'; + +/** + * @param {{ tag: string, files: string[], sums?: string }} input + * `files` are the names in the release directory; `sums` is its SHA256SUMS text, when written. + * @returns {string[]} the problems found; empty when the release matches `tarballUrl()` + */ +export function releaseNameProblems({ tag, files, sums }) { + if (!/^v\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(tag)) return [`'${tag}' is not a vX.Y.Z or vX.Y.Z-rc.N release tag`]; + const url = tarballUrl(tag.slice(1)); + const name = basename(url); + const problems = []; + if (!url.endsWith(`/releases/download/${tag}/${name}`)) problems.push(`tarballUrl() points at ${url}, which is not a download from the ${tag} release`); + if (!files.includes(name)) { + const tgz = files.filter((f) => f.endsWith('.tgz')); + problems.push(`the release has no ${name}, the name tarballUrl() gives (it has ${tgz.length === 0 ? 'no tarball' : tgz.join(', ')})`); + } + if (sums !== undefined && !sums.split('\n').some((line) => line.trim().endsWith(` ${name}`))) problems.push(`SHA256SUMS does not list ${name}`); + return problems; +} + +function main() { + const [dir, tag] = process.argv.slice(2); + if (dir === undefined || tag === undefined) throw new Error('usage: check-release-name.mjs '); + const sumsFile = join(dir, 'SHA256SUMS'); + const problems = releaseNameProblems({ tag, files: readdirSync(dir), ...(existsSync(sumsFile) ? { sums: readFileSync(sumsFile, 'utf8') } : {}) }); + if (problems.length > 0) { + for (const p of problems) console.error(`::error::${p}`); + process.exit(1); + } + console.log(`${join(dir, basename(tarballUrl(tag.slice(1))))}: matches ${tarballUrl(tag.slice(1))}`); +} + +if (process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main(); diff --git a/tests/release-name.test.ts b/tests/release-name.test.ts new file mode 100644 index 0000000..1dd2524 --- /dev/null +++ b/tests/release-name.test.ts @@ -0,0 +1,78 @@ +import { spawnSync } from 'node:child_process'; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { afterAll, describe, expect, it } from 'vitest'; +import { parse } from 'yaml'; +import { releaseNameProblems } from '../scripts/check-release-name.mjs'; +import { tarballUrl } from '../scripts/prepare.mjs'; +import { ROOT } from './helpers.ts'; + +/** + * The release attaches the full tarball under the name `tarballUrl()` gives, so the command a + * `"install": "tarball"` refusal prints, and the documented install line, never drift from what + * release.yml uploads. release.yml runs scripts/check-release-name.mjs after packing. + */ +const work = mkdtempSync(join(tmpdir(), 'ichava-release-name-')); +afterAll(() => rmSync(work, { recursive: true, force: true })); + +const SUMS = (name: string) => `${'0'.repeat(64)} ${name}\n`; + +type Step = { name?: string; run?: string }; +const workflow = parse(readFileSync(join(ROOT, '.github/workflows/release.yml'), 'utf8')) as { + on: { push: { tags: string[] } }; + jobs: { release: { steps: Step[] } }; +}; +const steps = workflow.jobs.release.steps; + +describe('the release tarball name', () => { + it('matches tarballUrl() for a final tag', () => { + const name = 'ichava-js-icon-components-0.2.0.tgz'; + expect(tarballUrl('0.2.0')).toBe(`https://github.com/ichava/js-icon-components/releases/download/v0.2.0/${name}`); + expect(releaseNameProblems({ tag: 'v0.2.0', files: [name, 'SHA256SUMS'], sums: SUMS(name) })).toEqual([]); + }); + + it('matches tarballUrl() for a pre-release tag, which packs with its own version', () => { + const name = 'ichava-js-icon-components-0.2.0-rc.1.tgz'; + expect(releaseNameProblems({ tag: 'v0.2.0-rc.1', files: [name], sums: SUMS(name) })).toEqual([]); + }); + + it('refuses a release whose tarball is named differently, or that SHA256SUMS does not list', () => { + expect(releaseNameProblems({ tag: 'v0.2.0', files: ['js-icon-components-0.2.0.tgz'], sums: SUMS('js-icon-components-0.2.0.tgz') })).toEqual([ + 'the release has no ichava-js-icon-components-0.2.0.tgz, the name tarballUrl() gives (it has js-icon-components-0.2.0.tgz)', + 'SHA256SUMS does not list ichava-js-icon-components-0.2.0.tgz', + ]); + expect(releaseNameProblems({ tag: 'v0.2.0', files: [] })).toEqual(['the release has no ichava-js-icon-components-0.2.0.tgz, the name tarballUrl() gives (it has no tarball)']); + expect(releaseNameProblems({ tag: '0.2.0', files: [] })).toEqual(["'0.2.0' is not a vX.Y.Z or vX.Y.Z-rc.N release tag"]); + }); + + it('the script exits non-zero on a drifted name and zero on the right one', () => { + const good = 'ichava-js-icon-components-0.2.0.tgz'; + writeFileSync(join(work, 'js-icon-components-0.2.0.tgz'), ''); + writeFileSync(join(work, 'SHA256SUMS'), SUMS('js-icon-components-0.2.0.tgz')); + const run = () => spawnSync('node', [join(ROOT, 'scripts/check-release-name.mjs'), work, 'v0.2.0'], { encoding: 'utf8' }); + const red = run(); + expect(red.status).toBe(1); + expect(red.stderr).toContain(`the release has no ${good}`); + + writeFileSync(join(work, good), ''); + writeFileSync(join(work, 'SHA256SUMS'), SUMS(good)); + expect(run().status).toBe(0); + }); +}); + +describe('release.yml', () => { + it('runs on final and pre-release tags', () => { + expect(workflow.on.push.tags).toEqual(['v*.*.*', 'v*.*.*-*']); + }); + + it('checks the tarball name against tarballUrl() after packing and before publishing', () => { + const at = (match: (s: Step) => boolean) => steps.findIndex(match); + const pack = at((s) => s.run?.includes('scripts/pack-tarball.mjs') === true); + const check = at((s) => s.run?.trim() === 'node scripts/check-release-name.mjs release "$TAG"'); + const publish = at((s) => s.name === 'Publish'); + expect(pack).toBeGreaterThan(-1); + expect(check).toBeGreaterThan(pack); + expect(publish).toBeGreaterThan(check); + }); +}); diff --git a/tests/tarball.test.ts b/tests/tarball.test.ts index cc54685..88605e4 100644 --- a/tests/tarball.test.ts +++ b/tests/tarball.test.ts @@ -1,10 +1,11 @@ import { execFileSync, spawnSync } from 'node:child_process'; import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; -import { join } from 'node:path'; +import { basename, join } from 'node:path'; import { afterAll, beforeAll, describe, expect, it } from 'vitest'; import { readTarball, tarballProblems } from '../scripts/check-tarball.mjs'; import { packTarball } from '../scripts/pack-tarball.mjs'; +import { tarballUrl } from '../scripts/prepare.mjs'; import type { Manifest } from '../src/generator/generate.ts'; import { ASSET_TARGETS } from '../src/shared/index.ts'; import { packs, ROOT } from './helpers.ts'; @@ -32,6 +33,8 @@ describe('the release tarball', () => { it('is named as the release download URL expects', () => { const { version } = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')) as { version: string }; expect(tgz.endsWith(`/ichava-js-icon-components-${version}.tgz`)).toBe(true); + // The name a `"install": "tarball"` refusal prints, so the two cannot drift. + expect(basename(tgz)).toBe(basename(tarballUrl(version))); }); it('holds dist/ for every pack and flavour, and nothing from the development tree', () => { From 92d630000aebaf616a36031487c2733045cbe2f0 Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Fri, 13 Nov 2026 15:44:19 -0500 Subject: [PATCH 2/2] Offer the release tarball first and the git install for contributors The README and installation guide lead with npm install of the release URL and the SHA256SUMS check, then the git install for contributors or a pinned commit. The git install itself is unchanged. --- CHANGELOG.md | 8 ++++++++ README.md | 25 ++++++++++++++++++------- docs/installation.md | 16 ++++++++++++---- 3 files changed, 38 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a74cbd0..c5af433 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,14 @@ All notable changes to `@ichava/js-icon-components` follow [Keep a Changelog](ht ## [Unreleased] +### Added + +- **The release checks its tarball against the install URL.** `scripts/check-release-name.mjs` runs in `release.yml` after packing and before publishing, and fails unless the release directory holds the full tarball under the exact name `tarballUrl()` in `scripts/prepare.mjs` gives for the tag (the command an `"install": "tarball"` refusal prints) and `SHA256SUMS` lists it. Pre-release tags are checked the same way. `tests/release-name.test.ts` covers final and pre-release tags, a drifted name and the workflow step's place (proven red by renaming the file in `tarballUrl()`, and by removing the step). + +### Changed + +- **The install docs offer both paths in order.** The README's Install and `docs/installation.md` lead with the release tarball (`npm install` of the release URL, and the `SHA256SUMS` check), for an install with no build, then the git install, for contributors or a pinned commit. The git install itself is unchanged. + ## [0.1.0] - 2026-11-13 First release. diff --git a/README.md b/README.md index ff0ddd6..68d5e31 100644 --- a/README.md +++ b/README.md @@ -22,15 +22,26 @@ Node 24 or newer to install. The framework is an optional peer, for the flavour ## Install -Two paths, chosen per application. The prebuilt release tarball has every pack, flavour and export -and builds nothing: +Two ways, both supported. **The release tarball** is the one to use in an application: it is built +once when a release is tagged, holds every pack, flavour and export, and installs with no build, +compiler or `git`: ```bash npm install https://github.com/ichava/js-icon-components/releases/download/v0.1.0/ichava-js-icon-components-0.1.0.tgz ``` -A git build compiles only what you choose, with environment variables or the same keys under -`"ichava": { "icons": { … } }` in your `package.json`. It needs `git` on the path: +To check it against the release's `SHA256SUMS` first: + +```bash +curl -sLO https://github.com/ichava/js-icon-components/releases/download/v0.1.0/ichava-js-icon-components-0.1.0.tgz +curl -sL https://github.com/ichava/js-icon-components/releases/download/v0.1.0/SHA256SUMS | grep ichava-js-icon-components-0.1.0.tgz | shasum -a 256 -c +npm install ./ichava-js-icon-components-0.1.0.tgz +``` + +**The git install** is for contributors, or for pinning a commit that has no release yet. npm runs +the `prepare` build, with the compilers (several hundred MB) in npm's temporary clone, in 24 to +69 s. It compiles only what you choose, with environment variables or the same keys under +`"ichava": { "icons": { … } }` in your `package.json`, and needs `git` on the path: ```bash ICHAVA_ICONS_PACKS=tabler ICHAVA_ICONS_FLAVOURS=react \ @@ -44,9 +55,9 @@ ICHAVA_ICONS_PACKS=tabler ICHAVA_ICONS_FLAVOURS=react \ | `ICHAVA_ICONS_SKIP_BUILD=1` | `"skipBuild": true` | builds nothing | | `ICHAVA_ICONS_INSTALL=tarball` | `"install": "tarball"` | refuses the git build and names the release tarball | -The release also attaches one tarball per pack (`@ichava/js-icon-components-`) and -`SHA256SUMS`. An import of a pack or flavour that was not built throws, naming the variable that adds -it. See [Installation](docs/installation.md) for the per-pack tarballs, checksums, sizes and times. +The release also attaches one tarball per pack (`@ichava/js-icon-components-`). An import of +a pack or flavour that was not built throws, naming the variable that adds it. See +[Installation](docs/installation.md) for the per-pack tarballs, checksums, sizes and times. ## Quick start guide and usage diff --git a/docs/installation.md b/docs/installation.md index 60c7488..81bbacd 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,11 +1,16 @@ # Installation -There are two ways in. Pick one per application: +There are two ways in, and both are supported. Pick one per application: | Path | Choose it when | What npm does | |---|---|---| -| **Release tarball** | You want every pack and flavour, installed fast | Downloads the prebuilt `dist/`; builds nothing, needs no `git` or compiler | -| **Git build** | You want only some packs or flavours, or to pin a commit | Clones the repository and builds `dist/` for your selection | +| **Release tarball** | Installing into an application: every pack and flavour, installed fast | Downloads the prebuilt `dist/`; builds nothing, needs no `git` or compiler | +| **Git build** | Contributing, pinning a commit that has no release, or building only some packs or flavours | Clones the repository and runs the `prepare` build for your selection | + +The release tarball is built once, by `release.yml`, when a `vX.Y.Z` tag is pushed (and for a +`vX.Y.Z-rc.N` tag, on a GitHub pre-release). It is attached to that release as +`ichava-js-icon-components-X.Y.Z.tgz`, with its checksum in `SHA256SUMS`. A git install builds +instead, with the compilers (several hundred MB) in npm's temporary clone; see [Size and time](#size-and-time). `"ichava": { "icons": { "install": "tarball" } }` in your application's `package.json` (or `ICHAVA_ICONS_INSTALL=tarball`) makes the choice binding: a git install then stops with the tarball @@ -28,7 +33,10 @@ npm install https://github.com/ichava/js-icon-components/releases/download/v0.1. } ``` -The tarball is `npm pack` output, built once by `release.yml` when the release is tagged. It +The tarball is `npm pack` output, built once by `release.yml` when the release is tagged. Its name +is the one `scripts/prepare.mjs` prints for an `"install": "tarball"` refusal: `release.yml` runs +`scripts/check-release-name.mjs` before publishing and fails on any other name, or a `SHA256SUMS` +that does not list it. It holds `dist/` for every pack, flavour and asset export and nothing else: no source, no tests, and no dependencies. npm runs no build for a tarball, so no compiler, `git` or network access to the packs is needed. Then import the flavour you use, as in the [README](../README.md#quick-start-guide-and-usage).