deterministic-scripts

# Deterministic Script Execution ## Overview HASTE has established scripts and commands for common operations. Agents must use these exact commands instead of generating free-form alternatives. This prevents hallucinated scripts, ensures consistency, and makes operations repeatable. ## Key Concepts ### Why Deterministic Scripts Matter - LLMs can "helpfully" generate plausible-looking but incorrect commands - HASTE has specific build tooling (hatch, conda) that must be used correctly - Azure Functions deployment has specific prerequisites and ordering - Geospatial processing requires exact GDAL/rasterio invocations ## Patterns & Techniques ### Build & Package Operations | Operation | Exact Command | Notes | |-----------|--------------|-------| | Build core wheel | `cd hastelib && hatch build -t wheel` | Auto-increments version, copies to func apps | | Run Python tests | `cd hastelib && hatch run test:pytest` | Uses conda env with GDAL | | Build UI | `cd ui && npm run build` | Production build via Vite | | Lint UI | `cd ui && npm run lint` | ESLint with React rules | | Install UI deps | `cd ui && npm install` | Uses package-lock.json | | Create conda env | `conda env create -f env.yml` | Full env with GDAL and dependencies | | Update conda env | `conda env update -f env.yml` | Preserves existing packages | | Install hastelib editable | `pip install -e hastelib/` | For local development hot-reload | ### Local Development | Operation | Exact Command | Notes | |-----------|--------------|-------| | Start API locally | `cd api/hastefuncapi && func host start` | Requires `.venv` or conda env | | Start UI locally | `cd ui && swa start --app-devserver-url http://localhost:5173 --run 'npm run dev'` | SWA CLI with Vite dev server | | Start Azurite | `azurite --silent --location ./data --debug ./data/debug.log` | Local Azure Storage emulator | | Start Docker stack | `docker-compose -f docker/docker-compose.yml up` | Full local stack | ### Deployment | Operation | Exact Command | Notes | |-----------|--------------|-------| | Deploy Azure Function | `func azure functionapp publish <NAME> --subscription <SUB> --tenant <TENANT>` | After `hatch build` | | Deploy SWA | `cd ui && swa deploy --app-location ./dist --app-name <NAME>` | After `npm run build` | | Build Docker images | `./build_and_push_images.sh` | Builds training + imagery prep images | ### Imagery Processing | Operation | Approach | Notes | |-----------|----------|-------| | COG generation | Use rasterio with `COG` driver profile | Never use raw GDAL CLI unless wrapping in Python | | Tile generation | Through `ImageryPreProcessor` | Not manual gdal2tiles | | Reprojection | `rasterio.warp.reproject()` | Always specify `src_crs` and `dst_crs` | | Format conversion | Through provider-specific adapter | Not generic `gdal_translate` | ## Decision Framework | Situation | Do This | NOT This | |-----------|---------|----------| | Need to run tests | `hatch run test:pytest` | `pytest` (wrong env) | | Need to build wheel | `hatch build -t wheel` | `python setup.py bdist_wheel` | | Need to start API | `func host start` | `python function_app.py` | | Need Azure storage locally | `azurite` | Custom mock storage | | Need to process imagery | Use `ImageryPreProcessor` | Write new GDAL script | | Need to deploy | `func azure functionapp publish` | Manual zip deployment | ## Common Pitfalls - **Inventing new build commands** — Use the established commands above - **Running pytest directly** — Use `hatch run test:pytest` to get the correct conda env - **Starting the UI with `npm start`** — HASTE uses `swa start` with Vite dev server - **Using `python setup.py`** — HASTE uses hatch/hatchling, not setuptools - **Generating GDAL scripts from scratch** — Use existing processor methods