@ghentcdh/crouton-cli 0.0.1-alpha.81 → 0.0.1-alpha.89

package/agent-files/.claude/skills/crouton/references/relations.md

@@ -0,0 +1,150 @@
+# Relations — recipes
+
+Relations are configured on the **column** via `column.relation`, not inside `fieldInput.options`.
+`fieldInput` only picks and configures the UI widget.
+
+## manyToOne (autocomplete lookup)
+
+Use when: this resource has a FK column pointing to another resource (e.g. `book.authorId → author.id`).
+
+```json
+{
+  "columns": {
+    "authorId": {
+      "label": "Author",
+      "relation": {
+        "resource": "./author/resource.json",
+        "type": "manyToOne",
+        "foreignKey": "authorId",
+        "displayKey": "name"
+      },
+      "fieldInput": {
+        "type": "autocomplete"
+      }
+    }
+  },
+  "operations": {
+    "findAll": {
+      "include": [
+        "author"
+      ]
+    },
+    "findOne": {
+      "include": [
+        "author"
+      ]
+    }
+  }
+}
+```
+
+- `relation.resource`: relative path to the target `resource.json`
+- `relation.foreignKey`: FK column on **this** resource
+- `relation.displayKey`: field on the related record shown in the dropdown
+- `fieldInput.type`: `"autocomplete"` for manyToOne (renders a search dropdown)
+
+## oneToMany (embedded table / panel)
+
+Use when: another resource has a FK pointing to this one (e.g. `review.bookId → book.id`).
+
+```json
+{
+  "columns": {
+    "reviews": {
+      "label": "Reviews",
+      "hiddenInTable": true,
+      "hiddenInForm": true,
+      "relation": {
+        "resource": "./review/resource.json",
+        "type": "oneToMany",
+        "foreignKey": "bookId",
+        "sort": "createdAt",
+        "sortDir": "desc"
+      },
+      "fieldInput": {
+        "type": "relation"
+      }
+    }
+  },
+  "operations": {
+    "findOne": {
+      "include": [
+        "reviews"
+      ]
+    }
+  }
+}
+```
+
+- `relation.foreignKey`: FK column on the **target** resource
+- `relation.sort` / `relation.sortDir`: default sort for the related list
+- `fieldInput.type`: `"relation"` renders an embedded table panel
+- Include goes in `findOne.include` only (heavy — skip from `findAll`)
+
+## manyToMany
+
+Use when: a join table connects both resources.
+
+```json
+{
+  "columns": {
+    "tags": {
+      "label": "Tags",
+      "relation": {
+        "resource": "./tag/resource.json",
+        "type": "manyToMany",
+        "foreignKey": "bookId",
+        "name": "tags"
+      },
+      "fieldInput": {
+        "type": "relation"
+      }
+    }
+  }
+}
+```
+
+## Detecting a relation column
+
+Use `isRelation(col)` (exported from `@ghentcdh/crouton-core`) — returns `true` when `col.relation` is set.
+Do not check `fieldInput.format` — that is removed.
+
+## column.relation full reference
+
+| Field        | Description                                                |
+|--------------|------------------------------------------------------------|
+| `resource`   | Relative path to target `resource.json`                    |
+| `type`       | `"manyToOne"` \| `"oneToMany"` \| `"manyToMany"`           |
+| `foreignKey` | FK column name                                             |
+| `name`       | Prisma relation field name (when different from column id) |
+| `displayKey` | Field on the related record to show in autocomplete/lookup |
+| `sort`       | Default sort field for the related list                    |
+| `sortDir`    | `"asc"` \| `"desc"` (default `"asc"`)                      |
+
+## include goes in operations, not at root
+
+```json
+// WRONG
+{
+  "include": [
+    "author"
+  ]
+}
+
+// RIGHT
+{
+  "operations": {
+    "findAll": {
+      "include": [
+        "author"
+      ]
+    },
+    "findOne": {
+      "include": [
+        "author"
+      ]
+    }
+  }
+}
+```
+

package/agent-files/.claude/skills/crouton/references/resource-json.md

@@ -0,0 +1,326 @@
+# resource.json — annotated full example
+
+```json
+{
+  "$schema": "node_modules/@ghentcdh/crouton-core/dist/resource.schema.json",
+  "schemaVersion": 1,
+  "name": "book",
+  "title": "Books",
+  "kind": "prisma",
+  "source": {
+    "model": "Book"
+  },
+  "lookup": {
+    "labels": ["title", "authorId"],
+    "separator": " · "
+  },
+  "openapi": {
+    "tag": "Books"
+  },
+  "columns": {
+    "id": {
+      "idField": true,
+      "hiddenInForm": true
+    },
+    "title": {
+      "label": "Title",
+      "fieldInput": { "type": "string" }
+    },
+    "pageCount": {
+      "label": "Page count",
+      "fieldInput": { "type": "number" }
+    },
+    "publishedAt": {
+      "label": "Published",
+      "fieldInput": { "type": "date" }
+    },
+    "genre": {
+      "label": "Genre",
+      "fieldInput": {
+        "type": "select",
+        "options": { "values": [
+          { "value": "fiction", "label": "Fiction" },
+          { "value": "non-fiction", "label": "Non-fiction" }
+        ]}
+      }
+    },
+    "authorId": {
+      "label": "Author",
+      "relation": {
+        "resource": "./author/resource.json",
+        "type": "manyToOne",
+        "foreignKey": "authorId",
+        "displayKey": "name"
+      },
+      "fieldInput": { "type": "autocomplete" }
+    },
+    "chapterCount": {
+      "label": "Chapters",
+      "type": "number",
+      "computed": {
+        "sql": "SELECT COUNT(*) FROM chapter WHERE chapter.book_id = main.id"
+      }
+    }
+  },
+  "operations": {
+    "findAll": {
+      "search": ["title"],
+      "include": ["author"]
+    },
+    "findOne": {
+      "include": ["author", { "relation": "chapters", "orderBy": { "position": "asc" } }]
+    }
+  },
+  "layout": {
+    "form": {
+      "container": { "mode": "modal", "size": "lg" },
+      "type": "grid",
+      "columns": 12,
+      "items": [
+        { "id": "title", "colspan": 9 },
+        { "id": "genre", "colspan": 3 },
+        "pageCount",
+        "publishedAt",
+        "authorId",
+        {
+          "type": "collapse",
+          "title": "Metadata",
+          "items": ["createdAt", "updatedAt"]
+        }
+      ]
+    },
+    "view": {
+      "container": { "mode": "page" }
+    },
+    "table": {
+      "pageSize": 50,
+      "pageSizes": [20, 50, 100],
+      "density": "compact",
+      "rowClick": "view",
+      "items": [
+        { "id": "title", "sortable": true, "defaultSort": "asc", "width": "md", "truncate": 2 },
+        { "id": "pageCount", "align": "right", "width": "xs" },
+        { "id": "publishedAt", "sortable": true },
+        { "id": "authorId" },
+        { "id": "genre", "visible": false }
+      ],
+      "searchFields": ["title"],
+      "filterFields": ["genre"],
+      "rowActions": [
+        { "id": "preview", "type": "link", "href": "/preview/{id}", "label": "Preview" }
+      ],
+      "tableActions": [
+        { "id": "export", "label": "Export CSV", "procedure": "exportCsv" }
+      ]
+    }
+  }
+}
+```
+
+## Where does a key go?
+
+| Concern | Key location |
+|---|---|
+| Data shape / validation / form input | `columns[id].*` |
+| How a record opens (modal vs page, size) | `layout.form.container` / `layout.view.container` |
+| Table display (width, align, pin, truncate) | `layout.table.items[].options` or item fields |
+| Storage (Prisma model, db table, datasource) | `source.*` |
+| Query / endpoints (search, include, filter) | `operations.<op>.*` |
+| Relation data model (type, FK, display field) | `columns[id].relation` |
+| Dropdown label in other resources | `lookup.labels` |
+| Navigation / sidebar | `sidebar` |
+| Access control | `security` |
+
+## Root-level key reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `$schema` | string | no | Path to JSON schema for editor autocomplete |
+| `schemaVersion` | number | yes | Must be `1` |
+| `name` | string | yes | Resource identifier (matches directory name) |
+| `title` | string | yes | Display name for the resource |
+| `kind` | `"prisma"` \| `"custom"` | no | `"prisma"` = Prisma-backed (default); `"custom"` = repository.ts |
+| `source` | object | prisma only | Storage config — see below |
+| `source.model` | string | prisma | Prisma model name (was root `model`) |
+| `source.dbTable` | string | no | Override DB table name (was root `table`) |
+| `source.datasource` | string | no | Named datasource from `crouton.json` (was root `database`) |
+| `source.idType` | `"number"` \| `"string"` | no | PK type (was root `idType`) |
+| `lookup` | object | no | How this resource labels itself in other resources' dropdowns |
+| `lookup.labels` | string[] | no | Column ids to show (ordered); replaces per-column `showInLookup` |
+| `lookup.separator` | string | no | Separator between label parts (default `" "`) |
+| `openapi` | object | no | OpenAPI metadata |
+| `openapi.tag` | string | no | API tag group name (default `"Crouton"`) |
+| `columns` | object | yes | Map of column id → column config |
+| `operations` | object | no | Per-operation query config |
+| `layout` | object | no | Presentation config (form / view / table) |
+| `sidebar` | object | no | Navigation placement |
+| `security` | object | no | Role-based access rules |
+
+## Column reference
+
+| Field | Type | Description |
+|---|---|---|
+| `label` | string | Human-readable label (defaults to title-cased id) |
+| `idField` | boolean | Mark as primary-key column (exactly one per resource) |
+| `hiddenInTable` | boolean | Hide in list view |
+| `hiddenInForm` | boolean | Hide in create/edit form |
+| `hiddenInView` | boolean | Hide in detail view |
+| `createable` | boolean | Include in create form (default `true`) |
+| `updateable` | boolean | Include in edit form (default `true`) |
+| `required` | boolean | Override Prisma-derived required state in forms |
+| `unique` | boolean \| UniqueConfig | Enforce uniqueness; object form allows `scope`, `caseInsensitive`, `message` |
+| `type` | string \| object | Data type (`"string"`, `"number"`, `"boolean"`, `"date"`, `"date-time"`, `"object"`, `"array"`) or JSON Schema fragment |
+| `fieldInput` | object | UI input widget config — see field-inputs.md |
+| `relation` | object | Relation data model — see below |
+| `computed` | object | SQL computed column — `{ sql, type? }` |
+| `enum` | string | Shared enum name from `crouton.enums.json` (mutually exclusive with `fieldInput.options.values`) |
+| `displayKey` | string | Dot-path to display a nested property |
+| `extend` | string | Relative path to another resource.json to expand as sub-columns |
+
+## column.relation reference
+
+Put relation config here, not in `fieldInput.options`:
+
+```json
+"authorId": {
+  "relation": {
+    "resource": "./author/resource.json",
+    "type": "manyToOne",
+    "foreignKey": "authorId",
+    "name": "author",
+    "displayKey": "name",
+    "sort": "name",
+    "sortDir": "asc"
+  },
+  "fieldInput": { "type": "autocomplete" }
+}
+```
+
+| Field | Description |
+|---|---|
+| `resource` | Relative path to target resource.json |
+| `type` | `"manyToOne"` \| `"oneToMany"` \| `"manyToMany"` |
+| `foreignKey` | FK column name (on this resource for manyToOne, on target for oneToMany) |
+| `name` | Prisma relation field name (when different from column id) |
+| `displayKey` | Field on the related record to show in the autocomplete |
+| `sort` / `sortDir` | Default sort for the related list |
+
+`isRelation(col)` returns `true` when `col.relation` is set.
+
+## operations reference
+
+```json
+"operations": {
+  "findAll": {
+    "search": ["title", "isbn"],
+    "include": ["author"]
+  },
+  "findOne": {
+    "include": ["author", { "relation": "chapters", "orderBy": { "position": "asc" } }]
+  },
+  "create": {},
+  "update": {},
+  "delete": {}
+}
+```
+
+Root `include` is removed — set `findAll.include` and `findOne.include` separately so heavy relations can be loaded only on the detail view.
+
+## layout.form / layout.view container
+
+```json
+"layout": {
+  "form": {
+    "container": { "mode": "modal", "size": "lg" }
+  },
+  "view": {
+    "container": { "mode": "page" }
+  }
+}
+```
+
+| Field | Values | Description |
+|---|---|---|
+| `container.mode` | `"modal"` \| `"page"` | How the record opens (default `"modal"`) |
+| `container.size` | `"xs"` \| `"sm"` \| `"lg"` \| `"xl"` | Modal width (default `"sm"`) |
+
+`display` and `modalSize` at root are removed — use `layout.<form\|view>.container`.
+
+## layout.table item options
+
+```json
+"items": [
+  { "id": "title",       "width": "md", "truncate": 2, "sortable": true, "defaultSort": "desc" },
+  { "id": "pageCount",   "align": "right", "width": "xs" },
+  { "id": "status",      "pin": "left" },
+  { "id": "internalRef", "visible": false, "headerTooltip": "Internal reference number" }
+]
+```
+
+| Option | Type | Description |
+|---|---|---|
+| `width` | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` or CSS value | Column width |
+| `minWidth` / `maxWidth` | CSS value | Width constraints |
+| `align` | `"left"` \| `"center"` \| `"right"` | Cell text alignment |
+| `truncate` | `boolean` \| number | `true` = single-line ellipsis; number = max lines before clamp |
+| `pin` | `"left"` \| `"right"` | Sticky column |
+| `visible` | boolean | `false` = hidden by default (no column chooser yet) |
+| `headerTooltip` | string | Tooltip text on the column header |
+| `defaultSort` | `true` \| `"asc"` \| `"desc"` | Initial sort; `true` = `"asc"` |
+
+## layout.table node options
+
+```json
+"table": {
+  "pageSize": 50,
+  "pageSizes": [20, 50, 100],
+  "density": "compact",
+  "selectable": true,
+  "rowClick": "view",
+  "emptyText": "No books yet",
+  "items": [...]
+}
+```
+
+| Option | Description |
+|---|---|
+| `pageSize` | Default page size (frontend hint; server still caps it) |
+| `pageSizes` | Page size selector options |
+| `density` | `"normal"` \| `"compact"` |
+| `selectable` | Row checkboxes |
+| `rowClick` | `"view"` \| `"edit"` \| `"none"` — what a row click opens |
+| `emptyText` | Message shown when there are no rows |
+
+## Layout items
+
+Every entry in a node's `items` array is one of:
+
+| Shape | Kind |
+|---|---|
+| `"fieldName"` | Field id — renders field's default input |
+| `{ "id": "fieldName", ... }` | Field control — field with overrides |
+| `{ "component": "Name", ... }` | Custom Vue component |
+| Object with `type` but no `id`/`component` | Nested container node |
+
+## Table layout: flat vs wrapper
+
+All table-specific settings (`rowActions`, `tableActions`, `searchFields`, `filterFields`, table options) go on the **`type: "table"` node**, never on an outer wrapper.
+
+```json
+"table": {
+  "type": "grid",
+  "items": [
+    { "component": "CreateByIsbn", "colspan": 12 },
+    {
+      "type": "table",
+      "pageSize": 50,
+      "items": ["title", "isbn"],
+      "searchFields": ["title", "isbn"]
+    }
+  ]
+}
+```
+
+## Layout is the full list
+
+When `layout.<ctx>` is defined, its `items` list is exhaustive — only listed columns render. Columns not listed are hidden regardless of `hiddenIn*`.

package/agent-files/.cursor/rules/crouton.mdc

@@ -0,0 +1,39 @@
+---
+description: Crouton resource workflow
+globs: ["**/resource.json", "**/datasource.json", "**/crouton.json"]
+alwaysApply: false
+---
+
+# Crouton skill
+
+Crouton is a resource-driven admin UI framework. This skill teaches the correct workflow for adding and changing resources.
+
+## What crouton is
+- Resources live in `<resourcesDir>` (see `crouton.json`). Each is a folder with `resource.json`.
+- Data sources live in `<dataSourcesDir>`. Each is a folder with `datasource.json`.
+- The Prisma schema (`schema.prisma`) is the source of truth for models and columns. Never hand-edit column lists that `crouton update` owns.
+
+## The workflow loop
+
+1. Change `schema.prisma` (add/modify models or fields).
+2. Run `crouton update` — regenerates column lists, migrations, and type stubs.
+3. Edit `resource.json` (UI/behaviour: labels, field inputs, relations, layout).
+4. Run `crouton validate` — fix any reported issues before proceeding.
+5. Typecheck/build to confirm no TS errors.
+
+## Key rules
+- Never hand-edit auto-generated sections inside `resource.json` (marked with comments).
+- Use `manyToOne` for autocomplete lookups; `oneToMany` for embedded tables.
+- `kind: "custom"` only when you have a `repository.ts` (config-only resource). For non-Prisma data, use `adapter` in `datasource.json`.
+- After any `resource.json` or `crouton.json` change, run `crouton validate`.
+
+## References
+- `references/resource-json.md` — annotated full example + key table
+- `references/relations.md` — relation recipes
+- `references/field-inputs.md` — which input for which column type
+- `references/data-sources.md` — prisma vs custom adapter
+- `references/recipes.md` — task recipes
+- `references/common-mistakes.md` — common mistakes
+
+## Docs for the installed version
+`node_modules/@ghentcdh/crouton-core/agent-docs/README.md`