ir

Documentation

Overview

Package ir defines the Forge Intermediate Representation: a language- and target-agnostic model of an API. Every Forge generator (tool-pack, MCP server, docs, SDKs) reads only the IR, so adding a new source format (OpenAPI, GraphQL, gRPC) means writing one ingester, and adding a new output means writing one generator — never an N×M matrix.

Index

• Constants
• func Slugify(s string) string
• type API
  • func (a *API) BaseURL() string
  • func (a *API) OperationByID(id string) *Operation
  • func (a *API) Resolve(s *Schema) *Schema
  • func (a *API) Slug() string
  • func (a *API) SortedOperations() []Operation
  • func (a *API) StreamByID(id string) *Operation
  • func (a *API) Tags() []string
• type AuthScheme
• type Operation
  • func (op *Operation) ToolInputSchema(api *API) json.RawMessage
• type PaginationHint
• type Param
• type Schema
  • func (s *Schema) JSONSchema(api *API) json.RawMessage
• type Server
• type SkippedOperation

Constants

const (
	SkipClientStreaming = "client-streaming" // gRPC client-streaming method
	SkipServerStreaming = "server-streaming" // gRPC server-streaming method
	SkipBidiStreaming   = "bidi-streaming"   // gRPC bidirectional-streaming method
	SkipSubscription    = "subscription"     // GraphQL subscription field
)

SkippedOperation.Kind values. SkipServerStreaming and SkipSubscription are retained for backward compatibility with stored IR JSON, but current ingesters place server-streaming methods and subscription fields in API.Streams (exposed as streaming sessions) rather than in Skipped.

Functions

func Slugify

func Slugify(s string) string

Slugify lower-cases and replaces non-alphanumeric runs with single hyphens.

Types

type API

type API struct {
	Name        string             `json:"name"`
	Version     string             `json:"version"`
	Description string             `json:"description,omitempty"`
	SourceType  string             `json:"source_type"` // "openapi" | "graphql" | "grpc"
	Servers     []Server           `json:"servers,omitempty"`
	Auth        []AuthScheme       `json:"auth,omitempty"`
	Operations  []Operation        `json:"operations"`
	Schemas     map[string]*Schema `json:"schemas,omitempty"` // named component schemas
	// Streams lists source operations that are PUSH STREAMS — gRPC
	// server-streaming methods and GraphQL subscription fields — exposed at
	// runtime as background streaming sessions (start / poll / stop over a
	// bounded ring buffer, mirroring the bash_background pattern) instead of
	// unary tools. They are kept out of Operations on purpose: every unary
	// generator (SDKs, docs, static tool registration) would otherwise emit a
	// one-shot request/response wrapper that hangs or truncates at call time.
	// Only the live tool layer (toolpack stream tools) reads this list.
	Streams []Operation `json:"streams,omitempty"`
	// Skipped lists operations the ingester found in the source spec but
	// deliberately did NOT expose at all (gRPC client-streaming and
	// bidi-streaming methods, which cannot ride a JSON-over-HTTP bridge).
	// Generators ignore it; the CLI reports it at add time so exclusions are
	// specific instead of silent.
	Skipped []SkippedOperation `json:"skipped,omitempty"`
}

API is the normalized description of an API.

func (*API) BaseURL

func (a *API) BaseURL() string

BaseURL returns the first server URL, or "" if none.

func (*API) OperationByID

func (a *API) OperationByID(id string) *Operation

OperationByID returns the operation with the given ID, or nil.

func (*API) Resolve

func (a *API) Resolve(s *Schema) *Schema

Resolve dereferences a schema one level against the API's named schemas. It returns the input unchanged when it is not a reference.

func (*API) Slug

func (a *API) Slug() string

Slug returns a filesystem/URL-safe lower-case identifier for the API name.

func (*API) SortedOperations

func (a *API) SortedOperations() []Operation

SortedOperations returns operations sorted by ID for deterministic output.

func (*API) StreamByID

func (a *API) StreamByID(id string) *Operation

StreamByID returns the stream operation with the given ID, or nil.

func (*API) Tags

func (a *API) Tags() []string

Tags returns the sorted unique set of tags across all operations.

type AuthScheme

type AuthScheme struct {
	Name    string `json:"name"`               // security scheme name (key)
	Type    string `json:"type"`               // "apiKey" | "http" | "oauth2"
	In      string `json:"in,omitempty"`       // apiKey: "header" | "query" | "cookie"
	KeyName string `json:"key_name,omitempty"` // apiKey: the header/query parameter name
	Scheme  string `json:"scheme,omitempty"`   // http: "bearer" | "basic"
}

AuthScheme describes one authentication mechanism.

type Operation

type Operation struct {
	ID          string             `json:"id"`     // operationId → tool/method name (sanitized)
	Method      string             `json:"method"` // GET/POST/PUT/PATCH/DELETE
	Path        string             `json:"path"`   // /v1/customers/{id}
	Summary     string             `json:"summary,omitempty"`
	Description string             `json:"description,omitempty"`
	Params      []Param            `json:"params,omitempty"`
	RequestBody *Schema            `json:"request_body,omitempty"`
	Responses   map[string]*Schema `json:"responses,omitempty"`
	Auth        []string           `json:"auth,omitempty"`
	Pagination  *PaginationHint    `json:"pagination,omitempty"`
	Mutating    bool               `json:"mutating"` // non-GET ⇒ approval candidate
	Tags        []string           `json:"tags,omitempty"`
}

Operation is a single callable endpoint.

func (*Operation) ToolInputSchema

func (op *Operation) ToolInputSchema(api *API) json.RawMessage

ToolInputSchema builds a single flat JSON-Schema object for an operation by merging its path/query/header parameters and request body into one object — the convention agent tool callers expect (one flat input object per tool). A non-object body is wrapped under a "body" property.

type PaginationHint

type PaginationHint struct {
	Style     string `json:"style"`                // "cursor" | "page" | "offset"
	Param     string `json:"param"`                // request param that drives paging
	NextField string `json:"next_field,omitempty"` // response field holding the next token
}

PaginationHint records detected pagination so generators can emit iterators.

type Param

type Param struct {
	Name        string  `json:"name"`
	In          string  `json:"in"` // path | query | header | cookie
	Required    bool    `json:"required"`
	Description string  `json:"description,omitempty"`
	Schema      *Schema `json:"schema,omitempty"`
}

Param is a path / query / header / cookie parameter.

type Schema

type Schema struct {
	Name                 string             `json:"name,omitempty"` // component name, if a named schema
	Ref                  string             `json:"ref,omitempty"`  // referenced component name
	Type                 string             `json:"type,omitempty"` // object|array|string|number|integer|boolean
	Format               string             `json:"format,omitempty"`
	Description          string             `json:"description,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty"`
	Required             []string           `json:"required,omitempty"`
	Items                *Schema            `json:"items,omitempty"`
	Enum                 []string           `json:"enum,omitempty"`
	Nullable             bool               `json:"nullable,omitempty"`
	AdditionalProperties *Schema            `json:"additional_properties,omitempty"`
}

Schema is a normalized JSON-Schema node. A reference is represented by Ref (the component name); generators resolve it via API.Schemas when needed.

func (*Schema) JSONSchema

func (s *Schema) JSONSchema(api *API) json.RawMessage

JSONSchema renders a Schema as a draft-07-ish JSON Schema document (the shape tools.ToolSpec.Parameters and MCP inputSchema expect). References are inlined one level to keep the schema self-contained for the model.

type Server

type Server struct {
	URL         string `json:"url"`
	Description string `json:"description,omitempty"`
}

Server is a base URL the API is served from.

type SkippedOperation

type SkippedOperation struct {
	ID   string `json:"id"`
	Kind string `json:"kind"` // one of the Skip* constants below
}

SkippedOperation records one deliberately-unexposed source operation.