docs: make the documented install path executable

README.md

@@ -6,36 +6,42 @@ DiffBudget reads a git diff, scores the patch against plain local budgets, and w
 
 ## Install
 
+DiffBudget is not currently published to the npm registry. Install the current
+source directly from GitHub:
+
 ```sh
-npm install -D diffbudget
-npx diffbudget --version
+npm install -D github:rogerchappel/diffbudget#main
+npx --no-install diffbudget --version
 ```
 
-From a checkout of this repository:
+The `prepare` script builds the CLI during installation. Pin a commit SHA
+instead of `main` when you need a reproducible dependency.
+
+For local development from a checkout of this repository:
 
 ```sh
-npm install
+npm ci
 npm run build
 node dist/cli.js --help
 ```
 
 ## Quickstart
 
 ```sh
-# create diffbudget.config.json
-npx diffbudget init
+# create diffbudget.config.json (after installing as above)
+npx --no-install diffbudget init
 
 # score uncommitted changes against HEAD
-npx diffbudget scan --base HEAD --output .diffbudget/latest
+npx --no-install diffbudget scan --base HEAD --output .diffbudget/latest
 
 # short alias for the same CLI
-npx dbudget scan --base HEAD --output .diffbudget/latest
+npx --no-install dbudget scan --base HEAD --output .diffbudget/latest
 
 # fail with exit code 2 when the patch exceeds budget
-npx diffbudget scan --base HEAD --strict
+npx --no-install diffbudget scan --base HEAD --strict
 
 # render an existing JSON report
-npx diffbudget report --input .diffbudget/latest/diffbudget-report.json
+npx --no-install diffbudget report --input .diffbudget/latest/diffbudget-report.json
 ```
 
 ## Practical examples
@@ -126,6 +132,7 @@ npm test
 npm run check
 npm run build
 npm run smoke
+npm run install:smoke
 npm run package:smoke
 npm run release:check
 bash scripts/validate.sh
@@ -144,6 +151,7 @@ npm run build
 npm run check
 npm test
 npm run smoke
+npm run install:smoke
 npm run package:smoke
 npm run release:check
 ```

package.json

@@ -22,11 +22,13 @@
   ],
   "scripts": {
     "build": "tsc",
+    "prepare": "npm run build",
     "check": "tsc --noEmit",
     "test": "npm run build && node --test dist/*.test.js",
     "smoke": "bash scripts/smoke.sh",
+    "install:smoke": "bash scripts/install-smoke.sh",
     "package:smoke": "npm run build && node scripts/package-smoke.mjs",
-    "release:check": "npm run check && npm test && npm run smoke && npm run package:smoke",
+    "release:check": "npm run check && npm test && npm run smoke && npm run install:smoke && npm run package:smoke",
     "lint": "npm run check"
   },
   "keywords": [

scripts/install-smoke.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+install_root="$(mktemp -d "${TMPDIR:-/tmp}/diffbudget-install-smoke.XXXXXX")"
+
+cleanup() {
+  rm -rf "$install_root"
+}
+trap cleanup EXIT
+
+git -C "$repo_root" archive HEAD | tar -x -C "$install_root"
+git -C "$install_root" init --quiet
+git -C "$install_root" add .
+git -C "$install_root" \
+  -c user.name="DiffBudget install smoke" \
+  -c user.email="install-smoke@example.invalid" \
+  commit --quiet -m "install fixture"
+
+consumer_root="$install_root/consumer"
+mkdir "$consumer_root"
+cd "$consumer_root"
+npm init --yes >/dev/null
+npm install --save-dev "git+file://$install_root" >/dev/null
+
+installed_version="$(npx --no-install diffbudget --version)"
+expected_version="$(node -p "require('./node_modules/diffbudget/package.json').version")"
+
+test "$installed_version" = "$expected_version"
+test "$(npx --no-install dbudget --version)" = "$expected_version"
+
+printf 'source install smoke ok (%s)\n' "$installed_version"