chadstart 1.0.0

package/docs/functions.md

@@ -0,0 +1,196 @@
+---
+id: functions
+title: Functions
+description: Add custom functions to your ChadStart app — with multiple runtimes, triggers, and formats.
+---
+
+# Functions
+
+## Introduction
+
+Functions let you run custom logic on the server. Each function can be triggered by one or more events: an HTTP request, a scheduled cron job, or an emitted application event.
+
+## Syntax
+
+```yaml title="chadstart.yaml"
+functions:
+  hello:
+    runtime: js         # js (default) | bash | python | go | c++ | ruby | php
+    function: hello.js  # file path relative to /functions (or CHADSTART_FUNCTIONS_FOLDER)
+    triggers:
+      - type: http
+        method: GET
+        path: /hello
+      - type: cron
+        schedule: "@daily"
+      - type: event
+        name: user.created
+```
+
+## Triggers
+
+### HTTP trigger
+
+Registers an HTTP route. The function receives an `event` object and a `ctx` context.
+
+```yaml
+triggers:
+  - type: http
+    method: GET   # GET | POST | PUT | PATCH | DELETE
+    path: /hello
+    # policies omitted → public (anyone can call)
+```
+
+#### Access policies
+
+Add a `policies` array to restrict who can call an HTTP trigger:
+
+```yaml
+triggers:
+  - type: http
+    method: GET
+    path: /public-data
+    policies:
+      - access: public        # Anyone can call (default when omitted)
+
+  - type: http
+    method: GET
+    path: /admin-data
+    policies:
+      - access: admin         # Any valid JWT is required
+
+  - type: http
+    method: GET
+    path: /customer-data
+    policies:
+      - access: restricted    # JWT required, filtered by entity
+        allow: Customer       # Only Customer tokens are allowed (string or array)
+
+  - type: http
+    method: GET
+    path: /disabled
+    policies:
+      - access: forbidden     # Always returns 403
+```
+
+**Policy access values:**
+
+| Value        | Emoji alias | Description                                                       |
+| ------------ | ----------- | ----------------------------------------------------------------- |
+| `public`     | `🌐`        | Open to everyone (default when `policies` is omitted)             |
+| `admin`      | `👨🏻‍💻`     | Requires any valid JWT (any entity)                               |
+| `restricted` | `🔒`        | Requires a valid JWT; combine with `allow` to limit to an entity  |
+| `forbidden`  | `🚫`        | Always returns 403 — disables the route                           |
+
+### Cron trigger
+
+Runs the function on a schedule. Supports standard cron expressions and predefined aliases.
+
+```yaml
+triggers:
+  - type: cron
+    schedule: "*/10 * * * *"  # every 10 minutes
+  - type: cron
+    schedule: "@daily"        # once a day at midnight
+```
+
+**Predefined aliases:**
+
+| Alias       | Equivalent      | Description              |
+| ----------- | --------------- | ------------------------ |
+| `@yearly`   | `0 0 1 1 *`     | Once a year, Jan 1st     |
+| `@annually` | `0 0 1 1 *`     | Same as @yearly          |
+| `@monthly`  | `0 0 1 * *`     | First day of each month  |
+| `@weekly`   | `0 0 * * 0`     | Every Sunday at midnight |
+| `@daily`    | `0 0 * * *`     | Every day at midnight    |
+| `@midnight` | `0 0 * * *`     | Same as @daily           |
+| `@hourly`   | `0 * * * *`     | Every hour               |
+
+### Event trigger
+
+Runs the function when a named event is emitted via the shared `eventBus`.
+
+```yaml
+triggers:
+  - type: event
+    name: user.created
+```
+
+Emit from middleware or other functions:
+
+```js
+const { eventBus } = require('./core/functions-engine');
+eventBus.emit('user.created', { id: user.id });
+```
+
+## Function formats (JS runtime)
+
+### Universal (recommended)
+
+```js title="functions/hello.js"
+module.exports = async function(event, ctx) {
+  if (ctx.trigger === 'http')  return { message: 'Hello from HTTP!' };
+  if (ctx.trigger === 'cron')  console.log('Running scheduled task');
+  if (ctx.trigger === 'event') console.log('Event payload:', event);
+};
+```
+
+The `event` object for HTTP triggers contains `{ req, body, query, params, headers }`.
+The `ctx` object always has `{ trigger, name }` plus trigger-specific fields (`method`, `path`, `schedule`, `event`).
+
+### AWS Lambda format
+
+```js title="functions/hello.js"
+exports.handler = async (event, context) => {
+  return { statusCode: 200, body: JSON.stringify({ message: 'Hello!' }) };
+};
+```
+
+### Cloudflare Workers format
+
+```js title="functions/hello.js"
+export default {
+  async fetch(request) {
+    return new Response(JSON.stringify({ message: 'Hello!' }), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  },
+};
+```
+
+## Runtimes
+
+| Runtime  | Execution          | Notes                            |
+| -------- | ------------------ | -------------------------------- |
+| `js`     | In-process         | Default. Supports all formats.   |
+| `python` | Persistent worker  | Reads `event` from stdin as JSON |
+| `ruby`   | Persistent worker  | Reads `event` from stdin as JSON |
+| `php`    | Persistent worker  | Reads `event` from stdin as JSON |
+| `bash`   | Per-invocation     | Reads `event` from stdin as JSON |
+| `go`     | Per-invocation     | `go run` per invocation          |
+| `c++`    | Per-invocation     | Compiled with `g++`              |
+
+Python/Ruby/PHP runtimes spawn one persistent worker process per runtime (not per request) for better performance.
+
+## Configuration
+
+### Function options
+
+| Option       | Default | Description                                          |
+| ------------ | ------- | ---------------------------------------------------- |
+| `function`*  | —       | File name relative to the functions folder           |
+| `runtime`    | `js`    | Runtime to use                                       |
+| `description`| —       | Optional description (shown in OpenAPI docs)         |
+| `triggers`*  | —       | Array of trigger definitions                         |
+
+### HTTP trigger options
+
+| Option     | Default  | Description                                              |
+| ---------- | -------- | -------------------------------------------------------- |
+| `type`*    | —        | `http`                                                   |
+| `method`   | `GET`    | HTTP verb: `GET` `POST` `PUT` `PATCH` `DELETE`           |
+| `path`*    | —        | URL path, e.g. `/hello` or `/users/:id/activate`         |
+| `policies` | `public` | Array of policy objects to restrict access (see above)   |
+
+!!! tip
+    Set `CHADSTART_FUNCTIONS_FOLDER` in your `.env` to use a different folder than `/functions`.

package/docs/getting-started.md

@@ -0,0 +1,79 @@
+---
+title: Get Started
+description: ChadStart is an Open Source backend that fits in a single YAML file. Easy to edit, validate and version for humans and LLMs.
+---
+
+# Get Started 👋
+
+## Introduction
+
+ChadStart is a **1-file backend** for prototypes and MVPs.
+
+Most backend tools feel too heavy for simple apps. They force you to use bloated configuration UIs. Even with AI tools that generate frontend code, the backend remains a pain to set up and validate. It slows you down when you just want to test an idea or build something simple.
+
+ChadStart is an open source backend that fits in only 1 file. You define it in a simple yaml language to get data, auth, storage, logic and an admin panel.
+
+**Key advantages:**
+
+- 🧠 Zero friction setup
+- 🚀 Ship your backend fast and stay focused on building your app
+- 🤖 Easy for LLMs to generate
+- 💻 Can run everywhere
+
+## Install ChadStart
+
+Follow the steps below to install ChadStart in your local machine.
+
+### Prerequisites
+
+- [NodeJS](https://nodejs.org/en/) (**20.x** or superior).
+
+### Installation steps
+
+Run this command to create a ChadStart project ready to use with Cursor IDE.
+
+```bash
+# NPX
+npx chadstart my-project --cursor
+
+# Yarn
+yarn create chadstart my-project --cursor
+```
+
+This will create a `my-project` folder with a ChadStart backend configured for Cursor.
+
+You can replace `--cursor` with another option if you're using a different AI tool:
+
+- `--copilot` if you're using **GitHub Copilot**
+- `--windsurf` for **Windsurf**
+- or remove it entirely if you're not using any AI coding tool
+
+To start the ChadStart backend, run the following command in the new project folder:
+
+```
+cd my-project
+npm run start
+```
+
+You can now:
+
+- See your **Admin panel** at http://localhost:3000 using the email `admin@chadstart.com` and the password `admin`
+
+- Use your **REST API** at http://localhost:3000/api
+
+!!! tip
+    If you already have a frontend app, we recommend that you use a **monorepo** structure with one folder for the backend and one folder for the frontend. For example you can run `npx chadstart server` at root level to add your ChadStart to a `server` folder that you put next to the `client` folder that will contain your frontend.
+
+#### Note with PNPM
+
+As [PNPM](https://pnpm.io/fr/) blocks postinstall scripts, we have to adapt the `package.json`. Add this to your `package.json` file before doing `pnpm install`:
+
+```json
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@nestjs/core",
+      "sharp",
+      "sqlite3"
+    ]
+  }
+```

package/docs/groups.md

@@ -0,0 +1,85 @@
+---
+id: groups
+title: Groups (nested entities)
+slug: groups
+description: TODO
+---
+
+# Groups (nested entities)
+
+A group is a **reusable set of properties** that you can attach to your entities: whether they are [single](./entities.md#singles) or [collections](./entities.md#collections). They help you structure your nested data without having to repeat yourself. Some common use cases for groups are:
+
+- Testimonials
+- FAQs
+- Widgets (CTA, UI elements like cards, blocks etc.)
+
+Groups are automatically loaded when you fetch a list or a detail version of the parent entity (using both REST API and SDK).
+
+## Syntax
+
+Define your groups in the `chadstart.yaml` file to use it in entities as a property.
+
+```yaml title="chadstart.yaml"
+entities:
+  Service:
+    properties:
+      - name
+      - { name: description, helpText: 'Description of the service' }
+      - {
+          name: testimonials,
+          type: group, # Group type indicates that it is a group.
+          helpText: 'Add some testimonials for the service',
+          options: { group: Testimonial } # Pass the name of the group in the "group" option
+        }
+
+groups:
+  Testimonial: # We create a testimonial group with 3 properties.
+    properties:
+      - { name: author, type: text }
+      - { name: content, type: text }
+      - { name: rating, type: number, helpText: '1 to 5 stars' }
+    validation:
+      rating: { isNotEmpty: true }
+```
+
+The code above will add testimonials to service. Once the `Testimonial` group is created, you can add it in as many entities as you want.
+
+## Non-multiple groups
+
+In the example above, each service can have several testimonials, but you can also have non-multiple groups.
+
+This example shows a backend for a website where each page has a single "call to action" element that can be used as widget UI.
+
+```yaml title="chadstart.yaml"
+  Homepage:
+    single: true
+    properties:
+      - { name: title, type: text }
+      - {
+          name: callToAction,
+          type: group,
+          options: { group: CallToAction, multiple: false }
+        }
+
+  AboutPage:
+    single: true
+    properties:
+      - { name: title, type: text }
+      - { name: description, type: text }
+      - {
+          name: callToAction,
+          type: group,
+          options: { group: CallToAction, multiple: false }
+        }
+
+groups:
+  CallToAction:
+    properties:
+      - { name: title, type: string }
+      - { name: description, type: text }
+      - { name: buttonText, type: string, helpText: "Text for the button" }
+      - { name: buttonLink, type: link }
+    validation:
+      title: { isNotEmpty: true }
+      description: { isNotEmpty: true }
+```

package/docs/index.md

@@ -0,0 +1,5 @@
+---
+template: home.html
+title: ChadStart — YAML-first Backend as a Service
+description: ChadStart is an Open Source backend that fits in a single YAML file. Easy to edit, validate and version for humans and LLMs.
+---

package/docs/llm-rules.md

@@ -0,0 +1,81 @@
+---
+id: llm-rules
+title: LLM Rules
+description: Configure AI coding assistants to understand your ChadStart YAML backend. Works with Cursor, GitHub Copilot, Windsurf, and more.
+---
+
+# LLM Rules
+
+ChadStart is designed to be **LLM-friendly**: the entire backend is described in a single YAML file that AI coding assistants can read, generate, and modify with ease.
+
+When you scaffold a new project with the `--cursor`, `--copilot`, or `--windsurf` flag, ChadStart automatically creates the appropriate rules file that teaches your AI assistant about the `chadstart.yaml` format.
+
+## Scaffolding with AI rules
+
+=== "Cursor"
+
+    ```bash
+    npx chadstart my-project --cursor
+    ```
+
+    Creates `.cursor/rules/chadstart.mdc` — a Cursor rules file that helps Cursor understand the ChadStart schema.
+
+=== "GitHub Copilot"
+
+    ```bash
+    npx chadstart my-project --copilot
+    ```
+
+    Creates `.github/copilot-instructions.md` — custom instructions for GitHub Copilot.
+
+=== "Windsurf"
+
+    ```bash
+    npx chadstart my-project --windsurf
+    ```
+
+    Creates `.windsurf/rules/chadstart.md` — rules for the Windsurf AI assistant.
+
+=== "No AI tool"
+
+    ```bash
+    npx chadstart my-project
+    ```
+
+    Creates the project without any AI assistant configuration.
+
+## What the rules file contains
+
+The generated rules file provides your AI assistant with:
+
+- The full `chadstart.yaml` schema (entities, fields, auth, policies, etc.)
+- Descriptions of available field types (`string`, `text`, `image`, `file`, `boolean`, `choice`, …)
+- Examples of common patterns (authenticable entities, access policies, relations)
+- Instructions on how to generate valid YAML for ChadStart
+
+This means you can describe your app in plain English and let Cursor, Copilot, or Windsurf write the `chadstart.yaml` for you.
+
+## Prompt examples
+
+Once the rules file is in place you can use prompts like:
+
+> *"Add a `Comment` entity with a `body` (text) field, a relation to `Post`, and make it authenticable so only the author can delete their own comments."*
+
+> *"Add rate limiting: max 100 requests per minute."*
+
+> *"Create a `Product` entity with a `name` (string), `price` (money), `image` (image), and a `category` choice field with options: Electronics, Clothing, Food."*
+
+## Manual setup
+
+If you already have an existing project and want to add AI rules manually, create one of the following files with content describing the [ChadStart YAML schema](./entities.md):
+
+| AI tool            | Rules file location                            |
+| ------------------ | ---------------------------------------------- |
+| **Cursor**         | `.cursor/rules/chadstart.mdc`                  |
+| **GitHub Copilot** | `.github/copilot-instructions.md`              |
+| **Windsurf**       | `.windsurf/rules/chadstart.md`                 |
+
+You can base your rules file on the [chadstart.example.yml](https://github.com/saulmmendoza/chadstart.com/blob/main/chadstart.example.yml) reference file, which documents every available configuration option.
+
+!!! tip
+    Keep your rules file up to date whenever you upgrade ChadStart. Newer versions may introduce new field types, options, or top-level blocks that your AI assistant won't know about unless the rules file is updated.

package/docs/middlewares.md

@@ -0,0 +1,78 @@
+---
+id: middlewares
+title: Middlewares
+description: Add middlewares to trigger custom logic at defined lifecycle events of your ChadStart backend. 6 available events related to entities.
+---
+
+## Introduction
+
+**Middleware functions** or **middlewares** are intermediary functions that sit between the client's request and the server's response. They have access to the request object (req) and the response object (res).
+
+As ChadStart works with **ExpressJS**, ChadStart middlewares are [ExpressJS middlewares](https://expressjs.com/en/guide/using-middleware.html) enhanced with the [ChadStart SDK](./crud.md#using-the-javascript-sdk) that allows you to interact with your data with ease.
+
+## Middleware use cases
+
+Here are some examples of middleware use cases:
+
+- Patch the request body before storing it in the DB
+- Call an external API or any other custom logic
+- Hide some data from the response
+- Trigger an internal or external action on an event (see also [webhooks](./webhooks.md))
+
+## Syntax
+
+```yaml title="chadstart.yaml"
+entities:
+  Project 🗂️:
+    properties:
+      - name
+      - { name: date, type: date }
+    middlewares:
+      beforeCreate:
+        - function: setDate.js
+      afterCreate:
+        - function: sendEmail.js
+```
+
+This example triggers the function located at `/functions/setDate.js` before the item is created and stored in the database, and triggers `/functions/sendEmail.js` after.
+
+```js title="/functions/setDate.js"
+module.exports = async (req, res) => {
+  console.log('Hello from the function!')
+
+  req.body['date'] = new Date()
+}
+```
+
+!!! tip
+    You can add **several middlewares** for an event. They will be processed sequentially in the order you define.
+
+## Use your data with the ChadStart backend SDK
+
+ChadStart passes the [JS SDK](./crud.md#using-the-javascript-sdk) to middleware functions as third argument. You can use it to fetch or write data.
+
+```js title="/functions/patchDocumentNameIfEmpty.js"
+module.exports = async (req, res, chadstart) => {
+  // If the 'name' property of the item is empty.
+  if (!req.body['name']) {
+    // Get the user from the request body.
+    const user = await chadstart.from('users').findOneById(req.body['userId'])
+
+    // Set a custom name based on the user.
+    req.body['name'] = `${user.name}'s untitled document`
+  }
+}
+```
+
+## Events
+
+This is the list and description of the 6 events available to which you can attach middlewares. All of them are related to an [entity](./entities.md)
+
+| Name             | Description              |
+| ---------------- | ------------------------ |
+| **beforeCreate** | Before creating a record |
+| **afterCreate**  | After creating a record  |
+| **beforeUpdate** | Before updating a record |
+| **afterUpdate**  | After updating a record  |
+| **beforeDelete** | Before deleting a record |
+| **afterDelete**  | After deleting a record  |