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 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.

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.

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.