`punix upgrade`¶

Report newer upstream versions for packages with a meta.upstream declaration.

punix upgrade --check-all [FILE] [--scenario NAME]

What it does¶

For every package module in FILE (or the default-discovered tree — see $PUNIX_PACKAGES / ./packages/) that declares meta.upstream = { type = "...", repo = "X/Y" }:

Reads the upstream spec (type, repo).
Queries the upstream via the gh CLI (one call per package; uses your gh auth login).
Compares the returned version against the recipe's version.
Prints one row per package where they differ.

This is a read-only report — no PCL is rewritten. The --apply mode (auto-rewrite the version + hash) is deferred; operators bump recipes by hand or re-run the brew translator.

Supported upstream types¶

`type`	What it queries	Resolver
`github-release`	`repos/<repo>/releases/latest` → `tag_name`	`gh api`
`github-tag`	`repos/<repo>/tags?per_page=1` → first `name`	`gh api`

Modules without a meta.upstream declaration are silently skipped — they have no machine-readable upstream, so there's nothing to check.

Example¶

$ cd ~/projects/my-pcl-tree
$ punix upgrade --check-all
atuin    18.2.0 → 18.3.0  (github-release atuinsh/atuin)
just     1.50.0 → 1.51.0  (github-tag casey/just)
ripgrep  14.1.0 → 15.0.0  (github-release BurntSushi/ripgrep)

checked 47 package(s): 3 newer, 41 up-to-date, 3 error(s)

errors:
  flaky (owner/flaky): gh api repos/owner/flaky/releases/latest failed: 404 Not Found
  …

A v-prefix on either side is normalized in the comparison (a tag v1.51.0 does NOT count as newer than 1.51.0).

Adding `meta.upstream` to a recipe¶

Hand-port recipes can declare:

meta = {
  description = "…"
  upstream = { type = "github-release" repo = "X/Y" }
}

The brew translator auto-emits meta.upstream when the source URL matches https://github.com/X/Y/releases/download/... or https://github.com/X/Y/archive/..., so most translated recipes pick this up for free.

Options¶

--check-all — required in v1; the only mode currently implemented.
--file FILE — explicit PCL file or directory; overrides the default discovery.
--scenario NAME — evaluate under scenario NAME.

Errors¶

Symptom	Cause
`error: only`--check-all`is implemented in this release` (exit 2)	You ran `punix upgrade` without `--check-all`.
`gh CLI not found on PATH`	Install `gh` (`brew install gh`) and `gh auth login`.
Per-package `gh api … failed: …`	Network error or repo doesn't exist. The rest of the report continues; check the errors footer.

punix upgrade¶