@xrmforge/typegen 0.7.0 → 0.8.0

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 | ./generated | 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, generated/.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 '../generated/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 '../generated/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) {}
+```

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

@@ -0,0 +1,38 @@
+# 11. AGENT.md System
+
+## 11.1 Zweck
+
+Die AGENT.md ist eine generierte Datei, die KI-Coding-Assistenten (Claude, ChatGPT, Copilot, Cursor) beibringt, wie sie optimale D365-Formularskripte mit XrmForge schreiben. Sie wird von `xrmforge init` erzeugt und im Projektstamm abgelegt.
+
+## 11.2 Inhaltsstruktur
+
+1. **Package-Übersicht** - Was jedes @xrmforge-Package tut
+2. **10 Regeln: Immer** - Fields Enum, OptionSet Enum, FormContext-Cast, EntityNames, parseLookup, select, createFormMock, Modul-Exports, Tabs/Sections Enums, Fehlerbehandlung
+3. **Regeln: Niemals** - Rohe Strings, Magic Numbers, Xrm.Page, synchrone XHR, eval, window-Zuweisungen
+4. **Vorher/Nachher-Beispiele** - Feldzugriff, OptionSet-Vergleich, Testen
+5. **Pattern-Erkennungstabelle** - Zuordnung von Legacy-Pattern zu XrmForge-Ersetzung
+6. **OptionSet-Enum-Erstellungsanleitung** - Wie man Enums aus Magic Numbers in Legacy-Code erstellt
+7. **Testen mit setupXrmMock** - Globales Xrm-Mock-Pattern
+8. **Build-Befehle** - xrmforge build, Watch-Modus
+9. **@types/xrm-Fallstricke** - Bekannte Probleme und Workarounds
+10. **Dateistruktur** - Erwartetes Projektlayout
+
+## 11.3 Template-System
+
+Die AGENT.md ist als `src/scaffold/templates/AGENT.md` im devkit-Package gespeichert und wird zur Scaffolding-Zeit über `template-loader.ts` geladen. Es ist keine Variablenersetzung nötig (die Datei ist statisch).
+
+## 11.4 Ergebnisse des KI-Vergleichstests
+
+Fünf KI-Modelle wurden beim Konvertieren von Legacy-D365-JavaScript (account.js + lm_helper.js, 1.288 Zeilen) zu TypeScript mit XrmForge getestet:
+
+| Rang | Modell | Punkte | Werkzeug | Stärke |
+|------|--------|--------|----------|--------|
+| 1 | Claude Opus 4.6 | 42/50 | Claude Code | Meiste Tests (62), beste Codestruktur |
+| 2 | Claude Sonnet 4.6 | 41/50 | Claude Code | Meiste Bugs gefunden (5), bester DI-Ansatz |
+| 3 | Cursor Composer 2 | 35/50 | Cursor IDE | Hat select() Node-API-Problem erkannt |
+| 4 | ChatGPT GPT-4o | 30/50 | ChatGPT Web | Funktional, aber weniger XrmForge-spezifisch |
+| 5 | MS Copilot | 12/50 | Browser-Chat | Kein Workspace-Zugriff, hat AGENT.md nie gesehen |
+
+**Kriterien (11, maximal 5 Punkte je = 55 max):** Fields-Enum-Nutzung, OptionSet-Enums, FormContext-Typisierung, XrmForge-Helpers, Modul-Exports, Tests vorhanden, Testqualität, Fehlerbehandlung, Codequalität, gefundene Bugs, Dokumentation.
+
+**Zentrale Erkenntnis:** Keine KI hat konsistent `@xrmforge/helpers`-Imports (select, parseLookup) verwendet. Dies bleibt die grösste Adoptionslücke.

package/docs/architektur/12-xrm-fallstricke.md

@@ -0,0 +1,14 @@
+# 12. @types/xrm-Fallstricke
+
+Bekannte Probleme bei der Arbeit mit `@types/xrm`:
+
+| Problem | Falsch | Richtig |
+|---------|--------|---------|
+| Form-Interface | `interface extends Xrm.FormContext` | `extends Omit<Xrm.FormContext, 'getAttribute' \| 'getControl'>` |
+| AlertDialogResponse | `Xrm.Navigation.AlertDialogResponse` | `Xrm.Async.PromiseLike<void>` (Typ existiert nicht) |
+| ConfirmDialogResponse | `Xrm.Navigation.ConfirmDialogResponse` | `Xrm.Navigation.ConfirmResult` (Typ existiert nicht) |
+| setNotification | `setNotification(message)` | `setNotification(message, uniqueId)` (erfordert 2 Argumente) |
+| openFile | `openFile({ fileName, ... })` | Muss `fileSize`-Eigenschaft in FileDetails enthalten |
+| SubmitMode | `Xrm.Attributes.SubmitMode` | `Xrm.SubmitMode` |
+| const enum in .d.ts | `const enum` in `.d.ts`-Dateien | `const enum` in `.ts`-ES-Modulen verwenden (typegen 0.8.0+ generiert `.ts`-Dateien, wodurch dieses Problem gelöst ist) |
+| Grid.refresh() | `grid.refresh()` | `(grid as any).refresh()` (nicht typisiert in @types/xrm) |

package/docs/architektur/13-helpers.md

@@ -0,0 +1,50 @@
+# 13. @xrmforge/helpers Package
+
+## 13.1 Problem
+
+Der bisherige Ansatz nutzte einen `/helpers`-Subpath-Export auf `@xrmforge/typegen`. Das war verwirrend, weil typegen ein Node.js-Codegenerierungstool ist, während die Helpers browsersichere Laufzeitfunktionen sind. Der Subpath `@xrmforge/typegen/helpers` war nicht intuitiv und KI-Coding-Assistenten haben ihn durchgängig nicht gefunden.
+
+## 13.2 Lösung
+
+Ein eigenständiges `@xrmforge/helpers`-Package bündelt allen browsersicheren Laufzeitcode. Keine Node.js-Abhängigkeiten. Klarer, auffindbarer Import-Pfad:
+
+```typescript
+// Import vom dedizierten helpers-Package
+import { select, parseLookup, typedForm } from '@xrmforge/helpers';
+```
+
+## 13.3 Exports
+
+**Web-API-Helpers:**
+- `select(...fields: string[]): string` - Erstellt `?$select=field1,field2`
+- `selectExpand(fields: string[], expand: string): string` - Erstellt `?$select=...&$expand=...`
+- `parseLookup(response: Record<string, unknown>, fieldName: string): LookupValue | null` - Parst `_fieldname_value` mit OData-Annotationen
+- `parseLookups(response: Record<string, unknown>, fieldName: string): LookupValue[]` - Multi-Value-Lookup-Parsing
+- `parseFormattedValue(response: Record<string, unknown>, fieldName: string): string | null` - Extrahiert `@OData.Community.Display.V1.FormattedValue`
+
+**Xrm-Konstanten (8 const enums):**
+- DisplayState, FormNotificationLevel, RequiredLevel, SubmitMode, SaveMode, ClientType, ClientState, OperationType
+
+**typedForm()-Proxy:**
+- `typedForm<TForm>(formContext)` - Gibt einen Proxy zurück, bei dem `form.name` an `getAttribute('name')` delegiert
+- GET-Trap: Property-Zugriff delegiert an getAttribute(); `$context` gibt den rohen FormContext zurück; `$control(name)` gibt getControl() zurück
+- SET-Trap: Wirft TypeError und erzwingt die Verwendung von `.setValue()`
+- HAS-Trap: Prüft, ob ein Attribut auf dem Formular existiert
+
+**Action/Function-Laufzeit:**
+- `createBoundAction(entityName, actionName)` - Erstellt einen gebundenen Action-Executor
+- `executeRequest(request)` - Führt einen Organization Request über Xrm.WebApi.online.execute aus
+- `withProgress(message, fn)` - Umhüllt eine asynchrone Operation mit Xrm.Utility.showProgressIndicator
+
+## 13.4 Migration
+
+Der alte Import-Pfad `@xrmforge/typegen/helpers` wurde entfernt. Alle Imports aktualisieren:
+
+```typescript
+// Alt (entfernt)
+import { select } from '@xrmforge/typegen/helpers';
+import { typedForm } from '@xrmforge/formhelpers';
+
+// Neu
+import { select, typedForm } from '@xrmforge/helpers';
+```

package/docs/architektur/14-showcases.md

@@ -0,0 +1,21 @@
+# 14. Showcases
+
+## 14.1 Markant WebResources (Produktions-Showcase)
+
+Befindet sich im XrmForge-Workspace-Repository unter `docs/07_showcase/markant-webresources/`.
+
+- **30 WebResources** in `src/forms/` (Account, Contact, Opportunity, Lead, Quote, Email, Task usw.)
+- **1 gemeinsame Bibliothek** (DSGVO-Aufbewahrungsfristen-UI)
+- **9 Testdateien** mit 59 Tests
+- **79 generierte Typings:** 25 Form-Interfaces, 28 Entity-Interfaces, 22 OptionSet-Dateien, 4 Action-Executors
+- **esbuild-Build** über xrmforge.config.json (32 Einträge)
+- **Deploy-Skript** (deploy.mjs) mit @azure/identity-Authentifizierung, inkrementellem Deployment, Hash-basierter Änderungserkennung
+- **27 Entitäten, 236 OptionSet-Enums, 95 Form-Interfaces, 7 Custom-API-Executors**
+
+## 14.2 LMApp WebResources (KI-Vergleichs-Showcase)
+
+Erstellt während der KI-Vergleichstests (Session 9). 18 Legacy-JavaScript-Formularskripte (~8.400 Zeilen) zu TypeScript mit XrmForge-Patterns konvertiert.
+
+- **19 WebResources** mit Fields Enums, EntityNames, OptionSet Enums
+- **84 Tests** in 8 Testdateien
+- **XrmForge-optimiert:** Alle 10 AGENT.md-Regeln angewendet (FormContext-Cast, Fields Enum, EntityNames, OptionSet Enums, gemeinsames getLookupObject, Tab Enums)

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

@@ -0,0 +1,49 @@
+# 15. CI/CD
+
+## 15.1 GitHub Actions CI (`.github/workflows/ci.yml`)
+
+**Auslöser:** Push auf main, Pull Requests gegen main.
+
+**Matrix:** Node 20, Node 22 auf ubuntu-latest.
+
+**Schritte:**
+1. Checkout
+2. pnpm einrichten (aus packageManager-Feld)
+3. Node.js einrichten (Matrix-Version)
+4. `pnpm install --frozen-lockfile`
+5. `pnpm lint`
+6. `pnpm -r exec tsc --noEmit` (Typecheck aller Packages)
+7. `pnpm build`
+8. `pnpm test`
+9. Coverage (nur Node 22): `npx vitest run --coverage` in typegen
+
+## 15.2 Release-Workflow (`.github/workflows/release.yml`)
+
+**Auslöser:** Nach erfolgreicher CI bei Push auf main.
+
+**Schritte:**
+1. Checkout, pnpm einrichten, Node 22 einrichten
+2. `pnpm install --frozen-lockfile`
+3. `pnpm build`
+4. Changesets-Action: erstellt Release-PR oder veröffentlicht auf npm
+
+**Publish-Befehl:** `pnpm release` = `turbo run build && changeset publish`
+
+## 15.3 Turbo-Pipeline
+
+```
+build:      dependsOn: [^build], outputs: [dist/**]
+test:       dependsOn: [build]
+typecheck:  dependsOn: [^build]
+lint:       (keine Abhängigkeiten)
+dev:        cache: false, persistent: true
+clean:      cache: false
+```
+
+## 15.4 Changesets
+
+Konfiguriert für öffentlichen npm-Zugriff, automatische Aktualisierung interner Abhängigkeiten auf Patch-Ebene. Veröffentlichung erfordert NPM_TOKEN Secret.
+
+## 15.5 Veröffentlichungsreihenfolge
+
+Aufgrund interner Abhängigkeiten: zuerst typegen, dann devkit, dann cli. Es muss `pnpm publish` verwendet werden (nicht `npm publish`), um `workspace:*`-Referenzen in echte Versionen aufzulösen.

package/docs/architektur/16-technische-schulden.md

@@ -0,0 +1,17 @@
+# 16. Technische Schulden
+
+## 16.1 Bekannte Probleme
+
+| Problem | Status | Priorität |
+|---------|--------|-----------|
+| parseLookup/select wird von KI-Assistenten nicht übernommen | Offen | Hoch |
+| release.yml doppelte Ausführungen (CI löst Release aus, Release löst CI erneut aus) | Offen | Niedrig |
+| Keine Integrationstests gegen Live-Dataverse | Offen (OE-4) | Mittel |
+| @xrmforge/webapi hat keine Action/Function-Unterstützung | Akzeptiert | Niedrig |
+| devDependency-Versionen im generierten package.json sind auf alte Versionen fixiert | Offen | Niedrig |
+
+## 16.2 Akzeptierte Einschränkungen
+
+- **const-enum-Einschränkung:** Gelöst in typegen 0.8.0. Generierter Output sind jetzt `.ts`-ES-Module, sodass `const enum` direkt mit vitest und anderen Test-Frameworks funktioniert.
+- **Grid.refresh() erfordert `as any`:** Nicht typisiert in @types/xrm.
+- **Eine Solution pro Entität:** Wenn eine Entität in mehreren Solutions vorkommt, wird sie nur einmal generiert.

package/docs/architektur/17-roadmap.md

@@ -0,0 +1,25 @@
+# 17. Roadmap
+
+## 17.1 Nächste Schritte (Prioritätsreihenfolge)
+
+1. **parseLookup/select-Adoption** - AGENT.md-Beispiele verbessern, damit KI-Assistenten konsistent `/helpers`-Imports verwenden
+2. **LMApp-Showcase-Neugenerierung** - Mit aktuellen Releases (testing@0.2.0, devkit@0.4.0 mit verbesserter AGENT.md)
+3. **KI-Battle Runde 3** - Sonnet vs. Opus erneut testen nach Verbesserungen, um Fortschritt zu messen
+4. **Dokumentationswebsite** - xrmforge.dev oder xrmforge.io (OE-3)
+
+## 17.2 Offene Entscheidungen
+
+| ID | Entscheidung | Status |
+|----|--------------|--------|
+| OE-1 | npm-Scope-Verfügbarkeit (@xrmforge) | Offen |
+| OE-2 | GitHub-Org vs. persönliches Repo | Entschieden: persönlich (juergenbeck/XrmForge) |
+| OE-3 | Dokumentationsdomain (xrmforge.dev oder .io) | Offen |
+| OE-4 | Dataverse-Testumgebung für Integrationstests | Offen |
+| OE-5 | Publisher-Prefix und Solution-Name für PCF/WebResource-Tests | Offen |
+
+## 17.3 Zukünftige Möglichkeiten
+
+- Relationship-Names const enum (OE-7, niedrige Priorität)
+- @xrmforge/webapi mit Action/Function-Unterstützung (DataverseHttpClient wiederverwenden)
+- Plugin-System für benutzerdefinierte Generatoren und Typ-Zuordnungen
+- Serverseitige Generierung (Custom API in Dataverse)

package/docs/architektur/18-designprinzipien.md

@@ -0,0 +1,22 @@
+# 18. Designprinzipien
+
+Die 18 Designprinzipien, die die gesamte XrmForge-Entwicklung bestimmen:
+
+1. **Erweitern, nicht ersetzen** - Typen bauen auf @types/xrm auf, überschreiben sie nie.
+2. **TypeScript durchgängig** - 100% TypeScript-nativ. Kein .NET, kein ADAL.
+3. **Code muss bauen** - Jeder Arbeitsschritt endet mit grünem Build + Tests.
+4. **Recherche vor Geschwindigkeit** - Untersuchen, vergleichen, entscheiden, dann implementieren. Niemals raten.
+5. **Kein Modul ohne Grundlagen** - Fehlerbehandlung, Logging, Unit-Tests, JSDoc auf allen öffentlichen APIs.
+6. **Monorepo-Disziplin** - Jedes Package eigenständig, keine zirkulären Abhängigkeiten, Barrel-Exports.
+7. **Enterprise-Resilienz** - Retry + exponentielles Backoff, Rate-Limit-Erkennung, Token-Caching, Read-only als Standard.
+8. **esbuild-first, webpack-kompatibel** - Standard: esbuild (schnell). webpack bleibt unterstützt. IIFE-Output für D365.
+9. **Nur MSAL-Authentifizierung** - Ausschliesslich @azure/identity (kein Legacy-ADAL). Drei Flows: Client Credentials, Browser, Device Code.
+10. **Review erforderlich** - Nach jedem Schritt sofortiges kritisches Review (6 Dimensionen). Nicht fragen, ob Review gewünscht ist.
+11. **Session-State erforderlich** - session-state.md aktualisiert, Changelog geschrieben, offene Fragen erfasst.
+12. **Keine halben Sachen** - Jeder Schritt vollständig abgeschlossen: grüner Build + Tests + Review vor dem nächsten Schritt.
+13. **Fundierte Architekturentscheidungen** - Recherchieren, vergleichen, mit Pro/Contra empfehlen, Entscheidung einholen, persistieren.
+14. **Abstraktion statt Vendor-Lock-in** - Externe Abhängigkeiten hinter Interfaces (Parser, Auth, Bundler).
+15. **Zweisprachige Labels** - Primärsprache (1033/Englisch) für Bezeichner, Sekundärsprache in JSDoc. Deutsche Umlaute transliteriert.
+16. **Review mit Recherche und Live-Verifikation** - Internetrecherche, Live-D365-Verifikation, Produktionscode-Prüfungen, Quellen zitieren.
+17. **Aufschub hinterfragen** - "Später"-Check: Wird es schwieriger? API-Vertrag? Echter Aufwand? Technische Gründe?
+18. **Read-only als Standard für Dataverse-Zugriff** - DataverseHttpClient ist standardmässig readOnly: true. Schreibzugriff ist ein explizites Opt-in.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xrmforge/typegen",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "TypeScript declaration generator for Dynamics 365 / Dataverse",
   "keywords": [
     "dynamics-365",
@@ -33,6 +33,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "MIGRATION.md"
   ],
   "sideEffects": false,
@@ -54,12 +55,12 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node scripts/copy-docs.mjs",
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist docs"
   }
 }