@xrmforge/devkit 0.7.0 → 0.7.2

package/dist/templates/AGENT.md

@@ -1,6 +1,22 @@
 # XrmForge - AI Agent Instructions
 
-This file helps AI coding assistants write optimal Dynamics 365 form scripts.
+## Quality Philosophy
+
+The goal is not "code that compiles" or "code that passes a linter". The goal is
+code that reads like a description of the business logic. A developer opening a
+file should immediately understand what happens, without Xrm API docs, without
+OData knowledge, without deciphering GUIDs or magic numbers.
+
+Every string that references a Dataverse resource (field name, entity name,
+OptionSet value, tab name, section name, notification ID, navigation property)
+MUST come from a generated constant or a named constant from constants.ts.
+No exceptions. No workarounds. No helper wrappers that accept raw strings.
+
+Abstraction layers that merely wrap single API calls with string parameters
+(getValue, setValue, setDisabled, addOnChange) destroy type safety and must not
+exist. The correct abstraction is `typedForm()` (language-level proxy), not
+string wrappers (API-level indirection). Business logic belongs in named
+functions with domain-specific names, not in anonymous chains of API calls.
 
 ## Packages
 
@@ -484,22 +500,79 @@ each attribute to its control. `mock.getControl(Fields.Name)` works out of the b
 
 ## Pattern Recognition: Legacy to XrmForge
 
+### Xrm API Patterns
 | Legacy Pattern | XrmForge Replacement |
 |---|---|
-| `getAttribute("name")` | `form.name` (via typedForm) or `getAttribute(Fields.Name)` |
+| `getAttribute("name")` | `form.name` (via typedForm) |
 | `getControl("name")` | `form.$control(Fields.Name)` |
-| `getValue() === 595300000` | `form.statuscode.getValue() === StatusCode.Active` |
-| `Xrm.WebApi.retrieveRecord("account", id)` | `Xrm.WebApi.retrieveRecord(EntityNames.Account, id)` |
-| `"?$select=name,revenue"` | `select(AccountFields.Name, AccountFields.Revenue)` |
-| `value[0].id.replace("{","")` | `formLookupId(form.customerid)` |
 | `Xrm.Page.getAttribute(...)` | `form.fieldname` (via typedForm) |
 | `var formContext` (global) | `const form = typedForm<MyForm>(ctx.getFormContext())` |
 | `function form_OnLoad(ctx)` | `export const onLoad = wrapHandler(...)` |
+| `Xrm.WebApi.retrieveRecord("account", id)` | `Xrm.WebApi.retrieveRecord(EntityNames.Account, id)` |
+| `"?$select=name,revenue"` | `select(AccountFields.Name, AccountFields.Revenue)` |
+| `value[0].id.replace("{","")` | `formLookupId(form.customerid)` |
 | `ExecuteFunctionCall("name", ...)` | `import { Name } from '../../generated/actions/global.js'` |
 | `setFormNotification(msg, 'ERROR', id)` | `setFormNotification(msg, FormNotificationLevel.Error, id)` |
+| `getValue() === 595300000` | `form.statuscode.getValue() === StatusCode.Active` |
 | `86400000` | `const MS_PER_DAY = 24 * 60 * 60 * 1000` |
 | `'[Kurzbeschreibung]'` | `pickLang(languageId, MESSAGES).placeholder` |
 
+### Legacy Helper Functions (DO NOT recreate, use typedForm instead)
+
+These helper wrappers are common in legacy code. They destroy type safety.
+Never recreate them. Use the typed API directly.
+
+| Legacy Helper | XrmForge Replacement |
+|---|---|
+| `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)` |
+| `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)` |
+| `GetLookupValueId(fieldName)` | `formLookupId(form.fieldname)` |
+| `SetLookupValue(field, id, type, name)` | `form.fieldname.setValue([{ id, entityType, name }])` |
+| `GetId()` | `form.$context.data.entity.getId()` |
+| `GetEntityName()` | `form.$context.data.entity.getEntityName()` |
+| `GetFormType()` | `form.$context.ui.getFormType()` |
+| `GetIsDirty()` | `form.$context.data.entity.getIsDirty()` |
+| `IsNullOrEmpty(value)` | `value == null \|\| value === ''` (inline) |
+| `IsAttributeNullOrEmpty(field)` | `form.fieldname.getValue() == null` |
+| `GetUserId()` | `Xrm.Utility.getGlobalContext().userSettings.userId` |
+| `GetUserLanguageId()` | `Xrm.Utility.getGlobalContext().userSettings.languageId` |
+| `OpenForm(entityName, id)` | `Xrm.Navigation.openForm({ entityName: EntityNames.X, entityId: id })` |
+| `OpenAlertDialog(text)` | `Xrm.Navigation.openAlertDialog({ text })` |
+| `OpenConfirmDialog(text, ...)` | `Xrm.Navigation.openConfirmDialog({ text, title, ... })` |
+| `ShowProgressIndicator(msg)` | `Xrm.Utility.showProgressIndicator(msg)` |
+| `CloseProgressIndicator()` | `Xrm.Utility.closeProgressIndicator()` |
+| `SetNotification(attr, msg)` | `form.$context.getControl(Fields.X).setNotification(msg, NOTIFICATION_IDS.x)` |
+| `SetSectionDisabled(tab, sec, off)` | `form.$context.ui.tabs.get(Tabs.X).sections.get(Sections.Y).setVisible(!off)` |
+
+### GUID Handling (common CRM anti-pattern)
+
+D365 returns GUIDs in various formats: `{A1B2C3D4-...}`, `a1b2c3d4-...`, `A1B2C3D4-...`.
+Legacy code commonly has helpers like `CompareGuid()`, `GetCompatibleGuid()`,
+`NormalizeGuid()`, `StripBraces()`. **Do NOT recreate these.**
+
+`formLookupId()` from @xrmforge/helpers already normalizes GUIDs (removes braces).
+GUID comparison is then a simple `===`:
+
+```typescript
+// WRONG: legacy GUID helpers
+function CompareGuid(a, b) { return a.replace(/[{}]/g,'').toLowerCase() === b.replace(/[{}]/g,'').toLowerCase(); }
+const id = GetCompatibleGuid(form.getAttribute("customerid").getValue()[0].id);
+
+// CORRECT: formLookupId normalizes automatically
+const customerId = formLookupId(form.customerid);  // already clean: "a1b2c3d4-..."
+if (customerId === otherNormalizedId) { ... }       // simple ===
+```
+
+**Rule of thumb:** If a helper function just wraps a single Xrm API call with a
+string parameter, it MUST NOT exist. The typed API is shorter, safer, and provides
+IDE autocomplete. Only keep shared helpers that contain actual domain logic
+(calculations, WebApi queries, multi-step workflows).
+
 ## @types/xrm Pitfalls (known issues)
 
 1. **Form Interface:** Do NOT use `interface extends Xrm.FormContext`. Use `Omit` pattern.

package/package.json

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