Instruction file imported from compozy/releasepr (.cursor/rules/global-config.mdc). Copyright stays with the author.

globs: *.go alwaysApply: false

Global Configuration Standards

Source of Truth & Precedence

Add a New Property (Existing Category)

2. Add struct field to typed config (required)

   • File: pkg/config/config.go
   • Add field under the respective *Config struct with tags:
     • koanf:"<name>" json:"<name>" yaml:"<name>" mapstructure:"<name>"
     • env:"<ENV_VAR>" when environment overrides are supported
     • validate:"..." when constraints apply
     • Use SensitiveString type or sensitive:"true" tag for secrets

3. Map from registry to typed struct (required)

   • File: pkg/config/config.go
   • Update corresponding build<Section>Config(registry *definition.Registry) to set the new field using getString/getInt/getBool/getDuration/getInt64/getStringSlice

4. Defaults map (usually automatic)

   • File: pkg/config/provider.go
   • Defaults come from Default() which is built from the registry; add to the section’s create<Section>Defaults only if special formatting is needed (e.g., .String() for durations)

5. Validation (if needed)

   • Prefer struct tag validation (validate:"...")
   • For cross-field rules, extend pkg/config/loader.go → validateCustom

6. Env var mapping (automatic, verify tags)

   • pkg/config/env_mappings.go auto-generates mappings from struct env:"..." tags
   • Ensure the new field has a correct env tag; verify with config diagnostics --verbose

7. CLI flag exposure (from registry)

   • Global flags are created from the registry: cli/helpers/global.go → AddGlobalFlags
   • If the property should be user-settable via CLI, add a CLIFlag and optional Shorthand in the registry entry

8. Help categorization (for better UX)

   • File: cli/helpers/flag_categories.go
   • Add the new flag name to an existing category’s Flags list; if not categorized it appears under “Other Flags”

9. Diagnostics and config show visibility

   • File: cli/cmd/config/config.go
   • Add the field to the appropriate flatten<Section>Config so it appears in table/JSON/YAML outputs with proper redaction

10. Sensitive output handling

• Use redactSensitive() for plain secrets and redactURL() for connection strings in flatteners
• Prefer SensitiveString for secrets to ensure automatic JSON redaction across outputs

11. Tests & validation

• Run make lint and make test
• Add/extend tests under pkg/config/*_test.go when adding validation or complex defaults

Create a New Category (Top-level Section)

2. Add to root Config

   • File: pkg/config/config.go
   • Add Section <Section>Config with koanf:"<section>" json:"<section>" yaml:"<section>" mapstructure:"<section>"

3. Register all fields in the registry

   • File: pkg/config/definition/schema.go
   • Create register<Section>Fields(registry *Registry)
   • Add to CreateRegistry()

4. Map defaults from registry to typed struct

   • File: pkg/config/config.go
   • Add build<Section>Config(registry *definition.Registry)

5. Default provider map

   • File: pkg/config/provider.go
   • Add create<Section>Defaults and include in add<Service|Infra|Core>Defaults

6. CLI output visibility

   • File: cli/cmd/config/config.go
   • Add flatten<Section>Config

7. CLI help categorization

   • File: cli/helpers/flag_categories.go
   • Add a category block or include flags in an existing category as appropriate

8. Validation

   • Use struct tags and extend validateCustom if cross-field constraints apply

9. Run make lint and make test

Naming & Conventions

Quick Example: Add a Property

1. Registry (schema.go)

registry.Register(&FieldDef{
    Path:    "runtime.max_concurrent_jobs",
    Default: 8,
    CLIFlag: "max-concurrent-jobs",
    EnvVar:  "RUNTIME_MAX_CONCURRENT_JOBS",
    Type:    reflect.TypeOf(0),
    Help:    "Maximum concurrent runtime jobs",
})

2. Typed config (config.go)

type RuntimeConfig struct {
    MaxConcurrentJobs int `koanf:"max_concurrent_jobs" json:"max_concurrent_jobs" yaml:"max_concurrent_jobs" mapstructure:"max_concurrent_jobs" env:"RUNTIME_MAX_CONCURRENT_JOBS" validate:"min=1"`
}

3. Builder (config.go)

func buildRuntimeConfig(reg *definition.Registry) RuntimeConfig {
    return RuntimeConfig{
        // ...existing fields
        MaxConcurrentJobs: getInt(reg, "runtime.max_concurrent_jobs"),
    }
}

4. CLI flatten (cli/cmd/config/config.go)

func flattenRuntimeConfig(cfg *config.Config, out map[string]string) {
    // ...existing fields
    out["runtime.max_concurrent_jobs"] = fmt.Sprintf("%d", cfg.Runtime.MaxConcurrentJobs)
}

5. Categorize flag (cli/helpers/flag_categories.go) Add "max-concurrent-jobs" under "Runtime & Performance".

6. Validate Run: make lint && make test

Verification

Notes on Sensitivity & Redaction

Where Things Happen

Final Gate