@xrmforge/devkit 0.7.29 → 0.7.31

package/dist/index.js

@@ -310,8 +310,9 @@ function generatePackageJson(projectName) {
       // 0.7.0) plus the ./.env auto-load and interactive prompt (0.8.0) need cli at
       // that minor; a 0.x caret never crosses a minor boundary, so an older pin
       // would hand fresh projects a cli without these features.
-      // helpers ^0.11.0: on-form setAndSubmit, off-form formLookupIdUnsafe/formLookupUnsafe,
-      // getEnvironmentVariable, isUnsavedRecord ship in 0.11.0 (Runde 8: F-LMA8-N1/N2, F-MK8-N4a/b);
+      // helpers ^0.12.0: addAppNotification autoHideMs (self-clearing transient banners) ships in 0.12.0
+      // (Runde 9 F-MK9-10); on-form setAndSubmit, off-form formLookupIdUnsafe/formLookupUnsafe,
+      // getEnvironmentVariable, isUnsavedRecord since 0.11.0 (Runde 8: F-LMA8-N1/N2, F-MK8-N4a/b);
       // MultiSelect/submit/app-notification (parseMultiSelect, clearAndSubmit, setUnsafeAndSubmit,
       // addAppNotification) since 0.10.0; void Custom API executors since 0.9.0; isFormType since 0.8.0.
       // testing ^0.6.0: subgrid MockControl.refresh() ships in 0.6.0 (Runde 9: F-MK9-01); online.execute
@@ -320,7 +321,7 @@ function generatePackageJson(projectName) {
       // utilityOverrides) since 0.4.0; tabs since 0.3.0.
       "@xrmforge/cli": "^0.8.0",
       "@xrmforge/eslint-plugin": "^0.3.0",
-      "@xrmforge/helpers": "^0.11.0",
+      "@xrmforge/helpers": "^0.12.0",
       "@xrmforge/testing": "^0.6.0",
       eslint: "^9.0.0",
       typescript: "^5.7.0",

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts","../src/config.ts","../src/builder/esbuild-builder.ts","../src/scaffold/scaffold.ts","../src/scaffold/template-loader.ts"],"sourcesContent":["/**\r\n * @xrmforge/devkit - Build Error Types\r\n *\r\n * Structured error types for build operations.\r\n */\r\n\r\nexport enum BuildErrorCode {\r\n  /** Build configuration is invalid or missing required fields */\r\n  CONFIG_INVALID = 'BUILD_6001',\r\n  /** Entry point file not found on disk */\r\n  ENTRY_NOT_FOUND = 'BUILD_6002',\r\n  /** esbuild compilation failed (syntax errors, missing imports) */\r\n  BUILD_FAILED = 'BUILD_6003',\r\n  /** Error in watch mode */\r\n  WATCH_ERROR = 'BUILD_6004',\r\n}\r\n\r\n/**\r\n * Structured error class for build operations.\r\n *\r\n * Carries a machine-readable {@link BuildErrorCode} and optional context\r\n * for debugging. The error message is prefixed with the code (e.g. `[BUILD_6001]`).\r\n *\r\n * @example\r\n * ```typescript\r\n * throw new BuildError(\r\n *   BuildErrorCode.ENTRY_NOT_FOUND,\r\n *   'Could not find entry point: ./src/missing.ts',\r\n *   { entry: 'my_script' },\r\n * );\r\n * ```\r\n */\r\nexport class BuildError extends Error {\r\n  /** Machine-readable error code for programmatic handling. */\r\n  public readonly code: BuildErrorCode;\r\n  /** Additional context for debugging (e.g. entry name, file path). */\r\n  public readonly context: Record<string, unknown>;\r\n\r\n  /**\r\n   * @param code - Machine-readable error code\r\n   * @param message - Human-readable error description\r\n   * @param context - Optional key-value pairs for debugging context\r\n   */\r\n  constructor(code: BuildErrorCode, message: string, context: Record<string, unknown> = {}) {\r\n    super(`[${code}] ${message}`);\r\n    this.name = 'BuildError';\r\n    this.code = code;\r\n    this.context = context;\r\n\r\n    if (Error.captureStackTrace) {\r\n      Error.captureStackTrace(this, BuildError);\r\n    }\r\n  }\r\n}\r\n","/**\r\n * @xrmforge/devkit - Build Configuration\r\n *\r\n * Types and validation for the `build` section in xrmforge.config.json.\r\n */\r\n\r\nimport { BuildError, BuildErrorCode } from './errors.js';\r\n\r\n/** A single build entry (one WebResource) */\r\nexport interface BuildEntry {\r\n  /** Relative path to the TypeScript source file */\r\n  input: string;\r\n  /** Global namespace for D365 form event binding (e.g. \"Contoso.Account\") */\r\n  namespace: string;\r\n  /** Optional output filename relative to outDir (defaults to entry key + \".js\") */\r\n  out?: string;\r\n}\r\n\r\n/** Build configuration for WebResource bundling */\r\nexport interface BuildConfig {\r\n  /** Bundler to use (currently only \"esbuild\") */\r\n  bundler?: 'esbuild';\r\n  /** Named build entries: key = entry name, value = entry config */\r\n  entries: Record<string, BuildEntry>;\r\n  /** Output directory for built bundles (default: \"./dist\") */\r\n  outDir?: string;\r\n  /** JavaScript target version (default: \"es2020\") */\r\n  target?: string;\r\n  /** Generate source maps (default: true) */\r\n  sourcemap?: boolean;\r\n  /** Minify output (default: false) */\r\n  minify?: boolean;\r\n  /** Additional modules to exclude from bundling */\r\n  external?: string[];\r\n}\r\n\r\n/** Fully resolved build config with all defaults applied */\r\nexport interface ResolvedBuildConfig {\r\n  bundler: 'esbuild';\r\n  entries: Record<string, BuildEntry>;\r\n  outDir: string;\r\n  target: string;\r\n  sourcemap: boolean;\r\n  minify: boolean;\r\n  external: string[];\r\n}\r\n\r\n/**\r\n * Validate a raw build config object parsed from xrmforge.config.json.\r\n *\r\n * Checks that all required fields (entries, input, namespace) are present\r\n * and have valid types. Throws {@link BuildError} with CONFIG_INVALID if\r\n * any validation check fails.\r\n *\r\n * @param raw - Untyped config object to validate\r\n * @returns The validated build configuration\r\n * @throws {BuildError} If any required field is missing or has an invalid type\r\n */\r\nexport function validateBuildConfig(raw: unknown): BuildConfig {\r\n  if (!raw || typeof raw !== 'object') {\r\n    throw new BuildError(\r\n      BuildErrorCode.CONFIG_INVALID,\r\n      'Build configuration must be an object.',\r\n    );\r\n  }\r\n\r\n  const config = raw as Record<string, unknown>;\r\n\r\n  // entries: required, non-empty object\r\n  if (!config['entries'] || typeof config['entries'] !== 'object' || Array.isArray(config['entries'])) {\r\n    throw new BuildError(\r\n      BuildErrorCode.CONFIG_INVALID,\r\n      'Build configuration requires an \"entries\" object with at least one entry.',\r\n    );\r\n  }\r\n\r\n  const entries = config['entries'] as Record<string, unknown>;\r\n  const entryNames = Object.keys(entries);\r\n\r\n  if (entryNames.length === 0) {\r\n    throw new BuildError(\r\n      BuildErrorCode.CONFIG_INVALID,\r\n      'Build configuration requires at least one entry in \"entries\".',\r\n    );\r\n  }\r\n\r\n  for (const name of entryNames) {\r\n    const entry = entries[name] as Record<string, unknown> | undefined;\r\n\r\n    if (!entry || typeof entry !== 'object') {\r\n      throw new BuildError(\r\n        BuildErrorCode.CONFIG_INVALID,\r\n        `Entry \"${name}\" must be an object with \"input\" and \"namespace\".`,\r\n        { entry: name },\r\n      );\r\n    }\r\n\r\n    if (!entry['input'] || typeof entry['input'] !== 'string') {\r\n      throw new BuildError(\r\n        BuildErrorCode.CONFIG_INVALID,\r\n        `Entry \"${name}\" requires an \"input\" field (path to .ts source file).`,\r\n        { entry: name },\r\n      );\r\n    }\r\n\r\n    if (!entry['namespace'] || typeof entry['namespace'] !== 'string') {\r\n      throw new BuildError(\r\n        BuildErrorCode.CONFIG_INVALID,\r\n        `Entry \"${name}\" requires a \"namespace\" field (e.g. \"Contoso.Account\").`,\r\n        { entry: name },\r\n      );\r\n    }\r\n  }\r\n\r\n  // bundler: optional, must be \"esbuild\" if set\r\n  if (config['bundler'] !== undefined && config['bundler'] !== 'esbuild') {\r\n    throw new BuildError(\r\n      BuildErrorCode.CONFIG_INVALID,\r\n      `Unsupported bundler: \"${String(config['bundler'])}\". Currently only \"esbuild\" is supported.`,\r\n      { bundler: config['bundler'] },\r\n    );\r\n  }\r\n\r\n  return config as unknown as BuildConfig;\r\n}\r\n\r\n/**\r\n * Apply default values to a validated build config.\r\n *\r\n * Fills in defaults for optional fields: bundler ('esbuild'), outDir ('./dist'),\r\n * target ('es2020'), sourcemap (true), minify (false), external ([]).\r\n *\r\n * @param config - Validated build configuration\r\n * @returns Fully resolved configuration with all defaults applied\r\n */\r\nexport function resolveBuildConfig(config: BuildConfig): ResolvedBuildConfig {\r\n  return {\r\n    bundler: config.bundler ?? 'esbuild',\r\n    entries: config.entries,\r\n    outDir: config.outDir ?? './dist',\r\n    target: config.target ?? 'es2020',\r\n    sourcemap: config.sourcemap ?? true,\r\n    minify: config.minify ?? false,\r\n    external: config.external ?? [],\r\n  };\r\n}\r\n","/**\r\n * @xrmforge/devkit - esbuild Builder\r\n *\r\n * Builds D365 WebResources as IIFE bundles with named globals.\r\n * Abstracts esbuild so users never write esbuild config.\r\n */\r\n\r\nimport * as esbuild from 'esbuild';\r\nimport { stat, mkdir } from 'node:fs/promises';\r\nimport { resolve, dirname } from 'node:path';\r\nimport type { BuildConfig } from '../config.js';\r\nimport { resolveBuildConfig } from '../config.js';\r\nimport { BuildError, BuildErrorCode } from '../errors.js';\r\nimport type { BuildResult, BuildResultEntry } from './types.js';\r\n\r\n/**\r\n * Build all entries defined in the config as IIFE bundles.\r\n *\r\n * @param config - Validated build configuration\r\n * @param cwd - Working directory for resolving relative paths (defaults to process.cwd())\r\n * @returns Build result with per-entry details\r\n */\r\nexport async function build(config: BuildConfig, cwd?: string): Promise<BuildResult> {\r\n  const startTime = Date.now();\r\n  const resolved = resolveBuildConfig(config);\r\n  const basedir = cwd ?? process.cwd();\r\n  const outDir = resolve(basedir, resolved.outDir);\r\n\r\n  // Ensure output directory exists\r\n  await mkdir(outDir, { recursive: true });\r\n\r\n  const entryNames = Object.keys(resolved.entries);\r\n  const results: BuildResultEntry[] = [];\r\n  const errors: string[] = [];\r\n  const warnings: string[] = [];\r\n\r\n  // Build all entries in parallel\r\n  const settled = await Promise.allSettled(\r\n    entryNames.map(async (name) => {\r\n      const entry = resolved.entries[name]!;\r\n      const entryStart = Date.now();\r\n      const outFile = resolve(outDir, entry.out ?? `${name}.js`);\r\n\r\n      // Ensure subdirectory exists for custom out paths\r\n      await mkdir(dirname(outFile), { recursive: true });\r\n\r\n      const buildOptions: esbuild.BuildOptions = {\r\n        entryPoints: [resolve(basedir, entry.input)],\r\n        bundle: true,\r\n        format: 'iife',\r\n        globalName: entry.namespace,\r\n        outfile: outFile,\r\n        target: [resolved.target],\r\n        minify: resolved.minify,\r\n        sourcemap: resolved.sourcemap,\r\n        treeShaking: true,\r\n        logLevel: 'silent',\r\n        external: resolved.external,\r\n      };\r\n\r\n      const result = await esbuild.build(buildOptions);\r\n\r\n      // Collect esbuild warnings\r\n      for (const w of result.warnings) {\r\n        warnings.push(`[${name}] ${w.text}`);\r\n      }\r\n\r\n      // Get output file size\r\n      const stats = await stat(outFile);\r\n\r\n      return {\r\n        name,\r\n        outFile,\r\n        sizeBytes: stats.size,\r\n        durationMs: Date.now() - entryStart,\r\n      } satisfies BuildResultEntry;\r\n    }),\r\n  );\r\n\r\n  for (let i = 0; i < settled.length; i++) {\r\n    const outcome = settled[i]!;\r\n    const name = entryNames[i]!;\r\n\r\n    if (outcome.status === 'fulfilled') {\r\n      results.push(outcome.value);\r\n    } else {\r\n      const errorMsg = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);\r\n      // Distinguish \"file not found\" from other build errors\r\n      if (errorMsg.includes('Could not resolve') || errorMsg.includes('ENOENT')) {\r\n        errors.push(`[${name}] ${new BuildError(BuildErrorCode.ENTRY_NOT_FOUND, errorMsg, { entry: name }).message}`);\r\n      } else {\r\n        errors.push(`[${name}] ${new BuildError(BuildErrorCode.BUILD_FAILED, errorMsg, { entry: name }).message}`);\r\n      }\r\n    }\r\n  }\r\n\r\n  return {\r\n    entries: results,\r\n    totalDurationMs: Date.now() - startTime,\r\n    errors,\r\n    warnings,\r\n  };\r\n}\r\n\r\n/**\r\n * Start watch mode for all entries.\r\n * Returns a dispose function to stop watching.\r\n *\r\n * @param config - Validated build configuration\r\n * @param options - Watch options\r\n * @returns Object with dispose() to stop watching\r\n */\r\nexport async function watch(\r\n  config: BuildConfig,\r\n  options?: {\r\n    cwd?: string;\r\n    onRebuild?: (result: BuildResult) => void;\r\n  },\r\n): Promise<{ dispose: () => Promise<void> }> {\r\n  const resolved = resolveBuildConfig(config);\r\n  const basedir = options?.cwd ?? process.cwd();\r\n  const outDir = resolve(basedir, resolved.outDir);\r\n\r\n  await mkdir(outDir, { recursive: true });\r\n\r\n  const contexts: esbuild.BuildContext[] = [];\r\n\r\n  for (const [name, entry] of Object.entries(resolved.entries)) {\r\n    const outFile = resolve(outDir, entry.out ?? `${name}.js`);\r\n    await mkdir(dirname(outFile), { recursive: true });\r\n\r\n    const ctx = await esbuild.context({\r\n      entryPoints: [resolve(basedir, entry.input)],\r\n      bundle: true,\r\n      format: 'iife',\r\n      globalName: entry.namespace,\r\n      outfile: outFile,\r\n      target: [resolved.target],\r\n      minify: resolved.minify,\r\n      sourcemap: resolved.sourcemap,\r\n      treeShaking: true,\r\n      logLevel: 'silent',\r\n      external: resolved.external,\r\n    });\r\n\r\n    contexts.push(ctx);\r\n    await ctx.watch();\r\n  }\r\n\r\n  return {\r\n    dispose: async () => {\r\n      for (const ctx of contexts) {\r\n        await ctx.dispose();\r\n      }\r\n    },\r\n  };\r\n}\r\n","/**\r\n * @xrmforge/devkit - Project Scaffolding\r\n *\r\n * Generates a complete D365 form scripting project from templates.\r\n */\r\n\r\nimport { mkdir, writeFile, readdir, access } from 'node:fs/promises';\r\nimport { join } from 'node:path';\r\nimport type { ScaffoldConfig, ScaffoldResult } from './types.js';\r\nimport { BuildError, BuildErrorCode } from '../errors.js';\r\nimport { loadTemplate } from './template-loader.js';\r\n\r\n/**\r\n * Scaffold a new D365 form scripting project.\r\n *\r\n * Creates a complete project structure with package.json, tsconfig,\r\n * xrmforge.config.json, example form script, and test file.\r\n *\r\n * @param config - Scaffold configuration\r\n * @returns List of created files and any warnings\r\n * @throws {BuildError} if target directory is not empty (unless files are only dotfiles)\r\n */\r\nexport async function scaffoldProject(config: ScaffoldConfig): Promise<ScaffoldResult> {\r\n  const { targetDir } = config;\r\n  const filesCreated: string[] = [];\r\n  const warnings: string[] = [];\r\n\r\n  // Ensure target directory exists\r\n  await mkdir(targetDir, { recursive: true });\r\n\r\n  // Check if directory is empty (ignore dotfiles and node_modules)\r\n  const existing = await readdir(targetDir);\r\n  const nonDotFiles = existing.filter((f) => !f.startsWith('.') && f !== 'node_modules');\r\n  if (nonDotFiles.length > 0 && !config.force) {\r\n    throw new BuildError(\r\n      BuildErrorCode.CONFIG_INVALID,\r\n      `Target directory is not empty: ${targetDir}\\n` +\r\n        `Found: ${nonDotFiles.slice(0, 5).join(', ')}${nonDotFiles.length > 5 ? '...' : ''}\\n` +\r\n        `Use --force to scaffold anyway (existing files will be skipped).`,\r\n      { targetDir, existingFiles: nonDotFiles },\r\n    );\r\n  }\r\n\r\n  // Create directory structure\r\n  const dirs = [\r\n    'src/forms',\r\n    'src/shared',\r\n    'generated',\r\n    'tests/forms',\r\n  ];\r\n\r\n  for (const dir of dirs) {\r\n    await mkdir(join(targetDir, dir), { recursive: true });\r\n  }\r\n\r\n  // Generate and write all template files\r\n  const templates = await generateTemplates(config);\r\n\r\n  for (const [relativePath, content] of templates) {\r\n    const absolutePath = join(targetDir, relativePath);\r\n    await mkdir(join(absolutePath, '..'), { recursive: true });\r\n\r\n    // In force mode: skip files that already exist\r\n    if (config.force) {\r\n      try {\r\n        await access(absolutePath);\r\n        warnings.push(`Skipped ${relativePath} (already exists)`);\r\n        continue;\r\n      } catch {\r\n        // File doesn't exist, proceed with write\r\n      }\r\n    }\r\n\r\n    await writeFile(absolutePath, content, 'utf-8');\r\n    filesCreated.push(relativePath);\r\n  }\r\n\r\n  return { filesCreated, warnings };\r\n}\r\n\r\n/**\r\n * Generate all template file contents for a scaffolded project.\r\n *\r\n * @param config - Scaffold configuration with project name, prefix, and namespace\r\n * @returns Array of [relativePath, content] tuples for each file to create\r\n */\r\nasync function generateTemplates(config: ScaffoldConfig): Promise<Array<[string, string]>> {\r\n  const { projectName, prefix, namespace } = config;\r\n  const lowerPrefix = prefix.toLowerCase();\r\n  const namespaceVars = { namespace };\r\n\r\n  return [\r\n    ['package.json', generatePackageJson(projectName)],\r\n    ['tsconfig.json', generateTsConfig()],\r\n    ['xrmforge.config.json', generateXrmForgeConfig(lowerPrefix, namespace)],\r\n    ['vitest.config.ts', await loadTemplate('vitest.config.ts')],\r\n    ['.gitignore', await loadTemplate('gitignore')],\r\n    ['.gitattributes', generateGitAttributes()],\r\n    ['AGENT.md', await loadTemplate('AGENT.md')],\r\n    ['src/forms/example-form.ts', await loadTemplate('example-form.ts', namespaceVars)],\r\n    ['generated/.gitkeep', ''],\r\n    ['tests/forms/example-form.test.ts', await loadTemplate('example-form.test.ts', namespaceVars)],\r\n    ['src/shared/logger.ts', await loadTemplate('logger.ts', namespaceVars)],\r\n    ['src/shared/error-handler.ts', await loadTemplate('error-handler.ts')],\r\n    ['src/shared/constants.ts', await loadTemplate('constants.ts', namespaceVars)],\r\n    ['eslint.config.js', await loadTemplate('eslint.config.js')],\r\n    ['.github/workflows/ci.yml', await loadTemplate('github-actions-ci.yml')],\r\n    ['azure-pipelines.yml', await loadTemplate('azure-pipelines.yml')],\r\n    ['scripts/validate-form.mjs', await loadTemplate('validate-form.mjs')],\r\n  ];\r\n}\r\n\r\n/**\r\n * Generate package.json content for a scaffolded project.\r\n *\r\n * @param projectName - The project name for the name field\r\n * @returns Formatted JSON string\r\n */\r\nfunction generatePackageJson(projectName: string): string {\r\n  const pkg = {\r\n    name: projectName,\r\n    version: '0.1.0',\r\n    private: true,\r\n    type: 'module',\r\n    scripts: {\r\n      generate: 'xrmforge generate',\r\n      typecheck: 'tsc --noEmit',\r\n      build: 'xrmforge build',\r\n      watch: 'xrmforge build --watch',\r\n      test: 'vitest run',\r\n      'test:watch': 'vitest',\r\n      validate: 'node scripts/validate-form.mjs',\r\n    },\r\n    devDependencies: {\r\n      '@types/xrm': '^9.0.90',\r\n      '@typescript-eslint/eslint-plugin': '^8.0.0',\r\n      '@typescript-eslint/parser': '^8.0.0',\r\n      // 0.x caret ranges only allow the same minor: keep these pins on the\r\n      // current minor of each package, otherwise scaffolded projects install\r\n      // outdated versions (e.g. helpers ^0.3.0 never resolves to 0.6.x).\r\n      // cli ^0.8.0: the env-var CI template (XRMFORGE_* without auth flags, since\r\n      // 0.7.0) plus the ./.env auto-load and interactive prompt (0.8.0) need cli at\r\n      // that minor; a 0.x caret never crosses a minor boundary, so an older pin\r\n      // would hand fresh projects a cli without these features.\r\n      // helpers ^0.11.0: on-form setAndSubmit, off-form formLookupIdUnsafe/formLookupUnsafe,\r\n      // getEnvironmentVariable, isUnsavedRecord ship in 0.11.0 (Runde 8: F-LMA8-N1/N2, F-MK8-N4a/b);\r\n      // MultiSelect/submit/app-notification (parseMultiSelect, clearAndSubmit, setUnsafeAndSubmit,\r\n      // addAppNotification) since 0.10.0; void Custom API executors since 0.9.0; isFormType since 0.8.0.\r\n      // testing ^0.6.0: subgrid MockControl.refresh() ships in 0.6.0 (Runde 9: F-MK9-01); online.execute\r\n      // override + OptionSet/view/setFilterXml mock methods since 0.5.0 (Runde 8: F-MK8-04b); complex-form\r\n      // mocks (createFormMock formType, getText/getPrecision, addOnSave/fireOnSave, roles ItemCollection,\r\n      // utilityOverrides) since 0.4.0; tabs since 0.3.0.\r\n      '@xrmforge/cli': '^0.8.0',\r\n      '@xrmforge/eslint-plugin': '^0.3.0',\r\n      '@xrmforge/helpers': '^0.11.0',\r\n      '@xrmforge/testing': '^0.6.0',\r\n      eslint: '^9.0.0',\r\n      typescript: '^5.7.0',\r\n      vitest: '^3.0.0',\r\n    },\r\n  };\r\n  return JSON.stringify(pkg, null, 2) + '\\n';\r\n}\r\n\r\n/**\r\n * Generate .gitattributes content for a scaffolded project.\r\n *\r\n * Pins generated declarations (and source/config) to LF. typegen writes LF,\r\n * but git with core.autocrlf=true (the Windows default) would otherwise check\r\n * the files out as CRLF, and `xrmforge generate --check` would report false\r\n * drift on every file. Forcing eol=lf keeps the drift gate green on Windows.\r\n *\r\n * @returns .gitattributes content\r\n */\r\nfunction generateGitAttributes(): string {\r\n  return [\r\n    '# typegen writes LF. Pin generated files to LF so `xrmforge generate --check`',\r\n    '# stays stable on Windows (git core.autocrlf would otherwise serve CRLF',\r\n    '# working copies and the byte comparison would report false drift).',\r\n    'generated/** text eol=lf',\r\n    '',\r\n    '# Keep source and config line endings consistent across platforms.',\r\n    '*.ts   text eol=lf',\r\n    '*.mjs  text eol=lf',\r\n    '*.json text eol=lf',\r\n    '',\r\n  ].join('\\n');\r\n}\r\n\r\n/**\r\n * Generate tsconfig.json content for a scaffolded project.\r\n *\r\n * @returns Formatted JSON string with D365-appropriate compiler options\r\n */\r\nfunction generateTsConfig(): string {\r\n  const config = {\r\n    compilerOptions: {\r\n      target: 'ES2020',\r\n      module: 'ESNext',\r\n      moduleResolution: 'bundler',\r\n      lib: ['ES2020', 'DOM'],\r\n      types: ['xrm'],\r\n      strict: true,\r\n      noEmit: true,\r\n      skipLibCheck: false,\r\n      esModuleInterop: true,\r\n    },\r\n    include: [\r\n      'src/**/*.ts',\r\n      'generated/**/*.ts',\r\n    ],\r\n  };\r\n  return JSON.stringify(config, null, 2) + '\\n';\r\n}\r\n\r\n/**\r\n * Generate xrmforge.config.json content for a scaffolded project.\r\n *\r\n * @param prefix - Publisher prefix for WebResource paths (lowercase)\r\n * @param namespace - Base namespace for form script globals\r\n * @returns Formatted JSON string with a sample build entry\r\n */\r\nfunction generateXrmForgeConfig(prefix: string, namespace: string): string {\r\n  const config = {\r\n    build: {\r\n      outDir: `./dist/${prefix}_/JS`,\r\n      target: 'es2020',\r\n      sourcemap: true,\r\n      minify: true,\r\n      entries: {\r\n        example_form: {\r\n          input: './src/forms/example-form.ts',\r\n          namespace: `${namespace}.Example`,\r\n          out: 'Example/OnLoad.js',\r\n        },\r\n      },\r\n    },\r\n  };\r\n  return JSON.stringify(config, null, 2) + '\\n';\r\n}\r\n","/**\r\n * Template loader for scaffold templates.\r\n *\r\n * Reads template files from the templates/ directory relative to this module.\r\n * Supports {{placeholder}} variable substitution.\r\n */\r\n\r\nimport { readFile } from 'node:fs/promises';\r\nimport { dirname, join } from 'node:path';\r\nimport { fileURLToPath } from 'node:url';\r\n\r\nconst __dirname = dirname(fileURLToPath(import.meta.url));\r\n\r\n/** Path to the templates directory (relative to compiled output or source). */\r\nconst TEMPLATES_DIR = join(__dirname, 'templates');\r\n\r\n/**\r\n * Load a template file by name and optionally substitute variables.\r\n *\r\n * Variables in the template use the `{{key}}` syntax.\r\n *\r\n * @param name - Template filename (e.g. 'AGENT.md', 'example-form.ts')\r\n * @param vars - Optional key-value pairs for placeholder substitution\r\n * @returns Template content with variables replaced\r\n */\r\nexport async function loadTemplate(\r\n  name: string,\r\n  vars?: Record<string, string>,\r\n): Promise<string> {\r\n  const content = await readFile(join(TEMPLATES_DIR, name), 'utf-8');\r\n\r\n  if (!vars || Object.keys(vars).length === 0) {\r\n    return content;\r\n  }\r\n\r\n  return Object.entries(vars).reduce(\r\n    (result, [key, value]) => result.replaceAll(`{{${key}}}`, value),\r\n    content,\r\n  );\r\n}\r\n"],"mappings":"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","names":["BuildErrorCode","context","build","mkdir","join","dirname","mkdir","join"]}
+{"version":3,"sources":["../src/errors.ts","../src/config.ts","../src/builder/esbuild-builder.ts","../src/scaffold/scaffold.ts","../src/scaffold/template-loader.ts"],"sourcesContent":["/**\r\n * @xrmforge/devkit - Build Error Types\r\n *\r\n * Structured error types for build operations.\r\n */\r\n\r\nexport enum BuildErrorCode {\r\n  /** Build configuration is invalid or missing required fields */\r\n  CONFIG_INVALID = 'BUILD_6001',\r\n  /** Entry point file not found on disk */\r\n  ENTRY_NOT_FOUND = 'BUILD_6002',\r\n  /** esbuild compilation failed (syntax errors, missing imports) */\r\n  BUILD_FAILED = 'BUILD_6003',\r\n  /** Error in watch mode */\r\n  WATCH_ERROR = 'BUILD_6004',\r\n}\r\n\r\n/**\r\n * Structured error class for build operations.\r\n *\r\n * Carries a machine-readable {@link BuildErrorCode} and optional context\r\n * for debugging. The error message is prefixed with the code (e.g. `[BUILD_6001]`).\r\n *\r\n * @example\r\n * ```typescript\r\n * throw new BuildError(\r\n *   BuildErrorCode.ENTRY_NOT_FOUND,\r\n *   'Could not find entry point: ./src/missing.ts',\r\n *   { entry: 'my_script' },\r\n * );\r\n * ```\r\n */\r\nexport class BuildError extends Error {\r\n  /** Machine-readable error code for programmatic handling. */\r\n  public readonly code: BuildErrorCode;\r\n  /** Additional context for debugging (e.g. entry name, file path). */\r\n  public readonly context: Record<string, unknown>;\r\n\r\n  /**\r\n   * @param code - Machine-readable error code\r\n   * @param message - Human-readable error description\r\n   * @param context - Optional key-value pairs for debugging context\r\n   */\r\n  constructor(code: BuildErrorCode, message: string, context: Record<string, unknown> = {}) {\r\n    super(`[${code}] ${message}`);\r\n    this.name = 'BuildError';\r\n    this.code = code;\r\n    this.context = context;\r\n\r\n    if (Error.captureStackTrace) {\r\n      Error.captureStackTrace(this, BuildError);\r\n    }\r\n  }\r\n}\r\n","/**\r\n * @xrmforge/devkit - Build Configuration\r\n *\r\n * Types and validation for the `build` section in xrmforge.config.json.\r\n */\r\n\r\nimport { BuildError, BuildErrorCode } from './errors.js';\r\n\r\n/** A single build entry (one WebResource) */\r\nexport interface BuildEntry {\r\n  /** Relative path to the TypeScript source file */\r\n  input: string;\r\n  /** Global namespace for D365 form event binding (e.g. \"Contoso.Account\") */\r\n  namespace: string;\r\n  /** Optional output filename relative to outDir (defaults to entry key + \".js\") */\r\n  out?: string;\r\n}\r\n\r\n/** Build configuration for WebResource bundling */\r\nexport interface BuildConfig {\r\n  /** Bundler to use (currently only \"esbuild\") */\r\n  bundler?: 'esbuild';\r\n  /** Named build entries: key = entry name, value = entry config */\r\n  entries: Record<string, BuildEntry>;\r\n  /** Output directory for built bundles (default: \"./dist\") */\r\n  outDir?: string;\r\n  /** JavaScript target version (default: \"es2020\") */\r\n  target?: string;\r\n  /** Generate source maps (default: true) */\r\n  sourcemap?: boolean;\r\n  /** Minify output (default: false) */\r\n  minify?: boolean;\r\n  /** Additional modules to exclude from bundling */\r\n  external?: string[];\r\n}\r\n\r\n/** Fully resolved build config with all defaults applied */\r\nexport interface ResolvedBuildConfig {\r\n  bundler: 'esbuild';\r\n  entries: Record<string, BuildEntry>;\r\n  outDir: string;\r\n  target: string;\r\n  sourcemap: boolean;\r\n  minify: boolean;\r\n  external: string[];\r\n}\r\n\r\n/**\r\n * Validate a raw build config object parsed from xrmforge.config.json.\r\n *\r\n * Checks that all required fields (entries, input, namespace) are present\r\n * and have valid types. Throws {@link BuildError} with CONFIG_INVALID if\r\n * any validation check fails.\r\n *\r\n * @param raw - Untyped config object to validate\r\n * @returns The validated build configuration\r\n * @throws {BuildError} If any required field is missing or has an invalid type\r\n */\r\nexport function validateBuildConfig(raw: unknown): BuildConfig {\r\n  if (!raw || typeof raw !== 'object') {\r\n    throw new BuildError(\r\n      BuildErrorCode.CONFIG_INVALID,\r\n      'Build configuration must be an object.',\r\n    );\r\n  }\r\n\r\n  const config = raw as Record<string, unknown>;\r\n\r\n  // entries: required, non-empty object\r\n  if (!config['entries'] || typeof config['entries'] !== 'object' || Array.isArray(config['entries'])) {\r\n    throw new BuildError(\r\n      BuildErrorCode.CONFIG_INVALID,\r\n      'Build configuration requires an \"entries\" object with at least one entry.',\r\n    );\r\n  }\r\n\r\n  const entries = config['entries'] as Record<string, unknown>;\r\n  const entryNames = Object.keys(entries);\r\n\r\n  if (entryNames.length === 0) {\r\n    throw new BuildError(\r\n      BuildErrorCode.CONFIG_INVALID,\r\n      'Build configuration requires at least one entry in \"entries\".',\r\n    );\r\n  }\r\n\r\n  for (const name of entryNames) {\r\n    const entry = entries[name] as Record<string, unknown> | undefined;\r\n\r\n    if (!entry || typeof entry !== 'object') {\r\n      throw new BuildError(\r\n        BuildErrorCode.CONFIG_INVALID,\r\n        `Entry \"${name}\" must be an object with \"input\" and \"namespace\".`,\r\n        { entry: name },\r\n      );\r\n    }\r\n\r\n    if (!entry['input'] || typeof entry['input'] !== 'string') {\r\n      throw new BuildError(\r\n        BuildErrorCode.CONFIG_INVALID,\r\n        `Entry \"${name}\" requires an \"input\" field (path to .ts source file).`,\r\n        { entry: name },\r\n      );\r\n    }\r\n\r\n    if (!entry['namespace'] || typeof entry['namespace'] !== 'string') {\r\n      throw new BuildError(\r\n        BuildErrorCode.CONFIG_INVALID,\r\n        `Entry \"${name}\" requires a \"namespace\" field (e.g. \"Contoso.Account\").`,\r\n        { entry: name },\r\n      );\r\n    }\r\n  }\r\n\r\n  // bundler: optional, must be \"esbuild\" if set\r\n  if (config['bundler'] !== undefined && config['bundler'] !== 'esbuild') {\r\n    throw new BuildError(\r\n      BuildErrorCode.CONFIG_INVALID,\r\n      `Unsupported bundler: \"${String(config['bundler'])}\". Currently only \"esbuild\" is supported.`,\r\n      { bundler: config['bundler'] },\r\n    );\r\n  }\r\n\r\n  return config as unknown as BuildConfig;\r\n}\r\n\r\n/**\r\n * Apply default values to a validated build config.\r\n *\r\n * Fills in defaults for optional fields: bundler ('esbuild'), outDir ('./dist'),\r\n * target ('es2020'), sourcemap (true), minify (false), external ([]).\r\n *\r\n * @param config - Validated build configuration\r\n * @returns Fully resolved configuration with all defaults applied\r\n */\r\nexport function resolveBuildConfig(config: BuildConfig): ResolvedBuildConfig {\r\n  return {\r\n    bundler: config.bundler ?? 'esbuild',\r\n    entries: config.entries,\r\n    outDir: config.outDir ?? './dist',\r\n    target: config.target ?? 'es2020',\r\n    sourcemap: config.sourcemap ?? true,\r\n    minify: config.minify ?? false,\r\n    external: config.external ?? [],\r\n  };\r\n}\r\n","/**\r\n * @xrmforge/devkit - esbuild Builder\r\n *\r\n * Builds D365 WebResources as IIFE bundles with named globals.\r\n * Abstracts esbuild so users never write esbuild config.\r\n */\r\n\r\nimport * as esbuild from 'esbuild';\r\nimport { stat, mkdir } from 'node:fs/promises';\r\nimport { resolve, dirname } from 'node:path';\r\nimport type { BuildConfig } from '../config.js';\r\nimport { resolveBuildConfig } from '../config.js';\r\nimport { BuildError, BuildErrorCode } from '../errors.js';\r\nimport type { BuildResult, BuildResultEntry } from './types.js';\r\n\r\n/**\r\n * Build all entries defined in the config as IIFE bundles.\r\n *\r\n * @param config - Validated build configuration\r\n * @param cwd - Working directory for resolving relative paths (defaults to process.cwd())\r\n * @returns Build result with per-entry details\r\n */\r\nexport async function build(config: BuildConfig, cwd?: string): Promise<BuildResult> {\r\n  const startTime = Date.now();\r\n  const resolved = resolveBuildConfig(config);\r\n  const basedir = cwd ?? process.cwd();\r\n  const outDir = resolve(basedir, resolved.outDir);\r\n\r\n  // Ensure output directory exists\r\n  await mkdir(outDir, { recursive: true });\r\n\r\n  const entryNames = Object.keys(resolved.entries);\r\n  const results: BuildResultEntry[] = [];\r\n  const errors: string[] = [];\r\n  const warnings: string[] = [];\r\n\r\n  // Build all entries in parallel\r\n  const settled = await Promise.allSettled(\r\n    entryNames.map(async (name) => {\r\n      const entry = resolved.entries[name]!;\r\n      const entryStart = Date.now();\r\n      const outFile = resolve(outDir, entry.out ?? `${name}.js`);\r\n\r\n      // Ensure subdirectory exists for custom out paths\r\n      await mkdir(dirname(outFile), { recursive: true });\r\n\r\n      const buildOptions: esbuild.BuildOptions = {\r\n        entryPoints: [resolve(basedir, entry.input)],\r\n        bundle: true,\r\n        format: 'iife',\r\n        globalName: entry.namespace,\r\n        outfile: outFile,\r\n        target: [resolved.target],\r\n        minify: resolved.minify,\r\n        sourcemap: resolved.sourcemap,\r\n        treeShaking: true,\r\n        logLevel: 'silent',\r\n        external: resolved.external,\r\n      };\r\n\r\n      const result = await esbuild.build(buildOptions);\r\n\r\n      // Collect esbuild warnings\r\n      for (const w of result.warnings) {\r\n        warnings.push(`[${name}] ${w.text}`);\r\n      }\r\n\r\n      // Get output file size\r\n      const stats = await stat(outFile);\r\n\r\n      return {\r\n        name,\r\n        outFile,\r\n        sizeBytes: stats.size,\r\n        durationMs: Date.now() - entryStart,\r\n      } satisfies BuildResultEntry;\r\n    }),\r\n  );\r\n\r\n  for (let i = 0; i < settled.length; i++) {\r\n    const outcome = settled[i]!;\r\n    const name = entryNames[i]!;\r\n\r\n    if (outcome.status === 'fulfilled') {\r\n      results.push(outcome.value);\r\n    } else {\r\n      const errorMsg = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);\r\n      // Distinguish \"file not found\" from other build errors\r\n      if (errorMsg.includes('Could not resolve') || errorMsg.includes('ENOENT')) {\r\n        errors.push(`[${name}] ${new BuildError(BuildErrorCode.ENTRY_NOT_FOUND, errorMsg, { entry: name }).message}`);\r\n      } else {\r\n        errors.push(`[${name}] ${new BuildError(BuildErrorCode.BUILD_FAILED, errorMsg, { entry: name }).message}`);\r\n      }\r\n    }\r\n  }\r\n\r\n  return {\r\n    entries: results,\r\n    totalDurationMs: Date.now() - startTime,\r\n    errors,\r\n    warnings,\r\n  };\r\n}\r\n\r\n/**\r\n * Start watch mode for all entries.\r\n * Returns a dispose function to stop watching.\r\n *\r\n * @param config - Validated build configuration\r\n * @param options - Watch options\r\n * @returns Object with dispose() to stop watching\r\n */\r\nexport async function watch(\r\n  config: BuildConfig,\r\n  options?: {\r\n    cwd?: string;\r\n    onRebuild?: (result: BuildResult) => void;\r\n  },\r\n): Promise<{ dispose: () => Promise<void> }> {\r\n  const resolved = resolveBuildConfig(config);\r\n  const basedir = options?.cwd ?? process.cwd();\r\n  const outDir = resolve(basedir, resolved.outDir);\r\n\r\n  await mkdir(outDir, { recursive: true });\r\n\r\n  const contexts: esbuild.BuildContext[] = [];\r\n\r\n  for (const [name, entry] of Object.entries(resolved.entries)) {\r\n    const outFile = resolve(outDir, entry.out ?? `${name}.js`);\r\n    await mkdir(dirname(outFile), { recursive: true });\r\n\r\n    const ctx = await esbuild.context({\r\n      entryPoints: [resolve(basedir, entry.input)],\r\n      bundle: true,\r\n      format: 'iife',\r\n      globalName: entry.namespace,\r\n      outfile: outFile,\r\n      target: [resolved.target],\r\n      minify: resolved.minify,\r\n      sourcemap: resolved.sourcemap,\r\n      treeShaking: true,\r\n      logLevel: 'silent',\r\n      external: resolved.external,\r\n    });\r\n\r\n    contexts.push(ctx);\r\n    await ctx.watch();\r\n  }\r\n\r\n  return {\r\n    dispose: async () => {\r\n      for (const ctx of contexts) {\r\n        await ctx.dispose();\r\n      }\r\n    },\r\n  };\r\n}\r\n","/**\r\n * @xrmforge/devkit - Project Scaffolding\r\n *\r\n * Generates a complete D365 form scripting project from templates.\r\n */\r\n\r\nimport { mkdir, writeFile, readdir, access } from 'node:fs/promises';\r\nimport { join } from 'node:path';\r\nimport type { ScaffoldConfig, ScaffoldResult } from './types.js';\r\nimport { BuildError, BuildErrorCode } from '../errors.js';\r\nimport { loadTemplate } from './template-loader.js';\r\n\r\n/**\r\n * Scaffold a new D365 form scripting project.\r\n *\r\n * Creates a complete project structure with package.json, tsconfig,\r\n * xrmforge.config.json, example form script, and test file.\r\n *\r\n * @param config - Scaffold configuration\r\n * @returns List of created files and any warnings\r\n * @throws {BuildError} if target directory is not empty (unless files are only dotfiles)\r\n */\r\nexport async function scaffoldProject(config: ScaffoldConfig): Promise<ScaffoldResult> {\r\n  const { targetDir } = config;\r\n  const filesCreated: string[] = [];\r\n  const warnings: string[] = [];\r\n\r\n  // Ensure target directory exists\r\n  await mkdir(targetDir, { recursive: true });\r\n\r\n  // Check if directory is empty (ignore dotfiles and node_modules)\r\n  const existing = await readdir(targetDir);\r\n  const nonDotFiles = existing.filter((f) => !f.startsWith('.') && f !== 'node_modules');\r\n  if (nonDotFiles.length > 0 && !config.force) {\r\n    throw new BuildError(\r\n      BuildErrorCode.CONFIG_INVALID,\r\n      `Target directory is not empty: ${targetDir}\\n` +\r\n        `Found: ${nonDotFiles.slice(0, 5).join(', ')}${nonDotFiles.length > 5 ? '...' : ''}\\n` +\r\n        `Use --force to scaffold anyway (existing files will be skipped).`,\r\n      { targetDir, existingFiles: nonDotFiles },\r\n    );\r\n  }\r\n\r\n  // Create directory structure\r\n  const dirs = [\r\n    'src/forms',\r\n    'src/shared',\r\n    'generated',\r\n    'tests/forms',\r\n  ];\r\n\r\n  for (const dir of dirs) {\r\n    await mkdir(join(targetDir, dir), { recursive: true });\r\n  }\r\n\r\n  // Generate and write all template files\r\n  const templates = await generateTemplates(config);\r\n\r\n  for (const [relativePath, content] of templates) {\r\n    const absolutePath = join(targetDir, relativePath);\r\n    await mkdir(join(absolutePath, '..'), { recursive: true });\r\n\r\n    // In force mode: skip files that already exist\r\n    if (config.force) {\r\n      try {\r\n        await access(absolutePath);\r\n        warnings.push(`Skipped ${relativePath} (already exists)`);\r\n        continue;\r\n      } catch {\r\n        // File doesn't exist, proceed with write\r\n      }\r\n    }\r\n\r\n    await writeFile(absolutePath, content, 'utf-8');\r\n    filesCreated.push(relativePath);\r\n  }\r\n\r\n  return { filesCreated, warnings };\r\n}\r\n\r\n/**\r\n * Generate all template file contents for a scaffolded project.\r\n *\r\n * @param config - Scaffold configuration with project name, prefix, and namespace\r\n * @returns Array of [relativePath, content] tuples for each file to create\r\n */\r\nasync function generateTemplates(config: ScaffoldConfig): Promise<Array<[string, string]>> {\r\n  const { projectName, prefix, namespace } = config;\r\n  const lowerPrefix = prefix.toLowerCase();\r\n  const namespaceVars = { namespace };\r\n\r\n  return [\r\n    ['package.json', generatePackageJson(projectName)],\r\n    ['tsconfig.json', generateTsConfig()],\r\n    ['xrmforge.config.json', generateXrmForgeConfig(lowerPrefix, namespace)],\r\n    ['vitest.config.ts', await loadTemplate('vitest.config.ts')],\r\n    ['.gitignore', await loadTemplate('gitignore')],\r\n    ['.gitattributes', generateGitAttributes()],\r\n    ['AGENT.md', await loadTemplate('AGENT.md')],\r\n    ['src/forms/example-form.ts', await loadTemplate('example-form.ts', namespaceVars)],\r\n    ['generated/.gitkeep', ''],\r\n    ['tests/forms/example-form.test.ts', await loadTemplate('example-form.test.ts', namespaceVars)],\r\n    ['src/shared/logger.ts', await loadTemplate('logger.ts', namespaceVars)],\r\n    ['src/shared/error-handler.ts', await loadTemplate('error-handler.ts')],\r\n    ['src/shared/constants.ts', await loadTemplate('constants.ts', namespaceVars)],\r\n    ['eslint.config.js', await loadTemplate('eslint.config.js')],\r\n    ['.github/workflows/ci.yml', await loadTemplate('github-actions-ci.yml')],\r\n    ['azure-pipelines.yml', await loadTemplate('azure-pipelines.yml')],\r\n    ['scripts/validate-form.mjs', await loadTemplate('validate-form.mjs')],\r\n  ];\r\n}\r\n\r\n/**\r\n * Generate package.json content for a scaffolded project.\r\n *\r\n * @param projectName - The project name for the name field\r\n * @returns Formatted JSON string\r\n */\r\nfunction generatePackageJson(projectName: string): string {\r\n  const pkg = {\r\n    name: projectName,\r\n    version: '0.1.0',\r\n    private: true,\r\n    type: 'module',\r\n    scripts: {\r\n      generate: 'xrmforge generate',\r\n      typecheck: 'tsc --noEmit',\r\n      build: 'xrmforge build',\r\n      watch: 'xrmforge build --watch',\r\n      test: 'vitest run',\r\n      'test:watch': 'vitest',\r\n      validate: 'node scripts/validate-form.mjs',\r\n    },\r\n    devDependencies: {\r\n      '@types/xrm': '^9.0.90',\r\n      '@typescript-eslint/eslint-plugin': '^8.0.0',\r\n      '@typescript-eslint/parser': '^8.0.0',\r\n      // 0.x caret ranges only allow the same minor: keep these pins on the\r\n      // current minor of each package, otherwise scaffolded projects install\r\n      // outdated versions (e.g. helpers ^0.3.0 never resolves to 0.6.x).\r\n      // cli ^0.8.0: the env-var CI template (XRMFORGE_* without auth flags, since\r\n      // 0.7.0) plus the ./.env auto-load and interactive prompt (0.8.0) need cli at\r\n      // that minor; a 0.x caret never crosses a minor boundary, so an older pin\r\n      // would hand fresh projects a cli without these features.\r\n      // helpers ^0.12.0: addAppNotification autoHideMs (self-clearing transient banners) ships in 0.12.0\r\n      // (Runde 9 F-MK9-10); on-form setAndSubmit, off-form formLookupIdUnsafe/formLookupUnsafe,\r\n      // getEnvironmentVariable, isUnsavedRecord since 0.11.0 (Runde 8: F-LMA8-N1/N2, F-MK8-N4a/b);\r\n      // MultiSelect/submit/app-notification (parseMultiSelect, clearAndSubmit, setUnsafeAndSubmit,\r\n      // addAppNotification) since 0.10.0; void Custom API executors since 0.9.0; isFormType since 0.8.0.\r\n      // testing ^0.6.0: subgrid MockControl.refresh() ships in 0.6.0 (Runde 9: F-MK9-01); online.execute\r\n      // override + OptionSet/view/setFilterXml mock methods since 0.5.0 (Runde 8: F-MK8-04b); complex-form\r\n      // mocks (createFormMock formType, getText/getPrecision, addOnSave/fireOnSave, roles ItemCollection,\r\n      // utilityOverrides) since 0.4.0; tabs since 0.3.0.\r\n      '@xrmforge/cli': '^0.8.0',\r\n      '@xrmforge/eslint-plugin': '^0.3.0',\r\n      '@xrmforge/helpers': '^0.12.0',\r\n      '@xrmforge/testing': '^0.6.0',\r\n      eslint: '^9.0.0',\r\n      typescript: '^5.7.0',\r\n      vitest: '^3.0.0',\r\n    },\r\n  };\r\n  return JSON.stringify(pkg, null, 2) + '\\n';\r\n}\r\n\r\n/**\r\n * Generate .gitattributes content for a scaffolded project.\r\n *\r\n * Pins generated declarations (and source/config) to LF. typegen writes LF,\r\n * but git with core.autocrlf=true (the Windows default) would otherwise check\r\n * the files out as CRLF, and `xrmforge generate --check` would report false\r\n * drift on every file. Forcing eol=lf keeps the drift gate green on Windows.\r\n *\r\n * @returns .gitattributes content\r\n */\r\nfunction generateGitAttributes(): string {\r\n  return [\r\n    '# typegen writes LF. Pin generated files to LF so `xrmforge generate --check`',\r\n    '# stays stable on Windows (git core.autocrlf would otherwise serve CRLF',\r\n    '# working copies and the byte comparison would report false drift).',\r\n    'generated/** text eol=lf',\r\n    '',\r\n    '# Keep source and config line endings consistent across platforms.',\r\n    '*.ts   text eol=lf',\r\n    '*.mjs  text eol=lf',\r\n    '*.json text eol=lf',\r\n    '',\r\n  ].join('\\n');\r\n}\r\n\r\n/**\r\n * Generate tsconfig.json content for a scaffolded project.\r\n *\r\n * @returns Formatted JSON string with D365-appropriate compiler options\r\n */\r\nfunction generateTsConfig(): string {\r\n  const config = {\r\n    compilerOptions: {\r\n      target: 'ES2020',\r\n      module: 'ESNext',\r\n      moduleResolution: 'bundler',\r\n      lib: ['ES2020', 'DOM'],\r\n      types: ['xrm'],\r\n      strict: true,\r\n      noEmit: true,\r\n      skipLibCheck: false,\r\n      esModuleInterop: true,\r\n    },\r\n    include: [\r\n      'src/**/*.ts',\r\n      'generated/**/*.ts',\r\n    ],\r\n  };\r\n  return JSON.stringify(config, null, 2) + '\\n';\r\n}\r\n\r\n/**\r\n * Generate xrmforge.config.json content for a scaffolded project.\r\n *\r\n * @param prefix - Publisher prefix for WebResource paths (lowercase)\r\n * @param namespace - Base namespace for form script globals\r\n * @returns Formatted JSON string with a sample build entry\r\n */\r\nfunction generateXrmForgeConfig(prefix: string, namespace: string): string {\r\n  const config = {\r\n    build: {\r\n      outDir: `./dist/${prefix}_/JS`,\r\n      target: 'es2020',\r\n      sourcemap: true,\r\n      minify: true,\r\n      entries: {\r\n        example_form: {\r\n          input: './src/forms/example-form.ts',\r\n          namespace: `${namespace}.Example`,\r\n          out: 'Example/OnLoad.js',\r\n        },\r\n      },\r\n    },\r\n  };\r\n  return JSON.stringify(config, null, 2) + '\\n';\r\n}\r\n","/**\r\n * Template loader for scaffold templates.\r\n *\r\n * Reads template files from the templates/ directory relative to this module.\r\n * Supports {{placeholder}} variable substitution.\r\n */\r\n\r\nimport { readFile } from 'node:fs/promises';\r\nimport { dirname, join } from 'node:path';\r\nimport { fileURLToPath } from 'node:url';\r\n\r\nconst __dirname = dirname(fileURLToPath(import.meta.url));\r\n\r\n/** Path to the templates directory (relative to compiled output or source). */\r\nconst TEMPLATES_DIR = join(__dirname, 'templates');\r\n\r\n/**\r\n * Load a template file by name and optionally substitute variables.\r\n *\r\n * Variables in the template use the `{{key}}` syntax.\r\n *\r\n * @param name - Template filename (e.g. 'AGENT.md', 'example-form.ts')\r\n * @param vars - Optional key-value pairs for placeholder substitution\r\n * @returns Template content with variables replaced\r\n */\r\nexport async function loadTemplate(\r\n  name: string,\r\n  vars?: Record<string, string>,\r\n): Promise<string> {\r\n  const content = await readFile(join(TEMPLATES_DIR, name), 'utf-8');\r\n\r\n  if (!vars || Object.keys(vars).length === 0) {\r\n    return content;\r\n  }\r\n\r\n  return Object.entries(vars).reduce(\r\n    (result, [key, value]) => result.replaceAll(`{{${key}}}`, value),\r\n    content,\r\n  );\r\n}\r\n"],"mappings":"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","names":["BuildErrorCode","context","build","mkdir","join","dirname","mkdir","join"]}

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.
@@ -466,7 +473,7 @@ Xrm.Navigation.openForm({ entityName: EntityNames.Account, entityId: id });  //
 - Never `eval()`, never synchronous XMLHttpRequest
 - Never hand-write `fetch`/`XMLHttpRequest` for Power Automate cloud-flow HTTP-trigger calls (use `callCloudFlow(flowUrl, body)` from `@xrmforge/helpers`)
 - Never check `.ok`/`.status` or call `.json()` on a Custom API executor result (`execute()` throws on failure; a void action returns nothing, so `if (!resp.ok)` crashes at runtime with `response.json is not a function`)
-- Never hand-build a MultiSelect parser, a set-and-submit (on-form `setAndSubmit`, off-form `setUnsafeAndSubmit`, clear `clearAndSubmit`), an off-form lookup-id read (`formLookupIdUnsafe`/`formLookupUnsafe`), an app-notification-level cast (`addAppNotification`/`AppNotificationLevel`), an environment-variable read (`getEnvironmentVariable`), or an unsaved-record check (`isUnsavedRecord`, handles "" AND null GUID) - all from `@xrmforge/helpers`
+- Never hand-build a MultiSelect parser, a set-and-submit (on-form `setAndSubmit`, off-form `setUnsafeAndSubmit`, clear `clearAndSubmit`), an off-form lookup-id read (`formLookupIdUnsafe`/`formLookupUnsafe`), an app notification or self-clearing banner (`addAppNotification`, incl. `{ autoHideMs }`; `AppNotificationLevel`), an environment-variable read (`getEnvironmentVariable`), or an unsaved-record check (`isUnsavedRecord`, handles "" AND null GUID) - all from `@xrmforge/helpers`
 - Never `getAttribute`/`getControl` with a `XxxFields` lookup value (it is `_value`-form and resolves to `null`); use the form-level `XxxFormFieldsEnum` or `XxxNavigationProperties` (blank). For a runtime/variable control name use the raw `ctx.getFormContext().getControl(name)` (typed `$context` has no string overload)
 - Never `window.X = ...` (use module exports)
 - Never `console.log/warn/error` in form scripts (use shared logger)
@@ -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.31",
   "description": "Build orchestration and project tooling for Dynamics 365 WebResources",
   "keywords": [
     "dynamics-365",