native-packages 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0f937a8788833696a7e7f71ae4a2892c9fbd5dc9da1492376155530e0fa349e6
+  data.tar.gz: 7dc4b26da615673f0639bdb54344978bc60f54386451e35286e00bb76f8228de
+SHA512:
+  metadata.gz: 6a66d883eb494ac1a0d04311fa09a844a110b88c9fd2e75df1178f4fb79e027fdd694185c15169a705a77b99a62f041e0a9f4415617ff20dc6a1b40aaf457fb5
+  data.tar.gz: a0900c282473d8b1b1b1da1855889a2279dcaa8eaddefc7abf7aaa554c6db40435f86aae1def077e189294adc3b1c142247a62fdeefeb9a34073e93abee460fc

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carmine Paolino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,119 @@
+# native-packages
+
+Build native distribution packages with [nFPM](https://nfpm.goreleaser.com/), generate distribution recipes and publish updates from one project configuration.
+
+Applications keep their build scripts, installation assets and native recipes. This gem shares the packaging and downstream repository automation, with no runtime gem dependencies.
+
+## Install and build
+
+Version 0.2 is being prepared for RubyGems publication. Until published, build and install the gem from this repository:
+
+```sh
+gem build native-packages.gemspec
+gem install ./native-packages-0.2.0.gem
+```
+
+After publication, installation is `gem install native-packages`. Install nFPM 2.47.0 separately for local use; the reusable CI workflow installs it for you. Ruby 3.2 or later is required.
+
+From an application directory:
+
+```sh
+native-packages init
+# Edit native-packages.yaml: metadata, inputs, dependencies and targets.
+native-packages doctor
+native-packages build --version 1.2.3
+```
+
+`init --interactive` offers guided setup. The default generates a Linux amd64 template, using available Cargo/Git metadata. It does not overwrite existing configuration. Applications need no Gemfile, lockfile or Ruby wrapper. Bundler remains available if preferred.
+
+## Configuration
+
+The [example](examples/native-packages.yaml) is a complete configuration for a static Linux application. A typical project contains:
+
+```text
+native-packages.yaml
+packaging/                 # native recipes, services, icons, etc. when needed
+```
+
+Use nFPM's existing metadata, contents, dependencies, scripts and format overrides under `nfpm`. Define inputs and output formats per target:
+
+```yaml
+targets:
+  linux-amd64:
+    platform: linux
+    arch: amd64
+    libc: static
+    formats: [deb, rpm, archlinux]
+    input:
+      local: dist/my-app-linux-amd64.tar.gz
+      release_asset: my-app_@VERSION@_linux_amd64.tar.gz
+```
+
+`build` creates all configured outputs. `--target ID` and `--format FORMAT` select a subset; repeat either option for several values. A missing target input fails the build.
+
+Inputs support `kind: archive` (default), `directory` or `file`. Paths resolve from the configuration directory. Targets can add `nfpm` overrides; maps merge recursively and arrays replace. `nfpm` can also reference a separate YAML file. `.yml` and `--config FILE` are supported.
+
+Linux binary targets declare `libc: glibc`, `musl` or `static`. The tool inspects ELF architecture, libc and required libraries without executing the binaries. Known DEB/RPM dependencies are inferred; additional mappings belong under `libraries`. Other formats require explicit dependencies when external libraries are linked. Runtime-loaded libraries and supported distribution baselines still need maintainer declarations and testing.
+
+`kind: data` allows packages with no executable; `kind: source` is reserved for SRPM sources/specs. Windows targets use PE architecture inspection. Input archive symlinks are currently rejected; represent installed symlinks with nFPM's `type: symlink` contents.
+
+See [configuration and commands](docs/configuration.md) for tokens, release assets, hooks, version selection and publishing, and [platform coverage](docs/platforms.md) for each format's requirements.
+
+The [all-formats example](examples/native-packages-all-formats.yaml) shows separate Linux, OpenWrt, Windows and source inputs, including MSIX identity/assets and an SRPM source/spec layout.
+
+## Release inputs and publication
+
+Build from local files before publishing an application release, or consume an existing release:
+
+```sh
+native-packages build --release v1.2.3
+native-packages publish --from dist/packages/1.2.3 --to github
+```
+
+Release mode verifies the declared binary assets against the release checksum file. Source assets outside that list may explicitly use `checksummed: false`. Local builds do not need a GitHub release or credentials. An optional target `before_build` argument array invokes the application's existing build script once; release mode skips it.
+
+Outputs include packages, prepared recipes, checksums and `build.json`. Publication verifies their hashes, configuration identity and complete target set. Partial builds can be combined with `aggregate DIR... --output DIRECTORY`. Native filenames come from nFPM.
+
+Optional `repositories` and `templates` sections replace the old separate registries. Existing `stage`, `diff`, `publish TARGET` and `status` commands support reviewed downstream updates. AUR uses PKGBUILD/`.SRCINFO`; Homebrew uses formulae/casks. Each destination has an independent ignored Git clone, with no application submodules or extra remotes. Native source repositories still apply their own validation and review.
+
+## GitHub Actions
+
+After publishing application binaries and checksums, call the reusable workflow from the same released tool version:
+
+```yaml
+packaging:
+  needs: release
+  permissions:
+    contents: write
+  uses: crmne/native-packages/.github/workflows/package.yml@v0.2.0
+  with:
+    version: ${{ github.ref_name }}
+    publish: true
+  secrets: inherit
+```
+
+This reference becomes available when v0.2.0 is tagged. Pin the corresponding commit SHA for an immutable workflow reference. With no version, the workflow validates configuration only. With a version, it installs the configured gem and nFPM, builds packages and uploads an Actions artifact. `publish: true` attaches packages to the existing release.
+
+To consume an Actions artifact instead, set `source-artifact` and, if necessary, `source-directory` (default `dist`). Its files must match the local input paths in the configuration. This workflow packages on Linux, including MSIX creation from Windows binaries; native application builds and platform-specific signing jobs can use the CLI separately.
+
+AUR publication additionally requires `PUBLISH_AUR=true`, `AUR_SSH_KEY` and `AUR_KNOWN_HOSTS`. Homebrew publication requires `PUBLISH_HOMEBREW=true` and `HOMEBREW_TAP_GITHUB_TOKEN`. Keep existing GoReleaser publishers for destinations they already own.
+
+## Migration and development
+
+```sh
+native-packages migrate --dry-run
+native-packages migrate
+```
+
+Migration combines `packaging/project.yml`, its nFPM definition and repository registry while preserving templates and existing files. Compare generated outputs before removing packaging-only Gemfiles or wrappers. App-specific Ruby generators, such as Hyprmoncfg's Nix/source-package logic, require a manual adapter; the generic migrator does not rewrite them. Existing v0.1 configurations and commands remain available. See the [legacy guide](docs/legacy.md).
+
+```sh
+bundle install
+bundle exec ruby -Ilib -e 'Dir["test/*_test.rb"].sort.each { |path| require_relative path }'
+gem build native-packages.gemspec
+ruby test/gem_install.rb native-packages-0.2.0.gem
+```
+
+Tests build real packages, inspect their payloads and exercise repository publication against local Git fixtures. CI additionally runs disposable Linux install/upgrade/remove checks, SRPM rebuilds and Windows MSIX acceptance. Runtime build manifests report installation as `not-tested`: CI fixture coverage is not a substitute for testing each application's packages.
+
+The [design document](docs/cli-design.md) records the agreed direction. [Gem release setup](docs/releasing.md) explains the RubyLLM-style token setup and GitHub release workflow.

data/docs/cli-design.md

@@ -0,0 +1,161 @@
+# Proposal: an installable CLI with one project configuration
+
+Status: accepted, 2026-09-13. Publishing was subsequently aligned with RubyLLM: GitHub release publication triggers the workflow, using `RUBYGEMS_AUTH_TOKEN`. The original Trusted Publishing proposal below is superseded by that decision. The v0.2 implementation follows this design. See the current [configuration reference](configuration.md) and [release setup](releasing.md) for the implemented interface and publication requirements. This document records the original design; it does not describe v0.1.0.
+
+The proposed interface is `gem install native-packages`, `native-packages init`, and `native-packages build`. A project normally needs one `native-packages.yaml` file. The tool should expose every nFPM packager and use the application's declared inputs to decide what to build.
+
+## Why v0.1 stops at DEB/RPM
+
+Version 0.1 extracted working automation from our applications. Its implementation still assumes Linux release archives, amd64/arm64, and DEB/RPM dependency names. These assumptions occur in `Project#binary_packages`, `Project#runtime_dependencies`, and the release-upload filename check in `Support#upload_assets`. It also requires a published GitHub release before packaging and loads configuration from several fixed paths.
+
+Those are implementation limits, not a desirable product boundary. Changing the format loop alone would still reject Windows inputs, attach incorrect dependency metadata, and reject the resulting filenames during publication.
+
+The repository already has a gemspec and an executable. The Git dependency and application Gemfiles were a distribution shortcut before RubyGems publication. They should become optional for consumers; the shared repository keeps its own development Gemfile and lockfile.
+
+## Installation and version selection
+
+After the proposed version is published:
+
+```sh
+gem install native-packages
+native-packages init
+native-packages doctor
+native-packages build --version 1.2.3
+```
+
+`gem install` supplies the `native-packages` executable through RubyGems. Application repositories need no Ruby wrapper script, Gemfile, lockfile, or vendored library. Existing Ruby projects can continue to use Bundler if they prefer its dependency resolution. [RubyGems publishing](https://guides.rubygems.org/publishing/)
+
+Use exact tool versions in the project configuration. CI reads those versions and installs them; the local CLI checks the running version and prints the matching install/invocation command when it differs. RubyGems can select an installed executable version with syntax such as `native-packages _0.2.0_ build`. Do not silently change the global installation or fall back to the latest gem. No new application lockfile is needed while the gem has no runtime gem dependencies. If dependencies are introduced, revisit the reproducibility contract rather than pretending a gem version locks its entire dependency tree.
+
+nFPM remains an external executable. RubyGems does not install that Go program as a Ruby dependency. Local users install it once using an existing supported installation method; `doctor` checks it. The shared CI installs the pinned nFPM version and only the additional tools needed by the selected targets. Avoid writing a second package manager or bundling copies of nFPM for every host into the gem.
+
+Publish the gem from this repository's release workflow using RubyGems Trusted Publishing. Configure ownership of the gem name and a pending trusted publisher for the first release, then publish tested tags. This is separate from publishing application packages. [RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/)
+
+## Commands
+
+| Command | Proposed behavior |
+| --- | --- |
+| `init` | Detect basic project metadata and write one default configuration. Print fields that still need editing. |
+| `init --interactive` | Ask for missing package identity, input locations and desired outputs, then write the same configuration. |
+| `doctor` | Check configuration, required executables and version compatibility. Report actionable missing requirements. |
+| `validate` | Check configuration and template structure without downloading artifacts, running application build commands or publishing. |
+| `build` | Use local inputs, render configured recipes and build every configured package target. |
+| `build --release v1.2.3` | Obtain the declared assets from an existing release, verify their checksums, then run the same build path. |
+| `build --target linux-amd64` | Build a named target; repeat the option to select several. |
+| `build --format apk` | Build that format across configured targets that explicitly include it. Fail if none match. |
+| `build --dry-run` | Show selected inputs, commands and outputs without running commands or downloading inputs. |
+| `publish --from dist/packages/1.2.3 --to github,aur` | Publish a previously built result to named configured destinations. |
+| `status` | Report downstream versions and pending submissions. |
+
+Keep the existing `stage`, `diff` and submission commands for maintainers who need to review native recipes before publication. Retain existing command forms during migration.
+
+`init` generates a template by default, so it also works without a terminal. Interactive prompts are optional and never run in CI. Infer metadata from Git and supported manifests only where unambiguous; never invent dependency names, credentials, publisher identities or unsupported platforms. Do not overwrite existing configuration. Offer migration when the old layout is detected.
+
+`build` means building distribution packages. It normally consumes files made by the application's existing build. An optional `before_build` command, expressed as an argument array, can call an existing script once per selected target. This lets `build` perform the complete local sequence without adding Rust, Go, CMake or cross-compilation implementations to this project. Release-download mode skips that source-build command. Other commands do not execute it.
+
+An omitted version is resolved only from an exact supported release tag at HEAD; otherwise request `--version`. `--release` supplies the version itself and conflicts with a different explicit version. Start with the current stable `vMAJOR.MINOR.PATCH` convention; prerelease publication and format-specific version conversions need a separate explicit policy.
+
+## One YAML file
+
+Use `native-packages.yaml` to match the gem and command name. Accept `.yml` as an alias and an explicit `--config PATH`; error if discovery finds both. Resolve relative paths from the configuration directory. Advanced projects can keep native templates and assets under `packaging/`.
+
+An illustrative configuration for an application with a static Linux binary:
+
+```yaml
+schema: 1
+tool:
+  version: "0.2.0" # Proposed release, not currently published.
+  nfpm: "2.47.0"
+
+nfpm:
+  name: example-app
+  description: An example desktop utility
+  maintainer: Example Maintainer <maintainer@example.org>
+  homepage: https://github.com/example/example-app
+  license: MIT
+  contents:
+    - src: "@PAYLOAD@/example-app"
+      dst: /usr/bin/example-app
+      file_info:
+        mode: 0755
+
+targets:
+  linux-amd64:
+    platform: linux
+    arch: amd64
+    libc: static
+    formats: [deb, rpm, archlinux]
+    input:
+      local: dist/example-app-linux-amd64.tar.gz
+      release_asset: example-app_@VERSION@_linux_amd64.tar.gz
+
+release:
+  repository: example/example-app
+  checksums: checksums.txt
+```
+
+Only one target is shown. Static does not imply a complete desktop application has no runtime dependencies; add its actual dependencies, assets and scripts. A second target can use the same package definition with different inputs or per-target nFPM fields.
+
+`nfpm` uses nFPM's existing keys for package metadata, contents, scripts, dependencies, overrides and signing. Avoid renaming them into our own packaging language. Target-specific `nfpm` mappings override shared mappings: maps merge recursively, lists replace in full, and scalar values replace. Resolve release version, architecture and platform once; reject conflicting declarations rather than silently overriding them. nFPM remains responsible for its format-specific semantics.
+
+The outer schema owns only tool versions, input acquisition, targets, optional build commands, templates and destinations. Use a small documented token set, extending the existing `@VERSION@`, `@PAYLOAD@` and `@ARCH@` syntax. Do not add general expression evaluation. Missing tokens fail with their configuration location.
+
+An input can be a local file, directory or archive. Release acquisition is optional and declares asset filenames plus a checksum source. Additional assets used only by recipes, such as source archives and macOS DMGs, can be declared without a binary-package target. Optional `templates` and `repositories` sections incorporate the existing template and downstream mappings; omitted sections mean there are none. A simple project needs no empty repository registry or separate nFPM file. A documented file-reference form can preserve larger configurations without making it the default.
+
+Recommend YAML for this version. A Ruby DSL would introduce another API to maintain and require executing configuration just to inspect it. Existing build scripts and native Homebrew Ruby recipes already cover the immediate need for code. Add a Ruby configuration frontend only if concrete applications cannot be represented cleanly by this model.
+
+## Wire all nFPM formats
+
+Expose all packagers supported by the pinned nFPM version. Use explicit target declarations, not a global attempt to package one archive into every format. `build` builds all configured outputs; missing or incompatible inputs fail instead of being silently skipped.
+
+The installed nFPM 2.47.0 CLI enumerates **seven** packagers, including `srpm`, which the original README's list omitted. It exposes format selection through the same `package --packager` command. [nFPM command implementation](https://github.com/goreleaser/nfpm/blob/v2.47.0/internal/cmd/package.go)
+
+| Packager | Target declaration and validation needed |
+| --- | --- |
+| `deb` | Appropriate Linux payload, dependencies and installation paths. Preserve current coverage. |
+| `rpm` | Same, using the intended RPM distribution's dependency names and baseline. |
+| `archlinux` | Arch-compatible payload and metadata. This creates a downloadable package; AUR publication continues to use PKGBUILD and `.SRCINFO`. |
+| `apk` | Payload and dependencies for the chosen Alpine target. Select musl/static inputs where appropriate; never reinterpret a glibc payload as musl merely by changing the suffix. |
+| `ipk` | Payload for an explicitly named device/distribution ABI and architecture. Do not assume that a desktop archive is suitable. |
+| `msix` | Windows payload and package layout, publisher identity, application entries and image assets. Run PE inspection instead of Linux ELF inspection. Signing uses the format's native configuration. |
+| `srpm` | Source/spec payload with a separate source target. Do not package an executable under a source-package label. Validate rebuildability through RPM tooling. |
+
+nFPM provides format-specific metadata and override fields; the shared layer should pass them through. MSIX needs Windows-specific identity and application settings. [nFPM configuration](https://nfpm.goreleaser.com/docs/configuration/)
+
+nFPM's SRPM implementation sets source-package metadata and writes the supplied contents. Our assessment is that a useful source package still requires a spec and suitable sources, with native rebuild testing. Generating that recipe remains application-owned. [nFPM RPM/SRPM implementation](https://github.com/goreleaser/nfpm/blob/v2.47.0/rpm/rpm.go)
+
+Use a small table of known formats and validation capabilities, tied to the supported nFPM version. Adding a packager should not require another full packaging implementation. New upstream formats should produce a clear unsupported-version diagnostic until their dispatch and checks are added; do not scrape human-readable help at runtime as a compatibility API.
+
+Remove hardcoded Rust target triples. Carry OS, architecture, libc/ABI and any compiler target string explicitly. Use nFPM's native architecture mapping, including format overrides. Binary inspectors must handle their supported architecture and endianness correctly and report validation coverage separately from the backend's ability to create a package. Data/source packages do not need an executable. An unimplemented inspection path cannot silently count as successful validation.
+
+Keep dependency handling modest. Preserve the existing verified DEB/RPM mappings, make inference format-aware, and allow explicit declarations for other targets. Do not invent a universal distro dependency database. Inspect the selected package contents, including bundled libraries, and document that runtime-loaded dependencies still need declarations.
+
+## Build results and publishing
+
+Let nFPM choose conventional package filenames by giving it a fresh output directory. Do not manufacture extensions such as `.archlinux` or `.srpm`. Separate target output directories prevent collisions when variants produce the same native filename.
+
+Write `dist/packages/<version>/` containing packages, rendered recipes, checksums and a machine-readable build manifest. Record the app/version, selected targets, tool versions, input hashes, configuration digest, output paths/hashes and completed validation. Generate repeatable timestamps from the release or an explicit build epoch. Reject an existing output unless the user explicitly chooses replacement.
+
+Publication reads this manifest instead of using the current DEB/RPM filename regex. Check identity, hashes, unique upload names and package ownership before uploading. Preserve upstream binary checksums. An incomplete target set cannot be published as a complete release. Partial CI jobs retain target manifests and the publish job verifies the combined set against the requested configuration.
+
+Package generation and publication remain separate commands. AUR, Homebrew and distro submissions use the existing downstream manager. No application Git remotes or submodules are needed. Existing GoReleaser publishers can continue to own their configured destinations.
+
+## CI and platforms outside nFPM
+
+The reusable workflow installs the configured gem version and packaging tools, then runs the same CLI as a maintainer. Application repositories keep a short workflow call; no Bundler bootstrap is required. Native build jobs supply local artifacts, or the packaging workflow consumes an existing release. PRs validate configuration; gem CI builds and inspects format fixtures.
+
+Support explicit target selection for separate Linux and Windows jobs, followed by one aggregation/publish job. Packaging host capabilities and the operating system of the packaged application are separate concerns. Do not promise every target can be built or tested on every host.
+
+For Homebrew, reuse existing formula/cask rendering and tap publication. macOS bundle creation, signing and notarization continue to call application-owned scripts. For Windows installers beyond MSIX and for Flatpak, invoke existing tools with their native definitions when those integrations are added. A shared command can coordinate them, but an nFPM format switch cannot replace those tools or port an application.
+
+Keep this implementation to a CLI, a configuration loader, input/build coordination, nFPM invocation and the existing downstream manager. Add shared helpers only where actual consumers repeat work; avoid a plugin framework or a new build language.
+
+## Implementation and acceptance
+
+1. Add the new configuration loader, `init`, `doctor` and `build`; support local inputs and optional release acquisition. Keep legacy commands/configuration readable.
+2. Generalize targets, output manifests, upload validation and nFPM dispatch for all seven formats. Add native configuration examples and fixtures for each.
+3. Test the built gem in an isolated install directory, outside this checkout, without Bundler or a project Gemfile. Verify `init` works in an empty directory and local `build` works without a published release or GitHub credentials.
+4. Exercise package contents and metadata for every format. Test install/remove/upgrade with native package managers in disposable environments, and rebuild an SRPM. Use Windows acceptance tests for MSIX. Track format generation and native installation coverage separately; neither a renamed archive nor an untested binary counts as platform support.
+5. Publish the new gem and matching reusable workflow. Provide `native-packages migrate --dry-run`, then an explicit migration that preserves native recipes and platform exceptions. Remove application wrappers and packaging-only Gemfiles after equivalent outputs are verified. Keep existing Git pins working during transition.
+
+The proposed decisions are: one YAML file by default, an installable gem, optional Bundler, package-oriented `init`/`build`/`publish`, all nFPM formats exposed with declared targets, and existing native tools for the remaining platforms. The exact field names and release number can change during review; none of these commands are a promise about v0.1.0.

data/docs/configuration.md

@@ -0,0 +1,61 @@
+# Configuration reference
+
+`native-packages.yaml` (or `.yml`) is discovered in the working directory. `--config FILE` selects a different file; relative paths resolve from that file's directory. The schema uses data only: no Ruby evaluation or general template expressions.
+
+| Field | Purpose |
+| --- | --- |
+| `schema` | Configuration schema version; currently `1`. |
+| `tool.version` | Exact native-packages gem version. A mismatch reports the install/version-selection command. |
+| `tool.nfpm` | Supported nFPM version; currently `2.47.0`. |
+| `nfpm` | Native nFPM configuration mapping, or a relative YAML filename. Name, contents, dependencies, hooks and signing use nFPM's schema. |
+| `targets` | Named platform/architecture/input/format combinations. May be empty for recipe-only projects. |
+| `release` | Optional GitHub `repository` and checksum filename (`checksums.txt` by default). |
+| `assets` | Additional recipe assets, keyed by uppercase identifiers. |
+| `templates` | Output recipe paths mapped to input template paths. |
+| `repositories` | The existing downstream registry entries, without the old `version`/`repositories` wrapper. Defaults to empty. |
+| `libraries` | Additional shared-library-to-package dependency mappings, keyed by SONAME then format. |
+| `revisions` | Per-version/per-template package revisions, preserving the v0.1 format. |
+| `version_file`, `version_section` | Existing Cargo manifest version checks used by `check-version`. |
+
+## Targets
+
+A target declares `platform` (`linux` or `windows`), `arch` (nFPM/Go architecture name), `formats`, and `input`. `kind` defaults to `binary`; `data` permits packages without executables, and `source` is required for a separate SRPM target. Linux binaries declare `libc` as `glibc`, `musl` or `static`. IPK also requires an `abi` label identifying the device/distribution baseline.
+
+A target's optional `nfpm` mapping overrides the shared definition. Maps merge recursively; lists replace in full. Package name, version, platform and architecture must not conflict with their canonical declarations. Format-specific architecture overrides belong in the corresponding nFPM section. Distinct target inputs must be supplied for incompatible ABIs or platforms.
+
+`input.local` is a path. `input.release_asset` is a filename; `input.url` can override its GitHub release URL. `input.kind` is `archive` (default), `directory` or `file`. Binary release inputs always require a matching release checksum. Archive extraction and Linux inspection require `bsdtar` and `readelf`, respectively.
+
+`before_build` is an argument array, for example:
+
+```yaml
+before_build: [./scripts/build-linux.sh, '@ARCH@']
+```
+
+It runs once per selected target in the configuration directory, before copying local inputs. `NATIVE_PACKAGES_TARGET` and `NATIVE_PACKAGES_VERSION` are also set. It is skipped in release mode and never executed by `validate`, `doctor` or a dry run. A shell script remains responsible for complex build operations.
+
+`after_package` is an optional argument array invoked once per generated package, before output hashes are recorded. It additionally receives `@PACKAGE@` and `@FORMAT@`. Use it for existing native signing tools, for example a Windows SDK SignTool script. It runs in local and release mode and must preserve the output filename and file set. The MSIX acceptance test uses SignTool because Windows rejected the signature produced by nFPM 2.47.0's built-in signer in that test.
+
+## Tokens and additional assets
+
+Strings can contain `@NAME@`, `@VERSION@`, `@TAG@`, `@DATE@`, `@SOURCE_DATE_EPOCH@`, `@ROOT@`, `@UPSTREAM@` and `@GIT_VERSION@`. Target definitions additionally receive `@ARCH@`, `@PLATFORM@`, `@TARGET_ID@`, `@TARGET@` and `@PAYLOAD@`. `TARGET` is the explicit `compiler_target` or, if omitted, the target ID. `PAYLOAD` is the extracted/copied input directory. Recipe templates also receive `@PKGREL@`.
+
+Additional `assets` retain the existing `file`, optional `url`, and `checksummed` fields. Local builds require `local` paths for these assets. Release builds download and hash them, checking the published checksum unless `checksummed: false` is explicitly set for a source asset. Each contributes `@KEY_FILE@`, `@KEY_URL@` and `@KEY_SHA256@` to recipe rendering. Unresolved tokens fail validation/build.
+
+Omitting `--version` requires an exact stable release tag at HEAD. `--release` supplies the version and conflicts with a different `--version`. Stable versions currently use `vMAJOR.MINOR.PATCH`; prerelease tags are rejected. Build timestamps use `SOURCE_DATE_EPOCH`, otherwise the relevant Git commit timestamp, otherwise the current time for projects without Git metadata. Supply `SOURCE_DATE_EPOCH` for repeatable builds outside Git.
+
+## Output and publication
+
+`build` writes a fresh `dist/packages/<version>` directory, or the explicit `--output` path. It refuses an existing output. Each target/format gets its own directory and nFPM chooses the native filename. `build.json` records the configuration digest, targets, input/output hashes and validation performed. It does not claim the application was installed or tested on each distro.
+
+`publish --from DIRECTORY --to github,aur` verifies the entire configured target set and file hashes before publishing. `github` means release assets; other names select a configured downstream destination or group. GitHub asset filenames must be unique across variants. Upstream `checksums.txt` is preserved and package upload checksums use `packaging-checksums.txt`.
+
+For builds split across CI jobs:
+
+```sh
+native-packages build --version 1.2.3 --target linux-amd64 --output dist/linux
+native-packages build --version 1.2.3 --target windows-amd64 --output dist/windows
+native-packages aggregate dist/linux dist/windows --output dist/complete
+native-packages publish --from dist/complete --to github
+```
+
+Each build must use the same configuration, release version and timestamp. Aggregate rejects duplicate target/format outputs, conflicting recipe files and incomplete sets. Publishing recipes can still use the existing reviewed sequence: `stage TARGET DIRECTORY/recipes`, `diff TARGET`, then `publish TARGET --body-file FILE` where required by a submission destination.

data/docs/legacy.md

@@ -0,0 +1,123 @@
+# Legacy v0.1 configuration and commands
+
+Package existing Linux release binaries with [nFPM](https://nfpm.goreleaser.com/), generate native distribution recipes, and prepare updates in downstream repositories.
+
+Applications keep their own configuration and templates. This repository holds the common Ruby code, tests and reusable GitHub Actions workflow. There are no runtime gem dependencies and no copied engine files in application repositories.
+
+## Boundaries
+
+| Layer | Responsibility |
+| --- | --- |
+| Application build jobs | Compile for each OS and architecture; create compatible binaries, macOS bundles and Windows installers; sign and notarize where required. |
+| nFPM | Turn a set of built files and package metadata into native package files. |
+| native-packages | Verify release checksums, render recipes, check Linux ELF dependencies, invoke nFPM, attach packaging assets, and stage or publish downstream updates. |
+| Distribution infrastructure | Build and review submitted recipes, host package indexes, and make packages available to users. |
+
+**Version 0.1 creates DEB and RPM files for Linux amd64 and arm64.** nFPM itself also supports Arch Linux, Alpine APK, IPK and MSIX, but those output paths are not wired into this release of the shared CLI. An APK needs suitable binaries, usually built against musl; converting a glibc binary into another package format does not make it compatible. [nFPM configuration](https://nfpm.goreleaser.com/docs/configuration/)
+
+Native AUR, Homebrew, Nix, Gentoo, Alpine, Void and other recipes can be supplied as templates. AUR uses `PKGBUILD` and `.SRCINFO`; Homebrew uses formulae or casks. These are distinct from downloadable binary package files. [AUR](https://wiki.archlinux.org/title/Arch_User_Repository), [Homebrew](https://docs.brew.sh/How-to-Create-and-Maintain-a-Tap)
+
+Flatpak needs its own runtime, SDK, modules and sandbox permissions. macOS needs application-specific bundle contents and signing settings. Windows needs an appropriate installer and publishing manifest. Keep those native definitions with the app and use their existing tools. This project does not port applications, replace those tools, or claim every application supports every platform. See [platform coverage](platforms.md).
+
+## Add an application
+
+Use the files in [examples](../examples/packaging/project.yml) as a starting point:
+
+```text
+packaging/
+  Gemfile                 # shared tool dependency
+  Gemfile.lock            # exact dependency revision
+  project.yml             # release assets and template mappings
+  nfpm.yml                # nFPM file mappings and target dependencies
+  repositories.yml        # registry of downstream destinations
+  arch/.../PKGBUILD.in     # only the native recipes this app needs
+```
+
+Add `packaging/Gemfile`:
+
+```ruby
+source "https://rubygems.org"
+gem "native-packages", git: "https://github.com/crmne/native-packages.git", tag: "v0.1.0"
+```
+
+From the application root:
+
+```sh
+export BUNDLE_GEMFILE="$PWD/packaging/Gemfile"
+bundle install
+bundle exec native-packages validate
+bundle exec native-packages prepare 1.2.3
+bundle exec native-packages artifacts dist/packaging/1.2.3
+```
+
+Commit the Gemfile and lockfile. Bundler records the exact Git revision. No RubyGems publication is required. Run `bundle update native-packages` after changing the selected tool version.
+
+Requirements: Ruby 3.2 or later (CI tests 3.4 and 4.0), Bundler, Git, curl, GNU tar, xz, bsdtar, readelf, and nFPM 2.47.0. AUR metadata generation additionally needs `makepkg` or accessible Docker. Publishing needs the destination credentials and GitHub CLI where applicable. Packaging currently runs on Linux; native macOS and Windows builds stay in their own jobs.
+
+## Configuration
+
+`project.yml` declares the name, source repository, optional separate `release_repository`, release assets, templates and Linux binary packaging configuration. Stable tags use `vMAJOR.MINOR.PATCH`. `checksums.txt` must contain SHA256 entries for every binary asset. Source archives not present in that list can explicitly use `checksummed: false`; their computed hashes still enter generated recipes.
+
+Template values use `@VERSION@`, `@TAG@`, `@NAME@`, `@UPSTREAM@`, `@DATE@`, `@SOURCE_DATE_EPOCH@`, `@GIT_VERSION@`, and per-asset `@KEY_FILE@`, `@KEY_URL@`, `@KEY_SHA256@`. nFPM templates additionally receive `@ROOT@`, `@PAYLOAD@`, `@ARCH@` and `@TARGET@`. Values in `nfpm.yml` otherwise use nFPM's own schema. `binary.nfpm` may reference this file or contain the configuration directly.
+
+Include `repositories.yml` even when no downstream publication is needed; use `version: 1` and `repositories: {}` for an empty registry.
+
+Files, icons, desktop entries, services, runtime dependencies and platform exceptions remain explicit. ELF inspection checks architecture and raises a glibc dependency floor when needed. It cannot discover every library loaded dynamically or prove compatibility with every distro. Additional shared-library mappings can be supplied under `binary.libraries`; verify dependency names against the target distributions.
+
+Optional `version_file` and `version_section` fields check the package or workspace version in a Cargo manifest with `check-version TAG`.
+
+## GitHub Actions
+
+After the application's stable release job has uploaded binaries and `checksums.txt`, call:
+
+```yaml
+packaging:
+  needs: release
+  if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-')
+  permissions:
+    contents: write
+  uses: crmne/native-packages/.github/workflows/package.yml@v0.1.0
+  with:
+    version: ${{ github.ref_name }}
+    publish: true
+  secrets: inherit
+```
+
+Use the same tool release as the Gemfile. Pin the workflow to the corresponding commit SHA for an immutable reference. A separate PR job can call the workflow with `publish: false` and no version; it validates local recipes without requiring an existing release. The shared library's tests run in this repository's CI.
+
+With a version supplied, the workflow verifies inputs, builds DEB/RPM files and a recipe archive, and uploads GitHub Actions artifacts. With `publish: true`, it also attaches those package assets and `packaging-checksums.txt` to the existing release. It preserves the original release `checksums.txt`.
+
+Optional downstream publication:
+
+- AUR: set `PUBLISH_AUR=true`, `AUR_SSH_KEY` and `AUR_KNOWN_HOSTS`; configure an `aur` group in the registry.
+- Homebrew: set `PUBLISH_HOMEBREW=true` and `HOMEBREW_TAP_GITHUB_TOKEN`; configure the `homebrew` destination.
+
+Publication is disabled unless requested. Test builds and recipes before enabling a destination. Credentials remain in the application repository's secrets. Workflow failure can be retried without intentionally creating duplicate submissions.
+
+If an application already uses GoReleaser's [AUR](https://goreleaser.com/customization/publish/aur/) or [Homebrew](https://goreleaser.com/customization/publish/homebrew_casks/) publisher, continue using it for that destination. Do not configure both publishers for the same package. Use the repository helper for destinations and native recipes those integrations do not cover.
+
+## Downstream repositories
+
+```sh
+bundle exec native-packages repositories
+bundle exec native-packages stage aur dist/packaging/1.2.3
+bundle exec native-packages diff aur
+bundle exec native-packages publish aur
+bundle exec native-packages status --json
+```
+
+Each destination has its own ignored clone under `.cache/packaging/repos`. The source repository needs neither submodules nor additional Git remotes. Mapping exact package paths preserves downstream history and unrelated files.
+
+The registry supports direct Git pushes, GitHub pull requests, GitLab merge requests and manual destinations. Fork-based submissions require the appropriate fork and a reviewed description passed as `publish TARGET --body-file FILE`. Staging can reuse an existing open request. Dirty changes outside the prepared files, unexpected remote advances and downgrades are rejected. Gentoo updates preserve older ebuilds and Manifest entries. See the [registry example](../examples/packaging/repositories.yml).
+
+Upstream review and acceptance are separate from successful submission. This tool does not host APT/DNF repositories or configure signing keys for you.
+
+## Development
+
+```sh
+bundle install
+bundle exec ruby -Ilib -e 'Dir["test/*_test.rb"].sort.each { |path| require_relative path }'
+gem build native-packages.gemspec
+```
+
+Tests use temporary directories and local Git repositories. With nFPM, a C compiler, readelf and bsdtar available, the integration test creates real DEB/RPM packages and verifies their payloads. It does not install them on the host or publish anything externally.

data/docs/platforms.md

@@ -0,0 +1,32 @@
+# Platform and distribution coverage
+
+All seven nFPM 2.47.0 packagers are exposed by the v0.2 CLI. Each target explicitly declares suitable inputs; enabling an output format does not port an application or guarantee acceptance by a distribution.
+
+| Output/destination | Shared implementation | Application responsibility |
+| --- | --- | --- |
+| DEB | nFPM, ELF inspection, known dependency inference, release upload | Supported distro baseline, runtime-loaded libraries, services/assets and installation testing |
+| RPM | Same, with RPM dependency names | Distribution-specific dependencies and compatibility |
+| Arch package | nFPM `archlinux`, native filename, ELF inspection | Arch-compatible files and explicit dependencies |
+| Alpine APK | nFPM `apk`, ELF/libc checks | Suitable musl/static inputs and Alpine dependencies |
+| IPK | nFPM `ipk`, ELF checks, explicit ABI label | Device/distribution ABI, architecture and dependencies |
+| MSIX | nFPM `msix`, PE architecture checks, `after_package` hook for native signing | Windows executables/DLLs, application identity, assets, capabilities and signing certificate |
+| SRPM | nFPM `srpm`, source/spec input validation | A correct spec and sources, native rebuild testing |
+| AUR | Template rendering, `.SRCINFO`, staged Git publication | Native PKGBUILD source/bin/git variants and build checks |
+| Homebrew | Hash/render supplied formulae or casks and publish a tap | macOS bundles, signing/notarization, native recipe logic |
+| Nixpkgs/Gentoo/Void and similar repositories | Template rendering and configured Git/PR/MR publication | Native recipes, dependency hashes, distro checks and review |
+| Flatpak | No build/publication adapter yet | Use flatpak-builder and native manifests/runtime/sandbox settings |
+| Other Windows installers | No installer adapter beyond MSIX | Existing Inno Setup/NSIS/WiX and WinGet/Scoop integrations |
+
+The IPK acceptance fixture targets OpenWrt 24.10.8. OpenWrt 25.12 switched to APK, so IPK is not the package format for every OpenWrt release. [OpenWrt 25.12 release notes](https://openwrt.org/releases/25.12/notes-25.12.0)
+
+nFPM ends at constructing the package file, including its supported signing operations. It does not compile the application or host package indexes. [nFPM configuration](https://nfpm.goreleaser.com/docs/configuration/)
+
+The Windows acceptance test uses Windows SDK SignTool through `after_package`. Windows rejected nFPM 2.47.0's built-in signature with `0x80096010` in the initial acceptance run; do not assume its signing configuration alone produces a Windows-installable result.
+
+The CLI uses known ELF machine/class/endianness mappings and PE machine mappings. Unsupported inspection architectures fail explicitly. Data and source targets do not require an executable. The small DEB/RPM dependency table can be extended in configuration; other formats require explicit runtime dependencies. These checks do not detect every dynamically loaded library or establish compatibility with every version of a distribution.
+
+CI builds fixtures in every format and defines native Linux install/upgrade/remove checks, an SRPM rebuild and a signed MSIX installation on Windows. A build manifest reports `installation: not-tested` unless such testing was actually performed for that application output. Fixture coverage is separate from app-specific validation.
+
+The [acceptance run for v0.2 development](https://github.com/crmne/native-packages/actions/runs/34748247545) passed on Debian trixie, Fedora 41, Arch's base image, Alpine 3.24.0, OpenWrt 24.10.8 and the GitHub Windows runner. Linux binary tests use a small static executable; the SRPM rebuilds its C source, and the Windows package contains a compiled Windows executable. These fixtures test package construction and lifecycle, not the compatibility of every application's GUI or device integrations.
+
+Version 0.1 and its pinned workflow retain their DEB/RPM behavior. The new formats are enabled through the v0.2 single-file configuration and `build` command. Existing v0.1 application configurations do not silently gain more output formats.

data/docs/releasing.md

@@ -0,0 +1,33 @@
+# Releasing the native-packages gem
+
+This repository follows RubyLLM's publishing convention: publishing a GitHub release starts gem publication. Branch and tag pushes run checks without publishing a gem.
+
+## Authentication
+
+Configure the repository secret `RUBYGEMS_AUTH_TOKEN`, using an existing RubyGems token with permission to push `native-packages`. GitHub passes it to RubyGems through `GEM_HOST_API_KEY`. GitHub Packages uses the workflow's built-in GitHub token.
+
+Repository secrets are scoped to their repository. RubyLLM's existing secret does not automatically become available here, and GitHub cannot reveal its value for copying. Use the original token from your credential store or a new appropriately scoped token. A pending trusted publisher is not required for this method.
+
+The secret can be set interactively without putting it in a shell command or chat:
+
+```sh
+gh secret set RUBYGEMS_AUTH_TOKEN --repo crmne/native-packages
+```
+
+[RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) is an alternative if the project adopts OIDC later; it is not the current release workflow.
+
+## Release procedure
+
+Update the gemspec, `NativePackages::VERSION`, example/version references and changelog, then update the development lockfile. Run tests and the isolated gem-install check. Commit and push the reviewed change to `main` and prepare release notes in a file.
+
+Create a GitHub release for that commit:
+
+```sh
+gh release create v0.2.0 --target main --title 'native-packages 0.2.0' --notes-file release-notes.md
+```
+
+Adding `--draft` permits review before publication and does not trigger the publisher. The tag must match the exact gem version and point to a commit on `main`. Set `--prerelease` only for a prerelease gem version.
+
+The release workflow verifies the tag, tested commit and prerelease setting, then runs the test workflow, including native package acceptance. It downloads the tested gem from the Ruby 4.0 job, publishes it to RubyGems and GitHub Packages, and attaches it to the GitHub release. It does not rebuild a different artifact after the tests.
+
+If authentication is missing, leave the tested gem and release draft available until the secret is configured. Failed release jobs can be rerun after configuration; already-published gem versions are not overwritten. Never move an existing release tag to retry publication.