velophex 0.2.0__py3-none-any.whl

velophex/packaging.py

@@ -0,0 +1,465 @@
+"""Builds an automation package (``.nupkg``) from a project directory (ADR-P003).
+
+This is the Python twin of ``Velophex.Workflow.Packaging.Automation.AutomationPackageBuilder``.
+The two must agree, because the Orchestrator inspects and the Runner verifies both with the
+same readers, and Studio and the CLI may publish the same project.
+
+**What "the same package" means.** The uncompressed content is byte-identical: the same entry
+names in the same order, the same fixed timestamp, and the same bytes in every entry -
+``project.json``, the manifest, the ``.nuspec`` and ``[Content_Types].xml`` down to the last
+escape. The *compressed* bytes are not compared, because the deflate stream a .NET
+``ZipArchive`` emits is not the one zlib emits and neither is part of the contract; what the
+platform hashes is the manifest and the files it lists, never the archive's compression.
+
+The output is deterministic in the sense the contract needs: the same project always produces
+the same package from this builder, so a rebuild does not invalidate a signature.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import stat as stat_module
+import zipfile
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from io import BytesIO
+from pathlib import Path
+from typing import Final
+
+from velophex.contracts.diagnostics import Diagnostic, has_errors
+from velophex.contracts.diagnostics import PackageDiagnosticCodes as Codes
+from velophex.contracts.package import (
+    PackageLayout,
+    PackageManifest,
+    create_package_manifest,
+    describe_file,
+    validate_package_manifest,
+    write_package_manifest,
+)
+from velophex.contracts.project import (
+    ProjectFiles,
+    ProjectManifest,
+    maximum_icon_bytes,
+    read_project_manifest,
+    write_project_manifest,
+)
+
+__all__ = [
+    "CREDENTIAL_SHAPED_PATHS",
+    "DEFAULT_EXCLUDED_PATHS",
+    "ENTRY_TIMESTAMP",
+    "MAXIMUM_PACKAGE_PATH_LENGTH",
+    "PackageBuildOptions",
+    "PackageBuildResult",
+    "build_package",
+    "build_package_to_directory",
+    "content_types_xml",
+    "nuspec_xml",
+    "write_project_file",
+]
+
+#: Every entry is stamped with this instant, so the same project gives the same package.
+#: (The ZIP format's own epoch is 1980; this is the .NET builder's value.)
+ENTRY_TIMESTAMP: Final = (2000, 1, 1, 0, 0, 0)
+
+MAXIMUM_PACKAGE_PATH_LENGTH: Final = 240
+
+#: Files that hold credentials by convention, never packed, in any directory (PY-05). Mirrors the
+#: engine's ``AutomationPackageBuildOptions.CredentialShapedPaths``: ``appsettings.json`` itself is
+#: packed (base configuration), its environment overlays are where the secrets go.
+CREDENTIAL_SHAPED_PATHS: Final[tuple[str, ...]] = (
+    "**/.env",
+    "**/.env.*",
+    "*.pfx",
+    "*.p12",
+    "*.pem",
+    "*.key",
+    "**/secrets.json",
+    "**/appsettings.*.json",
+)
+
+#: Project paths that are never packed: build output, local tool state, environments and
+#: credential files. Mirrors the engine's ``AutomationPackageBuildOptions.DefaultExcludedPaths``.
+DEFAULT_EXCLUDED_PATHS: Final[tuple[str, ...]] = (
+    "bin/",
+    "obj/",
+    ".git/",
+    ".vs/",
+    ".vscode/",
+    ".idea/",
+    ".velophex/",
+    ".venv/",
+    "__pycache__/",
+    "*.nupkg",
+    "*.user",
+    "*.pyc",
+    *CREDENTIAL_SHAPED_PATHS,
+)
+
+_RESERVED_DEVICE_NAMES: Final[frozenset[str]] = frozenset(
+    {"CON", "PRN", "AUX", "NUL", *(f"COM{n}" for n in range(1, 10)), *(f"LPT{n}" for n in range(1, 10))}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class PackageBuildOptions:
+    """Options for :func:`build_package`."""
+
+    #: Recorded as ``createdBy`` in the manifest, e.g. ``velophex-cli 0.1.0``.
+    created_by: str | None = None
+    excluded_paths: tuple[str, ...] = DEFAULT_EXCLUDED_PATHS
+    maximum_content_bytes: int = PackageLayout.DEFAULT_MAXIMUM_PACKAGE_BYTES
+
+
+@dataclass(slots=True)
+class PackageBuildResult:
+    """The outcome of building a package."""
+
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+    manifest: PackageManifest | None = None
+    package: bytes | None = None
+    file_name: str | None = None
+
+    @property
+    def succeeded(self) -> bool:
+        """True when the package was produced and nothing was reported as an error."""
+        return self.package is not None and not has_errors(self.diagnostics)
+
+
+def build_package(project_directory: str | Path, options: PackageBuildOptions | None = None) -> PackageBuildResult:
+    """Build the package for the project at *project_directory*, in memory."""
+    options = options or PackageBuildOptions()
+    root = Path(project_directory).resolve()
+    project_file = root / ProjectFiles.MANIFEST_FILE_NAME
+
+    if not project_file.is_file():
+        return PackageBuildResult(
+            diagnostics=[
+                Diagnostic.error(
+                    Codes.MISSING_PROJECT_MANIFEST,
+                    "$",
+                    f"'{project_directory}' has no {ProjectFiles.MANIFEST_FILE_NAME}.",
+                )
+            ]
+        )
+
+    project, diagnostics = read_project_manifest(project_file.read_bytes(), "$.project")
+
+    if project is None or has_errors(diagnostics):
+        return PackageBuildResult(diagnostics=list(diagnostics))
+
+    content, read_diagnostics = _read_content(root, options)
+    diagnostics.extend(read_diagnostics)
+    diagnostics.extend(_check_icon(project, content))
+
+    if has_errors(diagnostics):
+        return PackageBuildResult(diagnostics=diagnostics)
+
+    manifest = create_package_manifest(
+        project,
+        (describe_file(path, payload) for path, payload in content.items()),
+        options.created_by,
+    )
+
+    diagnostics.extend(validate_package_manifest(manifest))
+
+    if has_errors(diagnostics):
+        return PackageBuildResult(diagnostics=diagnostics)
+
+    return PackageBuildResult(
+        diagnostics=diagnostics,
+        manifest=manifest,
+        package=_write_archive(manifest, content),
+        file_name=f"{manifest.package_id}.{manifest.package_version}{PackageLayout.FILE_EXTENSION}",
+    )
+
+
+def _check_icon(project: ProjectManifest, content: dict[str, bytes]) -> list[Diagnostic]:
+    """Mirror of ``AutomationPackageBuilder.CheckIcon``: the icon is packed and within its limit."""
+    if project.icon is None:
+        return []
+
+    payload = content.get(PackageLayout.CONTENT_ROOT + project.icon)
+
+    if payload is None:
+        message = f"The package icon '{project.icon}' is not in the project, or the exclusions leave it out."
+        return [Diagnostic.error(Codes.MISSING_FILE, "$.project.icon", message)]
+
+    limit = maximum_icon_bytes(project.icon)
+
+    if len(payload) > limit:
+        message = f"The package icon '{project.icon}' is {len(payload)} bytes; the limit is {limit} bytes."
+        return [Diagnostic.error(Codes.DOCUMENT_TOO_LARGE, "$.project.icon", message)]
+
+    return []
+
+
+def build_package_to_directory(
+    project_directory: str | Path,
+    output_directory: str | Path,
+    options: PackageBuildOptions | None = None,
+) -> tuple[PackageBuildResult, Path | None]:
+    """Build the package and write it to ``{output}/{id}.{version}.nupkg``."""
+    result = build_package(project_directory, options)
+
+    if not result.succeeded:
+        return result, None
+
+    output = Path(output_directory)
+    output.mkdir(parents=True, exist_ok=True)
+    path = output / result.file_name  # type: ignore[arg-type]
+    path.write_bytes(result.package)  # type: ignore[arg-type]
+
+    return result, path
+
+
+# --------------------------------------------------------------------------- content
+
+
+def _read_content(root: Path, options: PackageBuildOptions) -> tuple[dict[str, bytes], list[Diagnostic]]:
+    diagnostics: list[Diagnostic] = []
+    content: dict[str, bytes] = {}
+    collisions: set[str] = set()
+    total = 0
+
+    for relative in _enumerate_files(root, root, options, diagnostics):
+        package_path = PackageLayout.to_package_path(relative)
+        reason = _invalid_package_path(package_path)
+
+        if reason is not None:
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_FILE_ENTRY, "$.files", f"Project file '{relative}' cannot be packed: {reason}."
+                )
+            )
+            continue
+
+        if package_path.upper() in collisions:
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.DUPLICATE_FILE,
+                    "$.files",
+                    f"Project file '{relative}' differs from another file only by case.",
+                )
+            )
+            continue
+
+        collisions.add(package_path.upper())
+
+        payload = (root / relative).read_bytes()
+        total += len(payload)
+
+        if total > options.maximum_content_bytes:
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.DOCUMENT_TOO_LARGE,
+                    "$.files",
+                    f"The project content exceeds {options.maximum_content_bytes} bytes.",
+                )
+            )
+            break
+
+        content[package_path] = payload
+
+    return dict(sorted(content.items())), diagnostics
+
+
+def _enumerate_files(
+    root: Path,
+    directory: Path,
+    options: PackageBuildOptions,
+    diagnostics: list[Diagnostic],
+) -> list[str]:
+    found: list[str] = []
+
+    for entry in sorted(directory.iterdir(), key=lambda item: item.name):
+        relative = entry.relative_to(root).as_posix()
+        is_directory = entry.is_dir()
+
+        if any(_matches(relative + "/" if is_directory else relative, pattern) for pattern in options.excluded_paths):
+            continue
+
+        if _is_link(entry):
+            diagnostics.append(
+                Diagnostic.error(
+                    Codes.INVALID_FILE_ENTRY, "$.files", f"'{relative}' is a link; links are never packed."
+                )
+            )
+            continue
+
+        if is_directory:
+            found.extend(_enumerate_files(root, entry, options, diagnostics))
+        else:
+            found.append(relative)
+
+    return found
+
+
+def _is_link(entry: Path) -> bool:
+    if entry.is_symlink():
+        return True
+
+    # Windows junctions are reparse points but not symlinks; packing one would follow a path
+    # outside the project.
+    attributes = getattr(entry.lstat(), "st_file_attributes", 0)
+    return bool(attributes & getattr(stat_module, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400))
+
+
+def _matches(path: str, pattern: str) -> bool:
+    """Match the pattern forms the .NET builder uses (``PackagePath.Matches``).
+
+    ``*.ext``, ``dir/``, ``**/name`` (a file name in any directory, ``*`` standing for any
+    characters) or an exact path.
+    """
+    if pattern.startswith("*."):
+        return path.lower().endswith(pattern[1:].lower())
+
+    if pattern.startswith("**/"):
+        return fnmatch.fnmatchcase(path.rsplit("/", 1)[-1].lower(), pattern[3:].lower())
+
+    if pattern.endswith("/"):
+        return path.lower().startswith(pattern.lower())
+
+    return path.lower() == pattern.lower()
+
+
+def _invalid_package_path(path: str) -> str | None:
+    """Why *path* cannot be an archive entry, or ``None`` when it is fine."""
+    if not path:
+        return "the path is empty"
+
+    if len(path) > MAXIMUM_PACKAGE_PATH_LENGTH:
+        return f"the path is longer than {MAXIMUM_PACKAGE_PATH_LENGTH} characters"
+
+    if "\\" in path:
+        return "the path contains a backslash"
+
+    if ":" in path:
+        return "the path contains a drive or stream separator ':'"
+
+    if path.startswith("/"):
+        return "the path is rooted"
+
+    for character in path:
+        if ord(character) < 0x20 or ord(character) == 0x7F:
+            return "the path contains a control character"
+
+        if character in '<>"|?*':
+            return f"the path contains the reserved character '{character}'"
+
+    for segment in path.split("/"):
+        if not segment:
+            return "the path has an empty segment or a trailing slash"
+
+        if segment in (".", ".."):
+            return "the path has a relative navigation segment"
+
+        if segment.endswith((".", " ")) or segment.startswith(" "):
+            return "a path segment starts with a space or ends with a dot or space"
+
+        if segment.split(".")[0].upper() in _RESERVED_DEVICE_NAMES:
+            return f"the path uses the reserved device name '{segment.split('.')[0]}'"
+
+    return None
+
+
+# --------------------------------------------------------------------------- archive
+
+
+def _write_archive(manifest: PackageManifest, content: dict[str, bytes]) -> bytes:
+    entries: dict[str, bytes] = dict(content)
+    entries["[Content_Types].xml"] = content_types_xml(content.keys()).encode("utf-8")
+    entries[f"{manifest.package_id}.nuspec"] = nuspec_xml(manifest).encode("utf-8")
+    entries[PackageLayout.MANIFEST_PATH] = write_package_manifest(manifest)
+
+    buffer = BytesIO()
+
+    with zipfile.ZipFile(buffer, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=9) as archive:
+        for path in sorted(entries):
+            info = zipfile.ZipInfo(path, date_time=ENTRY_TIMESTAMP)
+            info.compress_type = zipfile.ZIP_DEFLATED
+            # 0o600 in the high word; the low word stays 0, as .NET writes for a file entry.
+            info.external_attr = 0o600 << 16
+            archive.writestr(info, entries[path])
+
+    return buffer.getvalue()
+
+
+def nuspec_xml(manifest: PackageManifest) -> str:
+    """The ``.nuspec`` the package carries, byte for byte as the .NET builder writes it."""
+    project = manifest.project
+    authors = ", ".join(project.authors) if project.authors else project.name
+    description = project.name if not (project.description or "").strip() else project.description
+
+    return (
+        '<?xml version="1.0" encoding="utf-8"?>\n'
+        '<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">\n'
+        "  <metadata>\n"
+        f"    <id>{_escape_xml(manifest.package_id)}</id>\n"
+        f"    <version>{_escape_xml(manifest.package_version)}</version>\n"
+        f"    <authors>{_escape_xml(authors)}</authors>\n"
+        f"    <description>{_escape_xml(description or project.name)}</description>\n"
+        + (f"    <icon>{_escape_xml(PackageLayout.CONTENT_ROOT + project.icon)}</icon>\n" if project.icon else "")
+        + "    <packageTypes>\n"
+        f'      <packageType name="{PackageLayout.NUGET_PACKAGE_TYPE}" />\n'
+        "    </packageTypes>\n"
+        "  </metadata>\n"
+        "</package>\n"
+    )
+
+
+def content_types_xml(content_paths: Iterable[str]) -> str:
+    """The OPC content-types part, byte for byte as the .NET builder writes it."""
+    paths = list(content_paths)
+
+    extensions: list[str] = []
+    seen: set[str] = set()
+
+    for extension in [_extension(path) for path in paths] + ["json", "nuspec"]:
+        if extension and extension.upper() not in seen:
+            seen.add(extension.upper())
+            extensions.append(extension)
+
+    lines = [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">',
+    ]
+
+    for extension in sorted(extensions, key=str.upper):
+        lines.append(f'  <Default Extension="{_escape_xml(extension)}" ContentType="application/octet" />')
+
+    for path in paths:
+        if not _extension(path):
+            lines.append(f'  <Override PartName="/{_escape_xml(path)}" ContentType="application/octet" />')
+
+    lines.append("</Types>")
+    return "\n".join(lines) + "\n"
+
+
+def _extension(path: str) -> str:
+    """``Path.GetExtension`` without the dot: the last dot in the file name, unless it ends it."""
+    name = path.rsplit("/", 1)[-1]
+    index = name.rfind(".")
+
+    if index < 0 or index == len(name) - 1:
+        return ""
+
+    return name[index + 1 :]
+
+
+def _escape_xml(value: str) -> str:
+    """Escape as ``SecurityElement.Escape`` does: the five predefined entities."""
+    return (
+        value.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+        .replace("'", "&apos;")
+    )
+
+
+def write_project_file(project_directory: str | Path, manifest: ProjectManifest) -> Path:
+    """Write ``project.json`` deterministically into *project_directory*."""
+    path = Path(project_directory) / ProjectFiles.MANIFEST_FILE_NAME
+    path.write_bytes(write_project_manifest(manifest))
+    return path