toolgen

type FlagDef struct {
	// Name is the flag name.
	Name string

	// Type is the JSON schema type.
	Type string

	// ItemsType is the JSON schema type for array items (e.g., "string", "integer").
	// Only populated when Type is "array".
	ItemsType string

	// Description describes the flag.
	Description string

	// Required indicates if this flag is required.
	Required bool

	// Default is the default value.
	Default any

	// AppliesToSubcommands lists which subcommands this flag applies to.
	// Empty means it applies to all subcommands.
	AppliesToSubcommands []string
}

type OutputChunk struct {
	ToolID string // Identifier for the tool that produced this output (for correlation)
	Source string // "stdout" or "stderr"
	Chunk  string // The actual output content
}

type Parameter struct {
	Name        string
	Type        string // JSON schema type: "string", "integer", "boolean", "array", "object"
	Description string
	Required    bool
	Default     any
	Enum        []string   // Valid values for enum types
	Items       *Parameter // For array types
}

type SubcommandDef struct {
	// Name is the subcommand name (e.g., "deployment", "restart", "encrypt").
	Name string

	// Description describes what this subcommand does.
	Description string

	// CommandParts are the full command parts for execution.
	CommandParts []string

	// Flags contains metadata about flags specific to or modified by this subcommand.
	Flags map[string]*FlagDef
}

type ToolDefinition struct {
	// Name is the tool identifier (e.g., "ksail_cluster_create").
	Name string

	// Description provides context for the AI about what the tool does.
	Description string

	// Parameters is a map of parameter names to their JSON schema properties.
	// Format: map[paramName]map[string]any where inner map has "type", "description", etc.
	Parameters map[string]any

	// CommandPath is the full command path (e.g., "ksail cluster create").
	CommandPath string

	// CommandParts contains the command split into parts (e.g., ["ksail", "cluster", "create"]).
	CommandParts []string

	// RequiresPermission indicates if this tool performs edit operations.
	RequiresPermission bool

	// IsConsolidated indicates if this tool represents multiple subcommands.
	IsConsolidated bool

	// SubcommandParam is the name of the parameter that selects the subcommand.
	// Only set when IsConsolidated is true (e.g., "resource_type", "action", "operation").
	SubcommandParam string

	// Subcommands maps subcommand names to their metadata.
	// Only populated when IsConsolidated is true.
	Subcommands map[string]*SubcommandDef
}

type ToolOptions struct {
	// ExcludeCommands is a list of command paths to exclude (e.g., "ksail chat").
	ExcludeCommands []string
	// IncludeHidden includes hidden commands in tool generation.
	IncludeHidden bool
	// CommandTimeout is the timeout for command execution.
	CommandTimeout time.Duration
	// WorkingDirectory is the directory to run commands in.
	WorkingDirectory string
	// OutputChan receives real-time output chunks from running commands.
	// If nil, output is only available after command completion.
	OutputChan chan<- OutputChunk
	// Logger is used for debug logging during command execution.
	// If nil, no logging is performed.
	Logger *slog.Logger
}