We use a `Makefile` to orchestrate dev workflows. Install the environment and dependencies:

make install

We utilize a multi-tiered testing architecture to validate behavior safely.

Standard unit testing for core logic.

make test-unit

Tests distributed system logic (syncing, drift detection, shadow commits) locally by simulating two isolated machines interacting with a bare remote.

*Tip: Run `make test` to execute both Tier 1 and Tier 2 automatically.*

If you are modifying OS-level daemon logic, battery polling, or doing highly destructive testing, spin up a fully isolated Ubuntu VM. Requires [Multipass](https://multipass.run/).

make test-cluster

This provisions a VM, mounts your local source code as read-only, and drops you into a safe `~/playground` repository. Your local Mac repository remains 100% untouched. If you edit code on your Mac, simply run `reload-pulsar` inside the VM to instantly fetch your latest changes.

Ensure your code passes the linters and automated test tiers locally.

make lint

make test

.PHONY: help install format lint typecheck test-unit test-dist test-cluster test ci clean all

BLUE=\033[1;34m

GREEN=\033[1;32m

YELLOW=\033[1;33m

NC=\033[0m # No Color

define PRINT_STAGE

@echo "\n$(BLUE)=== $(1) ===$(NC)"

all: format lint typecheck test

help: ## Show this help menu

@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'

install: ## Install dependencies using uv

$(call PRINT_STAGE, Installing Dependencies)

uv sync --all-extras --dev

format: ## Auto-format Python code using Ruff

$(call PRINT_STAGE, Formatting Code)

uv run ruff check --fix .

uv run ruff format .

lint: ## Run linters (Ruff and Markdown)

$(call PRINT_STAGE, Running Linters)

uv run ruff check .

uv run ruff format --check .

@if command -v markdownlint >/dev/null 2>&1; then \

markdownlint "**/*.md" --ignore ".venv"; \

elif command -v npx >/dev/null 2>&1; then \

npx --yes markdownlint-cli "**/*.md" --ignore ".venv"; \

else \

echo "$(YELLOW)⚠ 'markdownlint' and 'npx' not found. Skipping markdownlint. (Requires Node.js or markdownlint-cli)$(NC)"; \

fi

typecheck: ## Run static type checking with Mypy

$(call PRINT_STAGE, Running Type Checks)

uv run mypy .

test-unit: ## Run Tier 1 unit tests

$(call PRINT_STAGE, Running Tier 1: Unit Tests)

uv run pytest

test-dist: ## Run Tier 2 distributed sandbox tests

$(call PRINT_STAGE, Running Tier 2: Distributed Sandbox)

bash scripts/test_distributed.sh

test-cluster: ## Spawn Tier 3 Multipass VM cluster for OS field testing

$(call PRINT_STAGE, Provisioning Tier 3: Field Test Cluster)

bash scripts/spawn_cluster.sh

test: test-unit test-dist ## Run all automated testing tiers (1 & 2)

@echo "\n$(GREEN)✔ All automated test tiers passed successfully.$(NC)"

ci: install lint typecheck test ## Run the exact pipeline executed by GitHub Actions

@echo "\n$(GREEN)✔ Local CI pipeline completed successfully. Clear to push!$(NC)"

clean: ## Remove cache directories and test artifacts

$(call PRINT_STAGE, Cleaning Workspace)

rm -rf .pytest_cache .mypy_cache .ruff_cache

find . -type d -name "__pycache__" -exec rm -rf {} +

@echo "$(GREEN)✔ Environment cleaned.$(NC)"

Because Git Pulsar operates asynchronously on the user's active working directory, a single race condition or unhandled edge case could corrupt a repository. Testing isn't just about coverage; it is about guaranteeing **Data Integrity** and **Zero-Interference**.

The project utilizes a strict, multi-tiered testing architecture orchestrated via CI/CD:

1. **Tier 1: Property Fuzzing & Plumbing (Unit)**

- Uses `pytest` and `Hypothesis` to fuzz critical registry paths and file manipulation logic.

- Deeply mocks the OS layer and strictly asserts that the daemon only invokes non-destructive Git plumbing commands (`write-tree`, `commit-tree`), verifying it never touches the user's porcelain state.

2. **Tier 2: Distributed Sandbox (Integration)**

- Simulates a multi-node distributed environment entirely locally.

- Exploits the `XDG_STATE_HOME` environment variable to spin up multiple isolated daemon instances that push and pull to a local bare remote, validating drift detection, session handoffs, and concurrent conflict resolution.

3. **Tier 3: Chaos Engineering (OS-Level Field Tests)**

- Fully automates the provisioning of ephemeral Ubuntu virtual machines (via Canonical's Multipass) to test OS-level integrations.

- Validates `systemd` user timers, `sysfs` battery polling limits, and allows for safe, destructive testing on a live Linux filesystem without risking the host machine's source code.

set -e

BLUE='\033[1;34m'

GREEN='\033[1;32m'

RED='\033[1;31m'

NC='\033[0m'

NODE_NAME="pulsar-field-node"

if ! command -v multipass &> /dev/null; then

echo -e "${RED}❌ Multipass is not installed.${NC}"

echo "Please install it via: brew install --cask multipass"

exit 1

echo -e "${BLUE}=== Provisioning Tier 3 Linux Field Node ===${NC}"

if multipass info "$NODE_NAME" &> /dev/null; then

echo -e "ℹ Destroying existing node '$NODE_NAME'..."

multipass delete "$NODE_NAME"

multipass purge

echo -e "ℹ Launching fresh Ubuntu instance (cached images boot in ~5s)..."

multipass launch --name "$NODE_NAME"

echo -e "ℹ Waiting for VM networking and SSHFS to stabilize..."

multipass exec "$NODE_NAME" -- bash -c "while ! id -g >/dev/null 2>&1; do sleep 1; done"

echo -e "ℹ Preparing mount point..."

multipass exec "$NODE_NAME" -- sudo mkdir -p /mnt/pulsar-source

multipass exec "$NODE_NAME" -- sudo chown ubuntu:ubuntu /mnt/pulsar-source

echo -e "ℹ Mounting git-pulsar source code (Retrying until VM is ready)..."

MAX_RETRIES=5

RETRY_COUNT=0

MOUNT_SUCCESS=false

while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do

if multipass mount "$(pwd)" "$NODE_NAME":/mnt/pulsar-source &> /dev/null; then

MOUNT_SUCCESS=true

break

fi

echo -e " [Wait] SSHFS not ready, retrying in 3s... ($((RETRY_COUNT+1))/$MAX_RETRIES)"

sleep 3

RETRY_COUNT=$((RETRY_COUNT+1))

if [ "$MOUNT_SUCCESS" = false ]; then

echo -e "${RED}❌ Fatal: Could not mount directory after $MAX_RETRIES attempts.${NC}"

exit 1

echo -e "ℹ Bootstrapping Python environment (uv)..."

multipass exec "$NODE_NAME" -- bash -c "curl -LsSf https://astral.sh/uv/install.sh | sh"

echo -e "ℹ Configuring global Git identity for shadow commits..."

multipass exec "$NODE_NAME" -- git config --global user.name "Pulsar Field Tester"

multipass exec "$NODE_NAME" -- git config --global user.email "[email protected]"

multipass exec "$NODE_NAME" -- git config --global pull.rebase false

echo -e "ℹ Creating isolated playground repository..."

multipass exec "$NODE_NAME" -- bash -c "mkdir -p ~/playground && cd ~/playground && git init && echo '# Playground' > README.md && git add README.md && git commit -m 'Initial commit' && git branch -M main"

echo -e "ℹ Installing git-pulsar into the VM..."

multipass exec "$NODE_NAME" -- bash -c "source ~/.local/bin/env && uv tool install /mnt/pulsar-source"

echo -e "ℹ Setting up auto-activation and aliases..."

multipass exec "$NODE_NAME" -- bash -c 'cat <<EOF >> ~/.bashrc

echo -e "\n${GREEN}✔ Cluster Provisioned Successfully.${NC}"

echo -e "\nTo begin field testing, run:"

echo -e " ${BLUE}multipass shell $NODE_NAME${NC}"