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/
│   └── 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