From 7600b73acf11c5493070f94355735dc5bd3a301d Mon Sep 17 00:00:00 2001 From: Altynbek Orumbayev Date: Wed, 30 Oct 2024 22:33:08 +0100 Subject: [PATCH 1/3] fix: simplifying logic for custom commands; fixing edge cases when empty picker is presented --- src/activateAvmDebug.ts | 63 ++++++++++++++++++++--------------------- src/utils.ts | 6 ++++ 2 files changed, 36 insertions(+), 33 deletions(-) diff --git a/src/activateAvmDebug.ts b/src/activateAvmDebug.ts index 87820e7..2a438db 100644 --- a/src/activateAvmDebug.ts +++ b/src/activateAvmDebug.ts @@ -27,20 +27,16 @@ export function activateAvmDebug(context: vscode.ExtensionContext, factory: vsco context.subscriptions.push( vscode.commands.registerCommand('extension.avmDebugger.clearAvmDebugRegistry', async () => { - const config = vscode.workspace.getConfiguration('avmDebugger') - let sourcesFilePath = config.get('programSourcesDescriptionFile') - - if (!sourcesFilePath) { - const workspaceFolder = await getWorkspaceFolder() - if (!workspaceFolder) return + const workspaceFolder = await getWorkspaceFolder() + if (!workspaceFolder) return - sourcesFilePath = await findAndPickFile(workspaceFolder, SOURCES_FILE_PATTERN, { - title: 'Select program sources description file to clear', - placeHolder: 'Please select a file to clear', - noFilesErrorMessage: `No program sources description files (with name ${SOURCES_FILE_NAME}) were found in the workspace.`, - }) - if (!sourcesFilePath) return - } + const sourcesFilePath = await findAndPickFile(workspaceFolder, SOURCES_FILE_PATTERN, { + title: 'Select program sources description file to clear', + placeHolder: 'Please select a file to clear', + noFilesErrorMessage: `No program sources description files (with name ${SOURCES_FILE_NAME}) were found in the workspace.`, + exitIfNoFiles: true, + }) + if (!sourcesFilePath) return const confirmation = await vscode.window.showWarningMessage( `Are you sure you want to clear the content of ${sourcesFilePath}?`, @@ -49,34 +45,35 @@ export function activateAvmDebug(context: vscode.ExtensionContext, factory: vsco ) if (confirmation === 'Yes') { - await workspaceFileAccessor.writeFile(sourcesFilePath, new TextEncoder().encode(JSON.stringify({}, null, 2))) - vscode.window.showInformationMessage('AVM Debug Registry cleared.') + const fileUri = vscode.Uri.joinPath(workspaceFolder.uri, sourcesFilePath) + await vscode.workspace.fs.delete(fileUri) + await workspaceFileAccessor.writeFile(fileUri.fsPath, new TextEncoder().encode(JSON.stringify({}, null, 2))) + vscode.window.showInformationMessage( + 'AVM Debug Registry file cleared. You can now restart the debugger to pick a new sourcemap to use.', + ) } }), ) context.subscriptions.push( vscode.commands.registerCommand('extension.avmDebugger.editAvmDebugRegistry', async () => { - const config = vscode.workspace.getConfiguration('avmDebugger') - const currentFile = config.get('programSourcesDescriptionFile') - - if (currentFile) { - const document = await vscode.workspace.openTextDocument(currentFile) - await vscode.window.showTextDocument(document) - } else { - const workspaceFolder = await getWorkspaceFolder() - if (!workspaceFolder) return + const workspaceFolder = await getWorkspaceFolder() + if (!workspaceFolder) { + vscode.window.showWarningMessage('No workspace folder found.') + return + } - const sourcesFilePath = await findAndPickFile(workspaceFolder, SOURCES_FILE_PATTERN, { - title: 'Program sources description file', - placeHolder: 'Please select a program sources description file', - noFilesErrorMessage: `No program sources description files (with name ${SOURCES_FILE_NAME}) were found in the workspace.`, - }) - if (!sourcesFilePath) return + const sourcesFilePath = await findAndPickFile(workspaceFolder, SOURCES_FILE_PATTERN, { + title: 'Program sources description file', + placeHolder: 'Please select a program sources description file', + noFilesErrorMessage: `No program sources description files (with name ${SOURCES_FILE_NAME}) were found in the workspace.`, + exitIfNoFiles: true, + }) + if (!sourcesFilePath) return - const document = await vscode.workspace.openTextDocument(sourcesFilePath) - await vscode.window.showTextDocument(document) - } + const fileUri = vscode.Uri.joinPath(workspaceFolder.uri, sourcesFilePath) + const document = await vscode.workspace.openTextDocument(fileUri) + await vscode.window.showTextDocument(document) vscode.window.showInformationMessage('AVM Debug Registry opened for editing.') }), diff --git a/src/utils.ts b/src/utils.ts index f45ca5b..f59b2a0 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -116,6 +116,7 @@ export async function findAndPickFile( noFilesErrorMessage: string allowBrowse?: boolean fileType?: string + exitIfNoFiles?: boolean }, ): Promise { const fileUris = await findFilesInWorkspace(workspaceFolder, filePattern) @@ -145,6 +146,11 @@ export async function findAndPickFile( ) } + if (options.exitIfNoFiles && fileUris.length === 0) { + vscode.window.showWarningMessage(options.noFilesErrorMessage) + return undefined + } + const selected = await vscode.window.showQuickPick(quickPickItems, { title: options.title, placeHolder: options.placeHolder, From 3a442582d11d10765bce1ee66dfa8f6b3ada9c0d Mon Sep 17 00:00:00 2001 From: Altynbek Orumbayev Date: Wed, 30 Oct 2024 22:51:39 +0100 Subject: [PATCH 2/3] docs: refreshing documentation; including extra docs for available vscode settings --- README.md | 76 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 59 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 900be17..53428b4 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ --- -The AlgoKit AVM VS Code Debugger extension provides a convenient way to debug any Algorand Smart Contracts written in TEAL. +The AlgoKit AVM VS Code Debugger extension enables step-by-step debugging of Algorand smart contracts on the AVM, whether written in TEAL directly or compiled from [Puya](https://github.com/algorandfoundation/puya). It leverages transaction traces and source maps to provide a seamless debugging experience. For detailed setup instructions, see the [Detailed Usage](#detailed-usage) section. --- @@ -23,7 +23,7 @@ The AlgoKit AVM VS Code Debugger extension provides a convenient way to debug an --- -It is built on top of the official [AVM Debug Adapter](https://github.com/algorand/avm-debugger) provided by [Algorand Technologies](https://www.algorand.com/). Additionally, a set of companion utilities are provided in the [TypeScript](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/debugging.md) and [Python](https://github.com/algorandfoundation/algokit-utils-py/blob/main/docs/source/capabilities/debugging.md) versions of `algokit-utils`, making it easier for developers to set up the required prerequisites and run the debugger. +The core functionality is built on top of the official [AVM Debug Adapter](https://github.com/algorand/avm-debugger) provided by [Algorand Technologies](https://www.algorand.com/). Additionally, a set of companion utilities are provided in the [TypeScript](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/debugging.md) and [Python](https://github.com/algorandfoundation/algokit-utils-py/blob/main/docs/source/capabilities/debugging.md) versions of `algokit-utils`, making it easier for developers to set up the required prerequisites and run the debugger. > To skip straight to the list of features, go to [Features](#features). @@ -46,14 +46,39 @@ Before you can use the AVM Debugger extension, you need to ensure that you have - [Visual Studio Code](https://code.visualstudio.com/download): Version 1.80.0 or higher. You can check your version by going to `Help > About` in VS Code. - [Node.js](https://nodejs.org/en/download/): Version 18.x or higher. The extension is built with Node.js. Check your Node.js version by running `node -v` in your terminal/command prompt. -> The extension is designed to debug TEAL programs running on the Algorand Virtual Machine. It provides a step-by-step debugging experience by utilizing transaction execution traces and compiled source maps of your smart contract. However, it's crucial to understand that debugging a smart contract language like TEAL has its unique aspects compared to general-purpose languages. For a comprehensive guide on how to initiate a debugging session, please refer to the [Usage](#usage) section. +### Quick Start -## Installation +Below is a bare-bones example of how to get started with the AVM Debugger extension in an AlgoKit based project relying on `algokit-utils`. -1. Install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger). -2. Follow the next steps in the [Usage](#usage) section. +1. **Enable debugging in algokit-utils**: -## Usage + ```typescript + // In your main file (TypeScript) + import { config } from 'algokit-utils-ts' + config.configure({ debug: true, traceAll: true }) + ``` + + or + + ```python + # In your main file (Python) + from algokit_utils.config import config + config.configure(debug=True, trace_all=True) + ``` + +2. **Interact with your smart contract**: Perform an application call using `algokit-utils`. + +3. **Start debugging**: + - Open the trace file (ends with `.trace.avm.json`) + - If using an official `algokit-python-template`, execute the `Debug TEAL via AlgoKit AVM Debugger` launch configuration. Otherwise, create a new VSCode launch configuration of type `avm` (which will automatically set recommended defaults). + - The extension can also be invoked via the debug icon in the editor (visible in top right corner when viewing a trace file) or using the `Debug AVM Trace File` command from the Command Palette. + - The debugger will guide you through the process of selecting the correct source files and traces and will initiate the debugging session. + +> **Pro Tip**: Use the `Clear AVM Debug Registry` command if you need to reset your sourcemap selections or if you're experiencing mapping issues. + +To learn more about the features and how to use them, continue reading below. + +## Detailed Usage The AVM Debugger extension automatically detects and operates on the following files: @@ -163,6 +188,33 @@ The extension also offers an interactive picker for simulation trace files. The > Please note the limit for max visible items in the extension picker is 100. If you have more than 100 `sources.avm.json` files in the working directory, consider using the `programSourcesDescriptionFile` property to specify the path to a specific file. +### VSCode Commands and Settings + +The following will become available within IDE after extension is installed. + +#### Commands + +The extension provides the following commands that can be accessed via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P): + +| Command | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| `Debug AVM Trace File` | Initiates a debugging session from an open trace file. Can also be triggered via the debug icon when viewing a trace file | +| `Clear AVM Debug Registry` | Resets the AVM debug registry file (sources.avm.json) - useful when you want to start fresh with sourcemap selections | +| `Edit AVM Debug Registry` | Opens the AVM debug registry file for manual editing | + +#### Settings + +Configure the debugger behavior through VS Code settings: + +| Setting | Description | Default | +| ------------------------------------------ | ------------------------------------------------------------------------------------------ | ----------------------------------- | +| `avmDebugger.debugAdapter.port` | Port number for the debug adapter when running in server mode. Leave empty for inline mode | `null` | +| `avmDebugger.defaultSourcemapRegistryFile` | Custom path to the sources.avm.json registry file | `.algokit/sources/sources.avm.json` | + +> **Tip for Beginners**: Start with the default settings. The inline debug adapter mode (default when `debugAdapter.port` is not set) is perfect for most use cases. + +> **Advanced Usage**: Set `debugAdapter.port` when you need to run the debug adapter as a separate process, which can be useful for development or when debugging the extension itself. + ## Features This document outlines the features supported by the AVM debugger. Screenshots and features are based on the VS Code client. @@ -181,16 +233,6 @@ This document outlines the features supported by the AVM debugger. Screenshots a | Support for Puya sourcemaps | The debugger now supports Puya sourcemaps, allowing debugging of contracts written in Puya. | ![Puya sourcemap](images/puya-sources.png) | | Ability to ignore or select external sourcemaps | Users can browse and select external sourcemap files if they're not found in the workspace. Additionaly providing an option to ignore sourcemaps for specific hashes, which can be reset via the 'Clear AVM Registry' command. | ![Picker v2](images/pickerv2.png) | -### VSCode Commands - -The extension provides the following commands: - -| Name | Command | Description | -| ------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -| Debug AVM Trace File | extension.avmDebugger.debugOpenTraceFile | Opens a trace file for debugging. Also accessible via debug icon visible when a trace file is opened in the editor. | -| Clear AVM Debug Registry | extension.avmDebugger.clearAvmDebugRegistry | Clears the AVM debug registry (contents of sources.avm.json). | -| Edit AVM Debug Registry | extension.avmDebugger.editAvmDebugRegistry | Edits the AVM debug registry (contents of sources.avm.json). | - ## How can I contribute? This is an open source project managed by the Algorand Foundation. See the [contributing page](./CONTRIBUTING.md) to learn about making improvements, including developer setup instructions. From a1f3e085174f26c795645eb372ba8474c87bcf45 Mon Sep 17 00:00:00 2001 From: Al Date: Thu, 31 Oct 2024 10:33:45 +0100 Subject: [PATCH 3/3] chore: apply suggestions from code review Co-authored-by: Neil Campbell --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 53428b4..e2fa218 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ --- -The AlgoKit AVM VS Code Debugger extension enables step-by-step debugging of Algorand smart contracts on the AVM, whether written in TEAL directly or compiled from [Puya](https://github.com/algorandfoundation/puya). It leverages transaction traces and source maps to provide a seamless debugging experience. For detailed setup instructions, see the [Detailed Usage](#detailed-usage) section. +The AlgoKit AVM VS Code Debugger extension enables line-by-line debugging of Algorand smart contracts on the AVM, whether written in TEAL directly or compiled from [Puya](https://github.com/algorandfoundation/puya). It leverages AVM simulate traces and source maps to provide a seamless debugging experience. For detailed setup instructions, see the [Detailed Usage](#detailed-usage) section. --- @@ -23,7 +23,7 @@ The AlgoKit AVM VS Code Debugger extension enables step-by-step debugging of Alg --- -The core functionality is built on top of the official [AVM Debug Adapter](https://github.com/algorand/avm-debugger) provided by [Algorand Technologies](https://www.algorand.com/). Additionally, a set of companion utilities are provided in the [TypeScript](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/debugging.md) and [Python](https://github.com/algorandfoundation/algokit-utils-py/blob/main/docs/source/capabilities/debugging.md) versions of `algokit-utils`, making it easier for developers to set up the required prerequisites and run the debugger. +The core functionality is built on top of the [AVM Debug Adapter](https://github.com/algorand/avm-debugger). Additionally, a set of companion utilities are provided in the [TypeScript](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/debugging.md) and [Python](https://github.com/algorandfoundation/algokit-utils-py/blob/main/docs/source/capabilities/debugging.md) versions of `algokit-utils`, making it easier for developers to set up the required prerequisites and run the debugger. > To skip straight to the list of features, go to [Features](#features). @@ -69,7 +69,7 @@ Below is a bare-bones example of how to get started with the AVM Debugger extens 2. **Interact with your smart contract**: Perform an application call using `algokit-utils`. 3. **Start debugging**: - - Open the trace file (ends with `.trace.avm.json`) + - Open the AVM simulate trace file (ends with `.trace.avm.json`) - If using an official `algokit-python-template`, execute the `Debug TEAL via AlgoKit AVM Debugger` launch configuration. Otherwise, create a new VSCode launch configuration of type `avm` (which will automatically set recommended defaults). - The extension can also be invoked via the debug icon in the editor (visible in top right corner when viewing a trace file) or using the `Debug AVM Trace File` command from the Command Palette. - The debugger will guide you through the process of selecting the correct source files and traces and will initiate the debugging session. @@ -190,7 +190,7 @@ The extension also offers an interactive picker for simulation trace files. The ### VSCode Commands and Settings -The following will become available within IDE after extension is installed. +The following will become available within the IDE after the extension is installed. #### Commands @@ -213,7 +213,7 @@ Configure the debugger behavior through VS Code settings: > **Tip for Beginners**: Start with the default settings. The inline debug adapter mode (default when `debugAdapter.port` is not set) is perfect for most use cases. -> **Advanced Usage**: Set `debugAdapter.port` when you need to run the debug adapter as a separate process, which can be useful for development or when debugging the extension itself. +> **Advanced Usage**: Set `debugAdapter.port` when you need to run the debug adapter as a separate process, which can be useful for development or debugging of the extension itself. ## Features