# Install, Build, And Release

This guide covers installer options, source verification, release builds, and the maintainer publication workflow.

## Installer Options

The README contains the standard installation commands. Direct installation and later updates use the same script. The installer resolves the latest release by default, verifies the archive checksum and executable version, and writes an ownership receipt beside the installed binary. It refuses to replace a binary owned by another installation method unless explicitly forced.

Pin a version or choose another destination on macOS and Linux:

```bash
curl -fsSL https://github.com/Quicksaver/lfs-cloud/releases/latest/download/install.sh \
  | sh -s -- --version 0.2.6 --install-dir "$HOME/.local/bin"
```

On Windows, save the script before supplying options:

```powershell
irm https://github.com/Quicksaver/lfs-cloud/releases/latest/download/install.ps1 -OutFile install.ps1
./install.ps1 -Version 0.2.6 -InstallDir "$HOME/.local/bin"
```

Use `--force` or `-Force` only to deliberately replace an unmanaged executable.

## Build From Source

Use the Rust version declared by `package.rust-version` in `Cargo.toml`:

```bash
cargo build
cargo run -- --help
```

Repository formatting and smoke tooling also require Node.js and Yarn. Python 3 is required by the manual smoke scripts, PowerShell 7 by Windows verification, and `cargo-audit` 0.22.2 by the security check:

```bash
cargo install cargo-audit --locked --version 0.22.2
```

## Verify Changes

Run the standard local checks before publishing a change:

```bash
cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
cargo test --doc
cargo audit
yarn lint:check
node --no-warnings --experimental-strip-types .agents/skills/smoke-test/scripts/smoke-test.ts
```

The smoke runner creates disposable repositories below an existing throwaway Git repository. It uses `~/Sites/throwaway` on macOS and `~/Projects/throwaway` on Windows by default; set `LFS_CLOUD_SMOKE_THROWAWAY` to select another prepared parent.

For a clean commit already pushed to its matching branch on `origin`, run every verifier supported by the host:

```bash
yarn verify:all
```

macOS and Windows use their native verifier. A responsive Docker Linux engine adds ARM64 and x86-64 Linux verification. Selected checks run concurrently, retain complete logs under `logs/verify-*/`, package the exact tested binaries under `dist/`, and post distinct `local-checks/*` commit statuses.

Run one environment when focused verification is sufficient:

```bash
yarn verify:macos
yarn verify:linux-arm64
yarn verify:linux-x86-64
```

On native Windows x86-64:

```powershell
yarn verify:windows
```

Linux verification uses persistent architecture-specific Docker images, containers, and target volumes so repeated runs reuse build work without mixing platform artifacts. GitHub Actions CI is manual-only and provides an independent native four-platform verification path.

## Build Release Binaries

Build one optimized binary without running the full verifier:

| Platform       | Command                   | Rust target                  |
| -------------- | ------------------------- | ---------------------------- |
| macOS ARM64    | `yarn build:macos`        | `aarch64-apple-darwin`       |
| Linux ARM64    | `yarn build:linux-arm64`  | `aarch64-unknown-linux-musl` |
| Linux x86-64   | `yarn build:linux-x86-64` | `x86_64-unknown-linux-musl`  |
| Windows x86-64 | `yarn build:windows`      | `x86_64-pc-windows-msvc`     |

Linux builds require `musl-gcc`; every target must be installed in the active Rust toolchain. Output is written below `target/<rust-target>/release/`. Use the corresponding `verify:*` command when packaged archives, checksums, manifests, tests, and commit statuses are required.

## Publish A Release

The preferred maintainer workflow coordinates verification, versioning, native Windows assets, GitHub publication, and package distribution:

```bash
yarn release:all patch
# or: minor / major
```

Run it from a clean `main` checkout that exactly matches `origin/main`. The Mac requires `gh`, `ssh`, `iconv`, `base64`, Homebrew, and GitHub permissions for statuses, tags, releases, the Homebrew tap, and a WinGet fork. The default Windows worker is the SSH alias `windows-desktop` with a clean checkout at `E:\Projects\lfs-cloud`; override these only when the fleet layout changes:

```bash
export LFS_CLOUD_WINDOWS_SSH_HOST=windows-desktop
export LFS_CLOUD_WINDOWS_REPO='E:\Projects\lfs-cloud'
```

The coordinator:

1. Runs only missing trusted checks for macOS ARM64, Linux ARM64, Linux x86-64, and native Windows x86-64.
2. Creates the version commit, tag, changelog-backed draft, and platform assets.
3. Requires all four commit statuses and verifies every checksum, manifest, target, version, and commit.
4. Publishes an immutable GitHub release, then distributes the direct installers, Homebrew formula, optional Cloudsmith APT packages, and WinGet manifests.
5. After publication and distribution succeed, concurrently removes LFS Cloud's debug/test and release artifacts from the Mac, both Linux Docker target volumes, and Windows while retaining reusable dependency caches.

Cross-machine logs are retained under `logs/release-*/`. The validated Mac GitHub token is sent to key-authenticated Windows SSH sessions through encrypted stdin and exists there only as transient `GH_TOKEN`; it is never placed in arguments, logs, or files.

### Recovery And Lower-Level Commands

Rerun the same `release:all` command after correcting a failure. A matching tagged release commit resumes its existing draft or incomplete distribution rather than creating another version. Before retrying an interrupted Windows wave, confirm that the remote process has stopped because terminating the local SSH client does not necessarily stop it.

The lower-level commands are available for focused recovery:

| Command                     | Purpose                                                             |
| --------------------------- | ------------------------------------------------------------------- |
| `yarn release:local patch`  | Create the version commit, tag, draft, and macOS/Linux assets       |
| `yarn release:local resume` | Resume an interrupted local release without incrementing again      |
| `yarn release:windows`      | Verify and attach native Windows assets to an existing draft        |
| `yarn release:publish`      | Publish an eligible draft or resume incomplete package distribution |

`release:publish` validates downloaded draft assets rather than rebuilding from the current worktree. It enables GitHub release immutability before distribution; a later channel failure cannot make the release editable. Rerunning it skips completed channels and resumes only incomplete ones.

Set `LFS_CLOUD_APT_CLOUDSMITH_TARGET=OWNER/REPOSITORY/DISTRO/VERSION` before publication to opt into Cloudsmith APT distribution. Without it, APT is skipped and does not block completion. WinGet completion means its upstream pull request was submitted, not necessarily merged.

No GitHub Actions workflow publishes releases or package entries.

## Release Contents

A complete GitHub release contains:

- macOS ARM64, Linux ARM64, Linux x86-64, and Windows x86-64 archives
- Debian packages for both Linux architectures
- `install.sh` and `install.ps1`
- SHA-256 checksums and commit-bound build manifests
- changelog-derived release notes

The source is [MIT licensed](../LICENSE). The crate is not published to crates.io; `publish = false` and the private JavaScript package setting prevent registry publication without changing the source license.