CC Plans Lister Expert

Expert guidance for working with CC Plans Lister, a comprehensive Go CLI application that fetches and documents Clever Cloud API services.

What This Skill Does

This skill provides expert knowledge for developing, maintaining, and extending the CC Plans Lister tool. It covers the Go codebase architecture, API integration patterns, multi-format output generation (Markdown, TXT, CSV, PDF), CLI design with Cobra, and Clever Cloud API authentication workflows.

Instructions

When assisting with CC Plans Lister development tasks, follow these guidelines:

1. Understand the Project Architecture

Before making changes, familiarize yourself with the modular architecture:

**`cmd/cc-plans-lister/`** - Main entry point with Cobra CLI setup

**`internal/api/`** - Clever Cloud API client wrapper with OAuth authentication

**`internal/config/`** - Configuration management and environment variable validation

**`internal/formatters/`** - Interface-based output formatters (Markdown, Text, CSV, PDF)

**`pkg/clevercloud/`** - Public types and data structures

**`test/fixtures/`** - Test data and utilities

The application follows clean separation of concerns with interface-based design for extensibility.

2. Working with the API Client

The API client (`internal/api/client.go`) wraps the official Clever Cloud Go library:

Authentication requires `CLEVER_API_TOKEN` environment variable

Two main endpoints are consumed:

- `/v2/products/addonproviders` - Addon providers and pricing plans

- `/v2/products/instances` - Application types and instance flavors

Data is automatically sorted for consistent output

Use `GetAddonProviders()` and `GetProductInstances()` methods

When extending API functionality:

Maintain the wrapper pattern for consistency

Add sorting logic for new data types

Include proper error handling and validation

3. Adding or Modifying Output Formats

All formatters implement the `Formatter` interface. When creating a new formatter:

Implement the interface in `internal/formatters/`

Generate comprehensive reports with:

- Summary tables for quick reference

- Detailed plans with pricing and specifications

- Logical grouping by provider/application type

Add corresponding tests with fixture data

Existing formatters follow these patterns:

**Markdown**: Tables with headers, organized sections

**Text**: Tab-aligned columns using `text/tabwriter`

**CSV**: Standard CSV format with proper escaping

**PDF**: Structured document with font fallbacks

4. CLI Development with Cobra

The CLI interface uses Cobra framework conventions:

Define flags with `--format` and `--output` options

Validate inputs before execution

Provide clear error messages and help text

Handle both file output and stdout

Use persistent flags for cross-command options

When extending CLI functionality:

Follow Cobra best practices for command structure

Add validation at the CLI layer, not deep in business logic

Provide examples in help text

Consider backward compatibility

5. Configuration Management

Configuration is environment-based with validation:

`CLEVER_API_TOKEN` is required and validated at startup

Supported formats are whitelisted

Use `internal/config/config.go` for all configuration logic

Fail fast with clear error messages for missing/invalid config

When adding new configuration:

Document required environment variables

Provide sensible defaults where possible

Validate early in the application lifecycle

6. Testing Strategy

The project includes comprehensive unit tests:

Test configuration validation in `internal/config/`

Test formatter output against fixture data in `test/fixtures/`

Test API client initialization and error handling

Use `github.com/stretchr/testify` for assertions

Testing best practices:

Run `make test` or `go test ./...` before committing

Use `make coverage` to check test coverage

Add fixture data for new formatters or API responses

Mock external API calls in unit tests

7. Build and Development Workflow

Standard development commands:

```bash

Full development cycle (format, vet, test, build)

make dev

Individual steps

make fmt # Format code

make vet # Check for issues

make test # Run tests

make build # Build binary

Cross-platform builds

make build-all

Dependency management

make deps

go mod tidy

```

Always run `make dev` before submitting changes to ensure code quality.

8. Authentication and API Integration

Authentication flow:

1. Load `CLEVER_API_TOKEN` from environment

2. Validate token is non-empty

3. Create OAuth-authenticated client using official SDK

4. Make API requests with automatic authentication

When debugging authentication issues:

Verify token is set: `echo $CLEVER_API_TOKEN`

Check token validity with Clever Cloud console

Review API client error messages for auth failures

9. Common Extension Points

**Adding a new output format:**

1. Create new formatter in `internal/formatters/`

2. Implement `Formatter` interface

3. Add format to CLI validation

4. Create tests with fixture data

5. Update README with usage examples

**Adding new API endpoints:**

1. Add method to `internal/api/client.go`

2. Define types in `pkg/clevercloud/`

3. Implement sorting if needed

4. Update formatters to include new data

5. Add tests for new functionality

**Extending CLI options:**

1. Define flags in `cmd/cc-plans-lister/main.go`

2. Add validation in config layer

3. Pass options through to formatters or API client

4. Update help text and documentation

10. Known Considerations

**PDF Font Handling:**

PDF formatter includes fallback logic for missing fonts

Test environment uses minimal output when fonts unavailable

Production may require TTF fonts in `./fonts/` directory

**API Rate Limiting:**

Clever Cloud API may enforce rate limits

Consider retry logic for production deployments

**Memory Usage:**

Current implementation loads all data into memory

For very large datasets, consider streaming or pagination strategies

**Error Handling:**

Use clear, actionable error messages

Log errors appropriately for debugging

Fail fast on unrecoverable errors (e.g., auth failures)

Examples

**Generate Markdown documentation:**

```bash

export CLEVER_API_TOKEN="your_token_here"

./bin/cc-plans-lister --format=markdown --output=services.md

```

**Generate CSV for data analysis:**

```bash

./bin/cc-plans-lister --format=csv --output=services.csv

```

**Output PDF report:**

```bash

./bin/cc-plans-lister --format=pdf --output=services.pdf

```

**Development workflow:**

```bash

Make changes to code

make dev # Format, vet, test, build

./bin/cc-plans-lister --format=markdown # Test output

```

Constraints

Always validate user inputs at the CLI layer

Maintain interface-based design for formatters

Follow Go idioms and standard library conventions

Keep API client as a thin wrapper around official SDK

Ensure consistent sorting for reproducible output

Write tests for all new functionality

Document new features in README and help text

CC Plans Lister Expert

CC Plans Lister Expert

What This Skill Does

Instructions

1. Understand the Project Architecture

2. Working with the API Client

3. Adding or Modifying Output Formats

4. CLI Development with Cobra

5. Configuration Management

6. Testing Strategy

7. Build and Development Workflow

Full development cycle (format, vet, test, build)

Individual steps

Cross-platform builds

Dependency management

8. Authentication and API Integration

9. Common Extension Points

10. Known Considerations

Examples

Make changes to code

Constraints

Reviews (0)