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

package/dist/server.js

@@ -31381,8 +31381,12 @@ function modulePaths(moduleDir) {
     menus: path3.join(root, "ui", "menus.json"),
     actions: path3.join(root, "ui", "actions.json"),
     reports: path3.join(root, "ui", "reports.json"),
+    queries: path3.join(root, "ui", "queries.json"),
+    printTemplates: path3.join(root, "ui", "print_templates.json"),
     roles: path3.join(root, "security", "roles.json"),
     jobs: path3.join(root, "logic", "jobs.json"),
+    triggers: path3.join(root, "logic", "triggers.json"),
+    webhooks: path3.join(root, "logic", "webhooks.json"),
     settings: path3.join(root, "settings.json")
   };
 }
@@ -31932,6 +31936,158 @@ function computeDepth(folder, current = 1) {
   return childDepths.length === 0 ? current : Math.max(...childDepths);
 }
 
+// src/tools/behavior.ts
+var triggerAddSchema = {
+  moduleDir: external_exports.string(),
+  code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Trigger code, unique within the module."),
+  entity: external_exports.string().describe(
+    "Entity whose events fire this trigger. Cross-module dotted form supported ('fin.invoice')."
+  ),
+  event: external_exports.enum(["insert", "update", "delete", "status_change", "any"]).describe(
+    "insert/update/delete are obvious. status_change fires only when status field changes value. 'any' fires for all insert/update/delete."
+  ),
+  action: external_exports.string().describe("Action code to invoke. Cross-module dotted form ('module.action') supported."),
+  description: external_exports.string().optional(),
+  condition: external_exports.string().optional().describe(
+    "Optional formula expression (same shape as canExecute) using `[field]` syntax. Single-line boolean. If omitted, trigger fires on every matching event."
+  ),
+  params: external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe(
+    "Static params merged into the action invocation alongside auto-injected record_id."
+  ),
+  async: external_exports.boolean().default(false).describe(
+    "When true, the action runs in background (recommended for slow actions). When false, runs in the same transaction \u2014 action failure rolls back the original DB change."
+  )
+};
+function triggerAdd(args) {
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const file2 = readJsonOrDefault(
+    paths.triggers,
+    { triggers: [] }
+  );
+  if (file2.triggers.some((t) => t.code === args.code)) {
+    throw new Error(`Trigger '${args.code}' already exists.`);
+  }
+  const entry = {
+    code: args.code,
+    entity: args.entity,
+    event: args.event,
+    action: args.action,
+    async: args.async
+  };
+  if (args.description) entry.description = args.description;
+  if (args.condition) entry.condition = args.condition;
+  if (args.params) entry.params = args.params;
+  file2.triggers.push(entry);
+  return makeResult(
+    `Added trigger '${args.code}' on ${args.entity}.${args.event} \u2192 action '${args.action}'${args.async ? " (async)" : ""}.`,
+    {
+      [rel(paths.root, paths.triggers)]: jsonText(file2),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
+var jobAddSchema = {
+  moduleDir: external_exports.string(),
+  code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Job code, unique within the module."),
+  action: external_exports.string().describe(
+    "Action code to invoke on schedule. MUST NOT use record-context (`[field]`) syntax \u2014 scheduled jobs run as system user with no current record. Wrap record-context actions in a thin action that queries first."
+  ),
+  schedule: external_exports.string().describe(
+    "5-field cron expression (minute hour day-of-month month day-of-week). Evaluated in the tenant's time zone (auth.tenant.time_zone) or per-job override."
+  ),
+  timeout: external_exports.number().int().min(1).max(3600).describe(
+    "Hard kill timeout in seconds. Required. If > 300, you must also set `class: 'long_running'`."
+  ),
+  description: external_exports.string().optional(),
+  concurrency: external_exports.number().int().min(1).default(1).describe("Max overlapping executions. Default 1 (skip new fire if previous still running)."),
+  jobClass: external_exports.enum(["standard", "long_running"]).default("standard").describe(
+    "Required to be 'long_running' when timeout > 300. Affects scheduler thread-pool routing."
+  ),
+  paused: external_exports.boolean().default(false)
+};
+function jobAdd(args) {
+  if (args.timeout > 300 && args.jobClass !== "long_running") {
+    throw new Error(
+      "Jobs with timeout > 300s must set jobClass: 'long_running' \u2014 see logic/jobs.json convention."
+    );
+  }
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const file2 = readJsonOrDefault(
+    paths.jobs,
+    { jobs: [] }
+  );
+  if (file2.jobs.some((j) => j.code === args.code)) {
+    throw new Error(`Job '${args.code}' already exists.`);
+  }
+  const entry = {
+    code: args.code,
+    action: args.action,
+    schedule: args.schedule,
+    timeout: args.timeout,
+    concurrency: args.concurrency,
+    class: args.jobClass
+  };
+  if (args.description) entry.description = args.description;
+  if (args.paused) entry.paused = true;
+  file2.jobs.push(entry);
+  return makeResult(
+    `Added job '${args.code}' (schedule '${args.schedule}', timeout ${args.timeout}s) \u2192 action '${args.action}'.`,
+    {
+      [rel(paths.root, paths.jobs)]: jsonText(file2),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
+var webhookAddSchema = {
+  moduleDir: external_exports.string(),
+  code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Subscription code, unique within the module."),
+  entity: external_exports.string().describe("Entity whose events fire this webhook."),
+  event: external_exports.enum(["insert", "update", "delete", "status_change", "any"]).describe("Same event taxonomy as triggers."),
+  endpointUrl: external_exports.string().url().describe("Destination URL \u2014 receives POST with the payload."),
+  description: external_exports.string().optional(),
+  condition: external_exports.string().optional().describe("Optional formula filter; fires only when true. Same shape as trigger condition."),
+  payload: external_exports.object({
+    include: external_exports.array(external_exports.string()).optional().describe("Whitelist of field codes to include. Omit to send all fields."),
+    exclude: external_exports.array(external_exports.string()).optional().describe("Blacklist (applied after include). Use for stripping sensitive cols."),
+    includeOld: external_exports.boolean().optional().describe(
+      "For update/status_change events, also include the pre-change record as `old`."
+    )
+  }).optional().describe(
+    "Payload shape. If omitted, sends full new record. The platform always wraps in `{ event, entity, record, old?, occurred_at }`."
+  ),
+  headers: external_exports.record(external_exports.string(), external_exports.string()).optional().describe(
+    "Extra HTTP headers (e.g. authentication tokens). Use `getSecret(...)` semantics: header values starting with `$secret:` are resolved at fire time."
+  )
+};
+function webhookAdd(args) {
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const file2 = readJsonOrDefault(
+    paths.webhooks,
+    { subscriptions: [] }
+  );
+  if (file2.subscriptions.some((s) => s.code === args.code)) {
+    throw new Error(`Webhook subscription '${args.code}' already exists.`);
+  }
+  const entry = {
+    code: args.code,
+    entity: args.entity,
+    event: args.event,
+    endpointUrl: args.endpointUrl
+  };
+  if (args.description) entry.description = args.description;
+  if (args.condition) entry.condition = args.condition;
+  if (args.payload) entry.payload = args.payload;
+  if (args.headers) entry.headers = args.headers;
+  file2.subscriptions.push(entry);
+  return makeResult(
+    `Added webhook subscription '${args.code}' on ${args.entity}.${args.event} \u2192 POST ${args.endpointUrl}.`,
+    {
+      [rel(paths.root, paths.webhooks)]: jsonText(file2),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
+
 // src/resources/index.ts
 var fs5 = __toESM(require("fs"));
 var path7 = __toESM(require("path"));
@@ -31994,7 +32150,17 @@ var resources = [
   schema(
     "webhooks",
     "Webhooks JSON schema",
-    "JSON Schema for ui/webhooks.json \u2014 outbound webhook definitions."
+    "JSON Schema for logic/webhooks.json \u2014 outbound webhook subscriptions: entity + event filter \u2192 POST to endpointUrl with selected fields."
+  ),
+  schema(
+    "triggers",
+    "Triggers JSON schema",
+    "JSON Schema for logic/triggers.json \u2014 intra-tenant DB-event \u2192 action invocation: entity + event + optional condition formula \u2192 fires an action (sync or async)."
+  ),
+  schema(
+    "print-templates",
+    "Print templates JSON schema",
+    "JSON Schema for ui/print_templates.json \u2014 Liquid HTML print templates and reusable snippets, bound to entities for the print menu."
   ),
   schema(
     "settings",
@@ -32146,10 +32312,28 @@ server.tool(
 );
 server.tool(
   "dforge_action_add",
-  "PHASE 3: Add a DSL action targeting an entity. Writes logic/actions/<code>.dsl plus an entry in ui/actions.json. Phase 3 is optional \u2014 only call when business logic genuinely requires custom actions.",
+  "PHASE 2: Add a DSL action targeting an entity. Writes logic/actions/<code>.dsl plus an entry in ui/actions.json. **Load dforge://docs/dsl before authoring.**",
   actionAddSchema,
   envelope(actionAdd)
 );
+server.tool(
+  "dforge_trigger_add",
+  "PHASE 2: Add a trigger that fires an action on a DB event (insert/update/delete/status_change/any) optionally gated by a condition formula. Appends to logic/triggers.json. **Use trigger when the platform should react to data changes WITHOUT user interaction**; use jobs for cron-driven; use webhooks for outbound HTTP.",
+  triggerAddSchema,
+  envelope(triggerAdd)
+);
+server.tool(
+  "dforge_job_add",
+  "PHASE 2: Schedule an existing action to fire on a 5-field cron. Appends to logic/jobs.json. Action must NOT use record-context (`[field]`) syntax \u2014 scheduled jobs run as system user with no current record.",
+  jobAddSchema,
+  envelope(jobAdd)
+);
+server.tool(
+  "dforge_webhook_add",
+  "PHASE 2: Subscribe an outbound HTTP endpoint to a DB event. Appends to logic/webhooks.json. Use for integrations with external systems (Slack, Zapier, custom dashboards).",
+  webhookAddSchema,
+  envelope(webhookAdd)
+);
 server.tool(
   "dforge_view_add",
   "PHASE 4: Add a data view to ui/data_views.json. viewType-specific viewConfig is supplied verbatim \u2014 pull dforge://schema/data-views first to know the shape.",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.0-rc.10",
+	"version": "0.1.0-rc.11",
 	"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",

package/resources/docs/conventions.md

@@ -539,7 +539,7 @@ seed-data/
 
 ### 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
 {
@@ -926,7 +926,7 @@ When creating a module, ensure:
 - [ ] 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`
 
 ---

package/resources/schemas/print-templates.schema.json

@@ -0,0 +1,82 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "dForge Module Print Templates",
+	"description": "Print template declarations for a dForge module package (ui/print_templates.json). Each key is the template_cd; the value declares either a printable template (default) or a reusable snippet pulled into other templates via {% include 'module_cd.snippet_cd' %}.",
+	"type": "object",
+	"additionalProperties": {
+		"type": "object",
+		"properties": {
+			"type": {
+				"type": "string",
+				"enum": ["template", "snippet"],
+				"default": "template",
+				"description": "'template' (default) — a full printable form bound to an entity. 'snippet' — a reusable Liquid partial, module-scoped, no entity binding, included from other templates."
+			},
+			"entityCd": {
+				"type": "string",
+				"description": "Entity code this template renders. Required when type='template'; ignored when type='snippet'. Cross-module form 'module.entity' is supported (e.g. fin-ch ships a template for fin.invoice)."
+			},
+			"description": {
+				"type": "string",
+				"description": "Human-readable label shown in the print menu."
+			},
+			"template": {
+				"type": "string",
+				"description": "Inline Liquid HTML. Either 'template' or 'file' must be set; 'file' takes precedence when both are present."
+			},
+			"file": {
+				"type": "string",
+				"description": "Relative path under the module's print_templates/ directory (e.g. 'invoice.html'). Loaded at install time."
+			},
+			"css": {
+				"type": "string",
+				"description": "Inline CSS, or a filename ending in .css (resolved relative to print_templates/). Snippets typically inherit CSS from the host template and omit this."
+			},
+			"pageSettings": {
+				"type": "object",
+				"description": "Default page geometry applied when the user prints from the UI. Stored as jsonb on the row; the editor lets users tweak per-template.",
+				"properties": {
+					"size": {
+						"type": "string",
+						"enum": ["A4", "letter", "legal"],
+						"default": "A4"
+					},
+					"orientation": {
+						"type": "string",
+						"enum": ["portrait", "landscape"],
+						"default": "portrait"
+					},
+					"margins": {
+						"type": "object",
+						"properties": {
+							"top":    { "type": "string", "description": "CSS length, e.g. '15mm'." },
+							"right":  { "type": "string" },
+							"bottom": { "type": "string" },
+							"left":   { "type": "string" }
+						},
+						"additionalProperties": false
+					}
+				},
+				"additionalProperties": false
+			}
+		},
+		"additionalProperties": false,
+		"allOf": [
+			{
+				"if": { "properties": { "type": { "const": "snippet" } }, "required": ["type"] },
+				"then": {
+					"description": "Snippets must not declare entityCd and their template_cd must not contain '.' (collides with {% include 'module_cd.snippet_cd' %})."
+				},
+				"else": {
+					"required": ["entityCd"]
+				}
+			},
+			{
+				"anyOf": [
+					{ "required": ["file"] },
+					{ "required": ["template"] }
+				]
+			}
+		]
+	}
+}

package/resources/schemas/triggers.schema.json

@@ -0,0 +1,59 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/triggers.schema.json",
+	"title": "dForge Module Triggers",
+	"description": "Trigger definitions for a dForge module (logic/triggers.json). A trigger watches an entity for an event (insert/update/delete/status_change/any), evaluates an optional formula condition using `[field]` syntax, and fires an action if true. Different from scheduled jobs (cron-driven) and webhooks (outbound HTTP) — triggers are intra-tenant DB-event-driven action invocations.",
+	"type": "object",
+	"required": ["triggers"],
+	"properties": {
+		"triggers": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/trigger" }
+		}
+	},
+	"additionalProperties": false,
+	"$defs": {
+		"trigger": {
+			"type": "object",
+			"required": ["code", "entity", "event", "action"],
+			"properties": {
+				"code": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9_]*$",
+					"description": "Trigger code, unique within the module."
+				},
+				"description": {
+					"type": "string",
+					"description": "Human-readable description of what the trigger does and when."
+				},
+				"entity": {
+					"type": "string",
+					"description": "Entity whose events this trigger watches. May be cross-module via dot notation (e.g. 'fin.invoice')."
+				},
+				"event": {
+					"type": "string",
+					"enum": ["insert", "update", "delete", "status_change", "any"],
+					"description": "DB event that fires this trigger. 'status_change' only fires when the entity's status field actually changes value. 'any' fires for all insert/update/delete."
+				},
+				"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."
+				},
+				"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."
+				},
+				"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)."
+				},
+				"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). When false, the action runs in the same transaction; failures roll back the original DB change."
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/skills/dforge-mcp-author/SKILL.md

@@ -175,15 +175,55 @@ A field is **batchable** only if ALL of these are true: scalar primitive (string
 
 **Exit criteria:** every entity has at least PK + audit traits + 1 user-visible field; FK references resolve; manifest's `entities` map reflects reality.
 
-## Phase 2 — Actions (optional, skip-able)
+## Phase 2 — Behavior (optional sub-steps)
 
 **Preconditions:** Phase 1 complete.
 
-Skip entirely if the module is pure CRUD. Do **not** fabricate actions to fill the phase.
+Phase 2 covers four kinds of behavior — all optional, all individually skip-able. Each fires action logic, but the **trigger** differs:
 
-When the user has a real business operation: **load `dforge://docs/dsl`** (the full action DSL reference — block structure, all 30 built-in functions, field-access syntax, batch-mode rules, JS subset, pitfalls), then call `dforge_action_add` per action — one at a time — with the full DSL body. `dforge://docs/conventions` is broader module-level guidance and does NOT cover the DSL grammar — load `docs/dsl` specifically.
+| Sub-step | Fires when | File | Tool | Use when |
+|---|---|---|---|---|
+| 2a Actions | user clicks a button | `ui/actions.json` + `logic/actions/*.dsl` | `dforge_action_add` | bulk operations, business workflows, anything that needs user input via params |
+| 2b Triggers | DB event happens (insert/update/delete/status_change) | `logic/triggers.json` | `dforge_trigger_add` | reactive automation: "when X happens, do Y" without user action |
+| 2c Scheduled jobs | cron timer | `logic/jobs.json` | `dforge_job_add` | periodic work: nightly cleanup, daily summary, hourly poll |
+| 2d Webhooks | DB event happens → POSTs to external URL | `logic/webhooks.json` | `dforge_webhook_add` | integrations: Slack notifications, Zapier, external dashboards, audit log shipping |
 
-**Exit criteria:** every action you added is intended, named, and has params/canExecute/execute blocks. Compilation is validated in Phase 6.
+Skip a sub-step entirely if the user has no need for it. Do NOT fabricate behavior to fill a sub-step. Phase 2 can be completely skipped for pure CRUD modules.
+
+### 2a. Actions — user-triggered
+
+**Load `dforge://docs/dsl`** (the full action DSL reference — block structure, all 30 built-in functions, field-access syntax, batch-mode rules, JS subset, common patterns, anti-patterns) before authoring any DSL. `dforge://docs/conventions` is broader module-level guidance and does NOT cover the DSL grammar.
+
+Call `dforge_action_add` per action — one at a time — with the full DSL body. Confirm with the user before each call.
+
+### 2b. Triggers — DB-event-driven
+
+**Load `dforge://schema/triggers`** for the shape; also re-read the trigger formula rules in `dforge://docs/dsl` (trigger conditions use the same syntax as `canExecute:`: single-line `[field] op value` formulas).
+
+For each trigger, propose: entity + event + (optional) condition formula + target action + async flag. Use `dforge_trigger_add`. Triggers reference EXISTING actions — make sure the action exists first (Phase 2a or scaffolded admin actions).
+
+**Async vs sync:** `async: true` runs the action in the background after the triggering transaction commits — recommended for slow actions (emails, external API calls). `async: false` runs in the same transaction; action failure rolls back the original DB change.
+
+### 2c. Scheduled jobs — cron-driven
+
+**Load `dforge://schema/jobs`**.
+
+Constraints baked into the tool:
+- Action MUST NOT use record-context (`[field]`) syntax — jobs run as system user with NO current record. Wrap any record-context action in a thin job-friendly action that uses `query()` to fetch the records it needs.
+- `timeout` is required, ≤ 3600s.
+- If `timeout > 300`, you MUST set `jobClass: 'long_running'`.
+
+Use `dforge_job_add` per job.
+
+### 2d. Webhooks — outbound HTTP
+
+**Load `dforge://schema/webhooks`**.
+
+For each webhook: entity + event + endpoint URL + (optional) condition + (optional) payload shape (include/exclude/includeOld). Use `dforge_webhook_add`.
+
+For authenticated endpoints: put bearer tokens / API keys behind `getSecret()` (configure secret in module's secrets), reference in headers as `"Authorization": "$secret:<secret_cd>"` — the platform resolves at fire time.
+
+**Exit criteria for Phase 2:** every action / trigger / job / webhook you added is intended (user-requested, not fabricated to fill space) and references existing entities + actions. Compilation is validated at install in Phase 6.
 
 ## Phase 3 — Views (required) + Reports (optional)