Aexol API Reference

Complete reference for using Aexol programmatically in TypeScript/JavaScript and Deno.

🎯 Overview

Aexol provides a complete toolkit for parsing, validating, and working with Aexol specifications. This reference covers:

• Parser API - Parse Aexol code into AST
• Validator API - Validate and analyze specifications
• CLI API - Use Aexol from the command line
• MCP Tools - Integrate with AI assistants

📦 Installation

Deno

import { Parser, Validator, CodeGenerator } from "jsr:@aexol/aexol";

Node.js / npm

npm install @aexol/aexol

import { Parser, Validator } from "@aexol/aexol";

🔧 Parser API

Parse Aexol source code into an Abstract Syntax Tree (AST).

Basic Parsing

import { Parser } from "@aexol/aexol";

const source = `
type User {
  id: string
  name: string
  email: string
}

visitor Admin {
  "manage users"
  "view reports"
}
`;

const parser = new Parser(source);
const ast = parser.parse();

console.log(ast);
// {
//   types: [...],
//   visitors: [...],
//   agents: [],
//   workflows: [],
//   roles: []
// }

Parser Options

interface ParserOptions {
  /** Include position information in AST nodes */
  includePositions?: boolean;
  /** Recover from errors and continue parsing */
  recoverFromErrors?: boolean;
}

const parser = new Parser(source, {
  includePositions: true,
  recoverFromErrors: true
});

AST Structure

The parser returns a AexolAST object:

interface AexolAST {
  types: TypeDefinition[];
  visitors: VisitorDefinition[];
  agents: AgentDefinition[];
  workflows: WorkflowDefinition[];
  roles: RoleDefinition[];
  enums: EnumDefinition[];
}

interface TypeDefinition {
  name: string;
  fields: FieldDefinition[];
  position?: Position;
}

interface FieldDefinition {
  name: string;
  type: string;
  isArray: boolean;
  isOptional: boolean;
}

interface VisitorDefinition {
  name: string;
  capabilities: Capability[];
  position?: Position;
}

interface Capability {
  verb: string;
  target: string;
  conditions?: Condition[];
  nested?: Capability[];
}

Error Handling

try {
  const ast = parser.parse();
} catch (error) {
  if (error instanceof SyntaxError) {
    console.error("Syntax error:", error.message);
    console.error("Line:", error.line, "Column:", error.column);
  }
}

✅ Validator API

Validate Aexol specifications for semantic correctness.

Basic Validation

import { Parser, Validator } from "@aexol/aexol";

const parser = new Parser(source);
const ast = parser.parse();

const validator = new Validator(ast);
const result = validator.validate();

if (!result.isValid) {
  console.error("Validation errors:", result.errors);
}

Validation Result

interface ValidationResult {
  isValid: boolean;
  errors: Diagnostic[];
  warnings: Diagnostic[];
  infos: Diagnostic[];
}

interface Diagnostic {
  severity: "error" | "warning" | "info";
  message: string;
  line?: number;
  column?: number;
  code?: string;
}

Validation Rules

The validator checks for:

• ✅ Unique names - Types, visitors, agents, roles must have unique names
• ✅ Valid references - Type references must exist
• ✅ Valid verbs - Capability verbs must be recognized
• ✅ Workflow states - Workflow transitions must reference defined states
• ✅ Circular references - Detect and report circular type dependencies

Custom Validation

const validator = new Validator(ast, {
  strictMode: true,  // More strict validation
  allowUnknownVerbs: false,  // Require known capability verbs
});

🖥️ CLI API

Use Aexol from the command line.

Available Commands

# Parse and validate
aexol parse app.aexol
aexol validate app.aexol

# Generate documentation
aexol docs app.aexol -o README.md

# Analyze complexity
aexol analyze app.aexol

# Interactive chat
aexol chat

# AI-assisted implementation
aexol implement app.aexol --agent copilot

Programmatic CLI Usage

import { exec } from "@aexol/aexol/cli";

// Parse file
const parseResult = await exec(["parse", "app.aexol"]);

// Validate file
const validateResult = await exec([
  "validate",
  "app.aexol"
]);

🤖 Remote MCP API

Integrate Aexol with AI assistants via backend Model Context Protocol endpoint.

Endpoint & Protocol

• Endpoint: https://api.aexol.ai/mcp
• Protocol: JSON-RPC 2.0
• Core methods: initialize, ping, tools/list, tools/call

Remote MCP Operations

Remote/team operations are exposed by the backend MCP endpoint at https://api.aexol.ai/mcp using a team API key.

Authentication header:

Authorization: Bearer sk-aexol-team-...

See Remote MCP Configuration for JSON-RPC method examples (initialize, ping, tools/list, tools/call).

Remote MCP Tool Catalog

Remote MCP Usage

Use your MCP client/server integration against https://api.aexol.ai/mcp with a team API key to invoke the remote_* tool catalog.

JSON-RPC Request Shape

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "remote_get_context",
    "arguments": {}
  }
}

📊 Analysis API

Analyze Aexol specifications for complexity and patterns.

Analyze AST

import { Parser, analyze } from "@aexol/aexol";

const parser = new Parser(source);
const ast = parser.parse();

const analysis = analyze(ast);

console.log(analysis);
// {
//   typeCount: 5,
//   visitorCount: 3,
//   workflowCount: 2,
//   totalCapabilities: 15,
//   maxNestingDepth: 4,
//   complexity: "medium"
// }

Visualization

import { visualize } from "@aexol/aexol/utils";

const tree = visualize(ast);
console.log(tree);

// Output:
// └── Admin
//     ├── "manage users"
//     │   └── "create users"
//     │   └── "delete users"
//     └── "view reports"

🔍 Utility Functions

Extract Types

import { extractTypes } from "@aexol/aexol/utils";

const types = extractTypes(ast);
// Returns array of all type definitions

Find References

import { findReferences } from "@aexol/aexol/utils";

const refs = findReferences(ast, "User");
// Returns all places where "User" type is referenced

Convert to JSON Schema

import { toJSONSchema } from "@aexol/aexol/utils";

const schema = toJSONSchema(ast);
// Returns JSON Schema representation of types

🎯 Complete Example

Here's a complete example using multiple APIs:

import { 
  Parser, 
  Validator, 
  analyze,
  visualize 
} from "@aexol/aexol";

async function processAexol(source: string) {
  // 1. Parse
  console.log("Parsing...");
  const parser = new Parser(source);
  const ast = parser.parse();
  
  // 2. Validate
  console.log("Validating...");
  const validator = new Validator(ast);
  const validation = validator.validate();
  
  if (!validation.isValid) {
    console.error("Validation errors:", validation.errors);
    return;
  }
  
  // 3. Analyze
  console.log("Analyzing...");
  const analysis = analyze(ast);
  console.log("Complexity:", analysis.complexity);
  
  // 4. Visualize
  console.log("Capability Tree:");
  console.log(visualize(ast));
  
  console.log("✅ Done!");
}

// Use it
const source = await Deno.readTextFile("app.aexol");
await processAexol(source);

🚨 Error Handling

Parser Errors

import { SyntaxError, Parser } from "@aexol/aexol";

try {
  const parser = new Parser(source);
  const ast = parser.parse();
} catch (error) {
  if (error instanceof SyntaxError) {
    console.error(`Syntax error at line ${error.line}: ${error.message}`);
  }
}

Validation Errors

const validation = validator.validate();

for (const error of validation.errors) {
  console.error(`[${error.severity}] ${error.message}`);
  if (error.line) {
    console.error(`  at line ${error.line}, column ${error.column}`);
  }
}

📚 Next Steps

• Read the Language Tutorial to learn Aexol syntax
• Explore Advanced Type Features
• Check out Workflow Features
• Set up AI & IDE Integration
• Browse Workflow Recipes for real-world patterns

Questions? Join our community or check the Quick Reference.