From dafa3487be3c64d9d8cee1aac0a2c4c7d8f19640 Mon Sep 17 00:00:00 2001 From: benbrastmckie Date: Mon, 8 Sep 2025 10:51:35 -0700 Subject: [PATCH] feat: add NixOS support for development environment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add NixOS-specific installation script (scripts/install-nixos.sh) - Create comprehensive NixOS development guide (NIX_GUIDE.md) - Fix pf CLI build issue by making rootCmd package-level variable - Use Python virtual environments to work around NixOS restrictions - Provide clear dependency installation instructions for NixOS users - Add colored output and detailed error messages in install script - Create activation script for convenient environment setup The NixOS installation script handles the unique requirements of NixOS: - Avoids global pip installations (uses venv instead) - Provides exact Nix package names for missing dependencies - Works with NixOS's read-only filesystem structure - Supports all installation methods (configuration.nix, nix-shell, nix-env) ๐Ÿค– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- NIX_GUIDE.md | 325 +++++++++++++++++++++++++++++++++++++++ core/cli/pf/main.go | 11 +- scripts/install-nixos.sh | 294 +++++++++++++++++++++++++++++++++++ 3 files changed, 626 insertions(+), 4 deletions(-) create mode 100644 NIX_GUIDE.md create mode 100755 scripts/install-nixos.sh diff --git a/NIX_GUIDE.md b/NIX_GUIDE.md new file mode 100644 index 00000000..457fa97c --- /dev/null +++ b/NIX_GUIDE.md @@ -0,0 +1,325 @@ +# NixOS Development Guide for Provability-Fabric + +This guide provides instructions for setting up and developing Provability-Fabric on NixOS systems. + +## Prerequisites + +### Required Packages + +Add the following to your `configuration.nix`: + +```nix +environment.systemPackages = with pkgs; [ + go + python3 + git + bash +]; +``` + +### Optional Packages + +```nix +environment.systemPackages = with pkgs; [ + nodejs # For UI components + lean4 # For formal proof verification +]; +``` + +After updating `configuration.nix`, rebuild your system: +```bash +sudo nixos-rebuild switch +``` + +### Alternative: Temporary Shell Environment + +For a temporary development environment without system changes: + +```bash +nix-shell -p go python3 git bash nodejs lean4 +``` + +## Installation + +### Quick Setup + +Run the NixOS-specific installation script: + +```bash +./scripts/install-nixos.sh +``` + +This script will: +- Check for all required dependencies +- Create a Python virtual environment (avoiding NixOS pip restrictions) +- Build the `pf` CLI tool +- Install Python dependencies in the virtual environment +- Create an activation script for future sessions + +### Manual Setup + +If you prefer manual installation: + +1. **Create Python virtual environment:** + ```bash + python3 -m venv venv + source venv/bin/activate + ``` + +2. **Build the pf CLI:** + ```bash + cd core/cli/pf + go build -o pf . + cd ../../.. + ``` + +3. **Install Python dependencies:** + ```bash + source venv/bin/activate + pip install -r tests/integration/requirements.txt + pip install -r tools/compliance/requirements.txt + pip install -r tools/proofbot/requirements.txt + ``` + +4. **Add to PATH:** + ```bash + export PATH=$PATH:$(pwd)/core/cli/pf + ``` + +## Daily Development Workflow + +### Activating the Environment + +Use the convenience script created during installation: + +```bash +source ./activate.sh +``` + +Or manually: + +```bash +source venv/bin/activate +export PATH=$PATH:$(pwd)/core/cli/pf +``` + +### Running Commands + +With the environment activated: + +```bash +# Initialize an agent +pf init my-agent + +# Run tests +python tests/trust_fire_orchestrator.py + +# Build Lean proofs (if Lean4 is installed) +cd spec-templates/v1/proofs && lake build +``` + +## Common Issues and Solutions + +### Issue: `pip install` fails globally + +**Solution:** Always use the virtual environment: +```bash +source venv/bin/activate +pip install +``` + +### Issue: `/bin/bash` not found + +**Solution:** Scripts should use `#!/usr/bin/env bash` or run with: +```bash +bash ./scripts/script-name.sh +``` + +### Issue: Node.js global packages fail + +**Solution:** Install locally with prefix: +```bash +npm install --prefix ./marketplace/ui +``` + +### Issue: Go build fails with linking errors + +**Solution:** Ensure all C dependencies are available: +```bash +nix-shell -p gcc pkg-config +``` + +### Issue: `rootCmd` undefined error in pf CLI + +**Solution:** This has been fixed in the codebase. The `rootCmd` is now properly declared as a package-level variable. + +## Development Tips + +### Using Nix Flakes (Advanced) + +Create a `flake.nix` for reproducible development: + +```nix +{ + description = "Provability-Fabric development environment"; + + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + }; + + outputs = { self, nixpkgs }: { + devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell { + buildInputs = with nixpkgs.legacyPackages.x86_64-linux; [ + go + python3 + python3Packages.pip + python3Packages.virtualenv + nodejs + lean4 + git + ]; + + shellHook = '' + echo "Provability-Fabric development environment" + if [ -f "./venv/bin/activate" ]; then + source ./venv/bin/activate + fi + export PATH=$PATH:$(pwd)/core/cli/pf + ''; + }; + }; +} +``` + +Then use: +```bash +nix develop +``` + +### Creating a Shell.nix + +For non-flake users, create `shell.nix`: + +```nix +{ pkgs ? import {} }: + +pkgs.mkShell { + buildInputs = with pkgs; [ + go + python3 + python3Packages.pip + python3Packages.virtualenv + nodejs + lean4 + git + ]; + + shellHook = '' + echo "Entering Provability-Fabric development environment" + if [ ! -d "venv" ]; then + python3 -m venv venv + fi + source venv/bin/activate + export PATH=$PATH:$(pwd)/core/cli/pf + ''; +} +``` + +Use with: +```bash +nix-shell +``` + +## Testing the Installation + +Run these commands to verify your setup: + +```bash +# Check pf CLI +./core/cli/pf/pf --help + +# Test agent initialization +./core/cli/pf/pf init test-agent +rm -rf bundles/test-agent + +# Check Python environment +source venv/bin/activate +python -c "import yaml; print('Python dependencies OK')" + +# Check Go build +cd core/cli/pf && go build -o pf . && echo "Go build OK" +``` + +## Maintaining the Environment + +### Updating Dependencies + +```bash +# Update Python packages +source venv/bin/activate +pip install --upgrade -r tests/integration/requirements.txt + +# Update Go modules +cd core/cli/pf +go get -u ./... +go mod tidy +``` + +### Cleaning Up + +```bash +# Remove virtual environment +rm -rf venv/ + +# Clean Go build cache +go clean -cache + +# Remove built binaries +rm -f core/cli/pf/pf +``` + +## NixOS-Specific Features + +The `install-nixos.sh` script includes: + +1. **Colored output** for clear status indication +2. **Dependency checking** with exact Nix package suggestions +3. **Virtual environment** for Python package isolation +4. **Local installations** for Node.js packages +5. **Activation script** for quick environment setup + +## Troubleshooting Commands + +```bash +# Check which packages are installed +nix-env -q | grep -E "go|python|node|lean" + +# Find Nix package names +nix search nixpkgs go +nix search nixpkgs python3 +nix search nixpkgs nodejs + +# Check current PATH +echo $PATH | tr ':' '\n' + +# Verify virtual environment is active +echo $VIRTUAL_ENV +``` + +## Additional Resources + +- [NixOS Python Guide](https://nixos.wiki/wiki/Python) +- [NixOS Go Guide](https://nixos.wiki/wiki/Go) +- [Nix Flakes Documentation](https://nixos.wiki/wiki/Flakes) +- [Provability-Fabric Documentation](./README.md) + +## Support + +If you encounter NixOS-specific issues: + +1. Check this guide first +2. Ensure all prerequisites are installed +3. Try the manual setup steps +4. Create an issue with NixOS-specific details + +Remember: NixOS's declarative and immutable approach requires different strategies than traditional Linux distributions, but provides better reproducibility and system stability. \ No newline at end of file diff --git a/core/cli/pf/main.go b/core/cli/pf/main.go index 1e4de407..ae3565e6 100644 --- a/core/cli/pf/main.go +++ b/core/cli/pf/main.go @@ -38,12 +38,13 @@ import ( var ( dryRun bool + rootCmd *cobra.Command ) -func main() { - var rootCmd = &cobra.Command{ - Use: "so", - Aliases: []string{"pf"}, +func init() { + rootCmd = &cobra.Command{ + Use: "pf", + Aliases: []string{"so"}, Short: "Provability-Fabric CLI tool", Long: `Provability-Fabric (pf) is a command-line tool for managing AI agent specifications with provable behavioral guarantees through formal verification.`, @@ -74,7 +75,9 @@ with provable behavioral guarantees through formal verification.`, rootCmd.AddCommand(epochCmd()) rootCmd.AddCommand(perfCmd()) rootCmd.AddCommand(traceCmd()) +} +func main() { if err := rootCmd.Execute(); err != nil { fmt.Fprintf(os.Stderr, "Error: %v\n", err) os.Exit(1) diff --git a/scripts/install-nixos.sh b/scripts/install-nixos.sh new file mode 100755 index 00000000..a7e9592c --- /dev/null +++ b/scripts/install-nixos.sh @@ -0,0 +1,294 @@ +#!/usr/bin/env bash + +# Provability-Fabric Installation Script for NixOS +# This script sets up the development environment for NixOS users +# It checks for required packages and suggests nix-env or configuration.nix additions + +set -e # Exit on any error + +echo "๐Ÿš€ Setting up Provability-Fabric development environment on NixOS..." +echo "" + +# Color codes for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +# Track missing packages for final report +MISSING_PACKAGES=() +NIX_PACKAGES_NEEDED=() + +# Function to check if a command exists +check_command() { + local cmd=$1 + local nix_pkg=$2 + local description=$3 + + if ! command -v "$cmd" &> /dev/null; then + echo -e "${RED}โŒ $description is not installed${NC}" + MISSING_PACKAGES+=("$cmd") + NIX_PACKAGES_NEEDED+=("$nix_pkg") + return 1 + else + echo -e "${GREEN}โœ… $description found: $(command -v $cmd)${NC}" + return 0 + fi +} + +# Check prerequisites +echo "๐Ÿ“‹ Checking prerequisites..." +echo "" + +# Essential tools +check_command "go" "go" "Go (1.21+)" +GO_AVAILABLE=$? + +check_command "python3" "python3" "Python 3" +PYTHON_AVAILABLE=$? + +check_command "bash" "bash" "Bash" +check_command "git" "git" "Git" + +# Optional tools +echo "" +echo "๐Ÿ“‹ Checking optional tools..." +check_command "node" "nodejs" "Node.js (for UI components)" || NODE_AVAILABLE=false +check_command "lake" "lean4" "Lean 4 (for formal proofs)" || LEAN_AVAILABLE=false + +# If we're missing essential packages, provide NixOS installation instructions +if [ ${#MISSING_PACKAGES[@]} -gt 0 ]; then + echo "" + echo -e "${YELLOW}โš ๏ธ Missing packages detected!${NC}" + echo "" + echo "You have several options to install the missing packages:" + echo "" + echo "Option 1: Add to your configuration.nix:" + echo "----------------------------------------" + echo "environment.systemPackages = with pkgs; [" + for pkg in "${NIX_PACKAGES_NEEDED[@]}"; do + echo " $pkg" + done + echo "];" + echo "" + echo "Then run: sudo nixos-rebuild switch" + echo "" + echo "Option 2: Use nix-shell (temporary):" + echo "------------------------------------" + echo -n "nix-shell -p" + for pkg in "${NIX_PACKAGES_NEEDED[@]}"; do + echo -n " $pkg" + done + echo "" + echo "" + echo "Option 3: Install with nix-env (user profile):" + echo "----------------------------------------------" + for pkg in "${NIX_PACKAGES_NEEDED[@]}"; do + echo "nix-env -iA nixos.$pkg" + done + echo "" + + # Exit if essential packages are missing + if [ $GO_AVAILABLE -ne 0 ] || [ $PYTHON_AVAILABLE -ne 0 ]; then + echo -e "${RED}Cannot continue without Go and Python. Please install them first.${NC}" + exit 1 + fi +fi + +echo "" +echo "โœ… Prerequisites check completed" +echo "" + +# Create Python virtual environment for isolated package management +echo "๐Ÿ Setting up Python virtual environment..." + +VENV_PATH="./venv" +if [ ! -d "$VENV_PATH" ]; then + python3 -m venv "$VENV_PATH" + echo "โœ… Created Python virtual environment at $VENV_PATH" +else + echo "โœ… Python virtual environment already exists at $VENV_PATH" +fi + +# Activate virtual environment +source "$VENV_PATH/bin/activate" +echo "โœ… Activated Python virtual environment" + +# Upgrade pip in virtual environment +pip install --upgrade pip > /dev/null 2>&1 +echo "โœ… Updated pip to latest version" + +# Build CLI tools +echo "" +echo "๐Ÿ”จ Building CLI tools..." + +# Build pf CLI +if [ -d "core/cli/pf" ]; then + cd core/cli/pf + go build -o pf . + if [ $? -eq 0 ]; then + echo "โœ… Built pf CLI tool" + else + echo -e "${YELLOW}โš ๏ธ Failed to build pf CLI - you may need additional Go dependencies${NC}" + fi + cd ../../.. +else + echo -e "${YELLOW}โš ๏ธ core/cli/pf directory not found${NC}" +fi + +# Build specdoc CLI (optional) +if [ -f "cmd/specdoc/main.go" ]; then + cd cmd/specdoc + go build -o specdoc . + if [ $? -eq 0 ]; then + echo "โœ… Built specdoc CLI tool" + else + echo -e "${YELLOW}โš ๏ธ Failed to build specdoc CLI${NC}" + fi + cd ../.. +else + echo "โš ๏ธ specdoc CLI not found, skipping" +fi + +# Install Python dependencies in virtual environment +echo "" +echo "๐Ÿ Installing Python dependencies in virtual environment..." + +install_python_deps() { + local req_file=$1 + local component=$2 + + if [ -f "$req_file" ]; then + echo "Installing $component dependencies..." + pip install -r "$req_file" > /dev/null 2>&1 + if [ $? -eq 0 ]; then + echo "โœ… Installed $component dependencies" + else + echo -e "${YELLOW}โš ๏ธ Some $component dependencies may have failed to install${NC}" + fi + fi +} + +install_python_deps "tests/integration/requirements.txt" "integration test" +install_python_deps "tests/proof-fuzz/requirements.txt" "proof-fuzz" +install_python_deps "tools/compliance/requirements.txt" "compliance tool" +install_python_deps "tools/insure/requirements.txt" "insurance tool" +install_python_deps "tools/proofbot/requirements.txt" "proofbot" + +# Handle Node.js dependencies +if [ "$NODE_AVAILABLE" != false ] && [ -f "marketplace/ui/package.json" ]; then + echo "" + echo "๐Ÿ“ฆ Installing Node.js dependencies..." + cd marketplace/ui + + # Use npm with local prefix to avoid global installation issues + npm install --prefix . > /dev/null 2>&1 + if [ $? -eq 0 ]; then + echo "โœ… Installed UI dependencies locally" + else + echo -e "${YELLOW}โš ๏ธ Some Node dependencies may have failed - this is common on NixOS${NC}" + echo " You may need to use node2nix or a proper Node development shell" + fi + cd ../.. +fi + +# Test basic functionality +echo "" +echo "๐Ÿงช Testing basic functionality..." + +# Test pf CLI +if [ -f "core/cli/pf/pf" ]; then + ./core/cli/pf/pf --help > /dev/null 2>&1 + if [ $? -eq 0 ]; then + echo "โœ… pf CLI is working" + else + echo -e "${YELLOW}โš ๏ธ pf CLI built but not functioning properly${NC}" + fi +else + echo "โŒ pf CLI not found" +fi + +# Test agent initialization +if [ -f "core/cli/pf/pf" ]; then + ./core/cli/pf/pf init test-agent 2>/dev/null + if [ $? -eq 0 ]; then + echo "โœ… Agent initialization works" + # Clean up test agent + rm -rf "bundles/test-agent" 2>/dev/null || true + else + echo -e "${YELLOW}โš ๏ธ Agent initialization test failed${NC}" + fi +fi + +# Test Lean build (if Lean is available) +if [ "$LEAN_AVAILABLE" != false ]; then + echo "๐Ÿ” Testing Lean build..." + if [ -d "spec-templates/v1/proofs" ]; then + cd spec-templates/v1/proofs + lake build > /dev/null 2>&1 + if [ $? -eq 0 ]; then + echo "โœ… Lean build works" + else + echo -e "${YELLOW}โš ๏ธ Lean build failed - you may need additional Lean packages${NC}" + fi + cd ../../.. + fi +fi + +echo "" +echo "=========================================" +echo "" + +if [ ${#MISSING_PACKAGES[@]} -eq 0 ]; then + echo -e "${GREEN}๐ŸŽ‰ Installation completed successfully!${NC}" +else + echo -e "${YELLOW}๐ŸŽ‰ Installation completed with warnings${NC}" + echo " Some optional components were skipped due to missing packages" +fi + +echo "" +echo "๐Ÿ“ Next steps:" +echo "" +echo "1. Activate the Python virtual environment for each session:" +echo " source ./venv/bin/activate" +echo "" +echo "2. Add the CLI to your PATH (in your shell configuration):" +echo " export PATH=\$PATH:$(pwd)/core/cli/pf" +echo "" +echo "3. Initialize an agent:" +echo " ./core/cli/pf/pf init my-agent" +echo "" +echo "4. Run tests (with venv activated):" +echo " python tests/trust_fire_orchestrator.py" +echo "" + +if [ "$LEAN_AVAILABLE" != false ]; then + echo "5. For Lean 4 proofs:" + echo " cd spec-templates/v1/proofs && lake build" + echo "" +fi + +echo "๐Ÿ’ก NixOS Tips:" +echo " - Always activate the virtual environment before running Python scripts" +echo " - Consider creating a shell.nix or flake.nix for this project" +echo " - For persistent development, add tools to your configuration.nix" +echo "" + +# Create a convenient activation script +cat > activate.sh << 'EOF' +#!/usr/bin/env bash +# Convenience script to activate the development environment + +if [ -f "./venv/bin/activate" ]; then + source ./venv/bin/activate + export PATH=$PATH:$(pwd)/core/cli/pf + echo "โœ… Provability-Fabric environment activated" + echo " Python venv: $VIRTUAL_ENV" + echo " pf CLI available: $(which pf 2>/dev/null || echo 'not in PATH yet')" +else + echo "โŒ Virtual environment not found. Run ./scripts/install-nixos.sh first" +fi +EOF + +chmod +x activate.sh +echo "Created ./activate.sh for quick environment activation" \ No newline at end of file