From fc1f62a7c8eb4adf2aed6353c72759eecb18a60f Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 22:33:59 +1100 Subject: [PATCH 1/5] docs: route published pre-commit hook changes --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 550de38a..3c2108b0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,7 +36,7 @@ Load the narrow source that owns the task instead of relying on cached repositor - **Generation, README ownership, versioning, convergence, formatting, or bundles:** read `docs/tool-contract.md`. - **Build, test, lint, or package-script behavior:** read `package.json` and `vite.config.ts`. -- **Git-hook behavior:** read the matching file under `.husky/` and the script it invokes in `package.json`. +- **Git-hook behavior:** for this repository's local hooks, read `.husky/` and the invoked `package.json` script; for the published consumer hook, read `.pre-commit-hooks.yaml` and `scripts/pre-commit-hook.sh`. - **CI behavior:** read the relevant file under `.github/workflows/`; workflow display names are not the source of truth. - **Release behavior:** read the relevant workflow and the `release` configuration in `package.json`. - **Before declaring a fix, review finding, or your own diff settled:** read `.claude/skills/checker-principle/SKILL.md`. From f63bf6a07a66c14a4207452aaf51375af3ac18fc Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 22:34:52 +1100 Subject: [PATCH 2/5] docs: publish supported pre-commit configuration --- README.md | 29 ++++++++++++----------------- 1 file changed, 12 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 61c8e819..a097631f 100644 --- a/README.md +++ b/README.md @@ -154,33 +154,28 @@ You can modify the script below to include any extra variables you like or use n ### Using as a Pre-commit Hook -You can automate README generation on every commit by using this tool as a pre-commit hook. This ensures your documentation stays up-to-date automatically. +This repository publishes a pre-commit hook. Consumers need a supported Node.js/npm installation, but do not need to install this package separately. -1. **Install the tool locally** (if you haven't already): +Add the hook to `.pre-commit-config.yaml` using an immutable release tag: -```sh -npm install --save-dev github-action-readme-generator -# or -yarn add -D github-action-readme-generator +```yaml +repos: + - repo: https://github.com/bitflight-devops/github-action-readme-generator + rev: v2.1.0 + hooks: + - id: github-action-readme-generator ``` -2. **Configure pre-commit**: +Use `pre-commit autoupdate` to move to newer releases. Do not use the moving `v2` alias as `rev`: pre-commit caches repositories by repository and revision string, so moving that tag does not reliably update an existing hook environment. -Add the following to your `.pre-commit-config.yaml` file: +The hook runs on every commit because the action and README paths are configurable. Staged filenames are not passed to the generator. Pass CLI options through `args` when needed: ```yaml -repos: - - repo: local - hooks: - id: github-action-readme-generator - name: Generate README from action.yml - entry: npx github-action-readme-generator - language: system - files: ^(action\.yml|\.ghadocs\.json)$ - pass_filenames: false + args: [--readme, docs/ACTION.md] ``` -This configuration will automatically regenerate your README whenever `action.yml` or `.ghadocs.json` changes. +Configuration is still read from the consumer repository's `.ghadocs.json`; there is no separate configuration-file path option. ## Configuration From 5bcab052d165a96da95b78200664a4f165e5018b Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 22:34:56 +1100 Subject: [PATCH 3/5] docs: define published pre-commit hook contract --- docs/tool-contract.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/tool-contract.md b/docs/tool-contract.md index 73ab8213..fa0d6411 100644 --- a/docs/tool-contract.md +++ b/docs/tool-contract.md @@ -141,6 +141,14 @@ This is the case the tool exists for and the case least covered by unit tests; - Zero-input and zero-output actions are ordinary third-party shapes, not edge cases. +## Published pre-commit hook + +The pre-commit manifest is an adapter to the released CLI, not a second installation of this development repository. `.pre-commit-hooks.yaml` uses `unsupported_script`; `scripts/pre-commit-hook.sh` requires the consumer's Node/npm runtime, reads the selected repository revision's `package.json` version, and executes that exact npm release. + +Consumer `args` are forwarded to the CLI. Staged filenames are not: `pass_filenames: false` keeps arbitrary staged paths from becoming CLI arguments. Action and README paths may therefore be supplied through the generator's normal CLI/config inputs, while configuration itself remains the consumer repository's `.ghadocs.json`. + +A published pre-commit `rev` must be an immutable release tag whose npm package already exists. Do not document a moving major tag such as `v2`: pre-commit caches hook repositories by repository and revision string, so moving the same ref does not reliably refresh an existing consumer. Use exact release tags and let `pre-commit autoupdate` select newer ones. + ## Published bundles are self-contained A GitHub Actions runner gives this action no `node_modules` of its own. Every From 2b8d427c3de265ed404beea96daf7accd40c0081 Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 22:35:33 +1100 Subject: [PATCH 4/5] test: verify documented pre-commit release --- .github/workflows/integration-test.yml | 35 ++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/.github/workflows/integration-test.yml b/.github/workflows/integration-test.yml index 9d09e193..11b02070 100644 --- a/.github/workflows/integration-test.yml +++ b/.github/workflows/integration-test.yml @@ -470,3 +470,38 @@ jobs: pre-commit run github-action-readme-generator --all-files --verbose cmp ACTION.after-first-run.md docs/ACTION.md + + - name: Verify documented release hook + working-directory: consumer + run: | + cat > docs/ACTION.md <<'MARKDOWN' + # Consumer + + + stale published description + + MARKDOWN + + cat > .pre-commit-config.yaml <<'YAML' + repos: + - repo: https://github.com/bitflight-devops/github-action-readme-generator + rev: v2.1.0 + hooks: + - id: github-action-readme-generator + args: [--readme, docs/ACTION.md] + YAML + + pre-commit validate-config .pre-commit-config.yaml + + set +e + pre-commit run github-action-readme-generator --all-files --verbose + published_status=$? + set -e + + if [ "$published_status" -eq 0 ]; then + echo "::error::published hook should report the target README modification" + exit 1 + fi + + grep -F "Generated through the published pre-commit hook" docs/ACTION.md + grep -F "default README must stay stale" README.md From c5ab23f5c4d5cf7a2bf0bfa3a908ccdc8fb3df24 Mon Sep 17 00:00:00 2001 From: Jamie Nelson Date: Tue, 13 Oct 2026 22:36:47 +1100 Subject: [PATCH 5/5] test: stage published hook fixture --- .github/workflows/integration-test.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/integration-test.yml b/.github/workflows/integration-test.yml index 11b02070..008bc034 100644 --- a/.github/workflows/integration-test.yml +++ b/.github/workflows/integration-test.yml @@ -491,6 +491,7 @@ jobs: args: [--readme, docs/ACTION.md] YAML + git add docs/ACTION.md .pre-commit-config.yaml pre-commit validate-config .pre-commit-config.yaml set +e