agents-md-compiler 0.1.0__py3-none-any.whl

agents_md_compiler/__init__.py

@@ -0,0 +1,127 @@
+"""Deterministic compiler for a single global ``AGENTS.md`` policy bundle.
+
+The public surface is intentionally small. Pure computation (manifest parsing,
+source validation, locking, rendering, state comparison) lives here; every
+filesystem mutation lives in :mod:`agents_md_compiler.installation` so a library
+consumer cannot confuse rendering with installing.
+
+Typical read-only use::
+
+    from pathlib import Path
+    from agents_md_compiler import compile_bundle, load_manifest
+
+    manifest = load_manifest(Path("global-agents.toml").absolute())
+    compiled = compile_bundle(manifest)
+    rendered_bytes = compiled.rendered.data
+"""
+
+from agents_md_compiler._version import distribution_version
+from agents_md_compiler.codex import (
+    CodexCapability,
+    RuntimeVerification,
+    detect_capability,
+    verify_rendered_visibility,
+)
+from agents_md_compiler.errors import (
+    CodexVerificationError,
+    CompilerError,
+    ConcurrentChangeError,
+    LockError,
+    LockMissingError,
+    LockStaleError,
+    ManifestError,
+    MutationError,
+    OutputExistsError,
+    ReceiptError,
+    RenderError,
+    ShadowedError,
+    SourceError,
+    TargetError,
+    UnmanagedTargetError,
+    UsageError,
+)
+from agents_md_compiler.lockfile import build_lock, load_lock, serialize_lock
+from agents_md_compiler.manifest import load_manifest
+from agents_md_compiler.models import (
+    LOCK_FORMAT_VERSION,
+    MANIFEST_SCHEMA_VERSION,
+    RECEIPT_SCHEMA_VERSION,
+    RENDER_FORMAT_VERSION,
+    BundleLimits,
+    BundleLock,
+    BundleManifest,
+    BundleState,
+    BundleStatus,
+    CompiledBundle,
+    LockedModule,
+    ModuleSpec,
+    OverrideInspection,
+    RenderedBundle,
+    SourceSnapshot,
+    TargetInspection,
+    TargetKind,
+)
+from agents_md_compiler.rendering import render_bundle, validate_rendered
+from agents_md_compiler.sources import read_source, read_sources
+from agents_md_compiler.state import (
+    compile_bundle,
+    evaluate,
+    inspect_override,
+    inspect_target,
+)
+
+__all__ = [
+    "LOCK_FORMAT_VERSION",
+    "MANIFEST_SCHEMA_VERSION",
+    "RECEIPT_SCHEMA_VERSION",
+    "RENDER_FORMAT_VERSION",
+    "BundleLimits",
+    "BundleLock",
+    "BundleManifest",
+    "BundleState",
+    "BundleStatus",
+    "CodexCapability",
+    "CodexVerificationError",
+    "CompiledBundle",
+    "CompilerError",
+    "ConcurrentChangeError",
+    "LockError",
+    "LockMissingError",
+    "LockStaleError",
+    "LockedModule",
+    "ManifestError",
+    "ModuleSpec",
+    "MutationError",
+    "OutputExistsError",
+    "OverrideInspection",
+    "ReceiptError",
+    "RenderError",
+    "RenderedBundle",
+    "RuntimeVerification",
+    "ShadowedError",
+    "SourceError",
+    "SourceSnapshot",
+    "TargetError",
+    "TargetInspection",
+    "TargetKind",
+    "UnmanagedTargetError",
+    "UsageError",
+    "__version__",
+    "build_lock",
+    "compile_bundle",
+    "detect_capability",
+    "distribution_version",
+    "evaluate",
+    "inspect_override",
+    "inspect_target",
+    "load_lock",
+    "load_manifest",
+    "read_source",
+    "read_sources",
+    "render_bundle",
+    "serialize_lock",
+    "validate_rendered",
+    "verify_rendered_visibility",
+]
+
+__version__ = distribution_version()

agents_md_compiler/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point so ``python -m agents_md_compiler`` matches the console script."""
+
+from agents_md_compiler.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agents_md_compiler/_version.py

@@ -0,0 +1,28 @@
+"""Installed distribution version discovery.
+
+The compiler reports its own version from installed package metadata rather than
+from a hard-coded string, so a wheel and its metadata can never disagree. The
+version deliberately never enters rendered output: a tool upgrade must not change
+policy bytes when the format, manifest, lock, and modules are identical.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+DISTRIBUTION_NAME = "agents-md-compiler"
+"""Distribution name used for metadata lookup."""
+
+UNKNOWN_VERSION = "0.0.0+unknown"
+"""Reported when the package is not installed, as in a bare source checkout."""
+
+
+def distribution_version() -> str:
+    """Report the installed distribution version.
+
+    Returns:
+        The version from installed package metadata, or ``0.0.0+unknown`` when no
+        installed distribution provides it.
+    """
+    try:
+        return version(DISTRIBUTION_NAME)
+    except PackageNotFoundError:
+        return UNKNOWN_VERSION

agents_md_compiler/atomic.py

@@ -0,0 +1,135 @@
+"""Atomic same-filesystem file replacement.
+
+An interrupted write must leave either the complete old bytes or the complete new
+bytes, never a partial file. The sequence is: create a temporary file in the
+target's own directory, write it, flush it, ``fsync`` it, apply the intended mode,
+atomically replace the target, then ``fsync`` the containing directory where the
+platform supports it.
+
+The temporary file must share the target's directory because ``os.replace`` is
+atomic only within one filesystem. A temporary directory elsewhere would silently
+degrade to a copy.
+"""
+
+import os
+import tempfile
+from pathlib import Path
+
+from agents_md_compiler.errors import MutationError, MutationProblem
+
+TEMP_PREFIX = ".agents-md-compiler-"
+"""Prefix for the same-directory temporary file, so a leftover is identifiable."""
+
+TEMP_SUFFIX = ".tmp"
+"""Suffix for the same-directory temporary file."""
+
+
+def sync_directory(directory: Path) -> bool:
+    """Flush a directory entry to stable storage where supported.
+
+    Windows cannot open a directory as a file descriptor, so this is a documented
+    best effort rather than a guarantee. The replacement itself is still atomic;
+    only the durability of the rename across a crash is platform-dependent.
+
+    Args:
+        directory: Directory whose entries were changed.
+
+    Returns:
+        ``True`` when the directory was synced, ``False`` when the platform does not
+        support it.
+    """
+    try:
+        descriptor = os.open(directory, os.O_RDONLY)
+    except OSError:
+        return False
+    try:
+        os.fsync(descriptor)
+    except OSError:
+        return False
+    finally:
+        os.close(descriptor)
+    return True
+
+
+def atomic_write(target: Path, data: bytes, *, mode: int) -> bool:
+    """Replace a file's contents atomically.
+
+    Args:
+        target: Destination path. Its parent directory must already exist.
+        data: Exact bytes to write.
+        mode: Permission bits to apply to the new file.
+
+    Returns:
+        ``True`` when the containing directory was also synced.
+
+    Raises:
+        MutationError: Any step failed. The temporary file is removed first, so a
+            failure never leaves a partial file behind and never damages the target.
+    """
+    directory = target.parent
+    try:
+        descriptor, temp_name = tempfile.mkstemp(
+            dir=directory, prefix=TEMP_PREFIX, suffix=TEMP_SUFFIX
+        )
+    except OSError as error:
+        raise MutationError(
+            MutationProblem.WRITE_FAILED,
+            path=target,
+            detail=error.strerror or type(error).__name__,
+        ) from error
+    temporary = Path(temp_name)
+    try:
+        try:
+            with os.fdopen(descriptor, "wb") as stream:
+                stream.write(data)
+                stream.flush()
+                os.fsync(stream.fileno())
+        except OSError as error:
+            raise MutationError(
+                MutationProblem.SYNC_FAILED,
+                path=target,
+                detail=error.strerror or type(error).__name__,
+            ) from error
+        try:
+            temporary.chmod(mode)
+        except OSError as error:
+            raise MutationError(
+                MutationProblem.PERMISSION_FAILED,
+                path=target,
+                detail=error.strerror or type(error).__name__,
+            ) from error
+        try:
+            temporary.replace(target)
+        except OSError as error:
+            raise MutationError(
+                MutationProblem.REPLACE_FAILED,
+                path=target,
+                detail=error.strerror or type(error).__name__,
+            ) from error
+    except MutationError:
+        temporary.unlink(missing_ok=True)
+        raise
+    return sync_directory(directory)
+
+
+def create_state_directory(directory: Path, *, mode: int) -> None:
+    """Create a state directory tree with owner-only access.
+
+    An existing directory's mode is left alone, so a more restrictive operator
+    choice is never broadened.
+
+    Args:
+        directory: Directory to create, including parents.
+        mode: Mode applied to directories this call creates.
+
+    Raises:
+        MutationError: The directory could not be created.
+    """
+    try:
+        directory.mkdir(parents=True, exist_ok=True, mode=mode)
+    except OSError as error:
+        raise MutationError(
+            MutationProblem.STATE_ROOT_FAILED,
+            path=directory,
+            detail=error.strerror or type(error).__name__,
+        ) from error