@xrmforge/devkit 0.5.7 → 0.7.0

package/dist/templates/error-handler.ts

@@ -4,6 +4,7 @@
  */
 import type { Logger } from './logger.js';
 import { NOTIFICATION_IDS } from './constants.js';
+import { FormNotificationLevel } from '@xrmforge/helpers';
 
 type EventHandler = (ctx: Xrm.Events.EventContext, ...args: never[]) => unknown;
 
@@ -73,7 +74,7 @@ function logAndNotify(
   const message = err instanceof Error ? err.message : String(err);
   logger.error(`${name} failed`, { err });
   try {
-    ctx.getFormContext().ui.setFormNotification(message, 'ERROR', NOTIFICATION_IDS.genericError);
+    ctx.getFormContext().ui.setFormNotification(message, FormNotificationLevel.Error, NOTIFICATION_IDS.genericError);
   } catch {
     /* ignore */
   }
@@ -88,7 +89,7 @@ function logAndNotifyForm(
   const message = err instanceof Error ? err.message : String(err);
   logger.error(`${name} failed`, { err });
   try {
-    formContext.ui.setFormNotification(message, 'ERROR', NOTIFICATION_IDS.genericError);
+    formContext.ui.setFormNotification(message, FormNotificationLevel.Error, NOTIFICATION_IDS.genericError);
   } catch {
     /* ignore */
   }

package/dist/templates/example-form.test.ts

@@ -1,19 +1,34 @@
-import { describe, it, expect } from 'vitest';
-
-/**
- * Example test for the form script.
- *
- * Uses @xrmforge/testing for type-safe mocking once you have
- * generated types. For now, this is a placeholder.
- */
-describe('{{namespace}}.Example', () => {
-  it('should export onLoad function', async () => {
-    const mod = await import('../../src/forms/example-form.js');
-    expect(typeof mod.onLoad).toBe('function');
-  });
-
-  it('should export onSave function', async () => {
-    const mod = await import('../../src/forms/example-form.js');
-    expect(typeof mod.onSave).toBe('function');
-  });
-});
+import { describe, it, expect, vi } from 'vitest';
+
+/**
+ * Example test for the form script.
+ *
+ * Uses @xrmforge/testing for type-safe mocking once you have
+ * generated types. Replace with real form tests after 'xrmforge generate'.
+ */
+describe('{{namespace}}.Example', () => {
+  it('should export onLoad handler', async () => {
+    const mod = await import('../../src/forms/example-form.js');
+    expect(typeof mod.onLoad).toBe('function');
+  });
+
+  it('should export onSave handler', async () => {
+    const mod = await import('../../src/forms/example-form.js');
+    expect(typeof mod.onSave).toBe('function');
+  });
+
+  // TODO: After running 'xrmforge generate', add real form tests:
+  //
+  // import { createFormMock } from '@xrmforge/testing';
+  // import type { ExampleFormMockValues } from '../../generated/entities/Example.js';
+  //
+  // it('should show notification on load', () => {
+  //   const { executionContext, formContext } = createFormMock<ExampleFormMockValues>({
+  //     name: 'Contoso Ltd',
+  //   });
+  //   onLoad(executionContext);
+  //   expect(formContext.ui.setFormNotification).toHaveBeenCalledWith(
+  //     'Form loaded successfully', 'INFO', 'example-load-notification'
+  //   );
+  // });
+});

package/dist/templates/example-form.ts

@@ -1,40 +1,76 @@
-/**
- * Example Form Script for Dynamics 365.
- *
- * Register in D365 as: {{namespace}}.Example.onLoad
- *
- * Replace this with your actual form logic.
- */
-
-/**
- * Called when the form loads.
- */
-export function onLoad(executionContext: Xrm.Events.EventContext): void {
-  const formContext = executionContext.getFormContext();
-
-  // Example: show a notification on the form
-  formContext.ui.setFormNotification(
-    'Form loaded successfully',
-    'INFO',
-    'example-notification',
-  );
-
-  // Example: read a field value
-  // TODO: Replace with generated Fields enum after running 'xrmforge generate'
-  // Example: formContext.getAttribute(Fields.Name)
-  const nameAttr = formContext.getAttribute('name');
-  if (nameAttr) {
-    const value = nameAttr.getValue();
-    console.log('Name field value:', value);
-  }
-}
-
-/**
- * Called when the form is saved.
- */
-export function onSave(executionContext: Xrm.Events.EventContext): void {
-  const formContext = executionContext.getFormContext();
-
-  // Clear the notification on save
-  formContext.ui.clearFormNotification('example-notification');
-}
+/**
+ * Example Form Script for Dynamics 365 using XrmForge best practices.
+ *
+ * Register in D365 as: {{namespace}}.Example.onLoad
+ *
+ * This template demonstrates the correct patterns:
+ * - typedForm() for direct typed field access
+ * - Fields Enum for addOnChange and $control
+ * - Entity-level Fields for Web API select() queries
+ * - wrapHandler for unified error handling
+ * - Logger instead of console.log
+ * - FormNotificationLevel constant instead of raw string
+ * - pickLang() for localized UI strings
+ *
+ * Replace this file with your actual form logic after running 'xrmforge generate'.
+ */
+import { createLogger } from '../shared/logger.js';
+import { wrapHandler } from '../shared/error-handler.js';
+import { MESSAGES, pickLang } from '../shared/constants.js';
+import { typedForm, FormNotificationLevel, select, formLookupId } from '@xrmforge/helpers';
+// TODO: After 'xrmforge generate', replace with your actual imports:
+// import type { ExampleForm } from '../../generated/forms/example.js';
+// import { ExampleFormFieldsEnum as Fields } from '../../generated/forms/example.js';
+// import { ExampleFields } from '../../generated/fields/example.js';
+// import { EntityNames } from '../../generated/entity-names.js';
+
+const logger = createLogger('{{namespace}}.Example');
+
+/**
+ * Called when the form loads.
+ */
+export const onLoad = wrapHandler('{{namespace}}.Example.onLoad', logger, async (ctx) => {
+  // TODO: Replace 'Xrm.FormContext' with your generated form type:
+  // const form = typedForm<ExampleForm>(ctx.getFormContext());
+  const form = typedForm<Xrm.FormContext>(ctx.getFormContext());
+
+  // Direct field access via typedForm proxy (fully typed):
+  // const name = form.name.getValue();          // string | null
+  // form.revenue.setValue(150000);               // NumberAttribute
+
+  // addOnChange uses Fields Enum via $context:
+  // form.$context.getAttribute(Fields.Name).addOnChange(() => {
+  //   logger.debug('Name changed', { value: form.name.getValue() });
+  // });
+
+  // Web API queries use entity-level Fields:
+  // const result = await Xrm.WebApi.retrieveRecord(
+  //   EntityNames.Account, id,
+  //   select(ExampleFields.Name, ExampleFields.WebsiteUrl)
+  // );
+
+  // Lookup access:
+  // const parentId = formLookupId(form.parentaccountid);
+
+  // Localized UI strings:
+  const lang = pickLang(
+    Xrm.Utility.getGlobalContext().userSettings.languageId,
+    MESSAGES,
+  );
+  logger.info('Form loaded', { language: lang });
+
+  // Form notifications use constants:
+  form.$context.ui.setFormNotification(
+    'Form loaded',
+    FormNotificationLevel.Info,
+    'example-load',
+  );
+});
+
+/**
+ * Called when the form is saved.
+ */
+export const onSave = wrapHandler('{{namespace}}.Example.onSave', logger, (ctx) => {
+  const form = typedForm<Xrm.FormContext>(ctx.getFormContext());
+  form.$context.ui.clearFormNotification('example-load');
+});

package/dist/templates/validate-form.mjs

@@ -0,0 +1,263 @@
+/**
+ * validate-form.mjs - Quality Gate for XrmForge Form Scripts
+ *
+ * Runs three checks in one command:
+ * 1. TypeScript Compiler (tsc --noEmit)
+ * 2. ESLint (src/ --max-warnings=0)
+ * 3. Pattern Compliance (critical rule violations via text search)
+ *
+ * Exit code: 0 = all green, 1 = errors found
+ *
+ * Usage:
+ *   node scripts/validate-form.mjs
+ *   npm run validate
+ */
+
+import { execSync } from 'node:child_process';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const NC = '\x1b[0m';
+
+let totalErrors = 0;
+
+// ============================================================
+// 1. TypeScript Compiler
+// ============================================================
+
+console.log('=== XrmForge Quality Gate ===\n');
+console.log('--- TypeScript ---');
+
+try {
+  execSync('npx tsc --noEmit', { stdio: 'pipe', encoding: 'utf-8' });
+  console.log(`${GREEN}OK${NC}   tsc --noEmit`);
+} catch (err) {
+  const output = (err.stdout || '') + (err.stderr || '');
+  const errorCount = (output.match(/error TS/g) || []).length;
+  console.log(`${RED}FAIL${NC} tsc --noEmit (${errorCount} errors)`);
+  console.log(output.split('\n').slice(0, 20).join('\n'));
+  totalErrors += errorCount || 1;
+}
+
+// ============================================================
+// 2. ESLint
+// ============================================================
+
+console.log('\n--- ESLint ---');
+
+try {
+  execSync('npx eslint src/ --max-warnings=0', { stdio: 'pipe', encoding: 'utf-8' });
+  console.log(`${GREEN}OK${NC}   eslint src/ --max-warnings=0`);
+} catch (err) {
+  const output = (err.stdout || '') + (err.stderr || '');
+  const problemMatch = output.match(/(\d+) problems?/);
+  const count = problemMatch ? problemMatch[1] : '?';
+  console.log(`${RED}FAIL${NC} eslint (${count} problems)`);
+  console.log(output.split('\n').slice(0, 20).join('\n'));
+  totalErrors += parseInt(count) || 1;
+}
+
+// ============================================================
+// 3. Pattern Compliance (critical rules)
+// ============================================================
+
+console.log('\n--- Pattern Compliance ---');
+
+/**
+ * Collect all .ts files recursively from a directory.
+ */
+function collectTsFiles(dir) {
+  const results = [];
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory() && entry.name !== 'node_modules' && entry.name !== 'dist') {
+        results.push(...collectTsFiles(fullPath));
+      } else if (entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+        results.push(fullPath);
+      }
+    }
+  } catch {
+    // Directory does not exist
+  }
+  return results;
+}
+
+/**
+ * Check a pattern rule against all files.
+ * @returns Number of violations
+ */
+function checkPattern(label, files, regex, excludeFiles = []) {
+  const violations = [];
+  for (const file of files) {
+    const relPath = relative(process.cwd(), file);
+    if (excludeFiles.some((ex) => relPath.includes(ex))) continue;
+
+    const lines = readFileSync(file, 'utf-8').split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+      if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue;
+      if (regex.test(line)) {
+        violations.push(`  ${relPath}:${i + 1}: ${trimmed}`);
+      }
+    }
+  }
+
+  if (violations.length === 0) {
+    console.log(`${GREEN}OK${NC}   [0] ${label}`);
+  } else {
+    console.log(`${RED}FAIL${NC} [${violations.length}] ${label}`);
+    violations.slice(0, 10).forEach((v) => console.log(v));
+    if (violations.length > 10) {
+      console.log(`  ... and ${violations.length - 10} more`);
+    }
+    totalErrors += violations.length;
+  }
+  return violations.length;
+}
+
+const formFiles = collectTsFiles('src/forms');
+const allSrcFiles = collectTsFiles('src');
+
+// ── Field Access ─────────────────────────────────────────────────────────────
+
+// 3a. Raw strings in getAttribute/getControl (must use Fields Enum)
+checkPattern(
+  'Raw field strings in getAttribute/getControl',
+  formFiles,
+  /(?:getAttribute|getControl)\s*\(\s*['"][a-z]/,
+);
+
+// 3b. Raw strings in helper wrappers (getValue, setFieldValue, setDisabled, addOnChange, setVisible, setRequiredLevel)
+checkPattern(
+  'Raw field strings in helper functions (use typedForm or Fields Enum)',
+  allSrcFiles,
+  /(?:getValue|setFieldValue|setDisabled|addOnChange|setVisible|setRequiredLevel|addPreSearch)\s*\(\s*\w+\s*,\s*['"][a-z]/,
+  ['generated/', 'logger.ts'],
+);
+
+// 3c. Raw strings in select() (must use entity-level Fields Enum)
+checkPattern(
+  'Raw field strings in select() (use entity-level Fields Enum)',
+  allSrcFiles,
+  /\bselect\s*\(\s*['"][a-z]/,
+  ['generated/'],
+);
+
+// ── Entity Names ─────────────────────────────────────────────────────────────
+
+// 3d. Raw entity name strings in WebApi calls (must use EntityNames Enum)
+checkPattern(
+  'Raw entity names in WebApi (must use EntityNames Enum)',
+  allSrcFiles,
+  /(?:retrieveRecord|retrieveMultipleRecords|createRecord|updateRecord|deleteRecord)\s*\(\s*['"]/,
+  ['generated/'],
+);
+
+// 3e. SystemEntities workaround (must extend generation instead)
+checkPattern(
+  'SystemEntities workaround (extend generation with --entities instead)',
+  allSrcFiles,
+  /SystemEntities\./,
+);
+
+// ── Magic Values ─────────────────────────────────────────────────────────────
+
+// 3f. Magic numbers in OptionSet comparisons (must use OptionSet Enum)
+checkPattern(
+  'Magic numbers in value comparisons (use OptionSet Enum)',
+  allSrcFiles,
+  /getValue\(\)\s*===?\s*\d{3,}/,
+  ['generated/'],
+);
+
+// 3g. Magic number 86400000 (must use named constant MS_PER_DAY)
+checkPattern(
+  'Magic number 86400000 (use named constant MS_PER_DAY)',
+  allSrcFiles,
+  /86400000/,
+);
+
+// 3h. Raw notification level strings (must use FormNotificationLevel)
+checkPattern(
+  'Raw notification level strings (use FormNotificationLevel from @xrmforge/helpers)',
+  allSrcFiles,
+  /setFormNotification\s*\([^)]*['"](?:ERROR|WARNING|INFO)['"]/,
+);
+
+// ── Deprecated / Unsafe ──────────────────────────────────────────────────────
+
+// 3i. Xrm.Page (deprecated since D365 v9.0)
+checkPattern(
+  'Xrm.Page (deprecated since D365 v9.0)',
+  allSrcFiles,
+  /\bXrm\.Page\b/,
+);
+
+// 3j. eval() usage
+checkPattern(
+  'eval() usage (use Number() or JSON.parse())',
+  allSrcFiles,
+  /\beval\s*\(/,
+);
+
+// 3k. console.log/warn/error outside logger.ts (must use Logger)
+checkPattern(
+  'console.* outside logger.ts (must use Logger)',
+  allSrcFiles,
+  /\bconsole\.(log|warn|error|info|debug)\b/,
+  ['logger.ts'],
+);
+
+// ── Handler Pattern ──────────────────────────────────────────────────────────
+
+// 3l. Exported handlers without wrapHandler
+checkPattern(
+  'Exported handlers without wrapHandler',
+  formFiles,
+  /^export\s+(const|async\s+function|function)\s+\w+(?!.*wrapHandler)/,
+);
+
+// ── Raw $select ──────────────────────────────────────────────────────────────
+
+// 3m. Raw $select strings (must use select() from @xrmforge/helpers)
+checkPattern(
+  'Raw $select strings (must use select() from @xrmforge/helpers)',
+  allSrcFiles,
+  /['"]\?\$select=/,
+  ['generated/'],
+);
+
+// ── FetchXML ─────────────────────────────────────────────────────────────────
+
+// 3n. Raw field names in FetchXML attribute= (should use Fields Enum interpolation)
+checkPattern(
+  'Raw field names in FetchXML (use Fields Enum interpolation)',
+  allSrcFiles,
+  /attribute\s*=\s*'[a-z][a-z0-9_]+'/,
+  ['generated/'],
+);
+
+// 3o. Magic numbers in FetchXML <value> (should use OptionSet Enum)
+checkPattern(
+  'Magic numbers in FetchXML values (use OptionSet Enum)',
+  allSrcFiles,
+  /<value>\d{3,}<\/value>/,
+  ['generated/'],
+);
+
+// ============================================================
+// Result
+// ============================================================
+
+console.log('\n=== Result ===');
+if (totalErrors === 0) {
+  console.log(`${GREEN}All checks passed. 0 violations.${NC}`);
+  process.exit(0);
+} else {
+  console.log(`${RED}${totalErrors} violations found.${NC}`);
+  process.exit(1);
+}

package/package.json

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