@airwallex/airi-cli 0.0.0-stage → 0.1.0-beta.1

package/README.md

@@ -1,3 +1,288 @@
-# Temporary Holding Version
+# airi-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![Version](https://img.shields.io/badge/version-0.1.0--beta.1-orange)
+
+Command-line tool for the Airi wallet. Authenticate with OAuth, inspect your
+session, and drive an **agentic checkout** — list payment methods, create a
+payment mandate, fetch the single-use checkout credential, and report the
+result — from your terminal or an AI agent.
+
+Results are printed to stdout as JSON, so they are easy to consume from scripts
+and agents.
+
+## Installation
+
+airi-cli is available for macOS and Linux as a single self-contained binary.
+Install it with npm:
+
+```bash
+npm install -g @airwallex/airi-cli@beta
+```
+
+This installs the `@airwallex/airi-cli` package, which downloads the prebuilt
+binary for your platform, verifies its SHA256 checksum, and puts `airi-cli` on
+your `PATH`.
+
+> **Agent skills:** deploy the bundled agent skills with `airi-cli skills install`
+> after installing (see [Skills](#skills)).
+
+Environment variables (install time):
+
+| Variable | Description |
+|----------|-------------|
+| `AIRI_CLI_VERSION` | Download a specific release tag (e.g. `v0.1.0`) instead of the version bundled with the package. |
+| `AIRI_CLI_SKIP_DOWNLOAD` | Set to `1` to skip the binary download during install. |
+| `AIRI_CLI_SKIP_CHECKSUM` | **Local development only.** Set to `1` to bypass SHA256 verification. Never use this in production or CI. |
+| `AIRI_CLI_BASE_URL` | Override the release host the binary is downloaded from (for internal mirrors). |
+
+### Checking for updates
+
+`airi-cli version` prints the installed version; `airi-cli version --check` also
+asks GitHub for the latest published release and reports whether an update is
+available:
+
+```bash
+airi-cli version            # e.g. 0.1.0
+airi-cli version --check     # reports whether a newer release exists
+```
+
+In JSON mode (the default for non-interactive callers) `--check` returns:
+
+```json
+{"current":"0.1.0","latest":"0.2.0","update_available":true,
+ "install_command":"npm install -g @airwallex/airi-cli"}
+```
+
+To update, run the `install_command` from that response to replace the binary
+with the latest release. The check is best-effort and never
+fails the command: if GitHub can't be reached it reports
+`update_available: false` with a `check_error` field, so it is safe to run as a
+pre-flight step.
+
+## Quick start
+
+Sign in:
+
+```bash
+airi-cli auth login
+```
+
+`login` shows a verification URL and a code:
+
+```
+╭─ Sign in to Airi ─────────────────────────────────╮
+│ Open this URL and enter the code to sign in:      │
+│                                                   │
+│   https://app.airi.com/device                     │
+│   Code: WXYZ-1234                                 │
+│                                                   │
+│ Expires in 10 min. Press Enter to open it in your │
+│ browser.                                          │
+│ Waiting for authorization…                        │
+╰───────────────────────────────────────────────────╯
+```
+
+Open the URL in a browser (or press Enter to open it for you), enter the code,
+and approve. The command confirms once you're signed in:
+
+```
+╭─ airi-cli ──────────────────────────────────────────────╮
+│ ✓  Signed in                                             │
+│    Session expires: 2026-08-12 18:00 +08 (in 29 days)    │
+╰──────────────────────────────────────────────────────────╯
+```
+
+Check your status at any time:
+
+```bash
+airi-cli auth whoami
+```
+
+`whoami` reports the current sign-in status and refreshes the session token
+when it is close to expiring, so the reported expiry reflects the renewed
+session. In JSON output (`-o json`, the default for scripts and agents) the
+expiry is the `session_expires` field as an RFC3339 timestamp.
+
+Every command refreshes the access token automatically — proactively before
+each call when it is close to expiring, and reactively if the server rejects
+it — so you never have to refresh it manually. If a command still reports an
+expired or unauthenticated session, the token could not be refreshed: sign in
+again with `airi-cli auth login` and retry.
+
+List the payment methods available for agentic checkout (a quick way to confirm
+your access token works):
+
+```bash
+airi-cli payment-methods list
+```
+
+## Agentic checkout
+
+The `mandate` commands drive a checkout on the user's behalf. The typical flow,
+after `auth login`, is:
+
+1. **Pick a payment method** — `airi-cli payment-methods list` returns the cards
+   available for agentic checkout; keep the `paymentMethodId` you want to use.
+2. **Create a mandate** — `airi-cli mandate create` records the merchant, order
+   total, currency, and line items. The response includes a `mandate_id` and a
+   passkey/verification URL for the user to approve the payment.
+
+   ```bash
+   airi-cli mandate create \
+     --source "<agent-name>" \
+     --payment-method-id "<payment-method-id>" \
+     --merchant-name "Acme" --merchant-url "https://acme.example" \
+     --merchant-country "US" \
+     --total-amount "42.00" --currency "USD" \
+     --item "name:Widget,unit_price:21.00,quantity:2" \
+     --description "Order #1234"
+   ```
+
+3. **Fetch the credential** — after the user approves in their browser,
+   `airi-cli mandate get-credential --mandate-id <id>` polls until the mandate is
+   authorized and returns a single-use credential (tokenized PAN, expiry, CVV).
+   Prefer `--file <path>`: the full credential is written to a `0600` file and
+   stdout shows only a receipt (`status`, `tokenType`, and `tokenExpiration`),
+   so the secret stays out of your terminal, logs, and an agent's transcript.
+
+   ```bash
+   airi-cli mandate get-credential --mandate-id "<mandate-id>" --file /tmp/airi-cred.json
+   ```
+
+4. **Report the result** — after submitting the checkout, always report the
+   outcome with `airi-cli mandate result --mandate-id <id> --result <SUCCEEDED|CANCELLED|DECLINED>`.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `airi-cli auth login` | Sign in via the OAuth device flow. |
+| `airi-cli auth poll` | Wait for a non-blocking login to be approved. |
+| `airi-cli auth whoami` | Print the current sign-in status. |
+| `airi-cli auth logout` | Sign out by removing the stored session (local only). |
+| `airi-cli payment-methods list` | List payment methods available for agentic checkout. |
+| `airi-cli mandate create` | Create a payment mandate for a checkout. |
+| `airi-cli mandate get-credential` | Poll for and fetch the single-use checkout credential. |
+| `airi-cli mandate result` | Report the transaction outcome for a mandate. |
+| `airi-cli skills install` | Deploy the bundled agent skills into local AI-agent skill directories. |
+| `airi-cli skills list` | List the agent skills bundled in the binary. |
+| `airi-cli version` | Print the CLI version (add `--check` to check for a newer release). |
+
+Flags for `airi-cli version`:
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--check` | `false` | Check GitHub for the latest release and report whether an update is available. |
+
+Flags for `airi-cli auth login`:
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--client-name` | `CLI` | Name to register this client under. |
+
+Flags for `airi-cli auth whoami`:
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--verbose` | `false` | Include device details (name, platform, device id). |
+
+Flags for `airi-cli mandate create` (all required):
+
+| Flag | Description |
+| --- | --- |
+| `--source` | Agent source identifier (use the calling agent's name). |
+| `--payment-method-id` | Payment method ID from `payment-methods list`. |
+| `--merchant-name` | Merchant name. |
+| `--merchant-url` | Merchant URL. |
+| `--merchant-country` | Merchant country code. |
+| `--total-amount` | Total order amount. |
+| `--currency` | Order currency code. |
+| `--item` | Line item as `name:<product>,unit_price:<price>,quantity:<n>` (repeat `--item` per item). |
+| `--description` | Mandate description. |
+
+Flags for `airi-cli mandate get-credential`:
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--mandate-id` | — | Mandate ID (required). |
+| `--interval` | `2` | Poll interval while waiting for authorization (seconds). |
+| `--timeout` | `300` | Stop polling after this many seconds. |
+| `--file` | — | Write the credential to this file (`0600`) instead of printing it; stdout shows only a receipt with `status`, `tokenType`, and the token `tokenExpiration` (no sensitive values). |
+| `--force` | `false` | Overwrite the `--file` target if it already exists. |
+
+Flags for `airi-cli mandate result`:
+
+| Flag | Description |
+| --- | --- |
+| `--mandate-id` | Mandate ID (required). |
+| `--result` | Transaction result: `SUCCEEDED`, `CANCELLED`, or `DECLINED` (required). |
+| `--reason` | Optional reason, e.g. when the result is `DECLINED`. |
+
+Global flags:
+
+| Flag | Description |
+| --- | --- |
+| `-o`, `--output` | Output format: `auto` (default), `text`, or `json`. |
+| `--pretty` | Pretty-print JSON output (JSON mode only). |
+| `--no-telemetry` | Disable anonymous usage telemetry for the invocation. |
+| `-V`, `--version` | Print the CLI version. |
+
+### Output
+
+`--output auto` (the default) renders human-friendly boxed **text** on an
+interactive terminal and machine-readable **JSON** when the output is piped or
+redirected — so scripts and agents get JSON automatically without any flag.
+Force a mode with `-o text` or `-o json`. In JSON mode, `--pretty` indents the
+output. `auth whoami` and `auth login` omit device diagnostics
+(`name`/`platform`/`device_id`) by default; `auth whoami --verbose` includes
+them.
+
+Times are reported in your **local timezone** (from the environment's `TZ` /
+host setting). In text mode the expiry carries the local offset (e.g.
+`2026-08-12 18:00 +08`); in JSON mode timestamps such as `session_expires` and
+the credential's `tokenExpiration` are RFC3339 values with the local offset.
+
+## Telemetry
+
+The CLI sends anonymous usage events — command name, exit code, duration,
+platform, and runtime/agent context — to help improve the tool. Events contain
+no tokens, no account information, and no command arguments, and are keyed by a
+random per-install identifier.
+
+Disable telemetry with any of:
+
+- the `--no-telemetry` flag,
+- `AIRI_TELEMETRY_DISABLED=1` (or `DISABLE_TELEMETRY=1`),
+- an empty `telemetryUrl` in your config.
+
+## Skills
+
+airi-cli bundles agent skill definitions that describe how an AI agent uses the
+tool. They are embedded into the binary, so every install carries the skills for
+its version. The install script deploys them for you; you can also (re)deploy
+them at any time:
+
+```bash
+airi-cli skills install                     # canonical dir + detected agents
+airi-cli skills install --all               # every known agent, detected or not
+airi-cli skills install --dir ./my-skills   # explicit destination(s)
+airi-cli skills list                        # show which skills the binary carries
+```
+
+`skills install` **auto-detects** installed agents. It always writes the
+canonical `~/.agents/skills` (the open Agent Skills standard location), and
+additionally writes each known agent whose config directory already exists:
+
+| Agent | Detected via | Skills dir |
+| --- | --- | --- |
+| Claude Code | `~/.claude/` | `~/.claude/skills` |
+| opencode | `~/.config/opencode/` | `~/.config/opencode/skills` |
+| Codex | `~/.codex/` | `~/.codex/skills` |
+| Cursor | `~/.cursor/` | `~/.cursor/skills` |
+| Windsurf | `~/.codeium/windsurf/` | `~/.codeium/windsurf/skills` |
+| GitHub Copilot | `~/.copilot/` | `~/.copilot/skills` |
+| Gemini CLI | `~/.gemini/` | `~/.gemini/skills` |
+
+Use `--all` to write every known agent dir regardless of detection, or `--dir`
+to pick your own. Skills are copied (not symlinked), so re-running
+`skills install` after an upgrade re-syncs every target.

package/bin/_shared.mjs

@@ -0,0 +1,65 @@
+// Shared constants and helpers for the @airwallex/airi-cli launcher and its
+// postinstall downloader. Keeping the platform matrix and binary paths in one
+// place means the downloader and the launcher can never disagree about where
+// the binary lives or what asset to fetch.
+
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// GitHub mirror that hosts the release assets. Matches release-github.sh and
+// install.sh.
+export const REPO = 'airwallex/airi-cli'
+
+// Base binary name inside each release archive (airi-cli_<os>_<arch>.tar.gz).
+export const BIN_NAME = 'airi-cli'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+
+// The downloaded binary lives in <package>/vendor/airi-cli, separate from the
+// bin/ launcher so `npm pack`'s `files` list (which ships bin/airi-cli.js) is
+// never confused with the runtime-downloaded artifact.
+export function binDir() {
+  return path.join(here, '..', 'vendor')
+}
+export function binPath() {
+  return path.join(binDir(), BIN_NAME)
+}
+
+// Map Node's process.platform/process.arch to the "<os>_<arch>" fragment used
+// in release asset filenames (and the extracted binary). macOS uses
+// macos/arm64|x86_64; Linux uses linux/amd64|arm64 — matching the
+// build-binaries CI job and install.sh's detect_platform.
+export function detectPlatform(
+  platform = process.platform,
+  arch = process.arch
+) {
+  let os
+  switch (platform) {
+    case 'linux':
+      os = 'linux'
+      break
+    case 'darwin':
+      os = 'macos'
+      break
+    default:
+      throw new Error(
+        `unsupported OS: ${platform} (airi-cli supports linux and darwin)`
+      )
+  }
+
+  let cpu
+  switch (arch) {
+    case 'x64':
+      cpu = os === 'macos' ? 'x86_64' : 'amd64'
+      break
+    case 'arm64':
+      cpu = 'arm64'
+      break
+    default:
+      throw new Error(
+        `unsupported architecture: ${arch} (airi-cli supports x64 and arm64)`
+      )
+  }
+
+  return `${os}_${cpu}`
+}

package/bin/airi-cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+'use strict'
+
+// Launcher for @airwallex/airi-cli.
+//
+// The real CLI is a Go binary downloaded by this package's postinstall script
+// (scripts/postinstall.mjs) into <package>/vendor/airi-cli. This launcher spawns
+// that binary and forwards everything to it — argv, stdio, exit code, and
+// signals — so callers cannot tell the Go binary was reached via a Node shim.
+//
+// If the binary is missing (postinstall was skipped with --ignore-scripts, or
+// the download/verification failed), it prints remediation and exits non-zero.
+
+const { spawn } = require('child_process')
+const fs = require('fs')
+const path = require('path')
+
+const REPO = 'airwallex/airi-cli'
+const BIN_NAME = 'airi-cli'
+const BIN_PATH = path.join(__dirname, '..', 'vendor', BIN_NAME)
+
+function fail(message) {
+  process.stderr.write(`airi-cli: ${message}\n`)
+  process.exit(1)
+}
+
+function main() {
+  if (!fs.existsSync(BIN_PATH)) {
+    fail(
+      `binary not found at ${BIN_PATH}.\n` +
+        `  The postinstall step did not install it — this happens with ` +
+        `--ignore-scripts, or if the download or checksum verification failed.\n` +
+        `  Reinstall the package (npm rebuild --global @airwallex/airi-cli for a ` +
+        `global install, or npm rebuild @airwallex/airi-cli locally), or ` +
+        `download it manually from:\n` +
+        `    https://github.com/${REPO}/releases`
+    )
+  }
+
+  // Async spawn (not spawnSync) so this process keeps its event loop running
+  // and can forward signals to the child while it executes. stdio is inherited
+  // so the child owns the terminal directly.
+  const child = spawn(BIN_PATH, process.argv.slice(2), {
+    stdio: 'inherit',
+    windowsHide: true,
+  })
+
+  // Forward the signals a supervisor (shell, init, CI) is likely to send to the
+  // wrapper on to the child, so killing the wrapper kills the real CLI rather
+  // than orphaning it. SIGINT/SIGTERM/SIGHUP/SIGQUIT cover the common cases.
+  const forwarded = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']
+  const handlers = {}
+  for (const sig of forwarded) {
+    handlers[sig] = () => {
+      if (!child.killed) {
+        try {
+          child.kill(sig)
+        } catch (_err) {
+          // Child may have already exited between the signal and this handler.
+        }
+      }
+    }
+    // Registering a handler also stops the default action from killing the
+    // wrapper before the child has a chance to exit and report its status.
+    process.on(sig, handlers[sig])
+  }
+
+  child.on('error', (err) => {
+    if (err.code === 'ENOENT') {
+      fail(`binary not found at ${BIN_PATH}; reinstall airi-cli.`)
+    }
+    if (err.code === 'EACCES') {
+      fail(`cannot execute ${BIN_PATH}: permission denied.`)
+    }
+    fail(`failed to launch ${BIN_PATH}: ${err.message}`)
+  })
+
+  child.on('exit', (code, signal) => {
+    // Stop forwarding so the re-raise below isn't intercepted by our own handler.
+    for (const sig of forwarded) {
+      process.removeListener(sig, handlers[sig])
+    }
+    // Mirror the child's termination: if it was killed by a signal, re-raise
+    // that signal on ourselves so the parent sees the real cause; otherwise
+    // exit with the child's status.
+    if (signal) {
+      process.kill(process.pid, signal)
+      return
+    }
+    process.exit(code === null ? 1 : code)
+  })
+}
+
+main()

package/checksums.json

@@ -0,0 +1,8 @@
+{
+  "checksums": {
+    "linux_amd64": "b6f0ea7935b018ef1752ddbde54eee6033b754709972ddffd1be4182b527934f",
+    "linux_arm64": "595b6f2ee28b8a254ad38d0e3db20947d06c4d0be77afa123348b2ba4bd6b8d4",
+    "macos_x86_64": "de210b14b727cecaf8f9d2feeb228d8374b3881e4dc52f7572466c13750cc2d5",
+    "macos_arm64": "11cfeaf377cae47048891735f616b40740b11c92f882d47739bcc035332fe4f0"
+  }
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@airwallex/airi-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.1",
+  "description": "Command-line tool for the Airi wallet — OAuth sign-in and agentic checkout from your terminal or an AI agent.",
+  "bin": {
+    "airi-cli": "bin/airi-cli.js"
+  },
+  "files": [
+    "bin/airi-cli.js",
+    "bin/_shared.mjs",
+    "scripts/postinstall.mjs",
+    "checksums.json",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "engines": {
+    "node": ">=14.14"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.awx.im/acquiring/airi-cli.git"
+  },
+  "keywords": [
+    "airwallex",
+    "airi",
+    "cli",
+    "agentic-checkout"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+// postinstall for @airwallex/airi-cli.
+//
+// airi-cli is a Go binary. This npm package ships only a small JS launcher;
+// the actual binary is downloaded here from the GitHub release whose tag
+// matches this package's version, verified against the SHA256 digest pinned
+// into the package at publish time (checksums.json), and unpacked next to the
+// launcher.
+//
+// Mirrors the asset layout that scripts/release-github.sh uploads and
+// install.sh downloads:
+//   https://github.com/<REPO>/releases/download/v<version>/airi-cli_<os>_<arch>.tar.gz
+//
+// Verification is fail-closed: if the package has no pinned digest for the host
+// platform (e.g. a non-release build), or the download does not match it, the
+// binary is NOT installed. An unverified executable is never left on disk.
+//
+// Environment variables:
+//   AIRI_CLI_VERSION        download this release tag instead of the package's
+//                           own version (e.g. "v0.2.0" or "0.2.0"). The pinned
+//                           digest only matches the package's own version, so
+//                           an override requires AIRI_CLI_SKIP_CHECKSUM.
+//   AIRI_CLI_SKIP_DOWNLOAD  set to "1" to skip the download entirely. Useful
+//                           for offline CI that provides the binary another
+//                           way; the CLI won't run until it is present.
+//   AIRI_CLI_SKIP_CHECKSUM  set to "1" to skip SHA256 verification (local-dev
+//                           only — never in production or CI).
+//   AIRI_CLI_BASE_URL       override the release host (internal mirror/testing).
+//
+// The script is resilient by design: a download or verification failure prints
+// clear guidance but does NOT hard-fail the install, so installing a larger
+// dependency tree is not aborted by a transient network issue. The launcher
+// re-reports a missing binary with the same remediation if the CLI is run.
+
+import { createWriteStream, existsSync } from 'node:fs'
+import { mkdir, mkdtemp, readFile, rm, chmod, rename } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import { createReadStream } from 'node:fs'
+
+import { REPO, BIN_NAME, binDir, binPath, detectPlatform } from '../bin/_shared.mjs'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+
+// Load the SHA256 pinned into this package at publish time (checksums.json).
+// This digest — not the mutable GitHub .sha256 sidecar — is the source of truth
+// the download is verified against, so a given npm version always resolves the
+// same bytes. Returns "" when the package was not built by the release pipeline
+// (checked-in placeholder), which the caller treats as "cannot verify".
+async function pinnedChecksum(platform) {
+  try {
+    const raw = await readFile(path.join(here, '..', 'checksums.json'), 'utf8')
+    const parsed = JSON.parse(raw)
+    const sum = parsed && parsed.checksums ? parsed.checksums[platform] : ''
+    return typeof sum === 'string' ? sum.trim().toLowerCase() : ''
+  } catch {
+    return ''
+  }
+}
+
+function log(msg) {
+  process.stdout.write(`airi-cli: ${msg}\n`)
+}
+function warn(msg) {
+  process.stderr.write(`airi-cli: ${msg}\n`)
+}
+
+// Resolve the release tag: AIRI_CLI_VERSION wins, otherwise this package's own
+// version (so `npm install @airwallex/airi-cli@X` fetches the X binary — the
+// install is reproducible rather than "whatever is newest").
+async function resolveTag() {
+  const override = process.env.AIRI_CLI_VERSION
+  if (override && override.trim()) {
+    const v = override.trim()
+    return v.startsWith('v') ? v : `v${v}`
+  }
+  const pkg = JSON.parse(
+    await readFile(path.join(here, '..', 'package.json'), 'utf8')
+  )
+  return `v${pkg.version}`
+}
+
+async function download(url, dest) {
+  // Node 18+ has global fetch; the package requires node >=14 so fall back to
+  // https.get on older runtimes. Both follow redirects (GitHub asset URLs
+  // redirect to a CDN).
+  if (typeof fetch === 'function') {
+    const res = await fetch(url, { redirect: 'follow' })
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status} for ${url}`)
+    }
+    const buf = Buffer.from(await res.arrayBuffer())
+    await writeFileAtomic(dest, buf)
+    return
+  }
+  const { get } = await import('node:https')
+  await new Promise((resolve, reject) => {
+    const followGet = (u, redirects) => {
+      if (redirects > 10) return reject(new Error('too many redirects'))
+      get(u, (res) => {
+        if (
+          res.statusCode &&
+          res.statusCode >= 300 &&
+          res.statusCode < 400 &&
+          res.headers.location
+        ) {
+          res.resume()
+          const next = new URL(res.headers.location, u).toString()
+          return followGet(next, redirects + 1)
+        }
+        if (res.statusCode !== 200) {
+          res.resume()
+          return reject(new Error(`HTTP ${res.statusCode} for ${u}`))
+        }
+        const out = createWriteStream(dest)
+        res.pipe(out)
+        out.on('finish', () => out.close(resolve))
+        out.on('error', reject)
+      }).on('error', reject)
+    }
+    followGet(url, 0)
+  })
+}
+
+async function writeFileAtomic(dest, buf) {
+  const tmp = `${dest}.tmp`
+  await new Promise((resolve, reject) => {
+    const out = createWriteStream(tmp)
+    out.on('error', reject)
+    out.on('finish', resolve)
+    out.end(buf)
+  })
+  await rename(tmp, dest)
+}
+
+function sha256File(file) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash('sha256')
+    const s = createReadStream(file)
+    s.on('error', reject)
+    s.on('data', (d) => hash.update(d))
+    s.on('end', () => resolve(hash.digest('hex')))
+  })
+}
+
+// Extract the single binary from the .tar.gz using the platform `tar`, which is
+// present on macOS and Linux (the only platforms we ship). Avoids adding a tar
+// dependency to the package.
+function extract(tarball, destDir) {
+  const res = spawnSync('tar', ['-xzf', tarball, '-C', destDir], {
+    stdio: 'inherit',
+  })
+  if (res.error) throw res.error
+  if (res.status !== 0) throw new Error(`tar exited ${res.status}`)
+}
+
+async function main() {
+  if (process.env.AIRI_CLI_SKIP_DOWNLOAD === '1') {
+    warn('AIRI_CLI_SKIP_DOWNLOAD=1 — skipping binary download.')
+    return
+  }
+
+  let platform
+  try {
+    platform = detectPlatform()
+  } catch (err) {
+    // Unsupported platform: warn, don't fail the whole install.
+    warn(err.message)
+    warn("the CLI will not run on this platform.")
+    return
+  }
+
+  const tag = await resolveTag()
+  const asset = `${BIN_NAME}_${platform}.tar.gz`
+  // AIRI_CLI_BASE_URL overrides the release host for testing and for mirrors
+  // (e.g. an internal proxy of the GitHub assets). It must point at a location
+  // serving the same <tag>/<asset> layout. Defaults to GitHub.
+  const host = (process.env.AIRI_CLI_BASE_URL || `https://github.com/${REPO}/releases/download`).replace(/\/+$/, '')
+  const base = `${host}/${tag}/${asset}`
+
+  const skipChecksum = process.env.AIRI_CLI_SKIP_CHECKSUM === '1'
+  const expected = await pinnedChecksum(platform)
+
+  // Fail closed BEFORE downloading: if we have no pinned digest to verify
+  // against and the caller has not explicitly opted out, do not install an
+  // unverified binary. (A non-release build has empty checksums.json entries.)
+  if (!skipChecksum && !expected) {
+    warn(
+      `no pinned SHA256 for ${platform} in this package — refusing to install ` +
+        `an unverified binary.`
+    )
+    warn(
+      `this usually means the package was not built by the release pipeline. ` +
+        `Install a released version, or set AIRI_CLI_SKIP_CHECKSUM=1 to bypass ` +
+        `verification (local development only).`
+    )
+    return
+  }
+
+  // Per-platform temp dir with a random suffix (mkdtemp), not a predictable
+  // pid-based path: prevents a pre-planted symlink/file at a known location
+  // from being followed during the install.
+  const tmp = await mkdtemp(path.join(tmpdir(), 'airi-cli-'))
+
+  try {
+    log(`downloading ${BIN_NAME} ${tag} (${platform})`)
+    const tarball = path.join(tmp, asset)
+    await download(base, tarball)
+
+    if (skipChecksum) {
+      warn('AIRI_CLI_SKIP_CHECKSUM=1 — skipping SHA256 verification.')
+    } else {
+      const actual = (await sha256File(tarball)).toLowerCase()
+      if (expected !== actual) {
+        throw new Error(
+          `SHA256 mismatch for ${asset}\n  expected: ${expected}\n  actual:   ${actual}`
+        )
+      }
+      log('checksum OK')
+    }
+
+    const dir = binDir()
+    await mkdir(dir, { recursive: true })
+    extract(tarball, tmp)
+    const extracted = path.join(tmp, BIN_NAME)
+    if (!existsSync(extracted)) {
+      throw new Error(`archive did not contain expected '${BIN_NAME}' binary`)
+    }
+    const finalPath = binPath()
+    // Stage the new binary INSIDE the vendor dir (same filesystem as finalPath)
+    // and rename it into place. Renaming within one filesystem is atomic and
+    // avoids EXDEV (which a rename from os.tmpdir() across filesystems would
+    // hit) — and because the staged copy is fully in place and executable
+    // before the swap, a failure never leaves the old working binary deleted
+    // with no replacement.
+    const staged = path.join(dir, `.${BIN_NAME}.new`)
+    await rm(staged, { force: true })
+    await rename(extracted, staged)
+    await chmod(staged, 0o755)
+    await rename(staged, finalPath)
+    log(`installed binary to ${finalPath}`)
+  } catch (err) {
+    warn(`failed to download the airi-cli binary: ${err.message}`)
+    warn(
+      `you can retry by reinstalling the package, or set a specific version ` +
+        `with AIRI_CLI_VERSION. The binary is also available from:`
+    )
+    warn(`  https://github.com/${REPO}/releases/tag/${tag}`)
+    // Do not exit non-zero: a transient failure must not abort a larger
+    // `npm install`. The launcher surfaces the same guidance if run.
+  } finally {
+    await rm(tmp, { recursive: true, force: true })
+  }
+}
+
+main().catch((err) => {
+  warn(`unexpected error: ${err && err.message ? err.message : err}`)
+  // Still never fail the install.
+})