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/cli

Once 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:info

This 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.