Scripts Module

This file defines the Scripts class, which manages the CLI scripts server in the @sodacore/core library. It discovers script controllers and their commands, starts a TCP server for CLI connections, handles incoming requests, and manages command execution and authentication.

---

Features

• Script Discovery: Scans all registered modules for script controllers and their commands.
• TCP Server: Starts a TCP server (using Bun) to handle CLI script connections.
• Command Routing: Maps incoming commands to their corresponding controller methods.
• Authentication: Ensures only authenticated sockets can execute commands (except internal commands).
• Connection Management: Tracks active connections and handles connection lifecycle events.
• Error Handling: Handles invalid packets, unknown commands, and execution errors gracefully.

---

Usage

import Scripts from './module/scripts';

const scripts = new Scripts(config);
await scripts.init();
await scripts.start();
// ... later
await scripts.stop();

---

API

Properties

• shouldStart: boolean Indicates whether the CLI server should be started.
• server: TCPSocketListener<IScriptSocketData> | undefined The TCP server instance.
• connections: Map<symbol, Socket<IScriptSocketData>> Map of active socket connections.
• commands: Record<string, { module: any, key: string }> Map of available script commands and their handlers.

---

Methods

async init(): Promise<void>

Scans all modules in the Registry for script controllers and their commands. Populates the commands map and determines if the CLI server should be started based on configuration.

async start(): Promise<void>

Starts the CLI scripts TCP server if enabled. Handles connection events (open, close, data, drain, error) and manages socket state.

async stop(): Promise<void>

Stops the CLI scripts TCP server and cleans up resources.

hasScripts(): boolean

Returns whether the CLI server should be started.

getCommands(): string[]

Returns a list of all registered script command names.

private async handle(socket: Socket<IScriptSocketData>, data: string): Promise<void>

Handles incoming data from a socket:

• Parses the packet.
• Validates the command and authentication.
• Executes the corresponding command method with a new ScriptContext.
• Handles and responds to errors or command results.

---

How It Works

1. Initialization:

   • Scans all modules for script controllers and their methods.
   • Registers commands in the commands map using the format namespace:method.

2. Server Startup:

   • Starts a TCP server on the configured port and hostname.
   • Handles new connections, disconnections, incoming data, and errors.

3. Command Handling:

   • Parses incoming packets and routes commands to the appropriate controller method.
   • Ensures only authenticated sockets can execute commands (except internal commands prefixed with _:).
   • Sends responses or error messages back to the client.

---

Notes

• Script controllers and methods must be registered using the appropriate decorators to be discovered.
• The server uses Bun's TCP server API for high-performance networking.
• Error handling is robust, ensuring clients receive meaningful feedback on failures.
• The ScriptContext object is passed to each command method, providing access to logging, session, and prompt helpers.