@raclettejs/core 0.0.3 → 0.0.4

package/LICENSE.md

@@ -0,0 +1,39 @@
+# License
+
+## GNU Affero General Public License v3.0 with Application Exception
+
+@raclettejs/core is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only) with the following exception:
+
+### Application Exception
+
+**Applications that use @raclettejs/core as a dependency are not required to be licensed under AGPL-3.0.**
+
+This exception allows you to:
+
+- Build commercial applications using @raclettejs/core
+- Keep your application source code closed source
+- Distribute your applications under any license you choose
+
+### What Requires AGPL-3.0 Compliance
+
+The following activities require full AGPL-3.0 compliance (source code must be made available):
+
+- **Modifying @raclettejs/core itself** and distributing those modifications
+- **Creating derivative frameworks** based on raclette core
+- **Offering @raclettejs/core functionality as a network service** (hosting platforms, development tools, deployment services, etc.)
+- **Redistributing @raclettejs/core** (modified or unmodified) as part of another framework or tool
+
+### Summary
+
+- ✅ **Applications using @raclettejs/core:** Can be closed source (you can also offer them as SaaS)
+- ❌ **Services offering @raclettejs/core:** Must be open source
+- ❌ **Modified versions of @raclettejs/core:** Must be open source
+- ❌ **Frameworks based on @raclettejs/core:** Must be open source
+
+---
+
+**Full License Text**
+
+The complete GNU Affero General Public License v3.0 can be found at: https://www.gnu.org/licenses/agpl-3.0.html
+
+**Copyright (c) 2025 Pacifico Digital Explorations GmbH**

package/README.md

@@ -1,435 +1,42 @@
-# raclette
+## What is **raclette**?
 
-Welcome :)
+**raclette** is a full-stack TypeScript meta-framework designed for building **platforms and portals** with minimal setup. It comes with bootstrapped features like authentication, WebSockets, database handling, containerization, and provides an easy-to-use, opinionated environment.
 
-## Notes
+**Perfect for:**
 
-run `yarn build` here to generate the "dist" folder. Post-Installation Hook would be perfect here!
+- 🚀 **SaaS platforms** - Get to market faster with built-in auth and user management
+- 🏢 **Customer/Supplier portals** - Enterprise-ready from day one
+- 🛠️ **Internal business tools** - Focus on business logic, not infrastructure
+- ⚡ **MVPs that can scale** - Start fast, grow clean with the plugin architecture
 
-Then run `raclette dev` in your app folder. When using `yarn link` the raclette command should be globally available (at least works on Mac)
+**Key Features:**
 
-This will generate a .raclette folder based on your raclette.config.ts file in the app.
+- **Widget-based frontend** (Vue.js + Vite, React support coming)
+- **Plugin architecture** for reusable business logic
+- **Built-in workbench** - Admin interface out of the box
+- **Full-stack development** with Fastify backend + MongoDB
+- **Docker containerization** for easy deployment
 
-## VSCode Launch for debugging
+## What You Get
 
-### CLI Tool
+- ✅ **raclette core & workbench** dependencies with dev dependencies
+- ✅ **raclette.config.js** - Main configuration file
+- ✅ **Development scripts** ready to go
+- ✅ **ESLint + Prettier** configuration
+- ✅ **TypeScript** setup
+- ✅ **Docker-ready** development environment
 
-```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"
-}
-```
+## [Getting Started](https://docs.raclettejs.com/docs/introduction/getting-started)
 
-**Important:** To enable debugging, you must add this into your raclette.config:
+Visit the [Getting Started Guide](https://docs.raclettejs.com/docs/introduction/getting-started) in our [online Documentation](https://docs.raclettejs.com)
 
-```typescript
-services: {
-  backend: {
-    enableDebug: true,
-  }
-}
-```
+## Links
 
----
+- 🌐 [Website](https://raclettejs.com/)
+- 📚 [Documentation](https://docs.raclettejs.com/)
+- 🚀 [GitLab](https://gitlab.com/raclettejs) (source code)
+- 📦 [npm](https://www.npmjs.com/org/raclettejs) (packages)
 
-# Raclette Framework Technical Documentation
+## License
 
-## 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
+[AGPL-3.0-only](https://gitlab.com/raclettejs/core/-/blob/main/LICENSE?ref_type=heads)

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@raclettejs/core",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "racletteJS core package",
-  "repository": "https://gitlab.com/raclettejs/raclette-core",
+  "repository": "https://gitlab.com/raclettejs/core",
   "author": "Pacifico Digital Explorations GmbH <info@raclettejs.com>",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -34,7 +34,8 @@
     "index.js",
     "README.md",
     "yarn.lock",
-    "src/types.ts"
+    "src/types.ts",
+    "LICENSE.md"
   ],
   "exports": {
     ".": {