cloudposse/atmos v1.202.0

on GitHub

what

• Fixed flaky PTY tests TestExecWithPTY_BasicExecution and TestExecWithPTY_DefaultOptions
• Replaced direct echo command with sh -c using printf for more reliable output handling
• Added a small sleep to ensure PTY has time to read buffered output before subprocess exit

why

The flaky tests were failing intermittently because the direct echo command doesn't reliably output through the PTY in all environments. Using sh -c with printf and a brief sleep resolves the race condition that occurs when the subprocess exits before all output is read from the PTY.

references

• https://go.dev/issue/57141 - PTY race condition documentation
• Tests now match the pattern already used in TestExecWithPTY_WithMasking and TestExecWithPTY_MaskingDisabled

what

Implements file-scoped locals for Atmos stack manifests, enabling temporary variables that reduce repetition and improve readability. Locals are resolved in dependency order with automatic cycle detection.

• File-scoped locals: Define at global, component-type (terraform/helmfile/packer), or component level
• Dependency resolution: Locals can reference other locals with topological sorting
• Circular dependency detection: Clear error messages for circular references
• File-scoped isolation: Locals do not inherit across imports (unlike vars)
• Provenance tracking: atmos describe locals command shows where each local is defined

why

Users working with complex stack configurations often repeat values (naming conventions, tags, etc.) across multiple components. File-scoped locals provide a DRY solution similar to Terraform and Terragrunt, reducing error-prone manual repetition and making configurations more maintainable.

references

• PRD: docs/prd/file-scoped-locals.md
• Blog post: website/blog/2025-12-16-file-scoped-locals.mdx
• Test scenarios: tests/fixtures/scenarios/locals/ and tests/fixtures/scenarios/locals-circular/

Summary by CodeRabbit

• New Features

  • File-scoped locals: declare temporary variables (global, component-type, component) with templating, dependency-aware resolution, deterministic ordering, and circular-dependency detection; locals are isolated to their file and injected during template processing.

• Schema

  • Manifest/schema updates to allow a locals section across supported component/tool scopes.

• Documentation

  • PRD, user docs, CLI/describe updates, and a blog post with examples and guidance.

• Tests

  • Extensive unit and fixture tests covering resolution, templating, inheritance within a file, cycles, and error cases.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

What

Add a new !literal YAML function that preserves values exactly as written, bypassing template processing. This enables passing template-like syntax ({{...}}, ${...}) to downstream tools without Atmos attempting to evaluate them.

Why

Users frequently need to pass template syntax to Terraform, Helm, ArgoCD, and other tools. Previously, they had to use awkward escaping patterns like "{{'{{value}}'}}". The !literal function provides a clean, self-documenting solution that resolves this common pain point.

References

• Implements feature discussed in YAML functions design
• Improves DX by eliminating need for complex escape sequences
• Follows existing patterns like !include.raw and !template

See documentation for usage examples and common use cases.

Summary by CodeRabbit

• New Features

  • Added a YAML literal function (!literal) that preserves values exactly as written, bypassing template processing to safely pass template-like syntax to downstream tools (Terraform, Helm, ArgoCD, Kustomize).

• Documentation

  • New docs page, examples, and a blog post demonstrating usage and common scenarios.

• Tests

  • Comprehensive test coverage across scalars, lists, multiline values, special characters, nesting, and mixed-tag scenarios.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Added comprehensive unit tests to improve test coverage across multiple packages
• Fixed stale mock signatures in pkg/list/utils that were causing test failures
• New test files added:
  • pkg/filesystem/os_filesystem_test.go - Tests for OSFileSystem, OSGlobMatcher, and OSIOCopier
  • pkg/filesystem/homedir_test.go - Tests for OSHomeDirProvider
  • cmd/terraform/generate/generate_test.go - Tests for GenerateCmd structure and flags
  • cmd/terraform/shared/prompt_test.go - Tests for HandlePromptError and stackContainsComponent
  • cmd/terraform/options_test.go - Tests for ParseTerraformRunOptions
  • cmd/terraform/generate/varfile/varfile_test.go - Tests for NewVarfileCommand

Coverage Improvements

Tests Added

pkg/filesystem

• TestNewOSFileSystem - Constructor test
• TestOSFileSystem_Open - Tests opening existing and non-existent files
• TestOSFileSystem_Create - Tests creating and truncating files
• TestOSFileSystem_Stat - Tests file/directory info retrieval
• TestOSFileSystem_MkdirAll - Tests nested directory creation
• TestOSFileSystem_Chmod - Tests permission changes
• TestOSFileSystem_MkdirTemp - Tests temp directory creation
• TestOSFileSystem_CreateTemp - Tests temp file creation
• TestOSFileSystem_WriteFile - Tests writing content to files
• TestOSFileSystem_ReadFile - Tests reading file content
• TestOSFileSystem_Remove - Tests file/directory removal
• TestOSFileSystem_RemoveAll - Tests recursive removal
• TestOSFileSystem_Walk - Tests directory tree walking
• TestOSFileSystem_Getwd - Tests current directory retrieval
• TestOSGlobMatcher_GetGlobMatches - Tests glob pattern matching
• TestOSGlobMatcher_PathMatch - Tests path matching patterns
• TestOSIOCopier_Copy - Tests data copying between readers/writers
• TestOSHomeDirProvider_Dir - Tests home directory retrieval
• TestOSHomeDirProvider_Expand - Tests tilde expansion

cmd/terraform/generate

• TestGenerateCmd - Tests command structure and subcommands
• TestBackendCmd - Tests backend command flags
• TestBackendsCmd - Tests backends command structure
• TestVarfileCmd - Tests varfile command structure
• TestVarfilesCmd - Tests varfiles command structure
• TestPlanfileCmd - Tests planfile command structure

cmd/terraform/shared

• TestHandlePromptError - Tests prompt error handling for nil, user abort, and interactive mode errors
• TestHandlePromptError_WrappedErrors - Tests error unwrapping behavior
• TestStackContainsComponent - Tests component lookup in stack data structures
• TestComponentsArgCompletion - Tests shell completion for components
• TestStackFlagCompletion_ArgsHandling - Tests stack flag completion branching

cmd/terraform

• TestParseTerraformRunOptions - Tests parsing terraform flags from Viper
• TestTerraformRunOptions_Fields - Tests struct field access

cmd/terraform/generate/varfile

• TestNewVarfileCommand - Tests command structure, args validation, and flags
• TestNewVarfileCommand_FlagValues - Tests flag value setting/getting

pkg/list/utils (fix)

• Fixed stale gomonkey mock signatures to include the new auth.AuthManager parameter
• All 8 mock functions updated from 10 to 11 parameters

why

• Improve overall test coverage to catch regressions early
• Fix broken tests caused by function signature changes
• Ensure filesystem abstraction layer is properly tested
• Validate CLI command structure and flag definitions

references

• Test coverage is enforced by CodeCov at 80% minimum

• Add a root-level env section to atmos.yaml that defines environment variables applied to all Atmos subprocesses
• Create new pkg/env/ package by refactoring pkg/utils/env_utils.go with global env support
• Inject global env into terraform, helmfile, packer, workflows, custom commands, and auth exec contexts

why

• Provides a single location to configure environment variables that affect all Atmos operations
• Useful for settings like AWS_DEFAULT_REGION, TF_PLUGIN_CACHE_DIR, proxy configurations, or logging flags
• Works seamlessly with Atmos profiles - e.g., set GITHUB_TOKEN for local dev while assuming it's already set in CI
• Global env has lowest priority and can be overridden at stack or component level

references

• Follows existing env precedence: atmos.yaml env < stack env < component-type env < component env < overrides env

Summary by CodeRabbit

• New Features

  • New env command to render/export atmos.yaml environment variables (bash, json, dotenv, GitHub).
  • Global env section in atmos.yaml applies vars to all Atmos subprocesses.

• Enhancements

  • Global env now merged with system/stack/component envs with clear precedence (system → global → stack/component).
  • Case-preservation for env keys across merged config files; deterministic ordering and GitHub format support.

• Documentation

  • Expanded docs, examples, demo, and PRD showing env usage and GitHub Actions integration.

• Tests

  • Added comprehensive tests for env handling, merging precedence, and case-preservation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Migrate all terraform commands from monolithic cmd files to registry-based modular structure
• Restructure terraform command handling into individual command providers under cmd/terraform/
• Update flag handling to use StandardFlagParser pattern for consistent CLI argument processing
• Fix I/O handling in terraform plan-diff to use data.Writeln() for proper output layering
• Add comprehensive terraform registry migration PRD documentation

why

Improves code maintainability and extensibility by following the CommandProvider registry pattern established in the codebase. Breaks down monolithic terraform command files into focused, single-responsibility modules. Ensures proper I/O separation between data output and UI messages as per CLAUDE.md standards.

references

• Implements docs/prd/command-registry-pattern.md
• Follows I/O/UI standards in CLAUDE.md
• Adds docs/prd/terraform-registry-migration.md with detailed migration architecture

Summary by CodeRabbit

• New Features

  • Full Terraform command suite added (many terraform subcommands) and interactive component/stack prompts in TTY.

• Improvements

  • Terraform compatibility/pass‑through flags exposed and shown in help; help output simplified.
  • Tab completion: stack suggestions filtered by selected component.
  • terraform clean: new --everything, --force (-f), --skip-lock-file and improved dry-run output.
  • plan/apply: enhanced from‑plan/planfile handling and upload-status behavior.

• Chores

  • Telemetry notice, docs/blog updates, and test/snapshot maintenance.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Exclude files and directories starting with underscore (_) from Docusaurus sidebar generation
• Prevents _partials and other internal-only directories from appearing in the documentation navigation

why

Docusaurus follows the convention that files and folders prefixed with _ should be excluded from the sidebar. The autogenerated sidebar feature doesn't automatically respect this convention, requiring explicit exclude patterns in the configuration.

references

The _partials directory is used internally for reusable documentation fragments that shouldn't appear in the public sidebar.

Summary by CodeRabbit

• Chores

  • Expanded documentation exclusion patterns to ignore underscore-prefixed files and directories, reducing which doc files are considered for site generation.

• Documentation

  • Updated a blog post front-matter release version from v1.95.0 to v1.195.0.

• Style

  • Table of contents container changed from fixed to sticky positioning for improved scrolling and layout behavior.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Summary

Implements interactive prompt support for CLI commands with positional arguments. When a required positional argument is missing and interactive mode is enabled (default), users see a filterable selector instead of an error message. This significantly improves discoverability and reduces cognitive load for users.

Key Features

• Three prompt use cases: missing required flags, optional value flags (sentinel pattern), missing positional arguments
• Graceful degradation: prompts only shown in TTY + non-CI environments, automatically disabled in pipelines
• Height-limited selector: Limited to 20 visible rows to prevent excessive scrolling and rendering artifacts
• Comprehensive testing: 399 lines of test coverage with multiple scenarios
• Documentation: Updated docs and example implementations

Test Plan

• Test atmos theme show without arguments → interactive selector appears
• Test atmos theme show dracula with argument → executes normally
• Test Ctrl-C abort → proper error handling
• Test filtering with "/" → case-sensitive (documented Huh limitation)
• Test non-interactive mode → graceful fallback to standard errors
• Test in CI environment → prompts disabled automatically
• All linter checks pass (new code only)

Summary by CodeRabbit

• New Features

  • Interactive prompts for missing required flags, optional flag values (sentinel), and positional arguments in TTY terminals (enabled by default, disabled in CI)
  • New --interactive CLI flag and ATMOS_INTERACTIVE env var to toggle prompts
  • Theme show now supports interactive theme selection with completion when name is omitted

• UI

  • Interactive prompt styling respects the current theme (button colors updated)

• Documentation

  • User guide updates and a blog post explaining interactive prompts

• Tests

  • Updated help snapshots and many new tests covering prompt-aware behavior

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Add optional working_directory field to custom commands and workflow steps to control where they execute
• Support absolute paths, relative paths (resolved against base_path), and !repo-root YAML function
• Automatically discover .atmos.d/ at git repository root for repo-wide configuration
• Add parent directory search for atmos.yaml configuration file
• Introduce Profiles as first-class configuration concept in precedence list
• Document all features with comprehensive examples in CLI configuration docs

why

Users need fine-grained control over where commands and workflows execute, especially when using .atmos.d/ at the repository root for shared configurations. Parent directory search and git root discovery make Atmos work seamlessly from any subdirectory, mirroring Git's behavior.

Profiles deserve first-class documentation as a primary configuration mechanism for environment-specific overrides.

references

Closes #DEV-3007

Summary by CodeRabbit

• New Features

  • Working directory support for commands and workflows (workflow- and step-level overrides; relative paths resolved against the project base).
  • Repo-wide fragments: automatic parent-directory search for atmos.yaml and discovery of .atmos.d at the Git repository root.

• Documentation

  • New docs and blog posts covering working_directory, discovery precedence, profiles, and examples.

• Improvements

  • Better config discovery diagnostics and more consistent path normalization in outputs and tests.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Fixed misleading "component not found" errors when Terraform components have invalid HCL syntax
• Improved error messages to show the actual HCL parsing error, file path, line number, and actionable hints
• Prevented detectComponentType() from masking HCL errors by trying other component types

why

When a Terraform component contained invalid HCL syntax, Atmos incorrectly reported "Could not find the component" instead of showing the actual HCL parsing error. This was confusing because the component existed in the stack manifest and appeared in the TUI menu. The root cause was that detectComponentType() tried Helmfile/Packer as fallbacks when Terraform processing failed, ultimately masking the real error with a generic "not found" message.

references

Closes #1864

Summary by CodeRabbit

• New Features

  • Improved Terraform HCL syntax error messages with file/line context, diagnostic details, and actionable validation hints.

• Bug Fixes

  • Better error propagation: stop trying other component types when a non-invalid-component error occurs, ensuring accurate error reporting.

• Tests

  • Added tests and fixtures to validate HCL syntax error detection, messaging, and formatted output.

• Documentation

  • Blog post describing the improved HCL syntax error messaging and troubleshooting steps.

• Chores

  • Renamed a public error identifier for clearer semantics.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Summary

• Implement automatic Terraform backend provisioning system to eliminate manual bootstrapping
• Add self-registering provisioner architecture with hook-based integration
• Provide S3 backend implementation with opinionated security defaults (versioning, AES-256 encryption, public access blocking)
• Support cross-account provisioning via AuthManager integration
• Enable CLI command for manual provisioning: atmos provision backend

Details

• Provisioner System: Extensible self-registering architecture that allows provisioners to declare when they should run via hook events
• S3 Backend: Hardcoded secure defaults (no configuration options), perfect for dev/test workflows
• Hook Integration: Automatic provisioning before terraform init when enabled
• Production Migration: Clear path to move from automatic provisioning to Terraform-managed via import blocks
• Documentation: 3 PRDs, CLI reference, configuration guide, and blog announcement

Test Plan

• Verify provisioner system loads and registers correctly
• Test S3 backend provisioning creates bucket with all security defaults
• Verify idempotent operations (running provision multiple times is safe)
• Test CLI command: atmos provision backend <component> --stack <stack>
• Verify automatic provisioning runs before terraform init
• Test error handling and exit codes
• Validate documentation builds successfully

Summary by CodeRabbit

• New Features

  • New "terraform backend" CLI with create/list/describe/update/delete and automatic backend provisioning (secure-by-default S3, cross-account support) plus a pre-Terraform-init hook to run provisioners.

• Documentation

  • Multiple PRDs, website guides, and a blog post covering provisioning architecture, configs, examples, CLI usage, and migration guidance.

• Bug Fixes

  • Help output printing now safely handles empty descriptions.

• Tests

  • Extensive tests for provisioning flows, S3 create/delete, CLI commands, registry/hook execution, and deletion workflows.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Updated store configuration examples to match actual implementation
• Changed all backend/config keys to type/options
• Fixed Azure Key Vault to use vault_url instead of vault_name
• Removed unsupported AWS Secrets Manager section
• Updated Redis configuration to use URL format
• Added complete Artifactory section with all options

why

GitHub issue #1860 reported that the documentation showed an incorrect format for store configuration. The code expects type/options keys, not backend/config keys. This created confusion for users following the documentation.

references

Closes #1860

Summary by CodeRabbit

• Documentation
  • Simplified store configuration schema for all backends (AWS SSM Parameter Store, Azure Key Vault, Google Secret Manager, Redis, Artifactory) using a unified type and options format.
  • Added support for additional optional configuration parameters including prefixes, delimiters, and credentials.
  • Enhanced configuration examples and clarified authentication methods across all store types.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Add release: v1.201.0 to the frontmatter of the devcontainer blog posts

why

These blog posts were released in v1.201.0, but subsequent corrections to them (fixing dates/tags in #1856) are currently unreleased. Without the release: field, these corrections cause the posts to appear in the "Unreleased" section of the changelog. By explicitly setting release: v1.201.0, we retroactively associate them with their original release, so the corrections don't show up as unreleased changes.

references

• Devcontainer feature was released in v1.201.0
• Date/tag corrections made in #1856

Summary by CodeRabbit

• Documentation
  • Updated metadata on blog posts related to development container support.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Added comprehensive section on YAML explicit type tags (!!str, !!int, !!float, !!bool) as an alternative to quoting
• Expanded null values documentation with detailed explanation of ~ tilde shorthand
• Added prominent warning explaining the semantic difference between null and "" empty string
• Updated quick reference table to include null and type tag entries
• Added practical use case for overriding inherited values to null

why

The YAML reference guide was missing documentation for explicit type tags and didn't sufficiently emphasize the difference between null and empty string, which is important in Terraform configuration where they have different behaviors.

references

Related to YAML syntax documentation completeness

Summary by CodeRabbit

• Documentation
  • Added guidance on YAML explicit type tags (!!str, !!int, !!float, !!bool) with examples and best practices for when to use them versus quoting
  • Expanded null values section with comprehensive guidance distinguishing null, tilde (~), and empty strings, including Terraform-specific implications
  • Enhanced Quick Reference table with entries for null handling and explicit typing

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Make workflow --file flag optional with auto-discovery and interactive selection
• Centralize workflow error formatting to main.go (eliminates "deep error printing" pattern)
• Refactor workflow command to cmd/workflow/ package structure following command registry pattern
• Add descriptive "Workflow Error" title to workflow-specific errors (not generic "Error")
• Use static error definitions (ErrNoWorkflowFilesToSelect, ErrNonTTYWorkflowSelection) instead of dynamic errors
• Improve command hints with markdown code fences and shell-safe single quotes
• Convert if-else chains to switch statements for better code style
• Regenerate workflow test snapshots to match new error output format

why

• Auto-discovery: When no workflow file is specified, automatically search across all workflow configuration files and prompt user to select if multiple matches found - makes workflows easier to use
• Centralized error handling: Follows the same architectural principle as eliminating "deep exits" (os.Exit calls) - now eliminating "deep error printing" (CheckErrorAndPrint calls throughout codebase)
• Better UX: Descriptive error titles ("Workflow Error" vs "Error"), properly formatted command hints, shell-safe quoting for values with spaces
• Code quality: Static errors for better error handling, cleaner code structure with switch statements

references

• Follows architectural pattern from "avoiding deep exits" - centralizing error handling in main.go
• Part of workflow command improvements to make Atmos workflows more user-friendly

Summary by CodeRabbit

• New Features

  • Workflow file auto-discovery: Run workflows without specifying --file when the name is unique across files
  • Interactive workflow selection when multiple files contain the same workflow name
  • Enhanced shell completion for workflow flags (stack, identity) and workflow names

• Documentation

  • Added workflow file auto-discovery documentation with usage examples and guidance

• Improvements

  • Refined error messages with actionable hints and improved formatting for better user guidance

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Introduces a top-level name field in stack manifests for explicit control over logical stack names
• Takes precedence over name_template and name_pattern from atmos.yaml
• Provides an escape hatch for legacy infrastructure or migrations from tools like Terragrunt
• Terraform workspace derivation respects the manifest name
• Updates JSON schema and documentation

why

Stack naming conventions work well for greenfield projects but struggle with:

• Legacy infrastructure that predates naming conventions
• Infrastructure acquired from other organizations
• Migrations from tools like Terragrunt with different naming schemes

This feature allows selective stack name overrides without requiring all stacks to follow a pattern.

references

• Stack name precedence: name > name_template > name_pattern > filename
• Analogous to component metadata.name field for component renaming

Summary by CodeRabbit

• New Features

  • Added explicit stack naming via "name" field in stack manifests with precedence over name_template and name_pattern

• Documentation

  • Comprehensive stack naming documentation covering precedence rules, examples, and migration scenarios

• Bug Fixes

  • Improved cross-platform test reliability with adjusted timeout values

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Removed invalid blog tags from 9 blog posts (tags that weren't in the approved list)
• Fixed devcontainer post dates to match their filenames (2025-12-05)
• All blog posts now use only valid tags: Breaking Change, Bug Fix, Core, DX, Documentation, Enhancement, Feature, Security

why

Blog posts were using tags outside the approved select list, which doesn't match the instructions. Updated all posts to comply with the tag restrictions and corrected the dates on the two devcontainer posts.

references

Follow-up to blog tag standardization.

Summary by CodeRabbit

• Documentation
  • Updated blog post metadata tags and publication dates for improved content organization.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

What

• Added ActionCard component to devcontainer commands page linking to configuration reference for improved discoverability
• Removed explicit sidebar_position values from 18 CLI Configuration docs to enable automatic alphabetical sorting
• Fixed How-To Guides sidebar labels to use Title Case (Catalogs, Inheritance, Mixins) for consistency
• Updated minimum Atmos version requirement to v1.201.0 in Geodesic guide
• Converted blockquote note to Docusaurus admonition format in using-geodesic.mdx

Why

• ActionCard provides consistent navigation pattern across all command documentation
• Alphabetical sidebar sorting improves discoverability and eliminates manual position management
• Title Case labels align with documentation style guidelines
• Version bump reflects latest feature requirements

References

• Docusaurus ActionCard pattern follows atmos.tools/cli/commands/auth/, terraform/, validate/ and other command pages

Summary by CodeRabbit

• New Features

  • Added a configuration guide card to devcontainer documentation with direct access to the configuration reference.

• Documentation

  • Updated minimum version requirement for devcontainer feature to v1.201.0.
  • Reorganized documentation navigation structure and improved sidebar label capitalization for consistency.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Fixed race condition in TestExecWithPTY_WithMasking and TestExecWithPTY_MaskingDisabled tests
• Changed subprocess commands to add a brief sleep before exit, allowing PTY to read all buffered output
• Improved error message in TestExecWithPTY_MaskingDisabled to show bytes for better debugging

why

These tests were failing intermittently due to Go issue #57141. When a subprocess exits immediately after writing to PTY, the PTY can receive EIO (end of input/output) before all buffered output is read. The sleep gives the PTY time to read the output before the subprocess exits.

references

• https://go.dev/issue/57141
• Related to PR #1835 (osterman/stack-manifest-name)

what

• Fixed a regression introduced in v1.201.0 where relative paths in atmos.yaml were resolved incorrectly
• Implemented correct base path resolution semantics that allow users to run atmos from anywhere inside a repository
• Treats . and .. as config-file-relative paths (following the convention of tsconfig.json, package.json, etc.)
• Empty base_path now triggers git root discovery with proper fallback order
• Added !cwd YAML function for explicit CWD-relative paths when needed
• Added comprehensive tests and documentation for path resolution semantics
• Fixed pipe buffer deadlock in tests that capture stdout/stderr (output now read concurrently)
• Added Windows skip conditions for tests using Unix-specific commands

why

Issue #1858 revealed that after upgrading from v1.200.0 to v1.201.0, atmos validate stacks failed with "stacks directory does not exist" when ATMOS_CLI_CONFIG_PATH pointed to a subdirectory while stacks/components were at repo root.

The root cause was that empty base_path was not properly triggering git root discovery when atmos.yaml is in a deeply nested subdirectory. The fix implements correct path resolution semantics where:

• Config-file-relative paths (. and ..) work like other configuration files
• Smart defaults (empty string) trigger git root discovery with proper fallback order
• Simple relative paths search git root first, then fall back to config directory

Path Resolution Semantics

Key Semantic Distinctions

1. "" vs ".": These are NOT the same

   • "" = smart default (git root with fallback to config dir)
   • "." = explicit config directory (where atmos.yaml lives)

2. "./foo" vs "foo": These are NOT the same

   • "./foo" = config-dir/foo (explicit config-file-relative)
   • "foo" = git-root/foo with fallback (search path)

3. "..": Always relative to atmos.yaml location

   • Used for navigating from config location to elsewhere in repo
   • Common pattern: config in subdirectory, base_path: "../.." to reach repo root

Config File Search Order

Atmos searches for atmos.yaml in the following order:

references

• Closes #1858
• See docs/prd/base-path-resolution-semantics.md for complete PRD
• See docs/fixes/path-resolution-regression.md for detailed analysis and manual testing instructions

Summary by CodeRabbit

• Bug Fixes

  • Clarified base_path resolution semantics, refined git-root discovery, and reduced noisy config-path debug logs.

• New Features

  • Added !cwd YAML function to reference the current working directory.
  • Introduced a dedicated CLI config-path env override and clearer multi-source config precedence.

• Documentation

  • Added PRD and user docs covering base-path semantics and !cwd with examples.

• Chores

  • Bumped dependency versions and updated license references; advanced example Atmos image.

• Tests

  • Expanded path-resolution and YAML-tag tests, improved test isolation, added Windows guards, and fixed pipe-buffer deadlocks.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• Fix command descriptions in help to render markdown properly and respect text width constraints
• Use correct commandDesc style for command descriptions instead of commandName style
• Update Atmos short and long descriptions to "framework for orchestrating and operating infrastructure workflows across multiple cloud and DevOps toolchains"

why

• Command descriptions were rendering with incorrect styling (bold primary color instead of secondary text color) and markdown was being processed incorrectly due to double word-wrapping
• The descriptions now match the rendering approach used by flag descriptions, ensuring consistent and proper markdown rendering
• Updated descriptions better reflect what Atmos is and how it works

references

• Related to help text rendering improvements

Summary by CodeRabbit

• Documentation

  • Updated Atmos product description in README and help text to reflect its positioning as a framework for orchestrating and operating infrastructure workflows across multiple cloud and DevOps toolchains.

• New Features

  • Enhanced help output rendering with markdown support for improved formatting and display of command descriptions.

• Tests

  • Added test coverage for markdown-aware help rendering and updated existing tests to align with new rendering capabilities.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

what

• CLI aliases defined in atmos.yaml now appear in a dedicated "ALIASES" section in --help output
• Separates user-defined command shortcuts from regular commands for improved help clarity
• Maintains distinction between built-in command aliases and CLI config aliases

why

Users reported that aliases added via CLI config (atmos.yaml) appeared mixed with regular commands in the "AVAILABLE COMMANDS" section, making help output less clear. Creating a dedicated "ALIASES" section improves UX by clearly distinguishing shortcuts from actual commands.

implementation

• Mark config aliases with "configAlias" annotation in processCommandAliases()
• Add isConfigAlias() helper to identify config alias commands
• Filter config aliases from printAvailableCommands() and calculateMaxCommandWidth()
• Add printConfigAliases() function to render aliases in dedicated section
• Comprehensive unit tests for new functionality

Summary by CodeRabbit

• New Features

  • Help output now shows configuration aliases in a dedicated "ALIASES" section for clearer discovery.
  • Alias commands are marked as config aliases and run as direct subprocesses, preserving their original exit status.
  • Help snapshots now include a telemetry notice banner with opt-out info.

• Bug Fixes

  • Improved alias execution to reliably surface underlying command exit codes.

• Tests

  • Added tests and updated snapshots to validate alias handling and help rendering.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

What

• Support rebuilding devcontainer images from Dockerfile with --replace flag
• Simplify Dockerfile using official install script for automatic version/platform detection
• Add comprehensive test coverage for rebuild operations
• Fix error message formatting to properly wrap YAML examples in code fences
• Add new example atmos.yaml showing devcontainer with custom Dockerfile configuration

Why

The --replace flag now properly handles custom Dockerfile builds, allowing users to rebuild their custom images when they make changes to their Dockerfile. The install script simplification eliminates complexity and ensures automatic detection of Atmos version and platform architecture.

References

Closes support for reproducible custom devcontainer builds with Geodesic base images.

Summary by CodeRabbit

• New Features

  • Added support for building custom devcontainers from Dockerfiles with inline build configuration.
  • Introduced top-level devcontainer configuration structure in atmos.yaml.
  • Enhanced --replace flag with conditional rebuild behavior for custom Dockerfile builds.

• Documentation

  • Added Quick Start section and updated devcontainer examples.
  • Updated shell command documentation with Dockerfile rebuild scenarios.
  • Improved example configuration with new devcontainer structure.

• Bug Fixes

  • Fixed code fence handling to prevent double-wrapping in examples.
  • Optimized image pulling to avoid failures for locally built devcontainer images.

_{✏️ Tip: You can customize this high-level summary in your review settings.}