RCL Packages

RCL Packages

The RCL ecosystem consists of several modular packages that work together to provide a complete language toolchain. Each package has a specific responsibility and can be used independently or as part of the full suite.

🚀 Quick Start Guide

For Users: Install the CLI globally to start compiling RCL files:

bun add -g @rcs-lang/cli
rcl compile my-agent.rcl

For Developers: Install packages for building RCL tools:

bun add @rcs-lang/parser @rcs-lang/compiler @rcs-lang/core

For IDE Integration: Use the language service for editor features:

bun add @rcs-lang/language-service

---

📦 Package Overview

🏗️ Foundation Packages

Core infrastructure that everything else builds on

Package	Purpose	When to Use
@rcs-lang/core	Shared types, interfaces, and abstractions	Building any RCL tool - required foundation
@rcs-lang/ast	Type-safe AST definitions and utilities	Working with parsed RCL syntax trees
@rcs-lang/types	RCS Business Messaging type definitions	Working with RBM APIs and message formats
@rcs-lang/file-system	Cross-platform file operations	Building tools that read/write files

⚙️ Language Processing

Parsing and compilation pipeline

Package	Purpose	When to Use
@rcs-lang/parser	ANTLR4-based RCL parser	Converting RCL source code to AST
@rcs-lang/compiler	Modern compilation pipeline	Transforming AST to executable formats
@rcs-lang/validation	Comprehensive validation system	Checking RCL code for errors/warnings

🛠️ Developer Tools

CLI and IDE integration

Package	Purpose	When to Use
@rcs-lang/cli	Command-line compiler	Building RCS agents from terminal
@rcs-lang/language-service	IDE features (completion, hover, etc.)	Building editor extensions

🤖 Runtime

Conversation execution engine

Package	Purpose	When to Use
@rcs-lang/csm	Lightweight conversation state machine	Running RCS agents in production

---

🎯 Choose the Right Package

I want to...

📝 Parse RCL code

import { AntlrRclParser } from '@rcs-lang/parser';
// ✅ Use @rcs-lang/parser

🔨 Compile RCL to JSON/JavaScript

import { RCLCompiler } from '@rcs-lang/compiler';
// ✅ Use @rcs-lang/compiler

💻 Add RCL support to my editor

import { LanguageService } from '@rcs-lang/language-service';
// ✅ Use @rcs-lang/language-service

🚀 Run RCS agents in production

import { ConversationalAgent } from '@rcs-lang/csm';
// ✅ Use @rcs-lang/csm

🧪 Build custom tooling

import { Result, IFileSystem } from '@rcs-lang/core';
// ✅ Start with @rcs-lang/core

---

🏛️ Architecture Overview

The RCL ecosystem follows a layered architecture:

graph TB
    subgraph "🛠️ Developer Tools"
        CLI[CLI Tool]
        LS[Language Service]
    end

    subgraph "⚙️ Language Processing"
        Parser[Parser]
        Compiler[Compiler]
        Validation[Validation]
    end

    subgraph "🏗️ Foundation"
        AST[AST Types]
        Core[Core Interfaces]
        Types[RBM Types]
        FileSystem[File System]
    end

    subgraph "🤖 Runtime"
        CSM[Conversation State Machine]
    end

    CLI --> Compiler
    CLI --> Parser
    CLI --> FileSystem

    LS --> Parser
    LS --> Compiler
    LS --> Validation

    Compiler --> AST
    Compiler --> Core
    Compiler --> Parser
    Compiler --> Validation

    Parser --> AST
    Parser --> Core

    Validation --> Core
    Validation --> Parser

    CSM --> Core

    FileSystem --> Core

🔄 Typical Data Flow

1. Source Code → Parser → AST
2. AST → Validation → Diagnostics
3. AST → Compiler → JSON/JavaScript
4. JSON → CSM → Running Agent

---

📚 Learning Path

🟢 Beginner - Just want to use RCL

1. Start with @rcs-lang/cli - compile your first agent
2. Learn @rcs-lang/csm - run your agent

🟡 Intermediate - Building RCL tools

1. Understand @rcs-lang/core - core concepts
2. Use @rcs-lang/parser - parse RCL code
3. Explore @rcs-lang/ast - work with syntax trees

🔴 Advanced - Contributing to RCL

1. Master @rcs-lang/compiler - compilation pipeline
2. Study @rcs-lang/validation - validation system
3. Dive into @rcs-lang/language-service - IDE features

---

🚀 Installation & Usage

Global CLI Installation

# Install CLI globally for terminal usage
bun add -g @rcs-lang/cli

# Verify installation
rcl --version

Library Usage

# Core packages for building tools
bun add @rcs-lang/core @rcs-lang/ast @rcs-lang/parser

# Full compilation stack
bun add @rcs-lang/compiler @rcs-lang/validation @rcs-lang/file-system

# Runtime for production agents
bun add @rcs-lang/csm

# IDE integration
bun add @rcs-lang/language-service

Package Versioning

All RCL packages follow synchronized versioning - when any package is updated, all packages are bumped to the same version number. This ensures compatibility across the ecosystem.

Current version: 0.2.1

---

🧑‍💻 Development

Monorepo Structure

All packages are part of a monorepo managed with Moon and use Bun for package management:

# Clone the repository
git clone https://github.com/rcs-lang/rcl.git
cd rcl

# Install dependencies
bun install

# Build all packages
moon run :build

# Run tests
moon run :test

# Watch mode for development
moon run :dev

Package Management

• Build System: Moon (task orchestration)
• Package Manager: Bun (fast, modern)
• Runtime: Node.js AND Web browser support
• Grammar: ANTLR4 (replaced Tree-sitter)

---

🤝 Contributing

We welcome contributions! Each package accepts:

• Bug reports - Help us improve stability
• Feature requests - Guide our roadmap
• Documentation - Make RCL more accessible
• Code contributions - Implement features and fixes

See the main repository for detailed contribution guidelines.

---

📖 Additional Resources

• Getting Started Guide - Build your first RCS agent
• RCL Language Specification - Complete language reference
• Examples - Real-world RCL implementations
• API Documentation - Complete API reference