aim/.audits/2026-03-21T02-02-28Z.md

# Repository Audit: aim (AppImage Manager)

**Timestamp:** 2026-03-21T02:02:28Z (UTC)  
**Commit:** f260790d915e350879838d027db8d602311d4437  
**Branch:** main  
**Repo Path:** /home/stoorps/repos/aim  
**Audit Scope:** Full repository — product completeness, provider support, registry operations, docs-vs-code mismatches, missing tests, v1.0 readiness

---

## Executive Summary

The `aim` AppImage manager has a **solid architectural foundation** with clean domain separation, good test coverage for GitHub flows, and working install/update/remove operations. However, **critical gaps exist** that block production v1.0 readiness:

- **Download reliability is insufficient** — entire files loaded into memory, no resume/retry, no timeouts, risking OOM on 500MB+ AppImages
- **Registry safety is weak** — no atomic writes, no backups, no corruption recovery, vulnerable to concurrent access
- **Documentation is stale** — README omits SourceForge, zsync, custom-json providers already in code
- **Missing product features** — no search, no version pinning, no dry-run, no info command, no rollback
- **Checksum verification exists but is unused** — metadata contains SHA-512 checksums that are parsed but never validated during downloads
- **CustomJsonAdapter is a non-functional stub** — declared but all methods return errors

**v1.0 Readiness Verdict:** **Not ready.** Core reliability gaps (download safety, registry atomicity, checksum validation) must be closed before production use. Feature gaps (search, info, dry-run) are acceptable for v1.0 but limit user expectations.

---

## Surface Map

### Entry Points
- **CLI:** `aim <query>`, `aim`, `aim update`, `aim list`, `aim remove <query>`
- **Scope Overrides:** `--user`, `--system`
- **Environment Variables:** `AIM_REGISTRY_PATH`, `AIM_GITHUB_TOKEN`, `GITHUB_TOKEN`, `AIM_GITHUB_API_BASE`, `HOME`

### Public Interfaces
- **Supported Query Forms:**
  - GitHub shorthand: `owner/repo`
  - GitHub URLs: repository, release, asset
  - GitLab URLs: repository, release-like, ambiguous candidates
  - SourceForge URLs: project, file download paths
  - Direct HTTPS/HTTP URLs
  - Local file imports: `file://...`

### Implemented Providers
- **Repository-backed:** GitHub, GitLab, SourceForge
- **Exact-resolution:** DirectUrl, File
- **Metadata-only:** Zsync (update channels), Electron Builder (checksums)
- **Stub:** CustomJson (all operations return errors)

### State & Data Layers
- **Registry:** TOML file at `~/.local/share/aim/registry.toml`, stores installed apps with source, version, update strategy
- **Install Paths:**
  - User scope: `~/.local/lib/aim/appimages`, `~/.local/share/applications`, `~/.local/share/icons`
  - System scope: `/opt/aim/appimages`, `/usr/share/applications`, `/usr/share/icons`
- **Staging:** `.local/share/aim/staging` for download-before-commit

### Cross-Cutting Concerns
- **Platform Detection:** Distro family (Debian, RedHat, Arch, Immutable, Nix, Alpine, Other), desktop session presence
- **Error Handling:** Distinct unsupported-query vs no-installable-artifact vs transport-failure errors
- **Progress Reporting:** Live spinners, byte progress, staged events (resolveQuery, discoverRelease, downloadArtifact, etc.)

---

## Findings (Prioritised Backlog)

### GAP-001: Download Reliability — Memory Exhaustion Risk
**Type:** Reliability / Performance  
**Severity:** **Critical**  
**Impact:** **Production blocker.** Large AppImages (500MB+) are loaded entirely into memory before writing to disk. Risky on low-memory systems, can trigger OOM kills.  
**Evidence:**
- [crates/aim-core/src/app/add.rs](crates/aim-core/src/app/add.rs#L506-L545): `download_artifact_bytes_with_reporter` allocates a `Vec<u8>`, reads 16KB chunks in a loop, then `extend_from_slice`. Full payload lives in heap before `stage_and_commit_payload` writes it.
- No streaming-to-disk, no memory pressure handling.

**Repro/Trace:**
1. Attempt `aim <large-appimage-url>` where payload is 1GB
2. Watch process RSS grow to 1GB+ before any file write

**Suggested Fix:**
- Stream directly to staged file path using `io::copy` or chunked writes with temp file + atomic rename
- Alternatively, use memory-mapped I/O for very large files
- Add download timeout via `reqwest::ClientBuilder::timeout`

**Acceptance Criteria:**
- [ ] Download writes directly to disk without intermediate full-buffer accumulation
- [ ] Memory usage stays constant regardless of AppImage size
- [ ] Configurable timeout (default 5 minutes)

---

### GAP-002: Download Reliability — No Resume, Retry, or Timeout
**Type:** Reliability  
**Severity:** **High**  
**Impact:** Network interruptions, slow connections, or server timeouts cause complete download restart. Poor UX for large files or unstable networks.  
**Evidence:**
- [crates/aim-core/src/app/add.rs](crates/aim-core/src/app/add.rs#L506-L545): Single `reqwest::blocking::get(url)` call, no retry loop, no partial-download resume via Range headers
- No timeout configured on `reqwest::blocking::Client` in `ReqwestGitHubTransport::new()` — hangs indefinitely on stalled connections

**Suggested Fix:**
- Add retry logic (3 attempts with exponential backoff)
- Support HTTP Range requests for resume if server supports it (check `Accept-Ranges` header)
- Configure request timeout (30s connect, 5m total)
- Provide `--no-resume` flag to skip range logic if needed

**Acceptance Criteria:**
- [ ] Failed downloads retry up to 3 times
- [ ] Partial downloads resume from last byte if server supports Range
- [ ] Timeout after 5 minutes of inactivity or 30s connect timeout

---

### GAP-003: Checksum Verification Not Used
**Type:** Security / Reliability  
**Severity:** **High**  
**Impact:** **Silent corruption or supply-chain attacks.** Metadata includes SHA-512 checksums (electron-builder) but downloads are never verified. Corrupted or tampered payloads install successfully.  
**Evidence:**
- [crates/aim-core/src/metadata/electron_builder.rs](crates/aim-core/src/metadata/electron_builder.rs#L8): Parses `sha512:` field from `latest-linux.yml`
- [crates/aim-core/src/domain/update.rs](crates/aim-core/src/domain/update.rs#L17): `MetadataHints` struct includes `checksum: Option<String>`
- No verification step in [crates/aim-core/src/app/add.rs](crates/aim-core/src/app/add.rs#L381) `download_artifact_bytes_with_reporter` or [crates/aim-core/src/integration/install.rs](crates/aim-core/src/integration/install.rs#L87-L115) `stage_and_commit_payload`

**Repro/Trace:**
1. Install app with known electron-builder metadata: `aim owner/repo`
2. Inject corrupt bytes into download stream (or MITM proxy)
3. Installation succeeds without checksum mismatch error

**Suggested Fix:**
- After download completes, compute SHA-512 of payload if `checksum` hint exists
- Fail installation with clear error if mismatch
- Add `--skip-checksum` flag for advanced users bypassing validation

**Acceptance Criteria:**
- [ ] SHA-512 checksums from metadata are verified post-download
- [ ] Mismatch triggers clear error with expected vs actual hash
- [ ] Installs without metadata checksums proceed with warning

---

### GAP-004: Registry Corruption — No Atomic Writes or Backups
**Type:** Reliability  
**Severity:** **High**  
**Impact:** Registry corruption if process killed mid-save. No recovery mechanism; complete data loss of installed apps list.  
**Evidence:**
- [crates/aim-core/src/registry/store.rs](crates/aim-core/src/registry/store.rs#L26-L31): `RegistryStore::save` directly writes to `self.path` via `fs::write`. Not atomic (no temp file + rename).
- [crates/aim-core/src/registry/store.rs](crates/aim-core/src/registry/store.rs#L14-L21): `load` returns `toml::de::Error` on corrupt file, no fallback to backup

**Repro/Trace:**
1. Start `aim sharkdp/bat`
2. Kill process (`kill -9`) during registry save stage
3. Attempt `aim list` — registry file is truncated or corrupt, operation fails

**Suggested Fix:**
- Atomic save: write to `registry.toml.new`, then `fs::rename` to `registry.toml`
- Backup previous registry to `registry.toml.bak` before overwrite
- On load failure, attempt restore from `.bak`
- Add corruption detection (signature header) for faster failure

**Acceptance Criteria:**
- [ ] Registry saves are atomic (temp file + rename)
- [ ] Previous registry backed up before save
- [ ] Corrupt registry auto-restores from backup with warning
- [ ] Test: kill process mid-save, verify registry intact

---

### GAP-005: Concurrent Access — No Registry Locking
**Type:** Reliability  
**Severity:** **Medium**  
**Impact:** Running multiple `aim` commands simultaneously can corrupt registry (race on read-modify-write). Data loss or duplicate entries possible.  
**Evidence:**
- [crates/aim-cli/src/lib.rs](crates/aim-cli/src/lib.rs#L34-L38): `dispatch_with_reporter` loads registry, mutates in-memory copy, saves back. No file lock.
- No `flock` or lock file mechanism in [crates/aim-core/src/registry/store.rs](crates/aim-core/src/registry/store.rs)
- Grep for `Mutex` found zero results in `crates/` — no concurrency control

**Repro/Trace:**
1. Terminal A: `aim sharkdp/bat` (slow network download)
2. Terminal B: `aim update` (starts while A is downloading)
3. Both save registry simultaneously, one clobbers the other

**Suggested Fix:**
- Advisory file lock on `registry.toml.lock` using `fs2` crate
- Acquire lock in `load()`, release in `save()`
- Fail fast with clear error if lock unavailable after 5s

**Acceptance Criteria:**
- [ ] Only one `aim` process can modify registry at a time
- [ ] Second process waits or fails cleanly with "registry locked" message
- [ ] Lock automatically released on crash (advisory lock semantics)

---

### GAP-006: Documentation — Missing Providers in README
**Type:** Documentation / DX  
**Severity:** **Medium**  
**Impact:** Users unaware of supported sources. SourceForge, zsync, custom-json implemented but undocumented.  
**Evidence:**
- [README.md](README.md#L23-L30): Documents GitHub, GitLab, direct URLs, file imports
- [crates/aim-core/src/adapters/mod.rs](crates/aim-core/src/adapters/mod.rs#L12-L19): `all_adapter_kinds()` includes `sourceforge`, `zsync`, `custom-json`
- [crates/aim-core/src/source/input.rs](crates/aim-core/src/source/input.rs#L53-L56): `classify_sourceforge_http` actively classifies SourceForge URLs
- grep for "SourceForge" in README.md: **no matches**

**Suggested Fix:**
- Update README "Query Forms" section:
  - Add SourceForge project URLs and file download URLs
  - Note zsync as discovered metadata only (not install source)
  - Document or remove custom-json (currently nonfunctional)
- Add examples: `aim https://sourceforge.net/projects/app/files/v1.0/App.AppImage/download`

**Acceptance Criteria:**
- [ ] README documents all functional source types
- [ ] SourceForge examples included
- [ ] Zsync role clarified (metadata vs source)
- [ ] Custom-json either documented as experimental or removed from public list

---

### GAP-007: CustomJsonAdapter Is Non-Functional Stub
**Type:** Missing Feature / Code Quality  
**Severity:** **Medium**  
**Impact:** Adapter listed in `all_adapter_kinds()` but completely unusable. Misleading.  
**Evidence:**
- [crates/aim-core/src/adapters/custom_json.rs](crates/aim-core/src/adapters/custom_json.rs#L1-L24):
  - `normalize()` returns `Err(AdapterError::UnsupportedQuery)`
  - `resolve()` returns `Err(AdapterError::UnsupportedSource)`
  - Zero tests for this adapter in `crates/aim-core/tests/`

**Suggested Fix:**
- **Option A (remove):** Delete adapter, remove from `all_adapter_kinds()`, document as future work
- **Option B (implement):** Define JSON schema for custom update metadata, implement resolution logic, add tests
- **Option C (mark experimental):** Add comment and feature flag, exclude from default builds

**Acceptance Criteria:**
- [ ] Either adapter works with documented schema, or removed from public API
- [ ] No adapter listed in `all_adapter_kinds()` that returns errors for all operations

---

### GAP-008: Missing CLI Commands — Search, Info, Show
**Type:** Missing Feature  
**Severity:** **Medium**  
**Impact:** Users must know exact owner/repo or URL beforehand. No discovery workflow.  
**Evidence:**
- [crates/aim-cli/src/cli/args.rs](crates/aim-cli/src/cli/args.rs#L1-L29): Only defines `Remove`, `List`, `Update` subcommands
- No `aim search`, `aim info <query>`, or `aim show <stable-id>` commands
- GitHub releases API supports search, but no CLI exposure

**Suggested Fix:**
- `aim search <keyword>` — search GitHub for AppImages (requires GitHub API search endpoint or external index)
- `aim info <query>` or `aim show <stable-id>` — display app details pre-install (version, description, assets) or post-install (installed paths, source, update status)

**Acceptance Criteria:**
- [ ] `aim search` returns list of candidate apps with descriptions
- [ ] `aim info` shows app metadata without installing
- [ ] `aim show bat` displays installed app details (version, files, source)

---

### GAP-009: Missing CLI Features — Dry-Run, Force, Verbose
**Type:** Missing Feature  
**Severity:** **Medium**  
**Impact:** Limited user control over operations. No preview mode, no way to debug issues, no forced reinstall.  
**Evidence:**
- [crates/aim-cli/src/cli/args.rs](crates/aim-cli/src/cli/args.rs): No `--dry-run`, `--force`, `--verbose`, `--no-desktop` flags
- All operations execute immediately without preview except update plan (`aim` bare shows pending updates but requires `aim update` to execute)

**Suggested Fix:**
- Add `--dry-run` / `-n`: Show what would be done without mutating state
- Add `--force` / `-f`: Reinstall even if already installed at same version
- Add `--verbose` / `-v`: Show detailed logs (API requests, file operations)
- Add `--no-desktop`: Skip desktop integration, install payload only

**Acceptance Criteria:**
- [ ] `aim --dry-run <query>` prints plan without installing
- [ ] `aim --force <query>` reinstalls existing app
- [ ] `aim --verbose list` shows debug output
- [ ] `aim --no-desktop <query>` installs without .desktop file

---

### GAP-010: No Version Pinning or Update Blocking
**Type:** Missing Feature  
**Severity:** **Medium**  
**Impact:** Users cannot pin to specific versions or exclude from updates. All apps track latest by default (unless installed from specific release URL).  
**Evidence:**
- [crates/aim-core/src/domain/app.rs](crates/aim-core/src/domain/app.rs): `AppRecord` has `installed_version`, `update_strategy`, but no `pinned` or `update_policy` field
- `aim update` blindly updates all apps without user filtering

**Suggested Fix:**
- Add `aim pin <stable-id>` and `aim unpin <stable-id>` commands
- Store `pinned: bool` or `update_policy: Auto | Manual | Pinned` in `AppRecord`
- `aim update` skips pinned apps, logs "X apps pinned, skipping"
- Add `--ignore <stable-id>` flag to `aim update` for one-time exclusion

**Acceptance Criteria:**
- [ ] `aim pin bat` prevents `aim update` from updating bat
- [ ] `aim list` shows pinned status
- [ ] `aim unpin bat` re-enables updates

---

### GAP-011: No Rollback or Update Failure Recovery
**Type:** Reliability  
**Severity:** **Medium**  
**Impact:** Failed updates leave old binary deleted but registry updated, or vice versa. No way to revert to previous version.  
**Evidence:**
- [crates/aim-core/src/app/update.rs](crates/aim-core/src/app/update.rs#L43-L75): `execute_updates_with_reporter` catches errors and records `UpdateExecutionStatus::Failed`, but old payload is already overwritten by [crates/aim-core/src/integration/install.rs](crates/aim-core/src/integration/install.rs#L102-L103) `fs::rename` steps
- No backup of old `.AppImage` file before update
- grep for `rollback` or `backup` found zero matches

**Repro/Trace:**
1. `aim sharkdp/bat` (install v1.0)
2. Tamper with network to force update download failure
3. `aim update` — old bat.AppImage replaced with corrupt download, registry shows v1.1 but binary is broken

**Suggested Fix:**
- Before update, rename `app.AppImage` to `app.AppImage.backup`
- On success, delete backup
- On failure, restore from backup and log rollback
- Add `aim rollback <stable-id>` command to restore previous version

**Acceptance Criteria:**
- [ ] Failed updates restore previous payload automatically
- [ ] Registry remains consistent with installed payload
- [ ] Manual rollback command available for user-initiated revert

---

### GAP-012: No Proxy Support or Network Configuration
**Type:** Missing Feature  
**Severity:** **Low**  
**Impact:** Corporate or privacy-conscious users behind proxies cannot use `aim`.  
**Evidence:**
- [crates/aim-core/src/source/github.rs](crates/aim-core/src/source/github.rs#L158-L175): `ReqwestGitHubTransport::new()` uses default `reqwest::blocking::Client` builder, no proxy configuration
- grep for `proxy`, `http_proxy`, `https_proxy`: zero matches

**Suggested Fix:**
- Respect `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` environment variables
- Use `reqwest::ClientBuilder::proxy()` to configure
- Add `--proxy <url>` CLI flag for override

**Acceptance Criteria:**
- [ ] `HTTP_PROXY=http://proxy:8080 aim <query>` uses proxy
- [ ] Corporate proxy users can install apps

---

### GAP-013: No Offline or Cache-First Mode
**Type:** Missing Feature  
**Severity:** **Low**  
**Impact:** Cannot use `aim` in air-gapped or intermittent-connectivity environments. Every operation requires network.  
**Evidence:**
- All provider adapters make live HTTP requests, no local cache

**Suggested Fix:**
- Cache GitHub release metadata in `~/.cache/aim/metadata/` for 1 hour
- Add `--offline` flag to use cached data only
- Add `--refresh` to force cache invalidation

**Acceptance Criteria:**
- [ ] `aim --offline list` works without network if metadata cached
- [ ] Metadata cached for 1 hour, revalidated on next request

---

### GAP-014: No Help Text or Usage Examples
**Type:** Documentation / DX  
**Severity:** **Low**  
**Impact:** Users must read README or guess commands. Poor discoverability.  
**Evidence:**
- [crates/aim-cli/src/cli/args.rs](crates/aim-cli/src/cli/args.rs#L1-L29): Clap definitions exist but no detailed `about` text or examples
- `aim --help` output is minimal (auto-generated clap summary)

**Suggested Fix:**
- Add `#[command(long_about = "...")]` with detailed usage examples
- Add `#[arg(help = "...")]` for each flag
- Include examples in help: `aim sharkdp/bat`, `aim list`, `aim remove bat`

**Acceptance Criteria:**
- [ ] `aim --help` shows examples and detailed descriptions
- [ ] Each subcommand has helpful usage text

---

### GAP-015: No CI-Friendly Output or Machine-Parseable Formats
**Type:** Missing Feature  
**Severity:** **Low**  
**Impact:** Cannot integrate `aim` into automation or scripts. Output is human-readable only.  
**Evidence:**
- [crates/aim-cli/src/ui/render.rs](crates/aim-cli/src/ui/render.rs): Output is styled text tables, no JSON or CSV option

**Suggested Fix:**
- Add `--format json|yaml|csv` flag
- Add `--quiet` / `-q` for errors-only output

**Acceptance Criteria:**
- [ ] `aim list --format json` returns machine-parseable output
- [ ] `aim --quiet <query>` suppresses progress spinners

---

### GAP-016: Test Coverage — Missing Tests
**Type:** Testing / Quality  
**Severity:** **Medium**  
**Impact:** Gaps in reliability verification.  
**Evidence:**
- **CustomJsonAdapter:** Zero tests in [crates/aim-core/tests/](crates/aim-core/tests/)
- **Concurrency:** No tests simulating concurrent registry access
- **Corruption recovery:** No tests for registry load failures + backup restore
- **Large files:** No tests for memory usage on 500MB+ downloads
- **Network failures:** Limited retry/timeout tests
- grep for `custom_json` in `tests/`: zero matches

**Suggested Fix:**
- Add `custom_json_adapter_contract_test` if adapter is retained
- Add `concurrent_registry_access_test` using threads
- Add `registry_corruption_recovery_test` with intentionally corrupt TOML
- Add `large_file_download_memory_test` mocking 1GB payload
- Add `network_failure_retry_test` with flaky mock server

**Acceptance Criteria:**
- [ ] All adapters in `all_adapter_kinds()` have contract tests
- [ ] Concurrency edge cases covered
- [ ] Corruption recovery path validated

---

## Quick Wins

Fixes that deliver high user value with low implementation cost:

1. **GAP-006 (Documentation)** — Update README with SourceForge, zsync usage (~30 minutes)
2. **GAP-014 (Help Text)** — Add detailed clap help strings (~1 hour)
3. **GAP-009 (Dry-Run Flag)** — Add `--dry-run` flag that skips final save (~2 hours)
4. **GAP-007 (CustomJson Cleanup)** — Remove non-functional adapter or add experimental marker (~30 minutes)
5. **GAP-004 (Registry Backups)** — Copy registry to `.bak` before save (~1 hour)

---

## Open Questions

1. **Checksums:** Should aim fail-closed (reject unverified downloads) or warn-only? Some sources lack checksums.
2. **Update Policy:** Default to auto-update all apps, or require explicit `aim update <stable-id>`?
3. **Version Pinning:** Should pinned apps show in `aim list` with special marker, or hidden?
4. **Search Scope:** Limit search to apps with AppImage releases, or show all repos?
5. **CustomJson:** Is this intended for user-defined update feeds? Should it support local JSON files or HTTP endpoints?
6. **Offline Mode:** Cache release metadata only, or cache payloads too?
7. **Platform Support:** Current code is Linux-only (by design). Document macOS/Windows as non-goals?
8. **Concurrency:** Should `aim` support lock wait timeout (fail fast) or infinite retry?

---

## Appendix

### Notable Search Patterns
- `TODO|FIXME|HACK`: **0 matches** in Rust source (clean codebase)
- `unimplemented!`: 0 matches
- `panic!`: Minimal use, only in test fixtures
- `.unwrap()`: Mostly in tests, production code uses `Result`

### Files Reviewed
- All `.rs` files in `crates/aim-core/src/` (app, adapters, domain, integration, platform, registry, source, update, metadata)
- All `.rs` files in `crates/aim-cli/src/` (cli, ui, lib, main)
- All test files in `crates/aim-core/tests/` and `crates/aim-cli/tests/`
- [README.md](README.md), [Cargo.toml](Cargo.toml)
- Planning docs in [.plans/007-source-provider-expansion/](.plans/007-source-provider-expansion/)

### Test Coverage Hotspots
- **Strong:** GitHub flows (discovery, parsing, install, update), GitLab basic flows, SourceForge URL classification
- **Moderate:** DirectUrl, file imports, metadata parsing (zsync, electron-builder), platform detection, remove flows
- **Weak:** CustomJson (zero), concurrency, corruption recovery, network failures, large file handling

---

## v1.0 Readiness Verdict

**Status:** **Pre-Alpha → Alpha** (not v1.0-ready)

**Blockers for v1.0:**
1. **GAP-001 (Memory exhaustion)** — Critical reliability issue
2. **GAP-003 (Checksum verification)** — Critical security issue
3. **GAP-004 (Registry atomicity)** — Critical data safety issue
4. **GAP-005 (Concurrent access)** — High-severity correctness issue

**Nice-to-Have for v1.0:**
- Search, info commands
- Dry-run mode
- Proxy support
- Better help text

**Recommendation:**  
Close **GAP-001, GAP-003, GAP-004, GAP-005** before any production announcement. After those fixes, aim reaches **beta** status (core safety established). User-facing features (search, pin, rollback) can ship in v1.1+.

**Effort Estimate (Blockers Only):** ~3-5 engineering days for someone familiar with Rust + reqwest + file I/O patterns.

**Current Strengths:**
- Clean architecture (adapters, domain, app separation)
- Provider expansion path is well-designed
- Good test coverage for happy paths
- Terminal UX is polished (progress bars, styled output)
- Platform detection handles immutable distros, Nix, etc.

**Overall Quality:** Well-built for internal/hobby use. Needs production hardening for public v1.0.