pg-maker 0.1.0__tar.gz

pg_maker-0.1.0/.gitattributes

@@ -0,0 +1,9 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.pdf binary
+*.whl binary
+*.gz binary
+*.xz binary
+# PostgreSQL regression output preserves psql alignment and final blank lines.
+tests/fixtures/stage4/**/expected/*.out -whitespace

pg_maker-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-publish
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    name: Verify and build the tagged source
+    uses: ./.github/workflows/tests.yml
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pg-maker
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: python-distributions
+          path: dist/
+      - name: Publish verified artifacts with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1

pg_maker-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,117 @@
+name: tests
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_call:
+  workflow_dispatch:
+    inputs:
+      run_db_tests:
+        description: Run the long PostgreSQL and installed database qualification suites
+        type: boolean
+        default: false
+      with_doc:
+        description: Build and install the English HTML, man and PDF documentation
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.12']
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6; shared pg_diag convention
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff check . && ruff format --check .
+      - run: python tools/check_release.py
+      - run: python tools/generate_planning_schemas.py && git diff --exit-code -- src/pg_maker/schemas
+      - run: python -m pytest -q tests/unit tests/contracts
+  distribution:
+    runs-on: ubuntu-24.04
+    needs: unit
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+      - run: python -m pip install 'build>=1.2,<2' 'twine>=6,<7'
+      - name: Check release identity
+        shell: bash
+        run: |
+          if [ "$GITHUB_REF_TYPE" = tag ]; then
+            python tools/check_release.py --tag "$GITHUB_REF_NAME"
+          else
+            python tools/check_release.py
+          fi
+      - run: python -m build
+      - run: python -m twine check --strict dist/*
+      - run: python tools/check_release.py --dist dist
+      - run: python tools/smoke_wheel.py dist/*.whl
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  docker:
+    runs-on: ubuntu-24.04
+    needs: unit
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -e '.[dev]'
+      - run: python tools/ci_pipeline.py --work "${RUNNER_TEMP}/pg-maker-fixtures" --fixtures-only
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: fixture-evidence
+          path: ${{ runner.temp }}/pg-maker-fixtures/exports
+          retention-days: 7
+
+  postgresql:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-24.04
+    needs: docker
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -e '.[dev]'
+      - name: Build PostgreSQL packages; database tests are explicit
+        env:
+          RUN_DB_TESTS: ${{ inputs.run_db_tests }}
+          WITH_DOC: ${{ inputs.with_doc }}
+        shell: bash
+        run: |
+          args=()
+          if [ "$RUN_DB_TESTS" = true ]; then args+=(--run-db-tests); fi
+          if [ "$WITH_DOC" = true ]; then args+=(--with-doc); fi
+          python tools/ci_pipeline.py --work "${RUNNER_TEMP}/pg-maker-postgresql" "${args[@]}"
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: postgresql-evidence
+          path: ${{ runner.temp }}/pg-maker-postgresql/exports
+          retention-days: 7

pg_maker-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.tox/
+.nox/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+build/
+dist/
+runs/
+operations/
+/.cache/
+/inputs/
+/development/
+/work/
+/delivery/
+*.log
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo

pg_maker-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0 — 2026-10-18
+
+Initial alpha of the PostgreSQL distribution controller:
+
+- Strict YAML configuration, pinned sources/environments, immutable locks and plans.
+- Isolated Docker builds, durable operations, events, cancellation, recovery and caches.
+- PostgreSQL 14–19 catalog; initial Debian 13 / x86_64 / DEB platform.
+- Default pg_stat_statements, pg_stat_kcache and pg_wait_sampling recipes with manuals.
+- Documentation-only and combined builds using DocBook/Sphinx, local assets, HTML/man/PDF
+  and explicit translation bundles.
+- Server/client/libpq/docs packaging, manifests, offline installation checks and exports.
+- Owned Git development sessions, patch import/refresh/pop/push/rebase, conflict recovery,
+  selected component rebuilds, debug commands and iteration retention.
+- Optional pg_play CLI/API/MCP integration and runtime image handoff.
+- English project documentation, distribution-content checks and a tag-triggered PyPI
+  Trusted Publishing workflow.
+
+Database suites are opt-in; quick/development builds remain unverified. RPM, additional
+platforms and PostgreSQL distribution repository publication remain future work.
+See the [roadmap](docs/roadmap.md) and dated validation reports for precise boundaries.

pg_maker-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Use Linux and Python 3.10 or newer. Install the checkout in a virtual environment:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+.venv/bin/python tools/generate_planning_schemas.py
+.venv/bin/python tools/check_release.py
+.venv/bin/pytest -q tests/unit tests/contracts
+```
+
+Review generated schema changes with the matching interface contract. Keep every
+project Markdown file in English, including examples and fixture descriptions.
+PostgreSQL manuals produced by the utility can use configured languages. Preserve
+upstream copyright/license notices in fixtures and generated artifacts.
+
+Public changes need an updated MD contract and, where applicable, JSON Schema.
+Use MakerService for CLI/API behavior, typed argv for commands, the shared logger,
+durable state/events and owned-resource cleanup. Prefer small concrete adapters;
+add protocols only at real replacement boundaries. See [architecture](docs/architecture.md)
+and [interfaces](docs/interfaces/README.md).
+
+## Tests and storage
+
+Unit/contract tests do not require PostgreSQL builds. Small Docker tests are opt-in;
+variables select already available images. A tiny development pipeline fixture needs
+an image with Make and the current non-root build user:
+
+```bash
+PG_MAKER_DEVELOPMENT_IMAGE=sha256:FULL_IMAGE_ID .venv/bin/pytest -q tests/integration/test_development_pipeline.py
+```
+
+This checks failed extension builds, Git fixes, core/component reuse, debug execution
+and retention without starting a database. Other fixtures use PG_MAKER_DOCKER_IMAGE,
+PG_MAKER_BUILD_IMAGE, PG_MAKER_PREPARATION_IMAGE, PG_MAKER_PACKAGE_ENVIRONMENTS and
+PG_MAKER_DOC_ENVIRONMENTS. CI prepares its own fixture environments through
+`tools/ci_pipeline.py --fixtures-only`.
+
+Database suites remain off by default. The expensive PG_MAKER_BUILD_LOCK integration
+and manual --run-db-tests path are separate checks, not routine prerequisites for
+editing the Python utility. Never treat a successful quick build as database qualification.
+Check free disk before work; use [explicit cleanup](docs/development-storage.md) and
+retain useful evidence. Do not put runs, inputs, environments, credentials or build
+artifacts into Git.
+
+## Distribution checks
+
+```bash
+.venv/bin/python -m build
+.venv/bin/python -m twine check --strict dist/*
+.venv/bin/python tools/check_release.py --dist dist
+.venv/bin/python tools/smoke_wheel.py dist/*.whl
+```
+
+Use a distribution directory containing exactly one version. Release checks compare
+all Markdown and runtime package files byte-for-byte between source, wheel and sdist,
+and ensure test fixtures/tooling are present in sdist. Wheel smoke creates and removes
+a temporary isolated environment, installs dependencies, checks entry points and
+initializes/validates a project outside checkout. It does not contact Docker.
+Publication is described in [releasing](docs/releasing.md).

pg_maker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleg Gurov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pg_maker-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE *.md pyproject.toml MANIFEST.in
+include .gitignore .gitattributes
+recursive-include .github/workflows *.yml
+recursive-include docs *.md
+recursive-include tests *.py
+recursive-include tests/fixtures *
+recursive-include tools *.py
+global-exclude __pycache__ *.py[cod]
+prune build
+prune dist

pg_maker-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: pg-maker
+Version: 0.1.0
+Summary: Build PostgreSQL distributions, documentation and patches in isolated environments
+Author-email: O2eg <oleg.ispu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://o2eg.com/
+Project-URL: Repository, https://github.com/O2eg/pg_maker
+Project-URL: Issues, https://github.com/O2eg/pg_maker/issues
+Project-URL: Documentation, https://github.com/O2eg/pg_maker/blob/main/README.md
+Keywords: postgresql,build,packaging,documentation,docker
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: PyYAML<7,>=6
+Requires-Dist: packaging<27,>=24
+Requires-Dist: lxml<7,>=5.3
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: pytest<9,>=8.3; extra == "dev"
+Requires-Dist: ruff<1,>=0.12; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+Requires-Dist: tomli<3,>=2; python_version < "3.11" and extra == "dev"
+Dynamic: license-file
+
+# pg_maker
+
+A Python controller for building PostgreSQL distributions, packages and documentation
+in isolated Docker environments. It also provides Git development sessions for
+editing patches, recovering failed builds and rebuilding individual extensions.
+
+The current package is an **alpha**. The implemented platform is Debian 13 / x86_64,
+with release/debug builds and DEB packages. The PostgreSQL catalog covers majors
+14–19, including beta/RC identities; versions below 14 are unsupported. Catalog
+coverage is distinct from validation coverage: see the [major-version report](docs/validation/postgresql-majors.md).
+RPM, other platforms and distribution repository publishing remain on the
+[roadmap](docs/roadmap.md).
+
+## Installation
+
+Requires Linux and Python 3.10+. Container operations require a local Docker daemon;
+Git development sessions also require Git. Installing the Python package and reading
+capabilities do not require Docker.
+
+From PyPI:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install pg-maker
+.venv/bin/pg-maker --help
+```
+
+For development, from a source checkout:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+.venv/bin/pg-maker --help
+.venv/bin/pg-maker --component-capabilities
+.venv/bin/pg-maker doctor --machine
+```
+
+A built wheel can be installed with `python -m pip install /path/to/pg_maker-VERSION-py3-none-any.whl`.
+
+## Build a distribution
+
+```bash
+pg-maker init example
+pg-maker validate example/build.yaml
+pg-maker config show example/build.yaml --resolved
+pg-maker env prepare example/build.yaml --out example/environments.json --operations example/operations
+pg-maker resolve example/build.yaml --environments example/environments.json --out example/lock.json --input-store example/inputs --operations example/operations
+pg-maker plan example/lock.json --out example/plan.json --goal build
+pg-maker build example/lock.json --plan example/plan.json --operations example/operations --detach
+```
+
+`init` creates editable vendor/defaults/documentation YAML, a `my-feature` variant,
+component recipes, schemas and the built-in socket-directory patch. The initial
+target is PostgreSQL 18.1 / Debian 13 / x86_64 / DEB, without documentation.
+The default components are `pg_stat_statements`, `pg_stat_kcache 2.3.2` and
+`pg_wait_sampling 1.1.11`. External sources are pinned by commit SHA. Set
+`components: []` to omit additional extensions. See [component recipes](docs/interfaces/components.md).
+
+`env prepare` downloads missing base images and installs dependencies inside
+containers. Its result records build/test image IDs, package versions and toolchain
+inventory. `resolve` freezes source commits, submodules, snapshots, archive
+checksums and ChangeSets in a BuildLock. Offline resolution reuses stored inputs
+and reports missing ones. Both operations support `--detach` and `--request-id`.
+
+The build user defaults to `1000:1000` and must match the non-root owner of the
+workspace. Environment preparation creates this user inside the image. Build
+commands run with networking disabled. Outputs stay inside the operation directory.
+
+**Database tests are disabled by default while developing the utility.** A normal
+build compiles the candidate and components without `check`, `check-world`,
+component tests, acceptance tests or a baseline build. Reports remain `unverified`,
+with `db_tests=skipped` and `publication_eligible=false`. Tests of pg_maker itself
+remain enabled.
+
+Use `--goal package` to build server/client/libpq DEBs, manifests, installation
+instructions and HTML/JSON reports. A quick package build remains unverified.
+The long source/database test adapter currently supports major 18 only:
+
+```bash
+pg-maker build example/lock.json --run-db-tests --operations example/operations
+# Explicitly requests source and installed-package qualification:
+pg-maker build example/lock.json --goal verified --operations example/operations
+```
+
+A supplied plan controls the test mode; create it with `plan --run-db-tests` when
+needed. `--skip-db-tests` explicitly selects the quick path. Successful source
+suites grant at most `source-verified`; `package-verified` requires installed-package
+qualification too. See [build](docs/interfaces/build.md) and [packaging](docs/interfaces/packaging.md).
+
+## Build documentation only
+
+```bash
+pg-maker init docs-project --with-doc --doc-language en
+pg-maker env prepare docs-project/build.yaml --out docs-project/environments.json
+pg-maker resolve docs-project/build.yaml --environments docs-project/environments.json --out docs-project/lock.json
+pg-maker docs build docs-project/lock.json
+```
+
+`docs build` builds documentation without compiling the server or producing DEBs.
+It accepts official archive/Git sources or a snapshot of a locally modified source
+tree. Set `branding: none` for upstream PostgreSQL branding. The default HTML uses
+`sphinx_book_theme`, with an expandable sidebar, page contents and local search.
+The footer uses the selected product, version, feature, language and optional vendor
+links. `html_backend: docbook` selects the original DocBook layout explicitly.
+
+`config/documentation.yaml` selects HTML/man/PDF. The two external extensions'
+guides join the main Sphinx HTML/PDF manual when documentation is enabled.
+Russian PostgreSQL output requires a complete, current external translation bundle;
+the project's own Markdown documentation is English. HTML/PDF can be packaged in
+a separate docs DEB, with manpages assigned to the packages that own their commands.
+See the [documentation contract](docs/interfaces/documentation.md).
+
+## Develop code and patches
+
+```bash
+pg-maker dev open development --from-run example/operations/FAILED_RUN
+pg-maker dev status development
+# Edit the source paths returned by status, then record a patch:
+pg-maker dev patch development commit --scope component:pg-wait-sampling --id fix-build
+pg-maker dev explain development --component pg-wait-sampling
+pg-maker dev build development --component pg-wait-sampling
+```
+
+Each session owns real Git repositories. It can import an existing local repository
+with history, maintain intermediate commits, refresh patches, pop/push a series and
+resolve rebase conflicts. New iterations freeze changed inputs into new locks;
+`resume` retains its original meaning: retry the same operation with the same inputs.
+Independent extensions and the core can be reused when their inputs match. Header,
+ABI, toolchain and declared dependency changes invalidate affected results.
+[Development guide](docs/development.md) and [interface contract](docs/interfaces/development.md).
+
+## Observe and retain results
+
+```bash
+pg-maker status example/operations/RUN --machine
+pg-maker events example/operations/RUN --after-sequence 0 --limit 20 --machine
+pg-maker wait example/operations/RUN --timeout 120 --machine
+pg-maker cancel example/operations/RUN --machine
+pg-maker export example/operations/RUN --out exported-result
+```
+
+The detached worker owns the operation. Closing a waiting CLI does not cancel it;
+cancellation is explicit and repeatable. `status` returns success when it can read
+the operation, even if the operation failed; `wait` returns the operation's exit code.
+The [Python API](docs/interfaces/api.md) and optional pg_play CLI/MCP integration
+use the same service and machine contract.
+
+Source stores, workspaces, checkpoints and Docker caches consume disk space.
+Check `df -h`, workspace sizes and `docker system df` before long runs. Use explicit
+preview/apply cleanup and preserve needed outputs. See [storage and cleanup](docs/development-storage.md).
+
+## Project documentation
+
+- [Architecture](docs/architecture.md) and [reuse decisions](docs/reuse.md).
+- [Roadmap and implementation limits](docs/roadmap.md).
+- [Interface specifications](docs/interfaces/README.md).
+- [Validation reports](docs/validation/stage56.md), [documentation](docs/validation/stage7.md)
+  and [integration](docs/validation/integration.md).
+- [Contributing and local checks](CONTRIBUTING.md).
+- [Git and PyPI release procedure](docs/releasing.md).
+
+Distributed under the [MIT License](LICENSE). Third-party test fixtures retain their
+original copyright and license notices.