Update documentation with comprehensive usage guide and improved update script

README.md

@@ -1,165 +1,320 @@
-# Cursor Flake
+# Cursor NixOS Flake
 
-A NixOS flake that provides a complete development environment with Cursor 1.3.9 (AI-first code editor) as an AppImage.
+A NixOS flake that provides Cursor 1.3.9 (AI-first code editor) as an AppImage with enhanced compatibility for NixOS systems.
 
 ## Features
 
 - **Cursor 1.3.9**: Latest version of the AI-first code editor
-- **AppImage Support**: Full AppImage compatibility with proper desktop integration
+- **Enhanced AppImage Support**: Optimized for NixOS with proper library paths and environment setup
-- **Development Tools**: Complete development environment with Node.js, Python, Rust, and more
+- **Easy Integration**: Can be used as a standalone system or integrated into existing NixOS flakes
+- **Development Tools**: Complete development environment with modern tools
 - **Modern Shell**: Zsh with Starship prompt and useful aliases
-- **Desktop Environment**: GNOME with essential utilities
-- **Git Integration**: Pre-configured Git with modern defaults
 
-## Prerequisites
+## Quick Start
 
-- NixOS system with flakes enabled
+### Option 1: Use as a Standalone System
-- At least 8GB RAM recommended
-- 20GB free disk space
-
-## Installation
-
-### 1. Clone the Repository
 
 ```bash
+# Clone the repository
 git clone https://github.com/thinktankmachine/cursor-nixos-flake
 cd cursor-nixos-flake
+
+# Build and switch to the configuration
+sudo nixos-rebuild switch --flake .#cursor-system
 ```
 
-### 2. Update the SHA256 Hash (if needed)
+### Option 2: Integrate into Existing NixOS Flake
 
-The current configuration uses the working Cursor 1.3.9 download URL. If you need to update to a newer version, run:
+Add to your `/etc/nixos/flake.nix`:
 
+```nix
+{
+  inputs = {
+    # ... your existing inputs
+    cursor-flake = {
+      url = "github:thinktankmachine/cursor-nixos-flake";
+      inputs.nixpkgs.follows = "nixpkgs";
+      inputs.home-manager.follows = "home-manager";
+    };
+  };
+
+  outputs = { nixpkgs, home-manager, cursor-flake, ... }: {
+    nixosConfigurations.your-system = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        # ... your existing modules
+        {
+          home-manager.users.your-username = { pkgs, ... }: {
+            home.packages = with pkgs; [
+              # ... your existing packages
+            ] ++ [
+              # Add Cursor from the flake
+              cursor-flake.packages.x86_64-linux.cursor
+            ];
+          };
+        }
+      ];
+    };
+  };
+}
+```
+
+Then rebuild:
 ```bash
+sudo nix flake update
+sudo nixos-rebuild switch --flake .#your-system
+```
+
+## Usage
+
+After installation, Cursor will be available:
+
+- **Applications Menu**: Look for "Cursor" in your desktop environment
+- **Terminal**: Run `cursor` from any terminal
+- **Command Line**: Use `cursor --version` to verify installation
+
+## Updating Cursor
+
+When a new version of Cursor is released, follow these steps to update the flake:
+
+### Step 1: Find the New Download URL
+
+1. Go to [Cursor's download page](https://cursor.sh/)
+2. Find the Linux AppImage download link
+3. Copy the URL (it will look like: `https://downloads.cursor.com/production/[hash]/linux/x64/Cursor-[version]-x86_64.AppImage`)
+
+### Step 2: Update the Flake
+
+1. **Update the URL in `home.nix`**:
+   ```nix
+   # Find this section in home.nix
+   cursorAppImage = pkgs.writeShellScriptBin "cursor" ''
+     # ... environment setup ...
+     
+     # Run the AppImage with appimage-run
+     exec ${pkgs.appimage-run}/bin/appimage-run ${pkgs.fetchurl {
+       url = "https://downloads.cursor.com/production/[NEW_HASH]/linux/x64/Cursor-[NEW_VERSION]-x86_64.AppImage";
+       sha256 = "OLD_HASH_HERE"; # This will be updated in the next step
+     }} "$@"
+   '';
+   ```
+
+2. **Update the SHA256 hash**:
+   ```bash
+   # Run the update script (it will fetch the new URL and update the hash)
    ./update-cursor-hash.sh
    ```
 
-This will automatically update the hash in `home.nix` with the correct value.
+3. **Test the build**:
-
-### 3. Customize Configuration
-
-Edit the following files to match your system:
-
-- `configuration.nix`: System-wide settings
-- `home.nix`: User-specific settings (change username from "liam" to your username)
-- `hardware-configuration.nix`: Hardware-specific settings (run `nixos-generate-config` on your target system)
-
-### 4. Build and Switch
-
    ```bash
-# Build the configuration
+   # Test that the flake builds correctly
-sudo nixos-rebuild build --flake .#cursor-system
+   nix build .#packages.x86_64-linux.cursor
-
-# Switch to the new configuration
-sudo nixos-rebuild switch --flake .#cursor-system
    ```
 
-### 5. First Boot Setup
+4. **Update your system**:
+   ```bash
+   # If using standalone system
+   sudo nixos-rebuild switch --flake .#cursor-system
    
-After the first boot:
+   # If integrated into main system
+   cd /etc/nixos
+   sudo nix flake update
+   sudo nixos-rebuild switch --flake .#your-system
+   ```
 
-1. Log in as the configured user
+### Step 3: Verify the Update
-2. Cursor will be available in the applications menu
+
-3. You can also launch it from the terminal with `cursor`
+```bash
+# Check the version
+cursor --version
+
+# Launch Cursor to ensure it works
+cursor
+```
+
+### Step 4: Commit and Push (Optional)
+
+```bash
+# Commit the changes
+git add .
+git commit -m "Update Cursor to version [NEW_VERSION]"
+git push origin main
+```
 
 ## Configuration
 
-### Cursor Settings
+### Customizing the Cursor Wrapper
 
-The flake includes pre-configured Cursor settings in `~/.config/Cursor/User/settings.json`:
+The Cursor AppImage wrapper in `home.nix` includes enhanced compatibility settings:
 
-- Modern font (JetBrains Mono with ligatures)
+```nix
-- Dark theme
+cursorAppImage = pkgs.writeShellScriptBin "cursor" ''
-- Optimized editor settings
+  # Set up environment for better AppImage compatibility
-- Cursor AI features enabled
+  export APPDIR=""
+  export ARGV0=""
+  export OWD=""
   
-### Development Environment
+  # Ensure proper library paths
+  export LD_LIBRARY_PATH="${pkgs.lib.makeLibraryPath [
+    pkgs.glib
+    pkgs.gtk3
+    pkgs.cairo
+    pkgs.pango
+    pkgs.atk
+    pkgs.gdk-pixbuf
+    pkgs.xorg.libX11
+    pkgs.xorg.libXcomposite
+    pkgs.xorg.libXcursor
+    pkgs.xorg.libXext
+    pkgs.xorg.libXfixes
+    pkgs.xorg.libXi
+    pkgs.xorg.libXrandr
+    pkgs.xorg.libXrender
+    pkgs.xorg.libXtst
+    pkgs.nss
+    pkgs.nspr
+    pkgs.dbus
+    pkgs.at-spi2-atk
+    pkgs.at-spi2-core
+    pkgs.mesa
+    pkgs.alsa-lib
+  ]}:$LD_LIBRARY_PATH"
   
-The flake includes:
+  # Run the AppImage with appimage-run
+  exec ${pkgs.appimage-run}/bin/appimage-run ${pkgs.fetchurl {
+    url = "https://downloads.cursor.com/production/[hash]/linux/x64/Cursor-[version]-x86_64.AppImage";
+    sha256 = "[hash]";
+  }} "$@"
+'';
+```
 
-- **Languages**: Node.js 20, Python 3, Rust
+### Adding Additional Packages
-- **Tools**: Git, ripgrep, fd, bat, exa, fzf, tmux
-- **Shell**: Zsh with Starship prompt
-- **Terminal**: Alacritty
 
-### Customization
+To add more development tools, edit `home.nix`:
 
-To customize the configuration:
+```nix
+home.packages = with pkgs; [
+  # Existing packages...
   
-1. **Add packages**: Edit `home.nix` and add to `home.packages`
+  # Add your packages here
-2. **Change shell**: Modify the shell configuration in `home.nix`
+  nodejs_20
-3. **Update Cursor settings**: Edit the settings in `home.nix`
+  python3
-4. **System packages**: Add to `environment.systemPackages` in `configuration.nix`
+  rustc
+  cargo
+  # ... more packages
+];
+```
 
 ## Troubleshooting
 
-### AppImage Issues
+### Common Issues
 
-If Cursor doesn't run properly:
+#### 1. AppImage Won't Run
 
-1. Check if AppImage support is enabled:
+**Symptoms**: `bwrap: Can't chdir to /etc/nixos: No such file or directory`
+
+**Solution**: Run Cursor from your home directory, not from system directories:
 ```bash
-   ls /proc/sys/fs/binfmt_misc/
+cd ~
+cursor
 ```
 
-2. Reinstall AppImage support:
+#### 2. Keymapping Errors
+
+**Symptoms**: `Error: Cannot find module './build/Debug/keymapping'`
+
+**Solution**: These are cosmetic errors and don't prevent Cursor from working. The enhanced wrapper should reduce these errors.
+
+#### 3. Library Loading Issues
+
+**Symptoms**: Various library-related errors
+
+**Solution**: The enhanced wrapper includes all necessary libraries. If issues persist, try:
 ```bash
-   sudo nixos-rebuild switch --flake .#cursor-system
+# Rebuild the system
+sudo nixos-rebuild switch --flake .#your-system
+
+# Clear AppImage cache
+rm -rf ~/.cache/appimage-run/*
 ```
 
-### Permission Issues
+#### 4. Git Authentication Issues
 
-If you encounter permission issues:
+**Symptoms**: `fatal: Authentication failed`
 
-1. Ensure the user is in the correct groups:
+**Solution**: Ensure your remote uses SSH:
 ```bash
-   groups
+git remote set-url origin git@github.com:username/repo.git
 ```
 
-2. Add user to additional groups if needed in `configuration.nix`
+### Testing the Flake
 
-### Update Cursor
+You can test the flake without affecting your system:
 
-To update to a newer version of Cursor:
+```bash
+# Build the VM image
+nix build .#nixosConfigurations.cursor-system.config.system.build.vm
 
-1. Update the version number in `home.nix`
+# Run the VM
-2. Update the download URL if needed
+./result/bin/run-cursor-system-vm
-3. Update the SHA256 hash
+```
-4. Rebuild the system
 
 ## File Structure
 
 ```
 cursor-flake/
-├── flake.nix                 # Main flake definition
+├── flake.nix                 # Main flake definition with outputs
 ├── configuration.nix         # NixOS system configuration
-├── home.nix                  # Home Manager user configuration
+├── home.nix                  # Home Manager configuration with Cursor wrapper
 ├── hardware-configuration.nix # Hardware-specific settings
-└── README.md                 # This file
+├── update-cursor-hash.sh     # Script to update Cursor hash
+├── test-configuration.nix    # Minimal test configuration
+├── test-home.nix            # Minimal test home configuration
+└── README.md                # This documentation
+```
+
+## Development
+
+### Adding Features
+
+1. **New packages**: Add to `home.packages` in `home.nix`
+2. **System changes**: Modify `configuration.nix`
+3. **User settings**: Update `home.nix` configuration
+
+### Testing Changes
+
+```bash
+# Test the flake syntax
+nix flake check
+
+# Test building the package
+nix build .#packages.x86_64-linux.cursor
+
+# Test the full system
+nix build .#nixosConfigurations.cursor-system.config.system.build.vm
 ```
 
 ## Contributing
 
 1. Fork the repository
-2. Create a feature branch
+2. Create a feature branch: `git checkout -b feature-name`
 3. Make your changes
-4. Test the configuration
+4. Test thoroughly: `nix flake check`
-5. Submit a pull request
+5. Commit: `git commit -m "Add feature description"`
+6. Push: `git push origin feature-name`
+7. Submit a pull request
 
 ## License
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+This project is licensed under the MIT License.
 
 ## Support
 
-For issues and questions:
+- **Issues**: [GitHub Issues](https://github.com/thinktankmachine/cursor-nixos-flake/issues)
-
+- **Discussions**: [GitHub Discussions](https://github.com/thinktankmachine/cursor-nixos-flake/discussions)
-1. Check the troubleshooting section
-2. Search existing issues
-3. Create a new issue with detailed information
 
 ## Acknowledgments
 
-- Cursor team for the excellent AI-first editor
+- [Cursor](https://cursor.sh/) team for the excellent AI-first editor
-- NixOS community for the amazing package management system
+- [NixOS](https://nixos.org/) community for the amazing package management system
-- Home Manager for user configuration management 
+- [Home Manager](https://github.com/nix-community/home-manager) for user configuration management 

update-cursor-hash.sh

@@ -1,32 +1,147 @@
 #!/usr/bin/env bash
 
 # Script to update the SHA256 hash for Cursor AppImage
-# Run this script to get the correct hash and update home.nix
+# This script helps you update the Cursor version and hash in the flake
 
 set -e
 
-echo "Fetching SHA256 hash for Cursor 1.3.9 AppImage..."
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Function to print colored output
+print_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+print_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Check if we're in the right directory
+if [[ ! -f "home.nix" ]]; then
+    print_error "This script must be run from the cursor-flake directory"
+    exit 1
+fi
+
+print_info "Cursor AppImage Hash Updater"
+echo ""
+
+# Get current URL from home.nix
+CURRENT_URL=$(grep -o 'https://downloads\.cursor\.com/[^"]*' home.nix | head -1)
+
+if [[ -z "$CURRENT_URL" ]]; then
+    print_error "Could not find Cursor download URL in home.nix"
+    exit 1
+fi
+
+print_info "Current URL: $CURRENT_URL"
+
+# Extract version from URL
+CURRENT_VERSION=$(echo "$CURRENT_URL" | grep -o 'Cursor-[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1 | sed 's/Cursor-//')
+
+if [[ -z "$CURRENT_VERSION" ]]; then
+    print_warning "Could not extract version from URL, using 'unknown'"
+    CURRENT_VERSION="unknown"
+fi
+
+print_info "Current version: $CURRENT_VERSION"
+echo ""
+
+# Ask user if they want to update to a new version
+read -p "Do you want to update to a new version? (y/N): " -n 1 -r
+echo
+
+if [[ $REPLY =~ ^[Yy]$ ]]; then
+    echo ""
+    print_info "To update to a new version:"
+    echo "1. Go to https://cursor.sh/"
+    echo "2. Download the Linux AppImage"
+    echo "3. Copy the download URL"
+    echo "4. Paste it below"
+    echo ""
+    
+    read -p "Enter the new Cursor download URL: " NEW_URL
+    
+    if [[ -z "$NEW_URL" ]]; then
+        print_error "No URL provided"
+        exit 1
+    fi
+    
+    # Extract new version
+    NEW_VERSION=$(echo "$NEW_URL" | grep -o 'Cursor-[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1 | sed 's/Cursor-//')
+    
+    if [[ -z "$NEW_VERSION" ]]; then
+        print_warning "Could not extract version from new URL"
+        NEW_VERSION="unknown"
+    fi
+    
+    print_info "New version: $NEW_VERSION"
+    
+    # Update the URL in home.nix
+    sed -i "s|$CURRENT_URL|$NEW_URL|g" home.nix
+    print_success "Updated URL in home.nix"
+    
+    URL_TO_HASH="$NEW_URL"
+else
+    URL_TO_HASH="$CURRENT_URL"
+fi
+
+echo ""
+print_info "Fetching SHA256 hash for AppImage..."
+echo "URL: $URL_TO_HASH"
 echo ""
 
 # Get the hash
-HASH=$(nix-prefetch-url https://downloads.cursor.com/production/54c27320fab08c9f5dd5873f07fca101f7a3e076/linux/x64/Cursor-1.3.9-x86_64.AppImage)
+print_info "Downloading and computing hash (this may take a moment)..."
+HASH=$(nix-prefetch-url "$URL_TO_HASH")
 
-echo "SHA256 hash: $HASH"
+if [[ -z "$HASH" ]]; then
-echo ""
+    print_error "Failed to get hash"
-echo "Please update the hash in home.nix:"
+    exit 1
-echo "Replace the placeholder hash with:"
-echo "sha256 = \"$HASH\";"
-echo ""
-echo "You can do this manually or run:"
-echo "sed -i 's/sha256 = \"sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=\";/sha256 = \"$HASH\";/' home.nix"
-echo ""
-
-# Optionally update the file automatically
-read -p "Do you want to update home.nix automatically? (y/N): " -n 1 -r
-echo
-if [[ $REPLY =~ ^[Yy]$ ]]; then
-    sed -i "s/sha256 = \"sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=\";/sha256 = \"$HASH\";/" home.nix
-    echo "Updated home.nix with the correct hash!"
-else
-    echo "Please update home.nix manually with the hash above."
 fi
+
+echo ""
+print_success "SHA256 hash: $HASH"
+echo ""
+
+# Find the current hash in home.nix
+CURRENT_HASH=$(grep -o 'sha256 = "[^"]*"' home.nix | head -1 | sed 's/sha256 = "//;s/"//')
+
+if [[ -z "$CURRENT_HASH" ]]; then
+    print_warning "Could not find current hash in home.nix"
+    print_info "Please manually update the hash in home.nix:"
+    echo "sha256 = \"$HASH\";"
+else
+    print_info "Current hash: $CURRENT_HASH"
+    print_info "New hash: $HASH"
+    echo ""
+    
+    if [[ "$CURRENT_HASH" == "$HASH" ]]; then
+        print_success "Hash is already up to date!"
+    else
+        # Update the hash in home.nix
+        sed -i "s/sha256 = \"$CURRENT_HASH\";/sha256 = \"$HASH\";/" home.nix
+        print_success "Updated hash in home.nix"
+    fi
+fi
+
+echo ""
+print_info "Next steps:"
+echo "1. Test the build: nix build .#packages.x86_64-linux.cursor"
+echo "2. Update your system: sudo nixos-rebuild switch --flake .#your-system"
+echo "3. Test Cursor: cursor --version"
+echo ""
+
+print_success "Hash update complete!"