p4n4-lib 0.2.0__tar.gz

p4n4_lib-0.2.0/.gitattributes

@@ -0,0 +1,21 @@
+# Normalize line endings to LF in the repository and working tree.
+* text=auto eol=lf
+
+# Binary files: no line-ending conversion or text diffs.
+*.png  binary
+*.jpg  binary
+*.jpeg binary
+*.gif  binary
+*.ico  binary
+*.webp binary
+*.mp4  binary
+*.webm binary
+*.pdf  binary
+*.woff binary
+*.woff2 binary
+*.ttf  binary
+*.otf  binary
+*.zip  binary
+*.gz   binary
+*.onnx binary
+*.eim  binary

p4n4_lib-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov=p4n4_lib --cov-report=term-missing

p4n4_lib-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

p4n4_lib-0.2.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Ruff / linters
+.ruff_cache/
+
+# Distribution / packaging
+*.whl
+*.tar.gz
+MANIFEST
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# Editor / OS
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo

p4n4_lib-0.2.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to `p4n4-lib` are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-03
+
+First release on PyPI. There is no 0.1.0: the package was versioned 0.1.0 while it lived
+only on GitHub, and the first published version is 0.2.0, released together with
+`p4n4` (CLI) 0.2.0.
+
+### Added
+
+- Shared library extracted from `p4n4-cli`, used by `p4n4-cli` and `p4n4-api`:
+  - `manifest`: find (walk-up), load, save and create `.p4n4.json`
+  - `env`: dotenv read/write that keeps the `.env.example` template's comments and layout
+  - `layers`: layer registry (repo URLs, copy paths, required files and env keys)
+  - `layout`: flat single-layer projects, per-layer subdirectories for multi-layer projects
+  - `scaffold`: fetch stack sources (local path or shallow clone) and copy them into a project
+  - `validate`: pure project checks returning `(passed, errors)`
+  - `secrets`: token generation and the rotatable-key policy
+  - `compose`: Docker Compose wrappers (`up`, `down`, `ps`, `logs`)
+- `edge` layer: compose file, runner, model directories and `.env`.
+- `dashboard` layer (p4n4-dashboard web service), and checks for the optional `.p4n4.json`
+  `dashboard` block (`grafana_path`, `tabs`, `theme`, and a `brand.json` in a named theme).
+- Template projects (a `template` block in `.p4n4.json`) are validated against the
+  template's own `.env.example` instead of the base stack's file list.
+- `layout.compose_project_name()`: a Compose project name per layer (`<project>` or
+  `<project>-<layer>`, sanitized), and `scaffold_layer(..., compose_project_name=...)`, which writes
+  it to the layer's `.env` as `COMPOSE_PROJECT_NAME`. Without it, every multi-layer project on a
+  host shared the `iot`, `ai`, … Compose projects and so their volumes.
+- `env.set_value()`: set one key in an existing `.env` (replace, or append with a comment).
+- `MQTT_REMOTE_PASSWORD` is an external secret: shown fully masked, never rotated.
+- The IoT layer requires `NODE_RED_USER` and `NODE_RED_PASSWORD`; `NODE_RED_PASSWORD` is
+  rotatable. Node-RED flows are copied from `config/node-red/flows/`.
+
+### Changed
+
+- `compose` falls back to the standalone `docker-compose` (v1) when the Docker Compose v2
+  plugin is missing.
+- `compose.down` enables every profile (`--profile "*"`), so services started by name, or
+  dropped from `COMPOSE_PROFILES` since, are stopped too. Not available on v1.
+
+### Fixed
+
+- `.env` values containing `$`, `#`, spaces or quotes are quoted, so Docker Compose reads
+  them literally.
+- Windows: stacks are cloned with `core.autocrlf=false`, so scaffolded shell scripts keep LF
+  line endings and run inside the Linux containers. `.env` and `.p4n4.json` are read and
+  written as UTF-8 with LF line endings instead of the platform defaults.
+
+[Unreleased]: https://github.com/raisga/p4n4-lib/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/raisga/p4n4-lib/releases/tag/v0.2.0

p4n4_lib-0.2.0/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.

p4n4_lib-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,43 @@
+# 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/p4n4_lib/__init__.py

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

p4n4_lib-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-0.2.0/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",
+        )