cloudposse/atmos v1.204.0-rc.3

on GitHub

• Enforce single stack name identity - each stack now has exactly ONE valid identifier
• Add filename-based identity - stacks work with just filenames when no naming config exists (zero-config for newcomers)
• Improve error messages - when using an invalid stack name, error now says "invalid stack" and provides hints suggesting the correct name and how to list available stacks
• Fix ProcessStacks to recognize the stack manifest name field when matching stacks
• Add JSON schema documentation for the name field
• Add PRD documenting the stack name identity rules
• Add CLI smoke tests with golden snapshots

why

Issue 1: Manifest name not recognized

When a stack manifest has name: "my-explicit-stack", users expect to use that name in commands:

atmos tf plan vpc -s my-explicit-stack

Previously this failed with "Could not find the component vpc in the stack".

Issue 2: Multiple names worked (incorrect)

After the initial fix, ALL of these worked for the same stack:

atmos tf plan vpc -s my-explicit-stack  # explicit name
atmos tf plan vpc -s prod-ue1           # generated from name_template
atmos tf plan vpc -s legacy-prod        # filename

This is incorrect - a stack should have exactly ONE valid identifier.

Issue 3: Misleading error message

When using an invalid stack name (e.g., filename when explicit name exists), the error said "invalid component" instead of "invalid stack":

**Error:** invalid component

Could not find the component vpc in the stack legacy-prod.

New: Zero-config for newcomers

When no name, name_template, or name_pattern is configured, stacks are now identified by their filename. This lets newcomers get started without any naming configuration:

# stacks/prod.yaml - no naming config needed
components:
  terraform:
    vpc:
      vars:
        cidr: "10.0.0.0/16"

# Just works!
atmos terraform plan vpc -s prod

Stack Name Identity Rule

Each stack has exactly ONE valid identifier based on precedence:

Evidence

my-legacy-prod-stack
no-name-prod

{
  "atmos_component": "vpc",
  "atmos_stack": "no-name-prod",
  "atmos_stack_file": "no-name-prod",
  "stack": "no-name-prod",
  "workspace": "no-name-prod"
}

{
  "atmos_component": "vpc",
  "atmos_stack": "my-legacy-prod-stack",
  "atmos_stack_file": "legacy-prod",
  "atmos_manifest": "legacy-prod",
  "stack": "my-legacy-prod-stack",
  "workspace": "my-legacy-prod-stack"
}

# Error

**Error:** invalid stack

## Explanation

Stack legacy-prod not found.

## Hints

💡 Did you mean my-legacy-prod-stack?

💡 Run atmos list stacks to see all available stacks.

# Error

**Error:** invalid stack

## Explanation

Stack legacy-prod not found.

## Hints

💡 Did you mean my-legacy-prod-stack?

💡 Run atmos list stacks to see all available stacks.

Changes

• errors/errors.go: Add ErrInvalidStack sentinel error
• internal/exec/utils.go: Enforce single-identity matching in findComponentInStacks; return helpful error with suggestion when filename is used for stack with explicit name; enable filename fallback in processStackContextPrefix
• internal/exec/stack_manifest_name_test.go: Add tests for identity enforcement, filename fallback, and improved error messages
• tests/test-cases/stack-manifest-name.yaml: Add CLI smoke tests with golden snapshots for stack name identity
• pkg/datafetcher/schema/atmos/manifest/1.0.json: Add schema documentation for name field
• docs/prd/stack-name-identity.md: PRD documenting the specification (status: Implemented)
• website/blog/2026-01-06-stack-name-identity.mdx: Blog post documenting the changes
• website/src/data/roadmap.js: Add "Filename-based stack identity" to DX roadmap

References

• Closes #1932

Summary by CodeRabbit

• New Features

  • Single canonical stack identity with precedence (name → name_template → name_pattern → filename), zero‑config filename naming, and clearer "Did you mean…?" suggestions for invalid stacks.

• Documentation

  • Added product requirements and a blog post explaining identity rules, examples, migration guidance, and UX notes.

• Tests

  • Expanded test suites and updated snapshots to validate naming precedence, listing/describe behavior, and suggestion messages.

• Chores

  • Roadmap updated and CLI telemetry notice added to outputs.

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

• Upgrades all Docusaurus packages to version 3.9.2 (latest stable)
• Updates package.json and pnpm-lock.yaml dependencies

why

The upgrade includes support for DocSearch v4 with AI-powered search features, improved i18n configuration options for multi-domain deployments, React 19 compatibility fixes, and new build APIs.

references

• Docusaurus 3.9 Release Notes

Summary by CodeRabbit

• New Features

  • Ask AI conversational search now integrated into documentation, powered by DocSearch v4 and ChatGPT for natural language queries and contextual answers.

• Documentation

  • Added Algolia search indexing setup guide and Ask AI feature announcement blog post.

• Chores

  • Updated documentation framework dependencies and roadmap entries.

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

• Adds robots.txt to website/static/ for search engine indexing
• Includes Algolia crawler verification token
• Explicitly allows all crawlers with User-agent: * and Allow: /
• References sitemap for efficient crawler discovery

why

• Improves search engine discoverability of the Atmos documentation
• Enables Algolia crawler verification for site search functionality
• Maximizes indexing potential by explicitly allowing all crawlers

references

• Algolia crawler verification: 10F61B92D9EB1214

Summary by CodeRabbit

• Chores
  • Added web crawler configuration to improve site indexing and point crawlers to the sitemap.
  • Updated deployment configuration to make the site base URL configurable via an environment variable, enabling PR-specific preview hosts during builds.

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

• Fix ATMOS_IDENTITY=false not being recognized in the legacy ProcessCommandLineArgs() code path
• Create shared NormalizeIdentityValue() function in pkg/config/identity.go to centralize normalization logic
• Add comprehensive tests for ATMOS_IDENTITY=false, 0, no, off in cli_utils_test.go
• Refactor three duplicate normalizeIdentityValue() functions to use shared implementation

why

PR #1900 fixed ATMOS_IDENTITY=false normalization for the flag parsing path (pkg/flags/global_registry.go), but missed a separate code path in internal/exec/cli_utils.go that reads ATMOS_IDENTITY directly via os.Getenv().

Two independent code paths exist:

1. Flag path (pkg/flags/global_registry.go): Used by Cobra commands with proper global flag inheritance - ✅ Fixed in PR #1900
2. Legacy path (internal/exec/cli_utils.go:ProcessCommandLineArgs()): Used by terraform commands - ❌ Not fixed until this PR

The legacy path was added in PR #1720 (Oct 2025) without normalization. When PR #1900 fixed the flag path (Dec 2025), this code path was missed, causing the regression reported in issue #1931.

Verified with user's reproduction case:

# From issue #1931's auth_bug.tar.gz
ATMOS_IDENTITY=false atmos terraform plan myapp -s dev
# Before: "Error: identity not found" (treats "false" as identity name)
# After: Terraform plan runs successfully with auth disabled

Note: This class of problems (duplicate code paths for auth handling) should be eliminated by #1919, which refactors Atmos auth to use the command registry pattern. Once that lands, there will be a single, unified code path for identity/auth handling across all commands.

references

Closes #1931
Related: #1900 (partial fix), #1720 (introduced the unfixed code path), #1919 (architectural fix to prevent this class of bugs)

Summary by CodeRabbit

• Refactor

  • Consolidated identity value normalization logic across the system. Identity values are now consistently processed to treat false-like representations (false, 0, no, off in various cases) uniformly, regardless of whether they originate from environment variables, configuration files, or command-line arguments.

• Tests

  • Added test coverage for identity value normalization with comprehensive edge case handling.

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

• Add validation to detect and prevent custom command flag conflicts with global persistent flags
• Return actionable error messages instead of panicking when conflicts are detected
• Query global flags dynamically to ensure new flags are automatically protected
• Update existing tests to use non-conflicting flag names

why

When custom commands in atmos.yaml define flags that conflict with global flags, Cobra would panic with a stack overflow. This fix gracefully detects conflicts before flag registration and returns a clear error message using the ErrorBuilder pattern, giving users explicit guidance on how to resolve the issue.

references

No GitHub issues referenced. This is a critical bug fix improving stability and user experience when working with custom commands.

Summary by CodeRabbit

• New Features

  • Runtime validation blocks custom commands from defining flag names or shorthands that conflict with global/parent reserved flags (including the identity flag); conflicts yield a clear reserved-flag error.

• Changes

  • Added a public reserved-flag error sentinel.
  • Renamed debug flag from verbose to customDebug (shorthand d).
  • Example/fixture command renamed from terraform to tf-custom; CLI help listings updated accordingly.

• Tests

  • Extensive unit and integration tests covering flag reservation, shorthands, nesting, inheritance, defaults, and error reporting.

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