@xrmforge/devkit 0.7.29 → 0.7.30

package/dist/templates/AGENT.md

@@ -305,6 +305,13 @@ export const onLoad = wrapHandler('Namespace.Entity.onLoad', logger, async (ctx)
 });
 ```
 
+Ribbon/command bar commands use `wrapCommand` (it receives a FormContext, not an
+EventContext). Pass extra command parameters through its `TArgs` type parameter
+instead of widening to `any`. A command registered on a **subgrid** receives a
+`GridControl` as PrimaryControl (which has no form `ui`), so wrap it with
+`wrapGridCommand` - its error surface is an app-level banner, and its default extra
+argument is the selected record ids (`string[]`).
+
 ### 8. Custom API Executors from generated/actions/
 
 Never build your own ExecuteFunctionCall wrapper. Use the generated executors.
@@ -515,8 +522,13 @@ export function createLogger(namespace: string): Logger;
 ### error-handler.ts
 ```typescript
 export function wrapHandler(name: string, logger: Logger, handler: EventHandler): EventHandler;
-export function wrapCommand(name: string, logger: Logger, handler: CommandHandler): CommandHandler;
-// Catches sync+async errors, shows form notification via FormNotificationLevel.Error
+// Ribbon/command bar command on a form. Pass extra command parameters through TArgs (default none).
+export function wrapCommand<TArgs extends unknown[] = []>(name, logger, handler): (formContext, ...args) => unknown;
+// Command registered on a SUBGRID: PrimaryControl may be a GridControl (no form ui).
+// Default extra arg is the selected record ids (string[]).
+export function wrapGridCommand<TArgs extends unknown[] = [string[]]>(name, logger, handler): (primaryControl, ...args) => unknown;
+// Catches sync+async errors. wrapHandler/wrapCommand show a form notification via
+// FormNotificationLevel.Error; wrapGridCommand uses an app-level banner (GridControl has no form ui).
 ```
 
 ### constants.ts
@@ -850,7 +862,7 @@ regenerate and commit.
 ```
 src/forms/{entity}-form.ts       - Form scripts (one per entity)
 src/shared/logger.ts             - Structured logger (only file with console.*)
-src/shared/error-handler.ts      - wrapHandler + wrapCommand
+src/shared/error-handler.ts      - wrapHandler + wrapCommand + wrapGridCommand
 src/shared/constants.ts          - NOTIFICATION_IDS, MESSAGES, pickLang
 generated/                       - Generated types (do not edit manually)
 tests/forms/{entity}.test.ts     - Tests

package/dist/templates/error-handler.ts

@@ -1,10 +1,11 @@
 /**
- * Unified error handling for D365 form event handlers.
- * Wraps sync and async handlers with try/catch and form notifications.
+ * Unified error handling for D365 form event handlers and ribbon commands.
+ * Wraps sync and async handlers with try/catch: form handlers and form commands
+ * show a form notification, subgrid commands an app-level notification banner.
  */
 import type { Logger } from './logger.js';
 import { NOTIFICATION_IDS } from './constants.js';
-import { FormNotificationLevel } from '@xrmforge/helpers';
+import { FormNotificationLevel, AppNotificationLevel, addAppNotification } from '@xrmforge/helpers';
 
 type EventHandler = (ctx: Xrm.Events.EventContext, ...args: never[]) => unknown;
 
@@ -36,20 +37,28 @@ export function wrapHandler(name: string, logger: Logger, handler: EventHandler)
 }
 
 /**
- * Wrap a ribbon command handler with error handling.
+ * Wrap a ribbon command handler (form context) with error handling.
  *
  * Unlike wrapHandler, this accepts a FormContext directly (not an EventContext),
  * which is the calling convention for ribbon/command bar handlers.
  *
+ * Pass extra ribbon command parameters via the TArgs type parameter so they stay
+ * typed end to end (e.g. `wrapCommand<[boolean]>(...)` for a handler that takes a
+ * flag after the form context). TArgs defaults to `[]` (no extra parameters).
+ *
+ * For commands registered on a subgrid (the PrimaryControl may be a GridControl,
+ * not a FormContext) use {@link wrapGridCommand} instead.
+ *
+ * @typeParam TArgs - Tuple of extra parameters passed after the form context
  * @param name - Handler name for logging
  * @param logger - Logger instance for error reporting
  * @param handler - The actual command handler function
  */
-export function wrapCommand(
+export function wrapCommand<TArgs extends unknown[] = []>(
   name: string,
   logger: Logger,
-  handler: (formContext: Xrm.FormContext, ...args: never[]) => unknown,
-): (formContext: Xrm.FormContext, ...args: never[]) => unknown {
+  handler: (formContext: Xrm.FormContext, ...args: TArgs) => unknown,
+): (formContext: Xrm.FormContext, ...args: TArgs) => unknown {
   return (formContext, ...args) => {
     try {
       const result = handler(formContext, ...args);
@@ -65,6 +74,43 @@ export function wrapCommand(
   };
 }
 
+/**
+ * Wrap a ribbon command handler whose PrimaryControl can be a subgrid.
+ *
+ * Commands registered on a subgrid (or on both a form and a subgrid) receive a
+ * `GridControl` as the first argument when fired from the grid, plus the selected
+ * record ids. A `GridControl` has no form `ui`, so a form notification cannot be
+ * shown - this variant reports errors via the logger and an app-level banner
+ * ({@link addAppNotification}) that works independently of the form context.
+ *
+ * TArgs defaults to `[string[]]` (the selected record ids that D365 passes as the
+ * SelectedControlSelectedItemIds command parameter).
+ *
+ * @typeParam TArgs - Tuple of extra parameters passed after the primary control
+ * @param name - Handler name for logging
+ * @param logger - Logger instance for error reporting
+ * @param handler - The actual command handler function
+ */
+export function wrapGridCommand<TArgs extends unknown[] = [string[]]>(
+  name: string,
+  logger: Logger,
+  handler: (primaryControl: Xrm.FormContext | Xrm.Controls.GridControl, ...args: TArgs) => unknown,
+): (primaryControl: Xrm.FormContext | Xrm.Controls.GridControl, ...args: TArgs) => unknown {
+  return (primaryControl, ...args) => {
+    try {
+      const result = handler(primaryControl, ...args);
+      if (result && typeof (result as Promise<unknown>).then === 'function') {
+        return (result as Promise<unknown>).catch((err: unknown) => {
+          logAndNotifyApp(name, logger, err);
+        });
+      }
+      return result;
+    } catch (err: unknown) {
+      logAndNotifyApp(name, logger, err);
+    }
+  };
+}
+
 function logAndNotify(
   ctx: Xrm.Events.EventContext,
   name: string,
@@ -94,3 +140,19 @@ function logAndNotifyForm(
     /* ignore */
   }
 }
+
+/**
+ * Log an error and surface it as an app-level (global) notification banner.
+ *
+ * Used by {@link wrapGridCommand}: the PrimaryControl may be a GridControl that
+ * has no form `ui`, so a form notification is not available. The app banner is
+ * shown regardless of the calling control. The async banner call is
+ * fire-and-forget so the command handler is not forced to be async.
+ */
+function logAndNotifyApp(name: string, logger: Logger, err: unknown): void {
+  const message = err instanceof Error ? err.message : String(err);
+  logger.error(`${name} failed`, { err });
+  void addAppNotification(message, AppNotificationLevel.Error).catch(() => {
+    /* ignore */
+  });
+}

package/package.json

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