tutti/packages/appcli/core/manifest.go

package core

import (
	"encoding/json"
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"regexp"
	"strings"
)

const (
	ManifestSchemaVersion = "tutti.app.cli.v1"
	maxManifestBytes      = 256 * 1024
	DefaultTimeoutMs      = 30000
	MinTimeoutMs          = 1000
	MaxTimeoutMs          = 600000
)

const (
	CommandVisibilityPublic      CommandVisibility = "public"
	CommandVisibilityIntegration CommandVisibility = "integration"
)

var segmentPattern = regexp.MustCompile(`^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$`)

type Manifest struct {
	SchemaVersion string                 `json:"schemaVersion"`
	Scope         string                 `json:"scope"`
	Description   string                 `json:"description,omitempty"`
	Documentation *ManifestDocumentation `json:"documentation,omitempty"`
	Commands      []ManifestCommand      `json:"commands"`
}

type ManifestDocumentation struct {
	File string `json:"file"`
}

type ManifestCommand struct {
	Path        []string                  `json:"path"`
	Summary     string                    `json:"summary"`
	Description string                    `json:"description,omitempty"`
	Visibility  CommandVisibility         `json:"visibility,omitempty"`
	Execution   *ManifestCommandExecution `json:"execution,omitempty"`
	InputSchema map[string]any            `json:"inputSchema,omitempty"`
	Output      ManifestCommandOutput     `json:"output"`
	Handler     ManifestCommandHandler    `json:"handler"`
}

type ManifestCommandExecution struct {
	Mode CommandExecutionMode `json:"mode"`
}

type ManifestCommandOutput struct {
	DefaultMode OutputMode           `json:"defaultMode"`
	JSON        bool                 `json:"json"`
	Table       *ManifestTableOutput `json:"table,omitempty"`
}

type ManifestTableOutput struct {
	Columns []TableColumn `json:"columns"`
}

type ManifestCommandHandler struct {
	Kind      string `json:"kind"`
	Method    string `json:"method"`
	Path      string `json:"path"`
	TimeoutMs int    `json:"timeoutMs,omitempty"`
}

func ReadManifest(path string) (Manifest, error) {
	file, err := os.Open(path)
	if err != nil {
		return Manifest{}, fmt.Errorf("read cli manifest: %w", err)
	}
	defer file.Close()

	info, err := file.Stat()
	if err != nil {
		return Manifest{}, fmt.Errorf("stat cli manifest: %w", err)
	}
	if info.Size() > maxManifestBytes {
		return Manifest{}, fmt.Errorf("cli manifest exceeds maximum size %d", maxManifestBytes)
	}

	decoder := json.NewDecoder(file)
	decoder.UseNumber()
	var manifest Manifest
	if err := decoder.Decode(&manifest); err != nil {
		return Manifest{}, fmt.Errorf("parse cli manifest json: %w", err)
	}
	if err := ValidateManifest(manifest); err != nil {
		return Manifest{}, err
	}
	return manifest, nil
}

func ValidateManifest(manifest Manifest) error {
	if !isSupportedManifestSchemaVersion(strings.TrimSpace(manifest.SchemaVersion)) {
		return fmt.Errorf("unsupported cli manifest schema version %q", manifest.SchemaVersion)
	}
	scope := strings.TrimSpace(manifest.Scope)
	if err := validateSegment(scope, "scope"); err != nil {
		return err
	}
	if manifest.Documentation != nil {
		if err := validatePackageRelativePath(manifest.Documentation.File, "documentation.file"); err != nil {
			return err
		}
	}
	if len(manifest.Commands) == 0 {
		return errors.New("cli manifest commands is required")
	}

	seenPaths := map[string]struct{}{}
	for index, command := range manifest.Commands {
		location := fmt.Sprintf("commands[%d]", index)
		if len(command.Path) == 0 {
			return fmt.Errorf("cli manifest %s.path is required", location)
		}
		if command.Path[0] == scope {
			return fmt.Errorf("cli manifest %s.path must not repeat scope", location)
		}
		for segmentIndex, segment := range command.Path {
			if err := validateSegment(strings.TrimSpace(segment), fmt.Sprintf("%s.path[%d]", location, segmentIndex)); err != nil {
				return err
			}
		}
		pathKey := strings.Join(command.Path, ".")
		if _, ok := seenPaths[pathKey]; ok {
			return fmt.Errorf("cli manifest command path %q is duplicated", strings.Join(command.Path, " "))
		}
		seenPaths[pathKey] = struct{}{}

		if strings.TrimSpace(command.Summary) == "" {
			return fmt.Errorf("cli manifest %s.summary is required", location)
		}
		if err := validateVisibility(command.Visibility, location+".visibility"); err != nil {
			return err
		}
		if err := validateExecution(command.Execution, command.InputSchema, command.Output, location+".execution"); err != nil {
			return err
		}
		if err := validateInputSchema(command.InputSchema, location+".inputSchema"); err != nil {
			return err
		}
		if err := validateOutput(command.Output, location+".output"); err != nil {
			return err
		}
		if err := validateHandler(command.Handler, location+".handler"); err != nil {
			return err
		}
	}
	return nil
}

func validateExecution(execution *ManifestCommandExecution, inputSchema map[string]any, output ManifestCommandOutput, location string) error {
	if execution == nil {
		return nil
	}
	if execution.Mode != CommandExecutionModeWait {
		return fmt.Errorf("cli manifest %s.mode must be wait", location)
	}
	if output.DefaultMode != OutputModeJSON || !output.JSON {
		return fmt.Errorf("cli manifest %s mode wait requires json default output", location)
	}
	properties, _ := inputSchema["properties"].(map[string]any)
	if _, declared := properties["timeout-ms"]; declared {
		return fmt.Errorf("cli manifest %s mode wait reserves --timeout-ms for the total CLI wait timeout", location)
	}
	return nil
}

func NormalizeVisibility(visibility CommandVisibility) CommandVisibility {
	switch CommandVisibility(strings.TrimSpace(string(visibility))) {
	case "", CommandVisibilityPublic:
		return CommandVisibilityPublic
	case CommandVisibilityIntegration:
		return CommandVisibilityIntegration
	default:
		return visibility
	}
}

func validateVisibility(visibility CommandVisibility, location string) error {
	switch NormalizeVisibility(visibility) {
	case CommandVisibilityPublic, CommandVisibilityIntegration:
		return nil
	default:
		return fmt.Errorf("cli manifest %s must be public or integration", location)
	}
}

func isSupportedManifestSchemaVersion(schemaVersion string) bool {
	return schemaVersion == ManifestSchemaVersion
}

func validateSegment(segment string, location string) error {
	if segment == "" {
		return fmt.Errorf("cli manifest %s is required", location)
	}
	if strings.HasPrefix(segment, "--") || strings.Contains(segment, " ") || !segmentPattern.MatchString(segment) {
		return fmt.Errorf("cli manifest %s must contain lowercase letters, numbers, and hyphen only", location)
	}
	return nil
}

func validatePackageRelativePath(value string, location string) error {
	value = strings.TrimSpace(value)
	if value == "" {
		return fmt.Errorf("cli manifest %s is required", location)
	}
	if filepath.IsAbs(value) || strings.HasPrefix(value, `\`) {
		return fmt.Errorf("cli manifest %s must be a relative package path", location)
	}
	for _, part := range strings.FieldsFunc(value, func(char rune) bool {
		return char == '/' || char == '\\'
	}) {
		if part == ".." {
			return fmt.Errorf("cli manifest %s must not contain parent path segments", location)
		}
	}
	return nil
}

func validateInputSchema(schema map[string]any, location string) error {
	if len(schema) == 0 {
		return nil
	}
	if schemaType(schema) != "object" {
		return fmt.Errorf("cli manifest %s.type must be object", location)
	}
	properties, ok := schema["properties"].(map[string]any)
	if !ok {
		return fmt.Errorf("cli manifest %s.properties is required", location)
	}
	for name, property := range properties {
		if err := validateSegment(strings.TrimSpace(name), location+".properties"); err != nil {
			return err
		}
		propertyMap, ok := property.(map[string]any)
		if !ok {
			return fmt.Errorf("cli manifest %s.properties.%s must be an object", location, name)
		}
		propertyType := schemaType(propertyMap)
		switch propertyType {
		case "string", "boolean", "integer":
		default:
			return fmt.Errorf("cli manifest %s.properties.%s.type must be string, boolean, or integer", location, name)
		}
		for key := range propertyMap {
			if key != "type" && key != "description" && key != "enum" && key != "default" {
				return fmt.Errorf("cli manifest %s.properties.%s has unsupported key %q", location, name, key)
			}
		}
		if enum, ok := propertyMap["enum"]; ok {
			if err := validateInputSchemaEnum(propertyType, enum, fmt.Sprintf("%s.properties.%s.enum", location, name)); err != nil {
				return err
			}
		}
		if defaultValue, ok := propertyMap["default"]; ok {
			if err := validateInputSchemaValue(propertyType, defaultValue, fmt.Sprintf("%s.properties.%s.default", location, name)); err != nil {
				return err
			}
		}
	}
	for _, required := range RequiredNames(schema) {
		if _, ok := properties[required]; !ok {
			return fmt.Errorf("cli manifest %s.required contains unknown property %q", location, required)
		}
	}
	for key := range schema {
		if key != "type" && key != "properties" && key != "required" {
			return fmt.Errorf("cli manifest %s has unsupported key %q", location, key)
		}
	}
	return nil
}

func validateInputSchemaEnum(typeName string, value any, location string) error {
	items, ok := value.([]any)
	if !ok {
		return fmt.Errorf("cli manifest %s must be an array", location)
	}
	for index, item := range items {
		if err := validateInputSchemaValue(typeName, item, fmt.Sprintf("%s[%d]", location, index)); err != nil {
			return err
		}
	}
	return nil
}

func validateInputSchemaValue(typeName string, value any, location string) error {
	switch typeName {
	case "string":
		if _, ok := value.(string); !ok {
			return fmt.Errorf("cli manifest %s must be a string", location)
		}
	case "boolean":
		if _, ok := value.(bool); !ok {
			return fmt.Errorf("cli manifest %s must be a boolean", location)
		}
	case "integer":
		switch typed := value.(type) {
		case int, int64:
			return nil
		case float64:
			if typed == float64(int64(typed)) {
				return nil
			}
		case json.Number:
			if _, err := typed.Int64(); err == nil {
				return nil
			}
		}
		return fmt.Errorf("cli manifest %s must be an integer", location)
	}
	return nil
}

func validateOutput(output ManifestCommandOutput, location string) error {
	switch output.DefaultMode {
	case OutputModeJSON:
		if !output.JSON {
			return fmt.Errorf("cli manifest %s.json must be true when defaultMode is json", location)
		}
	case OutputModeTable:
		if output.Table == nil || len(output.Table.Columns) == 0 {
			return fmt.Errorf("cli manifest %s.table.columns is required when defaultMode is table", location)
		}
	case "":
		return fmt.Errorf("cli manifest %s.defaultMode is required", location)
	default:
		return fmt.Errorf("cli manifest %s.defaultMode must be json or table", location)
	}
	if output.Table != nil {
		seen := map[string]struct{}{}
		for _, column := range output.Table.Columns {
			key := strings.TrimSpace(column.Key)
			if err := validateSegment(key, location+".table.columns.key"); err != nil {
				return err
			}
			if strings.TrimSpace(column.Label) == "" {
				return fmt.Errorf("cli manifest %s.table.columns.label is required", location)
			}
			if _, ok := seen[key]; ok {
				return fmt.Errorf("cli manifest %s.table.columns key %q is duplicated", location, key)
			}
			seen[key] = struct{}{}
		}
	}
	return nil
}

func validateHandler(handler ManifestCommandHandler, location string) error {
	if strings.TrimSpace(handler.Kind) != "http" {
		return fmt.Errorf("cli manifest %s.kind must be http", location)
	}
	if strings.TrimSpace(handler.Method) != "POST" {
		return fmt.Errorf("cli manifest %s.method must be POST", location)
	}
	handlerPath := strings.TrimSpace(handler.Path)
	if !strings.HasPrefix(handlerPath, "/tutti/cli/") {
		return fmt.Errorf("cli manifest %s.path must start with /tutti/cli/", location)
	}
	timeoutMs := NormalizedTimeoutMs(handler.TimeoutMs)
	if timeoutMs < MinTimeoutMs || timeoutMs > MaxTimeoutMs {
		return fmt.Errorf("cli manifest %s.timeoutMs must be between %d and %d", location, MinTimeoutMs, MaxTimeoutMs)
	}
	return nil
}

func NormalizedTimeoutMs(value int) int {
	if value == 0 {
		return DefaultTimeoutMs
	}
	return value
}

func schemaType(schema map[string]any) string {
	value, _ := schema["type"].(string)
	return strings.TrimSpace(value)
}

func RequiredNames(schema map[string]any) []string {
	value, ok := schema["required"]
	if !ok {
		return nil
	}
	switch typed := value.(type) {
	case []string:
		return append([]string(nil), typed...)
	case []any:
		names := make([]string, 0, len(typed))
		for _, item := range typed {
			if name, ok := item.(string); ok {
				names = append(names, name)
			}
		}
		return names
	default:
		return nil
	}
}

func PackageRelativePath(packageDir string, manifestPath string) (string, error) {
	manifestPath = strings.TrimSpace(manifestPath)
	if manifestPath == "" {
		return "", errors.New("cli manifest path is required")
	}
	if filepath.IsAbs(manifestPath) || strings.HasPrefix(manifestPath, `\`) {
		return "", errors.New("cli manifest path must be relative")
	}
	for _, part := range strings.FieldsFunc(manifestPath, func(char rune) bool {
		return char == '/' || char == '\\'
	}) {
		if part == ".." {
			return "", errors.New("cli manifest path must not contain parent path segments")
		}
	}
	return filepath.Join(packageDir, filepath.FromSlash(manifestPath)), nil
}