feat: unify stand orchestration for pg-play

Author: O2eg

.github/workflows/publish.yml

@@ -15,7 +15,7 @@ concurrency:
 jobs:
   build:
     name: Test and build distributions
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 60
 
     steps:
@@ -28,7 +28,9 @@ jobs:
           python-version: "3.10"
 
       - name: Install test and build dependencies
-        run: python -m pip install --upgrade pip build twine ".[test]"
+        run: >-
+          python -m pip install --upgrade 'pip>=24.3,<26'
+          'build>=1.2,<2' 'twine>=6,<7' ".[test]"
 
       - name: Verify tag matches package version
         shell: bash
@@ -88,7 +90,7 @@ jobs:
   publish:
     name: Publish distributions to PyPI
     needs: build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 15
     environment:
       name: pypi

.github/workflows/tests.yml

@@ -2,11 +2,21 @@ name: tests
 
 on:
   push:
+    branches:
+      - "**"
   pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   unit:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
         python-version: ["3.10", "3.12"]
@@ -21,7 +31,7 @@ jobs:
       - run: pytest
 
   tls-integration:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     needs: unit
     timeout-minutes: 25
     steps:

README.md

@@ -193,7 +193,7 @@ Set the PostgreSQL major in `spec.postgres.version` or override it for one comma
 ```bash
 pg-stand \
   -c configs/primary-standby-async.yaml \
-  --postgres-version 18 \
+  --pg-version 18 \
   up
 ```
 
@@ -262,7 +262,8 @@ are never passed to them. The `logs` command reads the active CSV file recorded
 
 Managed builds validate image-schema, family, major, and base-image labels. Changing
 `base_image` therefore cannot silently reuse an incompatible local image with the same tag.
-The default PostgreSQL 10 base is `postgres:10-bullseye`; other versions use
+The default PostgreSQL 10 and 11 bases use `postgres:<version>-bullseye`, so managed-image
+builds do not depend on archived Debian Stretch repositories. Later versions use
 `postgres:<version>`.
 
 ## Certificate-only TLS
@@ -403,7 +404,7 @@ pg-stand -c CONFIG storage clean
 
 ## Stand lifecycle
 
-Global options (`-c`, `--postgres-version`, `--tls`/`--no-tls`, and `--json`) precede the command.
+Global options (`-c`, `--pg-version`, `--tls`/`--no-tls`, and `--json`) precede the command. `--postgres-version` remains a compatibility alias.
 
 ```bash
 pg-stand init [--directory PATH] [--force]
@@ -673,7 +674,7 @@ docker image ls \
   --filter label=io.pg-stand.managed=true \
   --filter label=io.pg-stand.resource-kind=managed-image
 
-docker image inspect pg-stand/postgres:17-pg-stand-managed
+docker image inspect pg-stand/postgres:18-pg-stand-managed
 
 docker system df -v
 ```
@@ -899,7 +900,7 @@ python -m build
 python -m twine check dist/*
 ```
 
-A tag matching the package version, for example `v0.2.0`, runs unit and Docker integration
+A tag matching the package version, for example `v0.2.1`, runs unit and Docker integration
 tests, builds the wheel and source distribution, smoke-tests the installed wheel, and publishes
 through PyPI Trusted Publishing. The GitHub `pypi` environment and a PyPI trusted publisher for
 `O2eg/pg_stand` and `.github/workflows/publish.yml` must be configured before the first release.

docs/pg_play-integration.md

@@ -6,11 +6,16 @@ observation commands remain the supported human interface.
 `pg_stand` supports the hidden `pg_play/component/v1` machine transport:
 
 ```bash
-pg-stand --machine --request-id stand-001 capabilities
+pg-stand --machine --request-id stand-001 --component-capabilities
 pg-stand --machine --request-id stand-002 --config stand.yaml validate
 pg-stand --machine --request-id stand-003 --config stand.yaml plan
 ```
 
+The capability document uses `pg_play/capabilities/v1`. Every command declares
+the common boolean fields `mutates_target`, `machine_output`, and
+`accepts_plan_hash`. The public `capabilities` subcommand remains available.
+The `machine_interface` object records the canonical hidden option names.
+
 To plan a generated `pg_configurator` candidate without rewriting the stand
 source, pass a JSON parameter mapping through standard input:
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pg-stand"
-version = "0.2.0"
+version = "0.2.1"
 description = "Declarative Docker PostgreSQL stand manager"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -36,14 +36,16 @@ dependencies = [
 
 [project.optional-dependencies]
 test = [
-  "pytest>=7.4",
+  "pytest>=8.3,<9",
   "tomli>=2.0; python_version < '3.11'",
 ]
 dev = [
-  "pytest>=7.4",
-  "pytest-cov>=4.1",
-  "ruff>=0.6",
+  "build>=1.2,<2",
+  "pytest>=8.3,<9",
+  "pytest-cov>=6,<8",
+  "ruff>=0.12,<1",
   "tomli>=2.0; python_version < '3.11'",
+  "twine>=6,<7",
 ]
 
 [project.scripts]

src/pg_stand/__init__.py

@@ -2,6 +2,6 @@
 
 from pg_stand.config import MANAGED_POSTGRES_PARAMETERS
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 __all__ = ["MANAGED_POSTGRES_PARAMETERS", "__version__"]

src/pg_stand/cli.py

@@ -502,6 +502,10 @@ def _run_machine(args: argparse.Namespace) -> int:
 def main(argv: Sequence[str] | None = None) -> int:
     parser = _parser()
     args = parser.parse_args(argv)
+    if args.component_capabilities:
+        args.command = "capabilities"
+    elif args.command is None:
+        parser.error("a command is required")
     if args.machine:
         return _run_machine(args)
     try:

src/pg_stand/cli_parser.py

@@ -63,7 +63,9 @@ def _parser() -> argparse.ArgumentParser:
         help="path to a pg_stand/v1 YAML configuration; optional only for active",
     )
     parser.add_argument(
+        "--pg-version",
         "--postgres-version",
+        dest="postgres_version",
         type=int,
         help="override spec.postgres.version without editing the configuration",
     )
@@ -87,8 +89,13 @@ def _parser() -> argparse.ArgumentParser:
         "--parameters-json",
         help=argparse.SUPPRESS,
     )
+    parser.add_argument(
+        "--component-capabilities",
+        action="store_true",
+        help=argparse.SUPPRESS,
+    )
 
-    commands = parser.add_subparsers(dest="command", required=True)
+    commands = parser.add_subparsers(dest="command")
     commands.add_parser("active", help="discover the active pg-stand lease without a config")
     init = commands.add_parser(
         "init", help="write editable example profiles and the JSON Schema into a project"

src/pg_stand/config.py

@@ -93,8 +93,8 @@ def image_name(self) -> str:
     def base_image_name(self) -> str:
         if self.base_image:
             return self._resolve_image_template(self.base_image, "postgres.base_image")
-        if self.version == 10:
-            return "postgres:10-bullseye"
+        if self.version in {10, 11}:
+            return f"postgres:{self.version}-bullseye"
         return f"postgres:{self.version}"
 
     @property

src/pg_stand/configs/primary-standby-async.yaml

@@ -6,7 +6,7 @@ metadata:
 
 spec:
   postgres:
-    version: 17
+    version: 18
     superuser: postgres
     initdb_args: "--data-checksums --auth-host=scram-sha-256"
     tls: