Adopt safelibs/port-template hook-script CI contract

Replace the auto-generated build-debs.yml with the hook-script contract
from safelibs/port-template. The workflow runs a fixed sequence under
scripts/: install-build-deps, check-layout, build-debs, run-upstream-tests,
run-port-tests, run-validation-tests; uploads dist/*.deb; publishes a
build-<short-sha> GitHub release.

scripts/install-build-deps.sh and scripts/build-debs.sh are port-specific
and translate this port's entry from apt/repositories.yml
port_build_overrides into bash. The remaining hooks are template defaults.

See AGENTS.md for the full contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: zardus

.gitattributes

@@ -0,0 +1,5 @@
+*.sh text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.env text eol=lf
+.github/workflows/*.yml text eol=lf

.github/workflows/build-debs.yml

@@ -0,0 +1,118 @@
+name: ci-release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  test-build-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Print tool versions
+        run: |
+          set -euo pipefail
+          bash --version
+          git --version
+          python3 --version
+          dpkg --version
+          dpkg-deb --version
+
+      - name: Install build dependencies
+        run: bash scripts/install-build-deps.sh
+
+      - name: Check repository layout
+        run: bash scripts/check-layout.sh
+
+      - name: Build .deb artifacts
+        env:
+          SAFELIBS_COMMIT_SHA: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+          rm -rf build dist
+          bash scripts/build-debs.sh
+
+      - name: Run upstream tests
+        env:
+          SAFELIBS_COMMIT_SHA: ${{ github.sha }}
+        run: bash scripts/run-upstream-tests.sh
+
+      - name: Run port tests
+        env:
+          SAFELIBS_COMMIT_SHA: ${{ github.sha }}
+        run: bash scripts/run-port-tests.sh
+
+      - name: Run validation tests
+        env:
+          SAFELIBS_COMMIT_SHA: ${{ github.sha }}
+        run: bash scripts/run-validation-tests.sh
+
+      - name: Collect built artifacts
+        id: artifact
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          mapfile -t debs < <(find dist -type f -name '*.deb' -print | sort)
+          if (( ${#debs[@]} == 0 )); then
+            printf 'No .deb files were produced under dist/.\n' >&2
+            exit 1
+          fi
+          {
+            printf 'count=%d\n' "${#debs[@]}"
+            printf 'paths<<EOF\n'
+            printf '%s\n' "${debs[@]}"
+            printf 'EOF\n'
+          } >> "$GITHUB_OUTPUT"
+          printf 'Built %d .deb file(s):\n' "${#debs[@]}"
+          printf '  %s\n' "${debs[@]}"
+
+      - name: Upload Debian artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: debs-${{ github.run_id }}
+          path: dist/*.deb
+          if-no-files-found: error
+
+      - name: Publish build release
+        if: github.event_name == 'push'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          DEB_PATHS: ${{ steps.artifact.outputs.paths }}
+        run: |
+          set -euo pipefail
+
+          short_sha="${GITHUB_SHA:0:12}"
+          tag="build-${short_sha}"
+
+          mapfile -t deb_files <<< "$DEB_PATHS"
+
+          notes_file="$(mktemp)"
+          {
+            printf 'Commit SHA: %s\n\n' "$GITHUB_SHA"
+            printf 'Attached .deb file(s) were produced by `scripts/build-debs.sh`.\n'
+          } > "$notes_file"
+
+          if gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release upload "$tag" "${deb_files[@]}" --repo "$GITHUB_REPOSITORY" --clobber
+          else
+            gh release create "$tag" "${deb_files[@]}" \
+              --repo "$GITHUB_REPOSITORY" \
+              --target "$GITHUB_SHA" \
+              --title "Safe library debs for ${short_sha}" \
+              --notes-file "$notes_file"
+          fi
+
+          rm -f "$notes_file"

.github/workflows/ci-release.yml

@@ -0,0 +1,8 @@
+/.work/
+/build/
+/dist/
+*.deb
+*.ddeb
+*.buildinfo
+*.changes
+*.log

.gitignore

@@ -0,0 +1,125 @@
+# AGENTS.md
+
+Canonical contract for `safelibs/port-template` and every `safelibs/port-*` repository created from it. Read this before adding a new port, modifying a script under `scripts/`, or editing the workflow file.
+
+## Why This Document Exists
+
+Earlier versions of the template defined CI as a fixed sequence of inline workflow steps. Each port that diverged from the default needed a per-port workflow override, and a separate generator in `safelibs/apt` rendered those overrides from a central config. That bifurcation made it brittle to evolve either side.
+
+The current shape moves the divergence into hook scripts under `scripts/`. The workflow runs a fixed sequence of those hooks. Ports own their own hook contents; the template ships sensible defaults. There is no generator and no central config — each port is self-describing.
+
+## CI Pipeline
+
+`.github/workflows/ci-release.yml` runs the following sequence on every push to `main` and every manual `workflow_dispatch`:
+
+| # | Step | Script | Template default |
+| - | ---- | ------ | ---------------- |
+| 1 | Install build dependencies | `scripts/install-build-deps.sh` | No-op |
+| 2 | Check repository layout | `scripts/check-layout.sh` | Lint required files / executable bits |
+| 3 | Build .deb artifacts | `scripts/build-debs.sh` | Reference build from `packaging/package.env` + `safe/` |
+| 4 | Run upstream tests | `scripts/run-upstream-tests.sh` | Run every `*.sh` under `tests/upstream/` |
+| 5 | Run port tests | `scripts/run-port-tests.sh` | Run every `*.sh` under `tests/port/` |
+| 6 | Run validation tests | `scripts/run-validation-tests.sh` | Clone `safelibs/validator`, run `port-04-test` mode against `dist/*.deb` |
+| 7 | Upload `dist/*.deb` | (workflow) | One GitHub Actions artifact per run |
+| 8 | Publish release | (workflow) | `build-<short-sha>` GitHub Release with every `dist/*.deb` |
+
+Steps 1–6 are hooks. Steps 7–8 are workflow-owned and ports do not customize them.
+
+## Script Contracts
+
+Each hook script is invoked with `bash <script>` from the repository root. `set -euo pipefail` is the convention. Scripts must succeed (exit 0) on the happy path; non-zero is a CI failure.
+
+### `scripts/install-build-deps.sh`
+
+Install everything the build and tests need that is not preinstalled on `ubuntu-latest`:
+
+- apt packages (compilers, dev libraries, packaging tools)
+- language toolchains (rustup, cargo, custom Python venvs)
+- any other system-level setup
+
+May invoke `sudo`. Must be idempotent — reruns on a warm runner must succeed. Template default is a no-op because the reference build only needs `dpkg-deb`, which is preinstalled.
+
+### `scripts/check-layout.sh`
+
+Lint the repository against the template contract: required files exist, scripts are executable, JSON inventories parse, `.gitattributes` carries the expected entries, and `packaging/package.env` is well-formed. A port can extend this with port-specific invariants but must keep the baseline checks.
+
+### `scripts/build-debs.sh`
+
+Produce one or more Debian package files under `dist/`. There is no upper bound on the number of `.deb` files — most ports emit a handful (runtime, dev, tools, docs).
+
+The reference implementation copies `safe/` into `DEB_INSTALL_PREFIX` from `packaging/package.env` and emits a single `.deb` via `dpkg-deb --build`. Real ports usually replace this with `dpkg-buildpackage -us -uc -b` rooted in `safe/debian/`, or with a port-owned build script (`bash safe/scripts/build-deb.sh`, `cargo run -p xtask -- package-deb`, etc.).
+
+`SAFELIBS_COMMIT_SHA` is set in CI; a build script that stamps versions should consume it via that variable.
+
+### `scripts/run-upstream-tests.sh`
+
+Run the upstream library's regression suite against the just-built safe `.deb`s. The name was chosen to be unambiguous: it runs *upstream's* suite, not tests of upstream's behavior. The intent is to prove the safe implementation is API/ABI-compatible with what real consumers of the upstream library expect.
+
+The template default scans `tests/upstream/*.sh`. A real port typically replaces this with a script that installs `dist/*.deb` into a chroot or container and invokes the upstream test harness via `make check`, `meson test`, or similar.
+
+This script may need the artifacts produced by `build-debs.sh`. CI runs it after the build; local invocations must run the build first.
+
+### `scripts/run-port-tests.sh`
+
+Run port-authored tests for the safe implementation: unit tests, ABI checks, fuzzing harnesses, differential tests against upstream. The template default scans `tests/port/*.sh`. Ports replace it with whatever framework fits their language and toolchain.
+
+### `scripts/run-validation-tests.sh`
+
+Run the [safelibs/validator](https://github.com/safelibs/validator) test matrix in `port-04-test` mode against `dist/*.deb`.
+
+Inputs (mostly read from `packaging/package.env`):
+
+- `SAFELIBS_LIBRARY` — must match a `name:` entry in the validator's `repositories.yml`.
+- `dist/*.deb` — produced by the build hook.
+- `SAFELIBS_COMMIT_SHA` — used as the synthetic release tag.
+
+Optional environment overrides:
+
+- `SAFELIBS_VALIDATOR_DIR` — path to an existing validator checkout. When unset, the script clones `https://github.com/safelibs/validator` into `.work/validator`.
+- `SAFELIBS_VALIDATOR_REF` — git ref to clone (default `main`).
+- `SAFELIBS_VALIDATOR_REPO` — git remote (default `https://github.com/safelibs/validator`).
+- `SAFELIBS_RECORD_CASTS` — non-empty enables `--record-casts`.
+
+Behavior:
+
+1. Reads canonical `apt_packages` for `SAFELIBS_LIBRARY` from the validator manifest.
+2. Inspects every `dist/*.deb`, matching them by `dpkg-deb --field Package` against the canonical list. Non-canonical extras are ignored. Canonical packages with no matching deb become `unported_original_packages`.
+3. Synthesizes a `port-04-test` deb lock JSON file with the matching debs, sha256s, sizes, and the synthesized `release_tag = build-<commit[:12]>`.
+4. Lays out `<override-deb-root>/<library>/<filename>.deb`.
+5. Invokes `bash <validator>/test.sh --library <SAFELIBS_LIBRARY> --mode port-04-test --override-deb-root ... --port-deb-lock ... --artifact-root ...`.
+
+Soft skip: a library that has no entry in the validator manifest (the template itself, ports still being authored) returns a skip and the script exits 0. This is the only acceptable success without a real validator run.
+
+Hard failures: missing `dist/*.deb`, no canonical packages matched, mismatch between dist debs and canonical packages, validator clone failure, validator matrix failure.
+
+## Repository Layout
+
+Required directories: `original/`, `safe/`, `packaging/`, `docs/`, `tests/upstream/`, `tests/port/`, `scripts/`.
+
+Required files: `.github/workflows/ci-release.yml`, `.gitattributes`, `README.md`, `AGENTS.md`, `CLAUDE.md`, `all_cves.json`, `dependents.json`, `relevant_cves.json`, `docs/PORTING.md`, `docs/PUBLISHING.md`, `packaging/package.env`.
+
+Required executable scripts: `scripts/build-debs.sh`, `scripts/check-layout.sh`, `scripts/install-build-deps.sh`, `scripts/run-port-tests.sh`, `scripts/run-tests.sh`, `scripts/run-upstream-tests.sh`, `scripts/run-validation-tests.sh`.
+
+`scripts/check-layout.sh` is the source of truth for the layout. When you change required files or scripts, update it in the same commit.
+
+## `packaging/package.env`
+
+The reference build script consumes this file. Required fields:
+
+- `SAFELIBS_LIBRARY` — validator manifest identifier and `safelibs/port-<library>` suffix.
+- `DEB_PACKAGE`, `DEB_VERSION`, `DEB_ARCHITECTURE`, `DEB_MAINTAINER`, `DEB_SECTION`, `DEB_PRIORITY`, `DEB_DESCRIPTION`, `DEB_INSTALL_PREFIX`, `DEB_DEPENDS` — Debian package metadata.
+
+Ports that override `build-debs.sh` may leave the `DEB_*` fields at their template defaults but must still set a real `SAFELIBS_LIBRARY` for the validator hook.
+
+## When To Edit What
+
+- **Adding/changing a port-specific build step:** edit the relevant hook script in your port repo. Do not edit the workflow file.
+- **Changing the workflow shape (new step order, new global env, new artifact policy):** edit the template's `.github/workflows/ci-release.yml` and the corresponding section in this file. Sync changes back into `safelibs/port-*` repos by hand or by re-templating.
+- **Adding a new required file or directory:** update `scripts/check-layout.sh`, this file, and `README.md` in the same commit.
+- **Renaming a hook script:** update `scripts/check-layout.sh`, `.github/workflows/ci-release.yml`, this file, `README.md`, `docs/PORTING.md`, and `docs/PUBLISHING.md` in the same commit.
+
+## Non-Goals
+
+- The template is **not** a generator. There is no central config that produces per-port workflows. Every port owns its scripts.
+- The template is **not** a runtime library. It only defines layout and CI shape.
+- The template does **not** support cross-port dependencies. A port hook may not assume another port has already run.

AGENTS.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+See [AGENTS.md](AGENTS.md) for the canonical contract that governs this repository: the CI hook sequence, what each `scripts/*.sh` must do, the required layout, and when to edit which files. Both human and agent contributors should treat AGENTS.md as the source of truth.