feat: orchestration support (#61)

* feat: orchestration support

* chore: swapping to final prerelease branch

* chore: fix up the ts deployer build command

* chore: fixing race condition in tests (xdist); more robust tests

* chore: minor tweaks

* chore: minor tweaks

* chore: regen artifacts

* chore: bumping min version

BREAKING CHANGE: Support for algokit-cli v2.0

---------

Co-authored-by: Neil Campbell <neil.campbell@makerx.com.au>

.github/workflows/check-python.yaml

@@ -14,7 +14,10 @@ jobs:
         run: pipx install poetry
 
       - name: Install algokit
-        run: pipx install algokit 
+        run: pipx install algokit
+
+      - name: Run algokit localnet
+        run: algokit localnet start
 
       - name: Set up Python 3.12
         uses: actions/setup-python@v5

.gitignore

@@ -176,4 +176,7 @@ examples/**/poetry.lock
 
 # playground folder for previewing templates
 .playground/*
-!.playground/.gitkeep
+
+# Misc
+examples/**/smart_contracts/artifacts
+examples/**/.algokit/sources 

.vscode/tasks.json

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

CONTRIBUTING.md

@@ -5,23 +5,38 @@ This repository is a template for creating new AlgoKit projects. It includes a b
 ## Pre-requisites
 
 `poetry install` - Install the dependencies for the project.
+`pipx install algokit` - Ensure cli is installed.
 
 ## Testing
 
+Ensure localnet is running by executing `algokit localnet reset`.
+
 ```bash
-poetry run pytest
+poetry run pytest -n auto
 ```
 
 This will regenerate the tests for default `starter` and `production` presets as well as default tests for `generators` available on the template.
 
 ## Development
 
+### Manual
+
 ```bash
-poetry run copier copy . .playground/{some_dummy_folder_name} --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`.
 
+### 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
+
+To cleanup the .playground folder run dedicated cleanup task.
+
 ## Contributing
 
 ### Commits

copier.yaml

@@ -1,32 +1,39 @@
 _subdirectory: template_content
 _templates_suffix: ".jinja"
 
+use_workspace:
+  type: bool
+  when: false # never prompted to user explicitly, instead expect cli to auto fill (supported cli versions > v1.13.x)
+  help: Automatically filled by AlgoKit CLI (>1.13.x) - passes the --workspace/--no-workspace flag's value, can be used to reason whether this template is currently being instantiated as part of a workspace or not.
+  default: no
+
 # questions
-# project_name should never get prompted, AlgoKit should always pass it by convention
 project_name:
   type: str
   help: Name for this project.
   placeholder: "algorand-app"
 
-contract_name:
-  type: str
-  help: Name of the default smart contract app.
-  placeholder: "hello_world"
-  default: "hello_world"
-  validator: >-
-    {% if not (contract_name | regex_search('^[a-z]+(?:_[a-z]+)*$')) %}
-    contract_name must be formatted in snake case.
-    {% endif %}
-
 author_name:
   type: str
   help: Package author name
   placeholder: "Your Name"
+  default: "Your Name"
 
 author_email:
   type: str
   help: Package author email
   placeholder: "your@email.tld"
+  default: "your@email.tld"
+
+contract_name:
+  type: str
+  help: Name of the default smart contract app.
+  placeholder: "hello_world"
+  default: "hello_world"
+  validator: >-
+    {% if not (contract_name | regex_search('^[a-z]+(?:_[a-z]+)*$')) %}
+    contract_name must be formatted in snake case.
+    {% endif %}
 
 preset_name:
   type: str

examples/generators/production_beaker_smart_contract_python/.algokit.toml

@@ -1,20 +1,49 @@
 [algokit]
-min_version = "v1.10.0"
+min_version = "v2.0.0"
 
-[deploy]
+[generate.smart_contract]
+description = "Adds new smart contract to existing project"
+path = ".algokit/generators/create_contract"
+
+[project]
+type = 'contract'
+name = 'production_beaker_smart_contract_python'
+artifacts = 'smart_contracts/artifacts'
+
+[project.deploy]
 command = "poetry run python -m smart_contracts deploy"
 environment_secrets = [
   "DEPLOYER_MNEMONIC",
   "DISPENSER_MNEMONIC",
 ]
 
-[deploy.localnet]
+[project.deploy.localnet]
 environment_secrets = []
 
-[generate.smart_contract]
-description = "Adds new smart contract to existing project"
-path = ".algokit/generators/create_contract"
+[project.run]
+# Commands intented for use locally and in CI
+build = { commands = [
+  'poetry run python -m smart_contracts build',
+], description = 'Build all smart contracts in the project' }
+test = { commands = [
+  'poetry run pytest',
+], description = 'Run smart contract tests' }
+audit = { commands = [
+  'poetry export --without=dev -o requirements.txt',
+  'poetry run pip-audit -r requirements.txt',
+], description = 'Audit with pip-audit' }
+lint = { commands = [
+  'poetry run black --check .',
+  'poetry run ruff .',
+  'poetry run mypy',
+], description = 'Perform linting' }
+audit-teal = { commands = [
+  # 🚨 IMPORTANT 🚨: For strict TEAL validation, remove --exclude statements. The default starter contract is not for production. Ensure thorough testing and adherence to best practices in smart contract development. This is not a replacement for a professional audit.
+  'algokit task analyze smart_contracts/artifacts --recursive --force --exclude rekey-to --exclude is-updatable --exclude missing-fee-check --exclude is-deletable --exclude can-close-asset --exclude can-close-account --exclude unprotected-deletable --exclude unprotected-updatable',
+], description = 'Audit TEAL files' }
 
-[project]
-type = 'contract'
-name = 'production_beaker_smart_contract_python'
+# Commands indented for CI only, prefixed with `ci-` by convention
+ci-teal-diff = { commands = [
+  'git add -N ./smart_contracts/artifacts',
+  'git diff --exit-code --minimal ./smart_contracts/artifacts',
+], description = 'Check TEAL files for differences' }

examples/generators/production_beaker_smart_contract_python/.algokit/generators/create_contract/smart_contracts/{{ contract_name }}/deploy_config.py.j2

@@ -38,9 +38,11 @@ def deploy(
             if is_mainnet
             else algokit_utils.OnSchemaBreak.ReplaceApp
         ),
-        on_update=algokit_utils.OnUpdate.AppendApp
-        if is_mainnet
-        else algokit_utils.OnUpdate.UpdateApp,
+        on_update=(
+            algokit_utils.OnUpdate.AppendApp
+            if is_mainnet
+            else algokit_utils.OnUpdate.UpdateApp
+        ),
         allow_delete=not is_mainnet,
         allow_update=not is_mainnet,
     )