hyperloop 0.1.0__py3-none-any.whl

hyperloop/pr.py

@@ -0,0 +1,212 @@
+"""PR manager — draft PR lifecycle: creation, labeling, gate polling, merge.
+
+Uses the `gh` CLI for all GitHub operations. The interface is matched by
+FakePRManager (tests/fakes/pr.py) for testing without a real GitHub repo.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import subprocess
+
+logger = logging.getLogger(__name__)
+
+
+class PRManager:
+    """Manages draft PR lifecycle: creation, labeling, gate polling, merge."""
+
+    def __init__(
+        self,
+        repo: str,
+        merge_strategy: str = "squash",
+        delete_branch: bool = True,
+    ) -> None:
+        self.repo = repo
+        self.merge_strategy = merge_strategy
+        self.delete_branch = delete_branch
+
+    def create_draft(self, task_id: str, branch: str, title: str, spec_ref: str) -> str:
+        """Create a draft PR. Returns PR URL. Adds spec/task labels."""
+        result = subprocess.run(
+            [
+                "gh",
+                "pr",
+                "create",
+                "--draft",
+                "--head",
+                branch,
+                "--title",
+                title,
+                "--body",
+                "",
+                "--repo",
+                self.repo,
+            ],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        pr_url = result.stdout.strip()
+
+        spec_name = _spec_name_from_ref(spec_ref)
+        subprocess.run(
+            [
+                "gh",
+                "pr",
+                "edit",
+                pr_url,
+                "--add-label",
+                f"task/{task_id}",
+                "--add-label",
+                f"spec/{spec_name}",
+                "--repo",
+                self.repo,
+            ],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        logger.info("Created draft PR %s for task %s", pr_url, task_id)
+        return pr_url
+
+    def check_gate(self, pr_url: str, gate: str) -> bool:
+        """Check if a gate signal is present. v1: checks for 'lgtm' label.
+
+        Returns True if gate is cleared. Removes the label to prevent re-triggering.
+        """
+        result = subprocess.run(
+            [
+                "gh",
+                "pr",
+                "view",
+                pr_url,
+                "--json",
+                "labels",
+                "--repo",
+                self.repo,
+            ],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        data = json.loads(result.stdout)
+        label_names = {label["name"] for label in data.get("labels", [])}
+
+        if "lgtm" in label_names:
+            subprocess.run(
+                [
+                    "gh",
+                    "pr",
+                    "edit",
+                    pr_url,
+                    "--remove-label",
+                    "lgtm",
+                    "--repo",
+                    self.repo,
+                ],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            logger.info("Gate '%s' cleared for PR %s (lgtm label found and removed)", gate, pr_url)
+            return True
+
+        return False
+
+    def mark_ready(self, pr_url: str) -> None:
+        """Mark a draft PR as ready for review."""
+        subprocess.run(
+            [
+                "gh",
+                "pr",
+                "ready",
+                pr_url,
+                "--repo",
+                self.repo,
+            ],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        logger.info("Marked PR %s as ready for review", pr_url)
+
+    def merge(self, pr_url: str, task_id: str, spec_ref: str) -> bool:
+        """Squash-merge a PR, preserving trailers. Returns True on success.
+
+        If merge conflict, returns False (caller handles NEEDS_REBASE).
+        """
+        delete_flag = "--delete-branch" if self.delete_branch else ""
+        body = f"Spec-Ref: {spec_ref}\nTask-Ref: {task_id}"
+
+        cmd = [
+            "gh",
+            "pr",
+            "merge",
+            pr_url,
+            f"--{self.merge_strategy}",
+            "--body",
+            body,
+            "--repo",
+            self.repo,
+        ]
+        if delete_flag:
+            cmd.append(delete_flag)
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            logger.warning("Merge failed for PR %s: %s", pr_url, result.stderr.strip())
+            return False
+
+        logger.info("Merged PR %s for task %s", pr_url, task_id)
+        return True
+
+    def rebase_branch(self, branch: str, base_branch: str) -> bool:
+        """Rebase a branch onto base. Returns True if clean, False if conflicts."""
+        # Checkout the branch
+        checkout = subprocess.run(
+            ["git", "checkout", branch],
+            capture_output=True,
+            text=True,
+        )
+        if checkout.returncode != 0:
+            logger.warning("Failed to checkout branch %s: %s", branch, checkout.stderr.strip())
+            return False
+
+        # Attempt rebase
+        rebase = subprocess.run(
+            ["git", "rebase", base_branch],
+            capture_output=True,
+            text=True,
+        )
+        if rebase.returncode != 0:
+            # Abort the rebase on conflict
+            subprocess.run(
+                ["git", "rebase", "--abort"],
+                capture_output=True,
+                text=True,
+            )
+            logger.warning("Rebase conflict on branch %s onto %s", branch, base_branch)
+            return False
+
+        logger.info("Rebased branch %s onto %s", branch, base_branch)
+        return True
+
+
+def _spec_name_from_ref(spec_ref: str) -> str:
+    """Derive a spec label name from a spec_ref path.
+
+    'specs/persistence.md' -> 'persistence'
+    'specs/sub/feature.md' -> 'sub/feature'
+    """
+    name = spec_ref
+    name = re.sub(r"^specs/", "", name)
+    name = re.sub(r"\.md$", "", name)
+    return name

hyperloop-0.1.0.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: hyperloop
+Version: 0.1.0
+Summary: Orchestrator that walks tasks through composable process pipelines using AI agents
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.24.1
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hyperloop
+
+Walks tasks through composable process pipelines using AI agents. You write specs, it creates tasks, implements them, verifies the work, and merges PRs.
+
+## Prerequisites
+
+- Python 3.12+
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` on PATH)
+- `gh` CLI (authenticated, for PR management)
+- `git`
+
+## Install
+
+From PyPI (once published):
+
+```bash
+pip install hyperloop
+```
+
+From source (for development or testing):
+
+```bash
+git clone git@github.com:jsell-rh/hyperloop.git
+cd hyperloop
+uv sync --all-extras
+```
+
+## Quickstart
+
+1. Create a repo with a spec:
+
+```bash
+mkdir -p my-project/specs
+cd my-project
+git init && git commit --allow-empty -m "init"
+```
+
+2. Write a spec. This is what you want built. Be specific about acceptance criteria:
+
+```markdown
+<!-- specs/auth.md -->
+# User Authentication
+
+Implement JWT-based authentication for the API.
+
+## Acceptance Criteria
+
+- POST /auth/login accepts email + password, returns JWT
+- POST /auth/register creates a new user account
+- GET /auth/me returns the current user (requires valid JWT)
+- Passwords are hashed with bcrypt, never stored in plaintext
+- JWTs expire after 24 hours
+```
+
+3. Run:
+
+```bash
+# From source:
+uv run hyperloop run --repo owner/repo --branch main
+
+# Or if installed:
+hyperloop run --repo owner/repo --branch main
+```
+
+4. See what it would do without executing:
+
+```bash
+hyperloop run --repo owner/repo --dry-run
+```
+
+The orchestrator reads your specs, has the PM create tasks in `specs/tasks/`, then walks each task through the default pipeline: implement, verify, merge.
+
+## Configuration
+
+Create `.hyperloop.yaml` in your repo root:
+
+```yaml
+target:
+  base_branch: main
+
+runtime:
+  max_workers: 4
+
+merge:
+  auto_merge: true
+  strategy: squash
+```
+
+Then just run from the repo directory:
+
+```bash
+hyperloop run
+```
+
+The repo is inferred from your git remote. All settings have sensible defaults.
+
+## Customizing Agent Behavior
+
+Hyperloop ships with base agent definitions (implementer, verifier, etc.) that work out of the box. To customize them for your project, overlay with patches.
+
+### In-repo overlay
+
+For single-repo projects. Agent patches live in the repo itself:
+
+```yaml
+# .hyperloop.yaml
+overlay: .hyperloop/agents/
+```
+
+```
+your-repo/
+├── .hyperloop.yaml
+├── .hyperloop/
+│   └── agents/
+│       ├── implementer-patch.yaml
+│       └── process-patch.yaml
+└── specs/
+```
+
+An implementer patch injects your project's persona:
+
+```yaml
+# .hyperloop/agents/implementer-patch.yaml
+kind: Agent
+name: implementer
+annotations:
+  ambient.io/persona: |
+    You work on a Go API service.
+    Build: make build. Test: make test. Lint: make lint.
+    Follow Clean Architecture. Use dependency injection.
+```
+
+### Shared overlay via gitops repo
+
+For teams with multiple repos sharing agent definitions. The overlay lives in a central gitops repo and references the hyperloop base as a kustomize remote resource:
+
+```yaml
+# .hyperloop.yaml
+overlay: git@github.com:your-org/agent-gitops//overlays/api
+```
+
+```yaml
+# your-org/agent-gitops/overlays/api/kustomization.yaml
+resources:
+  - github.com/org/hyperloop//base?ref=v1.0.0
+
+patches:
+  - path: implementer-patch.yaml
+    target:
+      kind: Agent
+      name: implementer
+  - path: process-patch.yaml
+    target:
+      kind: Process
+      name: default
+```
+
+This pins the base version and lets you upgrade across all repos by bumping the ref.
+
+## Custom Processes
+
+The default pipeline is: implement, verify, merge. Override it by patching the process:
+
+```yaml
+# process-patch.yaml
+kind: Process
+name: default
+
+pipeline:
+  - loop:
+      - loop:
+          - role: implementer
+          - role: verifier
+      - role: security-reviewer
+  - gate: human-pr-approval
+  - action: merge-pr
+```
+
+Four primitives:
+
+| Primitive | What it does |
+|---|---|
+| `role: X` | Spawn an agent. Fail restarts the enclosing loop. |
+| `gate: X` | Block until external signal (v1: `lgtm` label on PR). |
+| `loop` | Wrap steps. Retry from top on failure. |
+| `action: X` | Terminal operation (`merge-pr`, `mark-pr-ready`). |
+
+Loops nest. Inner loops retry independently of outer loops.
+
+## What it creates in your repo
+
+The orchestrator writes to `specs/` in your repo:
+
+```
+specs/
+├── tasks/       # task files with status, findings, spec references
+├── reviews/     # review artifacts from verifier (on branches)
+└── prompts/     # process improvements (learned over time)
+```
+
+All task state is tracked in git. Every commit includes `Spec-Ref` and `Task-Ref` trailers for traceability. PRs are created as drafts and labeled by spec and task.
+
+## Configuration Reference
+
+```yaml
+# .hyperloop.yaml
+
+overlay: .hyperloop/agents/    # local path or git URL to kustomization dir
+
+target:
+  repo: owner/repo                 # GitHub repo (default: inferred from git remote)
+  base_branch: main                # trunk branch
+  specs_dir: specs                 # where specs live
+
+runtime:
+  default: local                   # local (v1) | ambient (planned)
+  max_workers: 6                   # max parallel task workers
+
+merge:
+  auto_merge: true                 # squash-merge on review pass
+  strategy: squash                 # squash | merge
+  delete_branch: true              # delete worker branch after merge
+
+poll_interval: 30                  # seconds between orchestrator cycles
+max_rounds: 50                     # max retry rounds per task before failure
+max_rebase_attempts: 3             # max rebase retries before full loop retry
+```
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest                    # run tests (280 tests)
+uv run ruff check .              # lint
+uv run ruff format --check .     # format check
+uv run pyright                   # type check
+uv run hyperloop --help          # CLI help
+```

hyperloop-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+hyperloop/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hyperloop/__main__.py,sha256=BSNHOzDGZgtLbVpUCzfZF85qaTEnASWqVun0CejFvaA,85
+hyperloop/cli.py,sha256=GXBxZFJb8q3kkh0oR_7yCtmcrmiII0wcedwWDrCDvrs,5076
+hyperloop/compose.py,sha256=rK1uWMzLVPlOwfqmmpJsZddFeAsw6eCiqWpPZlIdg0Q,4482
+hyperloop/config.py,sha256=s9v1CbGvfby2C9Hd_rtVDYj3LfmHtfJUnFMGue0KNeE,5303
+hyperloop/loop.py,sha256=bH8J1SbVbfSDe_4RPSRmXyYcciazdB_z4G5yvMXhmZ8,19937
+hyperloop/pr.py,sha256=2Q5cnpnLLOdn41ba_zkmCuFdJEhuUABYPX6yGlWJQIM,6071
+hyperloop/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hyperloop/adapters/git_state.py,sha256=8Da6lSMLwf3qP1Rn9WakAJ-88YQc8no36aoZbrfLCpQ,9003
+hyperloop/adapters/local.py,sha256=I-YCR76pa_bY5seac-29QRJWSI5DKhL0psNgrcIQfps,9262
+hyperloop/domain/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hyperloop/domain/decide.py,sha256=c9RbT1zYw3_neeswM1-fQPvIC_mEbQ98SvlaAXekShs,3996
+hyperloop/domain/deps.py,sha256=wMgGWpxxqmGdrobtVCRf32GMTs5DBaGIY0Yzx9rz9bg,2039
+hyperloop/domain/model.py,sha256=4QBJY-U2CCIUfNoIl6zhoDQfKzZg21yyVuXyE0O4cik,4926
+hyperloop/domain/pipeline.py,sha256=sIR9_gaNf-XHoYkrJYkuTO5sZ92UMmfvTJH8CSCzq0M,10712
+hyperloop/ports/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hyperloop/ports/pr.py,sha256=giSAGDk-vl4ycMJUdewSRk2ASu80_r_t9wJFxo1gGMA,1066
+hyperloop/ports/runtime.py,sha256=KeZ4BZozRpv_5MrqEjlYd47AgEzyQ81f79GaTIEDzk0,1229
+hyperloop/ports/state.py,sha256=WT_JSaYo8t5nlgqwd64I5JB214iRm0pI25wU7jaw4OE,1814
+hyperloop-0.1.0.dist-info/METADATA,sha256=XlcOvCQZEKm_GOWw2HIX5QS0-vkbRorVxKSHFQZ10jc,6327
+hyperloop-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hyperloop-0.1.0.dist-info/entry_points.txt,sha256=bP63nmW_9q_pSa8GOaP1svkdkVfX_MWd-QuKSYsPis8,48
+hyperloop-0.1.0.dist-info/RECORD,,

hyperloop-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hyperloop-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hyperloop = hyperloop.cli:app