V1: Multi-repo local build system

[ritorhymes]

Summary

This issue tracks a coordinated multi-repo local build system for the EIP WG stack. The original full preprocessor implementation was opened as preprocessor#9 and has since been split into the stacked review PRs preprocessor#10, preprocessor#11, preprocessor#12, and preprocessor#13. This issue also tracks the downstream wiring PRs in EIPs#10, ERCs#10, and template#1.

The goal is to make the full site pipeline practical to run locally, reduce multi-repo setup and orchestration friction, and provide a coherent local developer workflow across preprocessor, EIPs, ERCs, template, and eipw.

Problem

The current stack is split across multiple repos, but the practical build path is still oriented around CI and fragmented local conventions.

That creates a few problems:

Multi-repo assembly has no bootstrap path. A contributor who clones EIPs or ERCs has no direct way to get to a working local build. They have to reverse-engineer the workflow from CI definitions and scattered docs, finding and installing the toolchain, cloning and placing sibling repos, and reconstructing the right build commands by hand.

Site builds and editorial validation are not separated. build-eips check runs eipw lints and full site validation as one pass. A contributor who wants to know whether their proposal passes editorial checks has to run the entire site pipeline. There is no way to express “validate these changed files” as a distinct operation.

No local dev-serve or dirty workflow path. Building locally requires a clean working tree and a full rebuild on every change. There is no way to serve the site locally and see working-tree edits reflected without committing and rebuilding from scratch.

Solution

This change set introduces a local orchestration and build layer centered in preprocessor.

• workspace bootstrap that clones sibling repos, generates a local justfile, and validates readiness
• disposable build-time repos assembled from workspace sources for site checks, builds, and serving
• separate site commands (check, build, serve, preview) and editorial commands (editorial lint, editorial build) routed through eipw
• dirty workflow support for building and serving from uncommitted working-tree edits
• built-output preview as a separate path from local dev-serving
• checked-in scripts/dev-setup entrypoints in EIPs, ERCs, and template that bootstrap the workspace and point contributors at the local workflow
• CI aligned to the explicit editorial command surface

Covered Workflows

Workspace Bootstrap

A contributor who clones EIPs or ERCs can now use a checked-in entrypoint to install or locate build-eips, clone any missing sibling repos, generate local helper tasks, and validate that the workspace is ready.

Site Validation and Full Builds

From an active content repo, contributors can now run explicit site commands for validation and full output generation without reconstructing the pipeline from CI or scattered repo-specific conventions.

Dirty Local Iteration

The current local path assumes a clean working tree, which means tracked edits normally have to be committed before they can be exercised through the site pipeline.

This change set adds a dirty workflow path so contributors can build and serve from tracked working-tree edits without creating intermediate commits for each local validation or serve cycle.

Serve and Preview

serve runs the live Zola serving path for local site development, including the normal dev-server rebuild behavior as source changes are exercised locally.

preview is a separate path that serves already-built output without rebuilding, for inspecting generated artifacts after a completed site build.

Targeted Editorial Validation

Editorial checks can now be run against explicit proposal paths, batch input, working-tree selections, or upstream-relative selections as a distinct operation rather than only as part of a full site pass.

CI-Shaped Staging Verification

The same command surface can be exercised locally in staging mode for both editorial validation and full site builds, which gives contributors a more direct way to validate the behavior that downstream automation depends on.

Repo Breakdown

This coordinated local build system series is split across four PRs.

preprocessor (#9)

preprocessor implements the local multi-repo build system itself.

This PR adds the workspace model, the site and editorial command surfaces, the dirty workflow path, local serving and preview support, and the generated local helper/task layer that the downstream repos are wired around.

EIPs (#10) and ERCs (#10)

Both content repos add the same repo-local bootstrap and workflow wiring.

These PRs add the checked-in scripts/dev-setup entrypoint, update repo-facing local workflow guidance, and align CI with the explicit editorial command surface introduced in preprocessor.

template (#1)

template adds the same local bootstrap and workflow wiring for template consumers.

This PR adds the checked-in scripts/dev-setup entrypoint, updates contributor guidance, and aligns CI with the explicit editorial command surface introduced in preprocessor.

Architecture

Workspace Source Repos

The local system starts from a flat sibling-repo workspace. The primary workspace source repos are EIPs, ERCs, and theme, with optional local checkouts of preprocessor and eipw for platform development.

These are the persistent repos contributors edit and commit from.

Build-Time Repos and Built Output

Site commands do not operate directly on the mutable workspace source repos.

Instead, build-eips assembles disposable build-time repos under .local-build/.../repo and writes generated site output under .local-build/.../output. This separates the real workspace source repos from both the assembled build inputs and the final built artifacts.

Active Content Repo Model

Commands are anchored to an active content repo, either EIPs or ERCs.

That active repo determines which content tree is being validated or built, while sibling inputs are resolved through the workspace and profile model.

Command Surface

The command surface is partitioned into three layers:

• workspace commands for bootstrap and workspace maintenance
• site commands for site validation, builds, serving, and preview
• editorial commands for targeted proposal validation through eipw

This keeps workspace management, site pipeline operations, and editorial validation as distinct concerns.

Profiles and Overrides

The local system includes workspace profile support and local overrides.

Profiles cover normal local usage, parity-oriented checks against remote sibling inputs, and dirty workflow paths for tracked working-tree edits. Local overrides allow the active workspace to select local theme, sibling repo, and build root inputs when needed.

Validation

Validation for this change set covered the main local runtime, editorial, and CI-shaped paths.

The exercised paths included:

• clean runtime checks and full site builds
• dirty runtime checks, builds, and local serving
• parity profile runtime checks
• explicit editorial linting
• editorial --working-tree selection
• editorial empty-selection skip behavior

Final CI-shaped verification used a build-eips binary built from preprocessor#9 and the rewritten EIPs and ERCs branches.

From both content repos, the following commands were exercised successfully:

• build-eips --staging editorial build --against-upstream --format github
• build-eips --staging build

In both repos, the editorial selector resolved no changed proposal files relative to upstream, and the full staging site build completed successfully.

Dependency and Binary Footprint

This change set adds two new direct preprocessor dependencies:

• notify
• tiny_http

The Cargo.lock package count increased from 346 to 362 (+16).

Measured binary impact was modest in the shipped release build and more noticeable in debug builds. In prior comparison runs, the debug binary grew by roughly 5%, while the release binary grew by less than 1%.

Merge and Release Order

The coordinated PRs in this series should not merge all at once.

The intended order is:

1. merge preprocessor#9
2. cut a build-eips release from that merge
3. merge EIPs#10, ERCs#10, and template#1

Until the released build-eips binary includes the new editorial command surface, CI for the downstream PRs is expected to fail.

The downstream workflow changes consume the released build-eips binary. Until that release exists, local pre-release testing should use a binary built from preprocessor#9.

That binary can be invoked directly by path; no PATH changes are required. For example:

cd preprocessor
cargo build

B=$(pwd)/target/debug/build-eips

cd ../EIPs
$B --staging editorial build --against-upstream --format github
$B --staging build

cd ../ERCs
$B --staging editorial build --against-upstream --format github
$B --staging build

Out of Scope

This change set does not attempt to:

• add incremental site builds beyond the current local serving behavior
• redesign the underlying site generator or theme system
• vendor zola into preprocessor
• change eipw itself
• collapse the WG stack into a monorepo

Diagrams

Bootstrapping workspace

Workflow lanes