Metadata-Version: 2.4
Name: pkgpulse
Version: 0.1.6
Summary: Template-driven package recipe updater powered by nvchecker
Keywords: package,updater,nvchecker,template
Author: poesty
Author-email: poesty <poesty7450@gmail.com>
License-Expression: WTFPL
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: System :: Archiving :: Packaging
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: Utilities
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Requires-Dist: jinja2>=3.1
Requires-Dist: nvchecker>=2.20
Requires-Python: >=3.11
Project-URL: Homepage, https://codeberg.org/poesty/pkgpulse
Project-URL: Source, https://codeberg.org/poesty/pkgpulse
Description-Content-Type: text/markdown

# pkgpulse

`pkgpulse` is a template-driven package recipe updater with a broad scope:

- one TOML config file
- `nvchecker` Python API for update detection
- Jinja2 templates with user-defined template and output paths
- actions as plugins, with `git`, `webhook`, and `exec` at the same level

It is aimed at package recipe repositories rather than one packaging format.

## Quick Start

```sh
cd pkgpulse
uv sync
uv run pkgpulse --help
uv run pkgpulse check
uv run pkgpulse diff
uv run pkgpulse render
```

For development setup, local hooks, and validation commands, see
`CONTRIBUTING.md`.

## Automation Templates

Repository-local automation templates live here:

- GitHub: `.github/actions/pkgpulse/action.yaml`
- Forgejo: `.forgejo/actions/pkgpulse/action.yaml`
- GitLab: `.gitlab/pkgpulse.yml`

Use these when you want reusable platform-native execution templates instead of
inlining setup and `pkgpulse` invocation logic in every pipeline file.

## Configuration

The default config file is `pkgpulse.toml`.

```toml
[state]
oldver = ".pkgpulse/oldver.json"
newver = ".pkgpulse/newver.json"

[nvchecker]
max_concurrency = 8
tries = 2

[[targets]]
name = "nvchecker-release"
template = "templates/example.recipe.j2"
output = "build/nvchecker-release.txt"

[targets.check]
source = "github"
github = "lilydjwg/nvchecker"
use_max_tag = true

[targets.context]
package_name = "nvchecker"
summary = "Example package rendered by pkgpulse"
homepage = "https://github.com/lilydjwg/nvchecker"
archive_base = "https://github.com/lilydjwg/nvchecker/archive/refs/tags"

[[targets.actions]]
type = "exec"
when = "changed"
command = ["printf", "rendered %s -> %s\\n", "{{ job.name }}", "{{ paths.output }}"]
```

Additional example configs live under `examples/`:

- `examples/config/pkgpulse.example.toml`: render example with an `exec` action
- `examples/config/pkgpulse-webhook-action.example.toml`: webhook example for downstream triggers
- `examples/config/pkgpulse-git-action.example.toml`: commit example with a `git` action
- `examples/config/pkgpulse-strategies.example.toml`: multi-target example showing release and latest-commit packaging side by side

Example templates live under `examples/templates/`.

## Template Context

Every target render gets these objects:

- `job`: target metadata, template path, output path, and user context
- `check`: latest nvchecker result, including `version`, `old_version`, `changed`, `url`, `revision`, `gitref`
- `paths`: project root, template path, output path
- `context`: the raw `[targets.context]` mapping
- `now`: current UTC timestamp

The keys from `[targets.context]` are also merged into the top-level template namespace.

## Action Types

- `exec`
- `webhook`
- `git`

Each action supports `when = "always" | "changed" | "updated" | "rendered"`.

## Multi-Strategy Layout

`pkgpulse` models this by defining multiple `targets`:

- one target can follow tags directly from the upstream git remote
- another target can follow the latest upstream commit with `source = "git"` and `use_commit = true`

See `examples/config/pkgpulse-strategies.example.toml` for a concrete example
that renders both a release spec and a git snapshot spec from the same upstream project.

## Commands

- `pkgpulse check`
- `pkgpulse render`
- `pkgpulse diff`
- `pkgpulse validate`
- `pkgpulse run`

`pkgpulse run --dry-run` renders in memory and prints diffs without writing files or executing actions.

## Workflow Examples

Repository automation examples for GitHub Actions, GitLab CI, and Forgejo
Actions live under `examples/workflows/`.
They are optional outer workflow examples. The primary reusable automation
entrypoints are the local templates listed above.
