generator

type AITextWarning struct {
	Pattern string
	Match   string
	Line    int
	Context string // surrounding text
}

type AsyncJobInfo struct {
	// ResourceName and EndpointName identify the submitting endpoint
	// (the one that returns a job ID).
	ResourceName string
	EndpointName string

	// JobIDField is the response field name that carries the job identifier
	// (e.g. "job_id", "task_id"). Empty when detection fell back to
	// path-sibling inference.
	JobIDField string

	// StatusResource and StatusEndpoint point at the sibling status
	// endpoint used by the --wait polling loop. Empty only if no sibling
	// was found (in which case the endpoint is not marked async).
	StatusResource string
	StatusEndpoint string

	// StatusPath is the URL path template for the polling endpoint,
	// copied from the sibling endpoint's Path. The runtime substitutes
	// {id} or {job_id} with the actual job ID.
	StatusPath string

	// TerminalField and TerminalValues describe how the polling loop
	// decides the job is done. Defaults to "status" with a common
	// done/complete/completed/failed/errored set when the spec does not
	// declare one explicitly.
	TerminalField  string
	TerminalValues []string
}

type ColumnDef struct {
	Name       string
	Type       string
	PrimaryKey bool
	NotNull    bool
}

type DomainContext struct {
	APIName     string            `json:"api_name"`
	Description string            `json:"description"`
	Archetype   string            `json:"archetype"`
	Resources   []ResourceSummary `json:"resources"`
	QueryTips   []string          `json:"query_tips,omitempty"`
	Playbook    []PlaybookEntry   `json:"playbook,omitempty"`
}

type EntityMapping struct {
	TableName       string
	HumanSingular   string
	HumanPlural     string
	IdentifierField string
	TitleField      string
	UpdatedAtField  string
	AssigneeField   string
	PriorityField   string
	DueDateField    string
	TeamField       string
	LabelField      string
	EstimateField   string
	StateField      string
}

type Generator struct {
	Spec            *spec.APISpec
	OutputDir       string
	VisionSet       VisionTemplateSet
	FixtureSet      *browsersniff.FixtureSet
	TrafficAnalysis *browsersniff.TrafficAnalysis
	Sources         []ReadmeSource          // Ecosystem tools to credit in README
	DiscoveryPages  []string                // Pages visited during browser-sniff discovery
	NovelFeatures   []NovelFeature          // Transcendence features for README/SKILL
	Narrative       *ReadmeNarrative        // LLM-authored prose for README/SKILL; optional
	AsyncJobs       map[string]AsyncJobInfo // Detected async-job endpoints, keyed by "<resource>/<endpoint>"

	// Promoted-command plan, populated by Generate() before any rendering so
	// SKILL/README templates can honor leaf promotion (and not emit phantom paths
	// like `<cli> qr get-qrcode` for a resource the generator collapsed to `qr`).
	PromotedCommands      []PromotedCommand
	PromotedResourceNames map[string]bool
	PromotedEndpointNames map[string]string
	// contains filtered or unexported fields
}

type HelperFlags struct {
	HasDelete          bool // spec has DELETE endpoints → emit classifyDeleteError
	HasPathParams      bool // spec has path parameters → emit replacePathParam
	HasMultiPositional bool // spec has endpoints with 2+ positional params → emit usageErr
	HasDataLayer       bool // CLI has a local store (sync/search) → emit provenance helpers
	HasClientLimit     bool // at least one endpoint needs client-side limit truncation → emit truncateJSONArray
}

type IndexDef struct {
	Name      string
	TableName string
	Columns   string
	Unique    bool
}

type NovelFeature struct {
	Name         string
	Command      string
	Description  string
	Rationale    string
	Example      string // ready-to-run invocation
	WhyItMatters string // one-sentence agent-facing rationale
	Group        string // theme name for grouped rendering
}

type PlanCommand struct {
	Name        string // e.g., "record" or "auth login"
	Description string
}

type PlanSpec struct {
	CLIName     string
	Description string
	Commands    []PlanCommand
}

type PlaybookEntry struct {
	Topic   string `json:"topic"`
	Insight string `json:"insight"`
}

type PromotedCommand struct {
	PromotedName string
	ResourceName string
	Endpoint     spec.Endpoint
	EndpointName string
}

type QuickStartStep struct {
	Command string
	Comment string
}

type ReadmeNarrative struct {
	DisplayName    string
	Headline       string
	ValueProp      string
	AuthNarrative  string
	QuickStart     []QuickStartStep
	Troubleshoots  []TroubleshootTip
	WhenToUse      string
	Recipes        []Recipe
	TriggerPhrases []string
}

type ReadmeSource struct {
	Name     string
	URL      string
	Language string
	Stars    int
}

type Recipe struct {
	Title       string
	Command     string
	Explanation string
}

type ResourceSummary struct {
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Endpoints   []string `json:"endpoints"`
	Syncable    bool     `json:"syncable,omitempty"`
	Searchable  bool     `json:"searchable,omitempty"`
}

type TableDef struct {
	Name         string
	Columns      []ColumnDef
	Indexes      []IndexDef
	FTS5         bool
	FTS5Fields   []string
	FTS5Triggers bool
}

type TroubleshootTip struct {
	Symptom string
	Fix     string
}

type VisionTemplateSet struct {
	Export    bool
	Import    bool
	Store     bool
	Search    bool
	Sync      bool
	Tail      bool
	Analytics bool
	MCP       bool
	Workflows []string
	Insights  []string
}

type WorkflowTemplateContext struct {
	CLIName       string
	APIName       string
	Domain        string
	PrimaryEntity EntityMapping
	TeamEntity    EntityMapping
	UserEntity    EntityMapping
	StateEntity   EntityMapping
	HasAssignees  bool
	HasDueDates   bool
	HasPriority   bool
	HasTeams      bool
	HasLabels     bool
	HasEstimates  bool
}