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
- func DeriveLanguage(name, ext, explicitLanguage string) (string, error)
- func DirFor(configFilePath string) string
- func Resolve(scriptsDir, name, explicitLanguage string) (source []byte, language string, err error)
- func ValidateName(name string) error
- type AmbiguousError
- type Entry
- type InvalidError
- type InvalidNameError
- type LanguageMismatchError
- type NotFoundError
- type Status
Constants ¶
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" )
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
type InvalidError ¶
InvalidError reports a script file that exists but cannot be executed.
func (*InvalidError) Error ¶
func (e *InvalidError) Error() string
type InvalidNameError ¶
InvalidNameError rejects a script name before any filesystem access.
func (*InvalidNameError) Error ¶
func (e *InvalidNameError) Error() string
type LanguageMismatchError ¶
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