@xrmforge/devkit 0.7.1 → 0.7.3

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,48 @@ 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 ===
+```
+
+### Typed repetition beats untyped loops
+
+When multiple fields need the same operation (e.g. 8 address fields), write
+8 typed lines instead of 1 loop with raw strings:
+
+```typescript
+// WRONG: DRY reflex, but raw strings bypass type safety
+for (const f of ['address1_name', 'address1_line1', 'address1_city']) {
+  form.$unsafe(f)?.addOnChange(handler);
+}
+
+// CORRECT: more lines, but every field is compile-time validated
+form.address1_name.addOnChange(handler);
+form.address1_line1.addOnChange(handler);
+form.address1_city.addOnChange(handler);
+form.address1_postalcode.addOnChange(handler);
+form.address1_country.addOnChange(handler);
+```
+
+8 typed lines are better than 1 loop with raw strings. The type system
+catches renamed/removed fields at compile time. A loop with raw strings
+only fails at runtime. DRY is a recommendation, type safety is mandatory.
+
 **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/dist/templates/validate-form.mjs

@@ -87,9 +87,14 @@ function collectTsFiles(dir) {
 
 /**
  * Check a pattern rule against all files.
+ * @param {string} label - Description of the check
+ * @param {string[]} files - Files to check
+ * @param {RegExp} regex - Pattern to match (violation)
+ * @param {string[]} excludeFiles - File paths to exclude
+ * @param {RegExp[]} excludePatterns - Line patterns to exclude (not violations even if regex matches)
  * @returns Number of violations
  */
-function checkPattern(label, files, regex, excludeFiles = []) {
+function checkPattern(label, files, regex, excludeFiles = [], excludePatterns = []) {
   const violations = [];
   for (const file of files) {
     const relPath = relative(process.cwd(), file);
@@ -100,6 +105,7 @@ function checkPattern(label, files, regex, excludeFiles = []) {
       const line = lines[i];
       const trimmed = line.trim();
       if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue;
+      if (excludePatterns.some((ep) => ep.test(trimmed))) continue;
       if (regex.test(line)) {
         violations.push(`  ${relPath}:${i + 1}: ${trimmed}`);
       }
@@ -214,11 +220,16 @@ checkPattern(
 
 // ── Handler Pattern ──────────────────────────────────────────────────────────
 
-// 3l. Exported handlers without wrapHandler
+// 3l. Exported handlers without wrapHandler or wrapCommand
 checkPattern(
-  'Exported handlers without wrapHandler',
+  'Exported handlers without wrapHandler/wrapCommand',
   formFiles,
-  /^export\s+(const|async\s+function|function)\s+\w+(?!.*wrapHandler)/,
+  /^export\s+(const|async\s+function|function)\s+\w+(?!.*(?:wrapHandler|wrapCommand))/,
+  [],
+  [
+    // Re-exports: `export const form_OnLoad = onLoad;` (alias for a wrapped handler)
+    /^export\s+const\s+\w+\s*=\s*[a-zA-Z][a-zA-Z0-9]*\s*;/,
+  ],
 );
 
 // ── Raw $select ──────────────────────────────────────────────────────────────

package/package.json

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