Documentation
¶
Overview ¶
Package tee implements the TeePlugin: a transform plugin that wraps every non-trivial pipeline stage with `| tee /OUT/<idx>-<cmd>.stdout.txt` so the host can post-mortem the per-stage output of a script.
Behavior ¶
For every pipeline stage in the script (including a single-command "pipeline" that has no `|` operator), the plugin inserts a tee stage immediately after it that mirrors the stage's stdout to a file inside Options.OutputDir. Stages whose command name does not match Options.TargetCommandMatch (when non-nil) are skipped. Stages whose command name is `tee` itself are also skipped — the plugin is idempotent under repeated application.
PIPESTATUS preservation ¶
The naive `cmd | tee file` rewrite would shift PIPESTATUS by one position per inserted stage and change the exit status reported via pipefail. The spec calls for porting just-bash's restore semantics "faithfully"; the Phase 13 MVP injects the tee but does NOT yet emit the restore-pipeline. Scripts that observe `$PIPESTATUS` or `set -o pipefail` exit codes after a wrapped pipeline will see the shifted form. This is documented in DECISIONS.md as a Phase 13 follow-up.
Metadata ¶
The plugin's metadata payload is a `[]TeeFileInfo` (one entry per wrapped stage, in source order). It is exposed under BashExecResult.Metadata[Name] as `map[string]any{ "files": []TeeFileInfo{...} }`.
Index ¶
Constants ¶
const MetadataKey = "files"
MetadataKey is the key under the plugin's metadata payload that carries the []TeeFileInfo slice.
const Name = "tee"
Name is the metadata key the plugin uses.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// OutputDir is the directory the tee file paths are joined under.
// Required; empty disables the plugin (Transform becomes a no-op).
OutputDir string
// TargetCommandMatch decides which commands get wrapped. Nil
// means "every stage with a recognizable command name".
TargetCommandMatch func(string) bool
// Timestamp is exposed to plugins/hosts that want a single
// monotonic clock value for the wrapped run. Defaults to
// time.Now() at New time.
Timestamp time.Time
}
Options configures a TeePlugin.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the TeePlugin instance. Each Transform call assigns its own sequential CommandIndex starting at 0; sharing a Plugin across pipelines is safe (no per-Plugin state is mutated across calls).
Source Files