ignition-stack 0.1.0__py3-none-any.whl

ignition_stack/config/schema.py

@@ -0,0 +1,311 @@
+"""Pydantic schema for resolved project configuration.
+
+Phase 4 generalizes the Phase 2 single-gateway shape into a multi-gateway
+model with per-gateway overrides and an opt-in network split. The defaults
+are tuned so a bare ``ProjectConfig(name="demo")`` still resolves to exactly
+the Phase 2 walking skeleton (one standalone gateway + Postgres on a single
+bridge network).
+
+Phases 5-6 extend this with the service catalog and profile-class shaping.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+# Lowercase letters, digits, hyphen, underscore. Must start with a letter
+# because container_name / hostname need to be DNS-safe and Postgres
+# database names follow the same shape.
+_NAME_RE = re.compile(r"^[a-z][a-z0-9_-]*$")
+
+# Supported database kinds and their default images + .env image keys. The
+# default image is filled in when DatabaseConfig.image is left blank so a bare
+# DatabaseConfig(kind="mysql") resolves to a runnable image. Postgres stays
+# pinned to 18.1 to match the Phase-2 walking-skeleton golden; the others track
+# the current major tag (a demo tool, not a production pin).
+_DB_DEFAULT_IMAGE = {
+    "postgres": "postgres:18.1",
+    "mysql": "mysql:9",
+    "mariadb": "mariadb:11",
+    "mongo": "mongo:7",
+}
+_DB_IMAGE_ENV = {
+    "postgres": "POSTGRES_IMAGE",
+    "mysql": "MYSQL_IMAGE",
+    "mariadb": "MARIADB_IMAGE",
+    "mongo": "MONGO_IMAGE",
+}
+
+
+class GatewayConfig(BaseModel):
+    """A single Ignition gateway in the stack.
+
+    ``name`` doubles as the compose service key for this gateway, the
+    directory name under ``services/`` that holds its file-config
+    resources, and the prefix for its per-gateway env vars in the
+    generated ``.env``. The Phase-2 default ``name="gateway"`` keeps the
+    walking skeleton's existing layout intact.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(default="gateway")
+    role: str | None = Field(
+        default=None,
+        description=(
+            "Optional role tag used by the network-split logic and profile "
+            "classes (e.g. 'frontend', 'backend', 'hub', 'spoke'). When "
+            "network_split is on the role decides which network the "
+            "gateway joins."
+        ),
+    )
+    ignition_edition: str = Field(
+        default="standard",
+        description="Value of the IGNITION_EDITION env var: 'standard' or 'edge'.",
+    )
+    memory_mb: int = Field(default=2048, ge=256)
+    http_port: int = Field(default=9088, ge=1, le=65535)
+    modules: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Module catalog entry names (slugs) to attach to this gateway. "
+            "The compose engine wires each cached .modl into the gateway "
+            "volume AND enumerates it in ACCEPT_MODULE_LICENSES + "
+            "ACCEPT_MODULE_CERTS per the resolved q-module-install finding "
+            "(GATEWAY_MODULES_ENABLED is omitted - it quarantines built-ins)."
+        ),
+    )
+
+    @field_validator("name")
+    @classmethod
+    def _validate_name(cls, v: str) -> str:
+        if not _NAME_RE.match(v):
+            raise ValueError(
+                "gateway name must start with a lowercase letter and contain only "
+                "lowercase letters, digits, hyphens, or underscores"
+            )
+        return v
+
+    @field_validator("ignition_edition")
+    @classmethod
+    def _validate_edition(cls, v: str) -> str:
+        if v not in {"standard", "edge"}:
+            raise ValueError("ignition_edition must be 'standard' or 'edge'")
+        return v
+
+    @property
+    def env_prefix(self) -> str:
+        """Uppercase prefix for this gateway's per-gateway env-var keys.
+
+        Used by the compose engine when there are 2+ gateways to scope each
+        gateway's HTTP port and other per-instance settings in ``.env``.
+        For the single-gateway Phase-2 default (name == "gateway") the
+        prefix collapses to just "GATEWAY" so the walking skeleton's .env
+        keys stay unchanged.
+        """
+        if self.name == "gateway":
+            return "GATEWAY"
+        scrubbed = self.name.upper().replace("-", "_")
+        if scrubbed.startswith("GATEWAY_"):
+            return scrubbed
+        return f"GATEWAY_{scrubbed}"
+
+
+class DatabaseConfig(BaseModel):
+    """A single database service.
+
+    Phase 5 widens ``kind`` to the four catalog databases. ``image`` is filled
+    from the kind's default when left blank so the resolver can auto-add a
+    database (DatabaseConfig(kind="postgres")) without knowing the tag.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(default="db")
+    kind: str = Field(default="postgres")
+    image: str = Field(default="", description="image:tag; filled from the kind default if blank.")
+    user: str = Field(default="ignition")
+    password: str = Field(default="ignition")
+    extra_databases: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Additional logical databases to create on first init beyond the "
+            "default one named after the user. The resolver appends 'keycloak' "
+            "here when Keycloak is selected against this database."
+        ),
+    )
+
+    @field_validator("kind")
+    @classmethod
+    def _validate_kind(cls, v: str) -> str:
+        if v not in _DB_DEFAULT_IMAGE:
+            supported = ", ".join(sorted(_DB_DEFAULT_IMAGE))
+            raise ValueError(f"unsupported database kind '{v}'; supported: {supported}")
+        return v
+
+    @model_validator(mode="after")
+    def _fill_default_image(self) -> DatabaseConfig:
+        if not self.image:
+            self.image = _DB_DEFAULT_IMAGE[self.kind]
+        return self
+
+    @property
+    def image_env(self) -> str:
+        """The ``.env`` key the database fragment reads for its image."""
+        return _DB_IMAGE_ENV[self.kind]
+
+
+class ReverseProxyConfig(BaseModel):
+    """Optional reverse-proxy scaffolding.
+
+    Default behavior (``ProjectConfig.reverse_proxy is None``) emits a plain
+    host-port mapping on each gateway and assumes the user already runs Traefik,
+    nginx, or another proxy somewhere - or doesn't need one at all. Setting
+    this to a :class:`ReverseProxyConfig` lays down the ``ia-eknorr/traefik-
+    reverse-proxy`` README at ``path`` and adds a POST-SETUP entry pointing at
+    that repo. The CLI never silently bundles a proxy.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: Literal["traefik"] = Field(
+        default="traefik",
+        description="Reverse-proxy flavor. Only Traefik is supported today.",
+    )
+    path: str = Field(
+        default="reverse-proxy",
+        description=(
+            "Relative directory under the project root that holds the proxy "
+            "README + install instructions (e.g. 'reverse-proxy', "
+            "'infra/proxy'). Must be a non-empty relative POSIX path."
+        ),
+    )
+
+    @field_validator("path")
+    @classmethod
+    def _validate_path(cls, v: str) -> str:
+        stripped = v.strip()
+        if not stripped:
+            raise ValueError("reverse-proxy path must not be empty")
+        if stripped.startswith("/") or "\\" in stripped:
+            raise ValueError(
+                "reverse-proxy path must be a relative POSIX path "
+                "(no leading '/' and no backslashes)"
+            )
+        # Normalize "./foo" -> "foo" so the writer can join cleanly.
+        return stripped.removeprefix("./")
+
+
+class ProjectConfig(BaseModel):
+    """Resolved configuration for a single generated project."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(description="Project name; used for compose project and gateway naming.")
+    ignition_image: str = Field(default="inductiveautomation/ignition:8.3.6")
+    timezone: str = Field(default="UTC")
+    admin_username: str = Field(default="admin")
+    admin_password: str = Field(default="password")
+
+    gateways: list[GatewayConfig] = Field(
+        default_factory=lambda: [GatewayConfig()],
+        min_length=1,
+        description="One or more Ignition gateways. Default is a single standard gateway.",
+    )
+    database: DatabaseConfig | None = Field(
+        default_factory=DatabaseConfig,
+        description="Database service. Set to None for a gateway-only stack.",
+    )
+    services: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Non-database catalog services to include (e.g. 'keycloak', "
+            "'hivemq', 'opcua-sim'). Slugs are validated against the service "
+            "catalog by the resolver, which also auto-adds implicit "
+            "dependencies (Keycloak -> a SQL database)."
+        ),
+    )
+    network_split: bool = Field(
+        default=False,
+        description=(
+            "When False (default), all services share a single bridge network. "
+            "When True, Ignition + reverse-proxy services land on 'frontend' and "
+            "DB + broker services land on 'backend' (per 02-design.md)."
+        ),
+    )
+    reverse_proxy: ReverseProxyConfig | None = Field(
+        default=None,
+        description=(
+            "Reverse-proxy scaffolding. None (default) emits plain host-port "
+            "mappings. Set when the user accepts the wizard's offer to install "
+            "ia-eknorr/traefik-reverse-proxy at a chosen path."
+        ),
+    )
+    mcp_dropin: bool = Field(
+        default=False,
+        description=(
+            "True when the project should scaffold modules/dropin/ for the "
+            "EA-gated MCP module. Set by the mcp-n8n profile."
+        ),
+    )
+    profile: str | None = Field(
+        default=None,
+        description=(
+            "Slug of the architecture profile that produced this config "
+            "('standalone', 'scaleout', 'hub-and-spoke', 'mcp-n8n'). "
+            "Informational - the compose engine reads from the resolved "
+            "fields, not this slug - but lets generated files (header "
+            "comment, lifecycle records) name the profile they came from."
+        ),
+    )
+
+    # Phase 2 compatibility shims: these fields used to live on ProjectConfig
+    # itself. Resolving them through gateways[0] / database keeps the CLI's
+    # existing single-gateway output identical to Phase 2.
+    @property
+    def gateway_http_port(self) -> int:
+        return self.gateways[0].http_port
+
+    @property
+    def db_user(self) -> str:
+        return self.database.user if self.database else ""
+
+    @property
+    def db_password(self) -> str:
+        return self.database.password if self.database else ""
+
+    @property
+    def postgres_image(self) -> str:
+        return self.database.image if self.database else ""
+
+    @property
+    def is_multi_gateway(self) -> bool:
+        return len(self.gateways) > 1
+
+    @field_validator("name")
+    @classmethod
+    def _validate_name(cls, v: str) -> str:
+        if not _NAME_RE.match(v):
+            raise ValueError(
+                "name must start with a lowercase letter and contain only "
+                "lowercase letters, digits, hyphens, or underscores"
+            )
+        return v
+
+    @model_validator(mode="after")
+    def _unique_gateway_names(self) -> ProjectConfig:
+        names = [g.name for g in self.gateways]
+        if len(set(names)) != len(names):
+            dupes = sorted({n for n in names if names.count(n) > 1})
+            raise ValueError(f"gateway names must be unique; duplicates: {dupes}")
+        return self
+
+    @model_validator(mode="after")
+    def _unique_services(self) -> ProjectConfig:
+        if len(set(self.services)) != len(self.services):
+            dupes = sorted({s for s in self.services if self.services.count(s) > 1})
+            raise ValueError(f"services must be unique; duplicates: {dupes}")
+        return self

ignition_stack/lifecycle/__init__.py

@@ -0,0 +1,31 @@
+"""Lifecycle primitives: SE-demo record, scoped cleanup, in-place regeneration.
+
+Only the light modules (``record``, ``cleanup``) are re-exported here; both
+depend on the config schema alone. ``regenerate`` pulls in the compose writer,
+so import it from its submodule to keep this package free of an import cycle
+(the writer imports :mod:`ignition_stack.lifecycle.record`).
+"""
+
+from ignition_stack.lifecycle.cleanup import CleanupError, project_name, wipe_command
+from ignition_stack.lifecycle.record import (
+    LIFECYCLE_DIR,
+    RECORD_NAME,
+    LifecycleError,
+    has_record,
+    read_record,
+    record_path,
+    write_record,
+)
+
+__all__ = [
+    "LIFECYCLE_DIR",
+    "RECORD_NAME",
+    "CleanupError",
+    "LifecycleError",
+    "has_record",
+    "project_name",
+    "read_record",
+    "record_path",
+    "wipe_command",
+    "write_record",
+]

ignition_stack/lifecycle/cleanup.py

@@ -0,0 +1,71 @@
+"""Scoped cleanup: build the one ``docker compose`` command that removes a
+project's resources and nothing else.
+
+Docker Compose labels every container, network, and named volume it creates
+with ``com.docker.compose.project=<project>``. ``down -v`` only touches
+resources carrying the project's label, so naming the project explicitly
+(``-p <name>``) is what makes ``wipe`` provably scoped: unrelated containers
+and volumes on the same host are never matched.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ignition_stack.lifecycle.record import LIFECYCLE_DIR, has_record, read_record
+
+_ENV_PROJECT_KEY = "COMPOSE_PROJECT_NAME"
+
+
+class CleanupError(Exception):
+    """Raised when the project name to scope the wipe to can't be determined."""
+
+
+def wipe_command(project_name: str) -> list[str]:
+    """The scoped teardown for ``project_name``.
+
+    ``-p`` pins the compose project so ``down -v`` removes only that project's
+    containers, networks, and named volumes; ``--remove-orphans`` clears any of
+    its containers no longer in the compose file. Nothing global (no
+    ``system prune``, no unfiltered ``volume rm``) is ever issued.
+    """
+    return [
+        "docker",
+        "compose",
+        "-p",
+        project_name,
+        "down",
+        "-v",
+        "--remove-orphans",
+    ]
+
+
+def project_name(project_dir: Path) -> str:
+    """Resolve the compose project name for a generated project.
+
+    Prefers the SE-demo record (authoritative), then ``COMPOSE_PROJECT_NAME``
+    from the generated ``.env`` so one-shot projects can still be wiped.
+    """
+    project_dir = Path(project_dir)
+    if has_record(project_dir):
+        return read_record(project_dir).name
+
+    name = _project_name_from_env(project_dir / ".env")
+    if name is not None:
+        return name
+
+    raise CleanupError(
+        f"could not determine the compose project name in {project_dir}: no "
+        f"{LIFECYCLE_DIR} record and no {_ENV_PROJECT_KEY} in .env. Run from a "
+        "generated project directory."
+    )
+
+
+def _project_name_from_env(env_file: Path) -> str | None:
+    if not env_file.is_file():
+        return None
+    for line in env_file.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if stripped.startswith(f"{_ENV_PROJECT_KEY}="):
+            return stripped.split("=", 1)[1].strip() or None
+    return None

ignition_stack/lifecycle/record.py

@@ -0,0 +1,67 @@
+"""SE-demo lifecycle record.
+
+In SE-demo mode (``init --keep-cli``) the generated project keeps a copy of
+its resolved :class:`~ignition_stack.config.schema.ProjectConfig` under
+``.ignition-stack/config.json``. That record is the one primitive ``reset``
+and ``switch-profile`` need: they read it back, optionally reshape it, and
+re-run generation - no second trip through the wizard.
+
+One-shot projects (the default) never write this directory, which is how
+``reset`` tells the two modes apart: no record means the project deliberately
+self-deleted its primitives and cannot be regenerated in place.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ignition_stack.config.schema import ProjectConfig
+
+# The directory the SE-demo primitives live in, at the project root. Dot-prefixed
+# so it stays out of the way of the hand-readable compose/.env/Makefile tree.
+LIFECYCLE_DIR = ".ignition-stack"
+RECORD_NAME = "config.json"
+
+
+class LifecycleError(Exception):
+    """Raised when a lifecycle operation can't find or read its record."""
+
+
+def record_path(project_dir: Path) -> Path:
+    """Where the recorded config lives for a project rooted at ``project_dir``."""
+    return Path(project_dir) / LIFECYCLE_DIR / RECORD_NAME
+
+
+def has_record(project_dir: Path) -> bool:
+    """True when ``project_dir`` is an SE-demo project (carries a record)."""
+    return record_path(project_dir).is_file()
+
+
+def write_record(config: ProjectConfig, project_dir: Path) -> Path:
+    """Persist ``config`` as the project's recorded config. Returns its path.
+
+    The JSON is what ``reset`` reads back, so it is the *resolved* config (the
+    caller passes the same object it handed to the writer); pydantic's
+    round-trip via :meth:`ProjectConfig.model_validate_json` reproduces it
+    exactly.
+    """
+    dst = record_path(project_dir)
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    dst.write_bytes((config.model_dump_json(indent=2) + "\n").encode("utf-8"))
+    return dst
+
+
+def read_record(project_dir: Path) -> ProjectConfig:
+    """Load the recorded config for an SE-demo project.
+
+    Raises :class:`LifecycleError` when the project has no record (a one-shot
+    project, or a directory that was never generated by this CLI).
+    """
+    src = record_path(project_dir)
+    if not src.is_file():
+        raise LifecycleError(
+            f"no lifecycle record at {src}. This looks like a one-shot project "
+            "(generated without --keep-cli); reset/switch-profile need an "
+            "SE-demo project."
+        )
+    return ProjectConfig.model_validate_json(src.read_text(encoding="utf-8"))

ignition_stack/lifecycle/regenerate.py

@@ -0,0 +1,62 @@
+"""Regenerate an SE-demo project in place.
+
+``reset`` and ``switch-profile`` both clear the previously-generated tree and
+re-run the writer. The lifecycle record (``.ignition-stack/``) and the modules
+cache are preserved across the rewrite: the record because it is the input to
+the regeneration, the cache because re-downloading pinned ``.modl`` files on
+every reset would be wasteful and offline-hostile.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from ignition_stack.compose import write_project
+from ignition_stack.config.schema import ProjectConfig
+from ignition_stack.lifecycle.record import LIFECYCLE_DIR
+
+# Generated subtrees kept across a regenerate. Everything else under the project
+# root is removed before the writer re-runs.
+_PRESERVE = frozenset({LIFECYCLE_DIR})
+_PRESERVE_NESTED = (("modules", "cache"),)
+
+
+def regenerate(project_dir: Path, config: ProjectConfig) -> list[Path]:
+    """Clear the generated tree (keeping primitives) and re-run the writer."""
+    project_dir = Path(project_dir).resolve()
+    _clear_generated(project_dir)
+    return write_project(config, project_dir, keep_cli=True, overwrite=True)
+
+
+def _clear_generated(project_dir: Path) -> None:
+    preserved_cache = _stash_cache(project_dir)
+    for entry in project_dir.iterdir():
+        if entry.name in _PRESERVE:
+            continue
+        if entry.is_dir():
+            shutil.rmtree(entry)
+        else:
+            entry.unlink()
+    _restore_cache(project_dir, preserved_cache)
+
+
+def _stash_cache(project_dir: Path) -> Path | None:
+    """Move modules/cache aside so it survives the rmtree, returning its temp path."""
+    cache = project_dir / Path(*_PRESERVE_NESTED[0])
+    if not cache.is_dir():
+        return None
+    stash = project_dir / LIFECYCLE_DIR / "_cache-stash"
+    if stash.exists():
+        shutil.rmtree(stash)
+    stash.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(cache), str(stash))
+    return stash
+
+
+def _restore_cache(project_dir: Path, stash: Path | None) -> None:
+    if stash is None:
+        return
+    dst = project_dir / Path(*_PRESERVE_NESTED[0])
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(stash), str(dst))

ignition_stack/modules.yaml

@@ -0,0 +1,83 @@
+# Catalog of third-party Ignition modules and JDBC drivers the CLI knows how
+# to download, sha-verify, cache, and wire into a generated stack.
+#
+# This is the single source of truth a maintainer bumps per Ignition release.
+# Schema: ignition_stack/catalog/schema.py (pydantic-validated at load).
+#
+# Pinning a new entry:
+#   1. Set ignition_versions to the exact 8.3.x versions you have verified.
+#   2. Download the artifact and compute sha256: `shasum -a 256 <file>`.
+#      Until pinned, set sha256 to 'UNPINNED'; `modules validate` rejects
+#      this so a half-bumped catalog cannot ship to users.
+#   3. For modules, set module_identifier to the FQID found in module.xml
+#      inside the .modl zip (NOT the install path).
+#   4. install_path is the absolute path inside the gateway container.
+#      Modules go under user-lib/modules/, drivers under user-lib/jdbc/.
+#
+# Phase-1 finding (see scripts/seeding-poc/experiments/module-install/):
+#   GATEWAY_MODULES_ENABLED, ACCEPT_MODULE_LICENSES, and ACCEPT_MODULE_CERTS
+#   take comma-delimited fully-qualified module IDENTIFIERS, not paths.
+#   The path is only used for the volume-mount / bootstrap copy.
+
+version: 1
+
+entries:
+  - name: mqtt-engine
+    kind: module
+    vendor: cirrus-link
+    ignition_versions: ["8.3.6"]
+    module_identifier: com.cirruslink.mqtt.engine.gateway
+    download_url: https://inductiveautomation.com/downloads/third-party-modules/8.3.6/MQTT-Engine-signed.modl
+    sha256: UNPINNED
+    install_path: /usr/local/bin/ignition/user-lib/modules/MQTT-Engine.modl
+    requires_license_env: null
+    requires_manual_download: false
+
+  - name: mqtt-transmission
+    kind: module
+    vendor: cirrus-link
+    ignition_versions: ["8.3.6"]
+    module_identifier: com.cirruslink.mqtt.transmission.gateway
+    download_url: https://inductiveautomation.com/downloads/third-party-modules/8.3.6/MQTT-Transmission-signed.modl
+    sha256: UNPINNED
+    install_path: /usr/local/bin/ignition/user-lib/modules/MQTT-Transmission.modl
+    requires_license_env: null
+    requires_manual_download: false
+
+  - name: mqtt-distributor
+    kind: module
+    vendor: cirrus-link
+    ignition_versions: ["8.3.6"]
+    module_identifier: com.cirruslink.mqtt.distributor.gateway
+    download_url: https://inductiveautomation.com/downloads/third-party-modules/8.3.6/MQTT-Distributor-signed.modl
+    sha256: UNPINNED
+    install_path: /usr/local/bin/ignition/user-lib/modules/MQTT-Distributor.modl
+    requires_license_env: null
+    requires_manual_download: false
+
+  - name: mysql-jdbc
+    kind: jdbc_driver
+    vendor: oracle
+    ignition_versions: ["8.3.6"]
+    download_url: https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/9.1.0/mysql-connector-j-9.1.0.jar
+    sha256: UNPINNED
+    install_path: /usr/local/bin/ignition/user-lib/jdbc/mysql-connector-j-9.1.0.jar
+    requires_license_env: null
+    requires_manual_download: false
+
+  # MCP module is Early Access (survey-gated); no public download URL exists.
+  # See q-mcp-delivery in 02-design.md: catalog flag + optional maintainer
+  # local_source_path. Until GA, `modules download` skips this entry (or
+  # copies from local_source_path if the maintainer has configured one and
+  # the file exists on disk).
+  - name: mcp-module
+    kind: module
+    vendor: inductive-automation
+    ignition_versions: ["8.3.6"]
+    module_identifier: com.inductiveautomation.mcp.gateway
+    download_url: null
+    sha256: UNPINNED
+    install_path: /usr/local/bin/ignition/user-lib/modules/MCP.modl
+    requires_license_env: null
+    requires_manual_download: true
+    local_source_path: null

ignition_stack/postsetup/__init__.py

@@ -0,0 +1,3 @@
+from ignition_stack.postsetup.generator import generate_post_setup
+
+__all__ = ["generate_post_setup"]