scripticus-schema 0.1.0__py3-none-any.whl

scripticus_schema/__init__.py

@@ -0,0 +1,5 @@
+"""The shared Scripticus contract: manifest schema, identity, versioning.
+
+Code lives in this package only if it defines what a package is or how
+client and server communicate (D29).
+"""

scripticus_schema/manifest.py

@@ -0,0 +1,184 @@
+"""The package manifest (meta.toml): Pydantic schema and validation (D13).
+
+The client validates for UX at pack/install time; the server re-validates
+authoritatively at publish (D8). Both use this module, so there is exactly
+one definition of a valid manifest (D29).
+"""
+
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import BaseModel, Field, ValidationError, field_validator
+
+from scripticus_schema.semver import SEMVER_RE
+
+# Package names are kebab-case (enforced again at publish; validated
+# client-side so authors find out before they have written any code).
+PACKAGE_NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
+# Lower-case letters, digits, and dashes, starting with a letter. Stricter
+# than Gitea's own username rules (which also allow '.', '_', and upper
+# case): a namespace must satisfy both.
+NAMESPACE_RE = re.compile(r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$")
+
+KNOWN_OS = ("linux", "macos", "windows")
+
+
+@dataclass(frozen=True)
+class Language:
+    extension: str
+    interpreter: str
+    windows_interpreter: str
+
+
+LANGUAGES: dict[str, Language] = {
+    "bash": Language("sh", "bash", "bash"),
+    "python": Language("py", "python3", "python"),
+    "powershell": Language("ps1", "pwsh", "powershell"),
+}
+
+
+class ManifestError(Exception):
+    """A package directory does not contain a valid manifest."""
+
+
+class PackageMeta(BaseModel):
+    namespace: str
+    name: str
+    version: str
+    language: str
+    description: str = ""
+
+    @field_validator("namespace")
+    @classmethod
+    def _check_namespace(cls, value: str) -> str:
+        if not NAMESPACE_RE.match(value):
+            raise ValueError(
+                f"'{value}' is not a valid namespace"
+                " (lower-case letters, digits, and dashes, starting with a letter)"
+            )
+        return value
+
+    @field_validator("name")
+    @classmethod
+    def _check_name(cls, value: str) -> str:
+        if not PACKAGE_NAME_RE.match(value):
+            raise ValueError(f"'{value}' is not kebab-case")
+        return value
+
+    @field_validator("version")
+    @classmethod
+    def _check_version(cls, value: str) -> str:
+        if not SEMVER_RE.match(value):
+            raise ValueError(f"'{value}' is not strict semver")
+        return value
+
+    @field_validator("language")
+    @classmethod
+    def _check_language(cls, value: str) -> str:
+        if value not in LANGUAGES:
+            supported = ", ".join(sorted(LANGUAGES))
+            raise ValueError(f"'{value}' is not supported ({supported})")
+        return value
+
+
+class Platforms(BaseModel):
+    os: list[str]
+
+    @field_validator("os")
+    @classmethod
+    def _check_os(cls, value: list[str]) -> list[str]:
+        if not value or not all(os_name in KNOWN_OS for os_name in value):
+            known = ", ".join(KNOWN_OS)
+            raise ValueError(f"os must be a non-empty list drawn from: {known}")
+        return value
+
+
+class ToolDependencies(BaseModel):
+    requires: list[str] = Field(default_factory=list)
+    optional: list[str] = Field(default_factory=list)
+
+
+class Dependencies(BaseModel):
+    packages: dict[str, str] = Field(default_factory=dict)
+    tools: ToolDependencies = Field(default_factory=ToolDependencies)
+
+
+class Manifest(BaseModel):
+    package: PackageMeta
+    platforms: Platforms
+    commands: dict[str, str] | None = None
+    dependencies: Dependencies = Field(default_factory=Dependencies)
+
+
+def _format_error(error: dict) -> str:
+    location = ".".join(str(part) for part in error["loc"])
+    message = error["msg"]
+    message = message.removeprefix("Value error, ")
+    return f"[{location}] {message}" if location else message
+
+
+def validate_manifest(data: dict) -> Manifest:
+    """Validate parsed manifest data; raise ManifestError listing every problem."""
+    try:
+        return Manifest.model_validate(data)
+    except ValidationError as exc:
+        raise ManifestError(
+            "\n".join(_format_error(error) for error in exc.errors())
+        ) from exc
+
+
+def check_package_tree(manifest: Manifest, package_dir: Path) -> list[str]:
+    """Checks that need the package tree, not just the manifest: command
+    targets must exist inside the package, and without a [commands] table
+    the default entrypoint must exist. Used by pack/install client-side and
+    by the server at publish, which validates the extracted tree the same
+    way.
+    """
+    errors = []
+    if manifest.commands is None:
+        entrypoint = f"src/main.{LANGUAGES[manifest.package.language].extension}"
+        if not (package_dir / entrypoint).is_file():
+            errors.append(f"no [commands] table and no {entrypoint}")
+    else:
+        for command, script in manifest.commands.items():
+            script_path = package_dir / script
+            if not script_path.is_file():
+                errors.append(f"[commands] {command} points at missing file '{script}'")
+            elif package_dir.resolve() not in script_path.resolve().parents:
+                errors.append(f"[commands] {command} points outside the package: '{script}'")
+    return errors
+
+
+def load_manifest(package_dir: Path) -> Manifest:
+    """Read and validate ``meta.toml``; raise ManifestError listing every problem."""
+    manifest_path = package_dir / "meta.toml"
+    if not manifest_path.is_file():
+        raise ManifestError(f"no meta.toml found in '{package_dir}'")
+
+    try:
+        data = tomllib.loads(manifest_path.read_text())
+    except tomllib.TOMLDecodeError as exc:
+        raise ManifestError(f"meta.toml is not valid TOML: {exc}") from exc
+
+    try:
+        manifest = Manifest.model_validate(data)
+        errors = check_package_tree(manifest, package_dir)
+    except ValidationError as exc:
+        manifest = None
+        errors = [_format_error(error) for error in exc.errors()]
+
+    if errors:
+        problems = "\n".join(f"  - {error}" for error in errors)
+        raise ManifestError(f"'{package_dir}' is not a valid package:\n{problems}")
+    return manifest
+
+
+def commands_of(manifest: Manifest) -> dict[str, str]:
+    """The command -> script-path map, applying the default-entrypoint rule."""
+    if manifest.commands:
+        return dict(manifest.commands)
+    extension = LANGUAGES[manifest.package.language].extension
+    return {manifest.package.name: f"src/main.{extension}"}

scripticus_schema/semver.py

@@ -0,0 +1,29 @@
+"""Strict semver: the official pattern and precedence ordering (D16)."""
+
+import re
+
+# The official semver.org regex.
+SEMVER_RE = re.compile(
+    r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)"
+    r"(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)"
+    r"(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?"
+    r"(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"
+)
+
+
+def semver_key(version: str):
+    """A sort key implementing semver precedence (build metadata ignored).
+
+    Assumes ``version`` already matches ``SEMVER_RE``.
+    """
+    core = version.partition("+")[0]
+    numbers, _, prerelease = core.partition("-")
+    major, minor, patch = (int(part) for part in numbers.split("."))
+    if not prerelease:
+        # A release sorts after every prerelease of the same version.
+        return (major, minor, patch, 1, ())
+    identifiers = tuple(
+        (0, int(ident), "") if ident.isdigit() else (1, 0, ident)
+        for ident in prerelease.split(".")
+    )
+    return (major, minor, patch, 0, identifiers)

scripticus_schema/treehash.py

@@ -0,0 +1,36 @@
+"""Content-addressed package identity: a Merkle hash of a directory tree (D3).
+
+The canonical identity of a package artifact is the hash of its directory
+tree, git-style: files hash their contents, directories hash their sorted
+entry listing. Entry names are length-prefixed in the listing so the
+encoding is injective — a crafted file name cannot forge record structure,
+so distinct trees cannot hash identically (D27). File modes are deliberately
+excluded — zip extraction drops the executable bit, and the same content
+must hash identically whichever archive container it travelled in (D26).
+
+The client verifies this hash after download; the index verifies it at
+publish. Both sides use this module, so the implementations cannot diverge
+(D29).
+"""
+
+import hashlib
+from pathlib import Path
+
+
+def _blob_hash(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _tree_digest(directory: Path) -> str:
+    records = []
+    for child in sorted(directory.iterdir(), key=lambda p: p.name):
+        kind = "tree" if child.is_dir() else "blob"
+        digest = _tree_digest(child) if child.is_dir() else _blob_hash(child)
+        name = child.name.encode()
+        records.append(b"%s %s %d:%s\n" % (kind.encode(), digest.encode(), len(name), name))
+    return hashlib.sha256(b"".join(records)).hexdigest()
+
+
+def tree_hash(directory: Path) -> str:
+    """The content hash of a package directory, as ``sha256:<hex>``."""
+    return f"sha256:{_tree_digest(directory)}"

scripticus_schema-0.1.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: scripticus-schema
+Version: 0.1.0
+Summary: A package manager and registry for scripts — shared contract: manifest schema, identity, versioning
+License-Expression: MIT
+Requires-Dist: pydantic>=2.7
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# scripticus-schema
+
+The shared contract between the [Scripticus](https://pypi.org/project/scripticus/)
+client and [server](https://pypi.org/project/scripticus-server/): the
+package manifest schema and validation, the naming and versioning rules,
+and the content-addressed identity (tree hash) of a package.
+
+This package is internal plumbing — install `scripticus` (the CLI) or
+`scripticus-server` (the registry) instead; both depend on this package
+and pull it in automatically.
+
+Code lives here only if it defines what a package *is* or how client and
+server communicate. Utilities that merely happen to be useful to both
+sides do not belong here.

scripticus_schema-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+scripticus_schema/__init__.py,sha256=cEYc4YlJSfxGWiV0TT6PSb3vtvyNwUILT_yIEEJ1t70,187
+scripticus_schema/manifest.py,sha256=owhfm559U6PlUQohTG-B4Fr4NvkPYjSOBK9OIyUQ25I,6318
+scripticus_schema/semver.py,sha256=gU3fTK_CXbXXL9mWrehgxRV71Ska7G2KGs_6PoYmqZ4,1007
+scripticus_schema/treehash.py,sha256=UIRL-ZhNI0rQYkWgrrKjIV4b3ShIoxro_JVXdRpWQqo,1496
+scripticus_schema-0.1.0.dist-info/WHEEL,sha256=YR4QUxGCbsyoOnWBVTv-p1I4yc3seKGPev46mvmc8Cg,81
+scripticus_schema-0.1.0.dist-info/METADATA,sha256=3X-z5eJmQ5un63RRcSckdA8aLwOhRSu-YxYP_rd4sxA,943
+scripticus_schema-0.1.0.dist-info/RECORD,,

scripticus_schema-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.29
+Root-Is-Purelib: true
+Tag: py3-none-any