@xrmforge/typegen 0.6.0 → 0.7.1

package/docs/architecture/05-build.md

@@ -0,0 +1,50 @@
+# Build Architecture
+
+### 5.1 esbuild IIFE Bundles
+
+XrmForge uses esbuild to create IIFE (Immediately Invoked Function Expression) bundles for Dynamics 365. D365 requires scripts to be registered as namespace.function (e.g. `Contoso.Account.onLoad`).
+
+**esbuild configuration per entry:**
+```
+format: 'iife'
+bundle: true
+globalName: entry.namespace    // e.g. 'Contoso.Account'
+target: config.target          // default: 'es2020'
+minify: config.minify
+sourcemap: config.sourcemap
+external: config.external      // e.g. ['fs', 'path'] for Node.js deps
+```
+
+All entries are built in parallel using `Promise.allSettled()`, allowing partial success.
+
+### 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 Handling
+
+esbuild automatically creates nested globals from dotted namespaces:
+```javascript
+// namespace: "Contoso.Account" produces:
+var Contoso = Contoso || {};
+Contoso.Account = (() => { return { onLoad, onSave }; })();
+```
+
+D365 event registration: `Contoso.Account.onLoad`.

package/docs/architecture/06-incremental.md

@@ -0,0 +1,42 @@
+# Incremental Generation
+
+### 6.1 Overview
+
+Incremental generation uses the Dataverse `RetrieveMetadataChanges` function to detect which entities have changed since the last generation. This reduces generation time from seconds to milliseconds (measured: 4720ms to 473ms, 10x improvement).
+
+### 6.2 Components
+
+**ChangeDetector** (`src/metadata/change-detector.ts`):
+- `getInitialVersionStamp()` - First run: fetches the initial ServerVersionStamp
+- `detectChanges(clientVersionStamp)` - Subsequent runs: returns changedEntityNames, deletedEntityNames, newVersionStamp
+
+**MetadataCache** (`src/metadata/cache.ts`):
+- Filesystem-based: `.xrmforge/cache/metadata.json`
+- Stores: manifest (version, environment URL, ServerVersionStamp, last refreshed, entity list) + entityTypeInfos per entity
+- Validation: checks cache version, environment URL match, file existence
+
+### 6.3 Flow
+
+```
+First run (no cache):
+  1. Fetch all entity metadata
+  2. getInitialVersionStamp()
+  3. Save cache with ServerVersionStamp
+
+Subsequent run (cache exists):
+  1. Load cache, validate environment URL
+  2. detectChanges(cachedVersionStamp)
+  3. Fetch only changed entities
+  4. Remove deleted entities from cache
+  5. Save cache with new ServerVersionStamp
+
+Expired stamp (>90 days):
+  Error code 0x80044352 detected
+  Fall back to full refresh
+```
+
+### 6.4 RetrieveMetadataChanges API
+
+- **Type:** OData Function (GET, not POST)
+- **URL:** `/RetrieveMetadataChanges(Query=@q,ClientVersionStamp=@s)?@q={...}&@s='...'`
+- **Response:** EntityMetadata[] with HasChanged flag, ServerVersionStamp, DeletedMetadata

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

@@ -0,0 +1,59 @@
+# HTTP Client
+
+### 7.1 DataverseHttpClient
+
+The core HTTP client (`src/http/client.ts`) provides resilient communication with the Dataverse Web API.
+
+**Key methods:**
+- `get<T>(path, signal?)` - Single GET request with retry
+- `getAll<T>(path, signal?)` - GET with automatic @odata.nextLink paging (max 100 pages)
+
+### 7.2 Read-Only Default
+
+The client defaults to `readOnly: true`, blocking POST/PATCH/PUT/DELETE requests. This prevents accidental data mutations during type generation. Write access requires explicit `readOnly: false`.
+
+### 7.3 Retry with Exponential Backoff
+
+- **Base delay:** 1000ms (configurable)
+- **Max backoff:** 60 seconds
+- **Jitter:** Random delay up to base delay
+- **Formula:** `min(baseDelay * 2^(attempt-1) + jitter, 60000)`
+- **Max retries:** configurable (default: 3)
+
+### 7.4 Rate Limiting (HTTP 429)
+
+- **Separate counter** from standard retries (not mixed)
+- **Retry-After header** respected (seconds converted to milliseconds)
+- **Max 10 consecutive 429 retries** (DEFAULT_MAX_RATE_LIMIT_RETRIES)
+- 429 responses do NOT increment the standard retry counter
+
+### 7.5 Concurrency Control
+
+Non-recursive semaphore pattern:
+- **maxConcurrency:** 5 (default)
+- Wait queue with FIFO ordering
+- All retries happen inside a single slot (prevents slot exhaustion)
+
+### 7.6 Token Caching
+
+- In-memory only (never persisted to disk)
+- 5-minute buffer before expiry (TOKEN_BUFFER_MS = 300000)
+- Pending token refresh promise prevents concurrent token requests
+
+### 7.7 Input Sanitization
+
+OData injection prevention:
+- `sanitizeIdentifier()` - Regex `[a-zA-Z_][a-zA-Z0-9_]*`
+- `sanitizeGuid()` - GUID format validation
+- `escapeODataString()` - Single quote doubling
+
+### 7.8 Error Handling
+
+| HTTP Status | Behavior | Retried |
+|-------------|----------|---------|
+| 2xx | Success | No |
+| 401 | Clear token cache, retry once | Yes (1x) |
+| 429 | Respect Retry-After, separate counter | Yes (up to 10x) |
+| 5xx | Exponential backoff | Yes (up to maxRetries) |
+| 404, 403 | Non-retryable | No |
+| Network error | Exponential backoff | Yes |

package/docs/architecture/08-authentication.md

@@ -0,0 +1,18 @@
+# Authentication
+
+### 8.1 Credential Factory
+
+`createCredential(config: AuthConfig)` returns a `TokenCredential` (from @azure/identity) based on the auth method:
+
+### 8.2 Four Auth Flows
+
+| Method | Config | @azure/identity Class | Use Case |
+|--------|--------|-----------------------|----------|
+| client-credentials | tenantId, clientId, clientSecret | ClientSecretCredential | CI/CD, automated pipelines |
+| interactive | tenantId, clientId? | InteractiveBrowserCredential | Developer workstation |
+| device-code | tenantId, clientId? | DeviceCodeCredential | Headless CLI environments |
+| token | token (string) | StaticTokenCredential | Pre-acquired tokens (e.g. from TokenVault) |
+
+### 8.3 Token Scope
+
+All auth flows request the scope: `{environmentUrl}/.default`

package/docs/architecture/09-testing.md

@@ -0,0 +1,55 @@
+# Testing 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,
+});
+
+// Use in tests:
+onLoad(mock.executionContext);
+expect(mock.formContext.getControl('revenue').getVisible()).toBe(true);
+```
+
+**What it mocks:**
+- Attributes: MockAttribute instances with getValue/setValue, dirty tracking, onChange handlers, required level, submit mode
+- Controls: MockControl instances with visible/disabled/label/notification state
+- UI: Form notifications, tab/section stubs
+- Entity: ID, entity name, primary attribute
+- Data: refresh(), save() stubs returning Promise-like
+- Navigation: openForm/openAlertDialog stubs
+
+**Lazy initialization:** Attributes accessed via `getAttribute()` that were not in the initial values are created on-the-fly with null value.
+
+### 9.2 fireOnChange
+
+```typescript
+mock.fireOnChange('statuscode');
+// Triggers all handlers registered via getAttribute('statuscode').addOnChange(handler)
+```
+
+Creates a MockEventContext with the attribute as event source.
+
+### 9.3 setupXrmMock / teardownXrmMock
+
+```typescript
+import { setupXrmMock, teardownXrmMock } from '@xrmforge/testing';
+
+beforeEach(() => setupXrmMock());
+afterEach(() => teardownXrmMock());
+
+// With WebApi overrides:
+setupXrmMock({
+  webApiOverrides: {
+    retrieveMultipleRecords: async () => ({ entities: [{ name: 'Test' }] }),
+  },
+});
+```
+
+Sets up a global `Xrm` object on `globalThis` with minimal WebApi, Navigation, and Utility stubs.

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 '../typings/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/typegen/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 regular `enum` in `.ts` files (vitest cannot import const enums from .d.ts) |
+| 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:** Cannot be imported at runtime by test frameworks from `.d.ts` files. Workaround: use `.ts` files with regular `enum` for manual typings.
+- **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)