@xrmforge/typegen 0.7.0 → 0.8.0

package/docs/architecture/10-eslint-plugin.md

@@ -0,0 +1,82 @@
+# ESLint Plugin
+
+### 10.1 Installation
+
+```javascript
+// eslint.config.js (flat config, ESLint v9)
+import xrmforge from '@xrmforge/eslint-plugin';
+
+export default [
+  xrmforge.configs.recommended,
+  // or pick individual rules
+];
+```
+
+### 10.2 Rules
+
+#### no-xrm-page (error)
+
+Forbids the deprecated `Xrm.Page` API (removed in D365 v9.0+).
+
+```typescript
+// Bad
+Xrm.Page.getAttribute("name");
+
+// Good
+const form = executionContext.getFormContext();
+form.getAttribute("name");
+```
+
+#### no-magic-optionset (warn)
+
+Forbids raw numbers (>= 2) in comparisons with `.getValue()`.
+
+```typescript
+// Bad
+if (attr.getValue() === 595300000) { }
+
+// Good
+import { StatusCode } from '../generated/optionsets/account';
+if (attr.getValue() === StatusCode.Active) { }
+```
+
+#### no-sync-webapi (error)
+
+Forbids synchronous XMLHttpRequest (`new XMLHttpRequest()` and `.open()` with `async=false`).
+
+```typescript
+// Bad
+xhr.open("GET", url, false);
+
+// Good
+const data = await Xrm.WebApi.retrieveRecord("account", id);
+```
+
+#### require-error-handling (warn)
+
+Requires try/catch in exported async functions starting with "on" (event handlers).
+
+```typescript
+// Bad
+export async function onLoad(ctx) {
+  await fetch("/api");  // no error handling
+}
+
+// Good
+export async function onLoad(ctx) {
+  try { await fetch("/api"); }
+  catch (error) { console.error(error); }
+}
+```
+
+#### require-namespace (warn)
+
+Forbids direct `window.X = ...` or `globalThis.X = ...` assignments. Module exports with esbuild globalName should be used instead.
+
+```typescript
+// Bad
+window.Contoso = { onLoad: function() {} };
+
+// Good
+export function onLoad(ctx: Xrm.Events.EventContext) {}
+```

package/docs/architecture/11-agent-md.md

@@ -0,0 +1,38 @@
+# AGENT.md System
+
+### 11.1 Purpose
+
+The AGENT.md is a scaffolded file that teaches AI coding assistants (Claude, ChatGPT, Copilot, Cursor) how to write optimal D365 form scripts using XrmForge. It is generated by `xrmforge init` and placed in the project root.
+
+### 11.2 Content Structure
+
+1. **Package overview** - What each @xrmforge package does
+2. **10 Rules: Always** - Fields Enum, OptionSet Enum, FormContext cast, EntityNames, parseLookup, select, createFormMock, module exports, Tabs/Sections enums, error handling
+3. **Rules: Never** - Raw strings, magic numbers, Xrm.Page, sync XHR, eval, window assignments
+4. **Before/After examples** - Field access, OptionSet comparison, testing
+5. **Pattern Recognition table** - Legacy pattern to XrmForge replacement mapping
+6. **OptionSet Enum creation guide** - How to create enums from magic numbers in legacy code
+7. **Testing with setupXrmMock** - Global Xrm mock pattern
+8. **Build commands** - xrmforge build, watch mode
+9. **@types/xrm Pitfalls** - Known issues and workarounds
+10. **File structure** - Expected project layout
+
+### 11.3 Template System
+
+The AGENT.md is stored as `src/scaffold/templates/AGENT.md` in the devkit package and loaded via `template-loader.ts` at scaffold time. No variable substitution needed (the file is static).
+
+### 11.4 KI Comparison Test Results
+
+Five AI models were tested converting legacy D365 JavaScript (account.js + lm_helper.js, 1,288 lines) to TypeScript with XrmForge:
+
+| Rank | Model | Score | Tool | Strength |
+|------|-------|-------|------|----------|
+| 1 | Claude Opus 4.6 | 42/50 | Claude Code | Most tests (62), best code structure |
+| 2 | Claude Sonnet 4.6 | 41/50 | Claude Code | Most bugs found (5), best DI approach |
+| 3 | Cursor Composer 2 | 35/50 | Cursor IDE | Recognized select() Node API issue |
+| 4 | ChatGPT GPT-4o | 30/50 | ChatGPT Web | Functional but less XrmForge-specific |
+| 5 | MS Copilot | 12/50 | Browser Chat | No workspace access, never saw AGENT.md |
+
+**Criteria (11, max 5 points each = 55 max):** Fields Enum usage, OptionSet Enums, FormContext typing, XrmForge helpers, module exports, tests present, test quality, error handling, code quality, bugs found, documentation.
+
+**Key finding:** No AI consistently used `@xrmforge/helpers` imports (select, parseLookup). This remains the biggest adoption gap.

package/docs/architecture/12-xrm-pitfalls.md

@@ -0,0 +1,14 @@
+# @types/xrm Pitfalls
+
+Known issues when working with `@types/xrm`:
+
+| Issue | Wrong | Correct |
+|-------|-------|---------|
+| Form interface | `interface extends Xrm.FormContext` | `extends Omit<Xrm.FormContext, 'getAttribute' \| 'getControl'>` |
+| AlertDialogResponse | `Xrm.Navigation.AlertDialogResponse` | `Xrm.Async.PromiseLike<void>` (type does not exist) |
+| ConfirmDialogResponse | `Xrm.Navigation.ConfirmDialogResponse` | `Xrm.Navigation.ConfirmResult` (type does not exist) |
+| setNotification | `setNotification(message)` | `setNotification(message, uniqueId)` (requires 2 args) |
+| openFile | `openFile({ fileName, ... })` | Must include `fileSize` property in FileDetails |
+| SubmitMode | `Xrm.Attributes.SubmitMode` | `Xrm.SubmitMode` |
+| const enum in .d.ts | `const enum` in `.d.ts` files | Use `const enum` in `.ts` ES modules (typegen 0.8.0+ generates `.ts` files, resolving this issue) |
+| Grid.refresh() | `grid.refresh()` | `(grid as any).refresh()` (not typed in @types/xrm) |

package/docs/architecture/13-helpers.md

@@ -0,0 +1,50 @@
+# @xrmforge/helpers Package
+
+### 13.1 Problem
+
+The previous approach used a `/helpers` subpath export on `@xrmforge/typegen`. This was confusing because typegen is a Node.js code generation tool, while helpers are browser-safe runtime utilities. The subpath `@xrmforge/typegen/helpers` was non-obvious and AI coding assistants consistently failed to discover it.
+
+### 13.2 Solution
+
+A standalone `@xrmforge/helpers` package consolidates all browser-safe runtime code. Zero Node.js dependencies. Clean, discoverable import path:
+
+```typescript
+// Import from the dedicated helpers package
+import { select, parseLookup, typedForm } from '@xrmforge/helpers';
+```
+
+### 13.3 Exports
+
+**Web API Helpers:**
+- `select(...fields: string[]): string` - Builds `?$select=field1,field2`
+- `selectExpand(fields: string[], expand: string): string` - Builds `?$select=...&$expand=...`
+- `parseLookup(response: Record<string, unknown>, fieldName: string): LookupValue | null` - Parses `_fieldname_value` with OData annotations
+- `parseLookups(response: Record<string, unknown>, fieldName: string): LookupValue[]` - Multi-value lookup parsing
+- `parseFormattedValue(response: Record<string, unknown>, fieldName: string): string | null` - Extracts `@OData.Community.Display.V1.FormattedValue`
+
+**Xrm Constants (8 const enums):**
+- DisplayState, FormNotificationLevel, RequiredLevel, SubmitMode, SaveMode, ClientType, ClientState, OperationType
+
+**typedForm() Proxy:**
+- `typedForm<TForm>(formContext)` - Returns a proxy where `form.name` delegates to `getAttribute('name')`
+- GET trap: Property access delegates to getAttribute(); `$context` returns raw FormContext; `$control(name)` returns getControl()
+- SET trap: Throws TypeError forcing `.setValue()` usage
+- HAS trap: Checks if attribute exists on the form
+
+**Action/Function Runtime:**
+- `createBoundAction(entityName, actionName)` - Creates a bound action executor
+- `executeRequest(request)` - Executes an Organization Request via Xrm.WebApi.online.execute
+- `withProgress(message, fn)` - Wraps an async operation with Xrm.Utility.showProgressIndicator
+
+### 13.4 Migration
+
+The old import path `@xrmforge/typegen/helpers` has been removed. Update all imports:
+
+```typescript
+// Old (removed)
+import { select } from '@xrmforge/typegen/helpers';
+import { typedForm } from '@xrmforge/formhelpers';
+
+// New
+import { select, typedForm } from '@xrmforge/helpers';
+```

package/docs/architecture/14-showcases.md

@@ -0,0 +1,21 @@
+# Showcases
+
+### 14.1 Markant WebResources (Production Showcase)
+
+Located in the XrmForge-Workspace repository under `docs/07_showcase/markant-webresources/`.
+
+- **30 WebResources** in `src/forms/` (account, contact, opportunity, lead, quote, email, task, etc.)
+- **1 shared library** (GDPR retention UI)
+- **9 test files** with 59 tests
+- **79 generated typings:** 25 form interfaces, 28 entity interfaces, 22 OptionSet files, 4 action executors
+- **esbuild build** via xrmforge.config.json (32 entries)
+- **Deploy script** (deploy.mjs) with @azure/identity auth, incremental deployment, hash-based change detection
+- **27 entities, 236 OptionSet enums, 95 form interfaces, 7 Custom API executors**
+
+### 14.2 LMApp WebResources (KI Comparison Showcase)
+
+Created during the KI comparison tests (Session 9). 18 legacy JavaScript form scripts (~8,400 lines) converted to TypeScript with XrmForge patterns.
+
+- **19 WebResources** with Fields Enums, EntityNames, OptionSet Enums
+- **84 tests** in 8 test files
+- **XrmForge-optimized:** All 10 AGENT.md rules applied (FormContext cast, Fields Enum, EntityNames, OptionSet Enums, shared getLookupObject, Tab Enums)

package/docs/architecture/15-ci-cd.md

@@ -0,0 +1,49 @@
+# CI/CD
+
+### 15.1 GitHub Actions CI (`.github/workflows/ci.yml`)
+
+**Triggers:** Push to main, Pull Requests against main.
+
+**Matrix:** Node 20, Node 22 on ubuntu-latest.
+
+**Steps:**
+1. Checkout
+2. Setup pnpm (from packageManager field)
+3. Setup Node.js (matrix version)
+4. `pnpm install --frozen-lockfile`
+5. `pnpm lint`
+6. `pnpm -r exec tsc --noEmit` (typecheck all packages)
+7. `pnpm build`
+8. `pnpm test`
+9. Coverage (Node 22 only): `npx vitest run --coverage` in typegen
+
+### 15.2 Release Workflow (`.github/workflows/release.yml`)
+
+**Triggers:** After successful CI on push to main.
+
+**Steps:**
+1. Checkout, setup pnpm, setup Node 22
+2. `pnpm install --frozen-lockfile`
+3. `pnpm build`
+4. Changesets action: creates Release PR or publishes to npm
+
+**Publish command:** `pnpm release` = `turbo run build && changeset publish`
+
+### 15.3 Turbo Pipeline
+
+```
+build:      dependsOn: [^build], outputs: [dist/**]
+test:       dependsOn: [build]
+typecheck:  dependsOn: [^build]
+lint:       (no dependencies)
+dev:        cache: false, persistent: true
+clean:      cache: false
+```
+
+### 15.4 Changesets
+
+Configured for public npm access, auto-update internal dependencies on patch level. Publish requires NPM_TOKEN secret.
+
+### 15.5 Publishing Order
+
+Due to internal dependencies: typegen first, then devkit, then cli. Must use `pnpm publish` (not `npm publish`) to resolve `workspace:*` references to real versions.

package/docs/architecture/16-technical-debt.md

@@ -0,0 +1,17 @@
+# Technical Debt
+
+### 16.1 Known Issues
+
+| Issue | Status | Priority |
+|-------|--------|----------|
+| parseLookup/select not adopted by AI assistants | Open | High |
+| release.yml double runs (CI triggers release, release re-triggers CI) | Open | Low |
+| No integration tests against live Dataverse | Open (OE-4) | Medium |
+| @xrmforge/webapi has no Action/Function support | Accepted | Low |
+| devDependency versions in scaffolded package.json are pinned to old versions | Open | Low |
+
+### 16.2 Accepted Limitations
+
+- **const enum limitation:** Resolved in typegen 0.8.0. Generated output is now `.ts` ES modules, so `const enum` works directly with vitest and other test frameworks.
+- **Grid.refresh() requires `as any`:** Not typed in @types/xrm.
+- **Single solution per entity:** If an entity appears in multiple solutions, it is only generated once.

package/docs/architecture/17-roadmap.md

@@ -0,0 +1,25 @@
+# Roadmap
+
+### 17.1 Next Steps (Priority Order)
+
+1. **parseLookup/select Adoption** - Improve AGENT.md examples so AI assistants consistently use `/helpers` imports
+2. **LMApp Showcase regeneration** - With latest releases (testing@0.2.0, devkit@0.4.0 with improved AGENT.md)
+3. **KI Battle Round 3** - Re-test Sonnet vs Opus after improvements to measure progress
+4. **Documentation website** - xrmforge.dev or xrmforge.io (OE-3)
+
+### 17.2 Open Decisions
+
+| ID | Decision | Status |
+|----|----------|--------|
+| OE-1 | npm scope availability (@xrmforge) | Open |
+| OE-2 | GitHub org vs personal repo | Decided: personal (juergenbeck/XrmForge) |
+| OE-3 | Documentation domain (xrmforge.dev or .io) | Open |
+| OE-4 | Dataverse test environment for integration tests | Open |
+| OE-5 | Publisher prefix and solution name for PCF/WebResource tests | Open |
+
+### 17.3 Future Possibilities
+
+- Relationship Names const enum (OE-7, low priority)
+- @xrmforge/webapi with Action/Function support (reuse DataverseHttpClient)
+- Plugin system for custom generators and type mappings
+- Server-side generation (Custom API in Dataverse)

package/docs/architecture/18-design-principles.md

@@ -0,0 +1,22 @@
+# Design Principles
+
+The 18 design principles that govern all XrmForge development:
+
+1. **Extend, don't replace** - Types build on @types/xrm, never override them.
+2. **TypeScript all the way** - 100% TypeScript-native. No .NET, no ADAL.
+3. **Code must build** - Every work step ends with green build + tests.
+4. **Research before speed** - Investigate, compare, decide, then implement. Never guess.
+5. **No module without basics** - Error handling, logging, unit tests, JSDoc on all public APIs.
+6. **Monorepo discipline** - Each package standalone, no circular deps, barrel exports.
+7. **Enterprise resilience** - Retry + exponential backoff, rate-limit awareness, token caching, read-only default.
+8. **esbuild-first, webpack-compatible** - Default: esbuild (fast). webpack stays supported. IIFE output for D365.
+9. **MSAL-only authentication** - Only @azure/identity (no legacy ADAL). Three flows: client credentials, browser, device code.
+10. **Review required** - After every step, immediate critical review (6 dimensions). No asking if review is wanted.
+11. **Session state required** - session-state.md updated, changelog written, open questions tracked.
+12. **No half measures** - Every step completed fully: green build + tests + review before next step.
+13. **Informed architecture decisions** - Research, compare, recommend with pros/cons, get decision, persist.
+14. **Abstraction over vendor lock-in** - External dependencies behind interfaces (parser, auth, bundler).
+15. **Dual-language labels** - Primary language (1033/English) for identifiers, secondary in JSDoc. German umlauts transliterated.
+16. **Review with research and live verification** - Internet research, live D365 verification, production code checks, cite sources.
+17. **Challenge postponement** - "Later" check: Will it get harder? API contract? Real effort? Technical reasons?
+18. **Read-only default for Dataverse access** - DataverseHttpClient defaults to readOnly: true. Write access is an explicit opt-in.

package/docs/architektur/00-README.md

@@ -0,0 +1,26 @@
+# XrmForge Architektur
+
+> **Status:** Lebendes Dokument, das den aktuellen Implementierungsstand beschreibt.
+> **Letztes Update:** 2026-04-04 (Session 10)
+> **Version:** 7 Packages, 666+ Tests über alle Packages.
+
+## Kapitel
+
+1. [Zusammenfassung](01-zusammenfassung.md)
+2. [Package-Architektur](02-packages.md)
+3. [Generierte Typen](03-generierte-typen.md)
+4. [CLI-Befehle](04-cli.md)
+5. [Build-Architektur](05-build.md)
+6. [Inkrementelle Generierung](06-inkrementell.md)
+7. [HTTP-Client](07-http-client.md)
+8. [Authentifizierung](08-authentifizierung.md)
+9. [Test-Framework](09-testing.md)
+10. [ESLint-Plugin](10-eslint-plugin.md)
+11. [AGENT.md-System](11-agent-md.md)
+12. [@types/xrm-Fallstricke](12-xrm-fallstricke.md)
+13. [@xrmforge/helpers Package](13-helpers.md)
+14. [Showcases](14-showcases.md)
+15. [CI/CD](15-ci-cd.md)
+16. [Technische Schulden](16-technische-schulden.md)
+17. [Roadmap](17-roadmap.md)
+18. [Designprinzipien](18-designprinzipien.md)

package/docs/architektur/01-zusammenfassung.md

@@ -0,0 +1,11 @@
+# 1. Zusammenfassung
+
+XrmForge ist ein quelloffenes TypeScript-Toolkit für typsichere Dynamics 365 / Dataverse WebResource-Entwicklung. Es generiert TypeScript-Deklarationen aus Live-Dataverse-Metadaten und verwandelt Laufzeit-String-Fehler in Kompilierzeit-Typfehler.
+
+**Kernnutzenversprechen:** Jeder Feldname, OptionSet-Wert, Tab-Name, Entitätsname und Subgrid-Name wird zu einer typisierten Konstante mit IDE-Autovervollständigung und Kompilierzeit-Validierung.
+
+**Zielgruppe:** D365-Entwickler, die Formularskripte (WebResources) in JavaScript/TypeScript schreiben und Kompilierzeit-Sicherheit, null Magic Strings und moderne Werkzeuge (esbuild, vitest, ESLint) wollen.
+
+**Technologie-Stack:** TypeScript, pnpm-Monorepo mit Turborepo, esbuild für IIFE-Bundles, vitest für Tests, @azure/identity für Authentifizierung, fast-xml-parser für FormXml-Parsing.
+
+**npm-Organisation:** [@xrmforge](https://www.npmjs.com/org/xrmforge)

package/docs/architektur/02-packages.md

@@ -0,0 +1,110 @@
+# 2. Package-Architektur
+
+## 2.1 Package-Übersicht
+
+| Package | Version | Tests | Beschreibung |
+|---------|---------|-------|--------------|
+| @xrmforge/typegen | 0.8.0 | 444 | Kern: Typgenerierungs-Engine, Metadaten-Client, HTTP-Client, Hilfsfunktionen |
+| @xrmforge/cli | 0.4.2 | 10 | CLI: generate-, build-, init-Befehle |
+| @xrmforge/testing | 0.2.0 | 76 | Test-Hilfsmittel: createFormMock, fireOnChange, setupXrmMock |
+| @xrmforge/helpers | 0.1.0 | 59 | Browsersichere Laufzeit: select(), parseLookup(), typedForm(), Xrm-Konstanten, Action-Executors |
+| @xrmforge/webapi | 0.1.0 | 45 | Typsicherer Xrm.WebApi-Client mit QueryBuilder |
+| @xrmforge/devkit | 0.4.0 | 42 | Build-Orchestrierung, Scaffolding, AGENT.md-Generierung |
+| @xrmforge/eslint-plugin | 0.2.0 | 32 | 5 D365-spezifische ESLint-Regeln |
+
+**Gesamt:** 708 Tests über 7 Packages.
+
+## 2.2 Abhängigkeitsgraph
+
+```
+@xrmforge/cli
+  |-- @xrmforge/typegen (generate-Befehl)
+  |-- @xrmforge/devkit  (build- + init-Befehle)
+  '-- commander (CLI-Framework)
+
+@xrmforge/typegen
+  |-- @azure/identity  (Authentifizierung)
+  '-- fast-xml-parser  (FormXml-Parsing)
+
+@xrmforge/devkit
+  '-- esbuild (IIFE-Bundling)
+
+@xrmforge/testing     (keine Laufzeit-Abhängigkeiten)
+@xrmforge/helpers     (keine Laufzeit-Abhängigkeiten)
+@xrmforge/webapi      (keine Laufzeit-Abhängigkeiten)
+@xrmforge/eslint-plugin (ESLint Peer-Abhängigkeit)
+```
+
+## 2.3 Package-Details
+
+### @xrmforge/typegen
+
+Das Kern-Package. Enthält:
+
+- **TypeGenerationOrchestrator** - Koordiniert die gesamte Generierungs-Pipeline
+- **MetadataClient** - Fragt Dataverse-Metadaten ab (Entitäten, Formulare, OptionSets, Custom APIs)
+- **DataverseHttpClient** - Belastbarer REST-Client mit Retry, Rate Limiting, Nebenläufigkeitssteuerung
+- **ChangeDetector** - Inkrementelle Generierung über RetrieveMetadataChanges
+- **MetadataCache** - Dateisystem-basiertes Caching mit Versionsstempeln
+- **Generators** - Entitäts-Interfaces, Formular-Interfaces, OptionSet-Enums, Fields-Enums, EntityNames, Navigations-Properties, Action/Function-Executors
+- **Helpers** - select(), parseLookup(), parseFormattedValue() (verschoben nach @xrmforge/helpers)
+- **Xrm-Konstanten** - DisplayState, FormNotificationLevel, RequiredLevel, SubmitMode, SaveMode, ClientType, ClientState (verschoben nach @xrmforge/helpers)
+- **Authentifizierung** - createCredential()-Factory für 4 Authentifizierungsmethoden
+- **Logging** - Scope-basierte Logger mit austauschbaren Senken (Console, JSON, Silent)
+- **Fehler** - Strukturierte Fehlerhierarchie mit ErrorCode-Enum (AUTH_1xxx, API_2xxx, META_3xxx, GEN_4xxx, CONFIG_5xxx)
+
+### @xrmforge/cli
+
+Kommandozeilen-Interface basierend auf commander.js. Drei Befehle:
+- `xrmforge generate` - Orchestriert den TypeGenerationOrchestrator
+- `xrmforge build` - Delegiert an devkit build()
+- `xrmforge init` - Delegiert an devkit scaffoldProject()
+
+### @xrmforge/testing
+
+FormContext-Mocking für Unit-Tests:
+- `createFormMock<TForm>(values)` - Erstellt einen vollständigen Mock aus einfachen Schlüssel-Wert-Paaren
+- `MockAttribute` - getValue/setValue, Dirty-Tracking, onChange-Handler, Required Level, Submit Mode
+- `MockControl` - Sichtbar, Deaktiviert, Label, Benachrichtigungen
+- `MockUi` - Formular-Benachrichtigungen, Tab/Section-Stubs
+- `MockEntity` - Entitäts-ID, Name, Primärattribut
+- `fireOnChange(fieldName)` - Löst registrierte onChange-Handler aus
+- `setupXrmMock(options)` / `teardownXrmMock()` - Globaler Xrm-Mock mit WebApi/Navigation-Stubs
+
+### @xrmforge/helpers
+
+Bündelt allen browsersicheren Laufzeitcode. Keine Node.js-Abhängigkeiten. Enthält:
+- **Web-API-Helpers** - select(), parseLookup(), parseFormattedValue()
+- **Xrm-Konstanten** - DisplayState, SubmitMode, RequiredLevel, SaveMode, ClientType, ClientState, FormNotificationLevel, OperationType
+- **Action/Function-Executors** - createBoundAction(), executeRequest(), withProgress()
+- **typedForm()-Proxy** - Proxy-basierter FormContext-Wrapper, bei dem `form.name` an `getAttribute('name')` delegiert
+
+### @xrmforge/webapi
+
+Typsicherer Wrapper um Xrm.WebApi:
+- `retrieve<T>(entityName, id, query)` - Einzelner Datensatz
+- `retrieveMultiple<T>(entityName, query, options)` - Mit Paginierung (maxPages)
+- `create(entityName, data)` - Gibt Datensatz-ID zurück
+- `update(entityName, id, data)` - Void
+- `remove(entityName, id)` - Void
+- `QueryBuilder` - Fluent API: `.select().filter().orderBy().top().expand().build()`
+- `WebApiError` - Strukturierte Fehler mit statusCode, errorCode, innerMessage
+
+### @xrmforge/devkit
+
+Build-Orchestrierung und Projekt-Scaffolding:
+- `build(config)` - Parallele esbuild-IIFE-Builds über Promise.allSettled
+- `watch(config)` - esbuild-Watch-Modus mit Rebuild-Callbacks
+- `scaffoldProject(config)` - Generiert 11 Projektdateien aus Vorlagen
+- `validateBuildConfig(config)` / `resolveBuildConfig(config)` - Konfigurationsvalidierung
+- `BuildError` mit Codes: CONFIG_INVALID, ENTRY_NOT_FOUND, BUILD_FAILED, WATCH_ERROR
+- Vorlagensystem: 7 Textvorlagen in `src/scaffold/templates/`, geladen über `template-loader.ts`
+
+### @xrmforge/eslint-plugin
+
+5 Regeln für D365-Formularskripte (ESLint v9 Flat Config):
+- `no-xrm-page` (error) - Verbietet die veraltete Xrm.Page-API
+- `no-magic-optionset` (warn) - Verbietet Magic Numbers in OptionSet-Vergleichen
+- `no-sync-webapi` (error) - Verbietet synchrone XMLHttpRequest
+- `require-error-handling` (warn) - Verlangt try/catch in asynchronen on*-Event-Handlern
+- `require-namespace` (warn) - Verbietet window/globalThis-Zuweisungen

package/docs/architektur/03-generierte-typen.md

@@ -0,0 +1,172 @@
+# 3. Generierte Typen
+
+Die Ausführung von `xrmforge generate` erzeugt die folgenden TypeScript-ES-Module:
+
+## 3.1 Entitäts-Interfaces (`entities/{entity}.ts`)
+
+```typescript
+// generated/entities/account.ts
+/** Account | Konto */
+export interface Account {
+  /** Account Name | Kontoname */
+  name: string | null;
+  accountid: string | null;
+  revenue: number | null;
+  _parentaccountid_value: string | null;  // Lookup GUID
+  // ...
+}
+```
+
+**Typ-Zuordnung:** String/Memo/EntityName zu `string`, Integer/BigInt/Decimal/Double/Money zu `number`, Boolean zu `boolean`, DateTime/Uniqueidentifier/Lookup zu `string`, Picklist/State/Status zu `number`.
+
+## 3.2 Entity Fields Enums (`fields/{entity}.ts`)
+
+```typescript
+// generated/fields/account.ts
+export const enum AccountFields {
+  /** Account Name | Kontoname */
+  Name = 'name',
+  Telephone1 = 'telephone1',
+  Revenue = 'revenue',
+  // alle Entitätsattribute für $select-Abfragen
+}
+
+export const enum AccountNavigationProperties {
+  PrimaryContact = 'primarycontactid',
+  ContactCustomerAccounts = 'contact_customer_accounts',
+  // alle Lookup-Navigations-Properties
+}
+```
+
+Verwendet für Web API `$select`: `select(AccountFields.Name, AccountFields.Revenue)`.
+
+## 3.3 Navigations-Properties (`fields/{entity}.ts`)
+
+Navigations-Property-Enums befinden sich zusammen mit den Fields-Enums in derselben Datei (siehe 3.2 oben). Beispielverwendung:
+
+```typescript
+import { AccountNavigationProperties } from '../generated/fields/account';
+// verwendet für $expand-Abfragen
+```
+
+## 3.4 Formular-Interfaces (`forms/{entity}.ts`)
+
+```typescript
+// generated/forms/account.ts
+
+// Union-Typ, der gültige Feldnamen einschränkt
+export type AccountMainFormFields = 'name' | 'telephone1' | 'revenue';
+
+// Gemappter Typ: Feldname zu Xrm-Attributtyp
+export type AccountMainFormAttributeMap = {
+  name: Xrm.Attributes.StringAttribute;
+  telephone1: Xrm.Attributes.StringAttribute;
+  revenue: Xrm.Attributes.NumberAttribute;
+};
+
+// Gemappter Typ: Feldname zu Xrm-Steuerelementtyp
+export type AccountMainFormControlMap = {
+  name: Xrm.Controls.StringControl;
+  telephone1: Xrm.Controls.StringControl;
+  revenue: Xrm.Controls.NumberControl;
+};
+
+// Fields-Enum für Autovervollständigung
+export const enum AccountMainFormFieldsEnum {
+  /** Account Name | Kontoname */
+  AccountName = 'name',
+  Telephone1 = 'telephone1',
+  Revenue = 'revenue',
+}
+
+// Typsicherer FormContext mit überladenen getAttribute/getControl
+export interface AccountMainForm extends Omit<Xrm.FormContext, 'getAttribute' | 'getControl'> {
+  getAttribute<K extends AccountMainFormFields>(name: K): AccountMainFormAttributeMap[K];
+  getAttribute(index: number): Xrm.Attributes.Attribute;
+  getAttribute(): Xrm.Attributes.Attribute[];
+
+  getControl<K extends AccountMainFormFields>(name: K): AccountMainFormControlMap[K];
+  getControl(index: number): Xrm.Controls.Control;
+  getControl(): Xrm.Controls.Control[];
+}
+```
+
+**Spezielle Steuerelemente** werden anhand ihrer FormXml-ClassID typisiert:
+- Subgrid: `Xrm.Controls.GridControl`
+- Editierbares Grid: `Xrm.Controls.GridControl`
+- Quick View: `Xrm.Controls.QuickFormControl`
+- Web Resource / iFrame: `Xrm.Controls.IframeControl`
+
+## 3.5 Tabs/Sections/Subgrids/QuickViews Enums
+
+```typescript
+const enum AccountMainFormTabs { Summary = 'SUMMARY_TAB', Details = 'DETAILS_TAB' }
+const enum AccountMainFormSections { General = 'GENERAL', Address = 'ADDRESS' }
+const enum AccountMainFormSubgrids { Contacts = 'Contacts_Subgrid' }
+const enum AccountMainFormQuickViews { ContactPreview = 'ContactQuickView' }
+```
+
+## 3.6 OptionSet Enums (`optionsets/{entity}.ts`)
+
+```typescript
+// generated/optionsets/account.ts
+/** Account Category Code | Kontokategoriecode */
+export const enum AccountCategoryCode {
+  /** Preferred Customer | Bevorzugter Kunde */
+  PreferredCustomer = 1,
+  Standard = 2,
+}
+```
+
+Umfasst Picklist-, Status-, State- und MultiSelectPicklist-Attribute. Doppelte Labels werden mit dem Suffix `_{Value}` disambiguiert.
+
+## 3.7 EntityNames Enum (`entity-names.ts`)
+
+```typescript
+// generated/entity-names.ts
+export const enum EntityNames {
+  Account = 'account',
+  Contact = 'contact',
+  // alle Entitäten im Scope
+}
+```
+
+## 3.8 MockValues-Typen (in Formular-Interfaces)
+
+```typescript
+type AccountMainFormMockValues = {
+  name?: string | null;
+  telephone1?: string | null;
+  revenue?: number | null;
+};
+```
+
+Verwendet mit `createFormMock<AccountMainForm, AccountMainFormMockValues>({ name: 'Test' })`.
+
+## 3.9 Action/Function Executors (`actions/{entity|global}.ts`)
+
+```typescript
+// generated/actions/global.ts
+import { createUnboundAction } from '@xrmforge/helpers';
+
+export interface NormalizePhoneParams { Input: string; AllowSuspicious?: boolean; }
+export interface NormalizePhoneResult { Normalized: string; Status: number; }
+
+export const NormalizePhone = createUnboundAction<NormalizePhoneParams, NormalizePhoneResult>(
+  'markant_NormalizePhone',
+  { Input: { typeName: 'String', structuralProperty: 1 } }
+);
+// Verwendung: const result = await NormalizePhone.execute({ Input: '123' });
+```
+
+Factory-Funktionen: `createBoundAction`, `createUnboundAction`, `createBoundFunction`, `createUnboundFunction`. Batch-Ausführung über `executeMultiple()`, Fortschritts-UI über `withProgress()`.
+
+## 3.10 Zweisprachige Labels
+
+Alle generierten JSDoc-Kommentare unterstützen zweisprachige Labels:
+```typescript
+/** Account Name | Kontoname */
+Name = 'name',
+```
+
+Deutsche Umlaute werden in Bezeichnern transliteriert: ae, oe, ue, ss (z.B. "Übergeordnet" wird zu `Uebergeordnet`).