Developer Environment Setup

Developer Environment Setup

This guide provides step-by-step instructions to set up a complete development environment for contributing to Ash, compiling the core binaries, building native plugins (Go, Rust, TypeScript), and running the full lint, test, security, and packaging suites.

---

Required Toolchains and Dependencies

To build and test the full Ash workspace including multi-language plugins, you need:

• Go (1.23+ recommended, standard 1.27.0)
• Rust & Cargo (1.80+ / 1.98+) with clippy
• Node.js & npm (v20+ / v22+) with TypeScript (tsc)
• Python 3 (3.10+) with uv or venv
• Build Tools: make, git, curl
• Packaging Tools (optional, for release builds): rpm, ruby + fpm (Linux) or Xcode CLI tools (macOS)

---

Step-by-Step Installation by Platform

1. macOS (Homebrew)

Step 1: Install Homebrew and Core Toolchains

# Install Homebrew if not present:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Xcode Command Line Tools:
xcode-select --install

# Install Go, Rust, Node.js, Python, and uv:
brew install go rust node python3 git uv make

Step 2: Verify Toolchains

go version
rustc --version
cargo --version
node --version
npm --version
python3 --version

---

2. Linux Distributions

A. Debian / Ubuntu / Linux Mint (apt)

sudo apt-get update
sudo apt-get install -y \
  build-essential \
  curl \
  git \
  golang-go \
  rustc \
  cargo \
  nodejs \
  npm \
  python3 \
  python3-pip \
  python3-venv \
  ruby \
  ruby-dev \
  rpm

# Install uv (fast Python package installer):
curl -LsSf https://astral.sh/uv/install.sh | sh

# Optional (for building .deb and .rpm release packages):
sudo gem install --no-document fpm

B. Fedora / RHEL / CentOS Stream / Rocky Linux (dnf / yum)

sudo dnf check-update
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y \
  curl \
  git \
  golang \
  rust \
  cargo \
  nodejs \
  npm \
  python3 \
  python3-pip \
  rpm-build \
  ruby \
  ruby-devel

# Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Optional:
sudo gem install --no-document fpm

C. Arch Linux / Manjaro (pacman)

sudo pacman -Syu --needed \
  base-devel \
  curl \
  git \
  go \
  rust \
  nodejs \
  npm \
  python \
  python-pip \
  rpm-tools \
  ruby

# Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

D. openSUSE (zypper)

sudo zypper refresh
sudo zypper install -t pattern devel_basis
sudo zypper install -y \
  curl \
  git \
  go \
  rust \
  cargo \
  nodejs \
  npm \
  python3 \
  python3-pip \
  rpm-build \
  ruby \
  ruby-devel

# Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

E. Alpine Linux (apk)

sudo apk update
sudo apk add \
  build-base \
  bash \
  curl \
  git \
  go \
  rust \
  cargo \
  nodejs \
  npm \
  python3 \
  py3-pip

# Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

---

3. FreeBSD (pkg)

sudo pkg update
sudo pkg install -y \
  gmake \
  curl \
  git \
  go \
  rust \
  node \
  npm \
  python3 \
  py311-pip

# Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

---

Workspace Setup and Validation

Once the system prerequisites are installed:

1. Clone the Repository

git clone https://github.com/Jonconradt/ash.git
cd ash

2. Automated Developer Tool Installation

Run the built-in configuration target to install project linting and security tools:

make config

This fetches the pinned versions of:

• golangci-lint
• gosec
• govulncheck
• staticcheck
• yamlfmt
• ruff
• markdownlint-cli2

3. Build and Test Everything

Run the comprehensive validation suite:

# Run all linters (Go, Rust, TypeScript, Python, Markdown, YAML):
make lint

# Run all tests (unit tests, multi-language plugin tests, race detector):
make test-race

# Run security vulnerability and static analysis audits:
make security

# Compile all native plugins, ash CLI, and ash-broker:
make build

Note — quiet output and the V=1 escape hatch: the lint, test, and security targets are quiet by default. Each step prints a single ok line on success and dumps its full output only when it fails, so a green run shows a short summary instead of every passing file. To see full streaming output while debugging, prefix the target with V=1:

make V=1 lint
make V=1 test
make V=1 verify

In CI this can't be added to an already-queued run — edit the workflow's run: line (for example make V=1 lint test) and re-trigger instead. See CONTRIBUTING.md.

---

Verifying Plugins Locally

After running make build, check that the compiled plugins are placed into both bin/plugins/ and ~/.ash/plugins/:

# Go plugin
~/.ash/plugins/what_time_is_it --ai-docs
~/.ash/plugins/what_time_is_it --format json

# Rust plugin
~/.ash/plugins/flip_a_coin --ai-docs
~/.ash/plugins/flip_a_coin

# TypeScript plugin
~/.ash/plugins/calculator --ai-docs
~/.ash/plugins/calculator --expr "2 + 2 * 3"