@xrmforge/devkit 0.7.4 → 0.7.6

package/dist/templates/AGENT.md

@@ -69,23 +69,56 @@ export const onLoad = wrapHandler('LM.Account.onLoad', logger, (ctx) => {
   form.revenue.setValue(150000);                   // NumberAttribute
   const parent = form.parentaccountid.getValue();  // LookupValue[] | null
 
-  // Control access
-  form.$control('name').setDisabled(true);
+  // addOnChange directly on the proxy (NOT via $context.getAttribute)
+  form.name.addOnChange(() => { logger.debug('Name changed'); });
+  form.revenue.addOnChange(() => { recalculate(form); });
 
-  // Full FormContext for ui, data, tabs, addOnChange
+  // Control access via controls proxy (typed from ControlMap, no cast needed)
+  form.controls.name.setDisabled(true);
+  form.controls.customerid.setEntityTypes([EntityNames.Account]);  // LookupControl
+  form.controls.revenue.setVisible(false);                          // NumberControl
+
+  // Full FormContext for ui, data, tabs
   form.$context.ui.setFormNotification('OK', FormNotificationLevel.Info, 'id');
-  form.$context.getAttribute(Fields.Name).addOnChange(() => { ... });
 });
 ```
 
-**When to use `form.$context.getAttribute(Fields.X)` instead of `form.fieldname`:**
-- `addOnChange()`, `removeOnChange()` (event registration on the attribute)
+**Use `form.fieldname` (the typedForm proxy) for EVERYTHING on the attribute:**
+- `getValue()`, `setValue()` (reading and writing values)
+- `addOnChange()`, `removeOnChange()` (event registration)
 - `setRequiredLevel()`, `setSubmitMode()` (attribute-level settings)
-- `getControl()` with typed control access (use `form.$control(Fields.X)`)
+- Any attribute method: the proxy returns the full typed Attribute object
 
-**When to use `form.fieldname` (the typedForm proxy):**
-- `getValue()`, `setValue()` (reading and writing values)
-- Any read-only access to field values
+**Use `form.controls.fieldname` for control-level operations:**
+- `setDisabled()`, `setVisible()`, `setLabel()`
+- `addPreSearch()` (on LookupControl)
+- `setNotification()`, `clearNotification()`
+
+**Use `form.$context` ONLY for FormContext-level operations:**
+- `form.$context.ui` (setFormNotification, tabs, close)
+- `form.$context.data` (save, entity, process)
+- `form.$context.ui.getFormType()`
+- NOT for getAttribute (use the proxy instead)
+
+**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
 
@@ -334,6 +367,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)
@@ -344,6 +379,7 @@ Xrm.Navigation.openForm({ entityName: EntityNames.Account, entityId: id });  //
 - Never unlokalized UI strings (use `pickLang()` from constants.ts)
 - Never build your own getValue/setFieldValue/setDisabled/addOnChange helpers (use `typedForm` + native Xrm API)
 - Never `import ... from '@xrmforge/typegen'` in browser code (use `@xrmforge/helpers`)
+- Never `as Xrm.Controls.LookupControl` or similar control casts (`form.controls.fieldname` returns the typed control from ControlMap)
 - Never `as any` without eslint-disable comment explaining why
 - Never untyped `catch (error)` (always `catch (error: unknown)`)
 
@@ -438,13 +474,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 })
@@ -504,7 +559,7 @@ each attribute to its control. `mock.getControl(Fields.Name)` works out of the b
 | Legacy Pattern | XrmForge Replacement |
 |---|---|
 | `getAttribute("name")` | `form.name` (via typedForm) |
-| `getControl("name")` | `form.$control(Fields.Name)` |
+| `getControl("name")` | `form.controls.name` |
 | `Xrm.Page.getAttribute(...)` | `form.fieldname` (via typedForm) |
 | `var formContext` (global) | `const form = typedForm<MyForm>(ctx.getFormContext())` |
 | `function form_OnLoad(ctx)` | `export const onLoad = wrapHandler(...)` |
@@ -526,11 +581,11 @@ Never recreate them. Use the typed API directly.
 |---|---|
 | `GetValue(fieldName)` | `form.fieldname.getValue()` (typed via typedForm) |
 | `SetValue(fieldName, value)` | `form.fieldname.setValue(value)` (typed via typedForm) |
-| `SetDisabled(attributeName, disabled)` | `form.$control(Fields.X).setDisabled(disabled)` |
-| `SetVisible(attributeName, visible)` | `form.$control(Fields.X).setVisible(visible)` |
+| `SetDisabled(attributeName, disabled)` | `form.controls.fieldname.setDisabled(disabled)` |
+| `SetVisible(attributeName, visible)` | `form.controls.fieldname.setVisible(visible)` |
 | `SetRequiredLevel(attributeName, level)` | `form.$context.getAttribute(Fields.X).setRequiredLevel(RequiredLevel.Required)` |
 | `AddOnChange(attributeName, callback)` | `form.$context.getAttribute(Fields.X).addOnChange(cb)` |
-| `AddPreSearch(controlName, callback)` | `(form.$control(Fields.X) as Xrm.Controls.LookupControl).addPreSearch(cb)` |
+| `AddPreSearch(controlName, callback)` | `form.controls.fieldname.addPreSearch(cb)` (typed as LookupControl from ControlMap) |
 | `GetLookupValueId(fieldName)` | `formLookupId(form.fieldname)` |
 | `SetLookupValue(field, id, type, name)` | `form.fieldname.setValue([{ id, entityType, name }])` |
 | `GetId()` | `form.$context.data.entity.getId()` |

package/dist/templates/validate-form.mjs

@@ -239,6 +239,13 @@ checkPattern(
   ],
 );
 
+// 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
@@ -281,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.4",
+  "version": "0.7.6",
   "description": "Build orchestration and project tooling for Dynamics 365 WebResources",
   "keywords": [
     "dynamics-365",