codeplain 0.3.9__py3-none-any.whl → 0.3.10.dev2__py3-none-any.whl

plain_modules.py

@@ -2,15 +2,24 @@ from __future__ import annotations
 
 import os
 import shutil
+import tempfile
+import zipfile
 from functools import cached_property
 
-from plain2code_exceptions import GitNotInstalledError, MissingPreviousFunctionalitiesError, ModuleDoesNotExistError
+from plain2code_exceptions import (
+    GitNotInstalledError,
+    InvalidModuleArchiveError,
+    MissingPreviousFunctionalitiesError,
+    ModuleDoesNotExistError,
+)
 
 try:
+    from git import Repo
     from git.exc import NoSuchPathError
 except ImportError:
     raise GitNotInstalledError("git is not installed. Please install git and try again.")
 
+import file_utils
 import git_utils
 import metadata_utils
 import plain_file
@@ -28,6 +37,11 @@ CODEPLAIN_METADATA_FOLDER = ".codeplain"
 MODULE_CODE_SUBFOLDER = "code"
 MODULE_TESTS_SUBFOLDER = "tests"
 
+# A module's build output may be shipped as a single zip archive named
+# "<module>.module" instead of an unpacked "<module>/" folder. See PlainModule.materialize
+# (read/consume) and PlainModule.ensure_module_unpacked (unpack-on-change).
+MODULE_ARCHIVE_EXTENSION = ".module"
+
 
 def get_module_code_folder(modules_base_folder: str, module_name: str) -> str:
     return os.path.join(modules_base_folder, module_name, MODULE_CODE_SUBFOLDER)
@@ -37,6 +51,81 @@ def get_module_tests_folder(modules_base_folder: str, module_name: str) -> str:
     return os.path.join(modules_base_folder, module_name, MODULE_TESTS_SUBFOLDER)
 
 
+def _validate_module_repo(repo_path: str, subfolder: str, archive_path: str) -> None:
+    """Validate one extracted git repo (code/ or tests/) inside a module archive."""
+    if not os.path.isdir(os.path.join(repo_path, ".git")):
+        raise InvalidModuleArchiveError(
+            f"Module archive '{archive_path}' has no git repository in '{subfolder}/' "
+            "(the archive must include the '.git' directory)."
+        )
+    try:
+        repo = Repo(repo_path)
+        if repo.bare or repo.head.is_detached:
+            raise InvalidModuleArchiveError(
+                f"The git repository in '{subfolder}/' of module archive '{archive_path}' "
+                "must be a working tree checked out on a branch."
+            )
+    except InvalidModuleArchiveError:
+        raise
+    except Exception as e:
+        raise InvalidModuleArchiveError(
+            f"The git repository in '{subfolder}/' of module archive '{archive_path}' is invalid: {e}"
+        ) from e
+
+
+def _validate_module_tree(root: str, archive_path: str) -> None:
+    """Verify an extracted module tree. ``code/`` is required. ``tests/`` is optional: a module
+    rendered without a conformance-tests script has no tests folder, so its archive has none either.
+    When ``tests/`` is present it must be a valid git repo."""
+    code_path = os.path.join(root, MODULE_CODE_SUBFOLDER)
+    if not os.path.isdir(code_path):
+        raise InvalidModuleArchiveError(
+            f"Module archive '{archive_path}' is missing the '{MODULE_CODE_SUBFOLDER}/' folder at its root. "
+            "The archive must contain the module folder's contents (code/, optionally tests/, ...) at its "
+            "root, not nested under a top-level directory."
+        )
+    _validate_module_repo(code_path, MODULE_CODE_SUBFOLDER, archive_path)
+
+    tests_path = os.path.join(root, MODULE_TESTS_SUBFOLDER)
+    if os.path.isdir(tests_path):
+        _validate_module_repo(tests_path, MODULE_TESTS_SUBFOLDER, archive_path)
+
+
+def _extract_module_archive(archive_path: str, dest: str) -> None:
+    """Extract a "<module>.module" zip into dest and validate the module layout.
+
+    Guards against zip-slip, restores unix mode bits (zipfile drops them), and validates
+    that dest contains valid code/ and tests/ git repositories. Raises
+    InvalidModuleArchiveError on any problem.
+    """
+    if not zipfile.is_zipfile(archive_path):
+        raise InvalidModuleArchiveError(f"Module archive '{archive_path}' is not a valid zip file.")
+
+    os.makedirs(dest, exist_ok=True)
+    dest_root = os.path.realpath(dest)
+
+    try:
+        with zipfile.ZipFile(archive_path) as zf:
+            for member in zf.namelist():
+                target = os.path.realpath(os.path.join(dest, member))
+                if target != dest_root and not target.startswith(dest_root + os.sep):
+                    raise InvalidModuleArchiveError(
+                        f"Module archive '{archive_path}' contains an unsafe path: {member}"
+                    )
+            zf.extractall(dest)
+            for info in zf.infolist():
+                mode = (info.external_attr >> 16) & 0o777
+                if not mode:
+                    continue
+                member_path = os.path.join(dest, info.filename)
+                if os.path.exists(member_path) and not os.path.islink(member_path):
+                    os.chmod(member_path, mode)
+    except zipfile.BadZipFile as e:
+        raise InvalidModuleArchiveError(f"Module archive '{archive_path}' is corrupt: {e}") from e
+
+    _validate_module_tree(dest, archive_path)
+
+
 def _strip_functional_requirements(plain_source_tree: dict) -> dict:
     stripped = {k: v for k, v in plain_source_tree.items() if k != plain_spec.FUNCTIONAL_REQUIREMENTS}
     if "sections" in stripped:
@@ -49,6 +138,10 @@ class PlainModule:
         self.filename = filename
         self.build_folder = build_folder
         self.template_dirs = template_dirs
+        # When the module exists only as a "<module>.module" archive, these hold the
+        # scratch extraction used for read-only consumption. See materialize().
+        self._resolved_module_folder: str | None = None
+        self._scratch_dir: str | None = None
         module_name, plain_source, required_modules_names = plain_file.plain_file_parser(
             self.filename, self.template_dirs
         )
@@ -81,16 +174,28 @@ class PlainModule:
         return all_required_modules
 
     @property
-    def module_folder(self):
+    def _default_module_folder(self) -> str:
         return os.path.join(self.build_folder, self.module_name)
 
+    @property
+    def module_folder(self):
+        # When the module was materialized from a "<module>.module" archive, all subpaths
+        # resolve against the scratch extraction; otherwise against the real folder.
+        if self._resolved_module_folder is not None:
+            return self._resolved_module_folder
+        return self._default_module_folder
+
+    @property
+    def module_archive_path(self) -> str:
+        return self._default_module_folder + MODULE_ARCHIVE_EXTENSION
+
     @property
     def module_conformance_tests_folder(self):
-        return get_module_tests_folder(self.build_folder, self.module_name)
+        return os.path.join(self.module_folder, MODULE_TESTS_SUBFOLDER)
 
     @property
     def module_build_folder(self):
-        return get_module_code_folder(self.build_folder, self.module_name)
+        return os.path.join(self.module_folder, MODULE_CODE_SUBFOLDER)
 
     @property
     def module_memory_folder(self):
@@ -99,6 +204,84 @@ class PlainModule:
     def get_codeplain_folder(self):
         return os.path.join(self.module_folder, CODEPLAIN_METADATA_FOLDER)
 
+    def has_module_archive(self) -> bool:
+        return os.path.isfile(self.module_archive_path)
+
+    def is_archived_only(self) -> bool:
+        return not os.path.isdir(self._default_module_folder) and self.has_module_archive()
+
+    def archive_has_conformance_tests(self) -> bool:
+        """True if the "<module>.module" archive contains a tests/ folder. A module rendered without
+        a conformance-tests script has no tests/, so its archive has none either."""
+        if not self.has_module_archive() or not zipfile.is_zipfile(self.module_archive_path):
+            return False
+        prefix = MODULE_TESTS_SUBFOLDER + "/"
+        with zipfile.ZipFile(self.module_archive_path) as zf:
+            return any(name.startswith(prefix) for name in zf.namelist())
+
+    def materialize(self) -> None:
+        """Make an archive-only module readable without populating plain_modules/<module>/.
+
+        If the real folder is absent but a "<module>.module" archive exists, extract it to a
+        scratch directory and point this module's paths there. No-op if the real folder exists
+        or the module is already materialized. The archive file is preserved.
+        """
+        if self._resolved_module_folder is not None:
+            return
+        if os.path.isdir(self._default_module_folder):
+            return
+        if not self.has_module_archive():
+            return
+
+        scratch_dir = tempfile.mkdtemp(prefix=f"codeplain-module-{self.module_name}-")
+        try:
+            _extract_module_archive(self.module_archive_path, scratch_dir)
+        except BaseException:
+            shutil.rmtree(scratch_dir, ignore_errors=True)
+            raise
+        self._scratch_dir = scratch_dir
+        self._resolved_module_folder = scratch_dir
+
+    def ensure_module_unpacked(self) -> None:
+        """Unpack an archive-only module into the real plain_modules/<module>/ in place.
+
+        Called before a module is (re)rendered. Idempotent. If the real folder already exists,
+        only a stray archive is removed. Extraction is atomic (extract to a temp sibling under
+        the build folder, then os.replace), and the archive is deleted only after success.
+        """
+        if os.path.isdir(self._default_module_folder):
+            if self.has_module_archive():
+                os.remove(self.module_archive_path)
+            self._reset_scratch()
+            self._resolved_module_folder = None
+            return
+
+        if not self.has_module_archive():
+            return
+
+        os.makedirs(self.build_folder, exist_ok=True)
+        staging_dir = tempfile.mkdtemp(prefix=f".{self.module_name}-unpacking-", dir=self.build_folder)
+        try:
+            _extract_module_archive(self.module_archive_path, staging_dir)
+            os.replace(staging_dir, self._default_module_folder)
+        except BaseException:
+            shutil.rmtree(staging_dir, ignore_errors=True)
+            raise
+
+        os.remove(self.module_archive_path)
+        self._reset_scratch()
+        self._resolved_module_folder = None
+
+    def _reset_scratch(self) -> None:
+        if self._scratch_dir is not None:
+            shutil.rmtree(self._scratch_dir, ignore_errors=True)
+            self._scratch_dir = None
+
+    def cleanup_scratch(self) -> None:
+        """Remove any scratch extraction created by materialize(). Safe to call multiple times."""
+        self._reset_scratch()
+        self._resolved_module_folder = None
+
     def get_module_render_status(self) -> tuple[str | None, str | None]:
         module_name, frid = git_utils.get_last_rendered_functionality(self.module_build_folder)
         if module_name is not None and module_name == self.module_name:
@@ -149,6 +332,9 @@ class PlainModule:
         return plain_spec.get_hash_value([stripped] + self.resources_list)
 
     def get_module_code_hash(self) -> str:
+        # Content-only hash (see calculate_build_folder_hash): reading from the resolved (possibly
+        # scratch) folder yields the same hash as the in-place folder and the same hash across
+        # locations, so archived modules stay portable.
         return ImplementationCodeHelpers.calculate_build_folder_hash(self.module_build_folder)
 
     def has_required_modules_code_changed(
@@ -408,6 +594,10 @@ class PlainModule:
         return False
 
     def wipe_module(self) -> None:
-        if os.path.exists(self.module_folder):
-            console.warning(f"Wiping module {self.module_folder}...")
-            shutil.rmtree(self.module_folder)
+        if os.path.isdir(self._default_module_folder):
+            console.warning(f"Wiping module {self._default_module_folder}...")
+            file_utils.delete_folder(self._default_module_folder)
+        if self.has_module_archive():
+            os.remove(self.module_archive_path)
+        self._reset_scratch()
+        self._resolved_module_folder = None

render_machine/actions/prepare_repositories.py

@@ -32,6 +32,11 @@ class PrepareRepositories(BaseAction):
                 )
 
         else:
+            if render_context.required_modules:
+                # If the required module exists only as a "<module>.module" archive, extract it to scratch first
+                # (no-op if it is already an unpacked folder or already materialized).
+                render_context.required_modules[-1].materialize()
+
             file_utils.delete_folder(render_context.plain_module.module_folder)
             render_context.plain_module.seed_module_metadata()
 

render_machine/conformance_tests.py

@@ -1,5 +1,6 @@
 import json
 import os
+from typing import Callable, Optional
 
 import file_utils
 from plain2code_console import console
@@ -16,11 +17,20 @@ class ConformanceTests:
         self,
         modules_base_folder: str,
         conformance_tests_definition_file_name: str,
+        resolve_module_tests_folder: Optional[Callable[[str], Optional[str]]] = None,
     ):
         self.modules_base_folder = modules_base_folder
         self.conformance_tests_definition_file_name = conformance_tests_definition_file_name
+        # Optional resolver mapping a module name to its resolved tests folder. Lets an
+        # archive-only ("<module>.module") required module resolve to its scratch extraction
+        # instead of the (non-existent) default plain_modules/<module>/tests path.
+        self._resolve_module_tests_folder = resolve_module_tests_folder
 
     def get_module_conformance_tests_folder(self, module_name: str) -> str:
+        if self._resolve_module_tests_folder is not None:
+            resolved = self._resolve_module_tests_folder(module_name)
+            if resolved is not None:
+                return resolved
         return get_module_tests_folder(self.modules_base_folder, module_name)
 
     def _get_full_conformance_tests_definition_file_name(self, module_name: str) -> str:
@@ -29,21 +39,48 @@ class ConformanceTests:
             self.conformance_tests_definition_file_name,
         )
 
+    def _resolve_folder_names(self, module_name: str, conformance_tests_json: dict) -> dict:
+        """Turn each entry's on-disk relative ``folder_name`` into an absolute path rooted at the
+        module's (resolved) tests folder. An already-absolute value is left as-is, so archives
+        written by older builds still load."""
+        base = self.get_module_conformance_tests_folder(module_name)
+        resolved: dict = {}
+        for frid, entry in conformance_tests_json.items():
+            if isinstance(entry, dict) and "folder_name" in entry:
+                entry = {**entry, "folder_name": os.path.join(base, entry["folder_name"])}
+            resolved[frid] = entry
+        return resolved
+
+    def _relativize_folder_names(self, module_name: str, conformance_tests_json: dict) -> dict:
+        """Turn each entry's absolute in-memory ``folder_name`` into a path relative to the module's
+        tests folder, so the stored definition is location-independent (portable across projects and
+        usable from a "<module>.module" archive). Does not mutate the input dict."""
+        base = self.get_module_conformance_tests_folder(module_name)
+        serializable: dict = {}
+        for frid, entry in conformance_tests_json.items():
+            if isinstance(entry, dict) and "folder_name" in entry:
+                entry = {**entry, "folder_name": os.path.relpath(entry["folder_name"], base)}
+            serializable[frid] = entry
+        return serializable
+
     def get_conformance_tests_json(self, module_name: str) -> dict:
         try:
             with open(self._get_full_conformance_tests_definition_file_name(module_name), "r") as f:
-                return json.load(f)
+                conformance_tests_json = json.load(f)
         except FileNotFoundError:
             return {}
+        return self._resolve_folder_names(module_name, conformance_tests_json)
 
     def dump_conformance_tests_json(self, module_name: str, conformance_tests_json: dict) -> None:
-        """Dump the conformance tests definition to the file."""
+        """Dump the conformance tests definition to the file. Folder names are stored relative to the
+        module's tests folder so the definition is portable and works from a scratch extraction."""
         if os.path.exists(self.get_module_conformance_tests_folder(module_name)):
             console.debug(
                 f"Storing conformance tests definition to {self._get_full_conformance_tests_definition_file_name(module_name)}"
             )
+            serializable = self._relativize_folder_names(module_name, conformance_tests_json)
             with open(self._get_full_conformance_tests_definition_file_name(module_name), "w") as f:
-                json.dump(conformance_tests_json, f, indent=4)
+                json.dump(serializable, f, indent=4)
 
     def fetch_existing_conformance_test_folder_names(self, module_name: str) -> list[str]:
         if os.path.isdir(self.get_module_conformance_tests_folder(module_name)):

render_machine/implementation_code_helpers.py

@@ -8,8 +8,12 @@ import plain_spec
 class ImplementationCodeHelpers:
     @staticmethod
     def calculate_build_folder_hash(build_folder: str) -> str:
+        # Hash the code content only (relative paths + file contents), NOT the build folder's
+        # absolute path, so the hash is stable across directories and machines. This is required for
+        # distributable "<module>.module" archives: a module's code hash must match regardless of
+        # where plain_modules/ lives, or consuming an archive elsewhere falsely reports a code change.
         _, existing_files_content = ImplementationCodeHelpers.fetch_existing_files(build_folder)
-        return plain_spec.hash_text(f"folder={build_folder}|{json.dumps(existing_files_content)}")
+        return plain_spec.hash_text(json.dumps(existing_files_content))
 
     @staticmethod
     def fetch_existing_files(build_folder: str):

render_machine/render_context.py

@@ -87,10 +87,22 @@ class RenderContext:
         self.conformance_tests_running_context: Optional[ConformanceTestsRunningContext] = None
         # Constants that should remain for a single frid, but possible over multiple rerenderings of the same frid
         self.functional_requirements_render_attempts_failed_unit_during_conformance_tests = 0
-        # Initialize conformance tests utilities
+
+        # Initialize conformance tests utilities. The resolver lets a required module that ships
+        # as a "<module>.module" archive resolve to its scratch extraction (via materialize())
+        # rather than the non-existent default plain_modules/<module>/tests path.
+        def _resolve_module_tests_folder(module_name: str) -> Optional[str]:
+            if module_name == plain_module.module_name:
+                return plain_module.module_conformance_tests_folder
+            for required_module in plain_module.all_required_modules:
+                if required_module.module_name == module_name:
+                    return required_module.module_conformance_tests_folder
+            return None
+
         self.conformance_tests = ConformanceTests(
             modules_base_folder=plain_module.build_folder,
             conformance_tests_definition_file_name=CONFORMANCE_TESTS_DEFINITION_FILE_NAME,
+            resolve_module_tests_folder=_resolve_module_tests_folder,
         )
 
         self.machine = None

system_config.py

@@ -1,5 +1,6 @@
 import importlib.resources
 import os
+import re
 import sys
 
 import yaml
@@ -10,6 +11,15 @@ ENVIRONMENT_VAR = "CODEPLAIN_ENV"
 PRODUCTION_ENV = "production"
 DEVELOPMENT_ENV = "development"
 
+PRODUCTION_API_URL = "https://api.codeplain.ai"
+TEST_API_URL = "https://api.test.codeplain.ai"
+
+# PEP 440 pre-release markers, matched against the end of the release segment:
+# alpha/beta/release-candidate (0.4.0a1, 0.4.0b2, 0.4.0rc1) or a dev release
+# (0.3.10.dev7, published on every merge to main). ".postN" alone is NOT a
+# pre-release and must not match.
+_PRERELEASE_RE = re.compile(r"(?:a|b|rc)\d+$|\.dev\d+$", re.IGNORECASE)
+
 
 def _resolve_version() -> str:
     """Resolve the client version.
@@ -79,9 +89,33 @@ def _resolve_environment(installed: bool) -> str:
     return PRODUCTION_ENV if installed else DEVELOPMENT_ENV
 
 
+def _is_prerelease(version: str) -> bool:
+    """Return True if ``version`` is a PEP 440 pre-release (alpha, beta, rc or dev).
+
+    Deliberately dependency-free rather than using ``packaging``: that library
+    is not a runtime dependency (it only reaches this checkout via dev tools),
+    so it is absent from a real user install. The only versions that reach here
+    are the ones our own build pipeline produces.
+    """
+    # Drop any local version segment ("+gb710c298") before inspecting.
+    return _PRERELEASE_RE.search(version.split("+", 1)[0]) is not None
+
+
+def _resolve_default_api_url(version: str) -> str:
+    """Resolve the API this client talks to when ``--api`` is not given.
+
+    Pre-release builds — the dev build published on every merge to main, and
+    any alpha/beta/rc release — default to the test API, so an unreleased
+    client is exercised against the unreleased backend. Stable releases default
+    to production. ``--api`` always wins over this.
+    """
+    return TEST_API_URL if _is_prerelease(version) else PRODUCTION_API_URL
+
+
 __version__ = _resolve_version()
 __installed__ = _resolve_installed()
 __environment__ = _resolve_environment(__installed__)
+__default_api_url__ = _resolve_default_api_url(__version__)
 
 
 class SystemConfig:
@@ -95,6 +129,7 @@ class SystemConfig:
         self.client_version = __version__
         self.installed = __installed__
         self.environment = __environment__
+        self.default_api_url = __default_api_url__
         self.error_messages = self.config["error_messages"]
 
     def _load_config(self):

tests/test_cli_output.py

@@ -1,5 +1,6 @@
 """Unit tests for cli_output module."""
 
+from datetime import datetime, timezone
 from unittest.mock import Mock, patch
 
 from cli_output.status import (
@@ -10,6 +11,14 @@ from cli_output.status import (
     print_status,
 )
 
+FROZEN_NOW = datetime(2025, 6, 15, 12, 0, tzinfo=timezone.utc)
+
+
+class FrozenDatetime(datetime):
+    @classmethod
+    def now(cls, tz=None):
+        return FROZEN_NOW if tz is None else FROZEN_NOW.astimezone(tz)
+
 
 class TestProgressBar:
     """Tests for _create_progress_bar function."""
@@ -52,6 +61,7 @@ class TestProgressBar:
         assert bar == "█" * 5 + "░" * 5
 
 
+@patch("cli_output.status.datetime", FrozenDatetime)
 class TestDisplayCreditLine:
     """Tests for _display_credit_line function."""
 
@@ -132,6 +142,7 @@ class TestDisplayCreditLine:
         mock_console.print.assert_called_once()
 
 
+@patch("cli_output.status.datetime", FrozenDatetime)
 class TestDisplayBucketCreditLine:
     """Tests for _display_bucket_credit_line function."""
 
@@ -192,6 +203,7 @@ class TestDisplayBucketCreditLine:
         mock_console.print.assert_called_once()
 
 
+@patch("cli_output.status.datetime", FrozenDatetime)
 class TestDisplayStatusMessage:
     """Tests for _display_status_message function."""
 
@@ -271,6 +283,7 @@ class TestDisplayStatusMessage:
         assert "No rendering credits remaining" in call_args
 
 
+@patch("cli_output.status.datetime", FrozenDatetime)
 class TestPrintStatus:
     """Tests for print_status function."""