create-restforge-skills 0.3.0 → 1.0.0

package/skills/restforge/SKILL.md

@@ -10,7 +10,7 @@ description: >
   active for the codegen_*, designer_*, setup_*, runtime_* MCP tools and the
   @restforgejs/platform / @restforgejs/mcp-server packages. Defines the canonical
   operation order for the backend track (setup → schema → payload → codegen →
-  runtime) and the frontend track (init → udf → validate → generate), the
+  runtime) and the frontend track (migrate RDF → udf → validate → generate), the
   grounding-first catalog rules, decision branches, and destructive-operation
   guardrails. Active whenever working on a RESTForge project, not only when the
   word "skill" is mentioned.
@@ -56,8 +56,10 @@ The platform exposes its capabilities as MCP tools grouped by domain: `health_*`
 
 Verify readiness before planning or producing anything:
 
-1. **Are the RESTForge MCP tools present?** If `codegen_*` / `designer_*` are not
-   in your available tools, the MCP server is **not active**. Stop and tell the
+1. **Are the RESTForge MCP tools present?** Look for `codegen_*` / `designer_*`,
+   including client-prefixed names such as `mcp__restforge__codegen_*`. If the
+   client supports deferred tool discovery, search for RESTForge tools first.
+   If they remain unavailable, the MCP server is **not active**. Stop and tell the
    user to register the RESTForge MCP server and restart the client. Do **not**
    finish the task by hand-reading the bundled `references/` — that bypasses the
    generator and yields slower, non-deterministic output.
@@ -146,6 +148,11 @@ earlier steps that already succeeded.
 
 8.  codegen_dbschema_validate
       Validate SDF before any DDL is generated. Catch errors here, not at migrate.
+      File-only by default. With 'config' it also compares every model with the
+      database and gives one verdict per table: [OK], [DRIFT], or [ERROR] with
+      category table-missing or sdf-invalid. Exit code 1 in that mode is a
+      result (drift or error found), not a tool failure. SQLite is not
+      supported by the database mode.
       codegen_dbschema_models (optional) lists the models already defined in the
       SDF files with field count, primary key kind, indexes, uniques, relations.
 
@@ -166,19 +173,22 @@ earlier steps that already succeeded.
       Check the SELECT / WITH statement against the live database (EXPLAIN, no
       rows executed) BEFORE pasting it into the payload: syntax, column
       references, function existence, type compatibility, JOIN resolution.
-      Needs a platform that provides the 'query validate' sub-command
-      (confirmed present in 5.5.5).
 
 13. codegen_generate_payload
       Generate payload JSON from a table. Foundation for all subsequent
-      codegen operations.
+      codegen operations. 'detail' (a detail table name) also writes the
+      masterDetail block, the detail query file, and the composite actions.
+      Re-running it on an existing payload keeps the customisations made to
+      generator-owned keys; commit payload/.meta/<name>.json together with the
+      payload (see Decision Points § RDF Payload).
 
 14. codegen_validate_payload
       Validate the payload before codegen. Catch errors here.
 
 15. codegen_diff_payload   (when a payload exists and the DB schema has changed)
-    → codegen_sync_payload    (sync payload to the current DB state — non-breaking)
-    → codegen_migrate_payload (when the payload has breaking changes)
+    → codegen_sync_payload    (apply the schema drift to the payload)
+      'expandFk' (with 'table') also writes query/<table>-join.sql so
+      datatablesQuery (and viewQuery) show columns of referenced tables.
 
 16a. codegen_create_endpoint        (standard CRUD module)
        Leave 'database' UNSET unless the user named a database: the CLI then
@@ -186,16 +196,17 @@ earlier steps that already succeeded.
        MySQL/Oracle/SQLite project generates for its own dialect. 'config'
        selects that .env explicitly. createDemo (default true) writes the
        curl / Postman / Insomnia examples. force defaults to true — an existing
-       module is overwritten and the previous version archived as .archive.NNN;
-       force=false stops without writing anything when the module exists, which
-       is the closest thing to a conflict dry run.
+       module is overwritten and the previous files are moved to
+       .restforge/archive/<run>/<original relative path> (the 5 most recent runs
+       are kept); force=false stops without writing anything when the module
+       exists, which is the closest thing to a conflict dry run.
 16b. codegen_get_dashboard_catalog
      → codegen_validate_dashboard_payload
        ── GATE ── structural check of a dashboard payload; writes nothing.
-       Needs a platform NEWER than 5.5.5 ('dashboard create --validate-only').
-       On an older platform the tool answers with an upgrade suggestion instead
-       of a validation result — then let the generator itself validate, since it
-       runs the same validator before it writes.
+       On a platform without 'dashboard create --validate-only' the tool
+       answers with an upgrade suggestion instead of a validation result — then
+       let the generator itself validate, since it runs the same validator
+       before it writes.
      → codegen_create_dashboard     (analytic dashboard with SQL widgets)
        No database auto-detection here: the dashboard command uses 'database'
        when given and plain postgres otherwise, so pass it whenever the project
@@ -269,34 +280,47 @@ frontend can be defined and generated without the backend live.
 
 ```
 1.  designer_list_plugins
-      ── GROUNDING ── list available output plugins before initializing.
-      Built-in: vanilla-js-basic (no auth), vanilla-js-auth (JWT auth).
+      ── GROUNDING ── list available output plugins before creating the UDF.
+      Built-in: vanilla-js-basic (no auth), vanilla-js-auth and
+      vanilla-js-custom (JWT auth + RBAC).
       → references/udf-catalog.md § Plugins
 
-2.  designer_init_project
-      Scaffold a new frontend project from a plugin. Creates the project folder,
-      the initial UDF payload (payload.json), and plugin assets.
+2a. codegen_migrate_payload   ── PRIMARY ── when a backend RDF payload exists
+      Convert the RDF into a split UDF set in the output folder (default
+      frontend/payload/): app-config.json, pages/<pageId>.json, the aggregator
+      <appCode>.json, and snapshots in .meta/pages/. Run it once per RDF with
+      the same output folder to add pages to one app. It derives fields, types,
+      lookups, details[], status filters, and the date patterns from the
+      backend, so start here instead of writing pages by hand.
+      Needs a license and the backend config (like every codegen_* tool).
+2b. [hand-write the UDF]      only when there is no RDF to migrate from
+      Ground every key with designer_get_udf_catalog first.
+    designer_init_project      (optional) scaffold a project folder with the
+      assets of an auth-capable plugin (vanilla-js-auth / vanilla-js-custom).
+      It writes no UDF payload file.
 
 3.  designer_get_udf_catalog
-      ── GROUNDING ── call before defining or editing any UDF payload.
-      Returns valid field types, page anatomy, features, data-source formats,
-      and validation rules for the installed plugin version.
+      ── GROUNDING ── call before editing any UDF page.
+      Returns valid field types, enums, limits, and validation constants for
+      the installed designer version.
       → references/udf-catalog.md
 
-4.  [define / edit UDF payload JSON]
-      Edit payload.json: appConfig, pages[], navigation[], homepage.
-      One page entry = one CRUD page or one dashboard page.
+4.  [edit the UDF pages]
+      Edit pages/<pageId>.json (labels, layout, features, workflowActions) and
+      the aggregator (navigation, homepage). One page entry = one CRUD page or
+      one dashboard page. Re-running migrate later merges RDF changes into
+      these files without losing the edits (Decision Points § Frontend UDF).
 
 5.  designer_validate_payload
-      ── GATE ── validate the UDF payload. Catches structural errors before
-      generation. Run before preview or generate, every time.
+      ── GATE ── validate the UDF (the aggregator file). Catches structural
+      errors before generation. Run before preview or generate, every time.
 
 6.  designer_preview_files
       Dry-run: list files that would be generated, without writing to disk.
       Use to verify scope before an overwrite.
 
 7.  designer_generate
-      Generate frontend HTML/JS/CSS from the UDF payload. Writes output files.
+      Generate frontend HTML/JS/CSS from the aggregator. Writes output files.
       The agent STOPS here — the user opens the output in a browser.
 ```
 
@@ -314,7 +338,8 @@ not serve or deploy).
 
 Licensing note: the Designer tools (`designer_preview_files`, `designer_generate`,
 etc.) do **not** require a RESTForge license, unlike the `codegen_*`, `runtime_*`,
-and `setup_validate_config` tools on the backend track.
+and `setup_validate_config` tools. `codegen_migrate_payload` is a `codegen_*`
+tool, so step 2a runs in the backend project folder.
 
 ---
 
@@ -407,6 +432,7 @@ definition content from memory.
 | Defining `fieldValidation` in an RDF payload | `codegen_get_field_validation_catalog` | references/field-validation.md |
 | Defining queries in an RDF payload | `codegen_get_query_declarative_catalog` | — |
 | Defining a dashboard payload | `codegen_get_dashboard_catalog` | — |
+| Defining `/aggregate` joins or requests | — (no catalog tool yet) | references/rdf-advanced.md § Aggregate Config |
 | Defining UDF (frontend) | `designer_get_udf_catalog` | references/udf-catalog.md |
 | Listing available frontend plugins | `designer_list_plugins` | references/udf-catalog.md § Plugins |
 | Setting `db-connection.env` parameters | `setup_get_config_schema` | references/config-schema.md |
@@ -457,19 +483,41 @@ branch still obeys the Grounding-First Rules above.
   the SDF, and run `codegen_dbschema_validate`. The design shows presentation,
   not storage — do not turn every visible label into a column.
   → references/design-to-sdf.md
-- **DB exists with drift** → `codegen_dbschema_diff` to review, then
-  `codegen_dbschema_apply`. Not `codegen_dbschema_migrate` — that is for empty
-  DBs only.
+- **"Is my schema valid and in sync with the database?"** →
+  `codegen_dbschema_validate` with `config` (optionally `table`): one verdict per
+  table, `[OK]`, `[DRIFT]`, or `[ERROR]` (`table-missing` → migrate/apply fixes
+  it; `sdf-invalid` → fix the file). Exit code 1 means drift or an error was
+  found, not that the tool failed. Not available for SQLite.
+- **DB exists with drift** → `codegen_dbschema_diff` to review the per-column
+  differences, then `codegen_dbschema_apply`. Not `codegen_dbschema_migrate` —
+  that is for empty DBs only.
 
 ### RDF Payload
 
 - **No payload yet** → `codegen_generate_payload`.
 - **Payload exists, edit is API-layer only** (e.g. add/adjust `fieldValidation`,
   messages, or a query — no column added or dropped) → ground via the matching
-  catalog, edit `payload.json`, run `codegen_validate_payload`, then regenerate
+  catalog, edit `payload/<name>.json`, run `codegen_validate_payload`, then regenerate
   with `codegen_create_endpoint`. No DB migration: the schema (SDF) is unchanged.
 - **Payload exists, DB schema changed** → `codegen_diff_payload` first, then
-  `codegen_sync_payload` (non-breaking) or `codegen_migrate_payload` (breaking).
+  `codegen_sync_payload`. Turning the RDF into a frontend UDF is a separate
+  frontend step (Frontend Pipeline step 2a), not part of this branch.
+- **Customisations survive regeneration.** `codegen_generate_payload` and
+  `codegen_sync_payload` keep edits made to generator-owned keys (`action`,
+  `fieldValidation`, inline SQL, `auditColumns`, the datatables query file).
+  A column deliberately removed from `fieldName` stays removed because generate
+  records the known columns in `payload/.meta/<name>.json`; commit that snapshot
+  with the payload and never edit it.
+- **Show columns of a referenced table in the list** (e.g. `supplier_name` next
+  to `supplier_id`) → `codegen_sync_payload` with `table` and `expandFk`
+  (`"both"`, or `"datatables-only"` to leave a custom `viewQuery` alone). It
+  writes `query/<table>-join.sql` and points `datatablesQuery` (and `viewQuery`)
+  at it; `FK_AUTO_JOIN` picks LEFT or INNER JOIN. The display column per FK is
+  chosen automatically and is never the primary key. Use `fkColumns`
+  (`ref_table.column`, or `local_fk:ref_table.column`) to override it and
+  `expandFkSkip` to leave a relation out. When the CLI reports "No natural
+  display column found", **ask the user** which column to show or whether to
+  skip that relation — do not pick one yourself.
 - **Custom query needed** → ground via `codegen_get_query_declarative_catalog`,
   check the statement with `codegen_validate_sql` against the live database, then
   set `datatablesQuery`, `viewQuery`, or `exportQuery` in the payload. External
@@ -500,21 +548,36 @@ branch still obeys the Grounding-First Rules above.
   after the endpoints exist, and after `project_auth` when the project needs
   auth, so `client.auth` is included.
 - **Integration test for an existing endpoint** → `codegen_generate_test`.
-- **Workflow (status transitions)** → add `workflow` and `workflowActions` to the
-  RDF payload; generates a `/change-status` endpoint automatically.
+- **Every feature endpoint needs its `action` flag.** A feature block without
+  the matching flag in `action` produces no endpoint.
+  → references/rdf-advanced.md § The `action` Block
+- **Workflow (status transitions)** → set `action.workflow: true` and add a
+  `workflow` block (`statusField`, `transitions` as a map `status → [targets]`,
+  optional `hooks` keyed by target status) to the RDF; generates
+  `/change-status`. The buttons are UDF `workflowActions` — a frontend key that
+  never goes into the RDF.
   → references/rdf-advanced.md § Workflow
-- **Master-detail (composite CRUD)** → add `details[]` to the RDF payload;
-  generates `/create-composite`, `/update-composite`, `/read-composite`.
+- **Master-detail (composite CRUD)** → run `codegen_generate_payload` with
+  `detail: "<detail table>"`. It writes the `masterDetail` block, the detail
+  query file, and `action.createComposite` / `updateComposite` /
+  `readComposite`; then fill `headerCalculations` and `calculated` formulas by
+  hand. Generates `/create-composite`, `/update-composite`, `/read-composite`.
   → references/rdf-advanced.md § Master-Detail
+- **Summary numbers per resource** (count, sum, avg, min, max, optionally
+  grouped) → `action.aggregate: true`; the request body carries the operations,
+  and `aggregateConfig.joins` only whitelists JOINs. For charts or KPIs across
+  several tables, prefer a backend dashboard (`codegen_create_dashboard`).
+  → references/rdf-advanced.md § Aggregate Config
 - **Excel export** → `/export` works by default (falls back to
   `SELECT {fields} FROM tableName`); customise the columns/filter with
   `exportQuery` in the RDF payload. Tune `EXPORT_FILE_EXPIRY` / `EXPORT_CHUNK_SIZE`
   in config. Ground `exportQuery` via `codegen_get_query_declarative_catalog`.
   → references/rdf-advanced.md § Data Source Resolution
-- **Excel import (.xlsx)** → add `importConfig` (sheet, startRow, strategy,
-  upsertKey, columns header→fieldName, optional lookup) to the RDF payload;
-  generates `/import-preview` (validates, returns a diff) and `/import-commit`
-  (applies). → references/rdf-advanced.md § Import Config
+- **Excel import (.xlsx)** → set `action.import: true` and add `importConfig`
+  with `enabled: true` (`upsertKeys`, `upsertStrategy`, `requiredFields`,
+  optional `lookupFields`) to the RDF payload; generates `/import-upload`,
+  `/import-preview`, `/import-commit`, and `/import-status`.
+  → references/rdf-advanced.md § Import Config
   - Activate on an existing project: edit the payload to add `importConfig`
     (and/or `exportQuery`) → `codegen_validate_payload` → `codegen_create_endpoint`.
 
@@ -551,15 +614,38 @@ is `schemaPath` (CLI `--schema-path`, default `schema`).
   twice inserts the rows twice. Confirm with the user before pushing into a
   database that may already hold those rows.
 
+### Frontend UDF
+
+- **A backend RDF exists** → `codegen_migrate_payload`; do not write the page by
+  hand. Run it once per RDF into the same output folder to build one app.
+- **Re-running migrate** (RDF changed, or a page must pick up new columns) →
+  run it again **without** `overwrite`. Existing pages are merged: user edits
+  (labels, layout, removed fields, blocks) are kept and RDF changes to untouched
+  values are applied. Backend contract values (`apiPath`, `primaryKey`, `type`,
+  `required`, `maxlength`, `decimalPlaces`, `tableField`, lookup source, option
+  values) follow the RDF when both sides changed, with a warning. The merge uses
+  the snapshots in `<output>/.meta/pages/<pageId>.json`; commit them with the
+  pages and never edit them. The aggregator (`navigation`, `homepage`) and
+  `app-config.json` are merged too.
+- **`overwrite: true`** recreates the page from the RDF and discards every
+  customisation (the old file goes to `.restforge/archive/`). Confirm with the
+  user before using it.
+- **Date patterns** → `appConfig.dateFormat` / `dateTimeFormat` are rewritten
+  from the backend `DATEFORMAT` / `DATETIMEFORMAT` on every migrate. After the
+  backend changes them, re-run migrate and `designer_generate`; never edit the
+  frontend values to differ from the backend.
+
 ### Frontend page type
 
 - **Standard CRUD page** → `pageType: "crud"` (default) with `apiPath`,
   `primaryKey`, `displayField`, and `fields[]`.
-- **Dashboard page** → `pageType: "dashboard"` with `dataSources[]` and `rows[]`
-  containing widget columns.
+- **Dashboard page** → `pageType: "dashboard"` with a `dataSources` object
+  (`name → { url, method, body }`) and `rows[]` → `columns[]` → `widgets[]`.
   → references/udf-catalog.md § Dashboard Page
-- **Page with approval workflow** → add `workflow.statusField` and
-  `workflowActions[]` to the page.
+- **Page with approval workflow** → add `workflow` (`statusField` and
+  `transitions`, identical to the RDF) and `workflowActions[]` whose `actionId`
+  equals the target status. Add `fieldStates` to lock rows in final statuses.
+  → references/udf-catalog.md § Workflow Actions
 
 ### Frontend plugin choice
 
@@ -601,11 +687,15 @@ The following require explicit user confirmation before execution:
   and resource files of endpoints that no longer exist are left behind.
 - `setup_validate_config` with `autoCreateDb: true` — it runs CREATE DATABASE on
   the database server. The default call is read-only.
+- `codegen_migrate_payload` with `overwrite: true` — existing UDF pages are
+  recreated and every customisation in them is discarded (the old files are
+  archived). Without `overwrite`, pages are merged and nothing is lost.
 
 `codegen_create_endpoint` and `codegen_create_dashboard` overwrite by default
-(`force` is true) but archive the previous version as `.archive.NNN` first, so
-they need a plain intent confirmation rather than a destructive-operation
-confirmation. Use `force: false` when the point is to find out whether the module
+(`force` is true) but first move the previous files to
+`.restforge/archive/<run>/<original relative path>` (the 5 most recent runs are
+kept), so they need a plain intent confirmation rather than a
+destructive-operation confirmation. Use `force: false` when the point is to find out whether the module
 already exists: the endpoint command then stops at its confirmation question
 without writing, and the dashboard command refuses with a clean error.
 
@@ -711,13 +801,14 @@ pass:
 
 ### Tools that depend on the installed platform version
 
-Two tools wrap CLI sub-commands that older platforms do not have. Both fail in a
-recognisable way, so treat the failure as a version answer, not a payload problem:
+Two tools wrap CLI sub-commands that old platform releases do not have. Current
+releases have both. On an old project they fail in a recognisable way, so treat
+the failure as a version answer, not a payload problem:
 
 | Tool | Requirement | Symptom on an older platform |
 |---|---|---|
-| `codegen_validate_sql` | a platform providing `query validate` (confirmed present in 5.5.5; the exact minimum is not established) | `Unknown command: query` |
-| `codegen_validate_dashboard_payload` | a platform providing `dashboard create --validate-only`, which exists only after 5.5.5 | `Unknown flag: --validate-only`; the tool reports it as an upgrade requirement |
+| `codegen_validate_sql` | a platform providing `query validate` | `Unknown command: query` |
+| `codegen_validate_dashboard_payload` | a platform providing `dashboard create --validate-only` | `Unknown flag: --validate-only`; the tool reports it as an upgrade requirement |
 
 When `codegen_validate_dashboard_payload` is unavailable, the fallback is
 `codegen_create_dashboard` itself — it runs the same validator before writing.
@@ -734,6 +825,9 @@ When `codegen_validate_dashboard_payload` is unavailable, the fallback is
 | "Widget uses undeclared placeholder" | `:paramName` in SQL not in `params` | Add the entry to `params` in the dashboard payload |
 | "tableName and widgets conflict" | Payload contains both | Dashboard uses `widgets`; CRUD uses `tableName` — remove the wrong one |
 | UDF validation error on field type | Field type not supported by the active plugin | Run `designer_list_plugins` + `designer_get_udf_catalog` to verify supported types |
+| `constraints.format ... is not supported for type 'date'` (or `timestamp`) | Per-field date pattern in RDF | Remove `format`; the pattern comes from `DATEFORMAT` / `DATETIMEFORMAT` |
+| Frontend shows a different date than the backend stored | `appConfig.dateFormat` / `dateTimeFormat` differ from the backend config | Re-run `codegen_migrate_payload`, then `designer_generate` |
+| Hook rejection answered HTTP 400 with only the hook message | A component handler returned `{ success: false }` or threw | Expected behaviour; the handler name and path are in the server log |
 
 When an error is not in this table, do not guess a fix. Re-run the relevant
 `*_validate_*` tool, read its message, and ground against the catalog before

package/skills/restforge/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "RESTForge"
+  short_description: "Build RESTForge APIs and frontends through MCP"
+  default_prompt: "Use $restforge to build or update my RESTForge application."

package/skills/restforge/references/auth.md

@@ -2,7 +2,7 @@
 
 > **Offline mirror.** This file mirrors the auth commands of the installed
 > RESTForge platform and Designer (`restforge project auth`, `npx
-> restforge-designer auth`). The live tools/CLI are authoritative — when this file and them disagree,
+> npx restforge-designer auth`). The live tools/CLI are authoritative — when this file and them disagree,
 > trust the tools, then update this file.
 
 **This file documents the auth EXTENSION — auth WITHOUT RBAC.** It is one of two
@@ -116,7 +116,7 @@ injected automatically when `designer_generate` creates pages later.
 **Prerequisites:** the Designer is invoked via `npx restforge-designer` and is
 bundled inside the `@restforgejs/platform` package; the prerequisite is that
 `@restforgejs/platform` is installed in the project (e.g. a project created with
-`npx create-restforge-app`), not a standalone binary on PATH.
+`npx create-restforge-app`).
 
 Both are idempotent. **`--remove` is destructive** — confirm project name and
 intent with the user before running (MCP always passes `--force`).