@restforgejs/mcp-server 1.2.0

package/dist/tools/codegen/validate-dashboard-payload.js

@@ -0,0 +1,239 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function registerCodegenValidateDashboardPayload(server) {
+    server.registerTool('codegen_validate_dashboard_payload', {
+        title: 'Validate Dashboard Payload',
+        description: `Validate the structural correctness of a dashboard payload spec WITHOUT generating any file, by wrapping restforge dashboard --validate-only=true.
+
+Dashboards have a different shape than CRUD endpoints (widgets array, no tableName, no fieldValidation). The CLI's DashboardValidator checks: widgets array shape, allowed/forbidden fields per level, the 'query' vs 'queries' mutual exclusion, params contract (each ':placeholder' used in SQL must be declared in 'params'), 'file:query/<name>.sql' reference resolution, and that no frontend-only fields (widgetType, layout, title, subtitle, color) leak into the payload.
+
+This tool is READ-ONLY: it does NOT write any file, does NOT touch the database, does NOT update the project registry. It only reports whether the payload structure is valid. Re-running with the same input gives the same result (idempotent).
+
+Workflow positioning: this is the natural pre-flight before 'codegen_create_dashboard'. When the AI authors a dashboard payload (manually via Write), call this tool first to surface validation errors cheaply — before invoking the generator that performs filesystem writes.
+
+Gap closed: the general 'codegen_validate_payload' tool silently skips dashboard payloads (it filters on 'tableName' and 'fieldName'). This tool fills that gap for the dashboard shape.
+
+USE WHEN:
+- The user asks to validate, check, or verify the structure of a dashboard payload before generating
+- The user has authored a dashboard payload (with 'widgets' array) and wants to confirm it parses correctly before invoking the generator
+- Pertanyaan dalam bentuk: "cek dashboard payload saya valid?", "validate dashboard config", "is this dashboard schema correct?", "apakah payload dashboard ini OK?"
+- Before invoking 'codegen_create_dashboard' — pre-flight to surface validation errors early (cheaper than failing inside the generator stage, which performs filesystem writes)
+- The user reports that 'codegen_create_dashboard' failed with a validation-related error and wants to fix the payload iteratively
+- The user mentions specific dashboard validation rules: forbidden frontend fields (widgetType, layout, title, subtitle, color), 'query' vs 'queries' mutex, params placeholder declaration
+- After the user manually edited a dashboard payload and wants a quick sanity check before re-running the generator
+- The user is unsure whether their payload follows dashboard shape (widgets) or CRUD shape (tableName) and wants verification
+
+DO NOT USE FOR:
+- Validating a CRUD payload (with 'tableName' and 'fieldName') against database schema -> use 'codegen_validate_payload'
+- Generating the dashboard module after validation -> use 'codegen_create_dashboard'
+- Inspecting drift between CRUD payload and database -> use 'codegen_validate_payload' (this dashboard validator does NOT touch the database)
+- Generating a payload from scratch -> use 'codegen_generate_payload' for CRUD; for dashboard, the user authors manually
+- Looking up the field validation catalog -> use 'codegen_get_field_validation_catalog' (different scope; dashboard payloads have no fieldValidation)
+- Validating SQL syntax inside a widget query — the validator only checks placeholder declarations and structural shape, not SQL semantics. SQL errors will only surface when the dashboard endpoint is actually called at runtime.
+
+Cross-reference: this tool is the read-only sibling of 'codegen_create_dashboard'. Both have nearly identical input schemas, but this tool only validates and does NOT generate any file.
+
+Preconditions:
+- The project must have @restforgejs/platform installed in node_modules.
+- The payload file must exist at <cwd>/payload/<payload>.json before calling this tool.
+- The dashboard name MUST start with 'dash-' prefix (CLI requirement). For validate-only mode, this is checked at the argument-parser level even though the value is not used to write any file.
+
+PRESENTATION GUIDANCE:
+- Match the user's language. If the user writes in Indonesian, respond in Indonesian.
+- Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "validate the dashboard payload", "generate the dashboard module").
+- Speak in plain language. Summarise the result; do not paste raw CLI output unless the user explicitly asks.
+- This tool is read-only: it validates payload structure without writing files or touching the database. Safe to invoke proactively before 'codegen_create_dashboard' to give the user faster feedback on payload errors.
+- If validation passes, briefly confirm the result and offer to proceed with generation. If validation fails, surface the specific error in plain language and offer to help fix it. Do not paste raw CLI output unless the user explicitly asks.
+- When a precondition is not met, frame it as a question or next-step suggestion rather than an error.`,
+        inputSchema: {
+            cwd: z
+                .string()
+                .min(1)
+                .describe('Absolute path of the project folder (must contain node_modules/@restforgejs/platform and a payload/ directory with the named payload file)'),
+            project: z
+                .string()
+                .min(1)
+                .max(50)
+                .regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/, 'must start with a letter or number; only letters, numbers, dashes, underscores allowed')
+                .describe('Project name. Required by the CLI argument schema even in validate-only mode. Letters/numbers/dash/underscore, max 50 chars.'),
+            name: z
+                .string()
+                .min(6)
+                .max(50)
+                .regex(/^dash-[a-zA-Z0-9_-]+$/, "must start with 'dash-' prefix and have at least one character after it (e.g. dash-sales, dash-inbound)")
+                .describe("Dashboard name. MUST start with 'dash-' prefix (CLI requirement). For validate-only mode, this is checked at the argument-parser level even though the value is not used to write any file. The CLI rejects 'dash-' alone — there must be at least one character after the prefix."),
+            payload: z
+                .string()
+                .min(1)
+                .max(50)
+                .regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/, 'must start with a letter or number; only letters, numbers, dashes, underscores allowed')
+                .describe('Payload file name without the .json extension. The file must exist at <cwd>/payload/<payload>.json. Payload must follow the dashboard schema (with a `widgets` array; NOT a CRUD payload with `tableName`).'),
+            database: z
+                .enum(['postgres', 'oracle', 'mysql'])
+                .optional()
+                .describe('Database type. Default postgres. Database connection is NOT used in validate-only mode (validation is structural, not drift-based), but kept for argument-schema parity with codegen_create_dashboard.'),
+            skipSqlValidation: z
+                .boolean()
+                .optional()
+                .describe('Default false (CLI default). When true, skip SQL keyword validation in payload widget queries. Useful when the SQL fragments are intentional but the validator flags them as suspicious.'),
+        },
+        annotations: {
+            title: 'Validate Dashboard Payload',
+            readOnlyHint: true, // pure validation, no filesystem write, no DB write
+            idempotentHint: true, // re-running gives same result for same input
+        },
+    }, async ({ cwd, project, name, payload, database, skipSqlValidation }) => {
+        const projectCwd = resolve(cwd);
+        const dbType = database ?? 'postgres';
+        // Pre-flight 1: @restforgejs/platform must be installed. Treated as a non-error precondition per §3.4.
+        try {
+            await access(join(projectCwd, 'node_modules', '@restforgejs', 'platform'));
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Precondition not met: the RESTForge package is not installed in this project.
+
+Project path: ${projectCwd}
+Expected location: node_modules/@restforgejs/platform
+Requested project: ${project}
+Requested dashboard: ${name}
+Requested payload: ${payload}
+
+For the assistant:
+- The dashboard payload validator can only run once the RESTForge package is installed locally.
+- Suggest installing the package first, then retry validating the dashboard payload.
+- When explaining to the user, say something like "the RESTForge package isn't installed yet — should I install it first?". Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false, // per §3.4
+            };
+        }
+        // Pre-flight 2: payload file must exist. Treated as a non-error precondition per §3.4.
+        const payloadPath = join(projectCwd, 'payload', `${payload}.json`);
+        if (!(await pathExists(payloadPath))) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Precondition not met: payload file not found.
+
+Project path: ${projectCwd}
+Expected payload file: ${payloadPath}
+Requested project: ${project}
+Requested dashboard: ${name}
+Requested payload: ${payload}
+
+For the assistant:
+- The dashboard payload validator needs the payload file to exist before it can run.
+- Suggest creating or locating the payload first. Dashboard payloads have a different schema than CRUD payloads (a \`widgets\` array instead of \`tableName\`); see the dashboard documentation if the user is unfamiliar with the format.
+- When explaining to the user, say something like "the payload file '${payload}.json' isn't in the payload/ folder yet — should I help you draft it, or do you have one to put there?". Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false, // per §3.4
+            };
+        }
+        // Build CLI invocation. --validate-only=true is hardcoded: this tool is ONLY for validation.
+        // --force is NOT passed (not relevant for validate-only — no overwrite scenario).
+        // Validation logic itself is delegated to the CLI's DashboardValidator (single source of
+        // truth — see refactor 8C).
+        const cliArgs = [
+            'restforge',
+            'dashboard',
+            'create',
+            `--project=${project}`,
+            `--name=${name}`,
+            `--payload=${payload}`,
+            `--database=${dbType}`,
+            '--validate-only=true',
+        ];
+        if (skipSqlValidation !== undefined)
+            cliArgs.push(`--skip-sql-validation=${skipSqlValidation}`);
+        const result = await execProcess('npx', cliArgs, {
+            cwd: projectCwd,
+            timeout: 30_000, // validation is light: no DB connection, no filesystem write
+            env: { NODE_ENV: 'production' }, // suppress legacy banner output
+            stripFinalNewline: true,
+        });
+        // Branch C: CLI failure (validation failed or other) — real error per §3.4; structured per §3.5.
+        if (!result.success) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Dashboard payload validation failed.
+
+Project path: ${projectCwd}
+Project: ${project}
+Dashboard: ${name}
+Payload: payload/${payload}.json
+Command: ${result.command}
+Exit code: ${result.exitCode}
+
+--- CLI output ---
+stdout:
+${result.stdout}
+
+stderr:
+${result.stderr}
+--- end CLI output ---
+
+For the assistant:
+- Tell the user that the dashboard payload validation did not pass. Surface the error message from the CLI output (typically a single 'Error: ...' line) in plain language.
+- Common validation errors and suggested fixes:
+  * 'must not contain tableName' — the payload has CRUD shape; remove 'tableName' or use the CRUD payload validator instead (do not mention internal tool name; describe the action).
+  * 'must have widgets array' — payload is missing the 'widgets' field; suggest adding it with at least one entry.
+  * 'must declare either query or queries' — a widget is missing both fields; pick one based on whether the widget needs single SQL or multi-SQL.
+  * 'undeclared placeholder' — SQL uses ':param_name' that is not declared in 'params'; add it to 'params' or remove the placeholder from SQL.
+  * 'forbidden frontend field' (widgetType, layout, title, subtitle, color) — those belong in the frontend code; remove them from the payload.
+  * 'invalid type' for params — the param type must be one of: string, number, boolean, date.
+  * 'duplicate widget id' — two widgets share the same id; pick distinct ids.
+- Offer to help fix the payload and retry validation.
+- Do not paste the raw stdout/stderr unless the user explicitly asks. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Branch B: CLI success (validation passed) — one-line summary + labeled facts + fenced output per §3.5.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Dashboard payload validation passed.
+
+Project path: ${projectCwd}
+Project: ${project}
+Dashboard: ${name}
+Payload: payload/${payload}.json
+
+--- CLI output ---
+${result.stdout}
+--- end CLI output ---
+
+For the assistant:
+- Confirm to the user in plain language that the dashboard payload structure is valid.
+- This validation does NOT touch the database or write any file. It only checks payload structure (widgets array shape, allowed/forbidden fields, params contract, file:reference resolution, placeholder declaration).
+- If the user requested validation as a precursor to generation, the next step is to generate the dashboard module. Do not mention internal tool names; describe the action ("generate the dashboard module").
+- If the CLI output mentions warnings (lines starting with '! Warning'), surface them to the user — these are non-fatal but worth knowing.
+- Do not paste the full CLI output unless the user explicitly asks; summarise instead.
+- Match the user's language.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=validate-dashboard-payload.js.map

package/dist/tools/codegen/validate-dashboard-payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-dashboard-payload.js","sourceRoot":"","sources":["../../../src/tools/codegen/validate-dashboard-payload.ts"],"names":[],"mappings":"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"}

package/dist/tools/codegen/validate-payload.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCodegenValidatePayload(server: McpServer): void;

package/dist/tools/codegen/validate-payload.js

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+export function registerCodegenValidatePayload(server) {
+    server.registerTool('codegen_validate_payload', {
+        title: 'Validate Payload',
+        description: `Validate that existing payload spec files in a project are still in sync with the current database schema, by running restforge payload --validate.
+
+USE WHEN:
+- The user asks to validate, check, or verify whether existing payload files are still in sync with the current database schema
+- The user asks things like "cek drift payload", "validate semua payload", "apakah payload masih sinkron", "is the schema in sync", "check schema drift"
+- The user mentions ALTER TABLE in the database and wants to know which payloads are affected
+- Routine drift check after pulling new database migrations
+- Periodic audit of payload files in a project
+- Often called before 'codegen_diff_payload' as a quick overall status pass; if a file shows DRIFT, follow up with 'codegen_diff_payload' to see column-level details.
+- The user wants to validate PAYLOAD FILES against the database schema, not configuration credentials
+
+DO NOT USE FOR:
+- Seeing the per-column detail of what changed -> use 'codegen_diff_payload'
+- Generating a payload from scratch for a table that has no payload yet -> use 'codegen_generate_payload'
+- Updating payload files to match the database -> use 'codegen_sync_payload'
+- Checking the database connection, license, or other config credentials -> use 'setup_validate_config'
+
+This tool runs: npx restforge payload --validate --config=<config> [--table=<table>] [--output=<output>] in the given cwd.
+The CLI reads existing payload JSON files from the output directory, connects to the database described
+in the config file, and reports per-file status (typically OK / DRIFT / ERROR) without modifying any file.
+
+Preconditions:
+- The project must have @restforgejs/platform installed in node_modules.
+- The config file (default 'db-connection.env') must exist in the project and contain valid
+  database credentials. This tool does not pre-check that — if the CLI fails, the failure response
+  will surface the underlying cause.
+
+PRESENTATION GUIDANCE:
+- Match the user's language. If the user writes in Indonesian, respond in Indonesian.
+- Never mention internal tool names in the reply to the user. Describe actions by what they do (e.g. "validate the payload files", "see the column-level differences", "sync the payload files").
+- Speak in plain language. Summarise the result; do not paste raw CLI output unless the user explicitly asks.
+- When a precondition is not met, frame it as a question or next-step suggestion rather than an error.`,
+        inputSchema: {
+            cwd: z
+                .string()
+                .min(1)
+                .describe('Absolute path of the project folder (must contain node_modules/@restforgejs/platform and the config file)'),
+            config: z
+                .string()
+                .min(1)
+                .default('db-connection.env')
+                .describe('Config file name (relative to project) used by the CLI to connect to the database'),
+            table: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Specific table name to check (e.g. supplier or core.supplier). When omitted, all payload files in the output directory are checked.'),
+            output: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Payload directory relative to project (e.g. payload). When omitted, the CLI uses its default (payload/).'),
+        },
+        annotations: {
+            title: 'Validate Payload',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ cwd, config, table, output }) => {
+        const projectCwd = resolve(cwd);
+        // Precondition check: @restforgejs/platform must be present in node_modules.
+        // Treated as a non-error precondition per the authoring guide §3.4.
+        try {
+            await access(join(projectCwd, 'node_modules', '@restforgejs', 'platform'));
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Precondition not met: the RESTForge package is not installed in this project.
+
+Project path: ${projectCwd}
+Expected location: node_modules/@restforgejs/platform
+Requested table: ${table ?? 'all'}
+Requested config: ${config}
+Requested output: ${output ?? 'default (payload/)'}
+
+For the assistant:
+- The user needs to install the RESTForge package before payload files can be validated against the database schema.
+- Use the appropriate package-installation tool to do this, then retry validating the payload.
+- When explaining to the user, say something like "the RESTForge package isn't installed yet — should I install it first?". Do not mention internal tool names.`,
+                    },
+                ],
+                isError: false, // per §3.4
+            };
+        }
+        // Forward only the arguments the user supplied. Defaults inside restforge
+        // (e.g. payload/ as the default output dir, all files when --table is omitted)
+        // should remain in effect when the user does not specify them. per §3.5
+        const args = ['restforge', 'payload', 'validate', `--config=${config}`];
+        if (table)
+            args.push(`--table=${table}`);
+        if (output)
+            args.push(`--output=${output}`);
+        const result = await execProcess('npx', args, { cwd: projectCwd, timeout: 30_000 });
+        // CLI failure: real error per §3.4; structured per §3.5.
+        if (!result.success) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to validate payload.
+
+Project path: ${projectCwd}
+Config: ${config}
+Table: ${table ?? 'all'}
+Output: ${output ?? 'default (payload/)'}
+Command: ${result.command}
+Exit code: ${result.exitCode}
+
+--- CLI output ---
+stdout:
+${result.stdout}
+
+stderr:
+${result.stderr}
+--- end CLI output ---
+
+For the assistant:
+- Tell the user that the payload validation did not complete successfully.
+- Summarise the likely cause from the CLI output in plain language (common causes: the config file is missing or has incomplete credentials, the database is unreachable, the requested table does not exist, or the payload directory is empty). Do not paste the raw stdout/stderr unless the user explicitly asks.
+- Offer to retry once the underlying issue is resolved. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Success: one-line summary + labeled facts + fenced raw output per §3.5.
+        // The CLI prints a Summary section with counts (OK / DRIFT / ERROR); the
+        // model should extract those numbers from stdout when talking to the user.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Payload validation completed.
+
+Project path: ${projectCwd}
+Config: ${config}
+Table: ${table ?? 'all'}
+Output: ${output ?? 'default (payload/)'}
+Command: ${result.command}
+
+--- CLI output ---
+${result.stdout}
+--- end CLI output ---
+
+For the assistant:
+- Read the Summary section in the CLI output above and tell the user how many payload files are OK, in DRIFT, or in ERROR.
+- If every file is OK, confirm in plain language that the payload files are still in sync with the database.
+- If any file is in DRIFT or ERROR, suggest as the next step that the user can see the column-level differences for the affected file (added, removed, or changed columns). Do not name the internal tool — describe it by what it does.
+- If the user later wants to apply those changes, mention that the next step is to update the payload files automatically (with the previous version archived). Describe this step in plain language; do not name the internal tool.
+- Keep the reply concise. Do not paste the raw CLI output unless the user explicitly asks. Do not mention internal tool names.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=validate-payload.js.map

package/dist/tools/codegen/validate-payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-payload.js","sourceRoot":"","sources":["../../../src/tools/codegen/validate-payload.ts"],"names":[],"mappings":"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"}

package/dist/tools/codegen/validate-sql.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCodegenValidateSql(server: McpServer): void;