veragem 0.1.0 → 0.2.0

data/sig/veragem.rbs

@@ -4,25 +4,73 @@ module Veragem
   class Error < Bundler::PluginError
   end
 
-  def self.run: (Array[String] argv, ?dir: String) -> String
+  def self.run: (Array[String] argv, ?dir: String, ?input: Questions::_Input) -> String
 
   module Name
     PATTERN: Regexp
+    RESERVED: Regexp
+    LIBRARIES: Array[String]
     PROBE: String
 
+    self.@probed: Hash[[String, String, Array[String]], Array[String]]
+
     def self.modules: (String name) -> Array[String]
+    def self.path: (String name) -> String
+    def self.underscored: (String name) -> String
     def self.check: (String name) -> String
+    private def self.check_paths: (String name) -> void
     def self.check_modules: (String name) -> void
-    def self.check_shadowing: (String name, String shadowed, String found) -> void
-    def self.check_defined: (String name, Array[[String, String?]] defined, String? innermost) -> void
-    def self.library_of: (String name) -> String
-    def self.nestings_of: (String name) -> Array[String]
     def self.probe: (String library, String path, Array[String] nestings) -> Array[String]
+    private def self.answers: (String library, String path, Array[String] nestings) -> Array[String]
+    private def self.unchecked: (Array[String] nestings, String why) -> bot
+    private def self.check_shadowing: (String name, String shadowed, String found) -> void
+    private def self.check_defined: (String name, Array[[String, String?]] defined, String? innermost) -> void
+    private def self.library_of: (String name) -> String
+    private def self.nestings_of: (String name) -> Array[String]
+  end
+
+  module Citation
+    KEYS: Array[Symbol]
+    ORCID: Regexp
+    ORCID_BLOCKS: Array[Range[Integer]]
+
+    def self.cited?: (Hash[Symbol, String | bool | nil] values) -> bool
+    def self.check_values: (Hash[Symbol, String | bool | nil] values, bool citation) -> void
+    def self.check_name: (String name, bool citation) -> void
+    def self.check: (Symbol key, String value) { (String field, String text) -> String } -> String
+    def self.default: (Symbol key, Hash[Symbol, String | bool | nil] values) -> String?
+    private def self.names: (String field, String names) -> String
+    private def self.keywords: (String value) { (String keyword) -> String } -> Array[String]
+    private def self.orcid: (String value) -> String
+    private def self.valid?: (String digits) -> bool
+  end
+
+  module License
+    SPDX: Hash[String, Array[String]]
+    CHOICES: String
+
+    def self.check: (String value) -> String
+  end
+
+  module Summary
+    TAG: Regexp
+    ANNOTATION: Regexp
+    MAGIC: Regexp
+    MARKDOWN: Regexp
+    DASH: Regexp
+
+    def self.check: (String summary) -> String
+    private def self.refusal: (String summary) -> String?
+    private def self.left_open?: (String summary) -> bool
+    private def self.prose: (String summary) -> String
+    private def self.annotation?: (String summary) -> bool
   end
 
   class Project
     GITHUB: Regexp
-    LICENSES: Hash[String, Array[String]]
+    FIELDS: Hash[Symbol, String]
+    MARKUP: Regexp
+    OPTIONAL: Hash[Symbol, String]
 
     attr_reader name: String
     attr_reader author: String
@@ -31,49 +79,129 @@ module Veragem
     attr_reader summary: String
     attr_reader license: String
     attr_reader exe: bool
+    attr_reader citation: bool
+    attr_reader given_names: String?
+    attr_reader family_names: String?
+    attr_reader alias_name: String?
+    attr_reader orcid: String?
+    attr_reader keywords: Array[String]?
 
-    def initialize: (String name, Hash[Symbol, untyped] values) -> void
+    # each key's own type, which no Hash type has: Options' and Questions' hashes, asserted (#:)
+    # one. Steep checks each field against the Hash's values.
+    type values = { author: String, github: String, summary: String, license: String, ?exe: bool,
+                    ?citation: bool, ?email: (String | false)?, ?given_names: (String | false)?,
+                    ?family_names: String, ?alias: (String | false)?, ?orcid: String?, ?keywords: String? }
+
+    def initialize: (String name, values values) -> void
     def path: () -> String
     def underscored: () -> String
     def constant: () -> String
     def modules: () -> Array[String]
     def licenses: () -> Array[String]
     def year: () -> Integer
+    def today: () -> String
+    def yaml: (String value) -> String
     def quote: (String value) -> String
+    def markdown: (String value) -> String
     def nest: (String body, ?doc: String?) -> String
+    def self.field: (Symbol key) -> String
+    def self.strip: (String text) -> String
+    def self.quote: (String value) -> String
+    def self.check: (Symbol key, String? value) -> String
+    private def self.utf8: (Symbol key, String? value) -> String
+    private def self.github: (String value) -> String
+    private def self.text: (String field, String value) -> String
+    private def self.line: (String field, String value) -> String
 
     private
 
+    def extras: (values values) -> void
+    def cite: (values values) -> void
+    def optional: (Symbol key, (String | false)? value) -> String?
     def indent: (String code) -> String
-    def valid: [T < Object] (String field, T value) { (T) -> bool } -> T
-    def text: (String field, String value) -> String
+  end
+
+  class Questions
+    # what is read from: a line at a time, and whether a person types it
+    interface _Input
+      def gets: () -> String?
+      def tty?: () -> bool
+    end
+
+    interface _Output
+      def print: (String) -> void
+      def puts: (?String) -> void
+    end
+
+    QUESTIONS: Hash[Symbol, String]
+
+    @input: _Input
+    @output: _Output
+    @dir: String
+    @git: Hash[Symbol, String]
+
+    def self.none?: (String text) -> bool
+    def initialize: (_Input input, _Output output, String dir, ?git: Hash[Symbol, String]) -> void
+    def name: (String? given, exe: bool, citation: bool) -> String
+    def values: (String name, Hash[Symbol, String | bool] given, Hash[Symbol, String] defaults)
+              -> Project::values
+
+    private
+
+    def check_name: (String name, bool exe, bool citation) -> String
+    def answer: (Symbol key, String text, String name, Hash[Symbol, String | bool | nil] values) -> (String | bool)
+    def default: (Symbol key, Hash[Symbol, String] defaults, Hash[Symbol, String | bool | nil] values) -> String?
+    def source: (Symbol key) -> String
+    def ask: (String question, ?String? default, check: ^(String) -> (String | bool), ?from: String, ?optional: bool)
+           -> (String | bool | nil)
+    def offered: (String question, String? default, String from, ^(String) -> (String | bool) check) -> String?
+    def read: (String question, String? default, bool optional) -> String?
+    def unanswered: (String question) -> nil
+    def checked: (String question, String answer, ^(String) -> (String | bool) check, ?String note) -> (String | bool | nil)
+    def terminal: [T] (String question) { () -> T } -> T
+    def yes?: (String answer) -> bool
   end
 
   module Options
     GIT_CONFIG: Hash[Symbol, String]
+    DEFAULTS: Hash[Symbol, String]
+    BANNER: String
+    OPTIONS: Array[[String, String]]
 
-    def self.parse: (Array[String] argv, ?config: ^(String) -> String?) -> Project
-    def self.given: (Hash[Symbol, untyped] values) -> Hash[Symbol, untyped]
-    def self.parser: () -> OptionParser
-    def self.git_config: (String key) -> String?
+    def self.parse: (Array[String] argv, ?dir: String, ?config: ^(String) -> String?, ?input: Questions::_Input,
+                     ?output: Questions::_Output) -> Project
+    private def self.arguments: (Array[String] argv) -> [Array[String], Hash[Symbol, String | bool]]
+    private def self.checked: (Symbol key, String value) -> String
+    private def self.ask: (Array[String] names, Hash[Symbol, String | bool] given, Hash[Symbol, String] defaults,
+                           Questions questions) -> Project
+    private def self.name_of: (Array[String] names) -> String
+    private def self.required: (Hash[Symbol, String] defaults, Hash[Symbol, String | bool] given) -> Project::values
+    private def self.check_present: (Hash[Symbol, String | bool | nil] values) -> void
+    private def self.parser: () -> OptionParser
+    private def self.git_config: (String key) -> String?
   end
 
   module Generator
     TEMPLATE: String
     EXE: Array[String]
+    EXECUTABLES: Array[String]
     GIT_LOCAL: Hash[String, nil]
     LICENSE_FILES: Hash[String, String]
+    CITATION: String
+    TOOLS_LOCK: String
 
-    def self.files: (Project project) -> Hash[String, String]
-    def self.skipped: (Project project) -> Array[String]
-    def self.tools: () -> Array[String]
-    def self.check: (Project project, Array[String] paths) -> void
-    def self.check_command: (Project project) -> void
-    def self.path_of: (String file, Project project) -> String
     def self.generate: (Project project, String target) -> void
-    def self.removed_unless_done: (String target) { () -> void } -> void
-    def self.write: (String source, String destination, Project project) -> void
-    def self.render: (String source, Project project) -> String
-    def self.git: (String dir, *String args) -> void
+    def self.check: (String name, exe: bool, citation: bool, target: String) -> String
+    def self.check_name: (String name, bool exe) -> void
+    private def self.check_target: (String target) -> void
+    private def self.files: (Project project) -> Hash[String, String]
+    private def self.templates: (bool exe) -> Array[String]
+    private def self.tools: (?String lock) -> Array[String]
+    private def self.path_of: (String file, String name) -> String
+    private def self.removed_unless_done: (String target) { () -> void } -> void
+    private def self.write: (String file, String destination, Project project) -> void
+    private def self.stage: (String target, Array[String] executables) -> void
+    private def self.render: (String source, Project project) -> String
+    private def self.git: (String dir, *String args) -> void
   end
 end

data/template/.gitattributes

@@ -0,0 +1,3 @@
+# Every text file LF, as checked out on Windows too (core.autocrlf): a CRLF shebang does not run,
+# and RuboCop wants LF (.rubocop.yml).
+* text=auto eol=lf

data/template/.githooks/pre-commit

@@ -1,6 +1,5 @@
 #!/bin/sh
-# What fails fastest, so a commit stays quick: RuboCop, the shell, the workflows, dprint; the
-# types, the tests and the rest are `bundle exec rake checks` and CI. Checks the working tree, not
-# just what is staged.
+# What fails fastest, so a commit stays quick; the types, the tests and the rest are
+# `bundle exec rake checks` and CI. Checks the working tree, not just what is staged.
 set -eu
 bundle exec rake rubocop shell workflows dprint

data/template/.github/PULL_REQUEST_TEMPLATE.md

@@ -10,5 +10,6 @@
 
 - [ ] Code passes local CI (`bundle exec rake checks`).
 - [ ] Core logic is extracted into pure, unit-testable functions.
-- [ ] Any new `# rubocop:disable` or `# steep:ignore` names its cop or diagnostic and says why it is wrong here (RuboCop's after `--`, Steep's on the line above: AGENTS.md).
+- [ ] Any new `# rubocop:disable` or `# steep:ignore` names its cop or diagnostic and says why it
+      is wrong here (RuboCop's after `--`, Steep's on the line above: AGENTS.md).
 - [ ] Commits follow [Conventional Commits](https://www.conventionalcommits.org/).

data/template/.github/dependabot.yml

@@ -1,6 +1,8 @@
 # The gems (Gemfile.lock), weekly; GitHub Actions, pinned to commits, each release in a comment,
 # and Dependabot moves both (docs.github.com, "Dependabot supported ecosystems"), weekly; the
 # flake's inputs, monthly.
+# No time: Dependabot picks one for the repository (docs.github.com, "Dependabot options
+# reference").
 version: 2
 updates:
   - package-ecosystem: "bundler"
@@ -8,11 +10,9 @@ updates:
     schedule:
       interval: "weekly"
       day: "sunday"
-      time: "07:00"
-      timezone: "UTC"
     open-pull-requests-limit: 5
-    # `chore(deps): ...` -- no changelog entry: the lock is not in the gem, whose users resolve its
-    # gemspec's requirements themselves
+    # `chore(deps): ...` -- a Miscellaneous Task in the changelog, no feature or fix: the lock is not
+    # in the gem, whose users resolve its gemspec's requirements themselves
     commit-message:
       prefix: "chore"
       include: "scope"
@@ -38,8 +38,6 @@ updates:
     schedule:
       interval: "weekly"
       day: "sunday"
-      time: "07:00"
-      timezone: "UTC"
     open-pull-requests-limit: 5
     # `ci(deps): ...` -- nothing a user of the gem meets, so no changelog entry
     commit-message:
@@ -66,8 +64,6 @@ updates:
     directory: "/"
     schedule:
       interval: "monthly"
-      time: "06:00"
-      timezone: "UTC"
     open-pull-requests-limit: 1
     # `chore(deps): ...` -- the flake is the development shell, the checks and the Nix package,
     # nothing RubyGems ships: a command's image takes the new inputs at its next release

data/template/.github/image-registries.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 # The repositories a release's image goes to, one a line, each logged in before anything is
 # pushed: GHCR's always (the job's token), Docker Hub's when both vars.DOCKERHUB_USERNAME and
-# secrets.DOCKERHUB_TOKEN are set -- the name vars.DOCKERHUB_REPOSITORY, else <username>/<the
-# GitHub repository's name>. image.yml's; it passes GH_TOKEN and DOCKERHUB_USERNAME,
+# secrets.DOCKERHUB_TOKEN are set -- vars.DOCKERHUB_REPOSITORY (<namespace>/<name>), else
+# <username>/<the GitHub repository's name>. image.yml's; it passes GH_TOKEN and DOCKERHUB_USERNAME,
 # DOCKERHUB_TOKEN and DOCKERHUB_REPOSITORY (empty when unset).
 set -euo pipefail
 
@@ -24,7 +24,8 @@ repository=${repository,,}
 name=${repository#*/}
 if [[ ! $repository =~ ^[a-z0-9]+((\.|_|__|-+)[a-z0-9]+)*/[a-z0-9]+((_|__|-+)[a-z0-9]+)*$ ]] ||
   ((${#name} < 2 || ${#name} > 255)); then
-  echo "error: '$repository' is no Docker Hub repository: set vars.DOCKERHUB_REPOSITORY" >&2
+  echo "error: '$repository' is no Docker Hub repository:" \
+    "set vars.DOCKERHUB_REPOSITORY to <namespace>/<name>" >&2
   exit 1
 fi
 docker login docker.io --username "$username" --password-stdin <<< "$token" >&2

data/template/.github/workflows/dependabot-automerge.yml

@@ -1,26 +1,23 @@
 name: Dependabot Auto-Merge
 
-# Required repository settings (do these once):
-# 1. Settings → General → Allow auto-merge          ← enable
-# 2. Settings → Branches → Branch protection rule on main:
-#      - Require a pull request before merging, with no required approvals
-#        (one would hold every bump for a person)
-#      - Require status checks to pass before merging (select the real CI
-#        jobs: every job the workflows run on every pull request -- not one
-#        whose `pull_request:` has `paths:`, which reports only when those
-#        paths change, so would block every other merge)
+# Repository settings, once:
+# 1. Settings → General → Allow auto-merge: on.
+# 2. Settings → Branches → a branch protection rule on main, its bypass to admins left allowed
+#    (`rake release` pushes its commit and tag to main):
+#      - Require a pull request before merging, no required approvals (one would hold every bump
+#        for a person).
+#      - Require status checks to pass before merging: every job the workflows run on every pull
+#        request -- not one whose `pull_request:` has `paths:`, which reports only when those paths
+#        change, so would block every other merge.
+#    Without step 2, this workflow merges bumps no CI job gated: auto-merge waits for *required*
+#    checks alone.
 #
-# The `permissions:` below are all this workflow's token needs; the
-# repository's default token permissions can stay read-only, and nothing
-# here creates or approves a pull request. Leave the rule's bypass to
-# admins allowed: `rake release` pushes its commit and tag to main.
-#
-# A merge this token makes starts no workflow run (GitHub's rule for
-# GITHUB_TOKEN's events): main runs nothing for it, its pull request's
-# required checks are what gated it.
-#
-# Without step 2, this workflow merges bumps that no CI job gated:
-# auto-merge waits for *required* checks alone.
+# The token needs only the `permissions:` below: the repository's default token permissions can
+# stay read-only, and nothing here creates or approves a pull request. A merge this token makes
+# starts no workflow run (GitHub's rule for GITHUB_TOKEN's events): main runs nothing for it; its
+# pull request's required checks gated it, on the main its branch was last updated from. "Require
+# branches to be up to date before merging" makes that main the current one, each bump then waiting
+# for its branch's update (`@dependabot rebase`).
 
 on:
   pull_request:
@@ -29,14 +26,14 @@ permissions: {}
 
 jobs:
   dependabot:
+    name: Auto-merge
     runs-on: ubuntu-latest
     permissions:
-      contents: write
-      pull-requests: write
-    # user.login, not github.actor: the account that opened the pull request,
-    # not whoever caused the event (a person pushing to Dependabot's branch
-    # too).
-    # Ref: https://docs.github.com/en/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions
+      contents: write # the merge
+      pull-requests: write # auto-merge, set on the pull request
+    # user.login, not github.actor: the account that opened the pull request, not whoever caused
+    # the event (a person pushing to Dependabot's branch too).
+    # Ref: https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/automate-dependabot-with-actions
     # github.actor: https://docs.github.com/en/actions/reference/workflows-and-actions/contexts
     #
     # To keep forks from auto-merging their own bumps, pin the repository:
@@ -51,14 +48,12 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Enable auto-merge for patch and minor updates
-        # update-type is the highest version-update:semver-{major,minor,patch}
-        # among the updated dependencies whose level is known (Dependabot's
-        # metadata, else their versions); empty when none is, which this
-        # condition refuses. A security update carries the same labels, no
-        # "security:" prefix. To gate on security status, enable alert-lookup
-        # with a PAT or an App's token (a Dependabot secret: a run Dependabot
-        # starts reads no other) and check steps.metadata.outputs.alert-state
-        # (the first dependency's alert).
+        # update-type: the highest version-update:semver-{major,minor,patch} among the updated
+        # dependencies whose level is known (Dependabot's metadata, else their versions); empty
+        # when none is, which this condition refuses. A security update carries the same labels,
+        # no "security:" prefix. To gate on security status, enable alert-lookup with a PAT or an
+        # App's token (a Dependabot secret: a run Dependabot starts reads no other) and check
+        # steps.metadata.outputs.alert-state (the first dependency's alert).
         if: >-
           contains(
             fromJSON('["version-update:semver-patch", "version-update:semver-minor"]'),

data/template/.github/workflows/dependency-review.yml

@@ -1,9 +1,9 @@
 name: Dependency Review
 
-# The licences and advisories of what a pull request adds to Gemfile.lock and the workflows, as the
-# templates' Python and Rust ones review theirs. Advisory: it reports only when those files change,
-# so no required check can be it, and dependabot-automerge.yml merges a bump it flags (security.yml's
-# bundler-audit holds the lock daily).
+# The licences and advisories of what a pull request adds to Gemfile.lock and the workflows.
+# Advisory: it reports only when those files change, so no required check can be it, and
+# dependabot-automerge.yml merges a bump it flags (security.yml's bundler-audit holds the lock
+# daily).
 on:
   pull_request:
     paths:
@@ -12,18 +12,22 @@ on:
       - "*.gemspec"
       - ".github/workflows/**"
 
+# a pull request's newest run cancels its older ones; any other run, a group of its own: every
+# commit on main checked (in a shared group, a pending run gives way to the newest: the default)
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
 permissions: {}
 
-# NOTE: it needs the repository's dependency graph (Settings → Advanced
-# Security), and on a private repository GitHub Code Security too (an
-# organization's): without them, this job fails rather than skipping --
-# enable them, or delete the workflow.
+# NOTE: it needs the repository's dependency graph (Settings → Advanced Security), and on a
+# private repository an organization's GitHub Code Security too: without them the job fails, not
+# skips -- enable them, or delete the workflow.
 #
-# What it reads: Gemfile.lock has no scopes, so each of its gems counts as
-# runtime -- the gemspec's dependencies and the Gemfile's tools alike --;
-# the actions for licences in effect: advisories match actions by semantic
-# version alone, not the commits these are pinned to ("Dependency graph
-# supported package ecosystems").
+# Gemfile.lock has no scopes, so each of its gems counts as runtime, the gemspec's dependencies and
+# the Gemfile's tools alike. In effect, the actions are reviewed for licences alone: advisories
+# match an action by semantic version, not the commit it is pinned to ("Dependency graph supported
+# package ecosystems").
 jobs:
   dependency-review:
     name: License & Security Check
@@ -38,8 +42,8 @@ jobs:
           fail-on-severity: moderate
           # The licences are ClearlyDefined's, not the gemspecs'; a gem's:
           #   curl -s https://api.clearlydefined.io/definitions/gem/rubygems/-/NAME/VERSION
-          # (.licensed.declared). Add anything legitimate that is missing rather
-          # than deleting this list -- an empty allow-list allows everything.
+          # (.licensed.declared). Add what is legitimate and missing; never delete this list: an
+          # empty allow-list allows everything.
           # Ruby: Ruby's own licence, with MIT or BSD's (concurrent-ruby, reline)
           allow-licenses: >
             0BSD, Apache-2.0, BlueOak-1.0.0, BSD-2-Clause, BSD-3-Clause,

data/template/.github/workflows/image.yml

@@ -5,13 +5,19 @@
 # <version>-arm64) stay, the multi-architecture tag's parts. It runs beside release.yml, not after
 # it: the image does not wait for the gem's push to RubyGems.
 #
-# The job's token pushes: no secret stored. A first push is private (GHCR's default): make the
-# package public in its settings once.
+# The jobs' token pushes to GHCR: no secret stored. A first push is private (GHCR's default): make
+# the package public in its settings once.
 #
 # Docker Hub too, the same tags, once vars.DOCKERHUB_USERNAME and secrets.DOCKERHUB_TOKEN (an
 # access token that writes) are set: as vars.DOCKERHUB_REPOSITORY, else <username>/<repository>. A
-# Docker Hub failure in the build (its login, its name, a push) holds GHCR's multi-architecture tag
-# back too; a re-run, once fixed, completes both.
+# Docker Hub failure in a push (its login, its name) holds GHCR's multi-architecture tag back too;
+# once fixed, a re-run of the failed jobs within a day (the image's artifact kept so long), or of
+# all of them, completes both.
+#
+# The build, which runs the image, holds no write and no secret, and passes on the image it ran;
+# the jobs that push, which build nothing, run in the `image` environment, which holds
+# DOCKERHUB_TOKEN and which the generated CONTRIBUTING.md's first steps limit to the release tags: a
+# job of no other ref can read it.
 #
 # Run by hand (workflow_dispatch) on a branch, it builds and runs the image on both architectures,
 # pushing nothing: a rehearsal before the first release; on a tag, it publishes that release again.
@@ -37,8 +43,8 @@ jobs:
             arch: arm64
     permissions:
       contents: read
-      packages: write
     outputs:
+      image: ${{ steps.build.outputs.image }}
       description: ${{ steps.build.outputs.description }}
     steps:
       - name: Checkout
@@ -47,7 +53,7 @@ jobs:
           persist-credentials: false
 
       - name: Install Nix
-        uses: cachix/install-nix-action@448cde739abec1eaf0646249e3d25bb8d9bc7702 # v31.11.2
+        uses: cachix/install-nix-action@75c75c31ebece974e48ebc36b4ad125bd97bd97b # v31.11.3
 
       - name: Build and run
         id: build
@@ -59,9 +65,10 @@ jobs:
             echo "::error::$GITHUB_REF_NAME, but version.rb declares $version" >&2
             exit 1
           fi
-          # streamed into docker: no compressed copy of the closure in the store
+          # streamed: no compressed copy of the closure in the store
           stream="$(nix build --no-link --print-out-paths .#image.stream)"
-          "$stream" | docker load
+          "$stream" > image.tar
+          docker load --input image.tar
           loaded="$(nix eval --raw .#image.imageName):$version"
           # the image as a user runs it: its entrypoint, as its user
           expected="$(nix eval --raw .#image.imageName) $version"
@@ -73,10 +80,52 @@ jobs:
           # assigned first: a failing command substitution inside echo's arguments would not stop
           # the step
           description="$(nix eval --raw .#default.meta.description)"
-          echo "description=$description" >> "$GITHUB_OUTPUT"
+          {
+            echo "image=$loaded"
+            echo "description=$description"
+          } >> "$GITHUB_OUTPUT"
 
-      - name: Push
+      - name: Keep the image
         if: github.ref_type == 'tag'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: image-${{ matrix.arch }}
+          path: image.tar
+          if-no-files-found: error
+          retention-days: 1
+
+  push:
+    name: Push (${{ matrix.arch }})
+    needs: build
+    if: github.ref_type == 'tag'
+    runs-on: ${{ matrix.runner }}
+    environment:
+      name: image
+    strategy:
+      matrix:
+        include:
+          - runner: ubuntu-latest
+            arch: amd64
+          - runner: ubuntu-24.04-arm
+            arch: arm64
+    permissions:
+      contents: read
+      packages: write # GHCR's pushes
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: The build's image
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: image-${{ matrix.arch }}
+
+      - name: Load it
+        run: docker load --input image.tar
+
+      - name: Push
         env:
           GH_TOKEN: ${{ github.token }}
           # Docker Hub too, when both are set (.github/image-registries.sh): an unset variable or
@@ -86,25 +135,27 @@ jobs:
           DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
           DOCKERHUB_REPOSITORY: ${{ vars.DOCKERHUB_REPOSITORY }}
           ARCH: ${{ matrix.arch }}
+          LOADED: ${{ needs.build.outputs.image }}
         run: |
           set -euo pipefail
           repositories="$(.github/image-registries.sh)"
           version="${GITHUB_REF_NAME#v}"
-          loaded="$(nix eval --raw .#image.imageName):$version"
           # the list on its own descriptor: no command in the loop can read it away
           while read -r repository <&3; do
-            docker tag "$loaded" "$repository:$version-$ARCH"
+            docker tag "$LOADED" "$repository:$version-$ARCH"
             docker push "$repository:$version-$ARCH"
           done 3<<< "$repositories"
 
   publish:
     name: Multi-architecture tag
-    needs: build
+    needs: [build, push]
     if: github.ref_type == 'tag'
     runs-on: ubuntu-latest
+    environment:
+      name: image
     permissions:
       contents: read
-      packages: write
+      packages: write # GHCR's multi-architecture tag
     steps:
       - name: Checkout
         # every tag, to tell whether this one is the highest

data/template/.github/workflows/links.yml

@@ -0,0 +1,35 @@
+# The links of the files git tracks but the tests' (`rake links`, lychee), monthly and on demand: a
+# page moves or goes with nothing changed here. In the dev shell, whose lychee is the flake's;
+# GITHUB_TOKEN, so GitHub's links are not rate-limited, lychee's alone, not the gems' installs.
+name: Links
+
+on:
+  schedule:
+    - cron: "47 4 1 * *" # the 1st of each month, 04:47 UTC: off the hour, when GitHub delays runs
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  links:
+    name: lychee
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@75c75c31ebece974e48ebc36b4ad125bd97bd97b # v31.11.3
+
+      - name: Install the gems
+        env:
+          BUNDLE_FROZEN: "true"
+        run: nix develop --command bundle install
+
+      - name: rake links
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: nix develop --command bundle exec rake links

data/template/.github/workflows/nix.yml

@@ -7,8 +7,8 @@ name: Nix
 on:
   push:
     branches: [main]
-  # every pull request, whatever it touches: a path-filtered workflow never reports, and a
-  # required check that never reports blocks the merge
+  # every pull request, whatever it touches: a path-filtered workflow does not report on one
+  # outside its paths, and a required check that does not report blocks the merge
   pull_request:
   workflow_dispatch:
 
@@ -37,7 +37,7 @@ jobs:
 
       - name: Install Nix
         # flakes on, and the job's token for GitHub fetches
-        uses: cachix/install-nix-action@448cde739abec1eaf0646249e3d25bb8d9bc7702 # v31.11.2
+        uses: cachix/install-nix-action@75c75c31ebece974e48ebc36b4ad125bd97bd97b # v31.11.3
 
       - name: nix flake check
         run: nix flake check --print-build-logs