@xrmforge/typegen 0.8.3 → 0.8.5

package/docs/architecture/04-cli.md

@@ -1,58 +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 | ./generated | 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, generated/.gitkeep, GitHub Actions CI, Azure DevOps Pipeline.
+# 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 | ./generated | 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, generated/.gitkeep, GitHub Actions CI, Azure DevOps Pipeline.

package/docs/architecture/05-build.md

@@ -1,50 +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`.
+# 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

@@ -1,42 +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
+# 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

@@ -1,59 +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 |
+# 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

@@ -1,18 +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`
+# 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

@@ -1,55 +1,55 @@
-# Testing 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,
-});
-
-// 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.
+# Testing 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,
+});
+
+// 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.