# patchula design

> The goals and principles behind Count Patchula, a replacement for a scheduled Renovate runner: architecture, scope and run modes.

## Goal

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

The user-facing [principles](https://count-patchula.sweepy.dev/guide/how-it-works/#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

Pkl, evaluated in process with `pklr`; see [configuration](https://count-patchula.sweepy.dev/guide/configuration/).

## Architecture

- crates/

  - config/ Pkl schema, evaluation (pklr), typed model, rule engine, templates

    - …

  - versioning/ every version scheme in Versioning

    - …

  - datasource/ registry lookups with conditional GETs, through http/ and github/

    - …

  - notes/ release notes for changed dependencies: upstream changelogs and releases, rendered for PR bodies

    - …

  - mise/ tool version lookups through the pinned `mise ls-remote`

    - …

  - manager/ per-ecosystem extraction, the proposal facts a declaration answers and surgical edits, regex managers

    - …

  - lookup/ batch-wide deduplicated lookups, update classification, grouping

    - …

  - engine/ batch lookup and branch writing, shared by the CLI and server

    - …

  - update/ branch plans, API commits, PRs, dashboard

    - …

  - lockfiles/ the lockfile contract between update and the tool runtime

    - …

  - tools/ the real ecosystem tools that regenerate lockfiles, with the pinned tool store

    - …

  - github/ REST and GraphQL client, App tokens, rate-limit governor

    - …

  - cache/ SQLite: HTTP entries, release lists, typed state

    - …

  - http/ reqwest transport boundary, shared network pool

    - …

  - process/ external commands with an explicit environment and time limit

    - …

  - server/ GitHub App server over the engine

    - …

  - testkit/ dev-dependency only: redacted recording and offline replay

    - …

  - report/ versioned batch JSON caller contract

    - …

  - words/ the shared vocabulary every crate speaks: managers, sources, schemes, update kinds

    - …

  - cli/ `patchula` binary, 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

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`.

## Scope

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](https://count-patchula.sweepy.dev/renovate/compatibility/) lists what is supported.

## 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](https://count-patchula.sweepy.dev/guide/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

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.
