go-process/specs/process.md

# process
**Import:** `dappco.re/go/core/process`
**Files:** 11

## Types

### `ActionProcessStarted`
`struct`

Broadcast payload for a managed process that has successfully started.

Fields:
- `ID string`: Generated managed-process identifier.
- `Command string`: Executable name passed to the service.
- `Args []string`: Argument vector used to start the process.
- `Dir string`: Working directory supplied at start time.
- `PID int`: OS process ID of the child process.

### `ActionProcessOutput`
`struct`

Broadcast payload for one scanned line of process output.

Fields:
- `ID string`: Managed-process identifier.
- `Line string`: One line from stdout or stderr, without the trailing newline.
- `Stream Stream`: Output source, using `StreamStdout` or `StreamStderr`.

### `ActionProcessExited`
`struct`

Broadcast payload emitted after the service wait goroutine finishes.

Fields:
- `ID string`: Managed-process identifier.
- `ExitCode int`: Process exit code.
- `Duration time.Duration`: Time elapsed since `StartedAt`.
- `Error error`: Declared error slot for exit metadata. The current `Service` emitter does not populate it.

### `ActionProcessKilled`
`struct`

Broadcast payload emitted by `Service.Kill`.

Fields:
- `ID string`: Managed-process identifier.
- `Signal string`: Signal name reported by the service. The current implementation emits `"SIGKILL"`.

### `RingBuffer`
`struct`

Fixed-size circular byte buffer used for captured process output. The implementation is mutex-protected and overwrites the oldest bytes when full.

Exported fields:
- None.

### `DaemonOptions`
`struct`

Configuration for `NewDaemon`.

Fields:
- `PIDFile string`: PID file path. Empty disables PID-file management.
- `ShutdownTimeout time.Duration`: Grace period used by `Stop`. Zero is normalized to 30 seconds by `NewDaemon`.
- `HealthAddr string`: Listen address for the health server. Empty disables health endpoints.
- `HealthChecks []HealthCheck`: Additional `/health` checks to register on the health server.
- `Registry *Registry`: Optional daemon registry used for automatic register/unregister.
- `RegistryEntry DaemonEntry`: Base registry payload. `Start` fills in `PID`, `Health`, and `Started` behavior through `Registry.Register`.

### `Daemon`
`struct`

Lifecycle wrapper around a PID file, optional health server, and optional registry entry.

Exported fields:
- None.

### `HealthCheck`
`type HealthCheck func() error`

Named function type used by `HealthServer` and `DaemonOptions`. Returning `nil` marks the check healthy; returning an error makes `/health` respond with `503`.

### `HealthServer`
`struct`

HTTP server exposing `/health` and `/ready` endpoints.

Exported fields:
- None.

### `PIDFile`
`struct`

Single-instance guard backed by a PID file on disk.

Exported fields:
- None.

### `ManagedProcess`
`struct`

Service-owned process record for a started child process.

Fields:
- `ID string`: Managed-process identifier generated by `core.ID()`.
- `Command string`: Executable name.
- `Args []string`: Command arguments.
- `Dir string`: Working directory used when starting the process.
- `Env []string`: Extra environment entries appended to the command environment.
- `StartedAt time.Time`: Timestamp recorded immediately before `cmd.Start`.
- `Status Status`: Current lifecycle state tracked by the service.
- `ExitCode int`: Exit status after completion.
- `Duration time.Duration`: Runtime duration set when the wait goroutine finishes.

### `Process`
`type alias of ManagedProcess`

Compatibility alias that exposes the same fields and methods as `ManagedProcess`.

### `Program`
`struct`

Thin helper for finding and running a named executable.

Fields:
- `Name string`: Binary name to look up or execute.
- `Path string`: Resolved absolute path populated by `Find`. When empty, `Run` and `RunDir` fall back to `Name`.

### `DaemonEntry`
`struct`

Serialized daemon-registry record written as JSON.

Fields:
- `Code string`: Application or component code.
- `Daemon string`: Daemon name within that code.
- `PID int`: Running process ID.
- `Health string`: Health endpoint address, if any.
- `Project string`: Optional project label.
- `Binary string`: Optional binary label.
- `Started time.Time`: Start timestamp persisted in RFC3339Nano format.

### `Registry`
`struct`

Filesystem-backed daemon registry that stores one JSON file per daemon entry.

Exported fields:
- None.

### `Runner`
`struct`

Pipeline orchestrator that starts `RunSpec` processes through a `Service`.

Exported fields:
- None.

### `RunSpec`
`struct`

One process specification for `Runner`.

Fields:
- `Name string`: Friendly name used for dependencies and result reporting.
- `Command string`: Executable name.
- `Args []string`: Command arguments.
- `Dir string`: Working directory.
- `Env []string`: Additional environment variables.
- `After []string`: Dependency names that must complete before this spec can run in `RunAll`.
- `AllowFailure bool`: When true, downstream work is not skipped because of this spec's failure.

### `RunResult`
`struct`

Per-spec runner result.

Fields:
- `Name string`: Spec name.
- `Spec RunSpec`: Original spec payload.
- `ExitCode int`: Exit code from the managed process.
- `Duration time.Duration`: Process duration or start-attempt duration.
- `Output string`: Captured output returned from the managed process.
- `Error error`: Start or orchestration error. For a started process that exits non-zero, this remains `nil`.
- `Skipped bool`: Whether the spec was skipped instead of run.

### `RunAllResult`
`struct`

Aggregate result returned by `RunAll`, `RunSequential`, and `RunParallel`.

Fields:
- `Results []RunResult`: Collected per-spec results.
- `Duration time.Duration`: End-to-end runtime for the orchestration method.
- `Passed int`: Count of results where `Passed()` is true.
- `Failed int`: Count of non-skipped results that did not pass.
- `Skipped int`: Count of skipped results.

### `Service`
`struct`

Core service that owns managed processes and registers action handlers.

Fields:
- `*core.ServiceRuntime[Options]`: Embedded Core runtime used for lifecycle hooks and access to `Core()`.

### `Options`
`struct`

Service configuration.

Fields:
- `BufferSize int`: Ring-buffer capacity for captured output. `Register` currently initializes this from `DefaultBufferSize`.

### `Status`
`type Status string`

Named lifecycle-state type for a managed process.

Exported values:
- `StatusPending`: queued but not started.
- `StatusRunning`: currently executing.
- `StatusExited`: completed and waited.
- `StatusFailed`: start or wait failure state.
- `StatusKilled`: terminated by signal.

### `Stream`
`type Stream string`

Named output-stream discriminator for process output events.

Exported values:
- `StreamStdout`: stdout line.
- `StreamStderr`: stderr line.

### `RunOptions`
`struct`

Execution settings accepted by `Service.StartWithOptions` and `Service.RunWithOptions`.

Fields:
- `Command string`: Executable name. Required by both start and run paths.
- `Args []string`: Command arguments.
- `Dir string`: Working directory.
- `Env []string`: Additional environment entries appended to the command environment.
- `DisableCapture bool`: Disables the managed-process ring buffer when true.
- `Detach bool`: Starts the child in a separate process group and replaces the parent context with `context.Background()`.
- `Timeout time.Duration`: Optional watchdog timeout that calls `Shutdown` after the duration elapses.
- `GracePeriod time.Duration`: Delay between `SIGTERM` and fallback kill in `Shutdown`.
- `KillGroup bool`: Requests process-group termination. The current service only enables this when `Detach` is also true.

### `ProcessInfo`
`struct`

Serializable snapshot returned by `ManagedProcess.Info` and `Service` action lookups.

Fields:
- `ID string`: Managed-process identifier.
- `Command string`: Executable name.
- `Args []string`: Command arguments.
- `Dir string`: Working directory.
- `StartedAt time.Time`: Start timestamp.
- `Running bool`: Convenience boolean derived from `Status`.
- `Status Status`: Current lifecycle state.
- `ExitCode int`: Exit status.
- `Duration time.Duration`: Runtime duration.
- `PID int`: Child PID, or `0` if no process handle is available.

### `Info`
`type alias of ProcessInfo`

Compatibility alias that exposes the same fields as `ProcessInfo`.

## Functions

### Package Functions

- `func Register(c *core.Core) core.Result`: Builds a `Service` with a fresh `core.Registry[*ManagedProcess]`, sets the buffer size to `DefaultBufferSize`, and returns the service in `Result.Value`.
- `func NewRingBuffer(size int) *RingBuffer`: Allocates a fixed-capacity ring buffer of exactly `size` bytes.
- `func NewDaemon(opts DaemonOptions) *Daemon`: Normalizes `ShutdownTimeout`, creates optional `PIDFile` and `HealthServer` helpers, and attaches any configured health checks.
- `func NewHealthServer(addr string) *HealthServer`: Returns a health server with the supplied listen address and readiness initialized to `true`.
- `func WaitForHealth(addr string, timeoutMs int) bool`: Polls `http://<addr>/health` every 200 ms until it gets HTTP 200 or the timeout expires.
- `func NewPIDFile(path string) *PIDFile`: Returns a PID-file manager for `path`.
- `func ReadPID(path string) (int, bool)`: Reads and parses a PID file, then uses signal `0` to report whether that PID is still alive.
- `func NewRegistry(dir string) *Registry`: Returns a daemon registry rooted at `dir`.
- `func DefaultRegistry() *Registry`: Returns a registry at `~/.core/daemons`, falling back to the OS temp directory if the home directory cannot be resolved.
- `func NewRunner(svc *Service) *Runner`: Returns a runner bound to a specific `Service`.

### `RingBuffer` Methods

- `func (rb *RingBuffer) Write(p []byte) (n int, err error)`: Appends bytes one by one, advancing the circular window and overwriting the oldest bytes when capacity is exceeded.
- `func (rb *RingBuffer) String() string`: Returns the current buffer contents in logical order as a string.
- `func (rb *RingBuffer) Bytes() []byte`: Returns a copied byte slice of the current logical contents, or `nil` when the buffer is empty.
- `func (rb *RingBuffer) Len() int`: Returns the number of bytes currently retained.
- `func (rb *RingBuffer) Cap() int`: Returns the configured capacity.
- `func (rb *RingBuffer) Reset()`: Clears the buffer indexes and full flag.

### `Daemon` Methods

- `func (d *Daemon) Start() error`: Acquires the PID file, starts the health server, marks the daemon running, and auto-registers it when `Registry` is configured. If a later step fails, it rolls back earlier setup.
- `func (d *Daemon) Run(ctx context.Context) error`: Requires a started daemon, waits for `ctx.Done()`, and then calls `Stop`.
- `func (d *Daemon) Stop() error`: Sets readiness false, shuts down the health server, releases the PID file, unregisters the daemon, and joins health or PID teardown errors with `core.ErrorJoin`.
- `func (d *Daemon) SetReady(ready bool)`: Forwards readiness changes to the health server when one exists.
- `func (d *Daemon) HealthAddr() string`: Returns the bound health-server address or `""` when health endpoints are disabled.

### `HealthServer` Methods

- `func (h *HealthServer) AddCheck(check HealthCheck)`: Appends a health-check callback under lock.
- `func (h *HealthServer) SetReady(ready bool)`: Updates the readiness flag used by `/ready`.
- `func (h *HealthServer) Start() error`: Installs `/health` and `/ready` handlers, listens on `addr`, stores the listener and `http.Server`, and serves in a goroutine.
- `func (h *HealthServer) Stop(ctx context.Context) error`: Calls `Shutdown` on the underlying `http.Server` when started; otherwise returns `nil`.
- `func (h *HealthServer) Addr() string`: Returns the actual bound listener address after `Start`, or the configured address before startup.

### `PIDFile` Methods

- `func (p *PIDFile) Acquire() error`: Rejects a live existing PID file, deletes stale state, creates the parent directory when needed, and writes the current process ID.
- `func (p *PIDFile) Release() error`: Deletes the PID file.
- `func (p *PIDFile) Path() string`: Returns the configured PID-file path.

### `ManagedProcess` Methods

- `func (p *ManagedProcess) Info() ProcessInfo`: Returns a snapshot containing public fields plus the current child PID.
- `func (p *ManagedProcess) Output() string`: Returns captured output as a string, or `""` when capture is disabled.
- `func (p *ManagedProcess) OutputBytes() []byte`: Returns captured output as bytes, or `nil` when capture is disabled.
- `func (p *ManagedProcess) IsRunning() bool`: Reports running state by checking whether the `done` channel has closed.
- `func (p *ManagedProcess) Wait() error`: Blocks for completion and then returns a wrapped error for failed-start, killed, or non-zero-exit outcomes.
- `func (p *ManagedProcess) Done() <-chan struct{}`: Returns the completion channel.
- `func (p *ManagedProcess) Kill() error`: Sends `SIGKILL` to the child, or to the entire process group when group killing is enabled.
- `func (p *ManagedProcess) Shutdown() error`: Sends `SIGTERM`, waits for the configured grace period, and falls back to `Kill`. With no grace period configured, it immediately calls `Kill`.
- `func (p *ManagedProcess) SendInput(input string) error`: Writes to the child's stdin pipe while the process is running.
- `func (p *ManagedProcess) CloseStdin() error`: Closes the stdin pipe and clears the stored handle.
- `func (p *ManagedProcess) Signal(sig os.Signal) error`: Sends an arbitrary signal while the process is in `StatusRunning`.

### `Program` Methods

- `func (p *Program) Find() error`: Resolves `Name` through `exec.LookPath`, stores the absolute path in `Path`, and wraps `ErrProgramNotFound` when lookup fails.
- `func (p *Program) Run(ctx context.Context, args ...string) (string, error)`: Executes the program in the current working directory by delegating to `RunDir("", args...)`.
- `func (p *Program) RunDir(ctx context.Context, dir string, args ...string) (string, error)`: Runs the program with combined stdout/stderr capture, trims the combined output, and returns that output even when the command fails.

### `Registry` Methods

- `func (r *Registry) Register(entry DaemonEntry) error`: Ensures the registry directory exists, defaults `Started` when zero, marshals the entry with the package's JSON writer, and writes one `<code>-<daemon>.json` file.
- `func (r *Registry) Unregister(code, daemon string) error`: Deletes the registry file for the supplied daemon key.
- `func (r *Registry) Get(code, daemon string) (*DaemonEntry, bool)`: Reads one entry, prunes invalid or stale files, and returns `(nil, false)` when the daemon is missing or dead.
- `func (r *Registry) List() ([]DaemonEntry, error)`: Lists all JSON files in the registry directory, prunes invalid or stale entries, and returns only live daemons. A missing registry directory returns `nil, nil`.

### `RunResult` and `RunAllResult` Methods

- `func (r RunResult) Passed() bool`: Returns true only when the result is not skipped, has no `Error`, and has `ExitCode == 0`.
- `func (r RunAllResult) Success() bool`: Returns true when `Failed == 0`, regardless of skipped count.

### `Runner` Methods

- `func (r *Runner) RunAll(ctx context.Context, specs []RunSpec) (*RunAllResult, error)`: Executes dependency-aware waves of specs, skips dependents after failing required dependencies, and marks circular or missing dependency sets as failed results with `ExitCode` 1.
- `func (r *Runner) RunSequential(ctx context.Context, specs []RunSpec) (*RunAllResult, error)`: Runs specs in order and marks remaining specs skipped after the first disallowed failure.
- `func (r *Runner) RunParallel(ctx context.Context, specs []RunSpec) (*RunAllResult, error)`: Runs all specs concurrently and aggregates counts after all goroutines finish.

### `Service` Methods

- `func (s *Service) OnStartup(ctx context.Context) core.Result`: Registers the Core actions `process.run`, `process.start`, `process.kill`, `process.list`, and `process.get`.
- `func (s *Service) OnShutdown(ctx context.Context) core.Result`: Iterates all managed processes and calls `Kill` on each one.
- `func (s *Service) Start(ctx context.Context, command string, args ...string) core.Result`: Convenience wrapper that builds `RunOptions` and delegates to `StartWithOptions`.
- `func (s *Service) StartWithOptions(ctx context.Context, opts RunOptions) core.Result`: Starts a managed process, configures pipes, optional capture, detach and timeout behavior, stores it in the registry, emits `ActionProcessStarted`, streams stdout/stderr lines, and emits `ActionProcessExited` after completion.
- `func (s *Service) Get(id string) (*ManagedProcess, error)`: Returns one managed process or `ErrProcessNotFound`.
- `func (s *Service) List() []*ManagedProcess`: Returns all managed processes currently stored in the service registry.
- `func (s *Service) Running() []*ManagedProcess`: Returns only processes whose `done` channel has not closed yet.
- `func (s *Service) Kill(id string) error`: Kills the managed process by ID and emits `ActionProcessKilled`.
- `func (s *Service) Remove(id string) error`: Deletes a completed process from the registry and rejects removal while it is still running.
- `func (s *Service) Clear()`: Deletes every completed process from the registry.
- `func (s *Service) Output(id string) (string, error)`: Returns the managed process's captured output.
- `func (s *Service) Run(ctx context.Context, command string, args ...string) core.Result`: Convenience wrapper around `RunWithOptions`.
- `func (s *Service) RunWithOptions(ctx context.Context, opts RunOptions) core.Result`: Executes an unmanaged one-shot command with `CombinedOutput`. On success it returns the output string in `Value`; on failure it returns a wrapped error in `Value` and sets `OK` false.