1---
  2name: maintaining-aur-packages
  3description: Creates and updates AUR packages following Arch packaging standards. Use when creating new AUR packages, updating existing AUR PKGBUILDs, bumping package versions, or when the user mentions AUR, PKGBUILD, makepkg, pacman packaging, or Arch Linux packages.
  4user-invocable: true
  5license: LicenseRef-MutuaL-1.2
  6metadata:
  7  author: Amolith <amolith@secluded.site>
  8---
  9
 10## Code style
 11
 12- PKGBUILD is bash; `.install` files are POSIX-sh–compatible functions
 13- Indent 2 spaces; UTF-8; LF endings; no trailing whitespace
 14- Single quotes for literals; double quotes when expanding variables
 15- Quote variables: `"$pkgdir"`, `"$srcdir"`, and all paths
 16- Prefix custom PKGBUILD variables with `_` to avoid collisions with makepkg internals
 17- Arrays: `arch`, `license`, `provides`, `conflicts` use `( ... )` syntax
 18- `arch=('x86_64')` for compiled packages; `arch=('any')` for arch-independent ones
 19- `license=()` must use [SPDX identifiers](https://spdx.org/licenses/)
 20- Functions: `prepare()`, `build()`, `check()`, `package()`; only define the ones needed
 21- No `sudo`, networking, or user config in `build`/`package` functions
 22- Use `install -Dm755` for binaries; set exact modes explicitly
 23- Keep checksums in sync with sources
 24- Keep `.SRCINFO` in lockstep with PKGBUILD; never commit build artifacts
 25
 26## Package types
 27
 28When the working directory contains subdirectories with these suffixes, we're maintaining multiple packages for the same software:
 29
 30- **suffix-less**: Downloads a release archive, builds, and installs from source
 31- **`-bin`**: Downloads the project's pre-built binary and installs it
 32- **`-git`**: Clones the primary branch and builds from source; version is determined by `updpkgsums`, not specified manually
 33
 34If no subdirectories exist, we're maintaining a single package. The current directory name indicates which type.
 35
 36## Constraints
 37
 38- The agent **cannot run `makepkg`**. Always give the user a copyable code block of `makepkg` commands instead.
 39- Same applies to `makepkg --printsrcinfo > .SRCINFO`.
 40- Use `updpkgsums` for checksums (agent can run this).
 41- Use `namcap` to lint built `.pkg.tar.zst` files (agent can run this).
 42- Use `b2sums` for all packages.
 43
 44## Creating packages
 45
 46Follow this strict workflow. If a planning or todo tool is available, fill it
 47out in detail; the session might get interrupted and need to resume.
 48
 491. List the contents of the current working directory.
 50   - Read any text files present.
 51   - List subdirectory contents (ignore what looks like the upstream project repo).
 52   - Subdirectories with `-bin` or `-git` suffixes mean multiple packages for the same software.
 53
 542. Ask for: package name (`provides=`), description (`pkgdesc=`), license (`license=()`), and the license path inside the project repo (for `install`ing). For each non-`-git` package, ask for the current version and source URL.
 55   - **`-git` packages**: Use `"$pkgname::git+https://...#branch=BRANCH"` as the source entry (the `$pkgname::` prefix ensures makepkg clones into a directory matching `$pkgname`; the `#branch=` fragment selects the branch). Add `git` to `makedepends`. Use `b2sums=('SKIP')` — VCS sources have no static content to checksum. Include this versioning function:
 56     ```bash
 57     pkgver() {
 58       cd "$pkgname" || exit
 59       ( set -o pipefail
 60         git describe --long --abbrev=7 2>/dev/null | sed 's/\([^-]*-g\)/r\1/;s/-/./g' ||
 61         printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short=7 HEAD)"
 62       )
 63     }
 64     ```
 65   - **`-bin` packages**: Use `bin-name-$pkgver::https://...` in `source`, then `install` `bin-name-$pkgver` as `bin-name`. Obtain the license from the original repo. For GitHub sources, the raw URL is `https://raw.githubusercontent.com/USER/REPO/refs/tags/{TAG}/LICENSE`. For non-GitHub sources, ask for the raw tagged LICENSE URL.
 66
 673. Write a `PKGBUILD` for each package. `Maintainer` comment: `Amolith <amolith@secluded.site>`. If multiple packages, include `conflicts=()` so they can't coexist. Packages with `-git` or `-bin` suffixes use versioned provides: `provides=("pkgname=${pkgver}")`. Use `b2sums` (except `-git` sources, which use `'SKIP'`).
 68
 694. Ask to find and relay the build system/installation methods recommended by the project (e.g. `cargo` for Rust, `go` for Go).
 70
 715. Adapt those instructions for each package's `build()`, `check()`, `package()`, etc. See [build-patterns.md](references/build-patterns.md) for language-specific templates.
 72
 736. Present **all** diagnostics, whether seemingly relevant or not, with reasoning for each. Resolve genuine issues before proceeding.
 74
 757. Update checksums with `updpkgsums` in each package directory.
 76
 778. Give the user a copyable code block of `makepkg -Ccsi` commands. Include `cd` if multiple packages. Work through any build issues.
 78
 799. After the user builds, run `namcap` on `./package-name-*.pkg.tar.zst`. Report all issues with reasoning.
 80
 8110. Give the user `makepkg --printsrcinfo > .SRCINFO` commands (with `cd` if multiple packages).
 82
 8311. If only PKGBUILDs and `.SRCINFO`s were created, enter each package directory and `git add` + `git commit` them. If other tracked files were modified, show the diff and ask which to commit. Create a `.gitignore` in each repo listing everything not committed, using appropriate globs.
 84
 8512. Clean all artifacts with `git clean -fdx`.
 86
 87## Updating packages
 88
 89Follow this strict workflow.
 90
 911. List the contents of the current working directory.
 92   - Read any text files present.
 93   - List subdirectory contents (ignore what looks like the upstream project repo).
 94   - Subdirectories with `-bin` or `-git` suffixes mean multiple packages.
 95
 962. We're upgrading to version `$VERSION`. Read the PKGBUILD(s), then edit the version number for non-`-git` packages.
 97
 983. Update checksums with `updpkgsums`.
 99
1004. Present **all** diagnostics with reasoning. Resolve genuine issues before proceeding.
101
1025. Give the user a copyable code block of `makepkg -Ccsi` commands. Include `cd` if multiple packages. Work through any build issues.
103
1046. After the user builds, run `namcap` on `./package-name-*.pkg.tar.zst`. Report all issues with reasoning.
105
1067. Give the user `makepkg --printsrcinfo > .SRCINFO` commands.
107
1088. If only `PKGBUILD` and `.SRCINFO` were modified, `git add` and `git commit` them. If other tracked files were modified, show the diff and ask which to commit.
109
1109. Clean all artifacts with `git clean -fdx`.
111
112If anything other than `pkgver` is edited during the update, re-run `shellcheck` and `namcap` as appropriate.