diff --git a/specs/exec.md b/specs/exec.md new file mode 100644 index 0000000..068fdb7 --- /dev/null +++ b/specs/exec.md @@ -0,0 +1,68 @@ +# exec +**Import:** `dappco.re/go/core/process/exec` +**Files:** 3 + +## Types + +### `Options` +`struct` + +Execution settings stored on `Cmd`. + +Fields: +- `Dir string`: Working directory. +- `Env []string`: Additional environment entries appended to `os.Environ()`. +- `Stdin io.Reader`: Reader wired to command stdin. +- `Stdout io.Writer`: Writer wired to command stdout. +- `Stderr io.Writer`: Writer wired to command stderr. + +### `Cmd` +`struct` + +Fluent wrapper around `os/exec.Cmd`. + +Exported fields: +- None. + +### `Logger` +`interface` + +Structured logger contract used by the package. + +Methods: +- `Debug(msg string, keyvals ...any)`: Debug-level event logging. +- `Error(msg string, keyvals ...any)`: Error-level event logging. + +### `NopLogger` +`struct` + +No-op logger implementation used as the package default. + +Exported fields: +- None. + +## Functions + +### Package Functions + +- `func Command(ctx context.Context, name string, args ...string) *Cmd`: Creates a `Cmd` with the supplied command name, arguments, and context. +- `func RunQuiet(ctx context.Context, name string, args ...string) error`: Runs a command with stdout suppressed, captures stderr into a buffer, and wraps any failure with `core.E("RunQuiet", ...)`. +- `func SetDefaultLogger(l Logger)`: Replaces the package-level default logger. Passing `nil` resets it to `NopLogger`. +- `func DefaultLogger() Logger`: Returns the current package-level default logger. + +### `Cmd` Methods + +- `func (c *Cmd) WithDir(dir string) *Cmd`: Sets the working directory on the stored options and returns the same command for chaining. +- `func (c *Cmd) WithEnv(env []string) *Cmd`: Sets extra environment variables and returns the same command for chaining. +- `func (c *Cmd) WithStdin(r io.Reader) *Cmd`: Sets stdin and returns the same command for chaining. +- `func (c *Cmd) WithStdout(w io.Writer) *Cmd`: Sets stdout and returns the same command for chaining. +- `func (c *Cmd) WithStderr(w io.Writer) *Cmd`: Sets stderr and returns the same command for chaining. +- `func (c *Cmd) WithLogger(l Logger) *Cmd`: Sets a per-command logger that overrides the package default. +- `func (c *Cmd) Run() error`: Builds the underlying `exec.Cmd`, logs a debug event, runs the command, and wraps failures with command context. +- `func (c *Cmd) Output() ([]byte, error)`: Builds the underlying `exec.Cmd`, logs a debug event, returns stdout bytes, and wraps failures. +- `func (c *Cmd) CombinedOutput() ([]byte, error)`: Builds the underlying `exec.Cmd`, logs a debug event, returns combined stdout and stderr bytes, and wraps failures while preserving the output bytes from `exec.Cmd.CombinedOutput`. + +### `NopLogger` Methods + +- `func (NopLogger) Debug(string, ...any)`: Discards debug messages. +- `func (NopLogger) Error(string, ...any)`: Discards error messages. diff --git a/specs/pkg-api.md b/specs/pkg-api.md new file mode 100644 index 0000000..fc73f41 --- /dev/null +++ b/specs/pkg-api.md @@ -0,0 +1,29 @@ +# api +**Import:** `dappco.re/go/core/process/pkg/api` +**Files:** 2 + +## Types + +### `ProcessProvider` +`struct` + +Route-group and renderable provider for process-daemon registry APIs and the bundled UI entrypoint. + +Exported fields: +- None. + +## Functions + +### Package Functions + +- `func NewProvider(registry *process.Registry, hub *ws.Hub) *ProcessProvider`: Creates a provider backed by the supplied registry and WebSocket hub. When `registry` is `nil`, it uses `process.DefaultRegistry()`. +- `func PIDAlive(pid int) bool`: Uses `os.FindProcess` plus signal `0` to report whether a PID is still alive. + +### `ProcessProvider` Methods + +- `func (p *ProcessProvider) Name() string`: Returns the route-group name `"process"`. +- `func (p *ProcessProvider) BasePath() string`: Returns the route-group base path `"/api/process"`. +- `func (p *ProcessProvider) Element() provider.ElementSpec`: Returns the UI element spec with tag `core-process-panel` and script source `/assets/core-process.js`. +- `func (p *ProcessProvider) Channels() []string`: Returns the WebSocket channels exposed by the provider: daemon started, daemon stopped, daemon health, process started, process output, process exited, and process killed. +- `func (p *ProcessProvider) RegisterRoutes(rg *gin.RouterGroup)`: Registers `GET /daemons`, `GET /daemons/:code/:daemon`, `POST /daemons/:code/:daemon/stop`, and `GET /daemons/:code/:daemon/health`. +- `func (p *ProcessProvider) Describe() []api.RouteDescription`: Returns static route descriptions for the daemon list, single-daemon lookup, daemon stop, and daemon health endpoints. diff --git a/specs/process-ui.md b/specs/process-ui.md new file mode 100644 index 0000000..77ad8fb --- /dev/null +++ b/specs/process-ui.md @@ -0,0 +1,207 @@ +# @core/process-ui +**Import:** `@core/process-ui` +**Files:** 8 + +## Types + +### `DaemonEntry` +`interface` + +Daemon-registry row returned by `ProcessApi.listDaemons` and `ProcessApi.getDaemon`. + +Properties: +- `code: string`: Application or component code. +- `daemon: string`: Daemon name. +- `pid: number`: Process ID. +- `health?: string`: Optional health-endpoint address. +- `project?: string`: Optional project label. +- `binary?: string`: Optional binary label. +- `started: string`: Start timestamp string from the API. + +### `HealthResult` +`interface` + +Result returned by the daemon health endpoint. + +Properties: +- `healthy: boolean`: Health outcome. +- `address: string`: Health endpoint address that was checked. +- `reason?: string`: Optional explanation such as the absence of a health endpoint. + +### `ProcessInfo` +`interface` + +Process snapshot shape used by the UI package. + +Properties: +- `id: string`: Managed-process identifier. +- `command: string`: Executable name. +- `args: string[]`: Command arguments. +- `dir: string`: Working directory. +- `startedAt: string`: Start timestamp string. +- `status: 'pending' | 'running' | 'exited' | 'failed' | 'killed'`: Process status string. +- `exitCode: number`: Exit code. +- `duration: number`: Numeric duration value from the API payload. +- `pid: number`: Child PID. + +### `RunResult` +`interface` + +Pipeline result row used by `ProcessRunner`. + +Properties: +- `name: string`: Spec name. +- `exitCode: number`: Exit code. +- `duration: number`: Numeric duration value. +- `output: string`: Captured output. +- `error?: string`: Optional error message. +- `skipped: boolean`: Whether the spec was skipped. +- `passed: boolean`: Whether the spec passed. + +### `RunAllResult` +`interface` + +Aggregate pipeline result consumed by `ProcessRunner`. + +Properties: +- `results: RunResult[]`: Per-spec results. +- `duration: number`: Aggregate duration. +- `passed: number`: Count of passed specs. +- `failed: number`: Count of failed specs. +- `skipped: number`: Count of skipped specs. +- `success: boolean`: Aggregate success flag. + +### `ProcessApi` +`class` + +Typed fetch client for `/api/process/*`. + +Public API: +- `new ProcessApi(baseUrl?: string)`: Stores an optional URL prefix. The default is `""`. +- `listDaemons(): Promise`: Fetches `GET /api/process/daemons`. +- `getDaemon(code: string, daemon: string): Promise`: Fetches one daemon entry. +- `stopDaemon(code: string, daemon: string): Promise<{ stopped: boolean }>`: Sends `POST /api/process/daemons/:code/:daemon/stop`. +- `healthCheck(code: string, daemon: string): Promise`: Fetches `GET /api/process/daemons/:code/:daemon/health`. + +### `ProcessEvent` +`interface` + +Event envelope consumed by `connectProcessEvents`. + +Properties: +- `type: string`: Event type. +- `channel?: string`: Optional channel name. +- `data?: any`: Event payload. +- `timestamp?: string`: Optional timestamp string. + +### `ProcessPanel` +`class` + +Top-level custom element registered as ``. + +Public properties: +- `apiUrl: string`: Forwarded to child elements through the `api-url` attribute. +- `wsUrl: string`: WebSocket endpoint URL from the `ws-url` attribute. + +Behavior: +- Renders tabbed daemon, process, and pipeline views. +- Opens a process-event WebSocket when `wsUrl` is set. +- Shows the last received process channel or event type in the footer. + +### `ProcessDaemons` +`class` + +Daemon-list custom element registered as ``. + +Public properties: +- `apiUrl: string`: Base URL prefix for `ProcessApi`. + +Behavior: +- Loads daemon entries on connect. +- Can trigger per-daemon health checks and stop requests. +- Emits `daemon-stopped` after a successful stop request. + +### `ProcessList` +`class` + +Managed-process list custom element registered as ``. + +Public properties: +- `apiUrl: string`: Declared API prefix property. +- `selectedId: string`: Selected process ID, reflected from `selected-id`. + +Behavior: +- Emits `process-selected` when a row is chosen. +- Currently renders from local state only because the process REST endpoints referenced by the component are not implemented in this package. + +### `ProcessOutput` +`class` + +Live output custom element registered as ``. + +Public properties: +- `apiUrl: string`: Declared API prefix property. The current implementation does not use it. +- `wsUrl: string`: WebSocket endpoint URL. +- `processId: string`: Selected process ID from the `process-id` attribute. + +Behavior: +- Connects to the WebSocket when both `wsUrl` and `processId` are present. +- Filters for `process.output` events whose payload `data.id` matches `processId`. +- Appends output lines and auto-scrolls by default. + +### `ProcessRunner` +`class` + +Pipeline-results custom element registered as ``. + +Public properties: +- `apiUrl: string`: Declared API prefix property. +- `result: RunAllResult | null`: Aggregate pipeline result used for rendering. + +Behavior: +- Renders summary counts plus expandable per-spec output. +- Depends on the `result` property today because pipeline REST endpoints are not implemented in the package. + +## Functions + +### Package Functions + +- `function connectProcessEvents(wsUrl: string, handler: (event: ProcessEvent) => void): WebSocket`: Opens a WebSocket, parses incoming JSON, forwards only messages whose `type` or `channel` starts with `process.`, ignores malformed payloads, and returns the `WebSocket` instance. + +### `ProcessPanel` Methods + +- `connectedCallback(): void`: Calls the LitElement base implementation and opens the WebSocket when `wsUrl` is set. +- `disconnectedCallback(): void`: Calls the LitElement base implementation and closes the current WebSocket. +- `render(): unknown`: Renders the header, tab strip, active child element, and connection footer. + +### `ProcessDaemons` Methods + +- `connectedCallback(): void`: Instantiates `ProcessApi` and loads daemon data. +- `loadDaemons(): Promise`: Fetches daemon entries, stores them in component state, and records any request error message. +- `render(): unknown`: Renders the daemon list, loading state, empty state, and action buttons. + +### `ProcessList` Methods + +- `connectedCallback(): void`: Calls the LitElement base implementation and invokes `loadProcesses`. +- `loadProcesses(): Promise`: Current placeholder implementation that clears state because the referenced process REST endpoints are not implemented yet. +- `render(): unknown`: Renders the process list or an informational empty state explaining the missing REST support. + +### `ProcessOutput` Methods + +- `connectedCallback(): void`: Calls the LitElement base implementation and opens the WebSocket when `wsUrl` and `processId` are both set. +- `disconnectedCallback(): void`: Calls the LitElement base implementation and closes the current WebSocket. +- `updated(changed: Map): void`: Reconnects when `processId` or `wsUrl` changes, resets buffered lines on reconnection, and auto-scrolls when enabled. +- `render(): unknown`: Renders the output panel, waiting state, and accumulated stdout or stderr lines. + +### `ProcessRunner` Methods + +- `connectedCallback(): void`: Calls the LitElement base implementation and invokes `loadResults`. +- `loadResults(): Promise`: Current placeholder method. The implementation is empty because pipeline endpoints are not present. +- `render(): unknown`: Renders the empty-state notice when `result` is absent, or the aggregate summary plus per-spec details when `result` is present. + +### `ProcessApi` Methods + +- `listDaemons(): Promise`: Returns the `data` field from a successful daemon-list response. +- `getDaemon(code: string, daemon: string): Promise`: Returns one daemon entry from the provider API. +- `stopDaemon(code: string, daemon: string): Promise<{ stopped: boolean }>`: Issues the stop request and returns the provider's `{ stopped }` payload. +- `healthCheck(code: string, daemon: string): Promise`: Returns the daemon-health payload. diff --git a/specs/process.md b/specs/process.md new file mode 100644 index 0000000..a6f4460 --- /dev/null +++ b/specs/process.md @@ -0,0 +1,372 @@ +# 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:///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 `-.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.