cs-image-system-contract 0.1.4__py3-none-any.whl

cs_image_system/contract/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The plugin contract (stage 30).
+
+A plugin is written against this package and nothing else: the protocols a
+model and a builder satisfy, the constants and field helpers a model is
+declared with, the lifecycle phases a hook keys on, and the data carriers a
+hook returns (assets, command lists, a state backend's registration). The
+core (``cs_image_system.base``) implements the contract with its base
+classes, which are the convenient implementation and not the contract
+itself; a class that satisfies the protocols structurally is a first-class
+plugin.
+
+One module per kind of builder, over a shared core:
+
+- :mod:`.core` -- what every model and every builder is to the system;
+- :mod:`.runtime`, :mod:`.operating_system`, :mod:`.storage`, :mod:`.image`,
+  :mod:`.instance`, :mod:`.modification`, :mod:`.group`, :mod:`.user`,
+  :mod:`.state` -- the model and builder protocols of each kind;
+- :mod:`.constants`, :mod:`.model_config`, :mod:`.fields`,
+  :mod:`.field_kinds`, :mod:`.lifecycle`, :mod:`.lifecycles`,
+  :mod:`.assets`, :mod:`.executables`, :mod:`.metadata`, :mod:`.names`,
+  :mod:`.hcl` -- what a plugin declares, constructs and returns;
+- :mod:`.testing` -- ``assert_conforms``, the signature-level check the
+  core's tests run over every base class and every built-in plugin.
+
+The contract imports nothing from the core: a test holds the direction.
+The kind modules import :mod:`.core` and only the kinds they declare they
+read.
+"""

cs_image_system/contract/assets.py

@@ -0,0 +1,230 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""What a ``generate_items_*`` hook returns: assets, each a destination path
+and a value, gathered in an :class:`AssetSet`. In the contract since stage
+30 (``cs_image_system.base.basic.asset`` re-exports both); writing an asset
+set takes the generation path as an argument, so nothing here reaches the
+run context."""
+
+import os
+from collections.abc import Iterable
+from pathlib import Path
+import tempfile
+from typing import Any, overload
+import logging
+
+
+
+log = logging.getLogger(__name__)
+
+
+class Asset:
+    """Represents an asset to be included in the image build.  This is a tuple of
+    (source_path, destination_path) where source_path is the path to the asset on
+    the local filesystem and destination_path is the path where the asset should
+    be placed in the image.  The source_path must exist and be a file or directory.
+    The destination_path is relative to the root of the image and should not start
+    with a leading slash.  This class provides validation and utility methods for
+    working with assets, including ensuring that source paths exist and are valid,
+    and that destination paths are well-formed.  It also provides a method to
+    generate a dictionary representation of the asset for use in configuration files
+    or other contexts where a structured representation is needed.  This class is
+    designed to be used in conjunction with builders that need to include additional files or directories in the image, allowing for a clear and consistent way to specify and manage these assets throughout the build process.
+
+    Note that the path should usually be relative, and on remote assets is rooted off the primary
+    fileystem location ( i.e. / )
+    """
+
+    def __init__(self,
+                 asset_tuple: tuple[Path, Any],
+                 absolute: bool = False,
+                 remote: bool = False) -> None:
+        destination_path, val = asset_tuple
+        self._tuple = asset_tuple
+        self._binary =  isinstance(val, bytes)
+        self._remote = remote or destination_path.is_absolute()
+        if destination_path.is_absolute() and not absolute:
+            log.warning(f"Destination path '{destination_path}' should probably not be absolute.")
+
+    @property
+    def path(self) -> Path:
+        return self._tuple[0]
+    @property
+    def value(self) -> Any:
+        return self._tuple[1]
+    @property
+    def str_value(self) -> str|None:
+        return self.value if not self._binary else None
+    @property
+    def binary_value(self) -> bytes|None:
+        return self.value if self._binary else None
+    @property
+    def is_remote(self) -> bool:
+        return self._remote
+    @property
+    def is_binary(self) -> bool:
+        return self._binary
+    @property
+    def str_tuple(self) -> tuple[Path, str] | None:
+        return self._tuple if not self._binary else None
+    @property
+    def binary_tuple(self) -> tuple[Path, bytes] | None:
+        return self._tuple if self._binary else None
+
+
+class AssetSet(list[Asset]):
+    """A set of assets to be included in the image build.  This class provides
+    utility methods for working with sets of assets, including validation and
+    generation of structured representations for use in configuration files or
+    other contexts where a structured representation is needed.  This class is
+    designed to be used in conjunction with builders that need to include multiple
+    files or directories in the image, allowing for a clear and consistent way to
+    specify and manage these assets throughout the build process.
+
+    This returns a mapping of the remote assets to temp files containing those
+    assets.  This allows the builder to work with remote assets as if they were local files,
+    while still ensuring that the remote assets are properly included in the image build.
+    """
+    def __init__(self, default_path: Path | None = None) -> None:
+        super().__init__()
+        self.default_path = default_path
+
+    def with_default_path(self, default_path: Path) -> "AssetSet":
+        """Returns a new AssetSet with the given default path.  This allows for a more fluent interface when adding assets that share a common destination path."""
+        if self.default_path is not None and self.default_path != default_path:
+            raise ValueError(f"Cannot set default path to '{default_path}' because "
+                             f"it is already set to '{self.default_path}'.")
+        self.default_path = default_path
+        return self
+
+# 1. Overload names must match the implementation
+    @overload
+    def add(self, item: Path, value: Any) -> None: ...
+
+    @overload
+    def add(self, item: Any) -> None: ...
+
+    # 2. The implementation names now match 'item'
+    def add(self, item: Path | Any, value: Any = None) -> None:
+        if isinstance(item, Path):
+            path = item
+            val = value
+        else:
+            if self.default_path is None:
+                raise ValueError("Cannot add value without a default_path set.")
+            path = self.default_path
+            val = item
+        # if val.endswith("\n"):
+        #     log.warning(f"Value for asset at path '{path}' ends with a newline.  This may cause issues when writing the asset to a file.")
+        if not val:
+            if val is None:
+                log.warning(f"Value for asset at path '{path}' is None.")
+            return
+        if isinstance(val, list):
+            for v in val:
+                if not isinstance(v, (str)):
+                    raise ValueError(f"List values for asset at path '{path}' must be strings, got {type(v)}")
+                self._appendx(path, v)
+        else:
+            self._appendx(path, val)
+
+    def _appendx(self, item: Path, value: str ) -> None:
+        self.append(Asset((item, value.strip("\n"))))
+
+    @overload
+    def add_list(self, item: Path, value: Any) -> None: ...
+
+    @overload
+    def add_list(self, item: Any) -> None: ...
+
+    def add_list(self, item: Path, value: list[Any] | None = None) -> None:
+        if isinstance(item, Path):
+            path = item
+            val = value
+        else:
+            if self.default_path is None:
+                raise ValueError("Cannot add value without a default_path set.")
+            path = self.default_path
+            val = item
+        if not val:
+            if val is None:
+                log.warning(f"Value for asset list at path '{path}' is None.")
+            return
+        if not isinstance(val, list):
+            raise ValueError(f"Value must be a list, got {type(val)}")
+        for v in val:
+            self.add(path, v)
+
+    def extend(self, assets: Iterable[Asset]) -> None:
+        for asset in assets:
+            self.append(asset)
+
+
+    def sort_and_write(self,
+                       gen_path: Path,
+                       temp_loc: Path = Path("./temp_assets"),
+                       skip_remote: bool = False,
+                       skip_writes: bool = False) -> dict[Path, Path]:
+      """Write every asset under ``gen_path`` (stage 30: the caller names the
+      generation path; until then an omitted path was read from the run
+      context, the one reach into the core this module had). Local assets
+      land at ``gen_path / asset.path``, remote ones in temporary files
+      under ``gen_path / temp_loc``; the mapping returned is remote path to
+      temporary file."""
+
+      remote_write_mapping: dict[Path, Path] = {}
+      write_str_map: dict[Path, list[str]] = {}
+      write_bin_map: dict[Path, list[bytes]] = {}
+      write_remote_str_map: dict[Path, list[str]] = {}
+      write_remote_bin_map: dict[Path, list[bytes]] = {}
+      wrote_paths: set[Path] = set()
+      for asset in self:
+          if not asset.is_remote or (asset.is_remote and not skip_remote):
+            if asset.is_remote:
+              d = write_remote_str_map if not asset.is_binary else write_remote_bin_map
+            else:
+              d = write_str_map if not asset.is_binary else write_bin_map
+            d.setdefault(asset.path, []).append(asset.value)
+      if not skip_writes:
+        for path, str_values in write_str_map.items():
+            _gp = gen_path / path
+            _gp.parent.mkdir(parents=True, exist_ok=True)
+            mode = 'w' if _gp.exists() else 'a'
+            with _gp.open(mode) as f:
+                wrote_paths.add(_gp)
+                f.write("\n".join(str_values))
+        for path, bin_values in write_bin_map.items():
+            _gp = gen_path / path
+            _gp.parent.mkdir(parents=True, exist_ok=True)
+            mode = 'wb' if _gp.exists() else 'ab'
+            with _gp.open(mode) as f:
+                wrote_paths.add(_gp)
+                for bv in bin_values:
+                    f.write(bv)
+        if not skip_remote:
+            _temploc = gen_path / temp_loc
+            os.makedirs(_temploc, exist_ok=True)
+            for path, str_values in write_remote_str_map.items():
+                with tempfile.NamedTemporaryFile(dir=_temploc,
+                                                mode='w+t',
+                                                suffix = path.suffix,
+                                                delete=False) as tmp_file:
+                    tmp_file.write("\n".join(str_values))
+                    tmp_file.flush()
+                    wrote_paths.add(Path(tmp_file.name).absolute())
+                    remote_write_mapping[path] = Path(tmp_file.name).absolute()
+            for path, bin_values in write_remote_bin_map.items():
+                with tempfile.NamedTemporaryFile(dir=_temploc,
+                                                mode='w+b',
+                                                suffix = path.suffix,
+                                                delete=False) as tmp_file:
+                    for bv in bin_values:
+                        tmp_file.write(bv)
+                    tmp_file.flush()
+                    wrote_paths.add(Path(tmp_file.name).absolute())
+                    remote_write_mapping[path] = Path(tmp_file.name).absolute()
+      if wrote_paths: log.debug(f"Wrote assets to the following paths: {wrote_paths}")
+
+      return remote_write_mapping

cs_image_system/contract/constants.py

@@ -0,0 +1,208 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The constants a plugin declares its models with (stage 30: moved here
+from ``cs_image_system.base.constants``, which re-exports them): the
+sentinels that mean "not set", the classification enum ``VCT``, the field
+metadata keys the field helpers stamp, the entry-point groups, the
+collection names and the file names a run writes."""
+
+from enum import Enum, StrEnum
+
+
+NAME = "name"
+TYPE = "type"
+VERBOSE: str = "verbose"
+DEFAULT_CONFIG_FILE: str = "./image-actions.yml"
+DEFAULT: str = "default"
+ALL: str = "ALL" # ALL CAPS 'ALL' is a magic value that means "all groups, everywhere".  Use with caution.  This is basically saying "I don't care about groups, anyone can use it"
+SELF = "self"
+NONE = "none"
+# The words that mean "not set" wherever a value is read, so nothing may be NAMED
+# after one of them (stage 76). A field that gives one of them a meaning of its own
+# (the update policy's `none`, `--only none`) tests for it by name, never through
+# this list.
+OOPS_DEFAULTS: list[str | None] = [DEFAULT, None, "", SELF, NONE]
+SOURCE_MODEL: str = "SourceModel"
+
+
+RUNTIME_PROVIDER_TYPE: str = "runtime"
+CLOUD_PROVIDER_TYPE: str = "cloud_provider"
+CONTAINER_PROVIDER_TYPE: str = "container_provider"
+STATE_BACKEND_TYPE: str = "state_backend"
+S3_TYPE: str = "s3"
+STATE_BACKEND_FIELD: str = "state_configuration"
+
+CONFIGURED_OS: str = "configured_os_builders"
+CONFIGURED_IMAGE: str = "configured_image_builders"
+CONFIGURED_MOD: str = "configured_mod_builders"
+CONFIGURED_INSTANCE: str = "configured_instance_builders"
+CONFIGURED_RUNTIME: str = "configured_runtime_providers"
+CONFIGURED_STORAGE: str = "configured_storage_providers"
+CONFIGURED_GROUP: str = "configured_group_builders"
+CONFIGURED_USER: str = "configured_user_builders"
+ALL_SORTED_BUILDERS: str = "all_sorted_builders"
+STATE_SETUPS: str = "state_setups"
+DEFAULT_IMAGES_PER_RUNTIME_BUILDER: str = "default_images_per_rtb"
+
+EXECUTABLES: str = "executables"
+FORCE: str = "force"
+ONLY_PROVIDERS: str = "only_providers"
+WORKING_PATH: str = "working_path"
+GLOBAL_CONFIG: str = "config"
+LIFECYCLE: str = "lifecycle"
+CONFIG_FILE: str = "config_file"
+GENERATION_PATH: str = "generation_path"
+BASE_IMAGES = "base_images"
+IMAGES = "images"
+STORAGES = "storages"
+GROUPS = "groups"
+ROOT_GROUP = "root_group"
+USERS = "users"
+INSTANCES = "instances"
+DEFAULT_GITIGNORE_ENTRIES = [
+    "# DO NOT EDIT THIS FILE.",
+    "# This .gitignore file is auto-generated by cs-image-action.",
+    "# It includes default entries to ignore SOME generated files ",
+    "# and directories. ",
+    "target/",
+    ".terraform/",
+    "terraform.tfstate",
+    "terraform.tfstate.backup",
+    "!.terraform.lock.hcl",
+    # hygiene XII item 24 (the walk's F52): the identity runner's list of sanctioned
+    # membership removals belongs beside the plan, in the private mirror; wherever a
+    # copy lands under generated/, it is never staged (it names a person)
+    "csis-sanctioned-removals.txt",
+]
+# stage 49: the private mirror, beside generated/ under the configuration root.
+# It holds the plaintext of every value the emission carries as ciphertext, so
+# it is never committed: ignored here, refused by path, skipped by the scanner.
+PRIVATE_DIRNAME = "_private"
+# stage 43: the run-local files a run writes at the top of generated/ and never
+# commits -- the emitted root .gitignore names them, the run's commit excludes
+# them and drops them from the index where an older tree tracked them (the
+# strict state query rewrites the report outside any run, so a tracked copy
+# dirtied the checkout after every preflight)
+RUN_SUMMARY_FILENAME = "run-summary.json"
+STATE_REPORT_FILENAME = "state-report.json"
+PACKER_MANIFEST_FILENAME: str = "manifest.json"   # packer's post-processor output, read for the build's artifact id
+# Run-local (stage 43, 48.6): what a run writes for itself and never commits -- the summary,
+# the state report and packer's manifest (its artifact ids are recorded in lineage; the
+# file itself landed in the record once and is noise there). Ignored under generated/.
+RUN_LOCAL_FILENAMES: tuple[str, ...] = (RUN_SUMMARY_FILENAME, STATE_REPORT_FILENAME, PACKER_MANIFEST_FILENAME)
+SAVED_LOAD_DICT = "_saved_dict_from_load"
+ANY_AT_ALL = "ANY_AT_ALL"
+
+INVALID_CONFIG_KEYS = [ "self", "this", "same", "runtime",
+                       "os", "default", "defaults", "any",
+                       "anything", "none", "null", "" ,
+                       "timestamp", "date", "datetime",
+                       "config", "configuration",]
+
+IS_DEFERRED_LIST_GENERATED = "is_deferred_list_generated"
+DEFERRED_BUILDER_VCT = "deferred_builder_vct"
+DEFERRED_ITEM_VCT = "deferred_item_vct"
+FK_ALSO_SET_ON_UPDATE = "fk_also_set_on_update"
+IS_DEFERRED_LIST_FK = "is_deferred_list_fk"
+IS_FK = "is_fk"
+FK_TARGET = "fk_target"
+IS_REPLACE = "is_replace"
+REPLACE_VALUE = "replace_value"
+# Open discriminator: names a field's late-binding "kind" (see field_kinds.py).
+# Derived from the legacy boolean flags above when absent; plugins may set it
+# explicitly to register a brand-new kind + handler.
+FIELD_KIND = "field_kind"
+
+NO_MODEL_ID = "__NoParentModel__"
+UNSET_MODEL_ID = "__UNSETMODELID__"
+class VCT(StrEnum):
+    """Enum for valid classification types."""
+    UNCLASSIFIED = "__NMC__"
+    RUNTIME_BUILDER_MODEL = "runtime_builder_model"
+    RUNTIME_BUILDER = "runtime_builder"
+    CLOUD_BUILDER_MODEL = "cloud_builder_model"
+    CLOUD_BUILDER = "cloud_builder"
+    CONTAINER_BUILDER_MODEL = "container_builder_model"
+    CONTAINER_BUILDER = "container_builder"
+    USER_BUILDER_MODEL = "user_builder_model"
+    USER_BUILDER = "user_builder"
+    GROUP_BUILDER_MODEL = "group_builder_model"
+    GROUP_BUILDER = "group_builder"
+    OS_BUILDER_MODEL = "os_builder_model"
+    OS_BUILDER = "os_builder"
+    OS_IMAGE_BUILDER_SUBCONFIG = "os_image_builder_subconfig"
+    OS_IMAGE_BUILDER_SUBCONFIG_MODEL = "os_image_builder_subconfig_model"
+    IMAGE_BUILDER_MODEL = "image_builder_model"
+    IMAGE_BUILDER = "image_builder"
+    IMAGE_IMAGE_BUILDER_SUBCONFIG_MODEL = "image_image_builder_subconfig_model"
+    STORAGE_MAPPING_ITEM_MODEL = "storage_mapping_item_model"
+    MOD_BUILDER_MODEL = "mod_builder_model"
+    MOD_BUILDER = "mod_builder"
+    MOD_BUILDER_ITEM_MODEL = "mod_builder_item_model"
+    INSTANCE_BUILDER = "instance_builder"
+    INSTANCE_BUILDER_MODEL = "instance_builder_model"
+    STORAGE_BUILDER = "storage_builder"
+    STORAGE_BUILDER_MODEL = "storage_builder_model"
+    STATE_BACKEND = "state_backend"
+    STATE_BACKEND_MODEL = "state_backend_model"
+    EXECUTABLE_MODEL = "executable_model"
+    VERSION_CHECKER = "version_checker"
+    BASE_IMAGE_MODEL = "base_image_model"
+    IMAGE_MODEL = "image_model"
+    INSTANCE_MODEL = "instance_model"
+    GROUP_MODEL = "group_model"
+    USER_MODEL = "user_model"
+    STORAGE_MODEL = "storage_model"
+    MOD_MODEL = "mod_model"
+    SOURCE_MODEL_MODEL = "source_model_model"
+    RESOLVED_IMAGE_MODEL = "resolved_image_model"
+    PROVIDER_SPECIFIC_IMAGE = "provider_specific_image"
+
+
+PLUGIN_TYPES: list[tuple[str, str]] = [
+    ("base", "base_plugins"),
+    ("runtime", "runtime_builders"),
+    ("state", "state_backends"),
+    ("modification", "mod_builders"),
+    ("storage", "storage_builders"),
+    ("group", "group_builders"),
+    ("user", "user_builders"),
+    ("image", "image_builders"),
+    ("os", "os_builders"),
+    ("instance", "instance_builders"),
+    ("other", "other_builders"),
+    # ("executables", "executables")
+]
+class OSFamilies(StrEnum):
+    """
+    Enum for OS family classification.
+    These are the valid keys for os-family designations
+
+    """
+
+    RHEL = "rhel"
+    UBUNTU = "ubuntu"
+    DEBIAN = "debian"
+    FEDORA = "fedora"
+    OPENSUSE = "opensuse"
+    SUSE = "suse"
+    ROCKYLINUX = "rocky-linux"
+    ALMALINUX = "alma-linux"
+    CENTOS = "centos"
+    CENTOS_STREAM = "centos-stream"
+
+
+class ComplianceState(Enum):
+    """Enum for compliance state classification."""
+
+    IGNORED = "ignored"
+    ACCEPTABLE = "acceptable"
+    UNACCEPTABLE = "unacceptable"
+
+# The system's own command, as the emitted runner scripts and the in-process
+# callbacks name it (stage 64 / hygiene VII item 2: a committed script names
+# the bare command, which must be on PATH; a step the running process spawns
+# itself resolves to the running interpreter's own module instead).
+SYSTEM_CLI: str = "cs-image-system"