asd

AGENTS.md

@@ -6,7 +6,7 @@
 
 ## Overview
 
-Go tool that transpiles TypeScript to JavaScript using esbuild API and executes it with goja. Features a flexible builtin system for exposing Go functions to TypeScript.
+Go tool that transpiles TypeScript to JavaScript using esbuild API and executes it with goja. Features a flexible builtin system for exposing Go functions to TypeScript with support for both synchronous and asynchronous (Promise-based) operations.
 
 ## Build & Test
 
@@ -23,23 +23,63 @@ reichard.io/poiesis/
 ├── cmd/poiesis/              # CLI entry point
 │   └── main.go
 ├── internal/
-│   └── runtime/
-│       ├── pkg/
-│       │   └── builtin/      # Builtin framework (framework only, no implementations)
-│       │       └── builtin.go
-│       ├── standard/         # Standard builtin implementations
-│       │   ├── fetch.go
-│       │   └── fetch_test.go
-│       ├── runtime.go        # Runtime management, transpilation, execution
-│       └── runtime_test.go
+│   ├── runtime/              # Runtime management, transpilation, execution
+│   │   ├── runtime.go
+│   │   └── runtime_test.go
+│   ├── builtin/              # Builtin registration framework
+│   │   ├── types.go
+│   │   ├── registry.go
+│   │   ├── wrapper.go
+│   │   ├── convert.go
+│   │   ├── typescript.go
+│   │   └── builtin_test.go
+│   └── standard/             # Standard builtin implementations
+│       ├── fetch.go
+│       ├── fetch_test.go
+│       └── fetch_promise_test.go
 └── test_data/                # Test TypeScript files
 ```
 
 ## Key Packages
 
-- `reichard.io/poiesis/internal/runtime` - Runtime management, TypeScript transpilation, execution
-- `reichard.io/poiesis/internal/runtime/pkg/builtin` - Generic builtin registration framework (framework only)
-- `reichard.io/poiesis/internal/runtime/standard` - Standard builtin implementations (fetch, add, greet, etc.)
+- `reichard.io/poiesis/internal/runtime` - Runtime management, TypeScript transpilation, JavaScript execution
+- `reichard.io/poiesis/internal/builtin` - Generic builtin registration framework (sync/async wrappers, JS/Go conversion, type definition generation)
+- `reichard.io/poiesis/internal/standard` - Standard builtin implementations (fetch, add, greet, etc.)
+
+## Builtin System
+
+### Registration
+
+Two types of builtins:
+- **Sync**: `RegisterBuiltin[T, R](name, fn)` - executes synchronously, returns value
+- **Async**: `RegisterAsyncBuiltin[T, R](name, fn)` - runs in goroutine, returns Promise
+
+### Requirements
+
+- Args must be a struct implementing `Args` interface with `Validate() error` method
+- Use JSON tags for TypeScript type definitions
+- Async builtins automatically generate `Promise<R>` return types
+
+### Example
+
+```go
+type AddArgs struct {
+    A int `json:"a"`
+    B int `json:"b"`
+}
+
+func (a AddArgs) Validate() error { return nil }
+
+func Add(_ context.Context, args AddArgs) (int, error) {
+    return args.A + args.B, nil
+}
+
+// Register sync builtin
+builtin.RegisterBuiltin[AddArgs, int]("add", Add)
+
+// Register async builtin
+builtin.RegisterAsyncBuiltin[FetchArgs, *FetchResult]("fetch", Fetch)
+```
 
 ## Testing Patterns