feat(plugin): help integration with --help-oneliner protocol (Phase 2)#190
Open
gwpl wants to merge 5 commits intosteipete:mainfrom
Open
feat(plugin): help integration with --help-oneliner protocol (Phase 2)#190gwpl wants to merge 5 commits intosteipete:mainfrom
gwpl wants to merge 5 commits intosteipete:mainfrom
Conversation
Document Phase 1 MVP design for cargo/git-style external commands. Key design decisions with rationale: * Post-parse fallback (Option B): Built-in commands always take precedence over external plugins, preventing shadowing * Longest-first matching: More specific plugins win over generic ones * gog-* prefix: Matches CLI binary name (git/cargo convention) Part of steipete#188 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implement cargo/git-style external command discovery:
* Search PATH for gog-{subcommands} binaries
* Longest-first (greedy) matching: gog-docs-headings wins over gog-docs
* Pass remaining args to plugin
* Use syscall.Exec for true process replacement
Design rationale documented in code comments:
- Longest-first: More specific plugins take precedence
- gog-* prefix: Matches CLI binary name (following git/cargo)
Unit tests document and verify the matching behavior.
Part of steipete#188
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Hook external command discovery into Kong parse error handling: * Try external command AFTER Kong parsing fails (post-parse fallback) * If found: exec replaces current process * If not found: return original Kong error Design choice: Post-parse fallback (Option B) Why: Built-in commands always take precedence over external plugins. This prevents accidental or malicious shadowing of core functionality and follows the git/cargo convention. Part of steipete#188 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add infrastructure for Phase 2 help integration: * DiscoverExternalPlugins(): Scan PATH for all gog-* binaries * FetchOneliners(): Query plugins with --help-oneliner flag * GroupPluginsByTopLevel(): Group plugins by first subcommand * ExternalPlugin struct with CommandName() helper Protocol: Plugins respond to --help-oneliner with single line (≤80 chars). Short 100ms timeout keeps help responsive; unresponsive plugins get no description. Design notes in code: - First PATH occurrence wins (matches exec.LookPath behavior) - Plugins sorted alphabetically for consistent display Unit tests document grouping and command name behavior. Part of steipete#188 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Display discovered plugins in a "Plugins:" section after "Commands:".
Features:
* Lazy discovery: only scans PATH when help is requested
* Aligned output: plugin descriptions line up for readability
* Colorized: uses same styling as built-in commands
* Root help only: plugins not shown in subcommand help
Example output:
Plugins:
docs headings List document headings with hierarchy and URLs
hello Say hello (example plugin)
Part of steipete#188
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 2 of external plugin architecture (Issue #188). Builds on Phase 1 (#189).
Adds plugin discovery and help integration:
gog --helpunder a new "Plugins:" section--help-onelinerprotocol for plugin descriptionsFeatures
Plugin Discovery
gog-*binaries--help-oneliner Protocol
--help-onelinerwith single line (≤80 chars)Help Integration
Example Output
Example Plugin
Changes
internal/cmd/external.go- DiscoverExternalPlugins(), FetchOneliners()internal/cmd/external_test.go- Tests for grouping and CommandName()internal/cmd/help_printer.go- injectExternalPlugins(), colorizationTest plan
Dependencies
Depends on Phase 1: #189
Part of #188
Generated with Claude Code
Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com