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
**Automa- ✅ Numbers: Integer and float highlighting (cyan)
✅ Booleans: true/false highlighted (orange)
🚀 PHS expressions: Full PHS syntax in quoted values
⚠️ Argument validation: Warns about unused include arguments

New Argument Validation:

Detects unused arguments in !include statements
Scans target files for !arg usage patterns
Real-time warnings for better code quality 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)
Enhanced !include arguments: Type-aware syntax highlighting for include arguments
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
Local module support - Full support for local modules in workspace
Phlow Modules (.phlow) - Support for both .phlow and .yaml module formats
Relative path modules - Support for ./route, ../utils, etc.
Go to Definition - Ctrl+Click or F12 to navigate to module files
Automatic module discovery - Fetches available modules from GitHub API and local files
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
Local module priority - Local modules take precedence over remote ones
Multiple search locations - Searches in root, modules/ subdirectory
Property validation for module with configurations
Required property detection and warnings
File watching - Automatically updates when local modules change
Real-time cache invalidation - Smart cache management for local modules
No module restrictions - Use any module that exists locally or 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

🎯 Go to Definition

Module navigation - Ctrl+Click or F12 on module names to navigate to their files
Include navigation - Ctrl+Click or F12 on !include file paths to open included files
Extension-less support - Automatically finds .phlow, .yaml, or .yml files
Relative path support - Works with ./route, ../utils, ./modules/auth, etc.
Arguments aware - Navigation works even when include has arguments
Multi-format support - Automatically finds .phlow or .yaml module files
Smart search - Searches workspace root, modules/ folder, and relative paths
Real-time feedback - Console logs for debugging file resolution

💡 IntelliSense

Hover for Phlow element documentation
JSON schema validation
Module autocomplete:
- Binary modules: Schema-based property completion with type hints
- Local .phlow modules: Autocomplete based on existing with properties from target module
- Validation: Real-time validation against module schemas
- Path intellisense: Smart completion for relative module paths

Installation

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

Quick Start

Creating a new phlow

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

Running a phlow

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

Running phlow tests

Open a .phlow file that contains a tests: section
Right-click and select "Run Phlow Tests"
Or use Ctrl+Shift+P and type "Run Phlow Tests"
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 Local Modules and Go to Definition

main: http_server
name: API with Local Modules
version: 1.0.0
description: Using local modules with navigation support

modules:
  # Ctrl+Click on these module names to navigate to their files
  - module: ./route        # Goes to route.phlow or route.yaml in same folder
  - module: ../auth        # Goes to auth.phlow or auth.yaml in parent folder
  - module: cors           # Searches in workspace and modules/ folder
    with:
      origins: ["*"]
      methods: ["GET", "POST"]

steps:
  - use: route
    with:
      method: GET
      path: /api/users
  - use: cors
  - return:
      status: 200
      body: !phs payload

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 with Arguments

Include content from other files with typed arguments:

# Basic include
modules: !include modules.yaml

# Include with arguments (NEW!)
result: !include ./return.phlow target=route_get_authors output='!phs payload'

# Multiple arguments with different types
config: !include ./config.phlow 
  name=my_service 
  port=3000 
  enabled=true 
  data='!phs main.input'

Syntax Highlighting Features:

🎨 File paths: Clearly highlighted (green)
🔧 Parameter names: Highlighted as variables (blue)
⚡ Assignment operators: = highlighted (gray)
📝 String values: Quoted and unquoted strings (green)
🔢 Numbers: Integer and float highlighting (cyan)
✅ Booleans: true/false highlighted (orange)
🚀 PHS expressions: Full PHS syntax in quoted values

📖 See INCLUDE_ARGUMENTS_GUIDE.md for detailed syntax examples

`!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:

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

Contributing

Contributions are welcome! This project is in active development.

Fork the repository
Create a branch for your feature
Make your changes
Open a Pull Request

Useful Links

License

MIT

Made with ❤️ for the Phlow community

Phlow

phlow