commit 452f50a28146177209ae395e9a77b8bb4226e8a0 Author: Zhongwei Li Date: Sun Nov 30 08:46:26 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..29ff638 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "yaml", + "description": "Generate comprehensive YAML documentation from Go struct definitions with sensible default values", + "version": "0.0.1", + "author": { + "name": "saswatamcode" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..78e214c --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# yaml + +Generate comprehensive YAML documentation from Go struct definitions with sensible default values diff --git a/commands/docs.md b/commands/docs.md new file mode 100644 index 0000000..6b5c91e --- /dev/null +++ b/commands/docs.md @@ -0,0 +1,168 @@ +--- +description: Generate comprehensive YAML documentation from Go struct definitions with sensible default values +argument-hint: [file:StructName] [output.md] +--- + +## Name +yaml:docs + +## Synopsis +``` +/yaml:docs [file:StructName] [output.md] +``` + +## Description +The `yaml:docs` command generates comprehensive YAML documentation from Go struct definitions. It analyzes Go structs and produces complete, well-documented YAML configuration examples with intelligent default values for all fields. + +This command is designed to help developers quickly create YAML configuration documentation by: +- Automatically generating sensible default values for all struct fields +- Adding inline comments explaining each field's purpose and constraints +- Maintaining proper YAML formatting and structure +- Supporting nested structs, slices, maps, and complex types +- Respecting struct tags (yaml, json, validate, default) + +The spec sections is inspired by https://man7.org/linux/man-pages/man7/man-pages.7.html#top_of_page + +## Implementation + +You are a specialized tool for generating comprehensive YAML documentation from Go struct definitions. + +### Task + +Analyze the provided Go struct and generate complete YAML documentation with: +- All fields populated with intelligent, sensible default values (never leave fields empty) +- Inline comments explaining each field's purpose and constraints +- Proper YAML formatting and structure +- Nested YAML for embedded structs with all sub-fields populated + +### Input Handling + +The user may provide input in these formats: +1. `$1 $2` - File path with struct name (e.g., `pkg/api/types.go:MetricsConfig`) and optional output file path +2. `$1` - Just the file path with struct name +3. Selected code containing a Go struct definition (no arguments) + +### Instructions + +1. **Locate the struct:** + - If a file path is provided (format: `file.go:StructName`), read that file and find the specified struct + - If code is selected, use the selected Go struct definition + - Search for the struct definition and any embedded struct types + +2. **Analyze struct metadata:** + - Examine struct tags: `yaml`, `json`, `validate`, `default` + - Note validation constraints (min, max, required, etc.) + - Identify field types (strings, ints, bools, slices, maps, nested structs, pointers) + - Preserve field ordering from the struct definition + +3. **Generate intelligent defaults:** + - **Strings**: Use contextually appropriate values based on field names (e.g., "localhost" for host, "info" for log level) + - **Integers**: Use common sensible values (e.g., 8080 for port, 30 for timeout seconds) + - **Booleans**: Default to `false` unless the field name suggests otherwise + - **Durations**: Use human-readable format (e.g., "30s", "5m", "1h") + - **Slices**: Provide 1-2 example values in array format + - **Maps**: Provide 1-2 example key-value pairs + - **Nested structs**: Recursively populate all sub-fields + - **Pointers**: Treat as optional but still provide example values + +4. **Format the output:** + - Use proper YAML indentation (2 spaces) + - Add inline comments with `#` explaining each field + - Include validation constraints in comments where applicable + - Add section headers for major struct groups + - Ensure valid YAML syntax + +5. **Write the output:** + - If an output file path is provided as `$2`, use the Write tool to create that file with the generated YAML content (write pure YAML, not markdown) + - Otherwise, display the generated YAML to the user in a markdown code block with yaml syntax highlighting + +### Important Behaviors + +- **ALWAYS populate all fields** - never leave fields empty or use placeholder text +- Infer contextually appropriate defaults from field names and types +- Include helpful comments explaining what each field does +- Maintain the struct's field order in the YAML output +- Handle complex nested structures by recursively applying these rules + +## Return Value +- **Claude agent text**: Generated YAML documentation with intelligent defaults and inline comments +- **File output** (if $2 provided): YAML file written to the specified path + +## Examples + +### Example 1: Basic usage with file path and struct name +``` +/yaml:docs pkg/config/server.go:ServerConfig +``` + +Input struct: +```go +type ServerConfig struct { + Host string `yaml:"host" json:"host" validate:"required"` + Port int `yaml:"port" json:"port" validate:"min=1,max=65535"` + Timeout time.Duration `yaml:"timeout" json:"timeout"` + Debug bool `yaml:"debug" json:"debug"` + Features []string `yaml:"features" json:"features"` +} +``` + +Output: +```yaml +# Server configuration +host: "localhost" # Required: Server hostname or IP address +port: 8080 # Port number (1-65535) +timeout: "30s" # Request timeout duration +debug: false # Enable debug logging +features: ["metrics", "tracing"] # List of enabled features +``` + +### Example 2: Complex nested structs with output file +``` +/yaml:docs pkg/config/database.go:DatabaseConfig config/database.yaml +``` + +Input struct: +```go +type DatabaseConfig struct { + Host string `yaml:"host"` + Port int `yaml:"port"` + SSL SSLConfig `yaml:"ssl"` + Pools map[string]int `yaml:"pools"` + Metadata *MetadataConfig `yaml:"metadata,omitempty"` +} + +type SSLConfig struct { + Enabled bool `yaml:"enabled"` + CertFile string `yaml:"cert_file"` + KeyFile string `yaml:"key_file"` +} +``` + +Generated YAML (written to config/database.yaml): +```yaml +# Database configuration +host: "localhost" # Database host +port: 5432 # Database port +ssl: # SSL configuration + enabled: true # Enable SSL connection + cert_file: "/etc/ssl/certs/db.crt" # SSL certificate file path + key_file: "/etc/ssl/private/db.key" # SSL private key file path +pools: # Connection pools configuration + read: 10 # Read connection pool size + write: 5 # Write connection pool size +metadata: # Optional metadata configuration + cache_ttl: "1h" # Cache time-to-live + sync_interval: "5m" # Sync interval +``` + +### Example 3: Using with selected code +Select a Go struct definition in your editor, then run: +``` +/yaml:docs +``` + +The command will generate YAML documentation from the selected struct. + +## Arguments +- $1: File path and struct name in format `file.go:StructName` (e.g., `pkg/api/types.go:MetricsConfig`), or selected code containing a Go struct definition +- $2: (Optional) Output file path where the generated YAML will be written (e.g., `config/example.yaml`) diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..bf58396 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,45 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:openshift-eng/ai-helpers:plugins/yaml", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "d9dcf744fc3f4d430b39b32a99b71b428d8be362", + "treeHash": "6e9854a784f639eb2d656cd86c9c85d712095e2f1d9266f24cc97a2eba43f6ca", + "generatedAt": "2025-11-28T10:27:30.517902Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "yaml", + "description": "Generate comprehensive YAML documentation from Go struct definitions with sensible default values", + "version": "0.0.1" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "78990069f2ffe5048edbc2e1c8c79ac969466862a5867014d21728d28891d629" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "277bca4cc62662eed06b9d383b5423e56402bef12880e36cf664a2aa5014f9f6" + }, + { + "path": "commands/docs.md", + "sha256": "30b41aac753a447f8e323d6854e69c31903d69167483671c4e1d3575a6abc872" + } + ], + "dirSha256": "6e9854a784f639eb2d656cd86c9c85d712095e2f1d9266f24cc97a2eba43f6ca" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file