feat: add initial pacman Prometheus exporterv1.0.0

Add the first production-ready release of prometheus-pacman-exporter for
collecting pacman package statistics through the node exporter textfile
collector.

Collect installed, explicit, dependency, unrequired, foreign, native,
orphan, and updateable package metrics. Support checkupdates as an
alternative update source and optional AUR update collection through a
configurable command.

Add the Click-based CLI, Prometheus metric definitions, package
metadata, dependency lockfile, README, licensing metadata, and
development configuration.

1 files changed, 131 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4a5e90f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,131 @@
+<!--
+SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
+
+SPDX-License-Identifier: BSD-3-Clause
+-->
+
+# prometheus-pacman-exporter
+
+A Prometheus metrics exporter for [pacman](https://archlinux.org/pacman/),
+designed to be run via a systemd timer and consumed by the [node exporter
+textfile
+collector](https://github.com/prometheus/node_exporter#textfile-collector).
+
+## Requirements
+
+- Python 3.12+
+- pacman
+- checkupdates (optional)
+- An AUR helper or other update command (optional)
+
+## Installation
+
+```bash
+pip install prometheus-pacman-exporter
+```
+
+## Usage
+
+```
+Usage: prometheus-pacman-exporter [OPTIONS]
+
+  Collect pacman package metrics and export them for Prometheus.
+
+  Queries pacman for installed package statistics and available updates, then
+  writes them to a .prom file for consumption by the Prometheus node exporter
+  textfile collector.
+
+  By default, updateable packages are determined using pacman --query
+  --upgrades. Use --use-checkupdates to query updates with checkupdates
+  instead. AUR update metrics can optionally be collected by providing --aur
+  together with --aur-command.
+
+Options:
+  --textfile-collector-dir DIRECTORY
+                                  Directory where the Prometheus collector
+                                  textfile will be written.
+                                  [default: /var/lib/prometheus/node-exporter]
+  --use-checkupdates              Use checkupdates instead of pacman --query
+                                  --upgrades to check for available updates.
+  --aur                           Include AUR updates.
+  --aur-command TEXT              Command used to check for AUR updates.
+  --color [auto|always|never]     Colorize the output. A bare --color is the
+                                  same as --color=always.
+                                  [default: auto]
+  --no-color                      Disable colorization (alias of
+                                  --color=never).
+  -q, --quiet                     Suppress all non-error output.
+  -v, --verbose                   Enable verbose output.
+  --version                       Show version information and exit.
+  -h, --help, -?                  Show this message and exit.
+```
+
+### Checking for updates
+
+By default, available repository updates are determined using:
+
+```bash
+pacman --query --upgrades
+```
+
+This only reports updates already known to the local package database.
+
+Use `--use-checkupdates` to instead use
+[`checkupdates`](https://man.archlinux.org/man/checkupdates.8), which checks
+for available updates without modifying the system's package database:
+
+```bash
+prometheus-pacman-exporter --use-checkupdates
+```
+
+### AUR updates
+
+AUR updates can be included with `--aur`. An update command must also be
+provided with `--aur-command`:
+
+```bash
+prometheus-pacman-exporter \
+    --aur \
+    --aur-command "paru --query --upgrades --aur"
+```
+
+The AUR command may use any AUR helper or custom program, provided its standard
+output contains **exactly one available package update per line**. The exporter
+counts the number of output lines; it does not interpret the contents of those
+lines.
+
+For example, output such as:
+
+```text
+package-one 1.2.3-1 -> 1.2.4-1
+package-two 4.5.6-1 -> 4.6.0-1
+```
+
+is interpreted as two available AUR updates.
+
+Diagnostic or informational messages from the command should therefore be
+written to standard error rather than standard output.
+
+The value of `--aur-command` is split into command-line arguments and executed
+directly. It is not executed through a shell, so shell features such as pipes,
+redirections, variable expansion, and command substitution are not available.
+
+## Metrics
+
+| Metric                           | Description                                        |
+| -------------------------------- | -------------------------------------------------- |
+| `pacman_installed_packages`      | Total number of installed packages                 |
+| `pacman_explicit_packages`       | Number of explicitly installed packages            |
+| `pacman_depends_packages`        | Number of packages installed as dependencies       |
+| `pacman_unrequired_packages`     | Number of packages not required by another package |
+| `pacman_foreign_packages`        | Number of packages not present in sync databases   |
+| `pacman_native_packages`         | Number of packages present in sync databases       |
+| `pacman_orphan_packages`         | Number of orphaned dependency packages             |
+| `pacman_updateable_packages`     | Number of available repository package updates     |
+| `pacman_aur_updateable_packages` | Number of available AUR package updates            |
+
+The AUR update metric is only collected when `--aur` is enabled.
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSES/BSD-3-Clause.txt) for details.