pkgpulse 0.1.3

Template-driven package recipe updater powered by nvchecker

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

cd pkgpulse
uv sync
uv run pkgpulse --help
uv run pkgpulse check
uv run pkgpulse diff
uv run pkgpulse render
uv run ruff check .
uv run pytest

Local Hooks

This repository is configured for local hook management with prek.

cd pkgpulse
prek validate-config .pre-commit-config.yaml
prek install
prek install-hooks
prek run --all-files

If you invoke prek from the monorepo root, point it at this project:

prek -C pkgpulse validate-config .pre-commit-config.yaml
prek -C pkgpulse run --all-files

Hook policy:

• pre-commit: standard file hygiene checks plus ruff

For full project validation, keep using:

uv run pkgpulse validate
uv run pytest -q

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.

[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.