create-restforge-skills 0.2.0 → 0.4.0

package/skills/restforge/references/auth.md

@@ -2,7 +2,7 @@
 
 > **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,
+> 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
@@ -116,7 +116,7 @@ injected automatically when `designer_generate` creates pages later.
 **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.
+`npx create-restforge-app`).
 
 Both are idempotent. **`--remove` is destructive** — confirm project name and
 intent with the user before running (MCP always passes `--force`).

package/skills/restforge/references/config-schema.md

@@ -1,173 +1,238 @@
-# Reference: Config Schema (db-connection.env)
-
-> **Offline mirror.** This file mirrors `setup_get_config_schema` from the
-> installed RESTForge platform. The live tool is authoritative — when this file
-> and the tool disagree, trust the tool, then update this file. Parameter set and
-> defaults can change between platform versions.
-
-Source: `setup_get_config_schema` — installed platform version.
-Total: 63 parameters. Required parameters marked **\***.
-Schema version: 1.0.
-
----
-
-## Section: License
-
-| Parameter | Type | Default | Required |
-|---|---|---|---|
-| `LICENSE` | string | `XXXX-XXXX-XXXX-XXXX` | **\*** |
-
----
-
-## Section: Server
-
-| Parameter | Type | Default | Required |
-|---|---|---|---|
-| `SERVER_ADDRESS` | string | `127.0.0.1` | **\*** |
-| `SERVER_PORT` | integer | `3000` | **\*** |
-
----
-
-## Section: Live Sync (WebSocket)
-
-LIVE_SYNC_ENABLED=true requires an API Key (`KEY=...`) for WebSocket client authentication.
-
-| Parameter | Type | Default |
-|---|---|---|
-| `LIVE_SYNC_ENABLED` | boolean | `false` |
-| `LIVE_SYNC_PORT` | integer | `3033` |
-
----
-
-## Section: Redis
-
-| Parameter | Type | Default |
-|---|---|---|
-| `REDIS_HOST` | string | `localhost` |
-| `REDIS_PORT` | integer | `6380` |
-| `REDIS_PASSWORD` | string | `` |
-| `REDIS_DB` | integer | `0` |
-
----
-
-## Section: Export
-
-| Parameter | Type | Default |
-|---|---|---|
-| `EXPORT_FILE_EXPIRY` | integer | `3600000` |
-| `EXPORT_CHUNK_SIZE` | integer | `1000` |
-
----
-
-## Section: Kafka
-
-| Parameter | Type | Default | Notes |
-|---|---|---|---|
-| `KAFKA_ENABLED` | boolean | `false` | |
-| `KAFKA_BROKERS` | string | `localhost:9092` | Comma-separated for multiple brokers |
-| `KAFKA_CONNECTION_TIMEOUT` | integer | `3000` | |
-| `KAFKA_REQUEST_TIMEOUT` | integer | `25000` | |
-| `KAFKA_TOPIC_PATTERN` | string | `{module}.{endpoint}.events` | |
-| `KAFKA_TENANT_ID` | string | `default` | |
-| `KAFKA_SESSION_TIMEOUT` | integer | `30000` | |
-| `KAFKA_HEARTBEAT_INTERVAL` | integer | `3000` | |
-| `KAFKA_MAX_BYTES_PER_PARTITION` | integer | `1048576` | |
-| `KAFKA_AUTO_COMMIT` | boolean | `false` | |
-| `KAFKA_AUTO_COMMIT_INTERVAL` | integer | `5000` | |
-| `KAFKA_RETRY_ATTEMPTS` | integer | `3` | |
-| `KAFKA_RETRY_DELAY` | integer | `1000` | |
-| `KAFKA_RETRY_MAX_DELAY` | integer | `30000` | |
-| `KAFKA_SSL` | boolean | `false` | |
-| `KAFKA_LOG_LEVEL` | string | `info` | |
-
-SASL Authentication (optional, uncomment when broker requires authentication):
-`KAFKA_SASL_MECHANISM` (plain/scram-sha-256/scram-sha-512), `KAFKA_SASL_USERNAME`,
-`KAFKA_SASL_PASSWORD`.
-
----
-
-## Section: Database
-
-| Parameter | Type | Default | Required |
-|---|---|---|---|
-| `DB_TYPE` | string | `postgresql` | **\*** — postgresql, mysql, oracle, sqlite |
-| `DB_HOST` | string | `127.0.0.1` | **\*** |
-| `DB_PORT` | integer | `5432` | **\*** |
-| `DB_USER` | string | `postgres` | **\*** |
-| `DB_PASSWORD` | string | `your_password_here` | **\*** |
-| `DB_NAME` | string | `your_database_name` | **\*** |
-
-For SQLite: set `DB_TYPE=sqlite` and `DB_NAME=./data/myapp.db`.
-`DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD` are ignored for SQLite.
-
----
-
-## Section: Logging
-
-| Parameter | Type | Default |
-|---|---|---|
-| `LOG_LEVEL` | string | `debug` |
-| `LOG_TO_FILE` | boolean | `true` |
-
----
-
-## Section: SQL Logging
-
-| Parameter | Type | Default |
-|---|---|---|
-| `SQL_LOG_ENABLED` | boolean | `false` |
-| `SQL_LOG_LEVEL` | string | `debug` |
-| `SQL_LOG_PARAMS` | boolean | `false` |
-| `SQL_LOG_SLOW_THRESHOLD` | integer | `1000` |
-
----
-
-## Section: Cache
-
-| Parameter | Type | Default |
-|---|---|---|
-| `CACHE_ENABLED` | boolean | `false` |
-| `CACHE_TTL` | integer | `300` |
-
----
-
-## Section: Job Scheduler
-
-| Parameter | Type | Default |
-|---|---|---|
-| `JOB_ENABLED` | boolean | `false` |
-| `JOB_CONCURRENCY` | integer | `5` |
-| `JOB_RETENTION_HOURS` | integer | `72` |
-| `JOB_FAILED_RETENTION_HOURS` | integer | `168` |
-| `JOB_SHUTDOWN_TIMEOUT` | integer | `10000` |
-| `JOB_STALLED_INTERVAL` | integer | `30000` |
-| `JOB_MAX_STALLED_COUNT` | integer | `2` |
-
----
-
-## Section: Distributed Lock
-
-| Parameter | Type | Default |
-|---|---|---|
-| `LOCK_DISTRIBUTED_ENABLED` | boolean | `false` |
-| `LOCK_DISTRIBUTED_TTL` | integer | `10` |
-| `LOCK_RESOURCE_MAX_TTL` | integer | `600` |
-| `LOCK_DISTRIBUTED_RETRY` | integer | `3` |
-| `LOCK_DISTRIBUTED_RETRY_DELAY` | integer | `100` |
-| `LOCK_DISTRIBUTED_STRATEGY` | string | `reject` |
-
----
-
-## Section: ID Generator
-
-| Parameter | Type | Default |
-|---|---|---|
-| `IDGEN_ENABLED` | boolean | `false` |
-| `IDGEN_IDEM_TTL` | integer | `600` |
-| `IDGEN_COUNTER_TTL_MONTHLY` | integer | `2764800` |
-| `IDGEN_COUNTER_TTL_DAILY` | integer | `172800` |
-| `IDGEN_DEFAULT_MAX_RETRY` | integer | `10` |
-| `IDGEN_DEFAULT_PIN_DIGITS` | integer | `6` |
-| `IDGEN_DEFAULT_SERIAL_PATTERN` | string | `XXXX-XXXX-XXXX-XXXX` |
-| `IDGEN_DEFAULT_CODE_PATTERN` | string | `9999-9999` |
-| `IDGEN_ALLOW_RESET` | boolean | `false` |
+# Reference: Config Schema (db-connection.env)
+
+> **Offline mirror.** This file mirrors `setup_get_config_schema` from the
+> installed RESTForge platform. The live tool is authoritative — when this file
+> and the tool disagree, trust the tool, then update this file. Parameter set and
+> defaults can change between platform versions.
+
+Source: `setup_get_config_schema` — installed platform version.
+Total: 75 active parameters plus 4 commented-out optional ones (`KAFKA_CLIENT_ID`
+and the three SASL keys). Required parameters marked **\***.
+Schema version: 1.0.
+
+---
+
+## Section: Environment
+
+| Parameter | Type | Default | Notes |
+|---|---|---|---|
+| `NODE_ENV` | string | `production` | `production` or `development`. `development` exposes extra error detail (valid field lists, stack traces); keep `production` on deployed servers |
+
+---
+
+## Section: License
+
+| Parameter | Type | Default | Required |
+|---|---|---|---|
+| `LICENSE` | string | `XXXX-XXXX-XXXX-XXXX` | **\*** |
+
+---
+
+## Section: Server
+
+| Parameter | Type | Default | Required |
+|---|---|---|---|
+| `SERVER_ADDRESS` | string | `127.0.0.1` | **\*** |
+| `SERVER_PORT` | integer | `3000` | **\*** |
+
+---
+
+## Section: CORS
+
+| Parameter | Type | Default | Notes |
+|---|---|---|---|
+| `CORS_ENABLED` | boolean | `true` | Enables the CORS middleware |
+| `CORS_ORIGINS` | string | `*` | Comma-separated allowed origins; `*` allows every origin (development only) |
+
+---
+
+## Section: Live Sync (WebSocket)
+
+LIVE_SYNC_ENABLED=true requires an API Key (`KEY=...`) for WebSocket client authentication.
+
+| Parameter | Type | Default |
+|---|---|---|
+| `LIVE_SYNC_ENABLED` | boolean | `false` |
+| `LIVE_SYNC_PORT` | integer | `3033` |
+
+---
+
+## Section: Redis
+
+| Parameter | Type | Default |
+|---|---|---|
+| `REDIS_HOST` | string | `localhost` |
+| `REDIS_PORT` | integer | `6380` |
+| `REDIS_PASSWORD` | string | `` |
+| `REDIS_DB` | integer | `0` |
+
+---
+
+## Section: Export
+
+| Parameter | Type | Default |
+|---|---|---|
+| `EXPORT_FILE_EXPIRY` | integer | `3600000` |
+| `EXPORT_CHUNK_SIZE` | integer | `1000` |
+
+---
+
+## Section: Kafka
+
+| Parameter | Type | Default | Notes |
+|---|---|---|---|
+| `KAFKA_ENABLED` | boolean | `false` | |
+| `KAFKA_BROKERS` | string | `localhost:9092` | Comma-separated for multiple brokers |
+| `KAFKA_CLIENT_ID` | string | commented out | Optional; default `restforge-{project}-producer` / `-consumer` |
+| `KAFKA_CONNECTION_TIMEOUT` | integer | `3000` | |
+| `KAFKA_REQUEST_TIMEOUT` | integer | `25000` | |
+| `KAFKA_TOPIC_PATTERN` | string | `{module}.{endpoint}.events` | |
+| `KAFKA_TENANT_ID` | string | `default` | |
+| `KAFKA_SESSION_TIMEOUT` | integer | `30000` | |
+| `KAFKA_HEARTBEAT_INTERVAL` | integer | `3000` | |
+| `KAFKA_MAX_BYTES_PER_PARTITION` | integer | `1048576` | |
+| `KAFKA_AUTO_COMMIT` | boolean | `false` | |
+| `KAFKA_AUTO_COMMIT_INTERVAL` | integer | `5000` | |
+| `KAFKA_RETRY_ATTEMPTS` | integer | `3` | |
+| `KAFKA_RETRY_DELAY` | integer | `1000` | |
+| `KAFKA_RETRY_MAX_DELAY` | integer | `30000` | |
+| `KAFKA_SSL` | boolean | `false` | |
+| `KAFKA_LOG_LEVEL` | string | `info` | |
+
+SASL Authentication (optional, uncomment when broker requires authentication):
+`KAFKA_SASL_MECHANISM` (plain/scram-sha-256/scram-sha-512), `KAFKA_SASL_USERNAME`,
+`KAFKA_SASL_PASSWORD`.
+
+---
+
+## Section: Database
+
+| Parameter | Type | Default | Required |
+|---|---|---|---|
+| `DB_TYPE` | string | `postgresql` | **\*** — postgresql, mysql, oracle, sqlite |
+| `DB_HOST` | string | `127.0.0.1` | **\*** |
+| `DB_PORT` | integer | `5432` | **\*** |
+| `DB_USER` | string | `postgres` | **\*** |
+| `DB_PASSWORD` | string | `your_password_here` | **\*** |
+| `DB_NAME` | string | `your_database_name` | **\*** |
+
+For SQLite: set `DB_TYPE=sqlite` and `DB_NAME=./data/myapp.db`.
+`DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD` are ignored for SQLite.
+
+---
+
+## Section: Date/Time
+
+The single date/time standard of the application: it applies to every field and
+every endpoint, and each response repeats it in the `X-Timezone`, `X-Date-Format`,
+and `X-DateTime-Format` headers. There is no per-field pattern for `date` and
+`timestamp`. Invalid values stop the server at startup with a clear error.
+
+| Parameter | Type | Template value | Runtime default when absent | Notes |
+|---|---|---|---|---|
+| `TIMEZONE` | string | `Asia/Jakarta` | `UTC` | IANA zone name used for zone-less input and audit columns |
+| `DATEFORMAT` | string | `yyyy-MM-dd` | `yyyy-MM-dd` | `yyyy-MM-dd`, `dd/MM/yyyy`, `dd-MM-yyyy`, `MM/dd/yyyy`, `yyyy/MM/dd` |
+| `DATETIMEFORMAT` | string | `yyyy-MM-dd HH:mm` | `yyyy-MM-dd HH:mm:ss.SSS` | `<date pattern> <time pattern>`; time pattern `HH:mm`, `HH:mm:ss`, or `HH:mm:ss.SSS`. Input form only for `timestamptz`, whose output is always ISO UTC |
+
+After changing `DATEFORMAT` or `DATETIMEFORMAT`, re-run `codegen_migrate_payload`
+and `designer_generate`: the frontend copies both values into `appConfig` and
+cannot detect a mismatch by itself.
+
+---
+
+## Section: Tenancy
+
+| Parameter | Type | Default | Notes |
+|---|---|---|---|
+| `TENANT_MODE` | string | `single` | `single` (no tenant filtering) or `multi` (data partitioned by tenant) |
+| `TENANT_COLUMN` | string | `tenant_id` | Tenant identifier column in every table; `multi` only |
+| `TENANT_BYPASS_ROLES` | string | empty | Comma-separated roles that bypass the tenant filter; empty = strict isolation. Platform operators only |
+
+---
+
+## Section: Code Generation
+
+| Parameter | Type | Default | Notes |
+|---|---|---|---|
+| `FK_AUTO_JOIN` | string | `left` | JOIN type written by `codegen_sync_payload` FK expansion: `left` keeps rows with a NULL FK, `inner` keeps only rows with a valid reference |
+
+---
+
+## Section: Logging
+
+| Parameter | Type | Default |
+|---|---|---|
+| `LOG_LEVEL` | string | `debug` |
+| `LOG_TO_FILE` | boolean | `true` |
+
+---
+
+## Section: SQL Logging
+
+| Parameter | Type | Default |
+|---|---|---|
+| `SQL_LOG_ENABLED` | boolean | `false` |
+| `SQL_LOG_LEVEL` | string | `debug` |
+| `SQL_LOG_PARAMS` | boolean | `false` |
+| `SQL_LOG_SLOW_THRESHOLD` | integer | `1000` |
+
+---
+
+## Section: Query Limits
+
+| Parameter | Type | Default | Notes |
+|---|---|---|---|
+| `READ_MAX_LIMIT` | integer or `unlimited` | `5000` | Maximum rows returned by `/read` without `page`. Larger requests are cut and flagged `truncated: true`. `unlimited` lets clients send `limit: "all"`, holding the whole result in server memory |
+| `DATATABLES_MAX_LENGTH` | integer | `1000` | Maximum `length` accepted by `/datatables`. Larger requests are cut and flagged `truncated: true` |
+
+---
+
+## Section: Cache
+
+| Parameter | Type | Default |
+|---|---|---|
+| `CACHE_ENABLED` | boolean | `false` |
+| `CACHE_TTL` | integer | `300` |
+
+---
+
+## Section: Job Scheduler
+
+| Parameter | Type | Default |
+|---|---|---|
+| `JOB_ENABLED` | boolean | `false` |
+| `JOB_CONCURRENCY` | integer | `5` |
+| `JOB_RETENTION_HOURS` | integer | `72` |
+| `JOB_FAILED_RETENTION_HOURS` | integer | `168` |
+| `JOB_SHUTDOWN_TIMEOUT` | integer | `10000` |
+| `JOB_STALLED_INTERVAL` | integer | `30000` |
+| `JOB_MAX_STALLED_COUNT` | integer | `2` |
+
+---
+
+## Section: Distributed Lock
+
+| Parameter | Type | Default |
+|---|---|---|
+| `LOCK_DISTRIBUTED_ENABLED` | boolean | `false` |
+| `LOCK_DISTRIBUTED_TTL` | integer | `10` |
+| `LOCK_RESOURCE_MAX_TTL` | integer | `600` |
+| `LOCK_DISTRIBUTED_RETRY` | integer | `3` |
+| `LOCK_DISTRIBUTED_RETRY_DELAY` | integer | `100` |
+| `LOCK_DISTRIBUTED_STRATEGY` | string | `reject` |
+
+---
+
+## Section: ID Generator
+
+| Parameter | Type | Default |
+|---|---|---|
+| `IDGEN_ENABLED` | boolean | `false` |
+| `IDGEN_IDEM_TTL` | integer | `600` |
+| `IDGEN_COUNTER_TTL_MONTHLY` | integer | `2764800` |
+| `IDGEN_COUNTER_TTL_DAILY` | integer | `172800` |
+| `IDGEN_DEFAULT_MAX_RETRY` | integer | `10` |
+| `IDGEN_DEFAULT_PIN_DIGITS` | integer | `6` |
+| `IDGEN_DEFAULT_SERIAL_PATTERN` | string | `XXXX-XXXX-XXXX-XXXX` |
+| `IDGEN_DEFAULT_CODE_PATTERN` | string | `9999-9999` |
+| `IDGEN_ALLOW_RESET` | boolean | `false` |