ignition-stack 0.3.0__tar.gz → 0.4.0__tar.gz

{ignition_stack-0.3.0 → ignition_stack-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ignition-stack
-Version: 0.3.0
+Version: 0.4.0
 Summary: CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements
 Author-email: Eric Knorr <etknorr@gmail.com>
 License: MIT

ignition_stack-0.4.0/ignition_stack/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{ignition_stack-0.3.0 → ignition_stack-0.4.0}/ignition_stack/cli.py

@@ -56,6 +56,11 @@ from ignition_stack.profiles import (
     list_profiles,
 )
 from ignition_stack.services.resolver import resolve
+from ignition_stack.update_check import (
+    check_for_update,
+    detect_upgrade_command,
+    should_notify,
+)
 from ignition_stack.wizard import run_wizard
 
 app = typer.Typer(
@@ -89,6 +94,27 @@ def _root(
     if ctx.invoked_subcommand is None:
         console.print(ctx.get_help())
         raise typer.Exit()
+    _notify_update_available()
+
+
+def _notify_update_available() -> None:
+    """Print a one-line advisory when a newer release is on PyPI.
+
+    Runs only for real subcommands (not --version or bare help) and only on an
+    interactive terminal. Best-effort: any failure inside the check is swallowed
+    rather than allowed to disrupt the command the user actually ran.
+    """
+    if not should_notify():
+        return
+    result = check_for_update()
+    if result is None:
+        return
+    current, latest = result
+    console.print(
+        f"[dim]update available[/dim] [yellow]{current}[/yellow] -> "
+        f"[green]{latest}[/green] · run: [cyan]{detect_upgrade_command()}[/cyan]",
+        highlight=False,
+    )
 
 
 def _profile_help() -> str:

{ignition_stack-0.3.0 → ignition_stack-0.4.0}/ignition_stack/compose/engine.py

@@ -132,10 +132,7 @@ def _render_database(config: ProjectConfig) -> str:
     """
     db = config.database
     assert db is not None
-    if config.is_multi_gateway:
-        container_name_ref = f"{db.name}-${{COMPOSE_PROJECT_NAME}}"
-    else:
-        container_name_ref = f"{db.name}-${{GATEWAY_NAME}}"
+    container_name_ref = f"{db.name}-${{COMPOSE_PROJECT_NAME}}" if config.is_multi_gateway else f"{db.name}-${{GATEWAY_NAME}}"
     tpl = _service_jinja_env().get_template(f"{db.kind}/compose.yaml.j2")
     return tpl.render(
         name=db.name,
@@ -187,9 +184,7 @@ def _service_dependencies(manifest: object, config: ProjectConfig) -> list[str]:
     return deps
 
 
-def _gateway_context(
-    gw: GatewayConfig, config: ProjectConfig, catalog: Catalog | None
-) -> dict[str, object]:
+def _gateway_context(gw: GatewayConfig, config: ProjectConfig, catalog: Catalog | None) -> dict[str, object]:
     """Build the per-gateway context dict shared by the bootstrap + gateway fragments."""
     multi = config.is_multi_gateway
 
@@ -216,10 +211,7 @@ def _gateway_context(
         # (DB/broker access). Gateways with no role tag default to
         # frontend membership; explicit role=backend lands a gateway on
         # only the backend (rare; used for backend-only edge cases).
-        if gw.role == "backend":
-            networks = [NETWORK_BACKEND]
-        else:
-            networks = [NETWORK_FRONTEND, NETWORK_BACKEND]
+        networks = [NETWORK_BACKEND] if gw.role == "backend" else [NETWORK_FRONTEND, NETWORK_BACKEND]
 
     module_identifiers = _module_identifiers_for(gw, catalog)
     cached_modules = bool(gw.modules)
@@ -254,24 +246,40 @@ def _bootstrap_context(ctx: dict[str, object]) -> dict[str, object]:
     }
 
 
-def _ignition_context(
-    ctx: dict[str, object], config: ProjectConfig, multi: bool
-) -> dict[str, object]:
+def _ignition_context(ctx: dict[str, object], config: ProjectConfig, multi: bool) -> dict[str, object]:
     gw: GatewayConfig = ctx["gw"]  # type: ignore[assignment]
     # IGNITION_EDITION lives in the anchor as "standard", so only emit an
     # override when this gateway differs - keeps Phase 2's environment
     # block as the bare anchor reference.
     edition_override = gw.ignition_edition if gw.ignition_edition != "standard" else None
 
-    # Redundancy wiring (Phase 4, per the verified Phase-3 spike):
-    #  - Any node in a pair opens its incoming Gateway Network policy
-    #    (Unrestricted + no-SSL) so the plain redundancy link auto-approves.
-    #  - The backup additionally points a generic outgoing GAN connection at
-    #    the master (HOST/PORT/ENABLESSL - all three, not just HOST, or it
-    #    defaults to SSL:8060 and faults) and must NOT be renamed via -n: it
-    #    adopts the master's system name on first sync.
+    # Gateway Network wiring (Phase 4, per the verified Phase-3 spike, which the
+    # spike itself notes mirrors the publicdemo-all dev stack: 8088 / no-SSL /
+    # Unrestricted). Two kinds of GAN link ride this same plain, auto-approving
+    # path:
+    #  - Redundancy: the backup points an outgoing connection at its master and
+    #    must NOT be renamed via -n (it adopts the master's system name on sync).
+    #  - Multi-gateway profiles: each gateway names its peers in gan_outgoing
+    #    (scaleout frontend -> backend, hub-and-spoke spoke -> hub).
+    # Every GAN participant carries the full open incoming block. Mirroring the
+    # spike's BOTH-ends shape keeps requireSSL=false on the *initiator* too -
+    # the spike flagged that as the load-bearing setting for a plain link, so we
+    # don't shrink it to receiver-only.
     is_redundant = gw.redundancy is not None
     is_backup = is_redundant and gw.redundancy.mode == "backup"
+
+    # HOST/PORT/ENABLESSL trio per outgoing connection (all plain, SSL off).
+    gan_outgoing: list[dict[str, object]] = []
+    if is_backup:
+        gan_outgoing.append({"host": gw.redundancy.peer, "port": gw.redundancy.gan_port})
+    gan_outgoing.extend({"host": peer, "port": 8088} for peer in gw.gan_outgoing)
+
+    # A gateway opens the Unrestricted incoming policy when it takes part in the
+    # GAN at all: it is a redundancy node, it initiates a connection, or some
+    # other gateway opens one to it (hub/backend as a link target).
+    gan_targets = {peer for other in config.gateways for peer in other.gan_outgoing}
+    gan_incoming = is_redundant or bool(gan_outgoing) or gw.name in gan_targets
+
     return {
         "service_name": ctx["service_name"],
         "bootstrap_service_name": ctx["bootstrap_service_name"],
@@ -288,10 +296,9 @@ def _ignition_context(
         "modules_enabled": _modules_enabled_for(gw, ctx["module_identifiers"]),  # type: ignore[arg-type]
         "database_service": config.database.name if config.database else None,
         "networks": ctx["networks"],
-        "redundant": is_redundant,
         "rename": not is_backup,
-        "gan_peer_host": gw.redundancy.peer if is_backup else None,
-        "gan_port": gw.redundancy.gan_port if is_backup else None,
+        "gan_incoming": gan_incoming,
+        "gan_outgoing": gan_outgoing,
     }
 
 
@@ -300,19 +307,13 @@ def _module_identifiers_for(gw: GatewayConfig, catalog: Catalog | None) -> str:
     if not gw.modules:
         return ""
     if catalog is None:
-        raise ValueError(
-            f"gateway '{gw.name}' lists modules {gw.modules} but no catalog "
-            "was passed to render_compose; load modules.yaml first"
-        )
+        raise ValueError(f"gateway '{gw.name}' lists modules {gw.modules} but no catalog " "was passed to render_compose; load modules.yaml first")
     identifiers: list[str] = []
     for slug in gw.modules:
         try:
             entry = catalog.by_name(slug)
         except KeyError as exc:
-            raise ValueError(
-                f"gateway '{gw.name}' references unknown module '{slug}'; "
-                "check modules.yaml and the gateway config"
-            ) from exc
+            raise ValueError(f"gateway '{gw.name}' references unknown module '{slug}'; " "check modules.yaml and the gateway config") from exc
         # Modules-only env vars: JDBC drivers shouldn't be enumerated here.
         if not _is_module(entry):
             continue
@@ -376,10 +377,7 @@ def _describe(config: ProjectConfig) -> str:
     """Human-readable header comment summarizing the stack."""
     n = len(config.gateways)
     if n == 1 and config.database and config.database.kind == "postgres" and not config.services:
-        return (
-            "Walking skeleton: one Ignition 8.3 gateway, one Postgres, "
-            "env-driven commissioning so first boot needs no UI."
-        )
+        return "Walking skeleton: one Ignition 8.3 gateway, one Postgres, " "env-driven commissioning so first boot needs no UI."
     parts = [f"{n} Ignition 8.3 gateway{'s' if n != 1 else ''}"]
     if config.database:
         parts.append(f"one {config.database.kind}")

{ignition_stack-0.3.0 → ignition_stack-0.4.0}/ignition_stack/compose/templates/services/ignition.yaml.j2

@@ -25,18 +25,18 @@
 {%- if disable_active %}
     GATEWAY_MODULES_ENABLED: "{{ modules_enabled }}"
 {%- endif %}
-{%- if redundant %}
+{%- if gan_incoming %}
     GATEWAY_NETWORK_ENABLED: "true"
     GATEWAY_NETWORK_ALLOWINCOMING: "true"
     GATEWAY_NETWORK_SECURITYPOLICY: "Unrestricted"
     GATEWAY_NETWORK_REQUIRESSL: "false"
     GATEWAY_NETWORK_REQUIRETWOWAYAUTH: "false"
 {%- endif %}
-{%- if gan_peer_host %}
-    GATEWAY_NETWORK_0_HOST: "{{ gan_peer_host }}"
-    GATEWAY_NETWORK_0_PORT: "{{ gan_port }}"
-    GATEWAY_NETWORK_0_ENABLESSL: "false"
-{%- endif %}
+{%- for conn in gan_outgoing %}
+    GATEWAY_NETWORK_{{ loop.index0 }}_HOST: "{{ conn.host }}"
+    GATEWAY_NETWORK_{{ loop.index0 }}_PORT: "{{ conn.port }}"
+    GATEWAY_NETWORK_{{ loop.index0 }}_ENABLESSL: "false"
+{%- endfor %}
   command: >
 {%- if rename %}
     -n {{ gateway_name_ref }}

{ignition_stack-0.3.0 → ignition_stack-0.4.0}/ignition_stack/config/schema.py

@@ -61,24 +61,15 @@ class RedundancyConfig(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    mode: Literal["master", "backup"] = Field(
-        description="This node's redundancy role: 'master' or 'backup'."
-    )
+    mode: Literal["master", "backup"] = Field(description="This node's redundancy role: 'master' or 'backup'.")
     peer: str = Field(
-        description=(
-            "Service name of the other node in the pair. The backup points at "
-            "the master here (and over the Gateway Network); the master points "
-            "at its backup."
-        ),
+        description=("Service name of the other node in the pair. The backup points at " "the master here (and over the Gateway Network); the master points " "at its backup."),
     )
     gan_port: int = Field(
         default=8088,
         ge=1,
         le=65535,
-        description=(
-            "Gateway Network port the redundancy link rides. 8088 is plain "
-            "(non-SSL) and auto-approves; 8060 is SSL and needs a cert approval."
-        ),
+        description=("Gateway Network port the redundancy link rides. 8088 is plain " "(non-SSL) and auto-approves; 8060 is SSL and needs a cert approval."),
     )
     seed_redundancy_xml: bool = Field(
         default=True,
@@ -151,15 +142,26 @@ class GatewayConfig(BaseModel):
             "compose engine wires the backup's Gateway Network link to the master."
         ),
     )
+    gan_outgoing: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Service names of peer gateways this one opens an outgoing Gateway "
+            "Network connection to. Multi-gateway profiles set this to auto-form "
+            "the GAN with no UI approval (scaleout: each frontend -> backend; "
+            "hub-and-spoke: each spoke -> hub). The compose engine renders one "
+            "GATEWAY_NETWORK_<i>_HOST/PORT/ENABLESSL trio per entry on the plain, "
+            "non-SSL port 8088, and opens an Unrestricted incoming policy on every "
+            "GAN participant so the plain link auto-approves - the same proven "
+            "pattern the redundancy link rides. Plain transport is a demo-only "
+            "default; cross-host deployments should switch to SSL + approved certs."
+        ),
+    )
 
     @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"
-            )
+            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")
@@ -277,10 +279,7 @@ class ReverseProxyConfig(BaseModel):
         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)"
-            )
+            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("./")
 
@@ -332,10 +331,7 @@ class ProjectConfig(BaseModel):
     )
     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."
-        ),
+        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,
@@ -375,10 +371,7 @@ class ProjectConfig(BaseModel):
     @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"
-            )
+            raise ValueError("name must start with a lowercase letter and contain only " "lowercase letters, digits, hyphens, or underscores")
         return v
 
     @model_validator(mode="after")
@@ -420,3 +413,29 @@ class ProjectConfig(BaseModel):
                 "redundancy is Edge-to-Edge only, so both nodes must share an edition"
             )
         return self
+
+    @model_validator(mode="after")
+    def _gan_aggregation_target_is_standard(self) -> ProjectConfig:
+        """A Gateway Network aggregation link must terminate on a standard gateway.
+
+        Edge is a leaf edition: gateways aggregate *into* a full (standard)
+        gateway, never into an Edge one. So a ``gan_outgoing`` link may be
+        ``edge -> standard`` or ``standard -> standard``, but it may never target
+        an Edge node - this rejects both ``edge -> edge`` and ``standard -> edge``
+        (the latter is what ``scaleout --edge-role backend`` would produce).
+        Redundancy is unaffected: its Edge-to-Edge pair link rides
+        ``redundancy.peer``, not ``gan_outgoing``, and stays valid.
+        """
+        by_name = {gw.name: gw for gw in self.gateways}
+        for gw in self.gateways:
+            for peer in gw.gan_outgoing:
+                target = by_name.get(peer)
+                if target is None or target.ignition_edition != "edge":
+                    continue
+                raise ValueError(
+                    f"gateway '{gw.name}' opens a Gateway Network link to "
+                    f"'{target.name}', which runs the Edge edition; aggregate into "
+                    "a standard gateway instead (Edge is a leaf edition). "
+                    "Edge-to-Edge is supported only for redundancy pairs."
+                )
+        return self

{ignition_stack-0.3.0 → ignition_stack-0.4.0}/ignition_stack/postsetup/generator.py

@@ -55,19 +55,15 @@ from files. Bring it up with `docker compose up -d` and the gateway is ready.
 # manifest. Kept here (not in a manifest) because they're a property of the
 # resolved topology, not of any one catalog entry.
 _GATEWAY_NETWORK_LINK_REASON = (
-    "The Phase-1 matrix marks the gateway-network-link row partial: each "
-    "gateway's UUID and the outbound peer-link path are file-seeded, but the "
-    "per-link approval happens in the gateway UI, so the frontend<->backend "
-    "link is finished by hand."
-)
-_MCP_MODULE_REASON = (
-    "The Ignition MCP module is Early-Access and gated behind a survey, so the "
-    "CLI cannot bundle it. Request the .modl, drop it in, and re-up the stack."
+    "This stack auto-forms its gateway-network links: each connecting gateway "
+    "opens a plain (non-SSL, port 8088) outgoing connection and every node runs "
+    "an Unrestricted incoming policy, so the links are accepted on sight with no "
+    "UI approval. This step is a verification, not a manual procedure - confirm "
+    "the links came up, and reach for the runbook only if one did not."
 )
+_MCP_MODULE_REASON = "The Ignition MCP module is Early-Access and gated behind a survey, so the " "CLI cannot bundle it. Request the .modl, drop it in, and re-up the stack."
 _REVERSE_PROXY_REASON = (
-    "The CLI never clones a proxy silently. The wizard scaffolded a README that "
-    "walks through installing ia-eknorr/traefik-reverse-proxy in front of the "
-    "stack."
+    "The CLI never clones a proxy silently. The wizard scaffolded a README that " "walks through installing ia-eknorr/traefik-reverse-proxy in front of the " "stack."
 )
 _REDUNDANCY_PAIRING_REASON = (
     "This stack seeds redundancy fully: a pre-seeded redundancy.xml sets each "
@@ -126,7 +122,7 @@ def _collect_steps(config: ProjectConfig) -> list[_Step]:
         for item in manifest.post_setup:
             steps.append(_Step(item.connection, item.reason, slug))
 
-    if config.profile == "scaleout":
+    if any(gw.gan_outgoing for gw in config.gateways):
         steps.append(_Step("gateway-network-link", _GATEWAY_NETWORK_LINK_REASON, ""))
     if any(gw.redundancy is not None for gw in config.gateways):
         steps.append(_Step("redundancy-pairing", _REDUNDANCY_PAIRING_REASON, ""))
@@ -142,9 +138,10 @@ def _context(config: ProjectConfig, step: _Step) -> dict[str, object]:
     """Build the render context one snippet sees.
 
     ``env_vars`` is the (key, value) list the reader copies into the gateway
-    screen: a service step exposes that service's preset ``.env`` keys; the
-    gateway-network-link step exposes ``COMPOSE_PROJECT_NAME`` (the link target
-    is named after the compose project); the rest copy nothing.
+    screen: a service step exposes that service's preset ``.env`` keys. The
+    gateway-network-link step copies nothing - the links auto-form from env, so
+    it carries ``gan_links`` (who connects to whom) for a verification readout
+    instead.
     """
     catalog = load_all_services()
     gateways = [
@@ -157,12 +154,7 @@ def _context(config: ProjectConfig, step: _Step) -> dict[str, object]:
         for gw in config.gateways
     ]
 
-    if step.service:
-        env_vars = sorted(catalog[step.service].env.items())
-    elif step.connection == "gateway-network-link":
-        env_vars = [("COMPOSE_PROJECT_NAME", config.name)]
-    else:
-        env_vars = []
+    env_vars = sorted(catalog[step.service].env.items()) if step.service else []
 
     return {
         "project_name": config.name,
@@ -172,6 +164,7 @@ def _context(config: ProjectConfig, step: _Step) -> dict[str, object]:
         "gateway_url": gateways[0]["url"],
         "gateways": gateways,
         "redundancy_pairs": _redundancy_pairs(config),
+        "gan_links": _gan_links(config),
         "env_vars": env_vars,
         "env_map": dict(env_vars),
         "proxy_path": config.reverse_proxy.path if config.reverse_proxy else "",
@@ -207,6 +200,33 @@ def _redundancy_pairs(config: ProjectConfig) -> list[dict[str, object]]:
     return pairs
 
 
+def _gan_links(config: ProjectConfig) -> list[dict[str, object]]:
+    """Auto-formed Gateway Network links, for the gateway-network-link step.
+
+    One entry per outgoing connection a gateway declares in ``gan_outgoing``
+    (scaleout frontend -> backend, hub-and-spoke spoke -> hub): it names the
+    source and target, their UIs, and the plain port the link rides so the
+    verification readout can point the reader at each end.
+    """
+    by_name = {gw.name: gw for gw in config.gateways}
+    links: list[dict[str, object]] = []
+    for gw in config.gateways:
+        for peer in gw.gan_outgoing:
+            target = by_name.get(peer)
+            links.append(
+                {
+                    "source": gw.name,
+                    "source_role": gw.role or gw.name,
+                    "source_url": f"http://localhost:{gw.http_port}",
+                    "target": peer,
+                    "target_role": (target.role or target.name) if target else peer,
+                    "target_url": f"http://localhost:{target.http_port}" if target else "",
+                    "port": 8088,
+                }
+            )
+    return links
+
+
 def _render_step(env: Environment, ctx: dict[str, object]) -> str:
     connection = ctx["connection"]
     try:

{ignition_stack-0.3.0 → ignition_stack-0.4.0}/ignition_stack/profiles/hub_and_spoke.py

@@ -65,6 +65,9 @@ class HubAndSpokeProfile:
                     role="spoke",
                     ignition_edition="edge" if spokes_run_edge else "standard",
                     http_port=9088 + i,
+                    # Each spoke opens a plain Gateway Network link to the hub so
+                    # the GAN auto-forms with no UI approval; the hub aggregates.
+                    gan_outgoing=["hub"],
                 )
             )
 

{ignition_stack-0.3.0 → ignition_stack-0.4.0}/ignition_stack/profiles/scaleout.py

@@ -10,12 +10,13 @@ joins the frontend AND backend networks so a frontend can reach the DB the
 backend owns. The network split is on by default - that's the whole point
 of the scaleout demo - but ``options.network_split`` can override it.
 
-The plan's validation calls for "two networked gateways (frontend + backend)
-+ a DB; the gateway-network link config is present per the Phase-1 matrix";
-the gateway-network link itself is a follow-up resource set the seeding
-matrix marks ``file-seedable-config: yes``, so it travels with the
-``gateway-resources/`` overlay once that catalog grows. Today the
-``services`` list is empty by default; users add brokers/IDPs on top.
+The gateway-network link auto-forms with no UI approval: each frontend gets
+``gan_outgoing=["backend"]``, which the compose engine renders as a plain
+(non-SSL, port 8088) outgoing Gateway Network connection, and every participant
+runs an ``Unrestricted`` incoming policy so the link is accepted on sight - the
+same proven pattern the redundancy link rides. POST-SETUP carries a *verify*
+step (not a manual procedure). Today the ``services`` list is empty by default;
+users add brokers/IDPs on top.
 """
 
 from __future__ import annotations
@@ -47,6 +48,9 @@ class ScaleoutProfile:
                     role="frontend",
                     ignition_edition="edge" if edge_role == "frontend" else "standard",
                     http_port=9088 + (i - 1),
+                    # Each frontend opens a plain Gateway Network link to the
+                    # backend so the GAN auto-forms with no UI approval.
+                    gan_outgoing=["backend"],
                 )
             )
         gateways.append(

ignition_stack-0.4.0/ignition_stack/templates/post-setup/gateway-network-link.md.j2

@@ -0,0 +1,23 @@
+## Verify the gateway-network link
+
+{{ reason }}
+{% for link in gan_links %}
+- **{{ link.source_role }}** (`{{ link.source }}`): {{ link.source_url }}
+  connects to **{{ link.target_role }}** (`{{ link.target }}`) over the Gateway Network on **port {{ link.port }}** (plain, no SSL).
+{%- endfor %}
+
+Within about a minute of the gateways reaching RUNNING, open any gateway above
+and go to Config -> Networking -> Gateway Network. Each outgoing connection shows
+**Running**, and the receiving gateway lists the peer as **Approved**
+automatically - no UI approval is needed, because every node runs an
+`Unrestricted` policy with SSL disabled and the link rides plain port 8088.
+
+If a link has not formed, confirm the containers are up and re-check after the
+gateways finish starting. The plain-vs-SSL trade-off and the manual port-8060
+certificate-approval steps are documented in `docs/docs/guides/redundancy.md`
+(same Gateway Network mechanics).
+
+> **Security:** this stack uses **plain, non-SSL** gateway-network links with an
+> `Unrestricted` policy. That is safe only on an isolated demo network. For any
+> cross-host or production deployment, switch to SSL on port 8060 with approved
+> certificates.

ignition_stack-0.4.0/ignition_stack/update_check.py

@@ -0,0 +1,129 @@
+"""Passive "a newer release is available" notifier.
+
+Mirrors the pattern used by npm/update-notifier, gh, and pip's own notice: on a
+real command invocation, check PyPI at most once a day (cached), fail silently
+on any error, and never delay or block the command the user actually ran. The
+notice is advisory only - this module never installs anything. Presentation
+(TTY gating, printing) lives in the CLI; this module is the pure decision layer
+so it stays testable without a console.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+import httpx
+
+from ignition_stack import __version__
+
+_PYPI_URL = "https://pypi.org/pypi/ignition-stack/json"
+_CHECK_INTERVAL = 24 * 60 * 60  # seconds between live PyPI checks
+_HTTP_TIMEOUT = 1.5  # short on purpose: the check must never stall a command
+_OPT_OUT_ENV = "IGNITION_STACK_NO_UPDATE_CHECK"
+
+
+def _cache_path() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME")
+    root = Path(base) if base else Path.home() / ".cache"
+    return root / "ignition-stack" / "update-check.json"
+
+
+def _is_newer(latest: str, current: str) -> bool:
+    """True when ``latest`` is a strictly higher release than ``current``.
+
+    Both sides are this project's own clean ``X.Y.Z`` releases, so an int-tuple
+    compare on the dotted parts is exact. Anything that does not parse cleanly
+    returns False, so an unexpected version string can never raise a bogus
+    "update available" notice.
+    """
+    try:
+        latest_parts = tuple(int(p) for p in latest.split("."))
+        current_parts = tuple(int(p) for p in current.split("."))
+    except ValueError:
+        return False
+    return latest_parts > current_parts
+
+
+def _read_cache(path: Path) -> dict | None:
+    try:
+        return json.loads(path.read_text())
+    except (OSError, ValueError):
+        return None
+
+
+def _write_cache(path: Path, latest: str, now: float) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps({"checked_at": now, "latest": latest}))
+    except OSError:
+        pass  # caching is best-effort; never fail the CLI over it
+
+
+def _fetch_latest() -> str | None:
+    try:
+        resp = httpx.get(_PYPI_URL, timeout=_HTTP_TIMEOUT)
+        resp.raise_for_status()
+        return resp.json()["info"]["version"]
+    except Exception:
+        return None  # offline, slow, rate-limited, malformed - all non-fatal
+
+
+def _latest_version(now: float) -> str | None:
+    """Latest version from cache when fresh, otherwise refresh from PyPI.
+
+    The freshness window bounds live network calls to once per ``_CHECK_INTERVAL``,
+    so the common path is a local file read with no request at all.
+    """
+    path = _cache_path()
+    cached = _read_cache(path)
+    if cached and now - cached.get("checked_at", 0) < _CHECK_INTERVAL:
+        return cached.get("latest")
+    latest = _fetch_latest()
+    if latest is not None:
+        _write_cache(path, latest, now)
+    return latest
+
+
+def detect_upgrade_command() -> str:
+    """Return the exact command the user should run to upgrade.
+
+    ``sys.prefix`` is the environment the running CLI lives in; both managed
+    installers leave an unambiguous marker in that path. Match only those two
+    and fall back to plain pip for everything else (a venv, ``--user`` site, a
+    system Python) - suggesting ``pipx upgrade`` to someone on plain pip just
+    errors for them, so when there is no clear marker the generic command is
+    the safe choice rather than a guess.
+    """
+    if f"pipx{os.sep}venvs" in sys.prefix:
+        return "pipx upgrade ignition-stack"
+    if f"uv{os.sep}tools" in sys.prefix:
+        return "uv tool upgrade ignition-stack"
+    return "pip install --upgrade ignition-stack"
+
+
+def check_for_update(*, now: float | None = None) -> tuple[str, str] | None:
+    """Return ``(current, latest)`` when a newer release exists, else ``None``.
+
+    Applies the opt-out gate and the once-a-day cache policy, then compares.
+    Presentation (and the TTY gate) is the caller's job.
+    """
+    if os.environ.get(_OPT_OUT_ENV):
+        return None
+    now = time.time() if now is None else now
+    latest = _latest_version(now)
+    if latest and _is_newer(latest, __version__):
+        return (__version__, latest)
+    return None
+
+
+def should_notify() -> bool:
+    """Whether a notice may be shown at all, independent of version state.
+
+    Suppressed when stdout is not a TTY (CI, pipes, shell completion), so the
+    notice never contaminates scripted output or non-interactive runs.
+    """
+    return sys.stdout.isatty()

{ignition_stack-0.3.0 → ignition_stack-0.4.0}/pyproject.toml

@@ -60,7 +60,7 @@ packages = ["ignition_stack"]
 include = ["ignition_stack", "tests", "README.md", "pyproject.toml", "modules.yaml", "builtin_modules.yaml"]
 
 [tool.ruff]
-line-length = 100
+line-length = 180
 target-version = "py311"
 
 [tool.ruff.lint]