extension

package
v0.27.0 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package extension runs a Go extension from one value, as SDK in contract.md defines. It starts as ncly-<slug>, or as ncly compiled with the extension and started 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

View Source
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

func Check(e Extension) error

Check reports what Main would refuse. It also checks the catalog rules of SDK in contract.md and requires a skill's name to equal the slug. Every Go extension has a test that calls it.

func Export added in v0.18.0

func Export(e Extension, dir string) error

Export writes the sidecars of e into dir, as SDK in contract.md defines. They are the manifest as ncly-<slug>.toml, the catalogs as ncly-<slug>.locales/, and the skill as ncly-<slug>.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.

func Main

func Main(e Extension)

Main runs the extension as this process with the arguments of the process, then exits with its exit code.

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

func (c Call) Key(service string) (string, *contract.Problem)

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

func (c Call) Worker(name string) (string, *contract.Problem)

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-<slug>.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

type Frontmatter struct {
	Name        string
	Description string
}

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

type Handler func(ctx context.Context, call Call) contract.Outcome

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

Jump to

Keyboard shortcuts

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