From cca45eebccfd2d90f7cdaa36338e5bbe11ce3ff8 Mon Sep 17 00:00:00 2001 From: Virgil Date: Fri, 27 Mar 2026 22:06:02 +0000 Subject: [PATCH] docs(specs): move subpackage RFC stubs --- specs/api/RFC.md | 29 ++++++++++++++++++++ specs/exec.md | 68 ----------------------------------------------- specs/exec/RFC.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++ specs/pkg-api.md | 29 -------------------- 4 files changed, 97 insertions(+), 97 deletions(-) create mode 100644 specs/api/RFC.md delete mode 100644 specs/exec.md create mode 100644 specs/exec/RFC.md delete mode 100644 specs/pkg-api.md diff --git a/specs/api/RFC.md b/specs/api/RFC.md new file mode 100644 index 0000000..158b73f --- /dev/null +++ b/specs/api/RFC.md @@ -0,0 +1,29 @@ +# api +**Import:** `dappco.re/go/core/process/pkg/api` +**Files:** 2 + +## Types + +### `ProcessProvider` +`struct` + +Service provider that wraps the go-process daemon registry and bundled UI entrypoint. + +Exported fields: +- None. + +## Functions + +### Package Functions + +- `func NewProvider(registry *process.Registry, hub *ws.Hub) *ProcessProvider`: Returns a `ProcessProvider` for the supplied registry and WebSocket hub. When `registry` is `nil`, it uses `process.DefaultRegistry()`. +- `func PIDAlive(pid int) bool`: Returns `false` for non-positive PIDs and otherwise reports whether `os.FindProcess(pid)` followed by signal `0` succeeds. + +### `ProcessProvider` Methods + +- `func (p *ProcessProvider) Name() string`: Returns `"process"`. +- `func (p *ProcessProvider) BasePath() string`: Returns `"/api/process"`. +- `func (p *ProcessProvider) Element() provider.ElementSpec`: Returns an element spec with tag `core-process-panel` and source `/assets/core-process.js`. +- `func (p *ProcessProvider) Channels() []string`: Returns `process.daemon.started`, `process.daemon.stopped`, `process.daemon.health`, `process.started`, `process.output`, `process.exited`, and `process.killed`. +- `func (p *ProcessProvider) RegisterRoutes(rg *gin.RouterGroup)`: Registers the daemon list, daemon lookup, daemon stop, and daemon health routes. +- `func (p *ProcessProvider) Describe() []api.RouteDescription`: Returns static route descriptions for the registered daemon routes. diff --git a/specs/exec.md b/specs/exec.md deleted file mode 100644 index 068fdb7..0000000 --- a/specs/exec.md +++ /dev/null @@ -1,68 +0,0 @@ -# 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/exec/RFC.md b/specs/exec/RFC.md new file mode 100644 index 0000000..5a43ad8 --- /dev/null +++ b/specs/exec/RFC.md @@ -0,0 +1,68 @@ +# exec +**Import:** `dappco.re/go/core/process/exec` +**Files:** 3 + +## Types + +### `Options` +`struct` + +Command execution options used by `Cmd`. + +Fields: +- `Dir string`: Working directory. +- `Env []string`: Environment entries appended to `os.Environ()` when non-empty. +- `Stdin io.Reader`: Reader assigned to command stdin. +- `Stdout io.Writer`: Writer assigned to command stdout. +- `Stderr io.Writer`: Writer assigned to command stderr. + +### `Cmd` +`struct` + +Wrapped command with chainable configuration methods. + +Exported fields: +- None. + +### `Logger` +`interface` + +Command-execution logger. + +Methods: +- `Debug(msg string, keyvals ...any)`: Logs a debug-level message. +- `Error(msg string, keyvals ...any)`: Logs an error-level message. + +### `NopLogger` +`struct` + +No-op `Logger` implementation. + +Exported fields: +- None. + +## Functions + +### Package Functions + +- `func Command(ctx context.Context, name string, args ...string) *Cmd`: Returns a `Cmd` for the supplied context, executable name, and arguments. +- `func RunQuiet(ctx context.Context, name string, args ...string) error`: Runs a command with stderr captured into a buffer and returns `core.E("RunQuiet", core.Trim(stderr.String()), err)` on failure. +- `func SetDefaultLogger(l Logger)`: Sets the package-level default logger. Passing `nil` replaces it with `NopLogger`. +- `func DefaultLogger() Logger`: Returns the package-level default logger. + +### `Cmd` Methods + +- `func (c *Cmd) WithDir(dir string) *Cmd`: Sets `Options.Dir` and returns the same command. +- `func (c *Cmd) WithEnv(env []string) *Cmd`: Sets `Options.Env` and returns the same command. +- `func (c *Cmd) WithStdin(r io.Reader) *Cmd`: Sets `Options.Stdin` and returns the same command. +- `func (c *Cmd) WithStdout(w io.Writer) *Cmd`: Sets `Options.Stdout` and returns the same command. +- `func (c *Cmd) WithStderr(w io.Writer) *Cmd`: Sets `Options.Stderr` and returns the same command. +- `func (c *Cmd) WithLogger(l Logger) *Cmd`: Sets a command-specific logger and returns the same command. +- `func (c *Cmd) Run() error`: Prepares the underlying `exec.Cmd`, logs `"executing command"`, runs it, and wraps failures with `wrapError("Cmd.Run", ...)`. +- `func (c *Cmd) Output() ([]byte, error)`: Prepares the underlying `exec.Cmd`, logs `"executing command"`, returns stdout bytes, and wraps failures with `wrapError("Cmd.Output", ...)`. +- `func (c *Cmd) CombinedOutput() ([]byte, error)`: Prepares the underlying `exec.Cmd`, logs `"executing command"`, returns combined stdout and stderr, and wraps failures with `wrapError("Cmd.CombinedOutput", ...)`. + +### `NopLogger` Methods + +- `func (NopLogger) Debug(string, ...any)`: Discards the message. +- `func (NopLogger) Error(string, ...any)`: Discards the message. diff --git a/specs/pkg-api.md b/specs/pkg-api.md deleted file mode 100644 index fc73f41..0000000 --- a/specs/pkg-api.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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. -- 2.45.3