cloudposse/atmos v1.193.0-rc.0

on GitHub

why

• Identified coverage gaps during code review of #1504
• These edge cases ensure proper handling of URIs that pass isGitURI() but are actually archives or special types
• Malformed YAML tests ensure error paths are properly covered for config validation

references

• Builds on #1504 (fix: normalize legacy triple-slash vendor URIs for go-getter compatibility)
• Addresses coverage improvement opportunities identified during PR review

Background & Root Cause

This issue was introduced in Atmos v1.189.0 when go-getter was updated from v1.7.8 to v1.7.9 to address security vulnerability CVE-2025-8959. The security fix in go-getter v1.7.9 changed how subdirectory paths are handled in Git URLs, breaking the triple-slash pattern that was previously documented in Atmos examples.

Timeline:

• Atmos v1.180.0 - Last known working version with triple-slash patterns
• Atmos v1.189.0 - go-getter updated to v1.7.9 (commit 4c89983), breaking triple-slash patterns
• Atmos v1.190.0 - Issue reported by users upgrading from v1.180.0

The Problem:

Users following Atmos documentation were using vendor configurations like:

sources:
  - component: s3-bucket
    source: "github.com/terraform-aws-modules/terraform-aws-s3-bucket.git///?ref={{.Version}}"
    included_paths:
      - "**/*.tf"
      - "**/modules/**"

The triple-slash pattern (///) was interpreted by go-getter v1.7.9+ as attempting to access a subdirectory path starting with /, which resulted in:

• Zero files being downloaded
• Empty directories being created
• No error messages (silent failure)

Solution

This PR adds a normalizeVendorURI() function that detects and converts legacy triple-slash patterns:

• repo.git///?ref=v1.0 → repo.git?ref=v1.0 (empty subdirectory)
• repo.git///path?ref=v1.0 → repo.git//path?ref=v1.0 (with subdirectory)

The normalization is applied transparently to all vendor URIs, ensuring backward compatibility while maintaining the security improvements from go-getter v1.7.9.

Test plan

• Added comprehensive test cases in internal/exec/vendor_issue_dev3639_test.go
• Test cases verify vendor pull works with glob patterns and triple-slash URIs
• Tests pass with the normalization fix applied
• Verified backward compatibility with existing vendor configurations

Referenences

• Fixes DEV-3639
• closes #1500

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Vendor pull now normalizes vendor URLs (triple-slash, root vs subpath, Git URL handling).
  • CLI now honors base-path, config, and config-path flags earlier for more reliable config resolution.

• Bug Fixes

  • Import logging now sanitizes credentials and query parameters.
  • Environment variable handling consistently stringifies values.
  • Debug output shows more consistent/normalized URL forms.

• Documentation

  • New Vendor URL Syntax docs, cross-references, and default --logs-level updated to Warning.

• Tests

  • Extensive new unit, integration, and snapshot tests covering vendor pull, URI normalization, sanitization, and path handling.

why

• Makes performance analysis accessible to all developers without specialized profiling tools
• Enables quick identification of slow operations during stack processing
• Provides actionable insights for optimization efforts with P95 latency metrics
• Reduces friction in performance debugging workflow
• Offers flexible profiling approaches for different use cases (quick analysis vs deep profiling)

Performance Heatmap Feature

Atmos now includes built-in performance tracking that shows you exactly which operations are taking the longest time. This feature provides real-time visibility into function execution times with interactive visualization modes.

Quick Start

Run any Atmos command with the --heatmap flag:

atmos describe stacks --heatmap

Real Performance Analysis Example

Here's actual output from atmos describe stacks --heatmap:

Bar Chart View (Press 1 in interactive mode):

Performance Output

=== Atmos Performance Summary ===
Elapsed: 69.042791ms  Functions: 42  Calls: 5980
Function                                            Count      Total        Avg        Max      P95
exec.ProcessYAMLConfigFileWithContext                  52   18.305ms      352µs     3.61ms  3.495ms
exec.ValidateStacks                                     1    9.893ms    9.893ms    9.893ms  9.895ms
utils.processCustomTags                              1024    7.919ms        7µs      808µs     13µs
exec.FindStacksMap                                      2    7.038ms    3.519ms    6.463ms  6.463ms
exec.ProcessYAMLConfigFiles                             2    6.857ms    3.428ms    6.286ms  6.287ms
exec.Execute                                            1     6.43ms     6.43ms     6.43ms  6.431ms
merge.MergeWithOptions                                746    4.649ms        6µs      423µs     19µs
utils.GetHighlightedYAML                                1    4.171ms    4.171ms    4.171ms  4.171ms
utils.HighlightCodeWithConfig                           1    3.787ms    3.787ms    3.787ms  3.787ms
merge.MergeWithContext                                356    3.614ms       10µs      423µs     51µs
merge.MergeWithOptionsAndContext                      356    3.521ms        9µs      423µs     50µs
exec.ProcessImportSection                              52    3.346ms       64µs      872µs    784µs
utils.ConvertToYAML                                   177    3.287ms       18µs      660µs     71µs
exec.ProcessStackConfig                                12     1.69ms      140µs      265µs    192µs
merge.Merge                                           390    1.478ms        3µs       67µs     19µs
utils.GetGlobMatches                                   48    1.141ms       23µs      210µs    168µs
utils.JoinPaths                                         5     1.13ms      226µs    1.128ms  1.128ms
exec.getEmbeddedSchemaPath                              1      784µs      784µs      784µs    784µs
config.FindAllStackConfigsInPaths                       1      783µs      783µs      783µs    783µs
exec.ProcessYAMLConfigFile                              8      750µs       93µs      201µs    201µs
exec.ExecuteDescribeStacks                              1      682µs      682µs      682µs    682µs
exec.GetFileContent                                    52      446µs        8µs      161µs     25µs
utils.SliceContainsString                            2456      127µs          0        5µs        -
utils.PathMatch                                        32       57µs        1µs        6µs      1µs
utils.ResolveRelativePath                              32       43µs        1µs       36µs        -
exec.ProcessCommandLineArgs                             1       14µs       14µs       14µs     14µs
utils.EnsureDir                                         1       12µs       12µs       12µs     12µs
exec.BuildTerraformWorkspace                           10       10µs        1µs        9µs      9µs
exec.processSettingsIntegrationsGithub                 30       10µs          0        1µs        -
exec.createComponentStackMap                            2        7µs        3µs        7µs      7µs
utils.IsTemplateFile                                   52        5µs          0        1µs        -
exec.FindComponentsDerivedFromBaseComponents           10        3µs          0          0        -
utils.UniqueStrings                                    38        3µs          0          0        -
utils.getLexer                                          1        3µs        3µs        3µs      3µs
utils.GetHighlightSettings                              2        2µs        1µs        2µs      2µs
utils.IsDirectory                                       1        2µs        2µs        2µs      2µs
utils.JoinPath                                         11        2µs          0          0        -
config.processEnvVars                                   2        1µs          0          0        -

Visualization Modes

The interactive TUI supports three visualization modes:

• Press 1: Bar Chart - Color gradient from red (slow) to green (fast) showing relative execution times
• Press 2: Sparklines - Visual trend lines for each function
• Press 3: Table View - Detailed metrics with Count/Total/Avg/Max/P95 (top 50 functions by total time)

Navigation & Controls

• ↑/↓ or k/j: Navigate through rows (wraparound enabled)
• 1-3: Switch visualization modes
• q/esc: Exit and return to terminal

CLI Flags

All flag descriptions now match atmos --help output exactly:

• --heatmap: Show performance heatmap visualization after command execution (includes P95 latency) (default: false)
• --heatmap-mode: Heatmap visualization mode: bar, sparkline, table (press 1-3 to switch in TUI) (default: bar)

Comparison with Traditional Profiling

Implementation Details

• Added defer perf.Track() instrumentation to 150+ functions across critical paths
• Implemented HDR histogram for accurate P95 latency calculations
• Created Bubble Tea TUI with multiple visualization modes and vim-style navigation
• Added snapshot filtering to prevent zero-time function display
• Implemented visual display limits (top 25 for bar/sparkline, top 50 for table view)
• Added package prefix naming convention for clear function identification
• Consolidated profiling documentation into unified /docs/troubleshoot/profiling.mdx
• Synced all CLI flag descriptions with help text for consistency

Testing

✅ All tests passing with coverage >80%
✅ Comprehensive test suite for heatmap TUI (17 test functions)
✅ GitHub utils tests (11 test functions)
✅ Enhanced pro.go tests (11 additional test functions)
✅ Linter checks passing (0 issues)
✅ Website builds successfully with no broken links
✅ Performance tracking verified with real Atmos workflows

Documentation

• Comprehensive profiling guide: /docs/troubleshoot/profiling.mdx
  • Performance Heatmap section (quick analysis, interactive TUI)
  • pprof Profiling section (deep analysis, server/file modes)
  • Choosing the Right Tool comparison
  • Best practices and troubleshooting
• Developer guidelines: Updated CLAUDE.md with mandatory performance tracking patterns
• Real performance examples with screenshots and actual command output
• Accurate feature descriptions: Removed misleading claims (sorting, unlimited rows)
• Complete navigation documentation: All keyboard shortcuts documented

Key Documentation Updates

1. ✅ Consolidated separate performance-heatmap.mdx into unified profiling.mdx
2. ✅ Synced all CLI flag descriptions to exactly match atmos --help output
3. ✅ Clarified Table Mode shows top 50 rows (not unlimited)
4. ✅ Removed claim about sortable columns (not implemented)
5. ✅ Added complete keyboard navigation documentation (↑/↓, k/j)
6. ✅ Fixed broken link from /troubleshoot/logging to /troubleshoot/debugging

Summary by CodeRabbit

• New Features

  • Added a post-run performance heatmap (bar/sparkline/table) with P95 metrics and interactive TUI when a TTY is available; selectable via new global flags --heatmap and --heatmap-mode.

• Telemetry

  • Global performance tracking enabled across commands to collect timing/latency metrics for heatmap and diagnostics.

• Documentation

  • Consolidated profiling documentation into comprehensive guide covering both heatmap (quick analysis) and pprof (deep profiling) approaches
  • Synced all CLI flag descriptions with help text
  • Added complete keyboard navigation documentation
  • Fixed broken links and removed misleading claims

• Chores

  • Dependency updates (including HDR histogram library and various SDK bumps).

• Tests

  • Extensive tests for heatmap rendering, CLI flags, and performance-tracking behaviors
  • Added comprehensive test coverage for terraform_generate_backends, github_utils, and pro features
  • All tests passing with >80% coverage

why

• Template files with .yaml.tmpl and .yml.tmpl extensions were not being processed correctly
• Component configurations using these template extensions were failing to render properly
• Users need consistent template processing regardless of YAML file extension preference (.yaml vs .yml)
• Template context was not being handled properly for all YAML template file variations
• Improves developer experience by supporting common YAML template file naming conventions

references

• Enhances template processing capabilities for YAML template files
• Supports both .yaml.tmpl and .yml.tmpl file extension patterns
• Improves consistency in template rendering across different file naming conventions

Summary by CodeRabbit

• New Features

  • Imported files with .yaml.tmpl / .yml.tmpl are automatically detected and processed as templates.
  • Utility added to detect template-file extensions.

• Tests

  • Extensive unit and benchmark tests for template rendering, error cases, Sprig functions, import handling, skip behavior, and performance.
  • End-to-end tests confirm template detection and processing during stack operations.

• Chores

  • Test invocation adjusted to reduce verbose output.
  • Snapshot updated to include a Git-repo warning message.

why

• GitHub Dependabot reported 17 open vulnerabilities in website dependencies
• Initial fix with `npm audit fix` reduced vulnerabilities from 17 to 3
• Remaining 3 high-severity vulnerabilities were in @grnet/docusaurus-terminology (rollup < 2.79.2 XSS)
• No fix available from package maintainer - required custom implementation
• All vulnerabilities were in documentation site only, not affecting core Atmos CLI

Phase 1: npm audit fix (14 vulnerabilities resolved)

Fixed through automatic dependency updates:

• image-size: Updated to 1.2.1+ (high severity)
• @babel/helpers, @babel/runtime, @babel/runtime-corejs3: Updated to 7.26.10+ (3 moderate)
• prismjs: Updated to 1.30.0+ (moderate)
• dompurify: Updated to 3.2.4+ (moderate)
• katex: Updated to 0.16.21+ (moderate)
• estree-util-value-to-estree: Updated to 3.3.3+ (moderate)
• on-headers: Updated to 1.1.0+ (low)
• brace-expansion: Updated to 1.1.12+ (low)
• webpack-dev-server, http-proxy-middleware: Transitive updates (4 moderate)

Phase 2: Glossary tooltips implementation (3 vulnerabilities resolved)

Replaced vulnerable package

Removed @grnet/docusaurus-terminology and all dependencies:

• @grnet/docusaurus-terminology
• @grnet/docusaurus-term-preview
• @grnet/webpack-terms-loader
• @grnet/webpack-glossary-loader
• @grnet/webpack-terms-replace-loader
• @grnet/terminology-store

Custom implementation components

1. Glossary Tooltips Plugin (`website/plugins/glossary-tooltips/`)

• Scans `docs/glossary/` for term files during build
• Extracts frontmatter (id, title, hoverText) from each term markdown file
• Generates `glossary.json` with term metadata
• Custom webpack loader transforms term links into React components

2. Term Component (`website/src/components/Term.tsx`)

• Displays term as link with hover tooltip
• Fetches definitions from glossary.json
• Uses Docusaurus Link for navigation
• No external dependencies

3. CSS Tooltips (`website/src/components/Term.css`)

• Pure CSS tooltips (no JavaScript libraries)
• Responsive design with mobile support
• Dark mode compatible
• Smooth fade-in animation

Backward compatibility

✅ All 26 glossary term files unchanged
✅ All 29 term link references work unchanged
✅ Existing Glossary.tsx component works with new JSON format
✅ No changes needed to documentation content

Final Results

Testing

• ✅ npm audit shows 0 vulnerabilities
• ✅ Website builds successfully without errors
• ✅ Glossary.json generated with 25 terms (26 files, 1 index)
• ✅ All term links transform correctly
• ✅ No content changes required

Security Impact

• Risk Level: LOW (documentation website only, not core CLI)
• Blast Radius: Documentation site glossary feature
• Fix Status: ✅ Complete - zero vulnerabilities remaining

references

• Resolves all Dependabot security alerts
• Dependabot alerts: https://github.com/cloudposse/atmos/security/dependabot

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

Summary by CodeRabbit

• New Features

  • Glossary terms show hover/focus tooltips across docs with responsive, theme-aware styling.
  • Term links reliably navigate to glossary entries and display inline hover summaries.

• Chores

  • Replaced external glossary dependency with an in-repo glossary tooling pipeline that emits a static glossary file.
  • Added frontmatter parsing dependency and ignored generated glossary output.
  • Added CI validation for codecov configuration and adjusted coverage path settings.

why

• The regression was introduced in PR #1493 which refactored the include processing logic
• When local files couldn't be found, the code was falling back to go-getter which failed with "relative paths require a module with a pwd"
• This particularly affected describe affected when run with --repo-path flag

references

• Closes #1520
• Regression introduced in #1493

Summary by CodeRabbit

• Bug Fixes

  • Local YAML !include now reliably resolves local files before attempting remote fetch; clearer error messages when includes are missing and fewer false remote detections.
  • Adjusted error message wording for certain merge/list error paths.

• New Features

  • Improved cross-platform sandbox copying with layered fallbacks for more reliable file/directory replication and artifact exclusion.
  • Tests and harness now support named and isolated sandboxes for more flexible test setups.

• Tests

  • Added comprehensive tests covering include resolution, remote-detection heuristics, missing-file handling, and copy utilities.

• Chores

  • Added a public error identifier for invalid log level.

why

• LLMs need structured documentation: The llms.txt standard (https://llmstxt.org/) provides a standardized way for LLMs to efficiently understand website documentation
• Address context window limitations: Instead of crawling entire websites, LLMs can access curated, structured content optimized for their understanding
• Improve AI assistance: Tools like Claude, ChatGPT, and other AI assistants can provide better answers about Atmos by referencing these files
• Follow emerging standards: Similar to robots.txt for search engines, llms.txt is becoming a standard for AI-friendly documentation
• Better developer experience: Users asking AI assistants about Atmos will get more accurate, up-to-date responses

references

• https://llmstxt.org/ - llms.txt standard specification
• https://github.com/rachfop/docusaurus-plugin-llms - Docusaurus plugin used
• Live files will be available at:
  • https://atmos.tools/llms.txt
  • https://atmos.tools/llms-full.txt

Summary by CodeRabbit

• New Features
  • Generates machine-readable documentation artifacts during site builds and publishes them with the site.
  • Adds a post-build cleanup step to remove or mask import statements in generated artifacts for clearer output.
• Chores
  • Adds a new site dependency to support artifact generation.
  • Introduces a postbuild script to copy artifacts and run cleanup.
  • Updates ignore patterns to exclude generated artifacts from version control.

• Fixed path duplication bug when using absolute paths in component configurations
• Added JoinPath utility function for consistent path joining without filesystem checks
• Refactored all path joining logic to use the single JoinPath utility, eliminating code duplication
• Fixed handling of absolute paths in metadata.component field
• Added Windows-specific test cases for Windows absolute paths
• Created comprehensive test suite covering 28 edge case scenarios for path handling

why

• GitHub Actions pipelines were failing with duplicated paths: /home/runner/_work/infrastructure/infrastructure/home/runner/_work/infrastructure/infrastructure/atmos/components/terraform
• When component paths are configured with absolute paths, filepath.Join() on Unix systems doesn't handle two absolute paths correctly, causing path duplication
• This regression was introduced in PR #1512 (included in v1.192.0) which added the GetComponentPath function without proper handling of absolute paths
• Code duplication between atmosConfigAbsolutePaths() and buildComponentPath() could lead to inconsistent behavior

references

• Regression introduced in PR #1512: test: fix test isolation issues and improve sandbox testing
  • This PR added pkg/utils/component_path_utils.go with the GetComponentPath function
  • The function didn't account for components that are already absolute paths
• User impact: Users upgrading from v1.191.0 to v1.192.0 experienced broken GitHub Actions pipelines when using absolute paths in their configurations

Bug Details

The issue occurs when:

1. atmos.base_path is set to an absolute path (e.g., /home/runner/_work/infrastructure/infrastructure)
2. components.terraform.base_path or the component itself is also set to an absolute path
3. On Unix systems, filepath.Join() with two absolute paths creates unexpected results

Fix Implementation

pkg/utils/file_utils.go

Added JoinPath utility function for consistent path handling:

// JoinPath joins two paths handling absolute paths correctly.
// If the second path is absolute, it returns the second path.
// Otherwise, it joins the paths and returns the absolute path.
// This function does NOT check if the path exists on the filesystem.
func JoinPath(basePath string, providedPath string) string {
    if filepath.IsAbs(providedPath) {
        return providedPath
    }
    return filepath.Join(basePath, providedPath)
}

Refactored Path Joining

• pkg/config/config.go: atmosConfigAbsolutePaths() now uses JoinPath for all component base paths
• pkg/utils/component_path_utils.go: buildComponentPath() now uses JoinPath for consistent behavior
• Eliminated duplicate logic that was handling absolute path checks in multiple places

Design Decisions

Why no filesystem checks in JoinPath:

• The original JoinAbsolutePathWithPath performs os.Stat checks which fail in unit tests with mock paths
• Path construction logic should be separate from filesystem validation
• This follows the Single Responsibility Principle - path manipulation vs. path validation
• Filesystem checks can be performed by callers when needed, not during path construction

Test Coverage

Created comprehensive test files:

• pkg/config/config_path_absolute_test.go - Tests InitCliConfig absolute path handling
• pkg/config/config_path_comprehensive_edge_cases_test.go - 28 edge case scenarios including Windows paths
• pkg/utils/component_path_absolute_test.go - Tests GetComponentPath with absolute paths
• internal/exec/stack_metadata_component_path_test.go - Tests metadata.component field handling
• internal/exec/terraform_component_path_utils_test.go - Tests constructTerraformComponentWorkingDir

All tests pass successfully on Linux, macOS, and Windows, confirming the fix resolves the path duplication issue while maintaining backward compatibility with relative path configurations.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added exported path-joining and absolute-path resolution utilities and new public errors for pager/URL/file handling.

• Bug Fixes

  • Improved path normalization, duplication cleanup, and Windows/UNC/volume handling; more consistent component and sandbox path resolution.

• Documentation

  • Added Windows path guidance to CLI docs and a PRD on path construction vs validation.

• Tests

  • Extensive cross-platform tests for path joining, component resolution, absolute/relative edge cases, and sandbox behavior.

why

• Security & Governance: Enable policy enforcement based on process environment, CLI arguments, and Terraform variables for comprehensive security controls
• Compliance: Allow validation of sensitive operations, environment consistency, and approval workflows through policy-as-code
• Flexibility: Provide detailed context to OPA policies for sophisticated governance scenarios (production deployments, cost controls, naming conventions)
• Transparency: Make command execution context visible to policies for audit and compliance requirements

Enhanced OPA Policy Context

This enhancement provides 5 new input sections to OPA policies:

🔐 process_env: Process Environment Variables

• Purpose: Access environment variables from the current process for security and compliance
• Use Cases:
  • Enforce deployment approvals in production (DEPLOYMENT_APPROVED, APPROVED_BY)
  • Validate required credentials (AWS_REGION, AWS_PROFILE)
  • Restrict operations based on environment context
• Example: Block production deployments without proper approval workflow

🚀 cli_args: Command Line Arguments

• Purpose: List of command line arguments and flags (e.g., ["terraform", "apply"])
• Use Cases:
  • Block dangerous operations (terraform apply with specific conditions)
  • Enforce command structure and argument validation
  • Implement command-specific governance rules
• Example: Prevent terraform apply when certain variables are set

🛠️ tf_cli_vars: Terraform CLI Variables

• Purpose: Variables with proper type conversion from command-line -var arguments
• Use Cases:
  • Validate instance types, configurations, and resource limits
  • Enforce naming conventions and security policies
  • Prevent sensitive data from being passed via CLI
• Example: Restrict instance types and validate JSON configurations
• Type Safety: Automatic JSON parsing for complex objects and arrays

🌍 env_tf_cli_args: TF_CLI_ARGS Arguments

• Purpose: Parsed arguments from the TF_CLI_ARGS environment variable
• Use Cases:
  • Block dangerous flags (-auto-approve, -force) in production
  • Enforce plan file usage for apply operations
  • Validate parallelism and other execution parameters
• Example: Require plan files for production deployments

📊 env_tf_cli_vars: TF_CLI_ARGS Variables

• Purpose: Variables with type conversion from TF_CLI_ARGS environment variable
• Use Cases:
  • Cross-validate CLI and environment variable consistency
  • Enforce cost controls and resource naming conventions
  • Validate complex JSON configurations from environment
• Example: Ensure region consistency between CLI args and AWS_REGION

Technical Implementation

New Terraform CLI Utilities (terraform_cli_args_utils.go)

• GetTerraformEnvCliArgs(): Parses TF_CLI_ARGS into argument list with quote handling
• GetTerraformEnvCliVars(): Extracts and type-converts -var arguments from TF_CLI_ARGS
• Smart Parsing: Handles quoted strings, JSON values, and multiple -var formats
• Type Conversion: Automatic conversion of JSON objects, arrays, and numeric values

Enhanced Component Validation (validate_component.go)

• Process Environment Injection: Adds process_env section to component validation context
• CLI Context Integration: Incorporates command arguments and Terraform variables
• Backward Compatibility: All existing functionality preserved

Comprehensive Test Coverage

• Unit Tests: 286 test cases for argument parsing and variable extraction
• Integration Tests: 5 end-to-end validation scenarios
• Edge Cases: Quote handling, JSON parsing, malformed arguments, type conversion
• Performance: Benchmark tests for CLI argument processing

Updated Stack Configurations

• Test Components: 3 new validation components for comprehensive testing
• OPA Policy: Enhanced with 10 validation rules covering all new functionality
• Example Scenarios: Real-world governance examples for each context type

Policy Examples from Documentation

Environment-Based Security

# Block operations in production without proper approval
errors[message] {
  input.process_env.ENVIRONMENT == "production"
  not input.process_env.DEPLOYMENT_APPROVED
  message = "Production deployments require DEPLOYMENT_APPROVED environment variable"
}

CLI Variable Validation

# Ensure sensitive variables are not passed via CLI
errors[message] {
  sensitive_vars := ["password", "secret", "api_key", "token"]
  cli_var := sensitive_vars[_]
  input.tf_cli_vars[cli_var]
  message = sprintf("Sensitive variable '%s' should not be passed via command line", [cli_var])
}

TF_CLI_ARGS Governance

# Block dangerous flags in production
errors[message] {
  dangerous_flags := ["-auto-approve", "-force", "-lock=false"]
  flag := dangerous_flags[_]
  flag in input.env_tf_cli_args
  input.process_env.ENVIRONMENT == "production"
  message = sprintf("Flag '%s' is not allowed in production via TF_CLI_ARGS", [flag])
}

Cross-Context Validation

# Validate environment consistency across all sources
errors[message] {
  input.env_tf_cli_vars.region != input.process_env.AWS_REGION
  message = sprintf("Region mismatch: TF_CLI_ARGS region '%s' != AWS_REGION '%s'", [
    input.env_tf_cli_vars.region, input.process_env.AWS_REGION
  ])
}

Documentation Updates

Enhanced the OPA validation documentation with:

• Policy Execution Context: Comprehensive section explaining all 5 new context types
• Practical Examples: Real-world governance scenarios for each context type
• Best Practices: Guidelines for security, type safety, and error handling
• Combined Validation: Examples showing how to leverage multiple context sources
• Security Patterns: Templates for common governance use cases

Validation Results

All tests passing with comprehensive coverage:

✅ Process Environment: Validates env var injection and security policies
✅ CLI Arguments: Tests command structure and argument validation
✅ TF CLI Variables: Validates type conversion and security restrictions
✅ TF_CLI_ARGS Integration: Tests argument parsing and governance rules
✅ Cross-Context Validation: Ensures consistency across all input sources

Manual validation confirms:

• Environment variable injection working correctly
• CLI argument parsing handling all edge cases
• JSON type conversion functioning properly
• Security policies enforcing governance rules
• Backward compatibility maintained

This enhancement transforms Atmos OPA validation into a comprehensive governance platform, enabling sophisticated policy enforcement across infrastructure operations while maintaining full backward compatibility.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • TF_CLI_ARGS parsing and TF CLI vars from environment are exposed to validation and available to policies; process environment is also provided to validations.
• Bug Fixes
  • Improved OPA validation reliability on Windows with safer fallbacks and clearer errors.
• Documentation
  • Expanded docs and policy examples for env-based CLI args/vars and combined-context validation.
• Tests
  • Extensive unit, integration, and benchmark coverage for CLI parsing and validation flows.
• Chores
  • Linter settings adjusted and dependencies bumped.

why

• Git worktree environments were failing because subprocess execution didn't inherit working directory
• Windows tests were failing due to hardcoded Unix path assumptions and case-sensitive PATH handling
• Custom commands were silently ignoring all user-defined environment variables, breaking functionality
• Test structure was incorrect with git repository warning tests misplaced in empty-dir scenarios
• AtmosRunner was trying to build binaries after changing to test directories, causing build failures
• Cross-platform compatibility issues were preventing proper test execution on Windows/macOS/Linux
• Missing environment variable handling was causing production bugs in custom command execution

references

• Builds on AtmosRunner infrastructure introduced in #1526
• Addresses git worktree issues related to #1509
• Fixes critical environment variable handling bug discovered during testing
• Improves test infrastructure reliability and cross-platform compatibility

what

• Fixed regression where commands from .atmos.d/ directories and explicit imports were being replaced instead of merged with local commands
• Implemented proper command merging behavior that combines commands from all sources (defaults, .atmos.d, imports, local) with correct precedence
• Added comprehensive test coverage validating all command merging scenarios including CloudPosse's real-world use case
• Created Product Requirements Document capturing implementation details and requirements

why

• Organizations using Atmos need to maintain centralized command definitions that projects can import, extend, and optionally override
• Previous behavior broke workflows where teams define common commands in central repositories (e.g., CloudPosse's .github repo) that projects import and customize
• The regression prevented command inheritance, forcing teams to either duplicate all commands locally or lose access to centralized commands
• This fix enables:
  • Command inheritance from organizational repositories
  • Local project customization and overrides
  • Multi-level organizational structures with department/team/project command hierarchies
  • Modular command libraries using glob patterns

Technical Details

Root Cause

Viper's MergeConfig function doesn't overwrite arrays - it preserves existing array values. This caused imported commands to be ignored when local commands were present.

Solution

• Modified pkg/config/load.go to use temporary Viper instances to extract commands from imported files
• Restructured processConfigImportsAndReapply to apply correct precedence order: defaults < .atmos.d < imports < local
• Updated mergeCommandArrays to support name-based override behavior where later commands replace earlier ones with the same name

Command Precedence Order

1. Embedded defaults (lowest precedence)
2. .atmos.d/ directories
3. Explicit imports (via import: field)
4. Local configuration (highest precedence - wins on duplicates)

Test Coverage

• Basic merging: imported + local = all commands
• Override behavior: local overrides imported with same name
• Deep nesting: 4+ level import chains
• Empty imports: no effect on other commands
• Complex structures: command properties preserved
• Real-world scenario: 10 upstream + 1 local = 11 total commands (CloudPosse use case)

references

• Related to #1447 and #1489 which attempted to address this issue
• Fixes CloudPosse's workflow for centralized command management
• PRD: docs/prd/command-merging.md

Summary by CodeRabbit

• New Features

  • Deterministic command merging with clear precedence (embedded defaults → imported → local), per-name overrides, order preservation, and final merge ensuring local overrides; deep/nested imports and glob support.

• Documentation

  • New Product Requirements Document describing command merging behavior, use cases, testing, rollout, and success metrics.

• Tests

  • Extensive test coverage for merging semantics, deep import chains, overrides, deduplication, and command-structure preservation.

• Chores

  • More granular import-processing logs and updated CLI sample output reflecting merged commands.

• Add performance profiling with multiple profile types and environment variables
• Enhanced file-based profiling to support all 8 profile types: cpu, heap, allocs, goroutine, block, mutex, threadcreate, trace
• Added comprehensive environment variable support for all profiler settings
• Added --profile-type CLI flag for selecting profile type in file-based profiling
• Added mapstructure tags to profiler Config struct for proper environment variable unmarshaling
• Enhanced profiler configuration handling in root command with environment variable integration
• Updated profiling documentation with complete environment variable coverage
• Added comprehensive test coverage for new functionality
• Update docs:
  • https://pr-1534.atmos-docs.ue2.dev.plat.cloudposse.org/troubleshoot/profiling/

why

• Atmos includes built-in support for performance profiling using Go's standard pprof tool. Profiling helps identify performance bottlenecks, memory usage patterns, and CPU hotspots to optimize Atmos operations.
• Users need access to different types of profiling data beyond just CPU profiling for comprehensive performance analysis
• Environment variables enable easier CI/CD integration and automated profiling workflows
• The original implementation only supported CPU profiling in file-based mode, limiting debugging capabilities
• Missing mapstructure tags prevented environment variables from being properly loaded
• Documentation was incomplete regarding environment variable usage

references

• Enhanced pkg/profiler/profiler.go with multi-profile-type support
• Added environment variable binding in pkg/config/load.go
• Updated CLI flag handling in cmd/root.go
• Comprehensive test coverage in pkg/profiler/profiler_test.go
• Updated documentation in website/docs/troubleshoot/profiling.mdx and website/docs/cli/global-flags.mdx

Key Features Added

Multiple Profile Types Support:

• CPU Profile: Shows where your program spends CPU time
• Heap Profile: Shows current heap memory allocation patterns
• Allocs Profile: Shows all memory allocations since program start
• Goroutine Profile: Shows active goroutines and their call stacks
• Block Profile: Shows operations that led to blocking on synchronization primitives
• Mutex Profile: Shows lock contention patterns
• Thread Create Profile: Shows stack traces that led to thread creation
• Trace Profile: Shows detailed execution traces for performance analysis

Environment Variables Added:

• ATMOS_PROFILER_ENABLED - Enable/disable pprof HTTP profiling server
• ATMOS_PROFILER_HOST - Set host address for profiling server
• ATMOS_PROFILER_PORT - Set port for profiling server
• ATMOS_PROFILE_FILE - Set file path for file-based profiling
• ATMOS_PROFILE_TYPE - Set profile type for file-based profiling

CLI Enhancements:

• Added --profile-type flag with validation and error handling
• Enhanced --profile-file to automatically enable profiling
• Full backwards compatibility maintained

Configuration Precedence:

1. Command-line flags (highest priority)
2. Environment variables
3. Configuration file (atmos.yaml)
4. Default values (lowest priority)

Usage Examples

File-based profiling with different types:

# CPU profiling (default)
$ atmos terraform plan vpc -s prod --profile-file=cpu.prof
👽 Atmos 1.192.0 on darwin/arm64
INFO Profiling started type=cpu file=cpu.prof
INFO Profiling completed type=cpu file=cpu.prof

# Memory heap profiling
$ atmos terraform plan vpc -s prod --profile-file=heap.prof --profile-type=heap
👽 Atmos 1.192.0 on darwin/arm64
INFO Profiling started type=heap file=heap.prof
INFO Profiling completed type=heap file=heap.prof

# Execution trace profiling
$ atmos terraform plan vpc -s prod --profile-file=trace.out --profile-type=trace
👽 Atmos 1.192.0 on darwin/arm64
INFO Profiling started type=trace file=trace.out
INFO Profiling completed type=trace file=trace.out

# Goroutine profiling
$ atmos terraform plan vpc -s prod --profile-file=goroutine.prof --profile-type=goroutine
👽 Atmos 1.192.0 on darwin/arm64
INFO Profiling started type=goroutine file=goroutine.prof
INFO Profiling completed type=goroutine file=goroutine.prof

Environment variable usage:

# File-based profiling via environment variables
$ export ATMOS_PROFILE_FILE=debug.prof
$ export ATMOS_PROFILE_TYPE=goroutine
$ atmos describe stacks
👽 Atmos 1.192.0 on darwin/arm64
INFO Profiling started type=goroutine file=debug.prof
INFO Profiling completed type=goroutine file=debug.prof

# Server-based profiling via environment variables
$ export ATMOS_PROFILER_ENABLED=true
$ export ATMOS_PROFILER_PORT=8080
$ atmos terraform apply vpc -s prod
👽 Atmos 1.192.0 on darwin/arm64
INFO Profiler server available at: url=http://localhost:8080/debug/pprof/

Error handling for invalid profile types:

$ atmos terraform plan vpc -s prod --profile-file=test.prof --profile-type=invalid
👽 Atmos 1.192.0 on darwin/arm64
ERRO Failed to setup profiler error="invalid profile type: unsupported profile type: invalid. Supported types: [cpu heap allocs goroutine block mutex threadcreate trace]"

Server-based profiling:

$ atmos terraform apply vpc -s prod --profiler-enabled --profiler-port=9090
👽 Atmos 1.192.0 on darwin/arm64
INFO Profiler server available at: url=http://localhost:9090/debug/pprof/

Profile Analysis Examples

Analyzing CPU profiles:

# Interactive text mode
$ go tool pprof cpu.prof
(pprof) top
Showing nodes accounting for 230ms, 95.83% of 240ms total
flat  flat%   sum%        cum   cum%
80ms  33.33% 33.33%      80ms  33.33%  github.com/cloudposse/atmos/internal/exec.processStackConfig
60ms  25.00% 58.33%      60ms  25.00%  gopkg.in/yaml.v3.(*Decoder).Decode
40ms  16.67% 75.00%      40ms  16.67%  github.com/cloudposse/atmos/pkg/utils.ProcessTmplWithDatasources

# Web interface
$ go tool pprof -http=:8080 cpu.prof

Analyzing trace profiles:

# Use go tool trace for execution traces
$ go tool trace trace.out
# Opens web interface showing timeline view, blocking profiles, etc.

Analyzing memory profiles:

$ go tool pprof heap.prof
(pprof) top
Showing nodes accounting for 512.45MB, 98.23% of 521.63MB total
flat  flat%   sum%        cum   cum%
256.12MB 49.11% 49.11%  256.12MB 49.11%  github.com/cloudposse/atmos/internal/exec.(*StackProcessor).ProcessYAMLConfigFiles
128.33MB 24.61% 73.72%  128.33MB 24.61%  github.com/cloudposse/atmos/pkg/utils.ReadYamlFile

Testing

• Added comprehensive unit tests for all profile types
• Added environment variable integration tests
• Added configuration serialization tests
• Added error handling and validation tests
• All existing tests continue to pass
• 100% backwards compatibility maintained

Files Modified

• pkg/profiler/profiler.go - Enhanced with multi-profile support
• pkg/profiler/profiler_test.go - Added comprehensive test coverage
• cmd/root.go - Enhanced CLI flag and environment variable handling
• pkg/config/load.go - Added environment variable bindings
• website/docs/troubleshoot/profiling.mdx - Updated documentation
• website/docs/cli/global-flags.mdx - Added profiling flag docs

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

Summary by CodeRabbit

• New Features

  • Built-in profiling (pprof) with server- and file-based modes; new config and env options exposed in describe-config; new CLI flags: --profiler-enabled, --profiler-host, --profiler-port, --profile-file, --profile-type.

• Documentation

  • Added profiler guides, troubleshooting and usage docs; updated configuration and global flags pages with examples and security notes.

• Tests

  • Added comprehensive profiler tests and updated CLI help snapshots.

• Chores

  • Dependency upgrades and example Atmos version bumps; minor logging/no-op adjustments.

This PR contains the following updates:

Release Notes

Configuration

📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR is behind base branch, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

• If you want to rebase/retry this PR, check this box

This PR was generated by Mend Renovate. View the repository job log.

Welcome to Renovate! This is an onboarding PR to help you understand and configure settings before regular Pull Requests begin.

🚦 To activate Renovate, merge this Pull Request. To disable Renovate, simply close this Pull Request unmerged.

Detected Package Files

• .devcontainer/Dockerfile (dockerfile)
• Dockerfile (dockerfile)
• demo/screenshots/Dockerfile (dockerfile)
• .github/actions/pr-sizer/action.yml (github-actions)
• .github/actions/remove-dependabot-semver-labels/action.yml (github-actions)
• .github/workflows/autofix.yml (github-actions)
• .github/workflows/build.yml (github-actions)
• .github/workflows/codeql.yml (github-actions)
• .github/workflows/dependabot.yml (github-actions)
• .github/workflows/feature-release.yml (github-actions)
• .github/workflows/nightlybuilds.yml (github-actions)
• .github/workflows/pre-commit.yml (github-actions)
• .github/workflows/screengrabs.yaml (github-actions)
• .github/workflows/test.yml (github-actions)
• .github/workflows/validate-codeowners.yml (github-actions)
• .github/workflows/vhs.yaml (github-actions)
• .github/workflows/website-deploy-prod.yml (github-actions)
• .github/workflows/website-preview-build.yml (github-actions)
• .github/workflows/website-preview-deploy.yml (github-actions)
• .github/workflows/website-preview-destroy.yml (github-actions)
• go.mod (gomod)
• website/package.json (npm)
• website/plugins/custom-loaders/package.json (npm)
• website/plugins/fetch-latest-release/package.json (npm)
• website/.nvmrc (nvm)

Configuration Summary

Based on the default config's presets, Renovate will:

• Start dependency updates only once this onboarding PR is merged
• Hopefully safe environment variables to allow users to configure.
• Show all Merge Confidence badges for pull requests.
• Enable Renovate Dependency Dashboard creation.
• Use semantic commit type fix for dependencies and chore for all others if semantic commits are in use.
• Ignore node_modules, bower_components, vendor and various test/tests (except for nuget) directories.
• Group known monorepo packages together.
• Use curated list of recommended non-monorepo package groupings.
• Show only the Age and Confidence Merge Confidence badges for pull requests.
• Apply crowd-sourced package replacement rules.
• Apply crowd-sourced workarounds for known problems with packages.

🔡 Do you want to change how Renovate upgrades your dependencies? Add your custom config to renovate.json in this branch. Renovate will update the Pull Request description the next time it runs.

What to Expect

With your current configuration, Renovate will create 51 Pull Requests:

🚸 Branch creation will be limited to maximum 2 per hour, so it doesn't swamp any CI resources or overwhelm the project. See docs for prhourlylimit for details.

[!WARNING]
Please correct - or verify that you can safely ignore - these dependency lookup failures before you merge this PR.

• Failed to look up go package github.com/alicebob/miniredis/v2

Files affected: go.mod

❓ Got questions? Check out Renovate's Docs, particularly the Getting Started section.
If you need any further assistance then you can also request help here.

This PR was generated by Mend Renovate. View the repository job log.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.