p4n4-lib 0.2.0__py3-none-any.whl

p4n4_lib/__init__.py

@@ -0,0 +1,3 @@
+"""p4n4-lib: shared library between P4N4 stacks and clients."""
+
+__version__ = "0.2.0"

p4n4_lib/compose.py

@@ -0,0 +1,167 @@
+"""Docker Compose subprocess wrappers.
+
+Prefers the Compose v2 plugin (``docker compose``) and falls back to the
+standalone ``docker-compose`` binary. Hosts such as NVIDIA Jetson (JetPack
+ships Ubuntu's ``docker.io`` without the plugin) often only have the latter;
+there ``docker compose up -d`` fails with "unknown shorthand flag: 'd' in -d".
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+
+class ComposeNotFoundError(RuntimeError):
+    """Neither `docker compose` nor `docker-compose` is available."""
+
+
+@functools.cache
+def compose_cmd() -> tuple[str, ...]:
+    """Return the Compose invocation prefix for this host."""
+    if shutil.which("docker"):
+        probe = subprocess.run(
+            ["docker", "compose", "version"],
+            capture_output=True,
+            check=False,
+        )
+        if probe.returncode == 0:
+            return ("docker", "compose")
+    if shutil.which("docker-compose"):
+        return ("docker-compose",)
+    raise ComposeNotFoundError(
+        "Docker Compose not found. Install the Compose v2 plugin "
+        "(e.g. `sudo apt install docker-compose-plugin`) or the standalone "
+        "`docker-compose` binary."
+    )
+
+
+def _is_legacy() -> bool:
+    return compose_cmd() == ("docker-compose",)
+
+
+def _base(args: list[str], cwd: Path) -> int:
+    result = subprocess.run([*compose_cmd(), *args], cwd=cwd, check=False)
+    return result.returncode
+
+
+def up(cwd: Path, build: bool = False, pull: bool = False, detach: bool = True) -> int:
+    args = ["up"]
+    if detach:
+        args.append("-d")
+    if build:
+        args.append("--build")
+    if pull:
+        if _is_legacy():
+            # docker-compose v1 has no `up --pull`; pull explicitly first
+            rc = _base(["pull"], cwd)
+            if rc != 0:
+                return rc
+        else:
+            args.append("--pull=always")
+    return _base(args, cwd)
+
+
+def down(cwd: Path, volumes: bool = False) -> int:
+    # Stack services sit in Compose profiles, and `down` only stops the ones
+    # in active profiles; enable them all so services started by name (or
+    # dropped from COMPOSE_PROFILES since) are stopped too. docker-compose v1
+    # has no "*" profile.
+    args = ["down"] if _is_legacy() else ["--profile", "*", "down"]
+    if volumes:
+        args.append("-v")
+    return _base(args, cwd)
+
+
+def ps(cwd: Path) -> list[dict]:
+    """Return parsed service list from `docker compose ps --format json`."""
+    if _is_legacy():
+        return _ps_legacy(cwd)
+    result = subprocess.run(
+        [*compose_cmd(), "ps", "--format", "json"],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    services = []
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+            if isinstance(obj, list):
+                services.extend(obj)
+            else:
+                services.append(obj)
+        except json.JSONDecodeError:
+            continue
+    return services
+
+
+def _ps_legacy(cwd: Path) -> list[dict]:
+    """docker-compose v1 has no JSON output; build v2-shaped dicts via `docker inspect`."""
+    ids = subprocess.run(
+        ["docker-compose", "ps", "-q"],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+    ).stdout.split()
+    if not ids:
+        return []
+    result = subprocess.run(
+        ["docker", "inspect", *ids],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    try:
+        containers = json.loads(result.stdout or "[]")
+    except json.JSONDecodeError:
+        return []
+    services = []
+    for c in containers:
+        state = c.get("State") or {}
+        labels = (c.get("Config") or {}).get("Labels") or {}
+        publishers = []
+        for key, bindings in ((c.get("NetworkSettings") or {}).get("Ports") or {}).items():
+            target, _, proto = key.partition("/")
+            for b in bindings or []:
+                publishers.append(
+                    {
+                        "PublishedPort": int(b.get("HostPort") or 0),
+                        "TargetPort": int(target),
+                        "Protocol": proto or "tcp",
+                    }
+                )
+        services.append(
+            {
+                "Name": c.get("Name", "").lstrip("/"),
+                "Service": labels.get("com.docker.compose.service", ""),
+                "State": state.get("Status", ""),
+                "Health": (state.get("Health") or {}).get("Status", ""),
+                "Publishers": publishers,
+            }
+        )
+    return services
+
+
+def logs(
+    cwd: Path,
+    service: str | None = None,
+    tail: int | None = None,
+    follow: bool = True,
+) -> int:
+    args = ["logs"]
+    if follow:
+        args.append("-f")
+    if tail is not None:
+        args.extend(["--tail", str(tail)])
+    if service:
+        args.append(service)
+    return _base(args, cwd)

p4n4_lib/env.py

@@ -0,0 +1,96 @@
+"""Dotenv read/write utilities."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+ENV_FILE = ".env"
+
+# Characters Compose would interpolate, strip or split on in an unquoted value
+_NEEDS_QUOTES = set(" \t#$'\"\\")
+
+
+def quote(value: str) -> str:
+    """
+    Quote a value for a Compose .env file when it needs it. Generated secrets
+    are plain hex and stay bare; user-supplied ones (an external broker
+    password) may hold anything. Single quotes are literal in Compose; a value
+    containing one is double-quoted, with backslash, double quote and $ escaped.
+    """
+    if not _NEEDS_QUOTES.intersection(value):
+        return value
+    if "'" not in value:
+        return f"'{value}'"
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"').replace("$", "\\$")
+    return f'"{escaped}"'
+
+
+def unquote(value: str) -> str:
+    """
+    Reverse quote(): strip matching quotes and undo double-quote escapes. As
+    in Compose, an unquoted value ends at an inline " #" comment.
+    """
+    if len(value) >= 2 and value[0] == value[-1] == "'":
+        return value[1:-1]
+    if len(value) >= 2 and value[0] == value[-1] == '"':
+        out, chars = [], iter(value[1:-1])
+        for ch in chars:
+            out.append(next(chars, "") if ch == "\\" else ch)
+        return "".join(out)
+    return re.split(r"\s#", value, maxsplit=1)[0].rstrip()
+
+
+def load(path: Path) -> dict[str, str]:
+    """Parse .env file into a dict, skipping comments and blank lines."""
+    env: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" in line:
+            key, _, val = line.partition("=")
+            env[key.strip()] = unquote(val.strip())
+    return env
+
+
+def set_value(path: Path, key: str, value: str, comment: str | None = None) -> None:
+    """Set one key in an existing .env: replace its first assignment, or append it
+    (after `comment`, if given) when the file doesn't define it."""
+    lines = path.read_text(encoding="utf-8").splitlines() if path.exists() else []
+    entry = f"{key}={quote(value)}"
+    for i, line in enumerate(lines):
+        if line.strip().partition("=")[0].strip() == key and "=" in line:
+            lines[i] = entry
+            break
+    else:
+        if lines and lines[-1].strip():
+            lines.append("")
+        if comment:
+            lines.extend(f"# {c}" for c in comment.splitlines())
+        lines.append(entry)
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n")
+
+
+def write(path: Path, values: dict[str, str], template_path: Path | None = None) -> None:
+    """Write values to .env, preserving template comments/structure when a template is given."""
+    if template_path and template_path.exists():
+        lines = template_path.read_text(encoding="utf-8").splitlines()
+        out = []
+        for line in lines:
+            stripped = line.strip()
+            if stripped and not stripped.startswith("#") and "=" in stripped:
+                key, _, _ = stripped.partition("=")
+                key = key.strip()
+                if key in values:
+                    # Strip inline comments from template line before writing value
+                    out.append(f"{key}={quote(values[key])}")
+                    continue
+            out.append(line)
+        path.write_text("\n".join(out) + "\n", encoding="utf-8", newline="\n")
+    else:
+        path.write_text(
+            "\n".join(f"{k}={quote(v)}" for k, v in values.items()) + "\n",
+            encoding="utf-8",
+            newline="\n",
+        )

p4n4_lib/layers.py

@@ -0,0 +1,114 @@
+"""Layer registry: per-layer stack metadata shared by all clients."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+
+@dataclass(frozen=True)
+class Layer:
+    name: str
+    repo_url: str
+    # Files/dirs copied from the stack repo into a new project
+    copy_paths: tuple[str, ...] = ()
+    # Files a valid project must contain
+    required_files: tuple[str, ...] = ()
+    # Keys a valid project .env must define
+    required_env_keys: tuple[str, ...] = ()
+
+    @property
+    def clone_prefix(self) -> str:
+        return f"p4n4-{self.name}-"
+
+
+_sources: dict = yaml.safe_load(
+    (Path(__file__).parent / "sources.yaml").read_text(encoding="utf-8")
+)
+
+LAYERS: dict[str, Layer] = {
+    "iot": Layer(
+        name="iot",
+        repo_url=_sources["iot_repo_url"],
+        copy_paths=("docker-compose.yml", "config", "scripts"),
+        required_files=(
+            "docker-compose.yml",
+            ".env",
+            "config/mosquitto/mosquitto.conf",
+            "config/mosquitto/bridge.sh",
+            "config/node-red/settings.js",
+            "config/node-red/flows/flows.json",
+            "config/grafana/provisioning/datasources/datasources.yml",
+            "scripts/init-buckets.sh",
+        ),
+        required_env_keys=(
+            "TZ",
+            "INFLUXDB_USERNAME",
+            "INFLUXDB_PASSWORD",
+            "INFLUXDB_ORG",
+            "INFLUXDB_TOKEN",
+            "INFLUXDB_BUCKET",
+            "GRAFANA_USER",
+            "GRAFANA_PASSWORD",
+            "NODE_RED_USER",
+            "NODE_RED_PASSWORD",
+        ),
+    ),
+    "ai": Layer(
+        name="ai",
+        repo_url=_sources["ai_repo_url"],
+        copy_paths=("docker-compose.yml", "config", "scripts"),
+        required_files=(
+            "docker-compose.yml",
+            ".env",
+            "config/letta/letta.conf",
+            "scripts/pull-models.sh",
+        ),
+        required_env_keys=(
+            "LETTA_SERVER_PASSWORD",
+            "N8N_BASIC_AUTH_USER",
+            "N8N_BASIC_AUTH_PASSWORD",
+            "N8N_ENCRYPTION_KEY",
+            "N8N_HOST",
+            "INFLUXDB_TOKEN",
+            "INFLUXDB_ORG",
+            "INFLUXDB_BUCKET",
+        ),
+    ),
+    "edge": Layer(
+        name="edge",
+        repo_url=_sources["edge_repo_url"],
+        copy_paths=("docker-compose.yml", "runner", "edge-impulse", "onnx"),
+        required_files=(
+            "docker-compose.yml",
+            ".env",
+            "runner/Dockerfile",
+            "runner/runner.py",
+            "edge-impulse/models",
+            "onnx/models",
+        ),
+        required_env_keys=(
+            "MODEL_BACKEND",
+            "MQTT_HOST",
+            "MQTT_PORT",
+            "INFLUXDB_TOKEN",
+            "INFLUXDB_ORG",
+            "INFLUXDB_BUCKET_AI_EVENTS",
+            "TZ",
+        ),
+    ),
+    # The web UI (p4n4-dashboard): one container from a released image, so
+    # only its compose file is copied, not the Flutter sources. Last in the
+    # order, so `up` starts it after the stacks it shows and `down` stops it first.
+    "dashboard": Layer(
+        name="dashboard",
+        repo_url=_sources["dashboard_repo_url"],
+        copy_paths=("docker-compose.yml",),
+        required_files=("docker-compose.yml", ".env"),
+        required_env_keys=("DASHBOARD_VERSION", "DASHBOARD_PORT"),
+    ),
+}
+
+LAYER_NAMES: tuple[str, ...] = tuple(LAYERS)

p4n4_lib/layout.py

@@ -0,0 +1,55 @@
+"""Project layout: where each layer's stack files live inside a project.
+
+Single-layer projects keep stack files at the project root. Multi-layer
+projects give each layer its own subdirectory so the stacks run as separate
+Compose projects (p4n4-ai attaches to the p4n4-net network that p4n4-iot
+creates, so their compose files must not be merged).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+
+from p4n4_lib.layers import LAYERS
+
+COMPOSE_FILE = "docker-compose.yml"
+
+
+def ordered(names: Iterable[str]) -> list[str]:
+    """Sort layer names into dependency order (iot before ai before edge)."""
+    wanted = set(names)
+    return [name for name in LAYERS if name in wanted]
+
+
+def layer_dir(project_dir: Path, layers: Sequence[str], name: str) -> Path:
+    """Directory a layer's stack files live in."""
+    return project_dir / name if len(layers) > 1 else project_dir
+
+
+def compose_project_name(project: str, layers: Sequence[str], name: str) -> str:
+    """
+    Compose project name for a layer: the project name for single-layer projects,
+    `<project>-<layer>` for multi-layer ones. Without it, Compose names a layer after
+    its directory (`iot`, `ai`, ...), so every multi-layer project on a host would
+    share the same volumes. Lowercased, with characters Compose rejects replaced by `-`.
+    """
+    raw = project if len(layers) <= 1 else f"{project}-{name}"
+    cleaned = re.sub(r"[^a-z0-9_-]+", "-", raw.lower()).lstrip("-_")
+    return cleaned or "p4n4"
+
+
+def compose_dirs(project_dir: Path, layers: Sequence[str]) -> list[tuple[str, Path]]:
+    """
+    Return (layer, directory) pairs that contain a compose file, in
+    dependency order. Single-layer projects resolve to the project root.
+    """
+    if (project_dir / COMPOSE_FILE).exists():
+        names = ordered(layers)
+        return [(names[0] if names else "", project_dir)]
+    return [
+        (name, project_dir / name)
+        for name in ordered(layers)
+        if (project_dir / name / COMPOSE_FILE).exists()
+    ]

p4n4_lib/manifest.py

@@ -0,0 +1,93 @@
+"""Manifest (.p4n4.json) read/write utilities."""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path, PurePosixPath
+
+MANIFEST_FILE = ".p4n4.json"
+SCHEMA_VERSION = 1
+
+# Tabs p4n4-dashboard can show; the optional "dashboard" block narrows them
+DASHBOARD_TABS = ("services", "edge", "agent", "grafana", "video")
+
+
+def find(start: Path | None = None) -> Path | None:
+    """Walk up from start (default cwd) to find .p4n4.json."""
+    current = (start or Path.cwd()).resolve()
+    for directory in [current, *current.parents]:
+        candidate = directory / MANIFEST_FILE
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def load(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def save(path: Path, data: dict) -> None:
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8", newline="\n")
+
+
+def create(project: str, layers: list[str]) -> dict:
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "project": project,
+        "layers": layers,
+        "created_at": datetime.now(UTC).isoformat(),
+    }
+
+
+def dashboard_errors(data: dict) -> list[str]:
+    """
+    Problems with the optional ``dashboard`` block, which tells p4n4-dashboard
+    how to present the project:
+
+    - ``grafana_path``: Grafana page the Grafana tab opens, e.g.
+      ``/d/<uid>/<slug>``.
+    - ``tabs``: the dashboard tabs this project can serve (see
+      ``DASHBOARD_TABS``); the dashboard hides the others while connected.
+    - ``theme``: directory, relative to the project, holding the white-label
+      theme the project's dashboard is built with (``brand.json``, icon,
+      fonts). Installed with ``dart run tool/brand.dart install <project>``.
+
+    Only the block's shape is checked here; ``validate.validate_project``
+    checks that the theme directory exists.
+    """
+    if "dashboard" not in data:
+        return []
+    block = data["dashboard"]
+    if not isinstance(block, dict):
+        return [".p4n4.json: dashboard must be an object"]
+
+    errors = []
+    for key in sorted(set(block) - {"grafana_path", "tabs", "theme"}):
+        errors.append(f".p4n4.json: dashboard.{key} is not a known setting")
+
+    path = block.get("grafana_path")
+    if path is not None and not (isinstance(path, str) and path.startswith("/")):
+        errors.append('.p4n4.json: dashboard.grafana_path must be a path starting with "/"')
+
+    theme = block.get("theme")
+    if theme is not None and not (
+        isinstance(theme, str)
+        and theme.strip()
+        and not PurePosixPath(theme).is_absolute()
+        and ".." not in PurePosixPath(theme).parts
+    ):
+        errors.append(".p4n4.json: dashboard.theme must be a directory inside the project")
+
+    tabs = block.get("tabs")
+    if tabs is not None:
+        if not isinstance(tabs, list) or not tabs:
+            errors.append(".p4n4.json: dashboard.tabs must be a non-empty list")
+        else:
+            unknown = [t for t in tabs if t not in DASHBOARD_TABS]
+            if unknown:
+                errors.append(
+                    f".p4n4.json: unknown dashboard.tabs {unknown} "
+                    f"(expected any of {', '.join(DASHBOARD_TABS)})"
+                )
+    return errors

p4n4_lib/scaffold.py

@@ -0,0 +1,91 @@
+"""Project scaffolding: fetch stack sources and copy them into a project."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from p4n4_lib import env as envutil
+from p4n4_lib.layers import Layer
+
+
+class ScaffoldError(Exception):
+    """Raised when fetching or copying a stack source fails."""
+
+
+def fetch_source(layer: Layer, source: str | Path | None = None) -> tuple[Path, str | None]:
+    """
+    Return a (Path, tmpdir_or_None) to a stack source directory.
+
+    If `source` is a local path it is used directly; otherwise the layer repo is
+    cloned at shallow depth into a temp dir that the caller must clean up.
+    """
+    if source:
+        path = Path(source).expanduser().resolve()
+        if not path.exists():
+            raise ScaffoldError(f"source path does not exist: {path}")
+        return path, None
+
+    tmp = tempfile.mkdtemp(prefix=layer.clone_prefix)
+    # core.autocrlf=false: Git for Windows defaults to CRLF checkouts, which
+    # break shell scripts run inside the Linux containers ('bash\r').
+    result = subprocess.run(
+        ["git", "clone", "--depth", "1", "--config", "core.autocrlf=false", layer.repo_url, tmp],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        shutil.rmtree(tmp, ignore_errors=True)
+        raise ScaffoldError(
+            f"git clone failed:\n{result.stderr.strip()}\n\n"
+            f"Tip: pass a local checkout path to scaffold offline."
+        )
+    return Path(tmp), tmp
+
+
+def scaffold_layer(
+    project_dir: Path,
+    layer: Layer,
+    env_values: dict[str, str],
+    source: str | Path | None = None,
+    compose_project_name: str | None = None,
+) -> None:
+    """Copy a layer's files into project_dir and write its .env.
+
+    With `compose_project_name`, the .env also sets COMPOSE_PROJECT_NAME, so the
+    layer's containers and volumes are namespaced per project (see
+    `layout.compose_project_name`)."""
+    src, tmpdir = fetch_source(layer, source)
+    try:
+        for name in layer.copy_paths:
+            s = src / name
+            if not s.exists():
+                raise ScaffoldError(f"Expected '{name}' in source repo but it was not found.")
+            d = project_dir / name
+            if s.is_dir():
+                shutil.copytree(s, d, ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+            else:
+                shutil.copy2(s, d)
+
+        # Make shell scripts executable
+        scripts_dir = project_dir / "scripts"
+        if scripts_dir.is_dir():
+            for script in scripts_dir.glob("*.sh"):
+                script.chmod(script.stat().st_mode | 0o111)
+
+        # Write .env: values override the .env.example template from the repo
+        envutil.write(project_dir / ".env", env_values, template_path=src / ".env.example")
+        if compose_project_name:
+            envutil.set_value(
+                project_dir / ".env",
+                "COMPOSE_PROJECT_NAME",
+                compose_project_name,
+                comment="Compose project name, set by p4n4 init: keeps this project's\n"
+                "containers' volumes apart from other projects'. Changing it on an\n"
+                "existing project switches to new, empty volumes.",
+            )
+    finally:
+        if tmpdir:
+            shutil.rmtree(tmpdir, ignore_errors=True)

p4n4_lib/secrets.py

@@ -0,0 +1,35 @@
+"""Secret generation and rotation policy shared by all clients."""
+
+from __future__ import annotations
+
+import secrets as _secrets
+
+ROTATABLE_KEYS = (
+    # IoT layer
+    "INFLUXDB_PASSWORD",
+    "INFLUXDB_TOKEN",
+    "GRAFANA_PASSWORD",
+    "NODE_RED_PASSWORD",
+    # AI layer
+    "LETTA_SERVER_PASSWORD",
+    "N8N_BASIC_AUTH_PASSWORD",
+    "N8N_ENCRYPTION_KEY",
+)
+
+# Secrets issued by someone else (an external broker's credentials): shown
+# masked alongside the others, never rotated or generated, since a new value
+# would no longer match the remote side
+EXTERNAL_KEYS = (
+    # IoT layer: bridge to an external MQTT broker
+    "MQTT_REMOTE_PASSWORD",
+)
+
+
+def token(n: int = 32) -> str:
+    """Return a hex token from n random bytes (2n characters)."""
+    return _secrets.token_hex(n)
+
+
+def rotation_value(key: str) -> str:
+    """Generate a replacement value sized for the given rotatable key."""
+    return token(16 if "PASSWORD" in key else 32)

p4n4_lib/sources.yaml

@@ -0,0 +1,4 @@
+iot_repo_url: https://github.com/raisga/p4n4-iot.git
+ai_repo_url: https://github.com/raisga/p4n4-ai.git
+edge_repo_url: https://github.com/raisga/p4n4-edge.git
+dashboard_repo_url: https://github.com/raisga/p4n4-dashboard.git

p4n4_lib/validate.py

@@ -0,0 +1,105 @@
+"""Project validation checks shared by all clients."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from p4n4_lib import env as envutil
+from p4n4_lib import layout
+from p4n4_lib import manifest as mf
+from p4n4_lib.layers import LAYERS
+
+
+def validate_project(project_dir: Path, data: dict) -> tuple[list[str], list[str]]:
+    """
+    Validate a loaded manifest against the project tree.
+
+    Returns (passed, errors) as human-readable check labels.
+    """
+    passed: list[str] = []
+    errors: list[str] = []
+
+    if data.get("schema_version") != mf.SCHEMA_VERSION:
+        errors.append(
+            f".p4n4.json schema_version mismatch "
+            f"(got {data.get('schema_version')}, expected {mf.SCHEMA_VERSION})"
+        )
+    else:
+        passed.append(".p4n4.json: valid")
+
+    dashboard_errors = mf.dashboard_errors(data)
+    errors.extend(dashboard_errors)
+    if "dashboard" in data and not dashboard_errors:
+        passed.append(".p4n4.json: dashboard settings valid")
+        if theme := data["dashboard"].get("theme"):
+            errors_before = len(errors)
+            _check_theme(project_dir / theme, theme, errors)
+            if len(errors) == errors_before:
+                passed.append(f"{theme}/brand.json: dashboard theme")
+
+    layer_names: list[str] = data.get("layers", [])
+    multi = len(layer_names) > 1
+    # A template ships its own variant of a stack (e.g. MQTT → Telegraf instead
+    # of Node-RED), so the base stack's file list doesn't apply. The template
+    # registry validates and smoke-tests the template's own files; here only
+    # its compose file and the variables its .env.example documents are checked.
+    from_template = isinstance(data.get("template"), dict)
+
+    for name in layout.ordered(n for n in layer_names if n in LAYERS):
+        layer = LAYERS[name]
+        base = layout.layer_dir(project_dir, layer_names, name)
+        prefix = f"{name}/" if multi else ""
+
+        if from_template:
+            required_files: tuple[str, ...] = (layout.COMPOSE_FILE, envutil.ENV_FILE)
+            example = base / f"{envutil.ENV_FILE}.example"
+            required_keys = tuple(envutil.load(example)) if example.exists() else ()
+        else:
+            required_files, required_keys = layer.required_files, layer.required_env_keys
+
+        for rel in required_files:
+            if (base / rel).exists():
+                passed.append(f"{prefix}{rel}")
+            else:
+                errors.append(f"Missing file: {prefix}{rel}")
+
+        if not required_keys:
+            continue
+
+        env_path = base / envutil.ENV_FILE
+        if env_path.exists():
+            env = envutil.load(env_path)
+            # Template variables may be deliberately empty (COMPOSE_PROFILES=)
+            missing = [
+                key
+                for key in required_keys
+                if (key not in env if from_template else not env.get(key))
+            ]
+            if missing:
+                errors.extend(f"{prefix}.env missing required key: {key}" for key in missing)
+            else:
+                passed.append(f"{prefix}.env: all required keys present")
+        else:
+            errors.append(f"{prefix}.env file not found")
+
+    return passed, errors
+
+
+def _check_theme(theme_dir: Path, label: str, errors: list[str]) -> None:
+    """
+    The theme must be a directory with a parseable brand.json naming its id.
+    Full checks (colors, contrast, native IDs, fonts) are the dashboard's
+    `tool/brand.dart check`; this only catches a missing or broken theme.
+    """
+    brand = theme_dir / "brand.json"
+    if not brand.is_file():
+        errors.append(f"Missing file: {label}/brand.json (.p4n4.json dashboard.theme)")
+        return
+    try:
+        data = json.loads(brand.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        errors.append(f"{label}/brand.json is not valid JSON: {exc}")
+        return
+    if not isinstance(data, dict) or not isinstance(data.get("id"), str) or not data["id"]:
+        errors.append(f'{label}/brand.json must have an "id"')

p4n4_lib-0.2.0.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: p4n4-lib
+Version: 0.2.0
+Summary: Shared library between P4N4 stacks and clients
+Project-URL: Homepage, https://github.com/raisga/p4n4-lib
+Project-URL: Documentation, https://github.com/raisga/p4n4-docs
+Project-URL: Issues, https://github.com/raisga/p4n4-lib/issues
+Author-email: RAISGA <jraleman@raisga.com>
+License: MIT
+License-File: LICENSE
+Keywords: docker,edge-ai,iot,library
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# p4n4-lib
+
+Shared Python library mediating between P4N4 stacks and clients
+(`p4n4-cli`, `p4n4-api`, `p4n4-dashboard`).
+
+Framework-free by design: no CLI/TUI/web dependencies, only `pyyaml`.
+Presentation (prompts, tables, colors) stays in the clients.
+
+## Modules
+
+| Module | Purpose |
+|--------|---------|
+| `p4n4_lib.manifest` | `.p4n4.json` manifest: find (walk-up), load, save, create, and checks for the optional `dashboard` block |
+| `p4n4_lib.env` | Dotenv read/write, template-preserving writes |
+| `p4n4_lib.layers` | Layer registry: repo URLs, copy paths, required files/env keys per layer (`iot`, `ai`, `edge`, `dashboard`) |
+| `p4n4_lib.layout` | Project layout: flat for single-layer projects, per-layer subdirectories for multi-layer |
+| `p4n4_lib.scaffold` | Fetch stack sources (local path or shallow clone) and copy into a project |
+| `p4n4_lib.validate` | Pure project validation returning (passed, errors) check lists; template projects are checked against their `.env.example` instead of the base stack |
+| `p4n4_lib.secrets` | Token generation and the rotatable-key policy |
+| `p4n4_lib.compose` | Docker Compose subprocess wrappers (`up`, `down`, `ps`, `logs`) |
+
+Stack repo URLs live in `p4n4_lib/sources.yaml`.
+
+## Install
+
+```bash
+pip install p4n4-lib
+pip install -e path/to/core/lib           # monorepo development
+```
+
+See [CHANGELOG.md](https://github.com/raisga/p4n4-lib/blob/main/CHANGELOG.md) for release notes.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT

p4n4_lib-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+p4n4_lib/__init__.py,sha256=c8otB6Z1Yt3sL_1Cn8gCqr-gephg9mrmi6Hg_zBr5Tk,87
+p4n4_lib/compose.py,sha256=FYb8mK6F03Gap5kEIcX7aGHSmix4S9St3N5NGA7Vb8s,5036
+p4n4_lib/env.py,sha256=1EG0JeKmkql_z_ofs_SKs-DwZMSgEzgIis686s1jfTU,3647
+p4n4_lib/layers.py,sha256=ZUVQ1XQE2sccSxD0yxffW7H1739-RUCevZJENK71IKU,3400
+p4n4_lib/layout.py,sha256=meWZtc9iao7er72_HnSZyBJq-jjvoB2VBO0AKP5yClg,2073
+p4n4_lib/manifest.py,sha256=ACgg4ogppERaMFkksYH1xBdMjhT8gAaIXC81fD-34mU,3272
+p4n4_lib/scaffold.py,sha256=VXeELSYJhNwG5egvfudhQJsKuURsvs5KVIFogtvDb-8,3360
+p4n4_lib/secrets.py,sha256=1RIGdWFPwbZ54Qmupm1trZ1qyBileyERd6MbX7QhqaA,953
+p4n4_lib/sources.yaml,sha256=QCI_UEUAanpazBJx0cHQeEBcLMkMLGzM98kTvMJvc5o,224
+p4n4_lib/validate.py,sha256=FMwVIXYXydubaO4ogx1rzXZtZqJ1r0aoVsN7KdrHEfQ,4083
+p4n4_lib-0.2.0.dist-info/METADATA,sha256=0E_vbdUf95YoWw5mOqR4KWRuCALeGR2DbIcjOwpuElg,2574
+p4n4_lib-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+p4n4_lib-0.2.0.dist-info/licenses/LICENSE,sha256=80M4HKFVcFt1FZ-LCbuUyD2RyaFG4sk0iCdIt7KD0BE,1063
+p4n4_lib-0.2.0.dist-info/RECORD,,

p4n4_lib-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

p4n4_lib-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raisga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.