@thunder-so/thunder 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thunder-so/thunder",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "CDK library for deploying web applications on AWS",
   "keywords": [
     "aws",

package/.agents/CLI.md

@@ -1,65 +0,0 @@
-# Thunder CLI Scope
-
-The Thunder CLI (`th`) is the primary interface for developing, deploying, and managing applications built with `@thunder-so/thunder`. It is designed to be a thin, context-aware wrapper around the AWS CDK, providing a developer experience similar to SST but tailored for the Thunder ecosystem.
-
-## Core Mandates
-
-1.  **Context-Awareness:** [x] **DONE**: The CLI automatically detects the current environment, application, and service from the repository structure or configuration, minimizing repetitive flag usage.
-2.  **Zero-Config Defaults:** [x] **DONE**: "It just works" out of the box with sensible defaults for AWS regions, accounts, and resource sizing.
-3.  **Local Dev Parity:** [ ] **TODO**: Enables a local development loop that closely mirrors production, including live Lambda iteration (future scope) and local emulation of static sites.
-
-## Command Reference
-
-### `th init`
-- [ ] **TODO**: Scaffolds a new Thunder project or adds a new service to an existing monorepo.
-
--   **Usage:** `th init [template] [name]`
--   **Features:**
-    -   Detects if running in an existing workspace (monorepo).
-    -   Prompts for project type: `static`, `lambda`, `fargate`, `nuxt`, `astro`, `ec2`, `template`.
-    -   Generates `thunder.config.ts` (or updates it).
-    -   Creates necessary `bin/*.ts` entry points.
-    -   Sets up `.gitignore` and `package.json` scripts.
-
-### `th deploy`
-- [ ] **TODO**: Deploys the application to AWS.
-
--   **Usage:** `th deploy [--stage <stage>] [--filter <service>]`
--   **Features:**
-    -   **Stage Management:** defaults to `dev` for local, but supports `prod`, `staging`, `pr-*`.
-    -   **Context-Driven:** [x] **DONE**: Reads `bin/*.ts` files to determine which stacks to deploy.
-    -   **Metadata Push:** [x] **DONE**: Updates the `thunder-discovery` bucket with new resource ARNs and endpoints after successful deployment.
-    -   **Output:** Prints critical URLs (CloudFront, API Gateway, ALB) to the console.
-
-### `th destroy`
-- [ ] **TODO**: Tears down resources.
-
--   **Usage:** `th remove [--stage <stage>] [--filter <service>]`
--   **Features:**
-    -   **Safety Checks:** Prompts for confirmation, especially for `prod` stages or stateful resources (RDS, S3).
-    -   **Metadata Cleanup:** Removes entries from the `thunder-discovery` bucket.
-
-## Implementation Details
-
-### Context Resolution (`bin/*.ts`)
-- [x] **DONE**: The CLI relies on the convention of `bin/<type>.ts` files. 
--   `th deploy` scans `bin/` directory.
--   It executes these scripts using `ts-node` or `tsx`.
--   The scripts instantiate the Stacks (e.g., `NuxtStack`, `FargateStack`).
--   The CLI injects context (app, env, service, account, region) via environment variables or context context keys.
-
-### CLI Architecture
-- [ ] **TODO**:
--   **Runtime:** Node.js
--   **Core Libs:** `aws-cdk` (programmatic), `aws-sdk` (v3), `inquirer` (prompts), `commander` (args), `ink` (TUI).
--   **Build:** `esbuild` for fast bundling of Lambda code during `th dev`.
-
-## Comparison with SST
-
-| Feature | SST CLI | Thunder CLI |
-| :--- | :--- | :--- |
-| **Engine** | Pulumi / Terraform (v3) | AWS CDK (Native) |
-| **Language** | TypeScript / Python / Go | TypeScript (Strict) |
-| **State** | Cloud State Backend | CloudFormation + S3 Metadata |
-| **Local Dev** | Live Lambda (Multiplexing) | Hotswap + Local Framework Server |
-| **Constructs** | Broad (150+ providers) | Focused (AWS Web patterns) |

package/.agents/METADATA.md

@@ -1,75 +0,0 @@
-# Metadata Discovery
-
-Thunder implements an "SST-style" discovery mechanism to enable the Thunder CLI and potential future Thunder Console to automatically identify and interact with deployed resources without relying on manual tagging or complex CloudFormation stack queries.
-
-## How Thunder Tags Deployments
-
-- [x] **DONE**: Thunder uses a state-based approach rather than traditional AWS resource tags for discovery.
-
-### State Storage
-When you deploy a Thunder service, it automatically stores its deployment state in a centralized S3 bucket named `thunder-discovery-<account>-<region>`.
-
-### Key Structure
-Metadata files are stored with the following hierarchy:
-`apps/<application>/<environment>/<service>/metadata.json`
-
-### Metadata Content
-The `metadata.json` file contains a standardized set of properties that align with the service's `CfnOutput` names:
-```json
-{
-  "id": "myapp-prod-web",
-  "application": "myapp",
-  "service": "web",
-  "environment": "prod",
-  "region": "us-east-1",
-  "timestamp": "2026-03-04T12:00:00.000Z",
-  "type": "Nuxt",
-  "DistributionId": "E1234567890",
-  "DistributionUrl": "https://d123.cloudfront.net",
-  "Route53Domain": "https://myapp.com",
-  "CodePipelineName": "myapp-prod-web-pipeline"
-}
-```
-
-## How the CLI/Console Discovers Apps
-
-1.  **Bucket Resolution**: The tool determines the discovery bucket name based on the current AWS account and region.
-2.  **S3 Scanning**: It lists the objects in the bucket under the `apps/` prefix.
-3.  **Metadata Parsing**: It reads the `metadata.json` files to discover:
-    - All deployed Thunder apps.
-    - Their environments/stages.
-    - Their individual services and associated resource IDs/URLs.
-4.  **Automatic Discovery**: Because the `DiscoveryConstruct` is embedded in every Thunder stack, new services and updates are automatically reflected in S3 upon successful deployment.
-
-## Implementation Details
-
-- [x] **DONE**: **`DiscoveryConstruct`**: A shared construct located in `lib/constructs/discovery.ts`.
-- [x] **DONE**: **`BucketDeployment`**: Uses `aws-s3-deployment` to upload `Source.jsonData` during the CDK deployment phase.
-- [x] **DONE**: **Standardization**: Metadata field names are strictly aligned with `CfnOutput` logical IDs (e.g., `DistributionId`, `ServiceUrl`).
-- [x] **DONE**: Each deployment stores its metadata in a centralized S3 bucket (`thunder-discovery-<account>-<region>`). 
-
-Metadata includes:
-- [x] App identity (application, service, environment)
-- [x] Resource ARNs, IDs and URLs (Aligned with `CfnOutput` names)
-- [x] Deployment timestamps
-- [x] Framework-specific metadata
-- [x] Route53 domain integration
-
-
-## ISSUES:
-
-7:11:10 PM | CREATE_FAILED        | Custom::CDKBucketDeployment               | Discovery/StoreMet...omResource/Default
-Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'sync', '/tmp/tmpxgahyp87/contents', 's3://thunder-discovery-047719662375-us-east
--1/apps/nuxt3/dev/fargate']' returned non-zero exit status 1. (RequestId: afc6bb52-d373-4b97-9a7d-36d0ab9b9425)
-7:11:10 PM | ROLLBACK_IN_PROGRESS | AWS::CloudFormation::Stack                | nuxt3-fargate-dev-stack
-The following resource(s) failed to create: [DiscoveryStoreMetadataCustomResource5F6695DB, FargateFargateService7449B65B]. Rollback requested by user.
-7:11:10 PM | ROLLBACK_IN_PROGRESS | AWS::CloudFormation::Stack                | nuxt3-fargate-dev-stack
-The following resource(s) failed to create: [DiscoveryStoreMetadataCustomResource5F6695DB, FargateFargateService7449B65B]. Rollback requested by user.
-7:11:37 PM | DELETE_FAILED        | Custom::CDKBucketDeployment               | Discovery/StoreMet...omResource/Default
-Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'rm', 's3://thunder-discovery-047719662375-us-east-1/apps/nuxt3/dev/fargate', '--
-recursive']' returned non-zero exit status 1. (RequestId: f9383113-0976-4fe3-af60-bcefbf14d514)
-
-❌  nuxt3-fargate-dev-stack failed: ToolkitError: The stack named nuxt3-fargate-dev-stack failed creation, it may need to be manually deleted from the AWS console: ROLLBACK_FAILED (The following resource(s) failed to delete: [DiscoveryStoreMetadataCustomResource5F6695DB]. ): Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'sync', '/tmp/tmpxgahyp87/contents', 's3://thunder-discovery-047719662375-us-east-1/apps/nuxt3/dev/fargate']' returned non-zero exit status 1. (RequestId: afc6bb52-d373-4b97-9a7d-36d0ab9b9425), Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'rm', 's3://thunder-discovery-047719662375-us-east-1/apps/nuxt3/dev/fargate', '--recursive']' returned non-zero exit status 1. (RequestId: f9383113-0976-4fe3-af60-bcefbf14d514)
-
-The following resource(s) failed to delete: [DiscoveryStoreMetadataCustomResource5F6695DB].
-Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'rm', 's3://thunder-discovery-047719662375-us-east-1/apps/nuxt3/dev/fargate', '--recursive']' returned non-zero exit status 1. (RequestId: f9383113-0976-4fe3-af60-bcefbf14d514)

package/.agents/PRD.md

@@ -1,537 +0,0 @@
-# Thunder - CDK Library for AWS Deployments
-
-## Executive Summary
-
-Thunder (`@thunder-so/thunder`) is an AWS CDK library for deploying modern web applications. It provides opinionated, production-ready infrastructure patterns for one-line deployment of common web application architectures.
-
-**One library to rule them all**: Static SPAs, Lambda Functions, Containers (Fargate/EC2), and Full-stack Frameworks (Nuxt/Astro).
-
----
-
-## Project Overview
-
-Thunder provides high-level abstractions over AWS CDK, enabling developers to deploy complete infrastructure stacks with minimal configuration. The library covers the full spectrum of web deployment patterns from static sites to full-stack serverless applications.
-
----
-
-## Stacks
-
-| Stack | Description | Use Cases | Status |
-|-----------|-------------|-----------|--------|
-| `Static` | S3 + CloudFront for static SPAs | React, Vue, Svelte, Next.js (SSG), Gatsby | **DONE** |
-| `Lambda` | Lambda + API Gateway for serverless | API endpoints, background jobs, microservices | **DONE** |
-| `Fargate` | ECS Fargate + ALB for containers | Long-running containers, microservices | **DONE** |
-| `EC2` | EC2 instance with Docker + Elastic IP | Single containers, dev environments | **DONE** |
-| `Template` | Coolify One-Click Service Template on EC2 | Pre-built apps (n8n, Plausible, etc.) | **DONE** |
-| `Nuxt` | Full-stack Nuxt.js (Lambda + S3 + CloudFront) | SSR Nuxt applications | **DONE** |
-| `Astro` | Full-stack Astro SSR (with Edge fallback) | SSR Astro applications | **DONE** |
-| `VPC` | Shared VPC with public/private subnets | Shared networking infrastructure | **DONE** |
-
----
-
-## Stack Details
-
-### 1. Static Stack
-**Purpose**: Static SPA hosting
-**Resources**: S3 + CloudFront (OAC) + Route53 + Lambda@Edge
-**Key Features**:
-- Zero-downtime deployment without bucket pruning
-- Origin Access Control (OAC) for secure S3 access
-- Lambda@Edge for redirects/rewrites
-- Custom security headers policy
-- CI/CD pipeline support
-
-**Entry Point**: `bin/static.ts`
-**Stack File**: `stacks/StaticStack.ts`
-**Constructs**:
-- `HostingConstruct` (S3 + CloudFront + Route53)
-- `DeployConstruct` (direct local deployment)
-- `PipelineConstruct` (CodePipeline CI/CD)
-
-### 2. Lambda Stack
-**Purpose**: Serverless functions
-**Resources**: Lambda (Zip or Container) + API Gateway v2 + ECR + Route53
-**Key Features**:
-- Bun runtime support via Lambda Layer
-- Keep-warm scheduling (EventBridge)
-- Provisioned concurrency support
-- X-Ray tracing
-- VPC integration
-
-**Entry Point**: `bin/lambda.ts`
-**Stack File**: `stacks/LambdaStack.ts`
-**Constructs**:
-- `FunctionsConstruct` (Lambda + API Gateway)
-- `PipelineConstruct` (ECR-based CI/CD)
-
-### 3. Fargate Stack
-**Purpose**: Container orchestration
-**Resources**: ECS Fargate + ALB + VPC + ECR + Route53
-**Key Features**:
-- ARM64 or X86_64 architecture support
-- Auto-scaling capabilities
-- Health checks with customizable paths
-- Circuit breaker deployments
-- Nixpacks integration for Dockerfile generation
-- Rolling updates
-
-**Entry Point**: `bin/fargate.ts`
-**Stack File**: `stacks/FargateStack.ts`
-**Constructs**:
-- `ServiceConstruct` (ECS service + ALB + VPC)
-- `PipelineConstruct` (ECR-based CI/CD)
-
-### 4. EC2 Stack
-**Purpose**: Single EC2 container hosting
-**Resources**: EC2 + Elastic IP + Route53 + CloudWatch Agent
-**Key Features**:
-- Docker-on-EC2 deployment
-- Elastic IP assignment
-- Let's Encrypt SSL (via acmeEmail)
-- SSH access with authorized keys
-- CloudWatch monitoring
-- Nixpacks support
-
-**Entry Point**: `bin/ec2.ts`
-**Stack File**: `stacks/Ec2Stack.ts`
-**Constructs**:
-- `ComputeConstruct` (EC2 instance + Docker)
-- `PipelineConstruct` (CI/CD)
-- `Ec2Instance` (instance provisioning)
-- `UserData` (EC2 bootstrap scripts)
-- `CloudwatchAgent` (monitoring)
-
-### 5. Template Stack
-**Purpose**: Coolify one-click templates
-**Resources**: EC2 + Docker Compose + Traefik
-**Key Features**:
-- Fetches templates from Coolify GitHub repo
-- Hydrates SERVICE_FQDN, SERVICE_PASSWORD variables
-- Traefik reverse proxy with Let's Encrypt
-- Multi-service Docker Compose support
-
-**Entry Point**: `bin/template.ts`
-**Stack File**: `stacks/TemplateStack.ts`
-**Constructs**:
-- `TemplateConstruct` (template deployment)
-- `TemplateFetcher` (fetches from GitHub)
-- `TemplateHydrator` (variable substitution)
-
-### 6. Nuxt Stack
-**Purpose**: Full-stack Nuxt.js deployment
-**Resources**: Lambda (SSR) + S3 (Assets) + CloudFront (Dual Origin) + API Gateway
-**Key Features**:
-- Nitro preset optimized for AWS Lambda
-- Static assets served from S3
-- SSR via Lambda function
-- API routes support
-- Unified CloudFront distribution
-
-**Entry Point**: `bin/nuxt.ts`
-**Stack File**: `stacks/NuxtStack.ts`
-**Constructs**:
-- `NuxtConstruct` (SSR server + client)
-- `ServerConstruct` (Lambda SSR)
-- `ClientConstruct` (S3 + CloudFront)
-- `FrameworkPipeline` (CI/CD)
-
-### 7. Astro Stack
-**Purpose**: Full-stack Astro SSR deployment
-**Resources**: Lambda (SSR) + S3 + CloudFront + Edge Function fallback
-**Key Features**:
-- Same architecture as Nuxt (Lambda + S3 + CloudFront)
-- Lambda@Edge fallback for 404/403 handling
-- Edge-optimized for global distribution
-- Astro-specific optimizations
-
-**Entry Point**: `bin/astro.ts`
-**Stack File**: `stacks/AstroStack.ts`
-**Constructs**:
-- `AstroConstruct` (SSR server + client)
-- `ClientConstruct` (S3 + CloudFront + Edge fallback)
-- `FrameworkPipeline` (CI/CD)
-
-### 8. VPC Stack
-**Purpose**: Shared VPC infrastructure
-**Resources**: VPC with public/private subnets, NAT gateways
-**Key Features**:
-- Shared networking for multiple services
-- Implements IVpcLink interface
-- Configurable CIDR, AZs, NAT gateways
-- Can be linked to other stacks
-
-**Entry Point**: `bin/vpc.ts`
-**Stack File**: `stacks/VpcStack.ts`
-**Constructs**:
-- `VPC` (shared VPC construct)
-
----
-
-## Architecture
-
-### Project Structure
-
-```
-@thunder-so/thunder/
-├── bin/                          # CDK entry points
-│   ├── static.ts                 # Static SPA deployment
-│   ├── lambda.ts                 # Lambda deployment
-│   ├── fargate.ts                # Fargate deployment
-│   ├── ec2.ts                    # EC2 deployment
-│   ├── template.ts               # Coolify template deployment
-│   ├── nuxt.ts                   # Nuxt deployment
-│   ├── astro.ts                  # Astro deployment
-│   └── vpc.ts                    # VPC deployment
-│
-├── cli/                          # Thunder CLI
-│   ├── th.mjs                    # Main CLI entry
-│   ├── th-init.mjs               # Init command
-│   ├── th-deploy.mjs             # Deploy command
-│   └── th-destroy.mjs            # Destroy command
-│
-├── lib/                          # CDK constructs
-│   ├── astro/                    # Astro framework support
-│   │   ├── index.ts              # AstroConstruct
-│   │   └── client.ts             # Astro client (S3 + CloudFront + Edge)
-│   │
-│   ├── constructs/               # Shared constructs
-│   │   ├── vpc.ts                # VPC construct
-│   │   └── discovery.ts          # SST-style metadata discovery
-│   │
-│   ├── ec2/                      # EC2 implementation
-│   │   ├── compute.ts            # EC2 compute
-│   │   ├── pipeline.ts           # EC2 pipeline
-│   │   └── constructs/
-│   │       ├── cloudwatch-agent.ts
-│   │       ├── ec2-instance.ts
-│   │       └── user-data.ts
-│   │
-│   ├── fargate/                  # Fargate implementation
-│   │   ├── service.ts            # ECS Fargate service
-│   │   └── pipeline.ts           # Fargate pipeline
-│   │
-│   ├── frameworks/               # Framework pipeline
-│   │   └── pipeline.ts           # Shared framework CI/CD
-│   │
-│   ├── lambda/                   # Lambda implementation
-│   │   ├── functions.ts          # Lambda + API Gateway
-│   │   └── pipeline.ts           # Lambda pipeline
-│   │
-│   ├── nuxt/                     # Nuxt implementation
-│   │   ├── index.ts              # NuxtConstruct
-│   │   ├── server.ts             # Nuxt server (Lambda)
-│   │   └── client.ts             # Nuxt client (S3 + CloudFront)
-│   │
-│   ├── static/                   # Static implementation
-│   │   ├── hosting.ts            # S3 + CloudFront + Route53
-│   │   ├── pipeline.ts           # Static CI/CD
-│   │   └── deploy.ts             # Direct S3 deployment
-│   │
-│   ├── template/                 # Coolify template implementation
-│   │   ├── index.ts              # TemplateConstruct
-│   │   ├── template/
-│   │   │   ├── fetch.ts          # Fetch from GitHub
-│   │   │   └── hydrate.ts        # Variable hydration
-│   │   └── constructs/
-│   │       ├── cloudwatch-agent.ts
-│   │       ├── ec2-instance.ts
-│   │       └── user-data.ts
-│   │
-│   └── utils/                    # Shared utilities
-│       ├── index.ts              # Main exports
-│       ├── naming.ts             # Resource naming
-│       ├── paths.ts              # Path sanitization
-│       ├── nixpacks.ts           # Nixpacks integration
-│       └── vpc-link.ts           # VPC linking
-│
-├── stacks/                       # Stack definitions
-│   ├── StaticStack.ts
-│   ├── LambdaStack.ts
-│   ├── FargateStack.ts
-│   ├── Ec2Stack.ts
-│   ├── TemplateStack.ts
-│   ├── NuxtStack.ts
-│   ├── AstroStack.ts
-│   └── VpcStack.ts
-│
-├── types/                        # TypeScript interfaces
-│   ├── AppProps.ts               # Base props
-│   ├── StaticProps.ts
-│   ├── LambdaProps.ts
-│   ├── FargateProps.ts
-│   ├── Ec2Props.ts
-│   ├── TemplateProps.ts
-│   ├── NuxtProps.ts
-│   ├── VpcProps.ts
-│   ├── CloudFrontProps.ts
-│   └── PipelineProps.ts
-│
-├── .agents/                      # Documentation
-│   ├── PRD.md                    # This file
-│   ├── CLI.md                    # CLI scope
-│   ├── SKILLS.md                 # Claude skills plan
-│   └── METADATA.md               # Discovery mechanism
-│
-├── index.ts                      # Main exports
-└── package.json
-```
----
-
-## Shared Infrastructure Patterns
-
-### VPC Link Pattern
-All compute stacks (Lambda, Fargate, EC2, Template) support a `link` pattern for VPC integration:
-
-- Implemented via `resolveVpc()` utility
-- Accepts `IVpc` directly or `IVpcLink` implementing construct
-- Provides consistent VPC connectivity across stacks
-
-```typescript
-// Explicit VPC passing
-const vpc = new VpcStack(this, 'MyVPC', { ... });
-
-new FargateStack(this, 'MyService', {
-  vpc: vpc,
-  // ...
-});
-
-// Via link property
-new FargateStack(this, 'MyService', {
-  link: vpc,  // IVpcLink interface
-  // ...
-});
-```
-
-### Resource Naming
-**Pattern**: 23-character prefix ensuring uniqueness and AWS name limits
-- **Format**: `${app.substring(0,7)}-${service.substring(0,7)}-${env.substring(0,7)}`
-- **Utility**: `getResourceIdPrefix()` in `lib/utils/naming.ts`
-- **Example**: `myapp-t-web-dev` (app="myapplication", service="webfrontend", env="development")
-
-### Path Sanitization
-**Purpose**: Ensure valid Unix directory paths for Docker builds and deployments
-- **Utility**: `sanitizePath()` in `lib/utils/paths.ts`
-- **Regex**: Removes invalid characters, normalizes slashes
-- **Use Case**: User-provided rootDir/outputDir sanitization
-
----
-
-## Common Features Across Stacks
-
-### 1. Monorepo Support
-- **Path-based filters** in CodeBuild webhooks
-- **rootDir/outputDir** resolution for monorepo packages
-- **Context directory** support for taking source from any path
-
-### 2. CI/CD Pipeline Integration
-Optional AWS CodePipeline with GitHub support:
-- Triggered by `accessTokenSecretArn` + `sourceProps` + `buildProps`
-- Path-based filtering for monorepos
-- ECR integration for container stacks
-- S3 deployment for static stacks
-
-### 3. Nixpacks Integration
-Automatic Dockerfile generation:
-- **Utility**: `generateNixpacksDockerfile()` in `lib/utils/nixpacks.ts`
-- **Supported**: Fargate, EC2, Template stacks
-- **Build system**: Detects language and generates optimized Dockerfile
-
-### 4. Framework Fallbacks
-Astro-specific Edge function for 404/403 handling:
-- Implemented in `lib/astro/client.ts`
-- CloudFront origin failover to S3 for SPA routing
-
-### 5. Bun Support
-Bun runtime for Lambda:
-- Lambda Layer integration
-- Custom runtime configuration for CodeBuild
-
----
-
-## Thunder CLI
-
-**Location**: `cli/th.mjs`
-
-The Thunder CLI provides context-aware infrastructure management:
-
-### Commands
-
-| Command | Description | Status |
-|---------|-------------|--------|
-| `th init` | Scaffold new project/service | [ ] **TODO** |
-| `th deploy` | Deploy stacks to AWS | [ ] **TODO** |
-| `th destroy` | Remove resources from AWS | [ ] **TODO** |
-
-### CLI Architecture
-- **Runtime**: Node.js
-- **Core Libraries**: `commander`, `inquirer`, `chalk`, `ora`, `shelljs`
-- **Context Resolution**: Reads `bin/*.ts` files
-- **Environment**: Injects CDK context via environment variables
-
-### Context Resolution
-1. CLI scans `bin/` directory for stack entry points
-2. Executes via `ts-node` or `tsx`
-3. Injects context: app, env, service, account, region
-4. Delegates to CDK for actual deployment
-
-**Status**: Basic CLI structure done, full implementation pending
-
----
-
-## CLI Mandates
-
-1. **Context-Awareness**: [x] **DONE** - Auto-detects environment from repository
-2. **Zero-Config Defaults**: [x] **DONE** - Sensible defaults for AWS regions, accounts, resource sizing
-3. **Local Dev Parity**: [ ] **TODO** - Local development loop (future scope)
-4. **SST-Style Metadata**: [x] **DONE** - Discovery bucket for deployment state
-
----
-
-## Future Extensibility
-
-### Framework Support
-
-The library should support additional Vite + Nitro-based frameworks:
-- [ ] TanStack Start
-- [ ] Angular AnalogJS
-- [ ] SvelteKit
-- [ ] React Router v7
-- [ ] SolidStart
-
-Each framework construct will have preset configurations optimized for that framework.
-
-### Console UI
-
-Future scope: SST-style Console UI for:
-- Resource visualization
-- Log streaming
-- Real-time monitoring
-- Deployment history
-
-**Prerequisite**: Metadata Discovery system (already implemented)
-
----
-
-## Status Overview
-
-| Feature | Status | Notes |
-|---------|--------|-------|
-| **Static Stack** | [x] **DONE** | Production-ready |
-| **Lambda Stack** | [x] **DONE** | Production-ready |
-| **Fargate Stack** | [x] **DONE** | Production-ready |
-| **EC2 Stack** | [x] **DONE** | Production-ready |
-| **Template Stack** | [x] **DONE** | Production-ready |
-| **Nuxt Stack** | [x] **DONE** | Production-ready |
-| **Astro Stack** | [x] **DONE** | Production-ready |
-| **VPC Stack** | [x] **DONE** | Production-ready |
-| **VPC Link Pattern** | [x] **DONE** | All compute stacks |
-| **Monorepo Support** | [x] **DONE** | Path filters, rootDir |
-| **Nixpacks Integration** | [x] **DONE** | Auto Dockerfile gen |
-| **Metadata Discovery** | [x] **DONE** | SST-style in S3 |
-| **CI/CD Pipelines** | [x] **DONE** | CodePipeline + GitHub |
-| **Bun Support** | [x] **DONE** | Lambda layer |
-| **CLI Framework** | [x] **DONE** | Basic structure |
-| **th init Command** | [ ] **TODO** | Scaffold projects |
-| **th deploy Command** | [ ] **TODO** | Deploy stacks |
-| **th destroy Command** | [ ] **TODO** | Remove resources |
-| **Console UI** | [ ] **TODO** | Future scope |
-| **Additional Frameworks** | [ ] **TODO** | TanStack, SvelteKit, etc. |
-| **Claude Skills** | [ ] **TODO** | See SKILLS.md |
-
----
-
-## Supported Frameworks & Patterns
-
-### Static Sites
-- **Vite-based**: React, Vue, Svelte, Solid
-- **Next.js**: Static Site Generation (SSG)
-- **Astro**: Static Site Generation
-- **Gatsby**: Static site generator
-- **Other**: Any framework outputting to a directory
-
-### Serverless
-- **Node.js**: Lambda functions
-- **Bun**: Via Lambda Layer
-- **Containers**: Container-based Lambda
-- **Runtimes**: Node.js 18.x, 20.x
-
-### Containers
-- **ECS Fargate**: Serverless containers with ALB
-- **EC2 Docker**: Single-container on EC2
-- **Architectures**: ARM64, X86_64
-- **Orchestration**: Supports docker-compose (Template)
-
-### Full-Stack SSR
-- **Nuxt.js**: Universal Vue applications
-- **Astro**: Content-focused websites with SSR
-- **Extensible**: TanStack Start, SvelteKit, AnalogJS (planned)
-
----
-
-## Key Design Principles
-
-1. **One-Line Deployment**: Minimal configuration for common patterns
-2. **Convention over Configuration**: Sensible defaults, customization when needed
-3. **Framework Agnostic**: Works with any framework, optimized for popular ones
-4. **Production Ready**: Security, monitoring, CI/CD included
-5. **Cost Optimized**: Uses most cost-effective AWS services for each pattern
-6. **Developer Experience**: Fast feedback loops, clear errors, helpful defaults
-7. **Composable**: Stacks can be combined for complex architectures
-
----
-
-## Quick Start
-
-### Installation
-```bash
-bun add @thunder-so/thunder -d
-```
-
-### Basic Usage
-```typescript
-// stack/dev.ts
-import { Cdk, Static, type StaticProps } from '@thunder-so/thunder';
-
-const myApp: StaticProps = {
-  env: { 
-    account: '123456789012', 
-    region: 'us-east-1' 
-  },
-  application: 'myapp',
-  service: 'web',
-  environment: 'prod',
-  rootDir: '.',
-  outputDir: 'dist',
-};
-
-new Static(
-  new Cdk.App(),
-  `${myApp.application}-${myApp.service}-${myApp.environment}-stack`,
-  myApp
-);
-```
-
-### Deployment
-```bash
-npx cdk deploy --app "npx tsx stack/dev.ts" --profile default
-```
-
----
-
-## Documentation
-
-- **This PRD**: Project overview and architecture
-- **CLI.md**: CLI command reference and scope
-- **SKILLS.md**: Claude Code skills implementation plan
-- **METADATA.md**: Discovery/metadata mechanism details
-
----
-
-## License
-
-Apache-2.0
-
----
-
-**Last Updated**: 2026-03-08
-**Status**: Production-ready stacks, CLI implementation in progress

package/.agents/SKILLS.md

@@ -1,543 +0,0 @@
-# Claude Skills Implementation Plan for Thunder
-
-## Overview
-
-This document outlines the comprehensive plan for implementing Claude Code skills in the Thunder AWS CDK library to enable intelligent stack selection and configuration generation.
-
----
-
-## Current State Analysis
-
-### Project: `@thunder-so/thunder`
-A unified AWS CDK library for deploying web applications with multiple deployment patterns.
-
-### Available Stacks
-
-| Stack | Purpose | Resources |
-|-------|---------|-----------|
-| **Static** | Static SPA hosting | S3 + CloudFront + Route53 |
-| **Lambda** | Serverless functions | Lambda + API Gateway + ECR |
-| **Fargate** | Container orchestration | ECS Fargate + ALB + VPC |
-| **EC2** | Single container hosting | EC2 + Elastic IP + Docker |
-| **Template** | Coolify one-click templates | EC2 + Docker Compose |
-| **Nuxt** | Full-stack Nuxt.js | Lambda SSR + S3 + CloudFront |
-| **Astro** | Full-stack Astro SSR | Lambda SSR + S3 + CloudFront + Edge |
-| **VPC** | Shared infrastructure | VPC with public/private subnets |
-
-### Current CLI
-- `th init` - Initialize project
-- `th deploy` - Deploy services
-- `th destroy` - Remove resources
-
-### Missing Infrastructure
-- No `.claude/` directory
-- No intelligent stack selection
-- No automated configuration generation
-
----
-
-## Recommended Architecture
-
-### Option A: Project-Level Skills (Immediate Use)
-**Location**: `.claude/skills/` within repo
-- Automatically available in project
-- Version-controlled with code
-- No installation required
-- Best for team collaboration
-
-### Option B: Plugin Distribution (Global Distribution)
-**Location**: `thunder-claude-plugin/` directory
-- Install once, use everywhere
-- Distributed via marketplace
-- Namespaced: `/thunder:select-stack`
-- Best for community distribution
-
-**Recommendation**: Start with Option A, package as Option B later.
-
----
-
-## Skill System Design
-
-### 1. Master Stack Selector Skill (`select-stack`)
-
-**Purpose**: Primary entry point for "deploy on AWS" requests
-
-**Detection Logic**:
-```
-Framework Detection:
-├── Nuxt.js → NuxtStack
-├── Astro → AstroStack
-├── Next.js (SSG) → StaticStack
-├── React/Vue/Svelte SPA → StaticStack
-│
-Container Detection:
-├── Dockerfile exists → Fargate/EC2
-├── docker-compose.yml → TemplateStack
-│
-Architecture Analysis:
-├── Simple API → LambdaStack
-├── Long-running service → FargateStack
-├── Single container → EC2Stack
-└── Pre-built template → TemplateStack
-```
-
-**User Flow**:
-1. Analyze project structure (package.json, configs, Docker files)
-2. Detect framework and architecture patterns
-3. Ask clarifying questions if ambiguous
-4. Present 1-2 recommendations with rationale
-5. Generate configuration files upon confirmation
-
-### 2. Individual Stack Skills
-
-Each stack has a dedicated skill for:
-- Generating stack-specific configuration
-- Creating bin/*.ts entry points
-- Setting up thunder.config.ts
-- Providing best practice guidance
-- Troubleshooting common issues
-
-**Skills Required**:
-- `/select-stack` - Master selector
-- `/static` - Static SPA deployment
-- `/lambda` - Serverless functions
-- `/fargate` - Container orchestration
-- `/ec2` - Single EC2 container
-- `/template` - Coolify templates
-- `/nuxt` - Nuxt.js full-stack
-- `/astro` - Astro full-stack
-- `/vpc` - VPC infrastructure
-- `/troubleshoot` - Issue resolution
-
-### 3. Utility Skills
-
-- `/config` - Manage thunder.config.ts
-- `/deploy-guide` - Deployment walkthrough
-- `/teardown` - Safe resource cleanup
-
----
-
-## File Structure
-
-```
-.claude/
-├── CLAUDE.md                     # Project context
-└── skills/
-    ├── select-stack/
-    │   ├── SKILL.md              # Skill definition
-    │   ├── decision-matrix.md    # Selection criteria
-    │   └── examples/
-    │       ├── react-spa.md
-    │       ├── nuxt-app.md
-    │       └── api-service.md
-    │
-    ├── static/
-    │   ├── SKILL.md
-    │   └── templates/
-    │       ├── bin-static.ts
-    │       └── thunder.config.static.ts
-    │
-    ├── lambda/
-    │   ├── SKILL.md
-    │   └── templates/
-    │       ├── bin-lambda.ts
-    │       └── thunder.config.lambda.ts
-    │
-    ├── fargate/
-    │   ├── SKILL.md
-    │   └── templates/
-    │       ├── bin-fargate.ts
-    │       └── thunder.config.fargate.ts
-    │
-    ├── ec2/
-    │   ├── SKILL.md
-    │   └── templates/
-    │       ├── bin-ec2.ts
-    │       └── thunder.config.ec2.ts
-    │
-    ├── nuxt/
-    │   ├── SKILL.md
-    │   └── templates/
-    │       ├── bin-nuxt.ts
-    │       └── thunder.config.nuxt.ts
-    │
-    ├── astro/
-    │   ├── SKILL.md
-    │   └── templates/
-    │       ├── bin-astro.ts
-    │       └── thunder.config.astro.ts
-    │
-    ├── template/
-    │   ├── SKILL.md
-    │   └── templates/
-    │       ├── bin-template.ts
-    │       └── thunder.config.template.ts
-    │
-    ├── vpc/
-    │   ├── SKILL.md
-    │   └── templates/
-    │       └── bin-vpc.ts
-    │
-    └── troubleshoot/
-        ├── SKILL.md
-        └── common-issues.md
-```
-
----
-
-## Stack Selection Matrix
-
-| Use Case | Detection Signals | Primary Stack | Alternative |
-|----------|-------------------|---------------|-------------|
-| React/Vue/Angular SPA | `react`, `vue` in deps | **Static** | - |
-| SSG Framework (Next.js, Gatsby) | `next`, `gatsby` in deps | **Static** | - |
-| Nuxt.js Application | `nuxt` in deps | **Nuxt** | Fargate |
-| Astro Application | `astro` in deps | **Astro** | Static |
-| API-only Backend | No frontend deps | **Lambda** | Fargate |
-| Container w/ Dockerfile | `Dockerfile` present | **Fargate** | EC2 |
-| Simple Container | Single container | **EC2** | Fargate |
-| Coolify Template | `docker-compose.yml` | **Template** | EC2 |
-| Multi-service App | Multiple services | **Fargate** | Multiple stacks |
-| Background Workers | Queue/scheduling needs | **Lambda** | Fargate |
-| Microservices | Service architecture | **Fargate** + VPC | Multiple stacks |
-
----
-
-## Skill Content Structure
-
-### SKILL.md Format
-
-```yaml
----
-name: thunder:select-stack
-description: |
-  Analyzes project and recommends appropriate Thunder AWS deployment stack.
-  Use when user asks to deploy on AWS, setup infrastructure, or wants to
-  create a new deployment.
-argument-hint: [optional project description or specific stack name]
-disable-model-invocation: false
-allowed-tools: Read, Grep, Glob, Bash
----
-
-## Context
-When a user wants to deploy on AWS, follow this process:
-
-### Step 1: Project Analysis
-1. Read package.json to detect frameworks
-2. Check for existing configuration files (thunder.config.ts, bin/*.ts)
-3. Look for Dockerfile or docker-compose.yml
-4. Identify build scripts and entry points
-
-### Step 2: Framework Detection
-Common patterns:
-- React/Vue/Svelte SPA → Static stack
-- Nuxt.js → Nuxt stack
-- Astro → Astro stack
-- Next.js (with export) → Static stack
-- Next.js (with server) → Fargate stack
-- Express/Fastify API → Lambda or Fargate
-- Docker container → Fargate or EC2
-
-### Step 3: Ask Clarifying Questions
-If multiple options apply:
-- "Do you need server-side rendering (SSR)?"
-- "Do you have a backend API?"
-- "Is this a static site or dynamic application?"
-- "Do you need WebSocket support?"
-- "Do you have a Dockerfile?"
-
-### Step 4: Recommendation
-Present best option with:
-- Why this stack fits
-- Key features provided
-- Cost considerations
-- Alternative if applicable
-
-### Step 5: Configuration Generation
-Upon confirmation:
-1. Create bin/<stack>.ts entry point
-2. Create/update thunder.config.ts
-3. Add deployment scripts to package.json
-4. Provide next steps
-
-## Templates
-Reference files in ./templates/ directory for code generation.
-```
-
----
-
-## User Interaction Examples
-
-### Example 1: React SPA
-
-**User**: "Deploy my React app to AWS"
-
-**Claude Analysis**:
-- Detects React in package.json
-- Finds build script (likely `npm run build`)
-- No SSR indicators
-- No Dockerfile
-
-**Claude Response**:
-"I see you have a React application. The **Static** stack is perfect for this:
-
-**What it provides:**
-- S3 bucket for your built files
-- CloudFront CDN for fast global access
-- SSL certificate and custom domain support
-- Automatic cache invalidation on deploy
-- CI/CD pipeline integration
-
-**Next steps:**
-1. Build your app: `npm run build`
-2. Configure output directory (default: `dist` or `build`)
-3. Deploy with `th deploy`
-
-Shall I set up the Static stack configuration?"
-
-### Example 2: Nuxt.js Full-Stack
-
-**User**: "How do I deploy my Nuxt app?"
-
-**Claude Analysis**:
-- Detects Nuxt dependency
-- Finds nuxt.config.ts
-- Likely needs SSR support
-
-**Claude Response**:
-"I found your Nuxt.js project. For full-stack Nuxt apps, I recommend the **Nuxt** stack:
-
-**Architecture:**
-- Lambda functions for server-side rendering (SSR)
-- S3 bucket for static assets (JS, CSS, images)
-- CloudFront distribution with dual origins
-- API routes supported via API Gateway
-- Edge-optimized for global performance
-
-**Alternative:** If you need WebSocket support or long-running processes, consider the **Fargate** stack instead.
-
-Would you like me to configure the Nuxt stack?"
-
-### Example 3: Ambiguous Project
-
-**User**: "Deploy my app to AWS"
-
-**Claude Analysis**:
-- Limited context, no clear framework detected
-- Need to ask questions
-
-**Claude Response**:
-"I'd be happy to help you deploy to AWS! To recommend the best stack, I need to understand your application better:
-
-1. **What framework are you using?** (React, Vue, Nuxt, Astro, Express, etc.)
-2. **Does your app need server-side rendering (SSR)?**
-3. **Do you have a backend API?**
-4. **Is this a static site or dynamic application?**
-5. **Do you have a Dockerfile?**
-
-Or you can tell me more about your app and I'll analyze your project files."
-
----
-
-## Configuration Templates
-
-### thunder.config.ts Template
-
-```typescript
-export default {
-  application: '${application}',
-  service: '${service}',
-  environment: '${environment}',
-  env: {
-    account: process.env.CDK_DEFAULT_ACCOUNT,
-    region: process.env.CDK_DEFAULT_REGION || 'us-east-1',
-  },
-  
-  // Stack-specific configuration
-  $STACK_CONFIG
-};
-```
-
-### bin/<stack>.ts Template
-
-```typescript
-#!/usr/bin/env -S npx tsx
-import { App } from 'aws-cdk-lib';
-import { $StackName } from '@thunder-so/thunder';
-import config from '../thunder.config.ts';
-
-const app = new App();
-
-new $StackName(app, '$StackName', {
-  ...config,
-  $SPECIFIC_PROPS
-});
-
-app.synth();
-```
-
----
-
-## Implementation Phases
-
-### Phase 1: Foundation (Week 1)
-- [ ] Create `.claude/` directory structure
-- [ ] Write CLAUDE.md project context
-- [ ] Implement `select-stack` skill with framework detection
-- [ ] Implement `static` skill (most common use case)
-- [ ] Create templates for Static stack
-- [ ] Test with sample React project
-
-### Phase 2: Core Stacks (Week 2)
-- [ ] Implement `lambda` skill
-- [ ] Implement `fargate` skill
-- [ ] Implement `ec2` skill
-- [ ] Create templates for each
-- [ ] Add stack-specific configuration examples
-
-### Phase 3: Framework-Specific (Week 3)
-- [ ] Implement `nuxt` skill
-- [ ] Implement `astro` skill
-- [ ] Implement `template` skill
-- [ ] Create framework detection helpers
-- [ ] Add SSR vs SSG detection logic
-
-### Phase 4: Utilities & Polish (Week 4)
-- [ ] Implement `troubleshoot` skill
-- [ ] Implement `config` skill
-- [ ] Add comprehensive examples
-- [ ] Write skill documentation
-- [ ] Test with real projects
-
-### Phase 5: Plugin Packaging (Week 5)
-- [ ] Create `thunder-claude-plugin` directory
-- [ ] Write plugin.json manifest
-- [ ] Package skills for distribution
-- [ ] Write installation documentation
-- [ ] Publish to marketplace
-
----
-
-## Key Design Decisions
-
-### 1. Detection Strategy
-- **Automated detection** for clear cases (framework in package.json)
-- **Interactive questions** for ambiguous cases
-- **Confidence scoring** to determine when to ask
-
-### 2. Configuration Approach
-- Generate minimal viable configuration
-- Include helpful comments explaining options
-- Reference external docs for advanced settings
-- Allow user customization after generation
-
-### 3. Error Handling
-- Validate AWS credentials before generation
-- Check for existing configurations
-- Provide clear error messages with solutions
-- Offer rollback options
-
-### 4. Documentation Integration
-- Link to existing `.agents/` documentation
-- Include inline comments in generated code
-- Reference PRD and CLI docs
-- Provide external resource links
-
----
-
-## Testing Strategy
-
-### Test Scenarios
-1. **React SPA** → Static stack
-2. **Nuxt SSR app** → Nuxt stack
-3. **Express API** → Lambda or Fargate
-4. **Docker app** → Fargate or EC2
-5. **Multi-service app** → Multiple stacks
-6. **Ambiguous project** → Interactive flow
-
-### Validation Checklist
-- [ ] Skill triggers on appropriate prompts
-- [ ] Correct stack recommended for project type
-- [ ] Generated files are syntactically correct
-- [ ] Configuration matches project structure
-- [ ] User questions are relevant and helpful
-- [ ] Error messages are clear and actionable
-
----
-
-## Future Enhancements
-
-### Advanced Features
-- **Multi-stack recommendations** for microservices
-- **Migration skills** (Static → Fargate, etc.)
-- **Cost estimation** before deployment
-- **Performance optimization** suggestions
-- **Security best practices** enforcement
-
-### Framework Support
-- TanStack Start
-- Angular AnalogJS
-- SvelteKit
-- React Router v7
-- SolidStart
-
-### Integration Points
-- CI/CD pipeline generation
-- Database setup assistance
-- Secrets management
-- Monitoring configuration
-- Custom domain setup
-
----
-
-## Success Metrics
-
-### User Experience
-- Time to first deployment reduced by 50%
-- Stack selection accuracy >90%
-- User satisfaction with recommendations
-- Reduced support questions
-
-### Technical
-- All major framework types covered
-- Generated configs deploy successfully
-- Skills trigger appropriately
-- No false positives in detection
-
-### Adoption
-- Skills used in X% of new projects
-- Plugin installations (if distributed)
-- Community contributions
-- Documentation engagement
-
----
-
-## Resources
-
-### Documentation
-- [Claude Code Skills Documentation](https://docs.anthropic.com/en/docs/claude-code/skills)
-- [Claude Code Plugins](https://docs.anthropic.com/en/docs/claude-code/plugins)
-- [Thunder PRD](./PRD.md)
-- [Thunder CLI Scope](./CLI.md)
-
-### References
-- Agent Skills standard: https://agentskills.io
-- AWS CDK patterns: https://docs.aws.amazon.com/cdk/
-- Framework detection: package.json analysis
-
----
-
-## Notes
-
-- Keep SKILL.md files under 500 lines
-- Use frontmatter for metadata
-- Include examples in separate files
-- Test with real projects before finalizing
-- Document edge cases and limitations
-- Consider monorepo scenarios
-- Support both TypeScript and JavaScript projects
-
----
-
-**Last Updated**: 2026-03-08
-**Status**: Planning Complete - Ready for Implementation