ork

README

Ork

Ork is a Go package for SSH-based server automation. Think of it like Ansible, but in Go - you define Nodes (remote servers), organize them into Groups, and run commands or playbooks against them individually or at scale via Inventory.

Installation

go get github.com/dracory/ork

Quick Start

The core concept is the Node - a representation of a remote server:

package main

import (
    "log"
    "github.com/dracory/ork"
    "github.com/dracory/ork/config"
)

func main() {
    // Create a node (remote server) - multiple ways:
    
    // Option 1: From host (most common)
    node := ork.NewNodeForHost("server.example.com")
    
    // Option 2: From config (useful for complex setups)
    cfg := config.NodeConfig{
        SSHHost: "server.example.com",
        SSHPort: "22",
    }
    node := ork.NewNodeFromConfig(cfg)
    
    // Run a command
    results := node.RunCommand("uptime")
    result := results.Results["server.example.com"]
    if result.Error != nil {
        log.Fatal(result.Error)
    }
    log.Println(result.Message)
}

Vault (Secure Secrets Management)

Ork provides secure vault support for managing sensitive data like passwords and API keys. The vault uses encrypted storage with two loading strategies:

Load to Memory (Recommended for Security)

Secrets are loaded into a memory map, keeping them isolated from the rest of the process:

// Simple one-liner with interactive password prompt
secrets, err := ork.VaultFileToKeysWithPrompt(".env.vault")
if err != nil {
    log.Fatal(err)
}
dbPassword := secrets["DATABASE_PASSWORD"]

// Or separate prompt and load for custom workflows
password, err := ork.PromptPassword("Vault password: ")
if err != nil {
    log.Fatal(err)
}
secrets, err := ork.VaultFileToKeys(".env.vault", password)
if err != nil {
    log.Fatal(err)
}

Load to Environment (For .env Compatibility)

Secrets are loaded into environment variables for compatibility with tools that expect .env files:

// Simple one-liner with interactive password prompt
if err := ork.VaultFileToEnvWithPrompt(".env.vault"); err != nil {
    log.Fatal(err)
}
// Secrets now available via os.Getenv()

// Or separate prompt and load
password, err := ork.PromptPassword("Vault password: ")
if err != nil {
    log.Fatal(err)
}
if err := ork.VaultFileToEnv(".env.vault", password); err != nil {
    log.Fatal(err)
}

Available Functions

Load to Memory:

• VaultFileToKeys(filePath, password) - Load from file to map
• VaultContentToKeys(content, password) - Load from string to map
• VaultFileToKeysWithPrompt(filePath) - Load from file with interactive prompt
• VaultContentToKeysWithPrompt(content) - Load from string with interactive prompt

Load to Environment:

• VaultFileToEnv(filePath, password) - Load from file to environment
• VaultContentToEnv(content, password) - Load from string to environment
• VaultFileToEnvWithPrompt(filePath) - Load from file with interactive prompt
• VaultContentToEnvWithPrompt(content) - Load from string with interactive prompt

Utilities:

• PromptPassword(prompt) - Securely prompt for password from stdin (no echo)

Creating a Vault File

Use the envenc CLI tool to create encrypted vault files:

# Initialize a new vault
envenc init .env.vault

# Set secrets
envenc set DATABASE_PASSWORD "my-secret-password"
envenc set API_KEY "my-api-key"

# List keys
envenc list .env.vault

Design Trade-offs

ToKeys functions:

• Secrets stored in memory map
• No global exposure
• Recommended for security-sensitive applications
• Caller manages secret lifecycle

ToEnv functions:

• Secrets dumped to environment variables
• Global exposure via os.Getenv
• For compatibility with .env-based tooling
• Use when external tools expect environment variables

Configuration

Use the fluent API to configure connection settings:

// From host
node := ork.NewNodeForHost("server.example.com").
    SetPort("2222").
    SetUser("deploy").
    SetKey("production.prv")

results := node.RunCommand("uptime")
result := results.Results["server.example.com"]
if result.Error != nil {
    log.Fatal(result.Error)
}
output := result.Message

Persistent Connections

For multiple operations, establish a persistent connection:

node := ork.NewNodeForHost("server.example.com").
    SetPort("2222").
    SetUser("deploy")

if err := node.Connect(); err != nil {
    log.Fatal(err)
}
defer node.Close()

// These commands reuse the same SSH connection
results1 := node.RunCommand("uptime")
results2 := node.RunCommand("df -h")
output1 := results1.Results["server.example.com"].Message
output2 := results2.Results["server.example.com"].Message

Playbooks

Run pre-built automation tasks (playbooks) against a node:

node := ork.NewNodeForHost("server.example.com").
    SetArg("username", "alice").
    SetArg("shell", "/bin/bash")

results := node.RunPlaybook(playbooks.NewUserCreate())
result := results.Results["server.example.com"]
if result.Error != nil {
    log.Fatalf("Playbook failed: %v", result.Error)
}
if result.Changed {
    log.Printf("User created: %s", result.Message)
} else {
    log.Println("User already exists - no changes made")
}

Available Playbooks

ork Package	playbook Package	String	Args	Description
PlaybookPing	IDPing	ping	-	Check SSH connectivity
PlaybookAptUpdate	IDAptUpdate	apt-update	-	Refresh package database
PlaybookAptUpgrade	IDAptUpgrade	apt-upgrade	-	Install available updates
PlaybookAptStatus	IDAptStatus	apt-status	-	Show available updates
PlaybookReboot	IDReboot	reboot	-	Reboot server
PlaybookSwapCreate	IDSwapCreate	swap-create	size (GB)	Create swap file
PlaybookSwapDelete	IDSwapDelete	swap-delete	-	Remove swap file
PlaybookSwapStatus	IDSwapStatus	swap-status	-	Show swap status
PlaybookUserCreate	IDUserCreate	user-create	username	Create user with sudo
PlaybookUserDelete	IDUserDelete	user-delete	username	Delete user
PlaybookUserStatus	IDUserStatus	user-status	username (opt)	Show user info
PlaybookFail2banInstall	IDFail2banInstall	fail2ban-install	-	Install and configure fail2ban
PlaybookFail2banStatus	IDFail2banStatus	fail2ban-status	-	Show fail2ban status
PlaybookUfwInstall	IDUfwInstall	ufw-install	-	Install UFW firewall
PlaybookUfwStatus	IDUfwStatus	ufw-status	-	Show UFW status
PlaybookUfwAllowMariadb	IDUfwAllowMariadb	ufw-allow-mariadb	-	Allow MariaDB through UFW
PlaybookMariadbInstall	IDMariadbInstall	mariadb-install	-	Install MariaDB server
PlaybookMariadbStatus	IDMariadbStatus	mariadb-status	-	Show MariaDB status
PlaybookMariadbSecure	IDMariadbSecure	mariadb-secure	-	Secure MariaDB installation
PlaybookMariadbBackup	IDMariadbBackup	mariadb-backup	database (opt)	Backup database
PlaybookMariadbBackupEncrypt	IDMariadbBackupEncrypt	mariadb-backup-encrypt	-	Encrypted backup
PlaybookMariadbChangePort	IDMariadbChangePort	mariadb-change-port	port	Change MariaDB port
PlaybookMariadbCreateDB	IDMariadbCreateDB	mariadb-create-db	database	Create database
PlaybookMariadbCreateUser	IDMariadbCreateUser	mariadb-create-user	username, password	Create DB user
PlaybookMariadbEnableEncryption	IDMariadbEnableEncryption	mariadb-enable-encryption	-	Enable encryption at rest
PlaybookMariadbEnableSSL	IDMariadbEnableSSL	mariadb-enable-ssl	-	Enable SSL connections
PlaybookMariadbListDBs	IDMariadbListDBs	mariadb-list-dbs	-	List databases
PlaybookMariadbListUsers	IDMariadbListUsers	mariadb-list-users	-	List DB users
PlaybookMariadbSecurityAudit	IDMariadbSecurityAudit	mariadb-security-audit	-	Run security audit
PlaybookSecurityAideInstall	IDSecurityAideInstall	security-aide-install	-	Install AIDE IDS
PlaybookSecurityAuditdInstall	IDSecurityAuditdInstall	security-auditd-install	-	Install audit daemon
PlaybookSecurityKernelHarden	IDSecurityKernelHarden	security-kernel-harden	-	Apply kernel hardening
PlaybookSecuritySSHChangePort	IDSecuritySSHChangePort	security-ssh-change-port	port	Change SSH port
PlaybookSecuritySSHHarden	IDSecuritySSHHarden	security-ssh-harden	-	Harden SSH config

Inventory (Multi-Node Operations)

Manage multiple servers with the same API:

// Create inventory
inv := ork.NewInventory()

// Add nodes to groups
webGroup := ork.NewGroup("webservers")
webGroup.AddNode(ork.NewNodeForHost("web1.example.com"))
webGroup.AddNode(ork.NewNodeForHost("web2.example.com"))
webGroup.SetArg("env", "production")
inv.AddGroup(webGroup)

// Run playbook on entire inventory
results := inv.RunPlaybook(playbooks.NewPing())

// Check summary
summary := results.Summary()
fmt.Printf("Total: %d, Changed: %d, Failed: %d\n",
    summary.Total, summary.Changed, summary.Failed)

// Check individual results
for host, result := range results.Results {
    if result.Error != nil {
        log.Printf("%s failed: %v", host, result.Error)
    }
}

Idempotency

All playbooks support idempotent execution. Use CheckPlaybook() to preview changes:

// Check if changes would be made (dry-run)
results := node.CheckPlaybook(playbooks.NewAptUpgrade())
result := results.Results["server.example.com"]

if result.Changed {
    log.Printf("Would upgrade packages: %s", result.Message)
    // Now actually run it
    results = node.RunPlaybook(playbooks.NewAptUpgrade())
}

Result Structure

Results are returned as types.Results with per-node access:

type Results struct {
    Results map[string]Result  // Key is node hostname
}

func (r Results) Summary() Summary

type Result struct {
    Changed bool              // Whether changes were made
    Message string            // Human-readable description
    Details map[string]string // Additional information
    Error   error             // Non-nil if execution failed
}

type Summary struct {
    Total     int
    Changed   int
    Unchanged int
    Failed    int
}

Direct Playbook Access (Advanced)

For programmatic playbook handling, use the playbook package directly:

import (
    "github.com/dracory/ork/playbook"
    "github.com/dracory/ork/playbooks"
)

// Execute directly with config
aptUpgrade := playbooks.NewAptUpgrade()
aptUpgrade.SetConfig(cfg)
result := aptUpgrade.Run()

// Or check before running via CheckPlaybook
results := node.CheckPlaybook(playbooks.NewSwapCreate())
result := results.Results["server.example.com"]
if !result.Changed {
    log.Println("Swap already exists, skipping...")
    return
}

Dry-Run Mode

Preview what changes would be made without actually executing commands on the server. Safety is enforced at the SSH execution layer - no commands execute on the server in dry-run mode.

Enable Dry-Run

// At node level
node := ork.NewNodeForHost("server.example.com").
    SetDryRunMode(true)
results := node.RunPlaybook(playbooks.NewAptUpgrade())
// Commands are logged but not executed

// At group level
webGroup := ork.NewGroup("webservers")
webGroup.SetDryRunMode(true)
webGroup.AddNode(node1)
webGroup.AddNode(node2)
// All nodes inherit dry-run mode

// At inventory level
inv := ork.NewInventory()
inv.SetDryRunMode(true)
inv.AddGroup(webGroup)
results := inv.RunCommand("uptime")
// All groups and nodes inherit dry-run mode

How It Works

1. Safety at execution layer: ssh.Run() checks cfg.IsDryRunMode and returns "[dry-run]" without executing commands
2. Automatic propagation: Dry-run mode propagates from Inventory → Groups → Nodes at execution time
3. Thread-safe: Uses mutex protection for concurrent access to dry-run state

Detecting Dry-Run in Playbooks

func (p *MyPlaybook) Run() playbook.Result {
    output, _ := ssh.Run(p.cfg, "apt-get upgrade -y")

    if output == "[dry-run]" {
        return playbook.Result{
            Changed: true,
            Message: "Would run: apt-get upgrade -y",
        }
    }
    // Normal execution handling...
}

Note: Even if a playbook doesn't check for the [dry-run] marker, safety is guaranteed - no commands execute on the server when dry-run mode is enabled.

Advanced Usage

Inspecting Configuration

node := ork.NewNodeForHost("server.example.com").
    SetPort("2222").
    SetUser("deploy")

fmt.Printf("Host: %s\n", node.GetHost())
fmt.Printf("Port: %s\n", node.GetPort())
fmt.Printf("User: %s\n", node.GetUser())

// Get full config for integration with internal packages
cfg := node.GetNodeConfig()

Custom Playbooks

Extend Ork with custom automation tasks by implementing the Playbook interface:

Registering Custom Playbooks

Register your custom playbooks to use them via node.RunPlaybookByID("custom-id"):

import (
    "github.com/dracory/ork"
    "github.com/dracory/ork/playbook"
)

// Create a custom playbook
customPb := playbook.NewBasePlaybook()
customPb.SetID("install-docker")
customPb.SetDescription("Install Docker on the server")

// Register it globally
registry, err := ork.GetGlobalPlaybookRegistry()
if err != nil {
    log.Fatalf("Failed to get registry: %v", err)
}
if err := registry.PlaybookRegister(customPb); err != nil {
    log.Fatalf("Failed to register playbook: %v", err)
}

// Now use it like any built-in playbook
node := ork.NewNodeForHost("server.example.com")
result := node.RunPlaybookByID("install-docker")

Custom Playbooks with Full Idempotency

For full idempotency support, implement all methods:

type MyCustomPlaybook struct{}

func (p *MyCustomPlaybook) GetID() string { return "my-task" }
func (p *MyCustomPlaybook) Description() string { return "Does something" }

// Check() - returns true if changes needed
func (p *MyCustomPlaybook) Check(cfg config.NodeConfig) (bool, error) {
    // Check if already configured
    // Playbooks implement Check for use with CheckPlaybook()
    output, _ := ssh.Run(cfg, types.Command{Command: "cat /etc/my-config"})
    return !strings.Contains(output, "configured"), nil
}

// Run() - execute and return Result
func (p *MyCustomPlaybook) Run(cfg config.NodeConfig) playbook.Result {
    needsChange, _ := p.Check(cfg)
    if !needsChange {
        return playbook.Result{
            Changed: false,
            Message: "Already configured",
        }
    }

    // Apply changes...
    _, err := ssh.Run(cfg, types.Command{Command: "setup-command"})
    if err != nil {
        return playbook.Result{Changed: false, Error: err}
    }

    return playbook.Result{
        Changed: true,
        Message: "Configuration applied",
    }
}

Internal Packages

For advanced use cases or when you need fine-grained control, you can use the internal packages directly:

• ssh - SSH connection utilities and command execution
• config - Configuration types for remote operations
• playbook - Base interfaces and registry for organizing playbooks
• playbooks - Reusable playbook implementations (ping, apt, reboot, swap, user)

For advanced use cases, use the internal packages directly:

package main

import (
    "log"

    "github.com/dracory/ork/config"
    "github.com/dracory/ork/playbooks"
)

func main() {
    cfg := config.NodeConfig{
        SSHHost:  "db3.sinevia.com",
        SSHPort:  "40022",
        SSHKey:   "2024_sinevia.prv",
        RootUser: "root",
    }

    // Ping server to check connectivity
    ping := playbooks.NewPing()
    ping.SetConfig(cfg)
    result := ping.Run()
    if result.Error != nil {
        log.Fatal(result.Error)
    }

    // Update packages
    aptUpdate := playbooks.NewAptUpdate()
    aptUpdate.SetConfig(cfg)
    result = aptUpdate.Run()
    if result.Error != nil {
        log.Fatal(result.Error)
    }

    // Create a 2GB swap file
    cfg.Args = map[string]string{"size": "2"}
    swapCreate := playbooks.NewSwapCreate()
    swapCreate.SetConfig(cfg)
    result = swapCreate.Run()
    if result.Error != nil {
        log.Fatal(result.Error)
    }
}

Package Overview

• ork - Main API: NodeInterface, InventoryInterface, GroupInterface, RunnableInterface
• types - Shared types: Result, Results, Summary
• runnable - RunnableInterface for Node, Group, and Inventory
• config - Configuration types
• ssh - SSH client with connection management
• playbook - Playbook interface and registry
• playbooks - Built-in playbook implementations

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). You can find a copy of the license at https://www.gnu.org/licenses/agpl-3.0.en.html

For commercial use, please use my contact page to obtain a commercial license.

Documentation

Overview

Package ork provides a framework for remote server automation.

Package ork provides a simple, intuitive API for SSH-based server automation.

The core concept is the Node - a representation of a remote server that you can connect to and run commands or playbooks against.

Basic usage:

node := ork.NewNode("server.example.com")
output, err := node.Run("uptime")

With configuration:

node := ork.NewNode("server.example.com").
    SetPort("2222").
    SetUser("deploy")
output, err := node.Run("uptime")

Persistent connections for multiple operations:

node := ork.NewNode("server.example.com")
if err := node.Connect(); err != nil {
    log.Fatal(err)
}
defer node.Close()

output1, _ := node.Run("uptime")
output2, _ := node.Run("df -h")

Running playbooks:

node := ork.NewNode("server.example.com").
    SetArg("username", "alice")
err := node.Playbook("user-create")

For advanced use cases, the internal packages remain accessible:

• config - Configuration types
• ssh - SSH client
• types - Shared types (PlaybookInterface, Registry, Result, Command)
• playbook - Playbook interface (re-exports from types for backward compatibility)
• playbooks - Built-in playbook implementations

Package ork provides a framework for remote server automation.

Index

• Constants
• func GetGlobalPlaybookRegistry() (*types.Registry, error)
• func NewDefaultRegistry() (*types.Registry, error)
• func NewPlaybookRegistry() *types.Registry
• func PromptPassword(prompt string) (string, error)
• func VaultContentToEnv(vaultContent, vaultPassword string) (err error)
• func VaultContentToEnvWithPrompt(vaultContent string) (err error)
• func VaultContentToKeys(vaultContent, vaultPassword string) (keys map[string]string, err error)
• func VaultContentToKeysWithPrompt(vaultContent string) (keys map[string]string, err error)
• func VaultFileToEnv(vaultFilePath, vaultPassword string) (err error)
• func VaultFileToEnvWithPrompt(vaultFilePath string) (err error)
• func VaultFileToKeys(vaultFilePath string, vaultPassword string) (keys map[string]string, err error)
• func VaultFileToKeysWithPrompt(vaultFilePath string) (keys map[string]string, err error)
• type GroupInterface
  • func NewGroup(name string) GroupInterface
• type InventoryInterface
  • func NewInventory() InventoryInterface
• type NodeInterface
  • func NewNode() NodeInterface
  • func NewNodeForHost(host string) NodeInterface
  • func NewNodeFromConfig(cfg config.NodeConfig) NodeInterface
• type RunnableInterface

Constants

const (
	// PlaybookPing checks SSH connectivity
	PlaybookPing = playbooks.IDPing

	// PlaybookAptUpdate refreshes the package database
	PlaybookAptUpdate = playbooks.IDAptUpdate

	// PlaybookAptUpgrade installs available updates
	PlaybookAptUpgrade = playbooks.IDAptUpgrade

	// PlaybookAptStatus shows available updates
	PlaybookAptStatus = playbooks.IDAptStatus

	// PlaybookReboot reboots the server
	PlaybookReboot = playbooks.IDReboot

	// PlaybookSwapCreate creates a swap file (requires "size" arg in GB)
	PlaybookSwapCreate = playbooks.IDSwapCreate

	// PlaybookSwapDelete removes the swap file
	PlaybookSwapDelete = playbooks.IDSwapDelete

	// PlaybookSwapStatus shows swap status
	PlaybookSwapStatus = playbooks.IDSwapStatus

	// PlaybookUserCreate creates a user with sudo (requires "username" arg)
	PlaybookUserCreate = playbooks.IDUserCreate

	// PlaybookUserDelete deletes a user (requires "username" arg)
	PlaybookUserDelete = playbooks.IDUserDelete

	// PlaybookUserList lists all non-system users
	PlaybookUserList = playbooks.IDUserList

	// PlaybookUserStatus shows user info (requires "username" arg)
	PlaybookUserStatus = playbooks.IDUserStatus
)

Playbook ID constants for use with RunPlaybook. These constants provide compile-time safety and IDE autocomplete for playbook IDs. They are aliases to the constants in the playbooks package.

Example:

node := ork.NewNodeForHost("server.example.com")
err := node.RunPlaybook(ork.PlaybookPing)

Functions

func GetGlobalPlaybookRegistry

func GetGlobalPlaybookRegistry() (*types.Registry, error)

GetGlobalPlaybookRegistry returns the global playbook registry singleton. This is syntactic sugar for user convenience - it lazily initializes and returns the global registry with all built-in playbooks pre-registered.

For most use cases, users should call this function. For testing or custom configurations, use NewDefaultRegistry() to create isolated registries.

The registry is lazily initialized on first call using sync.Once to ensure thread-safe singleton behavior. Returns an error if initialization fails.

func NewDefaultRegistry

func NewDefaultRegistry() (*types.Registry, error)

NewDefaultRegistry creates a new playbook registry with all built-in playbooks registered. This creates a fresh registry instance (not a singleton), which is useful for: - Testing with isolated registries - Custom configurations without global state - Multiple independent registries in the same application

For most production use cases, use GetGlobalPlaybookRegistry() instead for convenience. Returns an error if any playbook registration fails.

func NewPlaybookRegistry

func NewPlaybookRegistry() *types.Registry

NewPlaybookRegistry creates a new empty playbook registry. This is a convenience method (sugar) for types.NewRegistry() with a more intuitive name. This creates a fresh empty registry instance, which is useful for: - Testing with isolated registries - Custom configurations with selective playbook registration - Multiple independent registries in the same application

Returns an empty registry ready for custom playbook registration.

func PromptPassword

func PromptPassword(prompt string) (string, error)

PromptPassword securely prompts for a password from stdin. The password is not echoed to the terminal.

func VaultContentToEnv

func VaultContentToEnv(vaultContent, vaultPassword string) (err error)

VaultContentToEnv hydrates environment variables from a vault content string.

func VaultContentToEnvWithPrompt

func VaultContentToEnvWithPrompt(vaultContent string) (err error)

VaultContentToEnvWithPrompt prompts for password and hydrates environment variables from a vault content string.

func VaultContentToKeys

func VaultContentToKeys(vaultContent, vaultPassword string) (keys map[string]string, err error)

VaultContentToKeys loads keys from a vault content string.

func VaultContentToKeysWithPrompt

func VaultContentToKeysWithPrompt(vaultContent string) (keys map[string]string, err error)

VaultContentToKeysWithPrompt prompts for password and loads keys from a vault content string.

func VaultFileToEnv

func VaultFileToEnv(vaultFilePath, vaultPassword string) (err error)

VaultFileToEnv decrypts vault and hydrates environment variables.

func VaultFileToEnvWithPrompt

func VaultFileToEnvWithPrompt(vaultFilePath string) (err error)

VaultFileToEnvWithPrompt prompts for password and hydrates environment variables from a vault file.

func VaultFileToKeys

func VaultFileToKeys(vaultFilePath string, vaultPassword string) (keys map[string]string, err error)

VaultFileToKeys loads keys from a vault file.

func VaultFileToKeysWithPrompt

func VaultFileToKeysWithPrompt(vaultFilePath string) (keys map[string]string, err error)

VaultFileToKeysWithPrompt prompts for password and loads keys from a vault file.

Types

type GroupInterface

type GroupInterface interface {
	// RunnableInterface is embedded for command and playbook execution.
	// Operations run on all nodes in this group only.
	RunnableInterface

	// GetName returns the group's name.
	GetName() string

	// AddNode adds a node to this group.
	// The node can be configured using the returned NodeInterface.
	AddNode(node NodeInterface) GroupInterface

	// GetNodes returns all nodes in this group.
	GetNodes() []NodeInterface

	// SetArg sets an argument for this group.
	// Group arguments are inherited by all nodes in the group.
	SetArg(key, value string) GroupInterface

	// GetArg retrieves an argument value by key.
	// Returns empty string if not set.
	GetArg(key string) string

	// GetArgs returns a copy of all arguments defined for this group.
	GetArgs() map[string]string
}

GroupInterface defines operations for managing a group of nodes. It embeds RunnableInterface for executing operations on the group's nodes.

func NewGroup

func NewGroup(name string) GroupInterface

NewGroup creates a new group with the given name.

type InventoryInterface

type InventoryInterface interface {
	// RunnableInterface is embedded for command and playbook execution.
	// Operations run concurrently across all nodes in the inventory.
	RunnableInterface

	// AddGroup adds a group to the inventory.
	AddGroup(group GroupInterface) InventoryInterface

	// GetGroup retrieves a group by name.
	// Returns nil if the group does not exist.
	GetGroupByName(name string) GroupInterface

	// AddNode adds a node directly to the inventory (not in any specific group).
	// The node can be configured using the returned NodeInterface.
	AddNode(node NodeInterface) InventoryInterface

	// GetNodes returns all nodes in the inventory across all groups.
	GetNodes() []NodeInterface

	// SetMaxConcurrency sets the maximum number of concurrent operations.
	// Default is 10. Set to 0 for unlimited.
	SetMaxConcurrency(max int) InventoryInterface
}

InventoryInterface defines operations for managing a collection of nodes organized into groups. It embeds RunnableInterface for executing operations across all nodes in the inventory.

func NewInventory

func NewInventory() InventoryInterface

NewInventory creates a new empty inventory.

type NodeInterface

type NodeInterface interface {
	// RunnableInterface defines operations that can be performed on the node.
	// NodeInterface embeds RunnableInterface for unified API with Group and Inventory.
	RunnableInterface

	// GetArg retrieves a single argument value by key.
	// Returns empty string if the argument is not set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetArg("username", "alice")
	//	fmt.Println(node.GetArg("username"))  // Output: alice
	GetArg(key string) string

	// GetArgs returns a copy of the entire arguments map.
	// Modifying the returned map will not affect the node's internal state.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetArg("username", "alice")
	//	args := node.GetArgs()
	//	fmt.Println(args["username"])  // Output: alice
	GetArgs() map[string]string

	// GetNodeConfig returns a copy of the underlying config.NodeConfig.
	// This allows integration with code that uses the config package directly.
	// The returned configuration includes all accumulated settings (host, port, user, key, args).
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").
	//	    SetPort("2222").
	//	    SetUser("deploy")
	//	cfg := node.GetNodeConfig()
	//	fmt.Printf("Connecting to %s\n", cfg.SSHAddr())
	GetNodeConfig() config.NodeConfig

	// GetHost returns the configured SSH host (hostname or IP address).
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com")
	//	fmt.Println(node.GetHost())  // Output: server.example.com
	GetHost() string

	// GetUser returns the configured SSH user.
	// Returns "root" if not explicitly set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetUser("deploy")
	//	fmt.Println(node.GetUser())  // Output: deploy
	GetUser() string

	// GetKey returns the configured SSH private key filename.
	// Returns "id_rsa" if not explicitly set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetKey("production.prv")
	//	fmt.Println(node.GetKey())  // Output: production.prv
	GetKey() string

	// GetPort returns the configured SSH port.
	// Returns "22" if not explicitly set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetPort("2222")
	//	fmt.Println(node.GetPort())  // Output: 2222
	GetPort() string

	// SetPort sets the SSH port for the connection.
	// Returns the NodeInterface to enable method chaining.
	// Default is "22" if not set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetPort("2222")
	SetPort(port string) NodeInterface

	// SetUser sets the SSH user for the connection.
	// Returns the NodeInterface to enable method chaining.
	// Default is "root" if not set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetUser("deploy")
	SetUser(user string) NodeInterface

	// SetKey sets the SSH private key filename for authentication.
	// The key is resolved to ~/.ssh/<keyname>.
	// Returns the NodeInterface to enable method chaining.
	// Default is "id_rsa" if not set.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").SetKey("production.prv")
	SetKey(key string) NodeInterface

	// SetArg adds a single argument to the arguments map.
	// This adds to existing arguments without replacing them.
	// Arguments are passed to playbooks for configuration.
	// Returns the NodeInterface to enable method chaining.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com").
	//	    SetArg("username", "alice").
	//	    SetArg("shell", "/bin/bash")
	SetArg(key, value string) NodeInterface

	// SetArgs replaces the entire arguments map with the provided map.
	// Any existing arguments are discarded.
	// Arguments are passed to playbooks for configuration.
	// Returns the NodeInterface to enable method chaining.
	//
	// Example:
	//
	//	args := map[string]string{
	//	    "username": "alice",
	//	    "shell": "/bin/bash",
	//	}
	//	node := ork.NewNode("server.example.com").SetArgs(args)
	SetArgs(args map[string]string) NodeInterface

	// Connect establishes a persistent SSH connection to the remote server.
	// The connection is maintained until Close() is called.
	// Subsequent RunCommand() and RunPlaybook() calls will reuse this connection.
	//
	// Returns an error if the connection fails, with a descriptive message
	// including the host and port.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com")
	//	if err := node.Connect(); err != nil {
	//	    log.Fatalf("Failed to connect: %v", err)
	//	}
	//	defer node.Close()
	Connect() error

	// Close terminates the persistent SSH connection and releases resources.
	// After calling Close(), IsConnected() will return false.
	// It is safe to call Close() multiple times or on a non-connected node.
	//
	// Returns an error if closing the connection fails.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com")
	//	node.Connect()
	//	defer node.Close()
	Close() error

	// IsConnected returns true if a persistent SSH connection is currently active.
	// Returns false if Connect() has not been called or if Close() was called.
	//
	// Example:
	//
	//	node := ork.NewNode("server.example.com")
	//	fmt.Println(node.IsConnected())  // Output: false
	//	node.Connect()
	//	fmt.Println(node.IsConnected())  // Output: true
	//	node.Close()
	//	fmt.Println(node.IsConnected())  // Output: false
	IsConnected() bool

	// RunPlaybookByID executes a playbook by ID from the registry.
	// Deprecated: Use RunPlaybook() instead. Run playbooks by creating the playbook
	// instance directly (e.g., playbooks.NewPing()) and passing it to RunPlaybook().
	// This provides better type safety and IDE autocomplete support.
	//
	// Optional PlaybookOptions can be provided to override node-level arguments for this
	// specific execution. This allows per-playbook variable scoping without affecting
	// the node's state.
	RunPlaybookByID(id string, opts ...types.PlaybookOptions) types.Results
}

NodeInterface defines the contract for managing a remote server via SSH. Implementations must support configuration via setter methods, connection management, command execution, and playbook execution.

The interface provides two patterns for configuration:

• Fluent builder pattern: Chain setter methods for readable configuration
• Getter methods: Inspect current configuration state

Connection management is explicit, allowing users to control the SSH connection lifecycle. Operations (RunCommand, RunPlaybook) can work with or without a persistent connection.

Example usage with fluent builder pattern:

node := ork.NewNode("server.example.com").
    SetPort("2222").
    SetUser("deploy").
    SetKey("production.prv")

if err := node.Connect(); err != nil {
    log.Fatal(err)
}
defer node.Close()

output, err := node.RunCommand("uptime")
if err != nil {
    log.Fatal(err)
}
fmt.Println(output)

Example usage without persistent connection:

node := ork.NewNode("server.example.com")
output, err := node.RunCommand("uptime")  // Creates one-time connection

Example usage with playbooks:

node := ork.NewNode("server.example.com").
    SetArg("username", "alice").
    SetArg("shell", "/bin/bash")

if err := node.RunPlaybook("user-create"); err != nil {
    log.Fatal(err)
}

func NewNode

func NewNode() NodeInterface

NewNode creates a new Node with default configuration values. Unlike NewNodeForHost, this function takes no arguments and creates a node with an empty host. Use SetArg or SetArgs to configure the node.

Default values:

• Host: "" (empty - must be set before connecting)
• Port: "22"
• User: "root"
• Key: "id_rsa"
• Args: empty map

Example:

node := ork.NewNode().
    SetHost("server.example.com").
    SetPort("2222").
    SetUser("deploy")

if err := node.Connect(); err != nil {
    log.Fatal(err)
}

func NewNodeForHost

func NewNodeForHost(host string) NodeInterface

NewNode creates a new Node with default configuration values. The host parameter specifies the remote server (hostname or IP address).

Default values:

• Port: "22"
• User: "root"
• Key: "id_rsa"
• Args: empty map

The returned NodeInterface can be configured using setter methods (SetPort, SetUser, SetKey, SetArg, SetArgs) before connecting.

Example:

node := ork.NewNode("server.example.com")
// Equivalent to:
// Node{
//     cfg: config.NodeConfig{
//         SSHHost: "server.example.com",
//         SSHPort: "22",
//         RootUser: "root",
//         SSHKey: "id_rsa",
//         Args: map[string]string{},
//     },
//     connected: false,
// }

Example with configuration:

node := ork.NewNode("server.example.com").
    SetPort("2222").
    SetUser("deploy").
    SetKey("production.prv")

func NewNodeFromConfig

func NewNodeFromConfig(cfg config.NodeConfig) NodeInterface

NewNodeFromConfig creates a new Node from an existing config.NodeConfig. This is useful when you have a pre-built configuration and want to create a Node from it directly.

The config is copied internally, so modifications to the original config after calling this function will not affect the Node.

Example:

cfg := config.NodeConfig{
    SSHHost:  "server.example.com",
    SSHPort:  "2222",
    RootUser: "deploy",
    SSHKey:   "production.prv",
    Args: map[string]string{"env": "production"},
}
node := ork.NewNodeFromConfig(cfg)

if err := node.Connect(); err != nil {
    log.Fatal(err)
}

type RunnableInterface

type RunnableInterface interface {
	// RunCommand executes a shell command and returns the output.
	// For Inventory, runs concurrently across all nodes.
	RunCommand(cmd string) types.Results

	// RunPlaybook executes a playbook instance.
	// For Inventory, runs concurrently across all nodes.
	RunPlaybook(pb types.PlaybookInterface) types.Results

	// RunPlaybookByID executes a playbook by ID from the registry.
	// Deprecated: Use RunPlaybook() instead.
	RunPlaybookByID(id string, opts ...types.PlaybookOptions) types.Results

	// CheckPlaybook runs the playbook's check mode to determine if changes would be made.
	// Sets Changed=true on result if changes are needed.
	CheckPlaybook(pb types.PlaybookInterface) types.Results

	// GetLogger returns the logger. Returns slog.Default() if not set.
	GetLogger() *slog.Logger

	// SetLogger sets a custom logger. Returns self for chaining.
	SetLogger(logger *slog.Logger) RunnableInterface

	// SetDryRunMode sets whether to simulate execution without making changes.
	// When true, ssh.Run() will log commands and return "[dry-run]" marker instead of executing.
	// Returns self for chaining.
	SetDryRunMode(dryRun bool) RunnableInterface

	// GetDryRunMode returns true if dry-run mode is enabled.
	// When true, commands are logged but not executed on the server.
	GetDryRunMode() bool
}

RunnableInterface defines operations that can be performed on either a single Node or an Inventory of nodes.