v2 review fixes for Pipe/runner branch

[znull]

This is a rebased version of #62 targeted at #61: Fixes issues discovered doing a review of the latest stage-v2-clean state.

/cc @mhagger

Copilot Summary

This PR ports the v2 review-fix commits onto PR #61's Pipe / runner / Config branch:

• Cancel the derived Pipe context on pre-start failures and include the offending stage name in invalid stream requirement errors.
• Close an already-configured stdout closer before Output() replaces stdout with its capture buffer, adapted to runner.output() / Pipeline.Output().
• Expose WithStdinRequirement and WithStdoutRequirement so Function stages can participate in stream requirement negotiation without reimplementing Stage.
• Document the known limitation for borrowed non-file stdin readers feeding command stages that can exit without draining stdin.

[Copilot]

Pull request overview

This PR ports review-driven fixes onto the Pipe / runner / Config branch, tightening lifecycle cleanup and making stream-requirement negotiation and related error reporting more robust and user-facing.

Changes:

• Ensure pipeline context is canceled on pre-start failures and include stage names in invalid stream requirement errors.
• Make Output() close any previously configured WithStdoutCloser destination before swapping stdout to an internal capture buffer.
• Expose WithStdinRequirement / WithStdoutRequirement for Function stages, and document a known stdin limitation for non-file readers feeding command stages.

Show a summary per file

File	Description
pipe/runner.go	Closes any previously configured stdout closer before capturing output into a buffer.
pipe/pipeline.go	Adds a lifecycle guard to prevent calling Output() after the pipeline has started.
pipe/pipeline_test.go	Adds/updates tests for stdout-closer behavior, function stream requirements, and improved invalid-requirement error messages.
pipe/pipe.go	Cancels derived context on startup failures and improves invalid stream requirement errors with stage names.
pipe/options.go	Documents a known limitation when using borrowed non-file stdin readers with command stages.
pipe/function.go	Exposes function-stage stream requirement options and reuses them in forbid helpers.
pipe/event_error.go	Minor control-flow cleanup in Error() formatting.
pipe/config.go	Fixes option-slice append logic to preserve Config immutability.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 8/8 changed files
• Comments generated: 0

[mhagger]

Thanks for rebasing your fixes on top of #61 ✨

Before I saw this, I addressed the linter problems and massaged those fixes into the #61 branch. My fixes were the same as yours, except that I added a user of sliceConfigOption rather than deleting it.

I also rebased the #61 branch on top of the current znull/stage-v2-clean branch.

Then I rebased this branch on top of the new #61 branch (minus the now-redundant linter fixes commit). The following two commits seemed uncontroversial, so I fast-forwarded them in to the #61 branch already:

• "Document WithStdin blocking-reader limitation"
• "Expose Function stream requirements"

Now I'm reviewing the remaining two commits.

I hope that you don't mind that I manhandled your PR a bit!

[mhagger]

I've adopted "Cancel failed pipeline starts" into #61, but split into two separate commits:

• "Pipe.Start(): improve errors"
• "Cancel context on failed pipeline starts" like the remainder, but using the error value itself to determine whether Start() failed. This seems less error-prone as the code evolves.

I also added more systematic assertions of whether stages and runner have started already to #61 in "More systematically check the states of objects before use". This covers part of the last remaining commit in this PR.

The remaining commit is rebased on top of the current state of #61. I'll have to continue tomorrow, but my comment here also applies to this commit, so let me know if you have thoughts about that topic.

[mhagger]

Regarding stdin or stdout being set redundantly, I decided after all to orient the behavior based on (exec.Cmd).Output(), which emits an error if Cmd.Output() is called on an object that already has Stdout set. If you like what I have pushed to #61, then I think that all of the fixes included in this PR have been integrated into #61, in one form or another. Thanks!

[znull]

everything here is reflected now in #61