@dforge-core/dforge-mcp 0.2.25 → 0.2.26

package/CHANGELOG.md

@@ -4,6 +4,40 @@ All notable changes to `@dforge-core/dforge-mcp`. This project uses semver-ish
 `0.1.0-rc.N` pre-release tags; the published version is set at publish time via
 the release workflow, so committed `package.json` versions are placeholders.
 
+## 0.2.26
+
+`logic/stored_procedures.json` is now something this server can describe. It had no
+schema, no reference and no resource — yet a `datasetType: "S"` dataset is unusable
+without it, because that file is what registers the function as the `spCd` a dataset
+binds and the `sec_object` an `sp:` right is granted on. An author who reached the
+install error demanding the file had nothing to read and guessed at its shape
+(dForge-core#1191). `dforge://schema/stored-procedures` serves it now, and
+`dforge://reference/reports` gained the declaration block, the `functionName` rule —
+it names the FUNCTION, not the `logic/reports/*.sql` script that creates it, and
+nothing in the file ever names a script — and the missing-declaration mistake.
+
+**`reports.schema.json` was actively wrong about the field an SP dataset binds
+through.** It declared `procedureName` under `additionalProperties: false`, so the
+schema this server serves *rejected* the real `spCd` and accepted a name the platform
+has never read. Re-vendored from `@dforge-core/metadata` 0.0.29, which fixes it.
+
+The same bump corrects `entity.schema.json`, which had drifted two releases behind:
+a column's `pattern` / `patternFlags` (format rules are metadata now, enforced in the
+browser and again on `data.insert` / `data.update`) and `lockedFields` on an
+accumulation register.
+
+The references also stop contradicting themselves on parameter codes. A report
+parameter must be spelled exactly as the procedure declares its `paramCd` —
+`report.run` resolves each argument by that code alone and neither adds nor strips a
+prefix — but the worked example named report parameters `customer_id` against a
+procedure declaring `p_customer_id`, which binds NULL and makes the filter silently
+disappear. Aligned, with the rule stated beside it.
+
+**Still missing:** no tool here writes `logic/stored_procedures.json`, and
+`dforge_report_add` takes its `datasets` map unvalidated — so an agent building an SP
+report still emits the `.sql` file and the dataset and no declaration, which is the
+shape that produced dForge-core#1191 in the first place.
+
 ## 0.2.25
 
 `sp:` is now a legal role-rights key. It always was, at install — `SecurityRegistrar`

package/dist/server.js

@@ -31002,7 +31002,7 @@ var import_node_crypto = require("crypto");
 var fs2 = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.19/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.20/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -31283,7 +31283,7 @@ function buildZedTasks() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.27/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.29/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -34449,7 +34449,7 @@ function entityDelete(args) {
 // src/tools/action-add.ts
 var path9 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.27/node_modules/@dforge-core/metadata/dist/dsl/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.29/node_modules/@dforge-core/metadata/dist/dsl/index.js
 var PUNCT3 = ["===", "!=="];
 var PUNCT2 = [
   "==",
@@ -38043,6 +38043,11 @@ var resources = [
     "Reports JSON schema",
     "JSON Schema for ui/reports.json \u2014 map of report code \u2192 { description, layout.panels[], datasets, parameters? }. Datasets and panel queries reuse the filter shape from data_views."
   ),
+  schema(
+    "stored-procedures",
+    "Stored procedures JSON schema",
+    "JSON Schema for logic/stored_procedures.json \u2014 map of stored-procedure code \u2192 { functionName, schemaName?, params?, columns? }. Required for any report dataset with datasetType 'S': the .sql file under logic/reports/ creates the function, this file registers it as the spCd a dataset binds and the sec_object an sp: right is granted on. functionName names the FUNCTION, never the script."
+  ),
   {
     uri: "dforge://docs/conventions",
     name: "dForge module conventions",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.25",
+	"version": "0.2.26",
 	"description": "MCP server for dForge module authoring. Exposes 34 scaffold/patch/validate/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
 	"license": "MIT",
 	"homepage": "https://github.com/iash44/dForge-core",
@@ -35,8 +35,8 @@
 		"install-skills": "node scripts/install-skills.mjs"
 	},
 	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.19",
-		"@dforge-core/metadata": "^0.0.27",
+		"@dforge-core/dforge-cli": "^0.2.20",
+		"@dforge-core/metadata": "^0.0.29",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"zod": "^4.4.3"
 	},

package/resources/schemas/entity.schema.json

@@ -363,6 +363,15 @@
 						},
 						"serverDefault": {
 							"$ref": "#/$defs/serverDefault"
+						},
+						"pattern": {
+							"type": "string",
+							"description": "Format rule for this column, as an ECMAScript regex source. Overrides the field type's own pattern (field_type.def_params.pattern, which is what makes email/phone/url reject a malformed value). Enforced in the browser and again on data.insert / data.update, so keep to constructs both engines read alike: [0-9] and \\d are the same there, \\s is normalized to JavaScript's set, and a pattern that will not compile is skipped by both rather than enforced by one."
+						},
+						"patternFlags": {
+							"type": "string",
+							"description": "Flags for 'pattern', as a JavaScript regex literal would carry them; 'i' and 'm' are the two honoured, each at most once — the RegExp constructor rejects a repeated flag, and a rule the browser cannot compile is skipped there and would then be enforced by the API alone. JavaScript has no inline (?i), so case-insensitivity has to be stated here.",
+							"pattern": "^(i|m|im|mi)?$"
 						}
 					}
 				},
@@ -569,7 +578,7 @@
 		"accumulationConfig": {
 			"type": "object",
 			"description": "Configuration for simple accumulation (document without lines, e.g. receipt → stock).",
-			"required": ["balanceEntity", "dimensions", "resources"],
+			"required": ["balanceEntity", "dimensions", "resources", "lockedFields"],
 			"properties": {
 				"balanceEntity": { "type": "string", "description": "Balance entity code (e.g. 'stock')" },
 				"dimensions": {
@@ -596,7 +605,6 @@
 				"allowNegative": { "type": "boolean", "default": true },
 				"lockedFields": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Document fields locked when posted. Required; [\"*\"] freezes the whole row." }
 			},
-			"required": ["lockedFields"],
 			"additionalProperties": false
 		},
 		"signConfig": {

package/resources/schemas/reports.schema.json

@@ -249,9 +249,9 @@
 					"$ref": "#/$defs/query",
 					"description": "Used when datasetType is 'Q'"
 				},
-				"procedureName": {
+				"spCd": {
 					"type": "string",
-					"description": "Used when datasetType is 'S'"
+					"description": "Used when datasetType is 'S': the stored-procedure code, as `logic/stored_procedures.json` keys it — NOT the PostgreSQL function name and never schema-qualified. `module.spCd` binds a dependency's procedure. Resolved to `report_ds.sp_id` at install. A role granting `report:<code>` must also grant `sp:<spCd>`, which no admin UI can add afterwards."
 				},
 				"columnsDef": {
 					"type": "object",

package/resources/schemas/stored-procedures.schema.json

@@ -0,0 +1,125 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "dForge Module Stored Procedures",
+	"description": "Stored-procedure declarations for a dForge module package (logic/stored_procedures.json). Each entry registers one PostgreSQL function as a procedure a report dataset can bind with `datasetType: \"S\"` and `spCd`. The SQL that creates the function ships separately, as a CREATE OR REPLACE FUNCTION script under logic/reports/; this file does not name the script, it names the function the script creates. See docs/business-logic/stored-procedures.md.",
+	"type": "object",
+	"additionalProperties": {
+		"type": "object",
+		"required": ["functionName"],
+		"description": "Keyed by stored-procedure code (sp_cd) — module-internal, referenced from a dataset's `spCd` and a role's `sp:` right. It may not contain a dot: a dot is the module qualifier in both of those key spaces.",
+		"properties": {
+			"description": {
+				"type": "string",
+				"description": "Label for the procedure, shown in the report editor's procedure picker. Defaults to the code."
+			},
+			"schemaName": {
+				"type": "string",
+				"pattern": "^[a-zA-Z_][a-zA-Z0-9_\\-]*$",
+				"description": "PostgreSQL schema holding the function. Defaults to the module's own schema, which is what a module-shipped function normally uses."
+			},
+			"functionName": {
+				"type": "string",
+				"pattern": "^[a-zA-Z_][a-zA-Z0-9_\\-]*$",
+				"description": "The PostgreSQL function's own name, unqualified — `report.run` calls SELECT * FROM \"schemaName\".\"functionName\"(...). Required: it is the one fact this file exists to record, and install fails naming it when absent."
+			},
+			"returnsTable": {
+				"type": "boolean",
+				"default": true,
+				"description": "The function is set-returning (RETURNS TABLE / SETOF). The only shape report.run projects."
+			},
+			"params": {
+				"type": "array",
+				"description": "The call signature, in order: report.run passes exactly one positional argument per entry and NOTHING else — no folder, no user. A function taking p_folder_uid / p_user_id can never be called, and install rejects the arity mismatch. Omit the block for a function taking no arguments.",
+				"items": { "$ref": "#/$defs/param" }
+			},
+			"columns": {
+				"type": "array",
+				"description": "Result columns, stored in dForge.sp_column and used to project the dataset. Omit the block and the registrar derives them from the function's own RETURNS TABLE / OUT column names. Declare it to set labels, widths, a currency/percent control or a refEntityCd link — a declared list is used as written and never merged with the signature. A function returning an unnamed SETOF composite or a bare scalar declares no column names, so it must list them here.",
+				"items": { "$ref": "#/$defs/column" }
+			}
+		},
+		"additionalProperties": false
+	},
+
+	"$defs": {
+		"param": {
+			"type": "object",
+			"required": ["paramCd"],
+			"properties": {
+				"paramCd": {
+					"type": "string",
+					"maxLength": 50,
+					"description": "Parameter code. Conventionally the function's own argument name (p_customer_id), though the call is positional."
+				},
+				"pgType": {
+					"type": "string",
+					"default": "bigint",
+					"description": "PostgreSQL type of the argument — this is what binds the value, and it is carried even when the value is null so an omitted optional argument arrives as a TYPED null. Defaults to `bigint`, so declare it for every argument that is not one. One of: bigint, integer, smallint, numeric, real, double precision, text, boolean, uuid, date, timestamp, timestamptz, time — or any alias PostgreSQL treats as the same type (int8, int4, int, int2, decimal, float8, float4, varchar, character varying, char, bpchar, bool, timestamp without time zone, timestamp with time zone, time without time zone). Case does not matter and a type modifier is ignored, so `numeric(18,2)` may be pasted straight from the signature. jsonb, arrays, enums and citext cannot be bound and are rejected at install. Enforced by SpParamTypes, which is where this list lives — left out of an enum here so the spellings install accepts are not flagged by an editor.",
+					"examples": ["bigint", "text", "date", "numeric(18,2)", "timestamptz", "uuid", "boolean"]
+				},
+				"fieldTypeCd": {
+					"type": "string",
+					"description": "Control the report editor copies into the report param when the procedure is bound there. Optional — derived from pgType when omitted."
+				},
+				"label": {
+					"type": "string",
+					"description": "Parameter label for that same copy."
+				},
+				"required": {
+					"type": "boolean",
+					"default": true,
+					"description": "Whether the parameter must have a value. Give every optional one DEFAULT NULL in the function signature."
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"column": {
+			"type": "object",
+			"required": ["columnCd"],
+			"properties": {
+				"columnCd": {
+					"type": "string",
+					"maxLength": 100,
+					"description": "Result column name as the function returns it. Unique within the procedure."
+				},
+				"label": {
+					"type": "string",
+					"description": "Column header. Defaults to the code."
+				},
+				"fieldTypeCd": {
+					"type": "string",
+					"default": "text",
+					"description": "Control that renders the value (number, currency, date, dropdown, flags, ...)."
+				},
+				"baseDatatypeCd": {
+					"type": "string",
+					"default": "string",
+					"description": "Underlying datatype the value is read as."
+				},
+				"orderNum": {
+					"type": "integer",
+					"description": "Display order. Defaults to declaration order in steps of 10."
+				},
+				"refEntityCd": {
+					"type": "string",
+					"description": "Entity this column links to, making the value clickable. Resolved within this module and its dependencies."
+				},
+				"refColumnCd": {
+					"type": "string",
+					"description": "Column in the result holding the FK value for that link, when it is not this column."
+				},
+				"width": {
+					"type": "integer",
+					"description": "Column width in pixels."
+				},
+				"params": {
+					"type": "object",
+					"description": "Control parameters, the same shape an entity column's `params` takes — `options` for a dropdown or flags, `currency`, `align`, and so on.",
+					"additionalProperties": true
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/skills/dforge-mcp-author/references/reports.md

@@ -87,8 +87,8 @@ For SQL the query builder can't express — window functions, CTEs, cross-schema
     "datasetType": "S",
     "spCd": "rpt_ar_aging",
     "params": {
-        "as_of_date": { "fieldTypeCd": "date", "label": "As of Date", "required": true, "default": "=NOW()" },
-        "customer_id": { "fieldTypeCd": "lookup", "label": "Customer", "required": false, "params": { "link": { "entity": "account" } } }
+        "p_as_of_date": { "fieldTypeCd": "date", "label": "As of Date", "required": true, "default": "=NOW()" },
+        "p_customer_id": { "fieldTypeCd": "lookup", "label": "Customer", "required": false, "params": { "link": { "entity": "account" } } }
     },
     "columnsDef": {
         "customer_name": { "label": "Customer", "fieldTypeCd": "text", "baseDatatypeCd": "string", "width": 200 },
@@ -100,7 +100,7 @@ For SQL the query builder can't express — window functions, CTEs, cross-schema
 
 Key differences from entity datasets:
 - `datasetType: "S"`.
-- `spCd` — the stored-procedure code (the function name **without** the schema prefix; resolved to `sp_id` at install). (**Not** `sp` or `procedureName`.)
+- `spCd` — the stored-procedure **code**: the key of an entry in `logic/stored_procedures.json`, never schema-qualified, resolved to `sp_id` at install. By convention it is spelled the same as the function it declares, but it is the code that is matched, not the function name. (**Not** `sp` or `procedureName`.)
 - `columnsDef` — labels, widths and formats for the columns, keyed by column code. Optional
   since the registrar derives a procedure's columns from its `RETURNS TABLE (…)` signature;
   ship it when you want a label or a width rather than the bare column code. It is an
@@ -108,6 +108,12 @@ Key differences from entity datasets:
   A function returning an unnamed `SETOF <composite>` or a bare scalar declares no column
   names, so that one needs an explicit `columns` block in `logic/stored_procedures.json`.
 - Params work exactly as they do for an entity dataset, and `datasetType` makes no difference: declare them at report level (`parameters`) or on the dataset (`params`). Report level wins on a code collision.
+- **The parameter code must match the procedure's declared `paramCd` exactly.** `report.run`
+  resolves each argument by that code alone — no prefix is added or stripped — so a report
+  offering `customer_id` against a procedure declaring `p_customer_id` passes NULL and the
+  filter silently does nothing. Prefix the report parameter too (as above), or drop the
+  prefix from `paramCd`; the SQL argument name is unconstrained either way, the call being
+  positional.
 
 **Multi-result-set SPs** map extra datasets to the same function via `parentDatasetCd` (the dataset that owns the SP call) + `parentRef` (the named refcursor). **Not wired at runtime**: both columns install, but `report.run` executes only datasets holding their own `sp_id`, so a child dataset returns nothing. Give each dataset its own function until that changes.
 
@@ -158,6 +164,35 @@ $$;
   aggregates that are safe for everyone holding the report's grant.
 - Grant **both** `report:<code>` and `sp:<spCd>` — see `references/security.md`.
 
+### The declaration — `logic/stored_procedures.json`
+
+The function existing in the database is not enough: this file is what creates the
+`stored_procedure` row an `spCd` resolves to and the `sec_object` an `sp:` right is
+granted on. Keyed by stored-procedure code, which may not contain a dot.
+
+```json
+{
+    "rpt_ar_aging": {
+        "description": "AR Aging",
+        "functionName": "rpt_ar_aging",
+        "params": [
+            { "paramCd": "p_as_of_date",  "pgType": "date",   "fieldTypeCd": "date",   "label": "As of Date", "required": true },
+            { "paramCd": "p_customer_id", "pgType": "bigint", "fieldTypeCd": "lookup", "label": "Customer",   "required": false }
+        ]
+    }
+}
+```
+
+- **`functionName` is required** — the function's own name, unqualified. It is **not** the
+  path of the `.sql` file: nothing here names a script, because every `logic/reports/*.sql`
+  runs at install regardless. Omitting it fails the package at load, on `pack`/`validate`
+  and every install path alike.
+- **`schemaName`** is optional, defaulting to the module's own schema.
+- **`params`** is the call signature, in order — omit it for a zero-argument function.
+- **`columns`** is optional; without it install derives the result columns from the
+  function's `RETURNS TABLE (…)`.
+- Schema: `stored_procedures.schema.json`.
+
 ## Parameters
 
 Parameters prompt the user before running the report.
@@ -372,6 +407,12 @@ A dependency's report is granted with the qualified form, `"report:fin.ar_aging"
 - Setting the chart kind as `vizType` (`"vizType": "bar"`) — the panel `vizType` is `"chart"`; the kind goes in `config.chartType`.
 - Using `entityCode` / `groupBy` / `aggregations` on a dataset — use `query.entityCd` + `query.columns`, and aggregate in the viz (`agg`, `metrics`).
 - Using `sp` / `procedureName` for an SP dataset — the field is `spCd`.
+- Shipping an SP's `.sql` file and its dataset but no `logic/stored_procedures.json` entry —
+  the function exists, the dataset names something, and nothing connects the two.
+- Writing `file` / `function` in `logic/stored_procedures.json` — the one required field is
+  `functionName`, and it names the function, not the script that creates it.
+- Naming a report parameter `customer_id` for a procedure param declared `p_customer_id` —
+  the lookup is by exact code, so the argument binds NULL and the filter quietly disappears.
 - Assuming an SP dataset must carry `columnsDef` — it is an override over the columns the
   registrar derives from the function signature, not the source of them.
 - Forgetting to grant `E` on the report in at least one role — it becomes invisible.