API: Plugin

Plugin interface for extending Cerebro functionality.

Plugin Interface

interface Plugin {
    name: string;
    description?: string;
    version?: string;
    dependencies?: string[];
    init?: (context: PluginContext) => Promise<void> | void;
    execute?: (toolbox: Toolbox) => Promise<void> | void;
    beforeCommand?: (toolbox: Toolbox) => Promise<void> | void;
    afterCommand?: (toolbox: Toolbox, result: unknown) => Promise<void> | void;
    onError?: (error: Error, toolbox: Toolbox) => Promise<void> | void;
}

Properties

name

Type: string
Required: Yes

Unique plugin name:

{
    name: "my-plugin";
}

description

Type: string
Required: No

Plugin description:

{
    description: "Adds file system utilities";
}

version

Type: string
Required: No

Plugin version:

{
    version: "1.0.0";
}

dependencies

Type: string[]
Required: No

Other plugins this plugin depends on:

{
    dependencies: ["logger", "filesystem"];
}

Lifecycle Hooks

init

Called once during plugin initialization:

{
    init: async ({ cli, cwd, logger }) => {
        // Initialize plugin
        logger.info("Plugin initialized");
    };
}

execute

Called during command execution to extend toolbox:

{
    execute: (toolbox) => {
        toolbox.myFeature = () => {
            console.log("My feature!");
        };
    };
}

beforeCommand

Called before each command executes:

{
    beforeCommand: async (toolbox) => {
        console.log(`Executing: ${toolbox.commandName}`);
    };
}

afterCommand

Called after successful command execution:

{
    afterCommand: async (toolbox, result) => {
        console.log(`Command completed: ${result}`);
    };
}

onError

Called when an error occurs:

{
    onError: async (error, toolbox) => {
        console.error(`Error in ${toolbox.commandName}:`, error);
    };
}

PluginContext

Context provided to init hook:

interface PluginContext<T extends Console = Console> {
    cli: Cli;
    cwd: string;
    logger: T;
}

Complete Example

cli.addPlugin({
    name: "http-client",
    version: "1.0.0",
    description: "HTTP client utilities",
    dependencies: ["logger"],

    init: async ({ logger }) => {
        logger.info("HTTP client plugin initialized");
    },

    execute: (toolbox) => {
        toolbox.http = {
            get: async (url: string) => {
                const response = await fetch(url);
                return response.json();
            },
            post: async (url: string, data: unknown) => {
                const response = await fetch(url, {
                    method: "POST",
                    body: JSON.stringify(data),
                });
                return response.json();
            },
        };
    },

    beforeCommand: async (toolbox) => {
        toolbox.logger.debug(`Preparing HTTP client`);
    },

    afterCommand: async (toolbox, result) => {
        toolbox.logger.debug(`Command completed`);
    },

    onError: async (error, toolbox) => {
        toolbox.logger.error(`HTTP error:`, error);
    },
});

Plugin