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

package/README.md

@@ -0,0 +1,87 @@
+# @ghentcdh/crouton-cli
+
+CLI for managing Crouton projects — update resources, datasources, and more.
+
+## Local Development
+
+Three ways to test your changes, ordered from fastest to most thorough.
+
+### 1. Run the built CLI directly (quickest)
+
+Best for: changes to `update resources` and other CLI commands.
+
+```bash
+# in the crouton repo
+pnpm nx build crouton-cli
+# or watch mode:
+cd packages/crouton-cli && npx tsup --watch
+
+# in your test project
+node ~/path/to/crouton/packages/crouton-cli/dist/index.js update resources
+```
+
+Tip — add an alias so you don't retype the path:
+
+```bash
+alias crouton-dev="node ~/path/to/crouton/packages/crouton-cli/dist/index.js"
+crouton-dev update resources
+```
+
+---
+
+### 2. Run `create-crouton` from your checkout
+
+Best for: changes to the scaffold flow (prompts, templates, next-steps output).
+
+```bash
+pnpm nx build create-crouton
+cd ~/project/workshop_crouton
+node ~/path/to/crouton/packages/create-crouton/dist/index.js my-app
+```
+
+Local templates are bundled into `dist`, so you get your edits. The generated `package.json` still references `@ghentcdh/*@<version>`, so `pnpm install` pulls from npm — fine for testing prompts and templates. Pass `--no-install` to skip the install step.
+
+---
+
+### 3. Local npm registry via Verdaccio (most complete)
+
+Best for: testing the full `npx @ghentcdh/create-crouton` flow, including the install step, an unpublished `crouton-cli`, and `crouton-prisma`. Run this at least once before cutting a release.
+
+```bash
+# start the registry (http://localhost:4873)
+npx verdaccio
+
+# build everything and publish each package to the local registry
+pnpm nx run-many -t build
+(cd packages/crouton-cli/dist    && npm publish --registry http://localhost:4873)
+(cd packages/create-crouton      && npm publish --registry http://localhost:4873)
+# repeat for crouton-core / crouton-api / crouton-vue / crouton-prisma
+
+# scaffold using only the local registry
+cd ~/project/workshop_crouton
+npm_config_registry=http://localhost:4873 npx @ghentcdh/create-crouton@latest my-app
+```
+
+Before republishing the same version, either bump it (e.g. `0.0.1-local.2`) or unpublish first:
+
+```bash
+npm unpublish --force --registry http://localhost:4873 @ghentcdh/crouton-cli
+```
+
+Verdaccio proxies anything it doesn't have through to the public npm registry. You can also let Nx manage the registry setup:
+
+```bash
+pnpm nx g @nx/js:setup-verdaccio
+# then use:
+pnpm nx local-registry
+```
+
+---
+
+### Which option to use?
+
+| Situation | Option |
+|-----------|--------|
+| Fixing a CLI command (`.env`, schema, etc.) | **1** |
+| Changing scaffold prompts or templates | **2** |
+| Pre-release smoke test (e.g. before alpha.83) | **3** |

package/agent-files/.claude/skills/crouton/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: crouton
+description: Add or change crouton resources, relations, field inputs, layouts, operations and data sources (resource.json, datasource.json, crouton.json). Use for any change to these files.
+crouton-version: 0.0.1-alpha.82
+---
+
+> If `crouton --version` differs from `crouton-version` above, the skill may be stale — check the installed version's docs in `node_modules/@ghentcdh/crouton-core/agent-docs/`.
+
+# 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`.
+- Layout nodes use `items` only — there is no `controls` list. Items render in declared order.
+- Table settings (`rowActions`, `tableActions`, `searchFields`, `filterFields`) go on the `type: "table"` node inside
+  `layout.table`, never on an outer wrapper node.
+- When `layout.<ctx>` is defined, it is the **full list** for that context — only listed columns render. Unlisted
+  columns are hidden regardless of `hiddenIn*` flags.
+- After editing layouts, run `crouton validate` to confirm no migration is needed.
+
+## Project-specific notes
+
+If `.claude/skills/crouton/project.md` exists, read it first — it holds project conventions that override these
+defaults.
+
+## 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`

package/agent-files/.claude/skills/crouton/references/common-mistakes.md

@@ -0,0 +1,89 @@
+# Common mistakes
+
+## 1. Using removed root keys
+
+Many root keys moved. Run `crouton validate` to detect them — it reports the correct replacement path for each key.
+
+| Wrong (old)                             | Right (new)                                                                                    |
+|-----------------------------------------|------------------------------------------------------------------------------------------------|
+| `"model": "Book"` at root               | `"source": { "model": "Book" }`                                                                |
+| `"database": "main"` at root            | `"source": { "datasource": "main" }`                                                           |
+| `"table": "books"` at root              | `"source": { "dbTable": "books" }`                                                             |
+| `"idType": "number"` at root            | `"source": { "idType": "number" }`                                                             |
+| `"display": { "mode": "page" }` at root | `"layout": { "view": { "container": { "mode": "page" } } }`                                    |
+| `"modalSize": "lg"` at root             | `"layout": { "form": { "container": { "size": "lg" } } }`                                      |
+| `"include": ["author"]` at root         | `"operations": { "findAll": { "include": ["author"] }, "findOne": { "include": ["author"] } }` |
+| `"calculatedColumns": [...]`            | `"columns": { "myCol": { "computed": { "sql": "..." } } }`                                     |
+| `column.showInLookup: true`             | `"lookup": { "labels": ["colId"] }` on resource root                                           |
+
+## 2. Putting relation config in fieldInput instead of column.relation
+
+`fieldInput` only configures the UI widget. Relation data model belongs in `column.relation`.
+
+```json
+// WRONG
+"authorId": {
+  "fieldInput": {
+    "type": "autocomplete",
+    "relationType": "manyToOne",
+    "resource": "./author/resource.json",
+    "foreignKey": "authorId"
+  }
+}
+
+// RIGHT
+"authorId": {
+  "relation": {
+    "resource": "./author/resource.json",
+    "type": "manyToOne",
+    "foreignKey": "authorId",
+    "displayKey": "name"
+  },
+  "fieldInput": { "type": "autocomplete" }
+}
+```
+
+## 3. Using `format: "relation"` to detect relations
+
+`fieldInput.format` is removed. Use `isRelation(col)` from `@ghentcdh/crouton-core` or check `!!col.relation`.
+
+## 4. Setting both `enum` and `fieldInput.options.values`
+
+`enum` resolves a shared list from `crouton.enums.json` at load time. Setting both causes a validation error.
+Use `enum` for shared lists, `fieldInput.options.values` for local inline lists — never both.
+
+## 5. Hand-editing auto-generated columns
+
+`crouton update` owns columns derived from Prisma. Edits to column names or types are overwritten on the next
+`crouton update`.
+Only edit `fieldInput`, `label`, `hidden`, `required`, `relation` inside each column entry.
+
+## 6. `kind: "custom"` when you need `adapter: "custom"`
+
+`kind: "custom"` = this resource has a custom `repository.ts`.
+If your data source is external (not Prisma), set `adapter: "custom"` in `datasource.json` instead.
+
+## 7. Typos in fieldInput type
+
+The `type` value is case-sensitive: `autocomplete` not `Autocomplete`; `select` not `Select`.
+Run `crouton validate` — it reports unknown fieldInput types.
+
+## 8. Missing `crouton validate` after edits
+
+Schema violations, unknown resources in relations, and broken references are only caught by the validator.
+Always run `crouton validate` after any change to `resource.json` or `crouton.json`.
+
+## 9. Wrong relation direction
+
+`manyToOne`: FK is on **this** resource. `oneToMany`: FK is on the **target** resource.
+Swapping them causes the relation panel to query the wrong table.
+
+## 10. `colspan`/`rowspan`/`hideLabel` on table items
+
+These form-layout options have no effect on table items and are rejected with a validation error.
+Remove them from `layout.table` items — use `width`, `align`, `truncate` for table-specific display.
+
+## 11. Table/column settings on the wrapper instead of the table node
+
+In a wrapper table layout, `rowActions`, `tableActions`, `searchFields`, `filterFields`, `pageSize` etc.
+belong on the **`type: "table"` node**, not on the outer wrapper.

package/agent-files/.claude/skills/crouton/references/data-sources.md

@@ -0,0 +1,47 @@
+# Data sources — decision table
+
+## Prisma-backed (default)
+
+Use when: data lives in the relational DB and a Prisma model exists.
+
+`datasource.json`:
+```json
+{
+  "name": "default",
+  "prismaSchema": "prisma/schema.prisma",
+  "prismaConfig": "prisma/prisma.config.ts",
+  "urlEnv": "DATABASE_URL",
+  "zodOutput": "generated/default/types/src",
+  "clientOutput": "generated/default/client",
+  "default": true
+}
+```
+
+- `crouton update` introspects this datasource and manages column lists.
+- Resources reference it implicitly when `kind` is `"default"`.
+
+## Custom adapter
+
+Use when: data comes from an external API, file, or non-Prisma store.
+
+`datasource.json`:
+```json
+{
+  "name": "external-api",
+  "adapter": "custom"
+}
+```
+
+- `crouton update` skips Prisma introspection for this datasource.
+- Resources using it must supply a `repository.ts` that implements the crouton repository interface.
+- Set `kind: "custom"` in `resource.json` and point `datasource` to this name.
+
+## kind vs adapter
+
+| Scenario | resource.json `kind` | datasource.json `adapter` |
+|----------|----------------------|---------------------------|
+| Prisma-backed resource | `"default"` (or omit) | omit (Prisma) |
+| Config-only resource with custom repo | `"custom"` | omit (Prisma still used for other resources) |
+| Fully external data source | `"custom"` | `"custom"` |
+
+**Common mistake**: using `kind: "custom"` when you only need a custom adapter. If your data is in the DB but you want custom read logic, keep `kind: "default"` and override the repository at the NestJS module level.

package/agent-files/.claude/skills/crouton/references/field-inputs.md

@@ -0,0 +1,52 @@
+# Field inputs — column type → input type
+
+| Column type (Prisma) | Recommended fieldInput type | Notes |
+|---------------------|-----------------------------|-------|
+| `String` | `string` | Default for text |
+| `String` (long text) | `textarea` | Use when content is multi-line prose |
+| `String` (rich text) | `markdown` | Renders a Markdown editor |
+| `Int` / `Float` / `Decimal` | `number` | |
+| `Boolean` | `toggle` | Renders a toggle switch |
+| `DateTime` | `date` | Date picker; use `date-range` for range filters |
+| `String[]` / `Int[]` | `array` | Multi-value field |
+| Enum | `select` | Pass `options` from the enum values |
+| FK column (relation) | `autocomplete` | Requires `resource` + `labelField` |
+| PK / internal | `hidden` | Suppresses the field from forms |
+| Computed / read-only | `string` + `readonly: true` | Shows value, disallows editing |
+
+## autocomplete options
+
+```json
+{
+  "type": "autocomplete",
+  "resource": "author",
+  "labelField": "name"
+}
+```
+
+`resource` — the target resource name (folder name under `resourcesDir`).
+`labelField` — the column from the target resource to show as the label.
+
+## select options
+
+```json
+{
+  "type": "select",
+  "options": [
+    { "value": "draft", "label": "Draft" },
+    { "value": "published", "label": "Published" }
+  ]
+}
+```
+
+Options can also be sourced from `crouton.enums.json` via `enumKey`.
+
+## custom field input
+
+Register a custom Vue component, then reference it:
+
+```json
+{ "type": "custom", "component": "MyCustomInput" }
+```
+
+The component must be registered globally or via `useCrouton` before the form mounts.

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

@@ -0,0 +1,222 @@
+# Recipes — common tasks
+
+## Add a resource for an existing Prisma model
+
+1. Confirm the model exists in `schema.prisma`.
+2. Run `crouton update` and select the model when prompted.
+3. Crouton writes `<resourcesDir>/<name>/resource.json`.
+4. Edit `resource.json`: set labels, choose fieldInput types, add relations.
+5. Run `crouton validate`.
+
+Minimal resource:
+
+```json
+{
+  "schemaVersion": 1,
+  "name": "book",
+  "title": "Books",
+  "source": { "model": "Book" },
+  "columns": {
+    "id": { "idField": true, "hiddenInForm": true },
+    "title": { "label": "Title" }
+  }
+}
+```
+
+## Add a manyToOne relation (autocomplete)
+
+In `resource.json` of the resource holding the FK:
+
+```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"] }
+  }
+}
+```
+
+## Add a oneToMany relation (embedded panel)
+
+In `resource.json` of the parent resource:
+
+```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"] }
+  }
+}
+```
+
+## Add an enum select
+
+1. Add the enum to `crouton.enums.json` (or let `crouton update` create it).
+2. In `resource.json` use `enum` to reference it:
+
+```json
+{
+  "columns": {
+    "status": {
+      "enum": "BookStatus",
+      "fieldInput": { "type": "select" }
+    }
+  }
+}
+```
+
+Or use inline `values` for a local list (not shared):
+
+```json
+{
+  "columns": {
+    "genre": {
+      "fieldInput": {
+        "type": "select",
+        "options": { "values": [
+          { "value": "fiction", "label": "Fiction" },
+          { "value": "non-fiction", "label": "Non-fiction" }
+        ]}
+      }
+    }
+  }
+}
+```
+
+Never set both `enum` and `fieldInput.options.values` — validation error.
+
+## Right-align numbers, newest-first, 50 per page
+
+```json
+{
+  "layout": {
+    "table": {
+      "pageSize": 50,
+      "pageSizes": [20, 50, 100],
+      "items": [
+        { "id": "title", "sortable": true },
+        { "id": "price", "align": "right", "width": "xs", "sortable": true },
+        { "id": "createdAt", "sortable": true, "defaultSort": "desc" }
+      ]
+    }
+  }
+}
+```
+
+`defaultSort: "desc"` sets newest-first as the initial sort direction.
+
+## Truncate long text in table
+
+```json
+{ "id": "description", "truncate": 3 }
+```
+
+`truncate: 3` = max 3 lines before clamp. `truncate: true` = single-line ellipsis.
+
+## Pin a column sticky left
+
+```json
+{ "id": "name", "pin": "left", "width": "md" }
+```
+
+## Open view as page, form as large modal
+
+```json
+{
+  "layout": {
+    "form": { "container": { "mode": "modal", "size": "xl" } },
+    "view": { "container": { "mode": "page" } }
+  }
+}
+```
+
+## Load a relation only on detail, not in list
+
+```json
+{
+  "operations": {
+    "findAll": { "include": [] },
+    "findOne": { "include": ["author", "chapters"] }
+  }
+}
+```
+
+## Add a computed column (SQL subquery)
+
+```json
+{
+  "columns": {
+    "chapterCount": {
+      "label": "Chapters",
+      "type": "number",
+      "computed": {
+        "sql": "SELECT COUNT(*) FROM chapter WHERE chapter.book_id = main.id"
+      }
+    }
+  }
+}
+```
+
+Use `main` as the alias for the parent table row.
+
+## Set dropdown labels for this resource
+
+Control how this resource's records appear in other resources' autocompletes:
+
+```json
+{
+  "lookup": {
+    "labels": ["title", "authorId"],
+    "separator": " · "
+  }
+}
+```
+
+Replaces `showInLookup: true` on individual columns.
+
+## Custom field input + renderer registration
+
+1. Create a Vue component `MyInput.vue`.
+2. Register it via `useCrouton`:
+   ```ts
+   crouton.registerRenderer('MyInput', MyInput);
+   ```
+3. Reference in `resource.json`:
+   ```json
+   { "fieldInput": { "type": "custom", "component": "MyInput" } }
+   ```
+
+## Config-only resource (kind: custom)
+
+Use when the resource has no Prisma model or uses fully custom data logic.
+
+1. Create `<resourcesDir>/<name>/resource.json` with `"kind": "custom"`.
+2. Create `<resourcesDir>/<name>/repository.ts` implementing the crouton repository interface.
+3. Register the repository in the NestJS module.
+4. Run `crouton validate`.