ignition-stack 0.6.0__tar.gz → 0.7.0__tar.gz

{ignition_stack-0.6.0 → ignition_stack-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ignition-stack
-Version: 0.6.0
+Version: 0.7.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
@@ -55,14 +55,14 @@ pipx install git+https://github.com/ia-eknorr/ignition-stack.git@<branch>
 Generate a project and bring it up:
 
 ```sh
-ignition-stack init demo --arch basic
+ignition-stack create demo --arch basic
 cd demo
 docker compose up -d
 ```
 
 The gateway reaches RUNNING with no UI prompts. The admin user is `admin / password` and the gateway is at `http://localhost:9088`. The default Postgres credentials are `ignition / ignition` on the `db` service.
 
-Run `init` without `--arch` to walk the interactive wizard instead: it opens architecture-first, then layers database, edition, IIoT, services, and exposure on top, with a summary you can preview, tweak, or generate.
+Run `create` without `--arch` to walk the interactive wizard instead: it opens architecture-first, then layers database, edition, IIoT, services, and exposure on top, with a summary you can preview, tweak, or generate.
 
 Everything that ships in the generated project is hand-readable: `docker-compose.yaml`, `.env`, `scripts/docker-bootstrap.sh`, and a `services/ignition/` resources tree the gateway reads on first boot.
 
@@ -70,11 +70,8 @@ Everything that ships in the generated project is hand-readable: `docker-compose
 
 | Command | What it does |
 | --- | --- |
-| `init <name>` | Generate a project at `./<name>/` from an architecture and a few prompts. |
+| `create <name>` | Generate a project at `./<name>/` from an architecture and a few prompts. |
 | `modules` | Download, verify, and manage the `.modl` / JDBC catalog. |
-| `reset` | Re-run generation from an SE-demo project's recorded config. |
-| `switch-arch` | Reshape an SE-demo project under a different architecture. |
-| `wipe` | Remove this project's containers and volumes only. |
 
 See the [CLI reference](docs/docs/reference/cli.md) for every command, argument, and option.
 

{ignition_stack-0.6.0 → ignition_stack-0.7.0}/README.md

@@ -26,14 +26,14 @@ pipx install git+https://github.com/ia-eknorr/ignition-stack.git@<branch>
 Generate a project and bring it up:
 
 ```sh
-ignition-stack init demo --arch basic
+ignition-stack create demo --arch basic
 cd demo
 docker compose up -d
 ```
 
 The gateway reaches RUNNING with no UI prompts. The admin user is `admin / password` and the gateway is at `http://localhost:9088`. The default Postgres credentials are `ignition / ignition` on the `db` service.
 
-Run `init` without `--arch` to walk the interactive wizard instead: it opens architecture-first, then layers database, edition, IIoT, services, and exposure on top, with a summary you can preview, tweak, or generate.
+Run `create` without `--arch` to walk the interactive wizard instead: it opens architecture-first, then layers database, edition, IIoT, services, and exposure on top, with a summary you can preview, tweak, or generate.
 
 Everything that ships in the generated project is hand-readable: `docker-compose.yaml`, `.env`, `scripts/docker-bootstrap.sh`, and a `services/ignition/` resources tree the gateway reads on first boot.
 
@@ -41,11 +41,8 @@ Everything that ships in the generated project is hand-readable: `docker-compose
 
 | Command | What it does |
 | --- | --- |
-| `init <name>` | Generate a project at `./<name>/` from an architecture and a few prompts. |
+| `create <name>` | Generate a project at `./<name>/` from an architecture and a few prompts. |
 | `modules` | Download, verify, and manage the `.modl` / JDBC catalog. |
-| `reset` | Re-run generation from an SE-demo project's recorded config. |
-| `switch-arch` | Reshape an SE-demo project under a different architecture. |
-| `wipe` | Remove this project's containers and volumes only. |
 
 See the [CLI reference](docs/docs/reference/cli.md) for every command, argument, and option.
 

ignition_stack-0.7.0/ignition_stack/__init__.py

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

{ignition_stack-0.6.0 → ignition_stack-0.7.0}/ignition_stack/architectures/base.py

@@ -173,10 +173,10 @@ def _matching_gateways(config: ProjectConfig, redundant_role: str) -> list:
 def can_host_redundant_role(config: ProjectConfig, redundant_role: str) -> bool:
     """True when ``config`` has exactly one gateway that can be paired as master.
 
-    ``switch-arch`` uses this to decide whether redundancy intent recovered from
-    the old stack can carry to the target architecture, without raising the way
-    :func:`mark_redundant` does - an architecture-specific role (e.g. basic's
-    ``gateway``) simply may not exist in the destination.
+    Used to check whether a redundancy role from a recorded config could carry
+    to a target architecture, without raising the way :func:`mark_redundant`
+    does - an architecture-specific role (e.g. basic's ``gateway``) simply may
+    not exist in the destination.
     """
     if redundant_role in _NON_REDUNDANT_ROLES:
         return False

{ignition_stack-0.6.0 → ignition_stack-0.7.0}/ignition_stack/cli.py

@@ -1,19 +1,12 @@
 """Top-level Typer application.
 
-Phase 2 implements ``init`` for the standalone+Postgres walking skeleton.
-Phase 3 wires the real ``modules`` sub-app (catalog list/validate/download);
-``reset`` and ``wipe`` remain visible placeholders so the command surface
-is stable from day one, with later phases filling them in.
-
-Phase 6 widens ``init`` with ``--arch``, ``--spokes``, ``--force``, and
-``--edge-role`` for the system architectures, and falls into the interactive
-wizard when no architecture is named.
+The CLI surface is intentionally narrow: ``create`` generates a new named
+stack, and the ``modules`` sub-app manages the module catalog.  Stacks are
+short-lived; recreate with the recorded config rather than reshape in place.
 """
 
 from __future__ import annotations
 
-import subprocess
-from dataclasses import replace
 from pathlib import Path
 
 import typer
@@ -24,16 +17,9 @@ from ignition_stack.architectures import (
     ArchitectureError,
     ArchOptions,
     build_architecture,
-    can_host_redundant_role,
     get_architecture,
     list_architectures,
 )
-from ignition_stack.architectures.carry import (
-    carry_registry,
-    database_carried_by_kind,
-    detect_iiot_broker,
-    is_default_representable,
-)
 from ignition_stack.commands.modules import modules_app
 from ignition_stack.completion import (
     complete_architecture,
@@ -52,17 +38,7 @@ from ignition_stack.config import (
     dump_config,
     load_config,
 )
-from ignition_stack.lifecycle import (
-    LIFECYCLE_DIR,
-    RECORD_NAME,
-    CleanupError,
-    LifecycleError,
-    project_name,
-    read_record,
-    wipe_command,
-)
-from ignition_stack.lifecycle.regenerate import regenerate
-from ignition_stack.services.loader import load_all_services
+from ignition_stack.record import RECORD_DIR, RECORD_NAME
 from ignition_stack.services.resolver import resolve
 from ignition_stack.update_check import (
     check_for_update,
@@ -133,7 +109,7 @@ def _arch_help() -> str:
 
 
 @app.command()
-def init(
+def create(
     name: str = typer.Argument(
         ...,
         help="Project name. Becomes the directory, the compose project, and the gateway name.",
@@ -283,7 +259,7 @@ def init(
     """
     target = ((output_dir or Path.cwd()) / name).resolve()
 
-    _validate_init_flags(arch=arch, from_file=from_file, dry_run=dry_run, fmt=output_format)
+    _validate_create_flags(arch=arch, from_file=from_file, dry_run=dry_run, fmt=output_format)
 
     # Name validation runs before either the wizard or the architecture build so
     # invalid names fail fast with a clear exit code (2), instead of bubbling
@@ -337,7 +313,7 @@ def init(
     console.print("  docker compose up -d")
     console.print(f"  open {_gateway_open_url(config)}  (admin / {config.admin_password})")
     console.print()
-    console.print(f"  config recorded in {LIFECYCLE_DIR}/ - run `ignition-stack reset` to " "regenerate or `switch-arch <name>` to reshape this stack.")
+    console.print(f"  config recorded in {RECORD_DIR}/{RECORD_NAME} - pass it to" " `ignition-stack create <name> -f` to recreate or clone this stack")
 
 
 def _gateway_open_url(config: ProjectConfig) -> str:
@@ -353,7 +329,7 @@ def _gateway_open_url(config: ProjectConfig) -> str:
     return f"http://localhost:{config.gateways[0].http_port}"
 
 
-def _validate_init_flags(*, arch: str | None, from_file: Path | None, dry_run: bool, fmt: str | None) -> None:
+def _validate_create_flags(*, arch: str | None, from_file: Path | None, dry_run: bool, fmt: str | None) -> None:
     """Enforce the mutual-exclusion + flag-applicability rules, or exit code 2.
 
     ``--from-file`` already fully specifies the topology, so combining it with
@@ -459,207 +435,5 @@ def _run_wizard_or_exit(name: str) -> ProjectConfig:
         raise typer.Exit(code=130) from exc
 
 
-@app.command()
-def reset(
-    project_dir: Path = typer.Option(  # noqa: B008 - Typer pattern
-        Path("."),
-        "--project-dir",
-        "-C",
-        help="The generated project to reset. Defaults to the current directory.",
-    ),
-) -> None:
-    """Regenerate a project from its recorded config.
-
-    Reads ``.ignition-stack/config.json``, clears the generated tree (keeping the
-    record and the modules cache), and re-runs generation. Works on any project
-    generated by this CLI; a directory without a record can't be reset.
-    """
-    project_dir = project_dir.resolve()
-    try:
-        config = read_record(project_dir)
-    except LifecycleError as exc:
-        console.print(f"[red]error[/red]: {exc}")
-        raise typer.Exit(code=2) from exc
-
-    files = regenerate(project_dir, config)
-    console.print(f"[green]reset[/green] {project_dir}")
-    console.print(f"  {len(files)} file(s) regenerated from {LIFECYCLE_DIR}/{RECORD_NAME}")
-
-
-@app.command(name="switch-arch")
-def switch_arch(
-    arch: str = typer.Argument(
-        ...,
-        help="System architecture to switch this stack to.",
-        autocompletion=complete_architecture,
-    ),
-    project_dir: Path = typer.Option(  # noqa: B008 - Typer pattern
-        Path("."),
-        "--project-dir",
-        "-C",
-        help="The generated project to reshape. Defaults to the current directory.",
-    ),
-) -> None:
-    """Reshape a project under a different system architecture.
-
-    Carries the recorded database, services, reverse-proxy, and edge intent over
-    to the new architecture, then regenerates in place and re-records the result.
-    """
-    project_dir = project_dir.resolve()
-    try:
-        current = read_record(project_dir)
-    except LifecycleError as exc:
-        console.print(f"[red]error[/red]: {exc}")
-        raise typer.Exit(code=2) from exc
-
-    try:
-        get_architecture(arch)
-    except KeyError as exc:
-        console.print(f"[red]error[/red]: {exc}")
-        raise typer.Exit(code=2) from exc
-
-    options = _options_from_config(current)
-    # Redundancy is pinned to an architecture-specific role (e.g. basic's
-    # 'gateway'), which the target architecture may not have. Building its base
-    # topology lets us check before build_architecture's mark_redundant would
-    # reject it - drop the intent with an advisory rather than failing the reshape.
-    if options.redundant_role is not None and not can_host_redundant_role(get_architecture(arch).build(current.name, options), options.redundant_role):
-        console.print(
-            f"[yellow]note[/yellow]: redundancy on '{options.redundant_role}' was not "
-            f"carried to {arch} (no matching gateway); re-apply with --redundant "
-            "if the new topology has a role to pair"
-        )
-        options = replace(options, redundant_role=None)
-    try:
-        new_config = build_architecture(arch, current.name, options)
-    except ArchitectureError as exc:
-        console.print(f"[red]advisory[/red]: {exc}")
-        raise typer.Exit(code=3) from exc
-    except ValueError as exc:
-        console.print(f"[red]error[/red]: {exc}")
-        raise typer.Exit(code=2) from exc
-
-    # Re-graft the richer registry shapes ArchOptions can't express (custom
-    # ids, per-instance overrides, partial attachment sets, a second database),
-    # re-mapping their attachments by role and dropping any that the new topology
-    # can't host - each with a printed advisory. Resolve first so the
-    # architecture's legacy database is already lowered into per-gateway
-    # attachments; the carry's one-database-per-gateway guard then sees them and
-    # won't over-attach. The carry's output is resolved again by regenerate
-    # (resolve is idempotent).
-    new_config = carry_registry(resolve(new_config), current, console)
-
-    files = regenerate(project_dir, new_config)
-    console.print(f"[green]switched[/green] {current.architecture or 'custom'} -> {arch}")
-    console.print(f"  {len(files)} file(s) regenerated")
-
-
-def _options_from_config(config: ProjectConfig) -> ArchOptions:
-    """Recover the architecture inputs a switch should carry over from a recorded config.
-
-    Edge intent is recovered from whichever gateway runs the Edge edition (or
-    'none' to keep the new architecture from re-introducing its edge default); the
-    spoke count from the number of spoke-role gateways, the frontend count from
-    the number of frontend-role gateways, and the network split is carried over
-    verbatim so a reshape preserves the user's topology choice. Disabled
-    built-in modules are carried over too (see below) so a reshape doesn't
-    silently re-enable Vision/SFC/etc.
-    """
-    edge_roles = [gw.role or gw.name for gw in config.gateways if gw.ignition_edition == "edge"]
-    spoke_count = sum(1 for gw in config.gateways if (gw.role or "") == "spoke")
-    frontend_count = sum(1 for gw in config.gateways if (gw.role or "") == "frontend")
-    # Redundancy intent is carried by the master node (the backup is re-derived
-    # by the resolver), so recover the role/name of whichever gateway is the
-    # master and let the new architecture re-expand the pair.
-    redundant_role = next(
-        (gw.role or gw.name for gw in config.gateways if gw.redundancy is not None and gw.redundancy.mode == "master"),
-        None,
-    )
-    # Disabled built-ins are applied stack-wide, so carry over the slugs disabled
-    # on EVERY gateway (the intersection) - that is the stack-wide intent, and it
-    # won't over-disable a module that a hand-authored config turned off on only
-    # one node. The target architecture re-applies it uniformly.
-    disabled_sets = [set(gw.disable_builtins) for gw in config.gateways]
-    disable_builtins = tuple(sorted(set.intersection(*disabled_sets))) if disabled_sets else ()
-    # A recorded config is resolved: its database + services live in the
-    # registry, not the legacy fields. Recover the architecture inputs from the
-    # registry. The primary database rides database_kind (see below); the
-    # non-database instances that are default-representable ride `services`.
-    # IIoT intent is recovered from the attachment roles: a stack with any
-    # mqtt-transmission/mqtt-engine attachment was built with apply_iiot, so set
-    # iiot=True and the broker slug. build_architecture re-runs the overlay in the new
-    # topology, re-mapping Transmission/Engine onto the new roles naturally; the
-    # broker instance is therefore excluded from `services` below to avoid a
-    # double-add. Anything richer than `services` can express (custom ids,
-    # per-instance overrides, partial/role-specific attachments, a second
-    # database) is carried after build_architecture by carry_registry.
-    iiot_broker = detect_iiot_broker(config)
-    catalog = load_all_services()
-    representable = tuple(inst.service for inst in config.non_database_instances() if inst.service != iiot_broker and is_default_representable(inst, config, catalog))
-    # The primary database rides database_kind only when it has the clean
-    # canonical shape (id "db", default image/credentials, consumer on every
-    # non-Edge gateway). A custom primary database - or any second database - is
-    # left for carry_registry to re-graft, so database_kind stays None and the
-    # architecture does not also lay down a colliding default DB.
-    carried_db = database_carried_by_kind(config, catalog)
-    return ArchOptions(
-        spokes=spoke_count or 3,
-        frontends=frontend_count or 1,
-        edge_role=edge_roles[0] if edge_roles else "none",
-        network_split=config.network_split,
-        reverse_proxy=config.reverse_proxy,
-        database_kind=carried_db.service if carried_db is not None else None,
-        services=representable,
-        redundant_role=redundant_role,
-        disable_builtins=disable_builtins,
-        iiot=iiot_broker is not None,
-        iiot_broker=iiot_broker,
-    )
-
-
-@app.command()
-def wipe(
-    project_dir: Path = typer.Option(  # noqa: B008 - Typer pattern
-        Path("."),
-        "--project-dir",
-        "-C",
-        help="The generated project to wipe. Defaults to the current directory.",
-    ),
-    dry_run: bool = typer.Option(
-        False,
-        "--dry-run",
-        help="Print the scoped teardown command without running it.",
-    ),
-) -> None:
-    """Remove only this project's containers, networks, and volumes.
-
-    Runs ``docker compose -p <project> down -v --remove-orphans``; the ``-p``
-    pin scopes the teardown to resources labelled with this compose project, so
-    unrelated Docker resources on the host are never touched.
-    """
-    project_dir = project_dir.resolve()
-    try:
-        name = project_name(project_dir)
-    except CleanupError as exc:
-        console.print(f"[red]error[/red]: {exc}")
-        raise typer.Exit(code=2) from exc
-
-    command = wipe_command(name)
-    if dry_run:
-        console.print(" ".join(command))
-        return
-
-    try:
-        completed = subprocess.run(command, cwd=project_dir, check=False)
-    except FileNotFoundError as exc:
-        console.print("[red]error[/red]: docker not found on PATH; cannot wipe.")
-        raise typer.Exit(code=1) from exc
-
-    if completed.returncode != 0:
-        console.print(f"[red]error[/red]: `{' '.join(command)}` exited {completed.returncode}")
-        raise typer.Exit(code=completed.returncode)
-    console.print(f"[green]wiped[/green] project '{name}'")
-
-
 if __name__ == "__main__":  # pragma: no cover
     app()

{ignition_stack-0.6.0 → ignition_stack-0.7.0}/ignition_stack/compose/writer.py

@@ -30,8 +30,8 @@ from ignition_stack.catalog.loader import CatalogLoadError, load_catalog
 from ignition_stack.catalog.schema import Catalog
 from ignition_stack.compose.engine import render_compose
 from ignition_stack.config.schema import ProjectConfig, ServiceInstance
-from ignition_stack.lifecycle.record import write_record
 from ignition_stack.postsetup import generate_post_setup
+from ignition_stack.record import write_record
 from ignition_stack.services.loader import load_all_services, service_dir
 from ignition_stack.services.resolver import resolve
 
@@ -63,12 +63,7 @@ _IIOT_VERIFIED_BROKERS = frozenset({"chariot"})
 _BROKER_MQTT_USER: dict[str, str] = {"chariot": "admin"}
 
 
-def write_project(
-    config: ProjectConfig,
-    target_dir: Path,
-    *,
-    overwrite: bool = False,
-) -> list[Path]:
+def write_project(config: ProjectConfig, target_dir: Path) -> list[Path]:
     """Generate the project tree at ``target_dir``.
 
     The config is resolved first (implicit dependencies expanded - see
@@ -76,20 +71,16 @@ def write_project(
     the on-disk seeds agree on the same fully-expanded stack.
 
     Every project records its resolved config under ``.ignition-stack/`` so
-    ``reset`` / ``switch-arch`` can regenerate or reshape it in place; the
-    same artifact can be dumped with ``init --dry-run`` and rebuilt with
-    ``init -f``.
-
-    ``overwrite`` lets ``reset`` / ``switch-arch`` write into a directory
-    that still holds the preserved ``.ignition-stack/`` record; normal ``init``
-    leaves it ``False`` so a stray non-empty directory still refuses to clobber.
+    the same stack can be recreated or cloned with ``create <name> -f``; the
+    same artifact can be dumped with ``create --dry-run`` and rebuilt with
+    ``create -f``.
 
     Returns the list of files written (absolute paths), in the order they
     were written. Raises :class:`FileExistsError` if ``target_dir`` already
-    has files and ``overwrite`` is ``False``.
+    has files.
     """
     target_dir = Path(target_dir).resolve()
-    if not overwrite and target_dir.exists() and any(target_dir.iterdir()):
+    if target_dir.exists() and any(target_dir.iterdir()):
         raise FileExistsError(f"target directory '{target_dir}' is not empty; refusing to overwrite")
     target_dir.mkdir(parents=True, exist_ok=True)
 
@@ -520,7 +511,7 @@ COMPOSE := docker compose
 PROJECT := @@PROJECT@@
 
 .DEFAULT_GOAL := help
-.PHONY: help up down logs wipe reset
+.PHONY: help up down logs wipe
 
 help:  ## List available targets.
 \t@grep -hE '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) \\
@@ -537,17 +528,14 @@ logs:  ## Follow logs for every service.
 
 wipe:  ## Remove ONLY this project's containers, networks, and volumes.
 \t$(COMPOSE) -p $(PROJECT) down -v --remove-orphans
-
-reset:  ## Regenerate this project from its recorded config.
-\tignition-stack reset
 """
 
 
 def _write_makefile(config: ProjectConfig, target_dir: Path) -> Path:
-    """Write the project ``Makefile`` (up/down/logs/wipe/reset).
+    """Write the project ``Makefile`` (up/down/logs/wipe).
 
     ``wipe`` is scoped to the compose project name so it cannot reach unrelated
-    Docker resources; that scoping is the Phase-7 cleanup contract.
+    Docker resources on the host.
     """
     body = _MAKEFILE.replace("@@PROJECT@@", config.name)
     dst = target_dir / "Makefile"

{ignition_stack-0.6.0 → ignition_stack-0.7.0}/ignition_stack/config/io.py

@@ -1,12 +1,12 @@
 """Serialize and load a resolved :class:`ProjectConfig` as YAML or JSON.
 
 The resolved config is the CLI's full build input - project name, gateways,
-networks, database, services, env. ``ignition-stack init --dry-run`` dumps it;
-``ignition-stack init -f <file>`` loads it back and builds from it. The same
-artifact is what the lifecycle record (:mod:`ignition_stack.lifecycle.record`)
-persists, so dump/edit/rebuild and reset/switch-arch share one schema.
+networks, database, services, env. ``ignition-stack create --dry-run`` dumps it;
+``ignition-stack create -f <file>`` loads it back and builds from it. The same
+artifact is what the record module (:mod:`ignition_stack.record`) persists, so
+dump/edit/rebuild share one schema.
 
-JSON dumps reuse pydantic's ``model_dump_json`` so the on-disk lifecycle record
+JSON dumps reuse pydantic's ``model_dump_json`` so the on-disk config record
 stays byte-identical to what it was before this module existed. YAML dumps go
 through ruamel (already the compose engine's YAML library) in safe mode, which
 emits block-style, alias-free output suitable for hand-editing by a person or
@@ -55,7 +55,7 @@ def _yaml() -> YAML:
 def dump_config(config: ProjectConfig, fmt: Format = "yaml") -> str:
     """Serialize ``config`` to a string in ``fmt`` ('yaml' or 'json').
 
-    The JSON form matches the lifecycle record exactly (2-space indent, trailing
+    The JSON form matches the config record exactly (2-space indent, trailing
     newline). The YAML form is the hand-authorable artifact: block style, keys in
     schema declaration order, no anchors.
     """

{ignition_stack-0.6.0 → ignition_stack-0.7.0}/ignition_stack/config/schema.py

@@ -557,7 +557,7 @@ class ProjectConfig(BaseModel):
             "('basic', 'scale-out', 'hub-and-spoke'). "
             "Informational - the compose engine reads from the resolved "
             "fields, not this slug - but lets generated files (header "
-            "comment, lifecycle records) name the architecture they came from."
+            "comment, config records) name the architecture they came from."
         ),
     )
 

{ignition_stack-0.6.0/ignition_stack/lifecycle → ignition_stack-0.7.0/ignition_stack}/record.py

@@ -1,17 +1,16 @@
-"""Lifecycle record: every generated project's serialized resolved config.
-
-Each 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-arch`` need: they read it back, optionally reshape it, and re-run
-generation - no second trip through the wizard.
-
-The record is just the declarative config artifact (see
-:mod:`ignition_stack.config.io`) written to a known path; ``init -f <file>``
-consumes the identical format. ``read_record`` is a thin wrapper over
-``load_config`` that reports a missing record as a :class:`LifecycleError` so
-``reset`` / ``switch-arch`` can fail cleanly on a directory that was never
-generated by this CLI.
+"""The resolved config record every generated project writes.
+
+Every generation pass writes the fully-resolved
+:class:`~ignition_stack.config.schema.ProjectConfig` to
+``.ignition-stack/config.json``. That file is the only artifact
+``ignition-stack create`` needs to recreate or clone the stack:
+
+    ignition-stack create <name> -f .ignition-stack/config.json
+
+The positional name overrides the recorded one, so the same file clones
+a stack under a new name. Editing the file before re-running is a
+supported workflow - it is the same YAML/JSON schema that ``--dry-run``
+dumps and ``-f`` rebuilds from.
 """
 
 from __future__ import annotations
@@ -23,21 +22,21 @@ from ignition_stack.config.schema import ProjectConfig
 
 # The directory the record lives 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_DIR = ".ignition-stack"
 RECORD_NAME = "config.json"
 
 
-class LifecycleError(Exception):
-    """Raised when a lifecycle operation can't find or read its record."""
+class RecordError(Exception):
+    """Raised when a project's config record can't be found or read."""
 
 
 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
+    return Path(project_dir) / RECORD_DIR / RECORD_NAME
 
 
 def has_record(project_dir: Path) -> bool:
-    """True when ``project_dir`` carries a lifecycle record."""
+    """True when ``project_dir`` carries a config record."""
     return record_path(project_dir).is_file()
 
 
@@ -56,18 +55,14 @@ def write_record(config: ProjectConfig, project_dir: Path) -> Path:
 def read_record(project_dir: Path) -> ProjectConfig:
     """Load the recorded config for a project.
 
-    Raises :class:`LifecycleError` when the project has no record (a directory
+    Raises :class:`RecordError` when the project has no record (a directory
     that was never generated by this CLI, or one whose record was removed) or
     when the record can't be parsed or validated.
     """
     src = record_path(project_dir)
     if not src.is_file():
-        raise LifecycleError(
-            f"no lifecycle record at {src}. This directory was not generated by "
-            "ignition-stack (or its record was removed); reset/switch-arch "
-            "need a project with a recorded config."
-        )
+        raise RecordError(f"no config record at {src}. This directory was not generated by " "ignition-stack (or its record was removed).")
     try:
         return load_config(src)
     except ConfigIOError as exc:
-        raise LifecycleError(str(exc)) from exc
+        raise RecordError(str(exc)) from exc

{ignition_stack-0.6.0 → ignition_stack-0.7.0}/ignition_stack/wizard_composer.py

@@ -84,7 +84,7 @@ class ComposerResult:
     the same exit-130 path the architecture flow uses). ``architecture``/
     ``options`` carry the originating architecture so the
     :class:`~ignition_stack.wizard.WizardOutcome` stays populated for the
-    lifecycle record and tests.
+    config record and tests.
     """
 
     config: ProjectConfig