create-restforge-skills 0.1.0 → 0.1.1

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.1.1",
   "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
@@ -51,6 +52,24 @@ 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 `restforge-designer` is
+   on PATH; if it is missing, 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
@@ -134,12 +153,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 +207,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 +217,55 @@ 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: restforge-designer auth --create --project=<name>)
+designer_auth_remove   (wraps: 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. `restforge-designer` must be on PATH.
+→ 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 +300,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.
 
 ---
 
@@ -321,12 +385,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 +453,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,142 @@
+# Reference: Auth Extension
+
+> **Offline mirror.** This file mirrors the auth commands of the installed
+> RESTForge platform and Designer (`restforge project auth`, `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
+`restforge-designer auth --create | --remove`.
+
+```
+restforge-designer auth --create --project=<name> [options]
+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 `restforge-designer` binary is installed and 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 not on PATH" precondition | `restforge-designer` binary missing | Install RESTForge Designer and ensure it is on PATH |
+| 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)