cli-jaw 0.1.6 → 0.1.8

package/skills_ref/terraform/provider-development/skills/new-terraform-provider/assets/main.go

@@ -1,40 +0,0 @@
-package main
-
-import (
-	"context"
-	"flag"
-	"log"
-
-	"example.org/terraform-provider-demo/internal/provider"
-	"github.com/hashicorp/terraform-plugin-framework/providerserver"
-)
-
-var (
-	// these will be set by the goreleaser configuration
-	// to appropriate values for the compiled binary.
-	version string = "dev"
-
-	// goreleaser can pass other information to the main package, such as the specific commit
-	// https://goreleaser.com/cookbooks/using-main.version/
-)
-
-func main() {
-	var debug bool
-
-	flag.BoolVar(&debug, "debug", false, "set to true to run the provider with support for debuggers like delve")
-	flag.Parse()
-
-	opts := providerserver.ServeOpts{
-		// TODO: Update this string with the published name of your provider.
-		// Also update the tfplugindocs generate command to either remove the
-		// -provider-name flag or set its value to the updated provider name.
-		Address: "registry.terraform.io/example/demo",
-		Debug:   debug,
-	}
-
-	err := providerserver.Serve(context.Background(), provider.New(version), opts)
-
-	if err != nil {
-		log.Fatal(err.Error())
-	}
-}

package/skills_ref/terraform/provider-development/skills/provider-actions/SKILL.md

@@ -1,478 +0,0 @@
----
-name: provider-actions
-description: Implement Terraform Provider actions using the Plugin Framework. Use when developing imperative operations that execute at lifecycle events (before/after create, update, destroy).
-metadata:
-  copyright: Copyright IBM Corp. 2026
-  version: "0.0.1"
----
-
-# Terraform Provider Actions Implementation Guide
-
-## Overview
-
-Terraform Actions enable imperative operations during the Terraform lifecycle. Actions are experimental features that allow performing provider operations at specific lifecycle events (before/after create, update, destroy).
-
-**References:**
-- [Terraform Plugin Framework](https://developer.hashicorp.com/terraform/plugin/framework)
-- [Terraform Actions RFC](https://github.com/hashicorp/terraform/blob/main/docs/plugin-protocol/actions.md)
-
-## File Structure
-
-Actions follow the standard service package structure:
-
-```
-internal/service/<service>/
-├── <action_name>_action.go       # Action implementation
-├── <action_name>_action_test.go  # Action tests
-└── service_package_gen.go        # Auto-generated service registration
-```
-
-Documentation structure:
-```
-website/docs/actions/
-└── <service>_<action_name>.html.markdown  # User-facing documentation
-```
-
-Changelog entry:
-```
-.changelog/
-└── <pr_number_or_description>.txt  # Release note entry
-```
-
-## Action Schema Definition
-
-Actions use the Terraform Plugin Framework with a standard schema pattern:
-
-```go
-func (a *actionType) Schema(ctx context.Context, req action.SchemaRequest, resp *action.SchemaResponse) {
-    resp.Schema = schema.Schema{
-        Attributes: map[string]schema.Attribute{
-            // Required configuration parameters
-            "resource_id": schema.StringAttribute{
-                Required:    true,
-                Description: "ID of the resource to operate on",
-            },
-            // Optional parameters with defaults
-            "timeout": schema.Int64Attribute{
-                Optional:    true,
-                Description: "Operation timeout in seconds",
-                Default:     int64default.StaticInt64(1800),
-                Computed:    true,
-            },
-        },
-    }
-}
-```
-
-### Common Schema Issues
-
-**Pay special attention to the schema definition** - common issues after a first draft:
-
-1. **Type Mismatches**
-   - Using `types.String` instead of `fwtypes.String` in model structs
-   - Using `types.StringType` instead of `fwtypes.StringType` in schema
-   - Mixing framework types with plugin-framework types
-
-2. **List/Map Element Types**
-   ```go
-   // WRONG - missing ElementType
-   "items": schema.ListAttribute{
-       Optional: true,
-   }
-
-   // CORRECT
-   "items": schema.ListAttribute{
-       Optional:    true,
-       ElementType: fwtypes.StringType,
-   }
-   ```
-
-3. **Computed vs Optional**
-   - Attributes with defaults must be both `Optional: true` and `Computed: true`
-   - Don't mark action inputs as `Computed` unless they have defaults
-
-4. **Validator Imports**
-   ```go
-   // Ensure proper imports
-   "github.com/hashicorp/terraform-plugin-framework-validators/int64validator"
-   "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator"
-   ```
-
-5. **Region/Provider Attribute**
-   - Use framework-provided region handling when available
-   - Don't manually define provider-specific config in schema if framework handles it
-
-6. **Nested Attributes**
-   - Use appropriate nested object types for complex structures
-   - Ensure nested types are properly defined
-
-### Schema Validation Checklist
-
-Before submitting, verify:
-- [ ] All attributes have descriptions
-- [ ] List/Map attributes have ElementType defined
-- [ ] Validators are imported and applied correctly
-- [ ] Model struct uses correct framework types
-- [ ] Optional attributes with defaults are marked Computed
-- [ ] Code compiles without type errors
-- [ ] Run `go build` to catch type mismatches
-
-## Action Invoke Method
-
-The Invoke method contains the action logic:
-
-```go
-func (a *actionType) Invoke(ctx context.Context, req action.InvokeRequest, resp *action.InvokeResponse) {
-    var data actionModel
-    resp.Diagnostics.Append(req.Config.Get(ctx, &data)...)
-
-    // Create provider client
-    conn := a.Meta().Client(ctx)
-
-    // Progress updates for long-running operations
-    resp.Progress.Set(ctx, "Starting operation...")
-
-    // Implement action logic with error handling
-    // Use context for timeout management
-    // Poll for completion if async operation
-
-    resp.Progress.Set(ctx, "Operation completed")
-}
-```
-
-## Key Implementation Requirements
-
-### 1. Progress Reporting
-
-- Use `resp.SendProgress(action.InvokeProgressEvent{...})` for real-time updates
-- Provide meaningful progress messages during long operations
-- Update progress at key milestones
-- Include elapsed time for long operations
-
-### 2. Timeout Management
-
-- Always include configurable timeout parameter (default: 1800s)
-- Use `context.WithTimeout()` for API calls
-- Handle timeout errors gracefully
-- Validate timeout ranges (typically 60-7200 seconds)
-
-### 3. Error Handling
-
-- Add diagnostics with `resp.Diagnostics.AddError()`
-- Provide clear error messages with context
-- Include API error details when relevant
-- Map provider error types to user-friendly messages
-- Document all possible error cases
-
-Example error handling:
-```go
-// Handle specific errors
-var notFound *types.ResourceNotFoundException
-if errors.As(err, &notFound) {
-    resp.Diagnostics.AddError(
-        "Resource Not Found",
-        fmt.Sprintf("Resource %s was not found", resourceID),
-    )
-    return
-}
-
-// Generic error handling
-resp.Diagnostics.AddError(
-    "Operation Failed",
-    fmt.Sprintf("Could not complete operation for %s: %s", resourceID, err),
-)
-```
-
-### 4. Provider SDK Integration
-
-- Use provider SDK clients from `a.Meta().<Service>Client(ctx)`
-- Handle pagination for list operations
-- Implement retry logic for transient failures
-- Use appropriate error types
-
-### 5. Parameter Validation
-
-- Use framework validators for input validation
-- Validate resource existence before operations
-- Check for conflicting parameters
-- Validate against provider naming requirements
-
-### 6. Polling and Waiting
-
-For operations that require waiting for completion:
-
-```go
-result, err := wait.WaitForStatus(ctx,
-    func(ctx context.Context) (wait.FetchResult[*ResourceType], error) {
-        // Fetch current status
-        resource, err := findResource(ctx, conn, id)
-        if err != nil {
-            return wait.FetchResult[*ResourceType]{}, err
-        }
-        return wait.FetchResult[*ResourceType]{
-            Status: wait.Status(resource.Status),
-            Value:  resource,
-        }, nil
-    },
-    wait.Options[*ResourceType]{
-        Timeout:            timeout,
-        Interval:           wait.FixedInterval(5 * time.Second),
-        SuccessStates:      []wait.Status{"AVAILABLE", "COMPLETED"},
-        TransitionalStates: []wait.Status{"CREATING", "PENDING"},
-        ProgressInterval:   30 * time.Second,
-        ProgressSink: func(fr wait.FetchResult[any], meta wait.ProgressMeta) {
-            resp.SendProgress(action.InvokeProgressEvent{
-                Message: fmt.Sprintf("Status: %s, Elapsed: %v", fr.Status, meta.Elapsed.Round(time.Second)),
-            })
-        },
-    },
-)
-```
-
-## Common Action Patterns
-
-### Batch Operations
-- Process items in configurable batches
-- Report progress per batch
-- Handle partial failures gracefully
-- Support prefix/filter parameters
-
-### Command Execution
-- Submit command and get operation ID
-- Poll for completion status
-- Retrieve and report output
-- Handle timeout during polling
-- Validate resources exist before execution
-
-### Service Invocation
-- Invoke service with parameters
-- Wait for completion (if synchronous)
-- Return output/results
-- Handle service-specific errors
-
-### Resource State Changes
-- Validate current state
-- Apply state change
-- Poll for target state
-- Handle transitional states
-
-### Async Job Submission
-- Submit job with configuration
-- Get job ID
-- Optionally wait for completion
-- Report job status
-
-## Action Triggers
-
-Actions are invoked via `action_trigger` lifecycle blocks in Terraform configurations:
-
-```hcl
-action "provider_service_action" "name" {
-  config {
-    parameter = value
-  }
-}
-
-resource "terraform_data" "trigger" {
-  lifecycle {
-    action_trigger {
-      events  = [after_create]
-      actions = [action.provider_service_action.name]
-    }
-  }
-}
-```
-
-### Available Trigger Events
-
-**Terraform 1.14.0 Supported Events:**
-- `before_create` - Before resource creation
-- `after_create` - After resource creation
-- `before_update` - Before resource update
-- `after_update` - After resource update
-
-**Not Supported in Terraform 1.14.0:**
-- `before_destroy` - Not available (will cause validation error)
-- `after_destroy` - Not available (will cause validation error)
-
-## Testing Actions
-
-### Acceptance Tests
-
-- Test action invocation with valid parameters
-- Test timeout scenarios
-- Test error conditions
-- Verify provider state changes
-- Test progress reporting
-- Test with custom parameters
-- Test trigger-based invocation
-
-### Test Pattern
-
-```go
-func TestAccServiceAction_basic(t *testing.T) {
-    ctx := acctest.Context(t)
-
-    resource.ParallelTest(t, resource.TestCase{
-        PreCheck:                 func() { acctest.PreCheck(ctx, t) },
-        ProtoV5ProviderFactories: acctest.ProtoV5ProviderFactories,
-        TerraformVersionChecks: []tfversion.TerraformVersionCheck{
-            tfversion.SkipBelow(tfversion.Version1_14_0),
-        },
-        Steps: []resource.TestStep{
-            {
-                Config: testAccActionConfig_basic(),
-                Check: resource.ComposeTestCheckFunc(
-                    testAccCheckResourceExists(ctx, "provider_resource.test"),
-                ),
-            },
-        },
-    })
-}
-```
-
-### Test Cleanup with Sweep Functions
-
-Add sweep functions to clean up test resources:
-
-```go
-func sweepResources(region string) error {
-    ctx := context.Background()
-    client := /* get client for region */
-
-    input := &service.ListInput{
-        // Filter for test resources
-    }
-
-    var sweeperErrs *multierror.Error
-
-    pages := service.NewListPaginator(client, input)
-    for pages.HasMorePages() {
-        page, err := pages.NextPage(ctx)
-        if err != nil {
-            sweeperErrs = multierror.Append(sweeperErrs, err)
-            continue
-        }
-
-        for _, item := range page.Items {
-            id := item.Id
-
-            // Skip non-test resources
-            if !strings.HasPrefix(id, "tf-acc-test") {
-                continue
-            }
-
-            _, err := client.Delete(ctx, &service.DeleteInput{
-                Id: id,
-            })
-            if err != nil {
-                sweeperErrs = multierror.Append(sweeperErrs, err)
-            }
-        }
-    }
-
-    return sweeperErrs.ErrorOrNil()
-}
-```
-
-### Testing Best Practices
-
-**Service-Specific Prerequisites**
-- Always check for service-specific prerequisites that must be met before actions can succeed
-- Document prerequisites in action documentation and test configurations
-
-**Error Pattern Matching**
-- Terraform wraps action errors with additional context
-- Use flexible regex patterns: `regexache.MustCompile(\`(?s)Error Title.*key phrase\`)`
-
-**Test Patterns Not Applicable to Actions**
-1. Actions trigger on lifecycle events, not config reapplication
-2. Before/After Destroy Tests: Not supported in Terraform 1.14.0
-
-### Running Tests
-
-Compile test to check for errors:
-```bash
-go test -c -o /dev/null ./internal/service/<service>
-```
-
-Run specific action tests:
-```bash
-TF_ACC=1 go test ./internal/service/<service> -run TestAccServiceAction_ -v
-```
-
-Run sweep to clean up test resources:
-```bash
-TF_ACC=1 go test ./internal/service/<service> -sweep=<region> -v
-```
-
-## Documentation Standards
-
-Each action documentation file must include:
-
-1. **Front Matter**
-   ```yaml
-   ---
-   subcategory: "Service Name"
-   layout: "provider"
-   page_title: "Provider: provider_service_action"
-   description: |-
-     Brief description of what the action does.
-   ---
-   ```
-
-2. **Header with Warnings**
-   - Beta/Alpha notice about experimental status
-   - Warning about potential unintended consequences
-   - Link to provider documentation
-
-3. **Example Usage**
-   - Basic usage example
-   - Advanced usage with all options
-   - Trigger-based example with `terraform_data`
-   - Real-world use case examples
-
-4. **Argument Reference**
-   - List all required and optional arguments
-   - Include descriptions and defaults
-   - Note any validation rules
-
-5. **Documentation Linting**
-   - Run `terrafmt fmt` before submission
-   - Verify with `terrafmt diff`
-
-## Changelog Entry Format
-
-Create a changelog entry in `.changelog/` directory:
-
-```
-.changelog/<pr_number_or_description>.txt
-```
-
-Content format:
-```release-note:new-action
-action/provider_service_action: Brief description of the action
-```
-
-## Pre-Submission Checklist
-
-Before submitting your action implementation:
-
-- [ ] Code compiles: `go build -o /dev/null .`
-- [ ] Tests compile: `go test -c -o /dev/null ./internal/service/<service>`
-- [ ] Code formatted: `make fmt`
-- [ ] Documentation formatted: `terrafmt fmt website/docs/actions/<action>.html.markdown`
-- [ ] Changelog entry created
-- [ ] Schema uses correct types
-- [ ] All List/Map attributes have ElementType
-- [ ] Progress updates implemented for long operations
-- [ ] Error messages include context and resource identifiers
-- [ ] Documentation includes multiple examples
-- [ ] Documentation includes prerequisites and warnings
-
-## References
-
-- [Terraform Plugin Framework Documentation](https://developer.hashicorp.com/terraform/plugin/framework)
-- [Terraform Provider Development](https://developer.hashicorp.com/terraform/plugin)
-- [terraform-plugin-framework GitHub](https://github.com/hashicorp/terraform-plugin-framework)
-- [terraform-plugin-testing](https://github.com/hashicorp/terraform-plugin-testing)