asinstalled 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,3 @@
+asinstalled
+Copyright 2026 Theebbanraj Asokan
+https://github.com/Theebban/asinstalled

package/README.md

@@ -0,0 +1,165 @@
+# asinstalled
+
+**Test your npm package the way your users receive it: packed, installed into a clean project,
+and run on every Node version your `engines` field promises.**
+
+The package you test is not the package your users install. You run tests against your source
+tree. Your users get a tarball, filtered by `files`, resolved through `exports` and `bin`,
+running on whatever Node version `engines` admits, often the oldest. Every failure below passes
+the maintainer's own test suite:
+
+- an entry point or binary that `files` quietly leaves out of the tarball;
+- a feature newer than the Node version `engines` claims to support;
+- a binary without a `#!` line, so it cannot run as a command;
+- a README that documents a script that no longer exists, or a `git clone <this repo>` placeholder; <!-- asinstalled-ignore -->
+- a published version whose content is not what the tagged source builds.
+
+`asinstalled` catches each of them, from the consumer's side.
+
+## Install
+
+```bash
+npm install --save-dev asinstalled
+```
+
+Requires Node 22 or newer to run; the package it checks can declare any floor. macOS and Linux.
+
+## Commands
+
+```bash
+npx asinstalled check                        # pack, install, run on the engines floor and current Node
+npx asinstalled check --run "mycli --help"   # also run a binary, and require exit 0
+npx asinstalled check --script smoke.mjs     # also run your own smoke script inside the consumer
+npx asinstalled docs                         # check the Markdown against package.json
+npx asinstalled published                    # check the registry artifact against a fresh build
+```
+
+Exit status: `0` when every check passed, `1` when any failed, `2` for a usage or setup error.
+Every command takes `--dir <path>` and `--json`.
+
+### `check`
+
+1. Packs the package exactly as `npm publish` would, `prepack` included.
+2. Confirms every file named in `exports`, `main` and `bin` is actually inside the tarball.
+3. Installs the tarball into an empty project.
+4. On each Node version under test, imports every declared entry point (by `import` or `require`,
+   as the package declares) and runs the configured binaries and smoke script, all from the
+   installed copy and all with that exact Node binary, never the `node` on your `PATH`.
+
+**The engines floor.** By default it tests the lowest version your `engines.node` range admits,
+plus the Node you are running. The floor build is downloaded from nodejs.org, checked against
+the SHA-256 in Node's published `SHASUMS256.txt`, and cached. A range whose floor it cannot
+determine (`>20`, `<22`, `lts`) is refused with an error rather than guessed. Choose versions
+explicitly with `--node 20.11.1,22.0.0,current`, or pass a path to a `node` binary.
+
+Binaries are only executed when you say how (`--run`); an unknown CLI run with no arguments
+might start a server. Without `--run` they are checked for presence and a `#!` line.
+
+### `docs`
+
+Checks every Markdown file for references that no longer match `package.json`:
+`npm run <script>` and `npm test` naming scripts that do not exist, `npx <package>` when that
+binary is not declared, `git clone` with a placeholder instead of a URL, relative links to
+missing files, and a public package whose docs never show how to install it.
+
+Only text a reader is told to **run** is checked: fenced code blocks and inline code. A sentence
+describing a removed script is history, not an instruction, and changelogs are checked for
+broken links only.
+
+A deliberate exception, such as documentation that quotes a bad command as an example, is
+marked where a reader can see it: `<!-- asinstalled-ignore -->` on the line, or
+`<!-- asinstalled-ignore-next-line -->` above it. Suppressed lines are counted and listed in
+the report.
+
+It always reports how many references it checked, so a run that matched nothing cannot pass
+for a clean one.
+
+### `published`
+
+For the version in `package.json`, after a release:
+
+- **exists**: the exact version is live on the registry;
+- **identical**: its content equals a fresh build of your checkout. The registry tarball is
+  first verified against the registry's own `integrity`, then both sides are decompressed and
+  compared. The gzip layer is deliberately ignored: the same tarball compresses to different
+  bytes under different zlib builds, which says nothing about what users install;
+- **provenance**: a SLSA provenance attestation is attached, and which repository and workflow
+  it names;
+- **tag**: the repository has a `v<version>` tag.
+
+Provenance is reported as **attached, not cryptographically verified**. For signature
+verification, run `npm audit signatures` in a project that installs the package.
+
+## Security: what running asinstalled executes
+
+asinstalled checks a package by doing what a consumer does, so **it runs that package's code**.
+Use it on packages you trust, which normally means your own.
+
+- `check` runs `npm pack`, which runs the package's `prepack` and `prepare` scripts in your
+  project directory.
+- It then runs `npm install` on the tarball in a temporary project. With npm's default
+  configuration that runs the package's `preinstall`, `install` and `postinstall` scripts, and
+  those of every dependency. (npm 11 warns about install scripts you have not approved, but runs
+  them unless `strict-allow-scripts` is set.) asinstalled uses your npm and your npm
+  configuration: if you enforce `ignore-scripts` or `strict-allow-scripts`, so does it, and it
+  then models consumers who do the same.
+- It imports every entry point and runs the binaries and smoke script you configure. That is
+  code execution, by design.
+- Every child process inherits your environment, including any tokens in it. **In CI, run
+  asinstalled in a job that holds no publishing credentials**: not in a job with an npm token,
+  and not in one granted `id-token: write`.
+- `published` downloads the registry tarball, then hashes and decompresses it. It does not run it.
+- Node builds are downloaded from nodejs.org and checked against Node's published SHA-256 list.
+  The list's GPG signature is not checked.
+
+It is not a sandbox, and it does not safely inspect untrusted or malicious packages. For those,
+use a disposable container or VM that holds no credentials, or a dedicated supply-chain scanner.
+
+## Use in CI
+
+```yaml
+  consumer-path:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read          # no publishing credentials in this job
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: npm ci
+      - run: npx asinstalled check --run "mycli --help"
+      - run: npx asinstalled docs
+```
+
+## Where it sits
+
+It complements, and does not replace:
+
+- **[publint](https://github.com/publint/publint)** and
+  **[arethetypeswrong](https://github.com/arethetypeswrong/arethetypeswrong.github.io)**, which
+  check your `package.json` and type declarations statically. `asinstalled` executes the
+  installed package;
+- **[np](https://github.com/sindresorhus/np)** and **[release-it](https://github.com/release-it/release-it)**,
+  which run your release. `asinstalled` checks what that release will deliver, and what it did;
+- **a CI matrix over Node versions**, which usually runs your *source* on each version. That
+  can fail where the shipped package works (a source tree that needs a newer runtime flag) and
+  pass where it breaks (a file missing from `files`).
+
+## Limits, stated
+
+npm only (no Yarn, pnpm or Bun installs yet). macOS and Linux Node builds. The checksum list
+is fetched over HTTPS but its GPG signature is not verified. Native dependencies are installed
+with the current Node and may not match the floor. Executing arbitrary README code blocks is
+out of scope ([doc-detective](https://github.com/doc-detective/doc-detective) does that).
+
+## Development
+
+```bash
+npm install
+npm run check        # typecheck, lint and tests
+npm run self-check   # asinstalled checks itself as installed, on its own engines floor
+```
+
+Development runs TypeScript directly through Node's type stripping, so it needs Node 22.6 or
+newer; the published package runs on Node 22.0 and newer.

package/dist/check.js

@@ -0,0 +1,132 @@
+// `asinstalled check`: THE PACKAGE AS A CONSUMER RECEIVES IT.
+//
+// 1. Pack it the way `npm publish` would, `prepack` included.
+// 2. Statically confirm every declared entry point and binary is actually inside the tarball.
+// 3. Install the tarball into a fresh, empty project.
+// 4. On EACH Node version under test, import every declared entry point from that installed
+//    copy, run every binary the maintainer told us how to run, and run an optional smoke
+//    script, all with that exact Node binary rather than whatever `node` is on PATH.
+//
+// Nothing here reads the source tree after packing. That is the point.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { readManifest } from "./manifest.js";
+export function packProject(projectDir, destination) {
+    const out = execFileSync('npm', ['pack', '--json', '--pack-destination', destination], {
+        cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    // npm prints lifecycle output (prepack) before the JSON array; take the array.
+    const json = out.slice(out.indexOf('['));
+    const entry = JSON.parse(json)[0];
+    if (entry === undefined)
+        throw new Error('npm pack produced no tarball');
+    return entry;
+}
+/**
+ * The part of a failed run's output a reader needs: the error MESSAGE, which Node prints
+ * before the stack, rather than the last stack frames, which say where and not what.
+ */
+function tail(s) {
+    const lines = (s ?? '').trim().split('\n').map((l) => l.trim()).filter((l) => l.length > 0);
+    const message = lines.find((l) => /^(\w*Error|Error)\b|: .*Error:|^Error \[/.test(l) || /^\w+Error: /.test(l));
+    return (message ?? lines.slice(-2).join(' | ')).slice(0, 400);
+}
+function run(binary, args, cwd) {
+    const r = spawnSync(binary, args, { cwd, encoding: 'utf8', timeout: 120_000 });
+    if (r.error)
+        return { ok: false, detail: r.error.message };
+    if (r.status === 0)
+        return { ok: true, detail: 'exit 0' };
+    return { ok: false, detail: `exit ${r.status ?? r.signal}: ${tail(r.stderr) || tail(r.stdout)}` };
+}
+/** Files an export target or bin path points at, normalised to tarball paths. */
+function declaredFiles(projectDir, m) {
+    const pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'));
+    const out = new Set();
+    const walk = (v) => {
+        if (typeof v === 'string') {
+            if (v.startsWith('./') && !v.includes('*'))
+                out.add(v.slice(2));
+            return;
+        }
+        if (v !== null && typeof v === 'object')
+            for (const x of Object.values(v))
+                walk(x);
+    };
+    if (pkg['exports'] !== undefined)
+        walk(pkg['exports']);
+    else if (typeof pkg['main'] === 'string')
+        out.add(String(pkg['main']).replace(/^\.\//, ''));
+    for (const p of Object.values(m.bins))
+        out.add(p.replace(/^\.\//, ''));
+    out.delete('package.json');
+    return [...out];
+}
+export function runCheck(opts) {
+    const manifest = readManifest(opts.projectDir);
+    const work = mkdtempSync(join(tmpdir(), 'asinstalled-'));
+    const findings = [];
+    const all = 'all';
+    try {
+        const packed = packProject(opts.projectDir, work);
+        const inTarball = new Set(packed.files.map((f) => f.path));
+        for (const f of declaredFiles(opts.projectDir, manifest)) {
+            findings.push({
+                check: 'packed-contents', node: all, target: f, ok: inTarball.has(f),
+                detail: inTarball.has(f) ? 'in the tarball' : 'declared in package.json but NOT in the tarball (check "files" and the build)',
+            });
+        }
+        const consumer = join(work, 'consumer');
+        mkdirSync(consumer, { recursive: true });
+        writeFileSync(join(consumer, 'package.json'), JSON.stringify({ name: 'asinstalled-consumer', version: '0.0.0', private: true }));
+        const install = spawnSync('npm', ['install', join(work, packed.filename), '--no-audit', '--no-fund', '--no-package-lock'], {
+            cwd: consumer, encoding: 'utf8', timeout: 600_000,
+        });
+        const installed = install.status === 0;
+        findings.push({ check: 'install', node: all, target: packed.filename, ok: installed,
+            detail: installed ? 'installed into an empty project' : `npm install failed: ${tail(install.stderr)}` });
+        if (!installed)
+            return { manifest, tarball: { filename: packed.filename, integrity: packed.integrity, fileCount: packed.files.length }, findings, workdir: opts.keepWorkdir ? work : null };
+        let smoke = null;
+        if (opts.smokeScript !== undefined) {
+            smoke = join(consumer, basename(opts.smokeScript));
+            copyFileSync(opts.smokeScript, smoke);
+        }
+        for (const n of opts.nodes) {
+            for (const e of manifest.entryPoints) {
+                const code = e.loader === 'import' ? `await import(${JSON.stringify(e.specifier)})` : `require(${JSON.stringify(e.specifier)})`;
+                const args = e.loader === 'import' ? ['--input-type=module', '-e', code] : ['-e', code];
+                const r = run(n.binary, args, consumer);
+                findings.push({ check: e.loader, node: n.label, target: e.specifier, ...r });
+            }
+            for (const [bin, rel] of Object.entries(manifest.bins)) {
+                const path = join(consumer, 'node_modules', manifest.name, rel);
+                if (!existsSync(path)) {
+                    findings.push({ check: 'bin', node: n.label, target: bin, ok: false, detail: `installed package has no ${rel}` });
+                    continue;
+                }
+                const shebang = readFileSync(path, 'utf8').startsWith('#!');
+                const args = opts.runBins?.[bin];
+                if (args === undefined) {
+                    findings.push({ check: 'bin', node: n.label, target: bin, ok: shebang,
+                        detail: shebang ? 'present with a shebang; not executed (no arguments configured)' : `${rel} has no #! line, so it cannot run as a command` });
+                    continue;
+                }
+                const r = run(n.binary, [path, ...args], consumer);
+                findings.push({ check: 'bin', node: n.label, target: `${bin} ${args.join(' ')}`.trim(), ...r });
+            }
+            if (smoke !== null) {
+                const isTs = smoke.endsWith('.ts');
+                const r = run(n.binary, isTs ? ['--experimental-strip-types', smoke] : [smoke], consumer);
+                findings.push({ check: 'script', node: n.label, target: basename(smoke), ...r });
+            }
+        }
+        return { manifest, tarball: { filename: packed.filename, integrity: packed.integrity, fileCount: packed.files.length }, findings, workdir: opts.keepWorkdir ? work : null };
+    }
+    finally {
+        if (!opts.keepWorkdir)
+            rmSync(work, { recursive: true, force: true });
+    }
+}

package/dist/cli.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// asinstalled: check a package the way its users receive it.
+//
+//   asinstalled check      pack, install into a clean project, run on the engines floor and current Node
+//   asinstalled docs       check the Markdown documentation against the package
+//   asinstalled published  check the registry artifact against a fresh build, its provenance and its tag
+//
+// Exit status: 0 when every check passed, 1 when any check failed, 2 for a usage or setup error.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { readManifest } from "./manifest.js";
+import { enginesFloor } from "./engines.js";
+import { obtainNode } from "./nodeDist.js";
+import { runCheck } from "./check.js";
+import { runDocs } from "./docs.js";
+import { runPublished } from "./published.js";
+const USAGE = `usage:
+  asinstalled check     [--dir <path>] [--node floor,current,<version>,<path>] [--run "<bin> <args...>"]... [--script <file>] [--keep] [--json]
+  asinstalled docs      [--dir <path>] [--json]
+  asinstalled published [--dir <path>] [--registry <url>] [--no-compare] [--json]`;
+class UsageError extends Error {
+}
+function parse(argv) {
+    const a = { command: argv[0] ?? '', dir: '.', nodes: [], runs: [], keep: false, json: false, compare: true };
+    for (let i = 1; i < argv.length; i++) {
+        const flag = argv[i];
+        const value = () => {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new UsageError(`${flag} needs a value`);
+            return v;
+        };
+        switch (flag) {
+            case '--dir':
+                a.dir = value();
+                break;
+            case '--node':
+                a.nodes.push(...value().split(',').map((s) => s.trim()).filter(Boolean));
+                break;
+            case '--run':
+                a.runs.push(value());
+                break;
+            case '--script':
+                a.script = value();
+                break;
+            case '--registry':
+                a.registry = value();
+                break;
+            case '--keep':
+                a.keep = true;
+                break;
+            case '--json':
+                a.json = true;
+                break;
+            case '--no-compare':
+                a.compare = false;
+                break;
+            default: throw new UsageError(`unknown argument "${flag}"`);
+        }
+    }
+    return a;
+}
+async function resolveNodes(specs, enginesRange) {
+    const wanted = specs.length > 0 ? specs : ['floor', 'current'];
+    const out = [];
+    const seen = new Set();
+    const add = (label, binary, version) => {
+        if (seen.has(version))
+            return;
+        seen.add(version);
+        out.push({ label, binary });
+    };
+    for (const s of wanted) {
+        if (s === 'current')
+            add(`${process.version.slice(1)} (current)`, process.execPath, process.version.slice(1));
+        else if (s === 'floor') {
+            const f = enginesFloor(enginesRange);
+            if (!f.ok)
+                throw new UsageError(`${f.reason}. Pass --node <version> to choose one explicitly.`);
+            add(`${f.version} (engines floor)`, await obtainNode(f.version, { log: (l) => console.error(`  ${l}`) }), f.version);
+        }
+        else if (/^v?\d+\.\d+\.\d+$/.test(s)) {
+            const v = s.replace(/^v/, '');
+            add(v, await obtainNode(v, { log: (l) => console.error(`  ${l}`) }), v);
+        }
+        else {
+            add(s, resolve(s), s);
+        }
+    }
+    return out;
+}
+function print(rows, json, asJson) {
+    const failed = rows.filter((r) => !r.ok).length;
+    if (asJson)
+        console.log(JSON.stringify(json, null, 2));
+    else {
+        for (const r of rows)
+            console.log(`${r.ok ? 'PASS' : 'FAIL'}  ${r.cols.join('  ')}`);
+        console.log(`\n${rows.length - failed} of ${rows.length} checks passed${failed > 0 ? `, ${failed} FAILED` : ''}.`);
+    }
+    return failed > 0 ? 1 : 0;
+}
+async function main(argv) {
+    if (argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
+        console.log(USAGE);
+        return 0;
+    }
+    if (argv[0] === '--version' || argv[0] === '-v') {
+        const self = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        console.log(self.version);
+        return 0;
+    }
+    const args = parse(argv);
+    const dir = resolve(args.dir);
+    const manifest = readManifest(dir);
+    if (args.command === 'check') {
+        const runBins = {};
+        for (const r of args.runs) {
+            const [bin, ...rest] = r.split(/\s+/).filter(Boolean);
+            if (bin === undefined)
+                throw new UsageError('--run needs "<bin> <args...>"');
+            runBins[bin] = rest;
+        }
+        const nodes = await resolveNodes(args.nodes, manifest.enginesNode);
+        if (!args.json)
+            console.log(`${manifest.name}@${manifest.version} as installed, on: ${nodes.map((n) => n.label).join(', ')}\n`);
+        const r = runCheck({ projectDir: dir, nodes, runBins, keepWorkdir: args.keep, ...(args.script !== undefined ? { smokeScript: resolve(args.script) } : {}) });
+        if (!args.json)
+            console.log(`tarball ${r.tarball.filename}: ${r.tarball.fileCount} files${r.workdir ? `, kept at ${r.workdir}` : ''}\n`);
+        return print(r.findings.map((f) => ({ ok: f.ok, cols: [f.check.padEnd(15), f.node.padEnd(22), f.target, `(${f.detail})`] })), r, args.json);
+    }
+    if (args.command === 'docs') {
+        const r = runDocs(dir, manifest);
+        if (!args.json) {
+            const c = r.checked;
+            console.log(`${r.files.length} Markdown file(s); references checked: ${c.script} script, ${c.bin} binary, ${c.clone} clone, ${c.link} link, ${c.install} install`);
+            console.log(r.suppressed.length > 0 ? `${r.suppressed.length} line(s) suppressed by an ignore comment: ${r.suppressed.join(', ')}\n` : '');
+            if (r.files.length === 0)
+                console.log('no Markdown files found: nothing was checked, which is not the same as clean');
+        }
+        const total = Object.values(r.checked).reduce((s, n) => s + n, 0);
+        const rows = r.findings.map((f) => ({ ok: false, cols: [f.rule.padEnd(8), `${f.file}:${f.line}`, f.detail] }));
+        if (args.json)
+            console.log(JSON.stringify(r, null, 2));
+        else {
+            for (const row of rows)
+                console.log(`FAIL  ${row.cols.join('  ')}`);
+            console.log(`\n${total - rows.length} of ${total} references consistent${rows.length > 0 ? `, ${rows.length} FAILED` : ''}.`);
+        }
+        return rows.length > 0 || r.files.length === 0 ? 1 : 0;
+    }
+    if (args.command === 'published') {
+        const f = await runPublished({ projectDir: dir, manifest, compareLocal: args.compare, ...(args.registry !== undefined ? { registry: args.registry } : {}) });
+        if (!args.json)
+            console.log(`${manifest.name}@${manifest.version} as published\n`);
+        const code = print(f.map((x) => ({ ok: x.ok, cols: [x.check.padEnd(11), x.detail] })), f, args.json);
+        if (!args.json)
+            console.log('provenance is reported as attached, not cryptographically verified; run `npm audit signatures` in a consumer project for that.');
+        return code;
+    }
+    throw new UsageError(args.command === '' ? 'no command given' : `unknown command "${args.command}"`);
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    if (err instanceof UsageError) {
+        console.error(`asinstalled: ${err.message}\n\n${USAGE}`);
+        process.exit(2);
+    }
+    console.error(`asinstalled: ${err.message}`);
+    process.exit(2);
+});

package/dist/docs.js

@@ -0,0 +1,135 @@
+// `asinstalled docs`: DOES THE DOCUMENTATION DESCRIBE THIS PACKAGE, OR AN EARLIER ONE?
+//
+// Documentation is part of what a consumer receives, and it drifts silently: nothing fails
+// when a README names a script that was deleted. Each rule below exists because it happened:
+//
+//   script    `npm run <x>` / `npm test` / `npm start` names a script package.json no longer has
+//   bin       `npx <this package>` when the package does not declare that binary
+//   clone     a `git clone` whose argument is a placeholder rather than a URL or path
+//   link      a relative Markdown link to a file that does not exist
+//   install   a public package whose README never shows the command to install it
+//
+// Command rules apply only where a reader is told to RUN something: fenced code blocks and
+// inline code. A sentence describing a removed script or a past bug is history, not an
+// instruction, and flagging it would punish exactly the honesty a changelog is for. For the
+// same reason, changelogs are checked for broken links only.
+//
+// A deliberate exception is written where a reader can see it: an HTML comment
+// `<!-- asinstalled-ignore -->` on the line, or `<!-- asinstalled-ignore-next-line -->` on the
+// line before. Suppressions are COUNTED and reported, so they can be audited rather than
+// becoming a quiet hole.
+//
+// Subdirectories that contain their own package.json are different packages and are skipped:
+// their scripts are not this package's scripts.
+//
+// Every report states how many references were CHECKED, so a run that matched nothing can
+// never read as a clean result.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+function markdownFiles(projectDir) {
+    const out = [];
+    const skip = new Set(['node_modules', '.git', 'dist', 'coverage']);
+    const walk = (dir) => {
+        for (const name of readdirSync(dir)) {
+            if (skip.has(name) || name.startsWith('.'))
+                continue;
+            const p = join(dir, name);
+            if (statSync(p).isDirectory()) {
+                if (existsSync(join(p, 'package.json')))
+                    continue; // a nested package is not this package
+                walk(p);
+            }
+            else if (name.toLowerCase().endsWith('.md'))
+                out.push(p);
+        }
+    };
+    walk(projectDir);
+    return out.sort();
+}
+const NPM_RUN = /\bnpm\s+(?:run|run-script)\s+([A-Za-z0-9:_.-]+)/g;
+const NPM_LIFECYCLE = /\bnpm\s+(test|start|stop|restart)\b(?!\s*[=:])/g;
+const NPX = /\bnpx\s+(?:(?:--no-install|--yes|-y|--package=\S+|-p\s+\S+)\s+)*([@A-Za-z0-9/._-]+)/g;
+const CLONE = /\bgit\s+clone\s+(\S+)/g;
+const LINK = /!?\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const INSTALL = /\b(?:npm\s+(?:install|i|add)|pnpm\s+add|yarn\s+add|bun\s+add)\s+(?:-{1,2}\S+\s+)*([@A-Za-z0-9/._-]+)/g;
+export function runDocs(projectDir, manifest, files = markdownFiles(projectDir)) {
+    const findings = [];
+    const suppressed = [];
+    const checked = { script: 0, bin: 0, clone: 0, link: 0, install: 0 };
+    let installsThisPackage = 0;
+    for (const file of files) {
+        const rel = relative(projectDir, file);
+        const lines = readFileSync(file, 'utf8').split('\n');
+        const isHistory = /^(changelog|history|changes|releases?)([._-].*)?\.md$/i.test(file.split('/').pop() ?? '');
+        let inFence = false;
+        lines.forEach((raw, i) => {
+            const line = i + 1;
+            if (/^\s*(```|~~~)/.test(raw)) {
+                inFence = !inFence;
+                return;
+            }
+            // A marker counts only as a real comment, not as text quoting one inside inline code.
+            const bare = (t) => t.replace(/`[^`]*`/g, '');
+            if (/<!--\s*asinstalled-ignore\s*-->/.test(bare(raw)) || /<!--\s*asinstalled-ignore-next-line\s*-->/.test(bare(lines[i - 1] ?? ''))) {
+                suppressed.push(`${rel}:${line}`);
+                return;
+            }
+            // The runnable part of this line: all of it inside a fence, only its inline code outside.
+            const text = isHistory ? '' : inFence ? raw : [...raw.matchAll(/`([^`]+)`/g)].map((m) => m[1]).join('\n');
+            for (const m of text.matchAll(NPM_RUN)) {
+                const name = m[1] ?? '';
+                checked.script++;
+                if (!(name in manifest.scripts))
+                    findings.push({ file: rel, line, rule: 'script', detail: `\`npm run ${name}\`: package.json has no "${name}" script` });
+            }
+            for (const m of text.matchAll(NPM_LIFECYCLE)) {
+                const name = m[1] ?? '';
+                checked.script++;
+                if (!(name in manifest.scripts))
+                    findings.push({ file: rel, line, rule: 'script', detail: `\`npm ${name}\`: package.json has no "${name}" script` });
+            }
+            for (const m of text.matchAll(NPX)) {
+                const name = m[1] ?? '';
+                if (name !== manifest.name)
+                    continue; // npx of other packages is not ours to judge
+                checked.bin++;
+                const bare = name.replace(/^@[^/]+\//, '');
+                if (!(bare in manifest.bins))
+                    findings.push({ file: rel, line, rule: 'bin', detail: `\`npx ${name}\`: the package declares no "${bare}" binary` });
+            }
+            for (const m of text.matchAll(CLONE)) {
+                const arg = m[1] ?? '';
+                checked.clone++;
+                const looksReal = /^(https?:\/\/|git@|ssh:\/\/|file:\/\/|\.{0,2}\/)/.test(arg);
+                if (!looksReal)
+                    findings.push({ file: rel, line, rule: 'clone', detail: `\`git clone ${arg}\` is a placeholder, not something a reader can run` });
+            }
+            for (const m of inFence ? [] : raw.matchAll(LINK)) {
+                const target = m[1] ?? '';
+                if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('#'))
+                    continue;
+                const path = decodeURIComponent(target.split('#')[0].split('?')[0]);
+                if (path.length === 0)
+                    continue;
+                checked.link++;
+                if (!existsSync(join(dirname(file), path)))
+                    findings.push({ file: rel, line, rule: 'link', detail: `link to "${target}", which does not exist` });
+            }
+            for (const m of text.matchAll(INSTALL)) {
+                const raw = m[1] ?? '';
+                // Drop a version or tag suffix: `pkg@1.2.0` -> `pkg`, `@scope/pkg@next` -> `@scope/pkg`.
+                const spec = raw.startsWith('@') ? raw.replace(/^(@[^/]+\/[^@]+)@.*$/, '$1') : raw.replace(/@.*$/, '');
+                if (spec === manifest.name)
+                    installsThisPackage++;
+            }
+        });
+    }
+    if (!manifest.isPrivate) {
+        checked.install++;
+        if (installsThisPackage === 0 && files.length > 0) {
+            findings.push({ file: relative(projectDir, files[0]), line: 0, rule: 'install',
+                detail: `no documentation shows how to install "${manifest.name}" (for example \`npm install ${manifest.name}\`)` });
+        }
+    }
+    return { files: files.map((f) => relative(projectDir, f)), checked, findings, suppressed };
+}

package/dist/engines.js

@@ -0,0 +1,58 @@
+// THE ENGINES FLOOR: the lowest Node version a package's `engines.node` field admits.
+//
+// This is the version a package most often breaks on without anyone noticing, because
+// maintainers develop on something newer. A floor that cannot be determined is REFUSED, not
+// guessed: a guessed floor would turn "we tested the version you promised" into "we tested a
+// version we picked", which is the failure this tool exists to catch.
+//
+// Supported forms: `>=X[.Y[.Z]]`, `^X.Y.Z`, `~X.Y.Z`, `X.Y.Z`, `X`, `X.x`, `X.Y.x`, and
+// alternatives joined by `||` (the floor is the lowest alternative). A range with an upper
+// bound only, a `<` or `>` without `=`, or anything else is refused with the reason.
+function parseLoose(v) {
+    const m = /^v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/.exec(v.trim());
+    if (m === null)
+        return null;
+    const n = (s) => (s === undefined || s === 'x' || s === '*' ? 0 : Number(s));
+    return [n(m[1]), n(m[2]), n(m[3])];
+}
+function compare(a, b) {
+    return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+function floorOfComparatorSet(set) {
+    // Semver allows a space between an operator and its version: `>= 20.11` means `>=20.11`.
+    const parts = set.trim().replace(/(>=|<=|>|<|=|\^|~)\s+/g, '$1').split(/\s+/).filter((p) => p.length > 0);
+    if (parts.length === 0)
+        return 'empty range';
+    let floor = null;
+    for (const part of parts) {
+        const m = /^(?:>=|\^|~|=)?(.+)$/.exec(part);
+        if (m === null)
+            return `unsupported comparator "${part}"`;
+        if (part.startsWith('<'))
+            continue; // an upper bound does not move the floor
+        if (part.startsWith('>') && !part.startsWith('>='))
+            return `"${part}" has an exclusive lower bound; pass --node explicitly`;
+        const t = parseLoose(m[1] ?? '');
+        if (t === null)
+            return `unsupported version "${part}"`;
+        if (floor === null || compare(t, floor) > 0)
+            floor = t;
+    }
+    return floor ?? 'the range has no lower bound';
+}
+export function enginesFloor(range) {
+    if (range === null || range.trim() === '' || range.trim() === '*') {
+        return { ok: false, reason: 'package.json declares no engines.node, so there is no promised floor to test' };
+    }
+    let lowest = null;
+    for (const alt of range.split('||')) {
+        const f = floorOfComparatorSet(alt);
+        if (typeof f === 'string')
+            return { ok: false, reason: `cannot determine the floor of "${range}": ${f}` };
+        if (lowest === null || compare(f, lowest) < 0)
+            lowest = f;
+    }
+    if (lowest === null)
+        return { ok: false, reason: `cannot determine the floor of "${range}"` };
+    return { ok: true, version: lowest.join('.') };
+}

package/dist/manifest.js

@@ -0,0 +1,95 @@
+// WHAT THE PACKAGE CLAIMS. Read from package.json exactly as a consumer's tooling reads it.
+//
+// Entry points come from `exports` when present, because that is what Node resolves and what
+// a consumer can import; `main` is used only when there is no `exports`. Binaries come from
+// `bin`, in either of its two shapes.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Which loaders a single export target supports. A string target is loadable both ways. */
+function loadersOf(target, packageType) {
+    const out = new Set();
+    if (typeof target === 'string') {
+        // A bare path's module kind follows its extension and the package "type".
+        if (target.endsWith('.cjs') || (!target.endsWith('.mjs') && packageType !== 'module'))
+            out.add('require');
+        else
+            out.add('import');
+        return out;
+    }
+    if (!isObject(target))
+        return out;
+    for (const [condition, value] of Object.entries(target)) {
+        if (condition === 'types')
+            continue;
+        if (condition === 'import')
+            out.add('import');
+        else if (condition === 'require')
+            out.add('require');
+        else if (condition === 'default' || condition === 'node') {
+            for (const l of loadersOf(value, packageType))
+                out.add(l);
+        }
+    }
+    return out;
+}
+function entryPointsFrom(pkg, name) {
+    const packageType = pkg['type'] === 'module' ? 'module' : 'commonjs';
+    const exp = pkg['exports'];
+    const entries = [];
+    const add = (subpath, target) => {
+        // Patterns ("./*") and explicitly blocked subpaths (null) cannot be probed as one specifier.
+        if (subpath.includes('*') || target === null)
+            return;
+        const specifier = subpath === '.' ? name : `${name}/${subpath.replace(/^\.\//, '')}`;
+        for (const loader of loadersOf(target, packageType))
+            entries.push({ specifier, loader });
+    };
+    if (exp !== undefined) {
+        if (typeof exp === 'string' || (isObject(exp) && !Object.keys(exp).some((k) => k.startsWith('.')))) {
+            add('.', exp);
+        }
+        else if (isObject(exp)) {
+            for (const [subpath, target] of Object.entries(exp)) {
+                // package.json is a conventional export, not code; loading it proves nothing.
+                if (subpath === './package.json')
+                    continue;
+                add(subpath, target);
+            }
+        }
+        return entries;
+    }
+    if (typeof pkg['main'] === 'string')
+        add('.', pkg['main']);
+    return entries;
+}
+export function readManifest(dir) {
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    const name = pkg['name'];
+    const version = pkg['version'];
+    if (typeof name !== 'string' || typeof version !== 'string') {
+        throw new Error(`${join(dir, 'package.json')} has no string "name" and "version"`);
+    }
+    const engines = isObject(pkg['engines']) ? pkg['engines'] : {};
+    const rawBin = pkg['bin'];
+    const bins = {};
+    if (typeof rawBin === 'string')
+        bins[name.replace(/^@[^/]+\//, '')] = rawBin;
+    else if (isObject(rawBin))
+        for (const [k, v] of Object.entries(rawBin))
+            if (typeof v === 'string')
+                bins[k] = v;
+    return {
+        name,
+        version,
+        enginesNode: typeof engines['node'] === 'string' ? engines['node'] : null,
+        entryPoints: entryPointsFrom(pkg, name),
+        bins,
+        scripts: isObject(pkg['scripts'])
+            ? Object.fromEntries(Object.entries(pkg['scripts']).filter(([, v]) => typeof v === 'string'))
+            : {},
+        isPrivate: pkg['private'] === true,
+    };
+}

package/dist/nodeDist.js

@@ -0,0 +1,78 @@
+// OBTAINING AN EXACT NODE VERSION, verified before it is trusted.
+//
+// The official build is downloaded from the Node.js distribution, its SHA-256 is checked
+// against the checksum list Node publishes beside it, and only then is it extracted. A
+// mismatch is refused, never retried silently: a binary that does not match its published
+// checksum is not the binary the check claims to have run.
+//
+// Limits, stated rather than implied: the checksum list is fetched over HTTPS and its
+// detached GPG signature is NOT verified; Windows builds are not supported; the cache is
+// trusted once written.
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+export class ChecksumMismatchError extends Error {
+    constructor(file, expected, actual) {
+        super(`${file}: SHA-256 ${actual} does not match the published ${expected}. Refusing to use it.`);
+        this.name = 'ChecksumMismatchError';
+    }
+}
+export function defaultCacheDir() {
+    return join(process.env['XDG_CACHE_HOME'] ?? join(homedir(), '.cache'), 'asinstalled', 'node');
+}
+function distPlatform(p) {
+    if (p === 'darwin' || p === 'linux')
+        return p;
+    throw new Error(`Node builds for platform "${p}" are not supported by asinstalled`);
+}
+async function fetchBytes(url) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`GET ${url} returned ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+}
+/** Path to a `node` executable of exactly `version`, downloading and verifying it if needed. */
+export async function obtainNode(version, opts = {}) {
+    const v = version.replace(/^v/, '');
+    const platform = distPlatform(opts.platform ?? process.platform);
+    const arch = opts.arch ?? process.arch;
+    const base = (opts.baseUrl ?? 'https://nodejs.org/dist').replace(/\/$/, '');
+    const stem = `node-v${v}-${platform}-${arch}`;
+    const cacheRoot = opts.cacheDir ?? defaultCacheDir();
+    const binary = join(cacheRoot, stem, 'bin', 'node');
+    if (existsSync(binary))
+        return binary;
+    const file = `${stem}.tar.gz`;
+    opts.log?.(`downloading Node ${v} (${platform}-${arch})`);
+    const [sums, archive] = await Promise.all([
+        fetchBytes(`${base}/v${v}/SHASUMS256.txt`),
+        fetchBytes(`${base}/v${v}/${file}`),
+    ]);
+    const expected = sums.toString('utf8').split('\n').map((l) => l.trim().split(/\s+/))
+        .find((cols) => cols[1] === file)?.[0];
+    if (expected === undefined)
+        throw new Error(`${file} is not listed in the published SHASUMS256.txt for v${v}`);
+    const actual = createHash('sha256').update(archive).digest('hex');
+    if (actual !== expected)
+        throw new ChecksumMismatchError(file, expected, actual);
+    // Extract into a private temporary directory, then move into place, so a crash can never
+    // leave a half-extracted build in the cache that a later run would trust.
+    mkdirSync(cacheRoot, { recursive: true });
+    const work = mkdtempSync(join(tmpdir(), 'asinstalled-node-'));
+    try {
+        const tarball = join(work, file);
+        writeFileSync(tarball, archive);
+        execFileSync('tar', ['-xzf', tarball, '-C', work], { stdio: 'ignore' });
+        if (!existsSync(join(work, stem, 'bin', 'node')))
+            throw new Error(`${file} did not contain ${stem}/bin/node`);
+        if (!existsSync(join(cacheRoot, stem)))
+            renameSync(join(work, stem), join(cacheRoot, stem));
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+    opts.log?.(`verified and cached Node ${v}`);
+    return binary;
+}

package/dist/published.js

@@ -0,0 +1,93 @@
+// `asinstalled published`: IS WHAT THE REGISTRY SERVES WHAT WAS BUILT?
+//
+// After a release, three questions are usually answered by trust:
+//   exists       is this exact version actually live on the registry?
+//   identical    are its bytes the bytes a fresh local build produces from this source?
+//   provenance   does it carry a provenance attestation, and which repository does it name?
+// plus one about the source itself:
+//   tag          does the repository have the tag this version claims to come from?
+//
+// "identical" compares CONTENT, not the registry's integrity hash. That hash covers the
+// gzip-compressed file, and the same tar stream compresses to different bytes under
+// different zlib builds (for example Node 24 in CI and Node 26 on a laptop). Comparing it
+// would report a difference in the compressor as a difference in the package. So: download
+// the registry tarball, prove it matches the registry's own integrity (the download is
+// authentic), decompress both sides, and compare the tar streams. A remaining difference is
+// a real one: different source, or a build that is not reproducible.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { packProject } from "./check.js";
+export async function runPublished(opts) {
+    const { manifest } = opts;
+    const registry = (opts.registry ?? 'https://registry.npmjs.org').replace(/\/$/, '');
+    const url = `${registry}/${manifest.name.replace('/', '%2f')}/${manifest.version}`;
+    const findings = [];
+    const res = await fetch(url);
+    if (!res.ok) {
+        findings.push({ check: 'exists', ok: false, detail: `${manifest.name}@${manifest.version} is not on ${registry} (HTTP ${res.status})` });
+        return findings;
+    }
+    const doc = (await res.json());
+    findings.push({ check: 'exists', ok: true, detail: `${manifest.name}@${manifest.version} is live on ${registry}` });
+    if (opts.compareLocal !== false) {
+        const work = mkdtempSync(join(tmpdir(), 'asinstalled-pub-'));
+        try {
+            const packed = packProject(opts.projectDir, work);
+            const localGz = readFileSync(join(work, packed.filename));
+            const tarballUrl = doc.dist?.tarball;
+            if (tarballUrl === undefined)
+                throw new Error('the registry document has no dist.tarball');
+            const remoteGz = Buffer.from(await (await fetch(tarballUrl)).arrayBuffer());
+            const claimed = doc.dist?.integrity ?? '';
+            const actual = `sha512-${createHash('sha512').update(remoteGz).digest('base64')}`;
+            if (actual !== claimed) {
+                findings.push({ check: 'identical', ok: false, detail: `the downloaded tarball does not match the registry's own integrity ${claimed.slice(0, 24)}...; refusing to compare` });
+            }
+            else {
+                const sha = (b) => createHash('sha256').update(b).digest('hex');
+                const same = sha(gunzipSync(localGz)) === sha(gunzipSync(remoteGz));
+                const sameCompressed = localGz.equals(remoteGz);
+                findings.push({
+                    check: 'identical', ok: same,
+                    detail: !same
+                        ? 'the registry tarball CONTENT differs from a fresh local build (different source, or a build that is not reproducible)'
+                        : sameCompressed
+                            ? 'the registry tarball is byte-identical to a fresh local build'
+                            : 'content identical to a fresh local build; only the gzip layer differs (a different zlib build), which does not change what users install',
+                });
+            }
+        }
+        finally {
+            rmSync(work, { recursive: true, force: true });
+        }
+    }
+    const attUrl = doc.dist?.attestations?.url;
+    if (attUrl === undefined) {
+        findings.push({ check: 'provenance', ok: false, detail: 'no provenance attestation is attached to this version' });
+    }
+    else {
+        const bundle = (await (await fetch(attUrl)).json());
+        const slsa = bundle.attestations?.find((a) => a.predicateType?.includes('slsa.dev/provenance'));
+        let repo = 'unknown repository';
+        try {
+            const payload = JSON.parse(Buffer.from(slsa?.bundle?.dsseEnvelope?.payload ?? '', 'base64').toString('utf8'));
+            const wf = payload.predicate?.buildDefinition?.externalParameters?.workflow;
+            if (wf?.repository)
+                repo = `${wf.repository} (${wf.path ?? '?'} @ ${wf.ref ?? '?'})`;
+        }
+        catch { /* reported as unknown below */ }
+        findings.push({ check: 'provenance', ok: slsa !== undefined,
+            detail: slsa !== undefined ? `SLSA provenance attached, built from ${repo}` : 'an attestation exists but none is SLSA provenance' });
+    }
+    const tag = `v${manifest.version}`;
+    const git = spawnSync('git', ['tag', '-l', tag], { cwd: opts.projectDir, encoding: 'utf8' });
+    if (git.status !== 0)
+        findings.push({ check: 'tag', ok: false, detail: 'not a git repository, so the source tag cannot be checked' });
+    else
+        findings.push({ check: 'tag', ok: git.stdout.trim() === tag, detail: git.stdout.trim() === tag ? `git tag ${tag} exists` : `no git tag ${tag} in this repository` });
+    return findings;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "asinstalled",
+  "version": "0.1.0",
+  "description": "Test your npm package the way users receive it: pack it, install the tarball into a clean project, and run it on every Node version your engines field promises. Also checks your docs against package.json, and the published artifact against the build.",
+  "license": "Apache-2.0",
+  "author": "Theebbanraj Asokan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Theebban/asinstalled.git"
+  },
+  "homepage": "https://github.com/Theebban/asinstalled#readme",
+  "bugs": {
+    "url": "https://github.com/Theebban/asinstalled/issues"
+  },
+  "type": "module",
+  "bin": {
+    "asinstalled": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "npm-pack",
+    "package-testing",
+    "npm-publish",
+    "prepublish",
+    "smoke-test",
+    "tarball",
+    "engines",
+    "node-version",
+    "packaging",
+    "provenance",
+    "release",
+    "ci"
+  ],
+  "scripts": {
+    "asinstalled": "node --experimental-strip-types src/cli.ts",
+    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "check": "npm run typecheck && npm run lint && npm test",
+    "prepack": "npm run build",
+    "self-check": "node --experimental-strip-types src/cli.ts check --dir . --run \"asinstalled --help\" --script scripts/self-smoke.mjs && node --experimental-strip-types src/cli.ts docs --dir ."
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^22.20.4",
+    "eslint": "^9.39.5",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.70.1"
+  }
+}