Skip to main content
ubx is a Go application organised as a single-pass compiler followed by Pulumi Automation API orchestration.

​
Repository Structure

ubx/
  cmd/                    # CLI commands (cobra)
    root.go               # root command, global flags
    apply.go              # ubx apply
    plan.go               # ubx plan
    validate.go           # ubx validate
    fmt.go                # ubx fmt
    explain.go            # ubx explain (AI)
    fix.go                # ubx fix (AI)
    ...
  internal/
    compiler/
      lexer/              # tokenizer
      parser/
        ast/              # AST node types
        parser.go         # recursive descent parser
      typechecker/        # symbol resolution, `Pending<T>` tracking
      codegen/            # TypeScript emitter
        emitter.go
        registry.go       # resource type → TS class mapping
      formatter/          # ubx fmt
      merger/             # extend block merging
      schema/             # provider schema registry
    ai/                   # AI client (net/http → Anthropic API)
    config/               # ubx.yaml parsing
    ignore/               # .ubxignore implementation
    pulumi/               # Automation API wrapper
    testing/              # ubx test framework
  examples/               # example .iac projects
  ARCHITECTURE.md
  CLAUDE.md               # AI session context
  Technical_Reference.md

​
Compiler Pipeline

Source (.iac files)
  → Lexer       (internal/compiler/lexer/)
  → Parser      (internal/compiler/parser/)
  → Merger      (internal/compiler/merger/)
  → TypeChecker (internal/compiler/typechecker/)
  → CodeGen     (internal/compiler/codegen/)
  → index.ts    (written to .ubx/)
  → pulumi up   (internal/pulumi/ via Automation API)

​
Key Design Decisions

  • No TypeScript runtime dependency — users write .iac, TypeScript is a build artifact
  • No external AI SDK — net/http only for Anthropic API calls
  • Pulumi Automation API — replaces all exec.Command("pulumi", ...) subprocess calls
  • Single label for component — source attribute is the type identifier
  • output not export — familiar to Terraform users

​
Adding a New Resource Type

See Adding Resources.

​
Adding a New CLI Command

  1. Create cmd/<command>.go
  2. Define a cobra.Command with Use, Short, RunE
  3. Register in cmd/root.go via rootCmd.AddCommand()
  4. Write tests in cmd/<command>_test.go