Medios-Macina/docs/BOOTSTRAP.md

# Bootstrapping the development environment

This project includes convenience scripts to create a Python virtual environment, install the package, and (optionally) create OS shortcuts.

Files:
- `scripts/bootstrap.ps1` — PowerShell script for Windows (creates venv, installs, optional Desktop/Start Menu shortcuts)
- `scripts/bootstrap.sh` — POSIX shell script (Linux/macOS) (creates venv, installs, optional desktop launcher)

Quick examples

Windows (PowerShell):

```powershell
# Create a .venv, install in editable mode and add a Desktop shortcut
powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap.ps1 -Editable -CreateDesktopShortcut

# Use a specific python.exe and force overwrite
powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap.ps1 -Python "C:\\Python39\\python.exe" -Force
```

Linux/macOS (bash):

```bash
# Create a .venv and install the project in editable mode
./scripts/bootstrap.sh --editable

# Create a desktop entry (GNU/Linux)
./scripts/bootstrap.sh --editable --desktop
```

Notes

- On Windows you may need to run PowerShell with an appropriate ExecutionPolicy (example shows using `-ExecutionPolicy Bypass`).
- The scripts default to a venv directory named `.venv` in the repository root. Use `-VenvPath` (PowerShell) or `--venv` (bash) to choose a different directory.
- The scripts will also install Playwright browser binaries by default (Chromium only) after installing Python dependencies. Use `--no-playwright` (bash) or `-NoPlaywright` (PowerShell) to opt out, or `--playwright-browsers <list>` / `-PlaywrightBrowsers <list>` to request specific engines (comma-separated, or use `all` to install all engines).
- The scripts are intended to make day-to-day developer setup easy; tweak flags for your desired install mode (editable vs normal) and shortcut preferences.

## Deno — installed by bootstrap

The bootstrap scripts will automatically install Deno if it is not already present on the system. They use the official installers and attempt to add Deno's bin directory to the PATH for the current session. If the installer completes but `deno` is not available in your shell, restart your shell or add `$HOME/.deno/bin` (Windows: `%USERPROFILE%\\.deno\\bin`) to your PATH.

Opinionated behavior

Running `python ./scripts/setup.py` is intentionally opinionated: it will create a local virtual environment at `./.venv` (repo root), install Python dependencies and the project into that venv, install Playwright browsers, install Deno, and write small launcher scripts in the project root:

- `mm` (POSIX shell)
- `mm.ps1` (PowerShell)
- `mm.bat` (Windows CMD)

These launchers prefer the local `./.venv` Python and console scripts so you can run the project with `./mm` or `mm.ps1` directly from the repo root.

- When installing in editable mode from a development checkout, the bootstrap will also add a small `.pth` file to the venv's `site-packages` pointing at the repository root. This ensures top-level scripts such as `CLI.py` are importable even when using PEP 660 editable wheels (avoids having to create an egg-link by hand).

Additionally, the setup helpers install a global `mm` launcher into your user bin so you can run `mm` from any shell session:

- POSIX: `~/.local/bin/mm` (created if missing; the script attempts to add `~/.local/bin` to `PATH` by updating `~/.profile` / shell RCs if required)
- Windows: `%USERPROFILE%\bin\mm.cmd` and `%USERPROFILE%\bin\mm.ps1` (created if missing; the script attempts to add the folder to your **User** PATH)

The scripts back up any existing `mm` shims before replacing them and will print actionable messages when a shell restart is required.

Debugging the global `mm` launcher

- POSIX: set MM_DEBUG=1 and run `mm` to print runtime diagnostics (resolved REPO, VENV, and Python import checks):

  ```bash
  MM_DEBUG=1 mm
  ```

- PowerShell: set and export `$env:MM_DEBUG='1'` then run `mm.ps1` or the installed `mm` shim:

  ```powershell
  $env:MM_DEBUG = '1'
  mm
  ```

- CMD: `set MM_DEBUG=1` then run `mm`.

These diagnostics help identify whether the global launcher is selecting the correct repository and virtual environment; please include the output when reporting launcher failures.

PowerShell (Windows):
```powershell
irm https://deno.land/install.ps1 | iex
```

Linux/macOS:
```bash
curl -fsSL https://deno.land/install.sh | sh
```

Pinning a Deno version

You can pin a Deno release by setting the `DENO_VERSION` environment variable before running the bootstrap script. Examples:

PowerShell (Windows):
```powershell
$env:DENO_VERSION = 'v1.34.3'; .\scripts\bootstrap.ps1
```

POSIX (Linux/macOS):
```bash
DENO_VERSION=v1.34.3 ./scripts/bootstrap.sh
```

If you'd like, I can also:
- Add a short README section in `readme.md` referencing this doc, or
- Add a small icon and polish Linux desktop entries with an icon path.

## Troubleshooting: urllib3 / urllib3-future conflicts ⚠️

On some environments a third-party package (for example `urllib3-future`) may
install a site-packages hook that interferes with the real `urllib3` package.
When this happens you might see errors like:

  Error importing cmdlet 'get_tag': No module named 'urllib3.exceptions'

The bootstrap scripts now run a verification step after installing dependencies
and will stop if a broken `urllib3` is detected to avoid leaving you with a
partially broken venv.

Recommended fix (activate the venv first or use the venv python explicitly):

PowerShell / Windows (from repo root):

  .venv\Scripts\python.exe -m pip uninstall urllib3-future -y
  .venv\Scripts\python.exe -m pip install --upgrade --force-reinstall urllib3
  .venv\Scripts\python.exe -m pip install niquests -U

POSIX (Linux/macOS):

  .venv/bin/python -m pip uninstall urllib3-future -y
  .venv/bin/python -m pip install --upgrade --force-reinstall urllib3
  .venv/bin/python -m pip install niquests -U

If problems persist, re-run the bootstrap script after applying the fixes.