splent-cli 1.28.1__tar.gz → 1.28.2__tar.gz

{splent_cli-1.28.1/src/splent_cli.egg-info → splent_cli-1.28.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_cli
-Version: 1.28.1
+Version: 1.28.2
 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.28.1 → splent_cli-1.28.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_cli"
-version = "1.28.1"
+version = "1.28.2"
 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.28.1 → splent_cli-1.28.2}/src/splent_cli/commands/product/product_build.py

@@ -937,6 +937,37 @@ def _collect_feature_assets(workspace, declared_features, docker_path, env="prod
     return copied
 
 
+def unresolved_pins(
+    workspace: str, product: str, features: Sequence[str]
+) -> list[tuple[str, str]]:
+    """Pinned features this workspace has not resolved, each with the reason.
+
+    product:build reads every feature's env file and [tool.splent.config]
+    from the release the product pins, and copies the product's features/
+    links into the image. Both are product:resolve's work. Without it the
+    build used to carry on with whatever copy of the feature sat at the
+    workspace root, usually an old one: the .env.deploy.example lost every
+    setting the old copy did not declare, product:deploy then dropped them
+    from .env.deploy, and the image shipped links naming the old versions.
+    Editable features (no version) are not pinned and are not checked.
+    """
+    problems = []
+    for feat in features:
+        clean = compose.normalize_feature_ref(feat)
+        org_safe, _, name_ver = clean.partition("/")
+        if "@" not in name_ver:
+            continue
+        cached = os.path.join(
+            workspace, ".splent_cache", "features", org_safe, name_ver
+        )
+        linked = os.path.join(workspace, product, "features", org_safe, name_ver)
+        if not os.path.isdir(cached):
+            problems.append((name_ver, "not in .splent_cache"))
+        elif not os.path.isdir(linked):
+            problems.append((name_ver, f"not linked in {product}/features/"))
+    return problems
+
+
 @click.command(
     "product:build",
     short_help="Build deployment artifacts: env, compose, and Docker image.",
@@ -961,6 +992,27 @@ def product_build(no_image, skip_preflight):
 
     click.echo(f"🏗️  Building deployment artifacts for product: {product}\n")
 
+    # Read declared features from pyproject.toml (not glob)
+    pydata = load_toml(pyproject_path, what="pyproject.toml")
+    declared_features = read_features_from_data(pydata, "prod")
+
+    # ---------------------------------------------------------
+    # The releases the product pins, on disk
+    # ---------------------------------------------------------
+    unresolved = unresolved_pins(workspace, product, declared_features)
+    if unresolved:
+        click.secho(
+            "  The build reads the releases pyproject.toml pins, and these are "
+            "not resolved in this workspace.",
+            fg="red",
+        )
+        width = max(len(name) for name, _ in unresolved)
+        for name, why in unresolved:
+            click.echo(f"    {name.ljust(width)}  {why}")
+        click.echo()
+        click.echo("  Run splent product:resolve and build again.")
+        raise SystemExit(1)
+
     # ---------------------------------------------------------
     # Pre-flight checks (UVL + feature contracts)
     # ---------------------------------------------------------
@@ -987,10 +1039,6 @@ def product_build(no_image, skip_preflight):
     # unnamed courses with no categories in production.
     product_env, tunable_keys = load_env_file_with_markers(product_env_file)
 
-    # Read declared features from pyproject.toml (not glob)
-    pydata = load_toml(pyproject_path, what="pyproject.toml")
-    declared_features = read_features_from_data(pydata, "prod")
-
     # Unversioned features, and what actually happens to them.
     #
     # This warning used to say the build would fail. It does not, and that is

{splent_cli-1.28.1 → splent_cli-1.28.2}/src/splent_cli/commands/product/product_deploy.py

@@ -1,15 +1,17 @@
 import os
 import re
 import subprocess
+from dataclasses import dataclass, field
 
 import click
 
-from splent_cli.utils.io_utils import atomic_write
+from splent_cli.utils.io_utils import atomic_write, env_line
 import yaml
 from splent_cli.services import compose, context
 from splent_cli.commands.product.product_build import (
     OPTIONAL_DEPLOY_KEYS,
     host_docker_dir_env,
+    is_user_tunable_marker,
     load_env_file_with_markers,
     render_deploy_env,
 )
@@ -45,60 +47,205 @@ def suggest_value(key: str, product: str) -> str | None:
 ENV_DEPLOY_MODE = 0o600
 
 
+#: The template product:deploy merged into .env.deploy last time, kept next to
+#: it. Comparing against it is how a deploy tells a value the operator edited
+#: from one the template changed: without it, both look like "the file differs
+#: from the template". Ignored by git and by the image like every .env.*.
+ENV_DEPLOY_BASE_SUFFIX = ".base"
+
+#: Keys the CLI derives for the product and the operator has no reason to edit.
+#: Without a recorded base they still follow the template, so an upgrade that
+#: renames one (the database host, the network) reaches deployments made
+#: before the base existed.
+_DERIVED_KEYS = frozenset({"SPLENT_ENV", "SPLENT_NETWORK"})
+
+
+@dataclass
+class TemplateSync:
+    """What merging the template into an operator's env file did."""
+
+    env: dict
+    #: Keys the template changed and the operator had left alone.
+    updated: list = field(default_factory=list)
+    #: Keys the operator set that the template now sets differently.
+    kept: list = field(default_factory=list)
+    #: Keys the operator file had and the template no longer names.
+    dropped: list = field(default_factory=list)
+    #: User-tunable keys the operator deleted, which stay deleted.
+    deleted_tunables: set = field(default_factory=set)
+
+
+def derived_keys(product: str) -> frozenset:
+    """The keys the CLI writes into every product's production template.
+
+    Read from the CLI's own template rather than listed here, so a key the
+    template gains is covered too. Secrets (<SET>) and user-tunable keys are
+    the operator's and are left out.
+    """
+    from splent_cli.utils.template_drift import product_ctx, render_template
+
+    keys = set(_DERIVED_KEYS)
+    text = render_template("product/product_.env.prod.example.j2", product_ctx(product))
+    tunable_next = False
+    for line in text.splitlines():
+        stripped = line.strip()
+        if is_user_tunable_marker(stripped):
+            tunable_next = True
+            continue
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        key, _, value = stripped.partition("=")
+        if not tunable_next and value.strip() != "<SET>":
+            keys.add(key.strip())
+        tunable_next = False
+    return frozenset(keys)
+
+
+def base_path(env_path: str) -> str:
+    """Where the template behind ``env_path`` is recorded."""
+    return env_path + ENV_DEPLOY_BASE_SUFFIX
+
+
+def read_base(env_path: str) -> dict | None:
+    """The template last merged into ``env_path``, or None if never recorded."""
+    path = base_path(env_path)
+    if not os.path.isfile(path):
+        return None
+    values, _ = load_env_file_with_markers(path)
+    return values
+
+
+def write_base(env_path: str, template_vars: dict) -> None:
+    """Record the template just merged into ``env_path`` for the next merge."""
+    atomic_write(
+        base_path(env_path),
+        "".join(env_line(k, v) for k, v in template_vars.items()),
+        dir_owner=True,
+        mode=ENV_DEPLOY_MODE,
+        force_mode=True,
+    )
+
+
 def sync_with_template(
-    example_vars: dict, tunable_keys: set, existing_vars: dict
-) -> tuple[dict, list, set]:
+    example_vars: dict,
+    tunable_keys: set,
+    existing_vars: dict,
+    base_vars: dict | None = None,
+    derived: frozenset = frozenset(),
+) -> TemplateSync:
     """Bring an operator's env file up to date with its template.
 
-    The template is the source of truth for every infrastructure variable.
-    Two kinds of value belong to the operator instead and are never
-    overwritten:
-      * secrets and other keys the template ships as <SET>, once filled in;
-      * keys the template marks with a "# user-tunable" comment, such as the
-        interface a port binds to. A marked key the operator deleted stays
-        deleted, so removing it to fall back to the compose default works.
-
-    Returns ``(env_vars, updated_keys, deleted_tunables)``. product:deploy and
-    product:env --merge --prod both write .env.deploy through this, so one
-    cannot undo what the other kept.
+    A three-way merge. ``base_vars`` is the template as it was when the file
+    was last merged, so for every key that differs from the template now:
+
+      * the operator's value equals the old template: the operator never
+        touched it, the template moved, and the new template value is taken;
+      * otherwise the operator changed it and their value is kept.
+
+    Before this the template won every disagreement except secrets and
+    user-tunable keys, so a setting the operator turned on (publishing in the
+    marketplace, an API key the template ships empty) was silently undone on
+    every deploy.
+
+    With no recorded base (a file merged by an older CLI) nothing tells the
+    two apart, so the operator's value is kept and reported, except for the
+    ``derived`` keys the CLI computes for the product, which follow the
+    template as they always did.
+
+    Secrets the template ships as <SET> and user-tunable keys are the
+    operator's in every case, and a tunable the operator deleted stays
+    deleted. Keys the template no longer names are dropped and reported.
+
+    product:deploy and product:env --merge --prod both write .env.deploy
+    through this, so one cannot undo what the other kept.
     """
+    result = TemplateSync(env={})
     # Keys the operator removed on purpose. Only meaningful for tunables: a
-    # template-owned key that went missing is still restored below.
-    deleted_tunables = {
+    # template-owned key that went missing is restored below.
+    result.deleted_tunables = {
         k for k in tunable_keys if k in example_vars and k not in existing_vars
     }
 
-    env_vars = {}
-    updated = []
     for k, v in example_vars.items():
-        if k in deleted_tunables:
+        if k in result.deleted_tunables:
             # The operator deleted this tunable. Leave it out and let the
             # compose default apply.
             continue
-        elif k in tunable_keys and k in existing_vars:
-            # Operator-owned value — keep it exactly as they wrote it.
-            env_vars[k] = existing_vars[k]
-        elif (
-            v.strip() == "<SET>"
-            and k in existing_vars
-            and existing_vars[k].strip() != "<SET>"
-        ):
-            # User already configured this — keep their value
-            env_vars[k] = existing_vars[k]
-        elif k in existing_vars and existing_vars[k] != v:
-            # Infrastructure value changed in template — update it
-            env_vars[k] = v
-            updated.append(k)
+        if k not in existing_vars or existing_vars[k] == v:
+            result.env[k] = v
+            continue
+        mine = existing_vars[k]
+        if k in tunable_keys:
+            # Operator-owned value, kept exactly as they wrote it.
+            result.env[k] = mine
+        elif v.strip() == "<SET>":
+            # A secret, filled in unless the file still says <SET>.
+            result.env[k] = v if mine.strip() == "<SET>" else mine
+        elif base_vars is not None and k in base_vars:
+            if mine == base_vars[k]:
+                result.env[k] = v
+                result.updated.append(k)
+            else:
+                result.env[k] = mine
+                if base_vars[k] != v:
+                    result.kept.append(k)
+        elif k in derived:
+            result.env[k] = v
+            result.updated.append(k)
         else:
-            env_vars[k] = v
+            result.env[k] = mine
+            result.kept.append(k)
+
     # Optional operator settings (GUNICORN_WORKERS and the like) are not
     # live lines in any template, so the loop above never sees them. One the
     # operator set is theirs and stays, or uncommenting it in .env.deploy
     # would last until the next deploy.
     for k in sorted(OPTIONAL_DEPLOY_KEYS):
-        if k in existing_vars and k not in env_vars and k not in deleted_tunables:
-            env_vars[k] = existing_vars[k]
-    return env_vars, updated, deleted_tunables
+        if (
+            k in existing_vars
+            and k not in result.env
+            and k not in result.deleted_tunables
+        ):
+            result.env[k] = existing_vars[k]
+
+    result.dropped = [
+        k
+        for k in existing_vars
+        if k not in result.env and k not in result.deleted_tunables
+    ]
+    return result
+
+
+def report_sync(sync: TemplateSync, env_file: str) -> None:
+    """Say what merging the template changed, by key name only.
+
+    Values stay out of the output: half of them are passwords and keys.
+    """
+
+    def say(text: str) -> None:
+        click.echo(click.style("  env      ", dim=True) + text)
+
+    if sync.updated:
+        say(
+            f"updated {len(sync.updated)} variable(s) from the template: "
+            + ", ".join(sync.updated)
+        )
+    if sync.kept:
+        say(
+            f"kept your value for {len(sync.kept)} variable(s) the template sets "
+            f"differently: " + ", ".join(sync.kept)
+        )
+        say(f"  delete a line from {env_file} to take the template's value")
+    if sync.dropped:
+        say(
+            f"dropped {len(sync.dropped)} variable(s) the template no longer "
+            f"has: " + ", ".join(sync.dropped)
+        )
+    if sync.deleted_tunables:
+        say(
+            f"keeping {len(sync.deleted_tunables)} removed variable(s) out: "
+            + ", ".join(sorted(sync.deleted_tunables))
+        )
 
 
 # Env vars whose value is a directory the running app writes to. Their contents
@@ -266,22 +413,15 @@ def product_deploy(down, ci):
     # ---------------------------------------------------------
     existing_vars, _ = load_env_file_with_markers(env_path)
     example_vars, tunable_keys = load_env_file_with_markers(env_example_path)
-    env_vars, updated, deleted_tunables = sync_with_template(
-        example_vars, tunable_keys, existing_vars
+    sync = sync_with_template(
+        example_vars,
+        tunable_keys,
+        existing_vars,
+        base_vars=read_base(env_path),
+        derived=derived_keys(product),
     )
-
-    if updated:
-        click.echo(
-            click.style("  env      ", dim=True)
-            + f"updated {len(updated)} variable(s) from template"
-        )
-
-    if deleted_tunables:
-        click.echo(
-            click.style("  env      ", dim=True)
-            + f"keeping {len(deleted_tunables)} removed variable(s) out: "
-            + ", ".join(sorted(deleted_tunables))
-        )
+    env_vars = sync.env
+    report_sync(sync, "docker/.env.deploy")
 
     # ---------------------------------------------------------
     # Ask interactively for missing (<SET>) values
@@ -345,6 +485,7 @@ def product_deploy(down, ci):
         mode=ENV_DEPLOY_MODE,
         force_mode=True,
     )
+    write_base(env_path, example_vars)
 
     # ---------------------------------------------------------
     # Say when the app will not believe its proxy

{splent_cli-1.28.1 → splent_cli-1.28.2}/src/splent_cli/commands/product/product_derive.py

@@ -183,8 +183,9 @@ def product_derive(mode):
 
     \b
     --prod runs (after pre-flight):
-      1. product:build    merge env + compose + build Docker image
-      2. product:deploy   start production containers
+      1. product:resolve  clone the pinned releases and link them
+      2. product:build    merge env + compose + build Docker image
+      3. product:deploy   start production containers
 
     \b
     The pipeline stops at the first step that fails.
@@ -354,6 +355,13 @@ def product_derive(mode):
         step(product_port, env_flag="dev")
 
     elif mode == "prod":
+        # The build reads the pinned releases from the cache and refuses
+        # without them, so resolve them first, as the dev path does.
+        click.echo(
+            click.style("  sync     ", dim=True) + "resolving the pinned features..."
+        )
+        step(product_sync, force=False, mode="prod", strict=True)
+
         click.echo("  build    merging env + compose + Docker image")
         step(product_build, no_image=False, skip_preflight=True)
 

{splent_cli-1.28.1 → splent_cli-1.28.2}/src/splent_cli/commands/product/product_env.py

@@ -378,16 +378,29 @@ def product_env(generate, merge, env_name, process_all):
         if env_name == "prod":
             # .env.deploy is the operator's file: it holds the passwords and
             # the SECRET_KEY the running database was created with. The same
-            # rule product:deploy uses keeps every <SET> the operator filled
-            # in and every user-tunable value; the rest follows the template.
+            # three-way merge product:deploy uses keeps every value the
+            # operator set and takes every one the template changed.
             from splent_cli.commands.product.product_deploy import (
                 ENV_DEPLOY_MODE,
+                derived_keys,
+                read_base,
+                report_sync,
                 sync_with_template,
+                write_base,
             )
 
+            template = dict(merged)
             if os.path.isfile(target_env):
                 existing, _ = load_env_file_with_markers(target_env)
-                merged, _, _ = sync_with_template(merged, tunable_keys, existing)
+                sync = sync_with_template(
+                    template,
+                    tunable_keys,
+                    existing,
+                    base_vars=read_base(target_env),
+                    derived=derived_keys(product),
+                )
+                merged = sync.env
+                report_sync(sync, os.path.relpath(target_env, product_path))
                 backup_file(target_env, mode=ENV_DEPLOY_MODE)
             atomic_write(
                 target_env,
@@ -396,6 +409,7 @@ def product_env(generate, merge, env_name, process_all):
                 mode=ENV_DEPLOY_MODE,
                 force_mode=True,
             )
+            write_base(target_env, template)
         else:
             atomic_write(
                 target_env,

{splent_cli-1.28.1 → splent_cli-1.28.2/src/splent_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_cli
-Version: 1.28.1
+Version: 1.28.2
 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