@xrmforge/typegen 0.6.0 → 0.7.1

package/docs/architektur/02-packages.md

@@ -0,0 +1,110 @@
+# 2. Package-Architektur
+
+## 2.1 Package-Übersicht
+
+| Package | Version | Tests | Beschreibung |
+|---------|---------|-------|--------------|
+| @xrmforge/typegen | 0.6.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,176 @@
+# 3. Generierte Typen
+
+Die Ausführung von `xrmforge generate` erzeugt die folgenden TypeScript-Deklarationen:
+
+## 3.1 Entitäts-Interfaces (`entities/{entity}.d.ts`)
+
+```typescript
+declare namespace XrmForge.Entities {
+  /** Account | Konto */
+  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 (`entities/{entity}.d.ts`)
+
+```typescript
+declare namespace XrmForge.Entities {
+  const enum AccountFields {
+    /** Account Name | Kontoname */
+    Name = 'name',
+    Revenue = 'revenue',
+    // alle lesbaren Attribute
+  }
+}
+```
+
+Verwendet für Web API `$select`: `select(AccountFields.Name, AccountFields.Revenue)`.
+
+## 3.3 Navigations-Properties (`entities/{entity}.d.ts`)
+
+```typescript
+declare namespace XrmForge.Entities {
+  const enum AccountNavigation {
+    PrimaryContactId = 'primarycontactid',
+    ContactCustomerAccounts = 'contact_customer_accounts',
+    // OneToMany- + ManyToMany-Beziehungen
+  }
+}
+```
+
+## 3.4 Formular-Interfaces (`forms/{entity}.d.ts`)
+
+```typescript
+declare namespace XrmForge.Forms.Account {
+  // Union-Typ, der gültige Feldnamen einschränkt
+  type AccountMainFormFields = 'name' | 'telephone1' | 'revenue';
+
+  // Gemappter Typ: Feldname zu Xrm-Attributtyp
+  type AccountMainFormAttributeMap = {
+    name: Xrm.Attributes.StringAttribute;
+    telephone1: Xrm.Attributes.StringAttribute;
+    revenue: Xrm.Attributes.NumberAttribute;
+  };
+
+  // Gemappter Typ: Feldname zu Xrm-Steuerelementtyp
+  type AccountMainFormControlMap = {
+    name: Xrm.Controls.StringControl;
+    telephone1: Xrm.Controls.StringControl;
+    revenue: Xrm.Controls.NumberControl;
+  };
+
+  // Fields-Enum für Autovervollständigung
+  const enum AccountMainFormFieldsEnum {
+    /** Account Name | Kontoname */
+    AccountName = 'name',
+    Telephone1 = 'telephone1',
+    Revenue = 'revenue',
+  }
+
+  // Typsicherer FormContext mit überladenen getAttribute/getControl
+  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}.d.ts`)
+
+```typescript
+declare namespace XrmForge.OptionSets.Account {
+  /** Account Category Code | Kontokategoriecode */
+  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.d.ts`)
+
+```typescript
+declare namespace XrmForge {
+  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}.d.ts` + `.ts`)
+
+**Deklaration (.d.ts):**
+```typescript
+declare namespace XrmForge.Actions {
+  interface NormalizePhoneParams { Input: string; AllowSuspicious?: boolean; }
+  interface NormalizePhoneResult { Normalized: string; Status: number; }
+}
+```
+
+**Laufzeitmodul (.ts):**
+```typescript
+import { createUnboundAction } from '@xrmforge/typegen';
+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`).

package/docs/architektur/04-cli.md

@@ -0,0 +1,58 @@
+# 4. CLI-Befehle
+
+## 4.1 `xrmforge generate`
+
+Generiert TypeScript-Deklarationen aus einer Dataverse-Umgebung.
+
+| Flag | Typ | Standard | Beschreibung |
+|------|-----|----------|--------------|
+| `--url <url>` | string | erforderlich | Dataverse-Umgebungs-URL |
+| `--auth <method>` | string | erforderlich | Authentifizierungsmethode: client-credentials, interactive, device-code, token |
+| `--tenant-id <id>` | string | variiert | Azure AD Tenant-ID |
+| `--client-id <id>` | string | variiert | Azure AD Application-ID |
+| `--client-secret <s>` | string | variiert | Client Secret (nur client-credentials) |
+| `--token <token>` | string | variiert | Vorab erworbenes Bearer-Token (nur Token-Auth) |
+| `--entities <list>` | string | - | Kommagetrennte logische Entitätsnamen |
+| `--solutions <list>` | string | - | Kommagetrennte eindeutige Lösungsnamen |
+| `--output <dir>` | string | ./typings | Ausgabeverzeichnis |
+| `--label-language <n>` | string | 1033 | Primäre Label-Sprache (LCID) |
+| `--secondary-language <n>` | string | - | Sekundäre Label-Sprache für JSDoc |
+| `--no-forms` | flag | - | Formular-Interface-Generierung überspringen |
+| `--no-optionsets` | flag | - | OptionSet-Enum-Generierung überspringen |
+| `--actions` | flag | false | Custom-API-Executors generieren |
+| `--actions-filter <prefix>` | string | - | Custom APIs nach Uniquename-Präfix filtern |
+| `--cache` | flag | false | Metadaten-Caching für inkrementelle Generierung aktivieren |
+| `--no-cache` | flag | - | Vollständige Metadaten-Aktualisierung erzwingen |
+| `--cache-dir <dir>` | string | .xrmforge/cache | Cache-Verzeichnis |
+| `-v, --verbose` | flag | false | Debug-Logging |
+
+Mindestens eines von `--entities` oder `--solutions` ist erforderlich.
+
+## 4.2 `xrmforge build`
+
+Baut WebResources als IIFE-Bundles mit esbuild (über @xrmforge/devkit).
+
+| Flag | Typ | Standard | Beschreibung |
+|------|-----|----------|--------------|
+| `--watch` | flag | false | Watch-Modus mit inkrementellen Rebuilds |
+| `--minify` | flag | aus Konfiguration | Minifizierungseinstellung überschreiben |
+| `--no-sourcemap` | flag | - | Source Maps deaktivieren |
+| `--out-dir <dir>` | string | aus Konfiguration | Ausgabeverzeichnis überschreiben |
+| `-v, --verbose` | flag | false | Fehlerstacks anzeigen |
+
+Liest die Konfiguration aus `xrmforge.config.json`.
+
+## 4.3 `xrmforge init`
+
+Erstellt ein neues D365-Formularskript-Projekt.
+
+| Flag | Typ | Standard | Beschreibung |
+|------|-----|----------|--------------|
+| `[dir]` | positional | . | Zielverzeichnis |
+| `--name <name>` | string | Verzeichnisname | Projektname für package.json |
+| `--prefix <prefix>` | string | contoso | Publisher-Präfix |
+| `--namespace <ns>` | string | PascalCase(prefix) | Basis-Namespace für Skripte |
+| `--skip-install` | flag | false | npm install überspringen |
+| `--force` | flag | false | Nicht-leere Verzeichnisse erlauben |
+
+Generiert 11 Dateien: package.json, tsconfig.json, xrmforge.config.json, vitest.config.ts, .gitignore, AGENT.md, example-form.ts, example-form.test.ts, typings/.gitkeep, GitHub Actions CI, Azure DevOps Pipeline.

package/docs/architektur/05-build.md

@@ -0,0 +1,50 @@
+# 5. Build-Architektur
+
+## 5.1 esbuild IIFE-Bundles
+
+XrmForge verwendet esbuild, um IIFE-Bundles (Immediately Invoked Function Expression) für Dynamics 365 zu erstellen. D365 erfordert, dass Skripte als namespace.function registriert werden (z.B. `Contoso.Account.onLoad`).
+
+**esbuild-Konfiguration pro Eintrag:**
+```
+format: 'iife'
+bundle: true
+globalName: entry.namespace    // z.B. 'Contoso.Account'
+target: config.target          // Standard: 'es2020'
+minify: config.minify
+sourcemap: config.sourcemap
+external: config.external      // z.B. ['fs', 'path'] für Node.js-Abhängigkeiten
+```
+
+Alle Einträge werden parallel mit `Promise.allSettled()` gebaut, was Teilerfolge ermöglicht.
+
+## 5.2 xrmforge.config.json Schema
+
+```json
+{
+  "build": {
+    "outDir": "./dist/prefix_/JS",
+    "target": "es2020",
+    "sourcemap": true,
+    "minify": true,
+    "external": [],
+    "entries": {
+      "entry_name": {
+        "input": "./src/forms/account-form.ts",
+        "namespace": "Contoso.Account",
+        "out": "Account/OnLoad.js"
+      }
+    }
+  }
+}
+```
+
+## 5.3 globalName-Behandlung
+
+esbuild erstellt automatisch verschachtelte Globals aus gepunkteten Namespaces:
+```javascript
+// namespace: "Contoso.Account" erzeugt:
+var Contoso = Contoso || {};
+Contoso.Account = (() => { return { onLoad, onSave }; })();
+```
+
+D365-Event-Registrierung: `Contoso.Account.onLoad`.

package/docs/architektur/06-inkrementell.md

@@ -0,0 +1,42 @@
+# 6. Inkrementelle Generierung
+
+## 6.1 Übersicht
+
+Die inkrementelle Generierung verwendet die Dataverse-Funktion `RetrieveMetadataChanges`, um zu erkennen, welche Entitäten sich seit der letzten Generierung geändert haben. Dies reduziert die Generierungszeit von Sekunden auf Millisekunden (gemessen: 4720ms auf 473ms, 10-fache Verbesserung).
+
+## 6.2 Komponenten
+
+**ChangeDetector** (`src/metadata/change-detector.ts`):
+- `getInitialVersionStamp()` - Erster Lauf: holt den initialen ServerVersionStamp
+- `detectChanges(clientVersionStamp)` - Folgeläufe: gibt changedEntityNames, deletedEntityNames, newVersionStamp zurück
+
+**MetadataCache** (`src/metadata/cache.ts`):
+- Dateisystem-basiert: `.xrmforge/cache/metadata.json`
+- Speichert: Manifest (Version, Umgebungs-URL, ServerVersionStamp, letzter Refresh, Entitätsliste) + entityTypeInfos pro Entität
+- Validierung: prüft Cache-Version, Umgebungs-URL-Übereinstimmung, Dateiexistenz
+
+## 6.3 Ablauf
+
+```
+Erster Lauf (kein Cache):
+  1. Alle Entitäts-Metadaten abrufen
+  2. getInitialVersionStamp()
+  3. Cache mit ServerVersionStamp speichern
+
+Folgelauf (Cache vorhanden):
+  1. Cache laden, Umgebungs-URL validieren
+  2. detectChanges(cachedVersionStamp)
+  3. Nur geänderte Entitäten abrufen
+  4. Gelöschte Entitäten aus Cache entfernen
+  5. Cache mit neuem ServerVersionStamp speichern
+
+Abgelaufener Stempel (>90 Tage):
+  Fehlercode 0x80044352 erkannt
+  Rückfall auf vollständigen Refresh
+```
+
+## 6.4 RetrieveMetadataChanges API
+
+- **Typ:** OData-Funktion (GET, nicht POST)
+- **URL:** `/RetrieveMetadataChanges(Query=@q,ClientVersionStamp=@s)?@q={...}&@s='...'`
+- **Antwort:** EntityMetadata[] mit HasChanged-Flag, ServerVersionStamp, DeletedMetadata

package/docs/architektur/07-http-client.md

@@ -0,0 +1,59 @@
+# 7. HTTP-Client
+
+## 7.1 DataverseHttpClient
+
+Der zentrale HTTP-Client (`src/http/client.ts`) bietet belastbare Kommunikation mit der Dataverse Web API.
+
+**Kernmethoden:**
+- `get<T>(path, signal?)` - Einzelne GET-Anfrage mit Retry
+- `getAll<T>(path, signal?)` - GET mit automatischer @odata.nextLink-Paginierung (max 100 Seiten)
+
+## 7.2 Nur-Lesen-Standard
+
+Der Client ist standardmäßig auf `readOnly: true` eingestellt und blockiert POST/PATCH/PUT/DELETE-Anfragen. Dies verhindert versehentliche Datenänderungen während der Typgenerierung. Schreibzugriff erfordert explizites `readOnly: false`.
+
+## 7.3 Retry mit exponentiellem Backoff
+
+- **Basisverzögerung:** 1000ms (konfigurierbar)
+- **Maximaler Backoff:** 60 Sekunden
+- **Jitter:** Zufällige Verzögerung bis zur Basisverzögerung
+- **Formel:** `min(baseDelay * 2^(attempt-1) + jitter, 60000)`
+- **Maximale Retries:** konfigurierbar (Standard: 3)
+
+## 7.4 Rate Limiting (HTTP 429)
+
+- **Separater Zähler** von Standard-Retries (nicht vermischt)
+- **Retry-After-Header** wird respektiert (Sekunden in Millisekunden umgerechnet)
+- **Maximal 10 aufeinanderfolgende 429-Retries** (DEFAULT_MAX_RATE_LIMIT_RETRIES)
+- 429-Antworten inkrementieren den Standard-Retry-Zähler NICHT
+
+## 7.5 Nebenläufigkeitssteuerung
+
+Nicht-rekursives Semaphor-Muster:
+- **maxConcurrency:** 5 (Standard)
+- Warteschlange mit FIFO-Reihenfolge
+- Alle Retries erfolgen innerhalb eines einzelnen Slots (verhindert Slot-Erschöpfung)
+
+## 7.6 Token-Caching
+
+- Nur im Speicher (wird niemals auf die Festplatte persistiert)
+- 5-Minuten-Puffer vor Ablauf (TOKEN_BUFFER_MS = 300000)
+- Ausstehende Token-Refresh-Promise verhindert gleichzeitige Token-Anfragen
+
+## 7.7 Eingabe-Sanitisierung
+
+OData-Injection-Prävention:
+- `sanitizeIdentifier()` - Regex `[a-zA-Z_][a-zA-Z0-9_]*`
+- `sanitizeGuid()` - GUID-Format-Validierung
+- `escapeODataString()` - Verdopplung einfacher Anführungszeichen
+
+## 7.8 Fehlerbehandlung
+
+| HTTP-Status | Verhalten | Retry |
+|-------------|-----------|-------|
+| 2xx | Erfolg | Nein |
+| 401 | Token-Cache leeren, einmal wiederholen | Ja (1x) |
+| 429 | Retry-After respektieren, separater Zähler | Ja (bis zu 10x) |
+| 5xx | Exponentieller Backoff | Ja (bis zu maxRetries) |
+| 404, 403 | Nicht wiederholbar | Nein |
+| Netzwerkfehler | Exponentieller Backoff | Ja |

package/docs/architektur/08-authentifizierung.md

@@ -0,0 +1,18 @@
+# 8. Authentifizierung
+
+## 8.1 Credential Factory
+
+`createCredential(config: AuthConfig)` gibt ein `TokenCredential` (aus @azure/identity) basierend auf der Authentifizierungsmethode zurück:
+
+## 8.2 Vier Authentifizierungsabläufe
+
+| Methode | Konfiguration | @azure/identity-Klasse | Anwendungsfall |
+|---------|---------------|------------------------|----------------|
+| client-credentials | tenantId, clientId, clientSecret | ClientSecretCredential | CI/CD, automatisierte Pipelines |
+| interactive | tenantId, clientId? | InteractiveBrowserCredential | Entwickler-Arbeitsplatz |
+| device-code | tenantId, clientId? | DeviceCodeCredential | Headless-CLI-Umgebungen |
+| token | token (string) | StaticTokenCredential | Vorab erworbene Tokens (z.B. aus TokenVault) |
+
+## 8.3 Token-Scope
+
+Alle Authentifizierungsabläufe fordern den Scope an: `{environmentUrl}/.default`

package/docs/architektur/09-testing.md

@@ -0,0 +1,55 @@
+# 9. Test-Framework
+
+## 9.1 createFormMock
+
+```typescript
+import { createFormMock } from '@xrmforge/testing';
+import type { AccountMainForm, AccountMainFormMockValues } from '../typings/forms/account';
+
+const mock = createFormMock<AccountMainForm, AccountMainFormMockValues>({
+  name: 'Contoso Ltd',
+  statuscode: 0,
+  revenue: 1000000,
+});
+
+// Verwendung in Tests:
+onLoad(mock.executionContext);
+expect(mock.formContext.getControl('revenue').getVisible()).toBe(true);
+```
+
+**Was gemockt wird:**
+- Attribute: MockAttribute-Instanzen mit getValue/setValue, Dirty-Tracking, onChange-Handlern, Required Level, Submit Mode
+- Steuerelemente: MockControl-Instanzen mit Sichtbarkeits-/Deaktiviert-/Label-/Benachrichtigungszustand
+- UI: Formular-Benachrichtigungen, Tab/Section-Stubs
+- Entität: ID, Entitätsname, Primärattribut
+- Daten: refresh(), save() Stubs, die Promise-ähnliches zurückgeben
+- Navigation: openForm/openAlertDialog Stubs
+
+**Lazy-Initialisierung:** Attribute, die über `getAttribute()` angesprochen werden und nicht in den initialen Werten enthalten waren, werden spontan mit null-Wert erstellt.
+
+## 9.2 fireOnChange
+
+```typescript
+mock.fireOnChange('statuscode');
+// Löst alle über getAttribute('statuscode').addOnChange(handler) registrierten Handler aus
+```
+
+Erstellt einen MockEventContext mit dem Attribut als Eventquelle.
+
+## 9.3 setupXrmMock / teardownXrmMock
+
+```typescript
+import { setupXrmMock, teardownXrmMock } from '@xrmforge/testing';
+
+beforeEach(() => setupXrmMock());
+afterEach(() => teardownXrmMock());
+
+// Mit WebApi-Überschreibungen:
+setupXrmMock({
+  webApiOverrides: {
+    retrieveMultipleRecords: async () => ({ entities: [{ name: 'Test' }] }),
+  },
+});
+```
+
+Richtet ein globales `Xrm`-Objekt auf `globalThis` ein mit minimalen WebApi-, Navigation- und Utility-Stubs.

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

@@ -0,0 +1,82 @@
+# 10. ESLint Plugin
+
+## 10.1 Installation
+
+```javascript
+// eslint.config.js (Flat Config, ESLint v9)
+import xrmforge from '@xrmforge/eslint-plugin';
+
+export default [
+  xrmforge.configs.recommended,
+  // oder einzelne Regeln auswählen
+];
+```
+
+## 10.2 Regeln
+
+### no-xrm-page (error)
+
+Verbietet die veraltete `Xrm.Page`-API (entfernt in D365 v9.0+).
+
+```typescript
+// Falsch
+Xrm.Page.getAttribute("name");
+
+// Richtig
+const form = executionContext.getFormContext();
+form.getAttribute("name");
+```
+
+### no-magic-optionset (warn)
+
+Verbietet rohe Zahlen (>= 2) in Vergleichen mit `.getValue()`.
+
+```typescript
+// Falsch
+if (attr.getValue() === 595300000) { }
+
+// Richtig
+import { StatusCode } from '../typings/optionsets/account';
+if (attr.getValue() === StatusCode.Active) { }
+```
+
+### no-sync-webapi (error)
+
+Verbietet synchrone XMLHttpRequest (`new XMLHttpRequest()` und `.open()` mit `async=false`).
+
+```typescript
+// Falsch
+xhr.open("GET", url, false);
+
+// Richtig
+const data = await Xrm.WebApi.retrieveRecord("account", id);
+```
+
+### require-error-handling (warn)
+
+Verlangt try/catch in exportierten async-Funktionen, die mit "on" beginnen (Event-Handler).
+
+```typescript
+// Falsch
+export async function onLoad(ctx) {
+  await fetch("/api");  // keine Fehlerbehandlung
+}
+
+// Richtig
+export async function onLoad(ctx) {
+  try { await fetch("/api"); }
+  catch (error) { console.error(error); }
+}
+```
+
+### require-namespace (warn)
+
+Verbietet direkte `window.X = ...` oder `globalThis.X = ...` Zuweisungen. Stattdessen sollen Modul-Exports mit esbuild globalName verwendet werden.
+
+```typescript
+// Falsch
+window.Contoso = { onLoad: function() {} };
+
+// Richtig
+export function onLoad(ctx: Xrm.Events.EventContext) {}
+```