runpkg

Documentation

Overview

Package runpkg implements the `dockyard run` verb — running a Dockyard project's MCP server on a chosen transport (RFC §14, §9.1).

`dockyard run --transport <stdio|http>` builds the project (reusing the internal/buildpkg pipeline — a host-only build) and then runs the produced server binary as a supervised child process. The transport selection and the HTTP listen address are passed to the child through the DOCKYARD_TRANSPORT and DOCKYARD_HTTP_ADDR environment variables; the project's own main.go owns its transport wiring (RFC §5.2 — runpkg drives the server, it never reimplements a transport).

runpkg honours context cancellation / SIGINT: cancelling the context tears the server child down cleanly with a SIGTERM-then-SIGKILL grace window, the same teardown discipline internal/devloop uses, so a `dockyard run` leaves no orphan process.

runpkg is internal — the reusable, testable seam the `dockyard run` cobra verb and the Phase 20 integration test consume. It holds no shared mutable state.

Index

• Variables
• func Run(ctx context.Context, opts Options) error
• type Options
• type Transport
  • func ParseTransport(s string) (Transport, error)

Variables

var ErrRun = errors.New("dockyard/internal/runpkg: run failed")

ErrRun is the sentinel wrapping a `dockyard run` failure. Callers branch with errors.Is(err, ErrRun).

Functions

func Run

func Run(ctx context.Context, opts Options) error

Run builds the project's MCP server (a host-only `dockyard build`) and runs the produced binary as a supervised child process on the chosen transport. It blocks until ctx is cancelled, at which point the child is torn down cleanly (SIGTERM, then SIGKILL after stopGrace) — no orphan process.

Run reuses internal/buildpkg for the build so a `dockyard run` always serves a freshly-built, validated, CGo-free binary; a validation blocker fails the run before the server is ever started.

Types

type Options

type Options struct {
	// ProjectDir is the root of the Dockyard project — the directory holding
	// dockyard.app.yaml. Required.
	ProjectDir string
	// Transport is the deployment mode to serve over. The zero value ("")
	// defaults to stdio.
	Transport Transport
	// Addr is the listen address for the HTTP transport (e.g.
	// "127.0.0.1:8080"). Ignored for stdio. An empty value with TransportHTTP
	// defaults to defaultHTTPAddr.
	Addr string
	// Logger receives the run's structured output. A nil Logger falls back to
	// a discarding logger so Run never panics on a missing logger.
	Logger *slog.Logger
}

Options configures one `dockyard run` invocation.

type Transport

type Transport string

Transport is the deployment mode `dockyard run` serves the project's MCP server over (RFC §5.2, §14). V1 supports stdio and http.

const (
	// TransportStdio is the local single-user subprocess transport — the
	// default `dockyard run` mode.
	TransportStdio Transport = "stdio"
	// TransportHTTP is the streamable-HTTP transport.
	TransportHTTP Transport = "http"
)

func ParseTransport

func ParseTransport(s string) (Transport, error)

ParseTransport validates a transport flag value and returns the typed Transport. An empty value defaults to stdio (the local mode); an unknown value is a clear, typed error.