@dforge-core/dforge-mcp 0.1.13 → 0.2.1

package/docs/creating-modules.md

@@ -42,20 +42,28 @@ Sidebar also gives you right-click commands: **Pack Module**, **Install Module t
 
 ## Path 3 — AI co-pilot, wizard-driven
 
-Claude Code (or Cursor / Zed) with `dforge-mcp` connected. You describe what you want; the AI walks you through six phases via MCP tool calls, pausing at each gate for your approval.
+Claude Code (or Cursor / Zed) with `dforge-mcp` connected. You describe what you want; the AI walks you through seven phases (0-6) via MCP tool calls, pausing at each gate for your approval. Guidance ships as four skills — a router plus one per lifecycle stage — so only the active stage is loaded.
 
 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@${VERSION}/skills/dforge-mcp-author/SKILL.md" \
-  -o ~/.claude/skills/dforge-mcp-author/SKILL.md
+
+# Install the four authoring skills into ~/.claude/skills/
+npx -y -p @dforge-core/dforge-mcp dforge-install-skills
 ```
 
+That works as-is on Windows (cmd.exe / PowerShell), macOS and Linux — it's a
+Node script, not bash. From a clone, `npm run install-skills` installs the local
+copy instead. See the README's "Windows notes" for the WSL caveat.
+
+| Skill | Stage |
+|---|---|
+| `dforge-mcp-author` | Router — finds the current phase and hands off |
+| `dforge-module-design` | Phase 0 — identity, requirements, design, validation |
+| `dforge-module-build` | Phases 1-5 — entities, behavior, views, security |
+| `dforge-module-ship` | Phase 6 — validate, pack, install |
+
 Restart Claude Code, approve the MCP server on first prompt, then in a new conversation:
 
 ```
@@ -66,7 +74,7 @@ The wizard runs:
 
 ### Phase 0 — Identity, requirements, design, validation (required)
 
-A documented chain the `dforge-mcp-author` skill enforces — the AI authors each artifact directly (drafts it, you approve, your client writes the file):
+A documented chain the `dforge-module-design` 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.**
@@ -148,6 +156,9 @@ VS Code with the [dForge extension](https://github.com/dforge-core/dforge-editor
 
 ## Going further
 
-- [SKILL.md](../skills/dforge-mcp-author/SKILL.md) — the full wizard spec the AI follows, including the deterministic backtrack protocol, multi-trigger priority rule, tool-failure protocol, and resume-from-partial-state support
-- [README.md](../README.md) — full tool reference (18 tools, 13 resources) + maintainer docs
+- [dforge-mcp-author](../skills/dforge-mcp-author/SKILL.md) — the router: session start, tool inventory, hard rules, tool-failure protocol, resource index
+- [dforge-module-design](../skills/dforge-module-design/SKILL.md) — Phase 0, including the intake guardrails and gap scans
+- [dforge-module-build](../skills/dforge-module-build/SKILL.md) — Phases 1-5, the loading-policy table, core-rules cheat sheet, and the deterministic backtrack protocol
+- [dforge-module-ship](../skills/dforge-module-ship/SKILL.md) — Phase 6 and the install-fix loop
+- [README.md](../README.md) — full tool reference (34 tools) + maintainer docs
 - [iash44/dForge-core](https://github.com/iash44/dForge-core) — the platform itself: source of truth for the schemas + DSL conventions

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dforge-core/dforge-mcp",
-  "version": "0.1.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.",
+  "version": "0.2.1",
+  "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",
   "repository": {
@@ -9,13 +9,15 @@
     "url": "git+https://github.com/dforge-core/dforge-mcp.git"
   },
   "bin": {
-    "dforge-mcp": "dist/server.js"
+    "dforge-mcp": "dist/server.js",
+    "dforge-install-skills": "scripts/install-skills.mjs"
   },
   "files": [
     "dist/",
     "docs/",
     "resources/",
     "skills/",
+    "scripts/install-skills.mjs",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -28,7 +30,8 @@
     "sync-schemas": "node scripts/vendor-schemas.cjs",
     "prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "install-skills": "node scripts/install-skills.mjs"
   },
   "dependencies": {
     "@dforge-core/dforge-cli": "^0.2.7",

package/resources/docs/dsl-reference.md

@@ -90,7 +90,8 @@ execute:
 ### Current record (single / each mode)
 
 - `[fieldName]` — read or write a field on the current record
-- `[refField].[targetField]` — navigate via a Reference (FK) column to a field on the linked entity
+- `[refField].[targetField]` — navigate via a Reference (FK) column to a field on the linked entity. `[refField].targetField` (bare target) is accepted as an equivalent spelling. **Single-hop only** — `[a].[b].[c]` is a compile error; use `getRecord()` / `select()` to reach past one reference
+- `old[fieldName]` — the field's value *before* the change, in an action invoked by an event trigger. Read-only; reads `null` on `insert` events and outside triggers
 
 ```dsl
 # Read
@@ -151,6 +152,12 @@ if (open.length == 0) { exit('Nothing open', 'info') }
 info('Open invoices: ' + open.length + ', total $' + open[0].total)
 ```
 
+> **Pooled connection.** The connection is handed to another request once your
+> statement finishes — so don't leave state behind on it: `SET LOCAL` not `SET`,
+> `pg_advisory_xact_lock()` not `pg_advisory_lock()`, `ON COMMIT DROP` on temp
+> tables. Don't assume the whole action is one transaction either — that depends
+> on the execution path. Applies to `query()` only.
+
 #### `insert(entityCd, fields) → record`
 Insert a row. Returns the inserted record as a dictionary (PKs populated, defaults applied, audit columns set).
 
@@ -312,7 +319,10 @@ sendEmail([customer_id].[email], 'order_confirmation', {
 ```
 
 #### `error(message)`
-**Throw** — aborts execution and rolls back the **entire transaction** including any prior `insert()` / writes in this `execute:` block. Use for validation failures.
+**Throw** — aborts execution immediately. Use for validation failures. Whether
+prior `insert()` / writes in this `execute:` block are rolled back **depends on the
+execution path** and is not something to rely on — validate before writing
+anything (see the anti-pattern near the end of this document).
 
 ```dsl
 if ([rating] == null || [rating] < 1 || [rating] > 5) {
@@ -766,17 +776,28 @@ execute:
     [last_touched] = now()
 ```
 
-### ❌ Assuming `error()` skips work done above
+### ❌ Assuming you know what `error()` does to work done above
 
-`error()` rolls back the **entire transaction** including prior `insert()` calls. Don't use it to "log and continue" — it's a hard abort.
+`error()` is a hard abort — never use it to "log and continue". What happens to
+writes made *before* it is **not something you can rely on**: it depends on the
+execution path. The same script keeps the row on one path and discards it on
+another, and the difference isn't visible in the action.
 
 ```dsl
-# WRONG — the insert below is rolled back when error fires
+# WRONG — is this insert kept or discarded? Depends on the path.
 execute:
-    insert('audit_log', { event: 'attempted_close', record_id: [id] })   # rolled back!
+    insert('audit_log', { event: 'attempted_close', record_id: [id] })   # unreliable!
     if ([balance_due] > 0) { error('Cannot close — balance owing') }
 ```
 
+Whether an `error()` unwinds earlier writes turns on whether that path opened a
+transaction — for a synchronous action, on whether the entity has `auditHistory`
+**and** whether the mode is `single` (in `batch` mode nothing covers the script);
+a background action has none at all and keeps everything written before the
+failure. This is a platform defect rather than a contract — actions are intended
+to be atomic — so don't design around it either way. Write the script so the
+question never arises: validate first.
+
 ```dsl
 # RIGHT — validate first, then perform side-effects
 execute:

package/resources/schemas/domains.schema.json

@@ -0,0 +1,78 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/domains.schema.json",
+	"title": "dForge Column Domains",
+	"description": "domains.json — reusable, named semantic types. A domain bundles a base datatype, a control, sizing and a shared option list under one code; columns reference it via \"domain\": \"module_cd.domain_cd\" instead of restating the definition. Structural fields are materialized onto each column at install; options stay on the domain and resolve at metadata-load time, so a shared list is authored and translated exactly once.",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/domain"
+	},
+	"propertyNames": {
+		"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+		"description": "Domain code. Must not contain '.', which is reserved for the qualified 'module_cd.domain_cd' form."
+	},
+	"$defs": {
+		"domain": {
+			"type": "object",
+			"required": ["baseDatatypeCd"],
+			"additionalProperties": false,
+			"properties": {
+				"description": {
+					"type": "string",
+					"description": "Human-readable label. Localizable via translations/<locale>.json under domains.<domain_cd>.label."
+				},
+				"baseDatatypeCd": {
+					"type": "string",
+					"description": "Base datatype the domain stands for (e.g. string, number, date, datetime, boolean). Required — it is what consuming columns' DDL is generated from."
+				},
+				"dbDatatype": {
+					"type": "string",
+					"description": "Physical Postgres type for consuming columns (e.g. varchar, int4, numeric). Omit to let it be inferred from fieldTypeCd."
+				},
+				"fieldTypeCd": {
+					"type": "string",
+					"description": "Control used to render/edit consuming columns (e.g. dropdown, radio, flags, text, number)."
+				},
+				"maxLen": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Max length for string-backed domains."
+				},
+				"precision": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Decimal precision for numeric domains."
+				},
+				"params": {
+					"type": "object",
+					"description": "Field-type config shared by every consuming column — most importantly the 'options' list for dropdown/radio/flags. Never copied onto columns: it resolves from the domain at load time, which is what lets its labels be translated once for all consumers.",
+					"properties": {
+						"options": {
+							"type": "array",
+							"description": "Option list. Each entry is either a bare string (value doubles as label) or an object. Per-locale label/icon/color overrides live in translations/<locale>.json under domains.<domain_cd>.options.<value>.",
+							"items": {
+								"oneOf": [
+									{ "type": "string" },
+									{
+										"type": "object",
+										"required": ["value"],
+										"additionalProperties": false,
+										"properties": {
+											"value": {
+												"type": "string",
+												"description": "The stored code. Never translatable — translations match on it."
+											},
+											"label": { "type": "string" },
+											"icon": { "type": "string" },
+											"color": { "type": "string" }
+										}
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

package/resources/schemas/entity.schema.json

@@ -209,11 +209,29 @@
 					"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."
 				},
+				"domain": {
+					"type": "string",
+					"description": "Reference to a reusable column domain, qualified as 'module_cd.domain_cd' (unqualified resolves within this module, then tenant-created domains). The domain supplies dbDatatype, baseDatatypeCd, fieldTypeCd, maxLen, precision and params; declaring any of those alongside 'domain' is rejected at install. The column keeps its own description, flags, orderNum, isNullable and isPk."
+				},
 				"refFilter": {
 					"description": "Filter criteria for reference lookups. Condition values support @[field] placeholders resolved against the current record at lookup time (e.g. {\"c\":\"channel\",\"o\":\"eq\",\"v\":\"@[channel]\"} narrows options to rows matching the record's own channel); a condition whose placeholder is unset is dropped rather than matching nothing."
 				}
 			},
 			"oneOf": [
+				{
+					"title": "Domain-backed column",
+					"description": "Physical column whose datatype, control, sizing and options all come from a reusable column domain. Requires 'domain' and must NOT restate what the domain owns.",
+					"required": ["domain"],
+					"properties": {
+						"link": false,
+						"dbDatatype": false,
+						"baseDatatypeCd": false,
+						"fieldTypeCd": false,
+						"maxLen": false,
+						"precision": false,
+						"params": false
+					}
+				},
 				{
 					"title": "Data column",
 					"description": "Physical DB column (columnType 'D' or unspecified). Requires 'dbDatatype'. Must NOT have 'link'.",

package/resources/schemas/triggers.schema.json

@@ -37,20 +37,20 @@
 				},
 				"condition": {
 					"type": "string",
-					"description": "Optional formula expression — same shape as canExecute in action DSL. Uses `[field]` syntax to reference the affected record. Single-line, evaluates to boolean. If omitted, trigger fires for every matching event."
+					"description": "Optional formula expression — same shape as canExecute in action DSL. Uses `[field]` syntax to reference the affected record. Single-line, evaluates to boolean. If omitted, trigger fires for every matching event. Reference navigation (`[ref].[target]`) is REJECTED here: the event-time evaluator only reads columns of the changed row, so a nav path would resolve to null and the trigger would misfire. Navigate inside the action instead, or denormalise the value onto the watched entity."
 				},
 				"action": {
 					"type": "string",
-					"description": "Action code to invoke. The action must NOT use record-context (`[field]`) syntax in a way that requires the original triggering record — the trigger passes the record id via params. Cross-module form 'module.action' is supported."
+					"description": "Action code to invoke. The trigger binds the affected record to the action as RECORD CONTEXT, so the action reads its columns with `[field]` (and its PK with `[pk_column]`) exactly like a UI-invoked action — no lookup needed. The action's `entityCode` MUST equal this trigger's `entity`, and its `executionMode` must not be `batch`; both are enforced at pack time. Cross-module references use the qualified form 'module.action'."
 				},
 				"params": {
 					"type": "object",
-					"description": "Optional static parameters passed to the action at invocation time. Merged with the runtime-injected `record_id` / `record_old` (if event uses old-record diff)."
+					"description": "Optional STATIC parameters passed to the action at invocation time — the literal values written here, nothing else. Nothing is injected at runtime: there is no `record_id` param. The affected record arrives as record context (`[field]`), and its pre-change values as `old[field]` on update/delete/status_change events."
 				},
 				"async": {
 					"type": "boolean",
-					"default": false,
-					"description": "When true, the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls); background failures are logged, not surfaced to the caller. When false, the action runs synchronously inside the same transaction as the triggering insert/update/delete: if the action fails (e.g. calls error()), the whole mutation rolls back and the error is returned to the caller. Keep async:false actions fast — they run on the request's transaction."
+					"default": true,
+					"description": "When true (the default), the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls); background failures are logged, not surfaced to the caller. When false, the action runs synchronously inside the same transaction as the triggering insert/update/delete: if the action fails (e.g. calls error()), the whole mutation rolls back and the error is returned to the caller — so an async:false trigger can undo the user's write. Keep async:false actions fast; they run on the request's transaction."
 				}
 			},
 			"additionalProperties": false

package/scripts/install-skills.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// Install the dForge authoring skills into the Claude skills directory.
+//
+// The skills ship inside the npm tarball, but Claude Code only looks in
+// <config>/skills — not node_modules — so they have to be copied out. There are
+// four (a router plus three stage skills), and the router's directory also
+// carries the shared references/ + examples/ the MCP server serves as dforge://
+// resources, so hand-copying is error-prone.
+//
+// Written in Node rather than bash so it behaves identically on Windows
+// (cmd.exe, PowerShell), macOS, Linux, Git Bash and WSL. The bash version this
+// replaced could not run in cmd/PowerShell at all, and under WSL it resolved
+// $HOME to the LINUX home — silently installing to /home/you/.claude while
+// Claude Code on Windows read C:\Users\you\.claude.
+//
+// Usage:
+//   node scripts/install-skills.mjs              # from a local checkout
+//   node scripts/install-skills.mjs --from-npm   # download the published version
+//   DEST=/some/where node scripts/install-skills.mjs
+//
+//   npm run install-skills
+//   npm run install-skills -- --from-npm
+
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKILLS = [
+	["dforge-mcp-author", "router — start here; also holds the shared\n                        references/ and examples/ the MCP server serves"],
+	["dforge-module-design", "Phase 0  — identity, intake, design, validation"],
+	["dforge-module-build", "Phases 1-5 — entities, behavior, views, security"],
+	["dforge-module-ship", "Phase 6  — validate, pack, install-fix loop"],
+];
+
+const PKG = "@dforge-core/dforge-mcp";
+const fromNpm = process.argv.includes("--from-npm");
+
+// Piping into `head`/`less` closes our stdout mid-write; without this Node
+// turns that into an unhandled EPIPE and dumps a stack trace over what is
+// otherwise a successful install.
+for (const stream of [process.stdout, process.stderr]) {
+	stream.on("error", (e) => {
+		if (e.code === "EPIPE") process.exit(0);
+		throw e;
+	});
+}
+
+/**
+ * Where Claude Code looks for skills. `CLAUDE_CONFIG_DIR` wins when set;
+ * otherwise `<home>/.claude/skills`. os.homedir() is the point of this being a
+ * Node script — on Windows it's %USERPROFILE% regardless of which shell (or
+ * shell emulator) invoked us.
+ */
+function defaultDest() {
+	if (process.env.DEST) return process.env.DEST;
+	const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+	return path.join(configDir, "skills");
+}
+
+/** npm is a .cmd shim on Windows, which spawn can only launch through a shell. */
+const NPM = process.platform === "win32" ? "npm.cmd" : "npm";
+
+function npm(args, opts = {}) {
+	const r = spawnSync(NPM, args, {
+		encoding: "utf8",
+		shell: process.platform === "win32",
+		...opts,
+	});
+	if (r.error) {
+		throw new Error(`Failed to run \`npm ${args.join(" ")}\`: ${r.error.message}. Is npm on your PATH?`);
+	}
+	if (r.status !== 0) {
+		throw new Error(`\`npm ${args.join(" ")}\` failed (exit ${r.status}):\n${r.stderr || r.stdout}`);
+	}
+	return (r.stdout || "").trim();
+}
+
+/**
+ * Download + unpack the published tarball into a temp dir, returning its
+ * skills/ path. Uses `npm pack` (which fetches only this package, not its
+ * ~35 MB native CLI dependency) plus `tar`, which ships with Windows 10 1803+,
+ * macOS and every Linux.
+ */
+function fetchFromNpm(tmp) {
+	// Resolve the real latest version rather than relying on a CDN alias that
+	// caches for hours after a publish and would serve stale skills.
+	const version = npm(["view", PKG, "version"]);
+	process.stdout.write(`Fetching ${PKG}@${version} …\n`);
+	npm(["pack", `${PKG}@${version}`, "--pack-destination", tmp], { cwd: tmp });
+
+	const tarball = fs.readdirSync(tmp).find((f) => f.endsWith(".tgz"));
+	if (!tarball) throw new Error(`npm pack produced no .tgz in ${tmp}`);
+
+	const r = spawnSync("tar", ["-xzf", path.join(tmp, tarball), "-C", tmp], { encoding: "utf8" });
+	if (r.error || r.status !== 0) {
+		throw new Error(
+			`Could not extract ${tarball}: ${r.error?.message ?? r.stderr}\n` +
+				"`tar` is required (built into Windows 10 1803+, macOS and Linux). " +
+				"Alternatively clone the repo and run this script without --from-npm.",
+		);
+	}
+	return path.join(tmp, "package", "skills");
+}
+
+function main() {
+	const dest = defaultDest();
+	let tmp;
+	let src;
+
+	try {
+		if (fromNpm) {
+			tmp = fs.mkdtempSync(path.join(os.tmpdir(), "dforge-skills-"));
+			src = fetchFromNpm(tmp);
+		} else {
+			// Relative to this file, so it works from any cwd.
+			const here = path.dirname(fileURLToPath(import.meta.url));
+			src = path.join(here, "..", "skills");
+		}
+
+		if (!fs.existsSync(src)) {
+			throw new Error(
+				`No skills directory at ${src}.` +
+					(fromNpm ? "" : " Run with --from-npm to install from the published package instead."),
+			);
+		}
+
+		fs.mkdirSync(dest, { recursive: true });
+		let installed = 0;
+		for (const [skill] of SKILLS) {
+			const from = path.join(src, skill);
+			if (!fs.existsSync(from)) {
+				process.stderr.write(`  ! skipping ${skill} (not found in ${src})\n`);
+				continue;
+			}
+			// Replace wholesale: a stale reference file left behind is worse than a
+			// missing one, because the agent will happily author against it.
+			fs.rmSync(path.join(dest, skill), { recursive: true, force: true });
+			fs.cpSync(from, path.join(dest, skill), { recursive: true });
+			process.stdout.write(`  \u2713 ${skill}\n`);
+			installed++;
+		}
+
+		if (installed === 0) throw new Error(`No skills were installed from ${src}.`);
+
+		process.stdout.write(
+			`\nInstalled ${installed} skill${installed === 1 ? "" : "s"} to ${dest}\n\n`,
+		);
+		for (const [skill, blurb] of SKILLS) {
+			process.stdout.write(`  ${skill.padEnd(21)} ${blurb}\n`);
+		}
+		process.stdout.write(
+			"\nRe-run after every dforge-mcp upgrade. The skill version is not checked at\n" +
+				"runtime, so stale skills against new tools will misroute calls.\n",
+		);
+	} catch (e) {
+		process.stderr.write(`error: ${e.message}\n`);
+		process.exitCode = 1;
+	} finally {
+		if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
+	}
+}
+
+main();