# Cellar Static Deploy - Project Documentation

## Project Overview

This is a CLI tool for deploying static websites to Clever Cloud Cellar (S3-compatible storage). The project uses Bun runtime exclusively and follows a modular TypeScript architecture.

## Architecture

### Modular Structure

```
├── index.ts              # Main entry point
├── src/
│   ├── types.ts          # Types, interfaces, constants, and utilities
│   ├── cli.ts            # CLI argument parsing and prompts
│   ├── s3-client.ts      # S3/Cellar operations
│   ├── file-utils.ts     # File system and upload utilities
│   └── dns-utils.ts      # DNS validation and CNAME checking
├── package.json          # NPM package configuration
├── CHANGELOG.md          # Version history
└── README.md            # User documentation
```

### Key Components

1. **CLI Module** (`src/cli.ts`)
   - Interactive prompts using `inquirer`
   - Argument parsing with `@bomb.sh/args`
   - Environment variable support
   - DNS check command handling

2. **S3 Client Module** (`src/s3-client.ts`)
   - Bucket management (creation, verification)
   - Parallel batch deletion
   - Error handling with specific S3 error codes

3. **File Utils Module** (`src/file-utils.ts`)
   - Recursive directory scanning
   - MIME type detection
   - Parallel file uploads with worker pools

4. **DNS Utils Module** (`src/dns-utils.ts`)
   - CNAME record validation
   - DNS troubleshooting and error reporting
   - Cellar endpoint verification

5. **Types Module** (`src/types.ts`)
   - Shared interfaces and constants
   - Configuration types and utility functions
   - API endpoints and validation logic

## Bun Usage Guidelines

- Use `bun run index.ts` to execute the application
- Use `bun install` for dependency management
- Use `bun test` for testing (when tests are added)
- Leverage Bun's native S3Client instead of AWS SDK
- Use `Bun.file()` for file operations

## Development Workflow

### Running the Tool

```bash
# Interactive mode
bun run index.ts

# With CLI arguments
bun run index.ts --domain example.com --path ./dist

# Check DNS configuration
bun run index.ts check-dns --domain www.example.com

# Show help
bun run index.ts --help
```

### Key Features

- **Parallel Processing**: Upload and deletion operations use configurable worker pools
- **Progress Tracking**: Real-time progress with rates and statistics  
- **Error Recovery**: Comprehensive error handling with user guidance
- **Environment Support**: Automatic detection of Cellar environment variables
- **DNS Validation**: Built-in CNAME checking with troubleshooting guidance
- **APEX Domain Prevention**: Validation to ensure subdomains are used
- **Type Safety**: Full TypeScript with JSDoc documentation
- **Code Quality**: DRY principles with centralized utilities and constants

### Dependencies

- `@bomb.sh/args`: CLI argument parsing
- `inquirer`: Interactive prompts
- `@types/inquirer`: TypeScript definitions

### Code Quality

- All functions have JSDoc documentation
- Imports are organized alphabetically
- English-only comments and messages
- Proper ellipsis characters (…) in user messages
- Consistent error handling patterns
- DRY principles with centralized utilities
- Modular architecture with clear separation of concerns

## Release Process

Current version: 0.2.0

- Version management in `package.json`
- Changelog maintenance in `CHANGELOG.md`
- Apache 2.0 license
- GitHub repository: `https://github.com/davlgd/cellar-static-deploy`