create-restforge-skills 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-restforge-skills",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Install the RESTForge Agent Skill and MCP server configuration into Claude Code, Cursor, and OpenAI Codex.",
   "type": "commonjs",
   "bin": {

package/skills/restforge/SKILL.md

@@ -89,6 +89,7 @@ everything missing, and say the user may leave the choice to the agent.
 | Dashboard endpoint | Widgets (metrics, SQL), `dash-` name | `codegen_get_dashboard_catalog` | write payload → `codegen_validate_dashboard_payload` → `codegen_create_dashboard` |
 | Background job / Kafka consumer | Name, topic for a consumer | `codegen_create_processor` / `codegen_create_kafka_consumer` | consumer → `runtime_generate_consumer_launcher` |
 | Frontend page | Source RDF and plugin (the existing app's plugin when there is one) | `codegen_migrate_payload` when an RDF exists | `designer_get_udf_catalog` → edit page → `designer_validate_payload` → `designer_preview_files` → `designer_generate` |
+| Bring UDF changes into an existing app | Aggregator UDF, output folder | `designer_validate_payload` | `designer_generate` without `overwrite` (merge); exit 1 = conflicts to resolve → generate again |
 | Auth | Backend, frontend, or both; RBAC or not | references/auth.md § Choosing the mechanism | `project_auth` / plugin auth / `designer_auth_create` / `designer_auth_attach` |
 | JavaScript SDK | Project (endpoints already generated) | `project_sdk_generate` | user runs install / build / deploy |
 | Seed, export, or move rows | Tables or schema, config | references/data-seeding.md | `data_pull` / `data_push` |
@@ -125,6 +126,7 @@ Three layers co-exist and must not be conflated:
   regenerating the endpoint.
 - **UDF** — the frontend consuming the API. Derived from the RDF with
   `codegen_migrate_payload`, refined by hand, generated with `designer_generate`.
+  Re-generating merges into the existing app files, so edits there survive.
 
 When the user uses DDL terms (NOT NULL, UNIQUE, CHECK, REFERENCES, ALTER TABLE,
 CREATE INDEX), do not map them to payload validation automatically. Ask which
@@ -211,6 +213,8 @@ DESTRUCTIVE. Ask before:
 - `setup_validate_config` with `autoCreateDb: true` (runs CREATE DATABASE).
 - `codegen_migrate_payload` with `overwrite: true` (page customisations are
   discarded; without it pages are merged).
+- `designer_generate` with `overwrite: true` (every app file is recreated and
+  its customisations are discarded; without it files are merged).
 - `codegen_create_endpoint` and `codegen_create_dashboard` overwrite by default
   but archive the previous files to `.restforge/archive/<run>/` (5 most recent
   runs kept), so a plain intent confirmation is enough. `force: false` finds out
@@ -248,9 +252,14 @@ column is an SDF change), report the cross-over and ask before expanding.
 Grounding-First Rules). This rule is about syntax; choosing the business fields
 of a table the user handed over is allowed (Guardrail 9).
 
-**7. Generated output is not edited by hand.** Change the definition file (SDF,
-RDF, UDF) and regenerate. Snapshots in `payload/.meta/` and
-`frontend/payload/.meta/pages/` are committed with their files and never edited.
+**7. Know which generated output survives a regenerate.** Backend output
+(`src/modules/`, `src/models/`, metadata) is overwritten by
+`codegen_create_*` (archived first), so change the RDF instead of the code.
+Frontend app files may be edited: `designer_generate` merges the edits
+(references/frontend-pipeline.md § Regenerating an existing app). Snapshots in
+`payload/.meta/`, `frontend/payload/.meta/pages/`, and
+`frontend/apps/.meta/<project>/` (except `conflicts/`) are committed with their
+files and never edited.
 
 **8. Execute through tools; never emulate them.** When a tool produces or
 validates an artifact (`codegen_generate_payload`, `codegen_dbschema_introspect`,
@@ -278,4 +287,5 @@ file "to be filled in later" unless the user asked for a draft.
   presence only.
 - A precondition that is not met is a next step or a question, not an error.
 - An exit code that the tool describes as a verdict (drift found, payload
-  invalid, items skipped) is a result to relay, not a tool failure.
+  invalid, items skipped, merge conflicts) is a result to relay, not a tool
+  failure.

package/skills/restforge/references/backend-pipeline.md

@@ -313,6 +313,11 @@ for a skeleton.
   SQL files use the `file:` prefix
   (e.g. `"datatablesQuery": "file:sql/orders.sql"`). Validating first turns a
   runtime 500 into an error message before the payload is even written.
+  A joined column must not reuse the name of a main table column
+  (`s.status_name AS status` when `status` is the FK column is rejected by
+  `codegen_validate_payload`, and `codegen_migrate_payload` then skips that
+  field). Select the main table column itself and give the joined column its
+  own name, e.g. `s.status_name`.
 
 > **"Add an uppercase / case constraint" is ambiguous — disambiguate first.**
 > In RESTForge `uppercase` is an RDF `fieldValidation` *normalization transform*

package/skills/restforge/references/frontend-pipeline.md

@@ -7,8 +7,9 @@ Read this file when the intent router in SKILL.md points to the frontend track
 
 1. [Pipeline (canonical)](#pipeline-canonical)
 2. [UDF decisions](#udf-decisions)
-3. [Page type](#page-type)
-4. [Plugin choice](#plugin-choice)
+3. [Regenerating an existing app](#regenerating-an-existing-app)
+4. [Page type](#page-type)
+5. [Plugin choice](#plugin-choice)
 
 ---
 
@@ -58,11 +59,13 @@ frontend can be defined and generated without the backend live.
       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.
+      Dry-run: list the files the generator produces, without writing to disk.
+      It does not read the output folder, so it cannot show which files a
+      re-generate will merge, keep, or skip.
 
 7.  designer_generate
-      Generate frontend HTML/JS/CSS from the aggregator. Writes output files.
+      Generate frontend HTML/JS/CSS from the aggregator. On an existing app it
+      merges into the files on disk (§ Regenerating an existing app).
       The agent STOPS here — the user opens the output in a browser.
 ```
 
@@ -108,6 +111,48 @@ tool, so step 2a runs in the backend project folder.
 
 ---
 
+## Regenerating an existing app
+
+`designer_generate` without `overwrite` is the normal way to bring UDF changes
+into an app that already exists, for scope `app` and `form` alike. The user may
+edit the generated app files (`<page>.html`, `js/<page>.js`, `js/common.js`,
+`js/config.js`, `sidebar.html`, assets); the edits survive.
+
+- **Merge** — each text file is merged three-way against the snapshot of the
+  last generate in `<output parent>/.meta/<output folder>/` (for
+  `frontend/apps/<project>` that is `frontend/apps/.meta/<project>/`). User
+  edits are kept and UDF or template changes on untouched lines are applied.
+  The result lists a status per file: `written`, `merged`, `unchanged`, `kept`,
+  `conflict`, or `skipped`. Commit the `.meta` folder with the app, except
+  `conflicts/` (it has its own `.gitignore`); never edit it.
+- **Conflict** — a file whose edits clash with the new output is left untouched;
+  the version with conflict markers is in `.meta/<project>/conflicts/<path>`.
+  All other files are still processed and the command exits 1. That is a result
+  to relay, not a tool failure: resolve the file (apply the conflict version and
+  keep the user's intent), then run generate again. Do not use `overwrite` as
+  the fix.
+- **Managed lines** — `BACKEND_DATE_FORMAT` and `BACKEND_DATETIME_FORMAT` in
+  `js/common.js` (marked `restforge:managed`) always take the new value.
+- **Assets** — a modified asset (CSS, vendor bundle, image) is kept with a
+  warning; the new version is in `conflicts/<path>`.
+- **App generated before snapshots existed** — files that differ from the new
+  output are kept with a warning and the new version goes to `conflicts/<path>`.
+  The user merges by hand, or recreates one page with `scope: "form"`, `page`,
+  and `overwrite`.
+- **`index.html`** — merged like the shared files when it carries the
+  `RESTForge-Designer:LandingGenerated` marker. Without the marker it is never
+  replaced, even with `overwrite`, and is reported as `skipped`; a new page then
+  does not appear on the homepage. Remove the file or add the marker line back,
+  then generate with scope `app`.
+- **`overwrite: true`** recreates every file from scratch and discards the
+  customisations in all of them (each old file that differs is archived to
+  `.restforge/archive/`). Confirm with the user before using it.
+- **Not handled** — files of a page removed from the UDF are not deleted, and a
+  clean text merge is not proof that the logic still works; test the result in
+  the browser.
+
+---
+
 ## Page type
 
 - **Standard CRUD page** → `pageType: "crud"` (default) with `apiPath`,

package/skills/restforge/references/troubleshooting.md

@@ -66,6 +66,9 @@ When `codegen_validate_dashboard_payload` is unavailable, the fallback is
 | 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` |
+| `datatablesQuery ... selects joined column(s) ... under the name of a main table column` | A JOIN column is aliased to a main table column name | Select the main table column itself (`t.status`) and give the joined column another name |
+| Frontend generate exits 1 with "Conflicts (file kept as-is)" | User edits and the new output touch the same lines | Resolve each file from `.meta/<project>/conflicts/<path>`, then generate again; see frontend-pipeline.md § Regenerating an existing app |
+| New page missing from the homepage after generate | `index.html` has no `RESTForge-Designer:LandingGenerated` marker, so it is `skipped` | Remove the file or add the marker line back, then generate with scope `app` |
 | 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