chore: to production

.github/copilot-instructions.md

@@ -25,6 +25,14 @@
   regenerate `docs/cli.md` (it is generated — never edit it by hand). CI's
   `make verify-generated` fails on drift.
 
+## Documented command output is generated
+
+- The `console` code blocks in `README.md`, `docs/*.md`, and `examples/*/README.md`
+  are trycmd cases: their expected output is verified by the `documentation` test.
+  The dependency report the CLI prints carries the versions declared in
+  `crates/oapi-codegen/Cargo.toml`, so a dependency bump changes that output.
+  After any dependency upgrade, run `make update-docs` and commit the result.
+
 # Rust Coding Conventions and Best Practices
 
 Follow idiomatic Rust practices and community standards when writing Rust code.

.github/workflows/automatic-prod-pr.yml

@@ -0,0 +1,75 @@
+name: Automatic Production PR
+
+on:
+  schedule:
+    - cron: "0 0 * * 0" # Runs every Sunday at midnight UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  create-prod-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create temporary GitHub App Token
+        id: app
+        uses: actions/create-github-app-token@v3
+        with:
+          owner: ${{ github.repository_owner }}
+          client-id: ${{ vars.HOUSEKEEPING_BOT_APP_ID }}
+          repositories: ${{ github.event.repository.name }}
+          private-key: ${{ secrets.HOUSEKEEPING_BOT_PRIVATE_KEY }}
+
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          ref: develop
+          fetch-depth: 0
+          token: ${{ steps.app.outputs.token }}
+
+      - name: Check for changes between develop and main
+        id: check_changes
+        run: |
+          git fetch origin main develop
+
+          if git diff --quiet origin/main...origin/develop; then
+            echo "No changes detected between develop and main"
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Changes detected between develop and main"
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create Pull Request
+        if: steps.check_changes.outputs.has_changes == 'true'
+        id: create_pr
+        env:
+          GH_TOKEN: ${{ steps.app.outputs.token }}
+        run: |
+          # Check if PR already exists
+          EXISTING_PR=$(gh pr list --base main --head develop --json number --jq '.[0].number // empty')
+
+          if [ -n "$EXISTING_PR" ]; then
+            echo "Pull request already exists: #$EXISTING_PR"
+            echo "pr_number=$EXISTING_PR" >> "$GITHUB_OUTPUT"
+          else
+            echo "Creating pull request from develop to main"
+            PR_URL=$(gh pr create \
+              --title "chore: to production" \
+              --body "" \
+              --head develop \
+              --base main)
+
+            echo "Pull request created at: $PR_URL"
+            PR_NUMBER=$(gh pr view "$PR_URL" --json number --jq .number)
+            echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Enable auto-merge
+        if: steps.check_changes.outputs.has_changes == 'true'
+        uses: alchemaxinc/composite-toolbox/merge-pr@v1
+        with:
+          token: ${{ steps.app.outputs.token }}
+          pull-request-number: ${{ steps.create_pr.outputs.pr_number }}

.github/workflows/check-openapi-versions.yml

@@ -29,6 +29,7 @@ jobs:
         with:
           owner: ${{ github.repository_owner }}
           client-id: ${{ vars.HOUSEKEEPING_BOT_APP_ID }}
+          repositories: ${{ github.event.repository.name }}
           private-key: ${{ secrets.HOUSEKEEPING_BOT_PRIVATE_KEY }}
 
       - name: Checkout and setup

.github/workflows/ci.yml

@@ -3,8 +3,26 @@ name: CI
 on:
   pull_request:
 
+  # Do not remove this trigger as redundant with `pull_request`: it exists to
+  # seed the shared cache on the default branch after merges; the checks already
+  # ran for the change in the pull request workflow.
+  # GitHub scopes every cache entry to the ref that wrote it, and a run may
+  # only read entries from its own ref, its base ref, or the default branch.
+  # A `pull_request`-only workflow therefore writes every entry into a
+  # `refs/pull/N/merge` scope that no other pull request can ever read, so
+  # each one starts cold, rebuilds everything, and saves yet another private
+  # copy. That churn previously consumed the whole 10 GB repository cache
+  # quota and evicted entries faster than they could be reused.
+  #
+  # Running on pushes to the default branch writes the entries into a scope
+  # every pull request can read, so one post-merge run seeds them all.
+  push:
+    branches: [develop]
+
 concurrency:
-  cancel-in-progress: true
+  # Superseded pull request runs are worth cancelling, but a push to the
+  # default branch is what seeds the shared cache, so let it always finish.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
   group: ${{ github.workflow }}-${{ github.ref }}
 
 permissions:

.github/workflows/deploy.yml

@@ -41,6 +41,7 @@ jobs:
         with:
           owner: ${{ github.repository_owner }}
           client-id: ${{ vars.HOUSEKEEPING_BOT_APP_ID }}
+          repositories: ${{ github.event.repository.name }}
           private-key: ${{ secrets.HOUSEKEEPING_BOT_PRIVATE_KEY }}
 
       - name: Checkout and setup

.github/workflows/pr-title-lint.yml

@@ -27,15 +27,12 @@ jobs:
       - name: Checkout code (shallow)
         uses: actions/checkout@v7
 
-      - name: Cache Commitlint
-        id: cache-commitlint
-        uses: actions/cache@v6
-        with:
-          path: node_modules
-          key: v1-commitlint-${{ env.COMMITLINT_CLI_VERSION }}
-
+      # Deliberately not cached. This workflow only runs on `pull_request`, so
+      # every cache entry lands in a `refs/pull/N/merge` scope that no other
+      # pull request can read: each one paid the full install anyway and then
+      # wrote another ~12 MB private copy against the repository's 10 GB quota.
+      # Restoring the entry also costs about as long as the install it skips.
       - name: Install Commitlint
-        if: steps.cache-commitlint.outputs.cache-hit != 'true'
         run: npm i -D @commitlint/cli@${{ env.COMMITLINT_CLI_VERSION }} @commitlint/config-conventional @commitlint/types
 
       - name: Lint PR title (conventional commit)

.github/workflows/update-deps-cargo.yml

@@ -4,6 +4,9 @@ on:
   schedule:
     - cron: "0 0 * * 0" # Run every Sunday at midnight
 
+env:
+  BRANCH_PREFIX: update-cargo
+
 jobs:
   update-cargo:
     runs-on: ubuntu-latest
@@ -14,6 +17,7 @@ jobs:
         with:
           owner: ${{ github.repository_owner }}
           client-id: ${{ vars.HOUSEKEEPING_BOT_APP_ID }}
+          repositories: ${{ github.event.repository.name }}
           private-key: ${{ secrets.HOUSEKEEPING_BOT_PRIVATE_KEY }}
 
       - name: Update Cargo Dependencies
@@ -23,6 +27,31 @@ jobs:
           auto-merge: "true"
           base-branch: "develop"
           merge-method: "squash"
-          branch-prefix: "update-cargo"
+          branch-prefix: ${{ env.BRANCH_PREFIX }}
           pr-title: "fix(deps): update cargo dependencies"
           commit-message: "fix(deps): update cargo dependencies"
+
+      # The action leaves the working tree on the branch it created, so the
+      # regenerated output lands on the same pull request.
+      - name: Refresh the documented command output
+        run: |
+          set -euo pipefail
+          branch="$(git rev-parse --abbrev-ref HEAD)"
+          case "$branch" in
+            "$BRANCH_PREFIX"-*) ;;
+            *)
+              echo "::notice::No dependency-update branch exists; nothing to refresh."
+              exit 0
+              ;;
+          esac
+
+          make update-docs
+
+          paths="$(make --no-print-directory print-generated-paths)"
+          if [ -z "$(git status --porcelain -- $paths)" ]; then
+            echo "::notice::The documented command output is already up to date."
+            exit 0
+          fi
+          git add -- $paths
+          git commit -m "docs: refresh documented command output for updated dependencies"
+          git push origin "HEAD:$branch"

.github/workflows/update-deps-github-actions.yml

@@ -14,6 +14,7 @@ jobs:
         with:
           owner: ${{ github.repository_owner }}
           client-id: ${{ vars.HOUSEKEEPING_BOT_APP_ID }}
+          repositories: ${{ github.event.repository.name }}
           private-key: ${{ secrets.HOUSEKEEPING_BOT_PRIVATE_KEY }}
 
       - name: Update GitHub Actions