pyplines-builder 2026.9.2a1__tar.gz

pyplines_builder-2026.9.2a1/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: pyplines-builder
+Version: 2026.9.2a1
+Summary: Build and sign Pyplines Actions and Distributions
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.24
+Requires-Dist: docker<8,>=7.1
+Requires-Dist: cryptography>=44
+Requires-Dist: packaging>=25
+Requires-Dist: PyYAML>=6
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: referencing>=0.36
+
+# Pyplines Builder
+
+`pyplines-builder` is the Python/Typer authoring tool. `pyplines` remains the
+operational CLI: it installs and operates the resulting Distribution. Neither
+tool depends on the other. The obsolete Go/Buildah Action Builder is not used.
+
+Install with `pip install pyplines-builder`. Development: `uv sync --project builder`.
+Docker must provide Linux containers. The builder uses the Docker API, never a
+Docker/Buildah shell command. Source inspection runs in the target image using
+the SDK, not in the host interpreter.
+
+## Commands
+
+```text
+pyplines-builder version
+pyplines-builder check pyplines-build.yaml
+pyplines-builder keygen ./signing --source https://example.com --publisher example
+pyplines-builder build pyplines-build.yaml --registry registry.example.com/example \
+  --signing-key ./signing/publisher.pem --output ./hello-world-1.0.0.tar.gz
+pyplines-builder inspect ./hello-world-1.0.0.tar.gz
+pyplines-builder verify ./hello-world-1.0.0.tar.gz --trust-file ./signing/trust.json
+pyplines-builder action build ./action --platform linux/arm64
+pyplines-builder action inspect sha256:IMAGE_ID
+pyplines-builder action run sha256:IMAGE_ID --input-file ./input.yaml
+```
+
+Every command supports `--json`. Data goes to stdout, failures to stderr;
+failures have nonzero exit codes. No prompts, animations, or credential values
+in diagnostics. Local image IDs are reported by `action build`. `action run`
+reports runtime logs and the terminal InvocationResult; it does not replace
+testing against the Server. `--allow-network` explicitly enables test egress.
+
+## Build document
+
+See [Hello World](../example/v1alpha1/distributions/hello-world). The tooling-only
+`pyplines.dev/build/v1alpha1` document references workspace-neutral, standard
+Procedure resources and Action sources (or immutable prebuilt image references).
+IDs in Procedure references match IDs in the build document. Exactly one root
+Procedure is required; every included resource must be reachable from it.
+There is no additional Action Package format and no new platform resource.
+
+`check` performs offline structural checks; it does not import Action source or
+claim to validate runtime schemas. `build` validates the complete included
+resource graph. Server installation remains authoritative for semantic planning,
+authorization, trust and runtime compatibility.
+
+Each Action's `pyproject.toml` supplies static `project.name`, `version`,
+`requires-python`, and the `pyplines.action` handler entry point. Include source
+files explicitly with `[tool.pyplines.builder] include = ["hello_world.py"]`
+(default: `src`). Include required README/license/package data there too. No
+symlinks, hidden directories, environments or private-key files are copied.
+Review this allowlist: an ordinary source file can still contain a hardcoded
+secret. Building executes author-controlled packaging code and must only be
+done for trusted source on a suitable Docker engine.
+
+Python 3.11–3.14 is supported; the newest compatible minor is selected, or use
+`--python`. `--platform auto` uses the Docker engine's architecture. Cross-platform
+builds require engine-provided emulation. A build targets one architecture;
+produce a separately signed Distribution for each platform. Multi-platform OCI
+index assembly is not provided. `--base-image` permits an explicitly pinned Python
+base. Otherwise the selected Python slim tag is resolved to a digest before
+building. Base, source, SDK and recipe attribution is embedded at
+`/opt/pyplines/action/build.json` and returned in the build report. Docker provides
+layer caching. Unlocked third-party dependencies can change between builds;
+pin dependencies for reproducibility. Distribution bytes are deterministic for
+the same resource documents and signing key; source-to-image reproducibility is
+not claimed for unpinned dependencies.
+
+Released builders pin the matching published `pyplines` SDK. A development builder
+requires an explicit `--sdk-wheel`; it never silently includes the repository.
+Keep a private signing key outside Action sources. Keys are Ed25519 PKCS8 PEM,
+mode 0600 on POSIX. Existing keys and output archives are never overwritten.
+Existing registry version tags are reused only for identical images. Enable
+registry-side immutable tags as well to protect against concurrent publishers.
+The separate `trust.json` is public and can be supplied to Server trust
+configuration; the builder does not install trust or weaken verification.
+
+Private registries use `--registry-credentials /path/to/docker-auth.json`, a
+portable Docker `auths` file. Credential helpers/keychains are not required or
+invoked. Never put credentials in the build document or image reference.
+The default is anonymous registry access. Docker daemon insecure-registry
+configuration is needed for a local HTTP registry; the builder does not alter it.
+
+Local runtime tests use the same entrypoint, Unix socket transport, non-root UID,
+read-only root, capability restrictions and scratch mounts as the appliance.
+Test limits are 1 CPU, 256 MiB, 128 PIDs, 16 MiB scratch, 64 KiB test input/secrets,
+4 MiB collected logs and a configurable 1–3600 second deadline. Only the test's
+own containers/volume are removed. Build images/cache remain for reuse.
+
+## Development
+
+```sh
+python3 scripts/sync_builder_contracts.py --check
+uv run --project builder pytest -q builder/tests
+uv run --project builder black --check builder/pyplines_builder/app.py
+uv build --project builder
+```
+
+The generated readers and schema snapshot come from the same sources as the
+operational CLI. Edit those sources and regenerate, not the bundled copies.

pyplines_builder-2026.9.2a1/README.md

@@ -0,0 +1,100 @@
+# Pyplines Builder
+
+`pyplines-builder` is the Python/Typer authoring tool. `pyplines` remains the
+operational CLI: it installs and operates the resulting Distribution. Neither
+tool depends on the other. The obsolete Go/Buildah Action Builder is not used.
+
+Install with `pip install pyplines-builder`. Development: `uv sync --project builder`.
+Docker must provide Linux containers. The builder uses the Docker API, never a
+Docker/Buildah shell command. Source inspection runs in the target image using
+the SDK, not in the host interpreter.
+
+## Commands
+
+```text
+pyplines-builder version
+pyplines-builder check pyplines-build.yaml
+pyplines-builder keygen ./signing --source https://example.com --publisher example
+pyplines-builder build pyplines-build.yaml --registry registry.example.com/example \
+  --signing-key ./signing/publisher.pem --output ./hello-world-1.0.0.tar.gz
+pyplines-builder inspect ./hello-world-1.0.0.tar.gz
+pyplines-builder verify ./hello-world-1.0.0.tar.gz --trust-file ./signing/trust.json
+pyplines-builder action build ./action --platform linux/arm64
+pyplines-builder action inspect sha256:IMAGE_ID
+pyplines-builder action run sha256:IMAGE_ID --input-file ./input.yaml
+```
+
+Every command supports `--json`. Data goes to stdout, failures to stderr;
+failures have nonzero exit codes. No prompts, animations, or credential values
+in diagnostics. Local image IDs are reported by `action build`. `action run`
+reports runtime logs and the terminal InvocationResult; it does not replace
+testing against the Server. `--allow-network` explicitly enables test egress.
+
+## Build document
+
+See [Hello World](../example/v1alpha1/distributions/hello-world). The tooling-only
+`pyplines.dev/build/v1alpha1` document references workspace-neutral, standard
+Procedure resources and Action sources (or immutable prebuilt image references).
+IDs in Procedure references match IDs in the build document. Exactly one root
+Procedure is required; every included resource must be reachable from it.
+There is no additional Action Package format and no new platform resource.
+
+`check` performs offline structural checks; it does not import Action source or
+claim to validate runtime schemas. `build` validates the complete included
+resource graph. Server installation remains authoritative for semantic planning,
+authorization, trust and runtime compatibility.
+
+Each Action's `pyproject.toml` supplies static `project.name`, `version`,
+`requires-python`, and the `pyplines.action` handler entry point. Include source
+files explicitly with `[tool.pyplines.builder] include = ["hello_world.py"]`
+(default: `src`). Include required README/license/package data there too. No
+symlinks, hidden directories, environments or private-key files are copied.
+Review this allowlist: an ordinary source file can still contain a hardcoded
+secret. Building executes author-controlled packaging code and must only be
+done for trusted source on a suitable Docker engine.
+
+Python 3.11–3.14 is supported; the newest compatible minor is selected, or use
+`--python`. `--platform auto` uses the Docker engine's architecture. Cross-platform
+builds require engine-provided emulation. A build targets one architecture;
+produce a separately signed Distribution for each platform. Multi-platform OCI
+index assembly is not provided. `--base-image` permits an explicitly pinned Python
+base. Otherwise the selected Python slim tag is resolved to a digest before
+building. Base, source, SDK and recipe attribution is embedded at
+`/opt/pyplines/action/build.json` and returned in the build report. Docker provides
+layer caching. Unlocked third-party dependencies can change between builds;
+pin dependencies for reproducibility. Distribution bytes are deterministic for
+the same resource documents and signing key; source-to-image reproducibility is
+not claimed for unpinned dependencies.
+
+Released builders pin the matching published `pyplines` SDK. A development builder
+requires an explicit `--sdk-wheel`; it never silently includes the repository.
+Keep a private signing key outside Action sources. Keys are Ed25519 PKCS8 PEM,
+mode 0600 on POSIX. Existing keys and output archives are never overwritten.
+Existing registry version tags are reused only for identical images. Enable
+registry-side immutable tags as well to protect against concurrent publishers.
+The separate `trust.json` is public and can be supplied to Server trust
+configuration; the builder does not install trust or weaken verification.
+
+Private registries use `--registry-credentials /path/to/docker-auth.json`, a
+portable Docker `auths` file. Credential helpers/keychains are not required or
+invoked. Never put credentials in the build document or image reference.
+The default is anonymous registry access. Docker daemon insecure-registry
+configuration is needed for a local HTTP registry; the builder does not alter it.
+
+Local runtime tests use the same entrypoint, Unix socket transport, non-root UID,
+read-only root, capability restrictions and scratch mounts as the appliance.
+Test limits are 1 CPU, 256 MiB, 128 PIDs, 16 MiB scratch, 64 KiB test input/secrets,
+4 MiB collected logs and a configurable 1–3600 second deadline. Only the test's
+own containers/volume are removed. Build images/cache remain for reuse.
+
+## Development
+
+```sh
+python3 scripts/sync_builder_contracts.py --check
+uv run --project builder pytest -q builder/tests
+uv run --project builder black --check builder/pyplines_builder/app.py
+uv build --project builder
+```
+
+The generated readers and schema snapshot come from the same sources as the
+operational CLI. Edit those sources and regenerate, not the bundled copies.

pyplines_builder-2026.9.2a1/pyplines_builder/__init__.py

@@ -0,0 +1 @@
+"""Authoring tools for the v1alpha1 platform. No operational CLI dependency."""

pyplines_builder-2026.9.2a1/pyplines_builder/app.py

@@ -0,0 +1,347 @@
+"""Small, static Typer interface over reusable builder services."""
+
+from importlib.metadata import version as package_version
+import json
+from pathlib import Path
+import sys
+
+import typer
+from typer.core import TyperCommand, TyperGroup
+
+try:
+    from typer import _click as click
+except ImportError:
+    import click
+
+try:
+    from typer.exceptions import Abort
+except ImportError:
+    from typer._click.exceptions import Abort
+
+from .builds import build_document, procedures, build_distribution
+from .documents import read_document
+from .distributions import inspect_file
+from .errors import ClientError
+from .images import (
+    connection,
+    platform_name,
+    build_action,
+    image_manifest,
+    source_files,
+    push_action,
+)
+from .publication import keygen as generate_key, verify as verify_publication
+from .runtime import run_action
+
+
+class PlainCommand(TyperCommand):
+    def format_help(self, ctx, formatter):
+        self.format_usage(ctx, formatter)
+        self.format_help_text(ctx, formatter)
+        self.format_options(ctx, formatter)
+        self.format_epilog(ctx, formatter)
+
+
+class PlainGroup(TyperGroup):
+    format_help = PlainCommand.format_help
+
+    def main(self, args=None, standalone_mode=True, **kwargs):
+        arguments = list(sys.argv[1:] if args is None else args)
+        try:
+            result = super().main(args=arguments, standalone_mode=False, **kwargs)
+            if standalone_mode:
+                raise SystemExit(result if isinstance(result, int) else 0)
+            return result
+        except click.ClickException as exc:
+            if isinstance(exc, click.exceptions.NoArgsIsHelpError):
+                sys.stdout.write(exc.ctx.get_help() + "\n")
+                return 0
+            error = ClientError("invalid-command", exc.format_message(), 2)
+            sys.stderr.write(
+                (
+                    json.dumps(error.document())
+                    if "--json" in arguments
+                    else "Error: " + error.message
+                )
+                + "\n"
+            )
+            raise SystemExit(2) from None
+        except ClientError as exc:
+            if "--json" in arguments:
+                sys.stderr.write(json.dumps(exc.document()) + "\n")
+            else:
+                sys.stderr.write("Error: " + exc.message + "\n")
+            raise SystemExit(exc.exit_code) from None
+        except (KeyboardInterrupt, Abort):
+            error = ClientError(
+                "interrupted",
+                "Interrupted; check Docker if the connection failed during cleanup",
+                130,
+            )
+            sys.stderr.write(
+                (
+                    json.dumps(error.document())
+                    if "--json" in arguments
+                    else "Error: " + error.message
+                )
+                + "\n"
+            )
+            raise SystemExit(130) from None
+        except (OSError, ValueError, KeyError, TypeError) as exc:
+            error = ClientError(
+                "builder-failed",
+                "Builder input or operation failed ("
+                + type(exc).__name__
+                + "); check document fields, file permissions, signing trust and Docker availability",
+            )
+            sys.stderr.write(
+                (
+                    json.dumps(error.document())
+                    if "--json" in arguments
+                    else "Error: " + error.message
+                )
+                + "\n"
+            )
+            raise SystemExit(1) from None
+
+
+app = typer.Typer(
+    cls=PlainGroup,
+    help="Build and sign Pyplines Actions and Distributions.",
+    add_completion=False,
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+)
+actions = typer.Typer(
+    cls=PlainGroup,
+    help="Build and test Actions using Docker, without an installation.",
+    no_args_is_help=True,
+)
+app.add_typer(actions, name="action")
+
+
+@app.callback()
+def options(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit machine-readable JSON."
+    ),
+):
+    ctx.ensure_object(dict)
+    ctx.obj["json"] = json_output
+
+
+def emit(ctx, value, json_output=False):
+    if json_output or ctx.obj.get("json"):
+        typer.echo(json.dumps(value, ensure_ascii=False, allow_nan=False))
+    else:
+        for key, item in value.items():
+            text = (
+                json.dumps(item, indent=2, ensure_ascii=False)
+                if isinstance(item, (dict, list))
+                else str(item)
+            )
+            typer.echo(f"{key.replace('_', ' ').capitalize()}: {text}")
+
+
+@app.command(cls=PlainCommand)
+def version(ctx: typer.Context, json_output: bool = typer.Option(False, "--json")):
+    """Show the installed builder version."""
+    emit(ctx, {"version": package_version("pyplines-builder")}, json_output)
+
+
+@app.command(cls=PlainCommand)
+def keygen(
+    ctx: typer.Context,
+    directory: str,
+    source: str = typer.Option(...),
+    publisher: str = typer.Option(...),
+    key_id: str = typer.Option("publisher", "--key-id"),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Create a private signing key and separate public Server trust file."""
+    if not source.startswith("https://") or source.endswith("/"):
+        raise ClientError(
+            "invalid-source", "Use an HTTPS source without a trailing slash", 2
+        )
+    emit(ctx, generate_key(directory, source, publisher, key_id), json_output)
+
+
+@app.command("inspect", cls=PlainCommand)
+def inspect_distribution(
+    ctx: typer.Context,
+    distribution: str,
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Inspect a Distribution offline; does not assert publisher trust."""
+    emit(ctx, inspect_file(distribution).summary(), json_output)
+
+
+@app.command(cls=PlainCommand)
+def verify(
+    ctx: typer.Context,
+    distribution: str,
+    trust_file: str = typer.Option(..., "--trust-file"),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Verify resource digests and every Ed25519 publisher signature."""
+    from cryptography.exceptions import InvalidSignature
+
+    try:
+        value = verify_publication(distribution, trust_file)
+    except (InvalidSignature, KeyError, ValueError):
+        raise ClientError(
+            "invalid-publication",
+            "Publication is unsigned, untrusted, or has an invalid signature",
+        ) from None
+    emit(ctx, value, json_output)
+
+
+@app.command(cls=PlainCommand)
+def check(
+    ctx: typer.Context,
+    document: str = typer.Argument("pyplines-build.yaml"),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Check build-document/source structure without executing author code."""
+    directory, value = build_document(document)
+    resources = procedures(directory, value)
+    for action in value["actions"]:
+        if "source" in action:
+            source_files(directory / action["source"])
+    emit(
+        ctx,
+        {
+            "valid": True,
+            "procedures": len(resources),
+            "actions": len(value["actions"]),
+            "note": "Action schemas and the complete dependency graph are checked during build.",
+        },
+        json_output,
+    )
+
+
+@app.command(cls=PlainCommand)
+def build(
+    ctx: typer.Context,
+    document: str = typer.Argument("pyplines-build.yaml"),
+    output: str = typer.Option(..., "--output", "-o"),
+    signing_key: str = typer.Option(..., "--signing-key"),
+    registry: str = typer.Option("", "--registry"),
+    registry_credentials: str | None = typer.Option(None, "--registry-credentials"),
+    platform: str = "auto",
+    sdk_wheel: str | None = typer.Option(None, "--sdk-wheel"),
+    python: str | None = None,
+    base_image: str | None = typer.Option(None, "--base-image"),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Build/push Actions and emit one signed, installable Distribution."""
+    with connection(registry_credentials) as client:
+        result = build_distribution(
+            client,
+            document,
+            platform_name(client, platform),
+            registry,
+            signing_key,
+            output,
+            sdk_wheel,
+            python,
+            base_image,
+        )
+    emit(ctx, result, json_output)
+
+
+@actions.command("build", cls=PlainCommand)
+def action_build(
+    ctx: typer.Context,
+    source: str = typer.Argument("."),
+    platform: str = "auto",
+    sdk_wheel: str | None = typer.Option(None, "--sdk-wheel"),
+    python: str | None = None,
+    base_image: str | None = typer.Option(None, "--base-image"),
+    repository: str | None = None,
+    registry_credentials: str | None = typer.Option(None, "--registry-credentials"),
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Build a canonical Action image; --repository additionally pushes it."""
+    with connection(registry_credentials) as client:
+        result = build_action(
+            client,
+            source,
+            platform_name(client, platform),
+            sdk_wheel,
+            base_image,
+            python,
+        )
+        if repository:
+            result["published_image"] = push_action(
+                client,
+                result["image"],
+                repository,
+                result["manifest"]["action"]["version"],
+            )
+    emit(ctx, result, json_output)
+
+
+@actions.command("inspect", cls=PlainCommand)
+def action_inspect(
+    ctx: typer.Context,
+    image: str,
+    platform: str = "auto",
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Inspect a local built image's identity and input/output schemas without executing it."""
+    with connection() as client:
+        value = image_manifest(client, image, platform_name(client, platform))
+    emit(ctx, value, json_output)
+
+
+@actions.command("run", cls=PlainCommand)
+def action_run(
+    ctx: typer.Context,
+    image: str,
+    input_file: str = typer.Option(..., "--input-file"),
+    secrets_file: str | None = typer.Option(None, "--secrets-file"),
+    timeout: int = 60,
+    allow_network: bool = typer.Option(False, "--allow-network"),
+    platform: str = "auto",
+    json_output: bool = typer.Option(False, "--json"),
+):
+    """Test a built image through the real runtime protocol; networking is opt-in."""
+    with connection() as client:
+        manifest = image_manifest(client, image, platform_name(client, platform))
+        value = run_action(
+            client,
+            image,
+            manifest,
+            read_document(input_file),
+            timeout,
+            allow_network,
+            read_document(secrets_file) if secrets_file else None,
+        )
+    emit(ctx, value, json_output)
+    if value["result"]["status"] != "completed" or value["container_exit_code"] != 0:
+        raise typer.Exit(1)
+
+
+def main():
+    # Docker errors contain registry URLs/credentials and are not safe to echo.
+    from docker.errors import DockerException
+    from requests.exceptions import RequestException
+
+    try:
+        app()
+    except (DockerException, RequestException):
+        error = ClientError(
+            "docker-operation-failed",
+            "Docker operation failed; check engine availability, image/platform compatibility and registry access",
+        )
+        sys.stderr.write(
+            (
+                json.dumps(error.document())
+                if "--json" in sys.argv
+                else "Error: " + error.message
+            )
+            + "\n"
+        )
+        raise SystemExit(1) from None

pyplines_builder-2026.9.2a1/pyplines_builder/build.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Pyplines Builder document (tooling, not a platform resource)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["kind", "source", "publisher", "key_id", "root", "actions", "procedures"],
+  "properties": {
+    "kind": {"const": "pyplines.dev/build/v1alpha1"},
+    "source": {"type": "string", "format": "uri", "pattern": "^https://[^/?#@]+$"},
+    "publisher": {"$ref": "https://v1alpha1.pyplines.dev/schemas/SchemaCatalog.json#/$defs/slug"},
+    "key_id": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9._-]+$"},
+    "root": {"$ref": "https://v1alpha1.pyplines.dev/schemas/SchemaCatalog.json#/$defs/uuid"},
+    "procedures": {"type": "array", "minItems": 1, "maxItems": 256, "uniqueItems": true, "items": {"type": "string", "minLength": 1}},
+    "actions": {"type": "array", "maxItems": 255, "items": {
+      "type": "object", "additionalProperties": false, "required": ["id"],
+      "oneOf": [{"required": ["source"]}, {"required": ["image"]}],
+      "properties": {
+        "id": {"$ref": "https://v1alpha1.pyplines.dev/schemas/SchemaCatalog.json#/$defs/uuid"},
+        "source": {"type": "string", "minLength": 1},
+        "image": {"type": "string", "pattern": "^[^\\s@]+@sha256:[a-f0-9]{64}$"},
+        "size": {"enum": ["small", "medium", "large"]},
+        "network_required": {"type": "boolean"},
+        "retry_safety": {"enum": ["safe", "unsafe", "idempotency-key-required"]},
+        "secret_aliases": {"type": "array", "uniqueItems": true, "items": {"$ref": "https://v1alpha1.pyplines.dev/schemas/SchemaCatalog.json#/$defs/alias"}}
+      }
+    }}
+  }
+}