cli/docs/pkg/PACKAGE_STANDARDS.md

Core Package Standards

This document defines the standards for creating packages in the Core framework. The pkg/i18n package is the reference implementation; all new packages should follow its patterns.

Package Structure

A well-structured Core package follows this layout:

pkg/mypackage/
├── types.go           # Public types, constants, interfaces
├── service.go         # Service struct with framework integration
├── mypackage.go       # Global convenience functions
├── actions.go         # ACTION messages for Core IPC (if needed)
├── hooks.go           # Event hooks with atomic handlers (if needed)
├── [feature].go       # Additional feature files
├── [feature]_test.go  # Tests alongside implementation
└── service_test.go    # Service tests

Core Principles

1. Service-oriented: Packages expose a Service struct that integrates with the Core framework
2. Thread-safe: All public APIs must be safe for concurrent use
3. Global convenience: Provide package-level functions that use a default service instance
4. Options pattern: Use functional options for configuration
5. ACTION-based IPC: Communicate via Core's ACTION system, not callbacks

---

Service Pattern

Service Struct

Embed framework.ServiceRuntime[T] for Core integration:

// pkg/mypackage/service.go
package mypackage

import (
    "sync"
    "forge.lthn.ai/core/cli/pkg/framework"
)

// Service provides mypackage functionality with Core integration.
type Service struct {
    *framework.ServiceRuntime[Options]

    // Internal state (protected by mutex)
    data map[string]any
    mu   sync.RWMutex
}

// Options configures the service.
type Options struct {
    // Document each option
    BufferSize int
    EnableFoo  bool
}

Service Factory

Create a factory function for Core registration:

// NewService creates a service factory for Core registration.
//
//    core, _ := framework.New(
//        framework.WithName("mypackage", mypackage.NewService(mypackage.Options{})),
//    )
func NewService(opts Options) func(*framework.Core) (any, error) {
    return func(c *framework.Core) (any, error) {
        // Apply defaults
        if opts.BufferSize == 0 {
            opts.BufferSize = DefaultBufferSize
        }

        svc := &Service{
            ServiceRuntime: framework.NewServiceRuntime(c, opts),
            data:           make(map[string]any),
        }
        return svc, nil
    }
}

Lifecycle Hooks

Implement framework.Startable and/or framework.Stoppable:

// OnStartup implements framework.Startable.
func (s *Service) OnStartup(ctx context.Context) error {
    // Register query/task handlers
    s.Core().RegisterQuery(s.handleQuery)
    s.Core().RegisterAction(s.handleAction)
    return nil
}

// OnShutdown implements framework.Stoppable.
func (s *Service) OnShutdown(ctx context.Context) error {
    // Cleanup resources
    return nil
}

---

Global Default Pattern

Following pkg/i18n, provide a global default service with atomic access:

// pkg/mypackage/mypackage.go
package mypackage

import (
    "sync"
    "sync/atomic"

    "forge.lthn.ai/core/cli/pkg/framework"
)

// Global default service
var (
    defaultService atomic.Pointer[Service]
    defaultOnce    sync.Once
    defaultErr     error
)

// Default returns the global service instance.
// Returns nil if not initialised.
func Default() *Service {
    return defaultService.Load()
}

// SetDefault sets the global service instance.
// Thread-safe. Panics if s is nil.
func SetDefault(s *Service) {
    if s == nil {
        panic("mypackage: SetDefault called with nil service")
    }
    defaultService.Store(s)
}

// Init initialises the default service with a Core instance.
func Init(c *framework.Core) error {
    defaultOnce.Do(func() {
        factory := NewService(Options{})
        svc, err := factory(c)
        if err != nil {
            defaultErr = err
            return
        }
        defaultService.Store(svc.(*Service))
    })
    return defaultErr
}

Global Convenience Functions

Expose the most common operations at package level:

// ErrServiceNotInitialised is returned when the service is not initialised.
var ErrServiceNotInitialised = errors.New("mypackage: service not initialised")

// DoSomething performs an operation using the default service.
func DoSomething(arg string) (string, error) {
    svc := Default()
    if svc == nil {
        return "", ErrServiceNotInitialised
    }
    return svc.DoSomething(arg)
}

---

Options Pattern

Use functional options for complex configuration:

// Option configures a Service during construction.
type Option func(*Service)

// WithBufferSize sets the buffer size.
func WithBufferSize(size int) Option {
    return func(s *Service) {
        s.bufSize = size
    }
}

// WithFoo enables foo feature.
func WithFoo(enabled bool) Option {
    return func(s *Service) {
        s.fooEnabled = enabled
    }
}

// New creates a service with options.
func New(opts ...Option) (*Service, error) {
    s := &Service{
        bufSize: DefaultBufferSize,
    }
    for _, opt := range opts {
        opt(s)
    }
    return s, nil
}

---

ACTION Messages (IPC)

For services that need to communicate events, define ACTION message types:

// pkg/mypackage/actions.go
package mypackage

import "time"

// ActionItemCreated is broadcast when an item is created.
type ActionItemCreated struct {
    ID        string
    Name      string
    CreatedAt time.Time
}

// ActionItemUpdated is broadcast when an item changes.
type ActionItemUpdated struct {
    ID      string
    Changes map[string]any
}

// ActionItemDeleted is broadcast when an item is removed.
type ActionItemDeleted struct {
    ID string
}

Dispatch actions via s.Core().ACTION():

func (s *Service) CreateItem(name string) (*Item, error) {
    item := &Item{ID: generateID(), Name: name}

    // Store item...

    // Broadcast to listeners
    s.Core().ACTION(ActionItemCreated{
        ID:        item.ID,
        Name:      item.Name,
        CreatedAt: time.Now(),
    })

    return item, nil
}

Consumers register handlers:

core.RegisterAction(func(c *framework.Core, msg framework.Message) error {
    switch m := msg.(type) {
    case mypackage.ActionItemCreated:
        log.Printf("Item created: %s", m.Name)
    case mypackage.ActionItemDeleted:
        log.Printf("Item deleted: %s", m.ID)
    }
    return nil
})

---

Hooks Pattern

For user-customisable behaviour, use atomic handlers (see pkg/i18n/hooks.go):

// pkg/mypackage/hooks.go
package mypackage

import (
    "sync/atomic"
)

// ErrorHandler is called when an error occurs.
type ErrorHandler func(err error)

var errorHandler atomic.Value // stores ErrorHandler

// OnError registers an error handler.
// Thread-safe. Pass nil to clear.
func OnError(h ErrorHandler) {
    if h == nil {
        errorHandler.Store((ErrorHandler)(nil))
        return
    }
    errorHandler.Store(h)
}

// dispatchError calls the registered error handler.
func dispatchError(err error) {
    v := errorHandler.Load()
    if v == nil {
        return
    }
    h, ok := v.(ErrorHandler)
    if !ok || h == nil {
        return
    }
    h(err)
}

---

Thread Safety

Mutex Patterns

Use sync.RWMutex for state that is read more than written:

type Service struct {
    data map[string]any
    mu   sync.RWMutex
}

func (s *Service) Get(key string) (any, bool) {
    s.mu.RLock()
    defer s.mu.RUnlock()
    v, ok := s.data[key]
    return v, ok
}

func (s *Service) Set(key string, value any) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.data[key] = value
}

Atomic Values

Use atomic.Pointer[T] for single values accessed frequently:

var config atomic.Pointer[Config]

func GetConfig() *Config {
    return config.Load()
}

func SetConfig(c *Config) {
    config.Store(c)
}

---

Error Handling

Error Types

Define package-level errors:

// Errors
var (
    ErrNotFound    = errors.New("mypackage: not found")
    ErrInvalidArg  = errors.New("mypackage: invalid argument")
    ErrNotRunning  = errors.New("mypackage: not running")
)

Wrapped Errors

Use fmt.Errorf with %w for context:

func (s *Service) Load(path string) error {
    data, err := os.ReadFile(path)
    if err != nil {
        return fmt.Errorf("failed to load config: %w", err)
    }
    // ...
}

Error Struct (optional)

For errors needing additional context:

type ServiceError struct {
    Op      string // Operation that failed
    Path    string // Resource path
    Err     error  // Underlying error
}

func (e *ServiceError) Error() string {
    return fmt.Sprintf("%s %s: %v", e.Op, e.Path, e.Err)
}

func (e *ServiceError) Unwrap() error {
    return e.Err
}

---

Testing

Test File Organisation

Place tests alongside implementation:

mypackage.go      → mypackage_test.go
service.go        → service_test.go
buffer.go         → buffer_test.go

Test Helpers

Create helpers for common setup:

func newTestService(t *testing.T) (*Service, *framework.Core) {
    t.Helper()

    core, err := framework.New(
        framework.WithName("mypackage", NewService(Options{})),
    )
    require.NoError(t, err)

    svc, err := framework.ServiceFor[*Service](core, "mypackage")
    require.NoError(t, err)

    return svc, core
}

Test Naming Convention

Use descriptive subtests:

func TestService_DoSomething(t *testing.T) {
    t.Run("valid input", func(t *testing.T) {
        // ...
    })

    t.Run("empty input returns error", func(t *testing.T) {
        // ...
    })

    t.Run("concurrent access", func(t *testing.T) {
        // ...
    })
}

Testing Actions

Verify ACTION broadcasts:

func TestService_BroadcastsActions(t *testing.T) {
    core, _ := framework.New(
        framework.WithName("mypackage", NewService(Options{})),
    )

    var received []ActionItemCreated
    var mu sync.Mutex

    core.RegisterAction(func(c *framework.Core, msg framework.Message) error {
        if m, ok := msg.(ActionItemCreated); ok {
            mu.Lock()
            received = append(received, m)
            mu.Unlock()
        }
        return nil
    })

    svc, _ := framework.ServiceFor[*Service](core, "mypackage")
    svc.CreateItem("test")

    mu.Lock()
    assert.Len(t, received, 1)
    assert.Equal(t, "test", received[0].Name)
    mu.Unlock()
}

---

Documentation

Package Doc

Every package needs a doc comment in the main file:

// Package mypackage provides functionality for X.
//
// # Getting Started
//
//    svc, err := mypackage.New()
//    result := svc.DoSomething("input")
//
// # Core Integration
//
//    core, _ := framework.New(
//        framework.WithName("mypackage", mypackage.NewService(mypackage.Options{})),
//    )
package mypackage

Function Documentation

Document public functions with examples:

// DoSomething performs X operation with the given input.
// Returns ErrInvalidArg if input is empty.
//
//    result, err := svc.DoSomething("hello")
//    if err != nil {
//        return err
//    }
func (s *Service) DoSomething(input string) (string, error) {
    // ...
}

---

Checklist

When creating a new package, ensure:

• Service struct embeds framework.ServiceRuntime[Options]
• NewService() factory function for Core registration
• Default() / SetDefault() with atomic.Pointer
• Package-level convenience functions
• Thread-safe public APIs (mutex or atomic)
• ACTION messages for events (if applicable)
• Hooks with atomic handlers (if applicable)
• Comprehensive tests with helpers
• Package documentation with examples

Reference Implementations

• pkg/i18n - Full reference with handlers, modes, hooks, grammar
• pkg/process - Simpler example with ACTION events and runner orchestration
• pkg/cli - Service integration with runtime lifecycle

---

Background Operations

For long-running operations that could block the UI, use the framework's background task mechanism.

Principles

1. Non-blocking: Long-running operations must not block the main IPC thread.
2. Lifecycle Events: Use PerformAsync to automatically broadcast start and completion events.
3. Progress Reporting: Services should broadcast ActionTaskProgress for granular updates.

Using PerformAsync

The Core.PerformAsync(task) method runs any registered task in a background goroutine and returns a unique TaskID immediately.

// From the frontend or another service
taskID := core.PerformAsync(git.TaskPush{Path: "/repo"})
// taskID is returned immediately, e.g., "task-123"

The framework automatically broadcasts lifecycle actions:

• ActionTaskStarted: When the background goroutine begins.
• ActionTaskCompleted: When the task finishes (contains Result and Error).

Reporting Progress

For very long operations, the service handler should broadcast progress:

func (s *Service) handleTask(c *framework.Core, t framework.Task) (any, bool, error) {
    switch m := t.(type) {
    case MyLongTask:
        // Optional: If you need to report progress, you might need to pass
        // a TaskID or use a specific progress channel.
        // For now, simple tasks just use ActionTaskCompleted.
        return s.doLongWork(m), true, nil
    }
    return nil, false, nil
}

Implementing Background-Safe Handlers

Ensure that handlers for long-running tasks:

1. Use context.Background() or a long-lived context, as the request context might expire.
2. Are thread-safe and don't hold global locks for the duration of the work.
3. Do not use interactive CLI functions like cli.Scanln if they are intended for GUI use.