Add cursor rules

Author: adamw

cursor-rules/100-ox-direct-style.mdc

@@ -0,0 +1,57 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Ox Direct-Style Programming
+
+Ox uses direct-style programming where effectual computations return values directly without wrapper types like `Future`, `IO`, or `Task`. This leverages Java 21 virtual threads for high-performance concurrency.
+
+## Core Principles
+
+- **Direct return values**: Methods return actual values, not wrapped types
+- **Built-in control flow**: Use standard language constructs (if/else, for loops, try/catch)
+- **Virtual threads**: Blocking operations are cheap and efficient
+- **No coloring**: No need for special syntax like `async`/`await`
+
+## Good Examples
+
+```scala
+// Direct-style: values returned directly
+def fetchData(): String = 
+  val response = httpClient.get("https://api.example.com/data")
+  response.body
+
+def processData(): List[String] =
+  val data = fetchData()
+  data.split(",").toList
+
+// Combining operations naturally
+def pipeline(): Int =
+  val data = fetchData()
+  val processed = processData()
+  processed.length
+```
+
+## Avoid
+
+```scala
+// Don't use wrapper types like Future, IO, Task
+def fetchData(): Future[String] = ???
+def fetchData(): IO[String] = ???
+def fetchData(): Task[String] = ???
+
+// Don't use callback-style programming
+def fetchData(callback: String => Unit): Unit = ???
+```
+
+## Key Benefits
+
+- **Natural error handling**: Use try/catch for exceptions
+- **Simple control flow**: Standard if/else, loops, pattern matching
+- **Performance**: Virtual threads provide high throughput without callback complexity
+- **Readability**: Code reads like synchronous code but runs asynchronously
+
+## Integration
+
+Direct-style works seamlessly with blocking I/O operations, database calls, and HTTP requests, all efficiently managed by virtual threads under the hood.

cursor-rules/101-ox-structured-concurrency.mdc

@@ -0,0 +1,80 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# Ox Structured Concurrency
+
+All concurrent operations in Ox must happen within concurrency scopes that guarantee proper cleanup and resource management. Scopes define the lifetime of forks (threads) through code structure.
+
+## Scope Types
+
+- **`supervised`**: Default scope with error propagation
+- **`supervisedError`**: For application errors that should propagate as values
+- **`unsupervised`**: Manual error management, no automatic cancellation
+
+## Good Examples
+
+```scala
+import ox.{fork, supervised, sleep}
+import scala.concurrent.duration.*
+
+// Basic supervised scope
+supervised {
+  val f1 = fork {
+    sleep(2.seconds)
+    1
+  }
+  val f2 = fork {
+    sleep(1.second)
+    2
+  }
+  (f1.join(), f2.join())
+}
+
+// Helper methods requiring Ox capability
+def forkComputation(p: Int)(using Ox): Fork[Int] = fork {
+  sleep(p.seconds)
+  p + 1
+}
+
+supervised {
+  val f1 = forkComputation(2)
+  val f2 = forkComputation(4)
+  (f1.join(), f2.join())
+}
+```
+
+## Scope Guarantees
+
+1. **Cleanup**: All forks are interrupted when scope ends
+2. **Completion**: Scope waits for all forks to complete before returning
+3. **Error propagation**: Exceptions in any fork can end the entire scope
+4. **Resource safety**: No leaked threads or resources
+
+## Fork Types
+
+- `fork`: Daemon fork (scope doesn't wait if body completes)
+- `forkUser`: User fork (scope waits for completion)
+- `forkError`/`forkUserError`: With application error support
+- `forkUnsupervised`: Manual management (only in unsupervised scopes)
+
+## Avoid
+
+```scala
+// Never fork outside of scopes
+val f = fork { ??? } // Compile error!
+
+// Don't create long-running global scopes
+val globalScope = supervised { ??? } // Bad practice
+
+// Don't ignore scope requirements
+def helper(): Fork[Int] = fork { ??? } // Missing Ox capability
+```
+
+## Best Practices
+
+- Keep scopes as small as possible
+- Create scopes for single requests, messages, or jobs
+- Nest scopes when needed for complex operations
+- Use appropriate scope type for your error handling needs

cursor-rules/102-ox-virtual-threads.mdc

@@ -0,0 +1,95 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Ox Virtual Threads
+
+Ox leverages Java 21 virtual threads, making blocking operations cheap and efficient. Don't be afraid to block or create many concurrent forks.
+
+## Key Principles
+
+- **Blocking is cheap**: Virtual threads have low memory footprint and fast context switching
+- **Create many forks**: Thousands of virtual threads can run efficiently
+- **No thread pool management**: Virtual threads are managed by the JVM runtime
+- **Direct blocking**: No need for asynchronous programming patterns
+
+## Good Examples
+
+```scala
+import ox.{fork, supervised, sleep}
+import scala.concurrent.duration.*
+
+// Creating many concurrent operations
+supervised {
+  val forks = (1 to 1000).map { i =>
+    fork {
+      sleep(1.second) // Blocking is fine!
+      processItem(i)
+    }
+  }
+  forks.map(_.join())
+}
+
+// Blocking I/O operations
+def fetchFromDatabase(): List[User] =
+  // This blocks, but that's perfectly fine with virtual threads
+  databaseConnection.query("SELECT * FROM users")
+
+def processFiles(): Unit =
+  supervised {
+    val files = listFiles()
+    files.map { file =>
+      fork {
+        // Blocking file I/O
+        val content = Files.readString(file.toPath)
+        processContent(content)
+      }
+    }.foreach(_.join())
+  }
+```
+
+## Benefits of Virtual Threads
+
+- **High throughput**: Handle millions of concurrent requests
+- **Low memory usage**: ~200 bytes per virtual thread vs ~2MB per platform thread
+- **Fast creation**: Creating virtual threads is very cheap
+- **Familiar programming model**: Use blocking APIs without performance penalties
+
+## Blocking Operations That Are Efficient
+
+```scala
+// All of these are efficient with virtual threads:
+val data = httpClient.get(url) // HTTP requests
+val result = database.query(sql) // Database queries  
+val content = Files.readString(path) // File I/O
+val response = socket.read() // Network I/O
+Thread.sleep(duration) // Sleeping/delays
+```
+
+## Avoid Unnecessary Complexity
+
+```scala
+// Don't use callback-style when you can block
+// Bad:
+httpClient.getAsync(url, callback)
+
+// Good:
+val response = httpClient.get(url)
+
+// Don't limit concurrent operations artificially
+// Bad:
+val executor = Executors.newFixedThreadPool(10)
+
+// Good: Create as many forks as needed
+supervised {
+  items.map(item => fork { process(item) })
+}
+```
+
+## Usage Tips
+
+- Virtual threads shine with I/O-bound operations
+- CPU-bound tasks might be better served by running on a dedicated thread pool
+- Use `forkUser` when you need to wait for all operations to complete
+- Prefer high-level operations (`par`, `race`) which avoid creating scopes manually

cursor-rules/110-ox-error-handling-dual-channel.mdc

@@ -0,0 +1,152 @@
+---
+description: Ox uses two distinct channels for errors: exceptions for bugs/unexpected situations, and application errors as values (`Either`, union types).
+globs: 
+alwaysApply: false
+---
+# Ox Error Handling: Dual Channel
+
+Ox uses two distinct channels for error handling: exceptions for bugs and unexpected situations, and application errors represented as values.
+
+## Two Error Channels
+
+1. **Exceptions**: For bugs, unexpected situations, integration with Java libraries
+2. **Application errors**: Represented as values using `Either`, union types, or custom data types
+
+## Exception Handling
+
+Exceptions are handled by computation combinators and propagate normally:
+
+```scala
+import ox.{par, race, supervised, fork}
+
+// Exceptions propagate through high-level operations
+val result = par(
+  computation1(), // might throw
+  computation2()  // cancelled if computation1 throws
+)
+
+// Exceptions end supervised scopes
+supervised {
+  fork {
+    sleep(1.second)
+    println("This won't print")
+  }
+  fork {
+    sleep(500.millis)
+    throw new RuntimeException("boom!") // Ends entire scope
+  }
+}
+
+// Use try/catch for exception handling
+try {
+  riskyOperation()
+} catch {
+  case e: SpecificException => handleError(e)
+}
+```
+
+## Application Errors as Values
+
+For type-safe error handling, use `Either` and error modes:
+
+```scala
+import ox.either
+import ox.either.ok
+
+case class User()
+case class Organization()
+case class Assignment(user: User, org: Organization)
+
+def lookupUser(id: Int): Either[String, User] = ???
+def lookupOrganization(id: Int): Either[String, Organization] = ???
+
+// Use either block to unwrap values
+val result: Either[String, Assignment] = either:
+  val user = lookupUser(1).ok()
+  val org = lookupOrganization(2).ok()
+  Assignment(user, org)
+```
+
+## Union Types for Multiple Error Types
+
+```scala
+import ox.either
+import ox.either.ok
+
+val v1: Either[DatabaseError, String] = ???
+val v2: Either[NetworkError, String] = ???
+
+// Errors are combined in union type
+val result: Either[DatabaseError | NetworkError, String] = either:
+  v1.ok() ++ v2.ok()
+```
+
+## Error Modes for Advanced Scenarios
+
+```scala
+import ox.{supervisedError, EitherMode}
+
+// Use supervisedError for application error propagation
+given ErrorMode[String] = EitherMode[String]
+
+supervisedError {
+  val f1 = forkError {
+    Left("application error") // Propagated as value, not exception
+  }
+  f1.join() // Either[String, ResultType]
+}
+```
+
+## Best Practices
+
+### Use Exceptions For
+- Bugs and programming errors
+- Unexpected system failures
+- Integration with Java libraries that throw
+- Violations of preconditions/invariants
+
+### Use Application Errors For
+- Expected business logic failures
+- Validation errors
+- API error responses
+- Type-safe error handling
+
+### Working with Eithers
+- use the `either` block within which `Either` values can be unwrapped using `.ok()`
+
+## Exception Conversion
+
+Convert exceptions to values when needed:
+
+```scala
+import ox.either
+
+// Convert exception-throwing code to Either
+val result: Either[Throwable, String] = either.catching {
+  riskyOperationThatThrows()
+}
+
+// Handle specific exception types
+val result2: Either[SQLException, List[User]] = either.catching {
+  databaseQuery()
+}.recover {
+  case _: ConnectionException => Left(ConnectionError)
+}
+```
+
+## Avoid
+
+```scala
+// Don't mix error handling approaches inconsistently
+def badExample(): Either[String, User] = {
+  if (condition) throw new Exception("mixed approach") // Bad!
+  else Right(user)
+}
+
+// Don't swallow exceptions without handling
+try {
+  riskyOperation()
+} catch {
+  case _ => // Bad - don't ignore errors
+}
+```