go-process¶

forge.lthn.ai/core/go-process is a process management library that provides spawning, monitoring, and controlling external processes with real-time output streaming via the Core ACTION (IPC) system. It integrates directly with the Core DI framework as a first-class service.

Features¶

Spawn and manage external processes with full lifecycle tracking
Real-time stdout/stderr streaming via Core IPC actions
Ring buffer output capture (default 1 MB, configurable)
Process pipeline runner with dependency graphs, sequential, and parallel modes
Daemon mode with PID file locking, health check HTTP server, and graceful shutdown
Daemon registry for tracking running instances across the system
Lightweight exec sub-package for one-shot command execution with logging
Thread-safe throughout; designed for concurrent use

Quick Start¶

Register with Core¶

import (
    "context"
    framework "forge.lthn.ai/core/go/pkg/core"
    "forge.lthn.ai/core/go-process"
)

// Create a Core instance with the process service
c, err := framework.New(
    framework.WithName("process", process.NewService(process.Options{})),
)
if err != nil {
    log.Fatal(err)
}

// Retrieve the typed service
svc, err := framework.ServiceFor[*process.Service](c, "process")
if err != nil {
    log.Fatal(err)
}

Run a Command¶

// Fire-and-forget (async)
proc, err := svc.Start(ctx, "go", "test", "./...")
if err != nil {
    return err
}
<-proc.Done()
fmt.Println(proc.Output())

// Synchronous convenience
output, err := svc.Run(ctx, "echo", "hello world")

Listen for Events¶

Process lifecycle events are broadcast through Core's ACTION system:

c.RegisterAction(func(c *framework.Core, msg framework.Message) error {
    switch m := msg.(type) {
    case process.ActionProcessStarted:
        fmt.Printf("Started: %s (PID %d)\n", m.Command, m.PID)
    case process.ActionProcessOutput:
        fmt.Print(m.Line)
    case process.ActionProcessExited:
        fmt.Printf("Exit code: %d (%s)\n", m.ExitCode, m.Duration)
    case process.ActionProcessKilled:
        fmt.Printf("Killed with %s\n", m.Signal)
    }
    return nil
})

Global Convenience API¶

For applications that only need a single process service, a global singleton is available:

// Initialise once at startup
process.Init(coreInstance)

// Then use package-level functions anywhere
proc, _ := process.Start(ctx, "ls", "-la")
output, _ := process.Run(ctx, "date")
procs := process.List()
running := process.Running()

Package Layout¶

Path	Description
`*.go` (root)	Core process service, types, actions, runner, daemon, health, PID file, registry
`exec/`	Lightweight command wrapper with fluent API and structured logging

Module Information¶

Field	Value
Module path	`forge.lthn.ai/core/go-process`
Go version	1.26.0
Licence	EUPL-1.2

Dependencies¶

Module	Purpose
`forge.lthn.ai/core/go`	Core DI framework (`ServiceRuntime`, `Core.ACTION`, lifecycle interfaces)
`github.com/stretchr/testify`	Test assertions (test-only)

The package has no other runtime dependencies beyond the Go standard library and the Core framework.