@dforge-core/dforge-mcp 0.1.1 → 0.1.2

package/docs/creating-modules.md

@@ -101,9 +101,10 @@ Settings (`dforge_setting_add`), translations, seed data — only if intake decl
 
 ### Phase 6 — Verify (required, non-skippable)
 
-1. `dforge_module_pack` → `.dforge` tarball.
-2. `dforge_module_install` against your tenant (uses `DFORGE_URL` / `DFORGE_TOKEN` env or arg fallbacks). Runs the full server-side validator — the only real validator.
-3. On failure, the AI follows the **backtrack protocol**: stops, names the issue, identifies the earliest broken phase, asks for sign-off, patches with the smallest tool that fits, re-inspects, resumes.
+1. `dforge_module_validate` → offline cross-reference validation. The AI fixes every error before packing.
+2. `dforge_module_pack` → `.dforge` tarball.
+3. `dforge_module_install` against your tenant (uses `DFORGE_URL` / `DFORGE_TOKEN` env or arg fallbacks). Runs the full server-side validator — the only real validator.
+4. On module-defect failure, the AI reads the returned raw CLI `output`, fixes the referenced module files, and repeats validate → pack → install. It asks the user only for environment/tooling problems such as missing CLI, expired credentials, unreachable tenant/API, permissions, or a path outside the workspace.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"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/skills/dforge-mcp-author/SKILL.md

@@ -45,8 +45,8 @@ The phase column below indicates the **typical** use. During a backtrack, the ba
 | `dforge_role_right_set` | 5 | Grant / revoke one right on one object |
 | `dforge_folder_add` | 5 | Security folder (optional) |
 | `dforge_dependency_add` | any | Add a dep on another module |
-| `dforge_module_pack` | 6 | Produce .dforge tarball (needs dforge-cli on PATH) |
-| `dforge_module_install` | 6 | Install to tenant — the real validator |
+| `dforge_module_pack` | 6 | Produce .dforge tarball via bundled dforge-cli, PATH fallback, or `DFORGE_CLI_BINARY` |
+| `dforge_module_install` | 6 | Install to tenant — the real validator; returns raw CLI output for the install-fix loop |
 
 **Phase 0 (0a–0d) is owned by `dforge_module_plan`.** Call `dforge_module_plan({ action: "check", moduleDir })` to start or resume Phase 0. The tool returns the current state and exact next steps. Do not call `dforge_module_create` until the tool reports `readyToScaffold: true` — the tool enforces this gate programmatically.
 
@@ -128,14 +128,15 @@ Always-on cheat-sheet — enough to author inline; load the linked `references/*
 If any MCP tool returns an error at any time:
 
 1. **Surface the raw error verbatim** to the user. Do not paraphrase.
-2. **Do not attempt a workaround** with a different tool or hand-crafted JSON.
-3. **Ask the user to resolve the tool-level issue** (missing dep, bad path, schema validation, etc.) before continuing.
+2. **Classify the error before asking the user for help.** If the raw output names a module/package defect, fix the module yourself using the smallest appropriate tool or direct file edit allowed by the host agent, then re-run the required validation loop. Do not ask the user to paste the error back to you — it is already in the tool result.
+3. **Ask the user to resolve only environment/tooling issues** you cannot fix from module files: missing CLI, missing/expired credentials, unreachable tenant/API, permissions, or a bad module path outside the workspace.
 4. **Do not advance the phase** until the failing tool succeeds.
 
 Two specific tool errors have known causes worth distinguishing:
 
 - **`dforge_module_pack` / `_install` reports "command not found" or PATH error**: dforge-cli isn't installed. Tell the user: "dforge-cli is not on your PATH. Install with `npm install -g @dforge-core/dforge-cli`, then re-run. Do not continue Phase 6 until resolved."
 - **`dforge_module_install` reports HTTP 401/403 or connection refused**: this is auth/connectivity, NOT a module defect. Tell the user: "This appears to be a credentials or connectivity issue, not a module defect. Verify `DFORGE_URL` and `DFORGE_TOKEN` before re-running install." Do not backtrack to earlier phases.
+- **`dforge_module_install` returns `ok: false` with validation/import/compile/schema output**: this is a module defect. Treat `output` as the source of truth, fix the referenced files, and run Phase 6 again from automated validation. Keep repeating until install succeeds or the remaining error is clearly environment/tooling.
 
 ## Resume-from-partial-state
 
@@ -416,7 +417,15 @@ Get user confirmation on both version strings before packing.
 1. `dforge_module_pack` → produces `.dforge` tarball. (Blocked if any entity lacks a role granting Select — the Phase 5a gate; fix security coverage and re-run.)
 2. `dforge_module_install` with `DFORGE_URL` / `DFORGE_TOKEN`. Runs the full server-side validator.
 
-**If install fails on a module defect**, use this table to identify which phase to backtrack to, then apply the backtrack protocol, fix, re-run Steps 1–2 (validate + self-review), and re-pack:
+**Install-fix loop (mandatory):**
+
+1. Call `dforge_module_install` yourself. Do not ask the user to run the install command for you.
+2. If the result has `ok: false`, read the returned `output` in full. It is the raw CLI/server validator output and is the input for the next fix.
+3. If the failure is a module defect, fix it yourself. Use this table to identify which phase to backtrack to, then apply the backtrack protocol with the smallest suitable tool or file edit.
+4. Re-run Step 1 (`dforge_module_validate`), Step 2 (self-review for the touched area), Step 5 pack, and Step 5 install.
+5. Repeat this loop until install succeeds or the remaining failure is clearly an environment/tooling issue from the Tool failure protocol.
+
+Common module-defect patterns:
 
 | Install error pattern | Backtrack to |
 |---|---|
@@ -438,6 +447,8 @@ When a later phase exposes a problem in an earlier phase, follow steps 1–6 IN
 
 **Multi-trigger rule (deterministic):** If multiple phases simultaneously expose gaps in earlier phases (e.g. Phase 3 needs a field; Phase 5 needs an action), resolve the **earliest-phase gap first**, complete its full backtrack, run `dforge_module_inspect`, then evaluate remaining gaps.
 
+**Phase 6 install exception:** when `dforge_module_install` fails with a clear module defect (schema validation, missing file/key, translation completeness, DSL compile error, dependency contract, FK/seed/import error), do not ask the user for sign-off before the corrective patch. The server validator has already rejected the package, so fix the referenced files, report what changed, and immediately re-run validate → pack → install. Keep user sign-off for product/design choices or ambiguous fixes.
+
 1. **Stop the current phase.** Don't paper over or improvise.
 2. **Name the issue precisely.** "Phase 3 wants a kanban grouped by `lead_status`, but Phase 1 didn't define `lead_status` on entity `lead`."
 3. **Identify the target phase + decision.** "Backtrack to Phase 1: add field `lead_status` to entity `lead`."

package/skills/dforge-mcp-author/references/data-views.md

@@ -161,9 +161,11 @@ A pivot grid. The view's primary `dataSources` entity is the **cell** entity (on
 
 **`rowAxis` / `colAxis`** — what the rows and columns are. Three `kind`s:
 
-- `"dataset"` — axis values are an entity's records. `entity` + `labelField` required; optional `keyField` (defaults to the axis entity PK — what the cell's `rowKey`/`colKey` matches), `lockedField` (boolean column → that axis value's cells are read-only), `filter` (same `{c,o,v}` grammar as everywhere — scopes which axis records load), `hideEmpty` (**column axis only** — drop columns with no cell record in any row, e.g. periods with no postings; ignored if it would blank the whole grid), `sort` (`[{ col, dir }]`).
-- `"dropdown"` — axis values are a dropdown/flags column's options. Just `kind` + `column` (an `"entity.column"` reference). Codes line up by construction.
-- `"date"` — generated date window, **column axis only** (not valid on `rowAxis`). `kind` + `grain: "day"` + `window: "week"` (v1).
+- `"dataset"` — axis values are an entity's records. `entity` + `labelField` required; optional `keyField` (defaults to the axis entity PK — what the cell's `rowKey`/`colKey` matches), `lockedField` (boolean column → that axis value's cells are read-only), `filter` (same `{c,o,v}` grammar as everywhere — scopes which axis records load), `hideEmpty` (**column axis only** — drop columns with no cell record in any row, e.g. periods with no postings; ignored if it would blank the whole grid), `rangeControl` (**column axis only** — show a From/To range control so the user can narrow the visible columns to a span; persists in view options; composes with `hideEmpty`), `sort` (`[{ col, dir }]`).
+- `"dropdown"` — axis values are a dropdown/flags column's options. `kind` + `column` (an `"entity.column"` reference); optional `values` (`[...]` of option value codes — a subset + order of columns, chosen the way kanban lanes are; omit to show every option in field order). Codes line up by construction.
+- `"date"` — generated date window, **column axis only** (not valid on `rowAxis`). `kind` + `grain: "day"` + `window: "week"` (v1). *Roadmap (designed, not built): arbitrary `range` (`{from, to}`) + `grain` (`day`/`week`/`month`/`quarter`/`year`), surfaced as a date-picker variant of the range bar — lets a time matrix generate its columns instead of needing seeded period records. Don't author against it yet.*
+
+> **The matrix is source-agnostic.** A matrix is just config over generic entities: point the cell at *any* dated/keyed entity that fits your model — a pre-aggregated registry (e.g. `gl.balance_register`, fast but period-grained), raw dated movements (any-grain, heavier), or your own table. `gl` is a regular, replaceable module, not a platform requirement; nothing about the matrix knows or needs "gl". Choosing a pre-aggregated source vs raw rows (and the grain) is a per-view config decision, with the usual perf-vs-flexibility trade.
 
 **`cell`** — the value-source record at each intersection. `entity` (must match the primary dataSource), `rowKey` / `colKey` (cell columns matching the row/column axis keys), `fields` (cell columns rendered in each cell). Optional: `cardinality: "one"` (v1 default), `editable`, `drill` (read-only cells become clickable → open the cell record and its child sets), `seedFromRow` (`{ cellField: rowAxisField }` copied into new cell records on insert), `seedCurrentUser` (cell fields set to the current user id on insert).
 

package/skills/dforge-mcp-author/references/validation-checklist.md

@@ -1,6 +1,6 @@
 # Validation Checklist
 
-Run through this checklist **before** declaring a module complete. Do it mentally if there's no validate CLI available; run `dforge validate .` if there is.
+Run through this checklist **before** declaring a module complete. Always start with `dforge_module_validate` when the MCP server is connected; if you are outside MCP, use the current CLI equivalent: `dforge-cli module validate <moduleDir>`.
 
 ## Top install-blockers (scan first)
 
@@ -154,10 +154,11 @@ For each action:
 
 ## After validation
 
-- [ ] If a local `dforge validate .` CLI is available, run it and fix any errors
-- [ ] Try to `dforge package .` to build the `.dforge` file — it should succeed
-- [ ] If MCP is connected, run `dry_run_install` to see the generated SQL
-- [ ] Only after dry-run looks clean, `install_module` or `install-to-dev`
+- [ ] Run `dforge_module_validate` and fix every `error` in `files["_validate.json"]`
+- [ ] Run `dforge_module_pack` to build the `.dforge` file — it should succeed
+- [ ] Run `dforge_module_install` against a real test tenant — this is the full server-side validator
+- [ ] If `dforge_module_install` returns `ok: false`, read the returned `output`, fix the module defect it reports, then repeat validate → pack → install
+- [ ] Stop and ask the user only for environment/tooling failures: missing CLI, missing/expired token, unreachable tenant/API, permissions, or a path outside the workspace
 
 ## Red flags during review
 
@@ -180,4 +181,4 @@ If you see any of these, stop and investigate:
 
 ## When the checklist passes
 
-Tell the user what you built, summarize the entity model (e.g. "7 entities: contact, account, opportunity with its line items, quote with lines, activity, product"), list the data views and actions, and describe the security roles. Then ask if they want to install it.
+Tell the user what you built, summarize the entity model (e.g. "7 entities: contact, account, opportunity with its line items, quote with lines, activity, product"), list the data views and actions, describe the security roles, and run the Phase 6 install loop. The module is not complete until `dforge_module_install` succeeds against a real tenant.