windows bootstrap implemented

This commit is contained in:
nvaldez
2026-09-29 10:04:57 +02:00
parent 9b54aebe14
commit e6920aa691
6 changed files with 338 additions and 11 deletions
+1
View File
@@ -5,6 +5,7 @@ __pycache__/
# Virtual environments
.venv/
.venvs/
venv/
env/
ENV/
+25 -5
View File
@@ -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 <env_name> --python <version>
source bootstrap --env <env_name> -c
```
Windows (PowerShell, must be dot-sourced). This creates a repo-local venv
at `.venvs\<name>` 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 <env_name> --python <version>
. .\bootstrap.ps1 --env <env_name> -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 <env_name>
```
On Windows, dot-source the PowerShell script instead:
```powershell
. .\bootstrap.ps1 --env <env_name>
```
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 |
+15 -4
View File
@@ -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
```
+3
View File
@@ -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
+282
View File
@@ -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\<name> 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
+12 -2
View File
@@ -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