Merge pull request '[agent/codex] Update ALL specs/ sub-package stubs. 1. specs/exec/RFC.md ��...' (#10) from agent/review-codebase-for-ax-compliance--disal into dev
This commit is contained in:
commit
8296075202
4 changed files with 97 additions and 97 deletions
29
specs/api/RFC.md
Normal file
29
specs/api/RFC.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
68
specs/exec/RFC.md
Normal file
68
specs/exec/RFC.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
Loading…
Add table
Reference in a new issue