# Install Script Design

One-liner convenience script for downloading and installing the latest fafb-q binary on Linux.

## Usage

```bash
curl -fsSL https://bitbucket.org/thermsio/fafb-q/downloads/install.sh | sh
```

## Requirements

- Linux only (x86_64 or aarch64). macOS exits with a message directing users to `cargo install fafb-q`.
- POSIX `sh` compatible — no bashisms. Must work on Alpine/BusyBox, Debian, Ubuntu, RHEL, etc.
- Installs to `/usr/local/bin/fafb-q`.
- Uses `sudo` only when the current user is not root. If not root and `sudo` is not available, exits with a clear message ("Permission denied. Run as root or install sudo.").
- Cleans up temporary files on exit (success or failure).
- Requires `curl` (justified: the one-liner itself uses `curl` to fetch the script, so it is guaranteed present at execution time).

## Script Behavior

1. **Detect OS** — `uname -s` must be `Linux`. Any other value prints a message and exits 1.
2. **Detect architecture** — `uname -m` maps to a target triple:
   - `x86_64` → `x86_64-unknown-linux-musl`
   - `aarch64` / `arm64` → `aarch64-unknown-linux-musl`
   - Anything else → exit 1 with unsupported architecture message.
3. **Create temp directory** — `mktemp -d`. Register a `trap` to remove it on `EXIT`.
4. **Download** — `curl -fsSL` the tarball from `https://bitbucket.org/thermsio/fafb-q/downloads/fafb-q-latest-{target}.tar.gz` into the temp directory.
5. **Extract** — `tar xzf` with `--strip-components=1` into the temp directory.
6. **Verify** — confirm the `fafb-q` binary exists and is executable in the temp directory.
7. **Install** — `install -m 755` binary to `/usr/local/bin/fafb-q`. Create `/usr/local/bin` if it does not exist. Use `sudo` if current UID is not 0; if `sudo` is not found, exit with a clear permission error.
8. **Confirm** — run `fafb-q --version` as a smoke test that the binary is functional (not just present). Print a success message.
9. **Cleanup** — trap removes the temp directory.

## Error Handling

- `set -eu` at the top for fail-fast behavior.
- Each step prints a short status line so the user can see progress.
- If `curl` is not available, print a message and exit 1.
- If the download fails (curl returns non-zero), the `set -e` causes immediate exit.
- If the binary is missing after extraction, print an error and exit 1.

## Output Style

No color codes. Plain text only. Keeps output minimal and readable in all terminal environments and piped contexts.

Example output:
```
Detected: Linux x86_64
Downloading fafb-q for x86_64-unknown-linux-musl...
Installing to /usr/local/bin/fafb-q...
fafb-q 0.1.7
Install complete.
```

## File Location

- Source: `scripts/install.sh` in the repo
- Published: uploaded to Bitbucket Downloads alongside release tarballs so the one-liner URL works

## Distribution

The install script must be uploaded to Bitbucket Downloads as part of the release pipeline. Add a `curl -X POST` for `install.sh` inside the existing `&upload-downloads` step, alongside the tarball uploads. The script URL is stable across releases.

## README Update

Replace the manual curl/tar/cp instructions with the one-liner, keeping the manual steps as a fallback:

```markdown
### Pre-built binaries (recommended)

Statically linked binaries with no runtime dependencies:

```bash
curl -fsSL https://bitbucket.org/thermsio/fafb-q/downloads/install.sh | sh
```

Or manually:

```bash
# Linux x86_64
curl -LO https://bitbucket.org/thermsio/fafb-q/downloads/fafb-q-latest-x86_64-unknown-linux-musl.tar.gz
tar xzf fafb-q-latest-x86_64-unknown-linux-musl.tar.gz --strip-components=1
sudo cp fafb-q /usr/local/bin/
```
```

## Out of Scope

- macOS binary downloads (not published to Bitbucket Downloads today)
- Version pinning (always installs latest)
- Shell completion installation
- Config file scaffolding
- Checksum/signature verification (no separate checksum file is published today)
