cli: add show-extensions command to list extension hook points

[iav]

What

Adds a show-extensions CLI command (alias show-hooks) that lists the extension hook points available in the build framework.

./compile.sh show-extensions                      # sorted hook names, one per line
./compile.sh show-extensions SHOW_EXTENSIONS=docs # Markdown with each hook's inline docs

Why

The hooks documentation is auto-generated only during a build, so it captures just the hooks a given build path actually triggers and is therefore incomplete. armbian/documentation#859 documents this and works around it with a manual grep one-liner; igorpecovnik suggested baking that into a command instead.

How

• Statically scans lib/ and extensions/ for call_extension_method call sites, so the list is exhaustive regardless of board/branch/release and needs no board config or Docker.
• Default output is the hook names, sorted alphabetically.
• SHOW_EXTENSIONS=docs emits Markdown with each hook's inline documentation and backward-compat aliases — a static, complete equivalent of the build-time hooks.auto.docs.md.

Informational command only; builds nothing.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added show-extensions and show-hooks CLI commands to discover available framework hooks.
  • Commands scan the framework source to automatically extract hook names and their inline documentation.
  • Output supports two modes: a simple hook list (default) or formatted Markdown with hook descriptions and “Also known as” compatibility aliases.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 47cefae6-ef75-4f66-b6fc-192ff2c1b9f0

📥 Commits

Reviewing files that changed from the base of the PR and between e923174 and 04551dc.

📒 Files selected for processing (3)

• lib/functions/cli/cli-show-extensions.sh
• lib/functions/cli/commands.sh
• lib/library-functions.sh

🚧 Files skipped from review as they are similar to previous changes (3)

• lib/library-functions.sh
• lib/functions/cli/commands.sh
• lib/functions/cli/cli-show-extensions.sh

---

📝 Walkthrough

Walkthrough

Adds two new CLI commands (show-extensions and show-hooks) to the Armbian build framework. Both commands scan the source tree for call_extension_method call sites, extract hook names and inline heredoc documentation via an awk parser, and render results as either a plain sorted list or a generated Markdown document.

Changes

Hook-discovery CLI feature

Layer / File(s)	Summary
Command registration and module sourcing lib/functions/cli/commands.sh, lib/library-functions.sh	Registers show-extensions and show-hooks aliases in ARMBIAN_COMMANDS_TO_HANDLERS_DICT pointing to show_extensions, and inserts the sourcing of cli-show-extensions.sh into the library load sequence.
Pre-run setup and scan initialization lib/functions/cli/cli-show-extensions.sh (lines 1–31)	cli_show_extensions_pre_run sets USE_TMPFS=no for unprivileged container execution. cli_show_extensions_run selects list or docs output format from SHOW_EXTENSIONS, recursively greps for call_extension_method call sites under ${SRC}/{lib,extensions,config}, and returns early with a warning if none are found.
awk hook-name and heredoc extraction pipeline lib/functions/cli/cli-show-extensions.sh (lines 33–90)	Deduplicates and sorts matched files, then runs an awk parser to locate hook call lines, extract double-quoted hook name and compat arguments, normalize ${…} templated names, derive heredoc delimiters, accumulate heredoc bodies, and emit one record per hook point.
List and Markdown output rendering lib/functions/cli/cli-show-extensions.sh (lines 91–114)	In list mode prints deduplicated sorted hook names. In docs mode prints a Markdown header then formats each hook record into a named section with heredoc content and an optional "Also known as" alias list.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 Hippity-hop through the source tree I go,
Sniffing out hooks with my awk in a row,
Each call_extension_method laid bare,
Markdown or list — I'll show them all there!
From extensions to config, no hook shall hide,
This bunny's got docs on its side! 📜

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: adding a new CLI command to list extension hook points.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[EvilOlaf]

Is this redundant to https://github.com/armbian/build/blob/main/extensions/gen-sample-extension-docs.sh ?

[iav]

Is this redundant to extensions/gen-sample-extension-docs.sh?

Not redundant — they overlap in intent but differ in mechanism and use case.

gen-sample-extension-docs.sh is an extension that runs inside an actual build (via the extension_metadata_ready hooks, in the extension-manager lifecycle). It documents the hook points that were actually called for that particular board/release/option set — reading the runtime hook_point_calls.txt — and writes userpatches/extensions/hooks.auto.docs.md plus a sample-extension.sh scaffold. You have to run a build (with the extension enabled) to get it, and it only reflects the paths that build exercised.

show-extensions is a standalone CLI command — no build, no Docker, no config needed. It does a static scan of the sources (call_extension_method across lib/, extensions/, config/) and prints the complete set of hook points, instantly. That's the discoverability angle from armbian/documentation#859 — letting users (and docs) enumerate every hook without kicking off a build.

So: runtime/build-coupled/config-specific vs static/no-build/complete. The docs output format is intentionally aligned with the existing generator (same "Also known as" compat names), but the two answer different questions.

[rpardini]

While I think this is useful, saying we humans will be able to grok that grep / awk black magic in the future is a stretch. One case I think it might choke is when extensions themselves define new hook points -- which is supported, but currently not used.

[iav]

saying we humans will be able to grok that grep / awk black magic… is a stretch

Fair — the awk is dense. Two things that I think take the long-term-maintenance risk off the table:

It only has to recognize one shape: the call_extension_method "name" [compat…] <<- DELIM call plus its heredoc. That's an invariant call_extension_method() enforces anyway — it always consumes the heredoc as the hook's docs — so the parser is matching the framework's own contract, not free-form bash. And I'm happy to add a golden-file test that diffs show-extensions against a checked-in list in CI: if the parser ever drifts on new syntax it fails loudly instead of silently, so nobody has to re-read the awk to trust it.

it might choke when extensions themselves define new hook points — supported, but currently not used

That case already exists and is covered — the scan walks extensions/ and config/, not just lib/. extensions/grub.sh defines three (grub_early_config, grub_pre_install, grub_late_config), each with inline docs, and they all show up in the output.

The one place it intentionally degrades is runtime-templated names: main-config.sh calls post_family_config_branch_${BRANCH,,}, which isn't a literal hook, so it's listed as post_family_config_branch_<branch> rather than expanded per-branch.

If you had a different pattern in mind for "define new hook points" (e.g. a hook name assembled at runtime inside the extension), point me at it and I'll cover it.

[rpardini]

Fair. I won't oppose this...