Rust on PHP Boy Scout

The scaffolder that won't hand you code that doesn't compile

Fri, 17 Jul 2026 00:00:00 +0000

Most scaffolders hand you a stub. You run the generate command, you get a file with the right shape and a // TODO: implement where the actual work goes, and the rest is on you. That’s fine, it’s upfront, and it’s most of what the rtb scaffolder does too: it’s the Rust port of the go-tool-base one, it works from a single manifest, and it regenerates without clobbering the code you’ve written. If you want the whole tour, those three cover it.

This is about the one bit they don’t, which is what happens when you ask the scaffolder to write the implementation, not just the stub.

rtb generate command --prompt "add a command that lists the user's pinned repos" doesn’t drop a TODO. It drafts the actual command, with AI doing the drafting. Which sounds great in a demo and is a menace in practice, because AI-drafted code that doesn’t compile is strictly worse than a stub. A stub at least admits it’s empty. A plausible-looking command that references a function that doesn’t exist, or borrows something it can’t, or compiles but fails its own test, costs you more time to discover and unpick than writing it yourself would have. The generation isn’t the hard part. Trusting the output is.

Which is why the real work didn’t go into the generating at all. It went into ai/verifier.rs, a repair loop wrapped around the one grader in the Rust ecosystem that cannot be sweet-talked: cargo.

It runs in stages, and each stage is a gate. cargo check: does it compile? If not, the compiler’s error goes straight back to the AI as the next instruction, and it tries again. Then cargo clippy: is it idiomatic, does it trip any lints? Same deal, the lint output is the prompt for the next pass. Then cargo test: does it actually do the thing? A failing test is just another error to feed back. The loop only stops when all three are green, or when it hits --max-repair-iterations and gives up and tells you, rather than handing you something broken with a confident smile.

That cap is there on purpose, by the way. The loop is bounded on purpose, because AI repair loops have a lovely failure mode where they churn forever, each pass convinced it’s nearly there, burning tokens and time on something that was never going to converge. So there’s a cap, and when the cap is reached the scaffolder stops, tells you it couldn’t get there, and leaves you the last attempt plus the errors. That’s a far better outcome than the alternative, which is a tool that either loops to infinity or ships code that doesn’t build.

The bit I’m most attached to, though, is --agentless. It short-circuits the whole AI path. No drafting, no repair loop, no model in the chain at all, just the deterministic templating you’d get from any other scaffolder. And I built that in deliberately, because the moment an AI step becomes load-bearing in a tool other people depend on, you’ve added a requirement that there’s a model available, a network, an API key, and a budget. Sometimes you want none of that. CI that has to be reproducible. An offline machine. A change where you simply don’t want a model anywhere near the diff. --agentless keeps the AI an accelerator rather than a dependency, and a tool that can’t run without a model is a tool with a single point of failure you didn’t choose.

Generating the code is the cheap bit, and verifying it is the actual product. Anyone can wire a model up to write a Rust function. What makes it a tool and not a party trick is that nothing it writes gets anywhere near your project until cargo has had its say. The AI writes the first draft. Cargo decides whether you ever see it.

Which CLI library should you start with?

Mon, 13 Jul 2026 00:00:00 +0000

You’ve decided to build a command-line tool. Good. And before you’ve written a single line of the thing it’s actually meant to do, you hit a decision that feels far more permanent than it should: which library parses the arguments. You go looking for the answer, and instead of an answer… you get a scrap. The Go crowd will tell you flag, or Cobra, or urfave/cli, usually with a bit of heat. The Rust crowd will tell you clap, and then argue about how you ought to hold it.

I’ve shipped CLIs in both languages, and wired both into frameworks other people build on (go-tool-base and rust-tool-base). So here’s the map I wish I’d had. Not “the best one”, because there isn’t one, but where to start, and the single thing that tells you when you’ve outgrown it.

Go: a ladder you climb

Go hands you a perfectly good argument parser in the standard library, flag, and for a great many tools that is the entire answer. A couple of options, no subcommands, done:

name := flag.String("name", "world", "who to greet")
flag.Parse()
fmt.Printf("hello, %s\n", *name)

No dependency, no ceremony, and it’s already on your machine. If your tool is one verb and a handful of flags, stop reading and use this. Reaching for anything bigger is just wiring you’ll maintain for nobody’s benefit.

The moment flag runs out of road is a specific one, and it pays to know exactly where it sits… nested subcommands. The instant you want mytool build and mytool deploy to be separate commands, each with its own flags and its own --help, flag has nothing for you and you’re hand-rolling a tangle of switch statements. That’s the signal to climb.

At the top of the ladder is Cobra. It’s the one behind kubectl, docker, hugo, gh and helm, north of 170,000 projects all told, so if you’ve ever used a Go CLI you’ve used it. Subcommands, generated help, shell completions, man pages: all the furniture a “grown-up” tool eventually wants. The cost is ceremony. A cobra.Command per verb, usually Viper alongside it for config, and a fair pile of boilerplate before the tool does anything at all.

Between the two sits urfave/cli, the option people forget to mention in the fight. It does subcommands like Cobra, but with a lighter, more declarative feel, and if Cobra’s structure looks like more than you need, it’s the sensible middle rung.

So Go is a genuine ladder: start on flag, and climb to a framework the day subcommands arrive. Or don’t wire Cobra and Viper together yourself at all. That assembly is precisely the job go-tool-base wraps up for you, which is a whole series of its own. A funnel, I’ll grant you, but a fair one.

Rust: a ladder you descend

Rust is a different shape entirely, and that difference is the interesting part of this whole question.

There’s no argument parser in Rust’s standard library, and there’s no real fight over which crate to use either, because one of them won and won decisively. clap has getting on for a billion downloads and is a dependency of some sixty-odd thousand other crates. It’s the default in the truest sense of the word: it’s what people reach for without stopping to think, and it scales from a single flag to a deep tree of subcommands without you ever swapping libraries. One struct, subcommands and all:

#[derive(Parser)]
struct Cli {
 #[command(subcommand)]
 command: Command,
}

#[derive(Subcommand)]
enum Command {
 Build { target: String },
 Deploy { #[arg(long)] dry_run: bool },
}

That’s the derive style, macros hung on your structs, and it’s the ergonomic default (there’s a runtime builder API too, for when you’re assembling commands dynamically). It’s what we use in rust-tool-base, and the reasoning was nothing exotic. We already knew CLI conventions well, we knew rtb needed the configuration depth only a heavy-hitter gives you, and clap’s sheer popularity made it the boring, sensible bet. When a crate is that dominant, choosing it is the low-risk move, and rtb goes a step further and generates the clap wiring so you never write that struct by hand at all.

Which is why the Rust ladder runs the other way. In Go you start small and climb up toward a framework. In Rust the framework is the ground floor, and the only real question is whether some specific pressure justifies stepping down to something smaller:

pico-args or lexopt when binary size and compile time genuinely matter and you can live without generated help. Zero or near-zero dependencies, and you write the usage text yourself. Grand for a small, sharp tool.
argh when you want the derive ergonomics but lighter than clap, and you don’t mind that it follows Fuchsia’s conventions rather than the Unix ones your users will expect.
bpaf when your parsing is genuinely unusual and you’d sooner compose it from combinators, while keeping the niceties like completions.

Every one of those is a step down from clap for a reason you can actually name. Without such a reason, clap is the answer, and that isn’t laziness. It’s the ecosystem having already done the choosing on your behalf.

(One wrinkle worth a footnote: clap’s “global” flags don’t behave the way you’d assume once you start nesting commands, which cost me an afternoon and a post of its own.)

Same rule, opposite ends

Strip the two languages back and the principle underneath is identical: use the smallest thing that fits your constraints, and let a real need, not a hunch, be the thing that moves you off it. What’s genuinely interesting is that the two ecosystems put the default at opposite ends of that rule.

Go’s default sits at the bottom, because the standard library gives you flag for nothing and moving up to Cobra is a switch you make on purpose. Rust’s default sits at the top, because the standard library gives you nothing at all and one crate grew so dominant that starting anywhere else is the choice you’d have to justify. Go makes you pick and grow into it. Rust makes you descend under pressure.

So the real answer to “which should I start with” isn’t a library. It’s a direction. In Go, start at the bottom and climb the day the subcommands turn up. In Rust, start at the top and only ever climb down, and only when something forces your hand. Either way, you’ll know the exact moment you need to move, which is the only thing the question was ever really asking.

Cover: the Go gopher by Renée French (CC BY 3.0) and Ferris (CC0), reimagined in cut paper.

A flag is not a setting

Sun, 28 Jun 2026 00:00:00 +0000

I was reviewing a change to rust-tool-base’s scaffolder when a word stopped me dead. rtb generate config-field. I couldn’t have told you why in that first second… I looked at it and just knew it was wrong.

The verb there is generate, and the verb is fine. It was the noun that grated, config-field, the name of the thing being made. Renaming it is a small change. It’s also a breaking one, and a gut feeling is no reason to break someone’s command, so before I touched it I went and worked out what the instinct was reacting to.

Accurate, and still wrong

Here’s the awkward bit: config-field is correct. The thing it makes really is a field on a config struct. If that name lived deep in a package, somewhere only another developer reading the source would ever trip over it, it’d be fine. The code’s audience is me, and “config field” is exactly what the code sees.

But it doesn’t live deep in a package. It sits right out on the command line, on the one surface a user actually types, and a name out there has a different job. It has to telegraph what it does to someone who has never read a line of the source, in words a layperson would reach for. By that test config-field fails, and not because it’s wrong. It fails because it’s right about the wrong thing. It describes the plumbing when all the user wants is to turn on the tap.

That’s the rule I keep coming back to anywhere a person actually touches the tool: accurate is the floor, not the bar.

What the noun names

The right name falls out of what the thing actually is, so I went and pinned that down. rtb’s scaffolder makes three different things, and the noun is how you pick which:

rtb generate command <name> # a new subcommand
rtb generate flag <name> # a command-line argument on a command
rtb generate setting <name> # a field on the tool's typed config

A flag and a setting sound like cousins, but they answer two different questions: where does the value come from, and how long does it live. A flag is something the user types for a single run (a clap argument, in Rust terms), like deploy --region eu or --dry-run. Transient, scoped to the one command. A setting is a typed field on the tool’s AppConfig, read from its layered config: a file, the environment, or a one-off override on the CLI. Persistent, and tool-wide. (The full contrast is its own doc now.)

Put the two side by side and the old name gives itself away. flag says what the thing is to a user. config-field said what it is to the code. One tells the truth at the surface; the other leaks an implementation detail you were never meant to care about.

Why they’re two things at all

This is the bit that makes the rename honest rather than fussy, and it’s where rust-tool-base and go-tool-base part ways.

In go-tool-base, a flag and a setting are pretty much the same object. cobra and viper (Go’s CLI and config libraries) fuse them: you bind a flag, viper reads its value from a config file or the environment, and you’re done. One persistent flag laid over a config bag. That’s no compromise, it’s an excellent convenience abstraction, gtb leans on it to the hilt, and for what it’s worth it’s the model I personally find the simpler of the two. One mechanism, one thing to keep in your head.

Rust won’t hand you that fusion, and it’s right not to. rtb’s config is a typed AppConfig (built on figment, a Rust config library), not a dynamic get_string("key") bag, so a command-line argument and a config field genuinely are different types with different lifetimes. Splitting them isn’t rtb being puritanical about it. It’s the shape Rust’s type system gives you, and the framework leans in and makes the most of it. The rtb version is, no argument, the more type-safe of the two.

So neither is better. They suit different paradigms, and both do the job beautifully. But the knock-on for naming is concrete. Once a flag and a setting really are two different things, calling one of them config-field doesn’t just expose the plumbing, it tells a small lie: it implies a setting is the same kind of object as the struct field it happens to sit in. setting tells the truth. This is the thing you configure once and the tool remembers, the sibling of flag.

(rtb has form here, mind. “flag” already pulls double duty: a runtime feature flag and a compile-time Cargo feature are two more genuinely different things the framework keeps deliberately apart. Stretch one word across that many concepts and naming each one precisely stops being pedantry and becomes the only way anyone keeps them straight.)

The change

So config-field became setting, and picked up its mirror image remove setting to round out the trio of command / flag / setting. It’s a breaking change, rtb generate config-field is gone for good, and it earned its keep. The cost is a line in a changelog. The return is a command surface that says what it means.

Name the tap

The gut reaction was right, but the gut reaction was never the point. The point is what it was reacting to: a name, out on a surface a human uses, describing the machinery instead of the job. config-field was accurate. It still made the user stop and think about a struct field when all they wanted was to set something up and get on with it.

Nobody turning on a tap wants to think about the pipework behind the wall. Name the tap.

Everyone wants Rust's safety, nobody wants Rust

Sun, 14 Jun 2026 00:00:00 +0000

This spring, the better part of a million lines of Zig quietly became a million lines of Rust. Bun, the JavaScript runtime that was the showcase for “you don’t need a borrow checker, you need good tools and a steady hand”, looked at its own memory bugs and switched teams. Around 99.8% of its test suite passed on the rewritten code, a clutch of memory leaks closed in the move, and the maintainers said the quiet part out loud: the previous release would be the last one written in Zig.

It’s tempting to read that as Rust winning, hoist the flag, and move on. I don’t think that’s quite the story, and the more interesting one is happening everywhere else at the same time.

Because Bun is the exception that went all the way. Everyone else is trying to get the safety without the Rust, and watching how they’re going about it tells you more than one runtime’s heroic rewrite does.

What everyone’s actually after

A quick level-set, because not everyone reading this writes systems code daily. “Memory safety” is the property that a program can’t read or write memory it has no business touching: no using a value after you’ve freed it, no running off the end of an array. It sounds niche. It is, by most counts, behind something like 70% of serious security vulnerabilities, which is why governments and trillion-dollar companies suddenly care a great deal.

There are roughly three ways to get it. Rust uses a borrow checker: a compiler that flatly refuses to build your program unless it can prove, before it ever runs, that you never touch memory after you’re done with it. The price is that it argues with you the entire time you’re writing. The product is that an entire category of bug becomes literally unwriteable. Go (and most managed languages) uses a garbage collector: a runtime janitor that frees memory for you, so you mostly can’t get it wrong, at the cost of some overhead and a little control. And then there’s the old way, the one most code on Earth still uses: trust the developer to get it right, and add an escape hatch, usually a keyword like unsafe, for the bits where they promise they have.

The retrofit trend is everyone in that third camp trying to inch toward the first two without rewriting the world.

Rust didn’t invent any of this

Worth saying plainly, because the fan club rarely does: Rust invented almost none of it. The borrow checker is, by Rust’s own admission, Cyclone’s region-based memory management, from a safe-C experiment in the early 2000s, welded to affine types out of linear logic, ideas that predate Rust by decades. And it goes beyond the borrow checker. Rust’s exhaustive pattern matching came from ML and Haskell. Its “errors are values, and there is no null” approach, Result and Option, is Haskell’s Maybe and Either in work boots.

What Rust did, and did better than anyone before it, was taste and integration: it curated thirty-odd years of academic research into one coherent language and proved the ideas could carry real systems code rather than just research papers. That is the genuine USP, and it’s why the rest of the industry is now shopping from the same shelf. Pattern matching has landed in Python and Java, with a proposal in flight for C++26. Swift 6 shipped compile-time data-race safety, its Sendable machinery a close cousin of Rust’s Send and Sync. The borrow checker just gets the headlines because it’s the hardest bit to copy. Which makes the title almost too literal: everyone wants Rust’s safety, and they are quietly adopting its mechanisms one feature at a time.

Credit where it’s due: C# is doing this properly

The example that made me sit up is C#. In C# 16, Microsoft is redefining the unsafe keyword that’s been in the language since version one. Instead of unsafe marking a lump of syntax, it now marks a contract: a promise the compiler can’t verify and a human has to read and uphold, with documentation and static analysers nudging you to take it seriously. They’re even floating badges on NuGet packages to show which ones have opted in.

My first instinct with any retrofit is suspicion, because bolting safety onto a language after the fact has a long and miserable history, and an escape hatch that’s easy to reach is an escape hatch people will reach for the moment they’re in a hurry. But this isn’t a bolt-on. Taking the keyword that’s already there and giving it real teeth is working with the grain of the language instead of stapling a second safety system alongside the first. That’s honest engineering, and it deserves the credit. It genuinely raises the floor.

A contract is not a guarantee

Here’s where my enthusiasm meets its limit, and it’s a distinction I happen to have a lot of skin in.

C#’s redefined unsafe makes dangerous code visible and reviewable. That is a real improvement, and most teams would be better off for it. But visible and reviewable still means a human has to honour the promise. It’s a sign on the door. Rust’s equivalent is a wall: in rust-tool-base I put #![forbid(unsafe_code)] at the top of all eleven shipping crates, and forbid is not advice, it’s a refusal. The compiler will not build a crate that contains unsafe, full stop, and unlike its softer sibling deny, you can’t quietly switch it back off in a corner of the code where it’s inconvenient. The whole reason I use forbid and not deny is that I don’t trust future-me, in a hurry, not to reach for the hatch.

So when I look at the C# work I think: good, genuinely good, and they should take it further. A contract a human upholds is not the same kind of thing as a proof a compiler enforces, and the trend, if it’s serious, points at enforcement. Visible is better than invisible. Impossible is better than visible.

Discipline never scaled, and that’s not an insult

The objection I keep hearing, and that a younger me would have made, is that any language can be memory-safe if you’re just disciplined enough. And it’s true, in the way that any house can be tidy if you never get busy. In the before times we shipped memory-safe C with code review and valgrind and sheer bloody-mindedness, and it worked, sort of, at small scale.

It doesn’t scale, and Bun is the proof sitting on the table. That wasn’t a sloppy team learning the basics. It was a strong team, betting publicly on the discipline-and-good-tools model, and the memory bugs piled up anyway until the honest move was to let a compiler take the job. Discipline failing at scale isn’t a moral failure of the engineers. It’s just what happens when you ask humans to hold a thousand invariants in their heads across a million lines. Delegating that to a machine that never gets tired or rushed isn’t laziness. It’s the entire point of having compilers at all.

The part that changed my mind

I learned most of my Rust by building rust-tool-base with an AI alongside me, leaning on it to explain the borrow checker, suggest the idiomatic shape, and check my work. And somewhere in that I noticed the thing I now can’t unsee: the borrow checker is exactly as good a guardrail for the AI as it is for me.

A model, like a tired human, will write a confident use-after-free without blinking. In Rust it simply doesn’t compile, so the mistake never reaches me. What that does is move the whole error surface. The bugs that survive into review aren’t memory bugs or lifetime bugs or data races, the language has eaten those, they’re errors of logic: the code is safe and wrong. And logic is precisely where I want my attention, and the AI’s, because it’s the part a human has to own and the part the models are getting better at every month. (I split my AI work across a few providers for their different strengths, so this is not a pitch for anyone’s logo. The effect is the same whoever’s doing the typing.)

Which dissolves the one argument that ever really kept people out of Rust. “The borrow checker is too much friction” was always the case for the defence. But Bun’s million-line rewrite was done largely with an AI, because an AI is very good at paying a tax that is tedious and mechanical rather than creative. The friction is getting cheaper to pay at exactly the moment the guarantee is getting more valuable to have. In an AI-assisted world, a language that proves safety is worth more, not less, because it fences in the machine’s mistakes as firmly as your own.

None of this means rewrite everything in Rust

I want to be careful not to land somewhere smug, because most software does not need what Rust offers and pretending otherwise is how you end up rewriting a CRUD app nobody asked you to. Garbage collection is not a failure state. Go’s collector keeps getting meaningfully better, my own go-tool-base is GC’d top to bottom and I have never once wished it weren’t, and “safe-by-default with a GC” is the right answer for a vast amount of the work most of us do. The borrow checker is a price, and you should only pay it when the thing you’re buying, that last class of guarantee with no runtime cost, is something your stakes actually need.

What it comes down to

The question was never “is it as safe as Rust”. That framing turns everything into a loss for everyone who isn’t Rust, which is silly. The useful question is: what does your language make the default, and how hard does it make the escape hatch to reach? Go makes safety the default and charges you a GC. Rust makes it the default and charges you the borrow checker. C# is moving its default in the right direction and, for now, leaves the hatch as a promise rather than a wall.

Credit the retrofits, they are raising the floor for an enormous amount of code that was never going to be rewritten. Just don’t mistake the floor for the ceiling, or a contract a human signs for a guarantee a compiler keeps. Everyone wants Rust’s safety, and the interesting question, now that an AI will pay the toll for you, is who still has a reason not to want it.

Widen the lens past Rust, though, because that’s where the news gets genuinely good. We’re at a turn in how languages evolve. Compile-time rigour is spreading rather than retreating: borrow checking is reaching the Python family through Mojo, static typing long since conquered JavaScript, and even the managed languages are turning their escape hatches into something you have to argue with. More of our safety is quietly moving from “remember to” into “can’t not”. And the one thing that always made the strict path hard to start down, the friction, is being absorbed by an AI that will happily learn the rules so you can lean on them. I’ve been at this long enough to distrust a rosy forecast, but I’ll put my name to this one: the outlook for software that’s safe and secure by default has never looked better.

Three traps release-plz sets for a Rust workspace

Fri, 05 Jun 2026 00:00:00 +0000

I wrote up the two days I lost releasing a seventeen-crate workspace to crates.io as a war story, wrong turns and all. This is the other half: the field guide, so you don’t have to lose the same two days.

release-plz is a genuinely good tool, and none of what follows is a bug. It’s three behaviours that are entirely within its design and will still ambush you the moment you point it at a Cargo workspace rather than a single crate. Mildest first, because the third is the one that actually ate my release.

First, what release-plz is doing

In one line: it’s release-please for cargo. It keeps a Release MR open, bumps your versions and per-crate changelogs from your Conventional Commits, and when that MR merges it publishes every crate to crates.io and tags the release. On a workspace where N crates all share one version, “the release” is N publishes and N tag operations. Hold on to that N. It’s hiding behind all three traps.

Trap 1: the default tag template is built for one crate, not a workspace

You will reach for one tag per version, and for me it was more than tidiness. I wanted to ship the whole framework as a single release: one v0.5.1 covering all seventeen crates, because that was the compatibility promise I wanted to make. Use the crates that share a version and they’re guaranteed to work together. A single tag felt like the natural way to say “this is one coherent release of the whole thing” (and it didn’t hurt that the repo already had a v0.5.0 tag from before release-plz, so one unified tag also looked like continuity). So you either set this, or, worse, you leave git_tag_name unset assuming the default does something workspace-aware:

git_tag_name = "v{{ version }}"

Here’s the catch. release-plz’s default git_tag_name is v{{ version }}, and release-plz tags per crate. So the first crate publishes and creates the tag v0.5.1. The second crate publishes and tries to create v0.5.1 again:

ERROR failed to create git tag 'v0.5.1'
 "message": "Tag v0.5.1 already exists"

By the time you read that error, the first crate (and on a retry, the next, and the next) is already live on crates.io, and crates.io publishes are forever. Leaving the line out doesn’t save you, because the default is the same single-crate-shaped template. This is the trap I walked straight into on the release commit.

Trap 2: “one release for the whole workspace” isn’t a setting, it’s a category error

The natural next thought is “fine, I’ll keep one tag but configure release-plz to roll the crates into a single release.” There’s no knob for that, and chasing one is a waste of an afternoon. release-plz’s model is per-crate all the way down: per-crate tags, per-crate GitLab/GitHub releases, per-crate changelogs. “One unified release for the whole workspace” isn’t an option it withholds, it’s a shape it doesn’t have.

So you stop fighting it and set the per-crate templates explicitly:

git_tag_name = "{{ package }}-v{{ version }}"
git_release_name = "{{ package }} v{{ version }}"

Now each crate gets its own tag (rtb-assets-v0.5.1, rtb-config-v0.5.1, and so on) and its own release. It’s more objects per version than you wanted, but it’s the grain the tool works in, and once you accept that the collisions stop.

This is where I had to pull apart two things I’d quietly merged in my head: the version and the tag. The compatibility promise I cared about, that crates sharing a version work together, is carried by the version, and release-plz keeps every crate on the one workspace version no matter how it tags them. The tag is just a label pointing at a commit. I’d wanted a single tag to mean “one coherent framework release”, but the coherence was always in the shared version number, not in the tag. Once that landed, seventeen tags stopped feeling like seventeen releases of seventeen different things and started looking like what they are: seventeen labels on one versioned release. The version is not the tag. If you still want one human-facing narrative for the whole thing, keep a hand-written root CHANGELOG.md alongside the generated per-crate ones, rather than trying to make release-plz aggregate.

Trap 3: a release reads its config from the release commit, not HEAD

This is the small one, and the one that cost me the most, because it makes the fix for Trap 1 look like it isn’t working.

When release-plz runs a release, it does not read release-plz.toml from your working tree. It reads it from the release commit, the commit that first introduced the version it’s releasing. So picture the obvious recovery: you hit the tag collision, you realise your template is wrong, you fix it in a follow-up commit and push to main. Your fix is real. It’s committed. It’s on the default branch. And it is completely ignored, because the version hasn’t changed, so the release commit release-plz reads from is still the old one with the old template.

I didn’t take this on faith. With the corrected per-crate template sitting on HEAD, the CI release job still tried to create the unified tag, pinned to the old commit:

ERROR failed to create git tag 'v0.5.1' with ref 'f6de975...'
 "message": "Tag v0.5.1 already exists"

That ref is the release commit, not the HEAD that held my fix. And the cruel part: release-plz release --dry-run on your laptop reads your working-directory config, so it renders the shiny new per-crate tags and tells you you’re sorted. CI runs the real thing against the release commit and does something else entirely. Same config file, two different answers depending on who’s asking, which is why the war story has the title it does.

The operational rule that falls out of this: any release-plz config change that affects how a release behaves has to ride along with a version bump, or it does not apply. A “fix-up” commit on its own is a no-op.

If you set one thing

If you run release-plz on a multi-crate workspace and you change a single line from the defaults, make it the tag template:

git_tag_name = "{{ package }}-v{{ version }}"

And set it before your first release, not during it, so it’s already in the commit that introduces the version, because that’s the only commit a release will ever read it from. Everything else here follows from two facts: the grain is per-crate, and CI reads history while your laptop reads your working tree. Trust the history.

None of this is release-plz misbehaving. Every bit of it is documented and deliberate. It just isn’t where you’ll think to look until it has published six crates you can’t take back, which is roughly how I came to know it so well.

Same config, two answers

Wed, 03 Jun 2026 00:00:00 +0000

Let me confess a small heresy first, because it’s the reason any of this happened. After a career spent as a branching man, gitflow, gitlabflow, a tidy develop branch and a careful dance of merges, I’ve come round to trunk-based development. I resisted it for years. It felt like working without a net.

What changed my mind was working solo with an AI pair. The branch ceremony that earns its keep on a team of eight is just drag when it’s me and a model at two in the morning. So I’ve softened on “main is always deployable” and let the trunk act as the develop branch, with tagged releases as the actual source of truth. For compiled languages, where the artefact you ship is a built, tagged thing and not whatever’s on a server right now, that finally clicks.

I’d already rolled this out on my Go and Terraform projects with releaser-pleaser, a GitLab-native take on release-please: a bot keeps a Release MR open, and merging it cuts the tag. It’s the same model I wrote about when the infra repo moved to plan-on-merge, apply-on-tag. Lovely. Then I came to do the same for rust-tool-base, and Rust, being Rust, had opinions.

Rust brings its own toolchain

releaser-pleaser is happy to tag a repo and write a release. What it does not do is cargo publish seventeen crates to crates.io in dependency order. Rust’s release story isn’t “push a tag and let a runner build a binary”, it’s a whole publishing pipeline with a public registry at the end of it, and that registry has rules of its own. So for the Rust workspace I reached for the tool built for exactly that job: release-plz. Same Release-MR shape, but it understands cargo, versions every crate, and publishes the lot.

That was the right call. Getting it to actually do it was where I spent two days I’d quite like back.

The gauntlet before the gun

Before I got anywhere near the interesting failure, there was a run of CI papercuts, the sort where every fix politely reveals the next one. GitLab checks out a detached HEAD, and release-plz wants to be on a branch (“HEAD does not point to a branch”), so you re-attach. Then the default CI_JOB_TOKEN can’t push to a protected repo, so you point the remote at a real token. Then release-plz assumes you’re on GitHub and errors that the repo “is not hosted in GitHub”, so you tell it --forge gitlab. Then it refuses to run at all because the pages job left a public/ directory lying about and the working tree is “dirty”, so you stop pulling artefacts into the job.

Five merge requests before the thing would even start doing its actual job. You can read the scar tissue in the before_script; every line in it is a fix for something on that list. None of it was hard. It was just death by a thousand cuts, and I was feeling quite smug by the time it finally reached the publish step.

I should not have been.

“Tag v0.5.1 already exists”

My release-plz.toml asked for one tag per release:

git_tag_name = "v{{ version }}"
git_release_name = "v{{ version }}"

That felt obviously right. It matched the repo’s existing v0.5.0 tag, it’s how a single-crate project tags, and the crates all share one workspace version anyway. One version, one tag. What’s to argue with?

release-plz, that’s what. It tags per crate. So it publishes a crate, creates the tag, publishes the next crate, and tries to create the same tag again:

INFO published rtb-assets 0.5.1
ERROR failed to release package
Caused by:
 0: failed to create git tag 'v0.5.1' with ref 'f6de975a75...'
 1: Response body: { "message": "Tag v0.5.1 already exists" }
 2: HTTP status client error (400 Bad Request) ... /repository/tags

The collision is annoying. What makes it a proper trap is the half-second before it: published rtb-assets 0.5.1. That happened. On crates.io. For keeps. A crates.io publish is forever, there is no unpublish, only a yank that still leaves the name and version burned. So every time my flaky pipeline limped one crate further and then fell over on the tag, it left another crate live on the public registry that I could never take back. By the time the dust settled, six of the seventeen were out there: rtb-assets and rtb-config, then on a later retry rtb-credentials and rtb-error, then rtb-app and rtb-redact. Two more permanent crates per failed run.

I assumed the default

My first fix was the clever one, and it deserves to be on display because it’s the whole lesson in miniature. I deleted the git_tag_name line. My reasoning: per-crate tags are release-plz’s native model, so surely its default does the right thing without me spelling it out. I was confident enough to write it into the commit message: “per-crate tags/releases (release-plz defaults).”

The next run collided on v0.5.1, exactly as before.

Because release-plz’s default git_tag_name is not per-crate. It’s the unified v{{ version }}. I had deleted a line that said the wrong thing and replaced it with a default that said the same wrong thing, then congratulated myself for tidiness. If I’d spent thirty seconds on the configuration reference instead of thirty seconds being clever, I’d have read that in black and white.

Same config, two answers

So I read the manual, and set it explicitly:

git_tag_name = "{{ package }}-v{{ version }}"
git_release_name = "{{ package }} v{{ version }}"

On my laptop, a dry run rendered exactly the per-crate tags I wanted. In CI, the very next run published another crate and then created the tag v0.5.1. The unified one. The wrong one. The one I had just, demonstrably, on main, replaced. Same release-plz.toml, two completely different answers depending on who was asking.

That one took me an embarrassingly long time to see. release-plz does not read your config from the working tree when it runs a release. It reads it from the release commit, the commit that introduced the version it’s releasing. My version was still 0.5.1, set days earlier on a commit that still carried the unified template. You can see it in the failure: the tag it tries to create is pinned to ref 'f6de975...', an old commit, not the HEAD that held my fix. Every edit I made at the tip of main was real, committed, and utterly invisible to the release of 0.5.1, because no version bump had created a fresh release commit for it to read. My fix was correct and inert at the same time. The dry run read my working directory and looked perfect; CI read history and did something else.

There is no config change that rescues an in-flight release. The version was already out, half-published, tagged wrong, and pointed at a commit I couldn’t edit without bumping the version, which I couldn’t cleanly do with six crates already live.

Doing it the way I’d have done it a year ago

So I stopped. Three retries deep, each one a seventy-minute CI cycle thrown at an opaque mismatch, six crates already immovable on crates.io, and a tooling problem I now understood well enough to know the tool was never going to dig me out of this particular hole. The question quietly changed from “why is it doing this?” to “am I going to keep grinding, or finish this the way I would have before I had clever tooling?”

I went manual. cargo publish, the remaining eleven, by hand, in dependency order: the leaf crates first and the rust-tool-base umbrella dead last, because it depends on all of them. crates.io rate-limits new crate names, so after a burst it simply made me wait, a roughly half-hour pause in the middle while the registry caught its breath and I caught mine. Then one v0.5.1 tag, cut by hand, and one GitLab release to match the convention. The next CI run came up green, for the gloriously dull reason that there was nothing left to do: every crate published, the tag already there.

Stop being clever and RTFM

The tool was never broken. Every single thing it did was documented behaviour I hadn’t bothered to read: that the default tag template is unified, that the model is per-crate, that a release reads its config from the release commit and not from HEAD. I assumed my way past the manual three times in a row, and each assumption cost me real, permanent state on a public registry that doesn’t take returns.

And that’s the part that actually stung, because I should have known better than most. I wasn’t a beginner here. I knew the Release-MR pattern cold, I’d shipped it half a dozen times with releaser-pleaser on my Go and Terraform repos. That familiarity was the trap. I trusted the pattern and skipped the tool, on the lazy assumption that something I understood well in one tool would behave the same in the next. release-plz carries the same design, but it’s a different tool, with its own defaults and its own idea of where the config lives. The pattern came across fine. The mechanics didn’t, and I never thought to check.

So here’s the lesson, written down in the hope it sticks this time: no matter how familiar I am with a pattern or a design, the moment I switch the tool that implements it, reading the manual is paramount. The familiarity is exactly what tempts you to skip it, and exactly why you can’t. (The narrower, more practical one, while I’m here: a config change that affects how a release behaves has to travel with a version bump, or it sits there looking applied and doing nothing.)

release-plz is genuinely good, and every release since has gone out clean on the first try, the way the rest of the CI now does. I just had to stop being clever long enough to read how it actually works. RTFM. I’ll get it tattooed eventually.

From allow_failure to blocking

Sat, 30 May 2026 00:00:00 +0000

There’s a special kind of CI job that everyone on a team quietly learns to ignore: the one marked allow_failure: true. It runs, it goes red, the pipeline goes green anyway, and after the third time you stop looking at it. I inherited six of those when I moved rust-tool-base’s CI to GitLab. Over a few days I turned three of them into real gates, and the interesting part was never the YAML. It was working out which ones had earned the right to block, and which hadn’t.

What allow_failure actually buys you

allow_failure: true is genuinely useful, and quietly corrosive. It lets a job report a problem without stopping the pipeline, which is exactly right for a check that’s noisy, not yet stable, or guarding against something you can’t fix this minute. The trouble is that a warning nobody is forced to act on is a warning nobody acts on. Leave a job advisory long enough and it becomes scenery: red, ignored, pointless. So an advisory check is really a promise, “I’ll make this blocking once it’s trustworthy”, and a promise you only ever mean to keep is just a lie you haven’t noticed yet.

When I migrated rust-tool-base from GitHub Actions to GitLab CI, the move landed six jobs as allow_failure: true: the macOS and Windows tests, the integration tests, cargo-audit, trivy, and coverage. That wasn’t laziness. A migration is the wrong moment to also be fighting flaky gates. But it left me holding six promises to either keep or admit I wasn’t going to.

A check earns the right to block

Here’s the rule I settled on. A check earns the right to fail your build when two things are true: it’s meaningful (a red result is a real problem, not noise) and it’s reliable (it goes red only when there genuinely is a problem, and it can actually run to completion). Flip a check to blocking before both hold and you haven’t raised the bar, you’ve taught the team to force-merge past red, which is worse than no gate at all, because now the red means nothing.

Three of my six crossed that line within a few days. Three deliberately didn’t. The reasons are the whole story.

trivy: blocked once there was nothing to block on

trivy scans the dependency tree for HIGH and CRITICAL advisories. It went across as advisory for an honest reason: the Cargo.lock at migration time already carried two known HIGH/CRITICAL advisories I hadn’t cleared yet, a path-traversal in gix-validate and a DNS-rebinding issue in rmcp. Make trivy blocking with those sitting there and the pipeline is red from day one, over problems I already knew about and was already fixing. So it stayed advisory until the dependency bumps cleared both, and then the allow_failure line came out. The gate never changed. The tree underneath it got clean enough to stand on.

integration-tests: blocked once it could actually run

The integration tests stand up a real Gitea in a Docker-in-Docker service and talk to it. They were advisory for a different reason: they couldn’t reliably run. dind needs a privileged runner, and the suite was resolving the container host with a hardcoded 127.0.0.1 that didn’t hold everywhere. Blocking a job that fails for infrastructure reasons rather than code reasons is the fastest way to make people distrust the entire pipeline. So the fix wasn’t in the YAML, it was making the thing dependable: privileged set on the runner, and the host resolved through the test library’s own get_host() instead of a hardcoded address. Once it ran the same way every time, it earned the gate.

coverage: blocked once it could run at all, then once it cleared the bar

Coverage is the two-step one, and my favourite, because it nearly didn’t make it for a thoroughly undramatic reason: it ran out of memory. cargo llvm-cov instruments every test binary, and linking hundreds of instrumented object files needs more RAM than the shared medium runner had, so the job bus-errored on the link. I tagged it onto a larger runner, and then the shared SaaS runners were switched off entirely, so the tag matched nothing and the job sat pending forever.

The fix was a self-hosted homelab runner with the RAM the instrumented link actually needs. I moved coverage there but kept it advisory for one run, to confirm the box could finish the build before I trusted it. It did, at 73.22% line coverage, so I set the gate to fail under 70% and made it blocking. Three points of headroom: enough that ordinary churn won’t trip it, tight enough that a real drop will. A coverage gate pinned to the current number is a tripwire that fires on the very next commit; set it a touch below and it catches regressions instead of normal life.

The three I left advisory, on purpose

The point was never “block everything”. Three jobs are still allow_failure in the current pipeline, deliberately. The macOS and Windows tests run on SaaS runners that bill by the minute; they’re worth running, not worth blocking every merge of a Linux-first project over a quota I’m choosing to ration. And cargo-audit stays advisory because cargo-deny already does the blocking advisory check: cargo-audit is a second opinion from a different database, and a second opinion that can veto isn’t a second opinion, it’s a duplicate gate that will eventually disagree with the first and block you on the difference.

That’s the same rule from the other side. Those three haven’t earned the right to block, because blocking them would cost more than it ever caught.

The upshot

allow_failure: true is fine as a waiting room and corrosive as a destination. Every advisory check is a promise to make it blocking once it’s both meaningful and reliable, and the job is to keep the promise or admit you won’t. trivy earned its gate when the advisories cleared, the integration tests when they ran the same way every time, coverage when it had a runner with enough memory and a threshold set just below the current mark. The three I left advisory earned that standing too, by costing more to block than they’d catch. The YAML is one deleted line per job. Knowing which line to delete, and when, is the whole skill.

Pure-Rust Git, no git binary

Wed, 13 May 2026 00:00:00 +0000

go-tool-base’s VCS support has two halves that get confused for one. One half talks to forge APIs (GitHub, GitLab) for releases and pull requests. The other talks to the .git directory on disk: clone, history, diff, status. This post is mostly about the second half, and specifically about a question that turns out to have three answers in Rust, only one of which I’d recommend: how do you actually do Git from inside a program?

A VCS subsystem with two halves

go-tool-base has a VCS subsystem, and it does two distinct jobs.

The first is forge APIs. GitHub and GitLab, Enterprise and nested group paths included. It authenticates, lists releases, fetches release assets, manages pull requests. The self-update machinery sits on this half, and it’s what a tool uses to ask “what’s the latest release?”

The second is local Git. go-tool-base also carries a RepoLike object, an abstraction over an actual Git repository on disk: clone it, read its commit history, diff two trees, check its status. This half doesn’t talk to a hosting service at all. It talks to the .git directory.

It would be easy to assume the second half grew out of the first. It didn’t, and where it actually came from is the part worth telling.

A capability ahead of its consumer

The RepoLike object wasn’t built for go-tool-base. It came from another project, where it had already proved itself, and it was pulled into go-tool-base on purpose, with a specific future consumer in mind: the code generator.

The plan is for the generator to use Git directly. When it scaffolds a new tool, that tool should start life as a Git repository, with a git init and an initial commit. When you later regenerate, the generator should diff the regenerated template output against your working tree to detect drift, the same idea as respecting your edits. Both of those are local Git operations, not API calls, so the generator needs a repository abstraction to call into.

That wiring isn’t finished yet. The generator doesn’t drive RepoLike today. But the capability is in place, deliberately, ahead of the consumer that will use it, because the alternative is bolting Git support on later under deadline pressure, and that’s how you end up with the wrong abstraction.

So when rust-tool-base was built, a repository abstraction was never in question. The Rust port carries the same capability for the same reason: a Repo type with init, open, clone, walk, diff, blame, status, commit, fetch and checkout, present and ready for the generator to wire into. The open question was never whether to have it. It was how to do Git from inside a Rust program, and there are three answers, only one of which is any good.

Three ways to do Git, and the one worth picking

Shell out to git. Run the git binary as a subprocess and parse its output. It works until it doesn’t. The binary might not be installed. It might be a different version with different output. Its output is formatted for humans and changes between releases, so parsing it is a standing liability. You’ve made an undeclared dependency on a program you don’t ship.

Link libgit2. libgit2 is the C library that reimplements Git as something you can call from code, and git2 is the Rust binding to it. It’s solid and widely used. But it’s a C dependency, which means a C toolchain in the build, and it’s consistently the single biggest source of cross-compilation pain in the Rust Git ecosystem. The musl builds, the Windows builds, the static linking: libgit2 is where they tend to break.

Use gix. gix is a reimplementation of Git in pure Rust. No C library, no subprocess. It’s just Rust code, and it compiles and cross-compiles like any other crate, because that’s all it is. It’s also generally faster, and being pure Rust it fits the no-unsafe-in-first-party-code story far more comfortably than dragging a C library along.

rtb-vcs is gix-first. The Repo type is built on it. There’s no git binary dependency, and there’s no libgit2 in a default build.

gix is still maturing, and a few write paths, push in particular, aren’t ready in it yet. For those, git2 (the libgit2 binding) is held in reserve as a documented fallback, to be wired behind an opt-in Cargo feature if and when a write path actually needs it. Until then a default build carries no libgit2 at all, and the common case, a tool that clones, reads history, diffs and commits, never pays its cross-compile cost. (The gix backend itself sits behind an opt-in git feature, which is exactly the feature-flag story from a couple of weeks back, doing real work.)

`Repo` is a foundation, not a façade

One design decision is worth calling out, because it came straight from a go-tool-base lesson.

It would have been easy to build Repo as a narrow façade exposing exactly what the scaffolder and the release-notes feature need today, and nothing else. That was rejected on purpose. go-tool-base’s RepoLike is itself the cautionary tale: it arrived from another project, settled into a sensible abstraction, and is already lined up to carry a consumer, the generator, that wasn’t driving its design when it was first written. A repository abstraction gets used by code that doesn’t exist yet. Build one as a narrow façade around today’s needs and you’ve guaranteed a rewrite the first time a downstream tool wants something slightly different.

So rtb-vcs’s Repo is built as a foundation: a sensible, reasonably complete vocabulary of Git operations that a tool author can compose richer behaviour on, without re-importing gix directly and re-deriving the framework’s auth and concurrency conventions. The errors back this up. gix’s error types aren’t leaked through the public API; they’re wrapped in semantic RepoError variants, so the backend could be swapped, gix to git2, or to something else entirely, without breaking a single downstream caller.

Stepping back

go-tool-base’s VCS support has two halves: forge-API calls for releases and pull requests, and a RepoLike object for local Git operations. The repo half arrived from another project and is wired in ahead of its intended consumer, the code generator, which will use it to initialise repositories for scaffolded tools and to diff regenerated output for drift.

rust-tool-base carries the same capability on purpose. Its Repo type is built on gix, a pure-Rust Git implementation, so there’s no dependency on an installed git binary and no libgit2 C library in a default build, which keeps cross-compilation clean. git2 stays an opt-in fallback for the few write paths gix can’t do yet. And Repo is built as a foundation for downstream tools, with the backend wrapped behind its own error type so it can be replaced without breaking callers.

clap's global flag, except in a passthrough subtree

Thu, 07 May 2026 00:00:00 +0000

--output json worked everywhere. On the top-level command, on every ordinary subcommand, wherever the user fancied putting it. Then it stopped working in exactly one place, and of course it was the subcommand I’d been clever about.

How the global flag is meant to work

clap has a lovely feature for this. Define --output text|json once at the top, mark it global = true, and it’s reachable from every subcommand: mytool --output json widget and mytool widget --output json land the same. You stop thinking about it.

The one place it goes missing

One subcommand, credentials, is a passthrough: it sets subcommand_passthrough = true, which makes clap capture everything after the subcommand name as trailing_var_arg and hand it on, the way cargo run -- ... passes the trailing args to your program rather than to cargo. The handler then re-parses those captured tokens against its own clap definition.

The trouble is that the captured tokens include --output. clap’s global = true propagation doesn’t reach a passthrough subtree, because the post-name tokens are taken as trailing_var_arg before the outer parser ever sees them. So in this one subtree the global flag isn’t applied, and worse, when the inner parser re-parses the captured args it meets --output, which it doesn’t define, and rejects it as unknown. The code says so where it matters, in crates/rtb-cli/src/credentials.rs:

// clap's outer `global = true` propagation works for normal
// subcommands, but `subcommand_passthrough = true` captures
// post-name tokens as `trailing_var_arg`, so the global
// never reaches the outer parser for this subtree.
args = strip_global_output(args);

Parse it yourself, then strip it

The fix is two moves. First, parse --output out of the raw args by hand (there’s an OutputMode::from_args_os for exactly that), so the output mode is still honoured. Then strip --output out of the args before the inner parser runs, so the inner clap doesn’t choke on a flag it doesn’t define. strip_global_output is the second move, from crates/rtb-cli/src/render.rs:

if s.starts_with("--output=") {
 continue; // inline form: drop just this token
}
if s == "--output" {
 iter.next(); // space-separated form: drop the token and its value
 continue;
}

It handles both --output=json and --output json, and it’s idempotent, so it’s safe to call whether or not the flag is actually present.

The takeaway

global = true and trailing_var_arg are both “grab the args” features, and in a passthrough subcommand they reach for the same tokens. clap won’t arbitrate that overlap, and shouldn’t try to guess. So you arbitrate: parse the global out of the raw args yourself, strip it before you re-parse the rest, and the flag that “works everywhere” actually does.

Secrets that scrub themselves from RAM

Wed, 06 May 2026 00:00:00 +0000

A while ago I worked out where a CLI should keep your API key: env var, OS keychain, or, grudgingly, a literal in the config file. That answers where the secret lives. It says nothing about what happens to it once it’s loaded and sitting in your process memory, which is the half where secrets actually tend to leak. Rust, it turns out, can do something about that half that Go simply can’t.

What go-tool-base already settled

A while back I wrote about where a CLI should keep your API keys. The answer go-tool-base settled on was three storage modes, in a fixed precedence: an environment variable reference (the recommended default), the OS keychain (opt-in), or a literal value in the config file (legacy, and refused outright when CI=true).

rust-tool-base keeps that design unchanged. Same three modes, same precedence, same refusal of literal secrets in CI. A tool embeds a CredentialRef in its typed config, and a Resolver walks env, then keychain, then literal, then a well-known fallback variable, first hit wins. That part is a straight carry-over, because where to keep the secret was design, and design survives the port.

But storage is only half the life of a secret. The other half is what happens to it once it’s resolved and sitting in your process memory. That’s where Rust can do something Go can’t, and rust-tool-base takes the opening.

The two ways a secret leaks after you’ve loaded it

You’ve resolved the API key. It’s a value in memory now. Two very ordinary things can leak it from there, and neither involves your storage being wrong.

The first is the log line. Somewhere a developer writes a debug print of a config struct, or an error includes the struct that holds the key, or a panic dumps it. The secret is a string like any other string, so it renders like any other string, straight into a log aggregator that a lot of people can read.

The second is the leftover bytes. The key sat in a heap allocation. The variable goes out of scope, the allocation is freed, and on most runtimes “freed” just means “returned to the allocator”. The bytes are still there until something else writes over them. A core dump taken in that window contains your key. So does the next allocation that happens to land on that memory and gets logged before it’s overwritten.

A Go string can’t really defend against either. Go strings are immutable, so you can’t zero one in place; the runtime copies them freely, so you can’t even track every copy; and there’s no compile-time barrier stopping anyone printing one. You can be disciplined, but discipline is all you’ve got.

`SecretString` closes both

rust-tool-base routes every secret through secrecy::SecretString, and the crate is explicit that taking a plain &str or String for a secret is a type error, not a style preference.

For the log line, SecretString has its own Debug implementation, and it prints [REDACTED]. Always. A config struct holding a SecretString can be debug-printed, put in an error, caught in a panic, and the secret field shows up as [REDACTED] every single time. You don’t have to remember not to log it. The type already won’t.

For the leftover bytes, SecretString zeroes its memory when it’s dropped. When the value goes out of scope, before the allocation is handed back, the bytes are overwritten. The window where a freed allocation still holds your key is closed. A core dump taken afterwards finds zeroes.

There’s a third leak SecretString blocks that’s easy to miss. It deliberately doesn’t implement Serialize. You cannot serialise a SecretString. That sounds like an inconvenience until you see what it prevents: a tool that loads config, changes one setting, and writes the whole struct back would, with an ordinary string, faithfully write the resolved secret to disk in plain text. Because SecretString can’t be serialised, CredentialRef can’t be either, and that accident is structurally impossible. Writing a secret back is a deliberate, separate path, never a side effect of saving config.

When code genuinely needs the raw value, to drop it into an Authorization header, it calls expose_secret(). The name is the point. Getting at the plaintext is one explicit, greppable, reviewable call, and everywhere else the secret stays wrapped.

Discipline versus the type system

The plain framing is this. None of these leaks are exotic. Logging a struct, a core dump after a free, re-saving a config file: they’re all routine, and they’re all how real credentials end up somewhere they shouldn’t.

go-tool-base’s storage design is good, and rust-tool-base kept it. But in Go, not leaking the secret once it’s in memory comes down to every developer being careful every time. In Rust, SecretString makes the type system carry it. The redaction, the zeroing, the un-serialisability aren’t things you remember to do. They’re things the secret does to itself because of what it is. That’s the part Go structurally can’t match, and it’s why the port didn’t just copy the storage modes across, it tightened the handling underneath them.

The gist

go-tool-base settled where a CLI keeps a secret: env var, keychain, or literal, in a fixed precedence. rust-tool-base keeps that design and hardens what happens once the secret is loaded.

Every secret is a secrecy::SecretString. It debug-prints as [REDACTED], so it can’t fall into a log by accident. Its memory is zeroed on drop, so it doesn’t survive in freed heap. It isn’t serialisable, so it can’t be written back to config by a blanket save. Getting the plaintext is one explicit expose_secret() call. Go can only ask developers to be careful with a secret in memory; Rust lets the type be careful for them.

Two telemetry events, one mangled line

Sun, 03 May 2026 00:00:00 +0000

A line in a log file that no parser would touch. Not a wrong value, not a missing field. Half of one telemetry event spliced into the middle of another, like two people typing into the same text box at once. Which, it turns out, is pretty much exactly what had happened.

A format with exactly one rule

rust-tool-base writes its telemetry to a file as JSONL: one JSON object per line, newline at the end, next object on the next line. It’s a lovely format to work with precisely because it has one rule, and the rule is simple. Every line is a complete object. Honour that and you can tail it, grep it, stream it into anything. Break it once and the whole file is suspect, because now a reader can’t trust that a line is a line.

So the one job the file sink has, beyond writing the right bytes, is to never let two events end up sharing a line.

“Appending is atomic, though, isn’t it?”

The mental model I started with, and I suspect I’m not alone, was this: open the file with O_APPEND, write the serialised event, and the operating system tacks it onto the end atomically. Two writers can’t tread on each other because each write goes to wherever the end currently is, no questions asked. I’d half-remembered O_APPEND as the thing that makes concurrent appending safe, full stop.

It’s half true, and the half that’s missing is the half that bit me.

O_APPEND does guarantee one thing: the seek-to-end and the write happen as a unit, so you never get the classic lost-update where two writers compute the same offset and clobber each other. Good. What it does not guarantee, on POSIX, is that a single write() of arbitrary size is atomic with respect to other writers. That atomicity has a ceiling, and the ceiling is PIPE_BUF: 4096 bytes on Linux. Under it, a write is all-or-nothing against other writes to the same file. Over it, the kernel is entirely within its rights to split your write into chunks, and another writer’s bytes can land in the gap between them.

The fat event that went over the edge

For a long time nothing went wrong, which is the most dangerous way for a bug like this to behave. A typical event, a command name, a duration, a status, an attribute or two, serialises to a few hundred bytes. Comfortably under four kilobytes, so comfortably inside the atomic window. Hundreds of them a day, never a problem.

Then an event came along with a lot of attributes on it, and its serialised form sailed past 4 KiB. Two of those emitted at roughly the same moment, both over the line, and O_APPEND did the only thing it had ever promised: it put each write at the end. It said nothing about not interleaving the bytes on the way, because past PIPE_BUF that was never on offer. One spliced line, one file a parser would now choke on.

The fix isn’t a bigger write, it’s a smaller gate

You can’t buy your way out of this with a bigger buffer, because there’s no buffer size that’s reliably atomic above PIPE_BUF. The fix is to stop relying on the kernel for mutual exclusion you can do yourself: serialise the events through a lock, so only one write is ever in flight at a time. The FileSink carries a mutex for exactly that, and the doc comment on it is the whole post in a paragraph, from crates/rtb-telemetry/src/sink.rs:

pub struct FileSink {
 path: PathBuf,
 // Serialises concurrent `emit` calls. Shared across `Clone`s of
 // the same `FileSink` so multiple handles to the same path also
 // serialise correctly.
 gate: Arc<tokio::sync::Mutex<()>>,
}

If you don’t write Rust day to day (the primer has the rest of the basics): tokio::sync::Mutex is an async-aware lock, .await is where a task waits its turn for that lock without blocking the whole thread, and the Arc wrapper is shared ownership. That Arc is the load-bearing bit: it means every clone of the FileSink points at the same gate, rather than each getting its own lock that guards nothing.

The detail I like is where the lock sits. The event is serialised to a string first, outside the critical section, because turning an event into JSON is the expensive part and there’s no reason to hold the gate while you do it. Only then does emit take the lock, and it holds it across the whole open-write-flush, so no other emit can interleave a single byte:

// Serialise the line outside the critical section.
let mut line = serde_json::to_string(&redacted)?;
line.push('\n');

let _guard = self.gate.lock().await;
// ...create parent dir, open with append(true)...
f.write_all(line.as_bytes()).await?;
f.flush().await?;

write_all makes sure the whole line goes out as one logical write from our side, and the gate makes sure ours is the only one happening. The 4 KiB cliff is still there in the kernel. We just never walk near it any more, because we’ve serialised the writers ourselves rather than hoping the OS would.

The bit even the lock can’t fix

There is however a genuine limit, and the comment is upfront about it. The mutex lives in the process. Two FileSinks in two different processes, both pointed at the same file, are back to relying on O_APPEND alone, and back under the 4 KiB ceiling. The lock can’t reach across a process boundary, so it doesn’t pretend to. The guidance there is the older, duller, correct one: give each process its own file and aggregate them somewhere else. Don’t have two processes fighting over one log file and expect the filesystem to referee.

What it comes down to

O_APPEND is a real guarantee, just a much smaller one than its name talks you into. It keeps your write at the end of the file, and it keeps concurrent writes from interleaving only while they stay under PIPE_BUF, which on Linux is 4096 bytes. A fat JSON event slides straight over that and takes your file’s one rule with it.

The fix was never exotic. Serialise the line, take a mutex, do the write under it, and the interleave can’t happen because there’s only ever one writer at a time. The POSIX manual had all of this written down long before I went and learned it the interesting way, which is, I’m told, how most people meet PIPE_BUF too.

Supporting a provider, or actually using it

Sat, 02 May 2026 00:00:00 +0000

If your CLI tool talks to an AI model, you don’t want to hard-wire one vendor. So you reach for a single client interface over several providers, which is the right call. The trap is the next step: build that interface on only what every provider has in common, and you quietly throw away the very features that made you want a particular provider in the first place. rust-tool-base’s rtb-ai refuses to make that trade.

The pull toward one interface

If your CLI tool talks to an AI model, hard-wiring one vendor is a poor bet. One user has an Anthropic key, another an OpenAI key. Someone’s on Gemini. Someone runs Ollama locally because their data can’t leave the building. Someone points at an OpenAI-compatible endpoint from a provider you’ve never heard of. You don’t want a separate code path for each, so you want one AiClient that all of them slot behind.

rtb-ai gets that unification from the genai crate, which already speaks to Anthropic, OpenAI, Gemini, Ollama and OpenAI-compatible endpoints. One interface, five providers, the tool author picks one in config. The Go sibling makes the same bet: go-tool-base’s chat package also unifies several providers, behind an interface deliberately kept to four methods. So far this is the obvious design, and if it were the whole design there’d be nothing to write about.

What “unified” quietly costs you

Here’s the catch in any unified interface. It can only expose what every provider behind it has in common.

The common subset is plain chat. Messages go in, text comes out, optionally streamed token by token. That’s real and it’s useful and every provider does it. But the common subset is also the floor, and the features that make a particular provider worth choosing are almost never on the floor. They’re the things only that provider does.

Anthropic is the sharp example, because it has three features that matter and not one of them is common-subset.

Prompt caching. You can mark the stable parts of a request, the system prompt and the tool list, as cacheable. The provider keeps them warm, and on the next turn you aren’t billed to re-send and re-process text that didn’t change. On a long agent loop, where the same large system prompt rides along on every single turn, that’s a substantial saving in both cost and latency.

Extended thinking. The model works through a hard problem in a visible, budgeted reasoning pass before it commits to an answer, and you can see that reasoning.

Citations. Structured references back to source material in the response.

A client built strictly on the common subset can’t express any of those. It has no field for them, because four of the five providers wouldn’t know what to do with the field. So a purely lowest-common-denominator client would “support” Anthropic and then use it badly, leaving its best features unreachable. Support as a checkbox, not as the point.

The escape hatch

rtb-ai’s answer is to not choose. It runs two implementations under one interface.

For OpenAI, Gemini, Ollama and OpenAI-compatible endpoints, calls route through genai, the unified path. For Anthropic, every method drops to a direct reqwest implementation straight against the Messages API. Same AiClient on the surface, a different implementation underneath, selected by which provider the config names.

And the request type has deliberate room for the difference:

pub struct ChatRequest {
 pub system: Option<String>,
 pub messages: Vec<Message>,
 pub temperature: Option<f32>,
 pub max_tokens: Option<u32>,
 /// Anthropic-only: enables prompt caching at every stable point.
 /// Ignored on non-Anthropic providers.
 pub cache_control: bool,
 /// Anthropic-only: extended-thinking budget. `None` disables.
 /// Ignored on non-Anthropic providers.
 pub thinking: Option<ThinkingMode>,
}

Set cache_control and the Anthropic-direct path inserts cache breakpoints at the three stable points: the system prompt, the tool list, and the first message. Set thinking and it adds the thinking block, and streaming surfaces a separate ThinkingToken event so you can show the reasoning apart from the answer. On a non-Anthropic provider, both fields are simply ignored. The interface carries them; only the implementation that understands them acts on them.

A hatch, not a leak

It’s worth being precise about why this isn’t the thing it superficially resembles, which is a leaky abstraction.

A leaky abstraction is one where implementation details bleed through that you didn’t intend and can’t reason about. The abstraction quietly fails to abstract, and you’re left guessing which provider you’re really talking to.

This is the opposite of that. The two Anthropic-only fields aren’t a leak. They’re named, documented as Anthropic-only, inert everywhere else, and right there in the public type for anyone to see. The interface is uniform for the common case and deliberately, visibly non-uniform at exactly the points where uniformity would have cost you the good features. You opt into provider-specifics by setting a field. You stay fully portable by leaving it at its default. Nothing bleeds; you decide.

The same design line explains what does stay in the unified path. Structured output, chat_structured::<T>, sends a JSON Schema derived from your Rust type with the request and validates the reply against it before handing you a typed T. That’s a portability win that costs nothing across providers, so it belongs in the common interface. The split isn’t “Anthropic versus the rest”. It’s “features that are free to unify go in the unified path; features that aren’t get a designed door”. Prompt caching and extended thinking get the door, because flattening them away would be the expensive kind of convenient.

To sum up

A CLI tool that integrates AI wants one client over several providers, and a unified interface can only expose what those providers share. The shared floor is plain chat, and the features worth choosing a provider for, like Anthropic’s prompt caching, extended thinking and citations, are never on the floor.

rtb-ai keeps both. genai provides the unified path across five providers; an Anthropic-direct reqwest path drops below the abstraction for the features genai can’t reach, and ChatRequest carries the Anthropic-only fields openly, ignored elsewhere. Uniform where uniformity is free, with a designed escape hatch where it isn’t. That’s the difference between supporting a provider and actually using it.

Errors without an error handler

Fri, 01 May 2026 00:00:00 +0000

In the porting post I said go-tool-base’s error handler was one of the bits that didn’t survive the move to Rust, and promised to come back to it. Here’s the come-back. The short version is that Rust hands you, for free, the single consistent error exit that go-tool-base had to build a whole component to get.

What go-tool-base built

A while ago I wrote about error handling in go-tool-base. The core of it: an error should carry a hint, a separate field of human guidance telling the user what to do next, kept apart from the error’s identity so code can still match on it.

The other half of that post was about consistency. Every go-tool-base command returns its errors the idiomatic Cobra way, and they all funnel into one Execute() wrapper at the root, which routes every error through one ErrorHandler. One door out. Presentation decided in exactly one place, so no command can render a failure differently from its neighbour.

That handler is a real object. It exists, it’s wired in, it’s the thing every error passes through. Building it was a deliberate piece of work, and it was the right call for Go.

When I rebuilt this in Rust, the handler didn’t survive the move. Not because consistency stopped mattering. Because Rust gives you the single exit for free, and an object to enforce it would just be re-implementing something the language already does for you.

The shape of a Rust error

Start with the type. In rust-tool-base every crate defines its own error enum, and every one of them derives two traits:

#[derive(Debug, thiserror::Error, miette::Diagnostic)]
pub enum ConfigError {
 #[error("config file not found at {path}")]
 #[diagnostic(
 code(rtb::config::not_found),
 help("run `mytool init` to create one, or set MYTOOL_CONFIG"),
 )]
 NotFound { path: PathBuf },
 // ...
}

thiserror::Error makes it a proper error type. miette::Diagnostic is the interesting one. A Diagnostic is an error that also carries the things you’d want when presenting it: a stable code, a severity, a help string, and optionally source labels pointing at spans of input. The help line is the same idea as go-tool-base’s hint, the recovery step, except here it’s an attribute on the variant rather than a field threaded through a wrapper.

So the guidance lives on the error, structured, from the moment the error is created.

There is no handler, there’s a convention

Here’s where Rust does the work go-tool-base’s handler was built to do.

A rust-tool-base main looks like this:

#[tokio::main]
async fn main() -> miette::Result<()> {
 rtb::cli::Application::builder()
 .metadata(/* ... */)
 .version(VersionInfo::from_env())
 .build()?
 .run()
 .await
}

main returns miette::Result<()>. Every command’s run returns a Result too. In between, errors propagate with the ? operator: a function that hits an error returns it upward, immediately, and the caller does the same, all the way to main. Nobody writes a “check this error” call. ? is the propagation.

And when an error reaches main and main returns it, something has to render it for the user. That something is a report hook. rust-tool-base installs one at startup, and from then on any Diagnostic that exits main is rendered through it: the code, the severity, the help text, the source labels, with colour. One renderer, installed once.

Look at what that adds up to. Every error in the program flows to one place, main. It’s rendered by one thing, the hook. Presentation is decided in exactly one location and no command can deviate from it. That’s precisely the property go-tool-base’s ErrorHandler was built to guarantee. The difference is that nobody built it. The single exit is just where ? propagation ends, and the single renderer is one hook. The language’s own convention for returning errors from main is the funnel.

Errors are values, all the way

The thing that took me a moment to fully trust is that there’s no funnel to maintain, because there’s no funnel as an object. go-tool-base’s handler is a component: it can drift, it has to be kept in the path, a command could in principle be wired to bypass it. The Rust version cannot be bypassed, because bypassing it would mean a command not returning its error, and an error you don’t return is a compile-time warning at best and dead-obvious wrong code at worst.

So the model is just: errors are values, you return them, ? carries them up, main hands the last one to the hook. The consistency isn’t enforced by a guard. It’s the only thing the shape of the language really lets you do.

go-tool-base reaches a single, consistent error exit by building one and routing everything through it. rust-tool-base reaches the same exit by having errors be ordinary return values and letting them fall out of main. Same outcome. One of them is a component you own; the other is a convention you inherit.

Worth remembering

go-tool-base funnels every error through one ErrorHandler so presentation stays consistent. That handler is a deliberately built component, and it’s the right design in Go.

rust-tool-base has no handler. Every crate’s error type derives miette::Diagnostic, carrying its code, severity and help text. Errors propagate with ? to main, which returns miette::Result, and a framework-installed hook renders whatever comes out. The single consistent exit is the end of ? propagation, and the single renderer is one hook. The funnel go-tool-base built by hand is, in Rust, just the language’s return-from-main convention.

Two kinds of feature flag

Thu, 30 Apr 2026 00:00:00 +0000

go-tool-base has feature flags: switches that decide which built-in commands are live in a given run. rust-tool-base has those too. But it also has a second, completely separate kind of flag, and the difference between them is one of those distinctions that’s obvious the moment you see it and dangerously easy to conflate before you do. One decides what a command does. The other decides whether a chunk of code is in the binary at all.

A workspace of crates

Before the flags, the shape that makes them possible. go-tool-base is one Go module with packages under pkg/. rust-tool-base is a Cargo workspace of seventeen crates: rtb-app, rtb-config, rtb-cli, rtb-vcs, rtb-ai, rtb-mcp, rtb-docs, rtb-telemetry, and so on, with an umbrella crate called rtb that re-exports the public surface.

That isn’t tidiness for its own sake. Each subsystem being a separately compilable crate is what gives you a unit you can include or exclude wholesale. Hold onto that, because it’s the hinge for everything below.

The flag go-tool-base already has

go-tool-base has feature flags, and I’d describe them as runtime flags. A tool built on it can enable or disable built-in commands:

props.SetFeatures(
 props.Disable(props.InitCmd),
 props.Enable(props.AiCmd),
)

At startup the framework resolves that set and decides which commands are reachable for this run. The init command might be present in the binary but switched off; the ai command might be switched on. It’s about the user-facing surface: which commands exist for someone typing --help.

rust-tool-base keeps this idea. A command carries a CommandSpec with an optional feature field, and the runtime decides whether a feature-gated command is reachable. Same purpose: shape the surface per invocation.

If that were the whole story, there’d be nothing to write. The reason there’s a post is the other kind of flag, which Rust makes available and Go really doesn’t.

The flag Rust adds

Cargo features are a compile-time mechanism. The rtb umbrella crate declares them like this:

[features]
default = ["cli", "update", "docs", "mcp", "credentials", "tui"]
cli = ["dep:rtb-cli"]
update = ["dep:rtb-update"]
ai = ["dep:rtb-ai", "rtb-docs?/ai"]
vcs = ["dep:rtb-vcs"]
telemetry = ["dep:rtb-telemetry"]
full = ["cli", "update", "docs", "mcp", "ai", "credentials", "tui", "telemetry", "vcs"]

Each subsystem is an optional crate dependency, and a feature switches it on. This is a different kind of switch entirely, and the difference is the whole point.

A runtime flag decides what a command does while the program runs. The code is in the binary either way; the flag just gates it.

A Cargo feature decides what’s in the binary in the first place. Build a tool without the vcs feature and rtb-vcs is not compiled. Its dependencies are not compiled. gix, the pure-Rust Git implementation rtb-vcs pulls in, roughly two and a half megabytes of it, is not compiled and not linked. It isn’t switched off in the binary. It was never in the binary. The compiler never even saw it.

That’s something a runtime flag cannot do, because by the time anything runs, the binary already exists with everything in it.

Two axes, kept separate

So rust-tool-base has two flag systems answering two genuinely different questions.

Cargo features answer: what is this binary made of? They’re decided when you build the tool, in Cargo.toml. They control compilation, binary size, dependency surface, and compile time. A tool that never touches Git builds without vcs and is smaller, faster to compile, and has a smaller dependency tree to audit. A tool that wants everything turns on full.

Runtime feature flags answer: what can the user do in this run? They’re decided as the program starts. They control which commands appear, which paths are reachable.

These could have been mashed into one mechanism, and it would have been a mistake. The app-context design notes are blunt about it: feature gating doesn’t belong on the per-command context object, because a feature-gated command “either exists or doesn’t” rather than changing its behaviour mid-run. Compile-time composition is one decision, made by the person building the tool. Runtime gating is another, made per invocation. Conflating them would mean you couldn’t reason cleanly about either.

The Go version of this had to be hand-built

This isn’t a thing Go simply lacks. I wrote a whole post about how go-tool-base keeps its optional keychain dependency out of binaries that don’t want it, using a blank import and the linker’s dead-code elimination. It works. But it was a piece of deliberate engineering for one dependency, and getting it right took care.

Cargo features make that same outcome a first-class, declarative thing, and not for one dependency but for every subsystem the framework has. You don’t engineer the exclusion. You name a feature and leave it off. The crate, and its whole subtree, stays out. Rust’s build system was designed for exactly this, and rust-tool-base leans on it across the entire workspace rather than hand-rolling it once.

Where this leaves us

go-tool-base has runtime feature flags: they decide, per invocation, which built-in commands are reachable. rust-tool-base keeps that, and adds a second kind that Rust makes available.

Cargo features decide what the binary is compiled from. Each of the framework’s seventeen crates is an optional dependency, and a feature switched off means that crate and its entire dependency subtree are never compiled or linked. A runtime flag gates what code does; a Cargo feature gates whether code is there at all. Two axes, two questions, deliberately kept as separate systems.

forbid means forbid, until linkme needs a word

Wed, 29 Apr 2026 00:00:00 +0000

There’s a line at the top of every production crate in rust-tool-base that I’m quietly proud of: #![forbid(unsafe_code)]. And there are a couple of files that have to say #![allow(unsafe_code)] instead. Not because I wrote anything unsafe. Because a macro did, on my behalf, and forbid doesn’t care whose unsafe it is.

Why forbid, and why it isn’t the whole story

rust-tool-base makes a bold promise: no unsafe in its own code. The strong form of that is forbid, not deny. deny(unsafe_code) makes unsafe a compile error that any module can quietly re-permit with its own #[allow]. forbid can’t be overridden from inside the crate at all. That’s the appeal: nobody gets to wave unsafe through in a hurry.

So the workspace lint sits at deny, and every production lib.rs then tightens it to forbid:

# Cargo.toml
[workspace.lints.rust]
unsafe_code = "deny"

// crates/rtb-error/src/lib.rs
#![forbid(unsafe_code)]

Why deny at the workspace but forbid in each crate? Because deny leaves an escape hatch open for the rare file that genuinely needs one, while forbid slams it shut everywhere it can. Almost every file gets forbid. A tiny number need the hatch.

The files that need the hatch

The command and provider registries use linkme’s distributed_slice so backends can register themselves at link time, without life before main. And the linkme attribute expands to code carrying a #[link_section], which the unsafe_code lint counts as unsafe. So any file using the attribute, whether it declares a slice or registers into one, can’t live under forbid.

Here’s the Gitea release backend doing exactly that, from crates/rtb-vcs/src/gitea.rs:

#![allow(unsafe_code)]
// ...
/// Link-time registration entry.
#[distributed_slice(RELEASE_PROVIDERS)]
fn __register_gitea() -> Box<dyn ProviderRegistration> {
 Box::new(RegisteredProvider { source_type: "gitea", factory: factory as ProviderFactory })
}

That #![allow(unsafe_code)] isn’t there because the backend does anything dangerous. It’s there because the registration macro emits a #[link_section], and forbid would, correctly by its own rules, refuse to compile the file.

Where that leaves the promise

The guarantee survives, with an exception you can point at. Every production crate forbids unsafe outright. The workspace sits one notch looser at deny, precisely so the handful of files that use linkme (and a couple of test files that need Rust 2024’s unsafe env mutation) can open a narrow, module-scoped #![allow(unsafe_code)] with a written reason. The absolutist rule met a macro that writes a link_section for you. The answer wasn’t to drop the rule, it was to keep forbid everywhere it can hold and clearly label the one or two spots where it can’t.

A framework that contains no unsafe

Tue, 28 Apr 2026 00:00:00 +0000

“It’s written in Rust” gets thrown around as if it were a memory-safety guarantee. It mostly isn’t. Rust is memory-safe by default, which is a wonderful thing, but the unsafe keyword exists precisely so any crate, any module, can step outside that default when it needs to. So “written in Rust” really means “mostly safe, probably”. rust-tool-base makes the stronger claim about its own code, and gets the compiler to enforce it.

Safe by default is not the same as safe

People reach for Rust because of memory safety, and the reputation is earned. Write ordinary Rust and the compiler will not let you have a use-after-free, a data race, or a buffer overrun. That’s the default, and it’s a very good default.

But it’s a default, and defaults can be turned off. Rust has an unsafe keyword precisely so that, when you genuinely need to, you can dereference a raw pointer, call into C, or tell the compiler you’ve upheld an invariant it can’t check itself. Inside an unsafe block, the guarantees are yours to maintain, not the compiler’s to enforce.

That keyword has to exist. Some of the most foundational crates in the ecosystem are built on it, carefully. But it means a fact worth being precise about: a project being “written in Rust” tells you its code is mostly safe. It does not tell you the project’s own code contains no unsafe. Those are different claims, and only the second one is a guarantee.

rust-tool-base makes the second claim about its own code, and has the compiler back it up.

`forbid`, not just `deny`

The mechanism is one line at the top of every crate:

#![forbid(unsafe_code)]

unsafe_code is a lint, and Rust lints have levels. The interesting choice is forbid rather than deny, because the two are not the same strength.

deny makes the lint an error. But it’s an error a downstream module can locally override. Anyone can write #[allow(unsafe_code)] on a function or a block and the deny is lifted right there. As a policy, deny is “don’t do this unless you really mean to”, and “unless you really mean to” is a door.

forbid is the strict one. It makes the lint an error and it makes that error impossible to override from inside the crate. A module cannot #[allow] its way back out. Once a crate root says #![forbid(unsafe_code)], there’s no unsafe anywhere in that crate, and no local exception can be carved out. The compiler simply refuses.

So every rust-tool-base crate that ships in a built tool forbids unsafe at its root. Not “discourages”. Cannot contain it.

The one subtlety

There’s a wrinkle, and it’s worth showing rather than hiding, because it’s where the design got specific.

The workspace sets unsafe_code = "deny" as the baseline for everything, including test files. But test code occasionally has a real need for unsafe. In the 2024 edition, std::env::set_var became unsafe, because mutating the process environment isn’t thread-safe, and a test that exercises environment-driven configuration has to call it.

So the split is deliberate. The workspace-wide level is deny, which a test file can locally #[allow] when it genuinely needs that one environment call. But every production lib.rs and main.rs additionally carries #![forbid(unsafe_code)], and forbid cannot be relaxed. Test scaffolding gets a controlled, visible exception for a specific standard-library call. Shipping code gets none. The guarantee that matters, “the code in the binary contains no unsafe”, holds, and the place it’s slightly loosened is exactly the place that never reaches a user.

What the guarantee is actually worth

Two things, one for users and one for reviewers.

For users: an entire family of bug is ruled out of first-party code mechanically. Use-after-free, double-free, data races on shared memory, reading off the end of a buffer. These are the classic memory-safety vulnerabilities, and in a crate that forbids unsafe they cannot originate, because the constructs that produce them cannot be written. That’s not careful coding. It’s the compiler refusing to build anything else.

For reviewers: the cost of an unsafe block is mostly the review burden it carries. Every one is a spot where a human has to check, by hand, that an invariant holds, and has to re-check it whenever nearby code changes. A crate that forbids unsafe has zero of those. There’s no unsafe block to audit, ever, because the compiler guarantees there isn’t one.

The promise has a boundary. It covers rust-tool-base’s own code; its dependencies are another matter, and some of them do contain unsafe, correctly. Keeping that side honest is a different job, done by vetting the dependency tree and gating it in CI. Within first-party code, though, the guarantee is real, and there’s no Go equivalent to it. Go has an unsafe package, but nothing that lets a codebase prove, to the compiler, that it never touches it.

The bottom line

Rust is memory-safe by default, but the unsafe keyword exists so that default can be set aside. “Written in Rust” therefore does not by itself mean a project’s own code contains no unsafe.

rust-tool-base makes that the stronger claim. Every crate root carries #![forbid(unsafe_code)], and forbid, unlike deny, cannot be overridden from inside the crate. Test files get a narrow, visible deny-level exception for the one standard-library call that needs it; shipping code gets none. The payoff is a whole class of memory-safety bug ruled out of first-party code by construction, and not one unsafe block left for a reviewer to audit.

Reloading config without a restart

Mon, 27 Apr 2026 00:00:00 +0000

A config file changes. Someone edits a setting, rotates a credential, flips a feature flag. How does the running process find out? For most processes the answer is blunt: it doesn’t, until you restart it. For a short-lived CLI that’s completely fine. For a long-running service, “just restart it” is a much bigger ask than it sounds.

The default answer is a restart

Configuration lives in a file. The file changes: someone edits a setting, rotates a credential, flips a feature flag. How does the running process find out?

Overwhelmingly, the answer is that it doesn’t. A process reads its config once, at startup, and that snapshot is frozen for the life of the process. Change the file and nothing happens until you restart, at which point a fresh process reads the fresh file.

For a short-lived CLI invocation that’s completely fine. It reads config, does its job, exits, and the next invocation reads whatever the file says then. But the same frameworks are also used to build long-running services, and for a service “just restart it” is not the small thing it sounds like.

What a restart actually costs

Restarting a long-running service means every open connection drops. Any in-flight request is lost, or has to be retried by whoever sent it. Caches that took real time to warm are cold again. There’s a window, short but real, where the service simply isn’t serving.

If the thing you changed was a log level, or a feature flag, or a timeout, you’ve paid a disruption wildly out of proportion to the change. And the calculation only gets worse as the service gets more important, because the services you least want to bounce on a whim are exactly the ones that matter most.

Hot-reload: re-read in place

Hot-reload is the alternative, and both go-tool-base and rust-tool-base support it.

The process doesn’t read config once and freeze it. It watches the config file. When the file changes, it re-reads it, re-applies it, and carries on running. No new process, no dropped connections, no cold start. The change lands in the live process.

The shape is the same in both frameworks:

A file watcher notices the config file changed. Underneath, this is the operating system’s own file-notification facility, inotify on Linux and its equivalents elsewhere. rust-tool-base reaches it through the notify crate; go-tool-base, through the watcher built into Viper.
A debounce step waits for the writes to settle. Saving a file is often several separate operations, and you don’t want to reload three times for one edit.
The config is re-parsed from disk.
The new config is swapped in atomically.
Observers are notified, so the subsystems that care can react.

Steps four and five are the ones worth slowing down on, because they’re where a naive hot-reload quietly goes wrong.

The two details that make it safe

The atomic swap. You do not mutate the live config object in place. A reader on another thread, partway through reading it, would see a torn mix of old and new values, and that’s a genuinely nasty class of bug. Instead the process builds a new, complete config value and swaps the pointer to it in a single atomic operation. Any reader sees either the entire old config or the entire new one, never a blend. rust-tool-base does this with arc-swap; go-tool-base does the equivalent. Reads stay cheap and lock-free, and an update is one pointer swap.

The observer notification. Re-reading the file isn’t the end of the job. Some subsystems have to do something when config changes: a connection pool resizes, a logger changes level, a rate limiter takes a new ceiling. So a hot-reload system has to let those subsystems subscribe. rust-tool-base hands observers a watch::Receiver, a channel that always holds the latest value; go-tool-base exposes an Observable interface. A subsystem subscribes once and reacts every time config changes, for the life of the process.

Where this earns its keep: a Kubernetes pod

Hot-reload is a nicety on a developer’s laptop. Inside a Kubernetes pod it becomes genuinely valuable, and the reason is a neat fit between how Kubernetes delivers config and how a file watcher works.

In Kubernetes you don’t usually bake configuration into the container image. It lives in ConfigMap and Secret objects, and the clean way to consume them is to mount them as volumes. Mount a ConfigMap as a volume and each key becomes a file in the pod’s filesystem.

Here’s the part that connects to everything above. When you update that ConfigMap or Secret, Kubernetes does not restart your pod. The kubelet notices the object changed and rewrites the projected files inside the still-running pod. The files on disk change underneath a process that never stopped.

That file rewrite is exactly the event a hot-reload watcher exists to catch. So the whole chain becomes:

You kubectl apply an updated ConfigMap, or rotate a Secret.
The kubelet updates the projected files inside the pod.
The framework’s file watcher sees the write.
The config is re-parsed, swapped in atomically, and observers are notified.
The new configuration is live, and the pod never cycled.

You’ve changed a running service, in a running pod, with no rollout, nothing terminated and recreated, no dropped traffic. Rotate a database credential, raise a log level to debug an incident in progress, flip a feature flag: all of it live. For a service where a restart is the very thing you’re trying hard to avoid, the kind of long-running service these frameworks are built for, that’s the difference between a config change being routine and being an event.

The caveats

Two things, so this doesn’t read as magic.

First, not everything can be hot-reloaded. Some configuration genuinely needs a restart: the port a server binds to, the size of a thread pool, anything wired up exactly once at process start. Hot-reload covers the large category of settings a subsystem can re-read and re-apply; it doesn’t abolish restarts. A config system worth its salt is clear about which settings are live and which are not.

Second, a Kubernetes gotcha that catches people out. The in-place file update happens for ConfigMaps and Secrets mounted as volumes. Consume the same ConfigMap as environment variables instead, and those are fixed when the container starts and never update, short of a restart. If you want hot-reload in a pod, mount config and secrets as files, not env vars. And even with volumes the update isn’t instant: the kubelet syncs on a period, around a minute by default, so a reload is “within a minute or so”, not “the moment you hit apply”.

What it comes down to

A config file changes, and the default way to pick it up is to restart the process. For a long-running service that restart costs dropped connections, lost work and a cold start, often for a change as small as a log level.

go-tool-base and rust-tool-base both support hot-reload instead: a file watcher catches the change, the config is re-parsed and swapped in atomically so no reader sees torn state, and observers are notified so subsystems can react, all in a live process. The setting where it pays off most is a Kubernetes pod, where ConfigMaps and Secrets mounted as volumes are rewritten in place by the kubelet and the watcher catches that write directly. Mount them as volumes rather than env vars, allow for the kubelet’s sync delay, accept that some settings still need a restart, and within those limits “the config changed” stops meaning “cycle the pod”.

Waivers with an expiry date

Sun, 26 Apr 2026 00:00:00 +0000

A vulnerability scanner gives you a yes or a no. Is there a known advisory on a path you actually use? Yes, or no. That’s genuinely useful, and you should run one. But it’s a snapshot, taken on the day you ask, and supply-chain risk in a framework is a bigger and more ongoing thing than a single yes-or-no can capture.

So rust-tool-base treats its whole dependency tree as something to have a policy about, not something to scan and forget.

A scanner answers one question

When I had go-tool-base security-audited, part of the routine was running a vulnerability scanner over the dependencies. Go has a good one. It looks at your dependency graph, cross-references known advisories, and tells you whether any of them reach code you actually call.

That’s useful and you should do it. But notice the shape of what it gives back: essentially a yes or a no. Either there’s a known vulnerability on a reachable path or there isn’t. It answers one question, on the day you ask it.

Supply-chain risk in a framework is broader than that one question, because a framework drags its entire dependency tree into every tool built on it. rust-tool-base treats the whole tree as something to have a policy about, and the tool for that is cargo-deny.

A gate, not a scan

cargo-deny reads a deny.toml and checks the dependency graph against four kinds of rule.

Licences. There’s an allowlist: MIT, Apache-2.0, the BSD variants, ISC, a handful of others. Every transitive crate’s licence has to be on it. A dependency that pulls in something copyleft, or something with no licence at all, fails the build. You find out the first time it enters the tree, not during a release scramble when someone finally reads the legal implications.

Advisories. It checks the RustSec advisory database, and yanked crates are set to deny, so a dependency that’s been pulled from the registry stops CI.

Bans. Wildcard version requirements (version = "*") are denied outright, because a dependency that floats to whatever’s newest is a supply-chain hole by construction. Duplicate versions of the same crate get surfaced too.

Sources. Crates may only come from the official registry. An unknown registry or a stray git dependency is denied. Nothing sneaks in from a URL.

That’s a gate. It encodes, as rules in a file, what the project will and won’t accept into its dependency tree, and it enforces them on every build instead of once an audit.

The honest part is the waiver list

Here’s the thing every real project runs into. Sooner or later there’s an advisory you genuinely can’t fix this week. It’s against a crate three levels down your tree. The fix needs an upstream release that hasn’t happened. The crate is scheduled to be reworked two milestones from now anyway. The gate is going to fail, and the work to satisfy it honestly isn’t available to you yet.

The lazy response is a blanket ignore: silence the advisory, move on, forget. Now your gate has a hole in it that nobody remembers opening.

rust-tool-base’s deny.toml does something better. Every waiver in the ignore list is a documented record. Each one carries a comment that names the crate, traces the exact dependency path that reaches it, gives the reason, and names the condition that lifts it:

ignore = [
 # `instant` - reached via async-openai -> backoff -> rtb-ai (v0.3).
 "RUSTSEC-2024-0384",
 # `paste` - reached via ratatui -> rtb-docs (v0.2) / rtb-tui (v0.4).
 "RUSTSEC-2024-0436",
 # ...
]

The file states the policy out loud: “Every waiver points at a deferred stub crate that will be reworked before its ship milestone. Lift each waiver when the owning crate lands its v0.1.”

Some waivers go further and carry a structured reason field, so the why travels with the entry rather than living only in a comment above it:

{ id = "RUSTSEC-2025-0140",
 reason = "gix-date via gix is a stub dependency; rtb-vcs v0.5 will upgrade" },

Read that list and you don’t see a project that quietly stopped caring about seven advisories. You see seven advisories the project knows about, can trace, and has tied to a specific milestone. The waiver has an expiry condition. When rtb-vcs reaches v0.5, that gix entry is meant to come out, and the comment is the reminder that it should.

Why this is the bit to copy

A gate that can’t be relaxed is a gate people route around. They’ll find the broadest possible ignore and use it, because the alternative is being blocked on someone else’s release. The pressure to do that is real, and it’s not unreasonable.

So the design that actually holds up isn’t a stricter gate. It’s a gate with an honest, structured escape hatch: you can waive an advisory, but a waiver costs you a documented record with a dependency path and an expiry condition. That price is small enough that nobody routes around it, and high enough that waivers don’t accumulate silently. The ignore list stays readable, and every line in it is something you could defend out loud.

Supply-chain hygiene framed this way isn’t an audit you survive once a year. It’s bookkeeping: a ledger of what you accepted, why, and when each exception is due to close. Which, now I write it down, is just the Boy Scout rule again, pointed at a dependency tree. Leave it tidier than you found it, and write down the bits you couldn’t tidy yet.

Where this leaves us

A vulnerability scanner answers one question on one day. cargo-deny is a standing policy gate: licences against an allowlist, advisories and yanked crates denied, wildcard versions banned, sources restricted to the official registry, enforced on every build.

The part of rust-tool-base’s setup worth copying is the waiver list. Every advisory that can’t be fixed yet is recorded with its crate, its dependency path, its reason and the milestone that removes it. A waiver is a dated note, not a shrug, and that’s what keeps the gate honest enough that nobody actually wants to bypass it.

A builder that won't compile if you forget a field

Sat, 25 Apr 2026 00:00:00 +0000

go-tool-base configures things with functional options, and if you forget a required one, the best case is a runtime failure and the worst case is an empty value sailing silently into everything downstream. Most builder patterns share the same hole. rust-tool-base closes it in a way I find genuinely delightful: the .build() method simply doesn’t exist until you’ve set every required field.

When is a required field actually required

Every framework has constructors with a mix of required and optional inputs. An Application in rust-tool-base needs tool metadata and a version. It optionally takes a custom config type, extra commands, feature toggles. The metadata needs a name and a summary; a description and a help channel are optional.

The interesting question is when “required” gets enforced. There are really only two moments available: when the program runs, or when it compiles. Most APIs pick the first without ever framing it as a choice.

How go-tool-base does it

go-tool-base uses functional options, the standard Go pattern:

tool := props.New(
 props.WithName("mytool"),
 props.WithVersion(version),
)

New takes a variadic list of options and applies them. It’s flexible and it reads well. But look at what the type actually says. New accepts zero or more options. The signature is satisfied by passing nothing at all. If WithName is required, nothing in the type system knows that. Forget it and the code compiles cleanly, and you find out when the program runs, or worse, when it doesn’t visibly fail but quietly carries an empty name into everything downstream.

A plain builder is no better here. builder.name("mytool").build() and builder.build() are both perfectly valid calls as far as the compiler is concerned. The builder hopes you set the name. It can check at the end and return an error, but that check still happens at runtime.

In every one of these the required-ness of a field is a fact that lives in documentation and in the author’s head, not in the code.

Typestate: putting “required” in the type

rust-tool-base builds these with bon, and the pattern it generates is a typestate builder. The idea is that the builder’s type changes as you call it, and that type tracks which required fields you’ve set so far.

let metadata = ToolMetadata::builder()
 .name("mytool")
 .summary("my CLI tool")
 .build();

ToolMetadata::builder() returns a builder in a state that records “name not set, summary not set”. Calling .name(...) consumes that builder and returns a different type, one whose state records “name set”. Calling .summary(...) does the same for the summary.

The part that matters is .build(). It isn’t a method on the builder in general. It only exists on the builder type that represents “every required field has been set”. So this:

let metadata = ToolMetadata::builder()
 .summary("my CLI tool")
 .build();

doesn’t compile. Not because a runtime check fired, but because in the state “name not set” there’s no .build() method to call in the first place. The compiler stops you, and the error points straight at the missing .name(...).

Optional fields stay optional. You can call .description(...) or skip it, and .build() is reachable either way, because the description was never part of the state that gates it. The required and the optional are genuinely different in the type, which is exactly the distinction the functional-options version could only keep in a comment.

Application::builder() works the same way. It won’t produce an Application until it has metadata and a version, and “won’t” there means the method is absent, not that a check returns Err.

Why the moment matters

Moving the check from run time to compile time changes who finds the mistake, and when.

A runtime check finds it when that code path executes, which might be in a test, might be in CI, might be on a user’s machine at the worst possible moment. A compile-time check finds it the instant you write it, in the editor, before anything has run at all. The same mistake, caught at the cheapest possible point instead of one of the expensive ones.

It also changes what the API documents about itself. A functional-options constructor can’t tell you, from its signature alone, which options you must pass. A typestate builder can, because the set of methods available to you at each step is the documentation. You literally cannot reach .build() without having been walked past every required field on the way.

This is one of those places where Rust’s type system earns its reputation. The builder isn’t more careful than the Go version. It’s that “this field is required” stopped being a convention and became something the compiler enforces. (Another entry, if you’re keeping score from the porting post, in the column of outcomes that survived while the Go mechanism got left behind.)

The short version

Required fields have to be enforced somewhere. Functional options and ordinary builders enforce them at runtime, if at all, because .build() is always callable and the type system never learns which inputs were mandatory.

rust-tool-base uses typestate builders generated by bon. The builder’s type changes as you set fields, and .build() only exists once every required field is present. Forgetting one is a compile error that names the missing call, not a runtime surprise. The required-versus-optional distinction stops being a comment and becomes part of the type.

Process isolation won't save you from the filesystem

Sat, 25 Apr 2026 00:00:00 +0000

A test that passed every single time I ran it on its own, and failed maybe one run in five when I ran the whole suite. The failure was always the same: the self-update test downloaded a release archive, went to extract it, and found the archive corrupt. Half-written. As if something had been scribbling in the file while it read it. Something had.

The comfort I was leaning on

The self-update tests are heavier than a unit test wants to be. They stand up a fake release, download the artefact, verify its checksum, extract it, swap a binary. Real files, real I/O. So they’d been built to run as separate processes, not just separate threads, each one its own little world.

And I’d quietly filed that under “solved”. Separate processes don’t share an address space. One can’t reach into another’s memory and corrupt a value mid-read. That whole category of data race, the kind you reach for a mutex to fix, simply can’t happen across a process boundary. So I’d stopped thinking about concurrency in these tests at all, because I’d convinced myself the isolation was total.

It wasn’t total. It was isolation of memory, and I’d let myself hear it as isolation of everything.

Two processes, one path

The thing two processes very much do still share is the filesystem. And the self-update flow, sensibly, caches its download rather than re-fetching it. The default cache directory is computed from the tool’s name and the release version, in crates/rtb-update/src/flow.rs:

pub fn cache_dir_for(tool_name: &str, version: &str) -> PathBuf {
 let base = directories::ProjectDirs::from("", "", tool_name)
 .map_or_else(std::env::temp_dir, |p| p.cache_dir().to_path_buf());
 base.join("update").join(version)
}

Read that with two parallel test processes in mind. They’re testing the same tool, against the same fake release tag. So tool_name matches and version matches, which means cache_dir_for hands both of them the identical path. Two processes, isolated in every way that involves memory, both downloading and extracting into one shared directory on disk, at the same time. One writes the archive while the other is partway through reading it, and you get exactly the corrupt half-written file the test kept tripping over.

Process isolation did nothing here, because the contention was never in memory. It was on a path string that came out the same for both of them.

Once it’s framed as “they share a path”, the fix writes itself: don’t share the path. Give each invocation its own cache directory. The updater builder already had the seam for it, and the doc comment now says exactly why it’s there, in crates/rtb-update/src/updater.rs:

/// Tools call this when they want isolation per-invocation
/// (e.g. CI runners, tests with parallel processes) or to honour
/// a user-supplied `--cache-dir` flag.
pub fn cache_dir(mut self, cache_dir: impl Into<PathBuf>) -> Self {
 self.cache_dir = Some(cache_dir.into());
 self
}

Each test now builds its updater with cache_dir(its_own_tempdir), so two parallel processes land on two different directories and never meet. No lock, no serialisation, no clever cross-process file mutex. Just the realisation that the shared thing was a directory, and the cure for shared mutable state is usually to stop sharing it, not to guard it.

The fix that turned out to be a feature

The part I’m quietly pleased about is that this didn’t stay a test-only hack. The override I needed to isolate the tests is exactly the override a real tool wants for its own reasons. A CI runner doing self-update wants a writable cache path it controls, not wherever directories-rs decides the system cache lives. A user might reasonably want to point the whole thing somewhere specific. That’s a --cache-dir flag, and cache_dir() is precisely the hook you’d wire it to.

So the thing I added to stop a flaky test is the same thing a downstream tool reaches for to expose --cache-dir. The test forced the seam to exist, and the seam was worth having anyway. I’ll take that trade every time over a fix that only the test suite benefits from.

What it comes down to

I’d treated “separate processes” as a synonym for “can’t race”, and it isn’t. Processes don’t share memory, so the memory races are gone. They absolutely still share the filesystem, the network, every named resource the OS will hand to anyone who asks for it by the same name. My two test processes computed the same cache path from the same tool and tag, and raced on the files in it, and no amount of address-space isolation was ever going to touch that.

Shared mutable state on disk is still shared mutable state. The fix wasn’t a bigger hammer, it was giving each process its own directory and letting the isolation I thought I already had actually be true.

Registering commands without life before main

Fri, 24 Apr 2026 00:00:00 +0000

I ended the last post promising to show how a Rust command registers itself when the language flatly refuses to run any of your code before main(). This is that post, and it’s a lovely example of reaching the same outcome by a completely different road.

The outcome I wanted to keep is self-registration.

What self-registration buys

A command in go-tool-base lives in its own file, and that file puts the command into the framework itself. There’s no central list of commands to keep in sync. You add a file, the command appears. You delete the file, it’s gone. Nothing else changes.

That property is worth protecting. The alternative, a hand-maintained registry that every new command has to be threaded into, is exactly the sort of central file that turns into a merge-conflict magnet and quietly falls out of date. So when go-tool-base moved to Rust, self-registration was firmly in the column of things that had to survive.

The way Go did it was not.

How Go does it

A Go package can declare an init() function, and the runtime guarantees every init() runs before main() starts. A go-tool-base command file uses this to append itself to a package-level slice:

func init() {
 registry.Register(&DeployCommand{})
}

By the time main() runs, every command file’s init() has already fired and the registry slice is populated. It’s a tidy trick, and it leans entirely on a Go feature: code that executes before main().

Rust doesn’t have that

Rust has no init(). There’s no language-blessed phase that runs your code before main(). This is a deliberate decision, not an oversight. Code running before main() across many files has no well-defined order, and a startup phase whose ordering you can’t see is a classic source of subtle, miserable bugs. Rust closed that door on purpose.

Which leaves a real question. If nothing runs before main(), how does a command file insert itself into a registry without a central list editing it in?

Distributed slices

The answer is a crate called linkme, and the mechanism is the linker rather than a runtime phase.

You declare a slice the framework will collect into:

#[distributed_slice]
pub static BUILTIN_COMMANDS: [fn() -> Box<dyn Command>];

(Box<dyn Command> is just “a pointer to some value that implements the Command trait, whichever concrete type it turns out to be”; the primer covers it if that’s unfamiliar.)

A command file then contributes one entry to it:

struct Greet;

impl Command for Greet { /* ... */ }

#[distributed_slice(BUILTIN_COMMANDS)]
fn register_greet() -> Box<dyn Command> {
 Box::new(Greet)
}

Here’s the part that makes it work. The #[distributed_slice] attribute doesn’t generate any code that runs at startup. It places each entry into a dedicated section of the compiled object file. When the linker builds the final binary, it gathers everything in that section and lays it out as one contiguous array. BUILTIN_COMMANDS is that array.

So by the time the program exists as a binary on disk, the registry is already assembled. main() doesn’t build it. No init() builds it. The linker built it, statically, as part of producing the executable. At runtime the framework iterates a slice that was complete before the process ever started.

What you get from it

The outcome is the one Go’s init() gave, and then a bit more.

A command still lives in one file and still self-registers. Adding a command is still adding a file. There’s still no central list.

But there’s no startup phase to reason about, because there isn’t one. There’s no global mutable slice being appended to as init()s fire, because nothing is appended at runtime; the slice is immutable and finished. There’s no ordering question, because the linker isn’t running your code, it’s collecting data. And it costs nothing at runtime: assembling the registry happened at link time, so program start just reads it.

It’s the same idea go-tool-base had, expressed by the tool Rust actually gives you. Go reaches the registry through a controlled phase before main(). Rust reaches it without any phase at all, because the linker did the assembly while the binary was still being built. Two roads, one destination… which, if you’ve been following along, is becoming the whole theme of the Rust side of this project.

In short

Self-registration, where a command file inserts itself into the framework with no central list, is a property worth keeping. go-tool-base achieves it with a package-level init(), leaning on Go’s guarantee that such functions run before main().

Rust has no equivalent and wants none, because code running before main() has no clear ordering. rust-tool-base uses linkme distributed slices instead: each command is placed into a dedicated linker section, and the linker assembles them into one contiguous, immutable slice as it builds the binary. The registry is complete before the program runs. Same outcome as Go’s init(), with no life before main required.

Two API decisions that quietly contradict each other

Thu, 23 Apr 2026 00:00:00 +0000

Two design decisions on one enum, each sensible on its own, that would have quietly fought each other if I’d let them. I didn’t, but only because the second one is easy to get wrong and the compiler wouldn’t have said a word either way.

Decision one: promise the list can grow

#[non_exhaustive] on the Feature enum. It tells downstream code it can’t match the enum exhaustively, so it has to keep a wildcard arm, which in turn means adding a variant later is a non-breaking, minor-version change. Nobody’s match stops compiling just because the enum grew. The doc comment says exactly that: it “keeps variant additions a minor-version change for downstream matchers.”

Decision two: hand out the whole list

A convenience all() returning every variant, because iterating over the lot is something you genuinely want to do. The tempting signature is a fixed-size array, [Feature; 11]: you know precisely how many there are, so why not put it in the type?

Why those two can’t both be true

The catch is a quirk of Rust that often trips up people arriving from other languages: the length of a fixed-size array is part of its type. [Feature; 11], an array of exactly eleven features, and [Feature; 12], exactly twelve, are not one type holding a different number of items the way they might be elsewhere. They are two genuinely different, incompatible types, about as interchangeable as i32 and i64.

So the moment you add a twelfth variant, a fixed-size all() forces an unhappy choice, and both options are bad. Bump the array to [Feature; 12] and you break every caller who wrote the old length down. Leave it at 11 and the new variant is silently dropped, leaving you a function called all that doesn’t return all of them. Either way the #[non_exhaustive] promise (adding a variant breaks nobody) is quietly cancelled by a return type that welded today’s count into the public API.

So `all()` returns a slice

Which is exactly what it does, and the doc comment spells out why, in crates/rtb-app/src/features.rs:

#[non_exhaustive]
pub enum Feature {
 Init, Version, Update, Docs, Mcp, Doctor,
 Ai, Telemetry, Config, Changelog, Credentials,
}

pub const fn all() -> &'static [Self] {
 &[Self::Init, Self::Version, Self::Update, /* ...the rest... */]
}

A slice length is a value, not part of the type. Add a variant, the slice gets one longer, and not a single downstream signature changes. The promise holds.

The thing to watch for

#[non_exhaustive] is a promise about the future. A fixed-size array is a fact about the present. You can’t keep both at once, and nothing will warn you that you’ve contradicted yourself, because each decision is individually fine. The trap is always the second API surface that quietly re-bakes the flexibility the first one promised. When you mark a type “free to grow,” go and check that nothing in its public interface has secretly written down how big it is today.

What survives a port, and what doesn't

Thu, 23 Apr 2026 00:00:00 +0000

Rebuilding go-tool-base in Rust turned out to be the most honest design review I’ve ever sat through, and I didn’t have to do anything except keep going. Porting a framework into a language with completely different idioms forces a separation you can’t fake: the parts that survive the move are design, and the parts that don’t are just habit.

Two columns

When you port a system between languages that don’t share idioms, every piece of it sorts itself into one of two columns, without you having to make the call.

In the first column is the outcome a piece of the design produces: every command receives the framework’s services, configuration is layered with a fixed precedence, commands register themselves, errors carry guidance to the user. In the second column is the mechanism that produced that outcome in the original language.

Things in the first column survive the port. You rebuild them, differently, because the tool genuinely needs them. Things in the second column do not survive. You find their replacement, and the Go version turns out to have been one valid implementation of an idea, not the idea itself. Doing this for go-tool-base, mechanism by mechanism, was more honest about my own design than any amount of sitting and staring at it would have been.

The container

go-tool-base hands every command a Props struct. It carries the logger, the config, the assets, the filesystem handle. Some of it is reached through loosely-typed accessors. It works well, and I wrote a whole post about it.

The outcome is column one: a command should receive one object, and that object should carry the framework’s services so the command doesn’t go assembling them itself. That survived. RTB hands every command an App.

The loosely-typed accessors were column two. In Rust an App is a plain struct with concrete fields, each one an Arc<T> so a clone is a few atomic increments rather than a deep copy. Nothing is keyed by string. Nothing is fetched by name and asserted to a type. The thing the container is for survived; the way Go expressed it did not.

Registration

A go-tool-base command self-registers using a package-level init() function, which Go runs before main() and which appends the command to a global slice.

The outcome, column one, is that a command lives in its own file and inserts itself into the framework with no central list to edit. That’s genuinely worth keeping.

The init() mechanism is column two, and Rust doesn’t even offer it: Rust deliberately has no code that runs before main(). The replacement is link-time registration through distributed slices, which gets its own post next. Same outcome, no global mutable state, assembled by the linker rather than by a startup phase.

Configuration

go-tool-base layers configuration with a precedence: flags over environment over file over defaults. Some of it is read back through key lookups.

The layering and the precedence are column one. They survived exactly. RTB layers config with the same ordering.

The key lookups were column two. In Rust the merged configuration is deserialised into your own serde struct, so a config value is a typed field you access like any other field, and a typo is a compile error instead of a missing key at runtime. The precedence survived; reading values back out of a string-keyed bag did not.

The error path

go-tool-base routes every error through one handler so presentation is consistent, which I also wrote up.

One consistent exit for errors is column one. It survived. What didn’t survive was the handler: RTB has no error-handler object at all, because Rust’s own return-from-main convention plus a report hook does the job the handler was built to do. That one has its own post too.

What the exercise was actually worth

Every mechanism told the same story. The container, the registration, the config access, the error path, the cancellation signal that go-tool-base carries on a context.Context and RTB carries on a CancellationToken. In every case the thing it achieved walked across to Rust untouched, and the Go code that achieved it was left behind.

That’s the useful result. Before this port I couldn’t have told you, for any given pattern in go-tool-base, whether it was load-bearing design or just the idiomatic Go way to write it that day. Now I can, because each one was forced to prove itself by being rebuilt from nothing in a language that flatly wouldn’t accept the original. Whatever survived was real. Whatever I had to replace was always replaceable, which means it was never really the point.

The upshot

Porting a framework into a language with different idioms separates design from habit for free. The outcome a pattern produces is design, and it survives the move. The mechanism that produced it is idiom, and it gets left behind for the new language’s equivalent.

go-tool-base’s Props bag, its init() registration, its key-based config access and its error handler were all idiom. The single context object, self-registration, layered precedence and a consistent error exit were all design, and all four came through to RTB intact. The next three posts take the most interesting replacements one at a time, starting with how a Rust command registers itself when the language won’t run anything before main.

rust-tool-base: the same idea, in a language that argues back

Wed, 22 Apr 2026 00:00:00 +0000

I built go-tool-base because I was sick of rebuilding the same CLI scaffolding every time I started a new Go tool. You’d think that would have taught me a lesson about doing things more than once. Apparently not, because I’ve now started building rust-tool-base: the same idea, the same itch, for Rust.

In my defence, there’s method in it.

The same itch, a different language

go-tool-base exists because I kept writing the same couple of hundred lines of wiring every time I started a new Go CLI. Config loading, logging setup, an update check, an error path, a help system. None of it was the tool. All of it had to be there before the tool could be.

Lately I’ve been learning Rust, and two things collided. The first is how I tend to learn a language. I’ve always picked them up reasonably quickly, and the way I do it isn’t with a tutorial that builds a toy, it’s by rebuilding something whose shape I already know cold, so that every decision is about the language rather than the problem. The second is that every time I started a Rust CLI of any size, I hit the very same gap I’d already filled once in Go.

So rather than learn Rust on a throwaway, I decided to learn it by building rust-tool-base: the same idea, the same niche, for Rust.

One housekeeping note before the series gets going. You don’t need to write Rust to follow it. The posts lean on a handful of language ideas, and rather than stop and re-explain each one mid-flow, I’ve gathered them into a short primer. If a bit of syntax trips you up along the way, that’s where to look. If you already write Rust, ignore me and read on.

The gap in Rust

The Rust ecosystem has a well-earned reputation for sharp, focused crates and a deliberate shortage of big opinionated frameworks. clap for argument parsing, figment for layered config, tracing for logging, miette for errors, ratatui for terminal UI, reqwest and tokio underneath. Each of them is genuinely best-in-class.

What nobody hands you is the assembly. Wiring those into one coherent product, and then adding self-update, AI integration, an MCP server, embedded documentation, credential handling, telemetry and a scaffolder, is real work, and it’s the same work on every project.

The closest existing neighbours stop short of it. cli-batteries is a thin preamble: argument parsing plus a logging subscriber plus panic and signal handling. starbase has a proper session and lifecycle model but is CLI-agnostic and shaped around the moonrepo tooling it came from. cargo-dist and cargo-release are about release packaging, not the runtime. Good tools, all of them, but none is the opinionated, full-lifecycle, scaffolded base that go-tool-base is in the Go world. That space is empty, and rust-tool-base is built to fill it.

Why it is not a port

The obvious way to build this would be to open go-tool-base and translate it file by file. I’m not doing that, and the reason matters enough that it’s the rule the whole project is built around.

go-tool-base is full of Go. It leans on a Props struct that carries the framework’s services in loosely-typed fields. It configures things with functional options. It registers commands using package-level init(). It threads a context.Context through every call. Those are all good, idiomatic Go. Transliterated into Rust they’d become code that argues with the compiler on every single line, because Rust has its own answers to every one of those problems and they are emphatically not the Go answers.

So rust-tool-base reaches the same outcomes by Rust’s means. Commands still self-register, but through link-time machinery instead of init(). There’s still one context object per command, but it’s strongly typed rather than a loosely-keyed bag. Configuration is still layered, but it lands in your own typed struct instead of a string-keyed lookup. Same philosophy, same shape of product, an entirely different ecosystem underneath. The README says it plainly: it’s a sibling, not a port.

Why do it twice at all

Three reasons, and they reinforce each other.

The first is plain usefulness. The next time I want a Rust CLI tool, I want the same head start go-tool-base already gives me in Go.

The second is the learning. Rebuilding a system I understand forces me to meet Rust’s idioms where they actually bite, not where a tutorial gently stages them. You learn ownership properly when a real design is pushing back at you.

The third is the one I didn’t expect, and it’s the subject of the next post. Building the same framework twice, in two languages, turns out to be the cleanest way to find out which of your original decisions were genuine design and which were merely idiom. The design survives the move. The idiom does not. Sorting one from the other has been the most interesting part so far.

Boiling it down

rust-tool-base is the Rust sibling of go-tool-base: the same batteries-included, scaffolded, opinionated CLI framework, aimed at the same gap, which in Rust is the gap between a pile of excellent crates and a coherent product.

It’s not a port. Transliterating Go idioms into Rust produces code that fights the language, so RTB reaches the same outcomes through Rust’s own mechanisms instead. The posts after this one walk through the specific cases: how commands register, how the builder works, how errors are reported, and a few things RTB can do that the Go version structurally can’t. First, though, the thing the exercise taught me about my own design.

Just enough Rust to follow along

Tue, 21 Apr 2026 00:00:00 +0000

I’m about to write a run of posts about building rust-tool-base, and they lean on a handful of Rust ideas that I’d otherwise have to keep stopping to explain. So here they are, up front, in one place. You don’t need to write Rust to follow the series. You need a feel for maybe six concepts, and this is a quick, friendly tour of them. If you already write Rust, skip it with my blessing.

Ownership and borrowing

This is the one everybody mentions, and the one the whole language is built around. Every value in Rust has exactly one owner, and when the owner goes away, the value is cleaned up. No garbage collector deciding when, no manual free. If you want to let another piece of code use a value without handing over ownership, you borrow it: &thing lends it out for reading, &mut thing for writing, and the compiler enforces that you can’t, say, change something while someone else is reading it.

The payoff, and the reason people put up with the up-front fuss, is that an entire family of bug (use-after-free, data races, dangling pointers) becomes a compile error rather than a 3am one. When a post says something “moves” or is “borrowed”, that’s all this is.

Traits are Rust’s interfaces

A trait is a named set of methods a type can promise to provide, exactly like an interface in Go or Java. impl Command for Greet { ... } reads as “the Greet type fulfils the Command contract.”

Two bits of syntax show up a lot. dyn Command means “some value whose concrete type I don’t know, but which implements Command”, decided at runtime. And because the compiler needs a known size, you usually see it wrapped: Box<dyn Command> is “a pointer to some Command, whatever it turns out to be.” Whenever the series talks about a registry of Box<dyn Something>, it just means a list of different types that all satisfy the same trait.

Enums, `match`, and `#[non_exhaustive]`

A Rust enum is more than a list of named numbers; it’s a proper “one of these” type, and each variant can carry its own data. You handle one with match, which is like a switch that the compiler forces you to make complete: miss a case and it won’t build.

That completeness is usually a gift, but it’s awkward for a library, because adding a new variant would break everyone’s match. The fix is the attribute #[non_exhaustive]: it tells code outside the library “you must keep a catch-all _ => arm, because I reserve the right to add variants later.” With that in place, growing the enum is a non-breaking change. (One whole post turns on a subtle way to accidentally cancel that promise.)

The type system carries facts, not just shapes

Here’s an idea that surprises people coming from other languages: a Rust type often encodes more than “this is a number” or “this is a list.” The size of a fixed array is part of its type, so [Feature; 11] and [Feature; 12] are genuinely different, incompatible types, not one type holding a different count.

Pushed further, you can make the type track state. A “typestate” builder changes type as you call it, so .build() literally doesn’t exist as a method until every required field has been set, and forgetting one is a compile error rather than a runtime surprise. When a post says the compiler “won’t let you” do something, this is usually how: the mistake was made unrepresentable in the types.

`Result` and the `?` operator

Rust has no exceptions. A function that can fail returns a Result<T, E>: either Ok(value) or Err(problem), and you can’t use the value without acknowledging the error case. Writing that check by hand everywhere would be miserable, so there’s a shorthand: the ? operator. let x = thing()?; means “if this returned an error, return it up to my caller right now; otherwise give me the value.” Errors travel up the call stack as ordinary return values until something handles them, or until they fall out of main.

Crates, the workspace, and features

A crate is Rust’s unit of compilation, roughly “a library or binary.” A workspace is a bundle of crates built together, which is how rust-tool-base is laid out: rtb-app, rtb-cli, rtb-config and so on, each its own crate. And Cargo features are compile-time switches declared in Cargo.toml: turn a feature off and the code it guards, and any dependency it pulled in, is never compiled into your binary at all. Not disabled at runtime; simply absent. That distinction does real work in one of the posts.

That’s the toolkit

Ownership and borrowing, traits and dyn, enums and match and #[non_exhaustive], types that carry facts, Result and ?, and crates with features. Six ideas, and they’re enough to read everything else in this series without tripping over the language itself. Where a post needs a seventh thing, it’ll explain it in passing. Now, on with the actual building.

Rust on PHP Boy Scout

The scaffolder that won't hand you code that doesn't compile

Which CLI library should you start with?

Go: a ladder you climb

Rust: a ladder you descend

Same rule, opposite ends

A flag is not a setting

Accurate, and still wrong

What the noun names

Why they’re two things at all

The change

Name the tap

Everyone wants Rust's safety, nobody wants Rust

What everyone’s actually after

Rust didn’t invent any of this

Credit where it’s due: C# is doing this properly

A contract is not a guarantee

Discipline never scaled, and that’s not an insult

The part that changed my mind

None of this means rewrite everything in Rust

What it comes down to

Three traps release-plz sets for a Rust workspace

First, what release-plz is doing

Trap 1: the default tag template is built for one crate, not a workspace

Trap 2: “one release for the whole workspace” isn’t a setting, it’s a category error

Trap 3: a release reads its config from the release commit, not HEAD

If you set one thing

Same config, two answers

Rust brings its own toolchain

The gauntlet before the gun

“Tag v0.5.1 already exists”

I assumed the default

Same config, two answers

Doing it the way I’d have done it a year ago

Stop being clever and RTFM

From allow_failure to blocking

What allow_failure actually buys you

A check earns the right to block

trivy: blocked once there was nothing to block on

integration-tests: blocked once it could actually run

coverage: blocked once it could run at all, then once it cleared the bar

The three I left advisory, on purpose

The upshot

Pure-Rust Git, no git binary

A VCS subsystem with two halves

A capability ahead of its consumer

Three ways to do Git, and the one worth picking

Repo is a foundation, not a façade

Stepping back

clap's global flag, except in a passthrough subtree

How the global flag is meant to work

The one place it goes missing

Parse it yourself, then strip it

The takeaway

Secrets that scrub themselves from RAM

What go-tool-base already settled

The two ways a secret leaks after you’ve loaded it

SecretString closes both

Discipline versus the type system

The gist

Two telemetry events, one mangled line

A format with exactly one rule

“Appending is atomic, though, isn’t it?”

The fat event that went over the edge

The fix isn’t a bigger write, it’s a smaller gate

The bit even the lock can’t fix

What it comes down to

Supporting a provider, or actually using it

The pull toward one interface

What “unified” quietly costs you

The escape hatch

A hatch, not a leak

To sum up

Errors without an error handler

What go-tool-base built

The shape of a Rust error

There is no handler, there’s a convention

Errors are values, all the way

Worth remembering

Two kinds of feature flag

`Repo` is a foundation, not a façade

`SecretString` closes both

`forbid`, not just `deny`

So `all()` returns a slice