poiesis/AGENTS.md

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

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