moonlit 0.1.0__py3-none-any.whl

moonlit/__init__.py

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

moonlit/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m moonlit`` shim — delegates to :func:`moonlit.cli.main`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

moonlit/_bootstrap/__init__.py

@@ -0,0 +1,78 @@
+"""moonlit zipapp bootstrap (stdlib-only, D7).
+
+Shipped verbatim into every produced .pyz; runs before staged site-packages
+reaches sys.path. The :func:`bootstrap` orchestrator below is invoked by the
+generated ``__main__.py`` inside the .pyz:
+
+    import sys
+    from _bootstrap import bootstrap
+    sys.exit(bootstrap())
+
+Contract: specs/03-bootstrap-runtime.md §2 (operations), §3 (cache root),
+§10 (error model). Exit codes per D3 runtime enumeration.
+"""
+
+import os
+import sys
+import traceback
+import zipfile
+from pathlib import Path
+
+from . import environment, extract, runner
+from .errors import ArchiveError, BootstrapError
+
+
+def bootstrap() -> int:
+    """Bootstrap entry point. Returns an int in [0, 255] for ``sys.exit``."""
+    try:
+        return _do_bootstrap()
+    except BootstrapError as exc:
+        print(f"moonlit: {exc}", file=sys.stderr)
+        if _debug():
+            traceback.print_exc(file=sys.stderr)
+        return exc.exit_code
+
+
+# ---------- internal orchestration, in bootstrap()'s call order ----------
+
+
+def _do_bootstrap() -> int:
+    archive = _resolve_archive()
+    env = environment.load(archive)
+    cache_root = _resolve_cache_root()
+    _ensure_cache_root_exists(cache_root)
+    site_dir = extract.materialize(env, cache_root, archive)
+    return runner.run(env, site_dir)
+
+
+def _resolve_archive() -> str:
+    if not sys.argv or not sys.argv[0]:
+        raise ArchiveError("cannot locate zipapp (sys.argv[0] is empty)")
+    archive = os.path.abspath(sys.argv[0])
+    if not zipfile.is_zipfile(archive):
+        raise ArchiveError(f"not a moonlit zipapp: {archive}")
+    return archive
+
+
+def _resolve_cache_root() -> Path:
+    # D16: present and non-empty after os.environ.get is truthy.
+    override = os.environ.get("MOONLIT_ROOT", "")
+    if override:
+        return Path(override).expanduser().resolve()
+    if os.name == "nt":
+        local_app_data = os.environ.get("LOCALAPPDATA", "")
+        if local_app_data:
+            return Path(local_app_data) / "moonlit"
+    return Path.home() / ".moonlit"
+
+
+def _ensure_cache_root_exists(cache_root: Path) -> None:
+    try:
+        os.makedirs(cache_root, exist_ok=True)
+    except OSError as exc:
+        raise BootstrapError(f"cannot create cache root {cache_root}: {exc}") from exc
+
+
+def _debug() -> bool:
+    # D16: present and non-empty after os.environ.get is truthy.
+    return bool(os.environ.get("MOONLIT_DEBUG", ""))

moonlit/_bootstrap/environment.py

@@ -0,0 +1,170 @@
+"""Validate and load env.json from a moonlit zipapp.
+
+Implements the D8 9-step ordered validation (specs/05-env-json-schema.md §4)
+and the per-field format checks (§3). Every failure raises EnvJsonError; the
+bootstrap entry point translates it to runtime exit code 1 (D3).
+"""
+
+import json
+import re
+import zipfile
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from .errors import EnvJsonError
+
+_REQUIRED_FIELDS: tuple[str, ...] = (
+    "name",
+    "build_id",
+    "entry_point",
+    "built_at",
+    "moonlit_version",
+    "python_shebang",
+)
+
+# D11: PEP 508 name regex. The re.IGNORECASE flag is mandatory.
+_PEP508_NAME = re.compile(
+    r"^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$",
+    re.IGNORECASE,
+)
+
+_BUILD_ID = re.compile(r"^[0-9a-f]{64}$")
+
+# entry_point each side: dotted Python identifier; no whitespace.
+_ENTRY_POINT_SIDE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$")
+
+
+@dataclass(frozen=True)
+class Environment:
+    schema_version: int
+    name: str
+    build_id: str
+    entry_point: str
+    built_at: str
+    moonlit_version: str
+    python_shebang: str
+
+
+def load(archive_path: str | Path) -> Environment:
+    """Read env.json from ``archive_path``, validate per D8, return Environment."""
+    raw = _read_env_bytes(archive_path)
+    text = _decode_utf8(raw)
+    parsed = _parse_json(text)
+    _ensure_dict(parsed)
+    _check_schema_version(parsed)
+    _check_required_fields_present(parsed)
+    _check_required_field_types(parsed)
+    _check_field_formats(parsed)
+    return Environment(
+        schema_version=parsed["schema_version"],
+        name=parsed["name"],
+        build_id=parsed["build_id"],
+        entry_point=parsed["entry_point"],
+        built_at=parsed["built_at"],
+        moonlit_version=parsed["moonlit_version"],
+        python_shebang=parsed["python_shebang"],
+    )
+
+
+# ---------- D8 steps, in load()'s call order ----------
+
+
+def _read_env_bytes(archive_path: str | Path) -> bytes:
+    try:
+        with zipfile.ZipFile(archive_path, "r") as zf:
+            try:
+                return zf.read("env.json")
+            except KeyError as exc:
+                raise EnvJsonError("env.json missing from archive") from exc
+    except (zipfile.BadZipFile, OSError) as exc:
+        raise EnvJsonError(f"archive unreadable: {archive_path}") from exc
+
+
+def _decode_utf8(raw: bytes) -> str:
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise EnvJsonError("env.json is not valid UTF-8") from exc
+
+
+def _parse_json(text: str) -> object:
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise EnvJsonError("env.json is not valid JSON") from exc
+
+
+def _ensure_dict(parsed: object) -> None:
+    if not isinstance(parsed, dict):
+        raise EnvJsonError("env.json must be a JSON object")
+
+
+def _check_schema_version(parsed: dict) -> None:
+    if "schema_version" not in parsed:
+        raise EnvJsonError("env.json: schema_version missing or not an integer")
+    v = parsed["schema_version"]
+    # bool is a subclass of int in Python; reject explicitly per D8 step 5.
+    if not isinstance(v, int) or isinstance(v, bool):
+        raise EnvJsonError("env.json: schema_version missing or not an integer")
+    if v != 1:
+        raise EnvJsonError(
+            f"env.json: unsupported schema_version {v}; "
+            f"upgrade moonlit to a version that supports env.json schema version {v}"
+        )
+
+
+def _check_required_fields_present(parsed: dict) -> None:
+    for field in _REQUIRED_FIELDS:
+        if field not in parsed:
+            raise EnvJsonError(f"env.json: missing required field '{field}'")
+
+
+def _check_required_field_types(parsed: dict) -> None:
+    for field in _REQUIRED_FIELDS:
+        value = parsed[field]
+        # bool is rejected here because every string-typed field below
+        # is declared "string" in spec §2; True/False are not strings.
+        if not isinstance(value, str):
+            raise EnvJsonError(f"env.json: field '{field}' has wrong type (expected string)")
+
+
+def _check_field_formats(parsed: dict) -> None:
+    if not _PEP508_NAME.match(parsed["name"]):
+        raise EnvJsonError("env.json: field 'name' failed validation")
+    if not _BUILD_ID.fullmatch(parsed["build_id"]):
+        raise EnvJsonError("env.json: field 'build_id' failed validation")
+    if not _is_valid_entry_point(parsed["entry_point"]):
+        raise EnvJsonError("env.json: field 'entry_point' failed validation")
+    if not _is_valid_built_at(parsed["built_at"]):
+        raise EnvJsonError("env.json: field 'built_at' failed validation")
+    if not parsed["moonlit_version"]:
+        raise EnvJsonError("env.json: field 'moonlit_version' failed validation")
+    if not _is_valid_shebang(parsed["python_shebang"]):
+        raise EnvJsonError("env.json: field 'python_shebang' failed validation")
+
+
+def _is_valid_entry_point(value: str) -> bool:
+    parts = value.split(":")
+    if len(parts) != 2:
+        return False
+    lhs, rhs = parts
+    return bool(_ENTRY_POINT_SIDE.fullmatch(lhs) and _ENTRY_POINT_SIDE.fullmatch(rhs))
+
+
+def _is_valid_built_at(value: str) -> bool:
+    try:
+        datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")
+    except ValueError:
+        return False
+    return True
+
+
+def _is_valid_shebang(value: str) -> bool:
+    if not value:
+        return False
+    if "\n" in value:
+        return False
+    if value.startswith("#!"):
+        return False
+    return True

moonlit/_bootstrap/errors.py

@@ -0,0 +1,48 @@
+"""Error hierarchy for the bootstrap.
+
+Each subclass carries a stable ``exit_code`` per the D3 runtime enumeration
+(specs/03-bootstrap-runtime.md §0). The bootstrap entry point catches
+BootstrapError and translates ``exit_code`` into the process exit status.
+"""
+
+
+class BootstrapError(Exception):
+    """Base class for bootstrap-internal failures."""
+
+    exit_code: int = 1
+
+
+class EnvJsonError(BootstrapError):
+    """env.json missing, archive unreadable, or D8 validation failure (exit 1)."""
+
+    exit_code = 1
+
+
+class LockTimeoutError(BootstrapError):
+    """Lock acquisition exceeded the wall-clock timeout (exit 3)."""
+
+    exit_code = 3
+
+
+class ExtractionError(BootstrapError):
+    """Archive extraction failure or unsafe arcname (exit 1)."""
+
+    exit_code = 1
+
+
+class CollisionError(BootstrapError):
+    """``_bootstrap`` collision in the staged site-packages tree (exit 1)."""
+
+    exit_code = 1
+
+
+class EntryPointError(BootstrapError):
+    """Entry-point parse, import, attribute, or return-value coercion failure (exit 2)."""
+
+    exit_code = 2
+
+
+class ArchiveError(BootstrapError):
+    """Archive resolution failed: empty sys.argv[0] or path is not a zipfile (exit 1)."""
+
+    exit_code = 1

moonlit/_bootstrap/extract.py

@@ -0,0 +1,202 @@
+"""Extract archive site-packages into the per-build cache.
+
+Implements the D14 fast-path / slow-path protocol, the D4 atomic-replace
+directory swap, the D5 cache-key derivation, and the D1 arcname rule
+(specs/03-bootstrap-runtime.md §6).
+
+The single function that calls os.rename is named ``atomic_replace_dir``;
+the D7 stdlib-only gate's allowlist is keyed on that exact name.
+"""
+
+import os
+import posixpath
+import re
+import shutil
+import zipfile
+from pathlib import Path
+from time import sleep
+
+from .environment import Environment
+from .errors import ExtractionError
+from .locking import lock
+
+_OS_REPLACE_RETRIES = 3
+_OS_REPLACE_BACKOFF_S = 0.1
+
+
+def materialize(
+    env: Environment,
+    cache_root: Path,
+    archive_path: str | Path,
+) -> Path:
+    """Ensure the cache for ``env`` is populated; return the site-packages dir.
+
+    Implements the D14 protocol: an unsynchronized fast-path read for the
+    common cache-hit case, falling back to a locked slow path that extracts
+    under the D4 atomic-replace dance and sweeps stale ``.old.<pid>`` siblings.
+    """
+    cache_key = _cache_key(env)
+    site_parent = cache_root / cache_key
+    site_dir = site_parent / "site-packages"
+
+    # D14 fast path: no lock if cache hit and FORCE_EXTRACT unset.
+    if site_dir.is_dir() and not _force_extract():
+        return site_dir
+
+    lock_path = cache_root / f"{cache_key}.lock"
+    with lock(lock_path):
+        # Re-check inside the lock; a sibling may have just won the race.
+        if site_dir.is_dir() and not _force_extract():
+            return site_dir
+
+        tmp_dir = cache_root / f".{cache_key}.tmp.{os.getpid()}"
+        try:
+            _extract_to(archive_path, tmp_dir)
+            atomic_replace_dir(tmp_dir, site_parent, os.getpid())
+        finally:
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
+        _sweep_old_siblings(site_parent)
+
+    return site_dir
+
+
+def atomic_replace_dir(src: Path, dst: Path, pid: int) -> None:
+    """D4 protocol: rename existing ``dst`` aside, replace, clean up.
+
+    The ``os.rename`` calls in this function are intentional and audited; the
+    bootstrap stdlib gate (test_bootstrap_stdlib_only.py) keys its allowlist
+    on this exact function name.
+    """
+    old_path: Path | None = None
+    if dst.exists():
+        old_path = dst.with_name(f"{dst.name}.old.{pid}")
+        os.rename(dst, old_path)
+    try:
+        _replace_with_retry(src, dst)
+    except Exception:
+        if old_path is not None and old_path.exists():
+            os.rename(old_path, dst)
+        raise
+    if old_path is not None:
+        shutil.rmtree(old_path, ignore_errors=True)
+
+
+# ---------- private helpers, in materialize()'s call order ----------
+
+
+def _cache_key(env: Environment) -> str:
+    # D5: PEP 503 normalize the raw env.json name; build_id is already
+    # lowercase hex per spec 05 §3.3.
+    normalized = re.sub(r"[-_.]+", "-", env.name).lower()
+    return f"{normalized}_{env.build_id}"
+
+
+def _force_extract() -> bool:
+    # D16: present and non-empty after os.environ.get is truthy.
+    # MOONLIT_FORCE_EXTRACT="0" is non-empty hence truthy (spec 03 §9).
+    return bool(os.environ.get("MOONLIT_FORCE_EXTRACT", ""))
+
+
+def _extract_to(archive_path: str | Path, tmp_dir: Path) -> None:
+    if tmp_dir.exists():
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+    tmp_site_packages = tmp_dir / "site-packages"
+    tmp_site_packages.mkdir(parents=True, exist_ok=False)
+
+    with zipfile.ZipFile(archive_path, "r") as zf:
+        for info in zf.infolist():
+            arcname = info.filename
+            if not arcname.startswith("site-packages/"):
+                continue  # D1: only the site-packages/ prefix is extracted.
+            rel = arcname[len("site-packages/") :]
+            if not rel:
+                continue  # bare directory marker
+            normalized = posixpath.normpath(rel)
+            _reject_unsafe_path(arcname, normalized)
+            dest = tmp_site_packages / normalized
+            _extract_one(zf, info, dest)
+
+
+def _reject_unsafe_path(arcname: str, normalized: str) -> None:
+    if normalized.startswith("/") or ".." in normalized.split("/"):
+        raise ExtractionError(
+            f"archive entry has unsafe path after normalization: {arcname!r} -> {normalized!r}"
+        )
+
+
+def _extract_one(zf: zipfile.ZipFile, info: zipfile.ZipInfo, dest: Path) -> None:
+    if info.is_dir():
+        dest.mkdir(parents=True, exist_ok=True)
+        return
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    mode = info.external_attr >> 16
+    is_symlink = (mode & 0o170000) == 0o120000
+
+    if is_symlink:
+        _extract_symlink(zf, info, dest)
+        return
+
+    with zf.open(info, "r") as src, open(dest, "wb") as out:
+        shutil.copyfileobj(src, out)
+    if mode and os.name != "nt":
+        try:
+            os.chmod(dest, mode & 0o7777)
+        except OSError:
+            pass  # best-effort per spec §11
+
+
+def _extract_symlink(zf: zipfile.ZipFile, info: zipfile.ZipInfo, dest: Path) -> None:
+    target = zf.read(info).decode("utf-8")
+    if os.name != "nt":
+        os.symlink(target, dest)
+        return
+    # Windows: follow the link target inside the archive and write resolved
+    # bytes as a regular file (spec 03 §6 step 2).
+    resolved = _resolve_archive_path(info.filename, target)
+    try:
+        target_info = zf.getinfo(resolved)
+    except KeyError as exc:
+        raise ExtractionError(
+            f"symlink target not in archive: {info.filename!r} -> {target!r}"
+        ) from exc
+    with zf.open(target_info, "r") as src, open(dest, "wb") as out:
+        shutil.copyfileobj(src, out)
+
+
+def _resolve_archive_path(src_filename: str, target: str) -> str:
+    if posixpath.isabs(target):
+        return target.lstrip("/")
+    return posixpath.normpath(posixpath.join(posixpath.dirname(src_filename), target))
+
+
+def _replace_with_retry(src: Path, dst: Path) -> None:
+    """3-attempt retry around ``os.replace`` to ride out transient holds.
+
+    On Windows, AV/EDR may briefly hold extracted DLLs open (spec §6 step 4).
+    """
+    last: OSError | None = None
+    for attempt in range(_OS_REPLACE_RETRIES):
+        try:
+            os.replace(src, dst)
+            return
+        except OSError as exc:
+            last = exc
+            if attempt < _OS_REPLACE_RETRIES - 1:
+                sleep(_OS_REPLACE_BACKOFF_S)
+    raise ExtractionError(
+        f"os.replace({src} -> {dst}) failed after {_OS_REPLACE_RETRIES} "
+        f"attempts: errno={last.errno if last else '?'} {last}"
+    ) from last
+
+
+def _sweep_old_siblings(site_parent: Path) -> None:
+    """Best-effort cleanup of stale ``.old.<pid>`` siblings (D4)."""
+    parent = site_parent.parent
+    if not parent.is_dir():
+        return
+    prefix = f"{site_parent.name}.old."
+    for entry in parent.iterdir():
+        if entry.name.startswith(prefix):
+            shutil.rmtree(entry, ignore_errors=True)

moonlit/_bootstrap/locking.py

@@ -0,0 +1,64 @@
+"""Sentinel-file locking for the bootstrap (D13).
+
+A lock acquired via O_CREAT|O_EXCL|O_RDWR with polling. Timeout is 60 s
+wall clock; poll interval is 50 ms; the first attempt has no preceding
+sleep (specs/03-bootstrap-runtime.md §5).
+
+Stale-lock recovery is manual: ``rm <lock_path>``. A real flock /
+msvcrt.LK_NBLCK implementation is deferred to v0.2.
+
+``sleep`` and ``monotonic`` are imported as bare names so tests can
+monkeypatch them on this module without affecting the rest of the process.
+"""
+
+import contextlib
+import os
+from collections.abc import Iterator
+from pathlib import Path
+from time import monotonic, sleep
+
+from .errors import LockTimeoutError
+
+_TIMEOUT_S: float = 60.0
+_POLL_INTERVAL_S: float = 0.050
+
+
+def acquire(lock_path: str | Path) -> int:
+    """Acquire the sentinel lock at ``lock_path``; return the open fd.
+
+    Polls with O_CREAT|O_EXCL until the file can be created or the timeout
+    elapses. Raises :class:`LockTimeoutError` after the wall-clock timeout.
+    """
+    flags = os.O_CREAT | os.O_EXCL | os.O_RDWR
+    deadline = monotonic() + _TIMEOUT_S
+    while True:
+        try:
+            return os.open(lock_path, flags, 0o600)
+        except FileExistsError:
+            if monotonic() >= deadline:
+                # `from None` because the FileExistsError is the expected polling
+                # signal, not an underlying cause to surface to the user.
+                raise LockTimeoutError(
+                    f"lock acquisition timed out ({_TIMEOUT_S:g}s) at {lock_path}; "
+                    f"remove this file or set MOONLIT_FORCE_EXTRACT=1"
+                ) from None
+            sleep(_POLL_INTERVAL_S)
+
+
+def release(fd: int, lock_path: str | Path) -> None:
+    """Close ``fd`` and unlink ``lock_path``; tolerate an already-removed file."""
+    os.close(fd)
+    try:
+        os.unlink(lock_path)
+    except FileNotFoundError:
+        pass
+
+
+@contextlib.contextmanager
+def lock(lock_path: str | Path) -> Iterator[int]:
+    """Context-manager wrapping :func:`acquire` / :func:`release`."""
+    fd = acquire(lock_path)
+    try:
+        yield fd
+    finally:
+        release(fd, lock_path)

moonlit/_bootstrap/runner.py

@@ -0,0 +1,84 @@
+"""sys.path setup, entry-point resolution, and return-value coercion.
+
+Implements specs/03-bootstrap-runtime.md §7 (collision check, addsitedir)
+and §8 (entry-point parsing, import, getattr walk, invocation, return-value
+coercion). Failures from this module raise either CollisionError (exit 1)
+or EntryPointError (exit 2) per the D3 runtime enumeration.
+"""
+
+import importlib
+import os
+import site
+from pathlib import Path
+
+from .environment import Environment
+from .errors import CollisionError, EntryPointError
+
+
+def run(env: Environment, site_dir: Path) -> int:
+    """Set up sys.path, resolve and invoke the entry point, coerce its return.
+
+    Returns an int in [0, 255] suitable for ``sys.exit``.
+    """
+    _check_no_bootstrap_collision(site_dir)
+    site.addsitedir(str(site_dir))
+    entry_point_str = _resolve_entry_point_string(env)
+    module_name, attr = _parse_entry_point(entry_point_str)
+    obj = _import_and_resolve(module_name, attr)
+    return _coerce_return(obj())
+
+
+# ---------- private helpers, in run()'s call order ----------
+
+
+def _check_no_bootstrap_collision(site_dir: Path) -> None:
+    # spec §7: case-fold compare for Windows / HFS+ case-insensitive filesystems.
+    for entry in os.listdir(site_dir):
+        if entry.casefold() == "_bootstrap":
+            raise CollisionError("_bootstrap collision in staged tree")
+
+
+def _resolve_entry_point_string(env: Environment) -> str:
+    # D16: empty (after os.environ.get default) is treated as unset.
+    override = os.environ.get("MOONLIT_ENTRY_POINT", "")
+    return override if override else env.entry_point
+
+
+def _parse_entry_point(value: str) -> tuple[str, str]:
+    parts = value.split(":")
+    if len(parts) != 2:
+        raise EntryPointError(f"invalid entry point: {value}")
+    module, attr = parts
+    if not module or not attr:
+        raise EntryPointError(f"invalid entry point: {value}")
+    if "" in attr.split("."):
+        raise EntryPointError(f"invalid entry point: {value}")
+    return module, attr
+
+
+def _import_and_resolve(module_name: str, attr: str) -> object:
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as exc:
+        raise EntryPointError(f"cannot import {module_name}: {exc}") from exc
+    obj: object = module
+    for part in attr.split("."):
+        try:
+            obj = getattr(obj, part)
+        except AttributeError as exc:
+            raise EntryPointError(f"attribute {attr} not found on {module_name}") from exc
+    return obj
+
+
+def _coerce_return(result: object) -> int:
+    if result is None:
+        return 0
+    # bool is int in Python; True → 1, False → 0 fall through here (spec §8).
+    if isinstance(result, int):
+        return result & 0xFF
+    try:
+        return int(result) & 0xFF
+    except (TypeError, ValueError) as exc:
+        raise EntryPointError(
+            f"entry point returned uncoercible value: {type(result).__name__}"
+        ) from exc

moonlit/_templates/__init__.py

@@ -0,0 +1 @@
+"""Build-time template resources copied verbatim into produced .pyz files."""

moonlit/_templates/main_py.tmpl

@@ -0,0 +1,3 @@
+import sys
+from _bootstrap import bootstrap
+sys.exit(bootstrap())