docs: verify source tarball installation

README.md

@@ -32,10 +32,21 @@ What it does **not** promise yet:
 
 ## Install
 
+`@bargekit/core` is **not published to npm yet**. Install it from a source
+checkout and a locally built tarball:
+
 ```sh
-npm install @bargekit/core
+git clone https://github.com/rogerchappel/bargekit.git bargekit
+npm --prefix bargekit ci
+npm pack ./bargekit
+npm install ./bargekit-core-0.1.0.tgz
 ```
 
+The final command installs the same package contents that a future registry
+release will contain. Run it from the consumer project where you want to use
+BargeKit. Contributors working directly in the checkout can run commands with
+`npm --prefix bargekit run <script>` after `npm ci`.
+
 ## Quick start
 
 ```js

package.json

@@ -34,8 +34,9 @@
     "test": "node --test",
     "typecheck": "tsc --project tsconfig.json",
     "build": "node scripts/build.mjs",
+    "package:install-docs": "node scripts/verify-install-docs.mjs",
     "package:imports": "node scripts/verify-documented-imports.mjs",
-    "package:smoke": "node scripts/verify-package.mjs && npm run package:imports && npm pack --dry-run",
+    "package:smoke": "node scripts/verify-package.mjs && npm run package:install-docs && npm run package:imports && npm pack --dry-run",
     "release:check": "npm run check && npm test && npm run typecheck && npm run build && npm run smoke && npm run package:smoke",
     "smoke": "node test/fixtures.test.js",
     "lint": "npm run check"

scripts/verify-install-docs.mjs

@@ -0,0 +1,58 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const projectRoot = new URL('..', import.meta.url);
+const readme = readFileSync(new URL('../README.md', import.meta.url), 'utf8');
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const escapedName = pkg.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const registryInstall = new RegExp(`npm\\s+(?:i|install)\\s+${escapedName}(?:[@\\s]|$)`);
+const expectedTarball = `${pkg.name.replace(/^@/, '').replace('/', '-')}-${pkg.version}.tgz`;
+
+if (!readme.includes(`${pkg.name}\` is **not published to npm yet**`)) {
+  throw new Error(`README.md must prominently state that ${pkg.name} is not published`);
+}
+if (registryInstall.test(readme)) {
+  throw new Error(`README.md presents unavailable registry package ${pkg.name} as installable`);
+}
+for (const command of [
+  'npm --prefix bargekit ci',
+  'npm pack ./bargekit',
+  `npm install ./${expectedTarball}`
+]) {
+  if (!readme.includes(command)) {
+    throw new Error(`README.md is missing verified install command: ${command}`);
+  }
+}
+
+const consumerDir = mkdtempSync(join(tmpdir(), 'bargekit-install-docs-'));
+
+try {
+  const packResult = JSON.parse(execFileSync(
+    'npm',
+    ['pack', '--json', '--pack-destination', consumerDir],
+    { cwd: projectRoot, encoding: 'utf8' }
+  ));
+  const tarballPath = join(consumerDir, packResult[0].filename);
+
+  if (packResult[0].filename !== expectedTarball) {
+    throw new Error(`README tarball ${expectedTarball} does not match ${packResult[0].filename}`);
+  }
+
+  writeFileSync(join(consumerDir, 'package.json'), JSON.stringify({ private: true, type: 'module' }));
+  execFileSync(
+    'npm',
+    ['install', '--ignore-scripts', '--no-audit', '--no-fund', tarballPath],
+    { cwd: consumerDir, stdio: 'inherit' }
+  );
+  execFileSync(
+    'node',
+    ['--input-type=module', '--eval', `await import(${JSON.stringify(pkg.name)})`],
+    { cwd: consumerDir, stdio: 'inherit' }
+  );
+
+  console.log(`verified README installation from ${packResult[0].filename}`);
+} finally {
+  rmSync(consumerDir, { recursive: true, force: true });
+}