Phlow Language Support

A complete VS Code extension for the Phlow language - the low-code Rust runtime for modular backends.

Features

🎨 Full YAML Compatibility

• .phlow files behave exactly like YAML
• Complete syntax highlighting for YAML
• Automatic 2-space indentation (YAML standard)
• Block and structure folding
• Real-time YAML syntax validation
• Support for all YAML data types (strings, numbers, booleans, arrays, objects)
• Multi-line strings (| and >)
• Comments and nested structures
• Format on save and type enabled by default

✨ Complete PHS (Phlow Script) Support

• .phs files with complete syntax highlighting (based on Rhai)
• Automatic 4-space indentation (Rust standard)
• Inline PHS in .phlow and .yaml files after !phs directives
• Autocomplete and snippets for Rhai/PHS syntax
• Hover documentation for PHS functions and variables
• Automatic indentation and folding for code blocks
• Phlow-specific functions: main, payload, steps, envs
• Format on save and type enabled by default

✨ Phlow-Specific Features

• Special highlighting for Phlow keywords (main, modules, steps, etc.)
• Recognition of special directives (!phs, !include, !import)
• Highlighting for known modules (cli, postgres, log, http_server)
• Phlow-specific schema validation for phlows

📝 Smart Snippets

• phlow-basic: Basic phlow structure with CLI
• phlow-simple: Simple phlow without modules
• phlow-cli-module: CLI module configuration
• phlow-step-assert: Step with conditional logic
• phlow-step-use: Step using modules
• phs: Phlow Script expressions
• And much more...

✨ Enhanced Module Support

• Dynamic module validation - Validates any module from the Phlow repository
• Automatic module discovery - Fetches available modules from GitHub API
• Smart autocompletion for module properties based on their schemas
• Enhanced hover documentation with module-specific information and links
• Dynamic schema fetching from GitHub repository for up-to-date module information
• Property validation for module with configurations
• Required property detection and warnings
• No module restrictions - Use any module that exists in the Phlow repository

🔧 Commands

• Run Phlow Phlow: Execute the current phlow in terminal
• Run Phlow Tests: Execute the phlow tests using phlow file.phlow --test
• Validate Phlow Phlow: Comprehensive validation with detailed error reporting
• Create New Phlow Phlow: Wizard to create new phlows
• Format Document (Phlow Style): Apply proper indentation (2 spaces for .phlow, 4 for .phs)
• Clear Module Cache: Clear cached module schemas (useful for development)

🧪 Test Explorer Integration

• Native VS Code Test Explorer: All Phlow tests appear in the built-in Test Explorer
• Individual Test Execution: Run specific tests or entire test suites
• Real-time Discovery: Automatically detects and updates tests as you edit files
• Visual Feedback: Clear pass/fail status with detailed error reporting
• Quick Navigation: Jump to test code with a single click

💡 Tip: Open Test Explorer with View > Test Explorer or Ctrl+Shift+T

💡 IntelliSense

• Hover for Phlow element documentation
• JSON schema validation
• Intelligent autocomplete

Installation

1. Open VS Code
2. Go to Extensions tab (Ctrl+Shift+X)
3. Search for "Phlow Language Support"
4. Click "Install"

Quick Start

Creating a new phlow

1. Use the command Ctrl+Shift+P and type "Create New Phlow Phlow"
2. Choose the desired phlow type
3. Enter the phlow name
4. The file will be created automatically with a template

Running a phlow

1. Open a .phlow file
2. Right-click and select "Run Phlow Phlow"
3. Or use Ctrl+Shift+P and type "Run Phlow Phlow"

Running phlow tests

1. Open a .phlow file that contains a tests: section
2. Right-click and select "Run Phlow Tests"
3. Or use Ctrl+Shift+P and type "Run Phlow Tests"
4. The extension will execute phlow file.phlow --test in the terminal

💡 Tip: Files with tests will show a "🧪 Run Tests" CodeLens at the top for quick access

Usage Examples

Basic CLI Phlow

main: cli
name: Hello Phlow
version: 1.0.0
description: My first phlow
modules:
  - module: cli
    version: latest
    with:
      additional_args: false
      args:
        - name: name
          description: User name
          index: 1
          type: string
          required: true
steps:
  - payload:
      greeting: !phs main.name
  - return: !phs `Hello, ${payload.greeting}!`

Phlow with Inline PHS

main: cli
name: PHS Demo
modules:
  - module: cli
    version: latest
    with:
      args:
        - name: name
          type: string
          required: true
steps:
  # Inline PHS with complete syntax highlighting
  - payload: !phs `{
      user_name: main.name,
      processed_at: timestamp(),
      greeting: if main.name.len() > 0 {
        "Hello, " + main.name + "!"
      } else {
        "Hello, World!"
      }
    }`
  - return: !phs payload.greeting

Standalone PHS File

// script.phs - Complete support for Rhai syntax
fn process_data(input) {
    let result = #{
        original: input,
        processed: input.to_upper(),
        length: input.len()
    };
    
    log("info", `Processed: ${input}`);
    return result;
}

// Access to Phlow context
let user_data = main.user_name;
process_data(user_data)

Phlow with Tests

main: cli
name: Math Calculator
version: 1.0.0
description: Calculator with test cases
modules:
  - module: cli
    version: latest
    with:
      args:
        - name: total
          type: number
          required: true

# Test cases - run with "phlow file.phlow --test"
tests: 
  - main:
      total: 2
    payload: 10
    assert_eq: "Total is 20"
  - main:
      total: 3
    payload: 5
    assert: !phs payload == "Total is 15"

steps:
  - payload: !phs main.total * payload 
  - payload: !phs `Total is ${payload}`

Supported Phlow Types

• CLI Phlows: Command-line applications
• HTTP Phlows: Web servers and APIs
• Database Phlows: PostgreSQL integration
• Simple Phlows: Data processing without external modules

Special Directives

!phs - Phlow Script

Execute dynamic inline code:

message: !phs `Hello, ${main.name}!`
condition: !phs main.age > 18

!include - Include Files

Include content from other YAML files:

modules: !include modules.yaml

!import - Import Scripts

Import and execute PHS scripts:

result: !import scripts/calculation.phs

Configuration

The extension works automatically with .phlow files, which are treated as complete YAML with Phlow-specific features. This means you get:

• ✅ All YAML functionality: indentation, folding, syntax highlighting
• ✅ Phlow-specific features: keywords, directives, validation
• ✅ Complete compatibility: .phlow files are valid YAML
• ✅ Automatic formatting: 2-space indentation for .phlow, 4-space for .phs

Indentation Standards

• .phlow files: 2 spaces (YAML standard)
• .phs files: 4 spaces (Rust standard)
• Auto-formatting: Enabled by default (format on save, format on type)
• Manual formatting: Use Ctrl+Shift+P → "Format Document (Phlow Style)"

📖 See FORMATTING_GUIDE.md for detailed formatting rules and examples

For the best experience:

1. Install the Phlow runtime: Official Documentation
2. Configure your environment variables in VS Code
3. Use the integrated terminal to run phlows

Contributing

Contributions are welcome! This project is in active development.

1. Fork the repository
2. Create a branch for your feature
3. Make your changes
4. Open a Pull Request

Useful Links

• Phlow Documentation
• Phlow GitHub
• Phlow Examples

License

MIT

Made with ❤️ for the Phlow community