syntax

package
v0.1.3 Latest Latest
Warning

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

 Go to latest Published: Aug 30, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package syntax owns Plasmid's framework-free syntax document primitives.

Index

Constants

This section is empty.

Variables

View Source 
var ErrSubstitutionLimit = errors.New("substitution output exceeds byte limit")
View Source 
var ErrToolDenied = errors.New("tool denied by active instruction policy")

ErrToolDenied identifies a turn-scoped tool policy rejection.

Functions

func IsCodeOffset 

func IsCodeOffset(regions []CodeRegion, offset int) bool

IsCodeOffset reports whether an offset is inside a code region, including its delimiters.

func NativeToolInvocation 

func NativeToolInvocation(name string, args map[string]any) (string, string)

NativeToolInvocation maps supported host policy names to Plasmid's native wire names and selects the host-compatible argument string.

func Substitute 

func Substitute(source, path string, values Substitutions) (string, []warning.Warning)

Substitute expands arguments and explicit harness variables in one non-recursive pass. Unresolved tokens remain byte-for-byte intact.

func SubstituteBounded 

func SubstituteBounded(source, path string, values Substitutions, maximum int) (string, []warning.Warning, error)

SubstituteBounded performs the same single-pass substitution without ever constructing an output larger than maximum bytes. A non-positive maximum is unbounded.

Types

type Arguments 

type Arguments struct {
	Raw         string          `json:"raw"`
	Declared    []string        `json:"declared"`
	Positionals []string        `json:"positionals"`
	Named       []NamedArgument `json:"named"`
}

Arguments is one parsed invocation. Positionals are one-based when used by substitution.

func ParseArguments 

func ParseArguments(source string, declared []string) (Arguments, error)

ParseArguments tokenizes shell-like quoting without performing expansion. Only declared names are interpreted as name=value arguments.

type CodeRegion 

type CodeRegion struct {
	Kind         CodeRegionKind `json:"kind"`
	Start        int            `json:"start"`
	End          int            `json:"end"`
	ContentStart int            `json:"content_start"`
	ContentEnd   int            `json:"content_end"`
}

CodeRegion contains half-open byte offsets. Start and End include Markdown delimiters; ContentStart and ContentEnd exclude them.

func ScanCodeRegions 

func ScanCodeRegions(source string) []CodeRegion

ScanCodeRegions returns deterministic non-overlapping Markdown code spans. It recognizes CommonMark-style backtick and tilde fences with up to three leading spaces and backtick inline code spans outside fences.

type CodeRegionKind 

type CodeRegionKind string

CodeRegionKind identifies inline and fenced Markdown code. 

const (
	CodeRegionInline CodeRegionKind = "inline"
	CodeRegionFence  CodeRegionKind = "fence"
)

type CommandDirective 

type CommandDirective struct {
	Start        int    `json:"start"`
	End          int    `json:"end"`
	ContentStart int    `json:"content_start"`
	ContentEnd   int    `json:"content_end"`
	Line         int    `json:"line"`
	Command      string `json:"command"`
}

CommandDirective is one executable prompt command region.

func ScanCommandDirectives 

func ScanCommandDirectives(source string) []CommandDirective

ScanCommandDirectives recognizes !`inline` and ```! fenced commands while leaving ordinary Markdown code untouched.

type Document 

type Document struct {
	Host          Host            `json:"host"`
	Name          string          `json:"name"`
	Description   string          `json:"description"`
	License       string          `json:"license"`
	Compatibility string          `json:"compatibility"`
	Metadata      []MetadataEntry `json:"metadata"`
	ArgumentHint  string          `json:"argument_hint"`
	Arguments     []string        `json:"arguments"`
	AllowedTools  []ToolPattern   `json:"allowed_tools"`
	DeniedTools   []ToolPattern   `json:"denied_tools"`
	Globs         []string        `json:"globs"`
	Exposure      Exposure        `json:"exposure"`
	Body          string          `json:"body"`
	// contains filtered or unexported fields
}

Document is the normalized, framework-free syntax document model.

func ParseDocument 

func ParseDocument(source, path string, host Host) (Document, []warning.Warning)

ParseDocument projects one frontmatter document. Malformed and unsupported entries become stable warnings; successfully parsed independent entries are retained.

func ParseTemplate 

func ParseTemplate(source, path string, host Host, identity string) (Document, []warning.Warning)

ParseTemplate projects optional template frontmatter through the same parser as Agent Skills while retaining the filename as the template identity.

func (Document) RestrictsTools 

func (d Document) RestrictsTools() bool

RestrictsTools reports whether an allow-list was declared, including an explicitly empty or wholly invalid declaration that must deny all tools.

func (Document) ToolPolicy 

func (d Document) ToolPolicy() ToolPolicy

ToolPolicy returns the compiled policy while preserving the distinction between an absent allow-list and a configured list with no valid patterns.

type Exposure 

type Exposure struct {
	UserInvocable  bool `json:"user_invocable"`
	ModelInvocable bool `json:"model_invocable"`
}

Exposure contains visibility flags. Trust remains an independent host fact.

func DefaultExposure 

func DefaultExposure() Exposure

DefaultExposure is visible to users and models, subject to host trust.

func (Exposure) Allows 

func (e Exposure) Allows(kind InvocationKind, repositoryScoped, trusted bool) bool

Allows applies visibility and the automatic model-exposure trust boundary. Explicit user visibility does not grant prompt-command execution authority; that remains a separate runtime gate.

type FieldRule 

type FieldRule struct {
	Name     string      `json:"name"`
	Required bool        `json:"required"`
	Status   FieldStatus `json:"status"`
}

FieldRule is one ordered support-matrix row.

func SupportMatrix 

func SupportMatrix(host Host) []FieldRule

SupportMatrix returns a defensive ordered field-support matrix for a host.

type FieldStatus 

type FieldStatus string

FieldStatus records whether Plasmid honors or deliberately ignores a field. 

const (
	FieldCore        FieldStatus = "core"
	FieldSupported   FieldStatus = "supported"
	FieldUnsupported FieldStatus = "unsupported"
)

type Host 

type Host string

Host identifies the source syntax projected into a Document. 

const (
	HostPortable Host = "portable"
	HostPlasmid  Host = "plasmid"
	HostClaude   Host = "claude"
	HostCodex    Host = "codex"
	HostCopilot  Host = "copilot"
)

type Instruction 

type Instruction struct {
	Body              string     `json:"body"`
	Globs             []string   `json:"globs"`
	PathScopeDeclared bool       `json:"path_scope_declared"`
	Policy            ToolPolicy `json:"-"`
}

Instruction is the normalized syntax owned by an instruction file.

func ParseInstruction 

func ParseInstruction(source, path string, host Host) (Instruction, []warning.Warning)

ParseInstruction projects the supported instruction frontmatter subset. Files without frontmatter are returned unchanged.

type InvocationKind 

type InvocationKind uint8

InvocationKind identifies who is requesting document invocation. 

const (
	InvocationUser InvocationKind = iota + 1
	InvocationModel
)

type MetadataEntry 

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

MetadataEntry retains deterministic metadata order.

type NamedArgument 

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

NamedArgument is one deterministic name/value pair.

type ScopeKey 

type ScopeKey struct {
	SessionID    string
	InvocationID string
}

ScopeKey uniquely identifies one invocation within a session.

type ScopeStore 

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

ScopeStore owns concurrent turn scopes. Its zero value is ready for use.

func (*ScopeStore) Begin 

func (s *ScopeStore) Begin(key ScopeKey, scope TurnScope) error

Begin records a new scope and rejects accidental key reuse.

func (*ScopeStore) Get 

func (s *ScopeStore) Get(key ScopeKey) (TurnScope, bool)

Get returns a defensive copy of a scope.

func (*ScopeStore) IntersectPolicy 

func (s *ScopeStore) IntersectPolicy(key ScopeKey, policy ToolPolicy) error

IntersectPolicy atomically narrows an existing invocation policy.

func (*ScopeStore) Len 

func (s *ScopeStore) Len() int

Len returns the number of active scopes.

func (*ScopeStore) Release 

func (s *ScopeStore) Release(key ScopeKey) bool

Release deletes a scope and reports whether it existed.

func (*ScopeStore) ReleaseSession 

func (s *ScopeStore) ReleaseSession(sessionID string) int

ReleaseSession removes every invocation scope for one session.

func (*ScopeStore) Set 

func (s *ScopeStore) Set(key ScopeKey, scope TurnScope) error

Set records or replaces one invocation scope atomically.

func (*ScopeStore) SetOrIntersectPolicy 

func (s *ScopeStore) SetOrIntersectPolicy(key ScopeKey, policy ToolPolicy) error

SetOrIntersectPolicy creates the initial invocation scope or atomically narrows an existing one. Re-assembly during a turn can never erase a skill or template restriction installed by an earlier tool call.

type Substitutions 

type Substitutions struct {
	Arguments Arguments
	Variables Variables
}

Substitutions contains all deterministic expansion inputs.

type ToolPattern 

type ToolPattern struct {
	Tool     string `json:"tool"`
	Argument string `json:"argument"`
}

ToolPattern matches a tool name and, when present, its serialized argument.

func ParseToolPattern 

func ParseToolPattern(source string) (ToolPattern, error)

ParseToolPattern parses Tool or Tool(argument-pattern).

func ParseToolPatterns 

func ParseToolPatterns(source string) ([]ToolPattern, []error)

ParseToolPatterns parses whitespace-separated tool patterns. Valid patterns are retained when siblings are malformed; errors remain in source order.

type ToolPolicy 

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

ToolPolicy applies deny-wins matching. Intersect retains each policy as an independent layer, so a request must satisfy every nested scope.

func NewRestrictedToolPolicy 

func NewRestrictedToolPolicy(allowed, denied []ToolPattern) ToolPolicy

NewRestrictedToolPolicy constructs an allow-list layer even when the list is empty, preserving explicit deny-all declarations across package seams.

func NewToolPolicy 

func NewToolPolicy(allowed, denied []ToolPattern) ToolPolicy

NewToolPolicy constructs one policy layer using defensive copies.

func (ToolPolicy) Allowed 

func (p ToolPolicy) Allowed() []ToolPattern

Allowed returns a defensive copy of the first policy layer's allow list.

func (ToolPolicy) Allows 

func (p ToolPolicy) Allows(tool, argument string) bool

Allows reports whether every nested layer allows a tool invocation.

func (ToolPolicy) Denied 

func (p ToolPolicy) Denied() []ToolPattern

Denied returns a defensive copy of the first policy layer's deny list.

func (ToolPolicy) Intersect 

func (p ToolPolicy) Intersect(other ToolPolicy) ToolPolicy

Intersect combines nested policies without widening either one.

func (ToolPolicy) Visible 

func (p ToolPolicy) Visible(tool string) bool

Visible reports whether a tool name has any invocation permitted by every layer. Argument-specific denies do not hide an otherwise usable tool.

type TurnScope 

type TurnScope struct {
	Policy        ToolPolicy
	Arguments     Arguments
	Variables     Variables
	DocumentPath  string
	DocumentTrust bool
}

TurnScope contains immutable-by-convention per-invocation syntax state.

type Variables 

type Variables struct {
	SessionID  string `json:"session_id"`
	SkillDir   string `json:"skill_dir"`
	ProjectDir string `json:"project_dir"`
	PluginRoot string `json:"plugin_root"`
	PluginData string `json:"plugin_data"`
	Effort     string `json:"effort"`
}

Variables are the only harness values available to substitution. Process environment variables are deliberately absent.

type YAMLError 

type YAMLError struct {
	Line    int
	Message string
}

YAMLError reports a stable one-based source line.

func (*YAMLError) Error 

func (e *YAMLError) Error() string

type YAMLField 

type YAMLField struct {
	Name  string    `json:"name"`
	Line  int       `json:"line"`
	Value YAMLValue `json:"value"`
}

YAMLField is one ordered mapping entry.

type YAMLKind 

type YAMLKind uint8

YAMLKind identifies a value in the supported YAML subset. 

const (
	YAMLScalar YAMLKind = iota + 1
	YAMLSequence
	YAMLMapping
)

type YAMLValue 

type YAMLValue struct {
	Kind     YAMLKind    `json:"kind"`
	Line     int         `json:"line"`
	Scalar   string      `json:"scalar"`
	Sequence []YAMLValue `json:"sequence"`
	Mapping  []YAMLField `json:"mapping"`
}

YAMLValue is a value in the supported YAML subset. Mapping order and duplicate keys are retained so document projection can warn deterministically.

func ParseYAML 

func ParseYAML(source string) (YAMLValue, error)

ParseYAML parses the intentionally small YAML subset used by syntax frontmatter. It supports ordered mappings, nested mappings, scalar sequences, flow scalar sequences, quoted scalars, and literal or folded block scalars. Aliases, tags, flow mappings, and complex keys are rejected.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.