kuzybuild 0.2.0__py3-none-any.whl

kuzybuild/__init__.py

@@ -0,0 +1 @@
+"""Local build frontends. These commands never publish artifacts."""

kuzybuild/common.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tomllib
+
+
+def metadata(root: Path) -> tuple[str, str]:
+    from packaging.version import Version
+    project = tomllib.loads((root / "pyproject.toml").read_text())["project"]
+    name, version = project["name"], project["version"]
+    Version(version)
+    if not name or any(c not in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_." for c in name):
+        raise ValueError("invalid distribution name")
+    return name, version
+
+
+def native_name(root: Path) -> str:
+    data = tomllib.loads((root / "pyproject.toml").read_text())
+    name = data.get("tool", {}).get("kuzybuild", {}).get("native-name", data["project"]["name"])
+    if not isinstance(name, str) or not name or any(c not in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_." for c in name):
+        raise ValueError("invalid native package name")
+    return name
+
+
+def stage(root: Path, dest: Path) -> None:
+    def ignore(directory, names):
+        return [name for name in names if name in {
+            ".git", ".venv", "venv", "dist", "build", ".pybuild", ".pytest_cache",
+            ".mypy_cache", ".ruff_cache", "__pycache__",
+        } or name.endswith((".egg-info", ".pyc"))]
+    shutil.copytree(root, dest, ignore=ignore, symlinks=True)
+    for path in dest.rglob("*"):
+        if path.is_symlink():
+            try:
+                path.resolve().relative_to(dest.resolve())
+            except ValueError:
+                raise ValueError(f"source symlink escapes project: {path.relative_to(dest)}") from None
+
+
+def run(command: list[str], cwd: Path) -> None:
+    subprocess.run(command, cwd=cwd, check=True)
+
+
+def publish_local(artifacts: list[Path], output: Path, info: dict) -> None:
+    if not artifacts:
+        raise ValueError("build produced no artifacts")
+    output.mkdir(parents=True, exist_ok=True)
+    names = [artifact.name for artifact in artifacts]
+    record_path = output / (artifacts[0].name + ".build.json")
+    if len(names) != len(set(names)):
+        raise ValueError("build produced duplicate artifact names")
+    if any((output / name).exists() or (output / name).is_symlink() for name in names) or record_path.exists() or record_path.is_symlink():
+        raise ValueError("output artifacts already exist; use another --out-dir (nothing is deleted)")
+    hashes = {}
+    for artifact in artifacts:
+        target = output / artifact.name
+        with artifact.open("rb") as source, target.open("xb") as dest:
+            shutil.copyfileobj(source, dest)
+        with target.open("rb") as stream:
+            hashes[target.name] = hashlib.file_digest(stream, "sha256").hexdigest()
+    record = {**info, "artifacts": hashes, "published": False}
+    with record_path.open("x") as stream:
+        json.dump(record, stream, indent=2)
+        stream.write("\n")
+    print(json.dumps(record))
+
+
+def parser(kind: str) -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(prog=f"kuzybuild-{kind}")
+    result.add_argument("--release", action="store_true", help="Build the exact project version; no tag or upload.")
+    result.add_argument("--out-dir", type=Path)
+    return result
+
+
+def main_guard(func) -> int:
+    try:
+        return func()
+    except (ValueError, OSError, subprocess.CalledProcessError) as exc:
+        print(f"build failed: {exc}", file=sys.stderr)
+        return 1

kuzybuild/pypi.py

@@ -0,0 +1,42 @@
+"""Build/check local PyPI artifacts; deliberately no upload command."""
+from pathlib import Path
+import sys
+import tempfile
+import tomllib
+
+from .common import main_guard, metadata, parser, publish_local, run, stage
+
+
+def build() -> int:
+    ap = parser("pypi")
+    ap.add_argument("--no-isolation", action="store_true", help="Use installed build dependencies.")
+    args = ap.parse_args()
+    root = Path.cwd().resolve()
+    config = tomllib.loads((root / "pyproject.toml").read_text())
+    enabled = config.get("tool", {}).get("kuzybuild", {}).get("pypi", True)
+    if not isinstance(enabled, bool):
+        raise ValueError("tool.kuzybuild.pypi must be a boolean")
+    if not enabled:
+        raise ValueError("PyPI target disabled by tool.kuzybuild.pypi=false; native builds remain available")
+    name, version = metadata(root)
+    output = (args.out_dir or root / "dist/pypi").absolute()
+    with tempfile.TemporaryDirectory(prefix="kuzybuild-pypi-") as tmp:
+        source = Path(tmp) / "source"
+        stage(root, source)
+        command = [sys.executable, "-m", "build", "--outdir", str(Path(tmp) / "artifacts")]
+        if args.no_isolation:
+            command.append("--no-isolation")
+        # build's default builds the wheel from the sdist, not the checkout.
+        run(command, source)
+        artifacts = sorted((Path(tmp) / "artifacts").iterdir())
+        run([sys.executable, "-m", "twine", "check", "--strict", *map(str, artifacts)], source)
+        publish_local(artifacts, output, {"format": "pypi", "project": name, "version": version})
+    return 0
+
+
+def main() -> int:
+    return main_guard(build)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kuzybuild/rpm.py

@@ -0,0 +1,67 @@
+"""Native Fedora RPM frontend; never create a repository or upload anything."""
+from pathlib import Path
+import re
+import subprocess
+import tarfile
+import tempfile
+import tomllib
+
+from .common import main_guard, metadata, native_name, parser, publish_local, run, stage
+
+
+def build() -> int:
+    ap = parser("rpm")
+    ap.add_argument("--target-fedora", default="45")
+    ap.add_argument("--revision", default="1")
+    args = ap.parse_args()
+    if not re.fullmatch(r"[1-9][0-9]*", args.target_fedora) or not re.fullmatch(r"[1-9][0-9]*", args.revision):
+        raise ValueError("Fedora target and revision must be positive integers")
+    root = Path.cwd().resolve()
+    config = tomllib.loads((root / "pyproject.toml").read_text())
+    enabled = config.get("tool", {}).get("kuzybuild", {}).get("rpm", True)
+    if not isinstance(enabled, bool):
+        raise ValueError("tool.kuzybuild.rpm must be a boolean")
+    if not enabled:
+        raise ValueError("RPM target disabled by tool.kuzybuild.rpm=false; Python and Debian builds remain available")
+    native = subprocess.check_output(["rpm", "--eval", "%{fedora}"], text=True).strip()
+    if native != args.target_fedora:
+        raise ValueError(f"build inside Fedora {args.target_fedora}; native RPM target is {native!r}")
+    distribution, version = metadata(root)
+    name = native_name(root)
+    if not re.fullmatch(r"[0-9]+(?:\.[0-9]+)+", version):
+        raise ValueError("RPM releases currently require numeric dotted project versions")
+    output = (args.out_dir or root / "dist/rpm").absolute()
+    if not (root / "packaging/rpm" / f"{name}.spec").is_file():
+        raise ValueError(f"missing RPM spec for {name}")
+    with tempfile.TemporaryDirectory(prefix="kuzybuild-rpm-") as tmp:
+        top = Path(tmp)
+        for folder in ("SOURCES", "SPECS", "BUILD", "BUILDROOT", "RPMS", "SRPMS"):
+            (top / folder).mkdir()
+        source = top / f"{name}-{version}"
+        stage(root, source)
+        spec = source / "packaging/rpm" / f"{name}.spec"
+        text, count = re.subn(r"^Version:\s*\S+", f"Version:        {version}", spec.read_text(), flags=re.M)
+        if count != 1:
+            raise ValueError("spec must declare exactly one Version field")
+        text, count = re.subn(r"^Release:\s*\S+", f"Release:        {args.revision}%{{?dist}}", text, flags=re.M)
+        if count != 1:
+            raise ValueError("spec must declare exactly one Release field")
+        spec.write_text(text)
+        with tarfile.open(top / "SOURCES" / f"{name}-{version}.tar.gz", "w:gz") as tar:
+            tar.add(source, arcname=source.name)
+        run(["rpmbuild", "--define", f"_topdir {top}", "-ba", str(spec)], source)
+        artifacts = sorted((top / "RPMS").rglob("*.rpm")) + sorted((top / "SRPMS").glob("*.rpm"))
+        publish_local(artifacts, output, {
+            "format": "rpm", "project": name, "version": version,
+            "python_distribution": distribution,
+            "fedora": native, "revision": args.revision,
+        })
+    return 0
+
+
+def main() -> int:
+    return main_guard(build)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kuzybuild-0.2.0.data/scripts/kuzybuild-deb

@@ -0,0 +1,277 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$PWD"
+OUTPUT_DIR="${ROOT_DIR}/dist/debian"
+REVISION="1"
+EXACT_VERSION=""
+RELEASE="0"
+TARGET_CODENAME="${KUZYBUILD_TARGET_CODENAME:-}"
+TARGET_REVISION="${KUZYBUILD_TARGET_REVISION:-1}"
+
+PROG_NAME="$(basename "${BASH_SOURCE[0]}")"
+
+usage() {
+  cat <<USAGE
+Usage:
+  ${PROG_NAME} [options]
+
+Run from the project root (must contain pyproject.toml and debian/changelog).
+
+Options:
+  --version <v>              Build exact Debian version, for example
+                             0.1.0~dev202604271200-1 (incompatible with
+                             --target-codename: an explicit version is
+                             used verbatim)
+  --revision <n>             Debian revision for generated versions (default: 1)
+  --release                  Build the base release version from pyproject.toml
+  --target-codename <name>   Build for a specific Debian release. Rewrites
+                             the Distribution field in debian/changelog and
+                             appends a ~<codename><target-revision> suffix
+                             to the computed version. Pass "auto" to detect
+                             the host codename via lsb_release -cs.
+                             Env var: KUZYBUILD_TARGET_CODENAME
+  --target-revision <n>      Revision inside a given <codename> suffix
+                             (default: 1). Env var: KUZYBUILD_TARGET_REVISION
+  --out-dir <path>           Output directory (default: ./dist/debian)
+  --help                     Show this help
+
+Default:
+  Build a timestamped snapshot version:
+    <pyproject-version>~devYYYYMMDDHHMM-<revision>
+
+With --target-codename, the version becomes:
+    <computed-version>~<codename><target-revision>
+  and the changelog Distribution field is set to <codename> instead of
+  "unstable". The working copy of the calling repo is never modified:
+  the build runs in a staging copy under \$TMPDIR.
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --version)
+      EXACT_VERSION="${2:-}"
+      shift 2
+      ;;
+    --revision)
+      REVISION="${2:-}"
+      shift 2
+      ;;
+    --release)
+      RELEASE="1"
+      shift
+      ;;
+    --target-codename)
+      TARGET_CODENAME="${2:-}"
+      shift 2
+      ;;
+    --target-revision)
+      TARGET_REVISION="${2:-}"
+      shift 2
+      ;;
+    --out-dir)
+      OUTPUT_DIR="${2:-}"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ ! -f "${ROOT_DIR}/pyproject.toml" || ! -f "${ROOT_DIR}/debian/changelog" ]]; then
+  echo "Error: must be run from a project root containing pyproject.toml and debian/changelog." >&2
+  echo "       current directory: ${ROOT_DIR}" >&2
+  exit 1
+fi
+
+if [[ "$TARGET_CODENAME" == "auto" ]]; then
+  if ! command -v lsb_release >/dev/null 2>&1; then
+    echo "Error: --target-codename=auto requires lsb_release (install lsb-release)." >&2
+    exit 1
+  fi
+  TARGET_CODENAME="$(lsb_release -cs)"
+  if [[ -z "$TARGET_CODENAME" ]]; then
+    echo "Error: lsb_release -cs returned empty codename." >&2
+    exit 1
+  fi
+fi
+
+if [[ -n "$TARGET_CODENAME" ]]; then
+  if [[ ! "$TARGET_CODENAME" =~ ^[a-z][a-z0-9]*$ ]]; then
+    echo "Error: invalid target codename '${TARGET_CODENAME}' (expected lowercase alnum)." >&2
+    exit 1
+  fi
+  if [[ ! "$TARGET_REVISION" =~ ^[0-9]+$ ]]; then
+    echo "Error: invalid --target-revision '${TARGET_REVISION}' (expected integer)." >&2
+    exit 1
+  fi
+  if [[ -n "$EXACT_VERSION" ]]; then
+    echo "Error: --version and --target-codename are mutually exclusive." >&2
+    echo "       An explicit version is used verbatim; add the suffix yourself if needed." >&2
+    exit 1
+  fi
+fi
+
+base_version() {
+  python3 - "$ROOT_DIR/pyproject.toml" <<'PY'
+from __future__ import annotations
+
+import sys
+import tomllib
+from pathlib import Path
+
+print(tomllib.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))["project"]["version"])
+PY
+}
+
+check_changelog_matches() {
+  local pyproject_version="$1"
+  local changelog_path="${ROOT_DIR}/debian/changelog"
+  python3 - "$pyproject_version" "$changelog_path" <<'PY'
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+pyproject_version, changelog_path = sys.argv[1:]
+first_line = Path(changelog_path).read_text(encoding="utf-8").splitlines()[0]
+match = re.match(r"^[^(]+\(([^)]+)\)", first_line)
+if not match:
+    raise SystemExit(f"debian/changelog: cannot parse first line: {first_line!r}")
+debian_version = match.group(1)
+if ":" in debian_version:
+    debian_version = debian_version.split(":", 1)[1]
+upstream = debian_version.rsplit("-", 1)[0]
+if upstream != pyproject_version:
+    raise SystemExit(
+        f"version mismatch: pyproject.toml has {pyproject_version!r} "
+        f"but debian/changelog top stanza has upstream version {upstream!r}. "
+        f"Bump the lagging file before building."
+    )
+PY
+}
+
+validate_version() {
+  local value="$1"
+  if [[ ! "$value" =~ ^[0-9][A-Za-z0-9.+:~]*-[A-Za-z0-9.+~]+$ ]]; then
+    echo "Invalid Debian version: $value" >&2
+    exit 1
+  fi
+}
+
+SOURCE_NAME="$(dpkg-parsechangelog -l "${ROOT_DIR}/debian/changelog" -S Source)"
+ARCH="$(dpkg --print-architecture)"
+BASE_VERSION="$(base_version)"
+check_changelog_matches "$BASE_VERSION"
+
+if [[ -n "$EXACT_VERSION" ]]; then
+  VERSION="$EXACT_VERSION"
+elif [[ "$RELEASE" == "1" ]]; then
+  VERSION="${BASE_VERSION}-${REVISION}"
+else
+  VERSION="${BASE_VERSION}~dev$(date -u +%Y%m%d%H%M)-${REVISION}"
+fi
+
+if [[ -n "$TARGET_CODENAME" ]]; then
+  VERSION="${VERSION}~${TARGET_CODENAME}${TARGET_REVISION}"
+fi
+
+validate_version "$VERSION"
+
+DISTRIBUTION="${TARGET_CODENAME:-unstable}"
+
+mkdir -p "${OUTPUT_DIR}"
+OUTPUT_DIR="$(cd "$OUTPUT_DIR" && pwd -P)"
+if [[ -n "$(find "$OUTPUT_DIR" -mindepth 1 -maxdepth 1 -print -quit)" ]]; then
+  echo "Error: output directory is not empty; choose another --out-dir (nothing is deleted)." >&2
+  exit 1
+fi
+
+STAGE_DIR="$(mktemp -d -t "kuzybuild-stage.XXXXXX")"
+cleanup_stage() {
+  rm -rf "$STAGE_DIR"
+}
+trap cleanup_stage EXIT
+
+STAGE_PROJECT="${STAGE_DIR}/$(basename "$ROOT_DIR")"
+python3 - "$ROOT_DIR" "$STAGE_PROJECT" <<'PY'
+import shutil
+import sys
+from pathlib import Path
+
+source, target = map(Path, sys.argv[1:])
+shutil.copytree(source, target, symlinks=True, ignore=shutil.ignore_patterns(
+    '.git', '.venv', 'venv', 'dist', 'build', '.pybuild', '__pycache__',
+    '.pytest_cache', '.mypy_cache', '.ruff_cache', '*.egg-info', '*.pyc',
+))
+for path in target.rglob('*'):
+    if path.is_symlink() and not path.resolve().is_relative_to(target.resolve()):
+        raise SystemExit(f'source symlink escapes project: {path.relative_to(target)}')
+PY
+
+BUILD_DATE="$(date -Ru)"
+python3 - "$SOURCE_NAME" "$VERSION" "$DISTRIBUTION" "$BUILD_DATE" "${ROOT_DIR}/debian/changelog" "${STAGE_PROJECT}/debian/changelog" <<'PY'
+from __future__ import annotations
+
+from email.utils import parsedate_to_datetime
+import sys
+from pathlib import Path
+
+source_name, version, distribution, build_date, source_path, target_path = sys.argv[1:]
+lines = Path(source_path).read_text(encoding="utf-8").splitlines()
+if not lines:
+    raise SystemExit("debian/changelog is empty")
+lines[0] = f"{source_name} ({version}) {distribution}; urgency=medium"
+for index, line in enumerate(lines):
+    if line.startswith(" -- "):
+        selected_date = build_date
+        try:
+            existing_date = line.rsplit("  ", 1)[1]
+            if parsedate_to_datetime(existing_date) > parsedate_to_datetime(build_date):
+                selected_date = existing_date
+        except Exception:
+            pass
+        lines[index] = f" -- Michele Renda <michele@example.invalid>  {selected_date}"
+        break
+else:
+    raise SystemExit("debian/changelog: maintainer trailer not found")
+Path(target_path).write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+PY
+
+(
+  cd "${STAGE_PROJECT}"
+  dpkg-buildpackage -us -uc -b
+)
+
+shopt -s nullglob
+for artifact in "${STAGE_DIR}/"*_"${VERSION}"_all.deb \
+  "${STAGE_DIR}/"*_"${VERSION}"_"${ARCH}".deb \
+  "${STAGE_DIR}/${SOURCE_NAME}_${VERSION}_${ARCH}.buildinfo" \
+  "${STAGE_DIR}/${SOURCE_NAME}_${VERSION}_${ARCH}.changes"; do
+  if [[ -f "${artifact}" ]]; then
+    mv -n "${artifact}" "${OUTPUT_DIR}/"
+  fi
+done
+shopt -u nullglob
+
+if ! command -v lintian >/dev/null 2>&1; then
+  echo "Missing packaging check command: lintian" >&2
+  echo "Install with: sudo apt install lintian" >&2
+  exit 127
+fi
+
+(
+  cd "${OUTPUT_DIR}"
+  lintian "${SOURCE_NAME}_${VERSION}_${ARCH}.changes"
+)
+
+ls -1 "${OUTPUT_DIR}"

kuzybuild-0.2.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: kuzybuild
+Version: 0.2.0
+Summary: Local Debian, Fedora RPM and Python build helpers for kuzys.
+Author: Michele Renda
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://gitlab.com/kuzys/kuzybuild
+Project-URL: Repository, https://gitlab.com/kuzys/kuzybuild
+Project-URL: Issues, https://gitlab.com/kuzys/kuzybuild/-/issues
+Keywords: kuzys,debian,packaging,build
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: build>=1.2.2
+Requires-Dist: packaging>=24.2
+Requires-Dist: twine>=6.1
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Dynamic: license-file
+
+# kuzybuild
+
+Build Debian, Fedora RPM and Python distributions with shared checks and version rules.
+
+kuzybuild provides `kuzybuild-deb`, `kuzybuild-rpm` and `kuzybuild-pypi` for
+maintainers. They build locally, without publishing, installing packages,
+creating tags or creating repositories. You do not need kuzybuild to use
+another kuzys application.
+
+It is part of [kuzys](https://www.kuzys.com/tools.html), a suite of tools for long-lived AI agents.
+
+## What is included
+
+- `bin/kuzybuild-deb`: the shared Bash build command.
+- `src/kuzybuild/`: Python distribution and native RPM frontends.
+- `debian/`: the recipe for packaging kuzybuild itself.
+- `pyproject.toml`: package metadata and the upstream version.
+
+The helper checks that the project version and Debian changelog agree before
+building. It calls `dpkg-buildpackage`; each project's `debian/rules` decides
+how to build, install and test that project. It does not replace those recipes.
+
+## Install
+
+Choose one method; do not install Python packages into the system Python with
+pip. Source-build instructions and the Python/native boundary are documented
+in [Distribution packaging](docs/DISTRIBUTION_PACKAGING.md).
+
+### Python / PyPI
+
+Use Python 3.11 or newer with virtual-environment support, without sudo:
+
+```sh
+python3 -m venv ~/.venvs/kuzybuild
+. ~/.venvs/kuzybuild/bin/activate
+python -m pip install 'kuzybuild'
+```
+
+This installs all three build frontends, not the native toolchains.
+Debian builds also need dpkg-dev, debhelper, dh-python,
+pybuild-plugin-pyproject and lintian. Fedora builds need rpm-build,
+python3-devel, pyproject-rpm-macros and the project's BuildRequires.
+
+### Debian 13 / APT
+
+Configure the kuzys APT repository using [Get started](https://www.kuzys.com/install.html),
+then install on Debian 13 (trixie), amd64:
+
+```sh
+sudo apt install kuzybuild
+```
+
+Install each target project's build dependencies before building it; kuzybuild
+does not replace the project's native recipe.
+
+### Fedora 45 / RPM
+
+Configure the [kuzys RPM repository](https://rpm.kuzys.com/) using its
+repository and signing-key instructions. The coordinated release targets
+Fedora 45 on x86_64, from the kuzys testing repository. Once the repository
+and the package release are available:
+
+```sh
+sudo dnf install kuzybuild
+```
+
+The package supplies native RPM build prerequisites. Each target project's
+BuildRequires must also be installed, and RPM builds must run on Fedora 45.
+
+## First build
+
+Run from a project containing `pyproject.toml` and `debian/changelog`, after
+installing that project's build dependencies:
+
+```sh
+kuzybuild-deb --help
+kuzybuild-deb --release --target-codename trixie
+```
+
+The result goes into `dist/debian/`: `.deb` packages, a `.buildinfo` file and a
+`.changes` file. lintian checks the changes file. The original checkout is
+copied to a temporary staging directory; its changelog is not rewritten.
+
+The Debian output directory must be empty. No frontend removes old artifacts:
+choose a fresh `--out-dir` for each build. Staging excludes Git metadata,
+virtual environments, caches and previous build outputs.
+
+## Python and Fedora builds
+
+From a project root:
+
+```sh
+kuzybuild-pypi --release
+kuzybuild-rpm --release --target-fedora 45
+```
+
+The first builds an sdist and then builds its wheel from that sdist, and runs
+`twine check --strict`. It writes to `dist/pypi/`. Build isolation is enabled
+by default; `--no-isolation` is only for an already prepared build environment.
+All kuzys projects use `setuptools>=77.0.3`, including PEP 639 license metadata.
+
+The RPM frontend must run inside Fedora 45, with the project's BuildRequires
+installed. It uses `packaging/rpm/NAME.spec`, overrides Version from the Python
+metadata and Release from `--revision` in the staging copy only, and executes
+`rpmbuild -ba` including `%check`. It writes binary and source RPMs to
+`dist/rpm/`; it does not cross-build on Debian or pass `--nodeps`.
+
+When a Python distribution needs a distinct PyPI name, set
+`[tool.kuzybuild] native-name = "NAME"` in pyproject.toml (as a normal TOML
+table and key). The native source/spec name can then remain unchanged;
+Python import names and command names are independent of distribution names.
+
+Both new frontends record artifact SHA-256 hashes in a `.build.json` file.
+For PyPI releases there is deliberately no upload command: inspect the local
+artifacts, verify name ownership and obtain publication approval separately.
+
+A project excluded from the PyPI flow sets this in `pyproject.toml`:
+
+```toml
+[tool.kuzybuild]
+pypi = false
+```
+
+`kuzybuild-pypi` then refuses before building or creating output. This is a
+workflow safeguard, not a PyPI access-control mechanism. Native Deb/RPM builds
+and their internal Python wheel builds remain available.
+
+Independently, `rpm = false` in the same table disables `kuzybuild-rpm` before
+native tools are invoked. Python and Debian targets are unaffected. This is
+used when a required Fedora dependency is unavailable rather than emitting
+an RPM with an incomplete dependency declaration.
+
+## Version options
+
+| Option | Result |
+|---|---|
+| No version option | Timestamped development version. |
+| `--release` | Upstream version with a Debian revision. |
+| `--revision 2` | Change the Debian revision. |
+| `--target-codename trixie` | Add a distribution suffix and set the changelog distribution. |
+| `--target-revision 2` | Change the revision within that distribution suffix. |
+| `--version VERSION` | Use an exact Debian version; incompatible with `--target-codename`. |
+| `--out-dir PATH` | Collect artifacts in a different, disposable directory. |
+
+For example, upstream `0.2.0` with `--release --target-codename trixie` becomes
+`0.2.0-1~trixie1`. Use `--help` for environment variables and all options.
+
+## Development and bootstrap
+
+The in-tree command runs before the kuzybuild package itself is installed.
+On a Debian development machine with Python 3.11 or newer:
+
+```sh
+sudo apt install dpkg-dev debhelper dh-python pybuild-plugin-pyproject python3-all python3-setuptools python3-build python3-packaging python3-pytest twine lintian
+bash -n bin/kuzybuild-deb
+bin/kuzybuild-deb --help
+bin/kuzybuild-deb --release
+```
+
+The last command builds kuzybuild itself. Other repositories need their own
+build dependencies too. Projects using the helper declare it in
+`Build-Depends`. For the initial Fedora bootstrap, install kuzybuild's spec
+BuildRequires and run `PYTHONPATH=src python3 -m kuzybuild.rpm --release`.
+
+## Status and limits
+
+- The Fedora frontend currently supports numeric dotted release versions.
+- A distribution suffix is a label, not isolation. Build and test in an
+  environment with the target distribution's dependencies.
+- This command does not publish packages, sign repositories or install packages.
+- Builds include local changes. Use a reviewed, clean revision for a release.
+
+## License
+
+AGPL-3.0-or-later. See [LICENSE](LICENSE).
+
+## Distribution packaging
+
+See [Distribution packaging](docs/DISTRIBUTION_PACKAGING.md) for the common
+build commands, the Python/native boundary and external dependencies.