market

type CLIFlagHint struct {
	Shorthand string `json:"shorthand"`
	Alias     string `json:"alias"`
}

type CLIFlagOverride struct {
	Alias string `json:"alias"`
	// Aliases registers additional hidden CLI flag names for the same MCP
	// parameter. Use to preserve legacy flag names when migrating from
	// hardcoded commands (mirrors cmdutil.ValidateRequiredFlagWithAliases /
	// cmdutil.FlagOrFallback). All entries are registered as hidden flags
	// (not shown in --help); values are deduped against the primary flag
	// name and Alias, and reserved names ("json", "params") are skipped.
	// When any alias is set by the user, the binding's Required check is
	// satisfied and the value is written to params[Property].
	Aliases       []string       `json:"aliases,omitempty"`
	Transform     string         `json:"transform,omitempty"`
	TransformArgs map[string]any `json:"transformArgs,omitempty"`
	EnvDefault    string         `json:"envDefault,omitempty"`
	Hidden        bool           `json:"hidden,omitempty"`
	Default       string         `json:"default,omitempty"`
	// Shorthand registers a single-char flag alias (cobra StringP etc.).
	Shorthand string `json:"shorthand,omitempty"`
	// Required marks this flag as mandatory via cobra.MarkFlagRequired.
	// Ignored when Positional is true (positional args have their own arity rules).
	Required bool `json:"required,omitempty"`
	// Description overrides the usage string displayed in --help; takes
	// priority over the Detail API's toolDesc when non-empty.
	Description string `json:"description,omitempty"`
	// Positional, when true, binds this parameter to a positional CLI argument
	// instead of a --flag. PositionalIndex (0-based) selects which arg slot.
	Positional      bool `json:"positional,omitempty"`
	PositionalIndex int  `json:"positionalIndex,omitempty"`
	// Type explicitly declares the flag's type: "string" (default) / "int" /
	// "bool" / "stringSlice". When set, overrides the type inferred from MCP
	// tools/list inputSchema. See schema v3 §2.1.
	Type string `json:"type,omitempty"`
	// OmitWhen declares empty-value handling when building the invocation body:
	//
	//   "empty" (default): empty string / zero-length slice-or-map → omit
	//   "zero":            + zero numbers / false booleans → omit
	//   "never":           always send, even at zero value (explicit-zero semantics)
	//
	// See schema v3 §2.2.
	OmitWhen string `json:"omitWhen,omitempty"`
	// RuntimeDefault, when non-empty, injects a runtime-resolved value if the
	// user omits the flag. Allowed placeholders: "$currentUserId" / "$unionId"
	// / "$corpId" / "$now" / "$today". Unknown placeholders → warning + skip.
	// Resolution comes from edition.Hooks.RuntimeDefaults; open-source core
	// only recognises the placeholder set. See schema v3 §2.3.
	RuntimeDefault string `json:"runtimeDefault,omitempty"`
}

type CLIGroupDef struct {
	Description string `json:"description"`
}

type CLIHintDef struct {
	// Target is the canonical command path shown in the redirect message
	// (e.g. "dws chat message list").
	Target string `json:"target"`
	// Description overrides the Short/Long help text for the hint command.
	// Empty falls back to a generic "use: <target>" string.
	Description string `json:"description,omitempty"`
	// Group optionally nests the hint under a named sub-group (same syntax
	// as CLIToolOverride.Group with dot-separated paths). Empty means the
	// hint is attached directly to the overlay root.
	Group string `json:"group,omitempty"`
}

type CLIOutputFormat struct {
	// Rename moves fields from src key to dst key at top level and one level
	// of nested objects. Missing src keys are silently ignored.
	Rename map[string]string `json:"rename,omitempty"`
	// Drop removes these keys from the response (top level + one level deep).
	Drop []string `json:"drop,omitempty"`
	// Columns controls column order and subset for --format=table. Ignored in
	// JSON output mode.
	Columns []string `json:"columns,omitempty"`
}

type CLIOverlay struct {
	ID            string                     `json:"id"`
	Command       string                     `json:"command"`
	Parent        string                     `json:"parent,omitempty"`
	Description   string                     `json:"description"`
	Prefixes      []string                   `json:"prefixes"`
	Aliases       []string                   `json:"aliases"`
	Group         string                     `json:"group"`
	Skip          bool                       `json:"skip"`
	Hidden        bool                       `json:"hidden"`
	Tools         []CLITool                  `json:"tools"`
	Groups        map[string]CLIGroupDef     `json:"groups,omitempty"`
	ToolOverrides map[string]CLIToolOverride `json:"toolOverrides,omitempty"`
	// ServerDeps declares other product IDs that this overlay depends on at
	// runtime (e.g. chat depends on bot for cross-server tool routing).
	// Consumed by the portal merge service for fail-fast validation; CLI side
	// currently only stores the value for tooling/introspection.
	ServerDeps []string `json:"serverDeps,omitempty"`
	// Hints registers stub sub-commands under the overlay root that only
	// print a redirect message pointing to the canonical command path. Used
	// for deprecated command aliases and "did-you-mean" style hints.
	// Key is the sub-command name; value describes the target path.
	Hints map[string]CLIHintDef `json:"hintCommands,omitempty"`
	// RedirectTo, when non-empty, turns the entire top-level product into a
	// stub that prints "Please use: dws <target>" and performs no work. Used
	// for deprecated top-level products migrated to new paths (e.g.
	// `bot → chat bot`, `message → chat message`). See schema v3 §2.6.
	RedirectTo string `json:"redirectTo,omitempty"`
}

type CLITool struct {
	Name        string                 `json:"name"`
	CLIName     string                 `json:"cliName"`
	Title       string                 `json:"title"`
	Description string                 `json:"description"`
	IsSensitive bool                   `json:"isSensitive"`
	Category    string                 `json:"category"`
	Hidden      bool                   `json:"hidden"`
	Flags       map[string]CLIFlagHint `json:"flags"`
}

type CLIToolOverride struct {
	CLIName     string `json:"cliName"`
	Description string `json:"description,omitempty"`
	// Example, when non-empty, is wired to cobra.Command.Example to render
	// the "Examples:" section in --help. Mirrors hardcoded helper commands'
	// Example field (e.g. wukong/products/oa.go list-forms). Empty value
	// produces no Examples section. Multi-line strings keep "\n" literally.
	Example     string                     `json:"example,omitempty"`
	Group       string                     `json:"group,omitempty"`
	IsSensitive bool                       `json:"isSensitive,omitempty"`
	Hidden      bool                       `json:"hidden,omitempty"`
	Flags       map[string]CLIFlagOverride `json:"flags,omitempty"`
	// OutputFormat declares structured response post-processing. v3 typed form
	// supersedes v2's untyped map[string]any, but parsing stays lenient so v2
	// envelopes continue to deserialize (unknown keys are ignored).
	OutputFormat CLIOutputFormat `json:"outputFormat,omitempty"`
	// ServerOverride routes this leaf command's tool invocation to a different
	// product's MCP server (e.g. `chat bot ...` leaves live under the `chat`
	// command tree but call the `bot` endpoint). Empty means use the enclosing
	// overlay's server.
	ServerOverride string `json:"serverOverride,omitempty"`
	// BodyWrapper, when non-empty, wraps the collected params map under this
	// single key before the invocation is dispatched. Useful when the upstream
	// tool expects a typed DTO wrapper (e.g. `PersonalTodoCreateVO`). Only
	// user-provided params are wrapped; internal control keys starting with
	// '_' (e.g. `_blocked`, `_yes`) are preserved at the top level.
	BodyWrapper string `json:"bodyWrapper,omitempty"`
	// MutuallyExclusive groups flag aliases that must not be set together.
	// Each inner slice becomes one cobra.MarkFlagsMutuallyExclusive call.
	// Example: [["group","user","open-dingtalk-id"]] for `chat message list`.
	MutuallyExclusive [][]string `json:"mutuallyExclusive,omitempty"`
	// RequireOneOf groups flag aliases where at least one must be set. Each
	// inner slice becomes one cobra.MarkFlagsOneRequired call. Typically
	// paired with MutuallyExclusive to enforce "exactly one of".
	RequireOneOf [][]string `json:"requireOneOf,omitempty"`
	// RedirectTo, when non-empty, turns this entry into a stub command that
	// prints the redirect target instead of invoking a tool. All other
	// fields (Flags / BodyWrapper / IsSensitive / ServerOverride) are
	// ignored. Use for deprecated leaf commands that moved to a new path.
	RedirectTo string `json:"redirectTo,omitempty"`
}

type Client struct {
	BaseURL    string
	HTTPClient *http.Client
	Headers    map[string]string
}

type DetailLocator struct {
	MCPID     int    `json:"mcp_id,omitempty"`
	DetailURL string `json:"detail_url,omitempty"`
}

type DetailResponse struct {
	Result  DetailResult `json:"result"`
	Success bool         `json:"success"`
}

type DetailResult struct {
	MCPID       int          `json:"mcpId"`
	Name        string       `json:"name"`
	Description string       `json:"description"`
	Tools       []DetailTool `json:"tools"`
}

type DetailTool struct {
	ToolName      string `json:"toolName"`
	ToolTitle     string `json:"toolTitle"`
	ToolDesc      string `json:"toolDesc"`
	IsSensitive   bool   `json:"isSensitive"`
	ToolRequest   string `json:"toolRequest"`
	ToolResponse  string `json:"toolResponse"`
	ActionVersion string `json:"actionVersion"`
}

type EnvelopeMeta struct {
	Registry RegistryMetadata `json:"com.dingtalk.mcp.registry/metadata"`
	CLI      CLIOverlay       `json:"com.dingtalk.mcp.registry/cli"`
}

type LifecycleInfo struct {
	DeprecatedBy        int    `json:"deprecatedBy"`
	DeprecationDate     string `json:"deprecationDate"`
	MigrationURL        string `json:"migrationUrl"`
	DeprecatedCandidate bool   `json:"deprecatedCandidate,omitempty"`
}

type ListMetadata struct {
	Count      int    `json:"count"`
	NextCursor string `json:"nextCursor"`
	// Warnings is populated by the Portal merge service when envelopes are
	// dropped (e.g. missing serverDeps, status != active) or when a dangling
	// serverDeps / toolOverrides.*.serverOverride reference is detected.
	// Old Portals without the field simply leave this nil. CLI side should
	// treat any non-empty slice as non-fatal informational output: print to
	// stderr so cache refreshes expose Portal drift to the user, but do not
	// fail the discovery load.
	//
	// See plan fix-wukong-discovery-missing-servers Phase 4.2/4.3.
	Warnings []ListWarning `json:"warnings,omitempty"`
}

type ListResponse struct {
	Metadata ListMetadata     `json:"metadata"`
	Servers  []ServerEnvelope `json:"servers"`
}

type ListWarning struct {
	ProductID string `json:"productId"`
	Reason    string `json:"reason"`
	Detail    string `json:"detail"`
}

type QualityMetadata struct {
	HighQuality bool `json:"highQuality"`
	Official    bool `json:"official"`
	DTBiz       bool `json:"dtBiz"`
}

type RegistryMetadata struct {
	IsLatest    bool            `json:"isLatest"`
	PublishedAt string          `json:"publishedAt"`
	UpdatedAt   string          `json:"updatedAt"`
	Status      string          `json:"status"`
	MCPID       int             `json:"mcpId"`
	DetailURL   string          `json:"detailUrl"`
	Quality     QualityMetadata `json:"quality"`
	Lifecycle   LifecycleInfo   `json:"lifecycle"`
}

type RegistryRemote struct {
	Type string `json:"type"`
	URL  string `json:"url"`
}

type RegistryServer struct {
	SchemaURI   string           `json:"$schema"`
	Name        string           `json:"name"`
	Description string           `json:"description"`
	Remotes     []RegistryRemote `json:"remotes"`
}

type ServerDescriptor struct {
	Key                       string            `json:"key"`
	SourceServerID            string            `json:"source_server_id,omitempty"`
	DisplayName               string            `json:"display_name"`
	Description               string            `json:"description,omitempty"`
	Endpoint                  string            `json:"endpoint"`
	SchemaURI                 string            `json:"schema_uri,omitempty"`
	NegotiatedProtocolVersion string            `json:"negotiated_protocol_version,omitempty"`
	UpdatedAt                 time.Time         `json:"updated_at,omitempty"`
	PublishedAt               time.Time         `json:"published_at,omitempty"`
	Status                    string            `json:"status,omitempty"`
	Source                    string            `json:"source"`
	Degraded                  bool              `json:"degraded"`
	DetailLocator             DetailLocator     `json:"detail_locator,omitempty"`
	Lifecycle                 LifecycleInfo     `json:"lifecycle,omitempty"`
	CLI                       CLIOverlay        `json:"cli,omitempty"`
	HasCLIMeta                bool              `json:"has_cli_meta,omitempty"`
	AuthHeaders               map[string]string `json:"auth_headers,omitempty"` // plugin-level auth headers for third-party MCP servers
}

type ServerEnvelope struct {
	Server RegistryServer `json:"server"`
	Meta   EnvelopeMeta   `json:"_meta"`
}