Rustelo/templates/shared/README.md

# Shared Asset Repository

This directory contains the master repository of all assets that can be used by Rustelo implementation templates. This follows the DRY principle - all assets are defined once here and included by template variants as needed.

## Structure

```
shared/
├── scripts/              # Setup, build, database, deployment scripts
│   ├── setup/           # Installation and setup scripts
│   ├── build/           # Build and compilation scripts
│   ├── database/        # Database management scripts
│   ├── deploy/          # Deployment scripts
│   ├── testing/         # Testing and quality assurance scripts
│   └── utils/           # Utility scripts
├── configs/             # Configuration templates
│   ├── base/            # Base configurations (app.toml, database.toml, etc.)
│   ├── environments/    # Environment-specific configs (dev, prod, staging)
│   ├── features/        # Feature-specific configurations (auth, content, etc.)
│   └── examples/        # Example configurations
├── docker/              # Docker files for different purposes
│   ├── Dockerfile.dev   # Development Docker file
│   └── Dockerfile.cross # Cross-compilation Docker file
├── content/             # Sample content and localization
│   ├── locales/         # Localization files
│   ├── blog/            # Sample blog posts
│   └── pages/           # Sample pages
├── docs/                # Documentation templates
├── public/              # Public assets (images, logos, etc.)
├── src/                 # Source code templates
│   ├── main.rs.template # Main application entry point
│   └── lib.rs.template  # Library entry point
├── justfile.template    # Just task runner configuration
├── package.json.template # Node.js package configuration
├── Cargo.toml.template  # Rust package configuration
├── unocss.config.ts.template # UnoCSS configuration
└── rustelo-deps.toml.template # Rustelo dependency configuration
```

## Asset Inclusion System

Template variants use inclusion/exclusion patterns to select which assets they need:

### Template Manifest Format

Each template variant has a manifest that specifies:

```json
{
  "name": "basic",
  "includes": [
    "shared/scripts/setup/*.sh",
    "shared/scripts/build/build-docs.sh",
    "shared/configs/base/*.toml",
    "shared/docker/Dockerfile.dev"
  ],
  "excludes": [
    "shared/scripts/enterprise/*",
    "shared/configs/features/advanced/*"
  ],
  "template_files": [
    "shared/justfile.template",
    "shared/package.json.template",
    "shared/Cargo.toml.template",
    "shared/unocss.config.ts.template"
  ]
}
```

### Template Variables

All `.template` files support variable substitution:

- `{{project_name}}` - Project name
- `{{project_name_snake}}` - Project name in snake_case
- `{{template_variant}}` - Template variant (basic, enterprise, etc.)
- `{{rustelo_version}}` - Rustelo framework version
- `{{generation_timestamp}}` - When the template was generated
- `{{asset_source}}` - Where assets came from (local, remote, etc.)

## Adding New Assets

1. **Add the asset file** to the appropriate subdirectory
2. **Use template variables** if the asset needs customization
3. **Update template manifests** to include the new asset where appropriate
4. **Test with different variants** to ensure proper inclusion

## Maintaining DRY Principle

- **Single source of truth**: All assets live in `shared/`
- **Template variants include, don't duplicate**: Templates specify what to include, not what to copy
- **Easy updates**: Modify once in `shared/`, all templates benefit
- **Clear ownership**: Each asset has one canonical location

## Asset Types

### Scripts (`shared/scripts/`)
Executable shell scripts for various tasks:
- Setup and installation
- Build and compilation
- Database management
- Deployment
- Testing and validation

### Configurations (`shared/configs/`)
Configuration file templates:
- Base configurations for common settings
- Environment-specific configs
- Feature-specific configs
- Example configurations

### Templates (`shared/*.template`)
Core project file templates:
- Build system configuration
- Package management
- CSS/styling configuration
- Framework dependency management

### Content (`shared/content/`)
Sample content and localization:
- Blog posts
- Page content
- Localization files
- Menu structures

## Template Resolution Process

1. **Template selection**: User chooses a template variant
2. **Manifest loading**: CLI loads the template's manifest
3. **Asset resolution**: CLI processes include/exclude patterns
4. **File copying**: Matching assets are copied to target project
5. **Variable substitution**: Template variables are replaced in `.template` files
6. **File renaming**: `.template` extensions are removed

This approach ensures maintainability, reduces duplication, and provides flexibility for different implementation needs.