@xrmforge/devkit 0.5.2 → 0.5.4

package/dist/templates/azure-pipelines.yml

@@ -1,32 +1,32 @@
-trigger:
-  branches:
-    include:
-      - main
-
-pool:
-  vmImage: 'ubuntu-latest'
-
-steps:
-  - task: NodeTool@0
-    inputs:
-      versionSpec: '20.x'
-    displayName: 'Install Node.js'
-
-  - script: npm ci
-    displayName: 'Install dependencies'
-
-  - script: npx xrmforge generate --from-config
-    displayName: 'Generate types from Dataverse'
-    env:
-      XRMFORGE_CLIENT_ID: $(XRMFORGE_CLIENT_ID)
-      XRMFORGE_CLIENT_SECRET: $(XRMFORGE_CLIENT_SECRET)
-      XRMFORGE_TENANT_ID: $(XRMFORGE_TENANT_ID)
-
-  - script: npx tsc --noEmit
-    displayName: 'Type check'
-
-  - script: npx vitest run
-    displayName: 'Test'
-
-  - script: npx xrmforge build
-    displayName: 'Build WebResources'
+trigger:
+  branches:
+    include:
+      - main
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '20.x'
+    displayName: 'Install Node.js'
+
+  - script: npm ci
+    displayName: 'Install dependencies'
+
+  - script: npx xrmforge generate --from-config
+    displayName: 'Generate types from Dataverse'
+    env:
+      XRMFORGE_CLIENT_ID: $(XRMFORGE_CLIENT_ID)
+      XRMFORGE_CLIENT_SECRET: $(XRMFORGE_CLIENT_SECRET)
+      XRMFORGE_TENANT_ID: $(XRMFORGE_TENANT_ID)
+
+  - script: npx tsc --noEmit
+    displayName: 'Type check'
+
+  - script: npx vitest run
+    displayName: 'Test'
+
+  - script: npx xrmforge build
+    displayName: 'Build WebResources'

package/dist/templates/constants.ts

@@ -0,0 +1,32 @@
+/**
+ * Central constants for notifications and messages.
+ */
+
+/** Unique IDs for form-level notifications. */
+export const NOTIFICATION_IDS = {
+  genericError: '{{namespace}}.notification.generic-error'.toLowerCase(),
+} as const;
+
+/** Localized message strings (extend as needed). */
+export const MESSAGES = {
+  de: {
+    unsavedRecord: 'Der Datensatz muss zuerst gespeichert werden.',
+  },
+  en: {
+    unsavedRecord: 'The record must be saved first.',
+  },
+} as const;
+
+/**
+ * Pick the correct language table based on the user's D365 language setting.
+ *
+ * @param languageId - LCID from Xrm.Utility.getGlobalContext().userSettings.languageId
+ * @param table - Object with 'de' and 'en' keys containing the same message keys
+ * @returns The matching language table (defaults to English)
+ */
+export function pickLang<K extends string>(
+  languageId: number,
+  table: { de: Record<K, string>; en: Record<K, string> },
+): Record<K, string> {
+  return languageId === 1031 ? table.de : table.en;
+}

package/dist/templates/error-handler.ts

@@ -0,0 +1,95 @@
+/**
+ * Unified error handling for D365 form event handlers.
+ * Wraps sync and async handlers with try/catch and form notifications.
+ */
+import type { Logger } from './logger.js';
+import { NOTIFICATION_IDS } from './constants.js';
+
+type EventHandler = (ctx: Xrm.Events.EventContext, ...args: never[]) => unknown;
+
+/**
+ * Wrap a form event handler with error handling.
+ *
+ * Catches both sync and async errors, logs them, and shows a form notification.
+ * The original handler is never rethrown, so form execution continues.
+ *
+ * @param name - Handler name for logging (e.g. 'MyApp.Account.onLoad')
+ * @param logger - Logger instance for error reporting
+ * @param handler - The actual event handler function
+ */
+export function wrapHandler(name: string, logger: Logger, handler: EventHandler): EventHandler {
+  const wrapped: EventHandler = (ctx, ...args) => {
+    try {
+      const result = handler(ctx, ...args);
+      if (result && typeof (result as Promise<unknown>).then === 'function') {
+        return (result as Promise<unknown>).catch((err: unknown) => {
+          logAndNotify(ctx, name, logger, err);
+        });
+      }
+      return result;
+    } catch (err: unknown) {
+      logAndNotify(ctx, name, logger, err);
+    }
+  };
+  return wrapped;
+}
+
+/**
+ * Wrap a ribbon command handler with error handling.
+ *
+ * Unlike wrapHandler, this accepts a FormContext directly (not an EventContext),
+ * which is the calling convention for ribbon/command bar handlers.
+ *
+ * @param name - Handler name for logging
+ * @param logger - Logger instance for error reporting
+ * @param handler - The actual command handler function
+ */
+export function wrapCommand(
+  name: string,
+  logger: Logger,
+  handler: (formContext: Xrm.FormContext, ...args: never[]) => unknown,
+): (formContext: Xrm.FormContext, ...args: never[]) => unknown {
+  return (formContext, ...args) => {
+    try {
+      const result = handler(formContext, ...args);
+      if (result && typeof (result as Promise<unknown>).then === 'function') {
+        return (result as Promise<unknown>).catch((err: unknown) => {
+          logAndNotifyForm(formContext, name, logger, err);
+        });
+      }
+      return result;
+    } catch (err: unknown) {
+      logAndNotifyForm(formContext, name, logger, err);
+    }
+  };
+}
+
+function logAndNotify(
+  ctx: Xrm.Events.EventContext,
+  name: string,
+  logger: Logger,
+  err: unknown,
+): void {
+  const message = err instanceof Error ? err.message : String(err);
+  logger.error(`${name} failed`, { err });
+  try {
+    ctx.getFormContext().ui.setFormNotification(message, 'ERROR', NOTIFICATION_IDS.genericError);
+  } catch {
+    /* ignore */
+  }
+}
+
+function logAndNotifyForm(
+  formContext: Xrm.FormContext,
+  name: string,
+  logger: Logger,
+  err: unknown,
+): void {
+  const message = err instanceof Error ? err.message : String(err);
+  logger.error(`${name} failed`, { err });
+  try {
+    formContext.ui.setFormNotification(message, 'ERROR', NOTIFICATION_IDS.genericError);
+  } catch {
+    /* ignore */
+  }
+}

package/dist/templates/eslint.config.js

@@ -0,0 +1,21 @@
+import tseslint from '@typescript-eslint/eslint-plugin';
+import tsparser from '@typescript-eslint/parser';
+import xrmforge from '@xrmforge/eslint-plugin';
+
+export default [
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+    },
+    plugins: { '@typescript-eslint': tseslint },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    },
+  },
+  xrmforge.configs.recommended,
+  { rules: { 'no-console': ['error'] } },
+  { files: ['src/shared/logger.ts'], rules: { 'no-console': 'off' } },
+];

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

@@ -1,19 +1,19 @@
-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 } 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');
+  });
+});

package/dist/templates/example-form.ts

@@ -1,40 +1,40 @@
-/**
- * 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.
+ *
+ * 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');
+}

package/dist/templates/github-actions-ci.yml

@@ -1,36 +1,36 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - run: npm ci
-
-      - name: Generate types from Dataverse
-        run: npx xrmforge generate --from-config
-        env:
-          XRMFORGE_CLIENT_ID: ${{ secrets.XRMFORGE_CLIENT_ID }}
-          XRMFORGE_CLIENT_SECRET: ${{ secrets.XRMFORGE_CLIENT_SECRET }}
-          XRMFORGE_TENANT_ID: ${{ secrets.XRMFORGE_TENANT_ID }}
-
-      - name: Type check
-        run: npx tsc --noEmit
-
-      - name: Test
-        run: npx vitest run
-
-      - name: Build WebResources
-        run: npx xrmforge build
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - run: npm ci
+
+      - name: Generate types from Dataverse
+        run: npx xrmforge generate --from-config
+        env:
+          XRMFORGE_CLIENT_ID: ${{ secrets.XRMFORGE_CLIENT_ID }}
+          XRMFORGE_CLIENT_SECRET: ${{ secrets.XRMFORGE_CLIENT_SECRET }}
+          XRMFORGE_TENANT_ID: ${{ secrets.XRMFORGE_TENANT_ID }}
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Test
+        run: npx vitest run
+
+      - name: Build WebResources
+        run: npx xrmforge build

package/dist/templates/gitignore

@@ -1,19 +1,19 @@
-# Dependencies
-node_modules/
-
-# Build output
-dist/
-
-# XrmForge cache
-.xrmforge/
-
-# IDE
-.vscode/settings.json
-.idea/
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Logs
-*.log
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# XrmForge cache
+.xrmforge/
+
+# IDE
+.vscode/settings.json
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log

package/dist/templates/logger.ts

@@ -0,0 +1,67 @@
+/**
+ * Structured logger for D365 form scripts.
+ * This is the ONLY file allowed to use console.* directly.
+ */
+
+/** Logger interface for structured logging with namespace prefix. */
+export interface Logger {
+  debug(message: string, data?: unknown): void;
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+}
+
+const DEBUG_STORAGE_KEY = '{{namespace}}.debug'.toLowerCase();
+
+/** Check if the current host is a dev/test environment. */
+function isDebugHost(): boolean {
+  try {
+    const url = Xrm.Utility.getGlobalContext().getClientUrl() ?? '';
+    if (url.includes('-dev') || url.includes('-test')) return true;
+  } catch {
+    /* ignore */
+  }
+  return false;
+}
+
+/** Check if debug mode is enabled via localStorage. */
+function isDebugStorage(): boolean {
+  try {
+    return window?.localStorage?.getItem(DEBUG_STORAGE_KEY) === '1';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a namespaced logger instance.
+ *
+ * Debug messages are only shown in dev/test environments or when
+ * localStorage key is set to '1'.
+ *
+ * @param namespace - Prefix for all log messages (e.g. 'MyApp.Account')
+ */
+export function createLogger(namespace: string): Logger {
+  const prefix = `[${namespace}]`;
+  const debugEnabled = isDebugHost() || isDebugStorage();
+
+  return {
+    debug(message, data) {
+      if (!debugEnabled) return;
+      if (data !== undefined) console.debug(prefix, message, data);
+      else console.debug(prefix, message);
+    },
+    info(message, data) {
+      if (data !== undefined) console.info(prefix, message, data);
+      else console.info(prefix, message);
+    },
+    warn(message, data) {
+      if (data !== undefined) console.warn(prefix, message, data);
+      else console.warn(prefix, message);
+    },
+    error(message, data) {
+      if (data !== undefined) console.error(prefix, message, data);
+      else console.error(prefix, message);
+    },
+  };
+}

package/dist/templates/self-check.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# XrmForge Self-Check - Pattern Compliance Verification
+# Run this before tests to catch common violations.
+# Exit code: 0 = all clean, 1 = violations found
+
+set -uo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+NC='\033[0m'
+
+violations=0
+category_count=0
+
+check() {
+  local label="$1"
+  shift
+  local count
+  count=$("$@" 2>/dev/null | wc -l | tr -d ' ')
+  category_count=$((category_count + 1))
+  if [ "$count" -gt 0 ]; then
+    echo -e "${RED}FAIL${NC} [$count] $label"
+    "$@" 2>/dev/null | head -20
+    violations=$((violations + count))
+  else
+    echo -e "${GREEN}OK${NC}   [0] $label"
+  fi
+}
+
+echo "=== XrmForge Self-Check ==="
+echo ""
+echo "--- Pattern Compliance ---"
+
+check "Raw field strings in getAttribute/getControl (must use Fields Enum)" \
+  bash -c 'grep -rn "getAttribute('" '"'"'" src/forms/ --include="*.ts" | grep -v "Fields\." ; grep -rn "getControl('" '"'"'" src/forms/ --include="*.ts" | grep -v "Fields\."'
+
+check "Magic numbers in OptionSet comparisons (must use OptionSet Enum)" \
+  bash -c 'grep -rn "getValue() ===" src/ --include="*.ts" | grep -E "[0-9]{3,}"'
+
+check "Direct _value access instead of parseLookup (Web API responses)" \
+  bash -c 'grep -rn "_value\b" src/ --include="*.ts" | grep -v "generated/" | grep -v "parseLookup" | grep -v "getValue"'
+
+check "Raw entity names in WebApi calls (must use EntityNames)" \
+  bash -c 'grep -rn "retrieveRecord\|retrieveMultipleRecords\|deleteRecord\|createRecord\|updateRecord" src/ --include="*.ts" | grep "'"'"'[a-z]" | grep -v "EntityNames"'
+
+check "Raw \$select strings (must use select() from @xrmforge/helpers)" \
+  bash -c 'grep -rn '"'"'\$select'"'"' src/ --include="*.ts" | grep -v "select(" | grep -v "generated/"'
+
+check "Missing FormContext cast in onLoad (must have 'as <Generated>Form')" \
+  bash -c 'grep -rn "getFormContext()" src/forms/ --include="*.ts" | grep -v " as "'
+
+check "Exported handlers without wrapHandler" \
+  bash -c 'grep -rn "^export const\|^export async function\|^export function" src/forms/ --include="*.ts" | grep -v "wrapHandler"'
+
+echo ""
+echo "--- Code Quality ---"
+
+check "console.* outside logger.ts" \
+  bash -c 'grep -rn "console\." src/ --include="*.ts" | grep -v "logger.ts"'
+
+check "Xrm.Page (deprecated since D365 v9.0)" \
+  bash -c 'grep -rn "Xrm\.Page" src/ --include="*.ts"'
+
+check "var declarations" \
+  bash -c 'grep -rnE "^\s*var " src/ --include="*.ts"'
+
+check "eval()" \
+  bash -c 'grep -rn "\beval(" src/ --include="*.ts"'
+
+check "XMLHttpRequest" \
+  bash -c 'grep -rn "XMLHttpRequest" src/ --include="*.ts"'
+
+check "as any without eslint-disable comment" \
+  bash -c 'grep -rn "as any" src/ --include="*.ts" | grep -v "eslint-disable"'
+
+check "Import from @xrmforge/typegen in browser code (use @xrmforge/helpers)" \
+  bash -c 'grep -rn "from.*@xrmforge/typegen" src/ --include="*.ts" | grep -v "generated/"'
+
+echo ""
+echo "--- Test Completeness ---"
+
+missing_tests=0
+for f in src/forms/*.ts; do
+  [ -f "$f" ] || continue
+  base=$(basename "$f" .ts)
+  if [ ! -f "tests/forms/${base}.test.ts" ]; then
+    echo -e "${YELLOW}WARN${NC} No test file: $f"
+    missing_tests=$((missing_tests + 1))
+  fi
+done
+if [ "$missing_tests" -eq 0 ]; then
+  echo -e "${GREEN}OK${NC}   All form scripts have test files"
+else
+  echo -e "${YELLOW}WARN${NC} $missing_tests form scripts without tests"
+fi
+
+echo ""
+echo "=== Results ==="
+if [ "$violations" -eq 0 ]; then
+  echo -e "${GREEN}All $category_count checks passed. 0 violations.${NC}"
+  exit 0
+else
+  echo -e "${RED}$violations violations found across $category_count checks.${NC}"
+  exit 1
+fi

package/dist/templates/vitest.config.ts

@@ -1,8 +1,8 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    globals: false,
-    include: ['tests/**/*.test.ts'],
-  },
-});
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: false,
+    include: ['tests/**/*.test.ts'],
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xrmforge/devkit",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Build orchestration and project tooling for Dynamics 365 WebResources",
   "keywords": [
     "dynamics-365",
@@ -25,7 +25,8 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",