splent-cli 1.38.0__tar.gz → 1.40.0__tar.gz

{splent_cli-1.38.0/src/splent_cli.egg-info → splent_cli-1.40.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_cli
-Version: 1.38.0
+Version: 1.40.0
 Summary: SPLENT-CLI is a CLI to be able to work on your development more easily.
 Author-email: DiversoLab <diversolab@us.es>
 License-Expression: LGPL-3.0-or-later
@@ -16,7 +16,7 @@ Requires-Dist: packaging>=24.0
 Requires-Dist: python-dotenv>=1.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: requests>=2.31.0
-Requires-Dist: splent_framework<2,>=1.18.0
+Requires-Dist: splent_framework<2,>=1.22.0
 Requires-Dist: tomli_w>=1.0.0
 Provides-Extra: dev
 Requires-Dist: setuptools==80.3.1; extra == "dev"

{splent_cli-1.38.0 → splent_cli-1.40.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_cli"
-version = "1.38.0"
+version = "1.40.0"
 description = "SPLENT-CLI is a CLI to be able to work on your development more easily."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -24,11 +24,14 @@ dependencies = [
     "pyyaml>=6.0",
     "requests>=2.31.0",
     # The CLI drives the framework (paths, feature order, migrations, the
-    # app factory) and only works with the same major version of it. 1.18.0
-    # resolves a feature to the copy feature:test names (SPLENT_FEATURE_SOURCES)
-    # and brings the production defaults the deploy templates explain; 1.17.0
-    # the refinement rules product:validate shares with the boot.
-    "splent_framework>=1.18.0,<2",
+    # app factory) and only works with the same major version of it. 1.22.0
+    # brings splent_framework.params, the [tool.splent.config_schema] reader
+    # product:validate, product:env and product:build share with the boot;
+    # 1.18.0 resolves a feature to the copy feature:test names
+    # (SPLENT_FEATURE_SOURCES) and brings the production defaults the deploy
+    # templates explain; 1.17.0 the refinement rules product:validate shares
+    # with the boot.
+    "splent_framework>=1.22.0,<2",
     "tomli_w>=1.0.0",
 ]
 

{splent_cli-1.38.0 → splent_cli-1.40.0}/src/splent_cli/commands/feature/feature_contract.py

@@ -456,6 +456,7 @@ def feature_contract(feature_ref, write):
         # nobody would think to look.
         _check_declared_config(cache_path, inferred)
         _report_config_keys(inferred)
+        _report_params(cache_path, name)
         click.echo()
         return
 
@@ -468,6 +469,7 @@ def feature_contract(feature_ref, write):
         )
         _check_declared_config(cache_path, inferred)
         _report_config_keys(inferred)
+        _report_params(cache_path, name)
         click.echo()
         return
 
@@ -485,6 +487,7 @@ def feature_contract(feature_ref, write):
     # And whether the settings it reads are declared where a product looks
     _check_declared_config(cache_path, inferred)
     _report_config_keys(inferred)
+    _report_params(cache_path, name)
 
     click.echo()
 
@@ -535,7 +538,8 @@ def _check_declared_config(feature_path, inferred):
     except (OSError, tomllib.TOMLDecodeError):
         return
 
-    declared = set(data.get("tool", {}).get("splent", {}).get("config", {}))
+    splent = data.get("tool", {}).get("splent", {})
+    declared = set(splent.get("config", {})) | set(splent.get("config_schema", {}))
     # 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"
@@ -593,6 +597,46 @@ def _report_config_keys(inferred):
     )
 
 
+def _report_params(feature_path, name):
+    """Say what [tool.splent.config_schema] declares, and what of it changed
+    since the latest release in a way that breaks a product: feature:release
+    refuses that change without a major bump (a minor one below 1.0.0)."""
+    from splent_framework.params.schema import read_pyproject
+
+    from splent_cli.utils.feature_params import release_compatibility
+
+    pyproject = feature_path / "pyproject.toml"
+    try:
+        with open(pyproject, "rb") as handle:
+            declared = read_pyproject(name, tomllib.load(handle))
+    except (OSError, tomllib.TOMLDecodeError):
+        return
+    if not declared.declared:
+        return
+    click.echo()
+    count = len(declared.params)
+    click.secho(
+        f"  ℹ  {count} parameter{'s' if count != 1 else ''} declared in "
+        "[tool.splent.config_schema]",
+        fg="cyan",
+    )
+    for error in declared.errors:
+        click.secho(f"  ❌ [tool.splent.config_schema] {error}", fg="red")
+    compat = release_compatibility(str(feature_path), name)
+    if compat.changes:
+        click.secho(
+            f"  ⚠  Since {compat.previous}, changes that break a product that "
+            "sets them:",
+            fg="yellow",
+        )
+        for change in compat.changes:
+            click.secho(f"     {change}", fg="yellow")
+        click.secho(
+            f"     The next release must be a {compat.required_bump()} version.",
+            dim=True,
+        )
+
+
 def _check_config_py(feature_path, ns, name, inferred):
     """Warn if config.py is missing or stale relative to the inferred contract."""
     from splent_cli.commands.feature.feature_inject_config import (

{splent_cli-1.38.0 → splent_cli-1.40.0}/src/splent_cli/commands/feature/feature_release.py

@@ -488,17 +488,33 @@ def _spelled_string(node, constants: dict[str, str]) -> str | None:
     return None
 
 
+def _is_param_call(node) -> bool:
+    """Whether ``node`` is ``param("feature", "KEY")``, the reader of the
+    parameters a feature declares (splent_framework.params)."""
+    if not isinstance(node, ast.Call) or len(node.args) < 2:
+        return False
+    func = node.func
+    name = func.id if isinstance(func, ast.Name) else getattr(func, "attr", None)
+    return name == "param"
+
+
 def _config_keys(tree) -> tuple[set[str], set[str]]:
     """``(read, written)``: the app.config keys a module reads and sets.
 
-    Read: ``.config.get("KEY")`` and ``.config["KEY"]``. Set:
-    ``.config["KEY"] = ...``, ``.config.setdefault("KEY", ...)`` and the
-    literal keys of ``.config.update(...)`` or ``.config.from_mapping(...)``.
+    Read: ``.config.get("KEY")``, ``.config["KEY"]`` and
+    ``param("feature", "KEY")``. Set: ``.config["KEY"] = ...``,
+    ``.config.setdefault("KEY", ...)`` and the literal keys of
+    ``.config.update(...)`` or ``.config.from_mapping(...)``.
     """
     constants = _module_string_constants(tree)
     read: set[str] = set()
     written: set[str] = set()
     for node in ast.walk(tree):
+        if _is_param_call(node):
+            key = _spelled_string(node.args[1], constants)
+            if key:
+                read.add(key)
+            continue
         if isinstance(node, ast.Subscript) and _is_app_config(node.value):
             key = _spelled_string(node.slice, constants)
             if key and isinstance(node.ctx, ast.Store):
@@ -737,7 +753,7 @@ def _config_keys_of(py_files) -> tuple[set[str], set[str]]:
         try:
             text = py_file.read_text()
             # Most modules never touch the config, and parsing is the cost.
-            if ".config" not in text:
+            if ".config" not in text and "param(" not in text:
                 continue
             tree = ast.parse(text)
         except (SyntaxError, OSError, UnicodeDecodeError):
@@ -768,12 +784,45 @@ def config_reads(
     variable holds, can only come from a product's config.py.
     """
     read, written = _config_keys_of(_feature_sources(src_dir))
+    read |= _template_param_reads(src_dir)
     own_short = src_dir.name.removeprefix("splent_feature_")
     taken = {key for key, shorts in (others or {}).items() if shorts - {own_short}}
     left = read - written - taken - _framework_config_keys()
     return {key for key in left if not _is_extension_key(key)}
 
 
+# {{ param('media', 'MEDIA_PUBLIC_GALLERY') }} in a template.
+_TEMPLATE_PARAM = re.compile(
+    r"""\bparam\(\s*['"][\w.]+['"]\s*,\s*['"]([A-Z][A-Z0-9_]+)['"]"""
+)
+
+
+def _template_param_reads(src_dir: Path) -> set[str]:
+    """The parameters the feature's templates read with param()."""
+    keys: set[str] = set()
+    for path in sorted(src_dir.rglob("*.html")):
+        if "tests" in path.relative_to(src_dir).parts[:-1]:
+            continue
+        try:
+            text = path.read_text(errors="replace")
+        except OSError:
+            continue
+        if "param(" in text:
+            keys.update(_TEMPLATE_PARAM.findall(text))
+    return keys
+
+
+def declared_param_keys(feature_root: Path) -> set[str]:
+    """The keys the feature declares in [tool.splent.config_schema]. The
+    framework sets them on its behalf, so it reads them as its own."""
+    try:
+        data = tomllib.loads((Path(feature_root) / "pyproject.toml").read_text())
+    except (OSError, UnicodeDecodeError, tomllib.TOMLDecodeError):
+        return set()
+    schema = data.get("tool", {}).get("splent", {}).get("config_schema", {})
+    return set(schema) if isinstance(schema, dict) else set()
+
+
 def default_config_map() -> dict[str, frozenset[str]]:
     """:func:`build_config_map` over the workspace in reach, built once per
     process, or empty without one."""
@@ -788,7 +837,10 @@ def build_config_map(workspace: str) -> dict[str, frozenset[str]]:
     of every feature in reach took half a second, once per contract.
     """
     owners: dict[str, set[str]] = {}
-    for short, package, _, _ in _feature_dirs_in_reach(workspace):
+    for short, package, feature_dir, _ in _feature_dirs_in_reach(workspace):
+        # A parameter the feature declares is set by the framework for it.
+        for key in declared_param_keys(feature_dir):
+            owners.setdefault(key, set()).add(short)
         if package is None:
             continue
         files = (package / "config.py", package / "__init__.py")
@@ -1383,7 +1435,11 @@ def infer_contract(
     # is not one a product must put in its .env.
     if config_map is None:
         config_map = default_config_map()
-    config_keys = sorted(config_reads(src_dir, config_map) - set(env_vars))
+    config_keys = sorted(
+        config_reads(src_dir, config_map)
+        - set(env_vars)
+        - declared_param_keys(feature_root)
+    )
     signals_provided, signals_required = _extract_signals(src_dir / "signals.py")
     translations = _extract_translations(src_dir / "translations")
 
@@ -2111,6 +2167,10 @@ def feature_release(
     normalized = version.lstrip("v")
     tag = f"v{normalized}"
 
+    # A parameter change that breaks a product needs the version to say so,
+    # before anything is bumped, committed or tagged.
+    _refuse_breaking_params(feature_path, feature_name, tag)
+
     # Why the forge is off decides the advice: with --no-forge, release:resume
     # pushes the tag later; a package that does not publish to the forge
     # never gets its tag there, release:resume included.
@@ -2225,6 +2285,38 @@ def feature_release(
         ctx.invoke(feature_attach, feature_identifier=feature_ref, version=tag)
 
 
+def _refuse_breaking_params(feature_path, feature_name, tag) -> None:
+    """Stop the release when the parameters the feature declares changed in
+    a way that breaks a product (a key removed, a type changed, choices or a
+    range narrowed, a key made required) and ``tag`` does not bump the
+    version that says so: the major, or the minor below 1.0.0.
+
+    Compared with the pyproject.toml of the latest release tag in the
+    feature's repository. A feature never released, or without a schema
+    then and now, has nothing to compare.
+    """
+    from splent_cli.utils.feature_params import release_compatibility
+
+    compat = release_compatibility(feature_path, feature_name)
+    if compat.allows(tag):
+        return
+    click.secho(
+        f"  error: since {compat.previous} the parameters of {feature_name} "
+        "changed in a way that breaks a product that sets them:",
+        fg="red",
+    )
+    for change in compat.changes:
+        click.secho(f"     {change}", fg="red")
+    click.echo(
+        f"     {tag} keeps the {compat.required_bump()} version of "
+        f"{compat.previous}. Release it with --bump {compat.required_bump()}"
+        + (" (or major)" if compat.required_bump() == "minor" else "")
+        + ", or keep the old declaration compatible."
+    )
+    click.echo("  Nothing was changed. No version bump, no commit, no tag, no release.")
+    raise SystemExit(1)
+
+
 def _refuse_invalid_requirements(feature_path, namespace, feature_name) -> None:
     """Stop the release, before it changes anything, when the contract it
     would write has a requirement that does not parse (``auth>=soon``).

{splent_cli-1.38.0 → splent_cli-1.40.0}/src/splent_cli/commands/product/product_build.py

@@ -1132,7 +1132,15 @@ def _contracts_snapshot(workspace: str, declared_features: Sequence[str]) -> dic
     A feature that declares neither is still listed, so the framework knows
     it was looked at. One whose pyproject cannot be found is left out with a
     warning, and the framework then reports it as missing.
+
+    A feature's [tool.splent.config_schema] goes in too, as
+    ``config_schema``: the image resolves and checks its parameters from it.
+    Each default is filled in from [tool.splent.config], except a secret's,
+    which never goes to a file baked into the image. A schema that cannot be
+    used is left for the pre-flight to report; only its usable keys go in.
     """
+    from splent_framework.params.schema import read_pyproject
+
     features: dict[str, dict] = {}
     missing: list[str] = []
     for feat in declared_features:
@@ -1144,7 +1152,8 @@ def _contracts_snapshot(workspace: str, declared_features: Sequence[str]) -> dic
         if not os.path.isfile(pyproject):
             missing.append(name)
             continue
-        splent = load_toml(pyproject).get("tool", {}).get("splent", {})
+        data = load_toml(pyproject)
+        splent = data.get("tool", {}).get("splent", {})
         item: dict = {"entry": clean}
         if isinstance(splent, dict):
             if "refinement" in splent:
@@ -1152,6 +1161,11 @@ def _contracts_snapshot(workspace: str, declared_features: Sequence[str]) -> dic
             contract = splent.get("contract")
             if isinstance(contract, dict) and "extensible" in contract:
                 item["extensible"] = contract["extensible"]
+            declared = read_pyproject(name, data)
+            if declared.declared:
+                item["config_schema"] = {
+                    key: param.as_dict() for key, param in declared.params.items()
+                }
         features[name] = item
     if missing:
         click.secho(
@@ -1501,7 +1515,15 @@ def write_deploy_artifacts(
     # 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))
+    from splent_cli.utils.feature_params import product_params
+
+    env_result = merge_env_dicts(
+        feature_defaults,
+        _declared_config(
+            pyproject_path,
+            product_params(workspace, load_toml(pyproject_path), "prod"),
+        ),
+    )
     env_result = merge_env_dicts(env_result, product_env)
 
     # Resolve the product placeholders. A feature that talks to the product's

{splent_cli-1.38.0 → splent_cli-1.40.0}/src/splent_cli/commands/product/product_config.py

@@ -50,14 +50,16 @@ def _short_value(value, max_len: int = 50) -> str:
     return _truncate(repr(value), max_len)
 
 
-def _redacted(key: str, value) -> tuple[str, bool]:
+def _redacted(key: str, value, secrets=()) -> tuple[str, bool]:
     """repr(*value*) as it may be printed, and whether anything was hidden.
 
-    A secret-looking key's string is masked, and the password of any URI is
-    dropped, also inside a dict or a list such as SQLALCHEMY_BINDS.
+    A secret-looking key's string is masked, and so is one a feature's
+    [tool.splent.config_schema] marks as a secret (``secrets``), and the
+    password of any URI is dropped, also inside a dict or a list such as
+    SQLALCHEMY_BINDS.
     """
     masked = False
-    if is_secret_key(key) and isinstance(value, (str, bytes)) and value:
+    if is_secret_key(key, secrets) and isinstance(value, (str, bytes)) and value:
         value = mask_value(value) if isinstance(value, str) else MASK.encode()
         masked = True
     text = repr(value)
@@ -68,10 +70,13 @@ def _redacted(key: str, value) -> tuple[str, bool]:
 def _source_label(info: dict) -> str:
     """Human-readable label for who set this key."""
     source = info.get("source", "unknown")
-    # Prettify feature import names: "splent_io.splent_feature_redis" -> "feature (splent_feature_redis)"
-    if "." in source:
-        parts = source.rsplit(".", 1)
-        return f"feature ({parts[1]})"
+    # Prettify feature import names: "splent_io.splent_feature_redis" -> "feature (splent_feature_redis)",
+    # and a feature's default parameter: "... (default)" -> "feature (...) default".
+    # Only an import name: "product pyproject ([tool.splent.config])" has dots too.
+    name, default, _ = source.partition(" (default)")
+    if "." in name and " " not in name:
+        label = f"feature ({name.rsplit('.', 1)[1]})"
+        return f"{label} default" if default else label
     return source
 
 
@@ -120,11 +125,13 @@ def product_config(show_all, filter_feature, filter_key, show_secrets):
     """
     masked_any = False
 
+    secrets: set = set()
+
     def shown(key, value, max_len=50):
         nonlocal masked_any
         if show_secrets:
             return _short_value(value, max_len)
-        text, changed = _redacted(key, value)
+        text, changed = _redacted(key, value, secrets)
         masked_any = masked_any or changed
         return _truncate(text, max_len)
 
@@ -140,6 +147,9 @@ def product_config(show_all, filter_feature, filter_key, show_secrets):
         raise click.ClickException(f"could not boot app: {exc}")
 
     trace: dict = app.extensions.get("splent_config_trace", {})
+    # The keys the features' schemas mark as secrets, masked like the ones
+    # whose name says so.
+    secrets |= {key for key, info in trace.items() if info.get("secret")}
 
     # Separate overwritten keys
     overwrites = {k: v for k, v in trace.items() if v.get("action") == "overwritten"}
@@ -214,6 +224,24 @@ def product_config(show_all, filter_feature, filter_key, show_secrets):
                 f"     {key}: {prev_val} ({prev_src}) \u2192 {new_val} ({new_src})"
             )
 
+    # Drift: the environment replaced what the product decided (for a
+    # declared parameter, one bound at derivation). Accepted, and said.
+    drifted = {k: v for k, v in trace.items() if v.get("drift")}
+    if drifted:
+        click.echo()
+        click.secho(
+            "  \u26a0  Drift, the environment overrides what the product decided:",
+            fg="yellow",
+            bold=True,
+        )
+        for key, info in sorted(drifted.items()):
+            before = shown(key, info.get("overruled_value"), 30)
+            after = shown(key, info.get("value"), 30)
+            click.echo(
+                f"     {key}: {before} ({info.get('overruled_source', '?')}) "
+                f"\u2192 {after} (operator environment)"
+            )
+
     if masked_any:
         click.echo()
         click.secho(

{splent_cli-1.38.0 → splent_cli-1.40.0}/src/splent_cli/commands/product/product_env.py

@@ -31,17 +31,35 @@ def _scalar(value) -> str | None:
     return None
 
 
-def _env_value(pyproject_path: str, key: str, value) -> str:
+def _env_value(pyproject_path: str, key: str, value, param=None) -> str:
     """One declared value as the string the environment will carry.
 
     Raises ClickException for what an environment variable cannot hold
     without losing it: a table, a list of tables or of lists, and a list
     item with a comma in it, which the reader would split in two.
+
+    A key some feature declares in [tool.splent.config_schema] (``param``)
+    is written the way the framework reads it back at boot: a list item
+    with a comma, or a map, as JSON (splent_framework.params.schema
+    .env_text). A value the schema refuses raises ClickException too, so
+    the environment never carries what the app would refuse to start with.
     """
+    where = f"{key} in [tool.splent.config] of {pyproject_path}"
+    if param is not None:
+        from splent_framework.params.schema import PLACEHOLDER, ParamError, env_text
+
+        if value == PLACEHOLDER:
+            return value
+        try:
+            return env_text(param, value)
+        except ParamError as e:
+            raise click.ClickException(
+                f"{where}: {e} ({param.short} declares it in "
+                "[tool.splent.config_schema])"
+            ) from None
     text = _scalar(value)
     if text is not None:
         return text
-    where = f"{key} in [tool.splent.config] of {pyproject_path}"
     if isinstance(value, list):
         items = [_scalar(item) for item in value]
         if any(item is None for item in items):
@@ -68,7 +86,7 @@ def _env_value(pyproject_path: str, key: str, value) -> str:
     )
 
 
-def _declared_config(pyproject_path: str) -> dict:
+def _declared_config(pyproject_path: str, params: dict | None = None) -> dict:
     """The ``[tool.splent.config]`` block of a pyproject, as strings.
 
     A feature declares the variables it reads and what they default to; a
@@ -83,6 +101,11 @@ def _declared_config(pyproject_path: str) -> dict:
     can carry (a table, a list of tables) raises ClickException naming the
     key and the file: it used to be dropped without a word, and the feature
     then ran on its default while the pyproject said otherwise.
+
+    ``params`` are the declared parameters the values are written for, by
+    key (feature_params.product_params for a product's pyproject). Left
+    out, they are the file's own [tool.splent.config_schema], which is the
+    case of a feature's pyproject. A list or a map is then carried, typed.
     """
     try:
         with open(pyproject_path, "rb") as handle:
@@ -94,8 +117,15 @@ def _declared_config(pyproject_path: str) -> dict:
     if not isinstance(declared, dict):
         return {}
 
+    if params is None:
+        from splent_framework.params.schema import read_pyproject
+
+        feature = os.path.basename(os.path.dirname(pyproject_path)).split("@")[0]
+        params = read_pyproject(feature, data).params
+
     return {
-        key: _env_value(pyproject_path, key, value) for key, value in declared.items()
+        key: _env_value(pyproject_path, key, value, params.get(key))
+        for key, value in declared.items()
     }
 
 
@@ -398,7 +428,11 @@ def product_env(generate, merge, env_name, process_all):
             k for k in defaults.declared if k not in stated_by_the_product
         ]
 
-        product_declared = _declared_config(py_path)
+        from splent_cli.utils.feature_params import product_params
+
+        product_declared = _declared_config(
+            py_path, product_params(workspace, data, env_name)
+        )
         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