Initial commit

skills/east-development/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: east-development
+description: Write East code - a portable, type-safe functional language. Use when writing East functions, working with East IR, or creating portable computations. Automatically validates code with east_compile tool.
+---
+
+# East Development Skill
+
+## What is East?
+
+East is a **statically typed, expression-based functional language** embedded in TypeScript that compiles to portable **IR (Intermediate Representation)**. East enables you to write type-safe, portable computations that can execute in different environments (JavaScript, Julia, Python, etc.) without modification.
+
+**Key Characteristics:**
+- **Portable**: Compiles to IR that runs anywhere
+- **Type-safe**: Strong static typing with compile-time guarantees
+- **Functional**: Expression-based with immutable data structures
+- **Sandboxed**: Controlled execution environment with explicit platform functions
+
+## When to Use This Skill
+
+Use the `east-development` skill when:
+- User asks to write East functions or East code
+- User wants to create portable computations or IR
+- User mentions East types, expressions, or the East language
+- User needs type-safe functional programming with portability
+- User wants to validate East code syntax
+
+## Quick Example
+
+Here's a simple East function that adds two integers:
+
+```typescript
+return East.function(
+  [East.IntegerType, East.IntegerType],
+  East.IntegerType,
+  ($, x, y) => {
+    return $.return(x.add(y));
+  }
+);
+```
+
+This can be validated using the `east_compile` tool (provided by this plugin's MCP server).
+
+## Documentation
+
+This skill provides comprehensive East documentation:
+
+- **[USAGE.md](./USAGE.md)** - Complete East developer guide covering:
+  - All types (Null, Boolean, Integer, Float, String, DateTime, Blob, Array, Set, Dict, Struct, Variant)
+  - Functions and expressions
+  - Control flow and operations
+  - JSON serialization format
+  - Platform functions
+
+- **[STDLIB.md](./STDLIB.md)** - Standard library reference covering:
+  - Formatting utilities (e.g., `Integer.printCommaSeparated()`)
+  - Conversion functions (e.g., `DateTime.fromEpochMilliseconds()`)
+  - Generation utilities for each type
+
+## Validation Workflow
+
+When writing East code for users, follow this workflow:
+
+1. **Write the function** using the East TypeScript API (see USAGE.md for syntax)
+2. **Validate with `east_compile`** - call the tool to check syntax and generate IR
+3. **Fix any errors** - use compilation error messages to correct issues
+4. **Return validated code** - provide the working East function to the user
+
+Example validation:
+```json
+{
+  "typescript_code": "return East.function([East.IntegerType], East.IntegerType, ($, x) => $.return(x.add(1n)))"
+}
+```
+
+## Important: No Imports Required
+
+When calling `east_compile`, the `East` object is already injected into scope. Your code should:
+
+- **NOT** include import statements
+- **Use** `East.function()`, `East.IntegerType`, etc. directly
+- **Return** an East function expression
+- **Use** bigint literals for integers (e.g., `1n`, `42n`)
+
+**Correct:**
+```typescript
+return East.function([East.IntegerType], East.IntegerType, ($, x) => {
+  return $.return(x.add(1n));
+});
+```
+
+**Incorrect:**
+```typescript
+import { East } from '@elaraai/east';  // ❌ Don't import
+const fn = East.function(...);         // ❌ Don't assign, must return
+```
+
+## Common Patterns
+
+### Basic Arithmetic
+See USAGE.md § Integer and Float sections for arithmetic operations.
+
+### Working with Collections
+See USAGE.md § Array, Set, and Dict sections for collection operations.
+
+### Structured Data
+See USAGE.md § Struct section for working with structured types.
+
+### Pattern Matching
+See USAGE.md § Variant section for sum types and pattern matching.
+
+### Platform Functions
+See USAGE.md § Platform Functions section for declaring external functions.
+
+## Type System Quick Reference
+
+**Primitive Types:**
+- `East.NullType` - Null value
+- `East.BooleanType` - true/false
+- `East.IntegerType` - Arbitrary precision integers (use bigint literals: `42n`)
+- `East.FloatType` - IEEE 754 double precision floats
+- `East.StringType` - Unicode strings
+- `East.DateTimeType` - ISO 8601 date-times with timezone
+- `East.BlobType` - Binary data
+
+**Compound Types:**
+- `East.ArrayType(T)` - Ordered list of elements
+- `East.SetType(T)` - Unordered unique elements
+- `East.DictType(K, V)` - Key-value mappings
+- `East.StructType({field: Type, ...})` - Product types with named fields
+- `East.VariantType({Tag: Type, ...})` - Sum types (tagged unions)
+
+## Examples
+
+For worked examples, see:
+- USAGE.md - Contains comprehensive examples for each type and operation
+- `examples/` directory - Additional practical examples (if present)
+
+## Tips for Success
+
+1. **Always validate** - Use `east_compile` to catch errors early
+2. **Use bigint literals** - Integers must be `1n`, not `1`
+3. **Return the function** - Code must return an `East.function()` call
+4. **Check types carefully** - East is strongly typed; mismatches cause compilation errors
+5. **Read error messages** - Compilation errors provide specific guidance
+6. **Reference docs** - USAGE.md and STDLIB.md contain all the details
+
+## Common Errors and Solutions
+
+**"Code must evaluate to an East function"**
+- Ensure your code returns `East.function(...)`
+- Don't assign to a variable; return directly
+
+**Type mismatch errors**
+- Check that expression types match function signatures
+- Verify bigint literals are used for integers
+- Ensure operations are called on correct types
+
+**"Expected bigint" errors**
+- Use `42n` not `42` for integer values
+- Integer literals must have the `n` suffix
+
+## Getting Help
+
+- Review USAGE.md for comprehensive type and operation documentation
+- Check STDLIB.md for standard library utilities
+- Examine compilation errors for specific guidance
+- Test incrementally with `east_compile`