ide

package
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 7, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package ide implements the backend for `gad ide`: a small HTTP server that turns a workspace directory into a multi-file editing environment. On top of the shared language operations (format / diagnose / run / debug) it adds a sandboxed filesystem API rooted at the workspace and read/write access to the project's .gad.yaml (the `fmt` formatter settings and the `ide` layout key).

The server is transport-agnostic: New returns a *Server whose Handler can be mounted by `gad ide` (serving the bundled React app) or used directly in tests.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BreakpointSpec

type BreakpointSpec struct {
	Line      int    `json:"line"`
	Disabled  bool   `json:"disabled"`
	Condition string `json:"condition"`
}

BreakpointSpec is a breakpoint with optional disabled flag and condition, sent by the IDE. A bare line in StartRequest.Breakpoints is an enabled, unconditional breakpoint; BreakpointSpecs (when present) take precedence.

type CommandRequest

type CommandRequest struct {
	Session string `json:"session"`
	Command string `json:"command"`
}

CommandRequest resumes a session (continue/next/stepIn/stepOut/pause).

type DebugFrame

type DebugFrame struct {
	Name   string          `json:"name"`
	File   string          `json:"file"`
	Line   int             `json:"line"`
	Column int             `json:"column"`
	Locals []DebugVariable `json:"locals"`
}

DebugFrame is one call-stack frame, including its own local variables.

type DebugManager

type DebugManager struct {

	// BuildModuleMap, when set, builds the module map for a debug session from
	// its start request (e.g. rooted at the file's directory with the requested
	// module toggles). When nil, a default stdlib module map is used so builtin
	// imports such as `import("time")` still resolve.
	BuildModuleMap func(req StartRequest) *gad.ModuleMap
	// NormalizeFile, when set, maps a debugger source file name (the main file's
	// "(main)" sentinel, or a "file:<abs>" imported-module path) to a
	// workspace-relative path the UI can open. mainPath is the session's entry
	// file. When nil, file names are passed through unchanged.
	NormalizeFile func(mainPath, engineFile string) string
	// RelativizeValue, when set, rewrites absolute workspace paths embedded in a
	// rendered variable value (module / function ToString) to a relative form.
	RelativizeValue func(value string) string
	// TemplateDelimiter, when set, supplies the mixed-mode start/end delimiter
	// used to compile `.gadt` template sessions (from the workspace config). When
	// nil the parser default (`{%` / `%}`) is used.
	TemplateDelimiter func() parser.MixedDelimiter
	// contains filtered or unexported fields
}

DebugManager owns the live debug sessions.

func NewDebugManager

func NewDebugManager() *DebugManager

NewDebugManager returns an empty DebugManager.

func (*DebugManager) HandleCommand

func (m *DebugManager) HandleCommand(w http.ResponseWriter, r *http.Request)

HandleCommand resumes an existing session to the next stop or completion.

func (*DebugManager) HandleEval

func (m *DebugManager) HandleEval(w http.ResponseWriter, r *http.Request)

HandleEval evaluates an expression against the paused frame's locals, so the Evaluate panel reflects the live debug state (not a fresh standalone VM).

func (*DebugManager) HandleStart

func (m *DebugManager) HandleStart(w http.ResponseWriter, r *http.Request)

HandleStart compiles the source, starts a VM under the debugger and runs to the first stop (breakpoint, stop-on-entry) or to completion.

type DebugResponse

type DebugResponse struct {
	Session     string                 `json:"session,omitempty"`
	State       string                 `json:"state"` // "stopped" | "terminated" | "error"
	Reason      string                 `json:"reason,omitempty"`
	File        string                 `json:"file,omitempty"` // workspace-relative file of the stop
	Line        int                    `json:"line,omitempty"`
	Column      int                    `json:"column,omitempty"`
	Frames      []DebugFrame           `json:"frames,omitempty"`
	Locals      []DebugVariable        `json:"locals,omitempty"`
	Output      string                 `json:"output,omitempty"` // combined stdout+stderr delta (compat)
	Stdout      string                 `json:"stdout,omitempty"` // stdout delta since the last stop
	Stderr      string                 `json:"stderr,omitempty"` // stderr delta since the last stop
	Result      string                 `json:"result,omitempty"`
	Error       string                 `json:"error,omitempty"`
	Diagnostics []gadbridge.Diagnostic `json:"diagnostics,omitempty"`
}

DebugResponse is the result of a start/command call.

type DebugVariable

type DebugVariable struct {
	Name  string `json:"name"`
	Type  string `json:"type"`
	Value string `json:"value"`
}

DebugVariable is a local variable observed at a stop.

type EvalRequest

type EvalRequest struct {
	Session string `json:"session"`
	Expr    string `json:"expr"`
	Repr    bool   `json:"repr"`
}

EvalRequest evaluates an expression in a paused session's current frame.

type Server

type Server struct {
	// Root is the absolute path of the workspace directory. All filesystem
	// operations are confined to this subtree.
	Root string
	// OpenFile, when set, is a workspace-relative path the UI should open first
	// (used when `gad ide FILE` targets a single file).
	OpenFile string
	// Static, when non-empty, is a directory with the built React app served at
	// the site root.
	Static string
	// HTTPClient fetches remote files for handleFetch. Defaults to
	// http.DefaultClient; overridable in tests.
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

Server serves the IDE API for a single workspace directory.

func New

func New(path string) (*Server, error)

New creates a Server for the given workspace path. If path points at a file, the workspace root becomes its directory and the file is reported as the initial file to open. A relative path is resolved against the process CWD.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns the HTTP handler exposing the IDE API (and, if Static is set, the bundled web app).

type StartRequest

type StartRequest struct {
	Source          string           `json:"source"`
	Breakpoints     []int            `json:"breakpoints"`
	BreakpointSpecs []BreakpointSpec `json:"breakpointSpecs"`
	StopOnEntry     bool             `json:"stopOnEntry"`
	Path            string           `json:"path"`     // workspace-relative file, for imports
	Args            []string         `json:"args"`     // CLI-style positional arguments
	Disabled        []string         `json:"disabled"` // builtin modules to disable
	Safe            bool             `json:"safe"`     // disable all unsafe modules
}

StartRequest launches a debug session.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL