schema

Documentation

Overview

Package schema provides import-isolated command discoverability contracts.

It reflects Cobra command trees into ax-native schema output and a lightweight MCP-compatible adapter shape without importing the root ax runtime facade.

Index

• Constants
• func NewSchemaCommand(root *cobra.Command, opts ...Option) *cobra.Command
• func WithNonDeterministicFields[T any](cmd *cobra.Command)
• type CommandSchema
• type ErrorSchemaInfo
• type FlagSchema
• type MCPSchema
  • func BuildMCPSchema(root *cobra.Command) MCPSchema
• type MCPTool
• type Option
  • func WithSchemaVersion(version string) Option
• type Schema
  • func BuildSchema(root *cobra.Command, opts ...Option) Schema

Examples

• BuildMCPSchema
• BuildSchema

Constants

const SchemaVersion = contract.ErrorSchemaVersion

SchemaVersion is the current SemVer version for ax-native schemas.

Functions

func NewSchemaCommand

func NewSchemaCommand(root *cobra.Command, opts ...Option) *cobra.Command

NewSchemaCommand builds the reserved __schema command.

func WithNonDeterministicFields

func WithNonDeterministicFields[T any](cmd *cobra.Command)

WithNonDeterministicFields registers cmd as emitting the standard success envelope for T. It adds the built-in meta.* locators and records exported fields of T marked ax:"nondeterministic" as data.* locators. Reflection runs once at registration time; a nil command is ignored.

Types

type CommandSchema

type CommandSchema struct {
	Use                    string          `json:"use"`
	Short                  string          `json:"short,omitempty"`
	Long                   string          `json:"long,omitempty"`
	Example                string          `json:"example,omitempty"`
	Flags                  []FlagSchema    `json:"flags,omitempty"`
	Commands               []CommandSchema `json:"commands,omitempty"`
	NonDeterministicFields []string        `json:"non_deterministic_fields"`
}

CommandSchema describes a Cobra command and its direct children.

type ErrorSchemaInfo

type ErrorSchemaInfo struct {
	SchemaVersion          string   `json:"schema_version"`
	Required               []string `json:"required"`
	Optional               []string `json:"optional"`
	NonDeterministicFields []string `json:"non_deterministic_fields"`
}

ErrorSchemaInfo describes the shared stderr error envelope.

type FlagSchema

type FlagSchema struct {
	Name      string `json:"name"`
	Shorthand string `json:"shorthand,omitempty"`
	Type      string `json:"type"`
	Default   string `json:"default,omitempty"`
	Usage     string `json:"usage,omitempty"`
	Required  bool   `json:"required,omitempty"`
}

FlagSchema describes a command flag.

type MCPSchema

type MCPSchema struct {
	Tools []MCPTool `json:"tools"`
}

MCPSchema is the lightweight MCP-compatible adapter shape.

func BuildMCPSchema

func BuildMCPSchema(root *cobra.Command) MCPSchema

BuildMCPSchema adapts the command tree to a simple MCP tools list.

Example

package main

import (
	"fmt"

	"github.com/spf13/cobra"

	"github.com/rshade/ax-go/schema"
)

func main() {
	root := &cobra.Command{
		Use:   "app",
		Short: "test app",
	}
	root.Flags().String("config", "", "config file")

	got := schema.BuildMCPSchema(root)
	fmt.Println(got.Tools[0].Name)
	fmt.Println(got.Tools[0].InputSchema["type"])
}

Output:
app
object

type MCPTool

type MCPTool struct {
	Name                   string         `json:"name"`
	Description            string         `json:"description,omitempty"`
	InputSchema            map[string]any `json:"inputSchema"`
	NonDeterministicFields []string       `json:"nonDeterministicFields"`
}

MCPTool describes one command as an MCP-compatible tool.

type Option

type Option func(*options)

Option configures BuildSchema and NewSchemaCommand.

func WithSchemaVersion

func WithSchemaVersion(version string) Option

WithSchemaVersion sets the tool version reported by __schema.

type Schema

type Schema struct {
	SchemaVersion string          `json:"schema_version"`
	Tool          string          `json:"tool"`
	Version       string          `json:"version"`
	ModeDetection string          `json:"mode_detection"`
	Command       CommandSchema   `json:"command"`
	ErrorEnvelope ErrorSchemaInfo `json:"error_envelope"`
}

Schema is the ax-native reflective JSON tree emitted by __schema.

func BuildSchema

func BuildSchema(root *cobra.Command, opts ...Option) Schema

BuildSchema reflects a Cobra command tree into the ax-native schema.

Example

package main

import (
	"fmt"

	"github.com/spf13/cobra"

	"github.com/rshade/ax-go/schema"
)

func main() {
	root := &cobra.Command{
		Use:     "app",
		Short:   "test app",
		Example: "app run",
	}
	root.Flags().String("config", "", "config file")

	got := schema.BuildSchema(root, schema.WithSchemaVersion("v0.1.0"))
	fmt.Println(got.Tool)
	fmt.Println(got.Version)
	fmt.Println(got.Command.Flags[0].Name)
}

Output:
app
v0.1.0
config