intacto 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the intacto authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,230 @@
-# Temporary Holding Version
+# intacto
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Check that a CDN serves every file of your npm package exactly as published.**
+
+CDNs such as jsDelivr and unpkg serve npm packages to browsers straight from their caches. A CDN can refuse some files, for example past a package size limit, or serve bytes that differ from the published ones, and nothing says so until a page that loads them breaks. intacto downloads the package's tarball, requests every file in it from each CDN and compares their SHA-256 hashes.
+
+intacto supports three CDNs, and only these three: **jsDelivr**, **unpkg** and **hopjs**.
+
+## Quick start
+
+```sh
+npx intacto is-number
+```
+
+No install, no configuration and no account. A clean run ends like this:
+
+```text
+$ npx intacto is-number@7.0.0 --cdn unpkg
+https://unpkg.com/is-number@7.0.0/
+.... 4 of 4 100% 0:00 left
+4 files, 0.01 MB in 0.6 s
+4 requests: 4 succeeded, 0 failed (0.0%)
+OK: every file matches
+```
+
+## Supported CDNs
+
+intacto supports exactly these three CDNs. Any other value of `--cdn` is an argument error, and no other CDN can be added from the command line.
+
+| `--cdn`    | CDN      | Each file is requested at                              |
+| ---------- | -------- | ------------------------------------------------------ |
+| `jsdelivr` | jsDelivr | `https://cdn.jsdelivr.net/npm/<name>@<version>/<path>` |
+| `unpkg`    | unpkg    | `https://unpkg.com/<name>@<version>/<path>`            |
+| `hopjs`    | hopjs    | `https://cdn.hopjs.net/npm/<name>@<version>/<path>`    |
+
+Without `--cdn`, intacto checks all three, one after another.
+
+## Usage
+
+```sh
+npx intacto <package>[@<version>] [--cdn jsdelivr|unpkg|hopjs]
+```
+
+| Argument       | Meaning                                                                                                                      |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `<package>`    | The package name, scoped or not, such as `is-number` or `@scope/name`.                                                       |
+| `@<version>`   | Anything npm accepts after the name: an exact version, a dist-tag such as `next` or a range such as `^7`. Default: `latest`. |
+| `--cdn <name>` | Check one CDN only: `jsdelivr`, `unpkg` or `hopjs`. Default: all three.                                                      |
+| `-h`, `--help` | Print the usage line.                                                                                                        |
+
+npm resolves the version once, at the start, and every request names that exact version, so a dist-tag that moves during the run changes nothing.
+
+## Recipes
+
+### Check a library before you load it from a CDN
+
+Before a `<script>` tag or an `import` points at a CDN, make sure the CDN serves the version you pinned, byte for byte:
+
+```sh
+npx intacto some-library@3.2.1 --cdn jsdelivr
+```
+
+### Check every release automatically
+
+Add a `postpublish` script to your package. npm runs it right after `npm publish` succeeds, with the name and version it just published in the environment:
+
+```json
+{
+  "scripts": {
+    "postpublish": "npx --yes intacto $npm_package_name@$npm_package_version"
+  }
+}
+```
+
+`--yes` skips npx's install prompt. If a file fails, `npm publish` ends with an error; the package is published by then, so the error is the alert that a CDN needs a look.
+
+Right after a publish, the registry or a CDN can take a moment to see the new version. If intacto reports it missing, run the same check again a minute later.
+
+### Run it in CI after publishing
+
+In GitHub Actions, add a step after the one that publishes:
+
+```yaml
+- run: npx intacto "$(jq -r '.name + "@" + .version' package.json)"
+```
+
+The step fails when any file fails, because intacto exits with status 1. npx doesn't prompt in CI.
+
+### Watch a package every day
+
+A scheduled workflow catches a CDN that starts serving a file wrong after a purge or an outage:
+
+```yaml
+name: CDN check
+
+on:
+  schedule:
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+
+jobs:
+  intacto:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - run: npx intacto your-package
+```
+
+### Check a pre-release before you announce it
+
+```sh
+npx intacto your-package@next
+```
+
+### Check one CDN after purging its cache
+
+```sh
+npx intacto your-package@1.2.3 --cdn jsdelivr
+```
+
+### Check several versions
+
+```sh
+for v in 1.0.0 1.1.0 1.2.0; do
+  npx --yes intacto "your-package@$v" || echo "your-package@$v failed"
+done
+```
+
+Each check downloads every file of that version from each CDN, so keep the list short.
+
+### Keep the report
+
+```sh
+npx intacto your-package > intacto-report.txt || echo "intacto found a problem, see intacto-report.txt"
+```
+
+The progress marks go to stderr, so the file holds just the report.
+
+## Install
+
+npx is enough for an occasional check. To run intacto often, or to pin its version:
+
+```sh
+npm install --global intacto     # then run: intacto your-package
+npm install --save-dev intacto   # then use intacto in your package.json scripts
+```
+
+With intacto as a dev dependency, the `postpublish` script above becomes `intacto $npm_package_name@$npm_package_version`, and nothing is downloaded at publish time.
+
+## How it works
+
+1. **Downloads the tarball.** `npm pack` fetches the package from the registry your npm configuration points to and checks it against the registry's integrity hash. None of the package's scripts run.
+2. **Hashes every file.** intacto unpacks the tarball into a temporary directory, takes the SHA-256 of every file and deletes the directory.
+3. **Requests every file from the CDN,** 128 at a time over 4 HTTP/2 connections. It asks for the encodings browsers accept, decodes gzip, deflate, Brotli or zstd, and compares the SHA-256 of the result with the tarball's.
+4. **Retries what may be temporary.** A network error, 60 seconds without data, a 429 or a 5xx is tried again once every other file has had its try: after 10 seconds, then 20 seconds after that, three tries in all. Any other status, and any file with different bytes, is final.
+5. **Prints the report,** then moves on to the next CDN.
+
+## Reading the output
+
+```text
+$ npx intacto some-package@1.2.3 --cdn unpkg
+https://unpkg.com/some-package@1.2.3/
+...........X.....................X................. 51 of 100 51% 0:01 left
+...............X................................. 100 of 100 100% 0:00 left
+2 failed, trying again in 10 s (2 of 3)
+.X 2 of 2 100% 0:00 left
+1 failed, trying again in 20 s (3 of 3)
+X 1 of 1 100% 0:00 left
+100 files, 2.10 MB in 34.2 s
+103 requests: 98 succeeded, 5 failed (4.9%)
+
+Files with errors: 1
+500 Internal Server Error (1)
+  dist/bundle.js
+
+Files that don't match: 1
+  dist/index.css
+
+FAIL: 2 of 100 files
+```
+
+Each request prints a mark: a dot when the file comes back with a 200 and the right hash, an X for anything else, retries included. Requests go out in npm's file order, which is by path, so a run of X's points at one directory. Each line of marks ends with the round's progress and its time left. In a terminal the line grows in place; in a log, each line is written once it is full.
+
+The report follows:
+
+- **The totals:** the files checked, the bytes received, the time taken and how many requests succeeded. Retries are requests too, so there can be more requests than files.
+- **Files with errors:** the files the CDN would not serve, grouped by HTTP status, or by the network error when there was no status. When the CDN gives its reason as plain text, such as a size limit, the first line of it is part of the group's name.
+- **Files that don't match:** the files that came back with a 200 but different bytes.
+- **The verdict:** `OK: every file matches`, or `FAIL:` with the number of files that failed.
+
+The marks and the retry notices go to stderr and the report to stdout.
+
+## Exit status
+
+| Status | Meaning                                                                                                   |
+| ------ | --------------------------------------------------------------------------------------------------------- |
+| `0`    | Every file matches on every CDN checked.                                                                  |
+| `1`    | At least one file failed or doesn't match, or something else failed, such as npm not finding the package. |
+| `2`    | The arguments are wrong, including a CDN other than `jsdelivr`, `unpkg` or `hopjs`.                       |
+
+## Requirements
+
+- Node.js 22.15 or later, the first 22 release with zstd.
+- Linux or macOS, with `npm` and `tar` on the `PATH`. Windows is not supported.
+- Network access to the npm registry, and a direct HTTP/2 connection to each CDN checked. intacto never goes through an HTTP proxy.
+
+## Limits
+
+- intacto sees only the CDN locations that answer your machine. Run it from elsewhere to check other regions.
+- It checks the files in the tarball, not files the CDN makes itself, such as minified copies or directory listings.
+- Every run downloads the whole unpacked package from each CDN it checks, so a large package means a large download.
+- The time left covers the current round, not the retries that may follow.
+
+## FAQ
+
+**Which CDNs does it support?** jsDelivr, unpkg and hopjs, and no others.
+
+**Does intacto change anything?** It sends only GET requests, so a CDN treats them like any other download: as a side effect, the locations that answer may cache the files they serve. The only thing it writes locally is a temporary copy of the tarball, deleted once every file is hashed, before the first request goes out.
+
+**Does it need an npm account?** No. It only downloads the package, which works without an account for any public package.
+
+**How many requests does it make?** One per file per CDN, plus one per retry. A package of 500 files checked on all three CDNs takes at least 1,500 requests.
+
+**Why does it decode the responses?** CDNs compress what they send. intacto asks for the same encodings a browser does and compares what a browser would end up with, not the compressed bytes.
+
+## License
+
+MIT

package/intacto.mjs

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+// intacto checks that a CDN serves every file of a published npm package
+// exactly as the registry holds it.
+// It reports every file the CDN will not serve, with the CDN's reason when it
+// gives one, such as a package size limit, and every file it serves with
+// other bytes.
+//
+// Usage:
+//   npx intacto <package>[@<version>] [--cdn jsdelivr|unpkg|hopjs]
+//   npx intacto is-number
+//   npx intacto is-number@7.0.0 --cdn unpkg
+//   npx intacto @scope/name@next --cdn jsdelivr
+// The version is anything npm takes after the @: an exact version, a dist-tag
+// or a range, and latest when there is none. npm resolves it once at the start
+// and every request names the exact version, so a tag that moves during the
+// run changes nothing. Without --cdn it checks every CDN in CDNS, one after
+// another; --help prints the usage line. Needs Linux or macOS and Node 22.15
+// or later, which added zstd, with npm and tar on the PATH.
+//
+// What it does:
+// 1. npm pack downloads the tarball and checks it against the registry's
+//    integrity hash. None of the package's scripts run.
+// 2. It unpacks the tarball into a temporary directory, takes the SHA-256 of
+//    every file and deletes the directory.
+// 3. It requests every file from <base><name>@<version>/<path>, where <base>
+//    is the CDN's entry in CDNS, 128 at a time over 4 HTTP/2 connections. It
+//    asks for the encodings browsers accept, undoes gzip, deflate, Brotli or
+//    zstd and compares the SHA-256 of the result with the tarball's. As a
+//    side effect, like any download, the CDN location that answers may cache
+//    the file.
+// 4. A network error, a timeout (60 s without data), a 429 or a 5xx is tried
+//    again once every other file has had its try: after 10 s, then after 20 s
+//    more, three tries in all. Any other status and any mismatch are final.
+// 5. It prints the CDN's report, then moves on to the next CDN.
+// Each of those numbers comes from a constant in the code.
+//
+// Output:
+// For each CDN it prints the base URL, then one mark per request: a dot when
+// the file comes back with a 200 and the right hash, an X for anything else,
+// retried tries included. Requests go out in npm's file order, which is by
+// path, so a run of X's points at one directory. Each line of marks ends with
+// the round's progress and its time left, from the pace of its last 128
+// files. In a terminal the line grows in place; in a log each line is written
+// once full. The marks and the retry notices go to stderr and the report to
+// stdout, so redirecting stdout to a file saves just the report. For example:
+//   $ npx intacto some-package@1.2.3 --cdn unpkg
+//   https://unpkg.com/some-package@1.2.3/
+//   ...........X.....................X................. 51 of 100 51% 0:01 left
+//   ...............X................................. 100 of 100 100% 0:00 left
+//   2 failed, trying again in 10 s (2 of 3)
+//   .X 2 of 2 100% 0:00 left
+//   1 failed, trying again in 20 s (3 of 3)
+//   X 1 of 1 100% 0:00 left
+//   100 files, 2.10 MB in 34.2 s
+//   103 requests: 98 succeeded, 5 failed (4.9%)
+//
+//   Files with errors: 1
+//   500 Internal Server Error (1)
+//     dist/bundle.js
+//
+//   Files that don't match: 1
+//     dist/index.css
+//
+//   FAIL: 2 of 100 files
+// Files with errors are grouped by HTTP status, or by the network error when
+// there was no status, and by the first line of the CDN's reason when it sent
+// one as plain text.
+//
+// Exit status: 0 when every file matches on every CDN it checks; 1 when any
+// file does not, or when something else fails, such as npm not finding the
+// package; 2 when the arguments are wrong.
+//
+// Limits:
+// - It sees only the CDN locations that answer this machine. Run it from
+//   elsewhere to check other regions.
+// - It checks the files in the tarball, not files the CDN makes itself, such
+//   as minified copies or directory listings.
+// - Every run downloads the whole unpacked package from each CDN it checks.
+// - It connects to each CDN directly over HTTP/2, never through an HTTP proxy.
+// - The time left covers the current round, not the retries that may follow.
+//
+// To add a CDN, add its base URL to CDNS. It has to speak HTTP/2 and serve
+// <base><name>@<version>/<path>.
+import { parseArgs } from "node:util";
+import { connect, constants } from "node:http2";
+import { brotliDecompressSync, gunzipSync, inflateSync, zstdDecompressSync } from "node:zlib";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const ACCEPT = "gzip, deflate, br, zstd";
+const DECODE = {
+	br: brotliDecompressSync,
+	gzip: gunzipSync,
+	deflate: inflateSync,
+	zstd: zstdDecompressSync
+};
+const IDLE_MS = 6e4;
+function get(session, path) {
+	return new Promise((resolve, reject) => {
+		const stream = session.request({
+			":path": path,
+			"accept-encoding": ACCEPT
+		});
+		const chunks = [];
+		let headers;
+		stream.setTimeout(IDLE_MS, () => {
+			reject(/* @__PURE__ */ new Error(`nothing for ${IDLE_MS / 1e3} s`));
+			stream.close(constants.NGHTTP2_CANCEL);
+		});
+		stream.on("response", (h) => headers = h);
+		stream.on("data", (chunk) => chunks.push(chunk));
+		stream.on("end", () => {
+			try {
+				if (!headers?.[":status"]) throw new Error("no response");
+				const encoding = headers["content-encoding"];
+				if (encoding && !DECODE[encoding]) throw new Error(`unknown content-encoding ${encoding}`);
+				const body = Buffer.concat(chunks);
+				resolve({
+					status: headers[":status"],
+					type: headers["content-type"],
+					body: encoding ? DECODE[encoding](body) : body
+				});
+			} catch (error) {
+				reject(error);
+			}
+		});
+		stream.on("error", reject);
+		stream.on("close", () => reject(/* @__PURE__ */ new Error(`stream closed with code ${stream.rstCode}`)));
+		stream.end();
+	});
+}
+const sha256 = (data) => createHash("sha256").update(data).digest("base64");
+function pack(spec) {
+	const dir = mkdtempSync(join(tmpdir(), "intacto-"));
+	const run = (command, args) => {
+		const result = spawnSync(command, args, {
+			encoding: "utf8",
+			maxBuffer: 1 << 26,
+			stdio: [
+				"ignore",
+				"pipe",
+				"inherit"
+			]
+		});
+		if (result.error) throw result.error;
+		if (result.status !== 0) {
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+			process.exit(1);
+		}
+		return result.stdout;
+	};
+	try {
+		const [tarball] = Object.values(JSON.parse(run("npm", [
+			"pack",
+			spec,
+			"--json",
+			"--ignore-scripts",
+			"--pack-destination",
+			dir
+		])));
+		mkdirSync(join(dir, "package"));
+		run("tar", [
+			"-xzf",
+			join(dir, tarball.filename),
+			"-C",
+			join(dir, "package"),
+			"--strip-components=1"
+		]);
+		const hashes = tarball.files.map(({ path }) => [path, sha256(readFileSync(join(dir, "package", path)))]);
+		return {
+			name: tarball.name,
+			version: tarball.version,
+			hashes
+		};
+	} finally {
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+const clock = (ms) => `${Math.floor(ms / 6e4)}:${String(Math.floor(ms / 1e3) % 60).padStart(2, "0")}`;
+function progress(count, total, window) {
+	const perLine = Math.max(10, (process.stderr.columns || 80) - ` ${total} of ${total} 100% 999:59 left`.length - 1);
+	let line = "";
+	const stamps = [performance.now()];
+	return (char) => {
+		line += char;
+		const tried = stamps.push(performance.now()) - 1;
+		const from = Math.max(0, tried - window);
+		const left = (stamps[tried] - stamps[from]) / (tried - from) * (count - tried);
+		const text = `${line} ${tried} of ${count} ${Math.floor(100 * tried / count)}% ${clock(left)} left`;
+		const full = line.length === perLine || tried === count;
+		if (process.stderr.isTTY) process.stderr.write(`\r\x1b[K${text}${full ? "\n" : ""}`);
+		else if (full) process.stderr.write(`${text}\n`);
+		if (full) line = "";
+	};
+}
+const CONNECTIONS = 4;
+const TRIES = 3;
+const RETRY_WAIT_MS = 1e4;
+async function check(base, hashes) {
+	console.log(`${base}`);
+	const sessions = [];
+	function session(i) {
+		if (!sessions[i] || sessions[i].closed || sessions[i].destroyed) {
+			sessions[i] = connect(base.origin, { settings: { initialWindowSize: 8 << 20 } });
+			sessions[i].on("connect", (s) => s.setLocalWindowSize(64 << 20));
+			sessions[i].on("error", () => {});
+		}
+		return sessions[i];
+	}
+	const errors = {};
+	const different = [];
+	let bytes = 0;
+	let sent = 0;
+	let lost = 0;
+	const start = performance.now();
+	let files = hashes;
+	for (let round = 1; files.length; round++) {
+		if (round > 1) {
+			const wait = RETRY_WAIT_MS * 2 ** (round - 2);
+			console.error(`${files.length} failed, trying again in ${wait / 1e3} s (${round} of ${TRIES})`);
+			await new Promise((resolve) => setTimeout(resolve, wait));
+		}
+		const retry = [];
+		const mark = progress(files.length, hashes.length, 128);
+		let next = 0;
+		await Promise.all(Array.from({ length: 128 }, async (_, worker) => {
+			for (let i; (i = next++) < files.length;) {
+				const [path, hash] = files[i];
+				sent++;
+				const { status, type, body } = await get(session(worker % CONNECTIONS), base.pathname + path.split("/").map(encodeURIComponent).join("/")).catch((error) => ({
+					status: error.code ?? error.message,
+					body: Buffer.alloc(0)
+				}));
+				const whole = status === 200 && sha256(body) === hash;
+				if (!whole) lost++;
+				if (status === 200) {
+					bytes += body.length;
+					if (!whole) different.push(path);
+				} else if (round < TRIES && (typeof status !== "number" || status === 429 || status >= 500)) retry.push(files[i]);
+				else {
+					const why = type?.startsWith("text/plain") ? body.toString().trim().split("\n")[0].slice(0, 200) : "";
+					(errors[why ? `${status} ${why}` : status] ??= []).push(path);
+				}
+				mark(whole ? "." : "X");
+			}
+		}));
+		files = retry;
+	}
+	for (const s of sessions) s?.close();
+	const seconds = (performance.now() - start) / 1e3;
+	const failed = Object.values(errors).flat().length;
+	console.log(`${hashes.length} files, ${(bytes / 1e6).toFixed(2)} MB in ${seconds.toFixed(1)} s`);
+	console.log(`${sent} requests: ${sent - lost} succeeded, ${lost} failed (${(100 * lost / sent).toFixed(1)}%)`);
+	if (failed) {
+		console.log(`\nFiles with errors: ${failed}`);
+		for (const [reason, paths] of Object.entries(errors).sort((a, b) => b[1].length - a[1].length)) {
+			console.log(`${reason} (${paths.length})`);
+			for (const path of paths.sort()) console.log(`  ${path}`);
+		}
+	}
+	if (different.length) {
+		console.log(`\nFiles that don't match: ${different.length}`);
+		for (const path of different.sort()) console.log(`  ${path}`);
+	}
+	if (failed || different.length) {
+		console.log(`\nFAIL: ${failed + different.length} of ${hashes.length} files`);
+		return false;
+	}
+	console.log("OK: every file matches");
+	return true;
+}
+const CDNS = {
+	jsdelivr: "https://cdn.jsdelivr.net/npm/",
+	unpkg: "https://unpkg.com/",
+	hopjs: "https://cdn.hopjs.net/npm/"
+};
+const usage = (status) => {
+	(status ? console.error : console.log)(`usage: intacto <package>[@<version>] [--cdn ${Object.keys(CDNS).join("|")}]`);
+	process.exit(status);
+};
+function options() {
+	try {
+		return parseArgs({
+			options: {
+				cdn: { type: "string" },
+				help: {
+					type: "boolean",
+					short: "h"
+				}
+			},
+			allowPositionals: true
+		});
+	} catch (error) {
+		console.error(error.message);
+		return usage(2);
+	}
+}
+const { values, positionals } = options();
+if (values.help) usage(0);
+const cdns = values.cdn === void 0 ? Object.keys(CDNS) : [values.cdn];
+if (positionals.length !== 1 || !cdns.every((cdn) => Object.hasOwn(CDNS, cdn))) usage(2);
+const [spec] = positionals;
+const { name, version, hashes } = pack(spec);
+for (const [i, cdn] of cdns.entries()) {
+	if (i) console.log();
+	if (!await check(new URL(`${CDNS[cdn]}${name}@${version}/`), hashes)) process.exitCode = 1;
+}
+export {};

package/package.json

@@ -1,6 +1,16 @@
 {
-  "name": "intacto",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "intacto",
+	"version": "1.0.0",
+	"description": "Checks that a CDN serves every file of an npm package exactly as published",
+	"author": "<city-savage-word@duck.com>",
+	"license": "MIT",
+	"bin": {
+		"intacto": "intacto.mjs"
+	},
+	"files": [
+		"intacto.mjs"
+	],
+	"engines": {
+		"node": ">=22.15"
+	}
+}