command_catalog.go

package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"net/http"
	"net/url"
	"os"
	"sort"
	"strings"
	"time"

	"github.com/rest-sh/restish/cli"
	"github.com/rest-sh/restish/openapi"
	"github.com/spf13/cobra"
	"github.com/spf13/pflag"
)

const catalogSchemaVersion = "1"

// specHTTPClient fetches the OpenAPI spec for the command catalog and the
// help-context enrichment (help_context.go). Both call sites can now run
// from a --help invocation that used to be purely local and instant, so —
// like every other network client in this codebase (name_resolution.go,
// open_command.go, update.go) — this one carries an explicit timeout rather
// than blocking on http.DefaultClient's unbounded default.
var specHTTPClient = &http.Client{Timeout: 10 * time.Second}

type commandCatalog struct {
	Version    string                    `json:"version"`
	CLIVersion string                    `json:"cli_version"`
	Commands   []commandCatalogEntry     `json:"commands"`
	Shapes     map[string]map[string]any `json:"shapes"`
}

type commandCatalogEntry struct {
	Path          []string                 `json:"path"`
	Summary       string                   `json:"summary,omitempty"`
	Arguments     []commandCatalogArgument `json:"arguments,omitempty"`
	Flags         []commandCatalogFlag     `json:"flags,omitempty"`
	OutputShape   string                   `json:"output_shape"`
	Destructive   bool                     `json:"destructive"`
	ResolvesNames bool                     `json:"resolvesNames,omitempty"`
	RequiresAuth  bool                     `json:"requires_auth"`
	AgentFriendly bool                     `json:"agent_friendly"`
	// Stage marks non-GA commands ("beta"); GA entries omit it. Additive, so
	// the catalog schema version is unchanged.
	Stage       string `json:"stage,omitempty"`
	EarlyAccess string `json:"early_access,omitempty"`
	// Examples, Notes, and Related come from the curated command docs
	// (command_docs.go); additive, so the catalog schema version is unchanged.
	Examples []commandCatalogExample `json:"examples,omitempty"`
	Notes    string                  `json:"notes,omitempty"`
	Related  []string                `json:"related,omitempty"`
	// Keywords are the curated search words from the command doc; additive.
	Keywords []string `json:"keywords,omitempty"`
}

type commandCatalogExample struct {
	Description string `json:"description"`
	Command     string `json:"command"`
	Output      string `json:"output,omitempty"`
}

type commandCatalogArgument struct {
	Name        string      `json:"name"`
	Type        string      `json:"type"`
	Location    string      `json:"location"`
	Required    bool        `json:"required"`
	Description string      `json:"description,omitempty"`
	Example     interface{} `json:"example,omitempty"`
	MediaType   string      `json:"media_type,omitempty"`
}

type commandCatalogFlag struct {
	Name        string      `json:"name"`
	Type        string      `json:"type"`
	Default     interface{} `json:"default,omitempty"`
	Description string      `json:"description,omitempty"`
	Example     interface{} `json:"example,omitempty"`
	Required    bool        `json:"required"`
	SafetyRole  string      `json:"safety_role,omitempty"`
}

var requiredOperationFlags = map[string]map[string]bool{
	"cancel-invite":         {"idempotency-key": true},
	"import-cloudflow-flow": {"idempotency-key": true},
	"resend-invite":         {"idempotency-key": true},
}

func registerCommandCatalog() {
	command := &cobra.Command{
		Use:   "commands",
		Short: "Print the machine-readable command catalog, or search it in plain words",
		Long: "Print the machine-readable command catalog (every command with its arguments, flags, " +
			"and curated examples), or pass --search to find the command for a task described in " +
			"plain words — the catalog is large, so search first and read one command's --help " +
			"rather than loading the whole catalog.",
		Args: cobra.NoArgs,
		RunE: func(command *cobra.Command, args []string) error {
			apiCommand := findDCICommand()
			if apiCommand == nil {
				return errors.New("DCI API command tree is unavailable")
			}
			api, err := loadCatalogAPI(command)
			if err != nil {
				return fmt.Errorf("load DCI command catalog: %w", err)
			}
			catalog := buildCommandCatalog(api)
			query, searching := commandSearchRequested(command)
			includeBeta, _ := command.Flags().GetBool("beta")
			// Search always covers beta commands: a hit it hides is a command
			// the caller never learns exists. Results carry stage: beta and the
			// early-access note, so a gated hit is still an informed one.
			if includeBeta || searching {
				betaAPI, err := loadBetaAPI()
				if err != nil {
					return fmt.Errorf("load beta command catalog: %w", err)
				}
				betaEntries := betaCatalogEntries(betaAPI)
				for index := range betaEntries {
					applyCommandDocToCatalogEntry(&betaEntries[index])
				}
				catalog.Commands = append(catalog.Commands, betaEntries...)
				sort.Slice(catalog.Commands, func(i, j int) bool {
					return strings.Join(catalog.Commands[i].Path, " ") < strings.Join(catalog.Commands[j].Path, " ")
				})
			}
			if searching {
				return runCommandSearch(command, catalog.Commands, query, os.Stdout)
			}
			encoder := json.NewEncoder(os.Stdout)
			encoder.SetIndent("", "  ")
			return encoder.Encode(catalog)
		},
	}
	command.Flags().Bool("json", false, "Emit JSON (the catalog's stable wire format; with --search, the ranked results as JSON even at a terminal)")
	command.Flags().Bool("beta", false, "Include beta commands (invoked as dci beta <command>; entries carry stage: beta)")
	registerCommandSearchFlags(command)
	cli.Root.AddCommand(command)
}

func loadCatalogAPI(command *cobra.Command) (cli.API, error) {
	base, err := apiBase()
	if err != nil {
		return cli.API{}, err
	}
	response, err := fetchOpenAPISpec(command, base)
	if err != nil {
		return cli.API{}, err
	}
	defer response.Body.Close()
	entrypoint, err := url.Parse(base + "/")
	if err != nil {
		return cli.API{}, err
	}
	specURL, err := url.Parse(base + "/openapi.yaml")
	if err != nil {
		return cli.API{}, err
	}
	return openapi.New().Load(*entrypoint, *specURL, response)
}

// fetchOpenAPISpec issues the GET request for the DCI OpenAPI spec that both
// the command catalog and the help-context enrichment (help_context.go) need.
// The caller owns closing the response body.
func fetchOpenAPISpec(command *cobra.Command, base string) (*http.Response, error) {
	specURL, err := url.Parse(base + "/openapi.yaml")
	if err != nil {
		return nil, err
	}
	ctx := command.Context()
	if ctx == nil {
		// cobra only populates Context() once Execute()/ExecuteContext() has
		// run; a command built directly (tests, or a HelpFunc invoked before
		// dispatch) can still have a nil ctx, and net/http rejects that with
		// an opaque "nil Context" error instead of just using Background().
		ctx = context.Background()
	}
	request, err := http.NewRequestWithContext(ctx, http.MethodGet, specURL.String(), nil)
	if err != nil {
		return nil, err
	}
	response, err := specHTTPClient.Do(request)
	if err != nil {
		return nil, err
	}
	if response.StatusCode < 200 || response.StatusCode >= 300 {
		response.Body.Close()
		return nil, fmt.Errorf("OpenAPI endpoint returned HTTP %d", response.StatusCode)
	}
	return response, nil
}

func buildCommandCatalog(api cli.API) commandCatalog {
	resolutionTargets := buildResolutionIndex(api.Operations)
	entries := make([]commandCatalogEntry, 0, len(api.Operations)+len(cli.Root.Commands()))
	for _, operation := range api.Operations {
		if operation.Hidden {
			continue
		}
		flags := make([]commandCatalogFlag, 0, len(operation.QueryParams)+len(operation.HeaderParams)+6)
		for _, parameter := range append(append([]*cli.Param{}, operation.QueryParams...), operation.HeaderParams...) {
			flags = append(flags, commandCatalogFlag{
				Name:        "--" + parameter.OptionName(),
				Type:        parameter.Type,
				Default:     parameter.Default,
				Description: parameter.Description,
				Example:     parameter.Example,
				Required:    requiredOperationFlags[operation.Name][parameter.OptionName()],
			})
		}
		flags = appendUniqueCatalogFlags(flags, agentContractCatalogFlags())
		sort.Slice(flags, func(i, j int) bool { return flags[i].Name < flags[j].Name })
		_, resolvesNames := resolutionTargets[operation.Name]
		entries = append(entries, commandCatalogEntry{
			Path:          []string{operation.Name},
			Summary:       operation.Short,
			Arguments:     catalogArgumentsForOperation(operation),
			Flags:         flags,
			OutputShape:   "api_response",
			Destructive:   isDestructiveOperation(operation),
			ResolvesNames: resolvesNames,
			RequiresAuth:  true,
			AgentFriendly: true,
		})
	}
	for _, command := range cli.Root.Commands() {
		// "ai" stays out of the machine catalog: it is the interactive agent
		// session itself — an external agent driving it would nest agents
		// (the session's own tool layer deny-lists it for the same reason).
		if command.Hidden || command.Name() == "dci" || command.Name() == "help" ||
			command.Name() == "completion" || command.Name() == "ai" {
			continue
		}
		entries = append(entries, localCatalogEntries(command, nil)...)
	}
	entries = append(entries, questionCommandCatalogEntries()...)
	for index := range entries {
		applyCommandDocToCatalogEntry(&entries[index])
	}
	sort.Slice(entries, func(i, j int) bool {
		return strings.Join(entries[i].Path, " ") < strings.Join(entries[j].Path, " ")
	})
	return commandCatalog{
		Version:    catalogSchemaVersion,
		CLIVersion: version,
		Commands:   entries,
		Shapes: map[string]map[string]any{
			"api_response": {
				"description": "The response shape declared by the DCI OpenAPI operation",
			},
			"structured_error": {
				"required": []string{"error.code", "error.message", "error.retryable"},
			},
		},
	}
}

// applyCommandDocToCatalogEntry copies the curated examples, notes, and
// related commands onto a catalog entry and replaces the body argument's
// schema-synthesized example with the first curated example's parsed body.
// Drafts and commands without a doc leave the entry unchanged.
func applyCommandDocToCatalogEntry(entry *commandCatalogEntry) {
	doc, ok := lookupCommandDoc(strings.Join(entry.Path, " "))
	if !ok {
		return
	}
	for _, example := range doc.Examples {
		entry.Examples = append(entry.Examples, commandCatalogExample{
			Description: example.Description,
			Command:     strings.Join(strings.Fields(example.Command), " "),
			Output:      example.Output,
		})
	}
	entry.Notes = doc.Notes
	entry.Related = doc.Related
	entry.Keywords = doc.Keywords
	positional := 0
	for _, argument := range entry.Arguments {
		if argument.Location == "path" {
			positional++
		}
	}
	for index := range entry.Arguments {
		if entry.Arguments[index].Location != "body" {
			continue
		}
		if body, found := commandDocBodyExample(doc, positional); found {
			entry.Arguments[index].Example = body
		}
	}
}

// betaCatalogEntries renders the embedded beta surface for `dci commands
// --beta`. Beta entries are invoked as `dci beta <name>` (two-element path),
// carry stage: beta plus the gating early-access flag, and never mark
// idempotency-key flags required — the CLI auto-generates the header.
func betaCatalogEntries(api cli.API) []commandCatalogEntry {
	entries := make([]commandCatalogEntry, 0, len(api.Operations))
	for _, operation := range api.Operations {
		if operation.Hidden {
			continue
		}
		flags := make([]commandCatalogFlag, 0, len(operation.QueryParams)+len(operation.HeaderParams)+6)
		for _, parameter := range append(append([]*cli.Param{}, operation.QueryParams...), operation.HeaderParams...) {
			flags = append(flags, commandCatalogFlag{
				Name:        "--" + parameter.OptionName(),
				Type:        parameter.Type,
				Default:     parameter.Default,
				Description: parameter.Description,
				Example:     parameter.Example,
			})
		}
		flags = appendUniqueCatalogFlags(flags, agentContractCatalogFlags())
		sort.Slice(flags, func(i, j int) bool { return flags[i].Name < flags[j].Name })
		entries = append(entries, commandCatalogEntry{
			Path:          []string{"beta", operation.Name},
			Summary:       operation.Short,
			Arguments:     catalogArgumentsForOperation(operation),
			Flags:         flags,
			OutputShape:   "api_response",
			Destructive:   isDestructiveOperation(operation),
			RequiresAuth:  true,
			AgentFriendly: true,
			Stage:         "beta",
			EarlyAccess:   betaEarlyAccessByCommand[operation.Name],
		})
	}
	return entries
}

func appendUniqueCatalogFlags(existing []commandCatalogFlag, additional []commandCatalogFlag) []commandCatalogFlag {
	seen := make(map[string]bool, len(existing)+len(additional))
	for index, flag := range existing {
		seen[flag.Name] = true
		for _, candidate := range additional {
			if candidate.Name == flag.Name && existing[index].SafetyRole == "" {
				existing[index].SafetyRole = candidate.SafetyRole
			}
		}
	}
	for _, flag := range additional {
		if seen[flag.Name] {
			continue
		}
		seen[flag.Name] = true
		existing = append(existing, flag)
	}
	return existing
}

func catalogArgumentsForOperation(operation cli.Operation) []commandCatalogArgument {
	arguments := make([]commandCatalogArgument, 0, len(operation.PathParams)+1)
	for _, parameter := range operation.PathParams {
		arguments = append(arguments, commandCatalogArgument{
			Name:        parameter.OptionName(),
			Type:        parameter.Type,
			Location:    "path",
			Required:    true,
			Description: parameter.Description,
			Example:     parameter.Example,
		})
	}
	if operation.BodyMediaType != "" {
		var example interface{}
		if len(operation.Examples) > 0 {
			example = operation.Examples[0]
		}
		arguments = append(arguments, commandCatalogArgument{
			Name:        "body",
			Type:        "request_body",
			Location:    "body",
			Required:    true,
			Description: "Request body as shorthand arguments or stdin",
			Example:     example,
			MediaType:   operation.BodyMediaType,
		})
	}
	return arguments
}

func localCatalogEntries(command *cobra.Command, parent []string) []commandCatalogEntry {
	path := append(append([]string{}, parent...), command.Name())
	children := command.Commands()
	entries := make([]commandCatalogEntry, 0)
	if command.Runnable() || len(children) == 0 {
		entries = append(entries, commandCatalogEntry{
			Path:          path,
			Summary:       command.Short,
			Flags:         catalogFlagsFromFlagSet(command.Flags()),
			OutputShape:   "local_command_response",
			Destructive:   false,
			RequiresAuth:  false,
			AgentFriendly: true,
		})
	}
	for _, child := range children {
		if child.Hidden || child.Name() == "help" {
			continue
		}
		entries = append(entries, localCatalogEntries(child, path)...)
	}
	return entries
}

func catalogFlagsFromFlagSet(flags *pflag.FlagSet) []commandCatalogFlag {
	result := make([]commandCatalogFlag, 0)
	flags.VisitAll(func(flag *pflag.Flag) {
		if flag.Hidden || flag.Name == "help" {
			return
		}
		result = append(result, commandCatalogFlag{
			Name:        "--" + flag.Name,
			Type:        flag.Value.Type(),
			Default:     flag.DefValue,
			Description: flag.Usage,
		})
	})
	sort.Slice(result, func(i, j int) bool { return result[i].Name < result[j].Name })
	return result
}

func agentContractCatalogFlags() []commandCatalogFlag {
	flags := []commandCatalogFlag{
		{Name: "--dry-run", Type: "bool", Default: false, Description: "Preview a destructive operation without executing it", SafetyRole: "preview_before_execution"},
		{Name: "--output", Type: "string", Description: "Select table, JSON, YAML, automatic, or TOON output"},
		{Name: "--yes", Type: "bool", Default: false, Description: "Confirm a destructive operation", SafetyRole: "destructive_confirmation"},
	}
	apiCommand := findDCICommand()
	if apiCommand == nil {
		return flags
	}
	for _, optional := range []commandCatalogFlag{
		{Name: "--exclude", Type: "string", Description: "Exclude response fields"},
		{Name: "--fields", Type: "string", Description: "Select response fields"},
	} {
		if apiCommand.PersistentFlags().Lookup(strings.TrimPrefix(optional.Name, "--")) != nil {
			flags = append(flags, optional)
		}
	}
	return flags
}