modelith-dbt 0.7.1__tar.gz → 0.7.2__tar.gz

{modelith_dbt-0.7.1 → modelith_dbt-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: modelith-dbt
-Version: 0.7.1
+Version: 0.7.2
 Summary: Ontology-anchored, git-native data modeling tool for dbt-core teams
 License: Apache-2.0
 License-File: LICENSE

{modelith_dbt-0.7.1 → modelith_dbt-0.7.2}/docs/product-strategy/modelith-enterprise-plugin-architecture.md

@@ -19,12 +19,15 @@ This is already the written intent of the repo:
   shared policy file + a posted PR report** is **paid (Team)**. Server/enforcement features are
   gated by being a service you authenticate to — no shipped key to crack.
 
-**Two decisions locked with the user (2026-10-04):**
-1. **Gate delivery = GitHub App first** (not a hosted control plane). The gate runs in the
-   *customer's* CI; Modelith hosts no customer data. Fastest to revenue, lowest ops. Matches the
+**Decisions locked with the user:**
+1. **(2026-10-04) Gate delivery = GitHub App first** (not a hosted control plane). The gate runs in
+   the *customer's* CI; Modelith hosts no customer data. Fastest to revenue, lowest ops. Matches the
    spec's own open-decision #1 ("Taking this one next").
-2. **Plugin seam = Python entry-point registries.** Core exposes stable registration hooks;
-   enterprise registers into them when installed.
+2. **(2026-10-04) Plugin seam = Python entry-point registries.** Core exposes stable registration
+   hooks; enterprise registers into them when installed.
+3. **(2026-10-18) Versioning coupling = independent SemVer + a compatibility range** (not lockstep).
+   Enterprise has its own version line and pins core as `>=X.Y.0,<X.(Y+1).0`; core treats the seam
+   surface as a public API contract (minor bump when it changes). See **Track 2.5**.
 
 **The decisive finding from codebase exploration:** the drift *engine* is already complete and
 free; only the *enforcement wiring* is missing. And the entry-point seam already exists once, as
@@ -119,7 +122,8 @@ hosted Studio) — building all four now is over-engineering before a customer e
 A new **separate private repository** (not a package inside this monorepo), so the license story
 is clean and the core never imports it.
 - `pyproject.toml`: dist name `modelith-enterprise`, **commercial license** (per spec §8 line 214),
-  `dependencies = ["modelith-dbt>=<pinned>"]`. Registers into the new seam:
+  `dependencies = ["modelith-dbt>=0.7.0,<0.8.0"]` — a compatibility range, not a lockstep pin; see
+  **Track 2.5** for the versioning model. Registers into the new seam:
   `[project.entry-points."modelith.commands"] ci = "modelith_enterprise.ci:register"`.
 - Package `modelith_enterprise/` with a `ci.py` that `register(app)`s an `mdl ci` Typer command.
   Imports from core's public API only (`mdl_reverse.drift`, `mdl_reverse.render`,
@@ -129,6 +133,57 @@ is clean and the core never imports it.
   the entry point makes `mdl ci` appear with zero core changes) and the covenant boundary.
 - Its own CI mirroring the core's `ci.yml` (lint + pytest).
 
+### Track 2.5 — Release-cycle & versioning coupling (how enterprise pins to core)
+
+**Decision (2026-10-18): Independent SemVer + a compatibility range, NOT lockstep.** This resolves
+the `>=<pinned>` placeholder in Track 2.
+
+**The tension.** Enterprise reaches into core through the seam (`compute_drift`, `DriftReport`,
+`render_markdown`, `ModelRepo`, the `modelith.commands` entry-point protocol). Pin too loosely
+(`modelith-dbt>=0.7.0`, no ceiling) and a future core change silently breaks the paid gate in the
+*customer's* CI — the worst place to find out. Pin too tightly (`==0.7.0`) and every core patch
+forces an enterprise release and blocks customers from upgrading the free CLI. Neither works.
+
+**The model.**
+- **Enterprise has its own version line** (`modelith-enterprise 1.0.0`, independent of core's
+  `0.7.x`). The version number must not imply a false coupling to core's number.
+- **Enterprise pins core as a compatibility RANGE:** `modelith-dbt>=X.Y.0,<X.(Y+1).0` (start
+  `>=0.7.0,<0.8.0`). The lower bound is the minimum core that has the seam enterprise needs; the
+  upper bound is the next core minor, which enterprise has not yet certified.
+- **Enterprise widens the range only after its CI certifies the new core minor** (see the matrix
+  test below). Certification, not a date, moves the ceiling.
+
+**The core (`modelith-dbt`) SemVer rule this forces — a process change worth adopting now.** Treat
+the seam surface as a public API contract:
+- **Patch (0.7.0 → 0.7.1):** bug fixes, canvas changes, anything NOT touching the seam surface.
+  Guaranteed seam-safe; enterprise unaffected. (Note: looser than today's habit of shipping features
+  in 0.6.x patches — once enterprise exists, features that change the seam go in a minor.)
+- **Minor (0.7.x → 0.8.0):** new features, OR any change to the seam contract (a `compute_drift`
+  signature change, a `DriftReport` field change, the `render_markdown` body, the repo API, the
+  entry-point protocol). A minor bump is the signal to enterprise: "re-certify before widening your
+  pin." Pre-1.0, minor carries the "watch out" weight; at core 1.0, a breaking-seam change becomes a
+  major bump.
+
+**The mechanism that makes "independent + range" safe (build this with the scaffold, Track 2):**
+1. **Declare the seam surface explicitly** — a short `SEAM.md` in the core repo (or a
+   `mdl_core.__api__` tuple) listing exactly what enterprise may import. Anything not listed is
+   internal and may change in a patch. This turns "don't break the seam" from folklore into a
+   checkable contract.
+2. **Enterprise CI runs a core-version MATRIX** — on every enterprise build, install it against (a)
+   the lowest pinned core and (b) the latest core within/just above the range, then run `mdl ci`
+   against a breaking-drift fixture and assert exit code + the posted markdown. If the latest core
+   breaks the seam, the matrix goes red **in the enterprise repo**, never in a customer's CI. This
+   is the single highest-value piece of the coupling and the gate that lets the range be trusted.
+3. **The pin lives in enterprise and is a range.** When core ships a new minor, the matrix tests it;
+   green → widen the ceiling and release enterprise; red → core broke the seam (should have been a
+   minor, which it was) → fix core or adapt enterprise before widening.
+
+**Validate the coupling before the feature.** Scaffold the enterprise repo (Track 2) with a trivial
+`mdl ci` STUB — one command that prints "enterprise loaded, core X.Y.Z" — as soon as the Track 1a
+seam lands, BEFORE building the real gate (Track 3). The stub proves the whole mechanism end to end
+(entry-point discovery, the range pin, the clean-install isolation, the matrix test) cheaply, so the
+*mechanism* is de-risked separately from the *feature*.
+
 ### Track 3 — The CI drift gate (the first paid feature, in `modelith-enterprise`)
 
 **3a. `mdl ci` command** (enterprise) — the thin wiring over the free engine:
@@ -177,14 +232,19 @@ List it as the natural follow-on once the gate ships; do not build it in this mi
 - Enterprise repo: install it into a scratch venv alongside `modelith-dbt`, confirm `mdl ci` appears
   in `mdl --help` via the entry point with **zero** edits to the installed core; run `mdl ci`
   against `demos/fixtures` with a breaking drift and confirm exit non-zero + the posted markdown.
+- Enterprise core-version **matrix** (Track 2.5): the enterprise CI installs it against both the
+  lowest pinned core and the latest core in range and asserts the gate still passes — so a
+  seam-breaking core change goes red in the enterprise repo, not in a customer's CI.
 - Clean-install Docker check (`./sandbox/clean-install/run.sh`) — core-only install still has NO
   `mdl ci` (proves the core never depends on enterprise) and all free flows work.
 
 ## Sequencing & risk posture
 
-- **Order:** Track 1a (seam) → 1b (CLI unify + server boundary) → Track 2 (scaffold) → Track 3
-  (gate). 1a unblocks everything; 1b is the defect fix the user explicitly wanted and the identity
-  groundwork; 2+3 are the paid wedge. Each lands independently and keeps the tree green.
+- **Order:** Track 1a (seam) → 1b (CLI unify + server boundary) → Track 2 (scaffold, incl. the
+  Track 2.5 versioning model + a trivial `mdl ci` stub to prove the coupling) → Track 3 (gate). 1a
+  unblocks everything; 1b is the defect fix the user explicitly wanted and the identity groundwork;
+  the Track 2 stub de-risks the mechanism before Track 3 invests in the feature; 2+3 are the paid
+  wedge. Each lands independently and keeps the tree green.
 - **Covenant safety:** nothing local moves behind the paywall — `mdl drift`/`--check` stay free and
   unchanged; the paid value is purely the shared-policy + PR-posting + authenticated enforcement
   layer, which genuinely needs a team/server. The clean-install Docker check is the guard that the

{modelith_dbt-0.7.1 → modelith_dbt-0.7.2}/packages/cli/src/mdl_cli/main.py

@@ -3948,6 +3948,13 @@ def main() -> None:
     """
     _force_utf8_output()
 
+    # Apply subcommand plugins (e.g. the paid modelith-enterprise's `mdl ci`). Runs after
+    # the built-in commands are declared at import time and before the app is invoked, so a
+    # plugin sees them. Entirely fail-soft — a broken plugin never blocks the free CLI.
+    from mdl_cli.plugins import load_command_plugins
+
+    load_command_plugins(app)
+
     # Catch Typer's control-flow exceptions by the classes Typer ACTUALLY raises. This is
     # version-sensitive: older Typer vendors its own Click, so a parse error like
     # `NoSuchOption` derives from `typer._click.exceptions.UsageError` — a DIFFERENT class

modelith_dbt-0.7.2/packages/cli/src/mdl_cli/plugins.py

@@ -0,0 +1,81 @@
+"""Subcommand plugin seam — lets an installed package add `mdl` subcommands.
+
+This is the CLI counterpart of the config-resolver seam in
+`mdl_reverse/remote_config.py`: core exposes a stable entry-point group, and a
+separately-installed package (e.g. the paid `modelith-enterprise`) registers
+into it WITHOUT any edit to core. The core never imports the plugin; discovery
+is one-way.
+
+A plugin publishes an entry point in the `modelith.commands` group pointing at a
+callable `register(app)` that receives the root Typer app and adds commands or
+sub-apps to it:
+
+    # in the plugin's pyproject.toml
+    [project.entry-points."modelith.commands"]
+    ci = "modelith_enterprise.ci:register"
+
+    # modelith_enterprise/ci.py
+    def register(app):
+        app.add_typer(ci_app, name="ci")
+
+Failures are swallowed (logged at debug): a broken or incompatible plugin must
+never brick the free CLI. `load_command_plugins` is called once from `main()`
+after the built-in commands are declared, so a plugin can see — and, if it must,
+override — them.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import typer
+
+log = logging.getLogger("mdl.plugins")
+
+COMMAND_GROUP = "modelith.commands"
+
+_loaded = False
+
+
+def load_command_plugins(app: typer.Typer) -> list[str]:
+    """Discover and apply subcommand plugins on the `modelith.commands` group.
+
+    Each entry point loads to a `register(app)` callable; we call it with the root
+    Typer `app`. Returns the names of the plugins that registered successfully (for
+    tests / a debug line); the list is empty when none are installed, which is the
+    normal case for the free CLI. Idempotent: only runs its discovery once per process.
+    """
+    global _loaded
+    if _loaded:
+        return []
+    _loaded = True
+
+    applied: list[str] = []
+    try:
+        from importlib.metadata import entry_points
+
+        eps = entry_points()
+        group = (
+            eps.select(group=COMMAND_GROUP)
+            if hasattr(eps, "select")
+            else eps.get(COMMAND_GROUP, [])
+        )
+        for ep in group:
+            try:
+                register = ep.load()
+                register(app)
+                applied.append(ep.name)
+            except Exception:  # noqa: BLE001 - a bad plugin must never break the CLI
+                log.debug("skipping command plugin %r: it failed", ep.name, exc_info=True)
+                continue
+    except Exception:  # noqa: BLE001 - discovery itself must never break the CLI
+        log.debug("command-plugin discovery failed", exc_info=True)
+    return applied
+
+
+def _reset_for_tests() -> None:
+    """Allow a test to re-run discovery after installing a fake entry point."""
+    global _loaded
+    _loaded = False

modelith_dbt-0.7.2/packages/cli/tests/test_command_plugins.py

@@ -0,0 +1,142 @@
+"""The `modelith.commands` subcommand plugin seam (mdl_cli.plugins).
+
+A separately-installed package (the paid modelith-enterprise) adds `mdl` subcommands by
+publishing a `register(app)` entry point in the `modelith.commands` group. These tests pin
+the two guarantees the free CLI depends on: a valid plugin's command appears, and a broken
+plugin is swallowed rather than bricking the CLI. We drive the real discovery path by faking
+`importlib.metadata.entry_points`, so no actual package install is needed.
+"""
+
+from __future__ import annotations
+
+import typer
+from typer.testing import CliRunner
+
+import mdl_cli.plugins as plugins
+
+runner = CliRunner()
+
+
+class _FakeEP:
+    """A stand-in importlib.metadata entry point: `.name` + `.load()` returning a callable."""
+
+    def __init__(self, name, loader):
+        self.name = name
+        self._loader = loader
+
+    def load(self):
+        return self._loader()
+
+
+class _FakeEPs:
+    """A stand-in for entry_points(): supports the modern `.select(group=...)` API."""
+
+    def __init__(self, by_group):
+        self._by_group = by_group
+
+    def select(self, group):
+        return self._by_group.get(group, [])
+
+
+def _patch_eps(monkeypatch, eps):
+    monkeypatch.setattr("importlib.metadata.entry_points", lambda: _FakeEPs({plugins.COMMAND_GROUP: eps}))
+    plugins._reset_for_tests()
+
+
+def test_plugin_command_is_registered_and_visible(monkeypatch):
+    app = typer.Typer()
+
+    @app.command()
+    def builtin():  # a built-in so the app isn't empty
+        pass
+
+    def register(a: typer.Typer) -> None:
+        plug = typer.Typer()
+
+        @plug.command()
+        def run():
+            """the enterprise CI gate"""
+            print("ci ran")
+
+        a.add_typer(plug, name="ci")
+
+    _patch_eps(monkeypatch, [_FakeEP("ci", lambda: register)])
+    applied = plugins.load_command_plugins(app)
+    assert applied == ["ci"]
+    # the plugin's command group now shows in --help and is runnable
+    assert "ci" in runner.invoke(app, ["--help"]).output
+    assert runner.invoke(app, ["ci", "run"]).exit_code == 0
+
+
+def test_a_broken_plugin_is_swallowed(monkeypatch):
+    app = typer.Typer()
+
+    @app.command()
+    def builtin():
+        pass
+
+    def boom(a):
+        raise RuntimeError("plugin exploded on register")
+
+    # one plugin that raises on register, one that works — the good one still lands,
+    # the bad one never bricks the CLI.
+    def ok(a: typer.Typer) -> None:
+        a.add_typer(typer.Typer(), name="good")
+
+    _patch_eps(
+        monkeypatch,
+        [_FakeEP("bad", lambda: boom), _FakeEP("good", lambda: ok)],
+    )
+    applied = plugins.load_command_plugins(app)
+    assert applied == ["good"]  # bad swallowed, good applied
+    # the CLI still works
+    assert runner.invoke(app, ["--help"]).exit_code == 0
+
+
+def test_a_plugin_that_fails_to_load_is_swallowed(monkeypatch):
+    app = typer.Typer()
+
+    @app.command()
+    def builtin():
+        pass
+
+    def bad_load():
+        raise ImportError("no such module")
+
+    _patch_eps(monkeypatch, [_FakeEP("bad", bad_load)])
+    assert plugins.load_command_plugins(app) == []
+    assert runner.invoke(app, ["--help"]).exit_code == 0
+
+
+def test_no_plugins_is_the_normal_case(monkeypatch):
+    app = typer.Typer()
+
+    @app.command()
+    def builtin():
+        pass
+
+    _patch_eps(monkeypatch, [])
+    assert plugins.load_command_plugins(app) == []
+
+
+def test_discovery_runs_once_per_process(monkeypatch):
+    app = typer.Typer()
+    calls = {"n": 0}
+
+    def register(a):
+        calls["n"] += 1
+
+    _patch_eps(monkeypatch, [_FakeEP("ci", lambda: register)])
+    plugins.load_command_plugins(app)
+    plugins.load_command_plugins(app)  # second call is a no-op (idempotent)
+    assert calls["n"] == 1
+
+
+def test_real_cli_does_not_crash_with_the_seam(monkeypatch):
+    """The real `mdl` app loads the seam in main(); with no plugins installed it is a no-op
+    and --help still works. Guards the wiring in main()."""
+    from mdl_cli.main import app as real_app
+
+    plugins._reset_for_tests()
+    result = runner.invoke(real_app, ["--help"])
+    assert result.exit_code == 0

{modelith_dbt-0.7.1 → modelith_dbt-0.7.2}/pyproject.toml

@@ -3,7 +3,7 @@
 # project, so the install name is `modelith-dbt` (install: uv tool install
 # modelith-dbt). The command stays `mdl`; the import modules stay mdl_*.
 name = "modelith-dbt"
-version = "0.7.1"
+version = "0.7.2"
 description = "Ontology-anchored, git-native data modeling tool for dbt-core teams"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -68,6 +68,15 @@ mdl = "mdl_cli.main:main"
 # example (in a separate enterprise package's pyproject, NOT here):
 #   mdl = "modelith_enterprise.registry:MdlResolver"
 
+# Plugin seam for new `mdl` subcommands: a package can add top-level commands (e.g. the
+# paid `mdl ci` drift gate) by exposing a `register(app)` callable here. The loader
+# (mdl_cli.plugins.load_command_plugins) runs it against the root Typer app at startup, so
+# the command appears in `mdl --help` with no change to the open CLI. Failures are
+# swallowed — a broken plugin never bricks the free CLI. Modelith ships none.
+[project.entry-points."modelith.commands"]
+# example (in a separate enterprise package's pyproject, NOT here):
+#   ci = "modelith_enterprise.ci:register"
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

{modelith_dbt-0.7.1 → modelith_dbt-0.7.2}/uv.lock

@@ -939,7 +939,7 @@ requires-dist = [
 
 [[package]]
 name = "modelith-dbt"
-version = "0.7.0"
+version = "0.7.2"
 source = { editable = "." }
 dependencies = [
     { name = "dbt-artifacts-parser" },