cdk-cost-analyzer 0.1.1

package/.kiro/specs/repository-cleanup/design.md

@@ -0,0 +1,283 @@
+# Design Document - Repository Cleanup
+
+## Overview
+
+This design outlines the approach for cleaning up and reorganizing the CDK Cost Analyzer repository. The cleanup will consolidate documentation into a `docs/` folder, organize test artifacts appropriately, remove obsolete files, and ensure compliance with all steering guidelines. The goal is to create a professional, well-organized repository structure that follows Node.js/TypeScript best practices.
+
+## Architecture
+
+The cleanup is a structural reorganization task that involves:
+
+1. **File Analysis**: Identify all files in the repository and categorize them
+2. **Documentation Consolidation**: Move supplementary docs to `docs/` folder
+3. **Test Artifact Organization**: Move or remove manual test files
+4. **Obsolete File Removal**: Remove files that are no longer needed
+5. **Reference Updates**: Update any links or references to moved files
+6. **Validation**: Ensure all steering guidelines are followed
+
+## Components and Interfaces
+
+### File Categories
+
+The repository files fall into these categories:
+
+1. **Essential Root Files** (keep in root):
+   - `README.md` - Main project documentation
+   - `package.json`, `package-lock.json` - NPM configuration
+   - `tsconfig.json` - TypeScript configuration
+   - `vitest.config.mts` - Test configuration
+   - `.gitignore` - Git configuration
+
+2. **Supplementary Documentation** (move to `docs/`):
+   - `IMPLEMENTATION.md` - Technical implementation details
+   - `NEXT-STEPS.md` - Project status and next steps
+
+3. **Test Artifacts** (organize or remove):
+   - `test-api.js` - Manual test script
+   - `base.json`, `target.json` - Simple test templates
+   - `complex-base.json`, `complex-target.json` - Complex test templates
+   - `verify-structure.sh` - Verification script
+
+4. **Test Projects** (keep as-is):
+   - `test-cdk-project/` - Complete test CDK project with its own documentation
+
+5. **Source and Build** (keep as-is):
+   - `src/` - Source code
+   - `test/` - Automated tests
+   - `dist/` - Build output
+   - `node_modules/` - Dependencies
+
+6. **Configuration Directories** (keep as-is):
+   - `.kiro/` - Kiro configuration and specs
+   - `.git/` - Git repository data
+
+## Data Models
+
+### Repository Structure (Before)
+
+```
+cdk-cost-analyzer/
+├── README.md
+├── IMPLEMENTATION.md          ← Move to docs/
+├── NEXT-STEPS.md             ← Move to docs/
+├── package.json
+├── tsconfig.json
+├── vitest.config.mts
+├── test-api.js               ← Move to examples/ or remove
+├── base.json                 ← Move to examples/
+├── target.json               ← Move to examples/
+├── complex-base.json         ← Move to examples/
+├── complex-target.json       ← Move to examples/
+├── verify-structure.sh       ← Evaluate if needed
+├── src/
+├── test/
+├── test-cdk-project/
+├── dist/
+├── node_modules/
+└── .kiro/
+```
+
+### Repository Structure (After)
+
+```
+cdk-cost-analyzer/
+├── README.md
+├── package.json
+├── tsconfig.json
+├── vitest.config.mts
+├── .gitignore
+├── docs/
+│   ├── IMPLEMENTATION.md
+│   └── DEVELOPMENT.md        ← Renamed from NEXT-STEPS.md
+├── examples/
+│   ├── simple/
+│   │   ├── base.json
+│   │   └── target.json
+│   ├── complex/
+│   │   ├── base.json
+│   │   └── target.json
+│   └── api-usage.js          ← Renamed from test-api.js
+├── src/
+├── test/
+├── test-cdk-project/
+├── dist/
+├── node_modules/
+└── .kiro/
+```
+
+
+## Correctness Properties
+
+*A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
+
+
+### Property Reflection
+
+After reviewing the prework analysis, several properties can be consolidated:
+
+- Properties 1.4 and 5.3 are identical (no files with backup/temp suffixes) - keep as one property
+- Properties 2.3 and 3.4 both check link validity - combine into one comprehensive property
+- Properties 3.3 and 4.5 both check file preservation - combine into one property about preserving functional files
+
+The remaining properties provide unique validation value and should be kept.
+
+### Correctness Properties
+
+Property 1: No temporary or backup file suffixes
+*For any* file in the repository, the filename should not contain suffixes like `_backup`, `_old`, `_fixed`, `_clean`, `_temp`, or similar temporary naming patterns
+**Validates: Requirements 1.4, 5.3**
+
+Property 2: All documentation links are valid
+*For any* markdown file in the repository, all internal links (links to other files in the repository) should point to files that exist
+**Validates: Requirements 2.3, 3.4**
+
+Property 3: Functional files are preserved
+*For any* file in `src/`, `test/`, or configuration files (package.json, tsconfig.json, vitest.config.mts, .gitignore) that existed before cleanup, that file should still exist after cleanup
+**Validates: Requirements 3.3, 4.5**
+
+Note: Most acceptance criteria in this feature are about specific final states (examples) rather than universal properties, which is appropriate for a one-time cleanup task. The properties above capture the key invariants that should hold across all files.
+
+## Error Handling
+
+### File Operations
+
+- **Missing files**: If a file to be moved doesn't exist, log a warning and continue
+- **Permission errors**: If a file cannot be moved due to permissions, report error and stop
+- **Existing destinations**: If destination file already exists, report error and ask for confirmation
+
+### Link Updates
+
+- **Broken links found**: Report all broken links before making changes
+- **Ambiguous paths**: If a link could refer to multiple files, report and ask for clarification
+- **External links**: Do not modify external links (http://, https://)
+
+### Validation
+
+- **Steering guideline violations**: Report any violations found but don't block cleanup
+- **Structure issues**: Report if expected directories are missing
+
+## Testing Strategy
+
+### Manual Verification
+
+Since this is a one-time cleanup task, testing will primarily be manual verification:
+
+1. **Before Cleanup Snapshot**: Document current repository state
+2. **Execute Cleanup**: Perform file moves and deletions
+3. **Verify Structure**: Check that new structure matches design
+4. **Verify Links**: Check that all documentation links work
+5. **Verify Build**: Run `npm run build` to ensure nothing broke
+6. **Verify Tests**: Run `npm test` to ensure tests still pass
+7. **Verify CLI**: Test CLI functionality with examples
+
+### Property-Based Tests
+
+While this is a cleanup task, we can write simple verification scripts:
+
+- **Property 1 Test**: Script to find files with temporary suffixes
+- **Property 2 Test**: Script to validate all markdown links
+- **Property 3 Test**: Script to compare file lists before/after
+
+These scripts can be run after cleanup to verify correctness.
+
+### Checklist Validation
+
+After cleanup, verify:
+
+- [ ] Root directory contains only essential files
+- [ ] All supplementary docs are in `docs/`
+- [ ] README.md is in root
+- [ ] Test artifacts are in `examples/` or removed
+- [ ] No files with temporary suffixes exist
+- [ ] All markdown links are valid
+- [ ] `npm run build` succeeds
+- [ ] `npm test` passes
+- [ ] CLI works with example files
+- [ ] Test project documentation is unchanged
+- [ ] No duplicate files exist
+
+## Implementation Approach
+
+### Phase 1: Preparation
+
+1. Create new directory structure (`docs/`, `examples/`)
+2. Document current file locations for reference
+3. Identify all files to be moved or removed
+
+### Phase 2: Documentation Consolidation
+
+1. Create `docs/` folder
+2. Move `IMPLEMENTATION.md` to `docs/IMPLEMENTATION.md`
+3. Rename and move `NEXT-STEPS.md` to `docs/DEVELOPMENT.md`
+4. Update any links in README.md that reference moved files
+
+### Phase 3: Test Artifact Organization
+
+1. Create `examples/` folder with `simple/` and `complex/` subdirectories
+2. Move `base.json` and `target.json` to `examples/simple/`
+3. Move `complex-base.json` and `complex-target.json` to `examples/complex/`
+4. Rename and move `test-api.js` to `examples/api-usage.js`
+5. Update script to reference new example file locations
+6. Evaluate `verify-structure.sh` - remove if obsolete
+
+### Phase 4: Documentation Updates
+
+1. Update README.md to reference new file locations
+2. Update `docs/IMPLEMENTATION.md` if it references moved files
+3. Update `docs/DEVELOPMENT.md` to reflect new structure
+4. Update `examples/api-usage.js` to use new paths
+
+### Phase 5: Validation
+
+1. Run link validation script
+2. Run build: `npm run build`
+3. Run tests: `npm test`
+4. Test CLI with examples
+5. Verify no temporary files exist
+6. Review against steering guidelines
+
+### Phase 6: Documentation
+
+1. Update README.md with new structure information
+2. Add examples section showing how to use files in `examples/`
+3. Update any references to file locations
+
+## Steering Guideline Compliance
+
+### Development Standards (development-standards.md)
+
+✅ **No duplicate files with suffixes**: Property 1 ensures this
+✅ **Clean directory structure**: New structure is organized and logical
+✅ **Documentation approach**: Single comprehensive README with supplementary docs in `docs/`
+✅ **File management**: No temporary or backup files
+
+### Documentation Style (documentation-style.md)
+
+✅ **Professional tone**: Existing documentation already follows this
+✅ **Clear structure**: Documentation will be organized in `docs/` folder
+✅ **No emojis**: Existing docs comply (except NEXT-STEPS.md which will be reviewed)
+
+### TypeScript Best Practices (typescript-best-practices.md)
+
+✅ **Project structure**: Source in `src/`, tests in `test/`, follows conventions
+✅ **Configuration files**: All in root as expected
+
+### Testing Best Practices (testing-best-practices.md)
+
+✅ **Test organization**: Automated tests in `test/`, examples separate
+✅ **Clear separation**: Production code, tests, and examples are distinct
+
+## Success Criteria
+
+The cleanup is successful when:
+
+1. Root directory contains only essential files (README, package files, configs)
+2. All supplementary documentation is in `docs/` folder
+3. All test artifacts are in `examples/` folder or removed
+4. No files with temporary suffixes exist
+5. All markdown links are valid and working
+6. `npm run build` completes successfully
+7. `npm test` passes all tests
+8. CLI works correctly with example files
+9. Repository structure follows all steering guidelines
+10. Git history preserves all removed files

package/.kiro/specs/repository-cleanup/requirements.md

@@ -0,0 +1,74 @@
+# Requirements Document
+
+## Introduction
+
+This document outlines the requirements for cleaning up and reorganizing the CDK Cost Analyzer repository. The goal is to remove unnecessary files, consolidate documentation into a dedicated folder, and maintain a clean, professional repository structure that follows best practices.
+
+## Glossary
+
+- **Repository**: The CDK Cost Analyzer codebase and all its files
+- **Documentation Files**: Markdown files that provide information about the project (README, IMPLEMENTATION, NEXT-STEPS, etc.)
+- **Test Artifacts**: Sample JSON files and test scripts used for manual testing
+- **Docs Folder**: A dedicated directory (`docs/`) for storing all documentation except the main README
+
+## Requirements
+
+### Requirement 1
+
+**User Story:** As a developer, I want a clean repository structure, so that I can easily navigate and understand the project organization.
+
+#### Acceptance Criteria
+
+1. WHEN the repository is viewed THEN the root directory SHALL contain only essential files (README, package files, config files, and source directories)
+2. WHEN documentation is needed THEN all supplementary documentation SHALL be located in a `docs/` folder
+3. WHEN test artifacts exist THEN they SHALL be organized in appropriate test directories or removed if obsolete
+4. THE repository SHALL NOT contain duplicate or temporary files with suffixes like `_backup`, `_old`, or similar
+5. THE repository SHALL follow standard Node.js/TypeScript project conventions for file organization
+
+### Requirement 2
+
+**User Story:** As a developer, I want all documentation consolidated in one location, so that I can find information quickly without searching through the repository.
+
+#### Acceptance Criteria
+
+1. WHEN supplementary documentation exists THEN the system SHALL move it to the `docs/` folder
+2. THE main README.md file SHALL remain in the root directory for immediate visibility
+3. WHEN documentation is moved THEN all internal links SHALL be updated to reflect new paths
+4. THE `docs/` folder SHALL contain a clear structure with descriptive filenames
+5. WHEN test project documentation exists THEN it SHALL remain with the test project for context
+
+### Requirement 3
+
+**User Story:** As a developer, I want test artifacts properly organized, so that I can distinguish between automated tests and manual test files.
+
+#### Acceptance Criteria
+
+1. WHEN manual test scripts exist in the root THEN they SHALL be moved to appropriate locations or removed
+2. WHEN sample JSON templates exist for testing THEN they SHALL be moved to a test fixtures directory or examples folder
+3. THE automated test suite in the `test/` directory SHALL remain unchanged
+4. WHEN test artifacts are moved THEN any references in documentation SHALL be updated
+5. THE repository SHALL clearly separate production code, automated tests, and examples
+
+### Requirement 4
+
+**User Story:** As a repository maintainer, I want to remove obsolete files, so that the repository contains only current and necessary content.
+
+#### Acceptance Criteria
+
+1. WHEN implementation tracking documents exist THEN they SHALL be archived or removed if no longer needed
+2. WHEN duplicate documentation exists THEN it SHALL be consolidated into single authoritative sources
+3. THE repository SHALL NOT contain files that are no longer referenced or used
+4. WHEN files are removed THEN the git history SHALL preserve them for reference
+5. THE cleanup process SHALL maintain all functional code and configuration files
+
+### Requirement 5
+
+**User Story:** As a developer, I want the repository to follow all established steering guidelines, so that the codebase maintains consistency with team standards.
+
+#### Acceptance Criteria
+
+1. WHEN documentation is written THEN it SHALL follow the documentation-style.md guidelines
+2. WHEN the repository structure is organized THEN it SHALL adhere to development-standards.md conventions
+3. THE repository SHALL NOT contain files that violate the development standards (no duplicate files with suffixes)
+4. WHEN documentation references AWS services THEN it SHALL use official AWS service names as specified in documentation-style.md
+5. THE repository structure SHALL align with TypeScript and testing best practices from the steering documents

package/.kiro/specs/repository-cleanup/tasks.md

@@ -0,0 +1,64 @@
+# Implementation Plan
+
+- [ ] 1. Create new directory structure
+  - Create `docs/` folder in repository root
+  - Create `examples/` folder in repository root
+  - Create `examples/simple/` subdirectory
+  - Create `examples/complex/` subdirectory
+  - _Requirements: 1.1, 1.2, 3.5_
+
+- [ ] 2. Move supplementary documentation to docs folder
+  - Move `IMPLEMENTATION.md` to `docs/IMPLEMENTATION.md`
+  - Rename and move `NEXT-STEPS.md` to `docs/DEVELOPMENT.md`
+  - Review `docs/DEVELOPMENT.md` for any emojis or casual language and update to follow documentation-style.md
+  - _Requirements: 2.1, 2.2, 5.1_
+
+- [ ] 3. Organize test artifacts into examples folder
+  - Move `base.json` to `examples/simple/base.json`
+  - Move `target.json` to `examples/simple/target.json`
+  - Move `complex-base.json` to `examples/complex/base.json`
+  - Move `complex-target.json` to `examples/complex/target.json`
+  - Rename and move `test-api.js` to `examples/api-usage.js`
+  - Update `examples/api-usage.js` to reference new file paths (`./simple/base.json`, `./simple/target.json`)
+  - _Requirements: 3.1, 3.2, 3.5_
+
+- [ ] 4. Evaluate and remove obsolete files
+  - Check if `verify-structure.sh` is still needed
+  - Remove `verify-structure.sh` if it's obsolete
+  - _Requirements: 4.1, 4.3_
+
+- [ ] 5. Update documentation references
+  - Update README.md to add "Documentation" section referencing docs folder
+  - Update README.md "Quick Start" examples to reference new example file paths
+  - Update README.md "Programmatic Usage" example to reference `examples/api-usage.js`
+  - Check `docs/IMPLEMENTATION.md` for any references to moved files and update paths
+  - Check `docs/DEVELOPMENT.md` for any references to moved files and update paths
+  - _Requirements: 2.3, 3.4_
+
+- [ ] 6. Update test project documentation references
+  - Review `test-cdk-project/README.md` for any references to root-level files
+  - Update any paths in test project docs if needed
+  - Ensure test project documentation remains in place
+  - _Requirements: 2.5_
+
+- [ ] 6.1 Write property test for no temporary file suffixes
+  - **Property 1: No temporary or backup file suffixes**
+  - **Validates: Requirements 1.4, 5.3**
+
+- [ ] 6.2 Write property test for valid documentation links
+  - **Property 2: All documentation links are valid**
+  - **Validates: Requirements 2.3, 3.4**
+
+- [ ] 6.3 Write property test for functional file preservation
+  - **Property 3: Functional files are preserved**
+  - **Validates: Requirements 3.3, 4.5**
+
+- [ ] 7. Checkpoint - Verify repository structure and functionality
+  - Ensure all tests pass, ask the user if questions arise
+  - Verify `npm run build` succeeds
+  - Verify `npm test` passes
+  - Test CLI with example files: `node dist/cli/index.js examples/simple/base.json examples/simple/target.json --region eu-central-1`
+  - Test API usage script: `node examples/api-usage.js`
+  - Verify root directory contains only essential files
+  - Verify no files with temporary suffixes exist
+  - _Requirements: 1.1, 1.4, 3.3, 4.5_

package/.kiro/steering/aws-cli-best-practices.md

@@ -0,0 +1,41 @@
+---
+title: AWS CLI Best Practices
+inclusion: always
+---
+
+# AWS CLI Best Practices
+
+## Pager Behavior
+When running AWS CLI commands that might produce large outputs, always use the `--no-cli-pager` option to prevent interactive paging. This is especially important for:
+- List operations (`aws s3 ls`, `aws ec2 describe-instances`, etc.)
+- Commands that return large JSON responses
+- Commands used in scripts or automation
+
+Example:
+```bash
+aws amplify list-apps --profile da --no-cli-pager
+aws ec2 describe-instances --no-cli-pager
+aws s3 ls s3://my-bucket --no-cli-pager
+```
+
+## Output Formatting
+- Use `--output json` for programmatic processing
+- Use `--output table` for human-readable output
+- Use `--query` to filter results and reduce output size
+
+## Error Handling
+- Always check exit codes in scripts
+- Use `--debug` flag for troubleshooting
+- Consider using `--dry-run` for testing destructive operations
+
+## Security
+- Use IAM roles instead of access keys when possible
+- Rotate access keys regularly
+- Use least privilege principle for IAM policies
+
+## AWS Integration Best Practices
+- Use AWS-Knowledge MCP server for current documentation and best practices
+- Follow AWS Well-Architected Framework principles
+- Reference official AWS documentation for implementation patterns
+- Validate service usage against latest AWS documentation
+- Use aws-api-mcp-server for programmatic AWS API interactions

package/.kiro/steering/cdk-best-practices.md

@@ -0,0 +1,49 @@
+<!-- CDK Best Practices adopted from https://github.com/mbonig/kiro-steering-docs/blob/main/cdk/cdk-best-practices.md -->
+---
+title: CDK Best Practices
+inclusion: always
+---
+
+# CDK Best Practices
+
+## Basics
+- Use projen for project initialization and file management
+- Use the latest version of the CDK, found here: https://github.com/aws/aws-cdk/releases
+- Use cdk-iam-floyd for IAM policy generation
+- Additional CDK apps should have a projen task with a prefix `cdk:`. E.g. `cdk:iam-roles`
+
+## Structure
+- All files in the `src/**` directory
+- Applications in the `src/` directory
+- Stacks in the `src/stacks/**` directory
+- Constructs in the `src/constructs/**` directory
+- Stages in the `src/stages/**` directory
+- Lambda function handlers in a sub-directory of the defining construct, called `handler`
+- Pascal-casing for filenames (e.g. `SomeConstruct.ts`)
+- Each custom construct should reside in its own file named the same as the construct
+
+## Apps
+- SHOULD contain distinct stack/stage instances for each environment
+- SHOULD provide each stack/stage with account/region specific values
+- Context SHOULD NOT be used for anything, at all
+
+## Stacks
+- SHOULD be responsible for importing resources (`Vpc.fromLookup()`, `Bucket.fromBucketName()`, etc.)
+- SHOULD be responsible for instantiating constructs
+
+## Constructs
+- SHOULD save the incoming constructor props as a private field
+- SHOULD create all resources in protected methods, not in the constructor
+- SHOULD NOT import resources (e.g. `Vpc.fromLookup()`)
+- SHOULD be passed concrete objects representing resources
+- Properties representing resource identifiers should use template literal types (e.g. `vpc-${string}`)
+
+## Tests
+- All tests in the `test/` directory
+- Tests should match construct names (e.g. `SomeConstruct.test.ts`)
+- Use fine-grained assertions for constructs
+- Use snapshot tests for stacks
+- Mock `Code.fromAsset` and `ContainerImage.fromAsset` calls
+
+## Lambda Functions
+- Use `NodejsFunction` or `PythonFunction` whenever possible

package/.kiro/steering/development-standards.md

@@ -0,0 +1,54 @@
+---
+title: Development Standards
+inclusion: always
+---
+
+# Development Standards
+
+## Dependency Management
+- Use latest stable versions of all libraries and dependencies
+- Leverage Context7 MCP server to verify compatibility before adding dependencies
+- Justify each new dependency with clear business or technical value
+- Prefer well-maintained libraries with active communities
+- Document version constraints in project files
+- Remove unused dependencies regularly
+- Use lock files to ensure consistent installations across environments
+
+## Code Quality Standards
+- Never create duplicate files with suffixes like `_fixed`, `_clean`, `_backup`, etc.
+- Work iteratively on existing files (hooks handle commits automatically)
+- Include relevant documentation links in code comments
+- Follow language-specific conventions (TypeScript for CDK, Python for Lambda)
+- Use meaningful variable and function names
+- Keep functions small and focused on single responsibilities
+- Implement proper error handling and logging
+
+## File Management
+- Maintain clean directory structures
+- Use consistent naming conventions across the project
+- Avoid temporary or backup files in version control
+- Organize code logically by feature or domain
+- Keep configuration files at appropriate levels (project vs user)
+
+## Documentation Approach
+- Maintain single comprehensive README covering all aspects including deployment
+- Reference official sources through MCP servers when available
+- Update documentation when upgrading dependencies
+- Keep documentation close to relevant code
+- Use inline comments for complex business logic
+- Document API endpoints and data structures
+- Include setup and deployment instructions
+
+## Version Control Integration
+- Commit frequently with meaningful messages
+- Use feature branches for development
+- Keep main branch deployable at all times
+- Tag releases appropriately
+- Use .gitignore to exclude generated files and secrets
+
+## Quality Assurance
+- Write tests for new functionality
+- Run tests before committing changes
+- Use linting and formatting tools consistently
+- Perform code reviews for all changes
+- Monitor code coverage and maintain high standards

package/.kiro/steering/docker-best-practices.md

@@ -0,0 +1,34 @@
+---
+title: Docker Best Practices
+inclusion: fileMatch
+fileMatchPattern: 'Dockerfile*,docker-compose*,*.dockerfile'
+---
+
+# Docker Best Practices
+
+## Dockerfile Optimization
+- Use multi-stage builds to reduce image size
+- Use specific base image tags, avoid `latest`
+- Minimize layers by combining RUN commands
+- Use `.dockerignore` to exclude unnecessary files
+- Run as non-root user when possible
+
+## Security
+- Scan images for vulnerabilities
+- Use minimal base images (alpine, distroless)
+- Don't include secrets in images
+- Use secrets management for sensitive data
+- Keep base images updated
+
+## Performance
+- Order layers from least to most frequently changing
+- Use build cache effectively
+- Minimize context size
+- Use appropriate COPY vs ADD commands
+
+## Best Practices
+- Use LABEL for metadata
+- Set appropriate WORKDIR
+- Use EXPOSE for documentation
+- Use health checks when appropriate
+- Clean up package manager caches