specmint 0.1.0a2__py3-none-any.whl

opsdevcode_specmint/__init__.py

@@ -0,0 +1,7 @@
+"""Mint language: offline compiler, CLI, editor, and Integration Protocol v0."""
+
+from __future__ import annotations
+
+from opsdevcode_specmint.version import service_version
+
+__version__ = service_version()

opsdevcode_specmint/__main__.py

@@ -0,0 +1,10 @@
+"""Module entry for the public Mint CLI."""
+
+from __future__ import annotations
+
+import sys
+
+from opsdevcode_specmint.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

opsdevcode_specmint/automation.py

@@ -0,0 +1,158 @@
+"""AutomationSpecification and AutomationIntent contracts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any
+
+from opsdevcode_specmint.contracts import SpecContract
+from opsdevcode_specmint.errors import CompilationFailureError, SpecUnsupportedError
+from opsdevcode_specmint.identity import revision_digest
+from opsdevcode_specmint.pins import (
+    AUTOMATION_API_VERSION,
+    AUTOMATION_INTENT_KIND,
+    AUTOMATION_SPEC_KIND,
+    LOCAL_AUTOMATION_TYPE,
+)
+
+AUTOMATION_SPEC_V1ALPHA1 = SpecContract(AUTOMATION_API_VERSION, AUTOMATION_SPEC_KIND)
+AUTOMATION_INTENT_V1ALPHA1 = SpecContract(AUTOMATION_API_VERSION, AUTOMATION_INTENT_KIND)
+
+_FORBIDDEN_KEY_PARTS = ("password", "secret", "token", "credential", "url", "http")
+
+
+def is_automation_document(document: dict[str, Any]) -> bool:
+    return (
+        document.get("apiVersion") == AUTOMATION_API_VERSION
+        and document.get("kind") == AUTOMATION_SPEC_KIND
+    )
+
+
+def is_automation_intent(document: dict[str, Any]) -> bool:
+    return (
+        document.get("apiVersion") == AUTOMATION_API_VERSION
+        and document.get("kind") == AUTOMATION_INTENT_KIND
+    )
+
+
+def reject_forbidden_fields(value: Any, *, path: str = "document") -> None:
+    if isinstance(value, dict):
+        for key, item in value.items():
+            lowered = str(key).lower()
+            if any(part in lowered for part in _FORBIDDEN_KEY_PARTS):
+                raise SpecUnsupportedError(
+                    f"remove {path}.{key}; credentials and URLs are not accepted in specifications"
+                )
+            reject_forbidden_fields(item, path=f"{path}.{key}")
+        return
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            reject_forbidden_fields(item, path=f"{path}[{index}]")
+        return
+    if isinstance(value, str) and value.lower().startswith(("http://", "https://")):
+        raise SpecUnsupportedError(
+            f"remove URL at {path}; AutomationSpecification placement is a sandbox id"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class AutomationIntent:
+    identity_id: str
+    revision: str
+    owner: str
+    statement: str
+    automation_type: str
+    automation_version: str
+    sandbox: str
+    required_evidence: tuple[str, ...]
+    require_authorization: bool
+    status: str
+
+    def to_canonical_dict(self) -> dict[str, Any]:
+        return {
+            "apiVersion": AUTOMATION_API_VERSION,
+            "kind": AUTOMATION_INTENT_KIND,
+            "identity": {"id": self.identity_id, "revision": self.revision},
+            "source": {
+                "apiVersion": AUTOMATION_API_VERSION,
+                "kind": AUTOMATION_SPEC_KIND,
+                "id": self.identity_id,
+            },
+            "intent": {
+                "owner": self.owner,
+                "statement": self.statement,
+                "automation": {
+                    "type": self.automation_type,
+                    "version": self.automation_version,
+                },
+                "placement": {"sandbox": self.sandbox},
+                "required_evidence": list(self.required_evidence),
+                "constraints": {
+                    "require_authorization": self.require_authorization,
+                    "allow_platform_mutation": False,
+                },
+                "status": self.status,
+            },
+        }
+
+
+def build_automation_intent(closed: dict[str, Any]) -> AutomationIntent:
+    projected = _project_closed_automation(closed)
+    unsigned = replace(projected, revision="")
+    body = unsigned.to_canonical_dict()
+    del body["identity"]["revision"]
+    return replace(projected, revision=revision_digest(body))
+
+
+def _project_closed_automation(closed: dict[str, Any]) -> AutomationIntent:
+    spec = closed.get("spec")
+    metadata = closed.get("metadata")
+    if not isinstance(spec, dict) or not isinstance(metadata, dict):
+        raise CompilationFailureError("Closed automation is missing metadata or spec.")
+    spec_id = metadata.get("id")
+    owner = spec.get("owner")
+    statement = spec.get("intent")
+    automation = spec.get("automation")
+    placement = spec.get("placement")
+    constraints = spec.get("constraints")
+    evidence = spec.get("required_evidence")
+    status = spec.get("status")
+    if not isinstance(spec_id, str) or not spec_id:
+        raise CompilationFailureError("Closed automation is missing metadata.id.")
+    if not isinstance(owner, str) or not isinstance(statement, str):
+        raise CompilationFailureError("Closed automation is missing owner or intent.")
+    if not isinstance(automation, dict) or not isinstance(placement, dict):
+        raise CompilationFailureError("Closed automation is missing automation or placement.")
+    if not isinstance(constraints, dict):
+        raise CompilationFailureError("Closed automation is missing constraints.")
+    automation_type = automation.get("type")
+    automation_version = automation.get("version")
+    sandbox = placement.get("sandbox")
+    require_auth = constraints.get("require_authorization")
+    allow_mutation = constraints.get("allow_platform_mutation")
+    if automation_type != LOCAL_AUTOMATION_TYPE or automation_version != "v1alpha1":
+        raise SpecUnsupportedError(
+            f"Only {LOCAL_AUTOMATION_TYPE} v1alpha1 is accepted in this slice."
+        )
+    if not isinstance(sandbox, str) or not sandbox:
+        raise CompilationFailureError("Closed automation placement.sandbox is incomplete.")
+    if require_auth is not True or allow_mutation is not False:
+        raise CompilationFailureError(
+            "Closed automation must require authorization and forbid platform mutation."
+        )
+    if not isinstance(status, str):
+        raise CompilationFailureError("Closed automation status is incomplete.")
+    if not isinstance(evidence, list) or not all(isinstance(item, str) for item in evidence):
+        raise CompilationFailureError("Closed automation required_evidence is incomplete.")
+    return AutomationIntent(
+        identity_id=spec_id,
+        revision="",
+        owner=owner,
+        statement=statement,
+        automation_type=automation_type,
+        automation_version=automation_version,
+        sandbox=sandbox,
+        required_evidence=tuple(evidence),
+        require_authorization=True,
+        status=status,
+    )

opsdevcode_specmint/cli.py

@@ -0,0 +1,79 @@
+"""Public CLI: mint language plus a thin specmint alias. No serve, execute, or apply."""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import IO, Any, TextIO
+
+from opsdevcode_specmint import __version__
+from opsdevcode_specmint.compiler import inspect_artifact, validate_specification
+from opsdevcode_specmint.errors import SpecProblem
+from opsdevcode_specmint.parse import decode_body, decode_path, media_type_for_format
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    stdin: IO[bytes] | None = None,
+    stdout: TextIO | None = None,
+    stderr: TextIO | None = None,
+) -> int:
+    out = stdout or sys.stdout
+    err = stderr or sys.stderr
+    parser = _build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+    if args.show_version or args.command == "version":
+        out.write(f"specmint {__version__}\n")
+        return 0
+    if args.command is None:
+        parser.print_help(out)
+        return 0
+    try:
+        if args.command == "mint":
+            from opsdevcode_specmint.mint.cli import main as mint_main
+
+            raw_in = b"" if stdin is None else stdin.read()
+            text = raw_in.decode("utf-8") if isinstance(raw_in, bytes | bytearray) else str(raw_in)
+            return mint_main(list(args.mint_args), stdin=io.StringIO(text), stdout=out, stderr=err)
+        document = _load_document(args.path, stdin=stdin, format=getattr(args, "format", None))
+        if args.command == "validate":
+            payload = validate_specification(document)
+        elif args.command == "compile":
+            from opsdevcode_specmint.compiler import compile_specification
+
+            payload = compile_specification(document)
+        else:
+            payload = inspect_artifact(document)
+        out.write(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+        return 0
+    except SpecProblem as exc:
+        err.write(json.dumps(exc.as_dict(), indent=2, sort_keys=True) + "\n")
+        return 1
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="specmint")
+    parser.add_argument("--version", action="store_true", dest="show_version")
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("version")
+    mint = sub.add_parser("mint")
+    mint.add_argument("mint_args", nargs=argparse.REMAINDER)
+    for name in ("validate", "compile", "inspect"):
+        cmd = sub.add_parser(name)
+        cmd.add_argument("path", nargs="?", default="-")
+        cmd.add_argument("--format", choices=("json", "yaml", "markdown", "mint"))
+    return parser
+
+
+def _load_document(path: str, *, stdin: IO[bytes] | None, format: str | None) -> dict[str, Any]:
+    if path == "-":
+        raw = b"" if stdin is None else stdin.read()
+        media = media_type_for_format(format) if format else "application/json"
+        body = raw if isinstance(raw, bytes | bytearray) else str(raw).encode()
+        return decode_body(body, media)
+    return decode_path(Path(path), format=format)

opsdevcode_specmint/compiler.py

@@ -0,0 +1,38 @@
+"""Host identity compile for the public language extract. CUE is not included."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from opsdevcode_specmint.automation import is_automation_document
+from opsdevcode_specmint.contracts import reject_unsupported_spec
+from opsdevcode_specmint.errors import DocumentParseError
+
+
+def compile_specification(document: dict[str, Any]) -> dict[str, Any]:
+    reject_unsupported_spec(document)
+    if not is_automation_document(document) and document.get("kind") != "DeliverySpecification":
+        raise DocumentParseError("unsupported document kind for language extract compile")
+    closed = json.loads(json.dumps(document, sort_keys=True))
+    if not isinstance(closed, dict):
+        raise DocumentParseError("compile produced a non-object document")
+    return closed
+
+
+def validate_specification(document: dict[str, Any]) -> dict[str, Any]:
+    compiled = compile_specification(document)
+    return {
+        "valid": True,
+        "kind": compiled.get("kind"),
+        "api_version": compiled.get("apiVersion"),
+        "id": compiled.get("metadata", {}).get("id")
+        if isinstance(compiled.get("metadata"), dict)
+        else None,
+        "issues": [],
+    }
+
+
+def inspect_artifact(document: dict[str, Any]) -> dict[str, Any]:
+    compiled = compile_specification(document)
+    return {"artifact": compiled}

opsdevcode_specmint/contracts.py

@@ -0,0 +1,160 @@
+"""Versioned spec and compiled-intent contracts. CUE stays adapter-private."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any
+
+from opsdevcode_specmint.errors import CompilationFailureError, SpecUnsupportedError
+from opsdevcode_specmint.identity import revision_digest
+from opsdevcode_specmint.pins import (
+    AUTOMATION_API_VERSION,
+    AUTOMATION_SPEC_KIND,
+    COMPILED_INTENT_API_VERSION,
+    COMPILED_INTENT_KIND,
+    SPEC_API_VERSION,
+    SPEC_KIND,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class SpecContract:
+    api_version: str
+    kind: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"apiVersion": self.api_version, "kind": self.kind}
+
+
+DELIVERY_SPEC_V1ALPHA1 = SpecContract(SPEC_API_VERSION, SPEC_KIND)
+COMPILED_INTENT_V1ALPHA1 = SpecContract(COMPILED_INTENT_API_VERSION, COMPILED_INTENT_KIND)
+
+
+def reject_unsupported_spec(document: dict[str, Any]) -> None:
+    api_version = document.get("apiVersion")
+    kind = document.get("kind")
+    delivery = api_version == SPEC_API_VERSION and kind == SPEC_KIND
+    automation = api_version == AUTOMATION_API_VERSION and kind == AUTOMATION_SPEC_KIND
+    if delivery or automation:
+        return
+    raise SpecUnsupportedError(
+        "Only DeliverySpecification specs.opsdevcode.io/v1alpha1 or "
+        "AutomationSpecification automations.opsdevcode.io/v1alpha1 is accepted."
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class CompiledIntent:
+    identity_id: str
+    revision: str
+    owner: str
+    statement: str
+    target_repository: str
+    environment_name: str | None
+    required_capabilities: tuple[str, ...]
+    recorded_baseline_approved: bool
+    required_evidence: tuple[str, ...]
+    allow_unexpired: bool
+    compare: str
+    unknown_is_not_compliant: bool
+    status: str
+
+    def to_canonical_dict(self) -> dict[str, Any]:
+        intent: dict[str, Any] = {
+            "owner": self.owner,
+            "statement": self.statement,
+            "target": {"repository": self.target_repository},
+            "required_capabilities": list(self.required_capabilities),
+            "constraints": {"recorded_baseline_approved": self.recorded_baseline_approved},
+            "required_evidence": list(self.required_evidence),
+            "exception_rules": {"allow_unexpired": self.allow_unexpired},
+            "convergence": {
+                "compare": self.compare,
+                "unknown_is_not_compliant": self.unknown_is_not_compliant,
+            },
+            "status": self.status,
+        }
+        if self.environment_name is not None:
+            intent["environment"] = {"name": self.environment_name}
+        return {
+            "apiVersion": COMPILED_INTENT_API_VERSION,
+            "kind": COMPILED_INTENT_KIND,
+            "identity": {"id": self.identity_id, "revision": self.revision},
+            "source": {
+                "apiVersion": SPEC_API_VERSION,
+                "kind": SPEC_KIND,
+                "id": self.identity_id,
+            },
+            "intent": intent,
+        }
+
+
+def build_compiled_intent(closed: dict[str, Any]) -> CompiledIntent:
+    projected = _project_closed_spec(closed)
+    unsigned = replace(projected, revision="")
+    body = unsigned.to_canonical_dict()
+    del body["identity"]["revision"]
+    return replace(projected, revision=revision_digest(body))
+
+
+def _project_closed_spec(closed: dict[str, Any]) -> CompiledIntent:
+    spec = closed.get("spec")
+    metadata = closed.get("metadata")
+    if not isinstance(spec, dict) or not isinstance(metadata, dict):
+        raise CompilationFailureError("Closed specification is missing metadata or spec.")
+    spec_id = metadata.get("id")
+    owner = spec.get("owner")
+    statement = spec.get("intent")
+    target = spec.get("target")
+    constraints = spec.get("constraints")
+    exception_rules = spec.get("exception_rules")
+    convergence = spec.get("convergence")
+    capabilities = spec.get("required_capabilities")
+    evidence = spec.get("required_evidence")
+    status = spec.get("status")
+    if not isinstance(target, dict) or not isinstance(constraints, dict):
+        raise CompilationFailureError("Closed specification is missing target or constraints.")
+    if not isinstance(exception_rules, dict) or not isinstance(convergence, dict):
+        raise CompilationFailureError("Closed specification is missing compiled defaults.")
+    if not isinstance(spec_id, str) or not spec_id:
+        raise CompilationFailureError("Closed specification is missing metadata.id.")
+    if not isinstance(owner, str) or not isinstance(statement, str):
+        raise CompilationFailureError("Closed specification is missing owner or intent.")
+    repository = target.get("repository")
+    approved = constraints.get("recorded_baseline_approved")
+    allow_unexpired = exception_rules.get("allow_unexpired")
+    compare = convergence.get("compare")
+    unknown = convergence.get("unknown_is_not_compliant")
+    if not isinstance(repository, str) or not isinstance(approved, bool):
+        raise CompilationFailureError("Closed specification target or constraints are incomplete.")
+    if not isinstance(allow_unexpired, bool) or not isinstance(unknown, bool):
+        raise CompilationFailureError("Closed specification defaults are incomplete.")
+    if not isinstance(compare, str) or not isinstance(status, str):
+        raise CompilationFailureError("Closed specification convergence or status is incomplete.")
+    if not isinstance(capabilities, list) or not all(
+        isinstance(item, str) for item in capabilities
+    ):
+        raise CompilationFailureError("Closed specification required_capabilities is incomplete.")
+    if not isinstance(evidence, list) or not all(isinstance(item, str) for item in evidence):
+        raise CompilationFailureError("Closed specification required_evidence is incomplete.")
+    environment = spec.get("environment")
+    environment_name: str | None = None
+    if environment is not None:
+        if not isinstance(environment, dict) or not isinstance(environment.get("name"), str):
+            raise CompilationFailureError("Closed specification environment is incomplete.")
+        environment_name = environment["name"]
+    return CompiledIntent(
+        identity_id=spec_id,
+        revision="",
+        owner=owner,
+        statement=statement,
+        target_repository=repository,
+        environment_name=environment_name,
+        required_capabilities=tuple(capabilities),
+        recorded_baseline_approved=approved,
+        required_evidence=tuple(evidence),
+        allow_unexpired=allow_unexpired,
+        compare=compare,
+        unknown_is_not_compliant=unknown,
+        status=status,
+    )

opsdevcode_specmint/errors.py

@@ -0,0 +1,62 @@
+"""HTTP problem payloads. Operational codes, not policy decisions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SpecProblem(Exception):
+    status: int
+    code: str
+    title: str
+    detail: str
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "type": f"about:specmint/{self.code.lower()}",
+            "title": self.title,
+            "status": self.status,
+            "detail": self.detail,
+            "code": self.code,
+        }
+
+
+class DocumentParseError(SpecProblem):
+    def __init__(self, detail: str) -> None:
+        super().__init__(400, "DOCUMENT_PARSE_FAILED", "Document parse failed", detail)
+
+
+class UnsupportedMediaError(SpecProblem):
+    def __init__(self, detail: str) -> None:
+        super().__init__(415, "UNSUPPORTED_MEDIA_TYPE", "Unsupported media type", detail)
+
+
+class DocumentTooLargeError(SpecProblem):
+    def __init__(self) -> None:
+        super().__init__(
+            413,
+            "DOCUMENT_TOO_LARGE",
+            "Document too large",
+            "Specification documents must be 65536 bytes or smaller.",
+        )
+
+
+class CueUnavailableError(SpecProblem):
+    def __init__(self, detail: str) -> None:
+        super().__init__(503, "CUE_UNAVAILABLE", "CUE engine unavailable", detail)
+
+
+class SpecInvalidError(SpecProblem):
+    def __init__(self, detail: str) -> None:
+        super().__init__(422, "SPEC_INVALID", "Specification invalid", detail)
+
+
+class SpecUnsupportedError(SpecProblem):
+    def __init__(self, detail: str) -> None:
+        super().__init__(422, "SPEC_UNSUPPORTED", "Specification unsupported", detail)
+
+
+class CompilationFailureError(SpecProblem):
+    def __init__(self, detail: str) -> None:
+        super().__init__(422, "COMPILATION_FAILURE", "Compilation failed", detail)

opsdevcode_specmint/identity.py

@@ -0,0 +1,13 @@
+"""Specification revision identity. Independent of policy artifact identity."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def revision_digest(compiled: dict[str, Any]) -> str:
+    canonical = json.dumps(compiled, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+    return f"sha256:{digest}"

opsdevcode_specmint/integration/__init__.py

@@ -0,0 +1,11 @@
+"""Public Mint Integration SDK. No compiler, network, or provider SDK imports."""
+
+from opsdevcode_specmint.integration.canonical import SCHEMA_INTEGRATION, SCHEMA_PROTOCOL
+from opsdevcode_specmint.integration.models import IntegrationManifest, parse_manifest
+
+__all__ = [
+    "SCHEMA_INTEGRATION",
+    "SCHEMA_PROTOCOL",
+    "IntegrationManifest",
+    "parse_manifest",
+]

opsdevcode_specmint/integration/__main__.py

@@ -0,0 +1,8 @@
+"""python -m opsdevcode_specmint.integration runs the reference server."""
+
+from __future__ import annotations
+
+from opsdevcode_specmint.integration.reference_server import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

opsdevcode_specmint/integration/canonical.py

@@ -0,0 +1,87 @@
+"""Deterministic JSON and content digests. Stdlib only; no compiler imports."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+SCHEMA_INTEGRATION = "mint.integration/v0"
+SCHEMA_PROTOCOL = "mint.protocol/v0"
+SCHEMA_REQUEST = "mint.protocol.request/v0"
+SCHEMA_RESULT = "mint.protocol.result/v0"
+SCHEMA_REALIZATION = "mint.realization/v0"
+SCHEMA_OBSERVATION = "mint.observation/v0"
+SCHEMA_OPERATION = "mint.operation/v0"
+SCHEMA_VERIFICATION = "mint.verification/v0"
+SCHEMA_EVIDENCE = "mint.evidence/v0"
+PROTOCOL_VERSION = SCHEMA_PROTOCOL
+
+PHASES = (
+    "describe",
+    "validate",
+    "observe",
+    "plan",
+    "verify",
+    "recover",
+    "evidence",
+    "execute",
+)
+NONPRIVILEGED_PHASES = (
+    "describe",
+    "validate",
+    "observe",
+    "plan",
+    "verify",
+    "recover",
+    "evidence",
+)
+EXECUTION_SUPPORT = ("none", "fake", "privileged")
+SECRET_KEYS = frozenset(
+    {
+        "access_key",
+        "api_key",
+        "authorization",
+        "credential",
+        "password",
+        "pat",
+        "private_key",
+        "secret",
+        "token",
+    }
+)
+
+
+def canonical_json_bytes(mapping: Any) -> bytes:
+    payload = json.dumps(mapping, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return f"{payload}\n".encode()
+
+
+def digest_bytes(payload: bytes) -> str:
+    return "sha256:" + hashlib.sha256(payload).hexdigest()
+
+
+def content_digest(mapping: Any) -> str:
+    return digest_bytes(canonical_json_bytes(mapping))
+
+
+def reject_unknown(document: dict[str, Any], allowed: frozenset[str], *, label: str) -> None:
+    unknown = sorted(set(document) - allowed)
+    if unknown:
+        raise ValueError(f"{label} contains unknown fields {unknown}")
+
+
+def reject_secrets(value: Any, *, label: str) -> None:
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if str(key).lower() in SECRET_KEYS:
+                raise ValueError(f"{label} contains a secret-shaped field {key}")
+            reject_secrets(item, label=label)
+    elif isinstance(value, list):
+        for item in value:
+            reject_secrets(item, label=label)
+
+
+def reject_absolute_path(text: str, *, label: str) -> None:
+    if text.startswith("/") or (len(text) > 2 and text[1] == ":"):
+        raise ValueError(f"{label} contains an absolute path")