apiserver

type Config struct {
	Port          string
	CORS          bool
	FrontendPath  string      // optional: React project path for Vite proxy
	StaticPath    string      // optional: built frontend files
	Watch         bool        // enable file watching for hot reload
	EffCtx        interface{} // optional: pre-configured effect context (*effects.EffContext)
	MCP           bool        // enable MCP endpoint at /mcp/
	MCPOnly       bool        // run as MCP stdio server only (no HTTP)
	A2A           bool        // enable A2A endpoints (/.well-known/agent.json, /a2a/)
	MaxUploadSize int64       // max upload size in bytes (0 = DefaultMaxUploadSize)
	APIKeyHeader  string      // HTTP header for API key auth (empty = no auth)
	APIKeyEnv     string      // env var containing expected API key
	LogLevel      int         // minimum severity for Debug output (0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=NONE)
	RoutesOnly    bool        // only expose @route-annotated functions as HTTP endpoints
}

type ExportInfo struct {
	Name        string   `json:"name"`
	Type        string   `json:"type"`                   // human-readable type signature
	Pure        bool     `json:"pure"`                   // whether the function is pure
	Arity       int      `json:"arity"`                  // number of parameters (-1 if not a function)
	ParamNames  []string `json:"param_names,omitempty"`  // parameter names in order (for named JSON binding)
	ParamTypes  []string `json:"param_types,omitempty"`  // parameter type strings in order (for zero-value padding)
	RouteMethod string   `json:"route_method,omitempty"` // custom HTTP method from @route annotation
	RoutePath   string   `json:"route_path,omitempty"`   // custom URL path from @route annotation
	IsRaw       bool     `json:"is_raw,omitempty"`       // @raw annotation: pass full HttpRequest record
	IsNowrap    bool     `json:"is_nowrap,omitempty"`    // @nowrap annotation: skip FunctionCallResponse envelope
	IsNoExpose  bool     `json:"is_no_expose,omitempty"` // @noexpose annotation: hide from HTTP endpoints
	MCPName     string   `json:"mcp_name,omitempty"`     // @mcp_name annotation: explicit MCP tool name override
	DocComment  string   `json:"doc_comment,omitempty"`  // doc comment (-- lines) preceding the function
}

type FunctionCallRequest struct {
	Args []interface{} `json:"args,omitempty"`
}

type FunctionCallResponse struct {
	Result      interface{}        `json:"result,omitempty"`
	Error       string             `json:"error,omitempty"`
	ErrorDetail *RouterErrorDetail `json:"error_detail,omitempty"`
	Module      string             `json:"module"`
	Func        string             `json:"func"`
	ElapsedMs   int64              `json:"elapsed_ms"`
}

type HealthResponse struct {
	Status       string `json:"status"`
	ModulesCount int    `json:"modules_count"`
	ExportsCount int    `json:"exports_count"`
}

type MCPServer struct {
	// contains filtered or unexported fields
}

type ModuleInfo struct {
	// Path is the RelPath projection (forward-slash relative path with
	// .ail stripped). Kept as the primary JSON field for backwards compat.
	Path    string       `json:"path"`
	Exports []ExportInfo `json:"exports"`

	// PhysicalPath is the symlink-resolved absolute file path. This is
	// the module's *identity*: two ModuleInfo values with the same
	// PhysicalPath refer to the same physical source file, regardless of
	// how they were discovered. This is the key used in s.modules.
	PhysicalPath string `json:"-"`

	// CanonicalID is the pipeline's canonical module ID (used by loader
	// cache and callFunction dispatch). Example: "docparse/services/mcp_tools".
	CanonicalID string `json:"-"`

	// DeclaredPath is the `module X` header as written in source. Used
	// to resolve imports from other local modules. Usually matches
	// CanonicalID; differs under `module_prefix` aliasing.
	DeclaredPath string `json:"-"`

	// File is the parsed AST for the source file. Used for doc comment
	// extraction and by the extract* helpers during registration.
	File *ast.File `json:"-"`

	// Iface is the type-checked interface from the pipeline. Used by
	// callFunction for signature lookup and by the MCP schema generator.
	Iface *iface.Iface `json:"-"`
}

type ModulesListResponse struct {
	Modules []*ModuleInfo `json:"modules"`
	Count   int           `json:"count"`
}

type RouteEntry struct {
	Method     string   // "GET", "POST", etc.
	Path       string   // "/general/v0/general"
	Module     string   // module path
	Function   string   // function name
	IsRaw      bool     // @raw: pass full HttpRequest record instead of parsed args
	IsNowrap   bool     // @nowrap: skip FunctionCallResponse envelope, return raw JSON
	ParamNames []string // parameter names for named JSON binding
	ParamTypes []string // parameter type strings for zero-value padding
}

type RouterErrorDetail struct {
	// Code is a stable identifier (e.g. "ROUTE_NOT_FOUND"). Clients match
	// on this rather than the human-readable Message.
	Code string `json:"code"`

	// Message is a human-readable description of what went wrong. Always
	// mirrors the flat FunctionCallResponse.Error field for backward compat.
	Message string `json:"message"`

	// Retryable indicates whether the same request could succeed if retried
	// without modification. Router-layer errors are almost always false.
	Retryable bool `json:"retryable"`

	// SuggestedFix is an optional human-readable hint for how to recover.
	// For ROUTE_NOT_FOUND, this is populated with "Did you mean ...?" when
	// a close route match exists. May be empty.
	SuggestedFix string `json:"suggested_fix,omitempty"`

	// AvailableRoutes is an optional list of registered routes that might
	// be relevant to the failed request (e.g. routes sharing a path prefix).
	// Capped at 10 entries. Each entry is formatted as "METHOD /path".
	AvailableRoutes []string `json:"available_routes,omitempty"`
}

type Server struct {
	// contains filtered or unexported fields
}