Added cross-platform local dev experience per #24

* Windows and Bash setup script
* Local debug loop using custom commandline args that are omitted from source control
* VS Code settings including extensions, Python settings and launch configuration

.editorconfig

@@ -0,0 +1,10 @@
+root=true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+
+[*.py]
+indent_size = 4

.gitattributes

@@ -0,0 +1 @@
+* text=lf

.gitignore

@@ -49,6 +49,7 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+.ruff_cache/
 cover/
 
 # Translations

.vscode/extensions.json

@@ -1,8 +1,10 @@
-{
-  "recommendations": [
-    "esbenp.prettier-vscode",
-    "ms-python.python",
-    "ms-python.vscode-pylance",
-    "charliermarsh.ruff"
-  ]
-}
+{
+  "recommendations": [
+    "esbenp.prettier-vscode",
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+    "charliermarsh.ruff",
+    "bungcip.better-toml",
+    "EditorConfig.EditorConfig"
+  ]
+}

.vscode/launch.json

@@ -1,16 +1,17 @@
-{
-    // Use IntelliSense to learn about possible attributes.
-    // Hover to view descriptions of existing attributes.
-    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "name": "Python: Module",
-            "type": "python",
-            "cwd": "${workspaceFolder}/src",
-            "request": "launch",
-            "module": "algokit",
-            "justMyCode": true
-        }
-    ]
-}
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Python: Module",
+      "type": "python",
+      "cwd": "${workspaceFolder}",
+      "request": "launch",
+      "module": "localinvoke",
+      "justMyCode": true,
+      "console": "internalConsole"
+    }
+  ]
+}

.vscode/settings.json

@@ -1,10 +1,46 @@
-{
-  "python.formatting.provider": "black",
-  "editor.formatOnSave": true,
-  "python.formatting.blackArgs": ["--line-length\", \"120\""],
-  "python.analysis.typeCheckingMode": "strict",
-  "python.linting.enabled": true,
-  "python.linting.lintOnSave": true,
-  "editor.defaultFormatter": "esbenp.prettier-vscode",
-  "files.eol": "\n"
-}
+{
+  // General - see also /.editorconfig
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": true
+  },
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+
+  // Python
+  // Inform VS Code there is an interpreter in the .venv for the workspace
+  // On Windows this doesn't work since it's not in .venv/bin, but rather .venv/Scripts.
+  //    However if you symlink Scripts -> bin it does work! Run scripts/setup.ps1 as admin for that trick
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python.analysis.extraPaths": ["${workspaceFolder}/src"],
+  "python.formatting.provider": "black",
+  "[python]": {
+    // https://dev.to/eegli/quick-guide-to-python-formatting-in-vs-code-2040
+    "editor.defaultFormatter": null
+  },
+  "python.analysis.typeCheckingMode": "strict",
+  "python.linting.enabled": true,
+  "python.linting.lintOnSave": true,
+  "ruff.importStrategy": "fromEnvironment",
+  "python.linting.pylintEnabled": false,
+  "python.linting.mypyEnabled": false,
+  "python.linting.banditEnabled": false,
+  "python.linting.prospectorEnabled": false,
+  "python.linting.pydocstyleEnabled": false,
+  "python.linting.pycodestyleEnabled": false,
+  // https://github.com/microsoft/vscode-python/issues/6933
+  "python.sortImports.args": [
+    "--multi-line=3",
+    "--trailing-comma",
+    "--force-grid-wrap=0",
+    "--use-parentheses",
+    "--line-width=120"
+  ],
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestEnabled": true,
+
+  // PowerShell
+  "[powershell]": {
+    "editor.defaultFormatter": "ms-vscode.powershell"
+  },
+  "powershell.codeFormatting.preset": "Stroustrup"
+}

CONTRIBUTING.MD

@@ -1,15 +1,49 @@
 # AlgoKit CLI for contributors
 
-## Setup
+## Setup (AlgoKit CLI development)
 
-### Dev environment dependencies (AlgoKit CLI development)
+### Initial setup
 
-- `Python` - [Link](https://www.python.org/downloads/): The minimum required version is `3.10`.
-- `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `1.2`.
+1. Clone this repository: `git clone https://github.com/algorandfoundation/algokit-cli`
+2. Install pre-requisites:
+
+   - Manually:
+     - Install `Python` - [Link](https://www.python.org/downloads/): The minimum required version is `3.10`.
+     - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `1.2`.
+     - Run `poetry install` in the root directory (this should set up `.venv` and install all Python dependencies)
+   - Via automated script:
+
+     - Bash (e.g. Linux, MacOS): `./scripts/setup.sh`
+     - Windows
+
+       1. Ensure you have [Powershell Core (7+)](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.2) e.g. via `winget install --id Microsoft.Powershell --source winget` or `choco install pwsh -y`
+       2. `./scripts/setup.ps1` (or if you want to confirm each step `./scripts/setup.ps1 -Confirm`)
+
+     - This setup.(sh|ps1) script will:
+
+       - Install Python 3.10 if not present (via `pyenv`, after installing pyenv)
+       - Install Poetry (via `pyenv`)
+       - Install Python dependencies and setup Python venv (to `./.venv/`) (via `poetry install`)
+       - (On Windows, if you execute the script as admin) Set up `.venv/bin` as a symlink to `.venv/Scripts` to provide a consistent path to reference the Python interpreter (optional, makes for a smoother getting started experience)
+
+3. Open it and start debugging / developing via:
+
+   - VS Code
+     1. Open the repository root in VS Code
+     2. Install recommended extensions
+     3. Copy `src/.env.sample` to `src/.env` and change `DEBUG_ARGS` to whatever commandline args you want to debug
+     4. Hit F5 and it should start running with breakpoint debugging
+   - IDEA (e.g. PyCharm)
+     1. Open the repository root in the IDE
+     2. Hit F5 and it should start running with breakpoint debugging
+   - Other
+     1. Open the repository root in your text editor of choice
+     2. In a terminal run `source ./.venv/bin/activate` (Non-Windows) or `./venv/Scripts/Activate.ps1` (Windows)
+     3. To execute the commandline execute: `python -m src.algokit [args]`
 
 ### Libraries and Tools
 
-AlgoKit uses Python as a main language and many Python libraries and tools. This section lists all of them with a tiny brief.  
+AlgoKit uses Python as a main language and many Python libraries and tools. This section lists all of them with a tiny brief.
 
 - [Poetry](https://python-poetry.org/): Python packaging and dependency management.
 - [pipx](https://github.com/pypa/pipx): Install and Run Python Applications in Isolated Environments

README.md

@@ -6,13 +6,13 @@ AlgoKit gets developers of all levels up and running with a familiar, fun and pr
 
 ## Use Cases
 
-TODO: List some example user stories
+- Building and deploying Algorand PyTEAL smart contracts
 
 ## Roadmap
 
 This tool is currently in early development. Feel free to explore the repository and install the tool, but be aware that this is a work in progress and features may not be stable at this stage.
 
-TODO: list outcomes as intended features and basic summary of each
+- Building and deploying Algorand dApps
 
 ## Guiding Principles
 
@@ -33,7 +33,7 @@ The target audience for this tool is software developers building applications o
 
 ## Contributing
 
-This is an open source project managed by the Algorand Foundation. See the [contributing page](CONTRIBUTING.MD) to learn about making improvements to the CLI tool itself.
+This is an open source project managed by the Algorand Foundation. See the [contributing page](CONTRIBUTING.MD) to learn about making improvements to the CLI tool itself, including developer setup instructions.
 
 # User Guide
 
@@ -52,10 +52,18 @@ Here's how to test it out and maybe even start hacking, assuming you have access
 1. Ensure [Python](https://www.python.org/downloads/) 3.10 or higher is installed on your system and available on your `PATH`
    - Note there is probably a better way to install Python than to download it directly, e.g. your friendly local Linux package manager, Homebrew on macOS, chocolatey on Windows
 2. Install [pipx](https://pypa.github.io/pipx/)
-   - Make sure to follow _all_ the instructions for your OS, there will be two commands, the first to install, and the second to ensure your path is setup. Make sure to read the output of this second command as well, as it'll probably tell you to relaunch your terminal.
-3. Checkout this repo e.g. with git clone
-4. If you want to start hacking on algokit-cli, run `poetry install` to install dependencies (including dev dependencies) and activate the virtual environment it creates in `.venv` in your checkout (you can run `poetry shell` or just activate it directly if you know what you're doing). If you're using an IDE it should probably do that for you though.
-5. Optionally, if you want to rest running `algokit`, then:
-   1. Run `poetry build` in the checkout (you shouldn't need to activate the venv first). This will output a "source distribution" (a tar.gz file) and a "binary distribution" (a .whl file) in the `dist/` directory.
-   2. Run `pipx install ./dist/algokit-<TAB>-<TAB>` (ie the .whl file)
-   3. You can now run `algokit` and should see a help message! 🎉
+   - Make sure to follow _all_ the instructions for your OS, there will be two commands, the first to install, and the second to ensure your path is setup so you can execute `pipx`. Make sure to read the output of this second command as well, as it'll probably tell you to relaunch your terminal.
+3. Either:
+
+   - Install via Git:
+
+     1. `pipx install git+https://github.com/algorandfoundation/algokit-cli`
+     2. You can now run `algokit` and should see a help message! 🎉
+
+   - Install via source:
+
+     1. Checkout this repository e.g. with git clone
+     2. Ensure you have Poetry installed
+     3. Run `poetry build` in the checkout (you shouldn't need to activate the venv first). This will output a "source distribution" (a tar.gz file) and a "binary distribution" (a .whl file) in the `dist/` directory.
+     4. Run `pipx install ./dist/algokit-<TAB>-<TAB>` (ie the .whl file)
+     5. You can now run `algokit` and should see a help message! 🎉

pyproject.toml

@@ -15,6 +15,7 @@ pytest = "^7.2.0"
 black = {extras = ["d"], version = "^22.10.0"}
 ruff = "^0.0.120"
 pip-audit = "^2.4.5"
+python-dotenv = "^0.21.0"
 
 [build-system]
 requires = ["poetry-core"]
@@ -54,4 +55,7 @@ per-file-ignores = {}
 # Allow unused variables when underscore-prefixed.
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 # Assume Python 3.10.
-target-version = "py310"
+target-version = "py310"
+
+[tool.black]
+line-length = 120

scripts/install-poetry.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+function installPoetry () {
+  pyenv="$(pyenv --version 2>/dev/null)"
+  if [[ $? -ne 0 ]]; then
+    echo "Error: can't install poetry, pyenv is not available ❌"
+    return 1
+  fi
+
+  echo "Installing poetry..."
+
+  pyenv exec pip install poetry
+  if [[ $? -ne 0 ]]; then
+    return 1
+  fi
+}
+
+installPoetry

scripts/install-pyenv.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+function installPyenvLinux () {
+  # https://github.com/pyenv/pyenv-installer
+  curl https://pyenv.run | bash
+  if [[ $? -ne 0 ]]; then
+    return 1
+  fi
+
+  # set up .bashrc for pyenv https://github.com/pyenv/pyenv-installer
+  if ! grep -q "# pyenv config" ~/.bashrc; then
+    echo '' >> ~/.bashrc
+    echo '# pyenv config' >> ~/.bashrc
+    echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
+    echo 'eval "$(pyenv init -)"' >> ~/.bashrc
+    echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc
+  fi
+}
+
+function installPyenvMac() {
+  brew install pyenv
+}
+
+echo "Installing pyenv..."
+
+if [ "$(uname -s)" == Darwin ]; then
+  installPyenvMac
+else
+  installPyenvLinux
+fi

scripts/install-python.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+function installPython () {
+
+  if [ $# -ne 1 ]; then
+    echo Error: missing python version argument, e.g.: install-python.sh 3.10.6
+    return 1
+  fi
+
+  PYTHON_VERSION=$1
+
+  if [ "$(uname -s)" == Linux ]; then
+    echo "Installing python build pre-requisistes..."
+    # install python build pre-requisites https://github.com/pyenv/pyenv/wiki#suggested-build-environment
+    sudo apt-get update; sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \
+    libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
+    libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
+  fi
+
+  pyenv="$(pyenv --version 2>/dev/null)"
+  if [[ $? -ne 0 ]]; then
+    echo "Error: can't install python, pyenv is not available (if it just installed you might need to restart your shell for environment to update) ❌"
+    return 1
+  fi
+
+  echo "Installing python..."
+
+  # install and use python via pyenv
+  pyenv install ${PYTHON_VERSION}
+  pyenv global ${PYTHON_VERSION}
+}
+
+installPython $1