docs: minor refinements in readme (#9)

* docs: refining readme instructions + codetours

* fix: patching xdist

* fix: pyright warnings in codespace mode

Author: aorumbayev

.github/workflows/check-python.yaml

@@ -48,7 +48,7 @@ jobs:
         shell: bash
         run: |
           set -o pipefail
-          poetry run pytest --junitxml=pytest-junit.xml -n auto
+          poetry run pytest --junitxml=pytest-junit.xml
 
       - name: Check generated templates have been reviewed
         shell: bash

.gitignore

@@ -175,7 +175,7 @@ examples/**/package-lock.json
 examples/**/poetry.lock
 
 # playground folder for previewing templates
-.playground/*
+playground
 
 # Misc
 examples/**/smart_contracts/artifacts

.vscode/clear.ps1

@@ -1 +1 @@
-Remove-Item -Recurse -Force .playground -ErrorAction Ignore
+Remove-Item -Recurse -Force playground -ErrorAction Ignore

.vscode/tasks.json

@@ -8,7 +8,7 @@
         "-v",
         "init",
         "--name",
-        ".playground",
+        "playground",
         "--no-git",
         "--defaults",
         "--UNSAFE-SECURITY-accept-template-url",
@@ -23,7 +23,7 @@
         "kind": "build",
         "isDefault": true
       },
-      "dependsOn": ["Cleanup .playground folder"],
+      "dependsOn": ["Cleanup playground folder"],
       "problemMatcher": []
     },
     {
@@ -33,7 +33,7 @@
         "-v",
         "init",
         "--name",
-        ".playground",
+        "playground",
         "--no-git",
         "--defaults",
         "--UNSAFE-SECURITY-accept-template-url",
@@ -51,7 +51,7 @@
         "kind": "build",
         "isDefault": true
       },
-      "dependsOn": ["Cleanup .playground folder"],
+      "dependsOn": ["Cleanup playground folder"],
       "problemMatcher": []
     },
     {
@@ -61,7 +61,7 @@
         "-v",
         "init",
         "--name",
-        ".playground",
+        "playground",
         "--no-git",
         "--UNSAFE-SECURITY-accept-template-url",
         "--template-url",
@@ -71,13 +71,13 @@
         "--no-bootstrap"
       ],
       "type": "shell",
-      "dependsOn": ["Cleanup .playground folder"],
+      "dependsOn": ["Cleanup playground folder"],
       "problemMatcher": []
     },
     {
-      "label": "Cleanup .playground folder",
+      "label": "Cleanup playground folder",
       "command": "rm",
-      "args": ["-rf", ".playground"],
+      "args": ["-rf", "playground"],
       "type": "shell",
       "windows": {
         "command": "./.vscode/clear.ps1"

CONTRIBUTING.md

@@ -12,7 +12,7 @@ This repository is a template for creating new AlgoKit projects. It includes a b
 Ensure localnet is running by executing `algokit localnet reset`.
 
 ```bash
-poetry run pytest -n auto
+poetry run pytest
 ```
 
 This will regenerate the tests for default `starter` and `production` presets as well as default tests for `generators` available on the template.
@@ -22,20 +22,20 @@ This will regenerate the tests for default `starter` and `production` presets as
 ### Manual
 
 ```bash
-poetry run copier copy . .playground --vcs-ref=HEAD --trust
+poetry run copier copy . playground --vcs-ref=HEAD --trust
 ```
 
-To generate a dummy project into the `.playground` folder. This is useful for testing the template to quickly preview the output of the template before testing via `pytest`.
+To generate a dummy project into the `playground` folder. This is useful for testing the template to quickly preview the output of the template before testing via `pytest`.
 
 ### Using VSCode Tasks
 
 In VSCode IDE, you can find the tasks in the `.vscode/tasks.json` file. To run them:
 
 1. Open the command palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` on Windows/Linux) and type `> Run Task`
 2. Select the task you want to run
-3. It will be generated for you under the .playground folder
+3. It will be generated for you under the playground folder
 
-To cleanup the .playground folder run dedicated cleanup task.
+To cleanup the playground folder run dedicated cleanup task.
 
 ## Contributing
 

examples/generators/production_python_smart_contract_python/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2

@@ -1,3 +1,4 @@
+# pyright: reportMissingModuleSource=false
 from algopy import ARC4Contract, arc4
 
 

examples/generators/production_python_smart_contract_python/.tours/getting-started-with-your-algokit-project.tour

@@ -13,13 +13,13 @@
       "line": 9
     },
     {
-      "file": "smart_contracts/__main__.py",
-      "description": "This is the main entry point for building your smart contracts. The default template includes a starter 'Hello World' contract that is deployed via the `algokit-utils` package (either `ts` or `py`, depending on your choice). To create a new smart contract, you can use the [`algokit generate`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md) command and invoke a pre-bundled generator template by running `algokit generate smart-contract`. This action will create a new folder in the `smart_contracts` directory, named after your project. Each folder contains a `contract.py` file, which is the entry point for your contract implementation, and `deploy_config.py` | `deployConfig.ts` files (depending on the language chosen for the template), that perform the deployment of the contract.",
-      "line": 26
+      "file": ".algokit.toml",
+      "description": "This is the main configuration file used by algokit-cli to manage the project. The default template includes a starter 'Hello World' contract that is deployed via the `algokit-utils` package (either `ts` or `py`, depending on your choice). To create a new smart contract, you can use the [`algokit generate`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md) command and invoke a pre-bundled generator template by running `algokit generate smart-contract` (see how it is defined in the `.algokit.toml`, you can create your own generators if needed). This action will create a new folder in the `smart_contracts` directory, named after your project. Each folder contains a `contract.py` file, which is the entry point for your contract implementation, and `deploy_config.py` | `deployConfig.ts` files (depending on the language chosen for the template), that perform the deployment of the contract. Additionally you can define custom commands to run (similar to `npm` scripts), see definitions under `[project]` section in `.algokit.toml`.",
+      "line": 1
     },
     {
       "file": "smart_contracts/hello_world/deploy_config.py",
-      "description": "The default deployment scripts invoke a sample method on the starter contract that demonstrates how to interact with your deployed Algorand on-chain applications using the [`AlgoKit Typed Clients`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) feature.",
+      "description": "The default deployment scripts invoke a sample method on the starter contract that demonstrates how to interact with your deployed Algorand on-chain applications using the [`AlgoKit Typed Clients`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) feature. The invocation if deploy is aliased in `.algokit.toml` file, allowing simple deployments via `algokit project deploy` command.",
       "line": 32
     },
     {
@@ -32,14 +32,9 @@
       "description": "Environment files are a crucial mechanism that allows you to set up the [`algokit deploy`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/deploy.md) feature to simplify deploying your contracts in CI/CD environments (please note we still recommend careful evaluation when it comes to deployment to MainNet). Clone the file and remove the `.template` suffix to apply the changes to deployment scripts and launch configurations. The network prefix `localnet|testnet|mainnet` is primarily optimized for `algokit deploy`. The order of loading the variables is `.env.{network}` < `.env`.",
       "line": 2
     },
-    {
-      "file": ".algokit.toml",
-      "description": "This is the configuration file used by AlgoKit to determine version requirements, `algokit deploy` settings, and references to custom generators.",
-      "line": 5
-    },
     {
       "file": ".vscode/launch.json",
-      "description": "Refer to the pre-bundled Visual Studio launch configurations, offering various options on how to execute the build and deployment of your smart contracts.",
+      "description": "Refer to the pre-bundled Visual Studio launch configurations, offering various options on how to execute the build and deployment of your smart contracts. Alternatively execute `algokit project run` to see list of available custom commands.",
       "line": 5
     },
     {

examples/generators/production_python_smart_contract_python/README.md

@@ -9,19 +9,25 @@ This project has been generated using AlgoKit. See below for default getting sta
 - [Python 3.12](https://www.python.org/downloads/) or later
 - [Docker](https://www.docker.com/) (only required for LocalNet)
 
+> For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension.
+
 ### Initial setup
 
 1. Clone this repository locally
 2. Install pre-requisites:
    - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine.
-   - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is `1.7.3`. Ensure you can execute `algokit --version` and get `1.7.1` or later.
+   - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later.
    - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will:
      - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+
      - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies
      - Copy `.env.template` to `.env`
    - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you.
+   - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`).
 3. Open the project and start debugging / developing via:
-   - VS Code
+   - Terminal
+     1. Run `algokit project run build` to build all contracts in the project
+     2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network.
+   - VS Code (Launch Configurations)
      1. Open the repository root in VS Code
      2. Install recommended extensions
      3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging.
@@ -34,10 +40,6 @@ This project has been generated using AlgoKit. See below for default getting sta
      1. Open the repository root in the IDE
      2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment.
      3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task).
-   - Other
-     1. Open the repository root in your text editor of choice
-     2. In a terminal run `poetry shell`
-     3. Run `python -m smart_contracts` through your debugger of choice
 
 ### Subsequently
 
@@ -50,6 +52,10 @@ This project uses [GitHub Actions](https://docs.github.com/en/actions/learn-gith
 
 > Please note, if you instantiated the project with --workspace flag in `algokit init` it will automatically attempt to move the contents of the `.github` folder to the root of the workspace.
 
+### AlgoKit Workspaces
+
+To define custom `algokit project run` commands refer to [documentation](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md). This allows orchestration of commands spanning across multiple projects within an algokit workspace based project (monorepo).
+
 ### Debugging Smart Contracts
 
 This project is optimized to work with AlgoKit AVM Debugger extension. To activate it:
@@ -109,6 +115,6 @@ This project makes use of Algorand Python to build Algorand smart contracts. The
 - [mypy](https://mypy-lang.org/): Static type checker.
 - [pytest](https://docs.pytest.org/): Automated testing.
 - [pip-audit](https://pypi.org/project/pip-audit/): Tool for scanning Python environments for packages with known vulnerabilities.
- - [pre-commit](https://pre-commit.com/): A framework for managing and maintaining multi-language pre-commit hooks, to enable pre-commit you need to run `pre-commit install` in the root of the repository. This will install the pre-commit hooks and run them against modified files when committing. If any of the hooks fail, the commit will be aborted. To run the hooks on all files, use `pre-commit run --all-files`.
+- [pre-commit](https://pre-commit.com/): A framework for managing and maintaining multi-language pre-commit hooks, to enable pre-commit you need to run `pre-commit install` in the root of the repository. This will install the pre-commit hooks and run them against modified files when committing. If any of the hooks fail, the commit will be aborted. To run the hooks on all files, use `pre-commit run --all-files`.
 It has also been configured to have a productive dev experience out of the box in [VS Code](https://code.visualstudio.com/), see the [.vscode](./.vscode) folder.
 

examples/generators/production_python_smart_contract_python/smart_contracts/__main__.py

@@ -20,6 +20,7 @@
 logger = logging.getLogger(__name__)
 logger.info("Loading .env")
 load_dotenv()
+load_dotenv(".env.localnet")
 root_path = Path(__file__).parent
 
 

examples/generators/production_python_smart_contract_python/smart_contracts/cool_contract/contract.py

@@ -1,3 +1,4 @@
+# pyright: reportMissingModuleSource=false
 from algopy import ARC4Contract, arc4
 
 

examples/generators/production_python_smart_contract_typescript/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/contract.py.j2

@@ -1,3 +1,4 @@
+# pyright: reportMissingModuleSource=false
 from algopy import ARC4Contract, arc4
 
 

examples/generators/production_python_smart_contract_typescript/.tours/getting-started-with-your-algokit-project.tour

@@ -13,33 +13,23 @@
       "line": 9
     },
     {
-      "file": "smart_contracts/__main__.py",
-      "description": "This is the main entry point for building your smart contracts. The default template includes a starter 'Hello World' contract that is deployed via the `algokit-utils` package (either `ts` or `py`, depending on your choice). To create a new smart contract, you can use the [`algokit generate`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md) command and invoke a pre-bundled generator template by running `algokit generate smart-contract`. This action will create a new folder in the `smart_contracts` directory, named after your project. Each folder contains a `contract.py` file, which is the entry point for your contract implementation, and `deploy_config.py` | `deployConfig.ts` files (depending on the language chosen for the template), that perform the deployment of the contract.",
-      "line": 26
+      "file": ".algokit.toml",
+      "description": "This is the main configuration file used by algokit-cli to manage the project. The default template includes a starter 'Hello World' contract that is deployed via the `algokit-utils` package (either `ts` or `py`, depending on your choice). To create a new smart contract, you can use the [`algokit generate`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md) command and invoke a pre-bundled generator template by running `algokit generate smart-contract` (see how it is defined in the `.algokit.toml`, you can create your own generators if needed). This action will create a new folder in the `smart_contracts` directory, named after your project. Each folder contains a `contract.py` file, which is the entry point for your contract implementation, and `deploy_config.py` | `deployConfig.ts` files (depending on the language chosen for the template), that perform the deployment of the contract. Additionally you can define custom commands to run (similar to `npm` scripts), see definitions under `[project]` section in `.algokit.toml`.",
+      "line": 1
     },
     {
       "file": "smart_contracts/hello_world/deploy-config.ts",
-      "description": "The default deployment scripts invoke a sample method on the starter contract that demonstrates how to interact with your deployed Algorand on-chain applications using the [`AlgoKit Typed Clients`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) feature.",
+      "description": "The default deployment scripts invoke a sample method on the starter contract that demonstrates how to interact with your deployed Algorand on-chain applications using the [`AlgoKit Typed Clients`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) feature. The invocation if deploy is aliased in `.algokit.toml` file, allowing simple deployments via `algokit project deploy` command.",
       "line": 32
     },
-    {
-      "file": "tests/hello-world.spec.ts",
-      "description": "If you opted to include unit tests, the default tests provided demonstrate an example of mocking, setting up fixtures, and testing smart contract calls on an AlgoKit typed client.",
-      "line": 39
-    },
     {
       "file": ".env.localnet.template",
       "description": "Environment files are a crucial mechanism that allows you to set up the [`algokit deploy`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/deploy.md) feature to simplify deploying your contracts in CI/CD environments (please note we still recommend careful evaluation when it comes to deployment to MainNet). Clone the file and remove the `.template` suffix to apply the changes to deployment scripts and launch configurations. The network prefix `localnet|testnet|mainnet` is primarily optimized for `algokit deploy`. The order of loading the variables is `.env.{network}` < `.env`.",
       "line": 2
     },
-    {
-      "file": ".algokit.toml",
-      "description": "This is the configuration file used by AlgoKit to determine version requirements, `algokit deploy` settings, and references to custom generators.",
-      "line": 5
-    },
     {
       "file": ".vscode/launch.json",
-      "description": "Refer to the pre-bundled Visual Studio launch configurations, offering various options on how to execute the build and deployment of your smart contracts.",
+      "description": "Refer to the pre-bundled Visual Studio launch configurations, offering various options on how to execute the build and deployment of your smart contracts. Alternatively execute `algokit project run` to see list of available custom commands.",
       "line": 5
     },
     {