ADITO Standalone Tools

This VS Code extension takes care of the tools that are needed to deploy ADITO applications, so you never have to download or update them by hand.

Once your workspace contains an ADITO project (a .aditoprj folder), the extension activates, downloads the standalone tools from the tools webservice, and stores them in the global storage of VS Code. From then on, it keeps the tools up-to-date automatically: whenever the webservice offers a newer version, the tool is refreshed on the next download, and whenever the settings change, the tools are downloaded right away without you having to run anything.

Features

• Automatic downloads: the configured standalone tools are downloaded as soon as the extension is activated and whenever their settings change.
• Automatic updates: a tool is only downloaded again when the version on the webservice really differs from the stored one (compared by checksum), so unchanged tools are not transferred needlessly.
• Safe downloads: a download is written to a temporary location first and only replaces the old tool after it finished successfully, so an interrupted download never leaves a corrupt tool behind.
• Platform-aware: Windows, Linux, and JRE-based tools are supported. The right variant is detected from your operating system.
• Transparent: every download, update, and error is written to the ADITO Standalone Tools output channel, including the webservice URL, the execution mode, the file size, and the duration of each download. The Show standalone tool information command summarizes everything at a glance: where the tools are stored, when they were last refreshed, and which version each tool has.
• Forgiving: if one tool cannot be downloaded (for example, because the webservice has no information about it), the remaining downloads continue, and a notification tells you which tools failed so you can check the output channel for details.
• Status bar button: the deployment starts with one click from the status bar (Start Deployment), running the same flow as the command palette entry: the inputs are asked, the project is prepared, and the dry run result is shown in the tree view.
• Deploy dry run tree view: the dry run result is shown per database connection in a tree view (Deployment Overview), grouped into available and not available systems. The changed files are deployed selectively, the dry run can be rerun at any time, and the connection availability can be revalidated from the view title bar. Deploying to a not available system asks for a confirmation first (Deploy anyway?). After a deploy the connection stays in the view with its entries reset, so you see that it has no data left to deploy.
• Automatic DB connection detection: the database connections are read from the liquibase properties files of the project (liquibase.configurationPath, by default data/liquibase) and kept up to date by a file watcher: adding, changing, or removing a *.liquibase.properties file updates the suggested connections with their checked availability, and changing the configuration path setting switches to the new folder (the connections of the previous folder are dropped). The availability of every connection is checked with a canary dry run of the deploy tool.

Generated dist folder

The transpile writes its complete output (thousands of files) into the dist folder of your project. Because this folder is purely generated, the extension contributes default workspace settings as soon as it is installed, so VS Code does not watch and index every generated file:

• files.watcherExclude and search.exclude contain **/dist/** and **/dist by default.

Without these defaults, a full transpile can flood the file watcher and the search index of VS Code to a degree where the extension host stops reacting (for example, a running transpile task never reports its completion).

Notes:

• The defaults apply to every workspace, not only to ADITO projects. Generated dist folders are excluded from watching and search by design, which is the recommended setup for them anyway.
• Your own settings still win: if you already configured entries for these settings, they are kept, and you can re-include the folder for a single workspace with "**/dist/**": false.
• The defaults take effect after reloading the window.

Commands

The commands are available in the command palette (Ctrl+Shift+P) under the category ADITO Standalone Tools:

Deploy selected files and Collect deployable files again are tree view actions only (inline buttons and context menu entries of the group elements). They are hidden from the command palette because they need the clicked group as their input.

Tasks

The extension contributes tasks under the ADITO Standalone Tools task source: ADITO: Transpile (Full), ADITO: Convert (AOD), ADITO: Convert (YAML), and ADITO: Collect Deployable Files (Dry Run). Run them from the command palette (Tasks: Run Task) or bind them in tasks.json.

How it works

1. You open a workspace that contains a .aditoprj folder.
2. The extension reads its settings and asks the tools webservice which versions of the configured tools are available.
3. For every tool whose offered version differs from the stored one (or that is not stored yet), the tool binary is downloaded and stored in the global storage of VS Code.
4. The extension logs the result to the ADITO Standalone Tools output channel and repeats steps 2 and 3 whenever the settings change or you run the Download all standalone tools command.

Extension API for other extensions

Other extensions can call the standalone tools and the project model information of the transpile daemon through a typed API (AditoStandaloneToolsApi): transpile and convert runs, deploy with availability check and dry run, and the daemon endpoints (daemonStart, onDaemonReady, resolveModelsViaDaemon, and more). The contract is published as the types-only npm package @aditosoftware/standalone-tools-api; see docs/EXTENSION_API.md in the extension repository for how to consume it, what is required, and code examples.

Troubleshooting

If a tool is not downloaded or behaves unexpectedly, there are two places to look:

The output channel

Every download, update, and error is written to the ADITO Standalone Tools output channel. Open it via View → Output (or Ctrl+Shift+U) and select ADITO Standalone Tools from the dropdown on the right. You will find there:

• which tools were downloaded and which version each tool has,
• when the tools were last refreshed,
• why a tool was not downloaded (for example, when the webservice has no information about it or the webservice is unreachable).

Alternatively, run the Show standalone tool information command (Ctrl+Shift+P). It opens the output channel and shows the overview directly.

The global storage

The downloaded tools are stored in the global storage of VS Code, under adito.adito-standalone-tools:

Each tool lies there as a single file (transpile.exe on Windows, otherwise under its plain name). The overview of the Show standalone tool information command shows the exact location on your machine as well.

Tip: you can open the folder directly from VS Code by running the command Open Extensions Folder (Ctrl+Shift+P). The global storage is a sibling of the extensions folder.

If the output channel shows a download error and the tool is missing in the global storage, the download failed. Check the error message in the output channel (for example, an unreachable webservice or a checksum mismatch) and run Download all standalone tools again once the problem is fixed.

The transpile task stays at "Rendering eligible files into ..."

If a transpile task seems to hang forever with its last visible output line looking like this:

[INFO ] Rendering eligible files into c:\projects\your-project\dist...

the transpile itself is in most cases already finished: check the dist folder of your project (file dates no longer change), and you will find the output completely written there. What hangs is the reporting of the task, not the transpile.

The cause is the flood of file events that the freshly written dist folder triggers in VS Code (watcher and search indexing). When the extension host is busy processing this flood, it never receives the exit of the transpile process, so the task never reports its completion. The extension therefore excludes dist from the watcher and the search by default (see Generated dist folder).

If you still run into it:

1. Verify that the dist folder is really complete (its files stopped changing), so the transpile result is usable even though the task is still shown as running.
2. Check your workspace or user settings for overrides of files.watcherExclude or search.exclude that re-include dist (for example "**/dist/**": false) and remove them.
3. Restart VS Code so that the defaults take effect.