implement /api/schemas (json schemas from tsunami atoms /api/config /api/data) (#2335)

Author: sawka

tsunami/app/atom.go

@@ -12,6 +12,22 @@ import (
 	"github.com/wavetermdev/waveterm/tsunami/util"
 )
 
+// AtomMeta provides metadata about an atom for validation and documentation
+type AtomMeta struct {
+	Desc    string   // short, user-facing
+	Units   string   // "ms", "GiB", etc.
+	Min     *float64 // optional minimum (numeric types)
+	Max     *float64 // optional maximum (numeric types)
+	Enum    []string // allowed values if finite set
+	Pattern string   // regex constraint for strings
+}
+
+// Atom[T] represents a typed atom implementation
+type Atom[T any] struct {
+	name   string
+	client *engine.ClientImpl
+}
+
 // logInvalidAtomSet logs an error when an atom is being set during component render
 func logInvalidAtomSet(atomName string) {
 	_, file, line, ok := runtime.Caller(2)
@@ -58,12 +74,6 @@ func logMutationWarning(atomName string) {
 	}
 }
 
-// Atom[T] represents a typed atom implementation
-type Atom[T any] struct {
-	name   string
-	client *engine.ClientImpl
-}
-
 // AtomName implements the vdom.Atom interface
 func (a Atom[T]) AtomName() string {
 	return a.name

tsunami/app/defaultclient.go

@@ -16,6 +16,10 @@ func DefineComponent[P any](name string, renderFn func(props P) any) vdom.Compon
 	return engine.DefineComponentEx(engine.GetDefaultClient(), name, renderFn)
 }
 
+func Ptr[T any](v T) *T {
+	return &v
+}
+
 func SetGlobalEventHandler(handler func(event vdom.VDomEvent)) {
 	engine.GetDefaultClient().SetGlobalEventHandler(handler)
 }
@@ -35,30 +39,46 @@ func SendAsyncInitiation() error {
 	return engine.GetDefaultClient().SendAsyncInitiation()
 }
 
-func ConfigAtom[T any](name string, defaultValue T) Atom[T] {
+func ConfigAtom[T any](name string, defaultValue T, meta *AtomMeta) Atom[T] {
 	fullName := "$config." + name
 	client := engine.GetDefaultClient()
-	atom := engine.MakeAtomImpl(defaultValue)
+	engineMeta := convertAppMetaToEngineMeta(meta)
+	atom := engine.MakeAtomImpl(defaultValue, engineMeta)
 	client.Root.RegisterAtom(fullName, atom)
 	return Atom[T]{name: fullName, client: client}
 }
 
-func DataAtom[T any](name string, defaultValue T) Atom[T] {
+func DataAtom[T any](name string, defaultValue T, meta *AtomMeta) Atom[T] {
 	fullName := "$data." + name
 	client := engine.GetDefaultClient()
-	atom := engine.MakeAtomImpl(defaultValue)
+	engineMeta := convertAppMetaToEngineMeta(meta)
+	atom := engine.MakeAtomImpl(defaultValue, engineMeta)
 	client.Root.RegisterAtom(fullName, atom)
 	return Atom[T]{name: fullName, client: client}
 }
 
 func SharedAtom[T any](name string, defaultValue T) Atom[T] {
 	fullName := "$shared." + name
 	client := engine.GetDefaultClient()
-	atom := engine.MakeAtomImpl(defaultValue)
+	atom := engine.MakeAtomImpl(defaultValue, nil)
 	client.Root.RegisterAtom(fullName, atom)
 	return Atom[T]{name: fullName, client: client}
 }
 
+func convertAppMetaToEngineMeta(appMeta *AtomMeta) *engine.AtomMeta {
+	if appMeta == nil {
+		return nil
+	}
+	return &engine.AtomMeta{
+		Description: appMeta.Desc,
+		Units:       appMeta.Units,
+		Min:         appMeta.Min,
+		Max:         appMeta.Max,
+		Enum:        appMeta.Enum,
+		Pattern:     appMeta.Pattern,
+	}
+}
+
 // HandleDynFunc registers a dynamic HTTP handler function with the internal http.ServeMux.
 // The pattern MUST start with "/dyn/" to be valid. This allows registration of dynamic
 // routes that can be handled at runtime.

tsunami/demo/cpuchart/app.go

@@ -11,8 +11,12 @@ import (
 
 // Global atoms for config and data
 var (
-	dataPointCountAtom = app.ConfigAtom("dataPointCount", 60)
-	cpuDataAtom        = app.DataAtom("cpuData", func() []CPUDataPoint {
+	dataPointCountAtom = app.ConfigAtom("dataPointCount", 60, &app.AtomMeta{
+		Desc: "Number of CPU data points to display in the chart",
+		Min:  app.Ptr(10.0),
+		Max:  app.Ptr(300.0),
+	})
+	cpuDataAtom = app.DataAtom("cpuData", func() []CPUDataPoint {
 		// Initialize with empty data points to maintain consistent chart size
 		dataPointCount := 60 // Default value for initialization
 		initialData := make([]CPUDataPoint, dataPointCount)
@@ -24,13 +28,15 @@ var (
 			}
 		}
 		return initialData
-	}())
+	}(), &app.AtomMeta{
+		Desc: "Historical CPU usage data points for charting",
+	})
 )
 
 type CPUDataPoint struct {
-	Time      int64    `json:"time"`      // Unix timestamp in seconds
-	CPUUsage  *float64 `json:"cpuUsage"`  // CPU usage percentage (nil for empty slots)
-	Timestamp string   `json:"timestamp"` // Human readable timestamp
+	Time      int64    `json:"time" desc:"Unix timestamp (seconds since epoch)" units:"s"`
+	CPUUsage  *float64 `json:"cpuUsage" desc:"CPU usage percentage" units:"%" min:"0" max:"100"`
+	Timestamp string   `json:"timestamp" desc:"Human-readable HH:MM:SS"`
 }
 
 type StatsPanelProps struct {
@@ -207,7 +213,7 @@ var App = app.DefineComponent("App", func(_ struct{}) any {
 				}, "Real-Time CPU Usage Monitor"),
 				vdom.H("p", map[string]any{
 					"className": "text-gray-400",
-				}, "Live CPU usage data collected using gopsutil, displaying 60 seconds of history"),
+				}, "Live CPU usage data collected using gopsutil, displaying ", dataPointCount, " seconds of history"),
 			),
 
 			// Controls
@@ -334,7 +340,7 @@ var App = app.DefineComponent("App", func(_ struct{}) any {
 						vdom.H("span", map[string]any{
 							"className": "text-blue-400 mt-1",
 						}, "•"),
-						"Rolling window of 60 seconds of historical data",
+						"Rolling window of ", dataPointCount, " seconds of historical data",
 					),
 					vdom.H("li", map[string]any{
 						"className": "flex items-start gap-2",

tsunami/demo/githubaction/app.go

@@ -17,14 +17,37 @@ import (
 
 // Global atoms for config and data
 var (
-	pollIntervalAtom    = app.ConfigAtom("pollInterval", 5)
-	repositoryAtom      = app.ConfigAtom("repository", "wavetermdev/waveterm")
-	workflowAtom        = app.ConfigAtom("workflow", "build-helper.yml")
-	maxWorkflowRunsAtom = app.ConfigAtom("maxWorkflowRuns", 10)
-	workflowRunsAtom    = app.DataAtom("workflowRuns", []WorkflowRun{})
-	lastErrorAtom       = app.DataAtom("lastError", "")
-	isLoadingAtom       = app.DataAtom("isLoading", true)
-	lastRefreshTimeAtom = app.DataAtom("lastRefreshTime", time.Time{})
+	pollIntervalAtom = app.ConfigAtom("pollInterval", 5, &app.AtomMeta{
+		Desc:  "Polling interval for GitHub API requests",
+		Units: "s",
+		Min:   app.Ptr(1.0),
+		Max:   app.Ptr(300.0),
+	})
+	repositoryAtom = app.ConfigAtom("repository", "wavetermdev/waveterm", &app.AtomMeta{
+		Desc:    "GitHub repository in owner/repo format",
+		Pattern: `^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$`,
+	})
+	workflowAtom = app.ConfigAtom("workflow", "build-helper.yml", &app.AtomMeta{
+		Desc:    "GitHub Actions workflow file name",
+		Pattern: `^.+\.(yml|yaml)$`,
+	})
+	maxWorkflowRunsAtom = app.ConfigAtom("maxWorkflowRuns", 10, &app.AtomMeta{
+		Desc: "Maximum number of workflow runs to fetch",
+		Min:  app.Ptr(1.0),
+		Max:  app.Ptr(100.0),
+	})
+	workflowRunsAtom = app.DataAtom("workflowRuns", []WorkflowRun{}, &app.AtomMeta{
+		Desc: "List of GitHub Actions workflow runs",
+	})
+	lastErrorAtom = app.DataAtom("lastError", "", &app.AtomMeta{
+		Desc: "Last error message from GitHub API",
+	})
+	isLoadingAtom = app.DataAtom("isLoading", true, &app.AtomMeta{
+		Desc: "Loading state for workflow data fetch",
+	})
+	lastRefreshTimeAtom = app.DataAtom("lastRefreshTime", time.Time{}, &app.AtomMeta{
+		Desc: "Timestamp of last successful data refresh",
+	})
 )
 
 type WorkflowRun struct {
@@ -388,7 +411,7 @@ var App = app.DefineComponent("App",
 							vdom.H("span", map[string]any{
 								"className": "text-blue-400 mt-1",
 							}, "•"),
-							"Polls GitHub API every 5 seconds for real-time updates",
+							"Polls GitHub API every ", pollInterval, " seconds for real-time updates",
 						),
 						vdom.H("li", map[string]any{
 							"className": "flex items-start gap-2",

tsunami/demo/pomodoro/app.go

@@ -18,7 +18,12 @@ var (
 	BreakMode = Mode{Name: "Break", Duration: 5}
 
 	// Data atom to expose remaining seconds to external systems
-	remainingSecondsAtom = app.DataAtom("remainingSeconds", WorkMode.Duration*60)
+	remainingSecondsAtom = app.DataAtom("remainingSeconds", WorkMode.Duration*60, &app.AtomMeta{
+		Desc:  "Remaining seconds in current pomodoro timer",
+		Units: "s",
+		Min:   app.Ptr(0.0),
+		Max:   app.Ptr(3600.0),
+	})
 )
 
 type TimerDisplayProps struct {
@@ -34,7 +39,6 @@ type ControlButtonsProps struct {
 	OnMode    func(int) `json:"onMode"`
 }
 
-
 var TimerDisplay = app.DefineComponent("TimerDisplay",
 	func(props TimerDisplayProps) any {
 		minutes := props.RemainingSeconds / 60
@@ -151,7 +155,7 @@ var App = app.DefineComponent("App",
 			if !isRunning.Get() {
 				return
 			}
-			
+
 			// Calculate remaining time and update remainingSeconds
 			elapsed := time.Since(startTime.Current)
 			remaining := totalDuration.Current - elapsed
@@ -190,7 +194,7 @@ var App = app.DefineComponent("App",
 			),
 			TimerDisplay(TimerDisplayProps{
 				RemainingSeconds: remainingSecondsAtom.Get(),
-				Mode:            mode.Get(),
+				Mode:             mode.Get(),
 			}),
 			ControlButtons(ControlButtonsProps{
 				IsRunning: isRunning.Get(),

tsunami/demo/recharts/app.go

@@ -10,9 +10,16 @@ import (
 
 // Global atoms for config and data
 var (
-	chartDataAtom   = app.DataAtom("chartData", generateInitialData())
-	chartTypeAtom   = app.ConfigAtom("chartType", "line")
-	isAnimatingAtom = app.SharedAtom("isAnimating", false)
+	chartDataAtom = app.DataAtom("chartData", generateInitialData(), &app.AtomMeta{
+		Desc: "Chart data points for system metrics visualization",
+	})
+	chartTypeAtom = app.ConfigAtom("chartType", "line", &app.AtomMeta{
+		Desc: "Type of chart to display",
+		Enum: []string{"line", "area", "bar"},
+	})
+	isAnimatingAtom = app.ConfigAtom("isAnimating", false, &app.AtomMeta{
+		Desc: "Whether the chart is currently animating with live data",
+	})
 )
 
 type DataPoint struct {

tsunami/demo/tabletest/app.go

@@ -31,6 +31,8 @@ var sampleData = app.DataAtom("sampleData", []Person{
 	{Name: "Henry Taylor", Age: 33, Email: "[email protected]", City: "San Diego"},
 	{Name: "Ivy Chen", Age: 26, Email: "[email protected]", City: "Dallas"},
 	{Name: "Jack Anderson", Age: 31, Email: "[email protected]", City: "San Jose"},
+}, &app.AtomMeta{
+	Desc: "Sample person data for table display testing",
 })
 
 // The App component is the required entry point for every Tsunami application

tsunami/demo/tsunamiconfig/app.go

@@ -16,7 +16,10 @@ import (
 
 // Global atoms for config
 var (
-	serverURLAtom = app.ConfigAtom("serverURL", "")
+	serverURLAtom = app.ConfigAtom("serverURL", "", &app.AtomMeta{
+		Desc:    "Server URL for config API (can be full URL, hostname:port, or just port)",
+		Pattern: `^(https?://.*|[a-zA-Z0-9.-]+:\d+|\d+|[a-zA-Z0-9.-]+)$`,
+	})
 )
 
 type URLInputProps struct {

tsunami/engine/atomimpl.go

@@ -6,20 +6,33 @@ package engine
 import (
 	"encoding/json"
 	"fmt"
+	"reflect"
 	"sync"
 )
 
+// AtomMeta provides metadata about an atom for validation and documentation
+type AtomMeta struct {
+	Description string   // short, user-facing
+	Units       string   // "ms", "GiB", etc.
+	Min         *float64 // optional minimum (numeric types)
+	Max         *float64 // optional maximum (numeric types)
+	Enum        []string // allowed values if finite set
+	Pattern     string   // regex constraint for strings
+}
+
 type AtomImpl[T any] struct {
 	lock   *sync.Mutex
 	val    T
 	usedBy map[string]bool // component waveid -> true
+	meta   *AtomMeta       // optional metadata
 }
 
-func MakeAtomImpl[T any](initialVal T) *AtomImpl[T] {
+func MakeAtomImpl[T any](initialVal T, meta *AtomMeta) *AtomImpl[T] {
 	return &AtomImpl[T]{
 		lock:   &sync.Mutex{},
 		val:    initialVal,
 		usedBy: make(map[string]bool),
+		meta:   meta,
 	}
 }
 
@@ -84,3 +97,13 @@ func (a *AtomImpl[T]) GetUsedBy() []string {
 	}
 	return keys
 }
+
+func (a *AtomImpl[T]) GetMeta() *AtomMeta {
+	a.lock.Lock()
+	defer a.lock.Unlock()
+	return a.meta
+}
+
+func (a *AtomImpl[T]) GetAtomType() reflect.Type {
+	return reflect.TypeOf((*T)(nil)).Elem()
+}

tsunami/engine/hooks.go

@@ -77,7 +77,7 @@ func UseLocal(vc *RenderContextImpl, initialVal any) string {
 	atomName := "$local." + vc.GetCompWaveId() + "#" + strconv.Itoa(hookVal.Idx)
 	if !hookVal.Init {
 		hookVal.Init = true
-		atom := MakeAtomImpl(initialVal)
+		atom := MakeAtomImpl(initialVal, nil)
 		vc.Root.RegisterAtom(atomName, atom)
 		closedAtomName := atomName
 		hookVal.UnmountFn = func() {