chadstart 1.0.0

package/docs/access-policies.md

@@ -0,0 +1,155 @@
+---
+id: access
+title: Access Policies & Authorization
+description: Learn how to implement API policies to restrict resource access for CRUD operations and endpoints.
+---
+
+# Access policies
+
+Access Policies ensure that we provide specific access to resources for users. You may want to open publicly the **read** access for an entity while limiting **creation** to logged in users for example.
+
+Access policies are a way to implement **Authorization** following the RBAC (Role-Based Access Control) method. Indeed it is possible to create different entities (ex: User, Manager...) with different access to resources. You also can limit access to a user own's records using [ownership-based access](#ownership-based-access).
+
+Policies can be added to [entities](./entities.md) and [endpoints](./functions.md).
+
+!!! info
+    By default, all CRUD rules access are set to **admin** and thus only available for logged-in admins. Custom endpoints are **public** by default.
+
+## Syntax
+
+The policies for each rule can be added to each [entity description](./entities.md) as shown below:
+
+```yaml
+entities:
+  Invoice 🧾:
+    properties:
+      - number
+      - { name: issueDate, type: date }
+    policies:
+      create:
+        - { access: restricted, allow: User } # Only logged in users can create.
+      read:
+        - access: public # All read endpoints are public.
+      update:
+        - access: admin # Only logged in admins can update.
+      delete:
+        - access: forbidden # No one can delete (even admins!)
+```
+
+In this case, everyone can see the **Invoice** items, only logged-in **Users** can create new ones. Updating an Invoice is restricted to [Admins](./auth.md#admins) only and no one can delete them (not even Admins).
+
+| Prop       | Description                                                               | Type               |
+| ---------- | ------------------------------------------------------------------------- | ------------------ |
+| **access** | The type of access: **public**, **restricted**, **admin**, **forbidden**  | AccessType         |
+| **allow**  | Only for **restricted** access: the entity (or entities) that have access | string \| string[] |
+
+### Access types
+
+There are 4 possible access types:
+
+| Access         | Description                                                                                                                                                                                                                                                                                                        | Short version (emoji) |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
+| **public**     | Everyone has access                                                                                                                                                                                                                                                                                                | 🌐                    |
+| **restricted** | Only logged-in users have access to it. The _allow_ key must be used to specify one or several [authenticable entities](./auth.md#authenticable-entities) that will have access to the content. If _condition_ is set to `self`, it limits access to the item owner. Admins always have access to restricted rules | 🔒                    |
+| **admin**      | Only [admins](./auth.md#admins) have access                                                                                                                                                                                                                                                                        | 👨🏻‍💻                    |
+| **forbidden**  | No one has access, not even admins                                                                                                                                                                                                                                                                                 | 🚫                    |
+
+### Entity rules
+
+Each entity has **5 rules** where one or several access policies can be applied:
+
+- **create**: create a new item
+- **read**: see the detail and the list of items
+- **update**: update an existing item
+- **delete**: delete an existing item
+- **signup**: sign up as a new user (only for [authenticable entities](./auth.md#authenticable-entities))
+
+By default, all rules have the [admin access type](#access-types)
+
+## Ownership-based access
+
+Above rules are based on predefined roles, but you many want to grant user access only to their own records. For example, a platform like _Craigslist_ allows its users to create and manage classified ads only for them, not letting users edit others' content.
+
+In ChadStart, this is done simply by adding the `{condition: 'self'}` to a restricted policy:
+
+```yaml
+User:
+  properties:
+    - name
+  authenticable: true
+
+Project:
+  properties:
+    - name
+  belongsTo:
+    - User # Should belong to an authenticable entity.
+  policies:
+    create:
+      - { access: restricted, allow: User, condition: self }
+```
+
+See? Just adding the `self` condition prevent creating projects for other users than themselves.
+
+Even if it looks very simple, it has slightly different impact based on rule where it is added. See the following example:
+
+```yaml
+policies:
+  create:
+    - { access: restricted, allow: User, condition: self }
+  read:
+    - { access: restricted, allow: User, condition: self }
+  update:
+    - { access: restricted, allow: User, condition: self }
+  delete:
+    - { access: restricted, allow: User, condition: self }
+```
+
+This means:
+
+- Create: Record creation is authorized only if owner is the logged in user
+- Read: You can only fetch your own record: it forces a filter
+- Update: You only can update your own records and cannot change the ownership of them
+- Delete: You only can delete your own records
+
+## Additional examples
+
+```yaml
+entities:
+  Project 🗂️:
+    properties:
+      - name
+    belongsTo:
+      - Manager
+    policies:
+      read:
+        - { access: restricted, allow: [Contributor, Manager] } # Only some entities (and admins).
+      create:
+        - { access: restricted, allow: Manager, condition: self } # Only managers for themselves (and admins).
+      update:
+        - access: 👨🏻‍💻 # Only admin.
+      delete:
+        - access: 🚫 # Forbidden (no one).
+
+  Contributor 👨‍💼:
+    authenticable: true
+    properties:
+      - name
+    policies:
+      signup:
+        - access: 🚫 # Forbidden (no one).
+      create:
+        - { access: 🔒, allow: Manager } # Managers can create contributors.
+      update:
+        - { access: 🔒, allow: Manager }
+      delete:
+        - { access: 🔒, allow: Manager } # Managers can create contributors.
+
+functions:
+  basicEndpoint:
+    path: /basic
+    description: A basic endpoint that returns a simple message.
+    method: GET
+    function: basicEndpoint.js
+    policies:
+      - access: public # This endpoint is public.
+```

package/docs/admin-ui.md

@@ -0,0 +1,29 @@
+# Admin UI
+
+ChadStart ships with a built-in dark-mode single-page Admin UI at `/admin`.
+
+## Features
+
+- **Sidebar** with all entities and user collections
+- **Data table** with CRUD (create, edit, delete) for every record
+- **Login screen** — any user collection with `admin: true` (default) can sign in
+
+## Access
+
+Navigate to `http://localhost:3000/admin` and log in with credentials from any user collection that has `admin: true`.
+
+## Excluding Collections from Admin
+
+Set `admin: false` on a collection to prevent it from logging into the Admin UI:
+
+```yaml
+userCollections:
+  Customer:
+    properties:
+      - name
+    admin: false   # cannot log in to Admin UI
+```
+
+## Rate Limiting
+
+Admin UI is rate-limited to **100 requests / minute per IP**.

package/docs/angular.md

@@ -0,0 +1,69 @@
+---
+id: angular
+title: Create a Full-Stack app with Angular and ChadStart
+description: Quick start guide to create a full-stack app using Angular as a frontend and ChadStart as a backend.
+---
+
+# Quick start with Angular
+
+Give a proper backend to your Angular 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 Angular app
+
+If you already have your Angular app up and running, skip this step.
+
+We will use the [Angular CLI](https://angular.dev/tools/cli) to create a new Angular project. You can replace `my-client` by the name of your front-end app.
+
+```
+ng new my-client
+cd my-client
+ng serve
+```
+
+## 2. Install ChadStart SDK
+
+Install the JS SDK from the root of your Angular 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.
+
+```js title="app.component.ts"
+import { Component } from '@angular/core'
+import ChadStart from '@chadstart/sdk'
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html',
+  styleUrls: ['./app.component.css']
+})
+export class AppComponent {
+  cats: { id: string, name: string }[] = []
+
+  async ngOnInit() {
+    // Init SDK.
+    const chadstart = new ChadStart()
+
+    // Fetch the list of Cats.
+    const result = await chadstart.from('cats').find()
+    this.cats = result.data
+  }
+}
+```
+
+And in the template:
+
+```html
+<ul>
+  <li *ngFor="let cat of cats">{{ cat.name }}</li>
+</ul>
+```
+
+Checkout the [SDK doc](./crud.md#using-the-javascript-sdk) to see more usages of the SDK: CRUD operations, file upload, authentication,

package/docs/astro.md

@@ -0,0 +1,71 @@
+---
+id: astro
+title: Create a Full-Stack app with Astro and ChadStart
+description: Quick start guide to create a full-stack app using Astro as a frontend and ChadStart as a backend.
+---
+
+# Quick start with Astro
+
+Connect your ChadStart backend to your Astro 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 Astro app
+
+If you already have your Astro app up and running, skip this step. Replace `my-astro-app` by the name of the Astro app created.
+
+```
+npm create astro@latest
+cd my-astro-app
+npm run dev
+```
+
+## 2. Install ChadStart SDK
+
+Install the JS SDK from the root of your Astro 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.
+
+```js
+---
+
+import ChadStart from '@chadstart/sdk'
+
+// Init SDK.
+const chadstart = new ChadStart()
+
+// Fetch the cat list.
+const result = await chadstart.from('cats').find()
+const cats = result.data
+
+---
+
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<meta name="viewport" content="width=device-width" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Astro</title>
+	</head>
+	<body>
+		<ul>
+			{
+				cats.map((cat) => (
+					<li>{cat.name}</li>
+				))
+			}
+		</ul>
+
+	</body>
+</html>
+```
+
+Checkout the [SDK doc](./crud.md#using-the-javascript-sdk) to see more usages of the SDK: CRUD operations, file upload, authentication,

package/docs/auth.md

@@ -0,0 +1,160 @@
+---
+id: authentication
+title: Authentication
+description: Implement Authentication quickly with ChadStart built-in Auth component. Manage log in, sign up and admin roles.
+---
+
+# Authentication
+
+## Introduction
+
+Authentication is the process of proving that people are who they say they are.
+
+ChadStart uses **JSON Web Tokens (JWT)** to do that. When you log in, you basically create a new **token** that you use in your next requests to prove your identity. This allows us to use [Policies](./access-policies.md) to grant or deny the access to some resources based on the user characteristics.
+
+!!! info
+    Notice the `TOKEN_SECRET_KEY` variable in your `.env` file ? This is the key that will encrypt your tokens, you can [generate one here](https://jwtsecrets.com/).
+
+## Admins
+
+Admins are a built-in entity that are **the only ones with access to the admin panel** (located at http://localhost:3000 by default). The admins are usually the people who manage the application on a day-to-day basis. Only admins can see and manage other admins.
+
+Even though they are the most powerful users of your application, you can still create some [policies](./access-policies.md) that will restrict the access even for them.
+
+The [seed command](./entities.md#collections) will create an admin with the email `admin@chadstart.com` and the password `admin`. You can create more admins from the admin panel.
+
+!!! tip
+    In ChadStart, the admin panel is **non-technical** 😺.
+
+    It means that you can give credentials to the administrators of your app without worrying that they will end up breaking the system!
+
+## Authenticable entities
+
+You can convert any entity into an **authenticatable entity**, allowing users to log in with it.
+
+```yaml
+entities:
+  Patient 🤒:
+    authenticable: true # Makes entity authenticable.
+    properties:
+      - name
+```
+
+Authenticable entities have 2 extra properties that are used as credentials to log in: `email` and `password`. You do not need to specify them.The `email` property expects a unique valid emails and the `password` property is automatically hashed using _bcryt_ with 10 salt rounds.
+
+## Actions
+
+### Login
+
+Log in your credentials as an **admin** or an **authenticable entity**.
+
+=== "REST API"
+    ```http title="Example HTTP Request"
+    POST /api/auth/admins/login
+    Content-Type: application/json
+    {
+      "email": "admin@chadstart.com",
+      "password": "password"
+    }
+    ```
+    ```json title="Example HTTP Response"
+    {
+      "token": "12345"
+    }
+    ```
+
+    Then you can add your token to your requests `Authorization` header using the **Bearer** prefix:
+
+    ```http
+    GET /api/dynamic/cats
+    Content-Type: application/json
+    Authorization: Bearer your-token-here
+    ```
+
+=== "JS SDK"
+    ```js
+    // Login as Admin.
+    await chadstart.login('admins', 'admin@chadstart.com', 'password')
+
+    // Login as User entity.
+    await chadstart.login('users', 'user@example.com', 'password')
+
+    // Then all following requests will have the authorization token in their header until logout.
+    const example = await chadstart.from('restricted-resource').find()
+    ```
+
+### Sign up
+
+Any authenticable entity allows new users to sign up if the [policies](./access-policies.md) permit it.
+
+=== "REST API"
+    ```http title="Example HTTP Request"
+    POST /api/auth/users/signup
+    Content-Type: application/json
+    {
+        "email": "user@example.com",
+        "password": "password"
+    }
+    ```
+    ```json title="Example HTTP Response"
+    {
+        "token": "12345"
+    }
+    ```
+
+    Same as [login](#login), you can add your token to your requests `Authorization` header using the **Bearer** prefix:
+
+    ```http
+    GET /api/dynamic/cats
+    Content-Type: application/json
+    Authorization: Bearer your-token-here
+    ```
+
+=== "JS SDK"
+    ```js
+    // Sign up as a new user.
+    await chadstart.signup('users', 'user@example.com', 'password')
+
+    // Then all following requests will have the authorization token in its header until logout.
+    const example = await chadstart.from('restricted-resource').find()
+    ```
+
+!!! info
+    It is not possible to sign up as an **admin**. If you want to create more admins, do it from the admin panel.
+
+### Get current user
+
+Get the current logged-in user.
+
+=== "REST API"
+    ```http title="Example HTTP Request"
+    GET /api/auth/contributors/me
+    Content-Type: application/json
+    Authorization: Bearer your-token-here
+    ```
+
+    ```json title="Example HTTP Response"
+    {
+      id: 'a8f5f167-6d3b-4c8f-9e2a-7b4d8c9f1e3a',
+      email: 'contributor@test.com'
+    }
+    ```
+
+=== "JS SDK"
+    ```js
+    // Get the current user (logged as Contributor entity).
+    const me = await chadstart.from('contributors').me()
+    ```
+
+### Logout
+
+Logout removes the token from future request headers.
+
+=== "REST API"
+    Reset the `Authorization` header as you usually do, and you are good to go!
+
+=== "JS SDK"
+    ```js
+    // Resets the "Authorization" header for all future calls.
+    await chadstart.logout()
+    ```

package/docs/cli.md

@@ -0,0 +1,56 @@
+# CLI
+
+ChadStart includes a CLI for common development and production tasks.
+
+## Commands
+
+```
+npx chadstart create [path]                     # Create a new ChadStart project
+npx chadstart dev [--config path] [--port N]    # Hot-reload dev server
+npx chadstart start [--config path] [--port N]  # Production server
+npx chadstart build [--config path]             # Validate & summarize config
+```
+
+## `create`
+
+Create a new ChadStart project
+
+```bash
+npx chadstart create
+npx chadstart create new-folder-name
+```
+
+## `dev`
+
+Starts the server with hot-reload on config file changes:
+
+```bash
+npx chadstart dev
+npx chadstart dev --config ./my-config.yaml
+npx chadstart dev --port 4000
+```
+
+## `start`
+
+Starts the server in production mode (no hot-reload):
+
+```bash
+npx chadstart start
+npx chadstart start --config ./my-config.yaml --port 8080
+```
+
+## `build`
+
+Validates the config file and prints a summary without starting the server:
+
+```bash
+npx chadstart build
+npx chadstart build --config ./my-config.yaml
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--config <path>` | Path to config file (default: `./chadstart.yaml`) |
+| `--port <number>` | Override port from config (default: `3000`) |

package/docs/config.md

@@ -0,0 +1,127 @@
+---
+id: config
+title: ChadStart Configuration
+description: Configure ChadStart Database (PostgreSQL, MySQL or SQLite), Port, OpenAPI and environments with a simple config.
+---
+
+# Configuration
+
+## Introduction
+
+ChadStart embraces the **convention over configuration** concept: it assumes several logical situations by default without showing you the setting to keep things as simple as possible.
+
+Nevertheless there is still the possibility to adapt your ChadStart app to your needs, especially through the `.env` file. Here is the list of available environment variables:
+
+## General variables
+
+General environment variables.
+
+| Variable      | Default                             | Description                                                                                                                                                 |
+| ------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| NODE_ENV      | `development`                       | The app environment. For production and staging instances, it should be set to `production`, mostly to turn off live reload on file change.                 |
+| PORT          | `3000`                              | The port of your app. You can either adapt your server settings to listen to `3000` or change here to your server's default.                |
+| BASE_URL      | `http://localhost:$PORT`            | The base url of your backend. Change it when deploying if you use [file or image upload](./upload.md)                                                       |
+| OPEN_API_DOCS | `true` unless `NODE_ENV=production` | Determines whether the OpenAPI doc is shown (formerly Swagger) for your REST API at `/api`. Make sure to set to `true` if you want to display on production |
+
+## Paths
+
+Environment variables related to paths.
+
+| Variable                 | Default         | Description                                                                                                                 |
+| ------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| PUBLIC_FOLDER            | `/public`       | The public folder to show [static files](https://expressjs.com/en/starter/static-files.html)                                |
+| CHADSTART_FUNCTIONS_FOLDER | `/functions`    | The folder to put your functions for [custom endpoints](./functions.md)                                          |
+| CHADSTART_FILE_PATH       | `/chadstart.yaml` | The relative or absolute path of your ChadStart YAML file                                                                    |
+| TOKEN_SECRET_KEY         | `-`             | The secret key behind the JWT authentication. Required on production, you can [generate one here](https://jwtsecrets.com/). |
+
+## Database
+
+By default ChadStart runs with [SQLite](https://www.sqlite.org/) to enable instant launch with the `npx chadstart` command.
+
+We recommend switching to [PostgreSQL](https://www.postgresql.org/) or [MySQL](https://www.mysql.com/) or its alternative [MariaDB](https://mariadb.org/) on production for more robustness and to choose from a large number of managed database providers.
+
+| Variable      | Default                | Description                                                               | Applies To         |
+| ------------- | ---------------------- | ------------------------------------------------------------------------- | ------------------ |
+| DB_CONNECTION | `sqlite`               | Choose `postgres` switching to PostgreSQL or `mysql` for MySQL or MariaDB | All                |
+| DB_PATH       | `/.chadstart/db.sqlite` | Path of the database. Your server should have access to this path locally | SQLite             |
+| DB_HOST       | `localhost`            | Database host                                                             | PostgreSQL / MySQL |
+| DB_PORT       | `5432`                 | Database port                                                             | PostgreSQL / MySQL |
+| DB_USERNAME   | `postgres`             | Database username                                                         | PostgreSQL / MySQL |
+| DB_PASSWORD   | `postgres`             | Database password                                                         | PostgreSQL / MySQL |
+| DB_DATABASE   | `chadstart`             | Database name                                                             | PostgreSQL / MySQL |
+| DB_SSL        | `false`                | Require SSL for DB connection. Set to true if using remote DB.            | PostgreSQL / MySQL |
+
+### Example configurations
+
+Here are examples of `.env` files for different database connections:
+
+=== "SQLite"
+    ```env
+
+     DB_CONNECTION=sqlite
+
+     DB_PATH=/.chadstart/db.sqlite
+
+     ```
+
+=== "PostgreSQL"
+    ```env
+
+     DB_CONNECTION=postgres
+
+     DB_HOST=my-host.com
+     DB_USERNAME=owner
+     DB_PASSWORD=xxxxx
+     DB_DATABASE=my_app
+     DB_SSL=true # Required for remote managed DBs, remove if local
+
+     ```
+
+=== "MySQL / MariaDB"
+    ```env
+
+    DB_CONNECTION=mysql
+
+    DB_USERNAME=xxxxx
+    DB_PASSWORD=xxxxx
+    DB_HOST=my-host.com
+    DB_PORT=25060
+    DB_DATABASE=my_app
+    DB_SSL=true # Required for remote managed DBs, remove if local
+
+    ```
+
+## Error Reporting
+
+ChadStart integrates with [Sentry](https://sentry.io) for automatic exception tracking in production.
+
+To enable, set **only** the `SENTRY_DSN` environment variable — the DSN is a secret and must never be placed in the YAML file.
+
+```env
+SENTRY_DSN=https://xxxxx@oXXXXX.ingest.sentry.io/XXXXXXX
+```
+
+Non-sensitive settings can be placed in `chadstart.yaml`:
+
+```yaml
+sentry:
+  environment: production   # optional — defaults to NODE_ENV
+  tracesSampleRate: 0.2     # optional — fraction 0.0–1.0, defaults to 1.0
+  debug: false              # optional — enable Sentry SDK debug logging
+```
+
+:::tip Self-hosted alternative: Bugsink
+[Bugsink](https://www.bugsink.com) is a lightweight, privacy-first, self-hosted alternative to Sentry that is **fully compatible with the Sentry SDK**. To use it, simply set `SENTRY_DSN` to your Bugsink ingest URL — no other code changes are needed.
+:::
+
+## Integrating ChadStart
+
+**ChadStart has been designed to be easily integrated**, providing a simple yet complete backend to any tool. See how it runs on [Stackblitz](https://chadstart.new) for example.
+
+The backend fits in an [NPM Package](https://www.npmjs.com/package/chadstart) that you can add to your dependencies simply by running `npm install chadstart`. By default, ChadStart uses [SQLite](https://www.sqlite.org/), the n°1 file-based database. This means it's portable and doesn't require any kind of server to run.
+
+If you plan to run ChadStart on a **mounted drive** like most cloud editors do, add the `--mountedDrive` argument to the run command to prevent [watcher errors](https://github.com/remy/nodemon?tab=readme-ov-file#application-isnt-restarting):
+
+```
+npm run start -- --mountedDrive
+```