Matlas Prototype

Author: tip-dteller

.DS_Store

@@ -0,0 +1,53 @@
+---
+alwaysApply: true
+description: Guidance for maintaining CHANGELOG.md and integrating with semantic-release during feature/bugfix development
+---
+
+# Changelog maintenance
+
+This project uses Keep a Changelog style and Semantic Versioning. The changelog lives at [CHANGELOG.md](mdc:CHANGELOG.md) and release automation is handled by semantic-release via [semantic-release workflow](mdc:.github/workflows/semantic-release.yml) and [release config](mdc:.releaserc.json).
+
+## What to edit during development
+
+- Only update the `## [Unreleased]` section of [CHANGELOG.md](mdc:CHANGELOG.md)
+- Group entries under standard headings (include only those that apply):
+  - Added
+  - Changed
+  - Fixed
+  - Deprecated
+  - Removed
+  - Security
+- Use concise, imperative bullet points. Prefer user-facing language over internal implementation details.
+- Link related issues/PRs where helpful using `[#123]` with markdown links.
+- Do not add version numbers, dates, or modify past release sections.
+
+## When to add entries
+
+- When a change is user-visible (CLI flags/behavior, YAML kinds/fields, output format, docs that change user flows), add a bullet under `Unreleased`.
+- If a change is purely internal (refactor, tests, tooling) and has no user impact, skip the changelog.
+
+## Release automation contract
+
+- Do not manually bump versions or author release sections. semantic-release will cut releases and update the changelog based on Conventional Commits.
+- Keep `Unreleased` accurate for in-flight work; automation will reconcile at release time. Avoid duplicating the same change across multiple headings.
+
+## Style examples
+
+```markdown
+## [Unreleased]
+
+### Added
+- New `infra plan --json` output format for CI consumption
+
+### Changed
+- Enhanced `version` command to print build metadata (commit, time)
+
+### Fixed
+- Corrected `database list` pagination when `--limit` is provided
+```
+
+## Cross-feature hygiene
+
+- Align with the feature tracking policy: add a short summary file under `features/` (see [features/TEMPLATE.md](mdc:features/TEMPLATE.md)).
+- If the change adds a new user-facing capability, ensure documentation is updated under `docs/` and an example YAML is added under `examples/`, per repository standards.
+

.cursor/rules/changelog-maintenance.mdc

@@ -0,0 +1,56 @@
+---
+alwaysApply: true
+description: Conventional Commits guidance to power semantic-release and structured CHANGELOG updates
+---
+
+# Conventional Commits
+
+Follow Conventional Commits to enable automated versioning and changelog generation. See config at [release config](mdc:.releaserc.json) and workflow at [semantic-release workflow](mdc:.github/workflows/semantic-release.yml).
+
+## Format
+
+```
+<type>(<optional scope>)<!>: <short summary>
+
+<optional body>
+
+<optional footer(s)>
+```
+
+## Allowed types (common)
+
+- feat: user-facing feature (triggers minor version)
+- fix: bug fix (triggers patch version)
+- perf: performance improvement (patch)
+- refactor: code refactor without behavior change
+- docs: documentation only
+- test: tests only
+- build: build system or deps
+- ci: CI configuration
+- chore: maintenance tasks
+- revert: revert a previous commit
+
+## Breaking changes
+
+- Append `!` after type or scope, or include a `BREAKING CHANGE:` footer.
+- Example: `feat(api)!: drop deprecated v1 endpoints`
+- Footer example:
+  - `BREAKING CHANGE: removed --legacy flag from infra apply`
+
+## Scopes
+
+- Use repository areas for clarity: `infra`, `atlas`, `database`, `cli`, `docs`, `types`, `services`, `apply`, etc.
+- Examples: `feat(infra): add --json to plan`, `fix(database): correct list pagination`
+
+## Body and footers
+
+- Body: explain what and why, not how. Wrap at ~72 chars.
+- Reference issues/PRs in footers:
+  - `Refs: #123`
+  - `Closes: #456`
+
+## Changelog interplay
+
+- Conventional Commits drive release notes. Still update `## [Unreleased]` in [CHANGELOG.md](mdc:CHANGELOG.md) for visibility during development.
+- Keep summaries aligned between commit subjects and changelog bullets.
+

.cursor/rules/conventional-commits.mdc

@@ -0,0 +1,21 @@
+---
+globs: docs/**/*.md
+description: Checklist for authoring Markdown documentation under docs/
+---
+
+# Docs Markdown Authoring Checklist
+
+This rule applies to all Markdown files under `docs/`.
+
+- Include valid Jekyll frontmatter at the top (`--- ... ---`) with at least:
+  - `layout: page` (or `home` where appropriate)
+  - `title: <Concise Title>`
+  - `description:` (recommended)
+  - `permalink:` for top-level navigation pages
+
+- Use relative URLs with Jekyll helpers where possible, e.g. `{{ '/atlas/' | relative_url }}`.
+- Keep pages within the site structure and navigation defined in [docs/_config.yml](mdc:docs/_config.yml).
+- For code examples, use fenced code blocks with language tags and avoid excessive inline code.
+- Images and assets must be placed under `docs/assets/` and referenced with `{{ '/assets/... ' | relative_url }}`.
+- Do not add documentation outside the `docs/` directory or bypass the site theme.
+

.cursor/rules/docs-markdown-checklist.mdc

@@ -0,0 +1,49 @@
+---
+alwaysApply: true
+description: Enforce documentation standards (location under docs/ and GitHub Pages theme usage)
+---
+
+# Documentation Standards
+
+These rules ensure documentation is consistently authored and published.
+
+- All documentation must reside under the `docs/` directory in the repository root.
+- Documentation must use the GitHub Pages Jekyll setup and theme configured in [docs/_config.yml](mdc:docs/_config.yml) (theme `minima`, site served from `baseurl: /matlas-cli`).
+
+## Authoring requirements
+
+- New pages must include Jekyll frontmatter (at least `layout`, `title`, and where applicable `permalink`). Example:
+
+```markdown
+---
+layout: page
+title: My Page
+permalink: /my-page/
+---
+
+# My Page
+
+Content...
+```
+
+- Keep navigation consistent with the site menu. Update the `navigation` list in [docs/_config.yml](mdc:docs/_config.yml) when adding or renaming top-level pages.
+- Styles should flow through the existing pipeline: add SCSS to [docs/_sass/main.scss](mdc:docs/_sass/main.scss) (or additional partials) and import via [docs/assets/css/style.scss](mdc:docs/assets/css/style.scss). Do not add standalone CSS outside `docs/assets/`.
+- Use fenced code blocks with language tags for examples. Syntax highlighting is provided by the site layout and Highlight.js in [docs/_layouts/default.html](mdc:docs/_layouts/default.html).
+
+## Local preview and validation
+
+- Use the documented workflow in [docs/README.md](mdc:docs/README.md):
+
+```bash
+cd docs
+bundle install
+bundle exec jekyll serve
+```
+
+- Ensure the site builds without errors locally and remains compatible with GitHub Pages (respect the theme and plugins defined in [docs/_config.yml](mdc:docs/_config.yml)).
+
+## Do not
+
+- Do not place documentation outside `docs/`.
+- Do not change the configured Jekyll theme or `baseurl` without updating site structure, navigation, and deployment expectations.
+

.cursor/rules/documentation-standards.mdc

@@ -0,0 +1,65 @@
+---
+description: Standardized error handling for concise vs verbose output, real-cause preservation, and consistent formatting across all commands and services
+alwaysApply: false
+---
+### Error Handling Policy
+
+Follow a single, consistent pattern for all errors across the project:
+
+- Use `internal/cli` formatters for all user-facing errors
+  - Short/non-verbose: `ErrorFormatter.Format(err)` from [`internal/cli/errors.go`](mdc:internal/cli/errors.go)
+  - Verbose: `EnhancedErrorFormatter.FormatWithAnalysis(err)` from [`internal/cli/enhanced_errors.go`](mdc:internal/cli/enhanced_errors.go)
+  - Root command wires these already in [`cmd/root.go`](mdc:cmd/root.go). Subcommands must return errors; do not print or handle them locally.
+
+- Always show the real issue
+  - Preserve and propagate the original cause using Go error wrapping with `%w` and helpers in [`internal/cli/enhanced_errors.go`](mdc:internal/cli/enhanced_errors.go) (`WrapWithOperation`, `WrapWithContext`, `WrapWithStack`).
+  - Prefer specific sentinel or HTTP-based classification over generic networking guesses. Use Atlas sentinels from [`internal/clients/atlas/errors.go`](mdc:internal/clients/atlas/errors.go) via `errors.Is` or `atlas.IsNotFound`/`atlas.IsUnauthorized`/etc.
+  - Do not replace the real error with a generic message (e.g., “network error”) when a more specific validation/auth/resource error exists.
+
+- Output contract (must be consistent everywhere)
+  - Non-verbose (`--verbose` not set): show a single, clear message focused on the actionable cause.
+    - Shape: `Error: <concise message>` (the enhanced formatter prefixes when needed and extracts the most specific part).
+  - Verbose (`--verbose` set): include full description with category, root cause, and suggestions when available.
+    - Shape includes sections such as `Error:`, `Suggestions:`, and `Root Cause:` produced by the enhanced formatter.
+  - Never display Cobra usage/help text when returning an error. Use `cli.ConfigureCommandErrorHandling(cmd)` and return the error from `RunE`.
+
+- How to return errors in commands and services
+  - Return, don’t print: return `error` from `RunE`; let root formatting handle output.
+  - Wrap with context and operation to preserve meaning:
+    - `return cli.WrapWithOperation(err, "<operation>", <resourceID>)`
+    - For validation: `return cli.FormatValidationError(field, value, reason)`
+    - For additional guidance: `return cli.WrapWithSuggestion(err, "<next step>")`
+  - When calling Atlas SDK, map errors to sentinels in the client and use `errors.Is`/`atlas.Is*` to branch logic instead of string matching.
+
+- Classification precedence (to avoid misleading “network” diagnoses)
+  - Prefer: Validation/Configuration/AuthZ/AuthN > Resource (exists/not found/conflict) > HTTP status mapping > Network/Timeout fallbacks.
+  - In verbose mode, always include the original `err.Error()` content so the true cause is visible during debugging.
+
+- Logging and secrecy
+  - Use the structured logger from [`internal/logging/logger.go`](mdc:internal/logging/logger.go) for debug/diagnostic context. Do not `fmt.Println` raw errors.
+  - Ensure secrets are masked by relying on the logging package; do not embed credentials in error messages.
+
+### Examples
+
+```go
+// Good: preserve cause and context
+if err := svc.CreateCluster(ctx, req); err != nil {
+    return cli.WrapWithOperation(err, "create_cluster", req.Name)
+}
+
+// Good: specific validation error
+if req.Name == "" {
+    return cli.FormatValidationError("cluster name", req.Name, "must not be empty")
+}
+
+// Good: suggestion to help user fix
+return cli.WrapWithSuggestion(err, "Use --timeout 5m or check IP access list")
+```
+
+### Acceptance criteria for new/changed code
+
+- Non-verbose execution prints a single concise line without suggestions or stack details.
+- Verbose execution prints full enhanced output including `Suggestions:` and/or `Root Cause:` when available.
+- Real cause is preserved in verbose output; no generic “network error” replaces a more precise error.
+- All commands rely on central formatting; no command prints errors directly.
+

.cursor/rules/error-handling.mdc

@@ -0,0 +1,75 @@
+---
+alwaysApply: true
+description: Ensure every new feature supports both CLI and YAML ApplyDocument, and clearly distinguishes INFRA vs non-INFRA commands.
+---
+
+# Feature Interface Consistency (CLI + YAML ApplyDocument)
+
+When introducing any new user-facing feature, always provide both:
+
+- CLI interface with appropriate subcommands and flags
+- YAML ApplyDocument support via a dedicated YAML kind (create one if it does not exist)
+
+This policy prevents drift between interfaces and guarantees first-class automation support.
+
+## Command taxonomy: INFRA vs other commands
+
+- INFRA-related functionality belongs under `cmd/infra` (e.g., plan/apply/diff/show/validate flows)
+  - Keep business logic in the `internal/apply` pipeline and `internal/services/*` layers
+  - Ensure operations are surfaced in: `apply`, `plan`, `diff`, `show`, `validate`
+
+- Non-INFRA functionality belongs in its domain-specific command group:
+  - `cmd/atlas/*` for Atlas resources and account/project/cluster/user/network surfaces
+  - `cmd/database/*` for MongoDB database-level operations
+  - `cmd/config/*` for CLI configuration and credentials
+
+Both paths must call the same service-layer code in `internal/services/*` to avoid divergence.
+
+## CLI requirements
+
+- Add or extend a subcommand in the correct command group (`cmd/infra`, `cmd/atlas`, `cmd/database`, `cmd/config`)
+- Provide flags that are consistent with existing naming and patterns
+- Validate inputs and route requests through shared services in `internal/services/*`
+- Update command help and autocompletion if applicable
+
+Relevant entry points and patterns:
+- `cmd/infra/*.go`
+- `cmd/atlas/**/*.go`
+- `cmd/database/**/*.go`
+- `internal/services/*`
+
+## YAML (ApplyDocument) requirements
+
+- If a unique YAML kind already exists for the object, ensure ApplyDocument supports the new fields/behaviors.
+- If no unique YAML kind exists, create one and implement end-to-end support:
+  - Define or extend types in: [internal/types/apply.go](mdc:internal/types/apply.go), [internal/types/*.go](mdc:internal/types)
+  - Load and map kinds in: [internal/apply/loader.go](mdc:internal/apply/loader.go)
+  - Validate schema and semantics in: [internal/apply/validation.go](mdc:internal/apply/validation.go), [internal/validation/schema.go](mdc:internal/validation/schema.go)
+  - Wire execution to services in: [internal/apply/executor.go](mdc:internal/apply/executor.go), [internal/apply/fetchers.go](mdc:internal/apply/fetchers.go)
+  - Keep diff/dry-run output coherent in: [internal/apply/diff_formatter.go](mdc:internal/apply/diff_formatter.go), [internal/apply/dryrun_formatter.go](mdc:internal/apply/dryrun_formatter.go)
+
+Both CLI and YAML paths must use the same service-layer implementations in `internal/services/*` (e.g., [internal/services/atlas](mdc:internal/services/atlas), [internal/services/database](mdc:internal/services/database)).
+
+## Documentation and examples
+
+- Add a minimal YAML example to `examples/` and reference it from `docs/`
+- Update relevant docs pages under `docs/` to describe the CLI flags and YAML kind usage
+
+## Per-feature tracking
+
+To ensure clarity and traceability, every feature MUST include a concise per-feature summary file:
+
+- Location: `features/`
+- Template: `features/TEMPLATE.md`
+- Naming: `YYYY-MM-DD-<short-slug>.md` (e.g., `2025-08-13-temporary-users.md`) or `FTR-<id>-<short-slug>.md`
+- Minimum content: a top-level title (`Feature: <name>`) and a short "Summary" (2–6 sentences)
+- Recommended content: sections mapping changes across CLI, YAML ApplyDocument, service layer, apply pipeline, types, tests, docs, and any breaking/migration notes
+
+## Acceptance checklist (must have)
+
+- CLI subcommand/flags added in the correct command group
+- YAML kind exists and is supported by ApplyDocument end-to-end
+- Both interfaces call the same `internal/services/*` logic
+- Docs updated and example YAML added
+ - Per-feature tracking file added under `features/` using the template, with a filled Summary and links to relevant code/docs
+

.cursor/rules/feature-format-support.mdc

@@ -0,0 +1,38 @@
+---
+alwaysApply: false
+---
+## Live Tests Policy (CLI + YAML)
+
+This repository requires comprehensive, live tests for both CLI and YAML paths. Follow these rules when creating or updating tests:
+
+- **Location**: Place all live tests under `scripts/` (prefer `scripts/test/`), one focused script per surface. Entry point and orchestration live in [`scripts/test.sh`](mdc:scripts/test.sh).
+
+- **Coverage requirements**: Each test script must exercise the maximum breadth of its domain:
+  - Happy-path for every relevant command and subcommand of the surface
+  - Flag coverage: required, optional, combinations, mutually exclusive flags, and defaults
+  - Output variants: at least text and JSON, plus YAML where relevant
+  - Negative cases: missing/invalid arguments, invalid types, unsupported combinations, permission/auth failures
+  - Idempotency: repeated runs don’t drift; add dry-run checks where available
+
+- **Dual-path requirement**: For any supported capability, test both interfaces:
+  - CLI subcommands and flags under `cmd/*`
+  - YAML ApplyDocument flows handled by `cmd/infra/*` via `validate`, `plan`, `diff`, `show`, `apply`, and `destroy`
+
+- **Runner integration**: All new live tests must be invocable from the main runner:
+  - Add a dedicated mode/subcommand in [`scripts/test.sh`](mdc:scripts/test.sh)
+  - Ensure discoverability in help/usage and include the test in appropriate aggregates (e.g., `all`, `comprehensive`)
+  - Update documentation in [`scripts/README.md`](mdc:scripts/README.md)
+
+- **Script conventions**:
+  - Use `#!/usr/bin/env bash` and `set -euo pipefail`
+  - Validate environment (.env support OK) and print clear diagnostics
+  - Provide `--dry-run`, `--verbose`, and `--timeout` flags when applicable
+  - Track created resources and guarantee cleanup on EXIT/INT/TERM
+  - Emit non-zero exit codes on failures; write artifacts to `test-reports/`
+
+- **Naming**:
+  - Script file: `scripts/test/<domain>.sh`
+  - Test modes within script: granular selectors for subsets (e.g., `validation`, `errors`, `workflow`)
+
+By policy, tests that do not meet these criteria should be extended to include missing command paths, flag combos, and negative validations before merge.
+