h2h-dev-tools 0.2.1__py3-none-any.whl

h2h_dev_tools/formal.py

@@ -0,0 +1,209 @@
+"""Checksum-pinned TLC acquisition and offline host/container execution."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import tomllib
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+TlaRuntime = Literal["auto", "host", "docker"]
+
+
+@dataclass(frozen=True)
+class TlcLock:
+    filename: str
+    url: str
+    sha256: str
+    runtime_image: str
+
+
+def load_tlc_lock(path: Path, *, expected_version: str) -> TlcLock:
+    with path.open("rb") as stream:
+        document = tomllib.load(stream)
+    value = document.get("tla_plus", {}).get("tlc")
+    if not isinstance(value, dict):
+        raise RuntimeError(f"Missing [tla_plus.tlc] in {path}")
+    if value.get("version") != expected_version:
+        raise RuntimeError(f"Unsupported tla_plus.tlc.version in {path}")
+    for field in ("filename", "url", "sha256", "runtime_image"):
+        if not isinstance(value.get(field), str) or not value[field]:
+            raise RuntimeError(f"Invalid tla_plus.tlc.{field} in {path}")
+    filename, url, digest, image = (
+        str(value[field]) for field in ("filename", "url", "sha256", "runtime_image")
+    )
+    if Path(filename).name != filename or filename in {".", ".."}:
+        raise RuntimeError(f"tla_plus.tlc.filename in {path} must be a basename")
+    if not url.startswith("https://"):
+        raise RuntimeError(f"tla_plus.tlc.url in {path} must use HTTPS")
+    if re.fullmatch(r"[0-9a-fA-F]{64}", digest) is None:
+        raise RuntimeError(f"tla_plus.tlc.sha256 in {path} is invalid")
+    if re.fullmatch(r"[^@]+@sha256:[0-9a-f]{64}", image) is None:
+        raise RuntimeError(
+            f"tla_plus.tlc.runtime_image in {path} must be digest-pinned"
+        )
+    return TlcLock(filename, url, digest.lower(), image)
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def verify_jar(path: Path, expected: str) -> None:
+    actual = sha256(path)
+    if actual != expected:
+        raise RuntimeError(
+            f"TLC checksum mismatch: expected={expected} actual={actual}"
+        )
+
+
+def fetch_tlc(lock: TlcLock, output_directory: Path) -> Path:
+    """Explicit online acquisition; verification never calls this function."""
+    output_directory.mkdir(parents=True, exist_ok=True)
+    destination = output_directory / lock.filename
+    if destination.is_file() and sha256(destination) == lock.sha256:
+        return destination
+    with tempfile.NamedTemporaryFile(
+        dir=output_directory, prefix=".tlc-", delete=False
+    ) as temporary:
+        temporary_path = Path(temporary.name)
+        try:
+            with urllib.request.urlopen(lock.url, timeout=60) as response:
+                shutil.copyfileobj(response, temporary)
+        except BaseException:
+            temporary_path.unlink(missing_ok=True)
+            raise
+    try:
+        verify_jar(temporary_path, lock.sha256)
+        os.replace(temporary_path, destination)
+    finally:
+        temporary_path.unlink(missing_ok=True)
+    return destination
+
+
+def fetch_main(repository_root: Path, *, expected_version: str) -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--output-directory", type=Path, default=repository_root / ".formal-tools"
+    )
+    arguments = parser.parse_args()
+    lock = load_tlc_lock(
+        repository_root / "verification/tools.lock.toml",
+        expected_version=expected_version,
+    )
+    print(fetch_tlc(lock, arguments.output_directory))
+
+
+def host_java_available() -> bool:
+    java = shutil.which("java")
+    if java is None:
+        return False
+    result = subprocess.run(
+        [java, "-version"],
+        check=False,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    return result.returncode == 0
+
+
+def _run(command: list[str], *, cwd: Path) -> None:
+    print("+", " ".join(command), flush=True)
+    subprocess.run(command, cwd=cwd, check=True)
+
+
+def verify_tla(
+    repository_root: Path,
+    tla_jar: Path,
+    *,
+    profile: str,
+    runtime: TlaRuntime,
+    expected_version: str,
+) -> None:
+    """Execute the explicitly selected finite model profile, without downloading."""
+    repository_root = repository_root.resolve()
+    if not tla_jar.is_file():
+        raise FileNotFoundError(f"TLC JAR does not exist: {tla_jar}")
+    lock = load_tlc_lock(
+        repository_root / "verification/tools.lock.toml",
+        expected_version=expected_version,
+    )
+    verify_jar(tla_jar, lock.sha256)
+    configs = sorted((repository_root / "verification/tla").glob(f"*{profile}.cfg"))
+    if not configs:
+        raise RuntimeError("No TLA+ model configurations were found")
+    use_host_java = runtime == "host" or (runtime == "auto" and host_java_available())
+    if runtime == "host" and not host_java_available():
+        raise RuntimeError("The requested host Java runtime is not available")
+    if not use_host_java and shutil.which("docker") is None:
+        raise RuntimeError("Neither a working Java runtime nor Docker is available")
+    for config in configs:
+        module_stem = config.name.removesuffix(f"{profile}.cfg")
+        if not module_stem:
+            raise RuntimeError(f"Cannot infer a TLA+ module from {config.name}")
+        module = config.with_name(f"{module_stem}.tla")
+        if not module.is_file():
+            raise RuntimeError(f"Missing TLA+ module for {config.name}")
+        with tempfile.TemporaryDirectory(prefix="h2h-tlc-") as state_directory:
+            if use_host_java:
+                command = [
+                    "java",
+                    "-XX:+UseParallelGC",
+                    "-Xmx4g",
+                    "-cp",
+                    str(tla_jar.resolve()),
+                    "tlc2.TLC",
+                    "-workers",
+                    "auto",
+                    "-metadir",
+                    str(Path(state_directory) / config.stem),
+                    "-config",
+                    config.name,
+                    module.name,
+                ]
+                _run(command, cwd=config.parent)
+            else:
+                command = [
+                    "docker",
+                    "run",
+                    "--rm",
+                    "--pull=never",
+                    "--network",
+                    "none",
+                    "--read-only",
+                    "--tmpfs",
+                    "/tmp:rw,nosuid,nodev,size=512m",
+                    "--mount",
+                    f"type=bind,src={repository_root},dst=/workspace,readonly",
+                    "--mount",
+                    f"type=bind,src={tla_jar.resolve()},dst=/tools/tla2tools.jar,readonly",
+                    "--workdir",
+                    "/workspace/verification/tla",
+                    lock.runtime_image,
+                    "java",
+                    "-XX:+UseParallelGC",
+                    "-Xmx4g",
+                    "-cp",
+                    "/tools/tla2tools.jar",
+                    "tlc2.TLC",
+                    "-workers",
+                    "auto",
+                    "-metadir",
+                    f"/tmp/tlc/{config.stem}",
+                    "-config",
+                    config.name,
+                    module.name,
+                ]
+                _run(command, cwd=repository_root)

h2h_dev_tools/git-flow-merge.sh

@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+fail() {
+    printf 'git-flow-merge: %s\n' "$1" >&2
+    exit 1
+}
+
+usage() {
+    printf 'usage: scripts/git-flow-merge.sh [--cleanup-only]\n' >&2
+}
+
+assert_clean() {
+    local status_output worktree=$1
+
+    status_output="$(
+        git -C "$worktree" status --porcelain=v1 --untracked-files=all
+    )" || fail "could not inspect worktree status: $worktree"
+    [[ -z "$status_output" ]] \
+        || fail "worktree is not clean: $worktree"
+}
+
+assert_no_operation() {
+    local git_path name worktree=$1
+
+    for name in \
+        MERGE_HEAD \
+        CHERRY_PICK_HEAD \
+        REVERT_HEAD \
+        REBASE_HEAD \
+        rebase-apply \
+        rebase-merge \
+        sequencer \
+        BISECT_START; do
+        git_path="$(
+            git -C "$worktree" \
+                rev-parse --path-format=absolute --git-path "$name"
+        )" || fail "could not inspect Git operation state: $worktree"
+        [[ ! -e "$git_path" ]] || fail "Git operation is active: $name"
+    done
+}
+
+assert_ref_equals() {
+    local actual expected=$3 ref=$2 worktree=$1
+
+    actual="$(
+        git -C "$worktree" rev-parse --verify "$ref^{commit}" 2>/dev/null
+    )" || fail "Git ref is no longer available: $ref"
+    [[ "$actual" == "$expected" ]] \
+        || fail "Git ref changed during cleanup: $ref"
+}
+
+is_ancestor() {
+    local ancestor=$2 descendant=$3 status worktree=$1
+
+    if git -C "$worktree" merge-base --is-ancestor "$ancestor" "$descendant"; then
+        return 0
+    else
+        status=$?
+    fi
+    [[ "$status" -eq 1 ]] \
+        || fail "could not verify commit ancestry: $ancestor $descendant"
+    return 1
+}
+
+abort_merge_if_needed() {
+    local worktree=$1 merge_head
+
+    merge_head="$(
+        git -C "$worktree" \
+            rev-parse --path-format=absolute --git-path MERGE_HEAD
+    )" || fail "could not inspect merge state: $worktree"
+    if [[ -e "$merge_head" ]]; then
+        git -C "$worktree" merge --abort || return 1
+    fi
+}
+
+restore_after_failure() {
+    local status=$?
+
+    trap - EXIT HUP INT TERM
+    if (( status != 0 )); then
+        if [[ -n "$reviewer_pid" ]]; then
+            # wait is interruptible; stop review before discarding its candidate.
+            kill -TERM "$reviewer_pid" 2>/dev/null || true
+            wait "$reviewer_pid" || true
+        fi
+        if abort_merge_if_needed "$merge_worktree"; then
+            # A signal or cleanup failure after the commit must not undo success.
+            if [[ "$merge_worktree" == "$repository_root" ]] \
+                && [[ "$(git -C "$merge_worktree" rev-parse HEAD)" == "$primary_oid" ]]; then
+                git -C "$repository_root" switch "$task_branch" || {
+                    printf 'git-flow-merge: task branch retained; could not switch to %s\n' \
+                        "$task_branch" >&2
+                }
+            fi
+        fi
+    fi
+    exit "$status"
+}
+
+repository_root=${1:?repository root is required}
+strategy=${2:?merge strategy is required}
+review_command=${3-}
+shift 3
+[[ "$strategy" == direct || "$strategy" == candidate ]] || fail 'invalid merge strategy'
+
+mode='finish'
+if [[ $# -gt 1 ]]; then
+    usage
+    fail 'too many arguments'
+fi
+if [[ $# -eq 1 ]]; then
+    [[ "$1" == '--cleanup-only' ]] || {
+        usage
+        fail "unsupported argument: $1"
+    }
+    mode='cleanup-only'
+fi
+
+cd "$repository_root"
+
+primary="$(scripts/detect-primary-branch.sh)"
+task_branch="$(git branch --show-current)"
+[[ -n "$task_branch" ]] || fail 'detached HEAD is not supported'
+[[ "$task_branch" != "$primary" ]] \
+    || fail 'run this script from the task branch'
+
+assert_clean "$repository_root"
+assert_no_operation "$repository_root"
+
+primary_ref="refs/heads/$primary"
+task_ref="refs/heads/$task_branch"
+primary_oid="$(git rev-parse --verify "$primary_ref^{commit}")" \
+    || fail "primary branch is not a commit: $primary"
+task_oid="$(git rev-parse --verify "$task_ref^{commit}")" \
+    || fail "task branch is not a commit: $task_branch"
+git merge-base "$primary_oid" "$task_oid" >/dev/null \
+    || fail "task branch and primary have no common ancestor: $primary"
+
+primary_worktree=''
+candidate_worktree=''
+candidate_branch=''
+worktree_listing="$(git worktree list --porcelain)" \
+    || fail 'could not inspect repository worktrees'
+while IFS= read -r line || [[ -n "$line" ]]; do
+    case "$line" in
+        'worktree '*)
+            candidate_worktree="${line#worktree }"
+            candidate_branch=''
+            ;;
+        'branch refs/heads/'*)
+            candidate_branch="${line#branch refs/heads/}"
+            if [[ "$candidate_branch" == "$primary" ]]; then
+                primary_worktree="$candidate_worktree"
+            fi
+            ;;
+    esac
+done <<< "$worktree_listing"
+
+if is_ancestor "$repository_root" "$task_oid" "$primary_oid"; then
+    if [[ -n "$primary_worktree" ]]; then
+        assert_clean "$primary_worktree"
+        assert_no_operation "$primary_worktree"
+        cleanup_worktree="$primary_worktree"
+    else
+        cleanup_worktree="$repository_root"
+    fi
+
+    assert_ref_equals "$repository_root" "$task_ref" "$task_oid"
+    assert_ref_equals "$repository_root" "$primary_ref" "$primary_oid"
+    is_ancestor "$repository_root" "$task_oid" "$primary_oid" \
+        || fail 'task is no longer contained in primary; branch was retained'
+
+    if [[ "$cleanup_worktree" == "$repository_root" ]]; then
+        git switch "$primary" \
+            || fail "could not switch to primary; task branch was retained: $primary"
+    else
+        cd "$cleanup_worktree"
+        git -C "$cleanup_worktree" worktree remove "$repository_root" \
+            || fail "no-op task worktree remains: $repository_root"
+    fi
+
+    assert_clean "$cleanup_worktree"
+    assert_no_operation "$cleanup_worktree"
+    assert_ref_equals "$cleanup_worktree" "$task_ref" "$task_oid"
+    assert_ref_equals "$cleanup_worktree" "$primary_ref" "$primary_oid"
+    is_ancestor "$cleanup_worktree" "$task_oid" "$primary_oid" \
+        || fail 'task is no longer contained in primary; branch was retained'
+    git -C "$cleanup_worktree" branch -d "$task_branch" \
+        || fail "no-op task branch remains: $task_branch"
+
+    printf 'Cleaned up no-op task %s already contained in %s at %s\n' \
+        "$task_branch" "$primary" "$task_oid"
+    exit 0
+fi
+
+[[ "$mode" != 'cleanup-only' ]] \
+    || fail 'task contains commits not present in primary; branch was retained'
+
+hooks_path="$(git config --local --get core.hooksPath || true)"
+[[ "$hooks_path" == '.githooks' ]] \
+    || fail 'repository hooks are not installed; run scripts/install-git-hooks.sh'
+[[ -x .githooks/pre-merge-commit ]] \
+    || fail '.githooks/pre-merge-commit is missing or not executable'
+if [[ "$strategy" == candidate ]]; then
+    [[ -x .githooks/pre-commit ]] || fail '.githooks/pre-commit is missing or not executable'
+fi
+
+if [[ -n "$primary_worktree" ]]; then
+    assert_clean "$primary_worktree"
+    assert_no_operation "$primary_worktree"
+    merge_worktree="$primary_worktree"
+else
+    merge_worktree="$repository_root"
+fi
+
+reviewer_pid=''
+trap restore_after_failure EXIT
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+if [[ -z "$primary_worktree" ]]; then
+    git switch "$primary"
+fi
+assert_ref_equals "$merge_worktree" "$primary_ref" "$primary_oid"
+assert_ref_equals "$merge_worktree" "$task_ref" "$task_oid"
+export WORKFLOW_MERGE_TASK_REF="$task_branch"
+if [[ "$strategy" == direct ]]; then
+    # Git invokes pre-merge-commit for the exact candidate in these repositories.
+    git -C "$merge_worktree" merge --no-ff --no-edit "$task_branch" \
+        || fail 'merge or merge gate failed; task branch was retained'
+else
+    # These repositories' pre-commit hooks delegate pending merges to their gate.
+    git -C "$merge_worktree" merge --no-ff --no-commit "$task_branch" \
+        || fail 'merge failed; task branch was retained'
+    if [[ -n "$review_command" ]]; then
+        (cd "$merge_worktree" && exec bash "$review_command") &
+        reviewer_pid=$!
+        if ! wait "$reviewer_pid"; then
+            reviewer_pid=''
+            fail 'code review failed; task branch was retained'
+        fi
+        reviewer_pid=''
+    fi
+    git -C "$merge_worktree" commit --no-edit \
+        || fail 'merge commit or release gate failed; task branch was retained'
+fi
+
+cd "$merge_worktree"
+if [[ "$repository_root" != "$merge_worktree" ]]; then
+    assert_clean "$repository_root"
+    git -C "$merge_worktree" worktree remove "$repository_root" \
+        || fail "merge succeeded, but task worktree remains: $repository_root"
+fi
+
+git -C "$merge_worktree" branch -d "$task_branch" \
+    || fail "merge succeeded, but task branch remains: $task_branch"
+
+merge_commit="$(git -C "$merge_worktree" rev-parse HEAD)"
+printf 'Merged %s into %s at %s\n' \
+    "$task_branch" "$primary" "$merge_commit"

h2h_dev_tools/install-git-hooks.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root=${1:?repository root is required}
+resource_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$repo_root"
+
+existing_hooks_path="$(git config --get core.hooksPath || true)"
+if [[ -n "$existing_hooks_path" && "$existing_hooks_path" != ".githooks" ]]; then
+    echo "Refusing to replace existing core.hooksPath: $existing_hooks_path" >&2
+    exit 1
+fi
+
+if [[ -z "$existing_hooks_path" ]]; then
+    default_hooks_directory="$(git rev-parse --git-path hooks)"
+    shopt -s nullglob
+    for existing_hook in "$default_hooks_directory"/*; do
+        if [[ -f "$existing_hook" \
+            && -x "$existing_hook" \
+            && "$existing_hook" != *.sample ]]; then
+            echo "Refusing to disable existing Git hook: $existing_hook" >&2
+            exit 1
+        fi
+    done
+fi
+
+git config --local core.hooksPath .githooks
+primary="$(bash "$resource_dir/primary-branch.sh" "$repo_root")"
+git config --local "branch.$primary.mergeOptions" --no-ff
+git config --local "branch.$primary.rebase" false
+git config --local pull.rebase false
+git config --local pull.ff only
+
+printf 'Installed repository Git hooks; primary branch: %s\n' "$primary"

h2h_dev_tools/migrate_v1.py

@@ -0,0 +1,61 @@
+"""One-time conversion of verified toolkit 0.1 source bundles to components.
+
+Normal verification and synchronization accept only the current schema. This
+explicit converter verifies all legacy hashes before replacing generated files;
+it never executes the old payload or adopts local edits.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .bundle import replace_bundle
+from .bundle_verify import (
+    MANIFEST_NAME,
+    BundleError,
+    BundleManifest,
+    _reject_duplicate_keys,
+    bundle_directory,
+    regular_bytes,
+    validate_manifest,
+    verify_payload,
+)
+
+
+def _legacy_manifest(repository: Path) -> BundleManifest:
+    try:
+        document = json.loads(
+            regular_bytes(bundle_directory(repository) / MANIFEST_NAME),
+            object_pairs_hook=_reject_duplicate_keys,
+        )
+    except (UnicodeError, json.JSONDecodeError) as error:
+        raise BundleError(f"Invalid legacy manifest: {error}") from error
+    if (
+        not isinstance(document, dict)
+        or set(document)
+        != {
+            "schema_version",
+            "toolkit_name",
+            "toolkit_version",
+            "payload_sha256",
+            "files",
+        }
+        or type(document["schema_version"]) is not int
+        or document["schema_version"] != 1
+    ):
+        raise BundleError("migrate-v1 requires an unmodified schema-1 bundle")
+    document["schema_version"] = 2
+    document["components"] = [
+        "change-scope",
+        "dependencies",
+        "documentation",
+        "publish-version",
+    ]
+    return verify_payload(repository, validate_manifest(document))
+
+
+def migrate_v1(repository: Path) -> bool:
+    """Convert once using explicit current pyproject component configuration."""
+    _legacy_manifest(repository)
+    return replace_bundle(repository, lambda: _legacy_manifest(repository))