reconcilekit 0.1.0__py3-none-any.whl

reconcilekit/__init__.py

@@ -0,0 +1,43 @@
+"""reconcilekit -- a tiny stateless fetch-diff-apply reconciliation kernel.
+
+The pattern every fleet-wide config tool repeats: enumerate targets, fetch each
+one's current state, compare to the desired state, either report the plan
+(dry run) or apply it, classify the outcome into a small fixed vocabulary, and
+run the whole thing in bounded parallel with per-target failure isolation.
+"""
+
+from __future__ import annotations
+
+from .kernel import (
+    DEFAULT_JOBS,
+    HasName,
+    ReconcileError,
+    Result,
+    run_parallel,
+    run_reconcile,
+)
+from .render import print_status, progress_bar, result_line
+from .status import (
+    Status,
+    classify_status,
+    partition_fields,
+    summary_status,
+    unavailable_suffix,
+)
+
+__all__ = [
+    "DEFAULT_JOBS",
+    "HasName",
+    "ReconcileError",
+    "Result",
+    "Status",
+    "classify_status",
+    "partition_fields",
+    "print_status",
+    "progress_bar",
+    "result_line",
+    "run_parallel",
+    "run_reconcile",
+    "summary_status",
+    "unavailable_suffix",
+]

reconcilekit/kernel.py

@@ -0,0 +1,133 @@
+"""The reconciliation kernel: a fetch-then-branch skeleton for one target, and
+a bounded-parallel runner over a fleet of them with per-target failure
+isolation. Nothing here knows what a target is beyond its name.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import Generic, Protocol, TypeVar
+
+from .render import QUIET_STATUSES, console, print_status, progress_bar
+from .status import Status
+
+DEFAULT_JOBS = 6
+
+
+class ReconcileError(RuntimeError):
+    """A target's worker failed, or a run finished with failures.
+
+    Callers that need a domain-specific exception type (so `pytest.raises` and
+    `except` clauses can stay narrow) pass it as `run_parallel(..., error_cls=)`.
+    """
+
+
+class HasName(Protocol):
+    @property
+    def name(self) -> str: ...
+
+
+class ResultLike(Protocol):
+    status: Status
+    line: str
+
+
+Target = TypeVar("Target", bound=HasName)
+State = TypeVar("State")
+R = TypeVar("R", bound=ResultLike)
+
+
+@dataclass
+class Result(Generic[Target]):
+    target: Target
+    line: str
+    status: Status = Status.OK
+    tag: str | None = None
+
+
+async def run_reconcile(
+    *,
+    dry_run: bool,
+    fetch: Callable[[], Awaitable[State]],
+    plan_result: Callable[[State], R],
+    apply_result: Callable[[State], Awaitable[R]],
+) -> R:
+    """Read the target's current state once, then either report the plan (dry
+    run) or apply the change and report the outcome. Each worker keeps its own
+    planning, side effects, and result formatting in the three callables.
+    """
+    state = await fetch()
+    if dry_run:
+        return plan_result(state)
+    return await apply_result(state)
+
+
+async def run_parallel(
+    targets: Sequence[Target],
+    worker: Callable[[Target], Awaitable[R]],
+    jobs: int = DEFAULT_JOBS,
+    verbose: bool = False,
+    *,
+    error_cls: type[Exception] = ReconcileError,
+) -> list[R]:
+    """Runs worker(target) for each target concurrently (bounded by a semaphore
+    -- these are I/O-bound calls, not CPU-bound work), printing each result's
+    line as soon as it's ready (completion order, not submission order) above a
+    live progress bar, and returning every result.
+
+    A worker exception is caught inside call() itself -- not left to propagate
+    through the TaskGroup -- so one target failing doesn't cancel the others
+    (TaskGroup cancels every sibling task the moment any task raises). Instead
+    it's printed as a failure line and collected; once every target has been
+    attempted, any failures are raised together as a single `error_cls` so the
+    run still ends with a nonzero exit.
+
+    Unless verbose=True, a target already at its target state (UNCHANGED /
+    LIMITED_UNCHANGED) isn't printed live -- on a large fleet the handful of
+    lines that represent an actual change would otherwise be lost in a wall of
+    "unchanged: ..." lines. Suppressed lines are counted and reported as a
+    single dim summary line instead.
+    """
+    results: list[R] = []
+    failed_names: list[str] = []
+    unchanged_count = 0
+    sem = asyncio.Semaphore(jobs)
+
+    with progress_bar() as progress:
+        task = progress.add_task("Processing...", total=len(targets))
+
+        async def call(target: Target) -> None:
+            nonlocal unchanged_count
+            async with sem:
+                try:
+                    result = await worker(target)
+                except Exception as exc:  # noqa: BLE001 -- collected below, not swallowed
+                    failed_names.append(target.name)
+                    print_status(Status.FAILED, f"{target.name}: {exc}")
+                else:
+                    if not verbose and result.status in QUIET_STATUSES:
+                        unchanged_count += 1
+                    else:
+                        print_status(result.status, result.line)
+                    results.append(result)
+                finally:
+                    progress.advance(task)
+
+        async with asyncio.TaskGroup() as tg:
+            for target in targets:
+                tg.create_task(call(target))
+
+    if unchanged_count:
+        console.print(
+            f"  {unchanged_count} unchanged (rerun with --verbose to see them)",
+            style="dim",
+        )
+
+    if failed_names:
+        raise error_cls(
+            f"{len(failed_names)} target(s) failed: {', '.join(sorted(failed_names))}"
+        )
+
+    return results

reconcilekit/render.py

@@ -0,0 +1,54 @@
+"""Default terminal renderer for reconcile runs: a status symbol per line above
+a live progress bar, silenced when stdout isn't a terminal.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.progress import Progress
+
+from .status import Status
+
+console = Console()
+
+_STATUS_DISPLAY: dict[Status, tuple[str, str]] = {
+    Status.OK: ("✓", "green"),
+    Status.UNCHANGED: ("•", "green"),
+    Status.LIMITED: ("○", "yellow"),
+    Status.LIMITED_UNCHANGED: ("•", "yellow"),
+    Status.FAILED: ("✗", "red"),
+}
+
+QUIET_STATUSES = (Status.UNCHANGED, Status.LIMITED_UNCHANGED)
+
+
+def progress_bar(*, console: Console = console, **kwargs: Any) -> Progress:
+    """A Progress bound to `console` (module-level `console` by default),
+    silenced when its console isn't a terminal -- e.g. `cmd > file` or piping
+    into another command -- so its status text (which Progress still renders as
+    plain lines even without a tty) doesn't end up mixed into redirected output.
+    """
+    return Progress(console=console, disable=not console.is_terminal, **kwargs)
+
+
+def result_line(name: str, detail: str, status: Status) -> str:
+    prefix = (
+        "unchanged: " if status in (Status.UNCHANGED, Status.LIMITED_UNCHANGED) else ""
+    )
+    return f"{name:<30} {prefix}{detail}"
+
+
+def print_status(status: Status, line: str) -> None:
+    # Always goes through the single Console that Progress/Live owns
+    # (run_parallel passes it to Progress(console=...)): a second Console
+    # writing to a separate stream isn't coordinated by rich's Live redraw
+    # bookkeeping and can visually corrupt output on a real terminal.
+    symbol, color = _STATUS_DISPLAY[status]
+    # markup=False: `line` can contain target/error text with literal "[" (dict
+    # reprs, error messages) that would otherwise be parsed as rich markup.
+    # highlight=False: rich's default ReprHighlighter recolors numbers, paths,
+    # etc. within the line (e.g. a target named "foo-410"), fighting with the
+    # single status color we want for the whole line.
+    console.print(f"{symbol} {line}", style=color, markup=False, highlight=False)

reconcilekit/status.py

@@ -0,0 +1,55 @@
+"""The status vocabulary every reconcile result is classified into, plus the
+"enable a set of toggles, some of which are gated" summarising helpers.
+"""
+
+from __future__ import annotations
+
+import enum
+
+
+class Status(enum.Enum):
+    """How a target's result relates to the desired end state -- distinct from
+    a Result's tag, which is per-command bookkeeping for end-of-run summaries.
+    """
+
+    OK = "ok"  # full target reached, changed this run
+    UNCHANGED = "unchanged"  # full target reached, already was
+    LIMITED = "limited"  # best-effort (capped by plan/data) reached, changed this run
+    LIMITED_UNCHANGED = "limited_unchanged"  # best-effort reached, already was
+    FAILED = "failed"  # worker raised
+
+
+def classify_status(at_target: bool, changed: bool) -> Status:
+    if at_target:
+        return Status.OK if changed else Status.UNCHANGED
+    return Status.LIMITED if changed else Status.LIMITED_UNCHANGED
+
+
+def partition_fields(fields: dict[str, tuple[bool, bool]]) -> dict[str, list[str]]:
+    """Splits a `name -> (currently_enabled, available_here)` mapping into the
+    two lists every "enable a set of toggles" command reports: `would_enable`
+    (available but off) and `unavailable` (gated).
+    """
+    return {
+        "would_enable": [
+            name
+            for name, (enabled, available) in fields.items()
+            if available and not enabled
+        ],
+        "unavailable": [
+            name for name, (_enabled, available) in fields.items() if not available
+        ],
+    }
+
+
+def summary_status(summary: dict[str, list[str]]) -> Status:
+    """Status for a partition_fields() summary: at target once nothing is
+    gated, changed when there's anything left to enable.
+    """
+    return classify_status(
+        at_target=not summary["unavailable"], changed=bool(summary["would_enable"])
+    )
+
+
+def unavailable_suffix(unavailable: list[str]) -> str:
+    return f" (unavailable: {', '.join(unavailable)})" if unavailable else ""

reconcilekit-0.1.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: reconcilekit
+Version: 0.1.0
+Summary: A tiny stateless fetch-diff-apply reconciliation kernel for fleet-wide config tools
+Project-URL: Homepage, https://github.com/hugoh/gh-workflows/tree/main/reconcilekit
+Project-URL: Issues, https://github.com/hugoh/gh-workflows/issues
+Project-URL: Repository, https://github.com/hugoh/gh-workflows
+Author: Hugo Haas
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: rich>=13
+Description-Content-Type: text/markdown
+
+# reconcilekit
+
+A tiny, stateless fetch-diff-apply reconciliation kernel — the pattern a
+fleet-wide config tool repeats for every resource it manages, with none of the
+domain specifics.
+
+There is no state file, no backend, no daemon. Each run reads live state,
+compares it to what you want, and either reports the plan or applies it.
+
+## The pattern
+
+1. **Enumerate targets** — anything with a `name`.
+2. **Fetch** each target's current state.
+3. **Compare** to the desired state: already there? partly blocked?
+4. **Dry-run** → report the plan, or **apply** → mutate and report the outcome.
+5. **Classify** into `Status` (`OK`, `UNCHANGED`, `LIMITED`, `LIMITED_UNCHANGED`,
+   `FAILED`).
+6. **Run the fleet in bounded parallel**, isolating per-target failures and
+   raising them together at the end.
+
+## API
+
+Full API reference, generated from the docstrings:
+[hugoh.github.io/gh-workflows/reconcilekit](https://hugoh.github.io/gh-workflows/reconcilekit/)
+(rebuilt on every push that touches this package -- see
+`.github/workflows/docs.yml`).
+
+## Example
+
+```python
+import asyncio
+from dataclasses import dataclass
+
+from reconcilekit import (
+    Result,
+    Status,
+    classify_status,
+    result_line,
+    run_parallel,
+    run_reconcile,
+)
+
+
+@dataclass
+class File:
+    name: str
+    path: str
+    want: str
+
+
+def make_worker(dry_run: bool):
+    async def worker(f: File) -> Result[File]:
+        async def fetch() -> str:
+            return f.path_text()  # read current contents
+
+        def plan(current: str) -> Result[File]:
+            status = classify_status(
+                at_target=current == f.want, changed=current != f.want
+            )
+            return Result(
+                f,
+                result_line(
+                    f.name, "would rewrite" if current != f.want else "ok", status
+                ),
+                status,
+            )
+
+        async def apply(current: str) -> Result[File]:
+            if current != f.want:
+                f.write(f.want)
+            status = classify_status(at_target=True, changed=current != f.want)
+            return Result(
+                f,
+                result_line(f.name, "written" if current != f.want else "ok", status),
+                status,
+            )
+
+        return await run_reconcile(
+            dry_run=dry_run, fetch=fetch, plan_result=plan, apply_result=apply
+        )
+
+    return worker
+
+
+asyncio.run(run_parallel(files, make_worker(dry_run=True)))
+```
+
+## Consumers
+
+`repo-admin/` (in this repo) uses it for every account-wide GitHub `sync`
+command, consumed as a uv workspace member there.

reconcilekit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+reconcilekit/__init__.py,sha256=cjUcDWryeNmxbfMwfnpfZ8Ojz-JRghvWzJY4PYUj1BE,1028
+reconcilekit/kernel.py,sha256=LNru0fpigCA-cBWkEwmovxClj4i6VCSkUwq3JuSMvXw,4446
+reconcilekit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+reconcilekit/render.py,sha256=SXANXXA0yrVErfLSZ842dbNKNiHw8M2HpdBAi-7aJ3M,2167
+reconcilekit/status.py,sha256=Bfn738tU_Ly3RYranGLLUu-yQK3ekwoLr7XFy2ePAik,1981
+reconcilekit-0.1.0.dist-info/METADATA,sha256=l6_41FMv6li2QWiEan-KPisq3h4nNFCi5esGRjbgynU,3506
+reconcilekit-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+reconcilekit-0.1.0.dist-info/licenses/LICENSE,sha256=qCv-aayDkFcB09IGjnNETtrZ31NOA1tdCq4IJ7nZObc,1066
+reconcilekit-0.1.0.dist-info/RECORD,,

reconcilekit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

reconcilekit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugo Haas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.