feat(fn): add --help, --doc, and standalone file mode to AsMain

[efiacor]

Summary

Extends fn.AsMain with three new capabilities, eliminating the need for cobra, mdtogo, and command.Build() in KRM function implementations.

Changes

• --help flag: Renders human-readable documentation from embedded README mdtogo markers. No cobra boilerplate. Compatible with kpt fn doc.
• --doc flag: Outputs machine-readable JSON (the DocOutput schema) for catalog pipelines.
• Standalone file mode: Accepts positional file arguments for local debugging without piping through STDIN.
• fn.WithDocs(readme, meta): New functional option to register embedded README and metadata.yaml content.

All changes are backward-compatible — existing fn.AsMain(proc) calls work unchanged.

New internal package

go/fn/internal/docs/ provides:

• ParseMarkers: extracts Short/Long/Examples from <!--mdtogo:Short--> ... <!--mdtogo--> markers
• ParseMetadata: parses metadata.yaml
• RenderHelp / RenderDoc: formats output for the two flags

Testing

• 7 property-based tests (rapid) covering round-trip, containment, exclusion, and equivalence properties
• Unit tests for all new code paths (flags, file mode, error handling)
• All existing tests continue to pass

What this enables (downstream)

Once merged, the 21 catalog functions can:

1. Drop cobra and command.Build()
2. Delete generated/docs.go (mdtogo output)
3. Use //go:embed + fn.WithDocs for documentation

Tested against the real set-labels catalog function — --help and --doc produce correct output.

Related Issues

• Relates to Fix kpt fn doc for all catalog fns kpt#4485 — SDK functions now support --help natively
• Fixes Request for Approval: Fix kpt fn doc stdin handling for KRM functions kpt#4374 — fn.AsMain no longer reads stdin when --help is present
• Fixes fn doc output and documentation kpt#2009 — help output no longer includes cobra boilerplate

AI Disclosure

I have used AI in the creation of this PR.

I have used the following AI tools:

• Kiro for implementation, tests, and review iteration

[Copilot]

Pull request overview

This PR extends the Go SDK’s fn.AsMain entrypoint to support self-contained CLI documentation output (--help, --doc) and a “standalone file mode” for running functions against local YAML files, backed by a new internal docs package for parsing embedded README/metadata content.

Changes:

• Added functional options to fn.AsMain (via WithDocs) and implemented --help/--doc handling before STDIN is read.
• Added standalone file mode that assembles a ResourceList from positional file arguments and runs the processor without STDIN piping.
• Introduced go/fn/internal/docs (marker parsing, metadata parsing, help/doc rendering) plus unit and property-based tests (rapid).

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
go/fn/run.go	Adds AsMain options, --help/--doc handling, and standalone file mode + helpers.
go/fn/run_flags_test.go	Adds tests for --help/--doc behaviors and error handling.
go/fn/run_filemode_test.go	Adds unit tests for standalone file mode and helper behavior.
go/fn/run_filemode_property_test.go	Adds rapid property test for file-mode vs STDIN-mode equivalence.
go/fn/internal/docs/render.go	Implements help/doc renderers and the DocOutput JSON schema.
go/fn/internal/docs/render_test.go	Adds unit + property tests for rendering behaviors.
go/fn/internal/docs/metadata.go	Adds metadata.yaml parsing into a typed struct.
go/fn/internal/docs/metadata_test.go	Adds unit + property tests for metadata parsing and round-trips.
go/fn/internal/docs/markers.go	Adds README mdtogo marker extraction with a fallback mode.
go/fn/internal/docs/markers_test.go	Adds property tests for marker parsing and missing-marker fallback.
go/fn/go.mod	Adds pgregory.net/rapid dependency (currently marked indirect).
go/fn/go.sum	Adds checksum entries for pgregory.net/rapid.

---

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