codescripts

package
v0.57.0-rc.1 Latest Latest
Warning

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

Go to latest
Published: Aug 14, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package codescripts resolves and lists server-side stored scripts for the code_execution tool (Spec 097).

A stored script is a file named `<name>.js` or `<name>.ts` in the `scripts/` directory next to the ACTIVE configuration file. Callers address it by base NAME — never by path — and this package is the single owner of what a name may be, how it maps to a file, and what a usable script file looks like.

Confinement is the name validator, not the filesystem walk: a token-valid name contains no separators and no dots, so joining it to the scripts directory cannot escape that directory by construction (FR-003 / SC-003). ValidateName therefore runs before any filesystem call. On top of that boundary sits a symlink/non-regular POLICY, made atomic where the platform allows it (Unix O_NOFOLLOW) and best-effort where it does not (Windows).

Nothing here caches: each Resolve performs one open and one bounded read, so an atomic replacement of a script file is visible to the very next invocation with nothing to invalidate (FR-009).

Index

Constants

View Source
const (
	// MaxNameLen is the longest permitted script name.
	MaxNameLen = 64

	// MaxSizeBytes bounds the daemon-side read of a script file. Inline code
	// has no such bound; stored scripts do, purely to bound the read.
	MaxSizeBytes = 256 * 1024

	// MaxErrorNames is how many available names a not-found error lists
	// (FR-004); the total count is reported alongside.
	MaxErrorNames = 20

	// DirName is the scripts directory's name, relative to the config file.
	DirName = "scripts"

	// LanguageJavaScript / LanguageTypeScript are the languages a script
	// extension can derive, matching the code_execution `language` parameter.
	LanguageJavaScript = "javascript"
	LanguageTypeScript = "typescript"
)
View Source
const (
	ReasonEmpty      = "empty"
	ReasonOversized  = "oversized"
	ReasonUnreadable = "unreadable"
	ReasonNonRegular = "non-regular"
)

Reasons a script file is present but unusable.

Variables

This section is empty.

Functions

func DeriveLanguage

func DeriveLanguage(name, ext, explicitLanguage string) (string, error)

DeriveLanguage maps a script extension to a code_execution language and rejects an explicit language that contradicts it. An empty explicit language always agrees.

func DirFor

func DirFor(configFilePath string) string

DirFor returns the scripts directory belonging to a config file path. An empty config path yields an empty directory (no authority, no scripts).

func Resolve

func Resolve(scriptsDir, name, explicitLanguage string) (source []byte, language string, err error)

Resolve reads the stored script `name` from scriptsDir and returns its source together with the language derived from its extension.

Order matters: the name is validated BEFORE any filesystem call (SC-003), then the directory decides which candidates exist, then the surviving candidate is opened with the platform's no-follow idiom and read through a bounded reader. Exactly one open and one read per call — no cache, no re-read.

func ValidateName

func ValidateName(name string) error

ValidateName enforces the script-name token: 1-MaxNameLen characters of [A-Za-z0-9_-]. This is the confinement boundary and performs NO filesystem access — a valid name has no separators and no dots, so it cannot traverse.

Types

type AmbiguousError

type AmbiguousError struct {
	Name  string
	Paths []string
}

AmbiguousError reports a name backed by both a .js and a .ts file.

func (*AmbiguousError) Error

func (e *AmbiguousError) Error() string

type Entry

type Entry struct {
	Name   string   `json:"name"`
	Paths  []string `json:"paths"`
	Status Status   `json:"status"`
	Reason string   `json:"reason,omitempty"`
}

Entry is one listed script (FR-007). Paths holds the single source file, or both candidates when the name is ambiguous.

func List

func List(scriptsDir string) ([]Entry, error)

List enumerates the token-valid stored scripts in scriptsDir, alphabetically by name. An absent (or unset) directory is an empty list, not an error (FR-007). Statuses are advisory — Resolve re-checks at invocation time.

type InvalidError

type InvalidError struct {
	Name   string
	Path   string
	Reason string
	Detail string
}

InvalidError reports a script file that exists but cannot be executed.

func (*InvalidError) Error

func (e *InvalidError) Error() string

type InvalidNameError

type InvalidNameError struct {
	Name   string
	Reason string
}

InvalidNameError rejects a script name before any filesystem access.

func (*InvalidNameError) Error

func (e *InvalidNameError) Error() string

type LanguageMismatchError

type LanguageMismatchError struct {
	Name      string
	Extension string
	Requested string
	Derived   string
}

LanguageMismatchError reports an explicit `language` that contradicts the script's extension (the extension is authoritative).

func (*LanguageMismatchError) Error

func (e *LanguageMismatchError) Error() string

type NotFoundError

type NotFoundError struct {
	Name      string
	Dir       string
	Available []string // first MaxErrorNames ok names, alphabetical
	Total     int      // total ok scripts in the directory
}

NotFoundError reports a name with no script file behind it, carrying the available names so the caller can recover in one round trip (FR-004).

func (*NotFoundError) Error

func (e *NotFoundError) Error() string

type Status

type Status string

Status classifies a listed script.

const (
	StatusOK        Status = "ok"        // invocable
	StatusAmbiguous Status = "ambiguous" // both .js and .ts exist for this name
	StatusInvalid   Status = "invalid"   // present but not usable; see Reason
)

Jump to

Keyboard shortcuts

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