splent-cli 1.29.0__tar.gz → 1.29.1__tar.gz

{splent_cli-1.29.0/src/splent_cli.egg-info → splent_cli-1.29.1}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_cli"
-version = "1.29.0"
+version = "1.29.1"
 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.29.0 → splent_cli-1.29.1}/src/splent_cli/commands/feature/feature_release.py

@@ -3,6 +3,7 @@ feature:release — Release a feature: bump version, tag, publish to the git for
 """
 
 import ast
+import json
 import os
 import re
 import shutil
@@ -363,6 +364,83 @@ def _extract_commands(commands_path: Path) -> list[str]:
     return sorted(set(re.findall(r"""@click\.command\s*\(\s*['"]([^'"]+)['"]""", text)))
 
 
+def _call_name(node) -> str:
+    """``click.command`` for the decorator call ``@click.command(...)``."""
+    func = node.func if isinstance(node, ast.Call) else node
+    parts = []
+    while isinstance(func, ast.Attribute):
+        parts.append(func.attr)
+        func = func.value
+    if isinstance(func, ast.Name):
+        parts.append(func.id)
+    return ".".join(reversed(parts))
+
+
+def _literal(node):
+    try:
+        return ast.literal_eval(node)
+    except (ValueError, SyntaxError, TypeError):
+        return None
+
+
+def _first_line(text) -> str:
+    for line in (text or "").strip().splitlines():
+        if line.strip():
+            return line.strip()
+    return ""
+
+
+def _extract_command_help(commands_path: Path) -> dict:
+    """What each command a feature adds is for, and how it is called.
+
+    ``{name: {"usage": "EMAIL ROLE [OPTIONS]", "help": "..."}}``, read from
+    the source without importing it: the arguments in the order they are
+    declared, in click's uppercase, ``[OPTIONS]`` when there are any, and the
+    first line of ``short_help``, ``help`` or the docstring. The marketplace
+    shows it next to each command, which used to be a bare name.
+    """
+    if not commands_path.exists():
+        return {}
+    try:
+        tree = ast.parse(commands_path.read_text())
+    except SyntaxError:
+        return {}
+    found = {}
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        name, help_text, usage, has_options = None, "", [], False
+        for deco in node.decorator_list:
+            if not isinstance(deco, ast.Call):
+                continue
+            kind = _call_name(deco)
+            if kind.endswith("command") and deco.args:
+                name = _literal(deco.args[0])
+                kwargs = {k.arg: _literal(k.value) for k in deco.keywords}
+                help_text = kwargs.get("short_help") or kwargs.get("help") or ""
+            elif kind.endswith("argument") and deco.args:
+                arg = _literal(deco.args[0])
+                if not isinstance(arg, str):
+                    continue
+                kwargs = {k.arg: _literal(k.value) for k in deco.keywords}
+                metavar = arg.upper().replace("-", "_")
+                if kwargs.get("nargs") == -1:
+                    metavar += "..."
+                optional = kwargs.get("required") is False or "default" in kwargs
+                usage.append(f"[{metavar}]" if optional else metavar)
+            elif kind.endswith("option"):
+                has_options = True
+        if not isinstance(name, str):
+            continue
+        if has_options:
+            usage.append("[OPTIONS]")
+        found[name] = {
+            "usage": " ".join(usage),
+            "help": _first_line(help_text) or _first_line(ast.get_docstring(node)),
+        }
+    return dict(sorted(found.items()))
+
+
 def _feature_sources(src_dir: Path):
     """The feature's own Python files, without its tests.
 
@@ -693,6 +771,7 @@ def infer_contract(
     templates = _extract_templates(src_dir)
     template_hook_slots = _extract_template_hook_slots(src_dir)
     commands = _extract_commands(src_dir / "commands.py")
+    commands_help = _extract_command_help(src_dir / "commands.py")
     docker = _extract_docker(feature_root)
     docker_contract = _extract_docker_contract(feature_root)
     req_features, env_vars = _scan_dependencies(src_dir, feature_name)
@@ -751,6 +830,7 @@ def infer_contract(
         "blueprints": blueprints,
         "models": models,
         "commands": commands,
+        "commands_help": commands_help,
         "hooks": hooks,
         "services": services,
         "signals": signals_provided,
@@ -945,7 +1025,8 @@ def write_contract(pyproject_path: str, contract: dict, feature_name: str) -> No
         f"signals    = {_toml_value(contract.get('signals', []))}\n"
         f"translations = {_toml_value(contract.get('translations', []))}\n"
         f"docker     = {_toml_value(contract['docker'])}\n"
-        "\n"
+        + _commands_help_block(contract.get("commands_help") or {})
+        + "\n"
         "[tool.splent.contract.requires]\n"
         f"features = {_toml_value(contract['requires_features'])}\n"
         + (
@@ -989,6 +1070,20 @@ def write_contract(pyproject_path: str, contract: dict, feature_name: str) -> No
     path.write_text(text + contract_block + refinement_block)
 
 
+def _commands_help_block(commands_help: dict) -> str:
+    """The ``[tool.splent.contract.provides.commands_help]`` table, or nothing."""
+    if not commands_help:
+        return ""
+    lines = ["\n[tool.splent.contract.provides.commands_help]\n"]
+    for name, entry in commands_help.items():
+        key = name if re.fullmatch(r"[A-Za-z0-9_-]+", name) else json.dumps(name)
+        lines.append(
+            f"{key} = {{ usage = {json.dumps(entry.get('usage', ''))}, "
+            f"help = {json.dumps(entry.get('help', ''))} }}\n"
+        )
+    return "".join(lines)
+
+
 # ── Compile assets ────────────────────────────────────────────────────
 
 

{splent_cli-1.29.0 → splent_cli-1.29.1}/src/splent_cli/commands/product/product_release.py

@@ -2,8 +2,11 @@
 product:release, a product release: version bump, tag, forge, PyPI and the image.
 """
 
+import contextlib
+import json
 import os
 import subprocess
+import tempfile
 
 import click
 from splent_cli.commands.product.product_build import (
@@ -63,7 +66,32 @@ def release_targets(product: str, version: str, product_path: str, org: str):
     return image_registry.image_targets(product, version, org, registries, mirrors)
 
 
-def _login(target) -> bool:
+#: Docker Hub answers to these names in a client's configuration.
+_DOCKER_HUB_HOSTS = ("index.docker.io", "registry-1.docker.io", "docker.io")
+
+
+@contextlib.contextmanager
+def registry_session(hosts=()):
+    """A docker client configuration of its own for one release's logins and pushes.
+
+    The host's configuration may hand credentials to a helper, the macOS
+    keychain under Docker Desktop, and that helper refuses to store a login
+    for a host the keychain already holds a git password for ("The specified
+    item already exists in the keychain"), which stopped the marketplace's
+    first release. A configuration of its own also keeps the release tokens
+    off the machine: it is deleted when the release is done.
+    """
+    # An empty credsStore is not enough: the docker client then detects the
+    # platform's helper again. An empty helper per host is what makes it keep
+    # the login in this file.
+    helpers = {host: "" for host in (*hosts, *_DOCKER_HUB_HOSTS) if host}
+    with tempfile.TemporaryDirectory(prefix="splent-docker-") as config_dir:
+        with open(os.path.join(config_dir, "config.json"), "w") as handle:
+            json.dump({"auths": {}, "credHelpers": helpers}, handle)
+        yield {**os.environ, "DOCKER_CONFIG": config_dir}
+
+
+def _login(target, env=None) -> bool:
     user, secret = target.credentials()
     if not user or not secret:
         return False
@@ -71,7 +99,7 @@ def _login(target) -> bool:
     if target.host:
         command.insert(2, target.host)
     try:
-        run(command, input=secret, capture=True)
+        run(command, input=secret, capture=True, env=env)
     except subprocess.CalledProcessError:
         return False
     return True
@@ -105,51 +133,52 @@ def release_docker_image(product: str, version: str, docker_dir: str, targets):
         )
         raise SystemExit(1)
 
-    usable = []
-    for target in targets:
-        click.echo(f"  docker   logging into {target.label}...")
-        if _login(target):
-            usable.append(target)
-            continue
-        if target.mirror:
-            click.secho(
-                f"  docker   the {target.label} mirror is left out, its login failed "
-                f"or {' / '.join(target.credential_names())} are not set",
-                fg="yellow",
-            )
-            continue
-        user_env, secret_env = target.credential_names()
-        click.secho(
-            f"  error: could not log into {target.label}. Check {user_env} and "
-            f"{secret_env}.",
-            fg="red",
-        )
-        raise SystemExit(1)
-
-    refs = [ref for target in usable for ref in target.refs]
-    click.echo("  docker   building image...")
-    try:
-        build_production_image(product, str(context.workspace()), docker_dir, refs)
-    except subprocess.CalledProcessError:
-        click.secho("  error: Docker image build failed.", fg="red")
-        raise SystemExit(1)
-
-    for target in usable:
-        click.echo(f"  docker   pushing to {target.label}...")
-        try:
-            for ref in target.refs:
-                run(["docker", "push", ref])
-        except subprocess.CalledProcessError:
+    with registry_session([t.host for t in targets]) as docker_env:
+        usable = []
+        for target in targets:
+            click.echo(f"  docker   logging into {target.label}...")
+            if _login(target, docker_env):
+                usable.append(target)
+                continue
             if target.mirror:
                 click.secho(
-                    f"  docker   the push to the {target.label} mirror failed and is "
-                    "left out",
+                    f"  docker   the {target.label} mirror is left out, its login "
+                    f"failed or {' / '.join(target.credential_names())} are not set",
                     fg="yellow",
                 )
                 continue
-            click.secho(f"  error: the push to {target.label} failed.", fg="red")
+            user_env, secret_env = target.credential_names()
+            click.secho(
+                f"  error: could not log into {target.label}. Check {user_env} and "
+                f"{secret_env}.",
+                fg="red",
+            )
+            raise SystemExit(1)
+
+        refs = [ref for target in usable for ref in target.refs]
+        click.echo("  docker   building image...")
+        try:
+            build_production_image(product, str(context.workspace()), docker_dir, refs)
+        except subprocess.CalledProcessError:
+            click.secho("  error: Docker image build failed.", fg="red")
             raise SystemExit(1)
-        click.echo(f"  docker   {', '.join(target.refs)}")
+
+        for target in usable:
+            click.echo(f"  docker   pushing to {target.label}...")
+            try:
+                for ref in target.refs:
+                    run(["docker", "push", ref], env=docker_env)
+            except subprocess.CalledProcessError:
+                if target.mirror:
+                    click.secho(
+                        f"  docker   the push to the {target.label} mirror failed "
+                        "and is left out",
+                        fg="yellow",
+                    )
+                    continue
+                click.secho(f"  error: the push to {target.label} failed.", fg="red")
+                raise SystemExit(1)
+            click.echo(f"  docker   {', '.join(target.refs)}")
 
     click.echo("  docker   push complete")
 

{splent_cli-1.29.0 → splent_cli-1.29.1}/src/splent_cli/services/marketplace.py

@@ -19,7 +19,8 @@ Layout of the index document (schema 1)::
     }
 
 Feature entries carry the full contract (provides / requires / extensible /
-docker), the derived archetype, presentation metadata (description,
+docker), the settings the feature declares under ``[tool.splent.config]``
+(``config``), the derived archetype, presentation metadata (description,
 category, tags), distribution state (latest tag, PyPI presence) and the
 computed reverse dependencies (``used_by``).
 """
@@ -36,6 +37,11 @@ import click
 INDEX_SCHEMA = 1
 FEATURE_PREFIX = "splent_feature_"
 
+# Where a feature declares the variables it reads, and the value a setting
+# holds when only the deployment can supply it (a secret).
+CONFIG_TABLE = ("tool", "splent", "config")
+REQUIRED_VALUE = "<SET>"
+
 # Feeds feature:search / feature:info when no explicit path is given.
 INDEX_URL_ENV = "SPLENT_INDEX_URL"
 
@@ -72,6 +78,67 @@ def index_cache_path(workspace: str) -> Path:
 # ── Feature entries ───────────────────────────────────────────────────
 
 
+# The value types product:env writes into an env file. A table or a date
+# under [tool.splent.config] never reaches the environment, so it is no
+# setting a product can change.
+_CONFIG_TYPES = (bool, int, float, str, list)
+
+
+def _config_text(value) -> str:
+    """A declared value as the environment receives it from ``product:env``.
+
+    Booleans are ``true``/``false``, numbers and strings their plain text, and
+    a list its items joined by commas.
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, list):
+        return ",".join(_config_text(item) for item in value)
+    return str(value)
+
+
+def config_declarations(pyproject_text: str, data: dict | None = None) -> list[dict]:
+    """The settings a feature declares under ``[tool.splent.config]``.
+
+    One ``{"key", "default", "required", "help"}`` per key, in the order they
+    are declared (tomllib keeps it), for every key whose value reaches the
+    environment. ``default`` is the value as text (see :func:`_config_text`).
+    A value of ``<SET>`` means only the deployment can supply it, so it gives
+    ``required`` true and an empty ``default``. ``help`` is the comment above
+    the key, or trailing its value (see :func:`toml_edit.key_comments`), and
+    ``""`` when there is none.
+
+    The values come from tomllib (*data*, parsed from *pyproject_text* when
+    not given) and only the comments from the text, so an unusual layout
+    costs the help and never a key or a value.
+    """
+    from splent_cli.utils.toml_edit import TomlEditError, key_comments
+
+    if data is None:
+        data = tomllib.loads(pyproject_text)
+    declared = data.get("tool", {}).get("splent", {}).get("config", {})
+    if not isinstance(declared, dict) or not declared:
+        return []
+    try:
+        comments = key_comments(pyproject_text, CONFIG_TABLE)
+    except TomlEditError:
+        comments = {}
+    settings = []
+    for key, value in declared.items():
+        if not isinstance(value, _CONFIG_TYPES):
+            continue
+        required = isinstance(value, str) and value.strip() == REQUIRED_VALUE
+        settings.append(
+            {
+                "key": key,
+                "default": "" if required else _config_text(value),
+                "required": required,
+                "help": comments.get(key, ""),
+            }
+        )
+    return settings
+
+
 def feature_entry_from_pyproject(
     pyproject_text: str,
     *,
@@ -109,6 +176,7 @@ def feature_entry_from_pyproject(
         "provides": contract.get("provides", {}),
         "requires": contract.get("requires", {}),
         "extensible": contract.get("extensible", {}),
+        "config": config_declarations(pyproject_text, data),
         "docker": contract.get("docker") or None,
         "refinement": splent.get("refinement") or None,
         "cli_version": splent.get("cli_version"),

{splent_cli-1.29.0 → splent_cli-1.29.1}/src/splent_cli/services/release.py

@@ -203,11 +203,33 @@ def require_release_version(version: str | None) -> None:
     raise SystemExit(1)
 
 
-def commit_locally(cwd: str, version: str, subject: str = "bump version") -> None:
-    """Stage all changes and commit. Nothing leaves the machine here.
+def untracked_files(cwd: str) -> set[str]:
+    """Paths git does not track and does not ignore, relative to ``cwd``."""
+    r = subprocess.run(
+        ["git", "ls-files", "--others", "--exclude-standard"],
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+    )
+    return {line for line in r.stdout.splitlines() if line.strip()}
+
+
+def commit_locally(
+    cwd: str,
+    version: str,
+    subject: str = "bump version",
+    leave_out: set[str] | None = None,
+) -> None:
+    """Stage the release's changes and commit. Nothing leaves the machine here.
 
     A local commit is reversible, so it happens before the first irreversible
     step and is pushed only once the un-undoable channel has accepted.
+
+    ``leave_out`` are the untracked files that were already there before the
+    release started. They are not staged: the marketplace's first release
+    committed a derive log, the staged UVL model and the contracts snapshot,
+    all of them build output the developer never meant to version, and the
+    server then refused to update over its own copies of them.
     """
     r = subprocess.run(
         ["git", "status", "--porcelain"],
@@ -219,10 +241,34 @@ def commit_locally(cwd: str, version: str, subject: str = "bump version") -> Non
         click.echo("  commit   working tree clean, nothing to commit")
         return
 
+    leave_out = set(leave_out or ())
+    if leave_out:
+        click.secho(
+            f"  commit   leaving {len(leave_out)} file(s) out that were untracked "
+            "before the release: "
+            + ", ".join(sorted(leave_out)[:5])
+            + (" ..." if len(leave_out) > 5 else ""),
+            fg="bright_black",
+        )
     try:
         subprocess.run(
-            ["git", "add", "-A"], cwd=cwd, check=True, capture_output=True, text=True
+            ["git", "add", "-u"], cwd=cwd, check=True, capture_output=True, text=True
+        )
+        created = sorted(untracked_files(cwd) - leave_out)
+        if created:
+            subprocess.run(
+                ["git", "add", "--", *created],
+                cwd=cwd,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        staged = subprocess.run(
+            ["git", "diff", "--cached", "--quiet"], cwd=cwd, capture_output=True
         )
+        if staged.returncode == 0:
+            click.echo("  commit   nothing the release changed, nothing to commit")
+            return
         subprocess.run(
             ["git", "commit", "-m", f"chore: {subject} to {version}"],
             cwd=cwd,
@@ -1598,12 +1644,16 @@ def run_release_pipeline(
     # ── Everything below this line changes the world ──────────────────
     click.echo()
 
+    # Files nobody versioned before the release started are the developer's
+    # business (a log, a local note), not the release's.
+    left_alone = untracked_files(path)
+
     update_version(pyproject, normalized)
 
     if pre_commit_hook:
         pre_commit_hook(path, normalized)
 
-    commit_locally(path, tag, subject=f"release {name}")
+    commit_locally(path, tag, subject=f"release {name}", leave_out=left_alone)
 
     # Where this version is already published. From the first entry on, any
     # failure leaves the channels out of step, and is reported as such.

{splent_cli-1.29.0 → splent_cli-1.29.1}/src/splent_cli/utils/toml_edit.py

@@ -32,6 +32,10 @@ nothing is written. The same line by line idea is what
 ``upgrade_plan.replace_feature_pins`` does for ``feature:upgrade``; this module
 covers the edits that insert and remove entries, keys and tables as well.
 
+:func:`key_comments` reads the same scan the other way round. It returns
+the comment written above each key of a table, which is how a feature
+documents its settings, so the marketplace can show it.
+
 No third party round-trip library is needed. tomlkit would keep the
 formatting too, but it is one more dependency every CLI install and image
 has to carry, and replacing a list through it still loses the comments
@@ -742,6 +746,50 @@ def edit_toml(text: str, data: dict) -> str:
     return result
 
 
+def key_comments(text: str, table: tuple[str, ...]) -> dict[str, str]:
+    """The comment that documents each key written directly in *table*.
+
+    A key's comment is the block of ``#`` lines right above it, each line
+    without its leading ``#`` and joined into one paragraph. When there is no
+    block, it is the comment trailing the key's value instead. A blank line
+    ends a block, so a comment separated from the key by one documents
+    something else, and so does one above the table header. A key with
+    neither maps to ``""``. Keys of sub-tables and of arrays of tables are
+    left out.
+
+    Raises :class:`TomlEditError` for a file the scanner cannot read.
+    """
+    doc = _Scanner(text).scan()
+    # By TOML's grammar, what lies between the end of one statement and the
+    # start of the next is only blank lines and comments.
+    ends = sorted(
+        [t.header_end for t in doc.tables[1:]] + [kv.line_end for kv in doc.kvs]
+    )
+    depth = len(table) + 1
+    out: dict[str, str] = {}
+    for kv in doc.kvs:
+        if kv.in_aot or len(kv.path) != depth or kv.path[:-1] != table:
+            continue
+        gap_start = max((end for end in ends if end <= kv.line_start), default=0)
+        block: list[str] = []
+        for line in text[gap_start : kv.line_start].splitlines():
+            stripped = line.lstrip("\ufeff").strip()
+            block = (
+                [*block, _comment_text(stripped)] if stripped.startswith("#") else []
+            )
+        comment = " ".join(part for part in block if part)
+        if not comment:
+            tail = text[kv.value_end : kv.line_end].strip()
+            comment = _comment_text(tail) if tail.startswith("#") else ""
+        out[kv.path[-1]] = comment
+    return out
+
+
+def _comment_text(line: str) -> str:
+    """A comment line without its leading ``#`` marks and spaces."""
+    return line.lstrip("#").strip()
+
+
 def write_toml(path: str | os.PathLike, data: dict) -> None:
     """Write *data* to the TOML file at *path*, keeping its comments and layout.
 

{splent_cli-1.29.0 → splent_cli-1.29.1/src/splent_cli.egg-info}/PKG-INFO

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