core

type Alias ¶

type Alias struct {
	Tag     string
	ID      string
	Version string
}

Alias maps a runner keyword (for example, "py") to a canonical language ID and version. Aliases are derived from runner profiles, not hand-maintained.

func Aliases() []Alias

type Check ¶

type Check struct {
	ID      string
	Version string
	Tag     string
	Cmd     string
	Err     error
}

Check is one language examined during preflight.

type DefaultExecutor ¶

type DefaultExecutor struct{}

DefaultExecutor runs the selected interpreter with os/exec. Hosts can inject a different Executor into Execute to centralize subprocess policy.

func (DefaultExecutor) Run(ctx context.Context, cmd string, args []string, stdin []byte) (stdoutText, stderrText string, runErr error)

type Define ¶

type Define struct {
	ID           string   // required, e.g. "gleam"
	Version      string   // optional, e.g. "3"
	Ext          string   // required, including dot, e.g. ".gleam"
	Aliases      []string // optional, e.g. ["gleam", "beam"]
	Find         []string // required, e.g. ["gleam", "run"]
	Stdin        string   // "json" (default) | "text" | "raw"
	Stdout       string   // "json" (default) | "text" | "raw"
	FileTemplate string   // optional JSON-in/JSON-out source for .file :autocreate
	Install      OSRecipe // optional, per-OS install commands
	Deps         string   // optional command template containing {file}
	DepsMarker   string   // optional source marker that selects Deps
}

Define is the in-flow @lang.define directive's data model.

It lets users register a language the bundle doesn't ship built-in, without forking the repo or writing a runner file. Example DSL:

@lang.define "gleam" {
  ext: ".gleam"
  aliases: ["gleam"]
  find: ["gleam run"]
  stdin: "json"
  stdout: "text"
}
{ "value": "x" } -> gleam"..."

This is the runtime equivalent of a runners/*.nflow file — same fields, same RunnerSpec underneath. Definitions update the process-wide registry and remain registered for the process lifetime; each (ID, Version) and alias must be declared only once.

type Ensure ¶

type Ensure interface {
	Ensure(lang *Language, version string) (cmd string, args []string, err error)
}

Ensure is the auto-install seam.

Resolve calls Ensure when a language's Select (find-only) fails. The default installEnsure runs the runner's per-OS recipe and re-resolves the interpreter; tests or hosts can replace the hook when needed.

Pure Go: no nexssp/ensure, no Node.js. Recipes call winget/brew/apt/npm directly. See install.go.

func DefaultEnsure() Ensure

type EnsureFunc ¶

type EnsureFunc func(*Language, string) (string, []string, error)

EnsureFunc adapts a function to the Ensure interface.

func (f EnsureFunc) Ensure(language *Language, version string) (cmd string, args []string, err error)

type ExecError ¶

type ExecError struct {
	ID     string
	Cmd    string
	Cause  error
	Stderr string
}

ExecError is returned when an interpreter process exits unsuccessfully.

func (e *ExecError) Error() string

func (e *ExecError) Unwrap() error

type Executor ¶

type Executor interface {
	Run(ctx context.Context, cmd string, args []string, stdin []byte) (stdout, stderr string, err error)
}

Executor runs one resolved program and returns stdout and stderr as strings. Implementations must honor context cancellation.

type ExecutorFunc ¶

type ExecutorFunc func(context.Context, string, []string, []byte) (string, string, error)

ExecutorFunc adapts a function to the Executor interface.

func (f ExecutorFunc) Run(ctx context.Context, cmd string, args []string, stdin []byte) (stdout, stderr string, err error)

type Language ¶

type Language struct {
	// ID is the canonical language identifier, e.g. "python".
	ID string

	// Ext is the file extension used when materializing source to disk,
	// including the leading dot, e.g. ".py".
	Ext string

	// Select is the legacy context-free, find-only selector for languages
	// registered directly. Runner profiles use SelectContext instead.
	Select func(version string) (cmd string, args []string, err error)
	// SelectContext resolves a version while honoring the caller's context.
	// Runtime and preflight resolution prefer this selector when available.
	SelectContext func(ctx context.Context, version string) (cmd string, args []string, err error)

	// Encode serializes the incoming stream value to bytes for stdin.
	// JSON is the default; shell/raw languages use text.
	Encode func(v any) ([]byte, error)

	// Decode parses stdout back into a typed value the next atom sees.
	// Takes string (not []byte) to avoid the []byte(string) copy from
	// external.ExecResult.Stdout. JSON is the default; shell/raw return string.
	Decode func(s string) (any, error)
	// contains filtered or unexported fields
}

Language is the runtime view of a runner spec. One per (language, version). Tags are gone by here — runner file aliases are applied at parse time, and from this struct onward every code path speaks the canonical ID ("python"), never the tag ("py").

One struct, every language. New languages add a runners/<id>.nflow file, zero Go changes. See runners.go.

func Lookup(id, version string) (*Language, error)

func (l *Language) Spec() (RunnerSpec, bool)

func (l *Language) Version() string

type NotInstalledError ¶

type NotInstalledError struct {
	ID, Version string
	Cause       error // optional: why an auto-install attempt failed
}

NotInstalledError is the unified "interpreter missing" error. Preflight groups these into a single Report; the CLI prints the report and aborts.

func (e *NotInstalledError) Error() string

func (e *NotInstalledError) Unwrap() error

type OSRecipe ¶

type OSRecipe struct {
	Windows []string `json:"windows,omitempty"`
	Darwin  []string `json:"darwin,omitempty"`
	Linux   []string `json:"linux,omitempty"`
}

OSRecipe holds per-OS install commands. Each entry is a full command line; the first element is the binary, the rest are args.

func (r OSRecipe) RecipeFor() []string

type Preflight ¶

type Preflight struct {
	// Installer, if non-nil, is invoked for missing interpreters. A nil
	// Installer keeps preflight find-only.
	Installer Ensure
}

Preflight checks interpreter availability for a set of programs. It has no compiler or AST dependency; host adapters decide when and how to invoke it.

func (p Preflight) Run(programs []Program) Report

func (p Preflight) RunContext(ctx context.Context, programs []Program) Report

type Program ¶

type Program struct {
	ID         string
	Version    string
	Source     string
	Tag        string
	SourceFile string
}

Program describes source to execute with a registered language runner. It contains no parser- or compiler-specific data.

func FileProgramForTag(tag, sourceFile, source string) (Program, error)

func ProgramForTag(tag, source string) (Program, error)

type Report ¶

type Report struct {
	Checked []Check
	Missing []Check
}

Report is the result of a preflight pass. Zero Missing entries means every requested interpreter is available (or was installed successfully).

func (r Report) Error() string

func (r Report) OK() bool

func (r Report) SelfTestSkipReason() string

type RunnerSpec ¶

type RunnerSpec struct {
	ID               string   `json:"id,omitempty"`
	Version          string   `json:"version,omitempty"`
	Ext              string   `json:"ext"`
	Aliases          []string `json:"aliases,omitempty"`
	Find             []string `json:"find"`
	Stdin            string   `json:"stdin,omitempty"`
	Stdout           string   `json:"stdout,omitempty"`
	FileTemplate     string   `json:"file_template,omitempty"`
	FileTemplateFile string   `json:"file_template_file,omitempty"`
	FilePathMode     string   `json:"file_path_mode,omitempty"`
	Install          OSRecipe `json:"install,omitzero"`
	Deps             string   `json:"deps,omitempty"`
	DepsMarker       string   `json:"deps_marker,omitempty"`
}

RunnerSpec is the data model parsed from a @lang.runner block in a .nflow file. One RunnerSpec per (language, version). The Go side is generic — adding a language means shipping a runner profile and optional template asset, with no runtime-specific Go changes.

Native profile example:

@description "Python runner with JSON streams"
@lang.runner "python" {
  ext: ".py"
  aliases: ["py", "python"]
  find: ["python3", "python", "py -3"]
  stdin: "json"
  stdout: "json"
  file_template_file: "templates/python.py"
}

func ParseRunner(src string) (*RunnerSpec, error)

func (s RunnerSpec) Decode() (func(string) (any, error), error)

func (s RunnerSpec) Encode() (func(any) ([]byte, error), error)

func (s RunnerSpec) FindCmd() (cmd string, args []string, err error)

func (s RunnerSpec) FindCmdContext(ctx context.Context) (cmd string, args []string, err error)

type UnknownLanguageError ¶

type UnknownLanguageError struct {
	ID, Version string
}

UnknownLanguageError is returned by Lookup and ParseTag when the alias resolves to an (ID, Version) pair the Registry has no entry for. It surfaces as a compile-time SourceError via the parser hook.

func (e *UnknownLanguageError) Error() string

func (e *UnknownLanguageError) Unwrap() error

type UnknownTagError ¶

type UnknownTagError struct{ Tag string }

UnknownTagError reports an alias which is not registered by a runner.

func (e *UnknownTagError) Error() string