feat: set up Copilot agent environment with uv, pre-commit, and GitHub Actions workflow

.github/copilot-instructions.md

@@ -13,7 +13,9 @@ Always reference these instructions first and fallback to search or bash command
   ```bash
   uv venv .venv
   source .venv/bin/activate
-  uv pip install .[test] coverage ruff pre-commit
+  uv pip install .[test] coverage
+  uv tool install pre-commit
+  uv tool install pyright
   ```
 
 - **Run the test suite:**
@@ -29,11 +31,11 @@ Always reference these instructions first and fallback to search or bash command
 - **Run linting and formatting:**
 
   ```bash
-  ruff check .
-  ruff format --check .
+  pre-commit run --all-files
   ```
 
-  - **TIMING: Linting takes <1 second.**
+  - **TIMING: Linting takes <5 seconds.**
+  - **Fallback:** If pre-commit fails with network issues, use `ruff check . && ruff format --check .`
 
 - **Run type checking:**
 
@@ -53,6 +55,24 @@ Always reference these instructions first and fallback to search or bash command
 
   - **TIMING: Documentation build takes ~14 seconds.**
 
+### Copilot Agent Environment Setup
+
+Following GitHub's Copilot agent environment guidelines, this project uses:
+
+- **`uv`** for Python environment and dependency management
+- **`uv tool install`** for development tools (`pre-commit`, `pyright`)
+- **`pre-commit`** for automated code quality checks (preferred over direct tool usage)
+
+```bash
+# Initial setup
+uv venv .venv
+source .venv/bin/activate
+uv pip install .[test] coverage
+uv tool install pre-commit
+uv tool install pyright
+pre-commit install --install-hooks
+```
+
 ### CLI Usage
 
 - **Test basic CLI functionality:**
@@ -70,7 +90,7 @@ Always reference these instructions first and fallback to search or bash command
 ## Validation
 
 - **ALWAYS run the test suite after making code changes.** Tests execute quickly (~25 seconds) and should never be cancelled.
-- **ALWAYS run linting before committing:** `ruff check . && ruff format --check .`
+- **ALWAYS run linting before committing:** `pre-commit run --all-files`
 - **ALWAYS run type checking:** `pyright` to catch type-related issues.
 - **Test CLI functionality:** Run `dpdisp --help` and test with example scripts to ensure the CLI works correctly.
 - **Build documentation:** Run `make html` in the `doc/` directory to verify documentation builds without errors.
@@ -81,7 +101,7 @@ Always reference these instructions first and fallback to search or bash command
 - **Build system:** Uses `setuptools` with `pyproject.toml` configuration.
 - **Python versions:** Supports Python 3.7+ (check `pyproject.toml` for current support matrix).
 - **Testing:** Uses `unittest` framework with coverage reporting.
-- **Linting:** Uses `ruff` for both linting and formatting.
+- **Linting:** Uses `pre-commit` with `ruff` for linting and formatting, plus other quality checks.
 - **Type checking:** Uses `pyright` for static type analysis (configured in `pyproject.toml`).
 - **Documentation:** Uses Sphinx with MyST parser for markdown support.
 
@@ -161,13 +181,14 @@ dpdisp run examples/dpdisp_run.py
 - **Always add type hints** - Include proper type annotations in all Python code for better maintainability
 - **Always use conventional commit format** - All commit messages and PR titles must follow the conventional commit specification (e.g., `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`)
 - **Test artifacts are gitignored** - Job execution creates temporary files that are automatically excluded
-- **Pre-commit hooks available** - Use `pre-commit install` to enable automated code quality checks
+- **Pre-commit hooks available** - Use `pre-commit install --install-hooks` to enable automated code quality checks
 - **Multiple execution contexts** - Code supports local execution, SSH remote execution, and various HPC schedulers
 - **Extensive examples** - Use `examples/` directory as reference for proper configuration formats
 
 ## Troubleshooting
 
 - **Virtual environment issues:** Always use `uv venv .venv` and `source .venv/bin/activate`
+- **Tool installation:** Use `uv tool install pre-commit` and `uv tool install pyright` for dev tools
 - **Test failures:** Most tests run locally; some require specific HPC environments and will be skipped
 - **Documentation build warnings:** Some warnings about external inventory URLs are expected in sandboxed environments
 - **Pre-commit network issues:** If pre-commit fails with network timeouts, run `ruff check` and `ruff format` directly

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,65 @@
+name: "Copilot Setup Steps"
+
+# Automatically run the setup steps when they are changed to allow for easy validation, and
+# allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    # Set the permissions to the lowest permissions possible needed for your steps.
+    # Copilot will be given its own token for its operations.
+    permissions:
+      # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
+      contents: read
+
+    # You can define any steps you want, and they will run before the agent starts.
+    # If you do not check out your code, Copilot will do this for you.
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        run: |
+          # Install uv using pip to avoid network restrictions
+          python -m pip install --upgrade pip
+          python -m pip install uv
+
+      - name: Create virtual environment and install dependencies
+        run: |
+          uv venv .venv
+          source .venv/bin/activate
+          uv pip install .[test] coverage
+
+      - name: Install development tools
+        run: |
+          uv tool install pre-commit
+          uv tool install pyright
+
+      - name: Set up pre-commit hooks
+        run: |
+          source .venv/bin/activate
+          pre-commit install --install-hooks
+
+      - name: Verify installation
+        run: |
+          source .venv/bin/activate
+          python --version
+          uv --version
+          pre-commit --version
+          pyright --version
+          python -c "import dpdispatcher; print('DPDispatcher installed successfully')"

pyproject.toml

@@ -82,7 +82,7 @@ exclude = [
 [tool.isort]
 profile = "black"
 
-[tool.ruff]
+[tool.ruff.lint]
 select = [
     "E", # errors
     "F", # pyflakes
@@ -110,7 +110,6 @@ ignore = [
     "D401", # TODO: first line should be in imperative mood
     "D404", # TODO: first word of the docstring should not be This
 ]
-ignore-init-module-imports = true
 
-[tool.ruff.pydocstyle]
+[tool.ruff.lint.pydocstyle]
 convention = "numpy"