velophex 0.2.0__py3-none-any.whl

velophex/cli/main.py

@@ -0,0 +1,548 @@
+"""``velophex init | run | pack | publish``.
+
+The four verbs a Python automation author needs, in the order they are used:
+
+* ``init`` scaffolds a uv project with one decorated handler and a ``project.json``.
+* ``run`` executes an entry point locally, with the same input validation and the same
+  ``Business``/``Application`` distinction the Runner applies, so a run that works here
+  works on a robot.
+* ``pack`` refreshes ``project.json`` from the handlers and builds the ``.nupkg``
+  (ADR-P003), optionally adding the detached signature with ``--sign``.
+* ``publish`` pushes that package to an Orchestrator tenant's NuGet v3 feed.
+
+Diagnostics are printed with the same codes the .NET validators emit (``VPC1012`` and so on),
+so a message from the CLI and one from the Orchestrator upload name the same rule.
+
+Exit codes are stable: ``0`` success, ``1`` the command failed, ``2`` the inputs given to
+``run`` could not be read or do not fit the entry point, ``3`` the handler raised a business
+rule.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import shutil
+import sys
+import traceback
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Annotated, Any
+from uuid import UUID
+
+import typer
+
+from velophex import __version__, _json
+from velophex.cli.publish import PublishError, publish_package
+from velophex.cli.sync import synchronize
+from velophex.cli.templates import handler_module, module_name, new_project_manifest, pyproject_toml
+from velophex.contracts.diagnostics import Diagnostic, Severity, has_errors
+from velophex.contracts.project import ProjectFiles, read_project_manifest, write_project_manifest
+from velophex.contracts.runtimes import FaultCodes
+from velophex.entrypoints import EntryPointInputError, normalize_outputs
+from velophex.errors import BusinessError
+from velophex.packaging import PackageBuildOptions, build_package_to_directory
+from velophex.signing import SigningError, SigningKey, load_signing_key, sign_package_file
+from velophex.worker.loader import PackageLoadError, load_entry_point
+
+app = typer.Typer(
+    name="velophex",
+    help="Author, run, pack and publish VeloPhex Python automations.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+_CREATED_BY = f"velophex-cli {__version__}"
+
+_EXIT_FAILED = 1
+_EXIT_INPUT = 2
+_EXIT_BUSINESS = 3
+
+#: Where ``pack --sign`` reads the PKCS#12 password from. There is deliberately no option for
+#: it: a command-line argument is visible in shell history and in every process listing.
+SIGNING_PASSWORD_VARIABLE = "VELOPHEX_SIGNING_PASSWORD"
+
+#: Where ``publish`` reads the personal access token from, for the same reason.
+API_KEY_VARIABLE = "VELOPHEX_API_KEY"
+
+
+@app.callback()
+def _root(
+    version: Annotated[bool, typer.Option("--version", help="Print the SDK version and exit.")] = False,
+) -> None:
+    if version:
+        typer.echo(__version__)
+        raise typer.Exit
+
+
+@app.command()
+def init(
+    name: Annotated[str, typer.Argument(help="Project and package name, e.g. Invoice.Ocr.")],
+    directory: Annotated[Path | None, typer.Option("--directory", "-d", help="Where to create it.")] = None,
+    version: Annotated[str, typer.Option(help="Initial SemVer version.")] = "1.0.0",
+    sdk: Annotated[
+        str | None,
+        typer.Option(help="Version specifier for the velophex SDK dependency; this SDK's series by default."),
+    ] = None,
+    sdk_wheel: Annotated[
+        Path | None,
+        typer.Option(
+            help="The velophex SDK wheel to vendor into the project; by default this SDK's own wheel, "
+            "looked up in the UV_FIND_LINKS folders."
+        ),
+    ] = None,
+) -> None:
+    """Create a new Python automation project."""
+    sdk = sdk or sdk_specifier(__version__)
+    root = Path(directory) if directory is not None else Path.cwd() / name
+
+    if root.exists() and any(root.iterdir()):
+        _fail(f"'{root}' is not empty.")
+
+    if sdk_wheel is not None and not sdk_wheel.is_file():
+        _fail(f"The SDK wheel '{sdk_wheel}' does not exist.")
+
+    wheel = sdk_wheel or find_sdk_wheel(os.environ.get("UV_FIND_LINKS", ""), __version__)
+    vendored = None
+
+    if wheel is not None:
+        (root / SDK_WHEEL_FOLDER).mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(wheel, root / SDK_WHEEL_FOLDER / wheel.name)
+        vendored = f"{SDK_WHEEL_FOLDER}/{wheel.name}"
+
+    module = module_name(name)
+    manifest = new_project_manifest(name, version)
+
+    (root / "src" / module).mkdir(parents=True, exist_ok=True)
+    (root / "src" / module / "__init__.py").write_text("", encoding="utf-8")
+    (root / "src" / module / "main.py").write_text(handler_module(name), encoding="utf-8", newline="\n")
+    (root / "pyproject.toml").write_text(pyproject_toml(name, version, sdk, vendored), encoding="utf-8", newline="\n")
+    (root / ProjectFiles.MANIFEST_FILE_NAME).write_bytes(write_project_manifest(manifest))
+    (root / ".gitignore").write_text(".venv/\n__pycache__/\n*.nupkg\n", encoding="utf-8", newline="\n")
+
+    typer.echo(f"Created {name} in {root}.")
+
+    if vendored is None:
+        typer.echo(
+            f"Warning: no velophex-{__version__} wheel was vendored (pass --sdk-wheel, or put its folder in "
+            "UV_FIND_LINKS). The SDK is not on a public index, so a Robot cannot restore this project "
+            "until it is.",
+            err=True,
+        )
+
+    typer.echo(next_steps(root))
+
+
+#: Where ``init`` vendors the SDK wheel, relative to the project.
+SDK_WHEEL_FOLDER = "wheels"
+
+
+def find_sdk_wheel(find_links: str, version: str) -> Path | None:
+    """This SDK's wheel in one of the comma-separated *find_links* folders (``UV_FIND_LINKS``)."""
+    for folder in filter(None, (part.strip() for part in find_links.split(","))):
+        candidate = Path(folder) / f"velophex-{version}-py3-none-any.whl"
+
+        if candidate.is_file():
+            return candidate
+
+    return None
+
+
+def sdk_specifier(version: str) -> str:
+    """The SDK dependency a new project gets: this SDK's compatible series, never unbounded.
+
+    Before 1.0 a minor release may break, so ``0.1.1`` gives ``>=0.1.1,<0.2``; from 1.0 on the
+    bound is the next major.
+    """
+    found = re.match(r"(\d+)\.(\d+)\.\d+", version)
+
+    if found is None:
+        raise ValueError(f"'{version}' is not a release version.")
+
+    major, minor = int(found[1]), int(found[2])
+    upper = f"{major}.{minor + 1}" if major == 0 else f"{major + 1}"
+    return f">={found[0]},<{upper}"
+
+
+def next_steps(root: Path) -> str:
+    """What to type after ``init``: the same transcript as the README quickstart."""
+    try:
+        where = os.path.relpath(root)
+    except ValueError:  # another drive
+        where = str(root)
+
+    return (
+        "Next:\n"
+        f"  cd {where}\n"
+        "  uv sync\n"
+        """  echo '{"message": "Hi"}' > inputs.json\n"""
+        "  uv run velophex run main --inputs-file inputs.json"
+    )
+
+
+@app.command()
+def run(
+    entry_point: Annotated[str | None, typer.Argument(help="Entry point id; the default one when omitted.")] = None,
+    directory: Annotated[Path, typer.Option("--directory", "-d", help="Project directory.")] = Path("."),
+    inputs: Annotated[str | None, typer.Option("--inputs", help="Inputs as a JSON object.")] = None,
+    inputs_file: Annotated[Path | None, typer.Option("--inputs-file", help="Inputs as a JSON file.")] = None,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Show debug logging.")] = False,
+) -> None:
+    """Run one entry point locally.
+
+    There is no Orchestrator behind a local run, so ``velophex.runtime`` calls that need one
+    (assets, queues, child jobs) raise rather than silently doing nothing.
+    """
+    logging.basicConfig(level=logging.DEBUG if verbose else logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
+    try:
+        loaded = load_entry_point(directory, entry_point)
+    except PackageLoadError as error:
+        _fail(str(error))
+        return
+
+    try:
+        arguments = loaded.definition.bind(_read_inputs(inputs, inputs_file, verbose))
+    except EntryPointInputError as error:
+        _input_error(
+            f"{error} (at {', '.join(error.pointers)}). Check the inputs against the entry point's "
+            "parameters in project.json.",
+            error,
+            verbose,
+        )
+        return
+
+    # A local run installs the same ambient session the worker does, so stop_requested() and
+    # context() behave the same way here as on a robot.
+    from velophex.contracts.executor import ExecutionContextInfo
+    from velophex.runtime import _session as ambient
+
+    session = ambient.RunSession.create(ExecutionContextInfo(), loaded.definition, str(Path(directory).resolve()))
+    ambient.set_session(session)
+
+    try:
+        outputs = loaded.definition.function(**arguments)
+
+        if loaded.definition.is_async:
+            import asyncio
+
+            outputs = asyncio.run(outputs)
+    except BusinessError as error:
+        typer.secho(f"Business rule: [{error.code}] {error.message}", fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(_EXIT_BUSINESS) from error
+    finally:
+        ambient.clear_session()
+
+    # The worker's rule and the worker's writer, so a local run prints what a robot would send
+    # and refuses what a robot would refuse.
+    normalized = normalize_outputs(outputs)
+
+    try:
+        wire = _json.dumps_wire(normalized)
+    except (TypeError, ValueError) as error:
+        _fail(f"{FaultCodes.RESULT_NOT_SERIALIZABLE}: the outputs cannot be written as JSON: {error}")
+        return
+
+    typer.echo(json.dumps(json.loads(wire), indent=2, ensure_ascii=False))
+
+
+@app.command()
+def pack(
+    directory: Annotated[Path, typer.Option("--directory", "-d", help="Project directory.")] = Path("."),
+    output: Annotated[Path, typer.Option("--output", "-o", help="Where to write the .nupkg.")] = Path("artifacts"),
+    sync: Annotated[
+        bool,
+        typer.Option("--sync/--no-sync", help="Refresh project.json from the decorated handlers before packing."),
+    ] = True,
+    sign: Annotated[
+        Path | None,
+        typer.Option("--sign", help="Sign the package with this PKCS#12 (.pfx/.p12) certificate and key."),
+    ] = None,
+    sign_password_stdin: Annotated[
+        bool,
+        typer.Option(
+            "--sign-password-stdin",
+            help=f"Read the PKCS#12 password from stdin instead of ${SIGNING_PASSWORD_VARIABLE}.",
+        ),
+    ] = False,
+) -> None:
+    """Build the automation package (``.nupkg``) for this project.
+
+    ``--sign`` adds the detached ``velophex/signature.json`` (ADR-P003) after the manifest is
+    final. Its password comes from ``$VELOPHEX_SIGNING_PASSWORD``, from stdin with
+    ``--sign-password-stdin``, or from a hidden prompt on a terminal - never from an option,
+    which would be recorded in shell history and readable in the process list. Signing is
+    opt-in: an unsigned package is a valid package, and policy decides whether it may run.
+    """
+    root = Path(directory)
+    project_file = root / ProjectFiles.MANIFEST_FILE_NAME
+
+    if not project_file.is_file():
+        _fail(f"'{root}' has no {ProjectFiles.MANIFEST_FILE_NAME}. Run 'velophex init' first.")
+
+    manifest, diagnostics = read_project_manifest(project_file.read_bytes())
+
+    if manifest is None or has_errors(diagnostics):
+        _report(diagnostics)
+        _fail(f"{project_file} is not a valid project manifest.")
+        return
+
+    lock_file = root / (manifest.runtime.lock_file or ProjectFiles.PYTHON_LOCK_FILE_NAME)
+
+    if not lock_file.is_file():
+        # Without a lock file the Runner cannot reproduce the environment, so the package
+        # would be refused on upload; failing here saves that round trip (ADR-P008).
+        _fail(f"'{lock_file.name}' is missing. Run 'uv sync' to lock the environment before packing.")
+
+    if sync:
+        result = synchronize(root, manifest)
+
+        for warning in result.warnings:
+            typer.secho(f"warning: {warning}", fg=typer.colors.YELLOW, err=True)
+
+        if result.changed:
+            project_file.write_bytes(write_project_manifest(result.manifest))
+            typer.echo(f"Updated {ProjectFiles.MANIFEST_FILE_NAME} from the decorated handlers.")
+
+    built, path = build_package_to_directory(root, output, PackageBuildOptions(created_by=_CREATED_BY))
+    _report(built.diagnostics)
+
+    if not built.succeeded or path is None:
+        _fail("The package was not built.")
+        return
+
+    if sign is not None:
+        _sign_package(path, sign, sign_password_stdin)
+
+    typer.echo(f"Wrote {path} ({path.stat().st_size} bytes).")
+    typer.echo(f"Required runtimes: {', '.join(built.manifest.required_runtimes) if built.manifest else ''}")
+
+
+@app.command()
+def publish(
+    package: Annotated[
+        Path | None,
+        typer.Argument(help="The .nupkg to publish; the newest in --output when omitted."),
+    ] = None,
+    orchestrator: Annotated[str | None, typer.Option("--orchestrator", help="Orchestrator public base URL.")] = None,
+    tenant: Annotated[str | None, typer.Option("--tenant", help="Tenant id.")] = None,
+    api_key_stdin: Annotated[
+        bool,
+        typer.Option(
+            "--api-key-stdin",
+            help=f"Read the personal access token from stdin instead of ${API_KEY_VARIABLE}.",
+        ),
+    ] = False,
+    output: Annotated[Path, typer.Option("--output", "-o", help="Where packages are written.")] = Path("artifacts"),
+    retired_api_key: Annotated[
+        str | None,
+        typer.Option("--api-key", hidden=True, help="Retired: the token is never taken as an option."),
+    ] = None,
+) -> None:
+    """Publish a package to an Orchestrator tenant's NuGet v3 feed.
+
+    The personal access token comes from ``$VELOPHEX_API_KEY``, from stdin with
+    ``--api-key-stdin``, or from a hidden prompt on a terminal - never from an option, which
+    would be recorded in shell history and readable in the process list. The URL and tenant
+    come from ``--orchestrator``/``--tenant`` or ``VELOPHEX_ORCHESTRATOR_URL``/``VELOPHEX_TENANT_ID``.
+    """
+    if retired_api_key is not None:
+        # Refuse before anything else, and never echo or use the value.
+        _fail(
+            f"--api-key is not supported: a token on the command line ends up in shell history and the "
+            f"process list. Set ${API_KEY_VARIABLE}, pass --api-key-stdin, or run on a terminal to be prompted."
+        )
+        return
+
+    path = package or _only_package(output)
+    base_url = orchestrator or os.environ.get("VELOPHEX_ORCHESTRATOR_URL")
+    tenant_id = tenant or os.environ.get("VELOPHEX_TENANT_ID")
+
+    if path is None:
+        _fail(f"No package given and none found in '{output}'.")
+        return
+
+    if not base_url or not tenant_id:
+        _fail("An Orchestrator URL and a tenant id are required (--orchestrator/--tenant or their variables).")
+        return
+
+    token = _api_key(api_key_stdin)
+
+    if not token:
+        _fail(
+            f"No API key. Set ${API_KEY_VARIABLE}, pass --api-key-stdin, or run on a terminal to be prompted; "
+            "it is never taken as a command-line option."
+        )
+        return
+
+    try:
+        result = publish_package(path, public_base_url=base_url, tenant_id=UUID(tenant_id), api_key=token)
+    except PublishError as error:
+        for diagnostic in (error.problem or {}).get("errors") or []:
+            typer.secho(f"  {diagnostic}", fg=typer.colors.RED, err=True)
+
+        _fail(str(error))
+        return
+    except ValueError as error:
+        _fail(f"'{tenant_id}' is not a tenant id: {error}")
+        return
+
+    if result.already_published:
+        typer.secho(f"{path.name} is already published; nothing to do.", fg=typer.colors.YELLOW)
+    else:
+        typer.echo(f"Published {path.name}.")
+
+
+# --------------------------------------------------------------------------- signing
+
+
+def _sign_package(package: Path, certificate: Path, password_from_stdin: bool) -> None:
+    """Add the detached signature to a package that has already been written."""
+    try:
+        key = load_signing_key(certificate, _signing_password(password_from_stdin))
+        sign_package_file(package, key)
+    except SigningError as error:
+        # str(error) is the whole message by design: SigningError never carries a password,
+        # a key or a chained third-party exception that might.
+        _fail(str(error))
+        return
+
+    _warn_if_outside_validity(key)
+
+    typer.echo(f"Signed with {key.subject}.")
+    typer.echo(f"Pin this signer as SHA-256 {key.thumbprint}.")
+
+
+def _signing_password(from_stdin: bool) -> bytes | None:
+    """Resolve the PKCS#12 password without it ever becoming a process argument.
+
+    An empty password means an unprotected file, which PKCS#12 spells as no password at all.
+    """
+    if from_stdin:
+        secret = sys.stdin.readline().rstrip("\r\n")
+    elif SIGNING_PASSWORD_VARIABLE in os.environ:
+        secret = os.environ[SIGNING_PASSWORD_VARIABLE]
+    elif sys.stdin.isatty():
+        secret = typer.prompt("Signing key password", hide_input=True, default="", show_default=False)
+    else:
+        _fail(
+            f"No signing key password. Set ${SIGNING_PASSWORD_VARIABLE} or pass --sign-password-stdin; "
+            "it is never taken as a command-line option."
+        )
+        return None
+
+    return secret.encode("utf-8") or None
+
+
+def _api_key(from_stdin: bool) -> str | None:
+    """Resolve the personal access token without it ever becoming a process argument."""
+    if from_stdin:
+        return sys.stdin.readline().strip() or None
+
+    if os.environ.get(API_KEY_VARIABLE):
+        return os.environ[API_KEY_VARIABLE].strip() or None
+
+    if _stdin_is_terminal():
+        typed = typer.prompt("Personal access token", hide_input=True, default="", show_default=False)
+        return str(typed).strip() or None
+
+    return None
+
+
+def _stdin_is_terminal() -> bool:
+    return sys.stdin.isatty()
+
+
+def _warn_if_outside_validity(key: SigningKey) -> None:
+    if not key.is_valid_at(datetime.now(UTC)):
+        typer.secho(
+            "warning: the signer certificate is expired or not yet valid, so every verifier will "
+            "refuse this signature.",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+
+
+# --------------------------------------------------------------------------- helpers
+
+
+def _read_inputs(inline: str | None, from_file: Path | None, verbose: bool = False) -> Any:
+    if inline and from_file:
+        _input_error("Use --inputs or --inputs-file, not both.", None, verbose)
+
+    text: str | bytes
+
+    if from_file is not None:
+        try:
+            # Bytes, so json detects the encoding: Windows PowerShell's `>` writes UTF-16.
+            text = from_file.read_bytes()
+        except OSError as error:
+            _input_error(
+                f"Cannot read the inputs file '{from_file}': {error.strerror or error}. "
+                "Check the path, or pass the inputs inline with --inputs.",
+                error,
+                verbose,
+            )
+            return None
+
+        source = f"The inputs file '{from_file}'"
+    elif inline:
+        text = inline
+        source = "--inputs"
+    else:
+        return {}
+
+    try:
+        return json.loads(text)
+    except ValueError as error:
+        _input_error(
+            f'{source} is not valid JSON: {error}. Pass a JSON object such as {{"message": "Hi"}}; '
+            "if your shell strips the quotes (Windows PowerShell 5.1 does), put it in a file and use --inputs-file.",
+            error,
+            verbose,
+        )
+        return None
+
+
+def _only_package(output: Path) -> Path | None:
+    """The one package in *output*; more than one is ambiguous and must be named."""
+    candidates = sorted(output.glob("*.nupkg"))
+
+    if len(candidates) > 1:
+        _fail(
+            f"'{output}' holds {len(candidates)} packages ({', '.join(item.name for item in candidates)}). "
+            f"Name the one to publish, e.g. velophex publish {candidates[-1]}"
+        )
+
+    return candidates[0] if candidates else None
+
+
+def _report(diagnostics: list[Diagnostic]) -> None:
+    for diagnostic in diagnostics:
+        colour = typer.colors.RED if diagnostic.severity is Severity.ERROR else typer.colors.YELLOW
+        typer.secho(f"{diagnostic.code} {diagnostic.path}: {diagnostic.message}", fg=colour, err=True)
+
+
+def _fail(message: str) -> None:
+    typer.secho(message, fg=typer.colors.RED, err=True)
+    raise typer.Exit(_EXIT_FAILED)
+
+
+def _input_error(message: str, error: BaseException | None, verbose: bool) -> None:
+    """Report unusable ``run`` inputs: the problem and what to do; the traceback only with --verbose."""
+    if verbose and error is not None:
+        traceback.print_exception(error, file=sys.stderr)
+
+    typer.secho(message, fg=typer.colors.RED, err=True)
+    raise typer.Exit(_EXIT_INPUT)
+
+
+def main() -> None:
+    """Console entry point for the ``velophex`` command."""
+    app()
+
+
+if __name__ == "__main__":
+    sys.exit(app())

velophex/cli/publish.py

@@ -0,0 +1,152 @@
+"""Publishing a package to an Orchestrator tenant's NuGet v3 feed.
+
+Every tenant's packages are a NuGet v3 feed (``VeloPhex.Orchestrator/docs/package-feed.md``),
+so publishing is a ``PackagePublish/2.0.0`` push: a multipart ``PUT`` of the ``.nupkg`` with a
+personal access token. The server runs exactly the same inspection as an upload through the
+packages screen, which is why a ``400`` here carries the contract diagnostics and is worth
+showing verbatim.
+
+The token is a ``vpx_pat_…`` created with ``POST /api/v1/me/access-tokens`` or through the
+device flow; it is passed in ``X-NuGet-ApiKey`` so the same call works from ``dotnet nuget
+push -k``. It is never written to ``project.json`` or to the package.
+"""
+
+from __future__ import annotations
+
+import io
+import zipfile
+from dataclasses import dataclass
+from hashlib import sha256
+from pathlib import Path
+from typing import Any, Final
+from uuid import UUID
+
+import httpx
+
+from velophex import _json
+from velophex.contracts.package import PackageLayout
+from velophex.errors import VelophexError
+
+__all__ = ["PUBLISH_PATH_TEMPLATE", "PublishError", "PublishResult", "publish_package"]
+
+PUBLISH_PATH_TEMPLATE: Final = "/api/v1/tenants/{tenant_id}/feed/v3/package"
+
+#: The 409 ``code`` for bytes the feed already holds; the problem carries the server's ``sha256``.
+DUPLICATE_BINARY_CODE: Final = "package_binary_duplicate"
+#: The 409 ``code`` for a version the feed already holds with different bytes.
+VERSION_EXISTS_CODE: Final = "package_version_exists"
+
+_API_KEY_HEADER: Final = "X-NuGet-ApiKey"
+_DEFAULT_TIMEOUT: Final = httpx.Timeout(300.0, connect=15.0)
+
+
+class PublishError(VelophexError):
+    """The feed refused the package."""
+
+    def __init__(self, status_code: int, problem: dict[str, Any] | None, message: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.problem = problem or {}
+
+
+@dataclass(frozen=True, slots=True)
+class PublishResult:
+    """What the feed reported for a successful push."""
+
+    status_code: int
+    already_published: bool
+    body: Any | None
+
+
+def publish_package(
+    package_path: str | Path,
+    *,
+    public_base_url: str,
+    tenant_id: UUID | str,
+    api_key: str,
+    transport: httpx.BaseTransport | None = None,
+    timeout: httpx.Timeout | float = _DEFAULT_TIMEOUT,
+) -> PublishResult:
+    """Push *package_path* to the tenant's feed.
+
+    Args:
+        package_path: The ``.nupkg`` to publish.
+        public_base_url: The Orchestrator's public base URL, e.g.
+            ``https://orchestrator.example.com``.
+        tenant_id: The tenant whose feed receives the package.
+        api_key: A personal access token (``vpx_pat_…``) with ``packages.create``.
+        transport: An httpx transport, for tests.
+        timeout: Upload timeout; packages can be large and feeds can be far away.
+
+    Raises:
+        PublishError: The feed answered 4xx or 5xx, or could not be reached.
+    """
+    path = Path(package_path)
+
+    if not path.is_file():
+        raise PublishError(0, None, f"'{package_path}' does not exist.")
+
+    url = public_base_url.rstrip("/") + PUBLISH_PATH_TEMPLATE.format(tenant_id=tenant_id)
+    content = path.read_bytes()
+    files = {"package": (path.name, content, "application/octet-stream")}
+
+    with httpx.Client(timeout=timeout, transport=transport) as client:
+        try:
+            response = client.put(url, files=files, headers={_API_KEY_HEADER: api_key, "Accept": "application/json"})
+        except httpx.HTTPError as error:
+            raise PublishError(0, None, f"The feed at {url} could not be reached: {error}") from error
+
+    body = _body(response)
+
+    # A 409 is success only when the server proves it already holds these exact bytes: its own
+    # SHA-256 of the pushed package must equal ours. Different bytes under a published version
+    # would otherwise "succeed" while robots keep running the old code.
+    if response.status_code == httpx.codes.CONFLICT:
+        problem = body if isinstance(body, dict) else {}
+
+        if problem.get("code") == DUPLICATE_BINARY_CODE and problem.get("sha256") == sha256(content).hexdigest():
+            return PublishResult(status_code=response.status_code, already_published=True, body=body)
+
+        package = _identity(content) or path.name
+        why = (
+            "is already published with different content"
+            if problem.get("code") == VERSION_EXISTS_CODE
+            else f"conflicts with a published package ({problem.get('detail') or 'no detail'}), and the feed did "
+            "not confirm the bytes are identical"
+        )
+        raise PublishError(
+            response.status_code,
+            problem or None,
+            f"{package} {why}. A published version never changes: increment the version in project.json, "
+            "pack again and publish the new package.",
+        )
+
+    if not response.is_success:
+        detail = (body or {}).get("detail") if isinstance(body, dict) else None
+        raise PublishError(
+            response.status_code,
+            body if isinstance(body, dict) else None,
+            f"The feed refused {path.name} with {response.status_code}: {detail or response.reason_phrase}",
+        )
+
+    return PublishResult(status_code=response.status_code, already_published=False, body=body)
+
+
+def _identity(content: bytes) -> str | None:
+    """``<id> <version>`` from the package's manifest, or ``None`` when it cannot be read."""
+    try:
+        with zipfile.ZipFile(io.BytesIO(content)) as archive:
+            manifest = _json.loads(archive.read(PackageLayout.MANIFEST_PATH))
+        return f"{manifest['packageId']} {manifest['packageVersion']}"
+    except (KeyError, ValueError, TypeError, zipfile.BadZipFile):
+        return None
+
+
+def _body(response: httpx.Response) -> Any | None:
+    if not response.content:
+        return None
+
+    try:
+        return _json.loads(response.content)
+    except ValueError:
+        return None