yedit

README

A TUI YAML editor library for Go applications, built on bubbletea. Drop it into any CLI tool to give users a structured, schema-aware editor for their configuration files.

What it does

• Opens a YAML file in a split-pane TUI: block list on the left, YAML editor on the right.
• Drives the editor from a Go struct - no JSON Schema, no struct tag annotations, just yaml tags.
• Shows a field tree for struct blocks (toggle fields on/off) and a [N] navigator for list/map blocks.
• Validates on save with a declarative rule set.
• Displays per-field hints, types, defaults, and examples in a side panel.
• Supports presets, two-level undo/redo, nested drill-in editing, and theming.

Install

go get github.com/lucasassuncao/yedit

Minimal example

package main

import (
	"log"

	"github.com/lucasassuncao/yedit/editor"
	"github.com/lucasassuncao/yedit/metadata"
)

type Config struct {
	Server struct {
		Host string `yaml:"host"`
		Port int    `yaml:"port"`
	} `yaml:"server"`
}

func main() {
	src, err := metadata.NewFromTree(&Config{}, map[string]*metadata.Node{
		"server": {
			Children: map[string]*metadata.Node{
				"host": {FieldMeta: editor.FieldMeta{Description: "Address to bind.", Default: "localhost"}},
				"port": {FieldMeta: editor.FieldMeta{Description: "Port to listen on.", Default: "8080"}},
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	if err := editor.Run(editor.Config{
		Path:        "config.yaml",
		Schema:      &Config{},
		Metadata:    src,
		EnableHints: true,
	}); err != nil {
		log.Fatal(err)
	}
}

Documentation

Document	Contents
Getting Started	Full happy path: struct → metadata → editor.Run, validators, presets, and doc generation
Architecture	Package layout and design rationale
Schema Kinds Reference	How Go types map to editor behavior (KindObject, KindList, KindDictionary, KindVariant, …)
Validators Reference	All built-in validation rules with examples
Presets & Metadata	PresetSource and MetadataSource configuration
Interaction Model	Key bindings and tree action matrix

Demo

Example

examples/test is a self-contained example that exercises every schema pattern, validator, preset, and Config option. Run it from the repo root:

cd examples/test
go run . [--theme dracula]   # open the editor
go run . show-docs           # browse schema docs in the TUI

Documentation

Overview

Package yedit provides reusable building blocks for TUI editors over structured YAML files.

The library is composed of independent sub-packages:

• schema: reflection over the client's Go structs (yaml tags only)
• hints: tree-based MetadataSource with strict schema validation
• document: YAML state with block-level mutations, history, and parsing
• editor: two-panel bubbletea TUI that ties the pieces together
• presets: Source interface + struct-backed helpers (ForField, Combine) for per-field YAML snippets
• viewer: read-only TUI to browse a preset Source
• theme: palette and layout primitives (header, panels, two-column layout)
• internal: non-public helpers (alert widget, yaml node utilities)

yedit is intentionally headless of any specific YAML schema. Clients pass a pointer to their own annotated struct and (optionally) a preset Source; the editor introspects the struct via the schema package and renders an add/edit/remove UI keyed by the canonical top-level order.

See editor.Run and editor.Config for the main entry point.