myapp/
|-- cmd/myapp/main.go           # Entrypoint commands
|-- internal/
|   |-- app/                    # App routing and server
|   |-- controller/             # App controllers
|       |-- controller.go       # Root resource
|       |-- controller_test.go  # Tests co-located
|       |-- users/
|           |-- users.go        # Users resource
|           |-- users_test.go
|   |-- env/                    # Environment parsing
|   |-- log/                    # Centralized logging
|   |-- pogo/                   # Generated database client
|   |-- db/                     # Database connection
|   |-- slack/                  # Project-specific dependencies
|   |-- stripe/                 # Project-specific dependencies
|-- migrate/                    # Migrations
    |-- 001_setup.down.sql      # Up migration
    |-- 001_setup.up.sql        # Down migration
|-- scripts/                    # One-off scripts
    |-- add-teammates/main.go
    |-- team-resync/main.go
|-- e2e/                        # End-to-end tests
|-- terraform/                  # Terraform scripts
|-- .envrc                      # Direnv
|-- .gitignore
|-- Makefile                    # Command runner
|-- Readme.md                   # Project notes (install, development, test accounts, faq)
|-- go.mod
|-- go.sum

mycli/
|-- main.go              # Entrypoint (for simple CLIs)
|-- internal/
|   |-- cli/             # CLIs and commands
|   |-- env/             # Environment parsing
|-- testdata/            # Test fixtures
|-- Makefile             # Command runner
|-- go.mod

mycli/
|-- cmd/one/main.go    # Entrypoint
|-- cmd/two/main.go    # Entrypoint

mylib/
|-- mylib.go             # Public API
|-- mylib_test.go        # Tests co-located
|-- another.go
|-- another_test.go
|-- internal/            # Implementation details
|   |-- parser/
|   |-- stripe/          # Project-specific dependencies
|-- testdata/            # Test fixtures
|-- Makefile             # Command runner
|-- go.mod

func New(log *slog.Logger, db DB, cache Cache) *Client {
    return &Client{log: log, db: db, cache: cache}
}

// Wrap and prefix error with context
if err != nil {
    return fmt.Errorf("parser: parsing config: %w", err)
}

// Join multiple errors (validation)
func (in *Input) validate() (err error) {
    if in.Name == "" {
        err = errors.Join(err, errors.New("missing name"))
    }
    if in.Path == "" {
        err = errors.Join(err, errors.New("missing path"))
    }
    return err
}

// Check error types
if errors.Is(err, fs.ErrNotExist) {
    // handle not found
}

type Upload struct {
    From        string
    To          string
    MaxSize     string  // User-friendly string
    maxSize     int     // Parsed value (unexported)
}

func (in *Upload) validate() (err error) {
    if in.From == "" {
        err = errors.Join(err, errors.New("missing from"))
    }
    if in.MaxSize != "" {
        size, e := humanize.ParseBytes(in.MaxSize)
        if e != nil {
            err = errors.Join(err, fmt.Errorf("invalid max size: %w", e))
        }
        in.maxSize = int(size)
    }
    return err
}

func (c *Client) Upload(ctx context.Context, in *Upload) error {
    if err := in.validate(); err != nil {
        return fmt.Errorf("client: invalid input: %w", err)
    }
    // ...
}

func TestParser(t *testing.T) {
    is := is.New(t)
    input := "input"
    actual, err := Parse(input)
    is.NoErr(err)
    expect := "expected"
    is.Equal(actual.Name, expect)
}

func equal(t *testing.T, input, expected string) {
  t.Helper()
	t.Run(input, func(t *testing.T) {
    t.Helper()
    // ...
  })
}

func equalFile(t *testing.T, path string) {
}

func TestSample(t *testing.T) {
	equal(t, "input", `expect`)
	equal(t, "input", `expect`)
}

func TestComplex(t *testing.T) {
	equal(t, "input", `expect`)
	equal(t, "input", `expect`)
	equal(t, "input", `expect`)
	equal(t, "input", `expect`)
}

func TestFile(t *testing.T) {
	equalFile(t, "input")
	equalFile(t, "input")
}

var update = flag.Bool("update", false, "update golden files")

func TestOutput(t *testing.T) {
    is := is.New(t)
    got := Generate()

    golden := filepath.Join("testdata", t.Name()+".golden")
    if *update {
        is.NoErr(os.WriteFile(golden, []byte(got), 0644))
    }

    want, err := os.ReadFile(golden)
    is.NoErr(err)
    is.Equal(got, string(want))
}

type Store interface {
    Get(ctx context.Context, key string) ([]byte, error)
    Set(ctx context.Context, key string, value []byte) error
}

var _ Store = (*FileStore)(nil)
var _ Store = (*MemoryStore)(nil)

type Block interface {
    blockType() // unexported marker method
}

log.Info("processing file",
    slog.String("path", path),
    slog.Int("size", size),
)

log.Error("failed to parse",
    slog.String("file", file),
    slog.Any("error", err),
)

func (c *Client) Fetch(ctx context.Context, url string) (*Response, error)

g, ctx := errgroup.WithContext(ctx)
for _, item := range items {
    g.Go(func() error {
        return process(ctx, item)
    })
}
if err := g.Wait(); err != nil {
    return err
}

type Visitor interface {
    VisitHeader(*Header)
    VisitParagraph(*Paragraph)
}

type Node interface {
    Visit(Visitor)
}

package main

import (
	"context"
	"github.com/matthewmueller/logs"
	"github.com/package/internal/cli"
)

func main() {
  ctx := context.Background()
  log := logs.Default()
  if err := cli.Parse(ctx, os.Args[1:]...); err != nil {
    log.Fatal(err)
    os.Exit(1)
  }
}

package env

import (
	env11 "github.com/caarlos0/env/v11"
)

// Env environment
type Env struct {
	PORT         string `env:"PORT,required"`
	DATABASE_URL string `env:"DATABASE_URL,required"`
}

// Load the environment
func Load() (*Env, error) {
	env := new(Env)
  if err := env11.Parse(env); err != nil {
    return nil, err
  }
  return env, nil
}

package cli

type CLI struct {
  Stdout   io.Writer
  Stderr   io.Writer
  Stdin    io.Reader
  Env      []string
  Dir      string
  logLevel string
}

func Default() *CLI {
  return &CLI{
		Stdout: os.Stdout,
		Stderr: os.Stderr,
		Stdin:  os.Stdin,
		Env:    os.Environ(),
		Dir:    ".",
	}
}

// Parse the command line arguments
func (c *CLI) Parse(ctx context.Context, args ...string) error {
	cli := cli.New("root", "root description")
  // Enum with a default value
	cli.Flag("log", "log level").Enum(&c.logLevel, "debug", "info", "warn", "error").Default("info")

	{ // commands
		in := &Install{}
		cmd := cli.Command("command", "command description")
    // Optional flag
    cmd.Flag("force", "force install").Short('f').Optional().String(&in.Force)
    // Required argument
    cmd.Arg("pkg", "pkg to install").String(&in.Pkg)
		cmd.Run(func(ctx context.Context) error {
			return c.Install(ctx, in)
		})
	}
}

// Install input
type Install struct {
  Pkg string
  Force *bool
}

// Run the install command
func (c *CLI) Install(ctx context.Context, in *Install) error {
}