# 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/
│   ├── builtin/          # Builtin function framework
│   │   ├── builtin.go
│   │   └── builtin_test.go
│   └── runtime/          # TypeScript transpilation + execution
│       ├── runtime.go
│       └── runtime_test.go
└── test_data/            # Test TypeScript files
```

## Key Packages

- `reichard.io/poiesis/internal/runtime` - Runtime management, TypeScript transpilation, execution
- `reichard.io/poiesis/internal/builtin` - Builtin registration and type conversion

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