splent-cli 1.45.0__tar.gz → 1.47.0__tar.gz

{splent_cli-1.45.0/src/splent_cli.egg-info → splent_cli-1.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_cli
-Version: 1.45.0
+Version: 1.47.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.45.0 → splent_cli-1.47.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_cli"
-version = "1.45.0"
+version = "1.47.0"
 description = "SPLENT-CLI is a CLI to be able to work on your development more easily."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -78,8 +78,10 @@ where = ["src"]
 
 # The templates product:create, feature:create and the rest render. They are
 # data, not modules, so without this a wheel from PyPI shipped none of them.
+# The build context of the frontend toolchain image too, so a CLI installed
+# from PyPI can build the image a feature with frontend/ builds in.
 [tool.setuptools.package-data]
-splent_cli = ["templates/**/*"]
+splent_cli = ["templates/**/*", "toolchain/**/*"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{splent_cli-1.45.0 → splent_cli-1.47.0}/src/splent_cli/commands/feature/feature_compile.py

@@ -1,12 +1,14 @@
+import dataclasses
 import logging
 import os
 import posixpath
 import shlex
 import subprocess
+from pathlib import Path
 
 import click
 
-from splent_cli.services import compose, context
+from splent_cli.services import compose, context, frontend
 from splent_cli.utils.proc import run
 from splent_cli.utils.feature_utils import (
     get_features_from_pyproject,
@@ -196,17 +198,67 @@ def webpack_container(product: str, env: str, workspace: str) -> tuple[str | Non
     "assets/dist, and fail when the feature has nothing to build. "
     "feature:release runs it.",
 )
-def feature_compile(feature_name, watch, env_dev, env_prod, release_build):
+@click.option(
+    "--verify",
+    is_flag=True,
+    help="Build nothing: check that assets/meta/manifest.json matches the "
+    "files of assets/dist and the lock, for each feature with frontend/.",
+)
+def feature_compile(feature_name, watch, env_dev, env_prod, release_build, verify):
     if release_build and watch:
         raise click.UsageError("--release builds the bundle once; drop --watch.")
+    if verify and (watch or release_build):
+        raise click.UsageError("--verify builds nothing; drop --watch and --release.")
     production = (
         os.getenv("FLASK_ENV", "develop") == "production" or env_prod or release_build
     )
+    workspace = str(context.workspace())
 
-    features = (
-        [_feature_ref(feature_name)] if feature_name else get_features_from_pyproject()
-    )
+    # A feature with frontend/ of its own builds in the SPLENT toolchain and
+    # needs no product at all, so naming one is enough.
+    if feature_name and _frontend_root(workspace, _feature_ref(feature_name)):
+        features = [_feature_ref(feature_name)]
+    else:
+        features = (
+            [_feature_ref(feature_name)]
+            if feature_name
+            else get_features_from_pyproject()
+        )
 
+    if verify:
+        raise SystemExit(_verify_features(features, workspace))
+
+    frontend_features = [f for f in features if _frontend_root(workspace, f)]
+    legacy_features = [f for f in features if f not in frontend_features]
+    failed = [
+        feature
+        for feature in frontend_features
+        if not _compile_frontend(
+            _frontend_root(workspace, feature),
+            feature,
+            watch=watch,
+            production=production,
+            release_build=release_build,
+        )
+    ]
+
+    if legacy_features:
+        failed += _compile_legacy(
+            legacy_features, watch, production, env_dev, env_prod, release_build
+        )
+    if failed and not watch:
+        click.secho(
+            f"Compilation failed for {len(failed)} feature(s): {', '.join(failed)}",
+            fg="red",
+            err=True,
+        )
+        raise SystemExit(1)
+
+
+def _compile_legacy(features, watch, production, env_dev, env_prod, release_build):
+    """Compile features without frontend/ (legacy mode): their own
+    webpack.config.js, run in the product's web container against the
+    product's node_modules. The features that failed."""
     env = context.resolve_env(env_dev, env_prod)
     product = context.require_app()
     workspace = str(context.workspace())
@@ -218,7 +270,7 @@ def feature_compile(feature_name, watch, env_dev, env_prod, release_build):
     # Every feature is attempted, so one run reports every broken bundle, and
     # the exit code then says whether any failed: the production Dockerfile
     # chains `splent feature:compile && ...` and must stop on a failure.
-    failed = [
+    return [
         feature
         for feature in features
         if not _compile_in_container(
@@ -232,13 +284,246 @@ def feature_compile(feature_name, watch, env_dev, env_prod, release_build):
             release_build=release_build,
         )
     ]
-    if failed and not watch:
+
+
+def _split_ref(feature: str) -> tuple[str, str, str | None]:
+    """``(namespace, name, version)`` of a feature ref, splent_io by default."""
+    parts = feature.split("/")
+    if len(parts) == 2:
+        org_raw, name_version = parts
+        org_safe = normalize_namespace(org_raw)
+    else:
+        org_safe, name_version = "splent_io", parts[0]
+    base_name, _, version = name_version.partition("@")
+    return org_safe, base_name, version or None
+
+
+def _frontend_root(workspace: str, feature: str) -> str | None:
+    """The working copy at the workspace root of an unpinned FEATURE when it
+    has frontend/ of its own, else None. A pinned one is never compiled."""
+    _, base_name, version = _split_ref(feature)
+    if version:
+        return None
+    root = os.path.join(workspace, base_name)
+    return root if frontend.declares(root) else None
+
+
+def _compile_frontend(root, feature, *, watch, production, release_build) -> bool:
+    """Build one feature's frontend/ in the SPLENT toolchain. False only
+    when the build failed or could not run.
+
+    Inside the product's web container there is no Docker daemon to run the
+    toolchain in. Its startup script compiles every feature with --watch,
+    and a feature with frontend/ is left to the CLI there, with a note.
+    """
+    namespace, base_name, _ = _split_ref(feature)
+    if _is_product_container() and not release_build:
         click.secho(
-            f"Compilation failed for {len(failed)} feature(s): {', '.join(failed)}",
-            fg="red",
-            err=True,
+            f"    {feature} builds in the SPLENT toolchain, not in this container: "
+            f"run splent feature:compile {base_name} --watch from the CLI.",
+            fg="bright_black",
         )
-        raise SystemExit(1)
+        return True
+
+    mode = "production" if production else "development"
+    click.echo(
+        click.style(f"🚀 Compiling {feature} in the SPLENT toolchain...", fg="cyan")
+    )
+    try:
+        image = frontend.ensure_toolchain()
+        frontend.install(root, image=image, force=release_build)
+        result = frontend.build(
+            root,
+            namespace,
+            base_name,
+            mode=mode,
+            watch=watch and not production,
+            image=image,
+        )
+    except click.ClickException as e:
+        click.secho(f"❌ Error compiling {feature}: {e.format_message()}", fg="red")
+        return False
+    if watch and not production:
+        if result.returncode != 0:
+            click.secho(
+                f"❌ The watch container of {feature} did not start:\n"
+                f"{(result.stderr or '').strip()}",
+                fg="red",
+            )
+            return False
+        name = frontend.watch_container(base_name)
+        click.echo(click.style(f"👀 Watching {feature} in {mode} mode...", fg="blue"))
+        click.echo(
+            click.style(
+                f"    log: docker logs -f {name}    stop: docker stop {name}",
+                fg="bright_black",
+            )
+        )
+        return True
+    if result.returncode != 0:
+        click.secho(f"❌ Error compiling {feature}: the build failed", fg="red")
+        return False
+    click.echo(
+        click.style(f"✅ Successfully compiled {feature} in {mode} mode!", fg="green")
+    )
+    return True
+
+
+def _verify_features(features, workspace: str) -> int:
+    """feature:compile --verify: 1 when the bundle of any feature with
+    frontend/ does not match its manifest, else 0.
+
+    A working copy is checked at the workspace root, a pinned feature in the
+    copy the product links, which is what its app serves, and where neither
+    is, as in the production image, in the package pip installed. When the
+    product has docker/frontend.lock.json (product:build writes it), every
+    feature it lists is checked too, and has to carry the manifest the lock
+    names, of the version it names: the bundle its release built.
+    """
+    from splent_cli.utils.frontend_check import read_lock
+
+    product = context.active_app(workspace)
+    lock = read_lock(os.path.join(workspace, product)) if product else None
+    locked = (lock or {}).get("features") or {}
+    refs = list(features)
+    named = {_split_ref(feature)[1] for feature in refs}
+    for name, entry in sorted(locked.items()):
+        if name not in named:
+            version = entry.get("version")
+            namespace = entry.get("namespace") or "splent_io"
+            refs.append(f"{namespace}/{name}" + (f"@v{version}" if version else ""))
+
+    failed = 0
+    for feature in refs:
+        namespace, base_name, version = _split_ref(feature)
+        entry = locked.get(base_name)
+        copy = _copy_of(workspace, product, namespace, base_name, version)
+        if copy is None and entry is not None:
+            failed += 1
+            click.secho(
+                f"❌ {feature}: docker/frontend.lock.json lists it, and it is "
+                "neither here nor installed",
+                fg="red",
+            )
+            continue
+        if entry is None and (copy is None or not copy.declares):
+            click.echo(
+                click.style(
+                    f"    {feature} has no frontend/, nothing to verify.",
+                    fg="bright_black",
+                )
+            )
+            continue
+        problems = frontend.verify_assets(
+            copy.assets, lock=copy.lock, production=bool(version) or copy.installed
+        )
+        if entry is not None:
+            problems += _against_lock(copy, entry, base_name)
+        if problems:
+            failed += 1
+            click.secho(
+                f"❌ {feature}: the bundle does not match its manifest", fg="red"
+            )
+            for problem in problems:
+                click.secho(f"     {problem}", fg="red")
+        else:
+            click.secho(f"✅ {feature}: the bundle matches its manifest", fg="green")
+    return 1 if failed else 0
+
+
+@dataclasses.dataclass
+class _Copy:
+    """The copy of a feature --verify checks: its assets/, its frontend
+    lock (a package pip installed has none), whether pip installed it, and
+    whether it declares frontend/ (an installed one does when it carries a
+    manifest)."""
+
+    assets: Path
+    lock: Path | None
+    installed: bool
+    declares: bool
+
+
+def _copy_of(workspace, product, namespace, base_name, version) -> _Copy | None:
+    """The working copy, the product's link to a pinned release, or else
+    the package pip installed. None when there is none."""
+    if version:
+        root = (
+            os.path.join(
+                workspace, product, "features", namespace, f"{base_name}@{version}"
+            )
+            if product
+            else None
+        )
+    else:
+        root = os.path.join(workspace, base_name)
+    if root and os.path.isdir(root):
+        return _Copy(
+            frontend.assets_dir(root, namespace, base_name),
+            Path(root) / frontend.FRONTEND_DIR / frontend.LOCK,
+            False,
+            frontend.declares(root),
+        )
+    import importlib.util
+
+    try:
+        spec = importlib.util.find_spec(f"{namespace}.{base_name}")
+    except (ImportError, ValueError):
+        spec = None
+    if spec is None or not spec.submodule_search_locations:
+        return None
+    assets = Path(list(spec.submodule_search_locations)[0]) / "assets"
+    return _Copy(assets, None, True, (assets / "meta" / "manifest.json").is_file())
+
+
+def _against_lock(copy: _Copy, entry: dict, base_name: str) -> list[str]:
+    """What does not match between a feature's bundle and its entry in
+    docker/frontend.lock.json."""
+    problems = []
+    wanted = entry.get("manifest_sha256")
+    found = frontend.manifest_sha256(copy.assets)
+    if wanted and found and found != wanted:
+        problems.append(
+            "assets/meta/manifest.json is not the one docker/frontend.lock.json "
+            "names: run splent product:build"
+        )
+    if not copy.installed:
+        return problems
+    import importlib.metadata
+
+    distribution = entry.get("distribution") or base_name
+    try:
+        installed = importlib.metadata.version(distribution)
+    except importlib.metadata.PackageNotFoundError:
+        installed = None
+    if entry.get("version") and installed != entry["version"]:
+        problems.append(
+            f"pip installed {installed or 'no version'}, and "
+            f"docker/frontend.lock.json names {entry['version']}"
+        )
+    if found is None:
+        problems.append(
+            f"it was installed {_channel(distribution)}, without the bundle its "
+            "release built: release it again, so its wheel and its tag carry it"
+        )
+    return problems
+
+
+def _channel(distribution: str) -> str:
+    """How pip installed DISTRIBUTION: from its git tag (git+) or a wheel."""
+    import importlib.metadata
+    import json
+
+    try:
+        direct = importlib.metadata.distribution(distribution).read_text(
+            "direct_url.json"
+        )
+        url = json.loads(direct or "{}")
+    except (importlib.metadata.PackageNotFoundError, ValueError):
+        url = {}
+    if "vcs_info" in url:
+        return f"from its git tag (git+{url.get('url', '')})"
+    return "from a wheel"
 
 
 def _feature_ref(name: str) -> str:

{splent_cli-1.45.0 → splent_cli-1.47.0}/src/splent_cli/commands/feature/feature_create.py

@@ -200,13 +200,24 @@ JS_FILES = {
     "assets/js/webpack.config.js": "feature/feature_webpack.config.js.j2",
 }
 
+# What --frontend writes instead: the entry point under the package, and
+# frontend/ at the root of the repository, whose package.json
+# (services/frontend.py writes it) declares the bundle and its dependencies.
+FRONTEND_SRC_FILES = {
+    "assets/js/scripts.js": "feature/feature_frontend_scripts.js.j2",
+}
+FRONTEND_BASE_FILES = {
+    "frontend/.npmrc": "feature/feature_frontend.npmrc.j2",
+}
+
 
-def _build_file_map(feature_type, short_name, docker=False, js=False):
+def _build_file_map(feature_type, short_name, docker=False, js=False, frontend=False):
     """Return (src_files, base_files) dicts for the given feature type.
 
     ``js`` adds the webpack entry point and config (JS_FILES). Code that
     recognises what feature:create wrote passes it: a feature created with
-    --js, or by a CLI that always wrote them, has them.
+    --js, or by a CLI that always wrote them, has them. ``frontend`` adds the
+    entry point and frontend/ of a feature built by the SPLENT toolchain.
     """
     T = "feature/"  # template prefix
 
@@ -309,6 +320,9 @@ def _build_file_map(feature_type, short_name, docker=False, js=False):
     # for nothing.
     if js:
         src = {**src, **JS_FILES}
+    if frontend:
+        src = {**src, **FRONTEND_SRC_FILES}
+        base_common = {**base_common, **FRONTEND_BASE_FILES}
 
     # Merge common files (type-specific wins on conflict)
     merged_src = {**src_common, **src}
@@ -341,13 +355,21 @@ def _build_file_map(feature_type, short_name, docker=False, js=False):
     help="Also scaffold assets/js (scripts.js and webpack.config.js) for a "
     "feature with a JavaScript bundle of its own.",
 )
+@click.option(
+    "--frontend",
+    is_flag=True,
+    default=False,
+    help="Also scaffold frontend/ (package.json and .npmrc) and assets/js/scripts.js "
+    "for a feature whose bundle the SPLENT toolchain builds, with JavaScript "
+    "dependencies of its own.",
+)
 @click.option(
     "--no-git",
     is_flag=True,
     default=False,
     help="Do not make the feature a git repository.",
 )
-def make_feature(full_name, feature_type, docker, js, no_git):
+def make_feature(full_name, feature_type, docker, js, frontend, no_git):
     """
     Creates a new feature in the workspace.
     The name must follow the pattern <namespace>/<feature_name>.
@@ -371,6 +393,13 @@ def make_feature(full_name, feature_type, docker, js, no_git):
     the feature has no bundle, and nothing compiles one for it. Plain
     stylesheets and vendored libraries need neither (register_asset).
 
+    \b
+    --frontend adds frontend/package.json, which declares the bundle and the
+    npm packages it imports (splent feature:npm <feature> install <package>),
+    frontend/.npmrc and assets/js/scripts.js. The SPLENT toolchain builds it,
+    against the feature's own frontend/node_modules, with no webpack config
+    of the feature's. Not with --js, which writes the legacy one.
+
     \b
     The feature becomes a git repository on main, with the scaffold as its
     first commit made with your git identity, unless it is created inside a
@@ -384,7 +413,13 @@ def make_feature(full_name, feature_type, docker, js, no_git):
       splent feature:create splent-io/splent_feature_email_queue --type service
       splent feature:create splent-io/splent_feature_rabbitmq --type service --docker
       splent feature:create splent-io/splent_feature_charts --js
+      splent feature:create splent-io/splent_feature_charts --frontend
     """
+    if js and frontend:
+        raise click.UsageError(
+            "--js writes the legacy webpack.config.js and --frontend the "
+            "toolchain's frontend/: choose one."
+        )
 
     # --- Validate input pattern ---
     if "/" not in full_name:
@@ -452,11 +487,12 @@ def make_feature(full_name, feature_type, docker, js, no_git):
         # inline turns a line that has to be read literally into noise.
         "env_prefix": env_prefix,
         "host_port_ref": "${" + env_prefix + "_HOST_PORT}",
+        "frontend": frontend,
     }
 
     # --- Build file maps for the selected type ---
     src_files, base_files = _build_file_map(
-        feature_type, short_name, docker=docker, js=js
+        feature_type, short_name, docker=docker, js=js, frontend=frontend
     )
 
     # --- Create src structure ---
@@ -479,6 +515,14 @@ def make_feature(full_name, feature_type, docker, js, no_git):
 
     write_license_files(feature_dir)
 
+    if frontend:
+        from splent_cli.services import frontend as toolchain
+
+        toolchain.write_package(
+            feature_dir,
+            toolchain.new_package(org_safe, feature_name, license_="LGPL-3.0-or-later"),
+        )
+
     # --- src/__init__.py (namespace root) ---
     src_root = os.path.join(feature_dir, "src")
     os.makedirs(src_root, exist_ok=True)
@@ -517,6 +561,16 @@ def make_feature(full_name, feature_type, docker, js, no_git):
         _report_git(*git_state, feature_dir)
     click.echo()
 
+    if frontend:
+        click.echo(
+            click.style("     frontend/  ", fg="cyan")
+            + "add a dependency with "
+            + click.style(f"feature:npm {short_name} install <package>", bold=True)
+            + ", build with "
+            + click.style(f"feature:compile {short_name}", bold=True)
+        )
+        click.echo()
+
     if docker:
         click.echo(
             click.style("     docker/  ", fg="cyan")

{splent_cli-1.45.0 → splent_cli-1.47.0}/src/splent_cli/commands/feature/feature_drift.py

@@ -7,7 +7,7 @@ from splent_cli.services import context
 from splent_cli.utils.feature_resolution import resolve_feature_ref
 from splent_cli.utils.template_drift import (
     CLI_VERSION,
-    FEATURE_FILES,
+    feature_files,
     count_changed_lines,
     feature_ctx,
     file_diff,
@@ -74,7 +74,8 @@ def _print_diff_lines(diff: list[str]) -> None:
 def feature_drift(feature_identifier, verbose):
     """
     Compare SPLENT-owned files in a feature against the current templates.
-    Only scaffold files are checked (webpack.config.js, MANIFEST.in, .gitignore).
+    Only scaffold files are checked (webpack.config.js, MANIFEST.in, .gitignore;
+    for a feature with frontend/, MANIFEST.in, .gitignore and frontend/.npmrc).
     Developer-owned source files are never touched.
     Does not modify any files. Reads the editable copy at the workspace
     root, or else the snapshot the product pins (or the newest one).
@@ -125,10 +126,11 @@ def feature_drift(feature_identifier, verbose):
         )
     )
 
-    ctx = feature_ctx(org_safe, feature_name)
+    files, extra = feature_files(cache_path)
+    ctx = feature_ctx(org_safe, feature_name, **extra)
     any_drift = False
 
-    for rel_tpl, tpl_name in FEATURE_FILES.items():
+    for rel_tpl, tpl_name in files.items():
         rel_path = resolve_feature_rel(rel_tpl, org_safe, feature_name)
         abs_path = cache_path / rel_path
         expected = render_template(tpl_name, ctx)