docs: bootstrap.toml, and jb stops naming the runner - #10
Merged
Conversation
The org front page advertised two things that are no longer true: the tools
table listed the runner as `jb`, two rows above **just-buildit** the PEP 517
backend in the same table, and `jb.toml` / `jb-deps.toml` had separate bullets
and separate schema blocks when they are one file now. `bootstrap.toml` names
what the file declares — what must exist before the language ecosystem's own
package manager can run — rather than who reads it.
Rebased onto main, which had moved five commits. Three conflicts, each a case
of both sides editing the same line, resolved by taking BOTH changes rather
than a side:
- the tools table — main added the Status badge column and moved jm and
just-buildit to `pip install`; this branch renamed the runner. Kept main's
column and rows, applied the rename.
- the greenfield paragraph — main dropped ", and CI" (verified: `jm new`
writes no workflow; CI is the separate `jm ci` command) and folded the two
manifests into one. Kept both corrections, under the new name.
- the get-started block — same shape: main's `pip install just-makeit`, this
branch's rename.
Two more references lived only in the Makefile-standard section main added
after this branch forked, so the original sweep never saw them: the
`Required files` table and the adoption sentence under it.
`just-makeit new emits bootstrap.toml` is ticked, not un-ticked as the PR body
says. That was written when jm still emitted the old name; jm #936 shipped it
and **0.57.0 is on PyPI**, so the roadmap can claim it.
Two decision-log entries are struck through rather than deleted — a log records
what was decided, and both are now false: the `jb-` prefix decision is the very
mistake this rename corrects, and `jb`-may-conflict describes a fallback to
`just-buildit` that cannot happen, since `get-jb.sh` no longer installs either
name. The shipped-list row claiming conflict detection is marked superseded for
the same reason.
Unrelated but adjacent, both pre-existing on main: a doubled horizontal rule
above the fold, and a bold span mdformat mangles into an escaped list item
because its continuation line starts with `+ 25`. Reworded so the file is
mdformat-stable.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
hunterdsp
force-pushed
the
feat/bootstrap-toml
branch
from
August 12, 2026 21:25
079a1a0 to
67e5f65
Compare
GitHub renders `profile/README.md` as the organisation landing page. The root `README.md` is merely this repo's own README. They were two hand-maintained copies of the same public text — byte-identical before this branch — and the previous commit here updated only the root one. So the change that was supposed to fix the front page did not touch the front page. Verified live against https://github.com/just-buildit, which was still serving: | [**just-runit**](…) (`jb`) | Fast ephemeral script runner | the tool manifest (`jb.toml`, with system build deps folded in under `[dev.*]`) drop a `jb-deps.toml` at the repo root # Get the universal entrypoint (installs jb + jbx) This is the same peer-copy failure as `release-watch.sh` earlier today: two copies of one thing, a fix applied to one, and nothing that could notice. profile/ is DERIVED now. The root README is the public half plus the below-the-fold internal section, and the profile is exactly that public half, so `scripts/sync-profile.sh` generates it from everything above the fold. Two enforcement points, because they fail differently: - a pre-commit hook regenerates it, so the drift cannot be committed; - `--check` runs in CI ahead of the existing link checker, so a machine without hooks installed cannot push it either. CI is where it matters. Staleness is invisible to `check-readme-content.sh` — every link in a stale page still resolves perfectly. The generator refuses rather than guesses: no fold marker means it cannot tell public from internal, and a silent full copy would publish the roadmap on the org's front page, so it exits 1. It also refuses to write an empty file. Sabotage-verified in both directions: hand-editing profile/ is reverted, and a root-only edit — the exact bug above — propagates instead of drifting. The hook chain converges (two consecutive `pre-commit run --all-files` are clean), so the generator and mdformat do not fight over the file. Also corrects the `.pre-commit-config.yaml` comment that called README.md "the org profile", which is the misconception that produced this. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The Status column carried six badge URLs, which is what made those rows ~250
characters wide and the table unreadable in source. Status is now one row above
the table, and the table says what it is: the toolchain, three tools that stand
alone and compose.
`jbx` comes out of the table entirely. It was sitting in there as a peer of the
three, when it is the thing you install first and reach the others through —
and it was the one row whose "Get it" was a curl line rather than a package.
It is stated above the table now, with `just-runit` named as the same runner's
full form.
Three things the old column got wrong, all of which the consolidation fixed by
construction rather than by noticing:
- the just-bashit CI badge appeared TWICE, because just-runit had its own row
and ships from that repo;
- just-bashit had no version badge at all, though it publishes to PyPI
(v0.4.1);
- three bare "CI passing" badges were indistinguishable, since GitHub's
native badge takes no label.
So the CI badges are shields-rendered with explicit `<repo> CI` labels. shields
was already a dependency here for the PyPI badges, and it is what makes a
single row legible.
Version badges are pinned `color=blue`. shields colours a version badge by
semver, and every package in the org is 0.x — which it renders orange, reading
as a warning about nothing.
Every badge verified to render real data, not just to return 200: three
`passing`, and v0.4.1 / v0.57.0 / v0.3.10. A shields URL that 404s its upstream
still answers 200 with an error badge, and the link checker in CI would pass it
— the same "checker aimed at the wrong property" that let the stale org page
through in the first place.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
It was undersold twice over: first as a peer row among the three tools, then as a bold sentence. It is the thing you install before anything else and reach everything else through, and the page never showed that. A single-cell HTML table, which GitHub renders as a bordered card. Markdown inside survives (blank lines around the content), and mdformat leaves the block alone — verified, not assumed, and the hook chain still converges over two full runs. The card leads with what jbx IS, then shows the three shapes of use that matter — an alias, a namespaced script, a raw GitHub URL — so the namespace model is visible without reading the internal section. The features that were buried in prose further down (PEP 723 inline deps, cache TTL, checksum verification, sandboxed env) are named in one line. `Get started` keeps the curl, because it is a copy-pasteable walkthrough and breaking that to avoid a second occurrence would trade a real property for a cosmetic one. Its comment no longer repeats "the only curl you need" — the card owns that claim now. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`check-readme-content.sh` asks whether every URL answers. A page with broken markup passes that perfectly — which is the same shape as the bug that let a stale org page ship: a checker aimed at the wrong property. The concrete exposure is the new `jbx` card. Its markdown is nested inside an HTML block, and that only parses as markdown when blank lines separate it from the tags. Nothing in this repo could see it go wrong. Rendered through GitHub's own markdown API, in `markdown` mode — NOT `gfm`. That distinction is load-bearing and cost a wrong conclusion on the way here: `gfm` is comment semantics, where every newline becomes a <br>, so a hard-wrapped paragraph renders as a stack of broken lines and the check would fail a page that is perfectly fine. Every expectation is DERIVED from the source — fences, headings, images, tables — so adding a code block or a badge needs no edit here. **The first version of this check was decorative, and the sabotage proved it.** Removing the blank line after `<tr><td>` left it fully green. Measured why: GitHub keeps only the FIRST line inside the HTML block raw and parses the rest as markdown, so the fence and the bold text still render and only the heading degrades to literal "### ...". Four assertions, none of which looked at headings. The heading count is what makes this a gate, and with it the same sabotage now fails, naming the fix. Headings are counted outside fenced regions, because this page has `# comment` lines inside its shell blocks and they are not headings. Also consolidates the scripts. I had put `sync-profile.sh` in `scripts/` while `check-readme-content.sh` lived in `.github/scripts/` — two homes for the same kind of thing, in a repo whose whole subject this week is peer copies. All three live in `.github/scripts/` now; the pre-commit `files:` pattern was pointing at the old path and would have stopped firing when the script itself changed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
1 participant
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.
The org front page was advertising two things that are no longer true.
just-runit (jb)The tools table listed the runner as
jb— two rows above just-buildit, the PEP 517 backend, in the same table. That is the collision in miniature: one token meaning the org, the backend, and the script runner at once, on the page that introduces all three.The runner is
just-runit/jbx. The backend keepsjust-buildit— it is the one that actually builds.Two manifests became one
jb.tomlandjb-deps.tomlhad separate bullets and separate schema blocks. They are one file now,bootstrap.toml, carrying both halves: the system-package groups and the[tools.*]table. The schema section shows one example instead of two.The name is deliberate: it describes what the file declares — what must exist before the language ecosystem's own package manager can run — rather than who reads it.
jb.tomlwas named for a tool that never opened it, and two different tools already did.Roadmap: jm's row is TICKED
This reverses what this PR body said before. It originally un-ticked
just-makeit new emits …, on the grounds that jm still emitted the old name (just-makeit#935). That has since shipped — just-makeit#936 merged, 0.57.0 is released and on PyPI — so the row is ticked and cites the release.Added the rename itself to the completed list, next to the earlier
jbs-deps.toml → jb-deps.tomlone, with a pointer to just-bashit#30 for the deprecation removal.Rebased onto main (was DIRTY)
Main had moved five commits. Three conflicts, all the same shape — both sides edited the same line — resolved by taking both changes rather than picking a side:
pip installjb→jbxbootstrap.tomlpip install just-makeitMain's ", and CI" removal is a genuine correction and was kept — verified against jm:
jm newwrites no workflow, CI comes from the separatejm cicommand.Two further old-name references lived only in the Makefile-standard section main added after this branch forked, so the original sweep could not have seen them: the
Required filestable row and the adoption sentence beneath it.Decision log: struck through, not deleted
A log records what was decided, so reversed entries stay visible and are marked. Two are now false:
jb-filename prefix — that decision is the very mistake this rename corrects (its reasoning, that the name is org-level, survives and is whybootstrap.tomlis too)jbmay conflict … falls back tojust-buildit— cannot happen now;get-jb.shinstalls neither name and prunes both on upgradeThe Shipped row claiming conflict detection for
jbis marked superseded for the same reason.Two pre-existing blemishes, both on main
+ 25Reworded so the file is mdformat-stable;
pre-commit run --all-filesis green and idempotent.Part of