cmd

type ArtifactCapture ¶

type ArtifactCapture struct {
	Identity stepkind.InvocationIdentity
	Stream   Stream
	Name     string
	MaxBytes int64
	Metadata values.Metadata
}

ArtifactCapture describes already-redacted command bytes. ArtifactSink must stream and bound source to MaxBytes, preserve Metadata exactly, and return a persistable TypeArtifact value.

type ArtifactPutRequestFactory ¶

type ArtifactPutRequestFactory interface {
	ArtifactPutRequest(context.Context, ArtifactCapture) (values.ArtifactPutRequest, error)
}

ArtifactPutRequestFactory supplies host ownership, access, clock, and store data while the adapter fixes content metadata and hard byte bounds.

type ArtifactPutRequestFactoryFunc ¶

type ArtifactPutRequestFactoryFunc func(context.Context, ArtifactCapture) (values.ArtifactPutRequest, error)

ArtifactPutRequestFactoryFunc adapts a function to ArtifactPutRequestFactory.

func (f ArtifactPutRequestFactoryFunc) ArtifactPutRequest(ctx context.Context, capture ArtifactCapture) (values.ArtifactPutRequest, error)

type ArtifactSink ¶

type ArtifactSink interface {
	CaptureArtifact(context.Context, ArtifactCapture, io.Reader) (values.Value, error)
}

ArtifactSink stores a redacted command stream as an immutable artifact.

type ArtifactSinkFunc ¶

type ArtifactSinkFunc func(context.Context, ArtifactCapture, io.Reader) (values.Value, error)

ArtifactSinkFunc adapts a function to ArtifactSink.

func (f ArtifactSinkFunc) CaptureArtifact(ctx context.Context, request ArtifactCapture, source io.Reader) (values.Value, error)

type CaptureConfig ¶

type CaptureConfig struct {
	Mode          CaptureMode `json:"as"`
	Name          string      `json:"name,omitempty"`
	Parse         ParseMode   `json:"parse,omitempty"`
	MaxBytes      int64       `json:"max_bytes,omitempty"`
	MediaType     string      `json:"media_type,omitempty"`
	Compatibility bool        `json:"compatibility,omitempty"`
}

CaptureConfig is the typed cmd@v1 stream-capture contract. MaxBytes is a hard raw and redacted byte bound for retained output, artifacts, or emitted operational events; event streams retain no bytes.

type CaptureMode ¶

type CaptureMode string

const (
	CaptureOutput   CaptureMode = "output"
	CaptureArtifact CaptureMode = "artifact"
	CaptureEvent    CaptureMode = "event_stream"
)

type ConfigDescription ¶

type ConfigDescription struct {
	ConfiguredExecutable string
	Arguments            []string
	ConfiguredCWD        string
	EnvironmentNames     []string
	DeclaredEffects      graph.EffectSet
	DeclaredCapabilities []string
	SandboxExpectation   SandboxSpec
	ConservativeEffects  graph.EffectSet
	RequiredCapabilities []string
	Idempotency          graph.IdempotencyMode
	RetrySafety          stepkind.RetrySafety
}

ConfigDescription separates untrusted author expectations from the conservative metadata that policy must assume for an arbitrary executable.

func DescribeConfig(config graph.Config) (ConfigDescription, []diagnostic.Diagnostic)

type EnvironmentVariable ¶

type EnvironmentVariable struct {
	Name  string
	Value []byte
}

EnvironmentVariable is short-lived process-boundary material. Value may contain a resolved secret and must never be logged, persisted, or retained.

type EventSink ¶

type EventSink interface {
	EmitCommandEvent(context.Context, OperationalEvent) error
}

EventSink receives operational chunks. Implementations must be concurrency- safe and must not reinterpret events as typed workflow outputs.

type EventSinkFunc ¶

type EventSinkFunc func(context.Context, OperationalEvent) error

EventSinkFunc adapts a function to EventSink.

func (f EventSinkFunc) EmitCommandEvent(ctx context.Context, event OperationalEvent) error

type Executor ¶

type Executor struct {
	// contains filtered or unexported fields
}

Executor implements cmd@v1. It is immutable and concurrency-safe when its injected seams honor their documented concurrency contracts.

func New(options Options) (*Executor, error)

func (e *Executor) Execute(ctx context.Context, prepared stepkind.PreparedInvocation) (stepkind.StepResult, error)

func (*Executor) Spec() stepkind.StepKindSpec

func (*Executor) ValidateConfig(_ context.Context, config graph.Config) []diagnostic.Diagnostic

type OSProcessRunner ¶

type OSProcessRunner struct{}

OSProcessRunner is the standard-library direct process runner. It supplies no sandbox isolation and therefore accepts only direct or none profiles already authorized by Policy. It never invokes a shell or inherits env/cwd.

func (OSProcessRunner) Run(ctx context.Context, request ProcessRequest, stdout, stderr io.Writer) (ProcessResult, error)

type OperationalEvent ¶

type OperationalEvent struct {
	Identity stepkind.InvocationIdentity
	Stream   Stream
	Sequence uint64
	Payload  []byte
}

OperationalEvent is redacted, non-durable workflow-output data. Sequence is monotonic within one stream; cross-stream ordering is intentionally not data.

type Options ¶

type Options struct {
	Policy    Policy
	Runner    ProcessRunner
	Secrets   values.SecretResolver
	Artifacts ArtifactSink
	Events    EventSink
}

Options supplies all host-sensitive command boundaries. Policy is required; Runner defaults to OSProcessRunner. Other seams are required only when the corresponding config feature is used.

type ParseMode ¶

type ParseMode string

const (
	ParseText      ParseMode = "text"
	ParseJSON      ParseMode = "json"
	ParseLines     ParseMode = "lines"
	ParseKV        ParseMode = "kv"
	ParseSetOutput ParseMode = "set-output"
)

type Policy ¶

type Policy interface {
	AuthorizeCommand(context.Context, ConfigDescription) (ResolvedCommand, error)
}

Policy resolves and authorizes one structured launch description. It must not inspect shell-like substrings: arguments are already distinct values.

type PolicyFunc ¶

type PolicyFunc func(context.Context, ConfigDescription) (ResolvedCommand, error)

PolicyFunc adapts a function to Policy.

func (f PolicyFunc) AuthorizeCommand(ctx context.Context, description ConfigDescription) (ResolvedCommand, error)

type ProcessRequest ¶

type ProcessRequest struct {
	Executable  string
	Arguments   []string
	CWD         string
	Environment []EnvironmentVariable
	Sandbox     SandboxSpec
}

ProcessRequest is a direct, already-authorized launch request. Runners must defensively copy data they retain, observe ctx, terminate the process before returning on cancellation, drain/close both streams, and enforce Sandbox.

type ProcessResult ¶

type ProcessResult struct {
	ExitCode        int
	EnforcedSandbox SandboxSpec
}

ProcessResult attests the exit status and sandbox actually enforced. A runner returns non-zero exit codes as results, not as raw errors.

type ProcessRunner ¶

type ProcessRunner interface {
	Run(context.Context, ProcessRequest, io.Writer, io.Writer) (ProcessResult, error)
}

ProcessRunner launches a command without a shell.

type ProcessRunnerFunc ¶

type ProcessRunnerFunc func(context.Context, ProcessRequest, io.Writer, io.Writer) (ProcessResult, error)

ProcessRunnerFunc adapts a function to ProcessRunner.

func (f ProcessRunnerFunc) Run(ctx context.Context, request ProcessRequest, stdout, stderr io.Writer) (ProcessResult, error)

type ResolvedCommand ¶

type ResolvedCommand struct {
	Executable            string
	Arguments             []string
	CWD                   string
	EffectiveEffects      graph.EffectSet
	EffectiveCapabilities []string
	Sandbox               SandboxSpec
}

ResolvedCommand is the policy-authoritative launch description. Executable and CWD must be absolute, clean paths. Effective metadata is trusted only because it is returned by Policy, never because an author declared it.

type SandboxSpec ¶

type SandboxSpec struct {
	Profile string `json:"profile"`
}

SandboxSpec is a named isolation expectation. direct and none explicitly mean that the adapter supplies no isolation. Other profiles require an injected runner that enforces and attests the exact authorized profile.

type StoreArtifactSink ¶

type StoreArtifactSink struct {
	Store    values.ArtifactStore
	Requests ArtifactPutRequestFactory
}

StoreArtifactSink connects cmd capture to the workflow ArtifactStore without placing host ownership or authorization rules in this adapter.

func (s StoreArtifactSink) CaptureArtifact(ctx context.Context, capture ArtifactCapture, source io.Reader) (values.Value, error)

type Stream ¶

type Stream string

Stream identifies one process byte stream.

const (
	StreamStdout Stream = "stdout"
	StreamStderr Stream = "stderr"
)