create-restforge-skills 1.0.0 → 1.0.2

package/skills/restforge/references/troubleshooting.md

@@ -0,0 +1,144 @@
+# Reference: Prerequisites, Errors, and Commands Outside MCP
+
+Read this file when a tool fails, a prerequisite is missing, or the user asks
+for something no MCP tool wraps.
+
+## Table of Contents
+
+1. [Prerequisites and common errors](#prerequisites-and-common-errors)
+2. [Tools outside the pipelines](#tools-outside-the-pipelines)
+3. [Commands not wrapped as tools](#commands-not-wrapped-as-tools)
+4. [Runtime lifecycle](#runtime-lifecycle)
+
+---
+
+## Prerequisites and common errors
+
+### Environment prerequisites
+
+- Node.js ≥ 18.
+- A reachable database matching the configured `DB_TYPE` (PostgreSQL, MySQL,
+  Oracle, or SQLite).
+- A valid RESTForge license for `codegen_*`, `runtime_*`, and
+  `setup_validate_config`. Designer tools do not require a license.
+- The RESTForge MCP server registered in the client
+  (`npm install -g @restforgejs/mcp-server`, then registered as the `restforge`
+  MCP server). Without it, none of the tools below exist.
+- Redis if using cache, distributed lock, or live sync.
+- Kafka if using a Kafka consumer (`KAFKA_ENABLED=true`).
+
+### Required backend config parameters
+
+Nine of the full parameter set are mandatory before `setup_validate_config` can
+pass:
+
+`LICENSE`, `SERVER_ADDRESS`, `SERVER_PORT`, `DB_TYPE`, `DB_HOST`, `DB_PORT`,
+`DB_USER`, `DB_PASSWORD`, `DB_NAME`.
+
+→ references/config-schema.md for the full parameter list, and
+`setup_get_config_schema` for the live version of it.
+
+### Tools that depend on the installed platform version
+
+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` | `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.
+
+### Common error patterns
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| Tool not found / no `codegen_*` tools available | MCP server not registered in the client | Install `@restforgejs/mcp-server`, register it as the `restforge` MCP server, restart the client |
+| "authenticity check failed" / HTTP 401 | License not active or expired | Set `LICENSE` in `config/db-connection.env`, run `setup_validate_config` |
+| HTTP 429 from license server | Rate limit (10 req/min/IP) | Expected since v5.1.15 — the client falls back to cache; wait or retry |
+| DB connection failed | Wrong DB config or DB not running | Check `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`; verify the DB is running |
+| "softDelete contract violation" | Contract columns missing or wrong type | Fix the SDF declaration, run `codegen_dbschema_validate` |
+| "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` |
+| `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
+`*_validate_*` tool, read its message, and ground against the catalog before
+changing the definition.
+
+---
+
+## Tools outside the pipelines
+
+These MCP tools exist and are callable, but they are not steps of the backend or
+frontend pipeline. They are listed here so their absence from the pipelines reads
+as a decision, not an omission — call them when the user asks for exactly that,
+not as part of a generation run.
+
+| Tool | Why it is outside the pipeline |
+|---|---|
+| `health_ping` | Transport smoke test — answers "is the MCP server itself responsive", touches nothing in RESTForge |
+| `key_generate`, `key_list`, `key_revoke` | API key bookkeeping inside `.env` files; independent of definition files and code generation |
+| `project_list` | Registry inventory (endpoint count, database type, creation date) — useful for orientation, never a prerequisite of a later step |
+
+`license deactivate` has no MCP tool at all, on purpose: it frees a machine slot
+across machines, so the user runs it manually. `license_info` (read-only) is the
+wrapped half of that pair.
+
+---
+
+## Commands not wrapped as tools
+
+These commands are deliberately not MCP tools. Explain what they do and give the
+user the exact command to run in their own terminal; do not run them through a
+shell on the user's behalf.
+
+- **New project scaffolding** — `npx create-restforge-app <name>` creates the
+  folder, installs `@restforgejs/platform` locally, and bundles the designer
+  binary in one step. Point the user to it when they ask how to start. The
+  granular tools (`setup_create_folder` → `setup_install_package` →
+  `setup_init_config`) are the alternative when the agent must build the project
+  step by step.
+- **`fast-track`** — `npx restforge fast-track --project=<name>
+  --schema-path=<dir> [--config=<file>] [--license=<KEY>] [--overwrite]`. One
+  interactive flow from an SDF to a running API (and optionally the frontend):
+  write env → validate `--auto-create-db` → config set-default → schema migrate →
+  payload generate → payload sync `--expand-fk` → endpoint create, then (frontend
+  scope) migrate RDF → UDF → designer generate, and finally a server-start
+  launcher. It prompts for license, database, scope, and confirmation, so the
+  agent cannot drive it. Suggest it for the fastest path; `--overwrite` drops
+  tables and regenerates, so warn before suggesting it. The same pipeline can be
+  reproduced step by step with the MCP tools.
+- **`license deactivate`** — `npx restforge license deactivate`. Frees this
+  machine's activation seat on the license server, an effect that spans machines
+  and cannot be undone from here. Show the current activation with
+  `license_info` first, then let the user run it.
+
+---
+
+## Runtime lifecycle
+
+Starting, stopping, or restarting the RESTForge server or a Kafka consumer is
+always the user's action. A process spawned from the agent session becomes its
+child and dies when the session closes.
+
+- **Run the server** → `runtime_detect_project` → `runtime_detect_config` →
+  `runtime_validate_preflight` → `runtime_generate_launcher`, then tell the user
+  to execute the generated script.
+- **Run a consumer** → `runtime_generate_consumer_launcher` (mode `host` writes
+  consumer-start/consumer-stop, mode `pm2` writes the deploy files under
+  `./deploy/`). The consumer is a separate binary; `config` is mandatory.
+- **Stop or restart** → give the user the exact command or file (`server-stop.bat`,
+  `pm2 restart <project>`). Read-only checks (`runtime_check_status`, the PID
+  file, `pm2 jlist`) are allowed.
+- **User insists on a one-off background run** → state plainly that the process
+  ends with this session, and comply only as a last resort.