Documentation
¶
Overview ¶
Package pwsh provides a persistent PowerShell session for lore.
Architecture: Why a persistent session? ¶
Starlark is the orchestration layer (logic, control flow, variables). The execution backend differs by platform:
- Unix: stateless shell.run() is fine — each command is a new process.
- Windows: a persistent PowerShell session is the natural backend.
PowerShell modules (Az, ActiveDirectory, PackageManagement) establish authenticated sessions on import. COM/.NET objects (WMI, Registry, IIS) are expensive to instantiate. DSC operations require compile→test→apply within a single session. Spawning `pwsh -Command` for each operation loses all of this state.
This package is intended as a Starlark binding (pwsh.run, pwsh.set) — the Starlark script decides what to do, the PowerShell session handles how on Windows.
Usage ¶
Commands run directly in session scope. Variables, functions, and module imports persist across calls. If a command calls `exit N`, the session terminates and the exit code is captured from the process state.
ps, _ := pwsh.New()
defer ps.Close()
ps.Run("$greeting = 'Hello'")
result := ps.Run("Write-Output $greeting")
fmt.Println(result.Stdout) // "Hello"
Index ¶
- func Available() bool
- func Bootstrap() error
- func Ensure() error
- func Version() (string, error)
- type Result
- type Session
- func (s *Session) Audit(w io.Writer) *Session
- func (s *Session) Close() error
- func (s *Session) History() []*Result
- func (s *Session) Must(command string) *Result
- func (s *Session) Run(command string) *Result
- func (s *Session) Script(commands ...string) *Result
- func (s *Session) Set(name, value string) *Session
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Bootstrap ¶
func Bootstrap() error
Bootstrap installs PowerShell if not present. This is platform-specific and may require elevated privileges.
Types ¶
type Result ¶
type Result struct {
Command string `json:"command"`
Stdout string `json:"stdout,omitempty"`
Stderr string `json:"stderr,omitempty"`
ExitCode int `json:"exit_code"`
Start time.Time `json:"start"`
Duration time.Duration `json:"duration"`
Error string `json:"error,omitempty"`
}
Result captures the output of a PowerShell command.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is a persistent PowerShell session.
func New ¶
New creates and starts a new PowerShell session. Returns an error if PowerShell is not installed or fails to start.
func (*Session) Run ¶
Run executes a PowerShell command and returns the result. Commands run directly in session scope, so variables persist across calls. If the command calls `exit N`, the session terminates and the exit code is captured from the process state.
Source Files