@dforge-core/metadata 0.0.31 → 0.0.33

package/package.json

@@ -1,67 +1,68 @@
 {
-  "name": "@dforge-core/metadata",
-  "version": "0.0.31",
-  "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",
-  "homepage": "https://github.com/iash44/dForge-core/tree/main/clients/packages/metadata#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/iash44/dForge-core.git",
-    "directory": "clients/packages/metadata"
-  },
-  "bugs": {
-    "url": "https://github.com/iash44/dForge-core/issues"
-  },
-  "keywords": [
-    "dforge",
-    "metadata",
-    "field-type",
-    "trait",
-    "registry",
-    "low-code"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "source": "./src/index.ts",
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./dsl": {
-      "source": "./src/dsl/index.ts",
-      "types": "./dist/dsl/index.d.ts",
-      "default": "./dist/dsl/index.js"
-    },
-    "./schemas/*": "./schemas/*",
-    "./package.json": "./package.json"
-  },
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "src",
-    "schemas",
-    "CHANGELOG.md"
-  ],
-  "devDependencies": {
-    "@types/node": "^25.9.4",
-    "ajv": "^8.20.0",
-    "tsup": "^8.5.1",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
-  },
-  "scripts": {
-    "sync-schemas": "node scripts/sync-schemas.mjs",
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc -p tsconfig.build.json --noEmit",
-    "test": "vitest run",
-    "package": "pnpm pack"
-  }
-}
+	"name": "@dforge-core/metadata",
+	"version": "0.0.33",
+	"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",
+	"homepage": "https://github.com/iash44/dForge-core/tree/main/clients/packages/metadata#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/iash44/dForge-core.git",
+		"directory": "clients/packages/metadata"
+	},
+	"bugs": {
+		"url": "https://github.com/iash44/dForge-core/issues"
+	},
+	"keywords": [
+		"dforge",
+		"metadata",
+		"field-type",
+		"trait",
+		"registry",
+		"low-code"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"source": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./dsl": {
+			"source": "./src/dsl/index.ts",
+			"types": "./dist/dsl/index.d.ts",
+			"default": "./dist/dsl/index.js"
+		},
+		"./schemas/*": "./schemas/*",
+		"./package.json": "./package.json"
+	},
+	"sideEffects": false,
+	"files": [
+		"dist",
+		"src",
+		"schemas",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"sync-schemas": "node scripts/sync-schemas.mjs",
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"typecheck": "tsc -p tsconfig.build.json --noEmit",
+		"test": "vitest run",
+		"prepack": "pnpm sync-schemas && pnpm typecheck && pnpm build",
+		"package": "pnpm pack"
+	},
+	"devDependencies": {
+		"@types/node": "^25.9.4",
+		"ajv": "^8.20.0",
+		"tsup": "^8.5.1",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.10"
+	}
+}

package/schemas/entity.schema.json

@@ -2,7 +2,7 @@
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"$id": "https://dforge.dev/schemas/entity.schema.json",
 	"title": "dForge Entity Definition",
-	"description": "Defines an entity (table/view mapping) for a dForge module",
+	"description": "Defines an entity (a table) for a dForge module",
 	"type": "object",
 	"anyOf": [
 		{ "required": ["fields"] },
@@ -24,16 +24,7 @@
 		},
 		"dbObject": {
 			"type": "string",
-			"description": "Database table or view name (defaults to entity code)"
-		},
-		"isView": {
-			"type": "boolean",
-			"description": "When true, entity maps to a SQL view (read-only, no DDL generation). Default: false (table-backed).",
-			"default": false
-		},
-		"viewSql": {
-			"type": "string",
-			"description": "SQL SELECT statement for view-backed entities (isView=true). Executed as CREATE OR REPLACE VIEW during module install."
+			"description": "Database table name (defaults to entity code)"
 		},
 		"toString": {
 			"description": "Display pattern using column placeholders, e.g. \"{first_name} {last_name}\" — the caption of a record wherever it is referenced. Every `{placeholder}` must name a field of the entity (trait columns included) and not a set; pack and install fail otherwise. Omitted, the install generates one from the fields and warns. Not declared on extension entities (with `extends`). No `type` constraint here because `toString` collides with Object.prototype.toString in JSON validators — they read the inherited function and reject it, even when the property is absent from the JSON."
@@ -42,6 +33,11 @@
 			"type": "boolean",
 			"description": "Records of this entity accept comments \u2014 the composer and thread appear on the record card, beside the audit history. Opt-in per entity; `comments` in the manifest sets a module-wide default that this overrides in both directions."
 		},
+		"auditHistory": {
+			"type": "string",
+			"enum": ["basic", "fields", "full"],
+			"description": "Audit history level for this entity, overriding the manifest's `auditHistory`: 'basic' logs each insert/update/delete without field details; 'fields' adds old/new values of changed fields; 'full' also stores display values (reference and user names). Omit to disable."
+		},
 		"traits": {
 			"type": "array",
 			"description": "Entity traits expanded during module install (authoring shortcut). Trait definitions loaded from DB (seeded by metadata module).",
@@ -146,7 +142,7 @@
 		},
 		"views": {
 			"type": "object",
-			"description": "Entity views keyed by view name — column-level security. Unrelated to 'isView'/'viewSql' (a SQL-view-backed entity) and to ui/data_views.json (grids, kanban, calendars). A folder binds one view per entity via ui/folders.json (entities.<code>.viewName); users working in that folder see ONLY the columns the view lists. Entities without views show the entity's full column set; a folder naming a view that isn't declared here FAILS the install, since resolving it to nothing would show every column \u2014 the opposite of what naming a view asks for. A view can only be declared by the entity's own module: an extension ('extends') declaring 'views' is rejected, because a view lists the complete column set and an extension knows only the columns it adds.",
+			"description": "Entity views keyed by view name — column-level security. Unrelated to ui/data_views.json (grids, kanban, calendars). A folder binds one view per entity via ui/folders.json (entities.<code>.viewName); users working in that folder see ONLY the columns the view lists. Entities without views show the entity's full column set; a folder naming a view that isn't declared here FAILS the install, since resolving it to nothing would show every column \u2014 the opposite of what naming a view asks for. A view can only be declared by the entity's own module: an extension ('extends') declaring 'views' is rejected, because a view lists the complete column set and an extension knows only the columns it adds.",
 			"propertyNames": {
 				"pattern": "^[a-zA-Z_][a-zA-Z0-9_-]*$",
 				"maxLength": 100
@@ -364,6 +360,14 @@
 						"serverDefault": {
 							"$ref": "#/$defs/serverDefault"
 						},
+						"currency": {
+							"type": "string",
+							"description": "currency field type: fixed ISO 4217 code (e.g. 'USD') the value is formatted in. With currencyColumn, the code used for a record whose currencyColumn is empty."
+						},
+						"currencyColumn": {
+							"type": "string",
+							"description": "currency field type: a scalar column of the same entity holding the ISO 4217 code per record, e.g. a 'currency' dropdown. Each value is formatted in its own record's currency; a total over rows in different currencies shows no symbol. A line reads its header's code through a formula column ([invoice].[currency]). Display only — nothing converts between currencies."
+						},
 						"pattern": {
 							"type": "string",
 							"description": "Format rule for this column, as an ECMAScript regex source. Overrides the field type's own pattern (field_type.def_params.pattern, which is what makes email/phone/url reject a malformed value). Enforced in the browser and again on data.insert / data.update, so keep to constructs both engines read alike: [0-9] and \\d are the same there, \\s is normalized to JavaScript's set, and a pattern that will not compile is skipped by both rather than enforced by one."
@@ -388,7 +392,7 @@
 					"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."
+					"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), and @[ref].[field] nav placeholders that read through a Reference column, as a formula does (e.g. @[purchase_order].[supplier_id] on an order line narrows to the order's supplier, also in the New dialog of the order's Lines set). A condition whose placeholder is unset is dropped rather than matching nothing."
 				}
 			},
 			"oneOf": [

package/schemas/manifest.schema.json

@@ -104,8 +104,8 @@
 		},
 		"auditHistory": {
 			"type": "string",
-			"enum": ["none", "minimal", "full"],
-			"description": "Default audit history mode for entities in this module ('full' captures every field change; 'minimal' captures only inserts/deletes; 'none' disables). Individual entities can override."
+			"enum": ["basic", "fields", "full"],
+			"description": "Default audit history level for entities in this module: 'basic' logs each insert/update/delete without field details; 'fields' adds old/new values of changed fields; 'full' also stores display values (reference and user names). Omit to disable. Individual entities can override."
 		},
 		"comments": {
 			"type": "boolean",

package/schemas/traits.schema.json

@@ -56,6 +56,11 @@
 				"formula": { "type": "string" },
 				"orderNum": { "type": "integer" },
 				"description": { "type": "string", "description": "Supports {entity}/{Entity} placeholders" },
+				"labels": {
+					"type": "object",
+					"description": "Translated labels keyed by culture code (e.g. de-DE). Applied to every entity that takes the field from this trait; the module's translations/<locale>.json overrides them per entity. Supports {entity}/{Entity} placeholders.",
+					"additionalProperties": { "type": "string" }
+				},
 				"maxLen": { "type": "integer" },
 				"link": {
 					"type": "object",

package/schemas/translations.schema.json

@@ -0,0 +1,267 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/translations.schema.json",
+	"title": "dForge Translations",
+	"description": "A module's translations/<locale>.json, e.g. de-DE.json. English is the base text authored in the other module files, so an en-* file is not applied at install. Every key is optional: a missing entry falls back to the base text. Labels are required only for the locales the manifest lists in supportedLocales (constraint messages and DSL messages are warned about, never required).",
+	"type": "object",
+	"additionalProperties": false,
+	"properties": {
+		"$schema": {
+			"type": "string"
+		},
+		"entities": {
+			"type": "object",
+			"description": "Entity code → labels for the entity, its fields, card sections and constraint messages.",
+			"additionalProperties": {
+				"$ref": "#/$defs/entity"
+			}
+		},
+		"domains": {
+			"type": "object",
+			"description": "Column domain code (domains.json) → label and option labels, translated once for every column that uses the domain.",
+			"additionalProperties": {
+				"$ref": "#/$defs/withOptions"
+			}
+		},
+		"folders": {
+			"type": "object",
+			"description": "Folder code → label. A sub-folder is keyed by its own flat code, not its path.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelOnly"
+			}
+		},
+		"views": {
+			"type": "object",
+			"description": "Data view code → label and description (the subtitle under the view title).",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelDesc"
+			}
+		},
+		"menus": {
+			"type": "object",
+			"description": "Menu code → label and item labels.",
+			"additionalProperties": {
+				"$ref": "#/$defs/menu"
+			}
+		},
+		"settings": {
+			"type": "object",
+			"description": "Setting code (settings.json) → label and description.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelDesc"
+			}
+		},
+		"roles": {
+			"type": "object",
+			"description": "Module-qualified role code (e.g. \"crm.admin\") → label.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelOnly"
+			}
+		},
+		"reports": {
+			"type": "object",
+			"description": "Report code → label, dataset captions and parameter labels.",
+			"additionalProperties": {
+				"$ref": "#/$defs/report"
+			}
+		},
+		"actions": {
+			"type": "object",
+			"description": "Action code (ui/actions.json) → label, tooltip and parameter labels.",
+			"additionalProperties": {
+				"$ref": "#/$defs/action"
+			}
+		},
+		"print_templates": {
+			"type": "object",
+			"description": "Print template code → label. Accepted, but not applied at install yet.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelOnly"
+			}
+		},
+		"messages": {
+			"type": "object",
+			"description": "Text of a DSL info() / warn() / error() / exit() call, exactly as written in the .dsl file → its translation. {name} placeholders are filled from the call's values and may be reordered. See docs/business-logic/message-localization.md.",
+			"propertyNames": {
+				"minLength": 1
+			},
+			"additionalProperties": {
+				"type": "string",
+				"minLength": 1
+			}
+		}
+	},
+	"$defs": {
+		"label": {
+			"type": "string",
+			"description": "Translated display label."
+		},
+		"labelOnly": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				}
+			}
+		},
+		"labelDesc": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"desc": {
+					"type": "string",
+					"description": "Translated description or tooltip."
+				}
+			}
+		},
+		"option": {
+			"description": "A translated option: the label alone, or the label with an icon and color override.",
+			"oneOf": [
+				{
+					"type": "string"
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"properties": {
+						"label": {
+							"type": "string"
+						},
+						"icon": {
+							"type": "string"
+						},
+						"color": {
+							"type": "string"
+						}
+					}
+				}
+			]
+		},
+		"options": {
+			"type": "object",
+			"description": "Option value (the stored code) → its translation.",
+			"additionalProperties": {
+				"$ref": "#/$defs/option"
+			}
+		},
+		"withOptions": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"options": {
+					"$ref": "#/$defs/options"
+				}
+			}
+		},
+		"entity": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"desc": {
+					"type": "string"
+				},
+				"fields": {
+					"type": "object",
+					"description": "Column code → label and, for dropdown / radio / flags columns, option labels.",
+					"additionalProperties": {
+						"$ref": "#/$defs/withOptions"
+					}
+				},
+				"columnGroups": {
+					"type": "object",
+					"description": "Card-layout section code → heading.",
+					"additionalProperties": {
+						"$ref": "#/$defs/labelOnly"
+					}
+				},
+				"constraints": {
+					"type": "object",
+					"description": "Check / unique constraint name → violation message.",
+					"additionalProperties": {
+						"type": "object",
+						"additionalProperties": false,
+						"properties": {
+							"message": {
+								"type": "string"
+							}
+						}
+					}
+				}
+			}
+		},
+		"menu": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"items": {
+					"type": "object",
+					"description": "Menu item code → label. Flat even when ui/menus.json nests items under children: a group and its children are siblings here.",
+					"additionalProperties": {
+						"$ref": "#/$defs/labelOnly"
+					}
+				}
+			}
+		},
+		"params": {
+			"type": "object",
+			"description": "Parameter code → label and dropdown option labels.",
+			"additionalProperties": {
+				"$ref": "#/$defs/withOptions"
+			}
+		},
+		"report": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"datasets": {
+					"type": "object",
+					"description": "Dataset code → caption.",
+					"additionalProperties": {
+						"type": "object",
+						"additionalProperties": false,
+						"properties": {
+							"caption": {
+								"type": "string"
+							}
+						}
+					}
+				},
+				"params": {
+					"$ref": "#/$defs/params"
+				}
+			}
+		},
+		"action": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"desc": {
+					"type": "string",
+					"description": "Translated tooltip."
+				},
+				"params": {
+					"$ref": "#/$defs/params"
+				}
+			}
+		}
+	}
+}

package/src/dsl/builtins.ts

@@ -74,22 +74,27 @@ export const BUILTINS: Builtin[] = [
 	// Messaging
 	{
 		name: "error",
-		signature: "error(message)",
+		signature: "error(message, values?)",
 		returns: "never",
-		doc: "Abort the action and show an error. Rolls back all changes.",
+		doc: "Abort the action and show an error. Rolls back all changes. The text is looked up in the module's `messages` translations; `{name}` placeholders are filled from `values`.",
+	},
+	{
+		name: "warn",
+		signature: "warn(message, values?, opts?)",
+		returns: "void",
+		doc: "Show a warning and continue. The text is looked up in the module's `messages` translations; `{name}` placeholders are filled from `values`.",
 	},
-	{ name: "warn", signature: "warn(message)", returns: "void", doc: "Show a warning and continue." },
 	{
 		name: "info",
-		signature: "info(message)",
+		signature: "info(message, values?, opts?)",
 		returns: "void",
-		doc: "Show an informational message — a receipt for work the action did, not a way to publish a computed value.",
+		doc: "Show an informational message — a receipt for work the action did, not a way to publish a computed value. The text is looked up in the module's `messages` translations; `{name}` placeholders are filled from `values`. `opts.links` adds record links.",
 	},
 	{
 		name: "exit",
-		signature: "exit(message?, level?)",
+		signature: "exit(message?, level?, values?)",
 		returns: "never",
-		doc: "Stop the script early **without** error, keeping changes made so far. Level `'info'` (default) or `'warn'`. This is the DSL's early return — the block compiles to a bare script, so a `return` outside a function is a syntax error wherever it sits.",
+		doc: "Stop the script early **without** error, keeping changes made so far. Level `'info'` (default), `'warning'`, `'danger'` or `'success'`. The message is looked up in the module's `messages` translations; `{name}` placeholders are filled from `values`. This is the DSL's early return — the block compiles to a bare script, so a `return` outside a function is a syntax error wherever it sits.",
 	},
 	{
 		name: "notify",

package/src/dsl/check.ts

@@ -11,6 +11,7 @@
 // omits, and the rules that depend on it stand down. See ./types.
 
 import { BUILTIN_BY_NAME } from "./builtins";
+import { extractMessages } from "./messages";
 import { CONTROL_KEYWORDS, type Token } from "./lexer";
 import {
 	type BlockKind,
@@ -25,7 +26,7 @@ import type { ColumnLookup, DslContext, DslIssue, DslSeverity } from "./types";
  * Check a DSL body. Returns [] for a clean script.
  *
  * Issues come back in source-feature order (field reads, params, execution
- * mode, block spelling, built-ins, top-level returns, inline assignments)
+ * mode, block spelling, built-ins, top-level returns, inline assignments, messages)
  * rather than sorted by position — a host that wants them in file order can
  * sort on `start`.
  */
@@ -573,9 +574,49 @@ export function checkDsl(text: string, ctx: DslContext = {}): DslIssue[] {
 	}
 
 	out.push(...inlineAssignmentIssues(parsed, positionAt));
+
+	// ── messages ─────────────────────────────────────────────────────
+	// Install reports the same, module-wide (ActionMessageScanner).
+	const locales = Object.entries(ctx.messageTranslations ?? {});
+	for (const m of extractMessages(parsed)) {
+		if (m.kind === "concatenated" && locales.length > 0) {
+			add(
+				m.span,
+				`This ${m.builtin}() message joins text and values, so it cannot be translated. Put the values in {placeholders}: ${m.builtin}('Only {n} left', ${m.builtin === "exit" ? "'warning', " : ""}{ n: qty }).`,
+				"warning",
+				"dsl/message-concatenated",
+			);
+		}
+		if (m.text === undefined) continue;
+
+		// A call without values keeps a literal "{x}" as text, as before placeholders existed.
+		if (m.valueNames && m.valueNames.length > 0) {
+			for (const name of placeholders(m.text)) {
+				if (!m.valueNames.includes(name))
+					add(m.span, `{${name}} has no value in this call, so it shows as written.`, "warning", "dsl/message-placeholder");
+			}
+		}
+
+		// A blank translation is dropped at install, so the message still shows in English.
+		const missing = locales
+			.filter(([, messages]) => !(Object.hasOwn(messages, m.text!) && messages[m.text!]?.trim()))
+			.map(([locale]) => locale);
+		if (missing.length > 0) {
+			add(
+				m.span,
+				`No ${missing.join(", ")} translation for this message — add it to "messages" in translations/<locale>.json, keyed by the exact text.`,
+				"warning",
+				"dsl/message-untranslated",
+			);
+		}
+	}
 	return out;
 }
 
+function placeholders(text: string): string[] {
+	return [...new Set([...text.matchAll(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g)].map((x) => x[1]!))];
+}
+
 /**
  * Column matching is case-insensitive at the other end — `EntityColumnLookup`
  * hands the compiler an OrdinalIgnoreCase set — but a host passes us whatever

package/src/dsl/index.ts

@@ -27,6 +27,9 @@ export type {
 export { BUILTINS, BUILTIN_BY_NAME, BUILTIN_VALUES } from "./builtins";
 export type { Builtin } from "./builtins";
 
+export { extractMessages } from "./messages";
+export type { DslMessage, DslMessageKind } from "./messages";
+
 export { checkDsl } from "./check";
 export type {
 	ColumnLookup,