betools — Go API Reference#

Package#

import "github.com/conglinyizhi/better-edit-tools-mcp/pkg/betools"

betools is the core editing library extracted from better-edit-tools, designed to be embedded directly in Go agent frameworks. It provides read, replace, insert, delete, write, function-range detection, and tag-range detection primitives — all write operations are protected by atomic file writes (temp file + rename).

Minimum Go version: Go 1.26+

Public Functions#

File Operations#

Read#

func Read(path string, start int, endLine int, brief bool, opts ...Option) (ShowResult, string, error)

Reads a line range from a file. Returns the content and a viewed_code_id (second return value) that can be passed to Replace for line-number validation.

• start: starting line number (>= 1)
• endLine: ending line number. Pass 0 or negative to auto-expand to the enclosing function scope (via FuncRange)
• Returns a viewed_code_id: UUID v4 for later Replace session validation
• opts: optional WithFileSystem(...) injection for sandboxed environments

Show remains available as a compatibility alias.

Replace#

func Replace(path string, start, end int, old *string, content string, format string, preview bool, sessionID string, brief bool, opts ...Option) (ReplaceResult, error)

Precise line-range substitution.

• start, end: line range (inclusive), both required
• old: optional — when non-nil, verifies current file content against old before writing; returns error on mismatch
• content: replacement content
• format: output format ("trim" or "")
• preview: if true, returns diff without writing to disk
• sessionID: optional — validates line count consistency against a prior be-read session
• brief: return minimal response (omit diff and balance)

Insert#

func Insert(path string, after int, content string, format string, preview bool, brief bool, opts ...Option) (InsertResult, error)

Inserts content after a specified line.

• after: insert after this line. Pass 0 to insert at the very beginning of the file
• format, preview, brief: same semantics as Replace

Delete#

func Delete(path string, start, end int, format string, preview bool, brief bool, opts ...Option) (DeleteResult, error)

Deletes lines in the specified range.

• start, end: line range (inclusive), both required
• format, preview, brief: same semantics as Replace

Write#

func Write(spec string, preview bool, brief bool, opts ...Option) (WriteResult, error)

Raw file write tool for full-content replacement. Supports single-file and multi-file payloads.

• spec: JSON string
  • Single file: {"file":"...","content":"..."}
  • Multi file: {"files":[{"file":"...","content":"..."}]}
• preview: if true, returns results without writing to disk
• brief: return minimal response (omit per-file details)
• Falls back to character-level extraction when JSON parsing fails

Scope Detection#

FuncRange#

func FuncRange(path string, line int, opts ...Option) (FunctionRangeResult, error)

Detects the enclosing {} block or function range for a line. Backtracks through func/type/method keywords.

TagRange#

func TagRange(path string, line int, opts ...Option) (TagRangeResult, error)

Finds the enclosing XML/HTML/Vue tag pair for a line.

ResolveTargetSpan#

func ResolveTargetSpan(path string, target ContentTarget, opts ...Option) (TargetSpan, error)

Resolves a ContentTarget to a line range. ContentTarget.Kind supports "line", "function", "marker", "tag".

Structural Balance Detection#

CheckStructureBalance#

func CheckStructureBalance(path string, verbose bool, opts ...Option) (string, error)

Checks brackets, braces, parentheses, HTML/XML tag closure, and quote parity.

• verbose=false: only outputs unmatched items
• verbose=true: outputs all matched pairs

Session Management#

CreateSession#

func CreateSession(file string, start, end int, opts ...Option) string

Creates a read session and returns its UUID. Core building block for SessionFromCache.

GetSession#

func GetSession(id string) *ReadSession

Looks up a session by UUID. Returns nil if expired (>24h) or not found.

SessionFromCache#

func SessionFromCache(id string, opts ...Option) (s *ReadSession, warning string)

Looks up and validates a session. If the file has changed (line count mismatch), returns a non-fatal warning with head/tail sample lines to help re-sync.

CleanupSession#

func CleanupSession(id string)

Manually removes a session. Expired sessions are auto-cleaned by a background goroutine every 30 minutes.

File System Injection#

func WithFileSystem(fsys FileSystem) Option

Pass this option to constrain betools to a custom file system, such as a workspace wrapper or sandboxed view of the repository.

Chip Storage#

SaveChip#

func SaveChip(tool string, args map[string]any) int

Saves failed MCP tool call arguments as a chip record. Only records when the serialised JSON exceeds 50 bytes. Returns the chip ID, or 0 if args were too short. Maintains a FIFO queue of up to 10 records, persisted to /tmp/bet-chips/.

GetChip#

func GetChip(id int) (*ChipRecord, error)

Queries a chip record by ID. Checks memory first, falls back to /tmp/bet-chips/chip-{id}.json on disk.

ListChips#

func ListChips() []int

Returns all in-memory chip IDs in insertion order (oldest first).

Public Types#

Result Types#

Balance Detection Types#

Session#

Chip#

Target Resolution#

Write Parameters#

Sentinel Errors#

var ErrInvalid = errors.New("invalid argument")
var ErrRead    = errors.New("read error")
var ErrWrite   = errors.New("write error")

All betools errors can be matched with errors.Is against these three sentinels.