feat: algokit debugger support

pyproject.toml

@@ -1,19 +1,19 @@
 [tool.poetry]
-name = "copier-testing-template"
+name = "template_content"
 version = "0.1.0"
 description = ""
 authors = ["MakerX <[email protected]>"]
 readme = "README.md"
 
 [tool.poetry.dependencies]
 python = "^3.10"
-beaker-pyteal = "^1.0.0"
-algokit-utils = "^1.3"
+beaker-pyteal = "^1.1.1"
+algokit-utils = "^2.2.0"
 python-dotenv = "^1.0.0"
 
 [tool.poetry.group.dev.dependencies]
 ruff = "^0.1.6"
-black = {extras = ["d"], version = "^22.10.0"}
+black = { extras = ["d"], version = "^22.10.0" }
 flake8 = "^6.0.0"
 pytest = "^7.2.2"
 mypy = "^1.1.1"
@@ -26,36 +26,49 @@ requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
 [tool.ruff]
-select = ["E", "F", "ANN", "UP", "N", "C4", "B", "A", "YTT", "W", "FBT", "Q", "RUF", "I"]
+select = [
+  "E",
+  "F",
+  "ANN",
+  "UP",
+  "N",
+  "C4",
+  "B",
+  "A",
+  "YTT",
+  "W",
+  "FBT",
+  "Q",
+  "RUF",
+  "I",
+]
 extend-exclude = [
   "tests_generated/*", # Ignoring generated tests, ruff specific errors are to be caught by pytest
   "template_content",
   ".git",
   ".mypy_cache",
   ".ruff_cache",
-  ]
+]
 ignore = [
   "ANN101", # no type for self
   "ANN102", # no type for cls
   "RET505", # allow else after return
   "SIM108", # allow if-else in place of ternary
-  "E111", # indentation is not a multiple of four
-  "E117", # over-indented
+  "E111",   # indentation is not a multiple of four
+  "E117",   # over-indented
   "ISC001", # single line implicit string concatenation
   "ISC002", # multi line implicit string concatenation
-  "Q000", # bad quotes inline string
-  "Q001", # bad quotes multiline string
-  "Q002", # bad quotes docstring
-  "Q003", # avoidable escaped quotes
-  "W191", # indentation contains tabs
+  "Q000",   # bad quotes inline string
+  "Q001",   # bad quotes multiline string
+  "Q002",   # bad quotes docstring
+  "Q003",   # avoidable escaped quotes
+  "W191",   # indentation contains tabs
 ]
 unfixable = ["B", "RUF"]
 
 [tool.pytest.ini_options]
 pythonpath = ["tests"]
-testpaths = [
-    "tests",
-]
+testpaths = ["tests"]
 
 [tool.mypy]
 python_version = "3.10"

template_content/README.md.jinja

@@ -4,6 +4,8 @@ This project has been generated using AlgoKit. See below for default getting sta
 
 # Setup
 
+For an interactive guided walkthrough of the project install [CodeTour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) in VS Code and run the `Getting Started with Your AlgoKit Project` tour in the `CodeTour` in Explorer panel in your VSCode instance.
+
 ### Initial setup
 
 1. Clone this repository locally
@@ -49,6 +51,19 @@ This project has been generated using AlgoKit. See below for default getting sta
 
 This project uses [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) to define CI/CD workflows, which are located in the [`.github/workflows`](./.github/workflows) folder.
 
+### Debugging Smart Contracts
+
+This project is optimized to work with AlgoKit AVM Debugger extension. To activate it:
+{%- if deployment_language == 'python' %}
+Refer to the commented header in the `__main__.py` file in the `smart_contracts` folder.
+{%- elif deployment_language == 'typescript' %}
+Refer to the commented header in the `index.ts` file in the `smart_contracts` folder.
+{%- endif %}
+
+If you have opted in to include VSCode launch configurations in your project, you can also use the `Debug TEAL via AlgoKit AVM Debugger` launch configuration to interactively select an available trace file and launch the debug session for your smart contract.
+
+For information on using and setting up the `AlgoKit AVM Debugger` VSCode extension refer [here](https://github.com/algorandfoundation/algokit-avm-vscode-debugger). To install the extension from the VSCode Marketplace, use the following link: [AlgoKit AVM Debugger extension](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger).
+
 #### Setting up GitHub for CI/CD workflow and TestNet deployment
 
   1. Every time you have a change to your smart contract, and when you first initialize the project you need to [build the contract](#initial-setup) and then commit the `smart_contracts/artifacts` folder so the [output stability](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/articles/output_stability.md) tests pass

template_content/pyproject.toml.jinja

@@ -8,7 +8,7 @@ readme = "README.md"
 [tool.poetry.dependencies]
 python = "^3.10"
 beaker-pyteal = "^1.1.1"
-algokit-utils = "^2.0.1"
+algokit-utils = "^2.2.0"
 python-dotenv = "^1.0.0"
 
 [tool.poetry.group.dev.dependencies]

template_content/smart_contracts/__main__.py.jinja

@@ -5,13 +5,15 @@ from pathlib import Path
 from dotenv import load_dotenv
 
 from smart_contracts.config import contracts
-{% if deployment_language == 'python' -%}
 from smart_contracts.helpers.build import build
+{% if deployment_language == 'python' -%}
 from smart_contracts.helpers.deploy import deploy
-{%- elif deployment_language == 'typescript' -%}
-from smart_contracts.helpers.build import build
-{%- endif %}
 
+# # Uncomment the following lines to enable auto generation of AVM Debugger compliant sourceMap and simulation trace file.
+# # Learn more about using AlgoKit AVM Debugger to debug your TEAL source codes and inspect various kinds of Algorand transactions in atomic groups -> https://github.com/algorandfoundation/algokit-avm-vscode-debugger
+# from algokit_utils.config import config
+# config.configure(debug=True, trace_all=True)
+{%- endif %}
 logging.basicConfig(
     level=logging.DEBUG, format="%(asctime)s %(levelname)-10s: %(message)s"
 )

template_content/smart_contracts/{% if deployment_language == 'typescript' %}index.ts{% endif %}.jinja

@@ -3,8 +3,13 @@ import * as path from 'path'
 import { consoleLogger } from '@algorandfoundation/algokit-utils/types/logging'
 import * as algokit from '@algorandfoundation/algokit-utils'
 
+// Uncomment the debug and traceAll options to enable auto generation of AVM Debugger compliant sourceMap and simulation trace file.
+// Learn more about using AlgoKit AVM Debugger to debug your TEAL source codes and inspect various kinds of Algorand transactions in atomic groups -> https://github.com/algorandfoundation/algokit-avm-vscode-Debugger
+
 algokit.Config.configure({
   logger: consoleLogger,
+  //  debug: true,
+  //  traceAll: true,
 })
 
 // base directory

template_content/{% if deployment_language == 'typescript' %}package.json{% endif %}.jinja

@@ -12,7 +12,7 @@
     "node": ">=18.0"
   },
   "dependencies": {
-    "@algorandfoundation/algokit-utils": "^3.0.0",
+    "@algorandfoundation/algokit-utils": "^5.1.0",
     "algosdk": "^2.5.0"
   },
   "devDependencies": {

template_content/{% if ide_vscode %}.tours{% endif %}/getting-started-with-your-algokit-project.tour.jinja

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://aka.ms/codetour-schema",
+  "title": "Getting Started with Your AlgoKit Project",
+  "steps": [
+    {
+      "file": "README.md",
+      "description": "Welcome to your brand new AlgoKit template-based project. In this tour, we will guide you through the main features and capabilities included in the template.",
+      "line": 3
+    },
+    {
+      "file": "README.md",
+      "description": "Start by ensuring you have followed the setup of pre-requisites.",
+      "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": 25
+    },
+    {
+      "file": "smart_contracts/hello_world/{% if deployment_language == 'typescript' %}deploy-config.ts{% else %}deploy_config.py{% endif %}",
+      "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.",
+      "line": 32
+    },
+    {
+      "file": "tests/hello_world_test.py",
+      "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 application client.",
+      "line": 21
+    },
+    {
+      "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.",
+      "line": 5
+    },
+    {
+      "file": ".vscode/extensions.json",
+      "description": "We highly recommend installing the recommended extensions to get the most out of this template starter project in your VSCode IDE.",
+      "line": 3
+    },
+    {
+      "file": "smart_contracts/{% if deployment_language == 'python' %}__main__.py{% else %}index.ts{% endif %}",
+      "description": "Uncomment the following lines to enable complementary utilities that will generate artifacts required for the [AlgoKit AVM Debugger](https://github.com/algorandfoundation/algokit-avm-vscode-debugger) VSCode plugin available on the [VSCode Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger). A new folder will be automatically created in the `.algokit` directory with source maps of all TEAL contracts in this workspace, as well as traces that will appear in a folder at the root of the workspace. You can then use the traces as entry points to trigger the debug extension. Make sure to have the `.algokit.toml` file available at the root of the workspace.",
+      "line": 13
+    }
+  ]
+}

template_content/{% if ide_vscode %}.vscode{% endif %}/extensions.json.jinja

@@ -16,6 +16,8 @@
     "esbenp.prettier-vscode",
     {% endif -%}
     "tamasfe.even-better-toml",
-    "editorconfig.editorconfig"
+    "editorconfig.editorconfig",
+    "vsls-contrib.codetour",
+    "algorandfoundation.algokit-avm-vscode-debugger"
   ]
 }

template_content/{% if ide_vscode %}.vscode{% endif %}/launch.json.jinja

@@ -52,6 +52,13 @@
       "module": "smart_contracts",
       "args": ["build"],
       "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "avm",
+      "request": "launch",
+      "name": "Debug TEAL via AlgoKit AVM Debugger",
+      "simulateTraceFile": "${workspaceFolder}/${command:PickSimulateTraceFile}",
+      "stopOnEntry": true
     }
   ]
 }

tests_generated/test_default_parameters/.tours/getting-started-with-your-algokit-project.tour

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://aka.ms/codetour-schema",
+  "title": "Getting Started with Your AlgoKit Project",
+  "steps": [
+    {
+      "file": "README.md",
+      "description": "Welcome to your brand new AlgoKit template-based project. In this tour, we will guide you through the main features and capabilities included in the template.",
+      "line": 3
+    },
+    {
+      "file": "README.md",
+      "description": "Start by ensuring you have followed the setup of pre-requisites.",
+      "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": 25
+    },
+    {
+      "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.",
+      "line": 32
+    },
+    {
+      "file": "tests/hello_world_test.py",
+      "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 application client.",
+      "line": 21
+    },
+    {
+      "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.",
+      "line": 5
+    },
+    {
+      "file": ".vscode/extensions.json",
+      "description": "We highly recommend installing the recommended extensions to get the most out of this template starter project in your VSCode IDE.",
+      "line": 3
+    },
+    {
+      "file": "smart_contracts/__main__.py",
+      "description": "Uncomment the following lines to enable complementary utilities that will generate artifacts required for the [AlgoKit AVM Debugger](https://github.com/algorandfoundation/algokit-avm-vscode-debugger) VSCode plugin available on the [VSCode Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger). A new folder will be automatically created in the `.algokit` directory with source maps of all TEAL contracts in this workspace, as well as traces that will appear in a folder at the root of the workspace. You can then use the traces as entry points to trigger the debug extension. Make sure to have the `.algokit.toml` file available at the root of the workspace.",
+      "line": 13
+    }
+  ]
+}

tests_generated/test_default_parameters/.vscode/extensions.json

@@ -3,6 +3,8 @@
     "ms-python.python",
     "ms-python.black-formatter",
     "tamasfe.even-better-toml",
-    "editorconfig.editorconfig"
+    "editorconfig.editorconfig",
+    "vsls-contrib.codetour",
+    "algorandfoundation.algokit-avm-vscode-debugger"
   ]
 }

tests_generated/test_default_parameters/.vscode/launch.json

@@ -26,6 +26,13 @@
       "module": "smart_contracts",
       "args": ["build"],
       "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "avm",
+      "request": "launch",
+      "name": "Debug TEAL via AlgoKit AVM Debugger",
+      "simulateTraceFile": "${workspaceFolder}/${command:PickSimulateTraceFile}",
+      "stopOnEntry": true
     }
   ]
 }

tests_generated/test_default_parameters/README.md

@@ -4,6 +4,8 @@ This project has been generated using AlgoKit. See below for default getting sta
 
 # Setup
 
+For an interactive guided walkthrough of the project install [CodeTour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) in VS Code and run the `Getting Started with Your AlgoKit Project` tour in the `CodeTour` in Explorer panel in your VSCode instance.
+
 ### Initial setup
 
 1. Clone this repository locally

tests_generated/test_default_parameters/pyproject.toml

@@ -8,7 +8,7 @@ readme = "README.md"
 [tool.poetry.dependencies]
 python = "^3.10"
 beaker-pyteal = "^1.1.1"
-algokit-utils = "^2.0.1"
+algokit-utils = "^2.2.0"
 python-dotenv = "^1.0.0"
 
 [tool.poetry.group.dev.dependencies]

tests_generated/test_default_parameters/smart_contracts/__main__.py

@@ -8,6 +8,10 @@
 from smart_contracts.helpers.build import build
 from smart_contracts.helpers.deploy import deploy
 
+# # Uncomment the following lines to enable auto generation of AVM Debugger compliant sourceMap and simulation trace file.
+# # Learn more about using AlgoKit AVM Debugger to debug your TEAL source codes and inspect various kinds of Algorand transactions in atomic groups -> https://github.com/algorandfoundation/algokit-avm-vscode-debugger
+# from algokit_utils.config import config
+# config.configure(debug=True, trace_all=True)
 logging.basicConfig(
     level=logging.DEBUG, format="%(asctime)s %(levelname)-10s: %(message)s"
 )