@dforge-core/dforge-mcp 0.1.0-rc.11 → 0.1.0-rc.13

package/docs/creating-modules.md

@@ -64,10 +64,14 @@ You: "I want a module to collect end-user feedback on app pages."
 
 The wizard runs:
 
-### Phase 0 — Intake (required, ~1 turn)
+### Phase 0 — Identity, requirements, design, validation (required)
 
-Four questions in one message: purpose / users / dependencies / language scope.
-You can accept defaults to move fast. Writes `_brief/00-intake.md`.
+A documented chain the `dforge-mcp-author` skill enforces — the AI authors each artifact directly (drafts it, you approve, your client writes the file):
+
+- **0a Identity** — write `CLAUDE.md` (identity + MCP-first rules + a live status tracker).
+- **0b Requirements** — intake questions (purpose / users / dependencies / language scope), then write `docs/REQUIREMENTS.md`. **You review it before moving on.**
+- **0c Design** — entity list, relationships, status machines, then write `docs/DESIGN.md`. **You review it before moving on.**
+- **0d Validation** — the AI cross-checks the documents, reports every gap/flaw/inconsistency to `docs/VALIDATION.md`, and must reach a clean pass before scaffolding.
 
 ### Phase 1 — Domain (required, looping)
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.0-rc.11",
+	"version": "0.1.0-rc.13",
 	"description": "MCP server for dForge module authoring. Exposes scaffold/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",
@@ -16,7 +16,8 @@
 		"docs/",
 		"resources/",
 		"skills/",
-		"README.md"
+		"README.md",
+		"CHANGELOG.md"
 	],
 	"main": "dist/server.js",
 	"engines": {
@@ -24,17 +25,21 @@
 	},
 	"scripts": {
 		"build": "tsup",
-		"prepublishOnly": "tsup",
-		"typecheck": "tsc --noEmit"
+		"sync-schemas": "node scripts/vendor-schemas.cjs",
+		"prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run"
 	},
 	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.1.2",
+		"@dforge-core/dforge-cli": "^0.2.2",
+		"@dforge-core/metadata": "^0.0.2",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"zod": "^4.4.3"
 	},
 	"devDependencies": {
 		"@types/node": "^22.10.2",
 		"tsup": "^8.5.1",
-		"typescript": "^6.0.3"
+		"typescript": "^6.0.3",
+		"vitest": "^3.2.0"
 	}
 }

package/resources/docs/conventions.md

@@ -84,7 +84,7 @@ Use the CRM sample module (`modules/crm/`) as a reference implementation.
 ```json
 {
 	"packageFormat": 1,
-	"moduleId": "10000000-0000-0000-0000-000000000002",
+	"moduleId": "REPLACE-WITH-A-FRESH-UUID",
 	"code": "hr",
 	"version": "0.0.1",
 	"dbSchemaVersion": "0.0.1",
@@ -492,7 +492,7 @@ before the install pipeline touches the database.
 - Key is the role code (convention: `module.role-name`)
 - **Property name is `"rights"` (NOT `"entityRights"`)** — this maps to `RoleDef.Rights`
 - Each entry in `rights` maps entity code → rights string
-- Rights characters: `S` (Select), `I` (Insert), `U` (Update), `D` (Delete), `C` (Clone)
+- Rights characters: `S` (Select), `I` (Insert), `U` (Update), `D` (Delete), `C` (Clone) for entities, and `E` (Execute) for actions, reports, and folder access (e.g. `"action:create_quote": "E"`). The roles JSON schema enforces `^[SIUDCE]*$`.
 - Every entity should appear in every role (even if only `"S"` for read-only)
 
 **Common Mistakes:**
@@ -518,7 +518,7 @@ seed-data/
 	"entityCode": "department",
 	"records": [
 		{
-			"department_id": "a0030000-0000-0000-0000-000000000001",
+			"department_id": 3001,
 			"department_code": "EXEC",
 			"department_name": "Executive / Leadership",
 			"is_active": true
@@ -530,10 +530,10 @@ seed-data/
 **Rules:**
 - Files are loaded alphabetically — use numbered prefixes (01-, 02-, etc.)
 - Parent tables must come before child tables (FK dependency order)
-- Include explicit PK values (UUIDs) so child records can reference them
-- Use a stable UUID scheme: `a00X0000-0000-0000-0000-00000000000Y` where X=entity type, Y=record
+- Include explicit PK values so child records can reference them
+- PKs from the `identity` trait are `cuid` — physically `int8` (bigint), **not** UUID strings. Use numeric integers with a stable per-entity scheme: `1001`–`1099` for the first entity type, `2001`–`2099` for the next, etc. Using UUID strings here fails the seed load against `int8` columns.
 - Inserts use `ON CONFLICT DO NOTHING` (idempotent)
-- UUIDs and dates in string format are auto-converted by the seed runner
+- Dates in string format are auto-converted by the seed runner
 - Omit auto-generated fields (`created_date`, `last_updated`) — they use DB defaults
 - Omit cross-module FK fields (e.g., `owner_id` referencing `user` table)
 
@@ -593,13 +593,16 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 	"menus": {
 		"hr_menu": { "label": "Human Resources" }
 	},
-	"roles": {
-		"hr.admin": { "label": "HR Administrator" },
-		"hr.viewer": { "label": "HR Viewer" }
+	"actions": {
+		"approve_leave": { "label": "Approve Leave", "desc": "Approve a leave request" }
 	}
 }
 ```
 
+**Translatable sections (consumed by the installer):** `entities` (+ nested `fields`), `folders`, `views`, `menus` (+ nested `items`), `actions` (+ `params`), `reports` (+ `datasets.caption`, `params`).
+
+**Silently ignored at runtime:** `roles` and `print_templates` — the resource rows have no `res_id`, so translations are reserved for future use. `settings` is validated for completeness (when listed in `supportedLocales`) but the registrar does not display the translated labels, so don't expect localized output. Display names for these come from the source manifest (`description` for roles, `label` for print templates and settings).
+
 ---
 
 ## Entity Definitions (`entities/*.json`)
@@ -613,7 +616,7 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 	"toString": "{first_name} {last_name}",
 	"fields": {
 		"employee_id": {
-			"dbDatatype": "uuid",
+			"dbDatatype": "cuid",
 			"isPk": true,
 			"isIdentity": true,
 			"isNullable": false,
@@ -630,7 +633,8 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 			"description": "Employee Code"
 		},
 		"department_id": {
-			"dbDatatype": "uuid",
+			"dbDatatype": "cuid",
+			"fieldTypeCd": "hidden",
 			"flags": "EM",
 			"orderNum": 30,
 			"description": "Department ID"
@@ -703,7 +707,8 @@ For every foreign key relationship, create TWO columns:
 ### 1. Hidden FK Column (Database)
 ```json
 "department_id": {
-	"dbDatatype": "uuid",
+	"dbDatatype": "cuid",
+	"fieldTypeCd": "hidden",
 	"flags": "EM",
 	"orderNum": 30,
 	"description": "Department ID"
@@ -742,6 +747,7 @@ For every foreign key relationship, create TWO columns:
 - `params` is used for other purposes (e.g., dropdown `options`)
 - Hidden FK column: `flags: "EM"` (no `V` = hidden from UI)
 - Visible reference column: `flags: "VEM"`, `columnType: "R"`
+- The FK column's `dbDatatype` **MUST match the referenced PK's type** — use `cuid` for `identity`-trait PKs (`cuid` is physically `int8`, **not** a UUID). A mismatch (e.g. FK `uuid` → PK `cuid`) fails install with *"foreign key constraint … cannot be implemented"*.
 
 ---
 
@@ -921,8 +927,8 @@ When creating a module, ensure:
 - [ ] `folders.json` uses entity dictionary with `{ viewName, quickAdd }` objects
 - [ ] `roles.json` uses `"rights"` property (not `"entityRights"`)
 - [ ] Seed data files are numbered for FK dependency order (01-, 02-, etc.)
-- [ ] Seed data includes explicit PK UUIDs for cross-entity references
-- [ ] `translations/en-US.json` covers entities, fields, views, menus, folders, roles
+- [ ] Seed data includes explicit numeric (int8) PKs for cross-entity references — NOT UUID strings (`cuid` is `int8`)
+- [ ] `translations/<locale>.json` covers entities (+ fields), folders, views, menus (+ items), actions (+ params), and reports (+ dataset captions, + params) for every locale declared in `manifest.supportedLocales`. Do not include `en`/`en-US`. Sections `roles` and `print_templates` are not displayed even if listed.
 - [ ] Constraints have clear user-facing `message` values
 - [ ] Check constraint `expression` uses standard SQL subset (test in PostgreSQL first)
 - [ ] Number sequences declared as `numberSequence` on entity definitions (auto-fills on INSERT, never manual counting)

package/resources/schemas/entity.schema.json

@@ -46,7 +46,10 @@
 		},
 		"fields": {
 			"type": "object",
-			"description": "Column definitions keyed by column code",
+			"description": "Column definitions keyed by column code. Column codes must start with a letter or underscore and contain only letters, digits, and underscores — a leading `-` is reserved for the sort descending prefix in `view_json.order`.",
+			"propertyNames": {
+				"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
+			},
 			"additionalProperties": {
 				"$ref": "#/$defs/field"
 			}
@@ -196,6 +199,10 @@
 					"$ref": "#/$defs/fieldLink",
 					"description": "Relationship link for Reference (R) and Set (S) columns"
 				},
+				"cyclic": {
+					"type": "boolean",
+					"description": "On a self-referencing reference column (R column whose link.entity is the owning entity), set true to ALLOW parent/child cycles. When absent the self-reference is treated as an acyclic hierarchy and DB-level guards reject loops. Ignored on non-self-referencing columns."
+				},
 				"refFilter": {
 					"description": "Filter criteria for reference lookups"
 				}

package/resources/schemas/reports.schema.json

@@ -159,6 +159,10 @@
 					"description": "Field type code (see settings.schema.json for the common list)"
 				},
 				"label": { "type": "string" },
+				"orderNum": {
+					"type": "integer",
+					"description": "Display order of the parameter in the report's parameter form. Read by ReportRegistrar (paramDef.OrderNum); falls back to declaration order when omitted."
+				},
 				"required": {
 					"type": "boolean",
 					"default": false,