gosible Infrastructure Automation

A Go-first library for infrastructure automation, configuration management, and orchestration. Build type-safe automation tools without subprocess calls or YAML parsing.

What This Skill Does

This skill helps you work with gosible, a Go library that implements Ansible-like features for infrastructure automation. It guides you through:

Key Principles

1. **Library-First**: All functionality exposed through clean Go APIs

2. **Type-Safe**: Full Go type checking and IDE support

3. **No Subprocesses**: Direct function calls, no CLI parsing

4. **Composable**: Mix and match components as needed

5. **Early Stage**: No backward compatibility concerns, iterate freely

Instructions

Understanding the Project Structure

When working with gosible:

1. **Core packages** are in `pkg/`:

- `inventory/` - Host and group management

- `modules/` - Built-in and custom automation modules

- `playbook/` - YAML playbook parsing and execution

- `runner/` - Task execution engine with parallelization

- `template/` - Jinja2-compatible template rendering

- `connection/` - SSH, WinRM, local connection plugins

- `vars/` - Variable management and fact gathering

- `config/` - Configuration management

2. **Always prefer editing existing files** over creating new ones

3. **Focus on library API** - CLI is secondary

Development Workflow

For building and testing:

```bash

Development commands

go mod tidy # Clean dependencies

go build ./... # Build all packages

go test ./... # Run all tests

go test -v ./... # Verbose test output

go test -race ./... # Race detection

Single package operations

go test ./pkg/inventory # Test specific package

go run ./cmd/example # Run examples

Code quality

go fmt ./... # Format code

go vet ./... # Static analysis

```

Writing Library Code

When implementing features:

1. **Design for programmatic use first**:

```go

// Good: Clean API for library users

func deployApp(ctx context.Context) error {

inv, _ := inventory.NewFromFile("inventory.yml")

runner := runner.NewTaskRunner()

tasks := library.NewCommonTasks()

deployTasks := tasks.Package.InstallDependencies([]string{"nginx"})

deployTasks = append(deployTasks, tasks.Service.EnsureServiceRunning("nginx")...)

results, err := runner.ExecuteTasks(ctx, deployTasks, inv, "web_servers")

return err

}

```

2. **Follow key interfaces**:

- Modules: Implement `Module` interface with `Run(ctx context.Context, args map[string]interface{}) error`

- Connections: Implement `Connection` interface for remote execution

- Inventory: Implement `InventorySource` interface for dynamic inventory

3. **Use context propagation**:

- Always accept `context.Context` as first parameter

- Support cancellation and timeouts properly

4. **Error handling**:

- Use `fmt.Errorf` with `%w` verb for error wrapping

- Return proper Go errors, not exit codes

- Build error chains for debugging

5. **Concurrent execution**:

- Leverage goroutines for parallel tasks

- Use proper synchronization primitives

- Handle task dependencies correctly

Testing Approach

When writing tests:

1. **Unit tests** in `*_test.go` files alongside code

2. **Integration tests** in `integration/` directory

3. **Table-driven tests** for module validation

4. **Mock implementations** for external dependencies

5. **Benchmarks** for performance-critical paths

6. **No backward compatibility concerns** - iterate freely

Example test structure:

```go

func TestModule_Run(t *testing.T) {

tests := []struct {

name string

args map[string]interface{}

want error

wantErr bool

}{

// Test cases

}

for _, tt := range tests {

t.Run(tt.name, func(t *testing.T) {

// Test implementation

})

}

}

```

Common Use Cases

Help users implement:

1. **Embedded Automation**: Add automation to existing Go apps

2. **Custom Orchestration**: Build deployment tools

3. **Kubernetes Operators**: Implement operators with infrastructure automation

4. **CI/CD Integration**: Native Go-based pipeline integration

5. **Monitoring Remediation**: Add self-healing to monitoring systems

6. **Configuration Management**: Programmatic config management

Code Quality Standards

Before completing tasks:

1. Run `go fmt ./...` to format code

2. Run `go vet ./...` for static analysis

3. Ensure tests pass with `go test ./...`

4. Consider race conditions with `go test -race ./...`

5. Keep code idiomatic and composable

Key Design Patterns

When implementing features:

Important Notes

Examples

Simple Task Execution

```go

import (

"context"

"github.com/liliang-cn/gosible/pkg/inventory"

"github.com/liliang-cn/gosible/pkg/runner"

)

inv, _ := inventory.NewFromFile("hosts.yml")

runner := runner.NewTaskRunner()

results, err := runner.ExecuteTasks(ctx, tasks, inv, "web_servers")

```

Custom Module Implementation

```go

type MyModule struct{}

func (m *MyModule) Run(ctx context.Context, args map[string]interface{}) error {

// Module implementation

return nil

}

```