create-restforge-skills 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-restforge-skills",
-  "version": "0.1.1",
+  "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

@@ -29,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
@@ -63,8 +63,10 @@ Verify readiness before planning or producing anything:
    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.
+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.
 
@@ -80,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.
@@ -253,12 +262,14 @@ Adds (or removes) an **embedded** login / signup / forget-password overlay
 `/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)
+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. `restforge-designer` must be on PATH.
+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
@@ -364,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
 
@@ -373,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`,

package/skills/restforge/references/auth.md

@@ -1,8 +1,8 @@
 # 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,
+> 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
@@ -70,11 +70,11 @@ 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`.
+`npx restforge-designer auth --create | --remove`.
 
 ```
-restforge-designer auth --create --project=<name> [options]
-restforge-designer auth --remove --project=<name> [--frontend-path <path>] --force
+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.
@@ -113,7 +113,10 @@ injected automatically when `designer_generate` creates pages later.
 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.
+**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`).
@@ -138,5 +141,5 @@ separate mechanisms. If the user needs RBAC, only plugin auth provides it.
 |---|---|---|
 | 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: 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 |