star

package
v0.1.0-dev.20260813053751 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package star provides the runtime types and execution engine for the star CLI.

Index

Constants

This section is empty.

Variables

View Source 
var DryRun bool

DryRun is set by the --dry-run global flag.

When true, bindings with side effects (fs.write, fs.mkdir, fs.remove, etc.) log what they would do instead of executing.

Functions

This section is empty.

Types

type Application 

type Application struct {
	// contains filtered or unexported fields
}

Application manages Starlark script execution for the star CLI.

Holds the extension registry, the loaded-command map keyed by space-separated name, the unified config (lazily initialized), the starlarkbridge.Runtime, a typed reference to the application.Application whose Flags / Overrides this Application populates and refreshes, and the op.RuntimeEnvironment this Application owns. The bridge borrows the env; star.Application closes it on shutdown.

func NewApplication 

func NewApplication(rootCmd *cobra.Command) *Application

NewApplication creates a new star Application with a fully initialized Starlark runtime.

Constructs the receiver registry, builds a op.RuntimeEnvironmentSpec (with the active cobra command's flag projection on the application.Application), and hands the spec to starlarkbridge.NewRuntime which builds the session env. The star Application is the session owner — its Application.Close releases the env.

After the bridge is built, populates application.Application.Overrides with two star-internal handles that providers read at construction time via op.RuntimeEnvironment.RegisterParameter:

The `current_command` is mutated per-cobra-dispatch by Command.Run; the `commands` provider reads it directly from Overrides.

Parameters:

  • `rootCmd`: the cobra root command. Its persistent-flag surface drives the Application's Flags map.

Returns:

func (*Application) Close 

func (r *Application) Close() error

Close releases the underlying op.RuntimeEnvironment this Application owns. Idempotent via op.RuntimeEnvironment.Close's sync.Once. Callers `defer runtime.Close()` in main.

Returns:

  • `error`: the joined error from closing the env's owned resources, or nil on success.

func (*Application) CommandFlags 

func (r *Application) CommandFlags(name string) []commands.CommandFlag

CommandFlags returns the flag descriptors for the registered command identified by name.

Implements the commands.CommandTree contract. Accepts dotted or space-separated names by normalizing dots to spaces. Returns nil when no command matches.

Parameters:

  • name: the dotted or space-separated command name.

Returns:

  • []commands.CommandFlag: the flag descriptors, or nil if name does not match.

func (*Application) CommandHelp 

func (r *Application) CommandHelp(name string) string

CommandHelp returns the help text for the registered command identified by name.

Implements the commands.CommandTree contract. Accepts dotted or space-separated names by normalizing dots to spaces. Returns the empty string when no command matches.

Parameters:

  • name: the dotted or space-separated command name.

Returns:

  • string: the help text, or "" if name does not match.

func (*Application) CommandNames 

func (r *Application) CommandNames() []string

CommandNames returns the names of every registered command in space-separated form.

Implements the commands.CommandTree contract. Order is not guaranteed.

Returns:

  • []string: the registered command names.

func (*Application) Commands 

func (r *Application) Commands() map[string]*Command

Commands returns the map of registered commands keyed by space-separated command name.

Returns:

  • map[string]*Command: the registered commands.

func (*Application) Config 

func (r *Application) Config() *config.Config

Config returns the unified config, lazily initializing it on first access.

Returns:

  • *config.Config: the unified config.

func (*Application) DiscoverAndLoad 

func (r *Application) DiscoverAndLoad(loader *ExtensionLoader) error

DiscoverAndLoad uses the given loader to discover extensions, then registers and activates them.

Single entry point for extension loading. Discovery parses and deduplicates the candidate set; registration adds each extension to the registry, registers its config schema (when present), and reads config files; activation binds config to extensions and parses each extension's starlark commands into the application's command map.

Parameters:

  • loader: the extension loader configured with the search paths to scan.

Returns:

  • error: non-nil if discovery, registration, config loading, or activation fails.

func (*Application) Environment 

func (r *Application) Environment() *op.RuntimeEnvironment

Environment returns the runtime environment owned by the application's starlarkbridge runtime.

Returns:

  • *op.RuntimeEnvironment: the application's runtime environment.

func (*Application) LoadExtensionsFrom 

func (r *Application) LoadExtensionsFrom(dir string) error

LoadExtensionsFrom loads extensions from a specific directory.

Used by tests that need to load from a known path without the full discovery flow. Duplicate registrations are silently skipped to keep test isolation simple.

Parameters:

  • dir: the directory to scan for extensions.

Returns:

  • error: non-nil if discovery, config registration, config loading, or activation fails.

func (*Application) Refresh 

func (r *Application) Refresh(cmd *cobra.Command)

Refresh repopulates application.Application.Flags from the cobra command's parsed argv. Intended to be invoked from cobra.Command.PersistentPreRunE so the framework sees the user's actual `--dry-run` / `--silent` / etc. values at command-dispatch time, not the zero values present at process startup.

Parameters:

  • `cmd`: the cobra command whose parsed flags drive the refresh.

func (*Application) Registry 

func (r *Application) Registry() *ExtensionRegistry

Registry returns the extension registry.

Returns:

  • *ExtensionRegistry: the extension registry.

func (*Application) RunCommand 

func (r *Application) RunCommand(name string, flags map[string]string, positional ...string) error

RunCommand executes the registered command identified by name with the given flags and positional args.

Implements the commands.CommandTree contract. The name is matched against the space-separated form stored in the command map.

Parameters:

  • name: the space-separated command name (e.g., "lint go").
  • flags: the parsed flag values.
  • positional: the positional arguments.

Returns:

  • error: non-nil if no command matches name or if command execution fails.

type Arg 

type Arg struct {
	Name     string `yaml:"name"`
	Help     string `yaml:"help"`
	Default  string `yaml:"default"`
	Variadic bool   `yaml:"variadic"`
}

Arg represents a positional argument.

type Command 

type Command struct {
	// YAML fields.
	Name           string `yaml:"name"`
	Help           string `yaml:"help"`
	Implementation string `yaml:"implementation"`
	Args           []Arg  `yaml:"args"`
	Flags          []Flag `yaml:"flags"`

	// Runtime fields — set after unmarshaling.
	Extension *Extension        `yaml:"-"`
	RunFunc   starlark.Callable `yaml:"-"`
	// contains filtered or unexported fields
}

Command is an immutable object representing a single command within an extension. YAML fields are deserialized from the commands: section of extension.yaml. Runtime fields are set during extension loading.

func (*Command) Attr 

func (c *Command) Attr(name string) (starlark.Value, error)

Attr implements starlark.HasAttrs.

func (*Command) AttrNames 

func (c *Command) AttrNames() []string

AttrNames implements starlark.HasAttrs.

func (*Command) Freeze 

func (c *Command) Freeze()

Freeze implements starlark.Value.

func (*Command) Hash 

func (c *Command) Hash() (uint32, error)

Hash implements starlark.Value.

func (*Command) Run 

func (c *Command) Run(flags map[string]string, positional ...string) error

Run executes the command with the given flag values and optional positional arguments.

func (*Command) String 

func (c *Command) String() string

String implements starlark.Value.

func (*Command) Truth 

func (c *Command) Truth() starlark.Bool

Truth implements starlark.Value.

func (*Command) Type 

func (c *Command) Type() string

Type implements starlark.Value.

type ConfigNested 

type ConfigNested struct {
	Fields map[string]string       `yaml:"fields"`
	Nested map[string]ConfigNested `yaml:"nested,omitempty"`
}

ConfigNested describes a struct type used within an extension's config fields.

type ConfigSchema 

type ConfigSchema struct {
	Path     string                  `yaml:"path"`
	Type     string                  `yaml:"type"`
	Fields   map[string]string       `yaml:"fields"`
	Nested   map[string]ConfigNested `yaml:"nested"`
	Defaults map[string]interface{}  `yaml:"defaults"`
}

ConfigSchema describes the configuration schema for an extension.

type Extension 

type Extension struct {
	// YAML fields — populated by UnmarshalYAML.
	Name        string        `yaml:"extension"`
	Description string        `yaml:"description"`
	Commands    []*Command    `yaml:"commands"`
	Config      *ConfigSchema `yaml:"config"`

	// Runtime fields — set after unmarshaling.
	Source Source `yaml:"-"`
	Dir    string `yaml:"-"`
	FS     fs.FS  `yaml:"-"`
	// contains filtered or unexported fields
}

Extension is the immutable identity and context for a loaded extension. YAML fields are deserialized directly via UnmarshalYAML. Runtime fields are set by the discovery and loading code after unmarshaling.

func (*Extension) Attr 

func (e *Extension) Attr(name string) (starlark.Value, error)

Attr implements starlark.HasAttrs.

func (*Extension) AttrNames 

func (e *Extension) AttrNames() []string

AttrNames implements starlark.HasAttrs.

func (*Extension) ConfigPath 

func (e *Extension) ConfigPath() string

ConfigPath returns the dotted path where this extension's config is registered.

func (*Extension) Freeze 

func (e *Extension) Freeze()

Freeze implements starlark.Value.

func (*Extension) GetCommand 

func (e *Extension) GetCommand(name string) *Command

GetCommand returns the Command for the given name, or nil if not found.

func (*Extension) HasCommands 

func (e *Extension) HasCommands() bool

HasCommands returns true if this extension provides CLI commands.

func (*Extension) HasConfig 

func (e *Extension) HasConfig() bool

HasConfig returns true if this extension has a configuration schema.

func (*Extension) Hash 

func (e *Extension) Hash() (uint32, error)

Hash implements starlark.Value.

func (*Extension) ResolveConfig 

func (e *Extension) ResolveConfig() *config.Accessor

ResolveConfig returns the resolved config accessor for this extension on demand.

func (*Extension) SetConfig 

func (e *Extension) SetConfig(cfg *config.Config)

SetConfig sets the reference to the unified config tree.

func (*Extension) String 

func (e *Extension) String() string

String implements starlark.Value.

func (*Extension) ToConfigSpec 

func (e *Extension) ToConfigSpec() config.Spec

ToConfigSpec converts the extension's ConfigSchema to config.Spec.

func (*Extension) Truth 

func (e *Extension) Truth() starlark.Bool

Truth implements starlark.Value.

func (*Extension) Type 

func (e *Extension) Type() string

Type implements starlark.Value.

func (*Extension) Validate 

func (e *Extension) Validate() error

Validate checks that the extension is well-formed.

type ExtensionLoader 

type ExtensionLoader struct {
	// contains filtered or unexported fields
}

ExtensionLoader discovers, parses, and deduplicates extensions from the filesystem and embedded sources. It holds the search paths and embedded FS as state.

func NewExtensionLoader 

func NewExtensionLoader(embeddedFS fs.FS) *ExtensionLoader

NewExtensionLoader creates a loader with the given embedded FS and default search paths.

func NewExtensionLoaderWithPaths 

func NewExtensionLoaderWithPaths(searchPaths []string, embeddedFS fs.FS) *ExtensionLoader

NewExtensionLoaderWithPaths creates a loader with explicit search paths and the given embedded FS. Used by tests that need to control the search order.

func (*ExtensionLoader) DefaultSearchPaths 

func (l *ExtensionLoader) DefaultSearchPaths() []string

DefaultSearchPaths returns the search paths this loader will use.

func (*ExtensionLoader) DiscoverAll 

func (l *ExtensionLoader) DiscoverAll() ([]*Extension, error)

DiscoverAll walks all search paths and embedded sources in priority order, parses each extension.yaml into *Extension, and deduplicates by name (first seen wins). Returns an ordered slice of the winners.

func (*ExtensionLoader) FindExtensionDir 

func (l *ExtensionLoader) FindExtensionDir(name string) (string, error)

FindExtensionDir locates the directory containing an extension by name. Searches the loader's search paths and returns the path to the extension directory. Extension directories use the extension name directly (reverse domain format).

type ExtensionRegistry 

type ExtensionRegistry struct {
	// contains filtered or unexported fields
}

ExtensionRegistry holds registered extensions. Used for debugging and listing loaded extensions from the command line.

func NewExtensionRegistry 

func NewExtensionRegistry() *ExtensionRegistry

NewExtensionRegistry creates an empty registry.

func (*ExtensionRegistry) All 

func (r *ExtensionRegistry) All() map[string]*Extension

All returns a copy of all registered extensions.

func (*ExtensionRegistry) Clear 

func (r *ExtensionRegistry) Clear()

Clear removes all extensions from the registry.

func (*ExtensionRegistry) Count 

func (r *ExtensionRegistry) Count() int

Count returns the number of registered extensions.

func (*ExtensionRegistry) Get 

func (r *ExtensionRegistry) Get(name string) *Extension

Get returns an extension by name, or nil if not found.

func (*ExtensionRegistry) Names 

func (r *ExtensionRegistry) Names() []string

Names returns a sorted list of registered extension names.

func (*ExtensionRegistry) Register 

func (r *ExtensionRegistry) Register(ext *Extension) error

Register adds an extension to the registry. Returns an error if an extension with the same name is already registered.

type Flag 

type Flag struct {
	Name     string `yaml:"name"`
	Type     string `yaml:"type"`
	Help     string `yaml:"help"`
	Default  string `yaml:"default"`
	Required bool   `yaml:"required"`
}

Flag represents a command flag.

type Source 

type Source int

Source identifies where an extension was discovered. 

const (
	SourceProjectLocal Source = iota // ${GIT_WORKSPACE_ROOT}/star/extensions/
	SourceUser                       // ${XDG_DATA_HOME}/star/extensions/
	SourceSystem                     // /usr/local/share/star/extensions/
	SourceEmbedded                   // compiled into binary via //go:embed
)

The extension discovery locations, in precedence order.

func (Source) String 

func (s Source) String() string

String returns the human-readable name of the source.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.