patchula design
Replace a scheduled Renovate CLI runner with a tool that updates the dependencies of about a dozen repositories in seconds, not minutes.
Measured baseline (Renovate 44.155.6, warm caches, one EC2 c7i.large):
| Time | |
|---|---|
| Batch of 12 repos, before our release-notes patch | 6.7 min |
| Largest repository alone, after the patch | 44 s |
| Smallest repository alone, after the patch | 13 s |
Renovate’s time went to processing one repository at a time with per-repository caches, fetching full release and tag histories through paginated APIs, re-parsing every changelog per version, and starting Node per process. What remains is GitHub round-trips and lockfile tools, which no language change removes.
Principles
Section titled “Principles”The user-facing principles apply. Inside the engine they mean:
- Each lookup (data source and package) runs at most once per batch, however many repositories use the package.
- If the default branch’s commit and the resolved config are unchanged, the previous extraction is reused. If no new versions appeared either, no branch work happens.
Configuration
Section titled “Configuration”Pkl, evaluated in process with pklr; see configuration.
Architecture
Section titled “Architecture”Directorycrates/
Directoryconfig/ Pkl schema, evaluation (pklr), typed model, rule engine, templates
- …
Directoryversioning/ every version scheme in Versioning
- …
Directorydatasource/ registry lookups with conditional GETs, through http/ and github/
- …
Directorynotes/ release notes for changed dependencies: upstream changelogs and releases, rendered for PR bodies
- …
Directorymise/ tool version lookups through the pinned
mise ls-remote- …
Directorymanager/ per-ecosystem extraction, the proposal facts a declaration answers and surgical edits, regex managers
- …
Directorylookup/ batch-wide deduplicated lookups, update classification, grouping
- …
Directoryengine/ batch lookup and branch writing, shared by the CLI and server
- …
Directoryupdate/ branch plans, API commits, PRs, dashboard
- …
Directorylockfiles/ the lockfile contract between update and the tool runtime
- …
Directorytools/ the real ecosystem tools that regenerate lockfiles, with the pinned tool store
- …
Directorygithub/ REST and GraphQL client, App tokens, rate-limit governor
- …
Directorycache/ SQLite: HTTP entries, release lists, typed state
- …
Directoryhttp/ reqwest transport boundary, shared network pool
- …
Directoryprocess/ external commands with an explicit environment and time limit
- …
Directoryserver/ GitHub App server over the engine
- …
Directorytestkit/ dev-dependency only: redacted recording and offline replay
- …
Directoryreport/ versioned batch JSON caller contract
- …
Directorywords/ the shared vocabulary every crate speaks: managers, sources, schemes, update kinds
- …
Directorycli/
patchulabinary, defined with usage- …
Async runtime: tokio. HTTP: reqwest with HTTP/2 and rustls. Errors and diagnostics: miette. Terminal UI: ratatui, only on interactive terminals.
Proposal facts
Section titled “Proposal facts”Everything lookup, the engine and update need to know about a declaration to
propose for it — whether its ref pins to a commit, whether a range declares a
supported runtime rather than an installed version, whether its lockfile can
move — is a fact its ecosystem’s descriptor states. Callers read
Dependency::proposing() (crates/manager/src/proposal.rs), a Proposing
struct of named fact fields computed from the dependency, never stored on it.
The descriptors implement the required Ecosystem::proposing hook; lookup
holds the policy that consumes the facts. Facts about the version scheme
rather than the declaration live one crate down, on Versioning
(crates/versioning/src/lib.rs): a requirement’s floor, whether a
candidate stays on the same_release_line, and satisfies over the
declared range.
A new manager adds a Manager variant in words, a descriptor type in
manager, and its arm in ecosystem(), which is an exhaustive match.
proposing has no default body and Proposing has no Default, so the
descriptor does not compile until it states every fact. The compiler closes
the manager axis; the oracle in proposal.rs, which keeps the predicates the
facts replaced verbatim under #[cfg(test)], closes the kind and source axes
by asserting equality over every Manager × DependencyKind × Source.
GitHub only. Out of scope: other platforms, onboarding PRs, hosted services, Docker-based tool installation, arbitrary post-upgrade commands and encrypted config. The compatibility matrix lists what is supported.
Run modes
Section titled “Run modes”One engine runs every batch, so a batch behaves the same however it started.
The CLI (patchula run, patchula lookup) runs one batch with a token the
caller supplies. The server
(patchula serve) mints installation tokens from GitHub App credentials and
keeps its queue and caches warm. With --remote, the CLI signs in with the
server’s App through GitHub’s device flow, and the server runs the batch with
its own credentials once the user is shown to have push access.
Tooling
Section titled “Tooling”All tools come from mise. Builds go through mr-boxington (mbx) locally and in
CI. The CLI is defined with usage, which also generates completions, Markdown
docs and the man page. Performance is tracked with tak, report-only for now.
Tests never touch the network: they replay responses recorded by patchula
itself.
Linting is hk, configured in hk.pkl. mise run hooks:install installs a
pre-commit git hook that runs hk through mise. It fixes the staged files with
rustfmt and pkl format, checks that mise fmt has nothing to change, and
runs jactionlint and zizmor on the workflows, nu-lint on the nu file tasks and
betterleaks on every staged file. Mark a test credential betterleaks reports
with a trailing // betterleaks:allow comment on its line. nu-lint reads
nu-lint.toml, where each rule group is either an error or off; silence a
single finding with a # nu-lint-ignore: <rule> comment on the line before it.
Commit messages and pull request titles are not checked, since pull requests
are squash merged with a message written at merge time.
mise run lint runs hk check --all: the pre-commit checks on the whole tree
plus Clippy, which is too slow for every commit. CI’s lint job runs
mise run lint:ci instead, with the base branch or the commit before a push,
so each step checks only the files that changed, and Clippy runs only when
Rust sources, Cargo files or mise.toml change. hk’s findings go to GitHub
code scanning as SARIF, which shows them on the diff.
CI’s first job sorts the changed paths with dorny/paths-filter: a docs-only
change skips the Rust jobs and leaves the Rust toolchain out of lint, and a
change outside docs/ and the mise files skips the docs build. Caches are plain
actions/cache and mr-boxington entries that GitHub evicts on its own.
This site is Astro Starlight, in docs/, served from Cloudflare Workers and
built from main with no per-release versions. mise run docs:build builds it
and mise run docs:dev serves it with live reload.
© 2026 Sweepy
