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

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)

$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.