@restforgejs/mcp-server 1.2.0

package/dist/server.js

@@ -0,0 +1,220 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerHealthTools } from './tools/health/index.js';
+import { registerSetupTools } from './tools/setup/index.js';
+import { registerCodegenTools } from './tools/codegen/index.js';
+import { registerRuntimeTools } from './tools/runtime/index.js';
+const SERVER_NAME = 'restforge-mcp';
+const SERVER_VERSION = '1.0.0';
+const SERVER_INSTRUCTIONS = `
+This MCP server manages RESTForge backend project configuration.
+
+WHEN TO PREFER THESE TOOLS over generic filesystem operations:
+- The user asks about project configuration, settings, env values, or "what's set up"
+- The user asks vague questions like "apa yang sudah di-set", "cek project",
+  "tampilkan konfigurasi", "is this configured", "what's the status"
+- The user mentions "parameter", "config", "setup", "konfigurasi" in any form
+- The current working directory contains @restforgejs/platform in node_modules
+
+In these cases, prefer using RESTForge tools (setup_read_env, etc.) to inspect
+the actual state, rather than reading files manually with filesystem tools or
+guessing from directory structure.
+
+If the configuration file does not exist, that is meaningful information —
+the precondition response will tell you, and you should pass that information
+to the user as a question about whether to set up the initial config.
+
+Do not enumerate what "should" be in a backend project (folders like src, routes,
+models, etc.). RESTForge has its own conventions; do not assume generic Express
+or NestJS structure.
+
+PROACTIVE USAGE:
+When the user works in a project that contains @restforgejs/platform in node_modules,
+prefer these tools over generic file/bash operations for the following:
+- Reading or writing config/db-connection.env
+- Validating config (license, DB, redis, kafka connections)
+- Generating, validating, diffing, or syncing payload JSON files
+- Looking up the field validation catalog before editing payload constraints
+- Installing or upgrading the @restforgejs/platform package
+
+Detection signals for "this is a RESTForge project":
+- Folder contains node_modules/@restforgejs/platform, OR
+- Folder contains config/db-connection.env, OR
+- Folder contains a payload/ directory with .json files, OR
+- The user explicitly mentions "RESTForge", "restforge", "@restforgejs/platform", or
+  related keywords (payload, codegen, db-connection, license)
+
+When uncertain whether a folder is a RESTForge project, call setup_read_env
+first to inspect the config file content — it's a cheap local file read with
+no network calls. Don't assume from filenames alone. (setup_validate_config
+exists too, but it actively connects to the database and license server, so
+reserve it for explicit validation requests, not initial inspection.)
+
+Do not silently fall back to generic file/bash operations for the categories
+above. If a request requires an operation outside these tools' scope (e.g.
+DDL changes — see LAYER BOUNDARY below; running, stopping, or restarting the
+server — see RUNTIME LIFECYCLE BOUNDARY below), state that explicitly to the
+user before proceeding.
+
+RUNTIME LIFECYCLE BOUNDARY:
+For any user request involving starting, stopping, or restarting the
+RESTForge runtime server (e.g. "run my app", "jalankan server", "start
+restforge", "stop server", "restart server"), you MUST use the runtime_*
+tools — specifically 'runtime_generate_launcher' to scaffold a launcher
+script. Do NOT use the Bash tool to spawn 'npx restforge', 'pm2 start <app>',
+or equivalent processes. Server processes spawned via Bash become children of
+this AI session and will be killed when the session closes (process tree dies
+with the parent).
+
+The correct flow is: detect project (runtime_detect_project) → detect config
+(runtime_detect_config) → validate preflight (runtime_validate_preflight) →
+generate launcher (runtime_generate_launcher) → tell the user to execute the
+generated script themselves. The user's terminal, not the AI session, must
+own the running server process. This applies even when the request looks
+short ("just run it") or when running in the background via Bash seems
+convenient — the lifecycle constraint is absolute.
+
+Stopping or restarting an already-running server: tell the user the exact
+command or file to execute (e.g. "run server-stop.bat" or "pm2 restart
+<project>"). Do NOT spawn the stop/restart command via Bash on behalf of the
+user. Read-only inspection — 'runtime_check_status', reading the PID file,
+calling 'pm2 jlist' — is allowed because it does not mutate the server
+lifecycle.
+
+If the user explicitly insists on a one-off background run despite the
+warning ("I know it will die, just run it for now"), state plainly that the
+process will terminate when this session ends, then comply only as a last
+resort. Default behaviour: refuse Bash-based start and route through the
+runtime_* tools.
+
+LAYER BOUNDARY:
+The codegen and setup tools manage application-layer behavior in payload JSON
+files and generated model code. They do NOT modify database DDL (tables,
+columns, indexes, foreign keys, CHECK constraints, UNIQUE constraints).
+
+When the user uses SQL DDL terminology — NOT NULL, UNIQUE, CHECK, REFERENCES,
+ALTER TABLE, CREATE INDEX, DEFAULT (in DDL context) — do not automatically map
+to payload validation. Clarify which layer the user wants:
+  (a) Application-layer validation in payload (e.g. required, unique, min,
+      maxLength, pattern, enum) — handled by these tools
+  (b) Database-level DDL changes — out of scope; suggest direct SQL or a
+      migration tool
+
+Both layers can co-exist for the same field. They serve different purposes:
+DDL enforces at storage level (rejects with database error); payload validation
+provides structured HTTP 400 responses with custom error messages before the
+request reaches the database. Confirm intent before taking action — don't
+conflate the two layers.
+
+PROJECT FILE TAXONOMY:
+The RESTForge ecosystem uses three categories of declarative definition files.
+When the user mentions these abbreviations (case-insensitive), recognise and
+route them as follows:
+
+- SDF (Schema Definition File): JavaScript factory function (.js) at
+  schema/<table>.js that declares table structure for dbschema-kit. Source
+  for 'schema migrate' (apply DDL to database) and produced by
+  'schema introspect' (reverse-engineer database).
+  Example: <project>/schema/category.js
+
+- RDF (Resource Definition File): JSON file (.json) at
+  payload/<resource>.json that declares a backend REST API endpoint (CRUD +
+  datatables/view/export queries) for the RESTForge generator.
+  Example: <project>/payload/category.json
+
+- UDF (UI Definition File): JSON file (.json) at payload/NN-<name>.json in
+  the frontend project that declares page/component structure for the UI
+  generator.
+  Example: <frontend-project>/payload/01-category.json
+
+Routing for SDF requests:
+- create / init / scaffold -> codegen_dbschema_init
+- validate -> codegen_dbschema_validate
+- list models / show structural summary -> codegen_dbschema_models
+- generate DDL (preview or to file) -> codegen_dbschema_generate_ddl
+- reverse-engineer from database -> codegen_dbschema_introspect
+- apply to database (DESTRUCTIVE) -> codegen_dbschema_migrate
+- lookup syntax / defineModel API spec -> codegen_get_dbschema_catalog
+
+Routing for RDF requests:
+- generate from database table -> codegen_generate_payload
+- validate against current database -> codegen_validate_payload
+- diff against database -> codegen_diff_payload
+- sync (merge changes back to JSON) -> codegen_sync_payload
+- generate endpoint module from RDF -> codegen_create_endpoint
+- lookup field validation spec -> codegen_get_field_validation_catalog
+- lookup query declarative spec -> codegen_get_query_declarative_catalog
+
+UDF authoring and generation belongs to the frontend generator toolchain,
+which is a separate workflow from this MCP server. This server currently
+covers the SDF (database) layer and the RDF (backend API) layer; the UDF
+layer is handled by the frontend project's own generator. When the user
+asks about UDF — e.g. "generate UDF for category", "scaffold UI from
+payload", "buatkan UDF untuk halaman X" — recognise UDF as a valid
+first-class concept in the ecosystem and respond constructively:
+
+  1. Confirm in plain language that you understood the UDF intent (e.g.
+     "you want to generate the frontend UI definition for category").
+  2. Explain helpfully that the UDF generation step lives in the frontend
+     project and is run by its dedicated generator, separate from this
+     server's surface.
+  3. Suggest concrete next steps in the user's frontend project: locate
+     the payload/NN-<name>.json file, run the frontend generator there,
+     and verify the generated output.
+  4. Offer continued assistance for the SDF and RDF layers (which this
+     server DOES cover) — for example, you can still help draft the
+     underlying RDF that the frontend will consume.
+
+Tone guidance: frame UDF support as "this stage lives in another part of
+the workflow" rather than "this is unsupported" or "I cannot help". UDF
+is recognised as a legitimate ecosystem concept; the assistant should
+sound informed and forward-looking, not dismissive. Match the user's
+language.
+
+The three layers serve different purposes and co-exist in the same ecosystem:
+SDF defines database structure, RDF defines backend API behavior on that
+structure, UDF defines the frontend that consumes the API. They MUST NOT be
+conflated — a request about "schema" can mean SDF (database) or RDF (API
+shape) depending on context. When ambiguous, ask the user which layer they
+mean before invoking any tool.
+
+KNOWLEDGE BOUNDARY:
+This MCP server provides structured catalog data for SPECIFIC RESTForge
+features that AI agents commonly need for grounding (currently:
+field-validation, query-declarative). It does NOT provide complete
+documentation coverage for every RESTForge feature.
+
+When the user asks about RESTForge behavior, syntax, or configuration
+that is NOT covered by an available catalog tool:
+  1. Do NOT fabricate property names, syntax, or behavior from training
+     data. RESTForge has its own conventions that may differ from
+     similar frameworks (Express, NestJS, Strapi, Hasura, etc.).
+  2. Do NOT guess based on similar frameworks.
+  3. Either:
+     (a) Acknowledge that the specific information is not available via
+         this MCP server and suggest consulting the canonical docs at
+         https://restforge.dev/docs.
+     (b) Ask the user to clarify if the question can be reframed to
+         match an available catalog tool.
+
+Catalog tools are authoritative for the data they expose. The
+documentationUrl returned by each catalog points to narrative
+documentation which may lag behind the most recent npm release; trust
+the catalog data over the URL for property reference, but use the URL
+for use case examples and decision guides.
+`.trim();
+export async function startServer() {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    }, {
+        instructions: SERVER_INSTRUCTIONS,
+    });
+    registerHealthTools(server, SERVER_VERSION);
+    registerSetupTools(server);
+    registerCodegenTools(server);
+    registerRuntimeTools(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,MAAM,WAAW,GAAG,eAAe,CAAC;AACpC,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoM3B,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,EACD;QACE,YAAY,EAAE,mBAAmB;KAClC,CACF,CAAC;IAEF,mBAAmB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5C,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAE7B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}

package/dist/tools/codegen/create-dashboard.d.ts

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

package/dist/tools/codegen/create-dashboard.js

@@ -0,0 +1,256 @@
+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 registerCodegenCreateDashboard(server) {
+    server.registerTool('codegen_create_dashboard', {
+        title: 'Create Dashboard Module',
+        description: `Generate a multi-widget dashboard endpoint module from a payload spec by wrapping restforge dashboard. URL pattern produced: POST /api/{project}/{name}/dashboard.
+
+Dashboards differ structurally from CRUD endpoints: there is no table, no fieldValidation, no CRUD actions. The payload declares a 'widgets' array — each widget owns SQL aggregation queries that are embedded into the generated module file and executed in parallel at request time, returning a JSON envelope keyed by widget id.
+
+This tool is DESTRUCTIVE: it spawns the CLI which writes / overwrites files in 'src/modules/<project>.js' and 'src/modules/<project>/<name>.js', plus 'metadata/<project>/<name>.json' and updates '.restforge/projects.json'. Single-call semantics: the tool always executes; there is no preview mode. Internally the tool always passes '--force=true' to the CLI to bypass the CLI's interactive y/N readline prompt (which would deadlock in a no-TTY subprocess).
+
+Safety net: when the CLI overwrites an existing dashboard module, it FIRST renames the previous version to '<name>.archive.NNN' (NNN is a sequential generation number starting at 001) inside the same folder. Rollback by restoring the most recent archive is always possible.
+
+AI responsibility — IMPORTANT: because this tool always executes and may overwrite generated files, you MUST confirm intent with the user in plain language BEFORE invoking the tool. You do NOT need to detect file conflicts programmatically — the CLI handles that and the archive mechanism keeps the previous version safe. Just confirm intent. Examples of good confirmation phrasing in user-facing chat:
+- "Saya akan generate dashboard <name> di project <project>. Kalau modul lama sudah ada, versi sebelumnya akan disimpan sebagai '.archive.NNN'. Lanjut?"
+- "I will generate <name> under project <project>. Existing files will be archived as .archive.NNN before being overwritten. Proceed?"
+
+USE WHEN:
+- The user asks to generate, create, or scaffold a dashboard endpoint, multi-widget aggregator, or analytics endpoint (e.g. "buatkan dashboard X di project Y", "generate dashboard sales", "scaffold dashboard inbound dengan payload Z")
+- The user mentions "dashboard", "widget aggregator", "multi-widget", "POST .../dashboard", or terms like "donut breakdown", "metric card", "sparkline" in the context of generating an endpoint
+- The user has authored a payload file with a 'widgets' array (not a CRUD 'tableName' shape) and wants to materialise it as a runnable endpoint
+- Pertanyaan dalam bentuk: "buatkan dashboard X di project Y", "generate dashboard sales", "scaffold dashboard inbound dengan payload Z"
+- The user mentions the URL pattern POST /api/<project>/<name>/dashboard and wants to register it as runnable code
+- The user explicitly references dashboard concepts: scalar collapse rules, widget id, query versus queries, params contract, file:query/*.sql references inside widgets
+- After 'codegen_validate_payload' confirmed a dashboard-shape payload — this is the natural follow-up that turns it into runnable code
+- The user asks to regenerate an existing dashboard after the payload changed (overwrite + archive flow handled by the CLI)
+
+DO NOT USE FOR:
+- Generating a CRUD endpoint (payload has 'tableName', 'fieldName', 'action') -> use 'codegen_create_endpoint'
+- Generating the payload JSON itself from a database table -> use 'codegen_generate_payload' (note: codegen_generate_payload targets CRUD payloads — dashboard payloads are typically authored manually)
+- Validating a payload before generation -> use 'codegen_validate_payload'
+- Inspecting per-column differences between payload and database -> use 'codegen_diff_payload'
+- Syncing payload changes back into existing payload files after schema drift -> use 'codegen_sync_payload'
+- Looking up the field validation catalog (dashboards do not have field validation) -> use 'codegen_get_field_validation_catalog' only if discussing CRUD payload fields
+- Looking up the query declarative catalog (dashboards have their own query structure with widgets[].query and widgets[].queries) -> use 'codegen_get_query_declarative_catalog' only if discussing CRUD payload queries
+- Generating a processor (Kafka consumer, etc.) — out of scope; the CLI has separate 'processor' subcommand not covered by this MCP server yet
+- Deleting a dashboard or project — out of scope; the user must run 'npx restforge drop' manually
+- Changing widget visual presentation (widgetType, layout, color, title, subtitle) — those are frontend concerns and forbidden in the dashboard payload (separation of concerns); they belong in the frontend code, not in this generator
+
+Cross-reference: this tool is sibling of 'codegen_create_endpoint'. Both generate runnable code from payload JSON, but they consume different payload shapes (CRUD vs dashboard) and produce different artefacts (full module + model vs single dashboard module with embedded SQL).
+
+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 payload must follow the dashboard schema: a 'widgets' array (NOT a CRUD payload with 'tableName'). The CLI's DashboardValidator rejects payloads that mix shapes, declare forbidden frontend fields (widgetType, layout, title, subtitle, color), have widgets without 'id', have duplicate widget ids, declare both 'query' AND 'queries' in the same widget, declare neither, or use placeholders not declared in 'params'.
+- The dashboard name MUST start with 'dash-' prefix (e.g. dash-sales, dash-inbound). The prefix is required by the CLI and becomes part of the URL segment.
+
+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. "the dashboard generator", "validate the payload first", "draft the payload first").
+- Speak in plain language. Summarise the result; do not paste raw CLI output unless the user explicitly asks.
+- This tool is destructive: it can overwrite an existing dashboard module file. BEFORE invoking this tool, ALWAYS confirm with the user in plain language. Example: "Saya akan generate dashboard <name> di project <project>. Kalau modul lama sudah ada, akan ditimpa (versi sebelumnya disimpan sebagai .archive.NNN). Lanjut?". Do not detect conflicts programmatically; the CLI handles that and creates the archive.
+- After the tool runs, summarise the result. Surface the resulting endpoint URL (POST /api/<project>/<name>/dashboard) so the user knows where to call it. Read the CLI output and identify any archive activity using the '.archive.NNN' filesystem convention; surface to the user when archives exist.
+- If the user is confused about the difference between a dashboard and a CRUD endpoint: dashboards aggregate data from multiple SQL queries (widgets) and return a JSON envelope with widget keys; CRUD endpoints expose actions like /datatables, /read, /create, /update, /delete on a single table. Suggest the right tool based on what the user is actually building.
+- 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. Letters/numbers/dash/underscore, max 50 chars, cannot start or end with dash or underscore. Auto-lowercased by the CLI. Reserved names rejected by the CLI: src, lib, node_modules, config, utils, models, controllers, middleware, routes.'),
+            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. The prefix is required by the CLI and becomes part of the URL segment (POST /api/{project}/{name}/dashboard). The full name is the URL slug, e.g. dash-sales, dash-inbound. 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 for the generated code. Default postgres.'),
+            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: 'Create Dashboard Module',
+            readOnlyHint: false, // tool spawns CLI that writes module/metadata files and updates the registry
+            destructiveHint: true, // can overwrite an existing dashboard module file (CLI archives it as .archive.NNN first)
+            idempotentHint: false, // re-running creates new archive files
+        },
+    }, 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}
+Requested database: ${dbType}
+
+For the assistant:
+- The dashboard generator can only run once the RESTForge package is installed locally.
+- Suggest installing the package first, then retry generating the dashboard.
+- 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 database: ${dbType}
+
+For the assistant:
+- The dashboard generator 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. --force=true is hardcoded: it bypasses the interactive readline
+        // prompt that would otherwise deadlock the subprocess. Conflict detection and archive
+        // creation are delegated to the CLI (single source of truth — see refactor 8C).
+        const cliArgs = [
+            'restforge',
+            'dashboard',
+            'create',
+            `--project=${project}`,
+            `--name=${name}`,
+            `--payload=${payload}`,
+            `--database=${dbType}`,
+            '--force=true',
+        ];
+        if (skipSqlValidation !== undefined)
+            cliArgs.push(`--skip-sql-validation=${skipSqlValidation}`);
+        const result = await execProcess('npx', cliArgs, {
+            cwd: projectCwd,
+            timeout: 60_000,
+            env: { NODE_ENV: 'production' }, // suppress legacy banner output
+            stripFinalNewline: true,
+        });
+        // Branch C: CLI failure — real error per §3.4; structured per §3.5.
+        if (!result.success) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to create the dashboard module.
+
+Project path: ${projectCwd}
+Project: ${project}
+Dashboard: ${name}
+Payload: payload/${payload}.json
+Database: ${dbType}
+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 creating the dashboard module did not complete successfully.
+- Summarise the most likely cause from the CLI output in plain language. Common causes:
+  * Dashboard name did not start with 'dash-' prefix — suggest renaming (e.g. 'sales' becomes 'dash-sales').
+  * Payload uses CRUD shape (has 'tableName') instead of dashboard shape (has 'widgets') — suggest reviewing the payload structure or pointing to dashboard documentation.
+  * Payload contains forbidden frontend fields (widgetType, layout, title, subtitle, color) — those are frontend concerns and must be removed.
+  * Widget without 'id', duplicate widget id, or widget that declares both 'query' AND 'queries' (or neither) — suggest reviewing the widgets array.
+  * Widget SQL uses an undeclared placeholder (e.g. ':year' but 'year' missing from 'params') — suggest declaring the missing param or removing the placeholder.
+  * Database mismatch with the existing project registry entry — the CLI refuses to switch the database. Suggest sticking with the originally registered database.
+  * Reserved project name rejected by the validator — suggest a different project name.
+- Do not paste the raw stdout/stderr unless the user explicitly asks. Do not mention internal tool names.
+- Offer to retry once the underlying issue is resolved.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Branch B: CLI success — one-line summary + labeled facts + fenced output per §3.5.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Dashboard module created successfully.
+
+Project path: ${projectCwd}
+Project: ${project}
+Dashboard: ${name}
+Payload: payload/${payload}.json
+Database: ${dbType}
+Endpoint: POST /api/${project}/${name}/dashboard
+
+Generated artefacts (commonly produced by the CLI):
+- src/modules/${project}.js (main module — created or refreshed)
+- src/modules/${project}/${name}.js (dashboard handler with embedded SQL)
+- metadata/${project}/${name}.json (dashboard metadata)
+- .restforge/projects.json (registry update)
+
+--- CLI output ---
+${result.stdout}
+--- end CLI output ---
+
+For the assistant:
+- Confirm to the user in plain language that the dashboard endpoint was generated. Mention the project, dashboard name, and the resulting URL: POST /api/${project}/${name}/dashboard.
+- Do not paste the entire CLI output unless the user explicitly asks; summarise instead.
+- Read the CLI output to identify any archive activity (the CLI uses the '.archive.NNN' naming convention in the filesystem and reports archive activity in its output, but the exact phrasing may evolve). When archives are created, tell the user that the previous version of the dashboard module is preserved in case rollback is needed.
+- Suggest natural follow-up actions appropriate to context: review the generated module, run the project to test the new dashboard endpoint, draft a frontend caller, etc. Do not mention internal tool names.
+- Match the user's language.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=create-dashboard.js.map

package/dist/tools/codegen/create-dashboard.js.map

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

package/dist/tools/codegen/create-endpoint.d.ts

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