Contributing to Magpie

git clone https://github.com/<your-username>/magpie.git
cd magpie

export MAGPIE_REPO_DIR="$(pwd)"
export MAGPIE_BASE_BRANCH="main"
export MAGPIE_TEST_CMD="cargo test"
export MAGPIE_LINT_CMD="cargo clippy"

cargo build

cargo test

cargo fmt --check
cargo clippy -- -D warnings

crates/
  magpie-core/       # Library — agent, pipeline, blueprint engine, repo, tracing
  magpie-cli/        # Binary — CLI entry point for local usage
  magpie-discord/    # Binary — Discord bot adapter
  magpie-teams/      # Binary — Microsoft Teams webhook adapter

use anyhow::{Context, Result, bail};

// Use anyhow::Result everywhere
pub async fn do_something() -> Result<String> {
    // Add context to errors
    let data = fetch_data()
        .await
        .context("failed to fetch data")?;
    
    // Early returns with bail!
    if data.is_empty() {
        bail!("data cannot be empty");
    }
    
    Ok(data)
}

use async_trait::async_trait;
use std::sync::Arc;

#[async_trait]
trait MyTrait {
    async fn do_work(&self) -> Result<()>;
}

// Shared ownership: Arc::clone, not .clone()
let shared = Arc::new(data);
let cloned = Arc::clone(&shared); // ✓ Preferred
let cloned = shared.clone();       // ✗ Avoid

use tracing::{info, warn, error};

// Structured logging with tracing
info!(step_name = "test", "Starting test execution");
warn!(exit_code = 1, "Test failed");
error!(error = %e, "Pipeline failed");

// Never println! in library code
// println!("message"); // ✗ Don't do this

// Derive Debug, Clone on most structs
#[derive(Debug, Clone)]
pub struct Config {
    pub repo_dir: PathBuf,
    pub branch: String,
}

// Add Serialize, Deserialize for types that cross boundaries
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PipelineResult {
    pub status: PipelineStatus,
    pub pr_url: Option<String>,
}

// Builder pattern with with_* methods
impl Config {
    pub fn new() -> Self { ... }
    
    pub fn with_branch(mut self, branch: String) -> Self {
        self.branch = branch;
        self
    }
}

use anyhow::{Context, Result};
use dotenvy;

// Load .env at startup
dotenvy::dotenv().ok();

// Required env vars
let api_key = std::env::var("API_KEY")
    .context("API_KEY not set")?;

// Optional env vars
let branch = std::env::var("BRANCH")
    .unwrap_or_else(|_| "main".to_string());

let optional = std::env::var("OPTIONAL").ok();

git checkout -b your-branch-name

# Format code
cargo fmt

# Run lints
cargo clippy -- -D warnings

# Run tests
cargo test

# Test specific crate
cargo test -p magpie-core

# Run ignored tests (requires external services)
cargo test -- --ignored

git push origin your-branch-name

use crate::blueprint::step::{Step, StepKind, Condition};
use crate::blueprint::steps::ShellStep;

let step = Step {
    name: "run-tests".to_string(),
    kind: StepKind::Shell(
        ShellStep::new("cargo")
            .with_args(vec!["test".to_string()])
    ),
    condition: Condition::Always,
    continue_on_error: false,
};

# Single prompt
cargo run -p magpie-cli -- "your prompt here"

# Blueprint engine demo
cargo run -p magpie-cli -- --demo

# Full pipeline
cargo run -p magpie-cli -- --pipeline "add a health check"

# With tracing
cargo run -p magpie-cli -- --trace --pipeline "fix the bug"

DISCORD_TOKEN="your-token" cargo run -p magpie-discord

TEAMS_APP_ID="id" TEAMS_APP_SECRET="secret" cargo run -p magpie-teams