# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

SecretsInstaller is a DevOps tool that migrates configuration files from a local directory structure to AWS Secrets Manager. It replaces the legacy `ServerEnvironmentBuilder` which generated .env files for Jenkins build servers.

## Development Commands

### Build and Run
```bash
# Install dependencies
pnpm install

# Run TypeScript directly with ts-node
npx ts-node SecretsInstaller.ts <source-dir> <environment> [--dry-run]

# Example commands (from README)
npx ts-node SecretsInstaller.ts ./central-configs dev --dry-run   # Preview migration
npx ts-node SecretsInstaller.ts ./central-configs dev             # Apply to dev
npx ts-node SecretsInstaller.ts ./central-configs production      # Apply to prod
```

### Development Tools
- Package manager: pnpm (v10.17.1)
- Node version: 24.8.0 (managed via Volta)
- TypeScript config: Strict mode enabled with modern ES2023 target

## Architecture

### Core Components

**SecretsMigration Class** (`SecretsInstaller.ts`)
- Main orchestration class for the migration process
- Handles AWS Secrets Manager operations (create, update, describe)
- Supports dry-run mode for testing

**Key Methods:**
- `migrate()`: Main entry point, orchestrates the full migration
- `discoverApps()`: Scans directory structure to find apps and their configs
- `migrateApp()`: Processes a single app's configuration files
- `uploadSecret()`: Creates or updates secrets in AWS Secrets Manager

### Directory Structure Expected
```
central-configs/
├── app-auth/
│   ├── env.json              # Environment variables (flattened)
│   ├── firebase.json         # Config files (stored as-is)
│   └── database.json
├── app-api/
│   ├── env.json
│   └── stripe.json
└── app-worker/
    └── env.json
```

### Secret Path Convention
Secrets are created with the pattern: `/{environment}/{app-name}/{config-type}`

Examples:
- `/dev/app-auth/env` - Environment variables
- `/dev/app-auth/firebase` - Firebase configuration
- `/production/app-api/stripe` - Stripe configuration

### Configuration Processing
- **Environment files** (`env.json`): Nested objects are flattened to uppercase env vars (e.g., `server.port` becomes `SERVER_PORT`)
- **Config files**: Stored as-is in JSON format
- **App name mapping**: Optional mapping from directory names to app names via `appMappings` config

## AWS Requirements

### IAM Permissions
The AWS user/role needs:
- `secretsmanager:CreateSecret`
- `secretsmanager:UpdateSecret`
- `secretsmanager:DescribeSecret`
- `secretsmanager:TagResource`

### Environment Variables
- `AWS_REGION`: Target AWS region (defaults to us-east-1)
- `AWS_PROFILE` or `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`: Authentication

## Usage Patterns

### Typical Workflow
1. Prepare config files in expected directory structure
2. Run dry-run to preview changes: `--dry-run`
3. Apply to development environment first
4. Verify secrets in AWS Console or CLI
5. Apply to production

### Error Handling
- Failed migrations are tracked in `results.failed[]`
- Existing secrets are updated (not overwritten)
- Migration summary shows created/updated/failed counts