@dforge-core/dforge-mcp 0.1.0-rc.9 → 0.1.1

package/docs/creating-modules.md

@@ -48,8 +48,11 @@ Setup once:
 
 ```bash
 claude mcp add dforge --scope user -- npx -y @dforge-core/dforge-mcp
+# Resolve actual latest from npm, then pin jsdelivr URL to it.
+# (jsdelivr's @latest endpoint caches 6-12h; pinning the version skips that.)
+VERSION=$(npm view @dforge-core/dforge-mcp version)
 mkdir -p ~/.claude/skills/dforge-mcp-author
-curl -fsSL https://cdn.jsdelivr.net/npm/@dforge-core/dforge-mcp@latest/skills/dforge-mcp-author/SKILL.md \
+curl -fsSL "https://cdn.jsdelivr.net/npm/@dforge-core/dforge-mcp@${VERSION}/skills/dforge-mcp-author/SKILL.md" \
   -o ~/.claude/skills/dforge-mcp-author/SKILL.md
 ```
 
@@ -61,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.9",
+	"version": "0.1.1",
 	"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,16 +530,16 @@ 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)
 
 ### 7. Scheduled Jobs (`logic/jobs.json`)
 
-Cron-driven action fires. Each entry pairs an existing action (declared in `ui/actions.json`) with a 5-field cron expression; the `dForge.Scheduler` worker fires it on schedule. Full reference: [module-package-format.md → jobs.json](./module-package-format.md#jobsjson).
+Cron-driven action fires. Each entry pairs an existing action (declared in `ui/actions.json`) with a 5-field cron expression; the `dForge.Scheduler` worker fires it on schedule. Full reference: [Scheduled Jobs](../business-logic/jobs.md). Manifest schema: [`jobs.schema.json`](../schemas/jobs.schema.json).
 
 ```json
 {
@@ -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,12 +927,12 @@ 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)
-- [ ] Print templates defined in `ui/print_templates.json` with HTML files in `print_templates/`
+- [ ] Print templates defined in `ui/print_templates.json` with HTML files in `print_templates/` (see [Print Templates](../ui/print-templates.md))
 - [ ] Scheduled jobs (if any) declared in `logic/jobs.json` with 5-field cron, explicit `timeout`, and `class: "long_running"` for any `timeout > 300`
 
 ---