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):

# 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):

# 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/bootstrap.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):

  MM_DEBUG=1 mm
  

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

  $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):

irm https://deno.land/install.ps1 | iex

Linux/macOS:

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):

$env:DENO_VERSION = 'v1.34.3'; .\scripts\bootstrap.ps1

POSIX (Linux/macOS):

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.