splent-cli 1.26.1__tar.gz → 1.27.0__tar.gz

{splent_cli-1.26.1/src/splent_cli.egg-info → splent_cli-1.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_cli
-Version: 1.26.1
+Version: 1.27.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
@@ -14,7 +14,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.15.1
+Requires-Dist: splent_framework<2,>=1.16.0
 Requires-Dist: tomli_w>=1.0.0
 Provides-Extra: dev
 Requires-Dist: setuptools==80.3.1; extra == "dev"

{splent_cli-1.26.1 → splent_cli-1.27.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_cli"
-version = "1.26.1"
+version = "1.27.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,7 +24,7 @@ dependencies = [
     "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.
-    "splent_framework>=1.15.1,<2",
+    "splent_framework>=1.16.0,<2",
     "tomli_w>=1.0.0",
 ]
 

splent_cli-1.27.0/src/splent_cli/__init__.py

@@ -0,0 +1,15 @@
+"""The SPLENT command-line interface."""
+
+import os as _os
+from types import MappingProxyType as _MappingProxyType
+
+# What the operator actually exported, taken before anything reads a .env.
+#
+# This must stay the first thing the package does. cli.py runs load_dotenv(),
+# and so do framework modules it imports (path_utils, configuration), which
+# puts every workspace .env key into os.environ before any command runs. Read
+# afterwards, the shell and the file look identical: env:show could never say
+# "not loaded", env:list never showed "·", and the workspace .env passed for
+# shell values and beat the product's docker/.env. Compare against this
+# instead of os.environ whenever the question is "what did the shell export".
+SHELL_ENV = _MappingProxyType(dict(_os.environ))

{splent_cli-1.26.1 → splent_cli-1.27.0}/src/splent_cli/cli.py

@@ -6,6 +6,8 @@ from dotenv import load_dotenv
 
 from splent_cli.utils.command_loader import load_commands
 
+# From here on os.environ holds the workspace .env as well. What the shell
+# itself exported is splent_cli.SHELL_ENV, taken before this line ran.
 load_dotenv()
 
 

splent_cli-1.27.0/src/splent_cli/commands/cache/cache_clear.py

@@ -0,0 +1,208 @@
+from splent_cli.services import context, compose
+import re
+import click
+from pathlib import Path
+
+from splent_cli.utils.cache_utils import rmtree_force
+from splent_cli.utils.feature_utils import normalize_namespace, parse_feature_entry
+
+# A namespace, feature name or version is a single path component: it can
+# never be empty, a path, "." or "..", so a scope always stays inside
+# .splent_cache/features.
+_NAME_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_.-]*$")
+_VERSION_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_.+-]*$")
+
+
+def _plain(value: str, pattern=_NAME_RE) -> bool:
+    return bool(pattern.match(value)) and ".." not in value
+
+
+def _validate_namespace(ctx, param, value):
+    if value is None:
+        return None
+    if not _plain(value):
+        raise click.BadParameter(
+            "must be a namespace name such as splent_io or splent-io,"
+            " not empty and not a path."
+        )
+    return normalize_namespace(value)
+
+
+def _validate_feature(ctx, param, value):
+    if value is None:
+        return None
+    base, at, version = value.partition("@")
+    explicit_ns, slash, name = base.rpartition("/")
+    if (
+        not _plain(name)
+        or (slash and not _plain(explicit_ns))
+        or (at and not _plain(version, _VERSION_RE))
+    ):
+        raise click.BadParameter(
+            "must be a feature name such as splent_feature_auth, optionally"
+            " with a namespace and a version (splent-io/splent_feature_auth@v1.2.0)."
+        )
+    ns, name, version = parse_feature_entry(value)
+    return {
+        "raw": value,
+        "namespace": ns if slash else None,
+        "name": name,
+        "version": version,
+    }
+
+
+def _matches(entry_name: str, name: str, version: str | None) -> bool:
+    if version:
+        return entry_name == f"{name}@{version}"
+    return entry_name.split("@", 1)[0] == name
+
+
+def _delete(target: Path, cache_root: Path) -> None:
+    """Delete one cache entry or namespace, refusing anything that is not a
+    real directory directly under ``cache_root`` or one of its namespaces.
+
+    Raises ``OSError`` when the target is refused or cannot be removed.
+    """
+    root = cache_root.resolve()
+    parent = target.parent.resolve()
+    if (
+        target.is_symlink()
+        or not target.is_dir()
+        or target.resolve().parent != parent
+        or (parent != root and parent.parent != root)
+    ):
+        raise OSError(
+            f"refusing to delete {target}, it is not a directory inside {cache_root}"
+        )
+    rmtree_force(target)
+
+
+@click.command(
+    "cache:clear",
+    short_help="Clear the feature version cache (.splent_cache), totally or partially.",
+)
+@click.option(
+    "--namespace",
+    default=None,
+    callback=_validate_namespace,
+    help="Clear only a specific namespace (e.g. splent_io or splent-io).",
+)
+@click.option(
+    "--feature",
+    default=None,
+    callback=_validate_feature,
+    help=(
+        "Clear the entries of one feature, given as a bare name (all versions,"
+        " editable included), name@version or namespace/name[@version]."
+    ),
+)
+@click.option("--yes", is_flag=True, help="Skip confirmation prompt.")
+def cache_clear(namespace, feature, yes):
+    """
+    Deletes entries from the feature cache and removes broken symlinks in products.
+
+    \b
+    Scope (most to least specific):
+      --feature splent_feature_auth          → every entry of that feature
+      --feature splent_feature_auth@v1.2.0   → only that version
+      --feature splent-io/splent_feature_auth → that feature in one namespace
+      --namespace splent_io                  → the entire namespace folder
+      (no options)                           → the entire feature cache
+    """
+    if feature is not None and feature["namespace"] is not None:
+        if namespace is not None and namespace != feature["namespace"]:
+            raise click.BadParameter(
+                f"names namespace '{feature['namespace']}' but --namespace"
+                f" is '{namespace}'.",
+                param_hint="'--feature'",
+            )
+        namespace = feature["namespace"]
+
+    workspace = context.workspace()
+    cache_root = workspace / ".splent_cache" / "features"
+
+    if not cache_root.is_dir():
+        click.secho("⚠️  No .splent_cache/features directory found.", fg="yellow")
+        raise SystemExit(0)
+
+    # Resolve targets
+    if feature is not None:
+        targets = []
+        if namespace is not None:
+            search_in = [cache_root / namespace]
+        else:
+            search_in = sorted(cache_root.iterdir())
+        for ns_dir in search_in:
+            if ns_dir.is_symlink() or not ns_dir.is_dir():
+                continue
+            for feat_dir in sorted(ns_dir.iterdir()):
+                if feat_dir.is_dir() and _matches(
+                    feat_dir.name, feature["name"], feature["version"]
+                ):
+                    targets.append(feat_dir)
+        if not targets:
+            label = f"'{feature['raw']}'" + (
+                f" in namespace '{namespace}'" if namespace is not None else ""
+            )
+            click.secho(f"⚠️  No cache entries found for {label}.", fg="yellow")
+            raise SystemExit(0)
+        description = f"{len(targets)} entry/entries for feature '{feature['raw']}'"
+    elif namespace is not None:
+        targets = [cache_root / namespace]
+        if not targets[0].is_dir():
+            click.secho(f"⚠️  Namespace '{namespace}' not found in cache.", fg="yellow")
+            raise SystemExit(0)
+        description = f"namespace '{namespace}'"
+    else:
+        targets = sorted(cache_root.iterdir())
+        description = "entire feature cache"
+
+    if not yes and not click.confirm(
+        f"⚠️  This will permanently delete the {description}. Continue?"
+    ):
+        click.echo("❎ Cancelled.")
+        raise SystemExit(0)
+
+    # Delete, one entry at a time so a failure never stops the cleanup.
+    failures = []
+    for t in targets:
+        try:
+            if (
+                feature is None
+                and namespace is None
+                and (t.is_symlink() or not t.is_dir())
+            ):
+                # Stray file or link directly in features/: unlink, never follow.
+                t.unlink()
+            else:
+                _delete(t, cache_root)
+        except OSError as exc:
+            failures.append(t)
+            click.secho(
+                f"  Could not delete {t.relative_to(cache_root)}: {exc}",
+                fg="red",
+                err=True,
+            )
+    cache_root.mkdir(parents=True, exist_ok=True)
+    if not failures:
+        click.secho(f"🧹 Cleared: {description}.", fg="green")
+
+    # Clean broken symlinks
+    removed = compose.remove_broken_symlinks(workspace)
+    if removed:
+        click.secho(f"🔗 Removed {removed} broken feature symlink(s).", fg="yellow")
+    else:
+        click.secho("✅ No broken symlinks found.", fg="green")
+
+    if failures:
+        click.secho(
+            f"{len(failures)} cache entry/entries could not be deleted. Check the"
+            " filesystem permissions (files written by a container may belong"
+            " to root) and remove them by hand.",
+            fg="red",
+            err=True,
+        )
+        raise SystemExit(1)
+
+
+cli_command = cache_clear

splent_cli-1.27.0/src/splent_cli/commands/cache/cache_orphans.py

@@ -0,0 +1,58 @@
+from splent_cli.services import context
+import click
+from pathlib import Path
+
+from splent_cli.utils.cache_utils import (
+    cache_entries,
+    cache_entry_key,
+    product_ref_keys,
+)
+from splent_cli.utils.feature_utils import workspace_feature_entries
+
+
+def _get_cache_entries(cache_root: Path) -> list:
+    """Returns list of {namespace, name, version, is_versioned, path} dicts."""
+    return cache_entries(cache_root)
+
+
+def _get_all_product_refs(workspace: Path) -> set:
+    """Every ``(namespace, name, version)`` any product declares, in any
+    environment list.
+
+    The namespace is normalised and a bare entry belongs to the default
+    namespace, so the keys compare directly with :func:`cache_entry_key`.
+    """
+    return product_ref_keys(workspace_feature_entries(workspace))
+
+
+@click.command(
+    "cache:orphans", short_help="Show cached features not referenced by any product."
+)
+def cache_orphans():
+    """Lists features in the cache that no product references in its pyproject.toml."""
+    workspace = context.workspace()
+    cache_root = workspace / ".splent_cache" / "features"
+
+    entries = _get_cache_entries(cache_root)
+    if not entries:
+        click.secho("ℹ️  Feature cache is empty.", fg="yellow")
+        return
+
+    refs = _get_all_product_refs(workspace)
+
+    orphans = []
+    for e in entries:
+        if cache_entry_key(e) not in refs:
+            ref_key = f"{e['name']}@{e['version']}" if e["is_versioned"] else e["name"]
+            orphans.append(f"{e['namespace']}/{ref_key}")
+
+    if not orphans:
+        click.secho("✅ No orphaned features in cache.", fg="green")
+        return
+
+    click.secho(f"🗑  Orphaned cache entries ({len(orphans)}):", fg="yellow")
+    for o in orphans:
+        click.echo(f"  - {o}")
+
+
+cli_command = cache_orphans

{splent_cli-1.26.1 → splent_cli-1.27.0}/src/splent_cli/commands/cache/cache_outdated.py

@@ -1,13 +1,19 @@
 from splent_cli.services import context
-import re
 import click
 from pathlib import Path
 from collections import defaultdict
-from packaging.version import Version, InvalidVersion
+from packaging.version import Version
+
+from splent_cli.commands.cache.cache_versions import parse_version, sort_versions
+from splent_cli.utils.feature_utils import (
+    normalize_namespace,
+    parse_feature_entry,
+    workspace_feature_entries,
+)
 
 
 def _get_cache_versions(cache_root: Path) -> dict:
-    """Returns {name: [version, ...]} with all versioned snapshots in cache."""
+    """Returns {(namespace, name): [version, ...]} with all versioned snapshots in cache."""
     versions = defaultdict(list)
     if not cache_root.exists():
         return versions
@@ -18,51 +24,36 @@ def _get_cache_versions(cache_root: Path) -> dict:
             if not feat_dir.is_dir() or "@" not in feat_dir.name:
                 continue
             name, version = feat_dir.name.split("@", 1)
-            versions[name].append(version)
+            versions[(normalize_namespace(ns_dir.name), name)].append(version)
     return versions
 
 
 def _latest(versions: list) -> str:
-    """Returns the latest version string, using semver if possible."""
+    """Returns the latest version string, using semver if possible.
+
+    Valid versions beat unparseable ones; ties are broken by the raw string,
+    so the result never depends on the order of ``versions``.
+    """
 
     def sort_key(v):
-        try:
-            return Version(v.lstrip("v"))
-        except InvalidVersion:
-            return Version("0")
+        parsed = parse_version(v)
+        return (parsed is not None, parsed or Version("0"), v)
 
     return max(versions, key=sort_key)
 
 
 def _get_product_features(workspace: Path) -> dict:
-    """Returns {product_name: {feature_name: version_or_None}}."""
+    """Returns {product_name: {(namespace, feature_name): version_or_None}}.
+
+    Every environment list counts (features, features_dev, features_prod).
+    """
     products = {}
-    for product_dir in sorted(workspace.iterdir()):
-        if not product_dir.is_dir() or product_dir.name.startswith("."):
-            continue
-        pyproject = product_dir / "pyproject.toml"
-        if not pyproject.exists():
-            continue
-        content = pyproject.read_text()
-        m = re.search(
-            r"\[project\.optional-dependencies\].*?features\s*=\s*\[(.*?)\]",
-            content,
-            re.DOTALL,
-        )
-        if not m:
-            continue
+    for product, entries in workspace_feature_entries(workspace).items():
         features = {}
-        for raw in re.findall(r'"([^"]+)"|\'([^\']+)\'', m.group(1)):
-            ref = raw[0] or raw[1]
-            if "/" in ref:
-                ref = ref.split("/", 1)[1]
-            if "@" in ref:
-                name, version = ref.split("@", 1)
-                features[name] = version
-            else:
-                features[ref] = None
-        if features:
-            products[product_dir.name] = features
+        for entry in entries:
+            ns, name, version = parse_feature_entry(entry)
+            features[(ns, name)] = version
+        products[product] = features
     return products
 
 
@@ -90,8 +81,9 @@ def cache_outdated():
 
     outdated = []
     for product, features in sorted(products.items()):
-        for name, current_ver in features.items():
-            available = cache_versions.get(name)
+        for (ns, feat), current_ver in features.items():
+            name = f"{ns}/{feat}"
+            available = cache_versions.get((ns, feat))
             if not available:
                 continue
             if current_ver is None:
@@ -101,9 +93,11 @@ def cache_outdated():
                 )
                 continue
             latest = _latest(available)
-            try:
-                is_old = Version(latest.lstrip("v")) > Version(current_ver.lstrip("v"))
-            except InvalidVersion:
+            latest_parsed = parse_version(latest)
+            current_parsed = parse_version(current_ver)
+            if latest_parsed is not None and current_parsed is not None:
+                is_old = latest_parsed > current_parsed
+            else:
                 is_old = latest != current_ver
             if is_old:
                 outdated.append((product, name, current_ver, latest, available))
@@ -118,7 +112,7 @@ def cache_outdated():
             f"  {click.style(product, bold=True)}  {name}  "
             f"{click.style(current, fg='red')} → {click.style(latest, fg='green')}"
         )
-        others = sorted(set(available) - {latest})
+        others = sort_versions(set(available) - {latest})
         if others:
             click.echo(f"    also cached: {', '.join(others)}")
     click.echo()

splent_cli-1.27.0/src/splent_cli/commands/cache/cache_prune.py

@@ -0,0 +1,148 @@
+from splent_cli.services import context, compose
+import click
+import os
+import tomllib
+from pathlib import Path
+
+from splent_cli.utils.cache_utils import (
+    cache_entries,
+    cache_entry_key,
+    product_ref_keys,
+    rmtree_force,
+)
+from splent_cli.utils.feature_utils import (
+    load_product_pyproject,
+    read_all_feature_entries,
+)
+
+
+def _get_cache_entries(cache_root: Path) -> list:
+    return cache_entries(cache_root)
+
+
+def _scan_product_entries(workspace: Path) -> tuple[dict, list]:
+    """Strict variant of ``workspace_feature_entries`` for a destructive command.
+
+    Returns ``({product: entries}, [(directory, error), ...])``. A non-hidden
+    directory holding a pyproject.toml that cannot be read or parsed is a
+    failure, not a product to skip: it may pin entries that would otherwise
+    look orphaned. Directories without a pyproject.toml are ignored.
+    """
+    products: dict[str, list[str]] = {}
+    failures: list[tuple[str, str]] = []
+    try:
+        children = sorted(os.scandir(workspace), key=lambda e: e.name)
+    except OSError as e:
+        return products, [(str(workspace), str(e))]
+    for child in children:
+        if not child.is_dir() or child.name.startswith("."):
+            continue
+        try:
+            data = load_product_pyproject(child.path)
+        except FileNotFoundError:
+            continue
+        except (OSError, tomllib.TOMLDecodeError) as e:
+            failures.append((child.name, str(e)))
+            continue
+        entries = read_all_feature_entries(data)
+        if entries:
+            products[child.name] = entries
+    return products, failures
+
+
+def _get_all_product_refs(workspace: Path) -> set:
+    """Every ``(namespace, name, version)`` any product declares.
+
+    Raises ``SystemExit(1)`` when a product's pyproject.toml cannot be read.
+    """
+    products, failures = _scan_product_entries(workspace)
+    if failures:
+        click.secho(
+            "cache:prune stopped because these pyproject.toml files could not be read.",
+            fg="red",
+            err=True,
+        )
+        for directory, error in failures:
+            click.secho(f"  - {directory}/pyproject.toml ({error})", fg="red", err=True)
+        click.secho(
+            "   Every entry they pin would look orphaned. Fix them and run"
+            " cache:prune again. Nothing was deleted.",
+            fg="red",
+            err=True,
+        )
+        raise SystemExit(1)
+    return product_ref_keys(products)
+
+
+@click.command(
+    "cache:prune", short_help="Remove orphaned cache entries not used by any product."
+)
+@click.option("--yes", is_flag=True, help="Skip confirmation prompt.")
+def cache_prune(yes):
+    """
+    Removes cache entries that no product references in its pyproject.toml,
+    then cleans up broken symlinks in products.
+
+    Stops without deleting anything when a product's pyproject.toml cannot
+    be parsed.
+    """
+    workspace = context.workspace()
+    cache_root = workspace / ".splent_cache" / "features"
+
+    entries = _get_cache_entries(cache_root)
+    if not entries:
+        click.secho("ℹ️  Feature cache is empty.", fg="yellow")
+        return
+
+    refs = _get_all_product_refs(workspace)
+
+    orphans = [e for e in entries if cache_entry_key(e) not in refs]
+
+    if not orphans:
+        click.secho("✅ Nothing to prune — no orphaned entries.", fg="green")
+        return
+
+    click.secho(f"Orphaned entries to remove ({len(orphans)}):", fg="yellow")
+    for e in orphans:
+        click.echo(f"  - {_label(e)}")
+
+    click.echo()
+    if not yes and not click.confirm("Remove all of the above?"):
+        click.echo("❎ Cancelled.")
+        raise SystemExit(0)
+
+    failures = []
+    for e in orphans:
+        try:
+            rmtree_force(e["path"])
+        except OSError as exc:
+            failures.append((e, exc))
+            click.secho(f"  Could not delete {_label(e)}: {exc}", fg="red", err=True)
+
+    pruned = len(orphans) - len(failures)
+    if pruned:
+        click.secho(f"🧹 Pruned {pruned} orphaned cache entry/entries.", fg="green")
+
+    removed = compose.remove_broken_symlinks(workspace)
+    if removed:
+        click.secho(f"🔗 Removed {removed} broken feature symlink(s).", fg="yellow")
+    else:
+        click.secho("✅ No broken symlinks found.", fg="green")
+
+    if failures:
+        click.secho(
+            f"{len(failures)} cache entry/entries could not be deleted. Check the"
+            " filesystem permissions (files written by a container may belong"
+            " to root) and remove them by hand.",
+            fg="red",
+            err=True,
+        )
+        raise SystemExit(1)
+
+
+def _label(e: dict) -> str:
+    version = f"@{e['version']}" if e["is_versioned"] else "  (editable)"
+    return f"{e['namespace']}/{e['name']}{version}"
+
+
+cli_command = cache_prune

{splent_cli-1.26.1 → splent_cli-1.27.0}/src/splent_cli/commands/cache/cache_status.py

@@ -1,4 +1,6 @@
 from splent_cli.services import context
+from splent_cli.commands.cache.cache_versions import sort_versions
+from splent_cli.utils.feature_utils import editable_feature_dirs
 import click
 from pathlib import Path
 from collections import defaultdict
@@ -27,24 +29,8 @@ def _get_cache_grouped(cache_root: Path) -> dict:
 def _get_workspace_root_features(workspace: Path) -> dict:
     """Returns {namespace/name: ['workspace']} for editable features at workspace root."""
     grouped = defaultdict(list)
-    for entry in sorted(workspace.iterdir()):
-        if not entry.is_dir() or not entry.name.startswith("splent_feature_"):
-            continue
-        # Must have pyproject.toml to be a real feature
-        if not (entry / "pyproject.toml").exists():
-            continue
-        src = entry / "src"
-        if not src.is_dir():
-            continue
-        for ns_dir in src.iterdir():
-            if (
-                ns_dir.is_dir()
-                and not ns_dir.name.startswith(("_", "."))
-                and "." not in ns_dir.name
-                and (ns_dir / entry.name).is_dir()
-            ):
-                grouped[f"{ns_dir.name}/{entry.name}"].append("workspace")
-                break
+    for ns, name, _path in editable_feature_dirs(workspace):
+        grouped[f"{ns}/{name}"].append("workspace")
     return grouped
 
 
@@ -73,7 +59,7 @@ def cache_status():
 
     for feature, versions in sorted(grouped.items()):
         click.secho(f"  {feature}", bold=True)
-        sorted_versions = sorted(versions, key=lambda x: (x is not None, x or ""))
+        sorted_versions = sort_versions(versions)
         for i, v in enumerate(sorted_versions):
             connector = "└──" if i == len(sorted_versions) - 1 else "├──"
             if v == "workspace":