@xrmforge/devkit 0.7.3 → 0.7.5

package/dist/templates/AGENT.md

@@ -65,7 +65,7 @@ export const onLoad = wrapHandler('LM.Account.onLoad', logger, (ctx) => {
   const form = typedForm<AccountLMFirmaForm>(ctx.getFormContext());
 
   // Direct field access - fully typed, IDE autocomplete works
-  const name = form.name.getValue();              // string | null
+  const name = form.name.getValue();              // string | null (non-nullable, field is on form)
   form.revenue.setValue(150000);                   // NumberAttribute
   const parent = form.parentaccountid.getValue();  // LookupValue[] | null
 
@@ -85,8 +85,29 @@ export const onLoad = wrapHandler('LM.Account.onLoad', logger, (ctx) => {
 
 **When to use `form.fieldname` (the typedForm proxy):**
 - `getValue()`, `setValue()` (reading and writing values)
+- `addOnChange()` (event registration directly on the attribute)
 - Any read-only access to field values
 
+**When to use `form.$unsafe(EntityFields.X)` (off-form fields):**
+
+D365 loads all entity attributes into the FormContext, not just those on the form.
+If a field is NOT in the generated form interface (compile error on `form.fieldname`),
+use `$unsafe()` with the **Entity-level Fields Enum** (never a raw string):
+
+```typescript
+import { OpportunityFields } from '../../generated/fields/opportunity.js';
+
+// Off-form field: not in the form interface, but loaded by D365
+form.$unsafe(OpportunityFields.VslBeauftragung)?.setValue(closeDate);
+
+// WRONG: raw string in $unsafe
+form.$unsafe('estimatedclosedate')?.setValue(closeDate);
+```
+
+`$unsafe()` returns `Attribute | null` (nullable, because the field may not exist).
+Always use optional chaining (`?.`). The Entity-level Fields Enum ensures the field
+name is valid even though it's not on the form.
+
 ### 2. Fields Enum for ALL getAttribute/getControl AND select() calls
 
 Two types of Fields enums exist:
@@ -334,6 +355,8 @@ Xrm.Navigation.openForm({ entityName: EntityNames.Account, entityId: id });  //
 - Never access WebApi response properties with `as string` casts (use generated Entity interfaces)
 - Never `.getValue()[0].id` for lookups (use `formLookup`/`formLookupId`)
 - Never raw strings in `parseLookup()` (use NavigationProperties enum)
+- Never raw strings in `$unsafe()` (use Entity-level Fields Enum: `form.$unsafe(AccountFields.X)`)
+- Never manual OData annotation access (`_value`, `@OData.Community.Display.V1.FormattedValue`, `@Microsoft.Dynamics.CRM.lookuplogicalname`). Use `parseLookup()` which extracts all three.
 
 **Code quality:**
 - Never `Xrm.Page` (deprecated since D365 v9.0)
@@ -438,13 +461,32 @@ import { LmBestellungStatusCode } from '../../generated/optionsets/lm_bestellung
 </condition>`
 ```
 
-### Lookup Access
+### Lookup Access (Form)
 ```typescript
 // BEFORE: form.getAttribute("customerid").getValue()[0].id.replace("{","").replace("}","")
 // AFTER:
 const customerId = formLookupId(form.customerid);
 ```
 
+### Lookup from WebApi Response to Form Field
+```typescript
+// BEFORE (verbose, error-prone OData annotations):
+form.customerid.setValue([{
+  id: raw._parentcustomerid_value as string,
+  entityType: EntityNames.Account,
+  name: (raw['_parentcustomerid_value@OData.Community.Display.V1.FormattedValue'] as string) ?? '',
+}]);
+
+// AFTER (parseLookup extracts id, name, entityType automatically):
+import { parseLookup } from '@xrmforge/helpers';
+import { ContactNavigationProperties as ContactNav } from '../../generated/entities/contact.js';
+
+const customer = parseLookup(raw, ContactNav.ParentCustomerId);
+if (customer) {
+  form.customerid.setValue([customer]);
+}
+```
+
 ### Custom API Call
 ```typescript
 // BEFORE: ExecuteFunctionCall("CancelInvoice", { InvoiceId: id })

package/dist/templates/validate-form.mjs

@@ -218,6 +218,34 @@ checkPattern(
   ['logger.ts'],
 );
 
+// ── Type Safety Bypass ───────────────────────────────────────────────────────
+
+// 3l2. Cast to Xrm.FormContext (bypasses typed form interface)
+checkPattern(
+  'Cast to Xrm.FormContext (use typedForm $unsafe() for off-form fields)',
+  formFiles,
+  /as\s+(?:unknown\s+as\s+)?Xrm\.FormContext/,
+);
+
+// 3l3. Raw strings in $filter (field names must use Fields Enum interpolation)
+checkPattern(
+  'Raw field names in $filter (use Fields Enum interpolation)',
+  allSrcFiles,
+  /\$filter=[^$]*\b(?:eq|ne|gt|lt|ge|le|contains|startswith)\b/,
+  ['generated/', 'validate-form'],
+  [
+    // Allow if the line contains template literal interpolation (${...})
+    /\$\{/,
+  ],
+);
+
+// 3l4. Raw strings in $unsafe() (must use Entity-level Fields Enum)
+checkPattern(
+  'Raw field strings in $unsafe() (use Entity-level Fields Enum)',
+  formFiles,
+  /\$unsafe\s*\(\s*['"][a-z]/,
+);
+
 // ── Handler Pattern ──────────────────────────────────────────────────────────
 
 // 3l. Exported handlers without wrapHandler or wrapCommand
@@ -260,6 +288,60 @@ checkPattern(
   ['generated/'],
 );
 
+// ── WebApi Response Typing ────────────────────────────────────────────────────
+
+// 3p. Untyped WebApi responses (must use generated Entity interfaces)
+checkPattern(
+  'Untyped WebApi response cast (use generated Entity interface instead of Record<string, unknown>)',
+  allSrcFiles,
+  /as\s+Record\s*<\s*string\s*,\s*unknown\s*>/,
+  ['generated/'],
+);
+
+// 3q. Manual OData annotation access (use parseLookup instead)
+checkPattern(
+  'Manual OData annotation access (use parseLookup() from @xrmforge/helpers)',
+  allSrcFiles,
+  /@OData\.Community\.Display|@Microsoft\.Dynamics\.CRM\.lookuplogicalname|_value(?:@|\s*as\s)/,
+  ['generated/', 'node_modules'],
+);
+
+// ── Legacy Helper Wrappers ───────────────────────────────────────────────────
+
+// 3r. Forbidden legacy helper functions (must use typedForm + @xrmforge/helpers)
+checkPattern(
+  'Forbidden helper: getLookupId (use formLookupId from @xrmforge/helpers)',
+  allSrcFiles,
+  /\bgetLookupId\s*\(/,
+  ['generated/'],
+);
+
+checkPattern(
+  'Forbidden helper: setLookupValue (use form.field.setValue([{...}]))',
+  allSrcFiles,
+  /\bsetLookupValue\s*\(/,
+  ['generated/'],
+);
+
+// ── UI Localization ──────────────────────────────────────────────────────────
+
+// 3s. Hardcoded UI strings in dialogs/progress (must use pickLang from constants.ts)
+checkPattern(
+  'Hardcoded UI string in dialog/progress (use pickLang(MESSAGES) from constants.ts)',
+  allSrcFiles,
+  /(?:openAlertDialog|openConfirmDialog|openErrorDialog|showProgressIndicator)\s*\(\s*(?:\{\s*text\s*:\s*)?['"]/,
+  ['generated/', 'constants.ts'],
+);
+
+// ── Duplicate Framework Functions ────────────────────────────────────────────
+
+// 3t. Own normalizeGuid/compareGuid (use normalizeGuid from @xrmforge/helpers)
+checkPattern(
+  'Own normalizeGuid/compareGuid definition (use normalizeGuid from @xrmforge/helpers)',
+  allSrcFiles,
+  /(?:export\s+)?function\s+(?:normalizeGuid|compareGuid)\s*\(/,
+);
+
 // ============================================================
 // Result
 // ============================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xrmforge/devkit",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Build orchestration and project tooling for Dynamics 365 WebResources",
   "keywords": [
     "dynamics-365",