npm package: @sneezry/appcat
Description: appcat CLI wrapper that downloads the correct platform binary (windows/linux/macos × amd64/arm64)
Latest version: 1.2.2

# appcat npm wrapper

Global installer wrapper for the native appcat CLI (azure-migrate-appcat-for-java-cli). It downloads the correct prebuilt binary for your OS/arch (windows|linux|macos × amd64|arm64) during npm install, verifies its checksum, and exposes the `appcat` command via npm's bin mechanism.

## Install

```bash
npm install -g @sneezry/appcat
appcat --help
```

## Version Scheme

This npm wrapper uses independent semantic versioning. The wrapper downloads appcat CLI version specified in `package.json` field `appcatVersion`.

| npm Package Version | Wrapper Changes | appcat CLI Version |
|--------------------|----------------|-------------------|
| `1.1.1` | Bug fix for version mismatch | `7.7.0.3`        |
| `1.2.0` | Configuration improvement | `7.7.0.3`        |
| `1.2.1` | Critical fix for vendor path | `7.7.0.3`        |
| `1.3.0` | New appcat version (future) | `7.8.x.x`        |
| `2.0.0` | Breaking change (future) | `8.x.x.x`        |

> The wrapper version is independent of appcat CLI version. The actual appcat CLI version is configured in `package.json` under the `appcatVersion` field.

No manual PATH changes required.

## How it works

1. `postinstall` runs `install.js`.
2. It detects Node's `process.platform` & `process.arch`.
3. Maps to artifact naming: `azure-migrate-appcat-for-java-cli-<os>-<arch>-<version>.(zip|tar.gz)`.
4. Downloads from: `https://aka.ms/appcat/<artifact>` (unless overridden by env vars below).
5. Downloads corresponding checksum file `<artifact>.sha256sum.txt` and validates sha256.
6. Extracts to `vendor/<version>/<os>-<arch>/` and exposes launcher `bin/run.js` as `appcat`.

macOS special case: internal folder name uses `macOS` (capital O S) while URLs/archives use lowercase `macos`.

## Environment overrides

Set before running `npm install -g appcat@...`:

* `APPCAT_BINARY_URL` – Full URL to a specific archive (bypasses pattern).
* `APPCAT_BINARY_FILE` – Local path to a pre-downloaded archive file (skips network download).
* `APPCAT_BASE_URL` – Override base host (default `https://aka.ms/appcat`).
* `APPCAT_SKIP_CHECKSUM=1` – Skip checksum verification (NOT recommended).
* `APPCAT_DEBUG=1` – Verbose debug logging.
* `APPCAT_DRY_RUN=1` – Perform download + checksum only; skip extraction (useful to validate URLs & checksum files before publishing).
* `APPCAT_DEV_INSTALL=1` – Force download during a local development `npm install` in the repo root (otherwise skipped there for speed).
* `APPCAT_PROGRESS=1` – Show download progress. If the server omits Content-Length, a fallback shows bytes in MB every second / per MB chunk.

### Dry run example (Windows PowerShell)

```powershell
$env:APPCAT_DRY_RUN=1; npm install -g .
# Clear the variable afterward (optional)
Remove-Item Env:APPCAT_DRY_RUN
```

On success you will see a `DRY RUN` message and no `vendor/<version>/...` directory is created.

## Directory layout after install

```
vendor/7.7.0.3/windows-amd64/appcat.exe
vendor/7.7.0.3/linux-amd64/appcat
... (only your current platform/arch actually present)
```

## Reinstall / repair

```
npm rebuild -g appcat
```

## Uninstall

```
npm uninstall -g appcat
```

## Publishing

1. Update `version` in `package.json` for the npm wrapper release.
2. Update `appcatVersion` in `package.json` if upgrading the appcat CLI version.
3. Publish: `npm publish --access public` (if new package) / `npm publish`.
4. Users upgrade with `npm i -g @sneezry/appcat@<version>`.

## One-click self-check (maintainers)

Run locally:

```
npm run verify
```

Steps performed:
1. Dry run (download + checksum only).
2. Real install (extraction).
3. Assert binary exists and optionally execute it with arguments.

Environment variables:
* `APPCAT_VERIFY_ARGS` – Custom args passed to the binary (default `--help`).
* `APPCAT_SKIP_CHECKSUM=1` – Skip checksum verification (not recommended except in restricted networks).
* `APPCAT_DEV_INSTALL=1` – Force install script to download even in repo root.

## Notes

* Supports Node >=16.
* The native binary is NOT bundled in the npm tarball; download happens at user install time (supports multi-hop 301/302 redirects for short URLs).
* Only downloads the single matching artifact for the installing machine.
* No modifications to system PATH – relies on npm global bin directory.
* `vendor/` is generated on demand; it's excluded from the published package.
* Local development (`npm install` in repo root) skips the download by default; use `APPCAT_DEV_INSTALL=1` to override.