bb-run 1.0.0__py3-none-any.whl

bb_run-1.0.0.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: bb-run
+Version: 1.0.0
+Summary: Run Bitbucket Pipelines locally
+Author-email: Karl Hill <karlhillx@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/karlhillx/bb-run
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# bb-run
+
+[![Version](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fkarlhillx%2Fbb-run%2Fmain%2Fpyproject.toml&query=project.version&label=version)](https://github.com/karlhillx/bb-run/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://github.com/karlhillx/bb-run/blob/main/pyproject.toml)
+[![Test](https://github.com/karlhillx/bb-run/actions/workflows/test.yml/badge.svg)](https://github.com/karlhillx/bb-run/actions/workflows/test.yml)
+
+**Run Bitbucket Pipelines locally.** bb-run faithfully executes your `bitbucket-pipelines.yml` on your local machine using Docker or directly on your host.
+
+## Why bb-run?
+
+- **Test before pushing** - Catch CI failures locally before committing
+- **Fast iteration** - No waiting for Bitbucket's pipeline queue
+- **Debug easily** - Run in verbose mode, inspect outputs directly
+- **Two modes** - Docker for Bitbucket-accurate execution, Host for quick local testing
+- **No dependencies** - Works with just Python and Docker (optional)
+
+## Installation
+
+### via pip
+
+```bash
+pip install bb-run
+```
+
+### via Homebrew
+
+```bash
+brew install karlhillx/tap/bb-run
+```
+
+### from source
+
+```bash
+git clone https://github.com/karlhillx/bb-run.git
+cd bb-run
+pip install -e .
+```
+
+## Quick Start
+
+### Validate a pipeline (instant)
+
+```bash
+bb-run --validate
+```
+
+### Run the default pipeline
+
+```bash
+bb-run
+```
+
+### Run a specific branch
+
+```bash
+bb-run --target branches.main
+bb-run -t branches.main
+```
+
+### Simulate a feature branch
+
+```bash
+bb-run --branch feature/my-work
+```
+
+### Run on your host (no Docker)
+
+```bash
+bb-run --mode host
+```
+
+### Pass variables
+
+```bash
+bb-run -v ENVIRONMENT=staging -v API_KEY=secret
+```
+
+### List available targets
+
+```bash
+bb-run --list-targets
+```
+
+## Modes
+
+### Docker Mode (default)
+
+Runs steps in Docker containers matching Bitbucket's build environment.
+
+```bash
+bb-run --mode docker
+```
+
+**Pros:** Faithful reproduction of Bitbucket's environment  
+**Cons:** Requires Docker, images may take time to download
+
+### Host Mode
+
+Runs steps directly on your local machine.
+
+```bash
+bb-run --mode host
+```
+
+**Pros:** Fast, no image downloads  
+**Cons:** May differ from Bitbucket's environment (Python vs Python3, etc.)
+
+## Examples
+
+### Python project
+
+```bash
+cd my-python-project
+bb-run
+```
+
+### Node.js project
+
+```bash
+cd my-node-project
+bb-run --target branches.main
+```
+
+### Run with verbose output
+
+```bash
+bb-run --verbose
+```
+
+## Configuration
+
+bb-run automatically looks for `bitbucket-pipelines.yml` in your current directory. Use `--repo` to specify a different path:
+
+```bash
+bb-run --repo /path/to/repo
+```
+
+## Requirements
+
+- Python 3.12+
+- PyYAML
+- Docker (for Docker mode)
+
+### Local development (virtualenv)
+
+Use Python 3.12 for the project venv so `python --version` matches `requires-python` in `pyproject.toml`:
+
+```bash
+# macOS (Homebrew)
+brew install python@3.12
+"$(brew --prefix python@3.12)/bin/python3.12" -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+# or tests + coverage only: pip install -e ".[test]"
+python -m pytest
+python -m pytest --cov=bbrun --cov-report=xml tests/
+ruff check bbrun
+```
+
+## Environment Variables
+
+bb-run sets these Bitbucket-specific environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `BITBUCKET_BUILD_NUMBER` | Build number (set to "1") |
+| `BITBUCKET_CLONE_DIR` | Repository path |
+| `BITBUCKET_COMMIT` | Git commit SHA |
+| `BITBUCKET_BRANCH` | Branch name |
+| `BITBUCKET_REPO_SLUG` | Repository name |
+| `BITBUCKET_REPO_UUID` | Unique run ID |
+| `BITBUCKET_WORKSPACE` | Workspace (set to "local") |
+
+## Troubleshooting
+
+### "Docker is not available"
+
+Use `--mode host` to run on your local machine instead of in Docker:
+
+```bash
+bb-run --mode host
+```
+
+### "pip: command not found"
+
+bb-run automatically translates `pip` to `pip3` and adds `--break-system-packages` for PEP 668 environments.
+
+### `pytest: error: unrecognized arguments: --cov=...`
+
+Coverage flags come from the **pytest-cov** plugin. Install the `test` or `dev` extra, then use the same interpreter for pytest:
+
+```bash
+pip install -e ".[dev]"
+# or: pip install -e ".[test]"
+python -m pytest --cov=bbrun --cov-report=xml tests/
+```
+
+### Image pull failures
+
+Docker Hub rate limits may cause image downloads to fail. Try:
+1. Waiting and retrying later
+2. Using `--mode host` temporarily
+3. Configuring a Docker mirror
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions welcome! Please open an issue or submit a PR.
+
+## Publishing to PyPI
+
+The package name **`bb-run`** must exist on PyPI (first upload is manual or via this workflow after [trusted publishing](https://docs.pypi.org/trusted-publishers/adding-a-publisher/) is configured).
+
+1. In PyPI, add a **pending publisher** for this GitHub repo and workflow `publish.yml`, environment **`pypi`**.
+2. In GitHub → **Settings → Environments**, create environment **`pypi`** (no secrets needed for trusted publishing).
+3. Bump `version` in `pyproject.toml`, merge, then **create a GitHub Release** (or run the workflow manually after a release).
+
+Badges in this README use **GitHub** (version from `pyproject.toml` on `main`) so they stay valid before the first PyPI release. After publishing, you can add e.g. `https://img.shields.io/pypi/v/bb-run.svg`.
+
+## Links
+
+- [PyPI project](https://pypi.org/project/bb-run/) (live after first successful upload)
+- [GitHub Repository](https://github.com/karlhillx/bb-run)
+- [Issue Tracker](https://github.com/karlhillx/bb-run/issues)

bb_run-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+bb_run-1.0.0.dist-info/licenses/LICENSE,sha256=w7gLMqk8rKX33vCkMQJFyR-H8zvFG7BXDWeqjUbhNAQ,1065
+bbrun/__init__.py,sha256=o8_eaSXjj9zhhn23Ya2dTS_84tz7VsKWIFKaO0HAjGY,249
+bbrun/cli.py,sha256=lewHyEHX3b1Rxb2HhJ8i2Oq_w7jREkof8DOINhRMjJQ,4879
+bbrun/docker.py,sha256=MP7JWO7UaoHtGDwhCMt3LNC6Zd6N1uP1a6MB7dZTS7E,7111
+bbrun/host.py,sha256=Uf_UCNsSEmtPTvSHarUiguQhVAKuJzOwVVaRtdsdj2s,6048
+bbrun/validator.py,sha256=FxdOt-MwNnWtoDT0_A5qS5PUjgrFJLUkmCPIsQu_KxY,3389
+bb_run-1.0.0.dist-info/METADATA,sha256=jnxgLWOJEmpCvdGQc_yO9Ij9cvL8MyBe8vfrJR-3sug,6338
+bb_run-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+bb_run-1.0.0.dist-info/entry_points.txt,sha256=M4-RuBKtKFsdQBGHvloxQNAzSzcgEjCUefJU4eX0YfM,42
+bb_run-1.0.0.dist-info/top_level.txt,sha256=x1SUojzkaTzH4xk5aFHKUrjL3nbgJGaK3fIxv8QdSY4,6
+bb_run-1.0.0.dist-info/RECORD,,

bb_run-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bb_run-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bb-run = bbrun.cli:main

bb_run-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Karl Hill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bb_run-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bbrun

bbrun/__init__.py

@@ -0,0 +1,13 @@
+"""
+bb-run - Bitbucket Pipelines Local Runner
+
+Faithfully runs bitbucket-pipelines.yml locally using Docker or your host environment.
+"""
+
+from .cli import main
+
+__version__ = "0.1.0"
+__author__ = "Karl Hill"
+__license__ = "MIT"
+
+__all__ = ['main']

bbrun/cli.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+bb-run CLI - Bitbucket Pipelines Local Runner
+"""
+
+import sys
+import argparse
+from pathlib import Path
+
+from .validator import PipelineValidator
+from .docker import DockerRunner
+from .host import HostRunner
+
+
+def list_targets(repo_path: Path) -> int:
+    """List available pipeline targets."""
+    validator = PipelineValidator(repo_path)
+    config = validator.load()
+    
+    if not config:
+        return 1
+    
+    print("Available pipeline targets:")
+    print("\n  default")
+    
+    pipelines = config.get('pipelines', {})
+    
+    branches = pipelines.get('branches', {})
+    for branch in sorted(branches.keys()):
+        print(f"  branches.{branch}")
+    
+    tags = pipelines.get('tags', {})
+    for tag in sorted(tags.keys()):
+        print(f"  tags.{tag}")
+    
+    for name in pipelines:
+        if name not in ['default', 'branches', 'tags']:
+            print(f"  {name}")
+    
+    image = config.get('image', 'atlassian/default-image:latest')
+    print(f"\nDefault image: {image}")
+    
+    return 0
+
+
+def run_pipeline(
+    repo_path: Path,
+    target: str,
+    branch: str,
+    variables: dict,
+    mode: str,
+    verbose: bool
+) -> int:
+    """Run a pipeline in the specified mode."""
+    
+    if mode == 'docker':
+        runner = DockerRunner(repo_path)
+    else:
+        runner = HostRunner(repo_path)
+    
+    success = runner.run(
+        target=target,
+        branch=branch,
+        variables=variables,
+        verbose=verbose
+    )
+    
+    return 0 if success else 1
+
+
+def validate(repo_path: Path) -> int:
+    """Validate a pipeline YAML file."""
+    validator = PipelineValidator(repo_path)
+    
+    if validator.validate():
+        print("✅ Valid bitbucket-pipelines.yml")
+        validator.show_summary()
+        return 0
+    else:
+        print("❌ Invalid or missing bitbucket-pipelines.yml")
+        return 1
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog='bb-run',
+        description='Run Bitbucket Pipelines locally',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  bb-run                                    # Run default pipeline
+  bb-run --target master                   # Run master branch pipeline
+  bb-run --repo /path/to/repo              # Run in specific repo
+  bb-run --branch feature-x                # Simulate running on a branch
+  bb-run --mode host                       # Run on host (no Docker)
+  bb-run --mode docker                     # Run in Docker (default)
+  bb-run -v KEY=VALUE                      # Pass variables
+  bb-run --list-targets                    # List available targets
+  bb-run --validate                        # Validate YAML only
+        """
+    )
+    
+    parser.add_argument(
+        '--repo', '-r',
+        default='.',
+        help='Path to repository (default: current directory)'
+    )
+    parser.add_argument(
+        '--target', '-t',
+        default='default',
+        help='Pipeline target (default: default)'
+    )
+    parser.add_argument(
+        '--branch', '-b',
+        default='LOCAL',
+        help='Branch name to simulate (default: LOCAL)'
+    )
+    parser.add_argument(
+        '--mode', '-m',
+        choices=['docker', 'host'],
+        default='docker',
+        help='Execution mode (default: docker)'
+    )
+    parser.add_argument(
+        '--variables', '-v',
+        action='append',
+        help='Variables in KEY=VALUE format'
+    )
+    parser.add_argument(
+        '--list-targets',
+        action='store_true',
+        help='List available pipeline targets and exit'
+    )
+    parser.add_argument(
+        '--validate',
+        action='store_true',
+        help='Validate YAML only, do not run'
+    )
+    parser.add_argument(
+        '--verbose',
+        action='store_true',
+        help='Verbose output'
+    )
+    parser.add_argument(
+        '--version',
+        action='version',
+        version='%(prog)s 0.1.0'
+    )
+    
+    args = parser.parse_args()
+    
+    # Parse variables
+    variables = {}
+    if args.variables:
+        for var in args.variables:
+            if '=' in var:
+                key, value = var.split('=', 1)
+                variables[key] = value
+    
+    repo_path = Path(args.repo).resolve()
+    
+    # Validate repo has a pipeline file
+    pipeline_file = repo_path / 'bitbucket-pipelines.yml'
+    if not pipeline_file.exists() and not args.list_targets:
+        print(f"Error: bitbucket-pipelines.yml not found in {repo_path}")
+        return 1
+    
+    # Execute
+    if args.list_targets:
+        return list_targets(repo_path)
+    
+    if args.validate:
+        return validate(repo_path)
+    
+    return run_pipeline(
+        repo_path=repo_path,
+        target=args.target,
+        branch=args.branch,
+        variables=variables,
+        mode=args.mode,
+        verbose=args.verbose
+    )
+
+
+if __name__ == '__main__':
+    sys.exit(main())

bbrun/docker.py

@@ -0,0 +1,224 @@
+"""
+Docker Runner - Executes pipeline steps in Docker containers
+"""
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .validator import PipelineValidator
+
+
+class DockerRunner:
+    """Runs pipeline steps in Docker containers."""
+    
+    def __init__(self, repo_path: Path):
+        self.repo_path = Path(repo_path)
+        self.pipeline_file = self.repo_path / "bitbucket-pipelines.yml"
+        self.variables = {}
+        self.validator = PipelineValidator(repo_path)
+    
+    def _docker_available(self) -> bool:
+        """Check if Docker is available."""
+        try:
+            result = subprocess.run(
+                ['docker', 'info'],
+                capture_output=True,
+                timeout=10
+            )
+            return result.returncode == 0
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            return False
+    
+    def _image_exists(self, image: str) -> bool:
+        """Check if Docker image exists locally."""
+        result = subprocess.run(
+            ['docker', 'image', 'inspect', image],
+            capture_output=True
+        )
+        return result.returncode == 0
+    
+    def _pull_image(self, image: str) -> bool:
+        """Pull a Docker image."""
+        print(f"Pulling Docker image: {image}")
+        result = subprocess.run(
+            ['docker', 'pull', image],
+            capture_output=True,
+            text=True
+        )
+        if result.returncode != 0:
+            print(f"Warning: Could not pull {image}: {result.stderr}")
+        return result.returncode == 0
+    
+    def _build_env(self, branch: str) -> Dict[str, str]:
+        """Build environment variables for the container."""
+        env = dict(os.environ)
+        
+        # Get git commit
+        try:
+            commit = subprocess.run(
+                ['git', 'rev-parse', 'HEAD'],
+                capture_output=True,
+                text=True,
+                cwd=self.repo_path
+            ).stdout.strip()
+        except Exception:
+            commit = 'local'
+        
+        env.update({
+            'BITBUCKET_BUILD_NUMBER': '1',
+            'BITBUCKET_CLONE_DIR': '/opt/atlassian/pipelines/agent/build',
+            'BITBUCKET_COMMIT': commit,
+            'BITBUCKET_BRANCH': branch,
+            'BITBUCKET_REPO_SLUG': self.repo_path.name,
+            'BITBUCKET_REPO_UUID': f'bb-run-{os.getpid()}',
+            'BITBUCKET_WORKSPACE': 'local',
+            'HOME': '/root',
+        })
+        
+        # Add user variables
+        env.update(self.variables)
+        
+        return env
+    
+    def _run_step(self, step: Dict, step_name: str, default_image: str, env: Dict) -> bool:
+        """Execute a single pipeline step in Docker."""
+        print(f"\n{'='*60}")
+        print(f"Step: {step_name}")
+        print(f"{'='*60}")
+        
+        # Resolve image
+        image = step.get('image', default_image)
+        
+        # Check/pull image
+        if not self._image_exists(image):
+            print(f"Image not found locally: {image}")
+            if not self._pull_image(image):
+                print(f"Failed to pull image {image}")
+                return False
+        
+        # Build docker command
+        docker_cmd = [
+            'docker', 'run', '--rm',
+            '-w', '/opt/atlassian/pipelines/agent/build',
+            '-v', f'{self.repo_path}:/opt/atlassian/pipelines/agent/build:rw'
+        ]
+        
+        # Add environment variables
+        for key, value in env.items():
+            docker_cmd.extend(['-e', f'{key}={value}'])
+        
+        docker_cmd.append(image)
+        
+        # Handle script vs pipe
+        if 'script' in step:
+            script = step['script']
+            if isinstance(script, list):
+                bash_cmd = ' && '.join(script)
+            else:
+                bash_cmd = script
+            
+            docker_cmd.extend(['/bin/bash', '-c', bash_cmd])
+            print(f"Executing: {bash_cmd[:60]}...")
+        elif 'pipe' in step:
+            pipe = step['pipe']
+            print(f"Pipe: {pipe}")
+            print("Note: Pipes are not executed in Docker mode (simplified)")
+            return True
+        else:
+            print("Warning: Step has no script or pipe")
+            return True
+        
+        # Run
+        result = subprocess.run(
+            docker_cmd,
+            cwd=self.repo_path,
+            env=env
+        )
+        
+        if result.returncode != 0:
+            print(f"❌ Failed with exit code {result.returncode}")
+            return False
+        
+        return True
+    
+    def run(
+        self,
+        target: str = 'default',
+        branch: str = 'LOCAL',
+        variables: Optional[Dict] = None,
+        verbose: bool = False
+    ) -> bool:
+        """Run the pipeline for a given target."""
+        if variables:
+            self.variables.update(variables)
+        
+        # Check Docker
+        if not self._docker_available():
+            print("Error: Docker is not available")
+            print("Use --mode host to run on your host machine instead")
+            return False
+        
+        # Load pipeline
+        config = self.validator.load()
+        if not config:
+            print("Error: Could not load pipeline")
+            return False
+        
+        default_image = config.get('image', 'atlassian/default-image:latest')
+        
+        print(f"Repository: {self.repo_path}")
+        print(f"Target: {target}")
+        print(f"Branch: {branch}")
+        print("Mode: DOCKER")
+        print(f"Image: {default_image}")
+        
+        # Get steps
+        steps = self._get_steps(config, target)
+        if not steps:
+            print(f"No steps found for target: {target}")
+            return False
+        
+        # Run steps
+        env = self._build_env(branch)
+        all_passed = True
+        
+        for i, item in enumerate(steps):
+            step = item.get('step', item)
+            step_name = step.get('name', f'Step {i+1}')
+            
+            if not self._run_step(step, step_name, default_image, env):
+                all_passed = False
+                break
+        
+        if all_passed:
+            print(f"\n{'='*60}")
+            print("✅ All steps completed successfully!")
+            print(f"{'='*60}")
+        else:
+            print(f"\n{'='*60}")
+            print("❌ Pipeline failed!")
+            print(f"{'='*60}")
+        
+        return all_passed
+    
+    def _get_steps(self, config: Dict, target: str) -> List:
+        """Get steps for a given target."""
+        pipelines = config.get('pipelines', {})
+        
+        if target == 'default':
+            return pipelines.get('default', [])
+        
+        if target.startswith('branches.'):
+            branch_name = target.split('.', 1)[1]
+            return pipelines.get('branches', {}).get(branch_name, [])
+        
+        if target.startswith('tags.'):
+            tag_name = target.split('.', 1)[1]
+            return pipelines.get('tags', {}).get(tag_name, [])
+        
+        if target in pipelines:
+            return pipelines[target]
+        
+        return []

bbrun/host.py

@@ -0,0 +1,186 @@
+"""
+Host Runner - Executes pipeline steps directly on the host machine
+"""
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .validator import PipelineValidator
+
+
+class HostRunner:
+    """Runs pipeline steps directly on the host machine."""
+    
+    def __init__(self, repo_path: Path):
+        self.repo_path = Path(repo_path)
+        self.pipeline_file = self.repo_path / "bitbucket-pipelines.yml"
+        self.variables = {}
+        self.validator = PipelineValidator(repo_path)
+    
+    def _build_env(self, branch: str) -> Dict[str, str]:
+        """Build environment variables."""
+        env = dict(os.environ)
+        
+        # Get git commit
+        try:
+            commit = subprocess.run(
+                ['git', 'rev-parse', 'HEAD'],
+                capture_output=True,
+                text=True,
+                cwd=self.repo_path
+            ).stdout.strip()
+        except Exception:
+            commit = 'local'
+        
+        env.update({
+            'BITBUCKET_BUILD_NUMBER': '1',
+            'BITBUCKET_CLONE_DIR': str(self.repo_path),
+            'BITBUCKET_COMMIT': commit,
+            'BITBUCKET_BRANCH': branch,
+            'BITBUCKET_REPO_SLUG': self.repo_path.name,
+            'BITBUCKET_REPO_UUID': f'bb-run-{os.getpid()}',
+            'BITBUCKET_WORKSPACE': 'local',
+        })
+        
+        env.update(self.variables)
+        
+        return env
+    
+    def _translate_command(self, cmd: str) -> str:
+        """Translate commands for host compatibility."""
+        # Translate 'python' to 'python3' if python isn't available
+        if not shutil.which('python') and cmd.startswith('python '):
+            cmd = 'python3' + cmd[6:]
+        
+        # Translate 'pip ' to 'pip3 ' if pip isn't available
+        if not shutil.which('pip') and cmd.startswith('pip ') and not cmd.startswith('pip3 '):
+            cmd = 'pip3 ' + cmd[4:]
+        
+        # Add --break-system-packages for PEP 668
+        if 'pip3 install' in cmd and '--break-system-packages' not in cmd:
+            cmd = cmd.replace('pip3 install', 'pip3 install --break-system-packages')
+            print("  (added --break-system-packages for PEP 668)")
+        
+        return cmd
+    
+    def _run_step(self, step: Dict, step_name: str, env: Dict) -> bool:
+        """Execute a single pipeline step on the host."""
+        print(f"\n{'='*60}")
+        print(f"Step: {step_name}")
+        print(f"{'='*60}")
+        
+        if 'script' in step:
+            return self._run_script(step['script'], env)
+        elif 'pipe' in step:
+            return self._run_pipe(step)
+        else:
+            print("Warning: Step has no script or pipe")
+            return True
+    
+    def _run_script(self, script: List[str], env: Dict) -> bool:
+        """Run a script step."""
+        if isinstance(script, list):
+            commands = script
+        else:
+            commands = [script]
+        
+        for cmd in commands:
+            translated = self._translate_command(cmd)
+            print(f"$ {translated}")
+            
+            result = subprocess.run(
+                translated,
+                shell=True,
+                cwd=self.repo_path,
+                env=env
+            )
+            
+            if result.returncode != 0:
+                print(f"❌ Failed with exit code {result.returncode}")
+                return False
+        
+        return True
+    
+    def _run_pipe(self, step: Dict) -> bool:
+        """Handle a pipe step (not executed in host mode)."""
+        pipe = step.get('pipe', '')
+        print(f"⚠️  Pipe: {pipe}")
+        print("    (pipes not executed in host mode)")
+        return True
+    
+    def run(
+        self,
+        target: str = 'default',
+        branch: str = 'LOCAL',
+        variables: Optional[Dict] = None,
+        verbose: bool = False
+    ) -> bool:
+        """Run the pipeline for a given target."""
+        if variables:
+            self.variables.update(variables)
+        
+        # Load pipeline
+        config = self.validator.load()
+        if not config:
+            print("Error: Could not load pipeline")
+            return False
+        
+        image = config.get('image', 'atlassian/default-image:latest')
+        
+        print(f"Repository: {self.repo_path}")
+        print(f"Target: {target}")
+        print(f"Branch: {branch}")
+        print("Mode: HOST (runs on your machine)")
+        print(f"Note: Uses '{image}' as reference for command mapping")
+        
+        # Get steps
+        steps = self._get_steps(config, target)
+        if not steps:
+            print(f"No steps found for target: {target}")
+            return False
+        
+        # Run steps
+        env = self._build_env(branch)
+        all_passed = True
+        
+        for i, item in enumerate(steps):
+            step = item.get('step', item)
+            step_name = step.get('name', f'Step {i+1}')
+            
+            if not self._run_step(step, step_name, env):
+                all_passed = False
+                break
+        
+        if all_passed:
+            print(f"\n{'='*60}")
+            print("✅ All steps completed successfully!")
+            print(f"{'='*60}")
+        else:
+            print(f"\n{'='*60}")
+            print("❌ Pipeline failed!")
+            print(f"{'='*60}")
+        
+        return all_passed
+    
+    def _get_steps(self, config: Dict, target: str) -> List:
+        """Get steps for a given target."""
+        pipelines = config.get('pipelines', {})
+        
+        if target == 'default':
+            return pipelines.get('default', [])
+        
+        if target.startswith('branches.'):
+            branch_name = target.split('.', 1)[1]
+            return pipelines.get('branches', {}).get(branch_name, [])
+        
+        if target.startswith('tags.'):
+            tag_name = target.split('.', 1)[1]
+            return pipelines.get('tags', {}).get(tag_name, [])
+        
+        if target in pipelines:
+            return pipelines[target]
+        
+        return []

bbrun/validator.py

@@ -0,0 +1,107 @@
+"""
+Pipeline YAML Validator
+"""
+
+import yaml
+from pathlib import Path
+from typing import Dict, Optional
+
+
+class PipelineValidator:
+    """Validates and parses bitbucket-pipelines.yml"""
+    
+    def __init__(self, repo_path: Path):
+        self.repo_path = Path(repo_path)
+        self.pipeline_file = self.repo_path / "bitbucket-pipelines.yml"
+        self._config: Optional[Dict] = None
+    
+    def load(self) -> Optional[Dict]:
+        """Load and parse the pipeline YAML."""
+        if not self.pipeline_file.exists():
+            return None
+        
+        try:
+            with open(self.pipeline_file, 'r') as f:
+                self._config = yaml.safe_load(f)
+            return self._config
+        except yaml.YAMLError as e:
+            print(f"YAML parse error: {e}")
+            return None
+    
+    def validate(self) -> bool:
+        """Validate the pipeline configuration."""
+        config = self.load()
+        
+        if not config:
+            return False
+        
+        # Check for required 'pipelines' key
+        if 'pipelines' not in config:
+            print("Error: Missing 'pipelines' key")
+            return False
+        
+        return True
+    
+    def show_summary(self) -> None:
+        """Print a summary of the pipeline."""
+        if not self._config:
+            return
+        
+        image = self._config.get('image', 'atlassian/default-image:latest')
+        print(f"\nImage: {image}")
+        
+        pipelines = self._config.get('pipelines', {})
+        
+        # Default pipeline
+        if 'default' in pipelines:
+            print("\n📦 default:")
+            for item in pipelines['default']:
+                self._show_step(item)
+        
+        # Branches
+        branches = pipelines.get('branches', {})
+        if branches:
+            print("\n🌿 branches:")
+            for branch, items in branches.items():
+                print(f"   {branch}:")
+                for item in items:
+                    self._show_step(item, indent=4)
+        
+        # Tags
+        tags = pipelines.get('tags', {})
+        if tags:
+            print("\n🏷️  tags:")
+            for tag, items in tags.items():
+                print(f"   {tag}:")
+                for item in items:
+                    self._show_step(item, indent=4)
+    
+    def _show_step(self, item: Dict, indent: int = 2) -> None:
+        """Show details of a single step."""
+        step = item.get('step', item)
+        name = step.get('name', 'unnamed')
+        prefix = " " * indent
+        
+        suffix = ""
+        if step.get('deployment'):
+            suffix += f" [{step['deployment']}]"
+        if step.get('trigger'):
+            suffix += f" ({step['trigger']})"
+        
+        print(f"{prefix}• {name}{suffix}")
+        
+        for cmd in step.get('script', []):
+            if isinstance(cmd, str):
+                display = cmd[:70] + "..." if len(cmd) > 70 else cmd
+                print(f"{prefix}  → {display}")
+            elif isinstance(cmd, dict) and 'pipe' in cmd:
+                pipe_name = cmd['pipe']
+                vars_str = ""
+                if 'variables' in cmd:
+                    vars_str = f" ({cmd['variables']})"
+                print(f"{prefix}  → pipe: {pipe_name}{vars_str}")
+    
+    @property
+    def config(self) -> Optional[Dict]:
+        """Get the loaded configuration."""
+        return self._config