diff --git a/.Rbuildignore b/.Rbuildignore index eaddfcf5..aa8dcd8b 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -28,4 +28,6 @@ ^_quarto\.yml$ ^\.quarto$ +^\.vscode$ ^\.devcontainer$ +^DEVELOPMENT\.md$ diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index e331176c..ff414f19 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,39 +1,55 @@ { - "name": "serodynamics R Development", - "build": { - "dockerfile": "Dockerfile" - }, + "name": "serodynamics R Package Development", + "image": "rocker/tidyverse:latest", - // Features to add to the dev container "features": { - "ghcr.io/devcontainers/features/git:1": {} + "ghcr.io/devcontainers/features/git:1": {}, + "ghcr.io/devcontainers/features/github-cli:1": {}, + "ghcr.io/devcontainers/features/node:1": { + "version": "lts" + } }, - - // Configure tool-specific properties + "customizations": { "vscode": { - "extensions": [ - "REditorSupport.r", - "GitHub.copilot" - ], "settings": { "r.rterm.linux": "/usr/local/bin/R", - "r.rpath.linux": "/usr/local/bin/R" - } + "r.rpath.linux": "/usr/local/bin/R", + "terminal.integrated.defaultProfile.linux": "bash" + }, + "extensions": [ + "rdebugger.r-debugger", + "reditorsupport.r", + "github.copilot", + "github.copilot-chat", + "quarto.quarto", + "redhat.vscode-yaml", + "yzhang.markdown-all-in-one", + "streetsidesoftware.code-spell-checker", + "eamodio.gitlens" + ] } }, - - // Use 'postCreateCommand' to run commands after the container is created + "postCreateCommand": "bash .devcontainer/setup.sh", - - // Set the default shell + "remoteUser": "rstudio", - // Forward ports for RStudio Server (optional) "forwardPorts": [8787], - // Persist command history across container rebuilds + "portsAttributes": { + "8787": { + "label": "RStudio Server", + "onAutoForward": "notify" + } + }, + "mounts": [ - "source=serodynamics-bashhistory,target=/commandhistory,type=volume" - ] + "source=${localWorkspaceFolder}/.Rprofile,target=/home/rstudio/.Rprofile,type=bind,consistency=cached" + ], + + "containerEnv": { + "GITHUB_TOKEN": "${localEnv:GITHUB_TOKEN}", + "TZ": "UTC" + } } diff --git a/.devcontainer/setup.sh b/.devcontainer/setup.sh index 65dfe1a8..fa7081be 100755 --- a/.devcontainer/setup.sh +++ b/.devcontainer/setup.sh @@ -1,21 +1,63 @@ #!/bin/bash -# Post-creation setup script for the serodynamics dev container - -set -e # Exit on error +set -e echo "Setting up serodynamics development environment..." -# Set up persistent bash history -echo "Configuring bash history persistence..." -mkdir -p /commandhistory -touch /commandhistory/.bash_history -ln -sf /commandhistory/.bash_history /home/rstudio/.bash_history +# Update package list +echo "Updating package list..." +apt-get update + +# Install JAGS (required for serodynamics) +echo "Installing JAGS..." +apt-get install -y jags + +# Install system dependencies for R packages +echo "Installing system dependencies..." +apt-get install -y \ + libcurl4-openssl-dev \ + libssl-dev \ + libxml2-dev \ + libfontconfig1-dev \ + libharfbuzz-dev \ + libfribidi-dev \ + libfreetype6-dev \ + libpng-dev \ + libtiff5-dev \ + libjpeg-dev \ + libgit2-dev + +# Install Quarto +echo "Installing Quarto..." +QUARTO_VERSION="1.6.40" # Updated to latest stable version (January 2026) +wget -q https://github.com/quarto-dev/quarto-cli/releases/download/v${QUARTO_VERSION}/quarto-${QUARTO_VERSION}-linux-amd64.deb +dpkg -i quarto-${QUARTO_VERSION}-linux-amd64.deb +rm quarto-${QUARTO_VERSION}-linux-amd64.deb + +# Install R packages needed for development +echo "Installing R development packages..." +Rscript -e "install.packages(c('devtools', 'roxygen2', 'testthat', 'lintr', 'spelling', 'covr', 'rcmdcheck', 'pak'), repos = 'https://cloud.r-project.org')" + +# Install rjags from source (required for JAGS interface) +echo "Installing rjags..." +Rscript -e "install.packages('rjags', repos = 'https://cloud.r-project.org', type = 'source')" + +# Install package dependencies +echo "Installing package dependencies..." +Rscript -e "pak::local_install_dev_deps(dependencies = TRUE)" + +# Verify JAGS installation +echo "Verifying JAGS installation..." +Rscript -e "library(rjags); library(runjags); runjags::testjags()" -# Install project-specific R dependencies -echo "Installing R package dependencies..." -if ! Rscript -e 'devtools::install_dev_deps(dependencies = TRUE)'; then - echo "Error: Failed to install R dependencies. Please check the output above for details." - exit 1 -fi +# Clean up +echo "Cleaning up..." +apt-get clean +rm -rf /var/lib/apt/lists/* -echo "Setup complete! The environment is ready for development." +echo "Development environment setup complete!" +echo "" +echo "You can now:" +echo " - Run 'devtools::load_all()' to load the package" +echo " - Run 'devtools::test()' to run tests" +echo " - Run 'devtools::check()' to check the package" +echo " - Use VS Code tasks (Ctrl+Shift+P -> Tasks: Run Task)" diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index af3a1b11..880b6672 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -10,6 +10,53 @@ - **Key Dependencies**: runjags, rjags, JAGS 4.3.1, serocalculator, ggmcmc, dplyr, ggplot2 - **Lifecycle**: Experimental (under active development) +## Development Environment Options + +The repository provides multiple ways to set up your development environment: + +### Option 1: Dev Container (Recommended for consistency) + +Use the preconfigured development container for a fully automated setup: + +1. Install Docker Desktop and VS Code with Dev Containers extension +2. Open the repository in VS Code +3. Click "Reopen in Container" when prompted +4. All dependencies (R, JAGS, system libraries) are installed automatically + +See `.devcontainer/README.md` for details. + +### Option 2: Local Installation (Traditional) + +Install R, JAGS, and dependencies directly on your system (see Critical Setup Requirements below). + +### Option 3: GitHub Codespaces + +Use the dev container configuration in a cloud environment: +1. Go to the repository on GitHub +2. Click "Code" → "Codespaces" → "Create codespace" +3. Development environment is ready in your browser + +## Model Context Protocol (MCP) Integration + +The repository includes MCP server configurations in `.github/mcp/mcp-config.json` for enhanced AI-assisted development: + +- **Filesystem Server**: Navigate and edit repository files +- **GitHub Server**: Check CI/CD status, review PRs, manage issues +- **Git Server**: Version control operations (status, diff, commit, branch) +- **Brave Search Server**: Look up R documentation and CRAN resources + +These servers enhance GitHub Copilot and other AI assistants with context-aware capabilities. See `.github/mcp/README.md` for setup instructions. + +## VS Code Configuration + +The `.vscode/` directory contains optimized settings for R package development: + +- **settings.json**: R-specific editor settings, file associations, and Copilot configuration +- **extensions.json**: Recommended VS Code extensions for R development +- **tasks.json**: Quick tasks for common operations (document, test, check, lint) + +Use tasks via `Ctrl+Shift+P` → "Tasks: Run Task" or the Command Palette. + ## Critical Setup Requirements ### Copilot Setup Workflow (Automatic Environment Configuration) @@ -125,7 +172,7 @@ The package requires R version 4.1.0 or higher. Install R for your platform: # Add CRAN repository for latest R version sudo apt-get update sudo apt-get install -y software-properties-common dirmngr - wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/maruti.asc | sudo tee -a /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc + wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter.asc | sudo tee -a /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc sudo add-apt-repository "deb https://cloud.r-project.org/bin/linux/ubuntu $(lsb_release -cs)-cran40/" sudo apt-get update sudo apt-get install -y r-base r-base-dev @@ -408,6 +455,21 @@ Team members can trigger actions by commenting on PRs: - **pkgdown/**: pkgdown website configuration - `_pkgdown.yml`: Site structure, reference organization +- **.github/**: GitHub configuration and workflows + - `.github/workflows/`: CI/CD workflow definitions + - `.github/mcp/`: Model Context Protocol server configurations + - `.github/copilot-instructions.md`: Custom instructions for GitHub Copilot + +- **.vscode/**: VS Code workspace configuration + - `settings.json`: Editor settings for R development + - `extensions.json`: Recommended VS Code extensions + - `tasks.json`: Quick tasks for common R package operations + +- **.devcontainer/**: Development container configuration + - `devcontainer.json`: Container specification and VS Code integration + - `setup.sh`: Automated environment setup script + - `README.md`: Dev container usage documentation + ### Configuration Files - **DESCRIPTION**: Package metadata, dependencies, version (0.0.0.9044) diff --git a/.github/mcp/README.md b/.github/mcp/README.md new file mode 100644 index 00000000..bd76e141 --- /dev/null +++ b/.github/mcp/README.md @@ -0,0 +1,128 @@ +# Model Context Protocol (MCP) Configuration + +This directory contains the MCP server configuration for the serodynamics R package development environment. + +## What is MCP? + +Model Context Protocol (MCP) is an open protocol that enables seamless integration between AI assistants and development tools. It allows AI assistants to interact with your development environment through standardized servers. + +## Configured MCP Servers + +The `mcp-config.json` file configures the following MCP servers: + +### 1. Filesystem Server +- **Purpose**: Provides file system access to the repository +- **Use cases**: Reading/writing files, searching code, managing project structure +- **Scope**: `/home/runner/work/serodynamics/serodynamics` + +### 2. GitHub Server +- **Purpose**: Integrates with GitHub for repository operations +- **Use cases**: Issue tracking, pull requests, workflow management, CI/CD status +- **Authentication**: Uses `GITHUB_TOKEN` environment variable + +### 3. Git Server +- **Purpose**: Provides Git version control operations +- **Use cases**: Status checks, diff viewing, log inspection, commits, branch management +- **Scope**: Repository at `/home/runner/work/serodynamics/serodynamics` + +### 4. Brave Search Server +- **Purpose**: Enables web search capabilities +- **Use cases**: Finding R package documentation, CRAN resources, troubleshooting +- **Authentication**: Uses `BRAVE_API_KEY` environment variable (optional) + +## Setup Instructions + +### Important: Update Repository Paths + +**Before using this configuration**, you must update the hardcoded repository paths in `mcp-config.json` to match your local clone location: + +1. Open `.github/mcp/mcp-config.json` +2. Find all instances of `/home/runner/work/serodynamics/serodynamics` +3. Replace with your local repository path, for example: + - macOS/Linux: `/Users/yourname/projects/serodynamics` or `/home/yourname/serodynamics` + - Windows: `C:\\Users\\yourname\\projects\\serodynamics` + +The default paths are specific to GitHub Actions CI environment and will not work for local development. + +### Prerequisites + +1. **Node.js**: Required to run the MCP servers via `npx` + ```bash + # Check if Node.js is installed + node --version + npm --version + ``` + +2. **Environment Variables**: + - `GITHUB_TOKEN`: GitHub Personal Access Token (required for GitHub server) + - `BRAVE_API_KEY`: Brave Search API key (optional, for web search) + +### Using with GitHub Copilot + +1. **In VS Code**: + - Install the latest GitHub Copilot extension + - The MCP configuration will be automatically detected from `.github/mcp/mcp-config.json` + - Copilot will use these servers to enhance code suggestions and operations + +2. **In JetBrains IDEs**: + - Install GitHub Copilot plugin + - Configure MCP servers through the Copilot settings + - Point to this `mcp-config.json` file + +### Using with Claude Desktop + +If you want to use these MCP servers with Claude Desktop: + +1. Copy the `mcpServers` section from `mcp-config.json` +2. **Update the repository paths** (`/home/runner/work/serodynamics/serodynamics`) to your local clone path +3. Add the modified configuration to your Claude Desktop configuration file: + - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` + - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + - **Linux**: `~/.config/Claude/claude_desktop_config.json` + +## Development Workflow Integration + +The MCP servers are particularly useful for: + +1. **Code Navigation**: Quickly finding and reading R source files +2. **Testing**: Checking test results and coverage +3. **CI/CD**: Monitoring workflow status and debugging failures +4. **Documentation**: Finding R package documentation and CRAN resources +5. **Version Control**: Managing commits, branches, and reviewing changes + +## Best Practices + +1. **Always check Git status** before making commits using the Git MCP server +2. **Use the GitHub server** to monitor CI/CD workflows and PR status +3. **Leverage filesystem search** to find similar code patterns in the repository +4. **Search the web** for R package documentation when implementing new features + +## Troubleshooting + +### MCP servers not starting + +1. Ensure Node.js is installed and `npx` is available +2. Check that environment variables are set correctly +3. Verify repository paths are correct for your system + +### GitHub authentication issues + +1. Ensure `GITHUB_TOKEN` is set with appropriate scopes: + - `repo` (full control of private repositories) + - `workflow` (update GitHub Action workflows) + - `read:org` (read org and team membership) + +2. Generate a new token at: https://github.com/settings/tokens + +### Permission issues + +1. Ensure the filesystem server has read/write access to the repository +2. Check that you have the necessary GitHub repository permissions + +## References + +- [MCP Specification](https://modelcontextprotocol.io/) +- [MCP Filesystem Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) +- [MCP GitHub Server](https://github.com/modelcontextprotocol/servers/tree/main/src/github) +- [MCP Git Server](https://github.com/modelcontextprotocol/servers/tree/main/src/git) +- [GitHub Copilot Documentation](https://docs.github.com/en/copilot) diff --git a/.github/mcp/STRUCTURE.md b/.github/mcp/STRUCTURE.md new file mode 100644 index 00000000..776d2de5 --- /dev/null +++ b/.github/mcp/STRUCTURE.md @@ -0,0 +1,265 @@ +# Development Environment Structure + +This document provides a visual overview of the development environment configurations added to the repository. + +## Directory Structure + +``` +serodynamics/ +├── .github/ +│ ├── copilot-instructions.md # Enhanced with MCP and dev env sections +│ ├── mcp/ +│ │ ├── mcp-config.json # MCP server configuration +│ │ ├── README.md # MCP setup guide +│ │ ├── SUMMARY.md # Overview of additions +│ │ ├── STRUCTURE.md # This file +│ │ └── verify-mcp.sh # Configuration verification script +│ └── workflows/ # CI/CD workflows (existing) +│ +├── .vscode/ +│ ├── settings.json # R-specific VS Code settings +│ ├── extensions.json # Recommended extensions +│ └── tasks.json # Quick tasks for R package ops +│ +├── .devcontainer/ +│ ├── devcontainer.json # Container specification +│ ├── setup.sh # Automated environment setup +│ └── README.md # Dev container guide +│ +├── DEVELOPMENT.md # Comprehensive development guide +├── .Rbuildignore # Updated to exclude new configs +└── ... (other repository files) +``` + +## Configuration Flow + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Development Environment │ +└─────────────────────────────────────────────────────────────┘ + │ + ┌───────────────────┼───────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌───────────────┐ ┌──────────────┐ ┌──────────────┐ + │ MCP Servers │ │ VS Code │ │ Dev Container│ + │ (.github/mcp)│ │ (.vscode) │ │(.devcontainer)│ + └───────────────┘ └──────────────┘ └──────────────┘ + │ │ │ + │ │ │ + ▼ ▼ ▼ + ┌───────────────┐ ┌──────────────┐ ┌──────────────┐ + │ AI-Enhanced │ │ Editor │ │ Containerized│ + │ Development │ │ Optimization │ │ Environment │ + └───────────────┘ └──────────────┘ └──────────────┘ +``` + +## MCP Server Architecture + +``` +┌──────────────────────────────────────────────────────────────┐ +│ GitHub Copilot │ +└──────────────────────────────────────────────────────────────┘ + │ + │ Uses MCP Protocol + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ MCP Configuration │ +│ (.github/mcp/mcp-config.json) │ +└──────────────────────────────────────────────────────────────┘ + │ + ┌───────────────────┼───────────────────┬──────────┐ + │ │ │ │ + ▼ ▼ ▼ ▼ + ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ + │ Filesystem │ │ GitHub │ │ Git │ │ Brave Search │ + │ Server │ │ Server │ │ Server │ │ Server │ + └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ + │ │ │ │ + ▼ ▼ ▼ ▼ + ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ + │ File I/O │ │ PR/Issues │ │ Version │ │ Web Search │ + │ Code Search │ │ CI/CD Status │ │ Control │ │ CRAN Docs │ + └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ +``` + +## VS Code Integration + +``` +┌──────────────────────────────────────────────────────────────┐ +│ VS Code Editor │ +└──────────────────────────────────────────────────────────────┘ + │ + ┌───────────────────┼───────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ + │ settings │ │ extensions │ │ tasks │ + │ .json │ │ .json │ │ .json │ + └──────────────┘ └──────────────┘ └──────────────┘ + │ │ │ + ▼ ▼ ▼ + ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ + │ R Config │ │ R Extension │ │ Quick Tasks │ + │ Formatting │ │ GitHub │ │ - Document │ + │ File Assoc │ │ Copilot │ │ - Test │ + │ Copilot │ │ Quarto │ │ - Check │ + └──────────────┘ └──────────────┘ └──────────────┘ +``` + +## Dev Container Workflow + +``` +┌──────────────────────────────────────────────────────────────┐ +│ User Opens Repo in VS Code │ +└──────────────────────────────────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ VS Code Detects .devcontainer/devcontainer.json │ +└──────────────────────────────────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ Prompt: "Reopen in Container" │ +└──────────────────────────────────────────────────────────────┘ + │ + ▼ + ┌───────────────────┴───────────────────┐ + │ │ + ▼ ▼ + ┌──────────────┐ ┌──────────────┐ + │ Pull Base │ │ User Says │ + │ Image │ │ "Yes" │ + │ rocker/ │ └──────────────┘ + │ tidyverse │ │ + └──────────────┘ │ + │ │ + └───────────────────┬───────────────────┘ + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ Run .devcontainer/setup.sh │ +│ - Install JAGS │ +│ - Install system dependencies │ +│ - Install Quarto │ +│ - Install R packages │ +│ - Verify installation │ +└──────────────────────────────────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ VS Code Opens in Container Environment │ +│ - All dependencies ready │ +│ - Extensions installed │ +│ - Settings applied │ +└──────────────────────────────────────────────────────────────┘ +``` + +## Development Workflow + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Developer Starts Work │ +└─────────────────────────────────────────────────────────────┘ + │ + ┌───────────────────┼───────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ + │ Dev Container│ │ Local Setup │ │ Codespaces │ + │ (Recommended)│ │ (Traditional)│ │ (Cloud) │ + └──────────────┘ └──────────────┘ └──────────────┘ + │ │ │ + └───────────────────┼───────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Development Environment Ready │ +│ - R >= 4.1.0 installed │ +│ - JAGS 4.3.1 installed │ +│ - All dependencies available │ +│ - VS Code configured │ +│ - MCP servers available (with Copilot) │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ + ┌───────────────────┼───────────────────┬──────────┐ + │ │ │ │ + ▼ ▼ ▼ ▼ + ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ + │ Code with │ │ Use VS Code │ │ Use MCP for │ │ Run Tests │ + │ AI Assist │ │ Tasks │ │ Context │ │ via Tasks │ + └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Commit & Push (Standard Git Flow) │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Configuration Files Relationship + +``` +DEVELOPMENT.md ─────────┐ + │ +.github/ │ + copilot-instructions.md ──┐ + mcp/ │ │ + mcp-config.json ────┼───┼─── Used by GitHub Copilot + README.md ──────────┤ │ + verify-mcp.sh ──────┘ │ + │ +.vscode/ │ + settings.json ────────────┼─── Used by VS Code + extensions.json ──────────┼─── Suggests extensions + tasks.json ───────────────┼─── Quick operations + │ +.devcontainer/ │ + devcontainer.json ────────┼─── Used by VS Code + Docker + setup.sh ─────────────────┼─── Runs in container + README.md ────────────────┘ +``` + +## Key Integration Points + +1. **GitHub Copilot + MCP**: Copilot reads `.github/mcp/mcp-config.json` and uses configured servers +2. **VS Code + Dev Container**: VS Code reads `.devcontainer/devcontainer.json` and builds container +3. **VS Code + Settings**: VS Code applies `.vscode/settings.json` for R-optimized editing +4. **VS Code + Tasks**: Tasks in `.vscode/tasks.json` provide quick access to R package operations +5. **Container + Setup**: `.devcontainer/setup.sh` runs on container creation to install dependencies +6. **Documentation + Files**: All READMEs and DEVELOPMENT.md guide users to appropriate configurations + +## File Dependencies + +``` +devcontainer.json + ├── Requires: Docker, VS Code with Dev Containers extension + ├── Uses: setup.sh (postCreateCommand) + └── Installs: Extensions from extensions.json + +mcp-config.json + ├── Requires: Node.js, npx + ├── Optional: GITHUB_TOKEN, BRAVE_API_KEY + └── Used by: GitHub Copilot, Claude Desktop + +settings.json + ├── Requires: VS Code + └── Enhances: R development experience + +tasks.json + ├── Requires: VS Code, R installation + └── Provides: Quick access to devtools functions + +setup.sh + ├── Requires: apt, wget, Rscript + └── Installs: JAGS, Quarto, R packages, dependencies +``` + +## Notes + +- All JSON files are validated and properly formatted +- Shell scripts are executable and syntax-checked +- Configurations are platform-aware (Linux/macOS/Windows) +- MCP servers require Node.js but are optional +- Dev container is self-contained and reproducible +- VS Code settings work with or without container diff --git a/.github/mcp/SUMMARY.md b/.github/mcp/SUMMARY.md new file mode 100644 index 00000000..d6174485 --- /dev/null +++ b/.github/mcp/SUMMARY.md @@ -0,0 +1,137 @@ +# Summary of MCP and Development Environment Additions + +This document summarizes the Model Context Protocol (MCP) and development environment configurations added to the serodynamics repository. + +## Files Added + +### MCP Configuration (`.github/mcp/`) +- **mcp-config.json** - MCP server configuration with 4 servers: + - Filesystem server for repository access + - GitHub server for repository operations + - Git server for version control + - Brave Search server for documentation lookup +- **README.md** - Complete MCP setup and usage guide +- **verify-mcp.sh** - Verification script to test MCP setup +- **SUMMARY.md** - This file + +### VS Code Configuration (`.vscode/`) +- **settings.json** - R-specific editor settings, file associations, Copilot integration +- **extensions.json** - Recommended VS Code extensions for R development +- **tasks.json** - 9 quick tasks for common R package operations + +### Dev Container (`.devcontainer/`) +- **devcontainer.json** - Container specification based on rocker/tidyverse +- **setup.sh** - Automated setup script that installs: + - JAGS 4.3.1 + - System dependencies + - Quarto + - R development packages + - Package dependencies +- **README.md** - Dev container usage guide + +### Documentation +- **DEVELOPMENT.md** (root) - Comprehensive development guide with: + - Quick start instructions + - Environment setup guide + - MCP integration details + - Development workflow + - Testing guidelines + - Code style guide + - Contributing checklist + +### Updated Files +- **.Rbuildignore** - Excluded `.vscode`, `.devcontainer`, and `DEVELOPMENT.md` from package builds +- **.github/copilot-instructions.md** - Added sections on: + - Development environment options + - MCP integration + - VS Code configuration + - Updated repository structure + +## Features Provided + +### 1. MCP Integration +- **AI-Enhanced Development**: GitHub Copilot can access repository context, CI/CD status, and version control +- **Smart Code Suggestions**: MCP servers provide real-time repository information +- **Web Search Integration**: Look up R documentation and CRAN resources without leaving the IDE + +### 2. Dev Container +- **Instant Setup**: One-click containerized development environment +- **Consistency**: All developers work in identical environments +- **Complete**: Pre-installed with R, JAGS, all dependencies, and tools +- **Codespaces Ready**: Works with GitHub Codespaces for cloud development + +### 3. VS Code Optimizations +- **R-Optimized Settings**: Proper indentation, formatting, file associations +- **Quick Tasks**: Run common operations with keyboard shortcuts +- **Extensions**: Curated list of helpful extensions for R development +- **Copilot Integration**: Enhanced with R-specific context + +### 4. Documentation +- **DEVELOPMENT.md**: Single source of truth for development setup +- **READMEs**: Specific guides for MCP and devcontainer +- **Enhanced Copilot Instructions**: Comprehensive repository guidance + +## Usage + +### For New Contributors +1. Clone the repository +2. Choose your setup method: + - **Dev Container**: Open in VS Code → "Reopen in Container" + - **Local**: Follow DEVELOPMENT.md → "Critical Setup Requirements" + - **Codespaces**: GitHub → Code → Codespaces → Create + +### For Existing Contributors +- Review DEVELOPMENT.md for updated workflows +- Install recommended VS Code extensions +- Optionally set up MCP for enhanced AI assistance + +### For Maintainers +- Use verify-mcp.sh to validate MCP configuration +- Update mcp-config.json if adding new MCP servers +- Keep DEVELOPMENT.md synchronized with repository changes + +## Benefits + +1. **Reduced Onboarding Time**: New contributors can start in minutes instead of hours +2. **Consistency**: Everyone uses the same tools and configurations +3. **Enhanced Productivity**: Quick tasks, AI assistance, and proper tooling +4. **Better Code Quality**: Integrated linting, testing, and documentation generation +5. **Modern Workflow**: Leverages latest development tools (MCP, Copilot, containers) + +## Maintenance + +### Updating MCP Configuration +Edit `.github/mcp/mcp-config.json` to add/modify MCP servers. + +### Updating Dev Container +Edit `.devcontainer/devcontainer.json` and `.devcontainer/setup.sh` to change container configuration or dependencies. + +### Updating VS Code Settings +Edit files in `.vscode/` to change editor settings, tasks, or recommended extensions. + +### Updating Documentation +- Update `DEVELOPMENT.md` for workflow changes +- Update `.github/copilot-instructions.md` for repository-wide guidance +- Update specific READMEs for component-specific changes + +## Testing + +Run the verification script: +```bash +.github/mcp/verify-mcp.sh +``` + +This checks: +- Node.js installation +- MCP config validity +- Environment variables +- MCP server availability +- Development environment files + +## References + +- [Model Context Protocol Specification](https://modelcontextprotocol.io/) +- [Dev Containers Documentation](https://code.visualstudio.com/docs/devcontainers/containers) +- [GitHub Copilot Documentation](https://docs.github.com/en/copilot) +- [VS Code for R](https://code.visualstudio.com/docs/languages/r) +- [serodynamics Repository](https://github.com/UCD-SERG/serodynamics) diff --git a/.github/mcp/mcp-config.json b/.github/mcp/mcp-config.json new file mode 100644 index 00000000..7ea02102 --- /dev/null +++ b/.github/mcp/mcp-config.json @@ -0,0 +1,62 @@ +{ + "$schema": "https://github.com/modelcontextprotocol/specification/blob/main/schema/mcp-config-schema.json", + "$comment": "NOTE: Update the repository paths ('/home/runner/work/serodynamics/serodynamics') to match your local clone location before using this configuration. The current paths are specific to GitHub Actions CI environment.", + "mcpServers": { + "filesystem": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "/home/runner/work/serodynamics/serodynamics" + ], + "description": "Provides file system access to the serodynamics repository for reading and writing files, searching code, and managing the project structure" + }, + "github": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-github" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" + }, + "description": "Integrates with GitHub for repository operations, issue tracking, pull requests, and workflow management" + }, + "git": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-git", + "--repository", + "/home/runner/work/serodynamics/serodynamics" + ], + "description": "Provides Git version control operations including status, diff, log, commit, and branch management" + }, + "brave-search": { + "command": "npx", + "args": [ + "-y", + "@brave/brave-search-mcp-server" + ], + "env": { + "BRAVE_API_KEY": "${BRAVE_API_KEY}" + }, + "description": "Enables web search capabilities for finding R package documentation, CRAN resources, and troubleshooting information" + } + }, + "globalShortcut": "CommandOrControl+Shift+.", + "hints": { + "development": [ + "Use the filesystem server to navigate R source files in the R/ directory", + "Use the github server to check CI/CD workflow status and review pull requests", + "Use the git server to check repository status before making commits", + "Use brave-search to look up R package documentation or CRAN resources when needed" + ], + "r-package-workflow": [ + "Always run devtools::document() after modifying roxygen2 comments", + "Use devtools::test() to run tests before committing", + "Check linting with lintr::lint_package() before pushing", + "Ensure JAGS is installed before running tests or examples" + ] + } +} diff --git a/.github/mcp/verify-mcp.sh b/.github/mcp/verify-mcp.sh new file mode 100755 index 00000000..7e10accb --- /dev/null +++ b/.github/mcp/verify-mcp.sh @@ -0,0 +1,100 @@ +#!/bin/bash +# Test script to verify MCP configuration +set -e +set -u +set -o pipefail + +echo "🔍 Verifying MCP Configuration..." +echo "" + +# Check if Node.js is installed +echo "1. Checking Node.js installation..." +if command -v node &> /dev/null; then + echo " ✅ Node.js found: $(node --version)" + echo " ✅ npm found: $(npm --version)" +else + echo " ❌ Node.js not found. Please install Node.js to use MCP servers." + exit 1 +fi + +# Check if MCP config file exists +echo "" +echo "2. Checking MCP configuration file..." +if [ -f ".github/mcp/mcp-config.json" ]; then + echo " ✅ MCP config file found" + + # Validate JSON syntax + if python3 -m json.tool .github/mcp/mcp-config.json > /dev/null 2>&1; then + echo " ✅ MCP config JSON is valid" + else + echo " ❌ MCP config JSON is invalid" + exit 1 + fi +else + echo " ❌ MCP config file not found" + exit 1 +fi + +# Check environment variables +echo "" +echo "3. Checking environment variables..." +if [ -n "${GITHUB_TOKEN:-}" ]; then + echo " ✅ GITHUB_TOKEN is set" +else + echo " ⚠️ GITHUB_TOKEN is not set (optional for some MCP features)" +fi + +if [ -n "${BRAVE_API_KEY:-}" ]; then + echo " ✅ BRAVE_API_KEY is set" +else + echo " ⚠️ BRAVE_API_KEY is not set (optional for web search)" +fi + +# Test if we can install MCP servers (dry run) +echo "" +echo "4. Testing MCP server availability..." + +servers=( + "@modelcontextprotocol/server-filesystem" + "@modelcontextprotocol/server-github" + "@modelcontextprotocol/server-git" +) + +for server in "${servers[@]}"; do + echo -n " Testing $server... " + if npm view "$server" version &> /dev/null; then + echo "✅" + else + echo "❌ (not available or network issue)" + fi +done + +echo "" +echo "5. Checking development environment files..." + +files=( + ".vscode/settings.json" + ".vscode/extensions.json" + ".vscode/tasks.json" + ".devcontainer/devcontainer.json" + ".devcontainer/setup.sh" +) + +for file in "${files[@]}"; do + if [ -f "$file" ]; then + echo " ✅ $file found" + else + echo " ❌ $file not found" + fi +done + +echo "" +echo "✨ MCP configuration verification complete!" +echo "" +echo "To use MCP servers:" +echo " 1. Ensure Node.js is installed" +echo " 2. Set GITHUB_TOKEN environment variable for GitHub integration" +echo " 3. Open repository in VS Code with GitHub Copilot extension" +echo " 4. MCP servers will be automatically available to Copilot" +echo "" +echo "See .github/mcp/README.md for detailed setup instructions." diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 8eae438e..310d6689 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -6,8 +6,6 @@ # more info: https://github.com/rstudio/education-workflows/tree/main/examples#deploy-pkgdown-to-github-pages-with-pr-previews-and-tagged-versions on: pull_request: - branches: - - main types: - opened - reopened @@ -19,8 +17,8 @@ on: - 'vignettes/**' - '_quarto.yml' - '.github/workflows/pkgdown.yaml' - - 'Readme.md' - - 'Contributing.md' + - 'README.md' + - '.github/CONTRIBUTING.md' push: tags: - 'v[0-9]+.[0-9]+.[0-9]+' # build on version tags @@ -46,7 +44,7 @@ jobs: env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - name: Configure git run: | @@ -67,6 +65,11 @@ jobs: with: tinytex: true + - name: Install JAGS + run: | + sudo apt-get update + sudo apt-get install -y jags + - uses: r-lib/actions/setup-r@v2 with: use-public-rspm: true @@ -79,6 +82,19 @@ jobs: extra-packages: | local::. r-lib/pkgdown + + - name: Install rjags + run: | + install.packages("rjags", + repos = "https://cloud.r-project.org", + type = "source", + verbose = TRUE) + withr::local_options(warn = 2) + library(rjags) + library(runjags) + runjags::findJAGS() + runjags::testjags() + shell: Rscript {0} # If events is a PR, set subdir to 'preview/pr' - name: "[PR] Set documentation subdirectory" @@ -138,7 +154,7 @@ jobs: env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 with: ref: "gh-pages" diff --git a/.github/workflows/test-coverage.yaml b/.github/workflows/test-coverage.yaml index 70242556..3cc6393e 100644 --- a/.github/workflows/test-coverage.yaml +++ b/.github/workflows/test-coverage.yaml @@ -16,23 +16,7 @@ jobs: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} steps: - - name: Install JAGS (Windows) - if: runner.os == 'Windows' - run: | - curl.exe -o wjags.exe -L0 -k --url https://downloads.sourceforge.net/project/mcmc-jags/JAGS/4.x/Windows/JAGS-4.3.1.exe - wjags.exe /S - del wjags.exe - shell: cmd - - # from https://github.com/ku-awdc/runjags/issues/2: - - name: Install JAGS (macOS) - if: runner.os == 'macOS' - run: | - sudo curl --location https://sourceforge.net/projects/mcmc-jags/files/JAGS/4.x/Mac%20OS%20X/JAGS-4.3.1.pkg -o /usr/local/JAGS-4.3.1.pkg - sudo installer -pkg /usr/local/JAGS-4.3.1.pkg -target /usr/local/bin/ - - - name: Install JAGS (Ubuntu) - if: runner.os == 'Linux' + - name: Install JAGS run: | sudo apt-get update sudo apt-get install -y jags diff --git a/.gitignore b/.gitignore index e21e5425..a268c7b5 100644 --- a/.gitignore +++ b/.gitignore @@ -27,4 +27,5 @@ docs/ /.quarto/ **/*.quarto_ipynb +*.pdf README.html diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 00000000..2c01c021 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,18 @@ +{ + "recommendations": [ + "rdebugger.r-debugger", + "reditorsupport.r", + "github.copilot", + "github.copilot-chat", + "quarto.quarto", + "redhat.vscode-yaml", + "yzhang.markdown-all-in-one", + "streetsidesoftware.code-spell-checker", + "eamodio.gitlens", + "ms-vscode.live-server", + "tamasfe.even-better-toml" + ], + "unwantedRecommendations": [ + "ms-python.python" + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 00000000..15078771 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,105 @@ +{ + "r.rterm.linux": "/usr/bin/R", + "r.rterm.mac": "/usr/local/bin/R", + // Update this path to match your installed R version on Windows, e.g. R-4.4.0 + "r.rterm.windows": "C:\\Program Files\\R\\R-x.y.z\\bin\\R.exe", + "r.rpath.linux": "/usr/bin/R", + "r.rpath.mac": "/usr/local/bin/R", + // Update this path to match your installed R version on Windows, e.g. R-4.4.0 + "r.rpath.windows": "C:\\Program Files\\R\\R-x.y.z\\bin\\R.exe", + "r.alwaysUseActiveTerminal": true, + "r.bracketedPaste": true, + "r.sessionWatcher": true, + "r.rtermSendDelay": 0, + + "[r]": { + "editor.tabSize": 2, + "editor.insertSpaces": true, + "editor.formatOnSave": false, + "editor.wordWrap": "on", + "editor.rulers": [80, 100], + "files.trimTrailingWhitespace": true, + "files.insertFinalNewline": true, + "files.trimFinalNewlines": true + }, + + "[rmd]": { + "editor.tabSize": 2, + "editor.insertSpaces": true, + "editor.wordWrap": "on", + "files.trimTrailingWhitespace": true, + "files.insertFinalNewline": true + }, + + "files.associations": { + "*.Rmd": "rmd", + "*.rmd": "rmd", + "*.R": "r", + "*.r": "r", + ".Rprofile": "r", + ".Renviron": "properties" + }, + + "files.exclude": { + "**/.Rproj.user": true, + "**/.Rhistory": true, + "**/.RData": true, + "**/.Ruserdata": true, + "**/serodynamics.Rcheck": true, + "**/*.tar.gz": true, + "**/*.tgz": true + }, + + "search.exclude": { + "**/node_modules": true, + "**/.Rproj.user": true, + "**/serodynamics.Rcheck": true, + "**/docs": true, + "**/*.tar.gz": true + }, + + "editor.formatOnSave": false, + "editor.codeActionsOnSave": { + "source.fixAll": "never" + }, + + "github.copilot.enable": { + "*": true, + "r": true, + "rmd": true, + "markdown": true, + "yaml": true + }, + + "terminal.integrated.env.linux": { + "R_LIBS_USER": "${workspaceFolder}/renv/library" + }, + + "terminal.integrated.env.osx": { + "R_LIBS_USER": "${workspaceFolder}/renv/library" + }, + + "terminal.integrated.cwd": "${workspaceFolder}", + + "git.ignoreLimitWarning": true, + + "files.watcherExclude": { + "**/.Rproj.user/**": true, + "**/serodynamics.Rcheck/**": true, + "**/docs/**": true + }, + + "yaml.schemas": { + "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.{yml,yaml}" + }, + + "editor.defaultFormatter": null, + + "R.lsp.debug": false, + "r.lsp.diagnostics": true, + "r.lsp.lang": "en", + + "task.autoDetect": "off", + + "testing.automaticallyOpenPeekView": "never" +} diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 00000000..5e91b10f --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,164 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "R: Load Package", + "type": "shell", + "command": "Rscript", + "args": [ + "-e", + "devtools::load_all()" + ], + "group": "build", + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "R: Document Package", + "type": "shell", + "command": "Rscript", + "args": [ + "-e", + "devtools::document()" + ], + "group": "build", + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "R: Run Tests", + "type": "shell", + "command": "Rscript", + "args": [ + "-e", + "devtools::test()" + ], + "group": { + "kind": "test", + "isDefault": true + }, + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "R: Check Package", + "type": "shell", + "command": "Rscript", + "args": [ + "-e", + "devtools::check()" + ], + "group": "build", + "presentation": { + "echo": true, + "reveal": "always", + "focus": true, + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "R: Lint Package", + "type": "shell", + "command": "Rscript", + "args": [ + "-e", + "lintr::lint_package()" + ], + "group": "test", + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "R: Spell Check", + "type": "shell", + "command": "Rscript", + "args": [ + "-e", + "spelling::spell_check_package()" + ], + "group": "test", + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "R: Build README", + "type": "shell", + "command": "Rscript", + "args": [ + "-e", + "rmarkdown::render('README.Rmd')" + ], + "group": "build", + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "R: Install Dependencies", + "type": "shell", + "command": "Rscript", + "args": [ + "-e", + "devtools::install_dev_deps(dependencies = TRUE)" + ], + "group": "build", + "presentation": { + "echo": true, + "reveal": "always", + "focus": true, + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "R: Build Package", + "type": "shell", + "command": "Rscript", + "args": [ + "-e", + "devtools::build()" + ], + "group": { + "kind": "build", + "isDefault": true + }, + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "shared" + }, + "problemMatcher": [] + } + ] +} diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 00000000..ec770820 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,429 @@ +# Development Guide for serodynamics + +This guide provides comprehensive information on setting up your development environment and contributing to the serodynamics R package. + +## Table of Contents + +1. [Quick Start](#quick-start) +2. [Development Environment Setup](#development-environment-setup) +3. [Model Context Protocol (MCP)](#model-context-protocol-mcp) +4. [Development Workflow](#development-workflow) +5. [Testing and Quality Assurance](#testing-and-quality-assurance) +6. [Contributing](#contributing) + +## Quick Start + +### Option 1: Dev Container (Recommended) + +The fastest way to get started with a fully configured environment: + +```bash +# Prerequisites: Docker Desktop and VS Code with Dev Containers extension +# 1. Open this repository in VS Code +# 2. Click "Reopen in Container" when prompted +# 3. Wait for the container to build (~5-10 minutes first time) +# 4. Start developing! +``` + +See [.devcontainer/README.md](.devcontainer/README.md) for details. + +### Option 2: Local Setup + +If you prefer to install dependencies locally, follow the [Critical Setup Requirements](#critical-setup-requirements) section. + +## Development Environment Setup + +### Prerequisites + +- **R** (>= 4.1.0) - Statistical computing language +- **JAGS** (>= 4.3.1) - Just Another Gibbs Sampler for Bayesian MCMC +- **Git** - Version control +- **Node.js** (optional) - For MCP server support +- **RStudio** or **VS Code** - Recommended IDEs + +### Critical Setup Requirements + +#### 1. Install R + +**Ubuntu/Linux:** +```bash +sudo apt-get update +sudo apt-get install -y software-properties-common dirmngr +wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter.asc | sudo tee -a /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc +sudo add-apt-repository "deb https://cloud.r-project.org/bin/linux/ubuntu $(lsb_release -cs)-cran40/" +sudo apt-get update +sudo apt-get install -y r-base r-base-dev +``` + +**macOS:** +```bash +brew install r +``` + +**Windows:** +Download from https://cran.r-project.org/bin/windows/base/ + +#### 2. Install JAGS + +**Ubuntu/Linux:** +```bash +sudo apt-get update && sudo apt-get install -y jags +``` + +**macOS:** +Download from https://sourceforge.net/projects/mcmc-jags/files/JAGS/4.x/Mac%20OS%20X/JAGS-4.3.1.pkg + +**Windows:** +Download from https://sourceforge.net/projects/mcmc-jags/files/JAGS/4.x/Windows/JAGS-4.3.1.exe + +#### 3. Install System Dependencies (Linux/macOS) + +**Ubuntu/Linux:** +```bash +sudo apt-get install -y \ + libcurl4-openssl-dev \ + libssl-dev \ + libxml2-dev \ + libfontconfig1-dev \ + libharfbuzz-dev \ + libfribidi-dev \ + libfreetype6-dev \ + libpng-dev \ + libtiff5-dev \ + libjpeg-dev +``` + +**macOS:** +```bash +brew install pkg-config cairo +``` + +#### 4. Install R Development Packages + +```r +# Install devtools +install.packages("devtools", repos = "https://cloud.r-project.org") + +# Install all package dependencies +devtools::install_dev_deps(dependencies = TRUE) + +# Install rjags from source +install.packages("rjags", repos = "https://cloud.r-project.org", type = "source") +``` + +#### 5. Verify Installation + +```r +library(rjags) +library(runjags) +runjags::testjags() # Should show JAGS is working +``` + +### VS Code Configuration + +The repository includes pre-configured VS Code settings in `.vscode/`: + +- **settings.json** - R-specific editor settings, file associations +- **extensions.json** - Recommended extensions for R development +- **tasks.json** - Quick tasks for common operations + +#### Recommended Extensions + +Open VS Code and install the recommended extensions: +- R Debugger (`rdebugger.r-debugger`) +- R Language Support (`reditorsupport.r`) +- GitHub Copilot (`github.copilot`) +- GitHub Copilot Chat (`github.copilot-chat`) +- Quarto (`quarto.quarto`) +- YAML (`redhat.vscode-yaml`) +- Markdown All in One (`yzhang.markdown-all-in-one`) +- Code Spell Checker (`streetsidesoftware.code-spell-checker`) +- GitLens (`eamodio.gitlens`) + +#### Using VS Code Tasks + +Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS) and select "Tasks: Run Task": + +- **R: Load Package** - Load package in development mode +- **R: Document Package** - Generate documentation from roxygen2 comments +- **R: Run Tests** - Execute all tests +- **R: Check Package** - Run R CMD check +- **R: Lint Package** - Check code style +- **R: Spell Check** - Check spelling +- **R: Build README** - Render README.Rmd +- **R: Install Dependencies** - Install all package dependencies + +## Model Context Protocol (MCP) + +The repository includes MCP server configurations in `.github/mcp/mcp-config.json` that enhance AI-assisted development. + +### Configured MCP Servers + +1. **Filesystem Server** - Read/write repository files, search code +2. **GitHub Server** - Check CI/CD status, manage PRs and issues +3. **Git Server** - Version control operations (status, diff, commit) +4. **Brave Search Server** - Look up R documentation and CRAN resources + +### Setup MCP + +#### Prerequisites +```bash +# Ensure Node.js is installed +node --version # Should be >= 18.x +npm --version +``` + +#### Environment Variables + +Set these environment variables for MCP servers: + +```bash +# GitHub token (required for GitHub MCP server) +export GITHUB_TOKEN="your_github_personal_access_token" + +# Brave API key (optional, for web search) +export BRAVE_API_KEY="your_brave_api_key" +``` + +#### Using MCP with GitHub Copilot + +MCP is automatically detected by GitHub Copilot in VS Code when the configuration file is present in `.github/mcp/mcp-config.json`. + +See [.github/mcp/README.md](.github/mcp/README.md) for detailed setup instructions. + +## Development Workflow + +### 1. Load the Package + +```r +devtools::load_all() +``` + +This loads the package in development mode, making all functions available for testing. + +### 2. Make Code Changes + +Edit R source files in the `R/` directory. Follow the [code style guidelines](#code-style-guidelines). + +### 3. Document Your Changes + +After modifying roxygen2 comments: + +```r +devtools::document() +``` + +**Important:** Never edit files in `man/` or `NAMESPACE` directly. They are auto-generated. + +### 4. Test Your Changes + +```r +# Run all tests +devtools::test() + +# Run specific test file +testthat::test_file("tests/testthat/test-your-feature.R") +``` + +### 5. Check Code Quality + +```r +# Lint your code +lintr::lint_package() + +# Spell check +spelling::spell_check_package() +``` + +### 6. Run R CMD Check + +Before committing: + +```r +devtools::check() +``` + +This runs the full package validation suite (takes 5-10 minutes). + +### 7. Update Documentation + +If you edited `README.Rmd`: + +```r +rmarkdown::render("README.Rmd") +``` + +### 8. Commit Your Changes + +```bash +git add . +git commit -m "Your descriptive commit message" +git push +``` + +## Testing and Quality Assurance + +### Test Structure + +Tests are in `tests/testthat/` and use testthat 3.0+ with snapshot testing. + +### Writing Tests + +```r +test_that("your feature works correctly", { + # Use seed for reproducible tests + withr::local_seed(123) + + # Your test code + result <- your_function(input) + + # Assertions + expect_equal(result, expected_value) +}) +``` + +### Snapshot Testing + +For MCMC output validation: + +```r +test_that("JAGS output is consistent", { + withr::local_seed(123) + + output <- run_jags_model(...) + + # Create snapshot + expect_snapshot_value(output, style = "json2") +}) +``` + +### Platform-Specific Tests + +Use `variant` for platform-specific snapshots: + +```r +expect_snapshot_value( + platform_dependent_output, + variant = Sys.info()[["sysname"]] +) +``` + +### Continuous Integration + +All PRs must pass these checks: + +- ✅ R CMD check (Ubuntu, macOS, Windows) +- ✅ Linting (changed files only) +- ✅ Test coverage +- ✅ Spelling +- ✅ Documentation sync +- ✅ NEWS.md updated +- ✅ Version incremented + +## Code Style Guidelines + +### General Principles + +- Follow the [tidyverse style guide](https://style.tidyverse.org) +- Use native pipe `|>` (not `%>%`) +- Use snake_case for naming (acronyms may be uppercase, e.g., `prep_IDs`) +- Two spaces for indentation (no tabs) +- Maximum line length: 80 characters (soft), 100 characters (hard) + +### Function Documentation + +Use roxygen2 for all exported functions: + +```r +#' Brief function description +#' +#' Detailed description of what the function does. +#' +#' @param x Description of parameter x +#' @param y Description of parameter y +#' +#' @returns Description of return value +#' +#' @examples +#' your_function(1, 2) +#' +#' @export +your_function <- function(x, y) { + # Function body +} +``` + +### User-Facing Messages + +Use `cli` package functions: + +```r +# Information +cli::cli_inform("Operation completed") + +# Warning +cli::cli_warn("Potential issue detected") + +# Error +cli::cli_abort("Operation failed") +``` + +**Never use** `message()`, `warning()`, or `stop()` in package code. + +### Dependencies + +- Use `::` to call functions from other packages +- Don't use `library()` or `require()` in package code +- Add dependencies to DESCRIPTION (Imports or Suggests) + +### Avoid Code Duplication + +Don't copy-paste code. Instead, create helper functions: + +```r +# Bad - duplicated code +result1 <- transform_data(data1, param = "A") +result2 <- transform_data(data2, param = "A") + +# Good - extract common pattern +process_with_param_a <- function(data) { + transform_data(data, param = "A") +} +result1 <- process_with_param_a(data1) +result2 <- process_with_param_a(data2) +``` + +## Contributing + +### Pull Request Checklist + +Before submitting a PR, ensure: + +- [ ] Tests pass locally (`devtools::test()`) +- [ ] R CMD check passes (`devtools::check()`) +- [ ] Code is linted (`lintr::lint_package()`) +- [ ] Spelling is correct (`spelling::spell_check_package()`) +- [ ] Documentation is up to date (`devtools::document()`) +- [ ] README.md is updated (if you edited README.Rmd) +- [ ] NEWS.md has an entry for your changes +- [ ] DESCRIPTION version is incremented (`usethis::use_version()`) + +### Getting Help + +- 📖 See `.github/copilot-instructions.md` for comprehensive repository guidance +- 🐛 Report bugs via GitHub Issues +- 💬 Ask questions in GitHub Discussions +- 📧 Contact maintainers (see DESCRIPTION file) + +## Resources + +- [R Packages Book](https://r-pkgs.org/) - Comprehensive guide to R package development +- [tidyverse Style Guide](https://style.tidyverse.org) - R code style conventions +- [testthat Documentation](https://testthat.r-lib.org/) - Testing framework +- [roxygen2 Documentation](https://roxygen2.r-lib.org/) - Documentation generation +- [devtools Documentation](https://devtools.r-lib.org/) - Package development tools +- [JAGS Documentation](https://mcmc-jags.sourceforge.io/) - Bayesian MCMC with JAGS + +## License + +See [LICENSE.md](LICENSE.md) for license information.