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

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

@@ -0,0 +1,149 @@
+# Scheduled Jobs Reference
+
+A scheduled job is **a cron schedule + an action** declared in `logic/jobs.json`. The `dForge.Scheduler` worker process fires the action on schedule. No new DSL surface — jobs reuse existing actions.
+
+Lives in: `logic/jobs.json` at the module root. Schema: [`docs/schemas/jobs.schema.json`](../../../docs/schemas/jobs.schema.json). Full guide: [`docs/business-logic/jobs.md`](../../../docs/business-logic/jobs.md).
+
+## Structure
+
+```json
+{
+    "jobs": [
+        {
+            "code": "nightly_invoice_run",
+            "description": "Generate recurring invoices for active subscriptions.",
+            "action": "generate_invoices",
+            "schedule": "0 2 * * *",
+            "timeout": 600,
+            "class": "long_running",
+            "concurrency": 1,
+            "timeZone": "Europe/Zurich"
+        }
+    ]
+}
+```
+
+## Field reference
+
+| Field            | Required | Default      | Notes                                                                                                                                |
+| ---------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `code`           | Yes      |              | Unique within the module. `^[a-z][a-z0-9_]*$`.                                                                                       |
+| `action`         | Yes      |              | Action `code` from this module's `ui/actions.json`. Cross-module references are rejected — wrap in a local action.                   |
+| `schedule`       | Yes      |              | Five-field cron (minute granularity). Sub-minute schedules rejected.                                                                 |
+| `timeout`        | Yes      |              | Hard timeout in seconds. Range `(0, 3600]`. **No implicit default.** `timeout > 300` requires `class: "long_running"`.               |
+| `class`          | No       | `"standard"` | `"standard"` (≤ 300 s) or `"long_running"` (≤ 3600 s). Explicit opt-in for heavy jobs.                                               |
+| `concurrency`    | No       | `1`          | Max parallel runs `[1, 5]`. `1` = single-instance.                                                                                   |
+| `idempotencyKey` | No       |              | Template like `"{job_cd}:{run.month}"`. Successful run with same key blocks re-dispatch.                                             |
+| `timeZone`       | No       | tenant tz    | IANA name. Falls back to `auth.tenant.time_zone`.                                                                                    |
+| `params`         | No       | `{}`         | Static parameters passed to the action as `__params`. For runtime values, use folder-scoped module settings.                         |
+| `enabled`        | No       | `true`       | `false` fully disables — no scheduler, no manual trigger.                                                                            |
+| `paused`         | No       | `false`      | Soft pause. Scheduler skips, but "Run now" still works.                                                                              |
+| `description`    | No       |              | Human-readable description.                                                                                                          |
+
+**Hard cap: 50 jobs per module.**
+
+## Cron — five fields
+
+```
+minute  hour  day-of-month  month  day-of-week
+
+0 2 * * *      # daily at 02:00 in the job's tz
+*/15 * * * *   # every 15 minutes
+0 9 * * 1-5    # 09:00 weekdays
+0 0 1 * *      # midnight on the first of each month
+```
+
+## Writing the action
+
+Scheduled actions run with **no record bound**. Specifically:
+
+- `user_id = 0` (system user sentinel)
+- No `folder_id` — query / insert against the tenant DB directly
+- `notify()` writes to inbox only (no live SSE in Phase 1)
+- `sendEmail()` raw mode only in Phase 1
+
+**Record context is forbidden.** The install pipeline rejects any action whose compiled DSL references `[field]` or `for x in records { … }` — those compile to `__r.` / `__records.` which would `ReferenceError` at fire time. Refactor to operate via `query()` / `insert()`:
+
+```
+execute:
+    let cutoff = now() - days(30)
+    let drafts = query("SELECT invoice_id FROM invoice WHERE status = 'draft' AND created_date < @cutoff",
+                       { cutoff: cutoff })
+    for d in drafts {
+        callAction('archive_invoice', { invoice_id: d.invoice_id })
+    }
+```
+
+Hide the action from the UI with `canExecute: false` — the scheduler bypasses the check:
+
+```
+canExecute:
+    false
+
+execute:
+    // cron-only logic
+```
+
+## Reference example (the `chore` module)
+
+**`logic/jobs.json`**
+```json
+{
+    "jobs": [
+        {
+            "code": "tick",
+            "description": "Smoke test — fires every minute.",
+            "action": "log_tick",
+            "schedule": "* * * * *",
+            "timeout": 30
+        }
+    ]
+}
+```
+
+**`ui/actions.json`**
+```json
+{
+    "log_tick": {
+        "description": "Insert a chore_log row marking a scheduler tick",
+        "label": "Log Tick",
+        "icon": "bi-clock-history",
+        "entityCode": "chore_log",
+        "executionMode": "single",
+        "script": "log_tick",
+        "isTransacted": true,
+        "orderNum": 10
+    }
+}
+```
+
+**`logic/actions/log_tick.dsl`**
+```
+execute:
+    insert('chore_log', {
+        ran_at: now(),
+        message: 'Scheduler tick',
+        source: 'cron'
+    })
+```
+
+Full source: [`modules/chore/`](../../../modules/chore/).
+
+## Common mistakes
+
+- **Cross-module action reference.** A job in `crm` cannot reference an action in `fin`. Declare a thin `crm.run_fin_thing` action in your own module and bind the job to that.
+- **Record-bound action.** Any `[field]` or `for x in records` in the DSL fails install — the action has no record at fire time. Refactor to `query()`/`insert()`.
+- **Missing `timeout`.** Required, no default. Pick 30 s if you don't know; bump when you have evidence.
+- **`timeout > 300` without `class: "long_running"`.** Install fails. Heavy jobs are an explicit opt-in.
+- **Sub-minute cron.** The scheduler ticks every 60 s. Anything finer is dishonest — declare a minute cron.
+- **Renaming `code` between versions.** Treats it as a new job and leaves the old `scheduled_job` row orphaned until uninstall (actually reaped on upgrade — but you lose `job_run` history). Keep `code` stable.
+- **"Schedule this 5 minutes from now" pattern.** There is no per-call `schedule()`. Use a cron-scan job that watches a queue table — see [memory: cron-scan pattern](../../../docs/business-logic/jobs.md#when-to-use-a-job-vs-a-trigger).
+- **Confusing `enabled` and `paused`.** `enabled: false` → "Run now" no-ops. `paused: true` → cron skips but "Run now" works. Use `paused` for incident response; use `enabled: false` when you mean "turn this off entirely".
+
+## Reference
+
+- Full developer guide: [`docs/business-logic/jobs.md`](../../../docs/business-logic/jobs.md)
+- JSON Schema: [`docs/schemas/jobs.schema.json`](../../../docs/schemas/jobs.schema.json)
+- Reference module: [`modules/chore/`](../../../modules/chore/)
+- Source (registrar): `server/src/dForge.Admin/Services/ModuleInstall/JobRegistrar.cs`
+- Source (scheduler worker): `server/src/dForge.Scheduler/SchedulerWorker.cs`

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

@@ -0,0 +1,123 @@
+# Module Manifest Reference
+
+Every dForge module has a `manifest.json` at its root. This file declares the module's identity, version, dependencies, and the list of files that make up the package.
+
+## Minimal example
+
+```json
+{
+    "packageFormat": 1,
+    "moduleId": "10000000-0000-0000-0000-000000000001",
+    "code": "my_module",
+    "version": "0.1.0",
+    "dbSchemaVersion": "0.0.1",
+    "displayName": "My Module",
+    "description": "A module that does a thing.",
+    "author": { "name": "Your Name" },
+    "license": "MIT",
+    "category": "other",
+    "tags": ["tag1", "tag2"],
+    "icon": "bi-box",
+    "dependencies": {
+        "admin": ">=0.0.1"
+    },
+    "created": "2026-04-08",
+    "updated": "2026-04-08",
+    "entities": {
+        "my_entity": "./entities/my_entity.json"
+    }
+}
+```
+
+## Required fields
+
+| Field | Type | Description |
+|---|---|---|
+| `packageFormat` | number | Package format version. Always `1` for now. |
+| `moduleId` | UUID | Globally unique module identifier. Generate a fresh UUID for new modules; never reuse. |
+| `code` | string | Short identifier, lowercase, letters+digits+underscores. **Becomes the DB schema name.** Cannot be changed after install. |
+| `version` | semver | Module version. Bump on every release. |
+| `dbSchemaVersion` | semver | Schema version. Bump when the DB schema changes (column add/remove, new entity, etc.). |
+| `displayName` | string | Human-readable name shown in the UI and marketplace. |
+| `description` | string | One-line summary of what the module does. |
+
+## Optional but recommended
+
+| Field | Type | Description |
+|---|---|---|
+| `author` | object | `{name, email?, url?}` |
+| `license` | string | SPDX identifier (e.g. `"MIT"`, `"Apache-2.0"`) |
+| `category` | string | Marketplace category slug (e.g. `"sales"`, `"hr"`, `"other"`) |
+| `tags` | string[] | Search tags |
+| `icon` | string | Bootstrap icon name (e.g. `"bi-briefcase"`) or similar |
+| `dependencies` | object | Map of `module_code → semver range` |
+| `created`, `updated` | ISO date | Timestamps |
+
+## Content declarations
+
+The manifest lists every file in the package by logical key. The installer reads each path relative to the manifest.
+
+| Key | Type | Shape |
+|---|---|---|
+| `entities` | object | `{ "entity_code": "./entities/entity.json" }` |
+| `entityViews` | object | `{ "view_name": "./ui/entity_views/view.json" }` (optional) |
+| `dataViews` | string | path to `./ui/data_views.json` (or object with per-view files) |
+| `menus` | string | path to `./ui/menus.json` |
+| `actions` | object | Actions defined in `./ui/actions.json`, DSL in `./logic/actions/*.dsl` |
+| `reports` | object | `{ "report_code": "./ui/reports/report.json" }` |
+| `settings` | string | path to `./settings.json` |
+| `security` | object | `{ "roles": "./security/roles.json", "folders": "./ui/folders.json" }` |
+| `seedData` | array | List of paths to seed files, in install order |
+| `supportedLocales` | string[] | IETF locale tags that the module ships translations for, e.g. `["de-DE", "uk-UA"]`. Files are **auto-discovered** at `./translations/{locale}.json` — there is no per-file manifest entry. English (`en`/`en-*`) is the default and must not be listed. |
+| `printTemplates` | object | `{ "template_code": "./print_templates/template.scriban" }` |
+| `webhooks` | string | path to `./webhooks.json` |
+
+## Dependencies
+
+Dependencies are a map of module codes to semver ranges. The installer checks that all listed dependencies are installed with compatible versions before installing your module.
+
+```json
+"dependencies": {
+    "admin": ">=0.0.1",
+    "fin": ">=0.1.0 <0.2.0"
+}
+```
+
+**Always depend on `admin`** unless you have a very unusual module — admin provides the user/role system every other module needs.
+
+**For bridge modules** (`crm-fin`, `wms-fin`, etc.), depend on both sides:
+
+```json
+"dependencies": {
+    "admin": ">=0.0.1",
+    "crm": ">=0.1.0",
+    "fin": ">=0.1.0"
+}
+```
+
+## Extension entities
+
+Modules can extend entities owned by other modules. Declare these in `entities` with dotted keys:
+
+```json
+"entities": {
+    "my_extra_entity": "./entities/my_extra_entity.json",
+    "fin.invoice": "./entities/fin.invoice.json"  // extends fin's invoice
+}
+```
+
+The extension file has `"extends": "fin.invoice"` inside. See MODULE_CONVENTIONS.md for details.
+
+## What NOT to put in the manifest
+
+- **Do not** add a `translations` key (e.g. `"translations": { "en-US": "..." }`). There is **no** such manifest field — translation files are auto-discovered at `./translations/{locale}.json`, and non-English locales are declared in `supportedLocales` (English is never listed). The manifest schema is `additionalProperties: false`, so a stray `translations` key fails install.
+- **Do not** put entity definitions inline. Always reference external files.
+- **Do not** list sample or test files — only content that ships with the module.
+- **Do not** include `system: true` unless this is a dForge platform module (`admin`, `metadata`). Regular modules omit it (defaults to `false`).
+- **Do not** hardcode absolute paths. Everything is relative to the manifest.
+
+## Versioning notes
+
+- Bump `version` on every release (bug fix, feature add, etc.).
+- Bump `dbSchemaVersion` **only** when the DB schema changes. If you added an action but no new columns, `version` goes up but `dbSchemaVersion` stays the same.
+- The installer uses `dbSchemaVersion` to decide whether to run migrations.

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

@@ -0,0 +1,164 @@
+# Menus Reference
+
+Menus define the module's navigation tree. Shown in the sidebar when the module is installed.
+
+Lives in: `ui/menus.json`
+
+## Structure — root wrapper with `items`, then nested dictionaries with `children`
+
+**The real format** (from all reference modules — CRM, HR, Fin, WMS):
+
+```json
+{
+    "todo_menu": {
+        "label": "Todos",
+        "items": {
+            "lists": {
+                "orderNum": 1,
+                "label": "Lists",
+                "icon": "list-ul",
+                "children": {
+                    "all_lists": {
+                        "itemType": "V",
+                        "dataViewCode": "todo_list_grid",
+                        "orderNum": 1,
+                        "label": "All Lists",
+                        "icon": "list-ul"
+                    }
+                }
+            },
+            "items": {
+                "orderNum": 2,
+                "label": "Items",
+                "icon": "check2-square",
+                "children": {
+                    "all_items": {
+                        "itemType": "V",
+                        "dataViewCode": "todo_item_grid",
+                        "orderNum": 1,
+                        "label": "All Items",
+                        "icon": "check-square"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+Structure: **root key** → `label` + `items` → **section nodes** (with `children`) → **leaf nodes** (with `itemType` + data view/report code).
+
+## Item types (leaf nodes only)
+
+| `itemType` | Description | Required field |
+|---|---|---|
+| `"V"` | Data view | `dataViewCode` |
+| `"R"` | Report | `reportCode` |
+| `"D"` | Dashboard | `dashboardCode` |
+| `"A"` | Action | `actionCode` |
+
+**Section nodes** (with `children`) **omit `itemType`**. Only leaf items have it.
+
+## Icons
+
+In `ui/menus.json`, icons use Bootstrap icon names **without the `bi-` prefix**:
+
+- `"graph-up-arrow"` (not `"bi-graph-up-arrow"`)
+- `"people"` (not `"bi-people"`)
+- `"briefcase"` (not `"bi-briefcase"`)
+- `"receipt"`, `"building"`, `"calendar-event"`, `"box-seam"`, etc.
+
+**Note:** This no-prefix rule applies to module menu definitions. In other contexts, such as action registration, the icon value may need the full Bootstrap class name **with** the `bi-` prefix (for example, `"bi-graph-up-arrow"`). Always follow the format required by the specific configuration you are editing.
+See https://icons.getbootstrap.com/ for the full catalog. Common choices:
+
+- `people` — users/contacts
+- `briefcase` — work/business
+- `building` — companies/accounts
+- `cart` — sales/orders
+- `graph-up` — reports/analytics
+- `gear` — settings
+- `receipt` — invoices/quotes
+- `calendar-event` — activities/dates
+- `box-seam` — products/items
+- `kanban` — pipeline/board views
+
+## Real example from CRM module
+
+```json
+{
+    "crm_menu": {
+        "label": "Sales CRM",
+        "items": {
+            "sales": {
+                "orderNum": 1,
+                "label": "Sales",
+                "icon": "graph-up-arrow",
+                "children": {
+                    "leads": {
+                        "itemType": "V",
+                        "dataViewCode": "leads",
+                        "orderNum": 1,
+                        "label": "Leads",
+                        "icon": "person-plus"
+                    },
+                    "opportunities": {
+                        "itemType": "V",
+                        "dataViewCode": "opportunities",
+                        "orderNum": 3,
+                        "label": "Opportunities",
+                        "icon": "trophy"
+                    },
+                    "sales_pipeline_report": {
+                        "itemType": "R",
+                        "reportCode": "sales_pipeline",
+                        "orderNum": 6,
+                        "label": "Sales Pipeline Report",
+                        "icon": "file-earmark-bar-graph"
+                    }
+                }
+            },
+            "customers": {
+                "orderNum": 3,
+                "label": "Customers",
+                "icon": "people",
+                "children": {
+                    "accounts": {
+                        "itemType": "V",
+                        "dataViewCode": "accounts",
+                        "orderNum": 1,
+                        "label": "Accounts",
+                        "icon": "building"
+                    },
+                    "contacts": {
+                        "itemType": "V",
+                        "dataViewCode": "contacts",
+                        "orderNum": 3,
+                        "label": "Contacts",
+                        "icon": "person-lines-fill"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+## Required rules
+
+1. **Root wrapper key** (e.g. `"crm_menu"`) with a `label` and `items` property.
+2. **`items`** contains the section nodes, **not** direct leaf items at the top level.
+3. **`dataViewCode`**, not `viewCode`. The wrong name silently fails.
+4. **Section nodes have `children`**, leaf nodes have `itemType` + code.
+5. **`orderNum` controls display order** within a level.
+6. **`label` is required** on every node.
+7. **`icon` is optional** but recommended. Use Bootstrap icon names **without** `bi-` prefix.
+
+## Common mistakes
+
+- Skipping the root wrapper (no `{root_key: {label, items}}`) — **wrong**. All reference modules use this structure.
+- Using arrays like `"children": [...]` — **wrong**. Must be a dictionary.
+- Using `viewCode` instead of `dataViewCode` — **wrong**.
+- Putting `itemType: "V"` on a section node with `children` — **wrong**. Omit `itemType` on sections.
+- Using `"bi-people"` as the icon — **wrong in module menus**. Use `"people"` (no prefix).
+- Forgetting `label` — **required**.
+- Putting leaf items directly inside `items` without a section wrapper — **technically works** but doesn't match conventions.

package/skills/dforge-mcp-author/references/number-sequences.md

@@ -0,0 +1,117 @@
+# Number Sequences Reference
+
+dForge has built-in **automatic document numbering**. Declare a sequence on an entity, and any INSERT that leaves the target column empty gets the next value assigned automatically — no DSL, no manual counter, no race conditions.
+
+## Declaring on an entity
+
+```json
+{
+    "description": "Invoices",
+    "dbObject": "invoice",
+    "toString": "{number}",
+    "traits": ["identity", "audit"],
+    "numberSequence": {
+        "column": "number",
+        "pattern": "INV-{yyyy}-{seq:4}",
+        "resetPeriod": "year"
+    },
+    "fields": {
+        "number": {
+            "dbDatatype": "varchar",
+            "fieldTypeCd": "text",
+            "flags": "VEM",
+            "maxLen": 50,
+            "orderNum": 10,
+            "description": "Invoice Number"
+        },
+        /* ... */
+    }
+}
+```
+
+The platform:
+
+1. On INSERT, checks if the `number` column is empty.
+2. If empty, atomically increments the counter and formats the value.
+3. Writes it into the column before the row is committed.
+
+No code needed on your side. No DSL. No race conditions (the counter uses a database-level atomic operation).
+
+## Pattern placeholders
+
+| Placeholder | Meaning | Example |
+|---|---|---|
+| `{yyyy}` | 4-digit year | `2026` |
+| `{yy}` | 2-digit year | `26` |
+| `{mm}` | 2-digit month | `04` |
+| `{dd}` | 2-digit day | `08` |
+| `{seq:N}` | Zero-padded counter with N digits | `{seq:3}` → `001`, `002`, ... |
+
+You can combine them freely:
+
+```
+"INV-{yyyy}-{seq:4}"           → "INV-2026-0001"
+"Q{yyyy}{mm}-{seq:3}"          → "Q202604-001"
+"{dd}/{mm}/{yyyy}-{seq:2}"     → "08/04/2026-01"
+"PO-{seq:6}"                   → "PO-000001"
+```
+
+## Reset periods
+
+`resetPeriod` controls when the counter resets to 1:
+
+| Value | Resets |
+|---|---|
+| `"never"` | Counter never resets (monotonic forever) |
+| `"year"` | Counter resets on Jan 1 |
+| `"month"` | Counter resets on the 1st of each month |
+| `"day"` | Counter resets daily |
+
+If the pattern uses `{yyyy}` but `resetPeriod` is `"never"`, you get the same number each year — probably not what you want. Match the reset period to the pattern.
+
+## Prefix resolution via settings
+
+For multi-tenant or multi-folder setups, prefixes can come from module settings instead of being hardcoded. Declare a setting:
+
+```json
+// settings.json
+{
+    "invoice_prefix": {
+        "fieldTypeCd": "text",
+        "defaultValue": "INV",
+        "label": "Invoice Prefix"
+    }
+}
+```
+
+And reference it in the pattern:
+
+```
+"pattern": "$[invoice_prefix]-{yyyy}-{seq:4}"
+```
+
+Folder-scoped settings mean different folders can have different prefixes (e.g. `US-INV-2026-0001` in the US folder, `EU-INV-2026-0001` in the EU folder).
+
+## Cross-module sequences
+
+Sequences can be called from other modules via `nextNumber('<module>.<entity>')` in DSL actions:
+
+```
+execute:
+    invoice_num = nextNumber("fin.invoice")
+    notify("Next invoice number: " + invoice_num)
+```
+
+But most of the time, you don't need this — the automatic INSERT behaviour is enough.
+
+## Storage
+
+Counters are stored in `dForge.number_sequence` (definitions) and `dForge.number_sequence_counter` (atomic values). Don't touch these tables directly.
+
+## Common mistakes
+
+- Declaring a number column without a `numberSequence` and manually counting in a DSL — **unnecessary**. Use the platform.
+- Using `{seq}` without a width — the counter has no padding. Use `{seq:N}`.
+- Mismatching `resetPeriod` and placeholders — e.g. `resetPeriod: "month"` with a pattern like `{yyyy}-{seq:4}` (no month) means Jan and Feb start at 1 producing duplicate numbers.
+- Trying to set the number column manually on INSERT — it will be overwritten (unless you provide a non-null value, in which case the sequence respects it).
+- Forgetting `numberSequence` declaration and expecting it to "just work" — needs to be declared per entity.