rugby/README.md

A Node.js CLI to collect npm package tarballs and assets (including those fetched by pre/postinstall scripts) for offline Artifactory use.

## rugby

Collect npm package tarballs and install-script assets for offline installs and air‑gapped environments (e.g., publish to JFrog Artifactory or use a local cache/server).

### Requirements
- Node.js >= 20
- npm

### Install (from npm)
```bash
npm install -g rugby
```

### Install (from source)
```bash
git clone <repo>
cd arti-bundle
npm i
npm link   # or run via ./bin/rugby.js
```

### CLI
```bash
rugby --dir <projectDir> --out <outputDir> [--list-only] [--verbose] [--npm <path>] [--npm-args "..."]
```

Options:
- `--dir`: Project directory with `package.json` and `package-lock.json` (default: current dir)
- `--out`: Output folder (default: `./out`). Prompted to create if missing
- `--list-only`: Do not download; show dependency tree and install-script assets/packages
- `--npm`: Path to npm (auto-resolved)
- `--npm-args`: Extra args for npm when simulating scripts (e.g., `--registry`)
- `--verbose`: Verbose output

### What rugby does
1) Reads `package-lock.json` (v2 preferred) and enumerates all resolved packages (preserving multiple versions).
2) Installs with `--ignore-scripts` and then runs only lifecycle scripts via `npm rebuild` in a sandbox, while:
   - Capturing Node `http/https` requests (NODE_OPTIONS hook)
   - Shimming `curl`/`wget` to log/capture payloads
   - Diffing `node_modules` before/after to flag packages installed by scripts
3) Downloads all package tarballs to `out/packages/` and copies captured assets to `out/assets/`.
4) Writes `out/NEXT_STEPS.txt` with offline install instructions (local cache or Artifactory) for macOS/Linux and Windows.

### Fast start
List only:
```bash
rugby --dir /path/to/your/project --list-only
```

Full export:
```bash
rugby --dir /path/to/your/project --out /path/to/out --verbose
```

### Offline install options

After a successful export, see `out/NEXT_STEPS.txt`. Summary below.

Option A: local npm cache (no registry)
- macOS/Linux
```bash
export CACHE=/abs/path/to/cache
export PKGS=/abs/path/to/out/packages
mkdir -p "$CACHE"
for f in "$PKGS"/*.tgz; do npm cache add --cache "$CACHE" "$f"; done
cd /abs/path/to/project
rm -rf node_modules
npm ci --cache "$CACHE" --prefer-offline --offline
```

- Windows PowerShell
```powershell
$env:CACHE = "C:\path\to\cache"
$env:PKGS  = "C:\path\to\out\packages"
New-Item -ItemType Directory -Force -Path $env:CACHE | Out-Null
Get-ChildItem -Path $env:PKGS -Filter *.tgz | ForEach-Object { npm cache add --cache $env:CACHE $_.FullName }
cd C:\path\to\project
rmdir /s /q node_modules 2>$null
npm ci --cache "$env:CACHE" --prefer-offline --offline
```

Option B: Artifactory (npm repo for tarballs, generic repo or local hosting for assets)
- Publish tarballs to Artifactory npm repo
```bash
export REG=https://artifactory.example.com/artifactory/api/npm/your-npm-repo/
npm set registry "$REG"
for f in "/abs/path/to/out/packages"/*.tgz; do npm publish "$f" --registry "$REG" || true; done
```

- Upload assets to Generic repo
```bash
export GEN=https://artifactory.example.com/artifactory/generic-assets/
for f in "/abs/path/to/out/assets"/*; do curl -u <user:api_key> -T "$f" "$GEN$(basename "$f")"; done
```

- Alternative: host assets locally (no Artifactory)
```bash
ASSETS=/abs/path/to/out/assets
(cd "$ASSETS" && python3 -m http.server 9000) & SERVE_PID=$!
export npm_config_bcrypt_binary_host_mirror=http://127.0.0.1:9000/
export SHARP_DIST_BASE_URL=http://127.0.0.1:9000/
export SASS_BINARY_SITE=http://127.0.0.1:9000/
# run npm ci in your project, then:
kill $SERVE_PID
```

- Configure project to use Artifactory npm + assets
```bash
npm config set registry https://artifactory.example.com/artifactory/api/npm/your-npm-repo/
export npm_config_bcrypt_binary_host_mirror=https://artifactory.example.com/artifactory/generic-assets/
export SHARP_DIST_BASE_URL=https://artifactory.example.com/artifactory/generic-assets/
export SASS_BINARY_SITE=https://artifactory.example.com/artifactory/generic-assets/
```

### Notes & limitations
- Capturing non-HTTP(S) custom downloaders beyond curl/wget may require extending shims.
- Script-installed packages are detected and their network downloads are captured, but their tarballs are not yet auto-added to `out/packages/` if not present in the lockfile (planned enhancement).
- Works best with npm lockfile v2+.

### License
MIT