various changes + new -sys package example

.github/CONTRIBUTING.md

@@ -54,7 +54,9 @@ Repo-root helper scripts:
   `origin/master..HEAD`) carries a `Signed-off-by:` trailer matching its
   author. Homebaked DCO check; CI runs it on every push and PR.
 - `./clean` — remove all git-ignored build debris (`pkg/`, `src/`, fetched
-  sources, built packages) repo-wide, after a confirmation prompt.
+  sources, built packages, and makepkg's persistent git mirror clones)
+  repo-wide, after a confirmation prompt. Uses `git clean -Xffd`; the double
+  `-f` is needed to delete the embedded git checkouts makepkg leaves behind.
 - `./bump [pkg...]` — refresh packages to the latest upstream state, by tier:
   `*-rel` runs `pkgctl version upgrade` + `updpkgsums`; `*-git` re-clones and
   reruns `pkgver()` (no hashes to bump — git's ref is the integrity check).

.gitignore

@@ -12,26 +12,33 @@ src/
 # (!pkgs/**/ lets git descend into dirs to find the allowed files.)
 pkgs/**
 !pkgs/**/
-# ...but never descend back into makepkg build dirs (!pkgs/**/ re-included them).
-# Without this, an embedded VCS checkout under src/ leaks in as a git submodule.
-pkgs/**/pkg/
-pkgs/**/src/
-!pkgs/**/.directory
-!pkgs/**/PKGBUILD
-!pkgs/**/.SRCINFO
-!pkgs/**/.gitignore
-!pkgs/**/.nvchecker.toml
-!pkgs/**/REUSE.toml
-!pkgs/**/*.patch
-!pkgs/**/*.diff
-!pkgs/**/*.hook
-!pkgs/**/*.service
-!pkgs/**/*.sysusers
-!pkgs/**/*.tmpfiles
-!pkgs/**/*.desktop
-!pkgs/**/*.asc
+# Real recipe files live DIRECTLY in pkgs/<name>/. Re-ignore every subdirectory
+# of a recipe — makepkg's src/ and pkg/, and the persistent git mirror clone at
+# pkgs/<name>/<pkgname>/. Otherwise an upstream-shipped *.hook (or *.service,
+# *.desktop, ...) inside a clone would leak via the file allowlist below, and
+# the clone's embedded .git would be added as a gitlink. keys/ is re-allowed
+# right after as the one legitimate nested location.
+pkgs/*/*/
+!pkgs/*/keys/
+# Allowlisted files are matched ONE level deep (pkgs/*/FILE), never pkgs/**/FILE,
+# so nothing inside a re-ignored subdir can sneak back in.
+!pkgs/*/.directory
+!pkgs/*/PKGBUILD
+!pkgs/*/.SRCINFO
+!pkgs/*/.gitignore
+!pkgs/*/.nvchecker.toml
+!pkgs/*/REUSE.toml
+!pkgs/*/*.patch
+!pkgs/*/*.diff
+!pkgs/*/*.hook
+!pkgs/*/*.service
+!pkgs/*/*.sysusers
+!pkgs/*/*.tmpfiles
+!pkgs/*/*.desktop
 # .install scriptlets only in -sys recipe dirs (the suffix that opts in).
 !pkgs/*-sys/*.install
+# Detached signatures: the one allowed nested location (keys/pgp/*.asc).
+!pkgs/*/keys/**/*.asc
 
 # --- editor / OS noise ---
 *.swp

clean

@@ -1,7 +1,11 @@
 #!/bin/bash
-git clean -Xnd
+# -X  remove ignored files only (tracked/unknown files are left alone)
+# -d  recurse into directories
+# -ff force twice: the second -f is required to delete nested git repos
+set -u
+git clean -Xffdn
 
 read -rp "Proceed? [y/N] " reply
 [[ "${reply}" == [yY] ]] || { echo "aborted"; exit 0; }
 
-git clean -Xfd
+git clean -Xffd

pkgs/oprah-git-sys/.SRCINFO

@@ -0,0 +1,15 @@
+pkgbase = oprah-git-sys
+	pkgdesc = Pacman hook that lists orphaned packages after each transaction
+	pkgver = r1.gd416fa6
+	pkgrel = 1
+	url = https://github.com/h8d13/oprah
+	install = oprah.install
+	arch = any
+	license = 0BSD
+	depends = pacman
+	provides = oprah
+	conflicts = oprah
+	source = oprah-git-sys::git+https://github.com/h8d13/oprah.git
+	sha256sums = SKIP
+
+pkgname = oprah-git-sys

pkgs/oprah-git-sys/.nvchecker.toml

@@ -0,0 +1,4 @@
+[oprah-git-sys]
+source = "git"
+git = "https://github.com/h8d13/oprah.git"
+use_commit = true

pkgs/oprah-git-sys/PKGBUILD

@@ -0,0 +1,28 @@
+# Maintainer: Eihdran Lego <hadean-eon-dev@proton.me>
+
+pkgname=oprah-git-sys
+pkgver=r1.gd416fa6
+pkgrel=1
+pkgdesc="Pacman hook that lists orphaned packages after each transaction"
+arch=('any')
+_repo="h8d13/oprah"
+url="https://github.com/${_repo}"
+
+license=('0BSD')
+depends=('pacman')
+provides=('oprah')
+conflicts=('oprah')
+install="oprah.install"
+source=("$pkgname::git+$url.git")
+sha256sums=('SKIP')
+
+pkgver() {
+	cd "${srcdir}/${pkgname}"
+	printf 'r%s.g%s' "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)"
+}
+
+package() {
+	cd "${srcdir}/${pkgname}"
+	install -Dm755 check-orphans "${pkgdir}/usr/share/libalpm/scripts/check-orphans"
+	install -Dm644 check-orphans.hook "${pkgdir}/usr/share/libalpm/hooks/check-orphans.hook"
+}

pkgs/oprah-git-sys/REUSE.toml

@@ -0,0 +1,9 @@
+version = 1
+
+# Packaging files in this recipe are licensed 0BSD (Arch convention),
+# independent of the upstream project's own license.
+[[annotations]]
+path = "**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2026 Eihdran Lego <hadean-eon-dev@proton.me>"
+SPDX-License-Identifier = "0BSD"

pkgs/oprah-git-sys/oprah.install

@@ -0,0 +1,11 @@
+post_install() {
+	cat <<'EOF'
+==> oprah: orphaned packages will be listed after each
+    pacman transaction. It only reports — remove them yourself with:
+      sudo pacman -Rns $(pacman -Qtdq)
+EOF
+}
+
+post_upgrade() {
+	post_install
+}