Improve Atmos help

[samtholiya]

what

We would be fixing the following UX issues with help in this pr:

• atmos about non-existent should show usage:
  

• Double dash in flags of atmos terraform --help and examples rendering using markdown if available.
  

• Fixed atmos workflow --file example.yaml bug for markdown. Now it also exits with exit code 1.
  

• Updated Default error logger with markdown support.
  

• Added custom alias help support so that alias in config should also be displayed in help.
  

• Updated the workflow name invalid UI
  

• Invalid custom command config now shows better help
  

• Invalid flag usage added
  

why

• Outputting markdown in help descriptions makes it easier to visually parse
• Markdown stylesheet keeps formatting consistent, without each developer needing to know the style guide
• Changed the way error that exit are displayed, to show more helpful information and usage examples, also formatted in markdown
• Aliases were not shown in help, making their discoverability difficult

references

• DEV-2950
• DEV-2690

Summary by CodeRabbit

• Enhanced CLI Experience

  • Error messages, usage, and help outputs across multiple Atmos commands are now displayed using a clear Markdown format. Users receive more descriptive feedback for invalid commands or flags and improved prompts during execution.
  • Specific error messages have been improved to include context and suggestions for available workflows and commands, particularly when workflows are not found or when invalid commands are issued.
  • New error messages provide clear guidance when invalid or non-existent commands are invoked, listing valid options for user convenience.
  • The command atmos terraform now specifies required subcommands and provides usage examples when invoked incorrectly.

• Updated Documentation

  • Command usage examples and help texts for key functionality (such as for Atmos “about,” “terraform,” “workflow,” “helmfile,” and “atlantis” commands) have been refined, offering clearer guidance and structured instructions for end-user workflows.
  • New sections have been added to documentation, detailing how to apply changes to Terraform components and providing examples for using workflow commands effectively.
  • Additional help messages have been introduced for commands like atmos validate editorconfig, enhancing user understanding of available flags and options.
  • Documentation updates reflect the latest versions of Atmos and Geodesic tools, ensuring users have the most current information for their workflows.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

cmd/cmd_utils.go (2)

632-645: Remove unreachable return statement.

The function calls os.Exit(1) before returning, making the return statement unreachable.

Apply this diff to remove the unreachable code:

 func showFlagUsageAndExit(cmd *cobra.Command, err error) error {
     unknownCommand := fmt.Sprintf("%v for command `%s`\n\n", err.Error(), cmd.CommandPath())
     args := strings.Split(err.Error(), ": ")
     if len(args) == 2 {
         if strings.Contains(args[0], "flag needs an argument") {
             unknownCommand = fmt.Sprintf("`%s` %s for command `%s`\n\n", args[1], args[0], cmd.CommandPath())
         } else {
             unknownCommand = fmt.Sprintf("%s `%s` for command `%s`\n\n", args[0], args[1], cmd.CommandPath())
         }
     }
     showUsageExample(cmd, unknownCommand)
     os.Exit(1)
-    return nil
 }

---

225-227: Simplify error creation using fmt.Errorf.

Replace errors.New(fmt.Sprintf(...)) with fmt.Errorf(...) for better readability.

Apply this diff to simplify the error creation:

-            u.PrintErrorMarkdownAndExit("Invalid command", errors.New(
-                fmt.Sprintf("The `%s` command has no steps or subcommands configured.", cmd.CommandPath()),
-            ), "https://atmos.tools/cli/configuration/commands")
+            u.PrintErrorMarkdownAndExit("Invalid command", 
+                fmt.Errorf("The `%s` command has no steps or subcommands configured.", cmd.CommandPath()),
+                "https://atmos.tools/cli/configuration/commands")

🧰 Tools

🪛 golangci-lint (1.62.2)

225-225: S1028: should use fmt.Errorf(...) instead of errors.New(fmt.Sprintf(...))

(gosimple)

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3e4cee8 and 46e53e2.

📒 Files selected for processing (1)

• cmd/cmd_utils.go (5 hunks)

🧰 Additional context used

🧠 Learnings (1)

cmd/cmd_utils.go (2)

Learnt from: samtholiya
PR: cloudposse/atmos#914
File: cmd/root.go:172-178
Timestamp: 2025-01-18T15:18:35.475Z
Learning: The `showUsageAndExit` function in `cmd/cmd_utils.go` provides user feedback by showing error messages, command suggestions, and valid subcommands before terminating the program with `os.Exit(1)`. It never returns to the caller, making error handling unnecessary for calls to this function.

Learnt from: samtholiya
PR: cloudposse/atmos#959
File: cmd/cmd_utils.go:121-148
Timestamp: 2025-02-03T05:57:18.407Z
Learning: The Atmos CLI should fail fast (exit) when encountering configuration errors, including command alias configuration issues, to prevent undefined behavior. Use LogErrorAndExit instead of returning errors in such cases.

🪛 golangci-lint (1.62.2)

cmd/cmd_utils.go

225-225: S1028: should use fmt.Errorf(...) instead of errors.New(fmt.Sprintf(...))

(gosimple)

⏰ Context from checks skipped due to timeout of 90000ms (2)

• GitHub Check: Build (windows-latest, windows)
• GitHub Check: Summary

🔇 Additional comments (2)

cmd/cmd_utils.go (2)

49-53: LGTM! Command alias handling is well-implemented.

The implementation correctly processes command aliases by recursively building the command hierarchy and failing fast on invalid configurations. This aligns with the CLI's error handling strategy.

Also applies to: 122-149

---

620-630: LGTM! Enhanced error handling with markdown support.

The function now provides better error messages by utilizing markdown formatting and falling back to custom usage when needed.

[mergify]

Important

Cloud Posse Engineering Team Review Required

This pull request modifies files that require Cloud Posse's review. Please be patient, and a core maintainer will review your changes.

To expedite this process, reach out to us on Slack in the #pr-reviews channel.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

tests/test-cases/help-and-usage.yaml (1)

59-64: Consider using a shared template for update notifications.

The update notification messages are duplicated across multiple test cases. This could make maintenance challenging if the notification format needs to be updated.

Consider extracting these common expectations into a shared template:

-      diff:
-        - "──────────────────────────────────────────────────────────────"
-        - "Update available!"
-        - "Atmos Releases:"
-        - "Install Atmos:"
+      diff: !include update_notification_template.yaml

Also applies to: 76-81, 148-153, 164-169, 204-209, 221-226, 247-252, 263-268, 292-297, 309-314, 326-331, 344-349, 362-367, 400-405, 419-424, 458-463

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 46e53e2 and 67ee36d.

⛔ Files ignored due to path filters (1)

• go.sum is excluded by !**/*.sum

📒 Files selected for processing (4)

• examples/quick-start-advanced/Dockerfile (1 hunks)
• go.mod (1 hunks)
• tests/test-cases/help-and-usage.yaml (16 hunks)
• website/docs/integrations/atlantis.mdx (1 hunks)

✅ Files skipped from review due to trivial changes (2)

• examples/quick-start-advanced/Dockerfile
• website/docs/integrations/atlantis.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• go.mod

⏰ Context from checks skipped due to timeout of 90000ms (3)

• GitHub Check: Build (macos-latest, macos)
• GitHub Check: Build (windows-latest, windows)
• GitHub Check: Summary

🔇 Additional comments (4)

tests/test-cases/help-and-usage.yaml (4)

4-4: LGTM! Consistent addition of snapshot testing.

The addition of snapshot: true across all test cases is a good practice. This will help maintain consistent test outputs and make it easier to track changes in CLI behavior.

Also applies to: 14-14, 24-24, 37-37, 50-50, 67-67, 84-84, 95-95, 107-107, 119-119, 129-129, 140-140, 156-156, 172-172, 184-184, 195-195, 212-212, 229-229, 239-239, 255-255, 272-272, 283-283, 300-300, 317-317, 334-334, 352-352, 376-376, 389-389, 427-427

---

437-464: LGTM! Well-structured test cases for atmos about command.

The new test cases for atmos about command are well-structured and cover both error cases and help output scenarios.

---

464-476: LGTM! Good coverage for invalid flag usage.

The test case for atmos version --check --non-existent ensures proper handling of invalid flag combinations.

---

476-487: LGTM! Good test coverage for alias subcommands.

The test case for atmos terraform --help in the context of alias subcommands ensures that help output is correctly displayed for custom configurations.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

tests/test-cases/help-and-usage.yaml (2)

4-4: Consider consolidating snapshot configuration.

The snapshot: true attribute is being added to most test cases. This could be moved to a common configuration to reduce repetition.

Consider using YAML anchors and aliases to define a common base for snapshot tests:

+ _snapshot_base: &snapshot_base
+   snapshot: true

  tests:
    - name: atmos non-existent
      enabled: true
-     snapshot: true
+     <<: *snapshot_base
      description: "Ensure atmos CLI returns an error for a non-existent command."

Also applies to: 14-14, 24-24, 40-40, 56-56, 73-73, 90-90, 101-101, 113-113, 125-125, 145-145, 161-161, 177-177, 189-189, 200-200, 217-217, 234-234, 244-244, 260-260, 277-277, 288-288, 305-305, 322-322, 339-339, 357-357, 381-381, 394-394, 414-414

---

32-37: Consider consolidating common diff expectations.

The same diff expectations are repeated across multiple test cases. This could be consolidated to improve maintainability.

Consider using YAML anchors and aliases for common diff expectations:

+ _help_diff: &help_diff
+   diff:
+     - "──────────────────────────────────────────────────────────────"
+     - "Update available!"
+     - "Atmos Releases:"
+     - "Install Atmos:"

  tests:
    - name: atmos terraform help
      expect:
-       diff:
-         - "──────────────────────────────────────────────────────────"
-         - "Update available!"
-         - "Atmos Releases:"
-         - "Install Atmos:"
+       <<: *help_diff

Also applies to: 48-53, 65-70, 82-87, 153-158, 169-174, 209-214, 226-231, 252-257, 268-273, 297-302, 314-319, 331-336, 349-354, 367-372, 405-410, 424-429, 462-467

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 67ee36d and 8354b03.

📒 Files selected for processing (3)

• tests/snapshots/TestCLICommands_atmos_terraform_--help.stdout.golden (1 hunks)
• tests/snapshots/TestCLICommands_atmos_terraform_help.stdout.golden (1 hunks)
• tests/test-cases/help-and-usage.yaml (15 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

• tests/snapshots/TestCLICommands_atmos_terraform_help.stdout.golden
• tests/snapshots/TestCLICommands_atmos_terraform_--help.stdout.golden

⏰ Context from checks skipped due to timeout of 90000ms (5)

• GitHub Check: Build (windows-latest, windows)
• GitHub Check: Build (ubuntu-latest, linux)
• GitHub Check: website-deploy-preview
• GitHub Check: Analyze (go)
• GitHub Check: Summary

🔇 Additional comments (2)

tests/test-cases/help-and-usage.yaml (2)

441-491: Well-structured new test cases!

The new test cases for about, version, and terraform commands enhance the test coverage for error handling and help output scenarios. They follow consistent patterns and have clear descriptions.

---

133-142: Good improvements to existing test cases!

The modifications to the helmfile and validate editorconfig test cases align well with the PR's objective of improving help and error handling. The descriptions are now more accurate and the test cases maintain consistency with the new error handling approach.

Also applies to: 430-440

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

tests/test-cases/help-and-usage.yaml (2)

439-489: LGTM! New test cases enhance coverage.

The new test cases for atmos about and atmos version commands improve the test coverage for error handling and help output. The test in the fixtures/scenarios/subcommand-alias directory is particularly valuable for verifying custom alias functionality.

However, consider adding test cases for the following scenarios to make the test suite more comprehensive:

1. Invalid alias configurations
2. Multiple aliases for the same command
3. Nested alias commands

---

371-378: Consider standardizing stdout/stderr expectations.

While most test cases use the diff field for output validation, this test case uses explicit stdout and stderr fields. Consider standardizing the approach across all test cases.

-      stdout:
-        - "Flags:"
-        - "--affected-only"
-        - "--config-template"
-      stderr:
-        - "^$"
+      diff:
+        - "──────────────────────────────────────────────────────────────"
+        - "Update available!"
+        - "Atmos Releases:"
+        - "Install Atmos:"
+        - "Flags:"
+        - "--affected-only"
+        - "--config-template"

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8354b03 and 64424ee.

📒 Files selected for processing (1)

• tests/test-cases/help-and-usage.yaml (15 hunks)

⏰ Context from checks skipped due to timeout of 90000ms (3)

• GitHub Check: Build (windows-latest, windows)
• GitHub Check: website-deploy-preview
• GitHub Check: Summary

🔇 Additional comments (2)

tests/test-cases/help-and-usage.yaml (2)

4-4: LGTM! Consistent addition of snapshot testing.

The addition of snapshot: true across test cases is a solid improvement. This will help catch unintended changes in CLI output.

Also applies to: 14-14, 24-24, 40-40, 56-56, 73-73, 90-90, 101-101, 113-113, 125-125, 135-135, 145-145, 161-161, 188-188, 199-199, 216-216, 233-233, 243-243, 259-259, 276-276, 287-287, 304-304, 321-321, 338-338, 356-356

---

32-37: Standardize help output expectations.

The standardized diff expectations for help output will ensure consistent formatting and update notifications across all commands.

Also applies to: 48-53, 65-70, 82-87, 153-158, 169-174, 208-213, 225-230, 251-256, 267-272, 296-301, 313-318, 330-335, 348-353, 366-371, 403-408, 422-427

[github-actions]

These changes were released in v1.162.0.