backstitch 0.1.0__tar.gz

backstitch-0.1.0/.github/scripts/require_green_workflows.py

@@ -0,0 +1,336 @@
+#!/usr/bin/env python3
+"""Require workflow runs for the current SHA to be green before release."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass
+
+SUCCESS_CONCLUSION = "success"
+
+
+@dataclass(frozen=True)
+class WorkflowRun:
+    """The workflow-run fields the release gate cares about."""
+
+    id: int
+    name: str
+    status: str
+    conclusion: str | None
+    url: str
+    created_at: str
+    run_attempt: int
+
+    @classmethod
+    def from_api(cls, raw: Mapping[str, object]) -> WorkflowRun:
+        return cls(
+            id=_int_value(raw.get("id")),
+            name=str(raw.get("name") or ""),
+            status=str(raw.get("status") or ""),
+            conclusion=_optional_str(raw.get("conclusion")),
+            url=str(raw.get("html_url") or ""),
+            created_at=str(raw.get("created_at") or ""),
+            run_attempt=_int_value(raw.get("run_attempt"), default=1),
+        )
+
+
+@dataclass(frozen=True)
+class GateCheck:
+    """Result of evaluating the required workflow runs for one poll."""
+
+    passed: tuple[WorkflowRun, ...]
+    missing: tuple[str, ...]
+    pending: tuple[WorkflowRun, ...]
+    failed: tuple[WorkflowRun, ...]
+
+    @property
+    def ready(self) -> bool:
+        return not self.missing and not self.pending and not self.failed
+
+
+def _optional_str(value: object) -> str | None:
+    return None if value is None else str(value)
+
+
+def _int_value(value: object, *, default: int = 0) -> int:
+    try:
+        return int(value)  # type: ignore[arg-type]
+    except TypeError, ValueError:
+        return default
+
+
+def latest_runs_by_name(
+    runs: Iterable[WorkflowRun],
+    *,
+    exclude_run_id: int | str | None = None,
+) -> dict[str, WorkflowRun]:
+    """Return the latest observed run for each workflow name."""
+
+    excluded = str(exclude_run_id) if exclude_run_id is not None else None
+    latest: dict[str, WorkflowRun] = {}
+    latest_keys: dict[str, tuple[str, int, int]] = {}
+
+    for run in runs:
+        if excluded is not None and str(run.id) == excluded:
+            continue
+        if not run.name:
+            continue
+
+        sort_key = (run.created_at, run.run_attempt, run.id)
+        if sort_key >= latest_keys.get(run.name, ("", 0, 0)):
+            latest[run.name] = run
+            latest_keys[run.name] = sort_key
+
+    return latest
+
+
+def evaluate_required_workflows(
+    runs: Iterable[WorkflowRun],
+    required_workflows: Sequence[str],
+    *,
+    exclude_run_id: int | str | None = None,
+) -> GateCheck:
+    """Check whether all required workflow runs completed successfully."""
+
+    latest = latest_runs_by_name(runs, exclude_run_id=exclude_run_id)
+    passed: list[WorkflowRun] = []
+    missing: list[str] = []
+    pending: list[WorkflowRun] = []
+    failed: list[WorkflowRun] = []
+
+    for name in required_workflows:
+        run = latest.get(name)
+        if run is None:
+            missing.append(name)
+            continue
+        if run.status != "completed":
+            pending.append(run)
+            continue
+        if run.conclusion != SUCCESS_CONCLUSION:
+            failed.append(run)
+            continue
+        passed.append(run)
+
+    return GateCheck(
+        passed=tuple(passed),
+        missing=tuple(missing),
+        pending=tuple(pending),
+        failed=tuple(failed),
+    )
+
+
+def describe_gate_check(check: GateCheck) -> str:
+    """Return a concise status line for logs."""
+
+    parts: list[str] = []
+    if check.passed:
+        parts.append(
+            "green: " + ", ".join(f"{run.name} ({run.url})" for run in check.passed)
+        )
+    if check.pending:
+        parts.append(
+            "pending: "
+            + ", ".join(f"{run.name} [{run.status}]" for run in check.pending)
+        )
+    if check.missing:
+        parts.append("missing: " + ", ".join(check.missing))
+    if check.failed:
+        parts.append(
+            "failed: "
+            + ", ".join(
+                f"{run.name} [{run.conclusion or run.status}] {run.url}"
+                for run in check.failed
+            )
+        )
+    return "; ".join(parts) if parts else "no required workflow runs found"
+
+
+def fetch_workflow_runs(
+    *,
+    repo: str,
+    sha: str,
+    token: str,
+    api_url: str,
+) -> tuple[WorkflowRun, ...]:
+    """Fetch all GitHub Actions workflow runs for a commit SHA."""
+
+    runs: list[WorkflowRun] = []
+    page = 1
+    repo_path = urllib.parse.quote(repo, safe="/")
+
+    while True:
+        query = urllib.parse.urlencode(
+            {
+                "head_sha": sha,
+                "per_page": "100",
+                "page": str(page),
+            }
+        )
+        url = f"{api_url.rstrip('/')}/repos/{repo_path}/actions/runs?{query}"
+        payload = github_api_get(url, token=token)
+        raw_runs = payload.get("workflow_runs", [])
+        if not isinstance(raw_runs, list):
+            raise RuntimeError("GitHub API response did not include workflow_runs")
+
+        runs.extend(
+            WorkflowRun.from_api(run) for run in raw_runs if isinstance(run, Mapping)
+        )
+
+        if len(raw_runs) < 100:
+            return tuple(runs)
+        page += 1
+
+
+def github_api_get(url: str, *, token: str) -> dict[str, object]:
+    """Return a JSON object from the GitHub API."""
+
+    request = urllib.request.Request(
+        url,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "Authorization": f"Bearer {token}",
+            "User-Agent": "backstitch-release-gate",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            payload = json.load(response)
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"GitHub API request failed: {exc.code} {detail}") from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"GitHub API request failed: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise RuntimeError("GitHub API response was not a JSON object")
+    return payload
+
+
+def wait_for_required_workflows(
+    *,
+    fetch_runs: Callable[[], tuple[WorkflowRun, ...]],
+    required_workflows: Sequence[str],
+    exclude_run_id: int | str | None,
+    timeout_seconds: int,
+    missing_timeout_seconds: int,
+    poll_interval_seconds: int,
+) -> GateCheck:
+    """Poll until required workflow runs are green or a failure is known."""
+
+    start = time.monotonic()
+    missing_since: float | None = None
+    last_check: GateCheck | None = None
+
+    while True:
+        check = evaluate_required_workflows(
+            fetch_runs(),
+            required_workflows,
+            exclude_run_id=exclude_run_id,
+        )
+        last_check = check
+        print(describe_gate_check(check), flush=True)
+
+        if check.ready:
+            return check
+
+        if check.failed:
+            raise RuntimeError(
+                "required workflow run failed; refusing to publish release"
+            )
+
+        now = time.monotonic()
+        if check.missing:
+            if missing_since is None:
+                missing_since = now
+            if now - missing_since >= missing_timeout_seconds:
+                raise RuntimeError(
+                    "required workflow run was not found before the missing-run "
+                    f"timeout: {', '.join(check.missing)}"
+                )
+        else:
+            missing_since = None
+
+        if last_check is not None and now - start >= timeout_seconds:
+            detail = describe_gate_check(last_check)
+            raise RuntimeError(
+                f"timed out waiting for required workflow runs to be green: {detail}"
+            )
+
+        time.sleep(poll_interval_seconds)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Wait until required GitHub Actions workflow runs for a commit SHA "
+            "have completed successfully."
+        )
+    )
+    parser.add_argument(
+        "--workflow",
+        action="append",
+        dest="required_workflows",
+        required=True,
+        help="Workflow name that must complete with conclusion=success.",
+    )
+    parser.add_argument("--repo", default=os.environ.get("GITHUB_REPOSITORY"))
+    parser.add_argument("--sha", default=os.environ.get("GITHUB_SHA"))
+    parser.add_argument(
+        "--exclude-run-id",
+        default=os.environ.get("GITHUB_RUN_ID"),
+        help="Workflow run id to ignore, usually the release workflow itself.",
+    )
+    parser.add_argument(
+        "--api-url",
+        default=os.environ.get("GITHUB_API_URL", "https://api.github.com"),
+    )
+    parser.add_argument("--timeout-seconds", type=int, default=7200)
+    parser.add_argument("--missing-timeout-seconds", type=int, default=300)
+    parser.add_argument("--poll-interval-seconds", type=int, default=30)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    token = os.environ.get("GITHUB_TOKEN")
+    if not token:
+        parser.error("GITHUB_TOKEN is required")
+    if not args.repo:
+        parser.error("--repo or GITHUB_REPOSITORY is required")
+    if not args.sha:
+        parser.error("--sha or GITHUB_SHA is required")
+
+    try:
+        wait_for_required_workflows(
+            fetch_runs=lambda: fetch_workflow_runs(
+                repo=args.repo,
+                sha=args.sha,
+                token=token,
+                api_url=args.api_url,
+            ),
+            required_workflows=tuple(args.required_workflows),
+            exclude_run_id=args.exclude_run_id,
+            timeout_seconds=args.timeout_seconds,
+            missing_timeout_seconds=args.missing_timeout_seconds,
+            poll_interval_seconds=args.poll_interval_seconds,
+        )
+    except RuntimeError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

backstitch-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,86 @@
+name: CI
+
+# Hermetic CI runs on every push and PR with no secrets. The paid, flake-prone
+# live-LLM job is a post-merge canary (push to main) plus an on-demand manual
+# run (workflow_dispatch); it never runs on pull_request, so forked PRs -- which
+# do not receive repository secrets -- cannot reach it.
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: hermetic
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Pin reviewed at implementation time; re-check the action's latest major
+      # when touching this workflow.
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Hermetic tests (live LLM deselected)
+        run: uv run pytest tests -q -m "not live_llm"
+      - name: Prove live tests skip without opt-in
+        # No BACKSTITCH_LIVE_LLM here: the module must skip, not call a provider.
+        # Expect exactly one skipped test; provider activity here is a failure.
+        run: uv run pytest tests/live/test_live_llm.py -q
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format
+        run: >
+          uv run ruff format --check
+          backstitch
+          bin
+          .github/scripts
+          tests/test_release_script.py
+          tests/test_release_workflow.py
+          tests/test_release_workflow_gate.py
+      - name: Types
+        run: uv run mypy backstitch bin/release.py --config-file pyproject.toml
+      - name: Self-corpus gate
+        run: uv run backstitch check --repo-root .
+
+  live-llm:
+    name: live LLM
+    needs: test
+    # Event-based gate only. `secrets.*` is NOT available in job-level `if`
+    # (GitHub context table), so secret presence is checked inside the step.
+    if: ${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main') }}
+    runs-on: ubuntu-latest
+    env:
+      BACKSTITCH_LIVE_LLM: "1"
+      # MUST stay byte-identical to DEFAULT_BACKSTITCH_LIVE_LLM_MODEL in
+      # tests/live/test_live_llm.py -- one canonical value in two places. Update
+      # both together after re-checking `uv run llm models list` and OpenAI's
+      # model docs; availability changes faster than this repo.
+      DEFAULT_BACKSTITCH_LIVE_LLM_MODEL: "gpt-5.4-mini"
+      # Optional per-environment override; empty when the repo variable is unset.
+      BACKSTITCH_LIVE_LLM_MODEL: ${{ vars.BACKSTITCH_LIVE_LLM_MODEL }}
+      # Injected as env, never as a command-line argument. Empty string when the
+      # secret is not configured.
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Run live LLM tests
+        run: |
+          if [ -z "${OPENAI_API_KEY}" ]; then
+            echo "::notice::OPENAI_API_KEY not set; skipping live LLM tests without failure"
+            exit 0
+          fi
+          LLM_MODEL="${BACKSTITCH_LIVE_LLM_MODEL:-$DEFAULT_BACKSTITCH_LIVE_LLM_MODEL}"
+          export LLM_MODEL
+          echo "::notice::running live LLM tests with model ${LLM_MODEL}"
+          # Fail fast (no network) if the model id is not registered in llm.
+          uv run python -c 'import llm, os; llm.get_model(os.environ["LLM_MODEL"])'
+          uv run pytest tests/live/test_live_llm.py -q

backstitch-0.1.0/.github/workflows/release-gate.yml

@@ -0,0 +1,178 @@
+name: Release Gate (backstitch)
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  actions: read
+  contents: read
+
+concurrency:
+  group: release-gate-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  UV_VERSION: "0.11.11"
+  PACKAGE_NAME: backstitch
+  PACKAGE_DIR: .
+
+jobs:
+  require-ci:
+    runs-on: ubuntu-latest
+    timeout-minutes: 130
+    permissions:
+      actions: read
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Require CI workflow to be green
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          python .github/scripts/require_green_workflows.py \
+            --workflow "CI"
+
+  verify-tag-current:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    needs:
+      - require-ci
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify tag still points at tested commit
+        env:
+          EXPECTED_SHA: ${{ github.sha }}
+          TAG_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          remote_sha="$(git ls-remote --tags origin "refs/tags/${TAG_NAME}" "refs/tags/${TAG_NAME}^{}" | awk 'NR==1 { sha=$1 } END { print $1 ? $1 : sha }')"
+          if [ -z "${remote_sha}" ]; then
+            echo "Tag ${TAG_NAME} no longer exists on origin"
+            exit 1
+          fi
+          if [ "${remote_sha}" != "${EXPECTED_SHA}" ]; then
+            echo "Tag ${TAG_NAME} moved while the release gate was running"
+            echo "expected: ${EXPECTED_SHA}"
+            echo "actual:   ${remote_sha}"
+            exit 1
+          fi
+
+  build:
+    needs:
+      - require-ci
+      - verify-tag-current
+    runs-on: ubuntu-latest
+    timeout-minutes: 50
+    permissions:
+      attestations: write
+      artifact-metadata: write
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.sha }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Verify checked out commit matches tested release commit
+        run: |
+          test "$(git rev-parse HEAD)" = "${{ github.sha }}"
+
+      - name: Build package
+        working-directory: ${{ env.PACKAGE_DIR }}
+        run: |
+          uv build
+
+      - name: Generate artifact attestation
+        id: attest
+        uses: actions/attest@a1948c3f048ba23858d222213b7c278aabede763 # v4.1.1
+        with:
+          subject-path: ${{ env.PACKAGE_DIR }}/dist/*
+
+      - name: Stage attestation bundle
+        env:
+          BUNDLE_PATH: ${{ steps.attest.outputs.bundle-path }}
+          PACKAGE_NAME: ${{ env.PACKAGE_NAME }}
+          TAG_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          mkdir -p attestations
+          safe_tag="$(printf '%s' "${TAG_NAME}" | tr '/:' '--')"
+          cp "${BUNDLE_PATH}" "attestations/${PACKAGE_NAME}-${safe_tag}.sigstore.json"
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: ${{ env.PACKAGE_NAME }}-python-package-distributions
+          path: ${{ env.PACKAGE_DIR }}/dist/
+
+      - name: Store the attestation bundle
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: ${{ env.PACKAGE_NAME }}-attestations
+          path: attestations/*.sigstore.json
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    timeout-minutes: 50
+    environment:
+      name: pypi
+      url: https://pypi.org/p/backstitch
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: ${{ env.PACKAGE_NAME }}-python-package-distributions
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+
+  github-release:
+    name: Upload to GitHub Release
+    needs:
+      - publish-to-pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 50
+    permissions:
+      actions: read
+      contents: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: ${{ env.PACKAGE_NAME }}-python-package-distributions
+          path: dist/
+
+      - name: Download attestation bundle
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: ${{ env.PACKAGE_NAME }}-attestations
+          path: attestations/
+
+      - name: Create GitHub Release and upload artifacts
+        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
+        with:
+          generate_release_notes: true
+          tag_name: ${{ github.ref_name }}
+          files: |
+            dist/*.tar.gz
+            dist/*.whl
+            attestations/*.sigstore.json