@restforgejs/mcp-server 1.2.0

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

@@ -0,0 +1,153 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+export function registerCodegenDbschemaValidate(server) {
+    server.registerTool('codegen_dbschema_validate', {
+        title: 'Validate dbschema-kit Files',
+        description: `Validate dbschema-kit schema definition files (single-model + cross-model) by wrapping restforge schema validate. Single-model checks: defineModel structure, field types, length, nullable, primary key, default value compatibility. Cross-model checks: foreign key target table existence, referenced column existence, primary key requirement for belongsTo relations.
+
+USE WHEN:
+- The user asks to validate schema files or check defineModel correctness
+- Pertanyaan dalam bentuk: "validasi schema saya", "check apakah schema valid", "verify dbschema files", "cek schema definition"
+- After authoring or editing schema files (via Write/Edit tools) — to confirm correctness before downstream actions
+- Before invoking 'codegen_dbschema_generate_ddl' or 'codegen_dbschema_migrate' — to catch errors early
+- The user reports an unclear error message from another dbschema action and wants a focused validation check
+- The user asks about FK target validity ("does my FK reference work", "is the relation correct")
+- The user wants a sanity check after introspecting from a live database (after 'codegen_dbschema_introspect')
+
+DO NOT USE FOR:
+- Validating CRUD payload files -> use 'codegen_validate_payload'
+- Validating dashboard payload -> use 'codegen_validate_dashboard_payload'
+- Validating SQL syntax -> use 'codegen_validate_sql'
+- Looking up valid syntax -> use 'codegen_get_dbschema_catalog'
+- Generating or applying DDL -> use 'codegen_dbschema_generate_ddl' / 'codegen_dbschema_migrate'
+
+This tool runs: npx restforge schema validate [<path>] in the given cwd.
+The CLI loads each file in the path (file or folder), runs single-model checks first, then cross-model checks, and reports per-file status.
+
+Preconditions:
+- The project must have @restforgejs/platform installed in node_modules.
+- The schema path (default './schema') must exist. If the CLI fails because the folder is missing, the failure response surfaces 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 schema files", "look up the schema catalog", "generate the DDL").
+- Speak in plain language. Summarise the result; do not paste the raw CLI output unless the user explicitly asks.
+- Validation covers two layers: single-model (struct, types, constraints) and cross-model (FK target tables and columns). A model can be single-valid but fail cross-model if its FK target does not exist.
+- The path defaults to './schema'. If the user organizes files differently (e.g. 'db/models'), confirm the path before invoking.
+- 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)'),
+            path: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Path to schema file or folder relative to cwd. When omitted, the CLI uses its default (./schema).'),
+        },
+        annotations: {
+            title: 'Validate dbschema-kit Files',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ cwd, path }) => {
+        const projectCwd = resolve(cwd);
+        // Precondition check: @restforgejs/platform must be present in node_modules. 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 schema path: ${path ?? 'default (./schema)'}
+
+For the assistant:
+- The user needs to install the RESTForge package before schema files can be validated.
+- Suggest installing the package first, then retry validating the schema.
+- 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. CLI default './schema' applies otherwise. per §3.5
+        const cliArgs = ['restforge', 'schema', 'validate'];
+        if (path !== undefined)
+            cliArgs.push(path);
+        const result = await execProcess('npx', cliArgs, {
+            cwd: projectCwd,
+            timeout: 30_000,
+            env: { NODE_ENV: 'production' },
+            stripFinalNewline: true,
+        });
+        // Branch C: CLI failure — real error per §3.4 (validation failures land here). per §3.5
+        if (!result.success) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Schema validation failed.
+
+Project path: ${projectCwd}
+Schema path: ${path ?? 'default (./schema)'}
+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 schema validation surfaced one or more issues (or could not run at all).
+- Summarise the most likely cause from the CLI output in plain language. Common causes:
+  * Single-model error — a field has an invalid type, constraint, or shorthand. Suggest reviewing the offending file and consulting the schema catalog for valid syntax.
+  * Cross-model error — a foreign key references a table or column that does not exist in any sibling schema file. Suggest checking the FK target name and that the referenced model is included in the same path.
+  * Schema folder not found — the CLI cannot locate the path. Suggest verifying the folder name (default is './schema').
+  * Unknown command 'schema validate' — the installed RESTForge version may be older than this CLI subcommand; suggest upgrading the package.
+- Read the per-file error report in the CLI output to identify the failing file and field. Help the user fix it by referencing the catalog (do not invent rules from training data).
+- Do not paste the raw stdout/stderr unless the user explicitly asks. Do not mention internal tool names.
+- Offer to retry once the issue is resolved.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Branch B: success — labeled facts + fenced raw output per §3.5.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Schema validation passed.
+
+Project path: ${projectCwd}
+Schema path: ${path ?? 'default (./schema)'}
+
+--- CLI output ---
+${result.stdout}
+--- end CLI output ---
+
+For the assistant:
+- Confirm to the user that all schema files are valid. If the CLI output lists per-file status lines, count them and mention the file count in plain language.
+- The validation covers both single-model (type, length, nullable, primary key, default value) and cross-model (FK target table existence, referenced column existence). All layers passed.
+- Suggest the next step depending on user intent: list models for an overview, generate DDL for review, or apply via migrate.
+- Do not paste the raw CLI output unless the user explicitly asks.
+- Match the user's language.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=dbschema-validate.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dbschema-validate.js","sourceRoot":"","sources":["../../../src/tools/codegen/dbschema-validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,UAAU,+BAA+B,CAAC,MAAiB;IAC/D,MAAM,CAAC,YAAY,CACjB,2BAA2B,EAC3B;QACE,KAAK,EAAE,6BAA6B;QACpC,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uGA+BoF;QACjG,WAAW,EAAE;YACX,GAAG,EAAE,CAAC;iBACH,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,CAAC,uFAAuF,CAAC;YACpG,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,EAAE;iBACV,QAAQ,CAAC,mGAAmG,CAAC;SACjH;QACD,WAAW,EAAE;YACX,KAAK,EAAE,6BAA6B;YACpC,YAAY,EAAE,IAAI;YAClB,cAAc,EAAE,IAAI;SACrB;KACF,EACD,KAAK,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE;QACtB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAEhC,sFAAsF;QACtF,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,CAAC,CAAC,CAAC;QAC7E,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;;gBAEJ,UAAU;;yBAED,IAAI,IAAI,oBAAoB;;;;;gKAK2G;qBACnJ;iBACF;gBACD,OAAO,EAAE,KAAK,EAAE,WAAW;aAC5B,CAAC;QACJ,CAAC;QAED,mGAAmG;QACnG,MAAM,OAAO,GAAG,CAAC,WAAW,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;QACpD,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE3C,MAAM,MAAM,GAAG,MAAM,WAAW,CAC9B,KAAK,EACL,OAAO,EACP;YACE,GAAG,EAAE,UAAU;YACf,OAAO,EAAE,MAAM;YACf,GAAG,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE;YAC/B,iBAAiB,EAAE,IAAI;SACxB,CACF,CAAC;QAEF,wFAAwF;QACxF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;;gBAEJ,UAAU;eACX,IAAI,IAAI,oBAAoB;WAChC,MAAM,CAAC,OAAO;aACZ,MAAM,CAAC,QAAQ;;;;EAI1B,MAAM,CAAC,MAAM;;;EAGb,MAAM,CAAC,MAAM;;;;;;;;;;;;6CAY8B;qBAChC;iBACF;gBACD,OAAO,EAAE,IAAI,EAAE,WAAW;aAC3B,CAAC;QACJ,CAAC;QAED,kEAAkE;QAClE,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;;gBAEF,UAAU;eACX,IAAI,IAAI,oBAAoB;;;EAGzC,MAAM,CAAC,MAAM;;;;;;;;6BAQc;iBAClB;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/codegen/describe-table.d.ts

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

package/dist/tools/codegen/describe-table.js

@@ -0,0 +1,259 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+export function registerCodegenDescribeTable(server) {
+    server.registerTool('codegen_describe_table', {
+        title: 'Describe Database Table',
+        description: `Describe a single database table — columns (with dialect-specific types), primary key, foreign keys, and indexes — by wrapping restforge schema describe. Live introspection — the CLI connects to the database and queries the catalog.
+
+USE WHEN:
+- The user asks about the columns, primary key, foreign keys, or indexes of a specific table
+- Pertanyaan dalam bentuk seperti "kolom apa saja di tabel X", "describe tabel sales_order", "show schema for users table", "tabel X punya FK ke mana", "ada index apa di tabel Y"
+- Before authoring a SQL JOIN — to discover the foreign key path between two tables and write the JOIN clause correctly
+- Before authoring a dashboard widget query — to confirm column names and types before composing the SELECT
+- The user wants to verify whether a specific column exists in a table
+- The user asks "what type is column X in table Y" — column type is dialect-specific so live introspection is more reliable than guessing
+- Before invoking 'codegen_create_dashboard' (with widget SQL) — to ground SQL identifiers in the live schema
+- After 'codegen_list_tables' returned a candidate name and the user wants the per-column details
+
+DO NOT USE FOR:
+- Listing all tables in the database -> use 'codegen_list_tables'
+- Querying the actual row data inside a table -> out of scope; this tool returns metadata (columns, PK, FK, indexes) only, not row content
+- Validating a payload spec file against the database schema (file-level diff) -> use 'codegen_validate_payload' or 'codegen_diff_payload'
+- Modifying the schema (ALTER TABLE) -> out of scope
+- Inspecting the SQL definition behind a database view -> out of scope; only column-level info is returned for views
+- Cross-database introspection (multiple databases at once) -> out of scope; a single config = a single connection
+
+Cross-reference: this tool is the sibling of 'codegen_list_tables'. Use list-tables first to discover candidate names, then describe-table for the per-column details.
+
+This tool runs: npx restforge schema describe --config=<config> --table=<table> [--include-foreign-keys=<bool>] [--include-indexes=<bool>] in the given cwd.
+The CLI connects to the database described in the config file, queries the catalog, and emits a JSON envelope with the table metadata.
+
+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.
+- The named table must exist in the database; otherwise the CLI fails with a "Table 'X' not found" error.
+
+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. "describe the table", "list the database tables", "install the package").
+- Speak in plain language. Summarise the result; do not paste the raw JSON unless the user explicitly asks.
+- This is a live introspection: the tool actively queries the database catalog. The result reflects the schema state at query time.
+- Column types are dialect-specific (Postgres: 'character varying(N)', MySQL: 'varchar(N)', Oracle: 'VARCHAR2(N)'). Use the type as-is when the user asks about column constraints; do not normalise.
+- Foreign key 'references' field is the JOIN target — when the user asks "how do I join A and B", look at FK paths in both directions to compose the JOIN clause.
+- When a precondition is not met (e.g. the package is not installed), 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 the project, used by the CLI to connect to the database'),
+            table: z
+                .string()
+                .min(1)
+                .describe('Table name to describe. Format: <schema>.<table> or just <table> (the CLI resolves the schema). Example: supplier, public.supplier, core.users.'),
+            includeForeignKeys: z
+                .boolean()
+                .optional()
+                .describe('Default true (CLI default). When false, omit the foreignKeys field from output.'),
+            includeIndexes: z
+                .boolean()
+                .optional()
+                .describe('Default true (CLI default). When false, omit the indexes field from output.'),
+        },
+        annotations: {
+            title: 'Describe Database Table',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ cwd, config, table, includeForeignKeys, includeIndexes }) => {
+        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}
+Requested config: ${config}
+Requested includeForeignKeys: ${includeForeignKeys ?? 'default (true)'}
+Requested includeIndexes: ${includeIndexes ?? 'default (true)'}
+
+For the assistant:
+- The user needs to install the RESTForge package before the table description can be retrieved.
+- Suggest installing the package first, then retry describing the table.
+- 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. CLI defaults remain in
+        // effect when the user does not specify them. per §3.5
+        const cliArgs = [
+            'restforge',
+            'schema',
+            'describe',
+            `--config=${config}`,
+            `--table=${table}`,
+        ];
+        if (includeForeignKeys !== undefined)
+            cliArgs.push(`--include-foreign-keys=${includeForeignKeys}`);
+        if (includeIndexes !== undefined)
+            cliArgs.push(`--include-indexes=${includeIndexes}`);
+        const result = await execProcess('npx', cliArgs, {
+            cwd: projectCwd,
+            timeout: 30_000,
+            env: { NODE_ENV: 'production' },
+            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 describe the database table.
+
+Project path: ${projectCwd}
+Config: ${config}
+Table: ${table}
+includeForeignKeys: ${includeForeignKeys ?? 'default (true)'}
+includeIndexes: ${includeIndexes ?? 'default (true)'}
+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 describing the table did not complete successfully.
+- Summarise the most likely cause from the CLI output in plain language. Common causes:
+  * Table not found — the most common error. Suggest that the table name might be misspelled or that the user is looking in a different schema; offer to list the available tables first to find candidate names.
+  * Config file not found — suggest verifying the path and that the file exists in the project.
+  * Database connection failed — suggest verifying the credentials, that the host is reachable, and that the port is open.
+  * Unknown command 'schema describe' — the installed RESTForge version may be older than this CLI subcommand; suggest upgrading the package.
+- 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 D: JSON parse failure — real error per §3.4 (CLI succeeded but produced invalid output).
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to parse the table description as JSON.
+
+Project path: ${projectCwd}
+Config: ${config}
+Table: ${table}
+Reason: ${msg}
+
+--- Raw stdout ---
+${result.stdout}
+--- end Raw stdout ---
+
+For the assistant:
+- The CLI returned output that is not valid JSON.
+- Summarise this to the user in plain language; do not paste the raw stdout unless they explicitly ask.
+- Suggest checking that the installed RESTForge package version is compatible. Do not mention internal tool names.`,
+                    },
+                ],
+                isError: true, // per §3.4
+            };
+        }
+        // Defensive labeled facts: if the JSON shape changes upstream, fall back to 'unknown' / 'n/a'
+        // rather than crashing. Mirror the catalog tools pattern.
+        const root = (parsed ?? {});
+        const tableObj = (root.table ?? {});
+        const tableSchema = typeof tableObj.schema === 'string' ? tableObj.schema : 'unknown';
+        const tableName = typeof tableObj.name === 'string' ? tableObj.name : 'unknown';
+        const tableType = typeof tableObj.type === 'string' ? tableObj.type : 'unknown';
+        const databaseType = typeof root.database === 'string' ? root.database : 'unknown';
+        const columns = Array.isArray(root.columns) ? root.columns : [];
+        const columnsCount = columns.length;
+        const pk = root.primaryKey;
+        let primaryKeyLabel;
+        if (pk && typeof pk === 'object' && Array.isArray(pk.columns)) {
+            const pkCols = pk.columns;
+            primaryKeyLabel = `[${pkCols.map((c) => JSON.stringify(c)).join(', ')}]`;
+        }
+        else if (pk === null) {
+            primaryKeyLabel = 'none';
+        }
+        else {
+            primaryKeyLabel = 'unknown';
+        }
+        const foreignKeysCount = includeForeignKeys === false
+            ? 'n/a (excluded)'
+            : Array.isArray(root.foreignKeys)
+                ? root.foreignKeys.length
+                : 'unknown';
+        const indexesCount = includeIndexes === false
+            ? 'n/a (excluded)'
+            : Array.isArray(root.indexes)
+                ? root.indexes.length
+                : 'unknown';
+        const prettyJson = JSON.stringify(parsed, null, 2);
+        // Branch B: success — one-line summary + labeled facts + fenced JSON output per §3.5.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Table description retrieved successfully.
+
+Project path: ${projectCwd}
+Config: ${config}
+Database: ${databaseType}
+Table: ${tableSchema}.${tableName} (${tableType})
+columnsCount: ${columnsCount}
+primaryKey: ${primaryKeyLabel}
+foreignKeysCount: ${foreignKeysCount}
+indexesCount: ${indexesCount}
+
+--- Table Description (JSON) ---
+${prettyJson}
+--- end Table Description (JSON) ---
+
+For the assistant:
+- Confirm to the user that the table description was retrieved. Mention the table name and column count in plain language.
+- When the user asked to compose a SQL query (e.g. for a dashboard widget), use this metadata as ground truth for: (1) column names and types — match SQL identifiers exactly; (2) primary key — for JOIN target identity; (3) foreign keys — for cross-table JOIN paths; (4) indexes — informational, helps anticipate query performance.
+- Column types are dialect-specific (e.g. 'character varying(50)' in Postgres, 'varchar(50)' in MySQL, 'VARCHAR2(50)' in Oracle). Use the type as-is when the user asks about column constraints; do not normalise.
+- Foreign keys describe the schema-level relationship (which column references which target). Use the 'references' field to write JOIN clauses correctly.
+- This is a read-only operation: it queries the database catalog without modifying anything.
+- Do not paste the full JSON unless the user asks. Summarise — for a wide table (more than 10 columns), list only the columns relevant to the user's task.
+- For listing all tables in the database, suggest the table-list action. Do not mention internal tool names.
+- Match the user's language.`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=describe-table.js.map

package/dist/tools/codegen/describe-table.js.map

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

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

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

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

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+import { access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { execProcess } from '../../lib/exec.js';
+export function registerCodegenDiffPayload(server) {
+    server.registerTool('codegen_diff_payload', {
+        title: 'Diff Payload',
+        description: `Show the column-level differences between existing payload spec files and the current database schema, by running restforge payload --diff.
+
+USE WHEN:
+- The user asks to see the detailed differences between a payload file and the current database schema (column-level)
+- The user asks things like "tunjukkan diff payload", "apa yang berubah di table X", "kolom apa saja yang baru", "show schema diff", "what columns changed"
+- After 'codegen_validate_payload' reported DRIFT and the user wants to know what specifically changed
+- Pre-flight inspection before deciding whether to run sync
+- Often called after 'codegen_validate_payload' once a DRIFT status is reported, to drill into the column-level differences for the affected file.
+
+DO NOT USE FOR:
+- Quick overall status (OK / DRIFT / ERROR per file) -> use 'codegen_validate_payload'
+- Generating a payload from scratch for a table that has no payload yet -> use 'codegen_generate_payload'
+- Applying the changes to payload files -> use 'codegen_sync_payload'
+
+This tool runs: npx restforge payload --diff --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 prints a per-column diff (added, removed, or type-changed columns) without
+modifying any file. The CLI typically uses '[+]' for added columns, '[-]' for removed columns,
+and '[~]' for type-changed columns.
+
+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. "see the column-level differences", "do a quick overall validation", "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 inspect (e.g. supplier or core.supplier). When omitted, all payload files in the output directory are diffed.'),
+            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: 'Diff 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 column-level differences can be computed against the database schema.
+- Use the appropriate package-installation tool to do this, then retry computing the differences.
+- 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', 'diff', `--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 diff 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 computing the column-level differences 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 column-level diff with [+], [-], [~] markers; the model
+        // should translate those markers into plain language when talking to the user.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Payload diff 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:
+- Translate the diff markers into plain language for the user: '[+]' means a new column in the database that is not yet in the payload file, '[-]' means a column that exists in the payload file but has been removed from the database, and '[~]' means a column whose data type has changed.
+- Group the differences per file or per table when multiple are reported, and name the affected columns explicitly so the user can decide what to do.
+- If there are no differences, confirm in plain language that the payload files match the database.
+- If the user wants to apply these 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=diff-payload.js.map

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

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

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

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