rlsbl v0.113.0 /rlsbl.commands.monorepo.mirror_cmd
Updated
On this page

Monorepo mirror reconciler that converges a projects subtree mirror to a tool-owned derived state with dry-run planning and a foreign-commit tripwire.

#rlsbl.commands.monorepo.mirror_cmd

#rlsbl.commands.monorepo.mirror_cmd

Monorepo mirror reconciler.

The subtree mirror of a monorepo project is a TOOL-OWNED, derived artifact. Nothing is ever authored on it by hand -- it is regenerated from the monorepo whenever the project's history advances. Force-push (with lease) is the routine write, not an exceptional one.

The command is an observe-then-converge reconciler:

  • rlsbl monorepo mirror <project> -- observe, then converge (apply).
  • rlsbl monorepo mirror <project> --dry-run -- observe and report a plan only

(zero writes beyond the loose objects a branchless git subtree split leaves in the monorepo object store).

Desired state of the mirror's main:

  • its tip is exactly one scaffold commit atop the CURRENT split-lineage commit,

where the split-lineage commit equals the deterministic branchless subtree split of the project's current history, and

  • the scaffold commit touches only scaffold-owned paths.

A tripwire enforces the contract with no heuristics: the remote tip must be EITHER a bare split-lineage commit (the current split SHA or an older one -- covers pre-scaffold-layer mirrors) OR exactly one commit atop a split-lineage commit whose changed paths are all scaffold-owned. Anything else is a foreign commit -- a contract violation -- and is a hard error that touches nothing.

#MirrorError

A hard error in the mirror reconciler (contract violation, auth, etc.).

#MirrorPlan

The observed state of a mirror relative to its monorepo source.

state is one of: * "converged" -- scaffold commit atop the current split; nothing to do. * "behind" -- a scaffold layer exists atop an OLDER split; a new split is available. * "scaffold_missing" -- the tip is a bare split-lineage commit (no scaffold layer). May also be behind (older split). * "contract_violated" -- a foreign commit exists on the mirror. * "virgin" -- the remote is missing or empty.

#split_push_needed

python
def split_push_needed(self) -> bool

Whether converging requires pushing a fresh bare split to main.

#_git

python
def _git(args, cwd=None, timeout=180)

Run a git command, returning the CompletedProcess (never raises).

#_git_ok

python
def _git_ok(args, cwd=None, timeout=180)

Run a git command, returning stdout stripped; raise MirrorError on failure.

#is_ancestor

python
def is_ancestor(ancestor, descendant, cwd)

True iff ancestor is an ancestor of (or equal to) descendant.

Returns False when either object is unknown to the repo at cwd (git exits non-zero), which is exactly the "not part of our lineage" signal the tripwire needs.

#classify_remote

python
def classify_remote(remote, cwd)

Classify the remote via git ls-remote.

Returns a tuple (kind, tip, detail) where kind is one of: * "missing" -- ls-remote failed and stderr does not look like auth. * "auth" -- ls-remote failed with an authentication/authorization error. * "empty" -- ls-remote succeeded but the remote has no refs. * "no_main" -- the remote has refs but no refs/heads/main. * "populated" -- refs/heads/main exists; tip is its SHA.

#compute_split_sha

python
def compute_split_sha(root, project_path)

Deterministic branchless subtree split of project_path.

Runs git subtree split --prefix=<path> WITHOUT -b: it prints the resulting commit SHA to stdout, creates no refs, and materializes the whole synthetic split lineage as loose objects in the monorepo (so later ancestry checks against older split commits resolve locally).

#_clone_main

python
def _clone_main(remote, dest)

Full single-branch clone of main so the whole tip layer is inspectable.

#_first_parent_chain

python
def _first_parent_chain(clone_dir, tip)

First-parent commit chain from tip (newest first).

#_changed_paths

python
def _changed_paths(clone_dir, base, tip)

Paths changed between base and tip (name-only).

#_commit_paths

python
def _commit_paths(clone_dir, commit)

Paths changed by a single commit (vs its first parent).

#_load_owned_predicate

python
def _load_owned_predicate(clone_dir)

Build the is scaffold-owned? predicate for this mirror.

Reads the clone's .rlsbl/managed-files.json (if present) and unions its keys with the pinned prefixes/files.

#observe

python
def observe(remote, root, project_path)

Observe the mirror and return a :class:MirrorPlan.

Mutation-free apart from the loose objects the branchless split leaves in the monorepo object store.

python
def print_plan(plan, remote, project_path)

Print a human-readable plan for --dry-run (zero writes).

#_push_bare_split

python
def _push_bare_split(remote, split_sha, expected_tip, root)

Push the bare split commit to main.

Uses force-with-lease against expected_tip when the branch already exists; a plain push when creating the branch on a virgin remote.

#_run_scaffold

python
def _run_scaffold(clone_dir, sub_config_path)

Copy the project's .rlsbl/config.json into the clone and scaffold.

Runs rlsbl scaffold --no-auto-commit so the reconciler owns the commit. A non-zero scaffold exit is a HARD ERROR (no warn-and-continue).

#_converge

python
def _converge(plan, remote, root, project_path, sub_config_path)

Bring the mirror to the desired state. Idempotent; interrupted runs heal.

#_cmd_mirror

python
def _cmd_mirror(flags, project_root)

Observe-then-converge reconciler for a project's subtree mirror.

flags["project"] -- workspace project name. flags["dry-run"] -- plan only (no writes).

Search