splent-cli 1.18.0__tar.gz → 1.19.0__tar.gz

{splent_cli-1.18.0/src/splent_cli.egg-info → splent_cli-1.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_cli
-Version: 1.18.0
+Version: 1.19.0
 Summary: SPLENT-CLI is a CLI to be able to work on your development more easily.
 Author-email: DiversoLab <diversolab@us.es>
 Project-URL: Homepage, https://github.com/diverso-lab/splent_cli

{splent_cli-1.18.0 → splent_cli-1.19.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_cli"
-version = "1.18.0"
+version = "1.19.0"
 description = "SPLENT-CLI is a CLI to be able to work on your development more easily."
 readme = "README.md"
 requires-python = ">=3.13"

{splent_cli-1.18.0 → splent_cli-1.19.0}/src/splent_cli/commands/feature/feature_contract.py

@@ -13,6 +13,9 @@ Works with both editable features (no version) and versioned features (@v1.x.x).
 """
 
 import os
+import re
+import tomllib
+
 import click
 from pathlib import Path
 
@@ -337,6 +340,10 @@ def feature_contract(feature_ref, write):
 
     if not has_changes:
         click.secho("  ✅ Contract is already up to date.", fg="green")
+        # Reported here too: a settings gap has nothing to do with whether
+        # the contract changed, and an up to date contract is exactly when
+        # nobody would think to look.
+        _check_declared_config(cache_path, inferred)
         click.echo()
         return
 
@@ -347,6 +354,7 @@ def feature_contract(feature_ref, write):
             + click.style("--write", bold=True)
             + " to update pyproject.toml."
         )
+        _check_declared_config(cache_path, inferred)
         click.echo()
         return
 
@@ -357,7 +365,83 @@ def feature_contract(feature_ref, write):
     # Check if config.py needs updating
     _check_config_py(cache_path, ns, name, inferred)
 
+    # And whether the settings it reads are declared where a product looks
+    _check_declared_config(cache_path, inferred)
+
+    click.echo()
+
+
+# Variables whose value is a credential. A default for one of these does not
+# belong in a committed file, so they are expected to be absent from the
+# declaration and are not reported as missing.
+_SECRET = re.compile(r"(SECRET|PASSWORD|API_KEY|TOKEN|_KEY$)")
+
+# Set for every product by the framework and the compose files. A feature
+# that reads one is asking where it is running, not offering a setting, so
+# declaring a default for it would be claiming something it does not own.
+_FRAMEWORK_VARS = {
+    "FLASK_APP",
+    "PYTHONPATH",
+    "SPLENT_APP",
+    "SPLENT_ENV",
+    "SPLENT_HOST_PROJECT_DIR",
+    "SPLENT_NETWORK",
+    "WORKING_DIR",
+}
+
+
+def _check_declared_config(feature_path, inferred):
+    """Report settings the feature reads but declares nowhere.
+
+    A variable that appears only as an ``os.getenv`` fallback is invisible:
+    a product cannot discover the knob exists, and nothing tells a reader of
+    the pyproject what happens if it is left alone. ``[tool.splent.config]``
+    is where that is written down, whether or not the feature ships a
+    container.
+    """
+    env_vars = [
+        v
+        for v in inferred.get("env_vars", [])
+        if not _SECRET.search(v) and v not in _FRAMEWORK_VARS
+    ]
+    if not env_vars:
+        return
+
+    pyproject = feature_path / "pyproject.toml"
+    try:
+        with open(pyproject, "rb") as handle:
+            data = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError):
+        return
+
+    declared = set(data.get("tool", {}).get("splent", {}).get("config", {}))
+    # A feature that ships a service may state a default next to its compose
+    # file instead, which is equally visible to product:env --merge.
+    env_example = feature_path / "docker" / ".env.example"
+    if env_example.exists():
+        declared |= {
+            line.split("=", 1)[0].strip()
+            for line in env_example.read_text(
+                encoding="utf-8", errors="replace"
+            ).splitlines()
+            if "=" in line and not line.strip().startswith("#")
+        }
+
+    missing = sorted(set(env_vars) - declared)
+    if not missing:
+        return
+
     click.echo()
+    click.secho(
+        f"  ⚠  {len(missing)} setting(s) read but not declared in "
+        f"[tool.splent.config]: {', '.join(missing)}",
+        fg="yellow",
+    )
+    click.secho(
+        "     Add one line per variable, the value being its default, so a\n"
+        "     product can see the knob and override only what it decides.",
+        dim=True,
+    )
 
 
 def _check_config_py(feature_path, ns, name, inferred):

{splent_cli-1.18.0 → splent_cli-1.19.0}/src/splent_cli/commands/feature/feature_release.py

@@ -551,6 +551,49 @@ def infer_contract(
     }
 
 
+def _sections_not_owned_by_the_contract(tail: str) -> str:
+    """The TOML sections below the contract that the contract did not write.
+
+    ``[tool.splent.contract]`` and its subtables are regenerated from source
+    and go; anything else a maintainer put there stays, with the comments
+    written above it, since a comment above a table is about that table.
+    """
+    chunks: list[list[str]] = []
+    lead: list[str] = []
+    current: list[str] | None = None
+
+    for line in tail.splitlines():
+        if line.startswith("["):
+            if current is not None:
+                chunks.append(current)
+            current = [*lead, line]
+            lead = []
+        elif current is None:
+            # Before the first table: comments introducing whatever follows.
+            lead.append(line)
+        elif line.strip().startswith("#") or not line.strip():
+            # Might introduce the next table rather than close this one, so
+            # it is held until the next line says which.
+            lead.append(line)
+        else:
+            current.extend(lead)
+            lead = []
+            current.append(line)
+
+    if current is not None:
+        chunks.append(current)
+
+    kept = []
+    for chunk in chunks:
+        header = next((line for line in chunk if line.startswith("[")), "")
+        if header.startswith("[tool.splent.contract"):
+            continue
+        body = "\n".join(chunk).strip()
+        if body:
+            kept.append(body)
+    return "\n\n".join(kept)
+
+
 def write_contract(pyproject_path: str, contract: dict, feature_name: str) -> None:
     path = Path(pyproject_path)
     text = path.read_text()
@@ -596,20 +639,20 @@ def write_contract(pyproject_path: str, contract: dict, feature_name: str) -> No
         "requires_features_manual": sorted(set(manual_requires)),
     }
 
-    # Preserve any refinement section that comes after the contract
-    refinement_block = ""
-    ref_match = re.search(
-        r"((?:^# -- Refinement.*?\n)?^\[tool\.splent\.refinement\].*)",
-        text,
-        re.MULTILINE | re.DOTALL,
-    )
-    if ref_match:
-        refinement_block = "\n" + ref_match.group(1).rstrip() + "\n"
-
     match = re.search(r"^# ── Feature Contract\b.*$", text, re.MULTILINE)
     if not match:
         match = re.search(r"^\[tool\.splent\.contract\b", text, re.MULTILINE)
+
+    # Whatever a maintainer wrote below the contract is theirs, and the
+    # contract is refreshed by truncating from its header and writing a new
+    # block: everything after it went with it. That is how
+    # [tool.splent.config] vanished from five features the moment they were
+    # released, silently taking every declared default with them.
+    refinement_block = ""
     if match:
+        preserved = _sections_not_owned_by_the_contract(text[match.start() :])
+        if preserved:
+            refinement_block = "\n" + preserved + "\n"
         text = text[: match.start()]
     # Normalize trailing whitespace on both paths so a first write and a
     # rewrite produce byte-identical output.

{splent_cli-1.18.0 → splent_cli-1.19.0}/src/splent_cli/commands/feature/feature_upgrade.py

@@ -50,8 +50,13 @@ def _read_features(pyproject_path: Path) -> list[dict]:
     for ref in refs:
         if "/" in ref:
             ns_part, rest = ref.split("/", 1)
-            ns_github = ns_part
             ns_fs = normalize_namespace(ns_part)
+            # A pyproject writes the namespace the way a Python package
+            # needs it, splent_io, and GitHub serves it as splent-io. Taking
+            # it verbatim asked the API about an organisation that does not
+            # exist, and every feature was then reported as already up to
+            # date.
+            ns_github = ns_fs.replace("_", "-")
         else:
             ns_github = "splent-io"
             ns_fs = "splent_io"
@@ -178,9 +183,13 @@ def feature_upgrade(feature_ref, yes):
     click.secho("  Checking latest versions on GitHub...", fg="bright_black")
 
     upgrades = []
+    unchecked = []
     for feat in features:
         latest = _latest_remote_version(feat["ns_github"], feat["name"], token)
         if not latest:
+            # Not the same as being up to date, and saying so would be a
+            # lie about the one thing this command is for.
+            unchecked.append(feat["name"])
             continue
 
         current = feat["version"]
@@ -197,9 +206,27 @@ def feature_upgrade(feature_ref, yes):
         if is_newer:
             upgrades.append({**feat, "latest": latest})
 
+    if unchecked:
+        click.echo()
+        click.secho(
+            f"  ⚠  Could not check {len(unchecked)}: {', '.join(unchecked)}",
+            fg="yellow",
+        )
+        click.secho(
+            "     Whatever is declared for these was left alone. They may or\n"
+            "     may not have a newer version.",
+            dim=True,
+        )
+
     if not upgrades:
         click.echo()
-        click.secho("  ✅ All features are already at the latest version.", fg="green")
+        if unchecked and len(unchecked) == len(features):
+            click.secho("  Nothing could be checked.", fg="yellow")
+        else:
+            click.secho(
+                "  ✅ Every feature that could be checked is at its latest version.",
+                fg="green",
+            )
         click.echo()
         return
 

{splent_cli-1.18.0 → splent_cli-1.19.0}/src/splent_cli/commands/product/product_build.py

@@ -7,7 +7,11 @@ from splent_cli.services import context, compose
 from splent_cli.services.preflight import run_preflight
 from splent_cli.utils.feature_utils import read_features_from_data
 from splent_cli.utils.io_utils import load_toml
-from splent_cli.commands.product.product_env import _is_port_var
+from splent_cli.commands.product.product_env import (
+    _declared_config,
+    _feature_pyproject,
+    _is_port_var,
+)
 
 
 # ── User-tunable env vars ─────────────────────────────────────────────────────
@@ -415,19 +419,26 @@ def product_build(no_image, skip_preflight):
         seen_features.add(clean)
 
         f_docker = compose.feature_docker_dir(workspace, clean)
-        if not os.path.isdir(f_docker):
-            continue
+        if os.path.isdir(f_docker):
+            feature_env_file = (
+                os.path.join(f_docker, ".env.prod.example")
+                if os.path.isfile(os.path.join(f_docker, ".env.prod.example"))
+                else os.path.join(f_docker, ".env.example")
+            )
 
-        feature_env_file = (
-            os.path.join(f_docker, ".env.prod.example")
-            if os.path.isfile(os.path.join(f_docker, ".env.prod.example"))
-            else os.path.join(f_docker, ".env.example")
+            feature_env, feature_tunable = load_env_file_with_markers(feature_env_file)
+            feature_defaults = merge_env_dicts(feature_defaults, feature_env)
+            tunable_keys |= feature_tunable
+
+        # What the feature declares in its own pyproject, applied after its
+        # env example so the pyproject wins. Outside the isdir() guard on
+        # purpose: most features ship no docker/ at all, and those are the
+        # ones with nowhere else to state a default. Skipping them would put
+        # a deploy template together out of whatever config.py falls back to.
+        feature_defaults = merge_env_dicts(
+            feature_defaults, _declared_config(_feature_pyproject(workspace, clean))
         )
 
-        feature_env, feature_tunable = load_env_file_with_markers(feature_env_file)
-        feature_defaults = merge_env_dicts(feature_defaults, feature_env)
-        tunable_keys |= feature_tunable
-
     # Apply the product port offset to feature port variables. Only to those:
     # the offset exists so two products sharing a feature default do not fight
     # over the same host port, and a port the product wrote itself is already
@@ -442,7 +453,12 @@ def product_build(no_image, skip_preflight):
             except ValueError:
                 pass
 
-    env_result = merge_env_dicts(feature_defaults, product_env)
+    # And what the product decides about those features, which beats their
+    # defaults and loses to the product's own env file, exactly as in
+    # product:env --merge. The two paths have to agree: a deploy template
+    # that disagreed with dev would only be found in production.
+    env_result = merge_env_dicts(feature_defaults, _declared_config(pyproject_path))
+    env_result = merge_env_dicts(env_result, product_env)
 
     # Resolve __PRODUCT__ placeholder
     for k, v in env_result.items():

{splent_cli-1.18.0 → splent_cli-1.19.0}/src/splent_cli/commands/product/product_env.py

@@ -43,6 +43,46 @@ def _parse_env_line(line: str):
     return key, value
 
 
+def _declared_config(pyproject_path: str) -> dict:
+    """The ``[tool.splent.config]`` block of a pyproject, as strings.
+
+    A feature declares the variables it reads and what they default to; a
+    product declares the ones it decides differently. Both use the same
+    key, because they are the same kind of statement made by two different
+    owners, and the merge decides which wins.
+
+    Values are stringified because an env file has no types. A boolean
+    written as ``true`` in TOML reaches the environment as ``true``, which
+    is what every config.py in this workspace already parses.
+    """
+    try:
+        with open(pyproject_path, "rb") as handle:
+            data = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError):
+        return {}
+
+    declared = data.get("tool", {}).get("splent", {}).get("config", {})
+    if not isinstance(declared, dict):
+        return {}
+
+    out = {}
+    for key, value in declared.items():
+        if isinstance(value, bool):
+            out[key] = "true" if value else "false"
+        elif isinstance(value, (int, float, str)):
+            out[key] = str(value)
+        elif isinstance(value, list):
+            # A list is the natural way to write something the reader of
+            # the .env will see comma separated, like a set of locales.
+            out[key] = ",".join(str(item) for item in value)
+    return out
+
+
+def _feature_pyproject(workspace: str, clean_ref: str) -> str:
+    """Where a feature's own pyproject lives, editable or pinned."""
+    return os.path.join(compose.feature_dir(workspace, clean_ref), "pyproject.toml")
+
+
 def _is_port_var(key: str, value: str) -> bool:
     """Check if an env var looks like a port declaration.
 
@@ -231,6 +271,11 @@ def product_env(generate, merge, env_name, process_all):
                     k, v = parsed
                     merged[k] = v
 
+        # What the product's own env file states, captured before anything
+        # is merged into it. These keys are the product's last word: nothing
+        # declared in a pyproject, its own included, may quietly replace one.
+        stated_by_the_product = set(merged)
+
         # Always set SPLENT_ENV to match the current merge target
         merged["SPLENT_ENV"] = env_name
 
@@ -307,6 +352,59 @@ def product_env(generate, merge, env_name, process_all):
         # second product of the same line came up.
         merged["SPLENT_NETWORK"] = compose.network_name(product)
 
+        # ── What each side declares in its pyproject ─────────────────────
+        #
+        # A feature declares the variables it reads and their defaults; a
+        # product declares the ones it decides differently. Same key on both
+        # sides, because it is the same kind of statement made by two owners.
+        #
+        # This exists so a product's .env example can go back to being
+        # infrastructure. Feature settings used to be copied into it, which
+        # meant a product carried variables it had no opinion about, and a
+        # feature with no container had nowhere to declare a default at all,
+        # since .env.example lives under docker/.
+        #
+        # Precedence, weakest first:
+        #   feature docker/.env.example   (already merged above)
+        #   feature [tool.splent.config]
+        #   product [tool.splent.config]
+        #   product .env.<env>.example    (captured in stated_by_the_product)
+        #
+        # A feature that states a default in both places is saying the same
+        # thing twice; the pyproject wins because that is where a product's
+        # override sits, so the two can be read side by side.
+        declared_by_features = []
+        for feature in features:
+            clean_ref = compose.normalize_feature_ref(feature)
+            for key, value in _declared_config(
+                _feature_pyproject(workspace, clean_ref)
+            ).items():
+                if key in stated_by_the_product:
+                    continue
+                if _is_port_var(key, value):
+                    # Same offset the container defaults get: a port a
+                    # feature declares is still a port two products would
+                    # otherwise fight over.
+                    try:
+                        merged[key] = str(int(value) + port_offset)
+                        port_adjusted.append(
+                            (key, int(value), int(value) + port_offset)
+                        )
+                    except ValueError:
+                        merged[key] = value
+                else:
+                    merged[key] = value
+                declared_by_features.append(key)
+
+        product_declared = _declared_config(py_path)
+        for key, value in product_declared.items():
+            # Beats the feature's default, which is the point of writing it
+            # here, and loses to the product's own env file, which is the
+            # escape hatch for a setting an operator needs to force.
+            if key in stated_by_the_product:
+                continue
+            merged[key] = value
+
         # Replace __PRODUCT__ placeholder with the actual product name
         product_replaced = []
         for k, v in merged.items():
@@ -325,6 +423,17 @@ def product_env(generate, merge, env_name, process_all):
                 + f"resolved __PRODUCT__ in {len(product_replaced)} variable(s) → {product}"
             )
 
+        if declared_by_features:
+            click.echo(
+                click.style("  declared ", dim=True)
+                + f"{len(declared_by_features)} default(s) from feature pyprojects"
+            )
+        if product_declared:
+            click.echo(
+                click.style("  product  ", dim=True)
+                + f"{len(product_declared)} value(s) this product decides"
+            )
+
         if port_adjusted:
             click.echo(
                 click.style("  ports    ", dim=True)

{splent_cli-1.18.0 → splent_cli-1.19.0}/src/splent_cli/services/compose.py

@@ -437,24 +437,39 @@ def resolve_file(product_path: str, env: str) -> str | None:
     return None
 
 
-def feature_docker_dir(workspace: str, feature: str) -> str:
-    """Return the docker/ directory for a feature.
-
-    Accepts refs like 'splent_io/splent_feature_redis@v1.5.4' or bare 'splent_feature_redis'.
-    Checks workspace root first (editable features), then falls back
-    to the .splent_cache (pinned features).
+def feature_dir(workspace: str, feature: str) -> str:
+    """Return the root directory of a feature: where its pyproject lives.
+
+    Accepts refs like 'splent_io/splent_feature_redis@v1.5.4' or bare
+    'splent_feature_redis'. Checks the workspace root first (editable
+    features), then falls back to the .splent_cache (pinned features).
+
+    Resolution is by the feature's own directory rather than by any file
+    inside it, so a feature that ships no docker/ still resolves to its
+    editable copy. Keying on docker/ meant a feature with no container
+    silently resolved to a stale pinned copy in the cache, and read that
+    copy's settings instead of the ones being edited.
     """
     # Extract bare name (strip org prefix and version)
     name = feature.split("/")[-1] if "/" in feature else feature
     bare_name = name.split("@")[0]
 
     # Editable feature at workspace root
-    root_docker = os.path.join(workspace, bare_name, "docker")
-    if os.path.isdir(root_docker):
-        return root_docker
+    root = os.path.join(workspace, bare_name)
+    if os.path.isdir(root):
+        return root
 
     # Pinned feature in cache (needs full ref with org and version)
-    return os.path.join(workspace, ".splent_cache", "features", feature, "docker")
+    return os.path.join(workspace, ".splent_cache", "features", feature)
+
+
+def feature_docker_dir(workspace: str, feature: str) -> str:
+    """Return the docker/ directory for a feature.
+
+    The directory need not exist: only features that bring a container
+    have one, and callers check before reading.
+    """
+    return os.path.join(feature_dir(workspace, feature), "docker")
 
 
 def normalize_feature_ref(feat: str) -> str:

{splent_cli-1.18.0 → splent_cli-1.19.0/src/splent_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_cli
-Version: 1.18.0
+Version: 1.19.0
 Summary: SPLENT-CLI is a CLI to be able to work on your development more easily.
 Author-email: DiversoLab <diversolab@us.es>
 Project-URL: Homepage, https://github.com/diverso-lab/splent_cli