Helm Values Manager

https://github.com/zipstack/helm-values-manager
Admin
A Helm plugin for managing value configurations across multiple environments with schema-driven...
Tokens:8,427
Snippets:63
Trust Score:7.8
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Documentation: Draft README.md

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This task specifies the drafting of a comprehensive `README.md` file for the project. It should include essential sections such as installation instructions (specifically for Helm plugin), quickstart guides for both vendor and customer workflows, security best practices, a command reference table, and a troubleshooting guide for common errors.

```prompt
Draft README.md with:
1. Installation: helm plugin install
2. Quickstart: vendor and customer workflows
3. Security best practices
4. Command reference table
5. Troubleshooting common errors
```

--------------------------------

### Using Helm Values Manager Shell Completion

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Examples demonstrating how to use tab completion for commands and subcommands after setup, and how to show the completion script without installation.

```bash
# Tab completion for commands
helm values-manager <TAB><TAB>

# Tab completion for subcommands
helm values-manager schema <TAB><TAB>
helm values-manager values <TAB><TAB>

# Show available completion script (without installing)
helm values-manager --show-completion zsh
```

--------------------------------

### Install Shell Completion for Standalone CLI

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Instructions to install shell completion for the standalone `helm-values-manager` CLI for various shells, including steps to source configuration.

```bash
# Install completion for your shell
helm-values-manager --install-completion zsh

# Restart your shell or source the configuration
source ~/.zshrc  # for zsh
source ~/.bashrc # for bash
```

--------------------------------

### Build Helm Values Manager from Source

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Instructions to clone the Helm Values Manager repository, navigate into the project directory, and install all necessary dependencies using `uv sync`.

```bash
git clone https://github.com/Zipstack/helm-values-manager
cd helm-values-manager
uv sync
```

--------------------------------

### Helm Values Manager CLI Commands

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Overview of `helm values-manager` commands for setting, getting, listing, and removing values, and interactive setup for environments.

```APIDOC
Command: helm values-manager values set KEY VALUE --env ENV
  Description: Set or update a value
Command: helm values-manager values set-secret KEY --env ENV
  Description: Configure secret (interactive)
Command: helm values-manager values get KEY --env ENV
  Description: Get specific value
Command: helm values-manager values list --env ENV
  Description: List all values for environment
Command: helm values-manager values remove KEY --env ENV
  Description: Remove a value
Command: helm values-manager values init --env ENV
  Description: Interactive setup for environment
```

--------------------------------

### Example Helm Values Manager Schema File (JSON)

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

An example `schema.json` file defining value keys, paths, types, descriptions, and validation rules for a Helm chart's configuration.

```json
{
  "version": "1.0",
  "values": [
    {
      "key": "database-host",
      "path": "database.host",
      "description": "PostgreSQL database hostname",
      "type": "string",
      "required": true,
      "default": "localhost"
    },
    {
      "key": "database-password",
      "path": "database.password",
      "description": "PostgreSQL password",
      "type": "string",
      "required": true,
      "sensitive": true
    },
    {
      "key": "replicas",
      "path": "deployment.replicas",
      "type": "number",
      "required": false,
      "default": 3
    }
  ]
}
```

--------------------------------

### Helm Values Manager install.sh Script

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Presents the `install.sh` script used for setting up the `helm-values-manager` plugin, including creating a Python virtual environment and installing dependencies.

```bash
#!/bin/bash
cd "$HELM_PLUGIN_DIR"
python3 -m venv venv
./venv/bin/pip install -r requirements.txt
```

--------------------------------

### Helm Values Manager Customer Workflow Example

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Demonstrates the customer's workflow for setting up values and secrets, generating environment-specific `values.yaml` files, and deploying Helm charts using `helm-values-manager`.

```bash
# Initial setup
helm values-manager values set database-host "prod-db.com" --env prod
helm values-manager values set-secret database-password --env prod

# Generate values for deployment
export PROD_DB_PASSWORD="actual-password"
helm values-manager generate --env prod > values-prod.yaml

# Deploy with any CD system
helm upgrade myapp ./chart -f values-prod.yaml
```

--------------------------------

### Example Helm Values Manager Environment Values File (JSON)

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

An example `values-{env}.json` file demonstrating how to define specific values for an environment, including referencing environment variables for sensitive data.

```json
{
  "database-host": "prod-db.example.com",
  "database-password": {
    "type": "env",
    "name": "PROD_DB_PASSWORD"
  },
  "replicas": 5
}
```

--------------------------------

### Install helm-values-manager as Standalone CLI

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Instructions for installing the helm-values-manager as a standalone command-line tool using pip, source, or uv. This method provides better shell completion support and is easier to manage.

```bash
pip install helm-values-manager
```

```bash
git clone https://github.com/Zipstack/helm-values-manager
cd helm-values-manager
pip install -e .
```

```bash
git clone https://github.com/Zipstack/helm-values-manager
cd helm-values-manager
uv sync
# CLI will be available as: uv run helm-values-manager
```

--------------------------------

### Install Shell Completion for Helm Plugin

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Instructions to install shell completion for the `helm values-manager` plugin for various shells (bash, zsh, fish, powershell), including steps to source configuration.

```bash
# Install completion for your shell (bash, zsh, fish, powershell)
helm values-manager --install-completion zsh

# Restart your shell or source the configuration
source ~/.zshrc  # for zsh
source ~/.bashrc # for bash
```

--------------------------------

### Helm Values Manager Vendor Workflow Example

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Illustrates the typical workflow for a chart vendor using `helm-values-manager` to initialize and define a schema for their Helm chart, preparing it for distribution.

```bash
# Create schema for chart
helm values-manager init
helm values-manager schema add  # Add each value definition

# Distribute schema.json alongside helm chart
```

--------------------------------

### Install helm-values-manager as Helm Plugin

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Instructions for installing helm-values-manager as a Helm plugin using the Helm plugin manager or from source. Note that the Helm plugin installation has limited shell completion support due to the plugin wrapper architecture.

```bash
helm plugin install https://github.com/Zipstack/helm-values-manager
```

```bash
git clone https://github.com/Zipstack/helm-values-manager
helm plugin install ./helm-values-manager
```

--------------------------------

### Implement `helm values-manager schema list` and `schema get` Commands

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This section outlines the implementation of schema query commands: `schema list` for tabular output of key properties, and `schema get <key>` for pretty-printed JSON of a specific schema entry. Both commands support a `--schema` flag and handle missing keys gracefully.

```APIDOC
Command: helm values-manager schema list
  Description: Displays a tabular output of all schema entries.
  Output Columns: key, path, type, required.
  Parameters:
    --schema <path>: Optional. Specifies a custom path for the schema.json file.

Command: helm values-manager schema get <key>
  Description: Displays the pretty-printed JSON details of a specific schema entry.
  Parameters:
    <key>: Required. The key of the schema entry to retrieve.
    --schema <path>: Optional. Specifies a custom path for the schema.json file.
  Behavior:
    - Handles missing keys gracefully.
```

--------------------------------

### CLI: Implement Interactive Environment Setup (values init)

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This task details the implementation of the `values init --env <env>` command. It describes loading schema, checking for unset values, and interactively prompting for each value (required then optional). Sensitive values use a `set-secret` workflow, while non-sensitive values undergo type validation. A summary of set/skipped values is required, along with a `--force` flag to disable prompts.

```prompt
Implement `values init --env <env>` command that:
1. Loads schema and checks for unset values in specified environment
2. For each unset value (required first, then optional):
   a. Show key, description, type, and required status
   b. Prompt: "Set value for [key]? (Y/n/skip)"
      - Y: Proceed to value input (normal/sensitive based on schema)
      - n: Skip this field
      - skip: Skip all remaining
3. For sensitive values:
   a. Use `set-secret` workflow (with type selection)
4. For non-sensitive values:
   a. Show current default (if exists)
   b. Prompt for value with type validation
5. After all fields:
   a. Show summary:
        "Set X values, skipped Y required values"
   b. List any unset required values
6. Add --force to disable prompts (use defaults where possible)
```

--------------------------------

### Install and Run Pre-commit Hooks for Code Quality

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Commands to install pre-commit hooks that enforce code quality standards like formatting, linting, and type checking. Includes an option to manually run all configured hooks.

```bash
uv run pre-commit install

uv run pre-commit run --all-files
```

--------------------------------

### Implement `helm values-manager values get`, `list`, and `remove` Commands

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This section describes the values query and deletion commands: `values get <key>` to print a masked value, `values list` for tabular output with value previews, and `values remove <key>` for key deletion with confirmation. All commands operate within a specified environment.

```APIDOC
Command: helm values-manager values get <key> --env <env>
  Description: Prints the value for a specified key in an environment, masking secrets.
  Parameters:
    <key>: Required. The key to retrieve.
    --env <env>: Required. The environment.

Command: helm values-manager values list --env <env>
  Description: Displays a tabular output of all values for a specified environment.
  Output Columns: key, value_preview.
  Parameters:
    --env <env>: Required. The environment.

Command: helm values-manager values remove <key> --env <env>
  Description: Removes a key from an environment-specific values file with confirmation.
  Parameters:
    <key>: Required. The key to remove.
    --env <env>: Required. The environment.
  Behavior:
    - Prompts for confirmation before removal.
```

--------------------------------

### Run Pytest Directly for Development and Debugging

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Alternative methods for running unit tests directly with pytest, suitable for rapid development and debugging. Includes options for running via `uv` or after installing development dependencies with `pip`.

```bash
uv run pytest

pip install -e .[dev]
pytest
```

--------------------------------

### Multi-Environment Helm Values Definition (values-prod.json)

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Example of a values file containing environment-specific configurations. It demonstrates how to define values for 'dev', 'staging', and 'prod' environments, including direct values and references to environment variables for sensitive data.

```json
{
  "dev": {
    "database-host": "dev-db.example.com",
    "database-password": {
      "type": "env",
      "name": "DEV_DB_PASSWORD"
    },
    "replicas": 1
  },
  "staging": {
    "database-host": "staging-db.example.com",
    "database-password": {
      "type": "env",
      "name": "STAGING_DB_PASSWORD"
    },
    "replicas": 2
  },
  "prod": {
    "database-host": "prod-db.example.com",
    "database-password": {
      "type": "env",
      "name": "PROD_DB_PASSWORD"
    },
    "replicas": 3,
    "ingress-hosts": ["app.example.com", "www.example.com"]
  }
}
```

--------------------------------

### helm-values-manager Schema Management Commands

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Reference for commands specifically designed for managing schema entries within the helm-values-manager, including adding, listing, getting, updating, and removing schema definitions.

```APIDOC
helm values-manager schema add:
  Description: Add new value to schema (interactive)
helm values-manager schema list:
  Description: List all schema entries
helm values-manager schema get KEY:
  Description: Show details of specific schema entry
  Parameters:
    KEY: The key of the schema entry to retrieve
helm values-manager schema update KEY:
  Description: Update existing schema entry
  Parameters:
    KEY: The key of the schema entry to update
helm values-manager schema remove KEY:
  Description: Remove entry from schema
  Parameters:
    KEY: The key of the schema entry to remove
```

--------------------------------

### CLI Commands for Helm Values Management

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Commands for setting, getting, listing, and removing environment-specific values in the `values-<env>.json` files. The `set-secret` command interactively configures environment variable references for sensitive values.

```bash
# Set or update a value
helm values-manager values set <key> <value> --env <env>

# Configure environment variable secret (interactive)
helm values-manager values set-secret <key> --env <env>

# Get specific value
helm values-manager values get <key> --env <env>

# List all values for an environment
helm values-manager values list --env <env>

# Remove a value
helm values-manager values remove <key> --env <env>
```

--------------------------------

### Implement `helm values-manager init` Command

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This section details the implementation requirements for the `helm values-manager init` command. It covers checking for existing schema files, prompting for overwrite confirmation, creating a minimal `schema.json`, using Typer for CLI, and supporting a `--schema` flag for custom paths.

```APIDOC
Command: helm values-manager init
  Description: Initializes the schema.json file for the Helm values manager.
  Parameters:
    --schema <path>: Optional. Specifies a custom path for the schema.json file.
    --force: Optional. Forces overwrite of an existing schema.json without confirmation.
  Behavior:
    - Checks for existing schema.json.
    - Prompts for overwrite confirmation if schema.json exists (unless --force is used).
    - Creates a minimal schema.json: {"version": "1.0", "values": []}.
    - Uses Typer for CLI implementation with clean error handling.
```

--------------------------------

### Customer Workflow: Set Values, Secrets, Generate, and Deploy

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Steps for chart users (customers) to set regular and secret values, generate a values.yaml file for a specific environment, and deploy their application using Helm.

```bash
helm values-manager values set database-host "prod-db.example.com" --env prod
```

```bash
helm values-manager values set-secret database-password --env prod
```

```bash
export PROD_DB_PASSWORD="actual-secret-password"
```

```bash
helm values-manager generate --env prod > values-prod.yaml
```

```bash
helm upgrade myapp ./chart -f values-prod.yaml
```

--------------------------------

### Run Tox Tests via uv for Environment Management

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Demonstrates how to execute Tox commands using `uv run`, leveraging `uv` for dependency and environment management during testing, specifically for linting and version-specific tests.

```bash
uv run tox -e lint
uv run tox -e py311
```

--------------------------------

### Create Python Project Structure for Helm Plugin

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This prompt outlines the initial scaffolding for a Python-based Helm plugin. It specifies the creation of `plugin.yaml`, `install.sh`, `requirements.txt`, `main.py`, and a `src/` directory with various empty modules, setting up the basic project layout.

```prompt
Create Python project structure for Helm plugin:
- plugin.yaml: Name "values-manager", points to virtualenv entrypoint
- install.sh: Creates venv, installs from requirements.txt
- requirements.txt: Includes typer==0.9.0, pyyaml==6.0
- main.py: CLI entrypoint using Typer
- src/ directory with:
  • __init__.py
  • schema.py (empty)
  • values.py (empty)
  • generator.py (empty)
  • validator.py (empty)
  • utils.py (empty)
```

--------------------------------

### Vendor Workflow: Initialize and Add Schema Definitions

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Steps for chart publishers (vendors) to initialize a schema.json file and interactively add new schema definitions for their Helm chart values.

```bash
helm values-manager init
```

```bash
helm values-manager schema add
```

--------------------------------

### Troubleshooting: Resolving Schema File Not Found Error

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Solution for the 'Schema file not found' error, suggesting either running `helm values-manager init` to create a schema file or using the `--schema` flag to specify its path.

```bash
helm values-manager init
```

--------------------------------

### Helm Values Manager Global CLI Options

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Common command-line options supported by all `helm values-manager` commands, including paths for schema and values files.

```APIDOC
Option: --schema PATH
  Description: Path to schema.json (default: ./schema.json)
Option: --values PATH
  Description: Base path for values files (default: ./values-{env}.json)
```

--------------------------------

### CLI: Organize Commands and Global Flags

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This task describes the desired organization of CLI commands into main groups such as `schema`, `values`, and `core`. It also defines global flags like `--schema` for the path to `schema.json` and `--values` for the base path of values files. The task emphasizes the need for clear help texts for all commands.

```prompt
Organize commands:
- Main groups: [schema, values, core]
- Global flags:
   • --schema: path to schema.json
   • --values: base path for values files
- Help texts for all commands
```

--------------------------------

### Helm Values Manager plugin.yaml Configuration

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Provides the configuration for the `plugin.yaml` file, defining the plugin's name, version, usage, description, and the command executed by Helm.

```yaml
name: "values-manager"
version: "0.1.0"
usage: "Manage Helm values across environments"
description: "Schema-driven Helm values management for multi-environment deployments"
command: "$HELM_PLUGIN_DIR/venv/bin/python $HELM_PLUGIN_DIR/main.py"
```

--------------------------------

### CLI: Implement Generation Command (generate)

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This task outlines the implementation of the `generate --env <env>` command. It requires running validation first and exiting on error. The process involves merging schema defaults with environment-specific values, resolving secrets from environment variables, building a nested YAML structure using dot paths, and outputting the result to stdout as valid YAML. Handling missing environment variables as an error is also specified.

```prompt
Implement `generate --env <env>`:
1. Run validation first (exit on error)
2. Merge process:
   a. Start with schema defaults
   b. Override with values from values-<env>.json
   c. Resolve secrets from environment variables
3. Build nested YAML structure using dot paths
4. Output to stdout as valid YAML
5. Handle missing env vars (error)
```

--------------------------------

### Project Workflow Sequence Diagram

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This Mermaid diagram illustrates the sequential workflow between a Vendor and an Agent, detailing the execution of various project tasks from initial scaffolding to final documentation. It provides a visual representation of the project's development progression.

```mermaid
sequenceDiagram
    Vendor->>+Agent: Run Task 1.1
    Agent-->>-Vendor: Project scaffold
    Vendor->>+Agent: Run Task 1.2
    Agent-->>-Vendor: init command
    Vendor->>+Agent: Run Task 2.1
    Agent-->>-Vendor: schema add
    ... continue sequentially ...
    Vendor->>+Agent: Run Task 6.2
    Agent-->>-Vendor: Documentation
```

--------------------------------

### helm-values-manager CLI Command Reference

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Reference for the main commands available in the helm-values-manager CLI, including initialization, validation, and generation of values.yaml. Note that commands can be prefixed with `helm-values-manager` (standalone) or `helm values-manager` (plugin).

```APIDOC
helm values-manager init:
  Description: Initialize a new schema.json file
helm values-manager validate:
  Description: Validate schema and values
  Parameters:
    --env ENV: Optional environment to validate against
helm values-manager generate:
  Description: Generate values.yaml for deployment
  Parameters:
    --env ENV: Required environment for generation
```

--------------------------------

### Implement `helm values-manager values set` Command

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This section describes the `values set` command, which allows setting a value for a specific key within an environment. It includes parsing values based on schema type, rejecting sensitive keys, creating environment-specific values files if missing, and supporting a custom values path.

```APIDOC
Command: helm values-manager values set <key> <value> --env <env>
  Description: Sets a value for a specified key in an environment-specific values file.
  Parameters:
    <key>: Required. The key to set.
    <value>: Required. The value to assign. Parsed based on schema type (JSON for arrays/objects).
    --env <env>: Required. The environment (e.g., 'dev', 'prod') for which to set the value.
    --values <path>: Optional. Specifies a custom path for the values-<env>.json file.
  Behavior:
    - Rejects setting sensitive keys directly (suggests `set-secret`).
    - Creates values-<env>.json if it does not exist.
```

--------------------------------

### Execute Tests with Tox for Consistent Environments

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Commands to run various test suites using Tox, ensuring consistent environments across different Python versions. Includes options for specific Python versions, linting, type checking, integration tests, and parallel execution.

```bash
tox

tox -e py311

tox -e lint

tox -e type-check

tox -e integration

tox -p
```

--------------------------------

### Troubleshooting: Adding Key to Schema or Checking Typos

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Solution for the 'Key not found in schema' error, advising to add the key to the schema first using `helm values-manager schema add` or to check for typos in the key name.

```bash
helm values-manager schema add
```

--------------------------------

### CLI Commands for Helm Values Schema Management

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Commands to initialize, add, update, remove, list, and retrieve specific entries within the `schema.json` file. The `add` command provides an interactive prompt for defining new schema entries.

```bash
# Create initial schema.json in current directory
helm values-manager init

# Add new value to schema (interactive)
helm values-manager schema add

# Update existing schema entry
helm values-manager schema update <key>

# Remove entry from schema
helm values-manager schema remove <key>

# List all schema entries
helm values-manager schema list

# Show details of specific schema entry
helm values-manager schema get <key>
```

--------------------------------

### Implement Interactive `helm values-manager schema add` Command

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This section describes the interactive `schema add` command, which prompts the user for various fields to define a new schema entry. It includes validation for key uniqueness, path format, and type-aware input for default values, appending the new entry to `schema.json`.

```APIDOC
Command: helm values-manager schema add
  Description: Interactively adds a new field definition to the schema.json.
  Prompts for:
    - key (string, unique, slug format)
    - path (string, dot-separated YAML path, alphanumeric + dots validation)
    - description (string)
    - type (choice: string, number, boolean, array, object)
    - required (boolean)
    - default (any, type-aware input)
    - sensitive (boolean)
  Behavior:
    - Validates path format.
    - Appends the new field definition to schema.json.
```

--------------------------------

### Testing: Write Pytest Unit Tests

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This task outlines the requirement to write comprehensive pytest unit tests for various components of the Helm Values Manager. Specific areas include schema CRUD operations, value setting/getting, path nesting logic, secret resolution, and validation scenarios. It also mentions using temporary files and monkeypatching for environment variables to ensure isolated and reliable testing.

```prompt
Write pytest tests for:
- Schema CRUD operations
- Value setting/getting
- Path nesting logic
- Secret resolution
- Validation scenarios
Use temporary files and monkeypatch for env vars
```

--------------------------------

### Helm Values Manager Plugin Directory Structure

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Outlines the file and directory structure of the `helm-values-manager` plugin, showing the organization of its main components and source code.

```APIDOC
helm-values-manager/
├── plugin.yaml
├── install.sh
├── requirements.txt
├── main.py
└── src/
    ├── __init__.py
    ├── schema.py
    ├── values.py
    ├── generator.py
    └── validator.py
```

--------------------------------

### Helm Values Manager Project File Structure

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Typical directory layout for a project using Helm Values Manager, showing the location of schema and environment-specific values files.

```text
project/
├── schema.json              # Value definitions (from vendor)
├── values-dev.json         # Customer's values for dev environment
├── values-staging.json     # Customer's values for staging
└── values-prod.json        # Customer's values for production
```

--------------------------------

### CLI: Implement Consistent Error Handling

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This task specifies the implementation of consistent error handling across the CLI. It requires a specific error format, listing all validation failures, and using rich formatting with fallback for non-TTY environments. The system should also suggest solutions where possible to aid users in resolving issues.

```prompt
Implement consistent errors:
- Format: "Error: [context] - [specific issue]"
- Validation: List all failures
- Use rich formatting with fallback for non-TTY
- Suggest solutions where possible
```

--------------------------------

### CLI Global Options for Helm Values Manager

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Global command-line options to specify custom paths for the `schema.json` and environment-specific values files, overriding the default locations.

```bash
--schema <path>    # Path to schema.json (default: ./schema.json)
--values <path>    # Path to values file (default: ./values-<env>.json)
```

--------------------------------

### CLI Commands for Core Helm Values Operations

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Essential commands for validating schema and values files, and generating the final `values.yaml` file for Helm deployment. Includes a placeholder for future diff functionality.

```bash
# Validate schema and all values files
helm values-manager validate

# Generate values.yaml (includes validation)
helm values-manager generate --env <env>

# Show schema changes between versions (future feature)
helm values-manager diff
```

--------------------------------

### CLI: Create Validation Command (validate)

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This task specifies the creation of a `validate` command to ensure data integrity. It involves checking schema integrity, validating values for type matching, required presence, and valid secret structures. The command must aggregate all errors before exiting and support environment-specific checks via the `--env` flag.

```prompt
Create `validate` command:
1. Check schema integrity (required fields, valid types)
2. Validate values:
   • Type matches
   • Required values present
   • Secret structures valid
3. Aggregate all errors before exit
4. Support --env for single environment check
```

--------------------------------

### Helm Values Manager Generate Command Overview

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Describes the `helm-values-manager generate` command, outlining its six-step process for validating schemas, resolving values including secrets, and producing a `values.yaml` file for deployment.

```APIDOC
1. Validates schema.json structure
2. Validates values file for the specified environment
3. Checks all required values are present
4. Verifies environment variables exist for secrets
5. Resolves all values including secrets
6. Generates values.yaml file
```

--------------------------------

### Troubleshooting: Setting Missing Required Value

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Solution for the 'Missing required value' error, providing the `helm values-manager values set` command to resolve it.

```bash
helm values-manager values set database-host "value" --env prod
```

--------------------------------

### Troubleshooting: Exporting Missing Environment Variable

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Solution for the 'Environment variable not found' error, providing the `export` command to set the missing variable.

```bash
export PROD_DB_PASSWORD="secret"
```

--------------------------------

### Implement `helm values-manager schema update` and `schema remove` Commands

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This section details the implementation of schema modification commands: `schema update <key>` for interactive updates with pre-filled current values, and `schema remove <key>` for removing an entry with confirmation. The `remove` command prevents deletion if the key is referenced in any values file.

```APIDOC
Command: helm values-manager schema update <key>
  Description: Interactively updates an existing schema entry.
  Parameters:
    <key>: Required. The key of the schema entry to update.
  Behavior:
    - Pre-fills current values for interactive editing.

Command: helm values-manager schema remove <key>
  Description: Removes a schema entry with confirmation.
  Parameters:
    <key>: Required. The key of the schema entry to remove.
    --force: Optional. Forces removal without confirmation.
  Behavior:
    - Prevents removal if the key exists in any values file (unless --force is used).
    - Prompts for confirmation before removal.
```

--------------------------------

### CLI: Add Confirmation for Existing Values (values set/set-secret)

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This task outlines the requirement to add confirmation prompts when overwriting existing keys for `values set` and `values set-secret` commands. It specifies showing current values (masked for secrets), prompting for overwrite, and aborting if not confirmed. A `--force` flag is also required to bypass confirmation.

```prompt
Update both `values set` and `values set-secret` commands to:
1. Check if the key already exists in the specified environment
2. If exists:
   a. Show current value (masked for secrets)
   b. Prompt: "Value already exists. Overwrite? [y/N]"
   c. Abort if not confirmed
3. For `values set-secret`:
   a. Show both current type and name if available
   b. Example prompt:
        "Key 'database-password' already set as env:PROD_DB_PASSWORD
         Overwrite? [y/N]"
4. Add --force flag to bypass confirmation
```

--------------------------------

### Running Validation for Helm Values Manager

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Command to run a comprehensive validation check for all values in a specific environment, identifying missing values, type mismatches, and other errors.

```bash
helm values-manager validate --env prod
```

--------------------------------

### Implement Interactive `helm values-manager values set-secret` Command

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This section details the interactive `values set-secret` command, designed for sensitive keys. It validates the key against the schema's sensitive flag, prompts for an environment variable name, and stores the reference as `{"type": "env", "name": "VAR"}` in the values file, with a warning if the environment variable doesn't exist.

```APIDOC
Command: helm values-manager values set-secret <key> --env <env>
  Description: Interactively sets a secret value for a specified sensitive key in an environment.
  Parameters:
    <key>: Required. The sensitive key to set.
    --env <env>: Required. The environment for which to set the secret.
  Prompts for:
    - Environment variable name.
  Behavior:
    - Validates that the key is marked as sensitive in the schema.
    - Stores the secret as {"type": "env", "name": "VAR_NAME"}.
    - Issues a warning if the specified environment variable does not exist.
```

--------------------------------

### Project File Structure

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Standard file organization for a helm-values-manager project, separating schema definitions from environment-specific value files.

```text
project/
├── schema.json                 # Value definitions (from vendor)
├── values-dev.json            # Customer's values for dev environment
├── values-staging.json        # Customer's values for staging
└── values-prod.json           # Customer's values for production
```

--------------------------------

### Secret Management: Exporting Environment Variable Before Generation

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Bash command demonstrating how to export a sensitive environment variable before running the `helm values-manager generate` command to ensure secrets are available.

```bash
export PROD_DB_PASSWORD="actual-secret"
helm values-manager generate --env prod
```

--------------------------------

### Helm Value Schema Definition (schema.json)

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Defines the structure and metadata for Helm values, including key, path, description, type, required status, default values, and sensitivity. This file is typically provided by the vendor.

```json
{
  "version": "1.0",
  "values": [
    {
      "key": "database-host",
      "path": "database.host",
      "description": "PostgreSQL database hostname",
      "type": "string",
      "required": true,
      "default": "localhost"
    },
    {
      "key": "database-password",
      "path": "database.password",
      "description": "PostgreSQL password",
      "type": "string",
      "required": true,
      "sensitive": true
    },
    {
      "key": "replicas",
      "path": "deployment.replicas",
      "type": "number",
      "required": false,
      "default": 3
    },
    {
      "key": "ingress-hosts",
      "path": "ingress.hosts",
      "type": "array",
      "required": false,
      "default": ["example.com"]
    },
    {
      "key": "resources",
      "path": "resources",
      "type": "object",
      "required": false,
      "default": {
        "requests": {"memory": "256Mi", "cpu": "100m"},
        "limits": {"memory": "512Mi", "cpu": "200m"}
      }
    }
  ]
}
```

--------------------------------

### Secret Management: Piping Generated Values Directly to Helm

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Bash command showing how to pipe the output of `helm values-manager generate` directly to `helm upgrade` to avoid writing sensitive data to disk.

```bash
helm values-manager generate --env prod | helm upgrade myapp ./chart -f -
```

--------------------------------

### Helm Values Manager Validate Command Overview

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Explains the `helm-values-manager validate` command, which reports all detected errors simultaneously, including missing values, type mismatches, invalid schema, and missing environment variables for secrets.

```APIDOC
Reports all errors at once:
- Missing required values
- Type mismatches
- Invalid schema structure
- Missing environment variables for secrets
```

--------------------------------

### Validate Helm Values Manager Configuration

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Commands to validate the Helm Values Manager configuration for all or specific environments, providing detailed error information for debugging.

```bash
helm values-manager validate
helm values-manager validate --env prod
```

--------------------------------

### Troubleshooting: Correcting Type Mismatch for Numeric Values

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

Solution for the 'Type mismatch' error, specifically for numeric values, demonstrating how to set them without quotes.

```bash
helm values-manager values set replicas 3 --env prod
```

--------------------------------

### Enhance `helm values-manager values set-secret` for Extensible Secret Types

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This enhancement updates the `values set-secret` command to support extensible secret types. It prompts the user to choose a secret type (currently 'env' with placeholders for 'vault', 'aws', 'azure'), and for 'env' type, prompts for the environment variable name. The secret is stored with type metadata, and the generator validates against supported types.

```APIDOC
Enhancement: helm values-manager values set-secret
  Description: Extends secret configuration to support multiple secret types.
  Behavior:
    - Prompts for secret type (e.g., 'env', 'vault', 'aws', 'azure').
    - For 'env' type:
      - Prompts for environment variable name.
      - Validates env var existence (warning only).
    - Stores secret with type metadata in values file:
      {
        "key": {
          "type": "env",
          "name": "ENV_VAR_NAME"
        }
      }
    - Generator validates and only supports 'env' type for now, errors on unsupported types.
```

--------------------------------

### Secret Management: Referencing Environment Variables in Values File

Source: https://github.com/zipstack/helm-values-manager/blob/main/README.md

JSON snippet showing how to configure a sensitive value to be sourced from an environment variable instead of being stored directly in the values file.

```json
{
  "database-password": {
    "type": "env",
    "name": "PROD_DB_PASSWORD"
  }
}
```

--------------------------------

### Helm Values Manager Error Message Format

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/spec.md

Illustrates the standardized format for error messages generated by `helm-values-manager`, providing clear and actionable feedback on validation failures.

```APIDOC
Error: Validation failed:
- Missing required value: database-host (env: prod)
- Type mismatch: replicas should be number, got string (env: dev)
- Environment variable not found: PROD_DB_PASSWORD
```

--------------------------------

### Enhance `helm values-manager schema update` for Default Value Removal

Source: https://github.com/zipstack/helm-values-manager/blob/main/guide/prompt_plan.md

This enhancement to the `schema update` command introduces an option to remove a default value from a schema entry during interactive editing. It clears the default and warns if the field is required but now lacks a default, ensuring backward compatibility.

```APIDOC
Enhancement: helm values-manager schema update <key>
  Description: Adds functionality to remove default values from schema entries.
  Behavior:
    - During interactive update, presents an "Remove default value" option.
    - If selected, clears the default value from the schema entry.
    - Warns if the field is required but now has no default value.
    - Preserves backward compatibility with existing schema format.
```
Tokens:
Raw