Repository navigation
Conversation
Add scripts/build_index.py and the Index workflow. After every push to main, the workflow builds index.json from main's git history and publishes it on the "index" branch: https://raw.githubusercontent.com/OpenSAK-Org/OpenSAK-Macros/index/index.json OpenSAK's Macro manager can read this file to list, install and update macros without walking the repository through the GitHub API. Per macro the index holds: - the header, read with OpenSAK's own parser (from .github/opensak-ref) - every file in its folder, with size, SHA-256 and a download URL pinned to the commit - every version that was on main: publish date, SHA-256, size, Requires-API and permissions of the macro file - the changelog from the "## Changes" list in its README Macros removed from main are listed under "withdrawn" with the hashes of all their versions, so an installed copy can be recognised. The script only reads git objects and never runs macro code. The same commit always gives the same file, and a run that changes nothing pushes nothing. MAINTAINERS.md describes the format (schema 1). CONTRIBUTING.md and the template README now ask for a "## Changes" line per version.
nagisml
force-pushed
the
feature/macro-index
branch
from
November 18, 2026 20:38
a617aee to
dcb2fab
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
@AgreeDK this is my idea feel free to change it in any way
What
After every push to
main, a new Index workflow buildsindex.jsonand publishes it on anindexbranch:https://raw.githubusercontent.com/OpenSAK-Org/OpenSAK-Macros/index/index.json
OpenSAK's Macro manager can read this one file to browse, install and update macros. That is the planned "update from OpenSAK-Macros" follow-up to OpenSAK-Org/OpenSAK#938. The manager won't need the GitHub API or rate-limited directory listings.
What the index holds
For each macro:
Requires-API, permissions, network, headless. It is read with OpenSAK's own parser from.github/opensak-ref, the same one the PR check uses.size,sha256and a downloadurlpinned to the commit. The bytes behind a URL never change.main, newest first, with publish date,sha256, size,Requires-APIand permissions. The manager can use them to see which version is installed and whether an update needs a newer OpenSAK or asks for more permissions.## Changeslist from the README (- 1.1 — text). All current macros already use this format.Macros removed from
mainare listed underwithdrawn, with the hashes of all their versions, so OpenSAK can recognise an installed copy.MAINTAINERS.md ("The macro index") describes the full format. It is
schema1: new fields may be added later, and a breaking change would raise the schema number.How
scripts/build_index.pyonly reads git objects (ls-tree,show,log --first-parent) and never runs macro code. The same commit always gives the same file..github/workflows/index.ymlruns only on pushes tomainand on manual dispatch. It publishes to theindexbranch, which holds onlyindex.jsonand a short README. If the file is unchanged, nothing is pushed.main, so everything in the index has passed the pull request checks.Docs
## Changesline for each new version.Tests
tests/test_build_index.pyhas 13 new tests. They cover header, files and hashes, CRLF bytes, version history and dates, a version republished without a bump, changelog parsing, withdrawn macros, a macro that comes back after removal, an unreadable header, identical output from the same commit, and a check against this repository itself. "Test checker" runs them.Locally, all 54 tests pass with the pinned parser and with current OpenSAK beta.
After merging
indexbranch. No ruleset may block pushes to it; "Protect main" covers only the default branch.Headlesskey, soheadlessisnulluntil.github/opensak-refis moved to a commit that has it.