feat: introduce manifest-driven project control plane

.commitlintrc.yml

@@ -0,0 +1,5 @@
+extends:
+  - '@commitlint/config-conventional'
+
+rules:
+  header-max-length: [0, 'always', 100]

.dockerignore

@@ -0,0 +1,10 @@
+.git
+.github
+.idea
+.scratch
+dist
+Dockerfile
+.dockerignore
+devctl
+sx
+devctl-skills

.github/scripts/compute_release_version.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Literal
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+RC_IGNORE_TAGS = r"^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$"
+RC_VERSION_RE = re.compile(r"^(\d+\.\d+\.\d+)-rc\.(\d+)$")
+ReleaseKind = Literal["stable", "rc"]
+
+
+def bumped_version(release_kind: ReleaseKind) -> str:
+    try:
+        raw_version = run_command(*build_git_cliff_args(release_kind))
+    except subprocess.CalledProcessError as exc:
+        stderr = (exc.stderr or "").strip()
+        if "No releases found" in stderr:
+            return "0.1.0"
+        raise RuntimeError(stderr or "git-cliff failed while computing the next version.") from exc
+
+    return raw_version
+
+
+def build_git_cliff_args(release_kind: ReleaseKind) -> list[str]:
+    args = ["git-cliff"]
+    if release_kind == "stable":
+        args.extend(["--ignore-tags", RC_IGNORE_TAGS])
+    args.append("--bumped-version")
+    return args
+
+
+def build_git_cliff_context_args(release_kind: ReleaseKind) -> list[str]:
+    args = ["git-cliff", "--unreleased", "--bump", "--context"]
+    if release_kind == "stable":
+        args.extend(["--ignore-tags", RC_IGNORE_TAGS])
+    return args
+
+
+def run_command(*args: str) -> str:
+    completed = subprocess.run(
+        args,
+        cwd=REPO_ROOT,
+        check=True,
+        text=True,
+        capture_output=True,
+    )
+    return completed.stdout.strip()
+
+
+def normalize_version(raw_version: str) -> str:
+    version = raw_version.strip()
+    if version.startswith("v"):
+        version = version[1:]
+    return version
+
+
+def compute_next_tag(raw_version: str, release_kind: ReleaseKind) -> str:
+    version = normalize_version(raw_version)
+    if not version:
+        raise RuntimeError("git-cliff did not return a version.")
+
+    if release_kind == "stable":
+        if RC_VERSION_RE.fullmatch(version):
+            raise RuntimeError("git-cliff returned a prerelease version for a stable release.")
+        return f"v{version}"
+
+    if RC_VERSION_RE.fullmatch(version):
+        return f"v{version}"
+    return f"v{version}-rc.1"
+
+
+def release_commit_count(release_kind: ReleaseKind) -> int:
+    try:
+        raw_context = run_command(*build_git_cliff_context_args(release_kind))
+    except subprocess.CalledProcessError as exc:
+        stderr = (exc.stderr or "").strip()
+        raise RuntimeError(stderr or "git-cliff failed while checking for new commits.") from exc
+
+    try:
+        context = json.loads(raw_context)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError("git-cliff returned invalid JSON while checking for new commits.") from exc
+
+    if not context:
+        return 0
+
+    statistics = context[0].get("statistics", {})
+    return int(statistics.get("commit_count", 0))
+
+
+def ensure_new_commits(release_kind: ReleaseKind) -> None:
+    if release_commit_count(release_kind) == 0:
+        raise RuntimeError("nothing to release")
+
+
+def tag_exists(tag: str) -> bool:
+    completed = subprocess.run(
+        ["git", "ls-remote", "--exit-code", "--tags", "origin", f"refs/tags/{tag}"],
+        cwd=REPO_ROOT,
+        text=True,
+        capture_output=True,
+    )
+    if completed.returncode == 0:
+        return True
+    if completed.returncode == 2:
+        return False
+
+    stderr = (completed.stderr or completed.stdout or "").strip()
+    raise RuntimeError(stderr or f"git failed while checking whether {tag} exists in origin.")
+
+
+def ensure_tag_absent(tag: str) -> None:
+    if tag_exists(tag):
+        raise RuntimeError(f"tag {tag} already exists in origin")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="compute_release_version.py",
+        description="Compute the next release tag for stable or rc workflows.",
+    )
+    parser.add_argument(
+        "--release-kind",
+        required=True,
+        choices=("stable", "rc"),
+        help="Release line to compute the next tag for.",
+    )
+    parser.add_argument(
+        "--require-new-commits",
+        action="store_true",
+        help="Fail if there are no unreleased commits for the selected release line.",
+    )
+    parser.add_argument(
+        "--require-absent-tag",
+        action="store_true",
+        help="Fail if the computed release tag already exists in origin.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.require_new_commits:
+            ensure_new_commits(args.release_kind)
+        next_tag = compute_next_tag(bumped_version(args.release_kind), args.release_kind)
+        if args.require_absent_tag:
+            ensure_tag_absent(next_tag)
+        print(next_tag)
+    except (RuntimeError, subprocess.CalledProcessError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/scripts/tests/test_compute_release_version.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import io
+import subprocess
+import sys
+import unittest
+from contextlib import redirect_stderr
+from pathlib import Path
+from unittest.mock import patch
+
+
+SCRIPT_ROOT = Path(__file__).resolve().parents[1]
+if str(SCRIPT_ROOT) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_ROOT))
+
+import compute_release_version as release_version
+
+
+class ComputeReleaseVersionTests(unittest.TestCase):
+    def test_normalize_version_strips_leading_v(self) -> None:
+        self.assertEqual(release_version.normalize_version("v1.2.3"), "1.2.3")
+        self.assertEqual(release_version.normalize_version("1.2.3"), "1.2.3")
+
+    def test_build_git_cliff_args_for_stable_adds_ignore_tags(self) -> None:
+        self.assertEqual(
+            release_version.build_git_cliff_args("stable"),
+            ["git-cliff", "--ignore-tags", release_version.RC_IGNORE_TAGS, "--bumped-version"],
+        )
+
+    def test_build_git_cliff_args_for_rc_omits_ignore_tags(self) -> None:
+        self.assertEqual(release_version.build_git_cliff_args("rc"), ["git-cliff", "--bumped-version"])
+
+    def test_build_git_cliff_context_args_for_stable_adds_ignore_tags(self) -> None:
+        self.assertEqual(
+            release_version.build_git_cliff_context_args("stable"),
+            [
+                "git-cliff",
+                "--unreleased",
+                "--bump",
+                "--context",
+                "--ignore-tags",
+                release_version.RC_IGNORE_TAGS,
+            ],
+        )
+
+    def test_build_git_cliff_context_args_for_rc_omits_ignore_tags(self) -> None:
+        self.assertEqual(
+            release_version.build_git_cliff_context_args("rc"),
+            ["git-cliff", "--unreleased", "--bump", "--context"],
+        )
+
+    def test_bumped_version_returns_raw_git_cliff_output(self) -> None:
+        with patch.object(release_version, "run_command", return_value="v1.2.4"):
+            self.assertEqual(release_version.bumped_version("stable"), "v1.2.4")
+
+    def test_bumped_version_falls_back_without_releases(self) -> None:
+        error = subprocess.CalledProcessError(
+            returncode=1,
+            cmd=("git-cliff", "--bumped-version"),
+            stderr="No releases found, using 0.1.0 as the next version.",
+        )
+
+        with patch.object(release_version, "run_command", side_effect=error):
+            self.assertEqual(release_version.bumped_version("stable"), "0.1.0")
+            self.assertEqual(release_version.bumped_version("rc"), "0.1.0")
+
+    def test_release_commit_count_parses_json_context(self) -> None:
+        with patch.object(
+            release_version,
+            "run_command",
+            return_value='[{"statistics":{"commit_count":2}}]',
+        ):
+            self.assertEqual(release_version.release_commit_count("stable"), 2)
+
+    def test_release_commit_count_handles_empty_context(self) -> None:
+        with patch.object(release_version, "run_command", return_value="[]"):
+            self.assertEqual(release_version.release_commit_count("rc"), 0)
+
+    def test_ensure_new_commits_raises_for_empty_release(self) -> None:
+        with patch.object(release_version, "release_commit_count", return_value=0):
+            with self.assertRaisesRegex(RuntimeError, "nothing to release"):
+                release_version.ensure_new_commits("stable")
+
+    def test_compute_next_tag_for_stable_prefixes_version(self) -> None:
+        self.assertEqual(release_version.compute_next_tag("v1.2.4", "stable"), "v1.2.4")
+
+    def test_compute_next_tag_for_rc_keeps_existing_rc_suffix(self) -> None:
+        self.assertEqual(release_version.compute_next_tag("v1.2.4-rc.2", "rc"), "v1.2.4-rc.2")
+
+    def test_compute_next_tag_for_rc_adds_first_suffix_for_plain_version(self) -> None:
+        self.assertEqual(release_version.compute_next_tag("v1.2.4", "rc"), "v1.2.4-rc.1")
+
+    def test_compute_next_tag_for_stable_rejects_prerelease_version(self) -> None:
+        with self.assertRaisesRegex(RuntimeError, "prerelease version"):
+            release_version.compute_next_tag("v1.2.4-rc.2", "stable")
+
+    def test_compute_next_tag_for_empty_version_rejects_empty_output(self) -> None:
+        with self.assertRaisesRegex(RuntimeError, "did not return a version"):
+            release_version.compute_next_tag("   ", "stable")
+
+    def test_tag_exists_returns_true_when_origin_has_tag(self) -> None:
+        completed = subprocess.CompletedProcess(args=(), returncode=0, stdout="ref", stderr="")
+        with patch.object(release_version.subprocess, "run", return_value=completed):
+            self.assertTrue(release_version.tag_exists("v1.2.3"))
+
+    def test_tag_exists_returns_false_when_origin_has_no_tag(self) -> None:
+        completed = subprocess.CompletedProcess(args=(), returncode=2, stdout="", stderr="")
+        with patch.object(release_version.subprocess, "run", return_value=completed):
+            self.assertFalse(release_version.tag_exists("v1.2.3"))
+
+    def test_tag_exists_raises_for_git_errors(self) -> None:
+        completed = subprocess.CompletedProcess(args=(), returncode=128, stdout="", stderr="network failed")
+        with patch.object(release_version.subprocess, "run", return_value=completed):
+            with self.assertRaisesRegex(RuntimeError, "network failed"):
+                release_version.tag_exists("v1.2.3")
+
+    def test_ensure_tag_absent_raises_for_existing_tag(self) -> None:
+        with patch.object(release_version, "tag_exists", return_value=True):
+            with self.assertRaisesRegex(RuntimeError, "tag v1.2.3 already exists in origin"):
+                release_version.ensure_tag_absent("v1.2.3")
+
+    def test_main_fails_on_empty_release_when_required(self) -> None:
+        stderr = io.StringIO()
+        with (
+            patch.object(release_version, "ensure_new_commits", side_effect=RuntimeError("nothing to release")),
+            patch.object(release_version, "bumped_version") as bumped_version,
+            redirect_stderr(stderr),
+        ):
+            self.assertEqual(
+                release_version.main(["--release-kind", "stable", "--require-new-commits"]),
+                1,
+            )
+        bumped_version.assert_not_called()
+        self.assertEqual(stderr.getvalue().strip(), "nothing to release")
+
+    def test_main_fails_on_existing_tag_when_required(self) -> None:
+        stderr = io.StringIO()
+        with (
+            patch.object(release_version, "bumped_version", return_value="v1.2.4"),
+            patch.object(release_version, "ensure_tag_absent", side_effect=RuntimeError("tag v1.2.4 already exists in origin")),
+            redirect_stderr(stderr),
+        ):
+            self.assertEqual(
+                release_version.main(["--release-kind", "stable", "--require-absent-tag"]),
+                1,
+            )
+        self.assertEqual(stderr.getvalue().strip(), "tag v1.2.4 already exists in origin")
+
+
+if __name__ == "__main__":
+    unittest.main()