# Phase 2 Verification: install.sh + In-Place Update (v0.5 P2)

**Phase**: 2 (install.sh + in-place update)
**Milestone**: v0.5 Distribution
**Requirements covered**: REQ-043, REQ-044, REQ-016 (completion)
**Date**: 2026-08-03

## Structural Layer

- `gofmt -l .` → clean.
- `go vet ./...` → clean.
- `go build ./...` → succeeds.
- New files: `scripts/install.sh`, `scripts/install_test.sh`, `docs/install.md`.
- Modified files: `README.md`.
- `install.sh` is executable (`chmod +x`).

## Behavioral Layer

### install_test.sh — 8/8 tests pass

Run via `timeout 120 bash scripts/install_test.sh`:

1. **Test 1: user-level install (v0.4.1)** ✓
   - Binary at `~/.local/bin/orca` ✓
   - `orca version --json` returns `v0.4.1` ✓
2. **Test 2: in-place update (v0.4.1 → v0.4.2) preserves namespace** ✓
   - "updated orca from v0.4.1 to v0.4.2" message printed ✓
   - `~/.orca/orca.db` content preserved ("preserve-me") ✓
   - Binary version updated to `v0.4.2` ✓
3. **Test 3: idempotent re-install (v0.4.2 → v0.4.2)** ✓
   - "reinstalled orca v0.4.2" message printed ✓
4. **Test 4: --system install (root)** ✓
   - Binary at `/usr/local/bin/orca` ✓
   - Reports `namespace root: /root/.orca` ✓
5. **Test 5: --system without root** — SKIP (running as root)

### Manual e2e (real Gitea releases)
- `curl -fsSL ... | bash` downloads v0.4.2 tarball, extracts, installs ✓
- Re-run updates binary; namespace dir untouched ✓
- `--version v0.4.1` pins to v0.4.1 ✓

### Regression — Go tests
- `internal/cli/` ✓ (cached, no regressions from P1)
- `internal/store/` ✓
- `internal/doctor/` ✓

## Security Layer

- `install.sh` does not `eval` remote content — it downloads a tarball
  and extracts it with `tar -xzf`.
- No secrets in the script. `GITEA_TOKEN` is not required (public repo,
  anonymous download per REQ-045).
- `.env` is not referenced by install.sh.
- The script uses `set -euo pipefail` for fail-fast safety.
- `curl -fsSL` fails on HTTP errors (no silent 404 downloads).

## Quality Layer

- **1-liner install**: `curl -fsSL <url> | bash` works (verified).
- **--system flag**: installs to `/usr/local/bin`, namespace `/root/.orca`,
  requires root (errors otherwise).
- **--version pinning**: `--version vX.Y.Z` queries the specific release tag.
- **In-place update (REQ-044)**: detects existing binary, reads version via
  `orca version --json`, prints update message, overwrites binary, preserves
  namespace dir. Idempotent.
- **Env-overridable**: `GITEA_URL`, `GITEA_OWNER`, `GITEA_REPO` honor
  pre-set env vars (`${VAR:-default}`) for testability.
- **Timeout-guarded**: test harness uses `timeout 30` per test + `timeout 120`
  overall + `trap 'kill 0' EXIT` to prevent orphaned processes.
- **Documentation**: `docs/install.md` covers user/system install, version
  pinning, in-place update, uninstall, and troubleshooting. README quickstart
  updated with the 1-liner (REQ-016 completion).

## Must-Haves Checklist

- [x] `bash scripts/install_test.sh` passes (8/8).
- [x] `curl -fsSL <url> | bash` works on a fresh system.
- [x] `curl -fsSL <url> | bash -s -- --system` installs to `/usr/local/bin` (as root).
- [x] Re-running updates the binary; `~/.orca/orca.db` preserved.
- [x] README quickstart documents the 1-liner + `--system` variant.

## Verdict

**PASS** — all 4 verification layers pass. REQ-043, REQ-044, and REQ-016
(completion) are satisfied. Ready to ship as `v0.4.3`.