# AGENTS.md

Quickemu is a Bash wrapper around QEMU that automates VM creation for ~1000 operating systems (Linux, macOS, Windows, BSDs). Two main tools: `quickget` downloads ISOs and creates configs; `quickemu` launches VMs with optimised hardware detection.

## Project structure

```
quickemu        # Main VM launcher script (Bash)
quickget        # OS downloader and config generator (Bash)
quickreport     # System diagnostics tool (Bash)
chunkcheck      # Download verification utility (Bash)
flake.nix       # Nix flake for packaging
package.nix     # Nix package definition
devshell.nix    # Development environment
```

## Development environment

```shell
nix develop                    # Enter devshell with all dependencies
direnv reload                  # Update .direnv/bin/quickemu for testing
```

The devshell patches `quickemu` to use Nix store paths for OVMF and Samba, writing to `.direnv/bin/quickemu`.

## Build and test commands

- Lint scripts: `shellcheck quickemu quickget quickreport chunkcheck`
- Test quickget URLs: `./quickget --check <os> [release] [edition]`
- Test ARM64 downloads: `./quickget --arch arm64 --check <os> [release] [edition]`
- Test all architectures: `./quickget --check-all-arch <os> [release] [edition]`
- List all supported OSes: `./quickget --list`
- Run VM: `./quickemu --vm <name>.conf`

## Code style

All scripts are Bash 4.0+ with ShellCheck compliance.

| File | Indent | Notes |
|------|--------|-------|
| quickemu | 2 spaces | Main VM launcher |
| quickget | 4 spaces | OS definitions and download logic |

**General conventions:**

- UTF-8, LF line endings, final newline
- Trim trailing whitespace (except Markdown)
- Functions use `function name() {` syntax
- Many functions are invoked indirectly via dynamic dispatch - `SC2317` is disabled globally in quickget

## Adding a new OS to quickget

Follow the [guide in the wiki](https://github.com/quickemu-project/quickemu/wiki/06-Advanced-quickget-features#adding-a-new-os-to-quickget). Each OS requires:

1. Entry in `os_info()` case statement
2. `releases_<os>()` function returning available versions
3. `editions_<os>()` function if multiple editions exist
4. `arch_<os>()` function if ARM64 is supported (defaults to amd64 only if omitted)
5. Download URL construction logic

## Commit message format

Commits must follow [Conventional Commits](https://www.conventionalcommits.org/). PR titles are validated against this format.

**Common prefixes:**

- `fix(quickget):` - Fix distro downloads, update editions/releases
- `fix(quickemu):` - Fix VM configuration or runtime issues
- `feat(quickget):` - Add new OS support
- `feat(quickemu):` - Add new VM features
- `ci:` - CI/workflow changes
- `docs:` - Documentation updates

**Examples from recent history:**

```
fix(quickget): update Zorin OS download method and editions
fix(quickget): handle Solus Xfce beta naming for older releases
fix(quickget): remove Athena OS (no longer getting updates)
```

## Pull request guidelines

- PR titles must match Conventional Commits format (enforced by CI)
- Single-commit PRs: commit message must match PR title
- Run `shellcheck` before submitting
- Test affected OS downloads with `./quickget --check <os> <release>`

## CI workflows

| Workflow | Trigger | Purpose |
|----------|---------|---------|
| lint-shellcheck | PR | ShellCheck with severity: warning |
| lint-pr | PR | Validates PR title matches Conventional Commits |
| test-quickget | PR | Tests quickget functionality |
| test-build-quickemu | PR | Build verification |
| flake-checker | PR | Nix flake validation |

## Platform support

- Host: Linux (x86_64, aarch64), macOS (x86_64, aarch64)
- Guest: x86_64 (default), aarch64 (set `arch="aarch64"` in VM config)
- ARM64 guests use AAVMF firmware and `virt` machine type
- Cross-arch emulation uses TCG (no KVM acceleration)
- OVMF/UEFI firmware: Linux only
- Bash 4.0+ required (explicit version check at runtime)

## Key dependencies

Runtime: qemu, cdrtools, curl, jq, spice-gtk, swtpm, samba, zsync
Linux-specific: OVMF (x86_64 guests), AAVMF (aarch64 guests), usbutils, mesa-demos