Request for Approval: Fix kpt fn doc stdin handling for KRM functions

[pmady]

Summary

Some KRM functions fail when using kpt fn doc because they attempt to parse input from stdin even when the --help flag is provided. This results in the error: failed to parse input bytes: expected exactly one object, got 0.

Problem Statement

When running kpt fn doc <function>, the command invokes the container with --help to retrieve documentation. However, certain KRM functions are designed to always read from stdin, regardless of flags provided. When no input is piped, these functions fail before displaying help documentation.

Affected functions include (but not limited to):

• set-namespace
• set-labels
• set-annotations
• Other functions from the official catalog

Proposed Solution

PR #4352 implements a fix at the kpt fn doc level by providing an empty ResourceList as stdin when invoking containers with --help. This approach:

✅ Pros:

• Single fix that works for all functions (current and future)
• Provides immediate relief for users
• Backward-compatible - no breaking changes
• No changes needed in individual function repositories
• Common pattern used by many CLI tools
• Future KRM functions automatically benefit

⚠️ Cons:

• Masks the underlying behavior of functions that don't handle --help gracefully
• Doesn't address root cause in individual functions

Alternative Approach

Fix each KRM function individually to handle --help without requiring stdin input.

✅ Pros:

• Addresses root cause in each function
• Functions become more robust

⚠️ Cons:

• Requires changes across multiple function repositories/images
• Each function maintainer needs to update their code
• Takes longer to roll out
• Doesn't help with third-party or deprecated functions

Request for Approval

We're seeking official approval to proceed with the fix in PR #4352 (Option 1: fix at kpt fn doc level) for the following reasons:

1. User Impact: This issue affects users trying to view documentation for multiple supported functions
2. Immediate Solution: The fix is ready and tested
3. Future-Proof: Automatically handles new functions without requiring updates
4. Minimal Risk: The change is isolated and doesn't affect normal function execution

Follow-up Work

If approved, we should:

1. Merge PR fix: Add stdin support to kpt fn doc for KRM functions expecting input #4352 to provide immediate relief
2. Create a separate tracking issue to document which officially supported functions (from catalog.kpt.dev) should eventually be fixed upstream to handle --help gracefully
3. Work with function maintainers over time to implement proper --help handling

Related Issues

• Fixes The "kpt fn doc" command only works on some krm functions #4278
• PR fix: Add stdin support to kpt fn doc for KRM functions expecting input #4352

Questions for Maintainers

1. Do you approve proceeding with the kpt fn doc level fix?
2. Should we prioritize fixing individual functions instead?
3. Would you like both approaches (immediate fix + long-term upstream fixes)?

---

Note: This issue was created following feedback from @efiacor on PR #4352, who approved the approach but requested proper tracking of functions that need upstream fixes.

[SurbhiAgarwal1]

Hey! I'd like to work on this issue.

I've looked at PR #4352 and understand the fix - basically need to provide an empty ResourceList as stdin when running kpt fn doc so functions that always read stdin don't fail on --help.

I can implement this by modifying commands/fn/doc/cmdfndoc.go to add the stdin flags and provide the empty YAML structure. Will also add tests to cover the affected functions.

Can you assign this to me? Thanks!