@xrmforge/typegen 0.6.0 → 0.7.1

package/MIGRATION.md

@@ -2,6 +2,17 @@
 
 How to convert legacy Dynamics 365 JavaScript to type-safe TypeScript with XrmForge.
 
+## Breaking Changes in v0.7.0
+
+- The `@xrmforge/typegen/helpers` subpath export has been removed.
+- All browser-safe runtime code (`select`, `parseLookup`, `parseFormattedValue`,
+  `withProgress`, Xrm constants, Action/Function executors, `typedForm`) is now
+  in the new package `@xrmforge/helpers`.
+- Update imports: `import { select } from '@xrmforge/typegen/helpers'` becomes
+  `import { select } from '@xrmforge/helpers'`.
+- `@xrmforge/formhelpers` has been removed. `typedForm()` is now in
+  `@xrmforge/helpers`.
+
 ## Step 1: Initialize Project
 
 ```bash
@@ -86,8 +97,8 @@ export function onLoad(executionContext: Xrm.Events.EventContext): void {
 var value = formContext.getAttribute("primarycontactid").getValue();
 var id = value[0].id.replace("{","").replace("}","");
 
-// After: use parseLookup from @xrmforge/typegen
-import { parseLookup } from '@xrmforge/typegen/helpers';
+// After: use parseLookup from @xrmforge/helpers
+import { parseLookup } from '@xrmforge/helpers';
 const contact = parseLookup(form.getAttribute(Fields.PrimaryContactId));
 if (contact) {
   console.log(contact.id);  // already clean GUID
@@ -102,7 +113,7 @@ Xrm.WebApi.retrieveMultipleRecords("account",
   "?$select=name,revenue&$filter=statecode eq 0");
 
 // After: use Fields enum for $select
-import { select } from '@xrmforge/typegen/helpers';
+import { select } from '@xrmforge/helpers';
 import { AccountFields } from '../../typings/entities/account';
 Xrm.WebApi.retrieveMultipleRecords("account",
   `?$select=${select(AccountFields.Name, AccountFields.Revenue)}&$filter=statecode eq 0`);

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import { TokenCredential } from '@azure/identity';
-export { BindingType, ClientState, ClientType, DisplayState, FormNotificationLevel, OperationType, RequiredLevel, SaveMode, StructuralProperty, SubmitMode, parseFormattedValue, parseLookup, parseLookups, select, selectExpand } from './helpers.js';
 
 /**
  * @xrmforge/typegen - Error Types
@@ -1452,6 +1451,208 @@ interface EntityNamesGeneratorOptions {
  */
 declare function generateEntityNamesEnum(entityNames: string[], options?: EntityNamesGeneratorOptions): string;
 
+/**
+ * @xrmforge/typegen - Web API Helper Functions
+ *
+ * Lightweight utility functions for building OData query strings
+ * with type-safe field names from generated Fields enums.
+ *
+ * Zero runtime overhead when used with const enums (values are inlined).
+ *
+ * @example
+ * ```typescript
+ * import { select } from '@xrmforge/typegen';
+ *
+ * Xrm.WebApi.retrieveRecord(ref.entityType, ref.id, select(
+ *   AccountFields.Name,
+ *   AccountFields.WebsiteUrl,
+ *   AccountFields.Address1Line1,
+ * ));
+ * ```
+ */
+/**
+ * Build an OData $select query string from field names.
+ *
+ * @param fields - Field names (use generated Fields enum for type safety)
+ * @returns OData query string (e.g. "?$select=name,websiteurl,address1_line1")
+ */
+declare function select(...fields: string[]): string;
+/**
+ * Parse a lookup field from a Dataverse Web API response into a LookupValue.
+ *
+ * Dataverse returns lookups as `_fieldname_value` with OData annotations:
+ * - `_fieldname_value` (GUID)
+ * - `_fieldname_value@OData.Community.Display.V1.FormattedValue` (display name)
+ * - `_fieldname_value@Microsoft.Dynamics.CRM.lookuplogicalname` (entity type)
+ *
+ * This function extracts all three into an `Xrm.LookupValue` object.
+ *
+ * @param response - The raw Web API response object
+ * @param navigationProperty - Navigation property name (use NavigationProperties enum for type safety)
+ * @returns Xrm.LookupValue or null if the lookup is empty
+ *
+ * @example
+ * ```typescript
+ * // Mit NavigationProperties-Enum (empfohlen, keine Raw-Strings):
+ * parseLookup(result, AccountNav.Country);
+ *
+ * // Oder mit Navigation Property Name direkt:
+ * parseLookup(result, 'markant_address1_countryid');
+ * ```
+ */
+declare function parseLookup(response: Record<string, unknown>, navigationProperty: string): {
+    id: string;
+    name: string;
+    entityType: string;
+} | null;
+/**
+ * Parse multiple lookup fields from a Dataverse Web API response at once.
+ *
+ * @param response - The raw Web API response object
+ * @param navigationProperties - Navigation property names to parse
+ * @returns Map of navigation property name to LookupValue (null entries omitted)
+ *
+ * @example
+ * ```typescript
+ * const lookups = parseLookups(result, ['markant_address1_countryid', 'parentaccountid']);
+ * formContext.getAttribute(Fields.Country).setValue(
+ *   lookups.markant_address1_countryid ? [lookups.markant_address1_countryid] : null
+ * );
+ * ```
+ */
+declare function parseLookups(response: Record<string, unknown>, navigationProperties: string[]): Record<string, {
+    id: string;
+    name: string;
+    entityType: string;
+} | null>;
+/**
+ * Get the formatted (display) value of any field from a Web API response.
+ *
+ * Works for OptionSets, Lookups, DateTimes, Money, and other formatted fields.
+ *
+ * @param response - The raw Web API response object
+ * @param fieldName - The field logical name (e.g. "statecode", "createdon")
+ * @returns The formatted string value, or null if not available
+ *
+ * @example
+ * ```typescript
+ * const status = parseFormattedValue(result, 'statecode');
+ * // "Active" (statt 0)
+ * ```
+ */
+declare function parseFormattedValue(response: Record<string, unknown>, fieldName: string): string | null;
+/**
+ * Build an OData $select and $expand query string.
+ *
+ * @param fields - Field names to select
+ * @param expand - Navigation property to expand (optional)
+ * @returns OData query string
+ *
+ * @example
+ * ```typescript
+ * Xrm.WebApi.retrieveRecord("account", id, selectExpand(
+ *   [AccountFields.Name, AccountFields.WebsiteUrl],
+ *   "primarycontactid($select=fullname,emailaddress1)"
+ * ));
+ * ```
+ */
+declare function selectExpand(fields: string[], expand: string): string;
+
+/**
+ * @xrmforge/typegen - Xrm API Constants
+ *
+ * Const enums for all common Xrm string/number constants.
+ * Eliminates raw strings in D365 form scripts.
+ *
+ * @types/xrm defines these as string literal types for compile-time checking,
+ * but does NOT provide runtime constants (XrmEnum is not available at runtime).
+ * These const enums are erased at compile time (zero runtime overhead).
+ *
+ * @example
+ * ```typescript
+ * // Statt Raw-String:
+ * if (tab.getDisplayState() === 'expanded') { ... }
+ *
+ * // Mit XrmForge-Konstante:
+ * if (tab.getDisplayState() === XrmConstants.DisplayState.Expanded) { ... }
+ * ```
+ */
+/** Tab/Section display state */
+declare const enum DisplayState {
+    Expanded = "expanded",
+    Collapsed = "collapsed"
+}
+/** Form notification level (formContext.ui.setFormNotification) */
+declare const enum FormNotificationLevel {
+    Error = "ERROR",
+    Warning = "WARNING",
+    Info = "INFO"
+}
+/** Attribute required level (attribute.setRequiredLevel) */
+declare const enum RequiredLevel {
+    None = "none",
+    Required = "required",
+    Recommended = "recommended"
+}
+/** Attribute submit mode (attribute.setSubmitMode) */
+declare const enum SubmitMode {
+    Always = "always",
+    Never = "never",
+    Dirty = "dirty"
+}
+/** Save mode (eventArgs.getSaveMode()) */
+declare const enum SaveMode {
+    Save = 1,
+    SaveAndClose = 2,
+    Deactivate = 5,
+    Reactivate = 6,
+    Send = 7,
+    Disqualify = 15,
+    Qualify = 16,
+    Assign = 47,
+    SaveAsCompleted = 58,
+    SaveAndNew = 59,
+    AutoSave = 70
+}
+/** Client type (Xrm.Utility.getGlobalContext().client.getClient()) */
+declare const enum ClientType {
+    Web = "Web",
+    Outlook = "Outlook",
+    Mobile = "Mobile"
+}
+/** Client state (Xrm.Utility.getGlobalContext().client.getClientState()) */
+declare const enum ClientState {
+    Online = "Online",
+    Offline = "Offline"
+}
+/** Operation type for Xrm.WebApi.execute getMetadata().operationType */
+declare const enum OperationType {
+    /** Custom Action or OOB Action (POST) */
+    Action = 0,
+    /** Custom Function or OOB Function (GET) */
+    Function = 1,
+    /** CRUD operation (Create, Retrieve, Update, Delete) */
+    CRUD = 2
+}
+/** Structural property for getMetadata().parameterTypes[].structuralProperty */
+declare const enum StructuralProperty {
+    Unknown = 0,
+    PrimitiveType = 1,
+    ComplexType = 2,
+    EnumerationType = 3,
+    Collection = 4,
+    EntityType = 5
+}
+/** Binding type for Custom API definitions */
+declare const enum BindingType {
+    /** Nicht an eine Entity gebunden (global aufrufbar) */
+    Global = 0,
+    /** An einen einzelnen Entity-Datensatz gebunden */
+    Entity = 1,
+    /** An eine Entity-Collection gebunden */
+    EntityCollection = 2
+}
+
 /**
  * @xrmforge/typegen - Action/Function Runtime Helpers
  *
@@ -1800,4 +2001,4 @@ declare class TypeGenerationOrchestrator {
     private getPicklistAttributes;
 }
 
-export { type ActionGeneratorOptions, ApiRequestError, type AttributeMetadata, type AuthConfig, type AuthMethod, AuthenticationError, type BoundActionExecutor, type BoundActionWithParamsExecutor, type BoundFunctionExecutor, type CacheStats, type ChangeDetectionResult, ChangeDetector, type ClientCredentialsAuth, ConfigError, ConsoleLogSink, type CustomApiTypeInfo, DEFAULT_LABEL_CONFIG, DataverseHttpClient, type DateTimeAttributeMetadata, type DecimalAttributeMetadata, type DeviceCodeAuth, type EntityFieldsGeneratorOptions, type EntityGenerationResult, type EntityGeneratorOptions, type EntityMetadata, type EntityNamesGeneratorOptions, type EntityTypeInfo, ErrorCode, FastXmlParser, type FormControl, type FormGeneratorOptions, type FormSection, type FormTab, type GenerateConfig, type GeneratedFile, GenerationError, type GenerationResult, type GroupedCustomApis, type HttpClientOptions, type IntegerAttributeMetadata, type InteractiveAuth, JsonLogSink, type Label, type LabelConfig, type LocalizedLabel, type LogEntry, LogLevel, type LogSink, Logger, type LookupAttributeMetadata, type ManyToManyRelationshipMetadata, MetadataCache, MetadataClient, MetadataError, type MoneyAttributeMetadata, type OneToManyRelationshipMetadata, type OptionMetadata, type OptionSetGeneratorOptions, type OptionSetMetadata, type ParameterMeta, type ParameterMetaMap, type ParsedForm, type PicklistAttributeMetadata, SilentLogSink, type SolutionComponent, type StateAttributeMetadata, type StatusAttributeMetadata, type StringAttributeMetadata, type SystemFormMetadata, TypeGenerationOrchestrator, type UnboundActionExecutor, type UnboundActionWithParamsExecutor, type UnboundFunctionExecutor, type XmlElement, type XmlParser, XrmForgeError, configureLogging, createBoundAction, createBoundFunction, createCredential, createLogger, createUnboundAction, createUnboundFunction, defaultXmlParser, disambiguateEnumMembers, executeMultiple, executeRequest, extractControlFields, getJSDocLabel as formatDualLabel, generateActionDeclarations, generateActionModule, generateActivityPartyInterface, generateEntityFieldsEnum, generateEntityForms, generateEntityInterface, generateEntityNamesEnum, generateEntityNavigationProperties, generateEntityOptionSets, generateEnumMembers, generateFormInterface, generateOptionSetEnum, getEntityPropertyType, getFormAttributeType, getFormControlType, getFormMockValueType, getJSDocLabel, getLabelLanguagesParam, getPrimaryLabel, getSecondaryLabel, groupCustomApis, isLookupType, isPartyListType, isRateLimitError, isXrmForgeError, labelToIdentifier, parseForm, shouldIncludeInEntityInterface, toLookupValueProperty, toPascalCase, toSafeIdentifier, withProgress };
+export { type ActionGeneratorOptions, ApiRequestError, type AttributeMetadata, type AuthConfig, type AuthMethod, AuthenticationError, BindingType, type BoundActionExecutor, type BoundActionWithParamsExecutor, type BoundFunctionExecutor, type CacheStats, type ChangeDetectionResult, ChangeDetector, type ClientCredentialsAuth, ClientState, ClientType, ConfigError, ConsoleLogSink, type CustomApiTypeInfo, DEFAULT_LABEL_CONFIG, DataverseHttpClient, type DateTimeAttributeMetadata, type DecimalAttributeMetadata, type DeviceCodeAuth, DisplayState, type EntityFieldsGeneratorOptions, type EntityGenerationResult, type EntityGeneratorOptions, type EntityMetadata, type EntityNamesGeneratorOptions, type EntityTypeInfo, ErrorCode, FastXmlParser, type FormControl, type FormGeneratorOptions, FormNotificationLevel, type FormSection, type FormTab, type GenerateConfig, type GeneratedFile, GenerationError, type GenerationResult, type GroupedCustomApis, type HttpClientOptions, type IntegerAttributeMetadata, type InteractiveAuth, JsonLogSink, type Label, type LabelConfig, type LocalizedLabel, type LogEntry, LogLevel, type LogSink, Logger, type LookupAttributeMetadata, type ManyToManyRelationshipMetadata, MetadataCache, MetadataClient, MetadataError, type MoneyAttributeMetadata, type OneToManyRelationshipMetadata, OperationType, type OptionMetadata, type OptionSetGeneratorOptions, type OptionSetMetadata, type ParameterMeta, type ParameterMetaMap, type ParsedForm, type PicklistAttributeMetadata, RequiredLevel, SaveMode, SilentLogSink, type SolutionComponent, type StateAttributeMetadata, type StatusAttributeMetadata, type StringAttributeMetadata, StructuralProperty, SubmitMode, type SystemFormMetadata, TypeGenerationOrchestrator, type UnboundActionExecutor, type UnboundActionWithParamsExecutor, type UnboundFunctionExecutor, type XmlElement, type XmlParser, XrmForgeError, configureLogging, createBoundAction, createBoundFunction, createCredential, createLogger, createUnboundAction, createUnboundFunction, defaultXmlParser, disambiguateEnumMembers, executeMultiple, executeRequest, extractControlFields, getJSDocLabel as formatDualLabel, generateActionDeclarations, generateActionModule, generateActivityPartyInterface, generateEntityFieldsEnum, generateEntityForms, generateEntityInterface, generateEntityNamesEnum, generateEntityNavigationProperties, generateEntityOptionSets, generateEnumMembers, generateFormInterface, generateOptionSetEnum, getEntityPropertyType, getFormAttributeType, getFormControlType, getFormMockValueType, getJSDocLabel, getLabelLanguagesParam, getPrimaryLabel, getSecondaryLabel, groupCustomApis, isLookupType, isPartyListType, isRateLimitError, isXrmForgeError, labelToIdentifier, parseForm, parseFormattedValue, parseLookup, parseLookups, select, selectExpand, shouldIncludeInEntityInterface, toLookupValueProperty, toPascalCase, toSafeIdentifier, withProgress };

package/docs/architecture/00-README.md

@@ -0,0 +1,26 @@
+# XrmForge Architecture
+
+> **Status:** Living document describing the current implementation state.
+> **Last updated:** 2026-04-04 (Session 10)
+> **Version:** 7 packages, 666+ tests across all packages.
+
+## Chapters
+
+1. [Executive Summary](01-executive-summary.md)
+2. [Package Architecture](02-packages.md)
+3. [Generated Types](03-generated-types.md)
+4. [CLI Commands](04-cli.md)
+5. [Build Architecture](05-build.md)
+6. [Incremental Generation](06-incremental.md)
+7. [HTTP Client](07-http-client.md)
+8. [Authentication](08-authentication.md)
+9. [Testing Framework](09-testing.md)
+10. [ESLint Plugin](10-eslint-plugin.md)
+11. [AGENT.md System](11-agent-md.md)
+12. [@types/xrm Pitfalls](12-xrm-pitfalls.md)
+13. [@xrmforge/helpers Package](13-helpers.md)
+14. [Showcases](14-showcases.md)
+15. [CI/CD](15-ci-cd.md)
+16. [Technical Debt](16-technical-debt.md)
+17. [Roadmap](17-roadmap.md)
+18. [Design Principles](18-design-principles.md)

package/docs/architecture/01-executive-summary.md

@@ -0,0 +1,11 @@
+# Executive Summary
+
+XrmForge is an open-source TypeScript toolkit for type-safe Dynamics 365 / Dataverse WebResource development. It generates TypeScript declarations from live Dataverse metadata, turning runtime string errors into compile-time type errors.
+
+**Core value proposition:** Every field name, OptionSet value, tab name, entity name, and subgrid name becomes a typed constant with IDE autocomplete and compile-time validation.
+
+**Target audience:** D365 developers who write form scripts (WebResources) in JavaScript/TypeScript and want compile-time safety, zero magic strings, and modern tooling (esbuild, vitest, ESLint).
+
+**Tech stack:** TypeScript, pnpm monorepo with Turborepo, esbuild for IIFE bundles, vitest for testing, @azure/identity for authentication, fast-xml-parser for FormXml parsing.
+
+**npm organization:** [@xrmforge](https://www.npmjs.com/org/xrmforge)

package/docs/architecture/02-packages.md

@@ -0,0 +1,110 @@
+# Package Architecture
+
+## Package Overview
+
+| Package | Version | Tests | Description |
+|---------|---------|-------|-------------|
+| @xrmforge/typegen | 0.6.0 | 444 | Core: type generation engine, metadata client, HTTP client, helpers |
+| @xrmforge/cli | 0.4.2 | 10 | CLI: generate, build, init commands |
+| @xrmforge/testing | 0.2.0 | 76 | Test utilities: createFormMock, fireOnChange, setupXrmMock |
+| @xrmforge/helpers | 0.1.0 | 59 | Browser-safe runtime: select(), parseLookup(), typedForm(), Xrm constants, Action executors |
+| @xrmforge/webapi | 0.1.0 | 45 | Type-safe Xrm.WebApi client with QueryBuilder |
+| @xrmforge/devkit | 0.4.0 | 42 | Build orchestration, scaffolding, AGENT.md generation |
+| @xrmforge/eslint-plugin | 0.2.0 | 32 | 5 D365-specific ESLint rules |
+
+**Total:** 708 tests across 7 packages.
+
+## Dependency Graph
+
+```
+@xrmforge/cli
+  |-- @xrmforge/typegen (generate command)
+  |-- @xrmforge/devkit  (build + init commands)
+  '-- commander (CLI framework)
+
+@xrmforge/typegen
+  |-- @azure/identity  (authentication)
+  '-- fast-xml-parser  (FormXml parsing)
+
+@xrmforge/devkit
+  '-- esbuild (IIFE bundling)
+
+@xrmforge/testing     (no runtime deps)
+@xrmforge/helpers     (no runtime deps)
+@xrmforge/webapi      (no runtime deps)
+@xrmforge/eslint-plugin (ESLint peer dep)
+```
+
+## Package Details
+
+### @xrmforge/typegen
+
+The core package. Contains:
+
+- **TypeGenerationOrchestrator** - Coordinates the entire generation pipeline
+- **MetadataClient** - Queries Dataverse metadata (entities, forms, OptionSets, Custom APIs)
+- **DataverseHttpClient** - Resilient REST client with retry, rate limiting, concurrency control
+- **ChangeDetector** - Incremental generation via RetrieveMetadataChanges
+- **MetadataCache** - Filesystem-based caching with version stamps
+- **Generators** - Entity interfaces, form interfaces, OptionSet enums, Fields enums, EntityNames, Navigation Properties, Action/Function executors
+- **Helpers** - select(), parseLookup(), parseFormattedValue() (moved to @xrmforge/helpers)
+- **Xrm Constants** - DisplayState, FormNotificationLevel, RequiredLevel, SubmitMode, SaveMode, ClientType, ClientState (moved to @xrmforge/helpers)
+- **Authentication** - createCredential() factory for 4 auth methods
+- **Logging** - Scoped loggers with pluggable sinks (Console, JSON, Silent)
+- **Errors** - Structured error hierarchy with ErrorCode enum (AUTH_1xxx, API_2xxx, META_3xxx, GEN_4xxx, CONFIG_5xxx)
+
+### @xrmforge/cli
+
+Command-line interface built with commander.js. Three commands:
+- `xrmforge generate` - Orchestrates TypeGenerationOrchestrator
+- `xrmforge build` - Delegates to devkit build()
+- `xrmforge init` - Delegates to devkit scaffoldProject()
+
+### @xrmforge/testing
+
+FormContext mocking for unit tests:
+- `createFormMock<TForm>(values)` - Creates a complete mock from simple key-value pairs
+- `MockAttribute` - getValue/setValue, dirty tracking, onChange handlers, required level, submit mode
+- `MockControl` - visible, disabled, label, notifications
+- `MockUi` - Form notifications, tab/section stubs
+- `MockEntity` - Entity ID, name, primary attribute
+- `fireOnChange(fieldName)` - Triggers registered onChange handlers
+- `setupXrmMock(options)` / `teardownXrmMock()` - Global Xrm mock with WebApi/Navigation stubs
+
+### @xrmforge/helpers
+
+Consolidates all browser-safe runtime code. Zero Node.js dependencies. Contains:
+- **Web API helpers** - select(), parseLookup(), parseFormattedValue()
+- **Xrm constants** - DisplayState, SubmitMode, RequiredLevel, SaveMode, ClientType, ClientState, FormNotificationLevel, OperationType
+- **Action/Function executors** - createBoundAction(), executeRequest(), withProgress()
+- **typedForm() proxy** - Proxy-based FormContext wrapper where `form.name` delegates to `getAttribute('name')`
+
+### @xrmforge/webapi
+
+Type-safe wrapper around Xrm.WebApi:
+- `retrieve<T>(entityName, id, query)` - Single record
+- `retrieveMultiple<T>(entityName, query, options)` - With pagination (maxPages)
+- `create(entityName, data)` - Returns record ID
+- `update(entityName, id, data)` - Void
+- `remove(entityName, id)` - Void
+- `QueryBuilder` - Fluent API: `.select().filter().orderBy().top().expand().build()`
+- `WebApiError` - Structured errors with statusCode, errorCode, innerMessage
+
+### @xrmforge/devkit
+
+Build orchestration and project scaffolding:
+- `build(config)` - Parallel esbuild IIFE builds via Promise.allSettled
+- `watch(config)` - esbuild watch mode with rebuild callbacks
+- `scaffoldProject(config)` - Generates 11 project files from templates
+- `validateBuildConfig(config)` / `resolveBuildConfig(config)` - Config validation
+- `BuildError` with codes: CONFIG_INVALID, ENTRY_NOT_FOUND, BUILD_FAILED, WATCH_ERROR
+- Template system: 7 text templates in `src/scaffold/templates/`, loaded via `template-loader.ts`
+
+### @xrmforge/eslint-plugin
+
+5 rules for D365 form scripts (ESLint v9 flat config):
+- `no-xrm-page` (error) - Forbids deprecated Xrm.Page API
+- `no-magic-optionset` (warn) - Forbids magic numbers in OptionSet comparisons
+- `no-sync-webapi` (error) - Forbids synchronous XMLHttpRequest
+- `require-error-handling` (warn) - Requires try/catch in async on* event handlers
+- `require-namespace` (warn) - Forbids window/globalThis assignments

package/docs/architecture/03-generated-types.md

@@ -0,0 +1,176 @@
+# Generated Types
+
+Running `xrmforge generate` produces the following TypeScript declarations:
+
+### 3.1 Entity 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
+    // ...
+  }
+}
+```
+
+**Type mapping:** String/Memo/EntityName to `string`, Integer/BigInt/Decimal/Double/Money to `number`, Boolean to `boolean`, DateTime/Uniqueidentifier/Lookup to `string`, Picklist/State/Status to `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',
+    // all readable attributes
+  }
+}
+```
+
+Used for Web API `$select`: `select(AccountFields.Name, AccountFields.Revenue)`.
+
+### 3.3 Navigation Properties (`entities/{entity}.d.ts`)
+
+```typescript
+declare namespace XrmForge.Entities {
+  const enum AccountNavigation {
+    PrimaryContactId = 'primarycontactid',
+    ContactCustomerAccounts = 'contact_customer_accounts',
+    // OneToMany + ManyToMany relationships
+  }
+}
+```
+
+### 3.4 Form Interfaces (`forms/{entity}.d.ts`)
+
+```typescript
+declare namespace XrmForge.Forms.Account {
+  // Union type restricting valid field names
+  type AccountMainFormFields = 'name' | 'telephone1' | 'revenue';
+
+  // Mapped type: field name to Xrm attribute type
+  type AccountMainFormAttributeMap = {
+    name: Xrm.Attributes.StringAttribute;
+    telephone1: Xrm.Attributes.StringAttribute;
+    revenue: Xrm.Attributes.NumberAttribute;
+  };
+
+  // Mapped type: field name to Xrm control type
+  type AccountMainFormControlMap = {
+    name: Xrm.Controls.StringControl;
+    telephone1: Xrm.Controls.StringControl;
+    revenue: Xrm.Controls.NumberControl;
+  };
+
+  // Fields enum for autocomplete
+  const enum AccountMainFormFieldsEnum {
+    /** Account Name | Kontoname */
+    AccountName = 'name',
+    Telephone1 = 'telephone1',
+    Revenue = 'revenue',
+  }
+
+  // Type-safe FormContext with overloaded 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[];
+  }
+}
+```
+
+**Special controls** are typed based on their FormXml ClassID:
+- Subgrid: `Xrm.Controls.GridControl`
+- Editable 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,
+  }
+}
+```
+
+Includes Picklist, Status, State, and MultiSelectPicklist attributes. Duplicate labels are disambiguated with `_{Value}` suffix.
+
+### 3.7 EntityNames Enum (`entity-names.d.ts`)
+
+```typescript
+declare namespace XrmForge {
+  const enum EntityNames {
+    Account = 'account',
+    Contact = 'contact',
+    // all entities in scope
+  }
+}
+```
+
+### 3.8 MockValues Types (in form interfaces)
+
+```typescript
+type AccountMainFormMockValues = {
+  name?: string | null;
+  telephone1?: string | null;
+  revenue?: number | null;
+};
+```
+
+Used with `createFormMock<AccountMainForm, AccountMainFormMockValues>({ name: 'Test' })`.
+
+### 3.9 Action/Function Executors (`actions/{entity|global}.d.ts` + `.ts`)
+
+**Declaration (.d.ts):**
+```typescript
+declare namespace XrmForge.Actions {
+  interface NormalizePhoneParams { Input: string; AllowSuspicious?: boolean; }
+  interface NormalizePhoneResult { Normalized: string; Status: number; }
+}
+```
+
+**Runtime module (.ts):**
+```typescript
+import { createUnboundAction } from '@xrmforge/typegen';
+export const NormalizePhone = createUnboundAction<NormalizePhoneParams, NormalizePhoneResult>(
+  'markant_NormalizePhone',
+  { Input: { typeName: 'String', structuralProperty: 1 } }
+);
+// Usage: const result = await NormalizePhone.execute({ Input: '123' });
+```
+
+Factory functions: `createBoundAction`, `createUnboundAction`, `createBoundFunction`, `createUnboundFunction`. Batch execution via `executeMultiple()`, progress UI via `withProgress()`.
+
+### 3.10 Dual-Language Labels
+
+All generated JSDoc comments support dual-language labels:
+```typescript
+/** Account Name | Kontoname */
+Name = 'name',
+```
+
+German umlauts are transliterated in identifiers: ae, oe, ue, ss (e.g. "Ubergeordnet" becomes `Uebergeordnet`).

package/docs/architecture/04-cli.md

@@ -0,0 +1,58 @@
+# CLI Commands
+
+### 4.1 `xrmforge generate`
+
+Generates TypeScript declarations from a Dataverse environment.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--url <url>` | string | required | Dataverse environment URL |
+| `--auth <method>` | string | required | Auth method: client-credentials, interactive, device-code, token |
+| `--tenant-id <id>` | string | varies | Azure AD tenant ID |
+| `--client-id <id>` | string | varies | Azure AD application ID |
+| `--client-secret <s>` | string | varies | Client secret (client-credentials only) |
+| `--token <token>` | string | varies | Pre-acquired bearer token (token auth only) |
+| `--entities <list>` | string | - | Comma-separated entity logical names |
+| `--solutions <list>` | string | - | Comma-separated solution unique names |
+| `--output <dir>` | string | ./typings | Output directory |
+| `--label-language <n>` | string | 1033 | Primary label language (LCID) |
+| `--secondary-language <n>` | string | - | Secondary label language for JSDoc |
+| `--no-forms` | flag | - | Skip form interface generation |
+| `--no-optionsets` | flag | - | Skip OptionSet enum generation |
+| `--actions` | flag | false | Generate Custom API executors |
+| `--actions-filter <prefix>` | string | - | Filter Custom APIs by uniquename prefix |
+| `--cache` | flag | false | Enable metadata caching for incremental generation |
+| `--no-cache` | flag | - | Force full metadata refresh |
+| `--cache-dir <dir>` | string | .xrmforge/cache | Cache directory |
+| `-v, --verbose` | flag | false | Debug logging |
+
+At least one of `--entities` or `--solutions` is required.
+
+### 4.2 `xrmforge build`
+
+Builds WebResources as IIFE bundles using esbuild (via @xrmforge/devkit).
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--watch` | flag | false | Watch mode with incremental rebuilds |
+| `--minify` | flag | from config | Override minification setting |
+| `--no-sourcemap` | flag | - | Disable source maps |
+| `--out-dir <dir>` | string | from config | Override output directory |
+| `-v, --verbose` | flag | false | Show error stacks |
+
+Reads configuration from `xrmforge.config.json`.
+
+### 4.3 `xrmforge init`
+
+Scaffolds a new D365 form scripting project.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `[dir]` | positional | . | Target directory |
+| `--name <name>` | string | dir name | Project name for package.json |
+| `--prefix <prefix>` | string | contoso | Publisher prefix |
+| `--namespace <ns>` | string | PascalCase(prefix) | Base namespace for scripts |
+| `--skip-install` | flag | false | Skip npm install |
+| `--force` | flag | false | Allow non-empty directories |
+
+Generates 11 files: 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.