@dforge-core/dforge-mcp 0.2.24 → 0.2.25

package/CHANGELOG.md

@@ -4,6 +4,33 @@ 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.25
+
+`sp:` is now a legal role-rights key. It always was, at install — `SecurityRegistrar`
+resolves `sp:<cd>` and `sp:<module>.<cd>` against a stored procedure's sec_object, and
+`report.run` enforces `E` on it for every `datasetType: "S"` dataset, on top of the
+report's own right. This server's key validator did not know the prefix, so
+`dforge_role_add` and `dforge_role_right_set` rejected the one grant such a report needs,
+and nothing in the references mentioned it. A module built here with an SP-backed report
+therefore shipped a report that answered `PERMISSION_DENIED` for everyone, unfixably: the
+role-rights admin UI lists entities, actions and reports only, so no tenant admin can add
+an SP grant afterwards (dForge-core#1146).
+
+`report:` and `sp:` also accept the qualified `module.code` form now, which the installer
+has always resolved cross-module. `action:` and `folder:` still do not — the installer
+resolves those within the module, so a dotted one grants nothing.
+
+`references/security.md` gains the two-grant rule; `references/reports.md` loses two
+claims that were never true: that the platform injects `p_folder_uid` / `p_user_id` as an
+SP function's first two params (it passes exactly the declared params and nothing else,
+so such a function is uncallable and the install now says so), and that multi-result-set
+refcursor datasets work (they install and return nothing). Both files also carry the SP param types the
+runtime binds, now that dForge-core binds every scalar one (a `numeric` param used to go
+over as text and fail the call) and rejects the rest at install.
+
+The matching pack-time check lives in dForge-core (`ReportSpRightsValidator`), so
+`dforge_module_pack` picks it up through the CLI it shells out to.
+
 ## 0.2.23
 
 The DSL checker was written twice. This server had one — regexes over

package/dist/server.js

@@ -31633,8 +31633,9 @@ function isReadyToScaffold(moduleDir) {
   return fs.existsSync(v) && fs.readFileSync(v, "utf8").includes("readyToScaffold: true");
 }
 var RIGHTS_ENTITY = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$/;
-var RIGHTS_OBJECT = /^(action|report|folder):[a-z][a-z0-9_]*$/;
-var RIGHTS_OBJECT_DOT = /^(action|report|folder)\.[a-z]/;
+var RIGHTS_OBJECT = /^(action|folder):[a-z][a-z0-9_]*$/;
+var RIGHTS_OBJECT_QUALIFIABLE = /^(report|sp):[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$/;
+var RIGHTS_OBJECT_DOT = /^(action|report|sp|folder)\.[a-z]/;
 function assertValidRightKey(key) {
   if (RIGHTS_OBJECT_DOT.test(key)) {
     const fixed = key.replace(".", ":");
@@ -31642,9 +31643,9 @@ function assertValidRightKey(key) {
       `Rights key '${key}' uses a dot for an action/report/folder \u2014 use a colon: '${fixed}'. (A dot is only for cross-module entities like 'fin.invoice'.)`
     );
   }
-  if (RIGHTS_OBJECT.test(key) || RIGHTS_ENTITY.test(key)) return;
+  if (RIGHTS_OBJECT.test(key) || RIGHTS_OBJECT_QUALIFIABLE.test(key) || RIGHTS_ENTITY.test(key)) return;
   throw new Error(
-    `Invalid rights key '${key}'. Use a same-module entity ('product'), a cross-module entity ('fin.invoice'), or a colon-prefixed object ('action:approve', 'report:summary', 'folder:east').`
+    `Invalid rights key '${key}'. Use a same-module entity ('product'), a cross-module entity ('fin.invoice'), or a colon-prefixed object ('action:approve', 'report:summary', 'sp:rpt_totals', 'folder:east'). Only report: and sp: may be qualified ('report:fin.ar_aging').`
   );
 }
 function assertValidRightValue(key, value, allowEmpty) {
@@ -31659,13 +31660,13 @@ function assertValidRightValue(key, value, allowEmpty) {
       `Invalid rights '${value}' on '${key}'. Use S/I/U/D/C for entities, or 'E' for actions/reports/folders.`
     );
   }
-  const isObject2 = /^(action|report|folder):/.test(key);
+  const isObject2 = /^(action|report|sp|folder):/.test(key);
   if (isObject2 && value !== "E") {
     throw new Error(`Object '${key}' takes 'E' (Execute), got '${value}'.`);
   }
   if (!isObject2 && value.includes("E")) {
     throw new Error(
-      `'${key}' is granted 'E' but has no action:/report:/folder: prefix \u2014 entity rights are S/I/U/D/C. If '${key}' is an action or report, prefix it (e.g. 'action:${key}' or 'report:${key}').`
+      `'${key}' is granted 'E' but has no action:/report:/sp:/folder: prefix \u2014 entity rights are S/I/U/D/C. If '${key}' is an action or report, prefix it (e.g. 'action:${key}' or 'report:${key}').`
     );
   }
 }
@@ -36654,7 +36655,7 @@ var roleAddSchema = {
   ),
   description: external_exports.string(),
   rights: external_exports.record(external_exports.string(), external_exports.string()).describe(
-    "Map: object code \u2192 rights string. Keys: same-module entity bare ('product'), cross-module entity dotted ('fin.invoice'), action/report/folder with a COLON prefix ('action:approve', 'report:summary', 'folder:east') \u2014 never a dot. Values: entities use 'S'/'I'/'U'/'D'/'C' (e.g. 'SIUDC'); actions/reports/folders use 'E'. To deny, omit the key (never map to '')."
+    "Map: object code \u2192 rights string. Keys: same-module entity bare ('product'), cross-module entity dotted ('fin.invoice'), action/report/SP/folder with a COLON prefix ('action:approve', 'report:summary', 'sp:rpt_totals', 'folder:east') \u2014 never a dot. Values: entities use 'S'/'I'/'U'/'D'/'C' (e.g. 'SIUDC'); actions/reports/SPs/folders use 'E'. A report with a datasetType 'S' dataset needs BOTH 'report:<cd>' and 'sp:<spCd>'. To deny, omit the key (never map to '')."
   )
 };
 function roleAdd(args) {
@@ -36807,10 +36808,10 @@ var roleRightSetSchema = {
   moduleDir: external_exports.string(),
   roleCode: external_exports.string().describe("Role code as it appears in security/roles.json (e.g. 'crm.admin')."),
   object: external_exports.string().describe(
-    "Object to grant rights on. Same-module entity: bare ('product'). Cross-module entity: dotted ('fin.invoice'). Action/report/folder: COLON prefix ('action:approve', 'report:summary', 'folder:east') \u2014 never a dot."
+    "Object to grant rights on. Same-module entity: bare ('product'). Cross-module entity: dotted ('fin.invoice'). Action/report/SP/folder: COLON prefix ('action:approve', 'report:summary', 'sp:rpt_totals', 'folder:east') \u2014 never a dot. A report whose dataset is datasetType 'S' ALSO needs 'sp:<spCd>' \u2014 report.run enforces both, and the admin UI cannot grant SP rights later."
   ),
   rights: external_exports.string().describe(
-    "Rights string. Entities: any combination of S/I/U/D/C (use '' to revoke all). Actions/reports/folders: 'E' or '' to revoke."
+    "Rights string. Entities: any combination of S/I/U/D/C (use '' to revoke all). Actions/reports/SPs/folders: 'E' or '' to revoke."
   )
 };
 function roleRightSet(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.24",
+	"version": "0.2.25",
 	"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",

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

@@ -101,10 +101,15 @@ 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`.)
-- `columnsDef` — **required** — the platform can't infer columns from a function.
+- `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
+  **override** — `report.run` projects `dForge.sp_column`, and `columnsDef` only restyles it.
+  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.
 
-**Multi-result-set SPs** map extra datasets to the same function via `parentDatasetCd` (the dataset that owns the SP call) + `parentRef` (the named refcursor):
+**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.
 
 ```json
 "datasets": {
@@ -119,10 +124,8 @@ SP files live in `logic/reports/` and follow this convention:
 
 ```sql
 CREATE OR REPLACE FUNCTION crm.rpt_ar_aging(
-    p_folder_uid uuid,        -- REQUIRED: injected by platform (folder context)
-    p_user_id bigint,         -- REQUIRED: injected by platform (current user)
-    p_as_of_date date DEFAULT NULL,    -- User parameter
-    p_customer_id bigint DEFAULT NULL  -- User parameter (optional)
+    p_as_of_date date DEFAULT NULL,    -- one per declared param, in declaration order
+    p_customer_id bigint DEFAULT NULL
 )
 RETURNS TABLE ( customer_name text, current_amount numeric, total numeric )
 LANGUAGE sql STABLE
@@ -135,10 +138,25 @@ $$;
 ```
 
 **Rules for SP functions:**
-- First two params are **always** `p_folder_uid uuid` and `p_user_id bigint` — injected by the platform.
-- User params come after, `DEFAULT NULL` for optional ones (order matches `params` declaration order).
-- `RETURNS TABLE (...)` for a single set; `RETURNS SETOF refcursor` for multi-set (mapped via `parentRef`).
-- Use the module's schema prefix (`crm.rpt_*`), `STABLE` volatility, and filter by `p_folder_uid` / `p_user_id` where needed — **security is your responsibility**.
+- The signature is **exactly** the params declared in `logic/stored_procedures.json`, in that
+  order. `report.run` passes one positional argument per declared param and **nothing else** —
+  there is no folder or user argument, and a function taking one can never be called. Install
+  rejects the mismatch (`no callable PostgreSQL function … with N argument(s)`).
+- `DEFAULT NULL` for optional params — an empty one arrives as a typed NULL.
+- `pgType` must be a scalar type the runtime binds: `bigint`, `integer`, `smallint`,
+  `numeric`, `real`, `double precision`, `text`, `boolean`, `uuid`, `date`, `timestamp`,
+  `timestamptz`, `time`, or an alias of one. A type modifier is ignored, so
+  `numeric(18,2)` is fine. `jsonb`, arrays, enums and `citext` are rejected at install.
+- `paramCd` is capped at 50 characters, and a declared `fieldTypeCd` must be a real one —
+  both are checked at install, because binding the SP in the report editor copies them
+  into report params.
+- `RETURNS TABLE (...)`.
+- Use the module's schema prefix (`crm.rpt_*`) and `STABLE` volatility.
+- **Security is your responsibility, and the function has no context to work from**: it is not
+  told the folder or the user, so an SP dataset cannot be row-level scoped the way a `"Q"`
+  dataset is. Use `"Q"` for anything that must be filtered per user, and keep `"S"` for
+  aggregates that are safe for everyone holding the report's grant.
+- Grant **both** `report:<code>` and `sp:<spCd>` — see `references/security.md`.
 
 ## Parameters
 
@@ -354,13 +372,16 @@ 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`.
-- Forgetting `columnsDef` on an SP dataset — **required**.
+- 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.
 - Writing the rights key as `report.<code>` — actions/reports/folders take a **colon**: `report:<code>`.
 - Writing `isRequired` instead of `required`, or a top-level `link` instead of `params.link` — both are ignored at install.
 - Declaring both `fieldTypeCd` and `domain` on one param — install rejects the pair rather than picking a winner.
 - Mapping a record-report attachment onto a param no dataset declares, or from a `text`/`json` column — both are rejected.
 - Attaching a report to another module's entity without declaring that module as a dependency.
-- Forgetting `p_folder_uid` / `p_user_id` as the first two SP function params — the call fails.
+- Giving an SP function `p_folder_uid` / `p_user_id` params — the platform passes neither, so install rejects the function as uncallable. The signature is exactly the declared params.
+- Granting only `report:<code>` on a report with a `datasetType: "S"` dataset — it also needs `sp:<spCd>`, or every user gets PERMISSION_DENIED on open.
+- Declaring an SP param as `jsonb`, an array, an enum or `citext` — the runtime binds scalar types only (`bigint`, `integer`, `smallint`, `numeric`, `real`, `double precision`, `text`, `boolean`, `uuid`, `date`, `timestamp`, `timestamptz`, `time` and their aliases), and install rejects anything else. `citext` looks like `text` but is a distinct type PostgreSQL will not resolve a text argument against.
 - Referencing a parameter as `$param` — use `@param_code` in filters.
 - Writing an action that computes a number and `info()`s it, where a record report would show the working.

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

@@ -75,11 +75,11 @@ Example:
 | `D` | Delete (remove rows) |
 | `C` | Clone (duplicate a row as a new record) |
 
-### Action/Report/Folder rights
+### Action/Report/SP/Folder rights
 
 | Letter | Permission |
 |---|---|
-| `E` | Execute (run the action/report, access the folder) |
+| `E` | Execute (run the action/report/stored procedure, access the folder) |
 
 ### Common combinations
 
@@ -100,8 +100,13 @@ Role rights map object codes (entities, actions, reports) to rights strings. Obj
 - `fin.invoice` — the entity "invoice" in the `fin` module (cross-module entity — **dot**)
 - `action:send_welcome` — an action named "send_welcome" (**colon**)
 - `report:sales_pipeline` — a report named "sales_pipeline" (**colon**)
+- `sp:rpt_sales_totals` — a stored procedure from `logic/stored_procedures.json` (**colon**)
 - `folder:customers` — the folder with code "customers" (**colon**)
 
+`report:` and `sp:` also take a qualified form — `report:fin.ar_aging`, `sp:fin.rpt_ar_aging` — to
+grant on a **dependency's** report or stored procedure. `action:` and `folder:` do not: the
+installer resolves those within this module only, so a dotted one silently grants nothing.
+
 > **Separator matters — colon for non-entity objects, dot only for cross-module entities.**
 > Actions, reports and folders are prefixed with a **colon**: `action:<code>`, `report:<code>`,
 > `folder:<code>`. A **dot** is reserved for a cross-module *entity* (`module.entity`, e.g.
@@ -118,7 +123,28 @@ Role rights map object codes (entities, actions, reports) to rights strings. Obj
 4. **Never grant `D` (Delete) to a rep-level role** unless deletion is a normal part of their job. Audit trails prefer soft-delete or update.
 5. **Always grant the admin role `SIUDC` on everything the module owns.**
 6. **Action and report access** — grant `E` on specific action/report codes, or omit them entirely (defaulting to no access).
-7. **Folder access** is granted separately — roles can reference folder codes, but folder definitions themselves live in `ui/folders.json`.
+7. **A report with a `datasetType: "S"` dataset needs TWO grants** — `report:<code>` **and**
+   `sp:<spCd>` for the stored procedure the dataset binds. `report.run` enforces the SP's own
+   sec_object on top of the report's right, so granting only the report yields
+   `PERMISSION_DENIED` on open. There is no recovery after install: the role-rights admin UI
+   lists entities, actions and reports only, so a tenant admin cannot add an SP grant by hand.
+   `dforge_module_pack` fails the build when a role grants such a report and no role grants
+   the SP — for the module's own SP. A dependency's SP is left to install: its grant may
+   ship with the dependency's own role, and rights are additive across the roles a user holds.
+
+```json
+{
+    "sales.analyst": {
+        "description": "Sales Analyst",
+        "rights": {
+            "opportunity": "S",
+            "report:sales_totals": "E",
+            "sp:rpt_sales_totals": "E"
+        }
+    }
+}
+```
+8. **Folder access** is granted separately — roles can reference folder codes, but folder definitions themselves live in `ui/folders.json`.
 
 ## Folders (`ui/folders.json`)