@dforge-core/metadata 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,144 @@
+# @dforge-core/metadata
+
+Canonical dForge authoring registries, module-file types, and JSON schemas — the
+single source of truth shared by the web app, the SDK, the diagram library, the
+CLI, the MCP server, and the VS Code extension.
+
+- **Runtime-dependency-free.** Safe to import anywhere — editors, bundled web
+  apps, Node CLIs, MCP servers.
+- **One source of truth.** The registries mirror the platform metadata seed
+  (`server/database/system-modules/metadata/seed-data/`) and the structural
+  types mirror the JSON schemas under `docs/schemas/`. Parity tests fail the
+  build if either drifts.
+
+## Install
+
+```sh
+pnpm add @dforge-core/metadata
+```
+
+## What's inside
+
+| Surface | Exports |
+| --- | --- |
+| **Field types** | `fieldTypes`, `fieldTypeCds`, `isFieldTypeCd`, `getFieldType`, `fieldTypesByColumnType` |
+| **Base datatypes** | `baseDatatypes`, `baseToDbDatatype` |
+| **Column types** | `columnTypes`, `getColumnType` |
+| **Traits** | `traits`, `getTrait`, `expandTrait`, `expandTraits` |
+| **Derivation** | `deriveDbDatatype`, `deriveBaseDatatype`, `defaultParams`, `NUMERIC_TOTAL` |
+| **Aggregation** | `AggType`, `AGG_TYPE_LIST` |
+| **Display flags** | `flagDefs` (`V` Visible · `I` Identity · `E` Editable · `M` Mandatory · `H` Hidden) |
+| **View / report kinds** | `dataViewKinds`, `vizTypes`, `chartTypes` |
+| **Scalar enums** | `FieldTypeCd`, `BaseDatatypeCd`, `ColumnTypeCd`, `FlagCd`, `AlignType` |
+| **Module-file types** | `ManifestDef`, `EntityDef`, `DataViewsFile`, `ReportsFile`, `MenusFile`, `FoldersFile`, `RolesFile`, `SettingsFile`, `JobsFile`, `TriggersFile`, `WebhooksFile`, `PrintTemplatesFile`, `SeedDataFile`, `ActionsFile`, … |
+| **Filter expression** | `Filter`, `FilterCondition`, `FilterGroup`, `SortClause` |
+| **JSON schemas** | `./schemas/<name>.schema.json` (see [Schemas](#json-schemas)) |
+
+## Registries & derivation
+
+An author picks a friendly `fieldTypeCd`; the helpers derive the physical
+metadata so no one types a raw SQL type by hand.
+
+```ts
+import {
+  getFieldType,
+  isFieldTypeCd,
+  deriveDbDatatype,
+  deriveBaseDatatype,
+  defaultParams,
+} from "@dforge-core/metadata";
+
+isFieldTypeCd("currency");          // true
+isFieldTypeCd("reference");         // false — not a real code (it's `lookup`)
+
+getFieldType("currency");
+// { cd: "currency", columnType: "D", baseDatatypeCd: "number", precision: 2, ... }
+
+deriveDbDatatype("currency");       // "numeric(18,2)"
+deriveDbDatatype("text");           // "varchar"
+deriveDbDatatype("textarea");       // "text"
+deriveDbDatatype("lookup");         // null — relationship-backed, no own column
+deriveBaseDatatype("color");        // "string"
+defaultParams("number");            // { min: 0, max: 10000 }
+```
+
+### Traits
+
+```ts
+import { expandTrait, expandTraits } from "@dforge-core/metadata";
+
+// Expand a trait into the FieldDef map it contributes to an entity.
+expandTrait("audit", "invoice");
+expandTraits(["identity", "audit"], "invoice");
+```
+
+## Module-file types
+
+The structural types describe the *authoring* shape of every file in a `.dforge`
+module package — the same shapes the JSON schemas validate.
+
+```ts
+import type { ManifestDef, EntityDef, DataViewsFile } from "@dforge-core/metadata";
+
+const entity: EntityDef = {
+  description: "Customer",
+  dbObject: "customer",
+  fields: {
+    /* … */
+  },
+};
+```
+
+> Note: these are the **authoring** shapes. The resolved **runtime** model
+> returned by the API (`metadata.getModel`) is a different contract — see
+> `@dforge/sdk`'s `Model*` types, which reuse the scalar enums from this package.
+
+## JSON schemas
+
+The 14 canonical schemas are shipped alongside the types and stay byte-identical
+to `docs/schemas/` (a parity test enforces it; `prepack` re-syncs before
+publish). Import them directly or point a validator / editor at the files.
+
+```ts
+import entitySchema from "@dforge-core/metadata/schemas/entity.schema.json" with { type: "json" };
+```
+
+```jsonc
+// VS Code settings.json — validate module files against the shipped schemas
+"json.schemas": [
+  {
+    "fileMatch": ["entities/*.json"],
+    "url": "./node_modules/@dforge-core/metadata/schemas/entity.schema.json"
+  }
+]
+```
+
+Available: `manifest`, `entity`, `data_views`, `folders`, `menus`, `roles`,
+`settings`, `reports`, `jobs`, `triggers`, `webhooks`, `print_templates`,
+`traits`, `seed_data`.
+
+## Source of truth & parity
+
+This package never edits the canonical sources — it mirrors them and guards the
+mirror:
+
+- **Registries** mirror the platform metadata seed; `test/registries.test.ts`
+  fails if a code drifts from `field_types.json` (and a compile-time coverage
+  guard fails if the `FieldTypeCd` union and the `fieldTypes` array diverge).
+- **Schemas** are copied from `docs/schemas/` by `pnpm sync-schemas`;
+  `test/schemas.test.ts` fails if the shipped copy drifts. `prepack` re-syncs.
+
+When consumed standalone (no monorepo around the package) the parity checks are
+skipped — the shipped data is authoritative on its own.
+
+## Scripts
+
+```sh
+pnpm build          # tsc → dist/
+pnpm test           # vitest (registry + schema parity)
+pnpm sync-schemas   # refresh schemas/ from docs/schemas/
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/metadata",
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"description": "Canonical dForge authoring registries — field types, base datatypes, column types, traits, data-view kinds and chart types — with derivation helpers. Runtime-dependency-free; the single source of truth shared by editors, the web app and the CLI.",
 	"license": "MIT",
 	"author": "dForge",
@@ -33,17 +33,21 @@
 			"source": "./src/index.ts",
 			"types": "./dist/index.d.ts",
 			"default": "./dist/index.js"
-		}
+		},
+		"./schemas/*": "./schemas/*",
+		"./package.json": "./package.json"
 	},
 	"files": [
 		"dist",
-		"src"
+		"src",
+		"schemas"
 	],
 	"scripts": {
+		"sync-schemas": "node scripts/sync-schemas.mjs",
 		"build": "tsc -p tsconfig.build.json",
 		"dev": "tsc -p tsconfig.build.json --watch",
 		"test": "vitest run",
-		"prepack": "pnpm build",
+		"prepack": "pnpm sync-schemas && pnpm build",
 		"package": "pnpm pack"
 	},
 	"devDependencies": {

package/schemas/data_views.schema.json

@@ -0,0 +1,350 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/data_views.schema.json",
+	"title": "dForge Data Views",
+	"description": "Data view definitions for a dForge module",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/dataView"
+	},
+	"$defs": {
+		"dataView": {
+			"type": "object",
+			"required": ["viewType", "dataSources"],
+			"properties": {
+				"viewType": {
+					"type": "string",
+					"enum": ["grid", "list", "kanban", "calendar", "gallery", "tree-grid", "diagram", "master-detail", "library"],
+					"description": "View display type"
+				},
+				"label": {
+					"type": "string",
+					"description": "Human-readable view name"
+				},
+				"icon": {
+					"type": "string",
+					"description": "Bootstrap icon class (e.g. 'bi-bounding-box')"
+				},
+				"description": {
+					"type": "string",
+					"description": "Optional description text shown on view cards"
+				},
+				"dataSources": {
+					"type": "array",
+					"items": {
+						"$ref": "#/$defs/dataSource"
+					},
+					"minItems": 1,
+					"description": "Data sources providing data for this view"
+				},
+				"filter": {
+					"$ref": "#/$defs/filter",
+					"description": "Default filter criteria (applied to all dataSources unless one declares its own)"
+				},
+				"order": {
+					"description": "Default sort order"
+				},
+				"viewConfig": {
+					"type": "object",
+					"description": "View-type-specific configuration"
+				}
+			},
+			"additionalProperties": false,
+			"allOf": [
+				{ "$ref": "#/$defs/rules/kanban" },
+				{ "$ref": "#/$defs/rules/calendar" },
+				{ "$ref": "#/$defs/rules/tree-grid" },
+				{ "$ref": "#/$defs/rules/list" },
+				{ "$ref": "#/$defs/rules/diagram" },
+				{ "$ref": "#/$defs/rules/master-detail" }
+			]
+		},
+
+		"rules": {
+			"kanban": {
+				"if": {
+					"properties": { "viewType": { "const": "kanban" } },
+					"required": ["viewType"]
+				},
+				"then": {
+					"properties": {
+						"viewConfig": { "$ref": "#/$defs/kanbanViewConfig" }
+					}
+				}
+			},
+			"calendar": {
+				"if": {
+					"properties": { "viewType": { "const": "calendar" } },
+					"required": ["viewType"]
+				},
+				"then": {
+					"properties": {
+						"viewConfig": { "$ref": "#/$defs/calendarViewConfig" }
+					}
+				}
+			},
+			"tree-grid": {
+				"if": {
+					"properties": { "viewType": { "const": "tree-grid" } },
+					"required": ["viewType"]
+				},
+				"then": {
+					"properties": {
+						"viewConfig": { "$ref": "#/$defs/treeGridViewConfig" }
+					}
+				}
+			},
+			"list": {
+				"if": {
+					"properties": { "viewType": { "const": "list" } },
+					"required": ["viewType"]
+				},
+				"then": {
+					"properties": {
+						"viewConfig": { "$ref": "#/$defs/listViewConfig" }
+					}
+				}
+			},
+			"diagram": {
+				"if": {
+					"properties": { "viewType": { "const": "diagram" } },
+					"required": ["viewType"]
+				},
+				"then": {
+					"properties": {
+						"viewConfig": { "$ref": "#/$defs/diagramViewConfig" }
+					}
+				}
+			},
+			"master-detail": {
+				"if": {
+					"properties": { "viewType": { "const": "master-detail" } },
+					"required": ["viewType"]
+				},
+				"then": {
+					"properties": {
+						"dataSources": { "minItems": 2 }
+					}
+				}
+			}
+		},
+
+		"kanbanViewConfig": {
+			"type": "object",
+			"required": ["groupByField"],
+			"properties": {
+				"groupByField": {
+					"type": "string",
+					"description": "Column code of a dropdown/flags/reference field to group cards by"
+				}
+			},
+			"additionalProperties": false
+		},
+		"calendarViewConfig": {
+			"type": "object",
+			"required": ["dateField"],
+			"properties": {
+				"dateField": {
+					"type": "string",
+					"description": "Column code of the date/timestamp field used to place events on the calendar"
+				},
+				"titleField": {
+					"type": "string",
+					"description": "Column code of the field displayed as event title. Defaults to the entity's toString template."
+				},
+				"colorField": {
+					"type": "string",
+					"description": "Optional column whose value drives the event pill color. For dropdown/flags columns, colors come from params.options rich form; otherwise a deterministic hash is used."
+				}
+			},
+			"additionalProperties": false
+		},
+		"treeGridViewConfig": {
+			"type": "object",
+			"required": ["parentField"],
+			"properties": {
+				"parentField": {
+					"type": "string",
+					"description": "Column code of the self-referencing FK (parent record)"
+				},
+				"labelField": {
+					"type": "string",
+					"description": "Field to display as node label (defaults to entity toString)"
+				},
+				"iconField": {
+					"type": "string",
+					"description": "Field containing a Bootstrap icon class per node"
+				}
+			},
+			"additionalProperties": false
+		},
+		"listViewConfig": {
+			"type": "object",
+			"properties": {
+				"titleField": {
+					"type": "string",
+					"description": "Column code of the primary display field"
+				},
+				"subtitleField": {
+					"type": "string",
+					"description": "Column code of the secondary display field"
+				},
+				"levels": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/listLevelConfig" },
+					"description": "Hierarchical child levels for expandable list rows"
+				}
+			},
+			"additionalProperties": false
+		},
+		"listLevelConfig": {
+			"type": "object",
+			"required": ["entityCode", "foreignKey"],
+			"properties": {
+				"entityCode": {
+					"type": "string",
+					"description": "Entity code for this child level"
+				},
+				"foreignKey": {
+					"type": "string",
+					"description": "FK column in the child entity linking back to the parent"
+				},
+				"columns": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Columns to display inline for each child row"
+				}
+			},
+			"additionalProperties": false
+		},
+		"diagramViewConfig": {
+			"type": "object",
+			"properties": {
+				"groupByField": {
+					"type": "string",
+					"description": "Column code to group diagram nodes by (e.g. 'module', 'project')"
+				},
+				"defaultHiddenGroups": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Group values to hide by default in the diagram"
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"viewColumn": {
+			"oneOf": [
+				{
+					"type": "string",
+					"description": "Column code (shorthand)"
+				},
+				{
+					"type": "object",
+					"required": ["column_cd"],
+					"properties": {
+						"column_cd": {
+							"type": "string",
+							"description": "Column code"
+						},
+						"width": {
+							"type": "integer",
+							"minimum": 1,
+							"description": "Column width in pixels"
+						},
+						"visible": {
+							"type": "boolean",
+							"default": true,
+							"description": "Whether the column is visible"
+						},
+						"pinned": {
+							"type": "string",
+							"enum": ["left", "right"],
+							"description": "Pin column to left or right edge"
+						}
+					},
+					"additionalProperties": false
+				}
+			]
+		},
+		"dataSource": {
+			"type": "object",
+			"required": ["entityCode"],
+			"properties": {
+				"entityCode": {
+					"type": "string",
+					"description": "Entity code to query"
+				},
+				"level": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Nesting level (0 = root, 1+ = detail). Defaults to 0"
+				},
+				"label": {
+					"type": "string",
+					"description": "Human-readable label for this data source (used in master-detail tabs)"
+				},
+				"columns": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/viewColumn" },
+					"description": "Column configuration — strings or objects with width/visibility"
+				},
+				"parentSetField": {
+					"type": "string",
+					"description": "Set field name on parent entity linking to this detail level"
+				},
+				"filter": {
+					"$ref": "#/$defs/filter",
+					"description": "Per-source filter criteria; overrides the view-level filter for this source"
+				},
+				"order": {
+					"description": "Per-source sort order (array of {c, d} entries, where d is 'asc' or 'desc')"
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"filter": {
+			"description": "Canonical dForge filter expression. Either a single condition `{c, o, v}` or a group `{g, i: [...]}`. Used by data views, reports, folders (row-level security), and the API.",
+			"oneOf": [
+				{ "$ref": "#/$defs/filterCondition" },
+				{ "$ref": "#/$defs/filterGroup" }
+			]
+		},
+		"filterCondition": {
+			"type": "object",
+			"required": ["c", "o"],
+			"properties": {
+				"c": {
+					"type": "string",
+					"description": "Column code (supports dot navigation: 'customer.name')"
+				},
+				"o": {
+					"type": "string",
+					"description": "Operator: eq, neq, =, !=, gt, gtEq, grEq, lt, ltEq, in, nIn, like, isNull, isNotNull, etc."
+				},
+				"v": {
+					"description": "Comparison value. Scalars, arrays (for in/nIn), or parameter references like '@param_code'."
+				}
+			},
+			"additionalProperties": false
+		},
+		"filterGroup": {
+			"type": "object",
+			"required": ["g", "i"],
+			"properties": {
+				"g": {
+					"type": "string",
+					"enum": ["and", "or"],
+					"description": "Group combinator"
+				},
+				"i": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/filter" },
+					"description": "Group items: nested conditions or sub-groups"
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}