manage.py: cross-platform process manager (replaces manage.sh, enables native Windows) #6

New issue

Closed

opened 2026-04-01 08:18:21 -07:00 by pyr0ball · 0 comments

pyr0ball commented

2026-04-01 08:18:21 -07:00

Owner

Cross-platform `manage.py` — replaces `manage.sh` for all products

Current manage.sh is bash-only, which blocks native Windows self-hosting. Replace with a cross-platform Python manage.py that works on Linux, macOS, and Windows natively (no WSL2, no Docker required).

Architecture

manage.sh and manage.ps1 are thin shims — they auto-detect the Python environment and delegate to manage.py. Existing ./manage.sh workflows are unchanged.

manage.sh shim (Linux/macOS):

#!/usr/bin/env bash
# Auto-detect Python environment, delegate to manage.py
if command -v conda &>/dev/null && [ -n "$CONDA_DEFAULT_ENV" ]; then
    PYTHON="conda run -n $CONDA_DEFAULT_ENV python"
elif [ -f ".venv/bin/python" ]; then
    PYTHON=".venv/bin/python"
else
    PYTHON="python3"
fi
exec $PYTHON manage.py "$@"

manage.ps1 shim (Windows):
Same pattern — finds Python in venv, conda, or PATH, then calls manage.py @args.

Two modes in manage.py

Docker mode (Linux/macOS default, Windows optional):
Wraps docker compose commands — start, stop, restart, status, logs, build

Native mode (Windows primary path, Linux/macOS optional):
Manages processes directly:

ollama serve (inference)
uvicorn api.main:app (FastAPI backend)
Static file server or npm run preview (Vue frontend)
SQLite lives at a platform-appropriate path (platformdirs)

Mode detection

Auto-detect: if Docker is available → Docker mode; else → native mode
Override: --mode native / --mode docker

Requirements

pathlib.Path throughout — no hardcoded Unix paths
platformdirs for config/data paths (AppData on Windows, ~/.config on Linux/macOS)
PID file management for native mode start/stop/status
Log tailing that works on Windows (no tail -f)
Single entry point: python manage.py start|stop|restart|status|logs|open

Replaces

manage.sh in: peregrine, snipe, kiwi, avocet, osprey (and all future products)
Ships as part of circuitforge-core so products shim into it.

## Cross-platform `manage.py` — replaces `manage.sh` for all products Current `manage.sh` is bash-only, which blocks native Windows self-hosting. Replace with a cross-platform Python `manage.py` that works on Linux, macOS, and Windows natively (no WSL2, no Docker required). ### Architecture `manage.sh` and `manage.ps1` are **thin shims** — they auto-detect the Python environment and delegate to `manage.py`. Existing `./manage.sh` workflows are unchanged. **`manage.sh` shim (Linux/macOS):** ```bash #!/usr/bin/env bash # Auto-detect Python environment, delegate to manage.py if command -v conda &>/dev/null && [ -n "$CONDA_DEFAULT_ENV" ]; then PYTHON="conda run -n $CONDA_DEFAULT_ENV python" elif [ -f ".venv/bin/python" ]; then PYTHON=".venv/bin/python" else PYTHON="python3" fi exec $PYTHON manage.py "$@" ``` **`manage.ps1` shim (Windows):** Same pattern — finds Python in venv, conda, or PATH, then calls `manage.py @args`. ### Two modes in manage.py **Docker mode** (Linux/macOS default, Windows optional): Wraps `docker compose` commands — `start`, `stop`, `restart`, `status`, `logs`, `build` **Native mode** (Windows primary path, Linux/macOS optional): Manages processes directly: - `ollama serve` (inference) - `uvicorn api.main:app` (FastAPI backend) - Static file server or `npm run preview` (Vue frontend) - SQLite lives at a platform-appropriate path (`platformdirs`) ### Mode detection - Auto-detect: if Docker is available → Docker mode; else → native mode - Override: `--mode native` / `--mode docker` ### Requirements - `pathlib.Path` throughout — no hardcoded Unix paths - `platformdirs` for config/data paths (`AppData` on Windows, `~/.config` on Linux/macOS) - PID file management for native mode start/stop/status - Log tailing that works on Windows (no `tail -f`) - Single entry point: `python manage.py start|stop|restart|status|logs|open` ### Replaces `manage.sh` in: peregrine, snipe, kiwi, avocet, osprey (and all future products) Ships as part of `circuitforge-core` so products shim into it.