@xrmforge/devkit 0.7.1 → 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
 
@@ -533,6 +549,25 @@ Never recreate them. Use the typed API directly.
 | `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

package/package.json

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