@raclettejs/core 0.0.1

package/README.md

@@ -0,0 +1,435 @@
+# raclette
+
+Welcome :)
+
+## Notes
+
+run `yarn build` here to generate the "dist" folder. Post-Installation Hook would be perfect here!
+
+Then run `raclette dev` in your app folder. When using `yarn link` the raclette command should be globally available (at least works on Mac)
+
+This will generate a .raclette folder based on your raclette.config.ts file in the app.
+
+## VSCode Launch for debugging
+
+### CLI Tool
+
+```json
+{
+  "type": "node",
+  "request": "launch",
+  "name": "Debug Raclette CLI",
+  "skipFiles": ["<node_internals>/**"],
+  "program": "${workspaceFolder}/bin/raclette.js",
+  "args": ["dev"],
+  "cwd": "${workspaceFolder}/apps/dev-setup",
+  "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+  "runtimeArgs": [
+    "--experimental-specifier-resolution=node",
+    "--enable-source-maps"
+  ],
+  "console": "integratedTerminal"
+}
+```
+
+**Important:** To enable debugging, you must add this into your raclette.config:
+
+```typescript
+services: {
+  backend: {
+    enableDebug: true,
+  }
+}
+```
+
+---
+
+# Raclette Framework Technical Documentation
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Framework Architecture](#framework-architecture)
+3. [Core Components](#core-components)
+   - [Configuration System](#configuration-system)
+   - [CLI Tool](#cli-tool)
+   - [Virtual File System](#virtual-file-system)
+   - [Docker Integration](#docker-integration)
+   - [Package Management](#package-management)
+   - [Type System](#type-system)
+4. [Development Workflow](#development-workflow)
+5. [Configuration Reference](#configuration-reference)
+6. [CLI Command Reference](#cli-command-reference)
+7. [Best Practices](#best-practices)
+
+## Introduction
+
+Raclette is a full-stack JavaScript/TypeScript framework designed to provide a Nuxt-like developer experience with Docker integration for service management. The framework aims to streamline development by offering:
+
+- Better IDE support without explicit dependency installation
+- A virtual file system for component overriding
+- Integrated Docker support for service management
+- Package management for both frontend and backend services
+- TypeScript type extensions for enhanced development experience
+
+## Framework Architecture
+
+Raclette follows a modular architecture with clear separation between core functionality and application-specific customizations.
+
+### Core Package Structure
+
+The main npm package `@raclettejs/core` provides both development tools and runtime components:
+
+```
+core/
+├── services/
+│   ├── frontend/       # frontend-side orchestrator (Vue or React)
+│   ├── backend/       # Fastify-based API backend
+├── bin/              # CLI executable files
+├── types/            # TypeScript type definitions
+└── scripts/          # Utility scripts
+```
+
+### Application Structure
+
+A Raclette application has the following structure:
+
+```
+my-raclette-app/
+├── services/
+│   ├── frontend/       # frontend-side components/overrides
+│   ├── backend/       # Server-side customizations
+├── plugins/          # App-specific plugins
+├── pages/            # Page components
+├── .raclette/        # Generated files (git-ignored)
+└── raclette.config.js  # Main configuration file
+```
+
+The `.raclette` directory is generated during development and contains:
+
+- Docker configurations
+- Virtual file system mappings
+- Service-specific package.json files
+- TypeScript declarations for IDE support
+
+## Core Components
+
+### Configuration System
+
+The configuration system uses `raclette.config.js` as the single source of truth for application settings.
+
+#### Configuration Loading Process
+
+1. The `config-loader.ts` module looks for a `raclette.config.js` file in the project root
+2. If found, it merges the user configuration with default values
+3. Environment variables from `.env` or `.env.production` files are incorporated
+4. The merged configuration is used throughout the framework
+
+```typescript
+// Example raclette.config.js
+export default {
+  name: "my-raclette-app",
+  services: {
+    frontend: {
+      enabled: true,
+      port: 3000,
+    },
+    backend: {
+      enabled: true,
+      port: 8080,
+    },
+    mongodb: {
+      enabled: true,
+      port: 27017,
+    },
+    cache: {
+      enabled: true,
+      port: 6379,
+    },
+  },
+  frontend: {
+    framework: "vue",
+    vue: {
+      plugins: ["my-plugin"],
+    },
+  },
+  modules: [
+    "raclette-auth",
+    ["raclette-admin", { roles: ["admin", "editor"] }],
+  ],
+  env: {
+    development: {
+      LOG_LEVEL: "debug",
+    },
+    production: {
+      LOG_LEVEL: "error",
+    },
+  },
+}
+```
+
+### CLI Tool
+
+The CLI tool (`cli.ts`) provides commands for development, building, and package management. It uses Commander.js to define commands and their options.
+
+#### Available Commands
+
+- `raclette dev`: Start development environment
+- `raclette down`: Stop Docker Compose services
+- `raclette build`: Build for production
+- `raclette add-package <target> <package...>`: Add a package to the project
+- `raclette init`: Initialize a new Raclette project
+
+The CLI ensures the `.raclette` directory exists and handles command execution with appropriate error handling.
+
+### Virtual File System
+
+The virtual file system (`virtual-file-system.ts`) enables component overriding with a priority-based approach. This allows application-specific files to override core framework files without directly modifying them.
+
+#### Priority Levels
+
+1. App files (highest priority) - Located in the application's directory
+2. Module files (medium priority) - From installed Raclette modules
+3. Core files (lowest priority) - From the core framework package
+
+The virtual file system:
+
+- Builds a mapping of file paths to their physical locations
+- Watches for file changes and updates the mapping accordingly
+- Provides a `resolveFile` function for resolving file paths based on priority
+
+This approach enables hot-reloading during development and ensures that application-specific overrides take precedence.
+
+### Docker Integration
+
+Raclette provides Docker integration for service management through `docker-generator.ts` and `dev-environment.ts`.
+
+#### Docker Compose Generation
+
+The framework generates `docker-compose.yml` files based on the configuration:
+
+1. It adds services for MongoDB and Cache if enabled
+2. In non-direct mode, it adds containers for frontend and backend
+3. It sets up volumes for node_modules and source code
+4. It configures healthchecks and dependencies between services
+
+#### Development Environment Setup
+
+During development:
+
+1. Docker services are started based on the generated compose file
+2. If running in direct mode, databases run in Docker while frontend and backend run directly
+3. Logs are filtered based on user preferences
+4. The environment properly handles shutdown and cleanup
+
+The system includes detailed error handling for Docker-related issues, providing guidance when Docker is not installed or not running.
+
+### Package Management
+
+The package management system (`package-manager.ts`) handles dependencies for frontend and backend services:
+
+1. It sets up node packages for services based on the configuration
+2. It copies project files to the `.raclette` directory
+3. It merges package.json files with extra dependencies
+4. It provides commands for adding packages to frontend or backend
+
+```bash
+# Example: Add a package to the frontend
+raclette add-package frontend vue-chartjs
+
+# Example: Add a package to the backend
+raclette add-package backend fastify-auth
+
+# Example: Add a package to both frontend and backend
+raclette add-package both lodash
+```
+
+### Type System
+
+The type system (`types-generator.ts`) generates TypeScript declarations for IDE support:
+
+1. It generates FastifyJS type augmentations for the backend
+2. It creates project-specific types based on the configuration
+3. It provides interfaces for Raclette configuration and modules
+
+The generated types enable autocompletion and type checking in IDEs without explicitly installing dependencies.
+
+## Development Workflow
+
+A typical development workflow with Raclette:
+
+1. Create a new Raclette project or navigate to an existing one
+2. Configure services and settings in `raclette.config.js`
+3. Run `raclette dev` to start the development environment
+4. Create or modify files in the `app` directory
+5. Changes are immediately reflected through hot-reloading
+6. Use `raclette add-package` to manage dependencies
+7. Use `raclette build` to prepare for production
+8. Use `raclette down` to stop services when finished
+
+## Configuration Reference
+
+### RacletteConfig Interface
+
+```typescript
+interface RacletteConfig {
+  name: string
+  services: {
+    frontend?: {
+      enabled: boolean
+      port: number
+      name?: string
+      nodeModulesVolume?: string
+    }
+    backend?: {
+      enabled: boolean
+      port: number
+      name?: string
+      nodeModulesVolume?: string
+    }
+    mongodb?: {
+      enabled: boolean
+      port: number
+      name?: string
+      volume?: string
+      databaseName?: string
+    }
+    cache?: {
+      enabled: boolean
+      port: number
+      name?: string
+      volume?: string
+    }
+    workbench?: {
+      enabled: boolean
+      port: number
+    }
+    [key: string]: any
+  }
+  modules: Array<string | [string, any]>
+  env: {
+    development: Record<string, any>
+    production: Record<string, any>
+    [key: string]: Record<string, any>
+  }
+  frontend: {
+    framework: "vue" | "react"
+    vue?: {
+      plugins: string[]
+    }
+    react?: {
+      plugins: string[]
+    }
+  }
+}
+```
+
+### RacletteModule Interface
+
+```typescript
+interface RacletteModule {
+  name: string
+  services?: Record<string, any>
+  extendConfig?: (config: RacletteConfig, options: any) => RacletteConfig
+  backendExtensions?: {
+    plugins?: string[]
+    routes?: string[]
+  }
+  frontendExtensions?: {
+    components?: string[]
+    plugins?: string[]
+  }
+  hooks?: Record<string, (...args: any[]) => Promise<void>>
+}
+```
+
+## CLI Command Reference
+
+### raclette dev
+
+Start the development environment.
+
+```bash
+raclette dev [options]
+```
+
+Options:
+
+- `-d, --direct`: Run app services directly instead of in containers
+- `-q, --quiet`: Run Docker Compose in detached mode without following logs
+- `--filter <service>`: Filter logs to specific services (comma-separated)
+
+### raclette down
+
+Stop Docker Compose services.
+
+```bash
+raclette down
+```
+
+### raclette build
+
+Build for production.
+
+```bash
+raclette build
+```
+
+### raclette add-package
+
+Add a package to the project.
+
+```bash
+raclette add-package <target> <package...>
+```
+
+Parameters:
+
+- `target`: frontend, backend, or both
+- `package`: One or more package names to install
+
+### raclette init
+
+Initialize a new Raclette project.
+
+```bash
+raclette init
+```
+
+## Best Practices
+
+### Directory Structure
+
+Follow the recommended directory structure:
+
+- Place frontend-specific files in `services/frontend`
+- Place backend-specific files in `services/backend`
+- Place shared code in `services/backend/src/shared`
+- Use the `plugins` directory for reusable components
+
+### Docker Usage
+
+- Use direct mode (`raclette dev -d`) for faster development iterations
+- For full Docker integration, omit the `-d` flag
+- Filter logs to focus on relevant services with `--filter`
+
+### Configuration
+
+- Keep all configuration in `raclette.config.js`
+- Use environment variables for sensitive information
+- Create `.env` files for development and `.env.production` for production
+
+### Module Development
+
+When creating Raclette modules:
+
+- Follow the `RacletteModule` interface
+- Use the `extendConfig` hook to modify the config
+- Provide clear documentation for module options
+- Test modules in isolation before integration
+
+### Performance Considerations
+
+- Use the virtual file system judiciously to avoid overhead
+- Prefer direct mode for development when possible
+- Consider using separate Docker volumes for node_modules to speed up builds

package/bin/check-dependencies.sh

@@ -0,0 +1,184 @@
+#!/bin/bash
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo_info() {
+    echo -e "${BLUE}📦 $1${NC}"
+}
+
+echo_success() {
+    echo -e "${GREEN}✅ $1${NC}"
+}
+
+echo_warning() {
+    echo -e "${YELLOW}⚠️  $1${NC}"
+}
+
+echo_error() {
+    echo -e "${RED}❌ $1${NC}"
+}
+
+# Ensure we're in the app directory
+cd /app
+
+# Create node_modules directory if it doesn't exist
+mkdir -p /app/node_modules
+
+# Files to track changes
+PACKAGE_JSON="/app/package.json"
+YARN_LOCK="/app/yarn.lock"
+HASH_FILE="/app/node_modules/.dependency-hashes"
+INSTALL_RESULT_FILE="/app/node_modules/.install-result"
+
+# Check if required files exist
+if [ ! -f "$PACKAGE_JSON" ]; then
+    echo_error "package.json not found at $PACKAGE_JSON"
+    echo "1" > "$INSTALL_RESULT_FILE"
+    exit 1
+fi
+
+# Calculate hashes for change detection
+echo_info "Calculating dependency hashes..."
+PACKAGE_HASH=$(md5sum "$PACKAGE_JSON" | cut -d' ' -f1)
+LOCK_HASH=""
+if [ -f "$YARN_LOCK" ]; then
+    LOCK_HASH=$(md5sum "$YARN_LOCK" | cut -d' ' -f1)
+fi
+
+echo_info "Package hash: $PACKAGE_HASH"
+echo_info "Lock hash: $LOCK_HASH"
+
+# Determine if we need to install
+NEED_INSTALL=false
+INSTALL_REASON=""
+
+if [ ! -f "$HASH_FILE" ]; then
+    NEED_INSTALL=true
+    INSTALL_REASON="First run or hash file missing"
+elif [ ! -d "/app/node_modules" ] || [ -z "$(ls -A /app/node_modules 2>/dev/null)" ]; then
+    NEED_INSTALL=true
+    INSTALL_REASON="Node modules missing or empty"
+else
+    # Check if hashes changed
+    STORED_HASHES=$(cat "$HASH_FILE" 2>/dev/null || echo "")
+    CURRENT_HASHES="$PACKAGE_HASH:$LOCK_HASH"
+    
+    if [ "$STORED_HASHES" != "$CURRENT_HASHES" ]; then
+        NEED_INSTALL=true
+        INSTALL_REASON="Dependencies changed"
+        echo_info "Stored hashes: $STORED_HASHES"
+        echo_info "Current hashes: $CURRENT_HASHES"
+    fi
+fi
+
+if [ "$NEED_INSTALL" = true ]; then
+    echo_info "$INSTALL_REASON, installing dependencies..."
+    
+    # Backup yarn.lock if it exists (for rollback in case of failure)
+    YARN_LOCK_BACKUP=""
+    if [ -f "$YARN_LOCK" ]; then
+        YARN_LOCK_BACKUP="/tmp/yarn.lock.backup"
+        cp "$YARN_LOCK" "$YARN_LOCK_BACKUP"
+        echo_info "Backed up yarn.lock"
+    fi
+    
+    # Install dependencies
+    echo_info "Running yarn install..."
+    if yarn install --network-timeout 300000; then
+        INSTALL_EXIT_CODE=0
+        echo_success "Dependencies installed successfully"
+        
+        # Calculate new lock file hash
+        NEW_LOCK_HASH=""
+        if [ -f "$YARN_LOCK" ]; then
+            NEW_LOCK_HASH=$(md5sum "$YARN_LOCK" | cut -d' ' -f1)
+        fi
+        
+        # Save current state
+        NEW_HASHES="$PACKAGE_HASH:$NEW_LOCK_HASH"
+        echo "$NEW_HASHES" > "$HASH_FILE"
+        echo_success "Saved dependency hashes: $NEW_HASHES"
+        
+        # Clean up backup
+        if [ -n "$YARN_LOCK_BACKUP" ] && [ -f "$YARN_LOCK_BACKUP" ]; then
+            rm "$YARN_LOCK_BACKUP"
+        fi
+        
+    else
+        INSTALL_EXIT_CODE=$?
+        echo_error "Yarn install failed with exit code $INSTALL_EXIT_CODE"
+        
+        # Restore yarn.lock backup if installation failed
+        if [ -n "$YARN_LOCK_BACKUP" ] && [ -f "$YARN_LOCK_BACKUP" ]; then
+            echo_warning "Restoring yarn.lock backup due to installation failure"
+            cp "$YARN_LOCK_BACKUP" "$YARN_LOCK"
+            rm "$YARN_LOCK_BACKUP"
+        fi
+    fi
+    
+    # Save exit code for external monitoring
+    echo "$INSTALL_EXIT_CODE" > "$INSTALL_RESULT_FILE"
+    
+    if [ $INSTALL_EXIT_CODE -eq 0 ]; then
+        echo_success "Dependency installation completed successfully"
+    else
+        echo_error "Dependency installation failed"
+        # Don't exit here - let the main process continue and handle the error
+    fi
+    
+else
+    echo_success "Dependencies are up to date, skipping installation"
+    echo "0" > "$INSTALL_RESULT_FILE"
+fi
+
+# Additional health checks
+echo_info "Performing health checks..."
+
+# Check if critical packages are available
+HEALTH_CHECK_FAILED=false
+
+# For frontend services, check if Vue/React is available
+if [ -f "/app/package.json" ]; then
+    if grep -q '"vue"' /app/package.json; then
+        if ! yarn list vue > /dev/null 2>&1; then
+            echo_warning "Vue is listed in package.json but not found in node_modules"
+            HEALTH_CHECK_FAILED=true
+        fi
+    fi
+    
+    if grep -q '"react"' /app/package.json; then
+        if ! yarn list react > /dev/null 2>&1; then
+            echo_warning "React is listed in package.json but not found in node_modules"
+            HEALTH_CHECK_FAILED=true
+        fi
+    fi
+fi
+
+# Check if node_modules has reasonable content
+NODE_MODULES_COUNT=$(find /app/node_modules -maxdepth 1 -type d | wc -l)
+if [ "$NODE_MODULES_COUNT" -lt 5 ]; then
+    echo_warning "Very few packages in node_modules ($NODE_MODULES_COUNT directories)"
+    HEALTH_CHECK_FAILED=true
+fi
+
+if [ "$HEALTH_CHECK_FAILED" = true ]; then
+    echo_warning "Health checks detected potential issues, but continuing..."
+fi
+
+# Display final status
+echo_info "Dependency check completed"
+echo_info "Final status: $(cat $INSTALL_RESULT_FILE)"
+
+# Continue with the original command that was passed to this script
+if [ $# -gt 0 ]; then
+    echo_info "Executing command: $@"
+    exec "$@"
+else
+    echo_info "No command provided, dependency check complete"
+fi

package/bin/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "url"
+import { dirname, join } from "path"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+import(join(__dirname, "../dist/cli.js")).catch((err) => {
+  console.error("Failed to start Raclette CLI:", err)
+  process.exit(1)
+})