From e6920aa69135ccfdd6149e3f78f3e2b1d94409bf Mon Sep 17 00:00:00 2001 From: nvaldez Date: Tue, 29 Sep 2026 10:04:57 +0200 Subject: [PATCH] windows bootstrap implemented --- .gitignore | 1 + AGENTS.md | 30 +++++- README.md | 19 +++- bootstrap | 3 + bootstrap.ps1 | 282 ++++++++++++++++++++++++++++++++++++++++++++++++++ src/README.md | 14 ++- 6 files changed, 338 insertions(+), 11 deletions(-) create mode 100644 bootstrap.ps1 diff --git a/.gitignore b/.gitignore index 2c3c3af..1506685 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ __pycache__/ # Virtual environments .venv/ +.venvs/ venv/ env/ ENV/ diff --git a/AGENTS.md b/AGENTS.md index 5433ae1..e8a284c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,10 @@ --- name: Fiona-Assistant Agent Rules -version: 1.3.1 +version: 1.3.2 title: LLM Agent Rules type: summary created: 2025-09-23 -updated: 2026-09-26 +updated: 2026-09-29 tags: [agents, rules, guidelines, llm, ai] sources: [] --- @@ -90,7 +90,9 @@ AGENTS.md files (e.g. the llm-wiki template's `src/llm-wiki/AGENTS.md`). ### 3.1 Always Use Bootstrap for Environment -> BEFORE any testing or development work, you MUST source the bootstrap script +> BEFORE any testing or development work, you MUST load the bootstrap script + +Linux / macOS (bash, must be sourced): ```bash # Bare minimum - always run this first @@ -106,6 +108,17 @@ source bootstrap --env --python source bootstrap --env -c ``` +Windows (PowerShell, must be dot-sourced). This creates a repo-local venv +at `.venvs\` with the Python launcher. It does not install pyenv. + +```powershell +Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass +. .\bootstrap.ps1 +. .\bootstrap.ps1 --env fiona_env +. .\bootstrap.ps1 --env --python +. .\bootstrap.ps1 --env -c +``` + **Rationale**: The bootstrap script sets up the Python virtual environment, installs dependencies, and ensures a consistent development environment. All testing and development MUST happen within this environment. @@ -177,7 +190,8 @@ fiona-assistant/ │ └── install_packages.sh # Dependency installer │ ├── pyproject.toml # Project configuration -├── bootstrap # Environment setup +├── bootstrap # Environment setup (bash; source it) +├── bootstrap.ps1 # Environment setup (PowerShell; dot-source it) └── README.md # Project documentation ``` @@ -302,6 +316,12 @@ git commit -m "test: add TDD tests for name/version extraction" source bootstrap --env ``` + On Windows, dot-source the PowerShell script instead: + + ```powershell + . .\bootstrap.ps1 --env + ``` + 2. **Load Appropriate Skill** (if applicable) - Python tasks: Load `python-tdd` skill - Wiki tasks: Load `llm-wiki` skill @@ -435,7 +455,7 @@ These rules **CAN** be overridden by: | Task | Required Action | | ---- | -------------- | | Any Python work | Load python-tdd skill | -| Before testing | `source bootstrap` | +| Before testing | `source bootstrap` (Windows: `. .\bootstrap.ps1`) | | Changing functionality | Read [SPEC](./SPEC.md) first | | Modifying code | Write tests first (TDD) | | Before commit | Run tests + linters | diff --git a/README.md b/README.md index 5ba1d65..9a305e2 100644 --- a/README.md +++ b/README.md @@ -81,12 +81,22 @@ python -m pip install fiona-assistant ``` - **Create and activate the virtual environment:** - - ```bash + + Linux / macOS: + + ```bash source bootstrap --env fiona_env -c ``` - > Make sure `fiona_env` is activated as pyenv before proceeding + Windows (PowerShell): + + ```powershell + Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass + . .\bootstrap.ps1 --env fiona_env -c + ``` + + > Make sure `fiona_env` is activated before proceeding. On Windows the + > environment lives in `.venvs\fiona_env`. --- @@ -282,7 +292,8 @@ fiona-assistant/ │ └── README.md # Development documentation │ ├── pyproject.toml # Project configuration -├── bootstrap # Environment setup script +├── bootstrap # Environment setup script (bash) +├── bootstrap.ps1 # Environment setup script (PowerShell) ├── LICENSE # GPL-3.0-only └── README.md # This file ``` diff --git a/bootstrap b/bootstrap index 61e3812..eab1c39 100755 --- a/bootstrap +++ b/bootstrap @@ -5,6 +5,9 @@ # This script MUST be sourced to properly set up the environment: # source bootstrap # +# Windows (PowerShell): dot-source bootstrap.ps1 instead +# . .\bootstrap.ps1 [--env name] [--python 3.x.x] [-c|--clean] +# # What it does: # 1. Installs pyenv and required system dependencies if needed # 2. Initializes pyenv and pyenv-virtualenv in the current shell diff --git a/bootstrap.ps1 b/bootstrap.ps1 new file mode 100644 index 0000000..92eb31a --- /dev/null +++ b/bootstrap.ps1 @@ -0,0 +1,282 @@ +# Generated by CURSOR: 2026-09-29 - Windows PowerShell bootstrap for Fiona development +# +# Project bootstrap for Windows. Dot-source it so the virtual environment +# stays active in the current session (same idea as `source bootstrap`): +# +# Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass +# . .\bootstrap.ps1 +# . .\bootstrap.ps1 --env fiona_env +# . .\bootstrap.ps1 --env fiona_env --python 3.13.8 -c +# +# Creates a repo-local venv at .venvs\ with the Python launcher (py) +# or python on PATH. Does not install pyenv. --pyenv is accepted so the +# Linux flag still parses; on Windows it is a no-op notice. + +#Requires -Version 5.1 + +# CURSOR: flags are parsed by hand. Windows PowerShell 5.1 does not bind +# `--python` to a parameter alias, and the bash script uses those flags. + +function Write-FionaStatus { + param([string]$Message) + Write-Host "[+] $Message" -ForegroundColor Green +} + +function Write-FionaWarning { + param([string]$Message) + Write-Host "[!] $Message" -ForegroundColor Yellow +} + +function Write-FionaError { + param([string]$Message) + Write-Host "[x] $Message" -ForegroundColor Red +} + +function Remove-FionaBootstrapFunctions { + if (Get-Variable -Name FionaPrevErrorAction -Scope 1 -ErrorAction SilentlyContinue) { + Set-Variable -Name ErrorActionPreference -Value $FionaPrevErrorAction -Scope 1 + Remove-Variable -Name FionaPrevErrorAction -Scope 1 -ErrorAction SilentlyContinue + } + foreach ($name in @( + "Write-FionaStatus", + "Write-FionaWarning", + "Write-FionaError", + "Resolve-FionaPython", + "Remove-FionaBootstrapFunctions" + )) { + Remove-Item -Path "Function:\$name" -ErrorAction SilentlyContinue + } +} + +function Resolve-FionaPython { + # CURSOR: pick a real interpreter. Prefer the py launcher so a requested + # version (3.13.8, then 3.13) wins over whatever `python` happens to be. + param([string]$Version) + + $tags = @() + if ($Version) { + $tags += $Version + if ($Version -match '^(\d+\.\d+)') { + $minor = $Matches[1] + if ($minor -ne $Version) { + $tags += $minor + } + } + } + + $py = Get-Command py -ErrorAction SilentlyContinue + if ($py) { + foreach ($tag in $tags) { + $exe = & py "-$tag" -c "import sys; print(sys.executable)" 2>$null + if ($LASTEXITCODE -eq 0 -and $exe) { + return @($exe)[-1].ToString().Trim() + } + } + if (-not $Version) { + $exe = & py -3 -c "import sys; print(sys.executable)" 2>$null + if ($LASTEXITCODE -eq 0 -and $exe) { + return @($exe)[-1].ToString().Trim() + } + } + } + + if (-not $Version) { + foreach ($name in @("python", "python3")) { + $cmd = Get-Command $name -ErrorAction SilentlyContinue + if ($cmd -and $cmd.Source -notmatch "WindowsApps") { + return $cmd.Source + } + } + } + + return $null +} + +$FionaPrevErrorAction = $ErrorActionPreference +$ErrorActionPreference = "Stop" +# CURSOR: a failed pip/py call must be checked via $LASTEXITCODE, not thrown. +if (Get-Variable -Name PSNativeCommandUseErrorActionPreference -ErrorAction SilentlyContinue) { + $PSNativeCommandUseErrorActionPreference = $false +} + +$Clean = $false +$EnvName = "test_env" +$PythonVersion = "" +$Pyenv = $false +$bootstrapArgs = @($args) +for ($i = 0; $i -lt $bootstrapArgs.Count; $i++) { + $token = [string]$bootstrapArgs[$i] + if ($token -eq "--pyenv") { + $Pyenv = $true + } + elseif ($token -eq "-c" -or $token -eq "--clean") { + $Clean = $true + } + elseif ($token -eq "--env") { + if (($i + 1) -ge $bootstrapArgs.Count) { + Write-FionaError "--env requires an environment name argument" + Remove-FionaBootstrapFunctions + return + } + $i++ + $EnvName = [string]$bootstrapArgs[$i] + } + elseif ($token -eq "--python") { + if (($i + 1) -ge $bootstrapArgs.Count) { + Write-FionaError "--python requires a version number argument" + Remove-FionaBootstrapFunctions + return + } + $i++ + $PythonVersion = [string]$bootstrapArgs[$i] + } + else { + Write-FionaError "Unknown option: $token" + Write-FionaError "Usage: . .\bootstrap.ps1 [--pyenv] [-c|--clean] [--env custom_name] [--python 3.x.x]" + Remove-FionaBootstrapFunctions + return + } +} + +if ($MyInvocation.InvocationName -ne ".") { + Write-FionaError "Dot-source this script so the virtual environment stays active in this session." + Write-FionaError " . .\bootstrap.ps1" + Remove-FionaBootstrapFunctions + return +} + +if ($Pyenv) { + Write-FionaWarning "Windows bootstrap uses a local venv under .venvs\. It does not install pyenv." +} + +$repoRoot = $PSScriptRoot +if (-not $repoRoot) { + $repoRoot = (Get-Location).Path +} + +Write-FionaStatus "Starting project bootstrap with environment: $EnvName" + +try { + Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force -ErrorAction Stop | Out-Null +} +catch { + # CURSOR: a GPO can refuse the process override. RemoteSigned still runs local scripts. +} + +$pythonExe = Resolve-FionaPython -Version $PythonVersion +if (-not $pythonExe) { + Write-FionaError "Python is not installed, or version '$PythonVersion' is not available to the py launcher." + Write-FionaError "Install Python from https://www.python.org/downloads/ and enable the py launcher." + if ($PythonVersion) { + Write-FionaError "Then re-run: . .\bootstrap.ps1 --python $PythonVersion" + } + Remove-FionaBootstrapFunctions + return +} + +$venvRoot = Join-Path $repoRoot ".venvs" +$venvPath = Join-Path $venvRoot $EnvName + +if ($Clean -and (Test-Path -LiteralPath $venvPath)) { + Write-FionaStatus "Deleting existing virtual environment $EnvName..." + try { + Remove-Item -LiteralPath $venvPath -Recurse -Force + } + catch { + Write-FionaError "Failed to delete virtual environment $EnvName" + Write-FionaError $_.Exception.Message + Remove-FionaBootstrapFunctions + return + } +} + +$activate = Join-Path $venvPath "Scripts\Activate.ps1" +if (-not (Test-Path -LiteralPath $activate)) { + Write-FionaStatus "Creating virtual environment $EnvName with $pythonExe..." + New-Item -ItemType Directory -Path $venvRoot -Force | Out-Null + & $pythonExe -m venv $venvPath + if ($LASTEXITCODE -ne 0) { + Write-FionaError "Failed to create virtual environment $EnvName" + Remove-FionaBootstrapFunctions + return + } +} +else { + Write-FionaStatus "Virtual environment $EnvName already exists" +} + +Write-FionaStatus "Activating $EnvName..." +. $activate + +if (-not $env:VIRTUAL_ENV) { + Write-FionaError "Failed to activate $EnvName" + Remove-FionaBootstrapFunctions + return +} + +if ($env:PYTEST_ADDOPTS) { + $sanitized = $env:PYTEST_ADDOPTS -replace '--no-summary', '' -replace '(^|\s)-S(\s|$)', ' ' + $sanitized = ($sanitized -replace '\s+', ' ').Trim() + if ($sanitized -ne $env:PYTEST_ADDOPTS.Trim()) { + Write-FionaWarning "Removing --no-summary from PYTEST_ADDOPTS so test output can be parsed" + if ($sanitized) { + $env:PYTEST_ADDOPTS = $sanitized + } + else { + Remove-Item Env:PYTEST_ADDOPTS + } + } +} +if ($env:FORCE_COLOR) { + Write-FionaWarning "Unsetting FORCE_COLOR so pytest output can be parsed" + Remove-Item Env:FORCE_COLOR +} +if ($env:PY_COLORS) { + Write-FionaWarning "Unsetting PY_COLORS so pytest output can be parsed" + Remove-Item Env:PY_COLORS +} + +$pyproject = Join-Path $repoRoot "pyproject.toml" +if (-not (Test-Path -LiteralPath $pyproject)) { + Write-FionaError "No pyproject.toml found at $pyproject" + Remove-FionaBootstrapFunctions + return +} + +Write-FionaStatus "Upgrading pip..." +& python -m pip install --upgrade pip +if ($LASTEXITCODE -ne 0) { + Write-FionaWarning "Failed to upgrade pip. Continuing with package installation..." +} + +Write-FionaStatus "Installing package and dependencies from pyproject.toml..." +Push-Location $repoRoot +try { + & python -m pip install -e ".[dev]" + if ($LASTEXITCODE -ne 0) { + Write-FionaError "Failed to install package and dependencies from pyproject.toml" + Remove-FionaBootstrapFunctions + return + } +} +finally { + Pop-Location +} + +$pythonCmd = Get-Command python -ErrorAction SilentlyContinue +$pythonWhere = if ($pythonCmd) { $pythonCmd.Source } else { "python" } +$pythonVersionText = (& python --version 2>&1 | Out-String).Trim() +$pipVersionText = (& python -m pip --version 2>&1 | Out-String).Trim() + +Write-FionaStatus "Bootstrap completed successfully!" +Write-FionaStatus "Virtual environment '$EnvName' is active" +Write-FionaStatus "Python: $pythonVersionText ($pythonWhere)" +Write-FionaStatus "Pip: $pipVersionText" +Write-FionaStatus "" +Write-FionaStatus "To verify installation, try:" +Write-FionaStatus " python src/run_tests.py" +Write-FionaStatus " fiona-assistant --help" +Write-FionaStatus "" +Write-FionaStatus "Happy coding!" + +Remove-FionaBootstrapFunctions diff --git a/src/README.md b/src/README.md index 5dc46f2..587e615 100644 --- a/src/README.md +++ b/src/README.md @@ -20,7 +20,9 @@ The Fiona Assistant project provides command-line tools for: cd fiona-assistant ``` -2. Set up the Python environment using the bootstrap script: +2. Set up the Python environment using the bootstrap script. + + Linux / macOS: ```bash source bootstrap --env fiona_env @@ -32,6 +34,13 @@ The Fiona Assistant project provides command-line tools for: source bootstrap --env fiona_env --python 3.11.0 ``` + Windows (PowerShell): + + ```powershell + Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass + . .\bootstrap.ps1 --env fiona_env --python 3.11.0 + ``` + 3. Install the package in development mode: ```bash @@ -87,7 +96,8 @@ pytest --cov=src The project includes several development utilities: -- `bootstrap`: Set up the Python development environment +- `bootstrap`: Set up the Python development environment (bash) +- `bootstrap.ps1`: Set up the Python development environment (PowerShell) - `src/utils.sh`: Shell utility functions - `src/install_packages.sh`: Install local Python packages - `src/run_tests.sh`: Run the test suite