src — scripting

Module: src-scripting Cohesion: 0.80 Members: 0

src — scripting

The src/scripting module provides the core infrastructure for executing custom scripts within the Code Buddy environment. It unifies the capabilities of previous "FileCommander Script" (FCS) and "Buddy Script" systems, offering a rich set of built-in functions, AI integration, file system access, and shell command execution. Scripts written for this module typically use the .bs (primary) or .fcs (backward-compatible alias) extensions.

This module is designed to be extensible, allowing developers to define new language features, integrate with external tools, and provide a sandboxed environment for script execution.

Architecture Overview

The scripting module follows a classic compiler-interpreter pipeline:

  1. Lexer: Converts raw script source code into a stream of tokens.
  2. Parser: Transforms the token stream into an Abstract Syntax Tree (AST).
  3. Runtime: Executes the AST, interpreting statements and expressions within a defined context.
  4. Built-ins & Bindings: Provide the core functionality and external integrations available to scripts.

graph TD
    A[Script Source Code] --> B(Lexer: src/scripting/lexer.ts);
    B --> C{Tokens};
    C --> D(Parser: src/scripting/parser.ts);
    D --> E{Abstract Syntax Tree (AST)};
    E --> F(Runtime: src/scripting/runtime.ts);
    F --> G(Built-ins: src/scripting/builtins.ts);
    F --> H(CodeBuddy Bindings: src/scripting/codebuddy-bindings.ts);
    G & H --> F;
    F --> I{ScriptResult};

Key Components

1. Lexer (src/scripting/lexer.ts)

The FCSLexer class is responsible for the lexical analysis phase. It takes the raw script source code as input and produces an array of Token objects.

Key Features:

The tokenize(source: string) function is the primary entry point for the lexer.

2. Parser (src/scripting/parser.ts)

The FCSParser class performs syntactic analysis, taking the token stream from the lexer and constructing an Abstract Syntax Tree (AST). The parser uses a recursive descent approach.

Key Features:

The parse(tokens: Token[]) function is the primary entry point for the parser.

3. Runtime (src/scripting/runtime.ts)

The FCSRuntime class is the interpreter that executes the AST generated by the parser. It manages the script's execution context, handles control flow, and interacts with built-in functions and external bindings.

Key Features:

The execute(program: Program) method is the main entry point for running an AST.

4. Built-in Functions (src/scripting/builtins.ts)

The createBuiltins function generates a comprehensive set of standard functions and objects available to all scripts. These are fundamental operations that don't require specific Code Buddy integrations.

Categories of Built-ins:

5. CodeBuddy Bindings (src/scripting/codebuddy-bindings.ts)

The createGrokBindings function provides specialized functions that integrate scripts directly with Code Buddy's internal capabilities, such as AI interaction, tool execution, and session management. These bindings are designed to give scripts powerful control over the Code Buddy environment.

Namespaces:

The setCodeBuddyClient and setMCPManager functions are used by the main application to inject the necessary client instances for these bindings to function.

6. Script Manager (src/scripting/index.ts)

This file serves as the public API for the entire scripting module, consolidating exports and providing high-level utility functions for script management.

Key Functions & Classes:

Execution Flow

When a script is executed (e.g., via executeScript or executeScriptFile):

  1. The script source is passed to tokenize (from lexer.ts) to produce a list of Token objects.
  2. These tokens are then passed to parse (from parser.ts) to construct an AstNode representing the Program.
  3. A new FCSRuntime instance is created, configured with CodeBuddyScriptConfig.
  4. The FCSRuntime initializes its globalContext by calling createBuiltins and createGrokBindings, injecting all available functions and objects.
  5. The runtime.execute(program) method is called, which iterates through the AST's statements.
  6. For each statement or expression, executeNode or evaluate is called, recursively traversing the AST and performing the corresponding operations. Asynchronous operations (like AI calls or shell commands) are handled using await.
  7. The runtime captures all print output and any errors. If TestDeclaration nodes are present, their results are also collected.
  8. Finally, a ScriptResult object is returned, containing the success status, output, return value, duration, and test results.

Integration Points

The src/scripting module is a central piece of the Code Buddy application, integrating with various other components:

Developer Guide

Extending Built-ins or Bindings

To add new functionality available to scripts:

  1. For general utilities: Add functions to src/scripting/builtins.ts within an appropriate category or create a new one. Ensure they handle CodeBuddyValue types correctly and respect config.dryRun if they perform external actions.
  2. For Code Buddy-specific integrations: Add functions to src/scripting/codebuddy-bindings.ts under an existing namespace (e.g., tool, agent) or create a new one. These typically interact with CodeBuddyClientInterface or MCPManagerInterface.

Modifying the Language

Debugging Scripts