npm - @khester/create-dynamics-app - Versions diffs - 1.1.0 → 2.1.0 - Mend

@khester/create-dynamics-app 1.1.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (210) hide show

package/templates/dynamics-365-starter/docs/troubleshooting/platform-specific-issues.md DELETED Viewed

@@ -1,878 +0,0 @@
-# Platform-Specific Troubleshooting Guide
-## Overview
-This guide provides solutions for common issues encountered when developing Dynamics 365
-applications in mixed Windows/Mac environments. It's organized by platform and includes
-cross-platform compatibility troubleshooting.
-## Table of Contents
-1. [Windows-Specific Issues](#windows-specific-issues)
-2. [Mac-Specific Issues](#mac-specific-issues)
-3. [Cross-Platform Compatibility Issues](#cross-platform-compatibility-issues)
-4. [Deployment Issues](#deployment-issues)
-5. [Development Environment Issues](#development-environment-issues)
-6. [CI/CD Pipeline Issues](#cicd-pipeline-issues)
-7. [Quick Reference](#quick-reference)
-## Windows-Specific Issues
-### 🖥️ PowerShell Issues
-#### Issue: PowerShell Execution Policy Prevents Script Running
-**Error:**
-```powershell
-.\deploy.ps1 : File cannot be loaded because running scripts is disabled on this system.
-```
-**Solution:**
-```powershell
-# Check current execution policy
-Get-ExecutionPolicy
-# Set execution policy for current user
-Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
-# Alternative: Bypass for single session
-Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
-# Verify change
-Get-ExecutionPolicy -List
-```
-**Prevention:** Add to team onboarding checklist and PowerShell profile:
-```powershell
-# Add to $PROFILE
-if ((Get-ExecutionPolicy) -eq 'Restricted') {
-    Write-Warning "PowerShell execution policy is restricted. Run: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser"
-}
-```
-#### Issue: PowerShell Module Not Found
-**Error:**
-```powershell
-Import-Module : The specified module 'Microsoft.PowerApps.PowerShell' was not loaded because no valid module file was found.
-```
-**Solution:**
-```powershell
-# Install required modules (run as Administrator)
-Install-Module -Name Microsoft.PowerApps.Administration.PowerShell -Force -AllowClobber
-Install-Module -Name Microsoft.PowerApps.PowerShell -Force -AllowClobber
-# For current user only (no admin required)
-Install-Module -Name Microsoft.PowerApps.PowerShell -Scope CurrentUser -Force
-# Verify installation
-Get-Module -Name Microsoft.PowerApps* -ListAvailable
-# Import manually if needed
-Import-Module Microsoft.PowerApps.PowerShell -Force
-```
-**Prevention:**
-```powershell
-# Add to deployment scripts
-if (-not (Get-Module -Name Microsoft.PowerApps.PowerShell -ListAvailable)) {
-    Write-Host "Installing required PowerShell modules..." -ForegroundColor Yellow
-    Install-Module -Name Microsoft.PowerApps.PowerShell -Scope CurrentUser -Force
-}
-```
-#### Issue: PowerShell Version Compatibility
-**Error:**
-```powershell
-The term 'ConvertTo-Json' is not recognized as the name of a cmdlet
-```
-**Solution:**
-```powershell
-# Check PowerShell version
-$PSVersionTable
-# Update to PowerShell 7+ (recommended)
-winget install Microsoft.PowerShell
-# Alternative: Use Windows PowerShell 5.1 compatible syntax
-if ($PSVersionTable.PSVersion.Major -lt 6) {
-    # Use .NET methods for JSON
-    [System.Web.Script.Serialization.JavaScriptSerializer]::new().Serialize($object)
-} else {
-    # Use modern PowerShell
-    $object | ConvertTo-Json
-}
-```
-### 🔧 Windows Environment Issues
-#### Issue: Node.js Path Issues
-**Error:**
-```cmd
-'node' is not recognized as an internal or external command
-```
-**Solution:**
-```powershell
-# Check if Node.js is installed
-node --version
-# If not found, check PATH
-$env:PATH -split ';' | Where-Object { $_ -like '*node*' }
-# Install Node.js
-choco install nodejs
-# Or using winget
-winget install OpenJS.NodeJS
-# Refresh environment variables
-refreshenv
-# Verify installation
-node --version
-npm --version
-```
-#### Issue: npm Permission Errors
-**Error:**
-```cmd
-npm ERR! Error: EPERM: operation not permitted, mkdir 'C:\Users\...\AppData\Roaming\npm'
-```
-**Solution:**
-```powershell
-# Run as Administrator (temporary fix)
-Start-Process powershell -Verb runAs
-# Better solution: Configure npm for current user
-npm config set prefix $env:USERPROFILE\npm-global
-npm config set cache $env:USERPROFILE\.npm-cache
-# Add to PATH
-$npmPath = "$env:USERPROFILE\npm-global"
-if ($env:PATH -notlike "*$npmPath*") {
-    [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$npmPath", "User")
-}
-```
-#### Issue: Git Line Ending Problems
-**Error:**
-```
-warning: LF will be replaced by CRLF in package.json
-```
-**Solution:**
-```powershell
-# Configure Git for Windows line endings
-git config --global core.autocrlf true
-git config --global core.eol crlf
-# For cross-platform teams (recommended)
-git config --global core.autocrlf input
-git config --global core.eol lf
-# Add .gitattributes file to project root
-echo "* text=auto eol=lf" | Out-File -FilePath .gitattributes -Encoding utf8
-# Refresh repository
-git rm --cached -r .
-git reset --hard
-```
-### 🔒 Windows Security Issues
-#### Issue: Windows Defender Blocking Execution
-**Error:**
-```
-Windows Defender SmartScreen prevented an unrecognized app from starting
-```
-**Solution:**
-```powershell
-# Add project folder to Windows Defender exclusions
-Add-MpPreference -ExclusionPath "C:\path\to\your\project"
-# Or add via Windows Security app:
-# Windows Security > Virus & threat protection > Exclusions > Add exclusion
-# For development tools
-Add-MpPreference -ExclusionPath $env:USERPROFILE\.npm
-Add-MpPreference -ExclusionPath $env:USERPROFILE\node_modules
-```
-## Mac-Specific Issues
-### 🍎 Terminal and Shell Issues
-#### Issue: Command Not Found
-**Error:**
-```bash
-bash: node: command not found
-```
-**Solution:**
-```bash
-# Check if Node.js is installed
-which node
-# Install using Homebrew
-brew install node
-# Install Homebrew if not available
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-# Add Homebrew to PATH (for Apple Silicon Macs)
-echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
-source ~/.zshrc
-# Verify installation
-node --version
-npm --version
-```
-#### Issue: Shell Script Not Executable
-**Error:**
-```bash
-bash: ./deploy.sh: Permission denied
-```
-**Solution:**
-```bash
-# Make script executable
-chmod +x deployment/scripts/deploy.sh
-# Make all scripts executable
-find deployment/scripts -name "*.sh" -exec chmod +x {} \;
-# Check permissions
-ls -la deployment/scripts/
-# Add to Git to preserve permissions
-git update-index --chmod=+x deployment/scripts/deploy.sh
-git commit -m "fix: make deployment scripts executable"
-```
-#### Issue: Zsh vs Bash Compatibility
-**Error:**
-```bash
-zsh: bad pattern: *.json
-```
-**Solution:**
-```bash
-# Check current shell
-echo $SHELL
-# For Zsh compatibility in scripts
-#!/bin/zsh
-setopt BASH_REMATCH
-setopt KSH_GLOB
-# Or force Bash in script
-#!/bin/bash
-# Configure Zsh for better Bash compatibility
-echo 'setopt BASH_REMATCH' >> ~/.zshrc
-echo 'setopt KSH_GLOB' >> ~/.zshrc
-source ~/.zshrc
-```
-### 🔧 Mac System Issues
-#### Issue: Xcode Command Line Tools Missing
-**Error:**
-```bash
-xcrun: error: invalid active developer path
-```
-**Solution:**
-```bash
-# Install Xcode Command Line Tools
-xcode-select --install
-# Reset if already installed but broken
-sudo xcode-select --reset
-sudo xcode-select --install
-# Verify installation
-xcode-select -p
-gcc --version
-```
-#### Issue: MacOS Catalina+ Security Restrictions
-**Error:**
-```bash
-"deploy.sh" cannot be opened because the developer cannot be verified
-```
-**Solution:**
-```bash
-# Remove quarantine attribute
-xattr -dr com.apple.quarantine deployment/scripts/deploy.sh
-# Or for entire project
-find . -name "*.sh" -exec xattr -dr com.apple.quarantine {} \;
-# Allow in System Preferences
-# System Preferences > Security & Privacy > General > Allow anyway
-# Alternative: Use spctl
-sudo spctl --master-disable  # Disable Gatekeeper (not recommended)
-sudo spctl --master-enable   # Re-enable when done
-```
-#### Issue: Homebrew Path Issues
-**Error:**
-```bash
-brew: command not found
-```
-**Solution:**
-```bash
-# For Intel Macs
-echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
-# For Apple Silicon Macs
-echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
-# Reload shell configuration
-source ~/.zshrc
-# Alternative: Add Homebrew to path manually
-eval "$(/opt/homebrew/bin/brew shellenv)"  # Apple Silicon
-eval "$(/usr/local/bin/brew shellenv)"     # Intel
-# Verify Homebrew is working
-brew --version
-brew doctor
-```
-### 🔒 Mac Security Issues
-#### Issue: Gatekeeper Blocking Scripts
-**Error:**
-```bash
-"script.sh" is damaged and can't be opened
-```
-**Solution:**
-```bash
-# Remove quarantine for specific file
-xattr -d com.apple.quarantine script.sh
-# Remove quarantine for project directory
-find . -type f -exec xattr -d com.apple.quarantine {} \; 2>/dev/null
-# Check quarantine status
-xattr -l script.sh
-# Whitelist script
-sudo spctl --add script.sh
-```
-## Cross-Platform Compatibility Issues
-### 🌍 File Path Issues
-#### Issue: Hardcoded Path Separators
-**Problem:**
-```typescript
-// This breaks on different platforms
-const configPath = 'config\\environments\\dev.json'; // Windows only
-const configPath = 'config/environments/dev.json'; // Unix only
-```
-**Solution:**
-```typescript
-import path from 'path';
-// Cross-platform compatible
-const configPath = path.join('config', 'environments', 'dev.json');
-// For dynamic paths
-const buildPath = path.resolve(process.cwd(), 'dist', 'build');
-// For URLs (always forward slashes)
-const apiPath = ['api', 'v1', 'users'].join('/');
-```
-#### Issue: Case Sensitivity Differences
-**Problem:**
-```typescript
-// This might work on Windows but fail on Mac/Linux
-import Component from './MyComponent'; // File: mycomponent.tsx
-```
-**Solution:**
-```typescript
-// Always match exact case
-import Component from './mycomponent'; // Correct case
-// Use consistent naming convention
-// PascalCase for components: MyComponent.tsx
-// camelCase for utilities: myUtility.ts
-// kebab-case for assets: my-image.png
-```
-### 🔄 Environment Variable Issues
-#### Issue: Different Environment Variable Syntax
-**Problem:**
-```bash
-# Windows
-echo %NODE_ENV%
-# Mac/Linux
-echo $NODE_ENV
-```
-**Solution:**
-```javascript
-// Use Node.js process.env (works everywhere)
-const environment = process.env.NODE_ENV || 'development';
-// For scripts, detect platform
-const isWindows = process.platform === 'win32';
-const envVar = isWindows ? '%NODE_ENV%' : '$NODE_ENV';
-```
-#### Issue: Line Ending Inconsistencies
-**Problem:**
-```
-Files created on Windows have CRLF (\r\n)
-Files created on Mac/Linux have LF (\n)
-```
-**Solution:**
-```bash
-# Add .gitattributes to project root
-echo "* text=auto eol=lf" > .gitattributes
-echo "*.sh text eol=lf" >> .gitattributes
-echo "*.ps1 text eol=crlf" >> .gitattributes
-# Configure Git globally
-git config --global core.autocrlf input   # Mac/Linux
-git config --global core.autocrlf true    # Windows
-# Fix existing files
-git add --renormalize .
-git commit -m "fix: normalize line endings"
-```
-## Deployment Issues
-### 🚀 Platform-Specific Deployment Problems
-#### Issue: PowerShell Script Fails on Mac
-**Error:**
-```bash
-./deploy.ps1: line 1: param: command not found
-```
-**Solution:**
-```bash
-# Use the correct script for your platform
-./deployment/scripts/deploy.sh dev          # Mac/Linux
-.\deployment\scripts\deploy.ps1 -Environment dev  # Windows
-# Or use platform-agnostic npm script
-npm run deploy:dev
-```
-#### Issue: Bash Script Fails on Windows
-**Error:**
-```cmd
-'./deploy.sh' is not recognized as an internal or external command
-```
-**Solution:**
-```powershell
-# Use Git Bash or WSL
-& "C:\Program Files\Git\bin\bash.exe" ./deploy.sh dev
-# Or use PowerShell script
-.\deployment\scripts\deploy.ps1 -Environment dev
-# Or use npm script
-npm run deploy:dev
-```
-#### Issue: Different Command Outputs
-**Problem:** Scripts expect different output formats between platforms.
-**Solution:**
-```javascript
-// Create platform-agnostic deployment script
-const os = require('os');
-const { spawn } = require('child_process');
-function deploy(environment) {
-  const isWindows = os.platform() === 'win32';
-  const command = isWindows ? 'powershell' : 'bash';
-  const script = isWindows ? `./deployment/scripts/deploy.ps1` : `./deployment/scripts/deploy.sh`;
-  const args = isWindows ? ['-File', script, '-Environment', environment] : [script, environment];
-  const child = spawn(command, args, { stdio: 'inherit' });
-  return new Promise((resolve, reject) => {
-    child.on('close', (code) => {
-      code === 0 ? resolve() : reject(new Error(`Deployment failed with code ${code}`));
-    });
-  });
-}
-```
-### 🔒 Authentication Issues
-#### Issue: Certificate Store Differences
-**Problem:** Windows and Mac handle certificates differently.
-**Windows Solution:**
-```powershell
-# Use Windows Certificate Store
-$cert = Get-ChildItem -Path Cert:\CurrentUser\My | Where-Object {$_.Subject -like "*YourCert*"}
-```
-**Mac Solution:**
-```bash
-# Use Keychain
-security find-certificate -c "YourCert" -p > cert.pem
-```
-**Cross-Platform Solution:**
-```javascript
-// Use environment variables for certificate paths
-const certPath = process.env.CERT_PATH || './certificates/default.pem';
-const fs = require('fs');
-if (fs.existsSync(certPath)) {
-  const cert = fs.readFileSync(certPath);
-  // Use certificate
-} else {
-  console.error('Certificate not found:', certPath);
-}
-```
-## Development Environment Issues
-### 🛠️ IDE and Editor Issues
-#### Issue: VS Code Extensions Not Syncing
-**Problem:** Extensions work on one platform but not another.
-**Solution:**
-```json
-// .vscode/extensions.json
-{
-  "recommendations": [
-    "ms-vscode.powershell", // Windows PowerShell
-    "ms-vscode.vscode-typescript-next", // Cross-platform TypeScript
-    "esbenp.prettier-vscode", // Cross-platform formatting
-    "ms-vscode.vscode-json", // JSON support
-    "ms-azuretools.vscode-azurefunctions" // Azure development
-  ]
-}
-```
-#### Issue: Terminal Integration Problems
-**Problem:** VS Code terminal behaves differently on Windows vs Mac.
-**Solution:**
-```json
-// .vscode/settings.json
-{
-  "terminal.integrated.defaultProfile.windows": "PowerShell",
-  "terminal.integrated.defaultProfile.osx": "zsh",
-  "terminal.integrated.env.windows": {
-    "PATH": "${env:PATH};${workspaceFolder}\\node_modules\\.bin"
-  },
-  "terminal.integrated.env.osx": {
-    "PATH": "${env:PATH}:${workspaceFolder}/node_modules/.bin"
-  }
-}
-```
-### 📦 Package Management Issues
-#### Issue: npm install Fails with Different Errors
-**Windows Errors:**
-```cmd
-npm ERR! Error: EPERM: operation not permitted
-npm ERR! Error: ENOENT: no such file or directory
-```
-**Windows Solution:**
-```powershell
-# Run as Administrator
-Start-Process powershell -Verb runAs
-# Or fix npm permissions
-npm config set prefix $env:USERPROFILE\npm-global
-npm config set cache $env:USERPROFILE\.npm-cache
-# Clear cache
-npm cache clean --force
-```
-**Mac Errors:**
-```bash
-npm ERR! Error: EACCES: permission denied
-npm ERR! gyp ERR! stack Error: `make` failed with exit code: 2
-```
-**Mac Solution:**
-```bash
-# Install Xcode Command Line Tools
-xcode-select --install
-# Fix npm permissions
-sudo chown -R $(whoami) ~/.npm
-sudo chown -R $(whoami) /usr/local/lib/node_modules
-# Use nvm for better Node.js management
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
-```
-## CI/CD Pipeline Issues
-### ⚙️ Platform-Specific CI/CD Problems
-#### Issue: Different Build Outputs
-**Problem:** Build artifacts differ between Windows and Mac CI runners.
-**Solution:**
-```yaml
-# GitHub Actions - Ensure consistent builds
-jobs:
-  build:
-    runs-on: ubuntu-latest # Use Linux for consistency
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '18'
-          cache: 'npm'
-      - run: npm ci
-      - run: npm run build:prod
-  test-windows:
-    runs-on: windows-latest
-    needs: build
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/download-artifact@v4
-      - run: ./test-deployment.ps1
-  test-mac:
-    runs-on: macos-latest
-    needs: build
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/download-artifact@v4
-      - run: ./test-deployment.sh
-```
-#### Issue: Environment Variables Not Available
-**Problem:** Environment variables set differently on different platforms.
-**Solution:**
-```yaml
-# Set environment variables consistently
-env:
-  NODE_ENV: production
-  D365_API_URL: ${{ vars.D365_API_URL }}
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    env:
-      DEPLOYMENT_KEY: ${{ secrets.DEPLOYMENT_KEY }}
-    steps:
-      - name: Deploy (Cross-platform)
-        run: npm run deploy:prod
-        env:
-          D365_CLIENT_ID: ${{ secrets.D365_CLIENT_ID }}
-          D365_CLIENT_SECRET: ${{ secrets.D365_CLIENT_SECRET }}
-```
-## Quick Reference
-### 🔧 Platform Detection
-```javascript
-// JavaScript/Node.js
-const isWindows = process.platform === 'win32';
-const isMac = process.platform === 'darwin';
-const isLinux = process.platform === 'linux';
-```
-```powershell
-# PowerShell
-$IsWindows = $true  # Always true in Windows PowerShell
-$IsMacOS = $false   # Always false in Windows PowerShell
-```
-```bash
-# Bash
-case "$(uname -s)" in
-    Darwin*)    echo "Mac" ;;
-    Linux*)     echo "Linux" ;;
-    CYGWIN*|MINGW*) echo "Windows" ;;
-esac
-```
-### 📁 Cross-Platform Paths
-```javascript
-// Node.js - Always use path module
-const path = require('path');
-const configPath = path.join('config', 'environments', 'dev.json');
-const absolutePath = path.resolve(process.cwd(), 'dist');
-const relativePath = path.relative(process.cwd(), targetPath);
-```
-### 🔄 Command Equivalents
-| Task                     | Windows | Mac/Linux | Cross-Platform                                          |
-| ------------------------ | ------- | --------- | ------------------------------------------------------- |
-| **List files**           | `dir`   | `ls`      | `node -e "console.log(require('fs').readdirSync('.'))"` |
-| **Copy files**           | `copy`  | `cp`      | `node -e "require('fs').copyFileSync(src, dest)"`       |
-| **Environment variable** | `%VAR%` | `$VAR`    | `process.env.VAR`                                       |
-| **Path separator**       | `\`     | `/`       | `path.sep`                                              |
-### 🚀 Emergency Commands
-#### Get System Information
-```bash
-# Windows
-systeminfo | findstr "OS Name"
-Get-ComputerInfo | Select-Object WindowsProductName
-# Mac
-sw_vers
-system_profiler SPSoftwareDataType
-# Cross-platform (Node.js)
-node -e "console.log(process.platform, process.arch, process.version)"
-```
-#### Reset Development Environment
-```bash
-# All platforms
-npm cache clean --force
-rm -rf node_modules  # Mac/Linux
-rmdir /s node_modules  # Windows
-npm install
-# Git reset
-git clean -fdx
-git reset --hard HEAD
-```
-#### Check Tool Versions
-```bash
-# All platforms (if tools installed)
-node --version
-npm --version
-git --version
-# Windows specific
-powershell $PSVersionTable
-# Mac specific
-bash --version
-zsh --version
-```
----
-This troubleshooting guide covers the most common platform-specific issues encountered in
-cross-platform Dynamics 365 development. For issues not covered here, consult the team-specific
-documentation or escalate to the platform champions on your team.