# Poiesis

## Module Name

`reichard.io/poiesis`

## 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.

## Build & Test

```bash
go build ./cmd/poiesis
go test ./...
golangci-lint run
```

## Project Structure

```
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
└── 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.)

## Testing Patterns

- **Test framework**: Go's built-in `testing` package
- **Assertions**: `github.com/stretchr/testify/assert` and `require`
- **Linting**: `golangci-lint run` - must pass before committing
- **Test organization**: Test files use `_test.go` suffix, test functions prefixed with `Test`

## Dependencies

- `github.com/evanw/esbuild/pkg/api` - TypeScript transpilation
- `github.com/dop251/goja` - JavaScript execution
- `github.com/stretchr/testify/assert` - Test assertions

## Code Conventions

- Handle all return values from external functions (enforced by golangci-lint)
- Use `os` package instead of deprecated `io/ioutil`
- Error logging uses `_, _ = fmt.Fprintf(stderr, ...)` pattern
- Package structure follows standard Go project layout with internal packages