Scripts
When it comes to scripts, they are essentially classes that handle interactions within the same process as the main application, but can be called via the @sodacore/cli package, which provides a simple to use CLI interface for running scripts.
When I built these, I intended originally to use a command line tool, but then I realised that in a lot of cases, sometimes a script may want to interact with the main application, for example, you may want to trigger the same code that a task would run, or potentially you might want to get resource statistics, etc.
So the current implementation is that a script runs within the same process as the main application, so you can access the current running application.
Enabling scripts
To enable scripts within your platform (by default they are disabled), you need to enable them within your initialisation code, for example:
const app = new Application({
enableCli: true, // This enables the CLI.
hostname: 'localhost', // The hostname to bind the application to.
port: 3001, // The port to bind the application to.
password: 'supersecret', // The password to protect the CLI with.
});Once you add this, the CLI service will be started, and you will be able to connect to it.
Creating a script
To create a script, we simply create a class, and decorate it with the @Script() decorator, for example:
import { type AsScript, Namespace, Scripts, ScriptContext } from '@sodacore/core';
@Namespace('example')
export class ExampleScript implements AsScript<ExampleScript> {
@Script('hello')
public async sayHello(ctx: ScriptContext) {
// Ask for a name.
const name = await ctx.prompts.text({
message: 'What is your name?',
});
ctx.log.info(`Hello, ${name}!`);
// Return something.
return 'Done!';
}
}As you can see the types help with coalescing the response, and the ScriptContext provides a few useful utilities, such as logging, prompts and more.
Running a script
To run a script for the first time there are a few steps we need to follow.
Install the CLI
To run a script, we first suggest installing the CLI package globally, for example:
bun add -g @sodacore/cliOnce you do this, you should be able to access the sodacore command from anywhere.
Add a connection
To add a connection, you can simply follow the CLI prompts, for example:
Once you have done this, your connection will be saved locally.
WARNING
The password you set when creating a connection is not encrypted and stored in a JSON file within the user's home directory: ~/.sodacore/cli.json, this will be a future feature.
Run the script
To run a script, run the CLI again, but instead of adding a connection, you will notice that there is a new option:
Access: <YourName>This option will connect to your running application (of course, make sure your application is running first) and then you will be presented with a list of available commands from the core framework, as well as any plugins installed and any scripts you have created.
You can trigger a script by selecting it, and this will then call your script.
Non-interactive
Sometimes you may want to run a command quickly without having to go through the interactive prompts, this only works for non-interactive scripts, i.e. scripts that do not use any of the prompt features. To do this you can execute:
sodacore exec core:usage:infoThis will use the default connection, if there is no default connection, it will fail, you can pass the --connection="<name>" flag to specify a specific connection to use.
TIP
If you made connections before the CLI supported default connections, <= 0.3.36 then just remove and re-add the connection, you will be given an option to make it the default connection.
Interactive scripts
The scripts are interactive, so this means, the prompts actually create a bidirectional communication between the CLI and the main application, so you can ask for input, and then respond to it, this is actually used by the Discord plugin, which exposes two mains scripts for registering and unregistering slash commands, either globally or to a specific guild, and it uses the prompts to ask for the relevant information.
Available helpers
As of right now the library uses the @clack/prompts package to provide the prompts and clean interface, and you can read up the available prompts here.
The implemented features are:
| Method | Parameters | Description |
|---|---|---|
ctx.log.info | message: string | Log an info message. |
ctx.log.error | message: string | Log an error message. |
ctx.log.success | message: string | Log an success message. |
ctx.log.warning | message: string | Log a warning message. |
ctx.log.message | message: string | Log a message. |
ctx.log.warn | message: string | Log a warning message. |
ctx.log.step | message: string | Log a step message. |
ctx.prompts.text | options: Omit<TextOptions, 'validate'> | Prompt for a text input. |
ctx.prompts.confirm | options: ConfirmOptions | Prompt for a confirm input. |
ctx.prompts.select | options: SelectOptions<T> | Prompt for a select input. |
ctx.prompts.multiselect | options: MultiSelectOptions<T> | Prompt for a multi-select input. |
ctx.prompts.createGroup | void | Create a group of prompts using a class return you can add to. |
ctx.prompts.sendRequest | commands: IScriptPromptItem | A way to access the prompts manually without the wrapper. |
You can see an example of this here.
