create-restforge-skills 0.1.0 → 0.2.0

package/README.md

@@ -34,8 +34,10 @@ restforge-skills/
 ├── README.md                 ← this file
 ├── package.json              ← npm package: create-restforge-skills
 ├── bump-and-publish.bat      ← version bump + npm publish
+├── sync-to-plugin.bat        ← mirror the skill into the Claude Code plugin
 ├── cli/
-│   └── index.js              ← installer that copies the skill into each client
+│   ├── index.js              ← installer that copies the skill into each client
+│   └── mcp.js                ← merges the MCP server into each client config
 ├── docs/                     ← internal docs, NOT published (excluded from npm files)
 └── skills/
     └── restforge/
@@ -43,6 +45,17 @@ restforge-skills/
         └── references/       ← progressive-disclosure reference material
 ```
 
+## Single source of truth
+
+`skills/restforge/` here is the **one** authoritative copy of the skill. Two
+distribution channels consume it — do not edit the skill anywhere else:
+
+- **This package** (`create-restforge-skills`) — published to npm; cross-client.
+- **The Claude Code plugin** (`../packages/restforge-plugins`) — its
+  `skills/restforge-skills/` folder is a **generated mirror**. After editing the
+  canonical skill, run `sync-to-plugin.bat` to propagate, then commit the plugin
+  repo. Hand-edits to the plugin's skill copy are overwritten on the next sync.
+
 ## Install
 
 One command. It detects your installed clients (Claude Code, Cursor), copies the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-restforge-skills",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Install the RESTForge Agent Skill into Claude Code, Cursor, and other skills-compatible clients.",
   "type": "commonjs",
   "bin": {

package/skills/restforge/SKILL.md

@@ -4,7 +4,8 @@ description: >
   RESTForge end-to-end workflow — use for any task involving RESTForge: SDF
   (Schema Definition File), RDF (Resource Definition File), UDF (UI Definition
   File), dbschema, defineModel, codegen, payload, generate endpoint, generate
-  dashboard, generate frontend, migrate schema, setup project, or design-to-SDF
+  dashboard, generate frontend, migrate schema, setup project, add authentication
+  (project auth backend, embedded rfx_auth frontend auth), or design-to-SDF
   (deriving a schema from an HTML mockup, screenshot, image, or UI design). Also
   active for the codegen_*, designer_*, setup_*, runtime_* MCP tools and the
   @restforgejs/platform / @restforgejs/mcp-server packages. Defines the canonical
@@ -28,7 +29,7 @@ RESTForge is a deterministic, definition-first generator with two output tracks:
   endpoints. One SDF produces identical DDL; one RDF payload produces an
   identical endpoint module on every execution.
 - **Frontend track** — UDF defines the frontend application. One UDF payload
-  produces identical HTML/JS/CSS via `restforge-designer`, plugin-driven,
+  produces identical HTML/JS/CSS via `npx restforge-designer`, plugin-driven,
   no build step required.
 
 The agent interacts with the platform **exclusively through MCP tools**. The
@@ -51,6 +52,26 @@ The platform exposes its capabilities as MCP tools grouped by domain: `health_*`
 
 ---
 
+## Preflight (run before any RESTForge task)
+
+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
+   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.
+2. **Backend work** → confirm the project and config are ready with
+   `runtime_detect_project`, then the `setup_validate_config` gate.
+3. **Frontend work** → the Designer tools pre-check that `npx restforge-designer`
+   can run (its binary is bundled in `@restforgejs/platform`, so it is available
+   once the project is created with `npx create-restforge-app` / the platform is
+   installed); if it cannot run, surface that before proceeding.
+
+If a prerequisite is missing, report it as the next step — do not improvise around it.
+
+---
+
 ## Backend Pipeline (canonical)
 
 This is the canonical (golden) path. For state-dependent choices see Decision
@@ -61,11 +82,18 @@ project, start from the step that matches the current state — do not re-run
 earlier steps that already succeeded.
 
 ```
-1.  setup_create_folder
-      Create a new project folder at the specified location.
-
-2.  setup_install_package
-      Install @restforgejs/platform into the project folder.
+1.  npx create-restforge-app <name>     ── PRIMARY ── human-run scaffolder
+      One shot: creates the project folder, runs
+      npm install @restforgejs/platform (local), and bundles the designer
+      binary. This is the dominant way to start a new project.
+      Granular alternative (agent scaffolds step by step):
+        setup_create_folder   → create the project folder.
+
+2.  setup_install_package               (granular path only)
+      Install @restforgejs/platform into the folder. SKIP when the project
+      was created with create-restforge-app (already installed). Plain
+      'npm install @restforgejs/platform' stays valid but is not the
+      primary entry point.
 
 3.  setup_init_config
       Write config/db-connection.env from the default template.
@@ -134,12 +162,9 @@ earlier steps that already succeeded.
       Verify the server is running and endpoints are reachable.
 ```
 
-Two hard checkpoints in this track, both expanded under Guardrails:
-
-- **Step 5 is a gate**, not a suggestion. No `codegen_*` call before
-  `setup_validate_config` passes.
-- **Step 17 is where the agent stops.** The agent never starts, stops, or
-  restarts the server itself; it only generates the launcher.
+Two hard checkpoints (see Guardrails): **step 5** is a gate — no `codegen_*` call
+before `setup_validate_config` passes; **step 17** is where the agent stops (it
+generates the launcher, never runs the server).
 
 ---
 
@@ -191,12 +216,9 @@ designer_scaffold_plugin   →  [develop plugin templates]
   → designer_generate          (test generation with the custom plugin)
 ```
 
-Two checkpoints in this track, mirrored in Guardrails:
-
-- **Step 5 is a gate.** Never call `designer_generate` on an unvalidated UDF
-  payload — generation on an invalid payload produces incomplete or broken output.
-- **Step 7 is where the agent stops.** The agent generates files; it does not
-  serve, open, or deploy the frontend.
+Two checkpoints (see Guardrails): **step 5** is a gate — never `designer_generate`
+an unvalidated payload; **step 7** is where the agent stops (generates files, does
+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_*`,
@@ -204,6 +226,57 @@ and `setup_validate_config` tools on the backend track.
 
 ---
 
+## Auth Extension
+
+RESTForge has **two different auth mechanisms — do not confuse them.** Pick the
+right one; never describe one as the other, and never claim the extension does RBAC.
+
+| Mechanism | RBAC? | How |
+|---|---|---|
+| **Plugin auth** — built into the frontend at generation time | **Yes (auth + RBAC)** | `vanilla-js-auth` or `vanilla-js-custom` plugin in `designer_init_project`; disable with `noAuth: true` (`--no-auth`) |
+| **Auth extension** — bolt-on added to an existing project | **No RBAC** | backend `project_auth`; frontend `designer_auth_create` (embedded `rfx_auth`) |
+
+Confirm which plugins provide auth with `designer_list_plugins` — do not hardcode
+it. The rest of this section covers the **extension** (the no-RBAC bolt-on); for
+plugin auth see Decision Points § Frontend plugin choice. Google Sign-In and
+`@restforgejs/auth` are out of scope for the extension.
+
+### Backend auth — `project_auth`
+
+Adds the auth backend to an existing RESTForge project (run the standard backend
+pipeline first; the project and its endpoint must already exist, and the DB must
+be active).
+
+```
+project_auth   (wraps: npx restforge project auth --create --project=<name>)
+```
+
+Installs auth SDF (`rfx`), DB tables, middleware, router, six processors
+(register/login/refresh/logout/me/reset-password), a random `JWT_SECRET`, and
+`bcrypt`+`jsonwebtoken`. Idempotent. → references/auth.md § Backend
+
+### Frontend auth — `designer_auth_create` / `designer_auth_remove`
+
+Adds (or removes) an **embedded** login / signup / forget-password overlay
+(`rfx_auth`) on an existing frontend project, at route
+`/api/<project>/rfx_auth`. This is independent of the `vanilla-js-auth` plugin.
+
+```
+designer_auth_create   (wraps: npx restforge-designer auth --create --project=<name>)
+designer_auth_remove   (wraps: npx restforge-designer auth --remove --project=<name> --force)
+```
+
+`create` writes the auth pages + `js/rfx_auth.js` and injects a guard into existing
+pages; `remove` deletes them. Idempotent. Runs via `npx restforge-designer`
+(bundled in `@restforgejs/platform`; available once the project was created with
+`npx create-restforge-app` / the platform is installed).
+→ references/auth.md § Frontend
+
+Do not combine the two mechanisms on one app: if an app already has plugin auth
+(`vanilla-js-auth` / `vanilla-js-custom`), do not also add embedded `rfx_auth`.
+
+---
+
 ## Grounding-First Rules
 
 Before reasoning about, proposing, or generating any **definition content** —
@@ -238,8 +311,10 @@ type, or wrong semantics. Two concrete failure modes this rule prevents:
   constraint, not RDF `fieldValidation`. Grounding surfaces this distinction
   before the agent commits to the wrong one.
 
-The reference files mirror the catalog for offline reasoning, but the live
-catalog tool is authoritative — when they disagree, trust the tool.
+The reference files help you *understand* the catalog; they do **not** replace
+the tool. Call the tool to ground, produce, and validate — do not hand-produce
+output a tool would generate. The live tool is authoritative; when a reference and
+the tool disagree, trust the tool.
 
 ---
 
@@ -300,6 +375,17 @@ branch still obeys the Grounding-First Rules above.
 - **Master-detail (composite CRUD)** → add `details[]` to the RDF payload;
   generates `/create-composite`, `/update-composite`, `/read-composite`.
   → references/rdf-advanced.md § Master-Detail
+- **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
+  - Activate on an existing project: edit the payload to add `importConfig`
+    (and/or `exportQuery`) → `codegen_validate_payload` → `codegen_create_endpoint`.
 
 ### Soft-delete vs hard-delete
 
@@ -309,6 +395,31 @@ branch still obeys the Grounding-First Rules above.
 - Soft-delete is supported on PostgreSQL only (Phase 1).
 - Tables with composite UNIQUE constraints are incompatible with soft-delete.
 
+### Data seeding / migration (rows, not schema)
+
+Move table **rows** through SDF-driven envelope files. This is for data, never
+for schema — use the dbschema tools for structure.
+
+**Default output location:** `data-storage/<schema>/<table>.json`, relative to the
+project cwd. The `data-storage` folder is the default of the `storagePath` param
+(CLI `--storage-path <folder>`); override it to write elsewhere. The SDF read from
+is `schemaPath` (CLI `--schema-path`, default `schema`).
+
+- **Export / dump / snapshot / back up rows** → `data_pull`. Scope is exactly one
+  of `table`, `schema`, or `allSchemas`. Only tables registered in the SDF can be
+  pulled. `force: true` overwrites existing envelope files. Optional `limit`,
+  `batchSize`, `config` (falls back to the default set via `config set-default`,
+  i.e. `.restforge/defaults.json`), `schemaPath`, `storagePath`.
+- **Import / load / seed / restore rows** → `data_push`. Same file names as
+  `data_pull`, so pulled files push back directly. Scope is exactly one of `table`,
+  `schema`, or `allSchemas`; for `schema`/`allSchemas` tables load in FK
+  parent→child order.
+- **Move data between databases** → `data_pull` from the source, then `data_push`
+  into the target (`config` selects the env per side).
+- ⚠ `data_push` is **APPEND-ONLY** (batch INSERT, no upsert/replace). Running it
+  twice inserts the rows twice. Confirm with the user before pushing into a
+  database that may already hold those rows.
+
 ### Frontend page type
 
 - **Standard CRUD page** → `pageType: "crud"` (default) with `apiPath`,
@@ -321,12 +432,25 @@ branch still obeys the Grounding-First Rules above.
 
 ### Frontend plugin choice
 
-- **No authentication required** → `vanilla-js-basic`.
-- **JWT authentication required** → `vanilla-js-auth`.
-- **Custom branding / behavior** → `designer_scaffold_plugin` to create a new
-  plugin from template.
+- **No auth** → `vanilla-js-basic`.
+- **Auth WITH RBAC, built into the app** → `vanilla-js-auth` or
+  `vanilla-js-custom` at `designer_init_project`. Use `noAuth: true` (`--no-auth`)
+  to get the plugin's UI without its auth.
+- **Custom branding / new plugin** → `designer_scaffold_plugin`.
+- **Bolt-on auth WITHOUT RBAC** → not a plugin; see Authentication below.
   → references/udf-catalog.md § Plugins
 
+### Authentication
+
+- **Needs RBAC** → plugin auth (`vanilla-js-auth` / `vanilla-js-custom`) at
+  `designer_init_project`. The extension below does **not** do RBAC.
+- **Backend auth on an existing project (no RBAC)** → `project_auth` (after the
+  project and its endpoint exist, with an active DB).
+- **Frontend auth on an app built WITHOUT plugin auth (no RBAC)** →
+  `designer_auth_create` (embedded `rfx_auth`).
+- **Remove embedded frontend auth** → `designer_auth_remove` — destructive,
+  confirm first (see Guardrails).
+
 ---
 
 ## Guardrails
@@ -376,6 +500,20 @@ widgets, or UDF content from memory. Call the matching catalog tool first (see
 Grounding-First Rules). Inventing an option that "should" exist is the most
 common way to produce confidently wrong output.
 
+**7. Confirm before removing embedded auth.**
+`designer_auth_remove` deletes the auth files (`login.html`, `signup.html`, the
+forget-password overlay, `js/rfx_auth.js`) and strips the guard from existing
+pages. Under MCP it runs with `--force` (no interactive prompt), so confirm the
+project name and intent with the user **before** calling it.
+
+**8. Execute through tools; never emulate them.** The bundled `references/` help
+you *understand* options — they do not replace the tools. When a tool can produce
+or validate an artifact (`codegen_dbschema_template`/`init`,
+`codegen_generate_payload`, any `*_validate_*`), **call it**; do not hand-write its
+output by reading a reference. Emulating the generator is slower, loses
+determinism, and drifts from what the installed version emits. If the tool is not
+available, stop (see Preflight) rather than improvising from the references.
+
 ---
 
 ## Prerequisites and Common Errors

package/skills/restforge/references/auth.md

@@ -0,0 +1,145 @@
+# Reference: Auth Extension
+
+> **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,
+> trust the tools, then update this file.
+
+**This file documents the auth EXTENSION — auth WITHOUT RBAC.** It is one of two
+distinct auth mechanisms; do not confuse them:
+
+| Mechanism | RBAC? | Where |
+|---|---|---|
+| **Plugin auth** — built into the frontend at generation | **Yes (auth + RBAC)** | `vanilla-js-auth` / `vanilla-js-custom` plugin, chosen at `designer_init_project`; toggle off with `noAuth: true` (`--no-auth`). See `udf-catalog.md § Plugins`. |
+| **Auth extension** (this file) | **No RBAC** | `project_auth` (backend) + `designer_auth_create` (frontend `rfx_auth`) |
+
+The extension is an optional add-on installed into a project that already exists.
+Backend auth and frontend auth are **independent**: install either, both, or
+neither. Both are JWT-based.
+
+**Out of scope for the extension:** Google Sign-In, RBAC, and the
+`@restforgejs/auth` package. The embedded frontend flow is independent of the
+`vanilla-js-auth` plugin — if the user needs RBAC, use plugin auth, not this.
+
+---
+
+## Backend
+
+MCP tool: `project_auth` — wraps `npx restforge project auth --create`.
+
+```
+npx restforge project auth --create --project=<name> [options]
+```
+
+| Flag | Required | Default | Notes |
+|---|---|---|---|
+| `--create` | yes | `false` | Required trigger; must be present |
+| `--project <name>` | yes* | — | Target project name |
+| `--name <name>` | yes* | — | Alias of `--project` |
+| `--schema-path <dir>` | no | `./schema` | Output folder for auth SDF files |
+| `--config <file>` | no | `config/db-connection.env` | DB config for the migrate step |
+| `--force` | no | `false` | Overwrite existing files (backup still made) |
+
+\* one of `--project` / `--name` is required.
+
+MCP params: `cwd` (project folder, must contain `node_modules/@restforgejs/platform`),
+`project`, `schemaPath?`, `config?`, `force?`.
+
+**What it does (in order):**
+1. Generates auth SDF files (prefix `rfx`) to `--schema-path`.
+2. Creates auth DB tables via dbschema-kit (idempotent, `IF NOT EXISTS`).
+3. Writes auth middleware + router.
+4. Writes six processors: `register`, `login`, `refresh`, `logout`, `me`,
+   `reset-password`.
+5. Injects auth env vars (random `JWT_SECRET`) into the config file.
+6. Records `bcrypt` + `jsonwebtoken` as runtime dependencies in the project's
+   `package.json`.
+
+**Prerequisites:** the project already exists (run `endpoint create` /
+the standard backend pipeline first), `@restforgejs/platform` is installed in the
+project, and the DB is active and reachable with the config credentials.
+
+Idempotent (re-runnable). Non-destructive aside from `--force` overwrites, which
+still create a backup.
+
+---
+
+## Frontend
+
+Embedded login / signup / forget-password overlay (`rfx_auth`), mounted at route
+`/api/<project>/rfx_auth`. Independent of the `vanilla-js-auth` plugin.
+
+MCP tools: `designer_auth_create`, `designer_auth_remove` — wrap
+`npx restforge-designer auth --create | --remove`.
+
+```
+npx restforge-designer auth --create --project=<name> [options]
+npx restforge-designer auth --remove --project=<name> [--frontend-path <path>] --force
+```
+
+`--create` and `--remove` are mutually exclusive; exactly one is required.
+
+| Flag | Applies to | Default | Notes |
+|---|---|---|---|
+| `--create` | create | — | Install the overlay |
+| `--remove` | remove | — | Uninstall the overlay |
+| `--project <name>` | both | — | App code, localStorage prefix, route `/api/<project>/rfx_auth` |
+| `--frontend-path <path>` | both | `./frontend/apps` | Apps root; target app = `<frontend-path>/<project>` |
+| `--api-base-url <url>` | create | from `app-config.json` | Override backend base URL |
+| `--plugins-dir <dir>` | both | auto-detect | Plugins directory |
+| `--overwrite` | create | `false` | Overwrite existing auth files (+ archive backup) |
+| `--force` | remove | `false` | Skip the y/N removal prompt |
+
+MCP params — `designer_auth_create`: `cwd`, `project`, `frontendPath?`,
+`apiBaseUrl?`, `overwrite?`. `designer_auth_remove`: `cwd`, `project`,
+`frontendPath?` (the MCP tool always passes `--force`).
+
+**`--create` does (in order):**
+1. Renders `login.html`, `signup.html`, the forget-password overlay, and
+   `js/rfx_auth.js` from embedded templates (no Google Sign-In).
+2. Writes the artifacts to `<frontend-path>/<project>/`.
+3. Injects an auth guard `<script src="js/rfx_auth.js">` into all existing
+   `*.html` pages in the target dir (except `login.html` / `signup.html`).
+4. Writes the `embeddedAuth` marker to `payload/app-config.json` (non-destructive;
+   other keys untouched).
+
+If no app pages exist yet, guard injection is skipped with a warning; the guard is
+injected automatically when `designer_generate` creates pages later.
+
+**`--remove` does (in order):**
+1. Detects whether auth is installed (files + `embeddedAuth` marker).
+2. Deletes `login.html`, `signup.html`, the forget-password overlay,
+   `js/rfx_auth.js`.
+3. Strips the auth guard from all `*.html` pages (other content untouched).
+4. Removes the `embeddedAuth` key from `payload/app-config.json` (other keys kept).
+
+**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.
+
+Both are idempotent. **`--remove` is destructive** — confirm project name and
+intent with the user before running (MCP always passes `--force`).
+
+---
+
+## Two frontend auth approaches — do not combine
+
+| Approach | RBAC? | When | How |
+|---|---|---|---|
+| Plugin auth (`vanilla-js-auth`, `vanilla-js-custom`) | **Yes (auth + RBAC)** | A new app that needs auth/RBAC | Choose the plugin in `designer_init_project`; auth is built in at generation. Disable with `noAuth: true` (`--no-auth`) |
+| Embedded `rfx_auth` | **No RBAC** | An existing app generated WITHOUT plugin auth | `designer_auth_create` bolts auth on |
+
+Do not add `rfx_auth` to an app already built with plugin auth — they are two
+separate mechanisms. If the user needs RBAC, only plugin auth provides it.
+
+---
+
+## Common errors
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| Backend: "package not installed" precondition | `@restforgejs/platform` missing in the project | Install the package, then re-run |
+| Backend: project does not exist / DB not reachable | Auth runs against an existing project + live DB | Create the project + endpoints first; verify DB config |
+| Frontend: Designer (`npx restforge-designer`) cannot run | `@restforgejs/platform` (which bundles the Designer) missing in the project | Install `@restforgejs/platform` in the project (e.g. via `npx create-restforge-app`), then re-run |
+| Frontend: files already exist, not overwritten | Auth already installed | Use `--overwrite` (create) only if you intend to replace |

package/skills/restforge/references/udf-catalog.md

@@ -471,14 +471,21 @@ an event over the WebSocket channel.
 
 ## Plugins
 
-Two built-in plugins. Run `designer_list_plugins` to confirm available versions.
+Built-in plugins. Run `designer_list_plugins` to confirm what the installed
+version provides — do not hardcode this list.
 
 | Plugin | Auth | Notes |
 |---|---|---|
 | `vanilla-js-basic` | None | Standard CRUD app, no login flow |
-| `vanilla-js-auth` | JWT | Includes login page, token refresh, role-based visibility |
+| `vanilla-js-auth` | Auth + RBAC | Login page, token refresh, role-based access |
+| `vanilla-js-custom` | Auth + RBAC | Customisable markup/CSS/JS; auth + RBAC capable (confirm via `designer_list_plugins`) |
 
-`vanilla-js-auth` requires additional `appConfig` properties:
+Plugin auth is built into the app at generation time. Disable it with
+`noAuth: true` (`--no-auth`) on `designer_init_project` to get the plugin's UI
+without auth. **Plugin auth (with RBAC) is distinct from the embedded `rfx_auth`
+extension** (`designer_auth_create`, no RBAC) — see references/auth.md.
+
+`vanilla-js-auth` accepts additional `appConfig` / init properties:
 - `authAppCode` — must match the backend auth module's app code
 - `idleTimeout` — auto-logout after inactivity (seconds)