Documentation
¶
Overview ¶
Package extension runs a Go extension from one value, as SDK in contract.md defines: started as ncly-<domain>, or compiled into ncly and started by it under that name. Either way it parses the call with its manifest, runs the handler of the command, and prints the answer by the kind of the command's result.
A run that asks for a worker gets every worker of Resources in a private temporary folder. The SDK removes that folder once the handler returns, so no handler deletes it. After a signal, the folder goes a second before cleanup ends at the latest, because core then sends SIGKILL.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoFrontmatter = errors.New("no valid frontmatter")
ErrNoFrontmatter reports a SKILL.md without a frontmatter, or whose frontmatter is not a YAML mapping of strings.
Functions ¶
func Check ¶
Check reports what Main would refuse, a catalog that breaks the catalog rules of SDK in contract.md, and a skill whose name is not the domain. Every Go extension has a test that calls it.
func Export ¶ added in v0.18.0
Export writes the sidecars of e into dir, as SDK in contract.md defines. They are the manifest as ncly-<domain>.toml, the catalogs as ncly-<domain>.locales/, and the skill as ncly-<domain>.skill/. An install that calls it takes them from the build under test, never from the source tree. Each sidecar replaces the one of the same name. A file that e no longer holds goes, and so does the skill folder when e has no skill. Export writes no executable.
Types ¶
type Call ¶
type Call struct {
// Path is the command path, such as "hello run".
Path string
// Args holds the positional arguments.
Args []string
// Flags holds each flag that the caller set, by long name, except a
// variadic one. A switch holds "true" or "false".
Flags map[string]string
// Lists holds each variadic flag that the caller set, by long name,
// with its values in the caller's order.
Lists map[string][]string
JSON bool
Mode contract.Mode
Printer *i18n.Printer
Stdin io.Reader
// Stdout takes human text only: the SDK prints the answer. Under --json,
// it discards what a command other than a text command writes.
Stdout io.Writer
Stderr io.Writer
// contains filtered or unexported fields
}
Call is one validated call of a command.
func (Call) Key ¶ added in v0.18.0
Key returns the key of a service that the command declares, from the variable that core sets for a key that a human granted, or the problem that NCLY_MISSING_KEYS names for the service, with the hint and the next of Grants in contract.md, so a handler returns that problem and never builds one. A service whose variable is empty and that NCLY_MISSING_KEYS does not name, as when ncly-<domain> runs directly, gets AUTH_MISSING. A service that the command does not declare gets RUNTIME, because core never passes its key.
func (Call) Requirement ¶ added in v0.18.0
func (c Call) Requirement(program string) (contract.Requirement, bool)
Requirement returns the entry in programs of a program that the command declares in requires.bins. It returns false for any other program. sdk/wrap reads it to check a program as doctor does.
func (Call) Worker ¶ added in v0.18.0
Worker returns the absolute path of a worker that Resources holds, such as "count.sh" for worker/count.sh, or the problem that stops the call. The first call of a run extracts every worker into a private temporary folder. The SDK removes that folder once the handler returns.
type Extension ¶
type Extension struct {
// Manifest holds manifest.toml.
Manifest []byte
// Locales holds locales/<lang>.toml.
Locales fs.FS
// Skill holds skill/SKILL.md and the files that it names, which teach
// an agent the extension's commands. Installing an external extension
// writes them as ncly-<domain>.skill/. It is nil for an extension that
// ships no skill.
Skill fs.FS
// Resources holds worker/, the workers that the extension embeds, such
// as a user's script. Call.Worker extracts them for a run. It is nil for
// an extension that embeds no worker.
Resources fs.FS
// Handlers holds one handler per command that runs, keyed by path,
// such as "hello run".
Handlers map[string]Handler
}
Extension is a Go extension: its manifest, its catalogs, and one handler per command that runs.
type Frontmatter ¶ added in v0.18.0
Frontmatter holds the keys of the frontmatter of a SKILL.md that Nicely reads.
func ParseSkill ¶ added in v0.18.0
func ParseSkill(data []byte) (Frontmatter, error)
ParseSkill reads the frontmatter of a SKILL.md: the YAML between a first line --- and the next line ---, as the Agent Skills specification defines it. A file without one, whose YAML is invalid, or whose name or description is not a string is ErrNoFrontmatter, and one whose name or description is missing or empty is a MissingKeyError.
type Handler ¶
Handler runs one validated call. ctx ends on the first Ctrl-C or SIGTERM, and the handler then returns what it has.
type MissingKeyError ¶ added in v0.18.0
type MissingKeyError struct {
Key string
}
MissingKeyError reports a SKILL.md whose frontmatter lacks a key that a skill needs, or leaves it empty.
func (*MissingKeyError) Error ¶ added in v0.18.0
func (e *MissingKeyError) Error() string