chadstart 1.0.0

package/docs/overrides/home.html

@@ -0,0 +1,350 @@
+{% extends "main.html" %}
+
+{% block tabs %}
+  {{ super() }}
+
+  <!-- ═══════════════════════════════════════════════════════════
+       HERO / PARALLAX SECTION
+       ═══════════════════════════════════════════════════════════ -->
+  <section class="mdx-container">
+
+    <!-- Tech grid background overlay -->
+    <div class="mdx-tech-bg" aria-hidden="true"></div>
+
+    <!-- Floating warrior mascots (parallax) -->
+    <div class="mdx-mascot mdx-mascot--left" aria-hidden="true">
+      <img
+        src="https://github.com/user-attachments/assets/9fc6de81-e30f-4f4d-becd-6b332cd5b208"
+        alt="ChadStart warrior mascot"
+        loading="lazy"
+      >
+    </div>
+    <div class="mdx-mascot mdx-mascot--right" aria-hidden="true">
+      <img
+        src="https://github.com/user-attachments/assets/1060a160-bfc2-471c-8503-5cbd71783d20"
+        alt="ChadStart warrior mascot"
+        loading="lazy"
+      >
+    </div>
+
+    <div class="md-grid md-typeset">
+      <div class="mdx-hero">
+
+        <!-- Left column: headline + CTA -->
+        <div class="mdx-hero__teaser">
+          <h1>Your backend.<br><span class="mdx-hero__accent">One YAML file.</span></h1>
+          <p class="mdx-hero__description">
+            ChadStart is an open-source Backend as a Service that fits in a
+            single YAML file. Define entities, auth, storage, and custom logic — then ship.
+          </p>
+
+          <div class="mdx-cta-group">
+            <a
+              href="{{ page.next_page.url | url }}"
+              title="Get Started"
+              class="mdx-cta mdx-cta--primary"
+            >
+              <span>Get Started &nbsp;→</span>
+            </a>
+            <a
+              href="{{ config.repo_url }}"
+              title="View on GitHub"
+              class="mdx-cta mdx-cta--ghost"
+            >
+              {% include ".icons/fontawesome/brands/github.svg" %}
+              <span>GitHub</span>
+            </a>
+          </div>
+        </div>
+
+        <!-- Right column: YAML preview -->
+        <div class="mdx-hero__code">
+          <pre><code class="language-yaml"><span class="nc">entities</span>:
+  <span class="nc">Post</span>:
+    <span class="na">fields</span>:
+      <span class="na">title</span>: <span class="s">string</span>
+      <span class="na">body</span>: <span class="s">text</span>
+      <span class="na">published</span>: <span class="s">boolean</span>
+
+  <span class="nc">User</span>:
+    <span class="na">authenticable</span>: <span class="kc">true</span>
+    <span class="na">fields</span>:
+      <span class="na">username</span>: <span class="s">string</span>
+      <span class="na">avatar</span>: <span class="s">image</span>
+
+<span class="nc">rateLimits</span>:
+  <span class="na">windowMs</span>: <span class="m">60000</span>
+  <span class="na">max</span>: <span class="m">100</span></code></pre>
+        </div>
+
+      </div>
+    </div>
+  </section>
+{% endblock %}
+
+{% block content %}
+
+  <!-- ═══════════════════════════════════════════════════════════
+       GETTING STARTED — quick commands
+       ═══════════════════════════════════════════════════════════ -->
+  <section class="mdx-getting-started">
+    <div class="md-grid md-typeset">
+      <h2 class="mdx-section-title">Get started in seconds</h2>
+
+      <div class="mdx-gs-steps">
+
+        <div class="mdx-gs-step">
+          <div class="mdx-gs-step__num">1</div>
+          <div class="mdx-gs-step__body">
+            <p class="mdx-gs-step__label">Create your project</p>
+            <div class="mdx-gs-step__code">
+              <pre><code>npx chadstart my-project --cursor</code></pre>
+              <span class="mdx-gs-step__note">
+                Replace <code>--cursor</code> with <code>--copilot</code>,
+                <code>--windsurf</code>, or omit entirely.
+              </span>
+            </div>
+          </div>
+        </div>
+
+        <div class="mdx-gs-step">
+          <div class="mdx-gs-step__num">2</div>
+          <div class="mdx-gs-step__body">
+            <p class="mdx-gs-step__label">Start the server</p>
+            <div class="mdx-gs-step__code">
+              <pre><code>cd my-project &amp;&amp; npm run start</code></pre>
+              <span class="mdx-gs-step__note">
+                Admin panel at <code>http://localhost:3000</code>
+                &nbsp;·&nbsp; REST API at <code>/api</code>
+              </span>
+            </div>
+          </div>
+        </div>
+
+        <div class="mdx-gs-step">
+          <div class="mdx-gs-step__num">3</div>
+          <div class="mdx-gs-step__body">
+            <p class="mdx-gs-step__label">Edit <code>chadstart.yaml</code> and ship</p>
+            <div class="mdx-gs-step__code">
+              <pre><code>npm run deploy</code></pre>
+              <span class="mdx-gs-step__note">
+                Deploy to any Node.js host or Docker container.
+              </span>
+            </div>
+          </div>
+        </div>
+
+      </div>
+    </div>
+  </section>
+
+  <!-- ═══════════════════════════════════════════════════════════
+       ALL FEATURES GRID
+       ═══════════════════════════════════════════════════════════ -->
+  <section class="mdx-features">
+    <div class="md-grid md-typeset">
+      <h2 class="mdx-section-title">Everything your backend needs</h2>
+      <div class="mdx-features__grid">
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">🧠</div>
+          <h3>Zero friction setup</h3>
+          <p>One command to scaffold a project. One YAML file to define everything. No sprawling config directories.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">🔑</div>
+          <h3>Authentication built-in</h3>
+          <p>Mark any entity as <code>authenticable: true</code> to get register, login, and JWT-based auth routes instantly.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">📊</div>
+          <h3>Admin panel included</h3>
+          <p>A full-featured admin UI is generated from your schema — browse, create, update, and delete records out of the box.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">🚀</div>
+          <h3>REST API in seconds</h3>
+          <p>Full CRUD REST endpoints are automatically generated for every entity. No boilerplate, no glue code.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">🤖</div>
+          <h3>LLM-friendly</h3>
+          <p>Plain YAML is easy for AI coding assistants to read and generate. Ship faster with Cursor, Copilot, or Windsurf.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">💻</div>
+          <h3>Runs anywhere</h3>
+          <p>Deploy to any Node.js host, use Docker, or run locally. Lightweight enough for a side project, solid enough for production.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">🗂️</div>
+          <h3>File &amp; image uploads</h3>
+          <p>Add <code>image</code> or <code>file</code> field types to get upload endpoints with optional S3 storage support.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">⚡</div>
+          <h3>Realtime &amp; webhooks</h3>
+          <p>Built-in WebSocket support and webhook triggers let you react to data changes in real time.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">🔌</div>
+          <h3>Custom endpoints</h3>
+          <p>Drop a <code>.js</code> file in your functions folder and wire it to any HTTP route in your YAML — full Express power, zero config.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">🛡️</div>
+          <h3>Access policies</h3>
+          <p>Control who can read, create, update, or delete each entity with a simple policy array — public, restricted, or admin-only.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">✅</div>
+          <h3>Validation</h3>
+          <p>Add field-level validation rules in YAML — min/max length, regex, required, and more. Invalid requests are automatically rejected.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">🌊</div>
+          <h3>Rate limiting</h3>
+          <p>Protect your API from abuse with configurable rate limits. Set <code>windowMs</code> and <code>max</code> with two lines of YAML.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">☁️</div>
+          <h3>S3 storage</h3>
+          <p>Plug in any S3-compatible provider for file uploads with a few environment variables. Works with AWS, Cloudflare R2, and more.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">🔀</div>
+          <h3>Middlewares</h3>
+          <p>Inject custom logic before or after any route. Great for logging, request transformations, or custom auth flows.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">👥</div>
+          <h3>Groups</h3>
+          <p>Assign users to groups to implement role-based access control. Define which groups can access which entities and operations.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">🔐</div>
+          <h3>Security hardening</h3>
+          <p>Helmet.js headers, CORS configuration, JWT secrets, and bcrypt password hashing — security best practices out of the box.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">📡</div>
+          <h3>OpenTelemetry</h3>
+          <p>Built-in observability with OpenTelemetry. Send traces and metrics to any OTLP-compatible backend like Grafana or Datadog.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">🗝️</div>
+          <h3>API keys</h3>
+          <p>Generate and manage API keys per entity. Control per-key permissions: create, read, update, delete for each collection.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">⌨️</div>
+          <h3>CLI</h3>
+          <p>The <code>chadstart</code> CLI scaffolds new projects in seconds, pre-configured for your favorite AI coding assistant.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">🧩</div>
+          <h3>Plugins</h3>
+          <p>Extend ChadStart with community or custom plugins. Add new field types, routes, or behaviors without forking the core.</p>
+        </div>
+
+        <div class="mdx-feature-card">
+          <div class="mdx-feature-card__icon">⚛️</div>
+          <h3>Framework integrations</h3>
+          <p>Official guides and SDK helpers for React, Vue, Angular, Svelte, and Astro. Drop in and start calling your API immediately.</p>
+        </div>
+
+      </div>
+    </div>
+  </section>
+
+{% endblock %}
+
+{% block footer %}
+  {{ super() }}
+{% endblock %}
+
+{% block scripts %}
+  {{ super() }}
+  <script>
+    (function () {
+      'use strict';
+
+      document.addEventListener('DOMContentLoaded', function () {
+        var hero        = document.querySelector('.mdx-container');
+        var mascotLeft  = document.querySelector('.mdx-mascot--left');
+        var mascotRight = document.querySelector('.mdx-mascot--right');
+
+        if (!hero || (!mascotLeft && !mascotRight)) return;
+
+        var scrollY    = 0;
+        var mouseX     = 0.5;   /* normalised 0-1, centred */
+        var mouseY     = 0.5;
+        var rafPending = false;
+
+        function applyParallax() {
+          var heroH    = hero.offsetHeight;
+          var progress = Math.min(scrollY / (heroH || 1), 1);
+
+          /* Scroll: mascots drift upward (foreground is faster than background) */
+          var scrollOffset = progress * 60;
+
+          /* Mouse: subtle lateral + vertical nudge gives depth illusion */
+          var mx = (mouseX - 0.5) * 30;   /* ±15 px */
+          var my = (mouseY - 0.5) * 15;   /* ±7.5 px */
+
+          /* Apply to the wrapper div; CSS float-animation lives on the img
+             so these two transforms never interfere with each other. */
+          if (mascotLeft) {
+            mascotLeft.style.transform =
+              'translate(' + (-mx) + 'px, ' + (-(scrollOffset + my)) + 'px)';
+          }
+          if (mascotRight) {
+            mascotRight.style.transform =
+              'translate(' + mx + 'px, ' + (-(scrollOffset + my)) + 'px)';
+          }
+
+          rafPending = false;
+        }
+
+        /* rAF batching: coalesces rapid scroll/mousemove events into one
+           paint-cycle update, capping work to ~60 fps automatically. */
+        function scheduleUpdate() {
+          if (!rafPending) {
+            rafPending = true;
+            requestAnimationFrame(applyParallax);
+          }
+        }
+
+        window.addEventListener('scroll', function () {
+          scrollY = window.scrollY || window.pageYOffset;
+          scheduleUpdate();
+        }, { passive: true });
+
+        document.addEventListener('mousemove', function (e) {
+          mouseX = e.clientX / window.innerWidth;
+          mouseY = e.clientY / window.innerHeight;
+          scheduleUpdate();
+        }, { passive: true });
+      });
+    }());
+  </script>
+{% endblock %}

package/docs/plugins.md

@@ -0,0 +1,59 @@
+# Plugin System
+
+ChadStart supports plugins to extend the server with custom routes and logic.
+
+## Configuration
+
+Add plugins in `chadstart.yaml`:
+
+```yaml
+plugins:
+  - repo: https://github.com/org/chadstart-plugin-auth
+  - path: ./my-local-plugin
+```
+
+| Option | Description |
+|--------|-------------|
+| `repo` | Load plugin from a remote GitHub repository |
+| `path` | Load plugin from a local directory |
+
+> ⚠️ Remote plugins execute arbitrary code. Only load plugins from trusted sources.
+
+## Plugin Interface
+
+A plugin is a Node.js module that exports an object with a `name` and a `register` function:
+
+```js
+module.exports = {
+  name: 'my-plugin',
+  register(app, core) {
+    // app — Express application instance
+    // core — ChadStart core utilities
+    app.get('/custom', (req, res) => res.json({ hello: 'world' }));
+  }
+};
+```
+
+## Local Plugin Example
+
+Create `./my-local-plugin/index.js`:
+
+```js
+module.exports = {
+  name: 'custom-routes',
+  register(app, core) {
+    app.get('/ping', (req, res) => res.json({ pong: true }));
+    app.post('/notify', (req, res) => {
+      // custom business logic
+      res.json({ sent: true });
+    });
+  }
+};
+```
+
+Then reference it in `chadstart.yaml`:
+
+```yaml
+plugins:
+  - path: ./my-local-plugin
+```

package/docs/react.md

@@ -0,0 +1,75 @@
+---
+id: react
+title: Create a Full-Stack app with React and ChadStart
+description: Quick start guide to create a full-stack app using React as a frontend and ChadStart as a backend.
+---
+
+# Quick start with React
+
+Give a proper backend to your React app.
+
+!!! warning
+    This quick start guide focuses exclusively on the **frontend**. To ensure the functionality of this code, your ChadStart backend must be [up and running](./getting-started.md#install-chadstart) at `http://localhost:3000`.
+
+## 1. Create a React app
+
+If you already have a React app, you can skip this step.
+
+There are several ways to do that. We will use the easiest one: **create-react-app**. You can replace `my-client` by the name of your front-end app.
+
+```
+npx create-react-app my-client
+cd my-client
+npm start
+```
+
+## 2. Install ChadStart SDK
+
+Install the JS SDK from the root of your React app.
+
+```
+npm i @chadstart/sdk
+```
+
+## 3. Use it in your app
+
+In that example we are using a Cat entity [created previously](entities.md). Replace it by your own entity. This example uses TypeScript, you can remove the typing to have plain JS.
+
+```js title="App.tsx"
+import ChadStart from '@chadstart/sdk';
+import { useEffect, useState } from "react";
+
+function App() {
+  interface Cat {
+    id: string;
+    name: string;
+  }
+
+  const [cats, setCat] = useState<Cat[]>([]);
+
+  useEffect(() => {
+    // Init SDK.
+    const chadstart = new ChadStart();
+
+    // Fetch the list of Cats.
+    chadstart.from("cats")
+      .find<Cat>()
+      .then((res) => {
+        setCat(res.data);
+      });
+  }, []);
+
+  // Display a list of Cats.
+  return (
+    <ul>
+      {cats.map((cat) => (
+        <li>{cat.name}</li>
+      ))}
+    </ul>
+  );
+}
+
+export default App;
+```
+
+Checkout the [SDK doc](./crud.md#using-the-javascript-sdk) to see more usages of the SDK: CRUD operations, file upload, authentication,

package/docs/realtime.md

@@ -0,0 +1,43 @@
+# Realtime
+
+ChadStart provides realtime event streaming via WebSocket.
+
+## Connecting
+
+Connect to the WebSocket server at `ws://localhost:3000/realtime`:
+
+```js
+const ws = new WebSocket('ws://localhost:3000/realtime');
+```
+
+## Subscribing to Events
+
+Send a `subscribe` message to listen for changes on a specific entity:
+
+```js
+ws.send(JSON.stringify({ type: 'subscribe', channel: 'Post' }));
+```
+
+Subscribe to `*` to receive all events:
+
+```js
+ws.send(JSON.stringify({ type: 'subscribe', channel: '*' }));
+```
+
+## Receiving Events
+
+```js
+ws.onmessage = (e) => {
+  const { event, data } = JSON.parse(e.data);
+  // event: 'Post.created' | 'Post.updated' | 'Post.deleted'
+  console.log(event, data);
+};
+```
+
+## Event Types
+
+| Event | Triggered When |
+|-------|---------------|
+| `EntityName.created` | A new record is created |
+| `EntityName.updated` | A record is updated |
+| `EntityName.deleted` | A record is deleted |

package/docs/s3-storage.md

@@ -0,0 +1,40 @@
+---
+id: s3-storage
+title: S3 Storage
+description: Use any S3-compatible storage to store your user assets in your ChadStart backend. Images, videos, documents...
+---
+
+# S3 Storage
+
+## Introduction
+
+ChadStart supports **S3 storage** to manage assets. To use it, ensure you have:
+
+- A **storage bucket** (or equivalent).
+- Access credentials with read and write permissions.
+
+## Configuration
+
+Define these variables in your `.env` file:
+
+```
+S3_BUCKET=my-bucket-name
+S3_ENDPOINT=https://your-s3-provider.com
+S3_REGION=XXX
+S3_ACCESS_KEY_ID=XXX
+S3_SECRET_ACCESS_KEY=XXX
+```
+
+Optionally, you can set a folder prefix to prepend your object path:
+
+```
+S3_FOLDER_PREFIX=development/chadstart
+```
+
+!!! note
+    S3 storage in ChadStart has been **validated** with **AWS S3** and **Digital Ocean Spaces**. Other S3-compatible providers may work, but they have not been officially tested.
+
+## ChadStart guides
+
+- [AWS S3 Storage guide](https://chadstart.com/integrations/s3-storage)
+- [Digital Ocean Spaces guide](https://chadstart.com/integrations/digital-ocean-spaces)

package/docs/security.md

@@ -0,0 +1,23 @@
+---
+id: security
+title: Security
+description: Implement Security in your ChadStart backend and make sure that your app is protected.
+---
+
+# Security
+
+Implement security measures in your ChadStart backend.
+
+## Rate limiting
+
+Rate-limiting can protect your backend from **brute-force attacks** by blocking requests after reaching a limit.
+
+You can implement one or several throttler definitions to limit API calls in the `chadstart.yaml` file. The following example allow no more than 2 calls per second, and 50 calls per minute:
+
+```yaml title="chadstart.yaml"
+name: my app
+
+rateLimits:
+  - { name: 'short', limit: 2, ttl: 1000 } # 2 requests per second
+  - { name: 'medium', limit: 50, ttl: 60000 } # 50 requests per minute.
+```