splent-cli 1.52.0__tar.gz → 1.54.0__tar.gz

{splent_cli-1.52.0/src/splent_cli.egg-info → splent_cli-1.54.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_cli
-Version: 1.52.0
+Version: 1.54.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

{splent_cli-1.52.0 → splent_cli-1.54.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_cli"
-version = "1.52.0"
+version = "1.54.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.52.0 → splent_cli-1.54.0}/src/splent_cli/commands/command/command_create.py

@@ -10,7 +10,7 @@ from splent_cli.utils.path_utils import PathUtils
 # Segments separated by ':', each starting with a letter. Dashes are allowed
 # in the Click name (feature:inject-config) and become '_' in the file name
 # and the Python identifier.
-_NAME_RE = re.compile(r"[a-z][a-z0-9_-]*(:[a-z][a-z0-9_-]*)*")
+_NAME_RE = re.compile(r"[a-z][a-z0-9_-]*(:[a-z][a-z0-9_-]*)?")
 
 # Names the generated module already uses; a command function with one of
 # these names would shadow the import it relies on.
@@ -33,7 +33,7 @@ def _validate_name(name: str) -> tuple[str, str]:
     ):
         raise click.ClickException(
             f"Invalid command name '{name}'. Use lowercase letters, digits, "
-            "'_' and '-', starting with a letter, with ':' between segments "
+            "'_' and '-', starting with a letter, and at most one ':' "
             "(for example db:dump-all). Python keywords and the names click, "
             "current_app and requires_app are not allowed."
         )

{splent_cli-1.52.0 → splent_cli-1.54.0}/src/splent_cli/commands/feature/feature_frontend_init.py

@@ -1,5 +1,5 @@
 """
-splent feature:frontend:init
+splent feature:frontend-init
 
 Move a feature to frontend/ (SD-01): its bundle is then built by the SPLENT
 toolchain from frontend/package.json, against the feature's own
@@ -17,6 +17,7 @@ from splent_cli.services import frontend
 from splent_cli.commands.feature.feature_npm import editable_frontend_root
 from splent_cli.utils.io_utils import load_toml
 from splent_cli.utils.template_drift import feature_ctx, render_template
+from splent_cli.utils.command_loader import old_name
 
 # The SPLENT-owned files of a feature with frontend/, written as
 # feature:sync-template would write them.
@@ -176,7 +177,7 @@ def _leftovers(
 
 
 @click.command(
-    "feature:frontend:init",
+    "feature:frontend-init",
     short_help="Give a feature a frontend/ of its own, built by the SPLENT toolchain.",
 )
 @click.argument("feature_ref")
@@ -208,8 +209,8 @@ def feature_frontend_init(feature_ref, adopt_vendor):
 
     \b
     Examples:
-      splent feature:frontend:init charts
-      splent feature:frontend:init charts --adopt-vendor
+      splent feature:frontend-init charts
+      splent feature:frontend-init charts --adopt-vendor
     """
     root, name = editable_frontend_root(feature_ref)
     if frontend.declares(root):
@@ -247,7 +248,7 @@ def feature_frontend_init(feature_ref, adopt_vendor):
     if fallback:
         (root / "frontend" / "webpack.extra.js").write_text(
             "// What the feature's webpack.config.js set beyond the SPLENT preset,\n"
-            "// merged over it (feature:frontend:init carried it over).\n"
+            "// merged over it (feature:frontend-init carried it over).\n"
             "module.exports = {\n"
             f"  resolve: {{ fallback: {json.dumps(fallback)} }},\n"
             "};\n",
@@ -308,4 +309,7 @@ def feature_frontend_init(feature_ref, adopt_vendor):
     click.echo()
 
 
-cli_command = feature_frontend_init
+cli_commands = [
+    feature_frontend_init,
+    old_name("feature:frontend:init", feature_frontend_init),
+]

{splent_cli-1.52.0 → splent_cli-1.54.0}/src/splent_cli/commands/feature/feature_hook_add.py

@@ -1,5 +1,5 @@
 """
-splent feature:hook:add
+splent feature:hook-add
 
 Add a new template hook registration to a feature's hooks.py.
 Also updates [tool.splent.contract.provides].hooks in pyproject.toml.
@@ -17,13 +17,14 @@ from pathlib import Path
 from splent_cli.services import context
 from splent_cli.utils.feature_utils import normalize_namespace
 from splent_cli.utils.io_utils import atomic_write
+from splent_cli.utils.command_loader import old_name
 
 
 DEFAULT_NAMESPACE = os.getenv("SPLENT_DEFAULT_NAMESPACE", "splent_io")
 
 
 # ─────────────────────────────────────────────────────────────────────────────
-# Helpers (shared with feature:hook:remove)
+# Helpers (shared with feature:hook-remove)
 # ─────────────────────────────────────────────────────────────────────────────
 
 
@@ -317,7 +318,7 @@ def _check_function_name(function_name: str) -> None:
 
 
 @click.command(
-    "feature:hook:add",
+    "feature:hook-add",
     short_help="Add a new template hook to a feature's hooks.py.",
 )
 @click.argument("feature_ref")
@@ -342,14 +343,14 @@ def feature_hook_add(feature_ref, slot, function_name):
 
     \b
     Example:
-      splent feature:hook:add splent_feature_notes layout.sidebar render_notes_sidebar
+      splent feature:hook-add splent_feature_notes layout.sidebar render_notes_sidebar
     """
     _check_slot(slot)
     _check_function_name(function_name)
 
     workspace = str(context.workspace())
     feature_path, ns, name = resolve_editable(
-        feature_ref, workspace, "feature:hook:add"
+        feature_ref, workspace, "feature:hook-add"
     )
 
     package_dir = feature_path / "src" / ns / name
@@ -403,4 +404,4 @@ def feature_hook_add(feature_ref, slot, function_name):
     click.echo()
 
 
-cli_command = feature_hook_add
+cli_commands = [feature_hook_add, old_name("feature:hook:add", feature_hook_add)]

{splent_cli-1.52.0 → splent_cli-1.54.0}/src/splent_cli/commands/feature/feature_hook_remove.py

@@ -1,5 +1,5 @@
 """
-splent feature:hook:remove
+splent feature:hook-remove
 
 Remove a template hook registration from a feature's hooks.py.
 Optionally also removes the callback function definition.
@@ -17,6 +17,7 @@ from splent_cli.commands.feature.feature_hook_add import (
     rewrite_provides_hooks,
 )
 from splent_cli.utils.io_utils import atomic_write
+from splent_cli.utils.command_loader import old_name
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -90,7 +91,7 @@ def _remove_trailing_blank_lines(text: str) -> str:
 
 
 @click.command(
-    "feature:hook:remove",
+    "feature:hook-remove",
     short_help="Remove a template hook from a feature's hooks.py.",
 )
 @click.argument("feature_ref")
@@ -116,12 +117,12 @@ def feature_hook_remove(feature_ref, slot, with_function, yes):
 
     \b
     Example:
-      splent feature:hook:remove splent_feature_notes layout.sidebar
-      splent feature:hook:remove splent_feature_notes layout.sidebar --with-function -y
+      splent feature:hook-remove splent_feature_notes layout.sidebar
+      splent feature:hook-remove splent_feature_notes layout.sidebar --with-function -y
     """
     workspace = str(context.workspace())
     feature_path, ns, name = resolve_editable(
-        feature_ref, workspace, "feature:hook:remove"
+        feature_ref, workspace, "feature:hook-remove"
     )
 
     hooks_path = feature_path / "src" / ns / name / "hooks.py"
@@ -185,4 +186,7 @@ def feature_hook_remove(feature_ref, slot, with_function, yes):
     click.echo()
 
 
-cli_command = feature_hook_remove
+cli_commands = [
+    feature_hook_remove,
+    old_name("feature:hook:remove", feature_hook_remove),
+]

{splent_cli-1.52.0 → splent_cli-1.54.0}/src/splent_cli/commands/feature/feature_hooks.py

@@ -138,7 +138,7 @@ def feature_hooks(feature_ref, as_json):
     click.echo()
     click.echo(
         click.style("  Manage hooks with:", fg="bright_black")
-        + f"  splent feature:hook:add {name} <slot> <function>"
+        + f"  splent feature:hook-add {name} <slot> <function>"
     )
     click.echo()
 

{splent_cli-1.52.0 → splent_cli-1.54.0}/src/splent_cli/commands/feature/feature_npm.py

@@ -68,7 +68,7 @@ def feature_npm(feature_ref, npm_args):
     if not frontend.declares(root):
         raise click.ClickException(
             f"{name} has no frontend/package.json. Create it with "
-            f"splent feature:frontend:init {name}."
+            f"splent feature:frontend-init {name}."
         )
     args = [*npm_args, "--ignore-scripts"]
     if npm_args[0] in _SAVING:

{splent_cli-1.52.0 → splent_cli-1.54.0}/src/splent_cli/commands/product/product_commands.py

@@ -80,7 +80,7 @@ def product_commands():
     own = _own_commands()
     product = context.active_app() or "product"
 
-    if not registry and not own.commands and not own.shadowed and not own.error:
+    if not (registry or own.commands or own.shadowed or own.refused or own.error):
         click.echo()
         click.secho("  No feature or product commands registered.", fg="yellow")
         click.echo()
@@ -108,6 +108,12 @@ def product_commands():
         _table("Product Commands", "Product", own_rows)
         click.echo()
         click.secho(f"  {len(own_rows)} command(s) of {product}'s own.", dim=True)
+    for name in own.refused:
+        click.secho(
+            f"  ⚠ {product} has a command {name}, which cannot be reached: a "
+            "command's name has one colon. Use a hyphen.",
+            fg="yellow",
+        )
     for name in own.shadowed:
         click.secho(
             f"  ⚠ {product} has a command {name}, which is the CLI's own and "

{splent_cli-1.52.0 → splent_cli-1.54.0}/src/splent_cli/commands/product/product_frontend_audit.py

@@ -1,5 +1,5 @@
 """
-product:frontend:audit — what the product's bundles ship, audited as one set.
+product:frontend-audit — what the product's bundles ship, audited as one set.
 
 Each feature with frontend/ audits its own lock when it is released (npm
 audit, services/frontend.py), but a bundle is immutable: an advisory
@@ -28,6 +28,7 @@ import click
 from splent_cli.services import compose, context, frontend
 from splent_cli.utils.frontend_check import LOCK_FILE, read_lock
 from splent_cli.utils.npm_semver import satisfies
+from splent_cli.utils.command_loader import old_name
 
 DEFAULT_REGISTRY = "https://registry.npmjs.org"
 ADVISORIES = "/-/npm/v1/security/advisories/bulk"
@@ -206,7 +207,7 @@ def _vendored(workspace: str, feature: dict, name: str) -> list[dict]:
 
 
 @click.command(
-    "product:frontend:audit",
+    "product:frontend-audit",
     short_help="Audit what the product's bundles ship against npm's advisories.",
 )
 @click.option(
@@ -234,8 +235,8 @@ def product_frontend_audit(sbom_path):
 
     \b
     Examples:
-      splent product:frontend:audit
-      splent product:frontend:audit --sbom frontend.sbom.cdx.json
+      splent product:frontend-audit
+      splent product:frontend-audit --sbom frontend.sbom.cdx.json
     """
     product = context.require_app()
     workspace = str(context.workspace())
@@ -320,4 +321,7 @@ def _product_version(product_dir: str) -> str:
     return str(data.get("project", {}).get("version") or "unknown")
 
 
-cli_command = product_frontend_audit
+cli_commands = [
+    product_frontend_audit,
+    old_name("product:frontend:audit", product_frontend_audit),
+]

{splent_cli-1.52.0 → splent_cli-1.54.0}/src/splent_cli/commands/product/product_test.py

@@ -27,7 +27,7 @@ from pathlib import Path
 
 import click
 
-from splent_cli.services import context, web_container
+from splent_cli.services import context, ui_audit, web_container
 from splent_cli.utils.feature_utils import (
     load_product_features,
     load_product_pyproject,
@@ -131,30 +131,34 @@ def _run_product_tests(product, workspace, levels, verbose):
 
         rc = run(cmd, check=False, env=env_vars).returncode
 
-    if not own:
-        return rc
-
     if levels:
         # A level flag asks for a quick, partial run. The product's tests
         # build its whole app and are not split by level, so they wait for
         # a full run, which is the one the release checks and the CI make.
+        if own:
+            click.secho(
+                f"\n  {product}'s own tests ({OWN_TESTS_DIR}/) run only without a "
+                "level flag.",
+                dim=True,
+            )
+        return rc
+
+    if own:
         click.secho(
-            f"\n  {product}'s own tests ({OWN_TESTS_DIR}/) run only without a "
-            "level flag.",
-            dim=True,
+            f"\n  ▶  {product}  its own tests ({len(own)} file(s) in {OWN_TESTS_DIR}/)",
+            fg="cyan",
+            bold=True,
         )
-        return rc
+        cmd = [sys.executable, "-m", "splent_cli", "product:test", "--own-tests"]
+        if verbose:
+            cmd.append("-v")
+        rc = run(cmd, check=False, env=env_vars).returncode or rc
 
-    click.secho(
-        f"\n  ▶  {product}  its own tests ({len(own)} file(s) in {OWN_TESTS_DIR}/)",
-        fg="cyan",
-        bold=True,
-    )
-    cmd = [sys.executable, "-m", "splent_cli", "product:test", "--own-tests"]
-    if verbose:
-        cmd.append("-v")
-    own_rc = run(cmd, check=False, env=env_vars).returncode
-    return rc or own_rc
+    # The look of its pages, when the product asks for it and its stack is up.
+    if ui_audit.declared(product_path):
+        cmd = [sys.executable, "-m", "splent_cli", "product:ui-audit", "--if-up"]
+        rc = run(cmd, check=False, env=env_vars).returncode or rc
+    return rc
 
 
 def _run_own_tests(product, verbose) -> None:

splent_cli-1.54.0/src/splent_cli/commands/product/product_ui_audit.py

@@ -0,0 +1,233 @@
+"""
+product:ui-audit — look at every page of the product in a real browser.
+
+The checks live in services/ui_audit.py and the page itself, in
+templates/ui_audit/measure.js. This is what runs them: in the product's web
+container, the one place its Selenium grid can be reached from.
+"""
+
+import os
+import shutil
+
+import click
+
+from splent_cli.services import context, ui_audit, web_container
+
+
+class _CannotRun(Exception):
+    """No browser or no app to look at, which says nothing about the pages."""
+
+
+def _delegated_args(
+    url, start, widths, themes, public_only, screenshots, max_pages, if_up
+):
+    args = ["product:ui-audit"]
+    if if_up:
+        args.append("--if-up")
+    if url:
+        args += ["--url", url]
+    for path in start:
+        args += ["--start", path]
+    for width in widths:
+        args += ["--width", str(width)]
+    if len(themes) == 1:
+        args += ["--theme", themes[0]]
+    if public_only:
+        args.append("--public-only")
+    if screenshots:
+        args.append("--screenshots")
+    if max_pages != ui_audit.MAX_PAGES:
+        args += ["--max-pages", str(max_pages)]
+    return args
+
+
+def render(results, out) -> int:
+    """Print what RESULTS found. Returns how many distinct problems."""
+    summary = ui_audit.summarize(results)
+    problems = 0
+    for kind, title in ui_audit.KINDS.items():
+        entries = summary.get(kind)
+        if not entries:
+            continue
+        problems += len(entries)
+        click.echo()
+        click.secho(f"  {title} ({len(entries)})", bold=True)
+        ranked = sorted(entries.items(), key=lambda kv: -len(kv[1]["paths"]))
+        for key, entry in ranked:
+            click.echo(f"     {key}")
+            pages = len(entry["paths"])
+            more = f" and {pages - 1} more" if pages > 1 else ""
+            detail = f"  {entry['detail']}" if entry["detail"] else ""
+            click.secho(
+                f"       [{ui_audit.where_label(entry['where'])}] "
+                f"{entry['paths'][0]}{more}{detail}",
+                dim=True,
+            )
+    failed = ui_audit.errors_of(results)
+    for record in failed[:5]:
+        click.secho(
+            f"     could not measure {record['url']}: {record['error']}", fg="yellow"
+        )
+    click.echo()
+    pages = {(r.get("who"), r.get("path")) for r in results if "error" not in r}
+    click.echo(f"  {len(pages)} pages measured, {len(results)} measurements.")
+    click.secho(f"  Report and screenshots in {out}", dim=True)
+    return problems + len(failed)
+
+
+@click.command(
+    "product:ui-audit",
+    short_help="Look at every page in a real browser, at every width and theme.",
+)
+@click.option(
+    "--url",
+    default=None,
+    help="Audit this address, such as your production site, as an anonymous "
+    "visitor. Defaults to the product's development app.",
+)
+@click.option("--start", multiple=True, help="Start from this path. Can be repeated.")
+@click.option(
+    "--width",
+    "widths",
+    multiple=True,
+    type=int,
+    help="Only this width, in both themes. Can be repeated.",
+)
+@click.option(
+    "--theme",
+    type=click.Choice(["light", "dark", "both"]),
+    default="both",
+    help="Which theme to look at.",
+)
+@click.option("--public-only", is_flag=True, help="Skip the pages behind a login.")
+@click.option(
+    "--screenshots",
+    is_flag=True,
+    help="Keep a screenshot of every page, not only of those with a problem.",
+)
+@click.option(
+    "--max-pages",
+    default=ui_audit.MAX_PAGES,
+    show_default=True,
+    help="Stop discovering pages after this many, per visitor.",
+)
+@click.option(
+    "--if-up",
+    is_flag=True,
+    hidden=True,
+    help="Pass, saying so, when there is no grid or no app to look at "
+    "(used by product:test, whose tests need neither).",
+)
+def product_ui_audit(
+    url, start, widths, theme, public_only, screenshots, max_pages, if_up
+):
+    """
+    Look at every page of the product in a real browser.
+
+    \b
+    Walks the links from the first page and, in Chrome, at five widths from
+    a wide screen to a small phone and in the light and dark themes, looks
+    for what the tests cannot see: what leaves the screen, is cut off, is
+    squeezed or sits under something else, text too faint to read, light
+    boxes left on a dark page, and pictures that fail or fade away.
+
+    \b
+    Fails when it finds anything, so it can stop a release. product:test
+    runs it too when the product has a [tool.splent.ui_audit] table.
+
+    \b
+    Examples:
+      splent product:ui-audit
+      splent product:ui-audit --width 390 --theme dark
+      splent product:ui-audit --url https://www.example.org --screenshots
+    """
+    product = context.require_app()
+    themes = ("light", "dark") if theme == "both" else (theme,)
+    try:
+        if not web_container.is_product_container():
+            container = web_container.name(product)
+            if not web_container.running(container):
+                raise _CannotRun(
+                    f"{container} is not running. Start the product with "
+                    "splent product:up, then splent product:run --dev"
+                )
+            raise SystemExit(
+                web_container.delegate(
+                    product,
+                    _delegated_args(
+                        url,
+                        start,
+                        widths,
+                        themes,
+                        public_only,
+                        screenshots,
+                        max_pages,
+                        if_up,
+                    ),
+                )
+            )
+        audit, out = _audit_the_product(
+            product, url, start, widths, themes, public_only, screenshots, max_pages
+        )
+    except _CannotRun as error:
+        if not if_up:
+            raise click.ClickException(str(error)) from error
+        click.secho(f"\n  The UI audit did not run. {error}", fg="yellow")
+        return
+    except ui_audit.AuditError as error:
+        raise click.ClickException(str(error)) from error
+
+    if render(audit.results, out):
+        click.secho("  The audit found problems.\n", fg="red")
+        raise SystemExit(1)
+    click.secho("  Nothing wrong.\n", fg="green")
+
+
+def _audit_the_product(
+    product, url, start, widths, themes, public_only, screenshots, max_pages
+):
+    """Run the audit here, in the web container. Returns it and where it wrote."""
+    workspace = context.workspace()
+    config = ui_audit.read_config(workspace / product)
+    if start:
+        config.start = list(start)
+
+    grid_url = os.getenv("SELENIUM_GRID_URL")
+    grid = ui_audit.Grid(grid_url) if grid_url else None
+    if grid is None or not grid.ready():
+        raise _CannotRun(
+            "No Selenium grid answers here. It is part of the product's development "
+            "stack: start it with splent product:up"
+        )
+    base = url or os.getenv("SELENIUM_TARGET_URL")
+    if not base:
+        raise _CannotRun(
+            "SELENIUM_TARGET_URL is not set, so the browser does not know where the "
+            "app is. Pass --url"
+        )
+
+    out = workspace / ".splent_cache" / "ui_audit" / product
+    shutil.rmtree(out, ignore_errors=True)
+    audit = ui_audit.Audit(
+        grid,
+        base,
+        config,
+        out=out,
+        max_pages=max_pages,
+        log=lambda line: click.echo(line),
+    )
+    audit.every_screenshot = screenshots
+    runs = ui_audit.plan(widths, themes)
+
+    click.secho(f"\n  Auditing {base}\n", bold=True)
+    try:
+        audit.measure_as("public", None, runs)
+        # A login is a test account of the development app, and only there.
+        if not url and not public_only:
+            for login in config.logins:
+                audit.measure_as(login.split(":", 1)[0].split("@")[0], login, runs)
+    except ui_audit.NothingAnswers as error:
+        raise _CannotRun(str(error)) from error
+    finally:
+        audit.write_report()
+    return audit, out

{splent_cli-1.52.0 → splent_cli-1.54.0}/src/splent_cli/services/own_commands.py

@@ -9,7 +9,9 @@ context.
 
 The CLI's own ``product:*`` commands win. A product command named like one
 of them cannot be reached, and product:commands says so: a CLI that ships a
-new built-in never takes a product's command away unnoticed.
+new built-in never takes a product's command away unnoticed. A name with a
+colon of its own would make two, which no command has, so it is left out and
+product:commands says so too.
 """
 
 from __future__ import annotations
@@ -25,12 +27,14 @@ MODULE = "commands"
 
 class OwnCommands(NamedTuple):
     """What a product contributes: ``commands`` by the name they are run
-    with, ``shadowed`` the names a built-in took, and ``error`` why its
-    commands module could not be imported, None when it could."""
+    with, ``shadowed`` the names a built-in took, ``error`` why its commands
+    module could not be imported, None when it could, and ``refused`` the
+    names with a colon of their own."""
 
     commands: dict[str, click.Command]
     shadowed: list[str]
     error: str | None
+    refused: list[str] = []
 
 
 NONE = OwnCommands({}, [], None)
@@ -62,15 +66,18 @@ def collect(product: str | None, builtin) -> OwnCommands:
         commands = declared(product)
     except Exception as e:
         return OwnCommands({}, [], f"{product}.{MODULE}: {e}")
-    found, shadowed = {}, []
+    found, shadowed, refused = {}, [], []
     for command in commands:
         if not command.name:
             continue
         name = PREFIX + command.name
+        if ":" in command.name:
+            refused.append(name)
+            continue
         if name in builtin:
             shadowed.append(name)
             continue
         # Run in the app's context, as a feature's (cli.py).
         command.requires_app = True  # type: ignore[attr-defined]
         found[name] = command
-    return OwnCommands(found, shadowed, None)
+    return OwnCommands(found, shadowed, None, refused)