@tywalk/pcf-helper-run 1.2.9 → 1.2.12

package/README.md

@@ -1,22 +1,408 @@
-# PCF Helper Run
+# PCF Helper Run 🎯
 
-A simple command-line utility for building and publishing PCF controls to Dataverse.
+[![npm version](https://badge.fury.io/js/%40tywalk%2Fpcf-helper-run.svg)](https://badge.fury.io/js/%40tywalk%2Fpcf-helper-run)
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
-## Requirements
+**Unified CLI interface for all Power Platform Component Framework (PCF) operations.**
 
-This tool requires the following:
+This package provides a single, consolidated command-line interface that brings together all PCF Helper functionality under one roof. Perfect for developers who prefer a unified experience and simplified command structure.
 
-* `pac` cli installed on your machine.
-* `dotnet` cli or Visual Studio installed on your machine.
+## 📋 Table of Contents
 
-## Instructions
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Command Structure](#️-command-structure)
+- [Available Subcommands](#️-available-subcommands)
+- [Usage Examples](#-detailed-command-reference)
+- [Workflow Examples](#-workflow-examples)
+- [Global Options](#️-global-options)
+- [Troubleshooting](#-troubleshooting)
 
-1. In a terminal, install globally `npm install --save --global @tywalk/pcf-helper-run`. Or,
-2. In a terminal, run `npx @tywalk/pcf-helper-run [command] --path <path to pcf project folder> --environment <environment guid or url>`.
+## 📦 Installation
 
-### Commands
+### Global Installation (Recommended)
 
-* `upgrade` - Upgrades PCF manifest and solution versions (--environment is not required). `npx @tywalk/pcf-helper-run upgrade --path <path to pcf project folder>`
-* `build` - Builds PCF control (--environment is not required). `npx @tywalk/pcf-helper-run build --path <path to pcf project folder>`
-* `import` - Imports PCF control into specified environment. Defaults to auth profile environment. `npx @tywalk/pcf-helper-run import --path <path to pcf project folder> --environment <environment guid or url>`
-* `deploy` - Upgrades, builds, and imports PCF control. `npx @tywalk/pcf-helper-run deploy--path <path to pcf project folder> --environment <environment guid or url>`
+```bash
+npm install -g @tywalk/pcf-helper-run
+```
+
+### Local Installation
+
+```bash
+npm install @tywalk/pcf-helper-run
+```
+
+### Verify Installation
+
+```bash
+pcf-helper-run --version
+pcf-helper-run --help
+```
+
+## 🚀 Quick Start
+
+### Basic Usage Pattern
+
+```bash
+pcf-helper-run <subcommand> [options]
+```
+
+### Your First PCF Control
+
+```bash
+# 1. Initialize a new PCF project
+pcf-helper-run init -n "MyFirstControl" --publisher-name "My Company"
+
+# 2. Navigate to the created project
+cd MyFirstControl
+
+# 3. Build the control
+pcf-helper-run build -p .
+
+# 4. Import to your solution
+pcf-helper-run import -p .
+```
+
+## 🏗️ Command Structure
+
+PCF Helper Run uses a subcommand structure for organized functionality:
+
+```bash
+pcf-helper-run <subcommand> [options]
+```
+
+Each subcommand corresponds to a specific PCF operation, with consistent option patterns across all commands.
+
+## 🛠️ Available Subcommands
+
+| Subcommand | Description | Equivalent Individual Command |
+|------------|-------------|-------------------------------|
+| `init` | Initialize new PCF project | `pcf-helper-init` |
+| `build` | Build and compile controls | `pcf-helper-build` |
+| `import` | Import controls to solution | `pcf-helper-import` |
+| `deploy` | Deploy to environment (upgrade + build + import) | `pcf-helper-deploy` |
+| `upgrade` | Upgrade project dependencies | `pcf-helper-upgrade` |
+| `session` | Manage development sessions | `pcf-helper-session` |
+
+## 📖 Detailed Command Reference
+
+### 🏗️ init - Initialize New Project
+
+Create a new PCF project with proper scaffolding.
+
+```bash
+pcf-helper-run init -n <control-name> [options]
+```
+
+#### Required Parameters
+
+- `-n, --name <name>` - Name of the PCF control
+
+#### Optional Parameters
+
+- `--publisher-name <name>` - Publisher name
+- `--publisher-prefix <prefix>` - Publisher prefix
+- `-p, --path <path>` - Creation path (default: current directory)
+- `--run-npm-install` - Run npm install after creation (default: true)
+
+#### Examples
+
+```bash
+# Simple initialization
+pcf-helper-run init -n "CustomerLookup"
+
+# Full configuration
+pcf-helper-run init -n "CustomerLookup" \
+  --publisher-name "Contoso Corporation" \
+  --publisher-prefix "con" \
+  -p ./my-controls \
+  --verbose
+
+# Skip npm install for faster scaffolding
+pcf-helper-run init -n "QuickControl" --run-npm-install false
+```
+
+### ⚡ build - Build Controls
+
+Compile and build your PCF controls for deployment.
+
+```bash
+pcf-helper-run build -p <solution-path> [options]
+```
+
+#### Required Parameters
+
+- `-p, --path <path>` - Path to the solution folder
+
+#### Optional Parameters
+
+- `-e, --environment <environment>` - Target environment configuration
+- `--env <environment>` - (Deprecated: use `--environment`) Target environment
+- `-t, --timeout <milliseconds>` - Build timeout (default: 300000)
+
+#### Examples
+
+```bash
+# Basic build
+pcf-helper-run build -p ./MySolution
+
+# Build with environment and extended timeout
+pcf-helper-run build -p ./MySolution --environment Production --timeout 120000
+
+# Verbose build for debugging
+pcf-helper-run build -p ./MySolution --verbose
+```
+
+### 📦 import - Import to Solution
+
+Import your built PCF controls into a Dataverse solution.
+
+```bash
+pcf-helper-run import -p <solution-path> [options]
+```
+
+#### Required Parameters
+
+- `-p, --path <path>` - Path to the solution folder
+
+#### Optional Parameters
+
+- `-e, --environment <environment>` - Target environment
+- `--env <environment>` - (Deprecated: use `--environment`) Target environment
+- `-t, --timeout <milliseconds>` - Import timeout
+
+#### Examples
+
+```bash
+# Import to default environment
+pcf-helper-run import -p .
+
+# Import to specific environment
+pcf-helper-run import -p . --environment "Test Environment"
+
+# Extended timeout for large solutions
+pcf-helper-run import -p . --timeout 180000
+```
+
+### 🚀 deploy - Deploy to Environment
+
+Deploy your PCF controls to the target Dataverse environment. This command runs upgrade, build, and import in sequence.
+
+```bash
+pcf-helper-run deploy -p <solution-path> [options]
+```
+
+#### Required Parameters
+
+- `-p, --path <path>` - Path to the solution folder
+
+#### Optional Parameters
+
+- `-e, --environment <environment>` - Target environment for deployment
+- `--env <environment>` - (Deprecated: use `--environment`) Target environment
+- `-t, --timeout <milliseconds>` - Deployment timeout
+
+#### Examples
+
+```bash
+# Deploy to default environment
+pcf-helper-run deploy -p .
+
+# Deploy to production with extended timeout
+pcf-helper-run deploy -p . --environment "Production" --timeout 300000
+```
+
+### 🔄 upgrade - Upgrade Project
+
+Upgrade your PCF project dependencies and framework versions.
+
+```bash
+pcf-helper-run upgrade -p <solution-path> [options]
+```
+
+#### Required Parameters
+
+- `-p, --path <path>` - Path to the solution folder
+
+#### Examples
+
+```bash
+# Upgrade project dependencies
+pcf-helper-run upgrade -p .
+
+# Upgrade with verbose output
+pcf-helper-run upgrade -p . --verbose
+```
+
+### 🎯 session - Manage Development Sessions
+
+Manage development sessions with live reloading capabilities.
+
+```bash
+pcf-helper-run session [options]
+```
+
+#### Optional Parameters
+
+- `-u, --url <url>` - Remote environment URL
+- `-s, --script <path>` - Remote script to intercept
+- `-t, --stylesheet <path>` - Remote stylesheet to intercept
+- `-b, --bundle <path>` - Local bundle path
+- `-c, --css <path>` - Local CSS path
+- `-f, --config <path>` - Config file path (default: `session.config.json`)
+
+#### Examples
+
+```bash
+# Start session with default config
+pcf-helper-run session
+
+# Session with custom configuration
+pcf-helper-run session -u "https://contoso.crm.dynamics.com" -s ./bundle.js
+```
+
+## ⚙️ Global Options
+
+These options are available for all subcommands:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-v, --verbose` | Enable detailed logging | `false` |
+| `--version` | Display version information | - |
+| `-h, --help` | Show help for command | - |
+| `-t, --timeout <ms>` | Operation timeout in milliseconds | `300000` |
+
+### Global Usage Examples
+
+```bash
+# Enable verbose logging for any command
+pcf-helper-run build -p . --verbose
+
+# Set custom timeout
+pcf-helper-run import -p . --timeout 120000
+
+# Get help for specific subcommand
+pcf-helper-run build --help
+```
+
+## 💼 Workflow Examples
+
+### Complete Development Workflow
+
+```bash
+#!/bin/bash
+# Complete PCF development and deployment script
+
+set -e  # Exit on any error
+
+echo "🏗️  Initializing PCF project..."
+pcf-helper-run init -n "SalesCalculator" \
+  --publisher-name "Contoso Sales" \
+  --publisher-prefix "cs" \
+  -p ./sales-calculator
+
+echo "📂 Navigating to project directory..."
+cd ./sales-calculator
+
+echo "⚡ Building the control..."
+pcf-helper-run build -p . --verbose
+
+echo "📦 Importing to solution..."
+pcf-helper-run import -p . --timeout 120000
+
+echo "🚀 Deploying to test environment..."
+pcf-helper-run deploy -p . --environment "Test"
+
+echo "✅ Deployment complete!"
+```
+
+### Development with Multiple Environments
+
+```bash
+# Build and test locally
+pcf-helper-run build -p .
+
+# Deploy to development environment
+pcf-helper-run deploy -p . --environment "Development"
+
+# After testing, deploy to staging
+pcf-helper-run deploy -p . --environment "Staging"
+
+# Finally, deploy to production
+pcf-helper-run deploy -p . --environment "Production"
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues and Solutions
+
+#### Command Not Found
+
+```bash
+# Verify installation
+npm list -g @tywalk/pcf-helper-run
+
+# Reinstall if necessary
+npm uninstall -g @tywalk/pcf-helper-run
+npm install -g @tywalk/pcf-helper-run
+```
+
+#### Build Failures
+
+```bash
+# Enable verbose mode for detailed error info
+pcf-helper-run build -p . --verbose
+
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+
+# Verify prerequisites
+pac --version
+dotnet --version
+```
+
+#### Timeout Errors
+
+```bash
+# Increase timeout for large projects
+pcf-helper-run build -p . --timeout 120000  # 2 minutes
+```
+
+#### Deprecated Flag Warnings
+
+```bash
+# Replace deprecated --env with --environment
+pcf-helper-run deploy -p . --environment "Production"
+```
+
+### Debug Information
+
+```bash
+# Show detailed version and environment information
+pcf-helper-run --version --verbose
+
+# Get help for specific command
+pcf-helper-run deploy --help
+```
+
+## 📚 Additional Resources
+
+### Documentation Links
+
+- [Power Platform Component Framework Documentation](https://docs.microsoft.com/en-us/powerapps/developer/component-framework/)
+- [Power Platform CLI Documentation](https://docs.microsoft.com/en-us/powerapps/developer/data-platform/powerapps-cli)
+- [PCF Community Gallery](https://pcf.gallery/)
+
+## 🔗 Related Packages
+
+- **[@tywalk/pcf-helper](../pcf-helper/README.md)** - Individual CLI commands and core library
+- **[@tywalk/color-logger](https://www.npmjs.com/package/@tywalk/color-logger)** - Enhanced logging utilities
+
+---
+
+## 🏠 [← Back to Main Package](../../README.md)
+
+For questions, feature requests, or bug reports, please visit our [GitHub Issues](https://github.com/tywalk/pcf-helper/issues) page.
+
+**Happy PCF development! 🎉**

package/dist/__tests__/pcf-helper-run.test.js

@@ -37,20 +37,31 @@ const child_process_1 = require("child_process");
 const package_json_1 = require("../package.json");
 const tasks = __importStar(require("@tywalk/pcf-helper"));
 test('displays version', (done) => {
-    const task = (0, child_process_1.spawn)('node', ['./dist/index.js', '-v']);
+    const task = (0, child_process_1.spawn)('node', ['./dist/index.js', '--version']);
+    // Add timeout
+    const timeout = setTimeout(() => {
+        task.kill();
+        done.fail('Test timed out');
+    }, 5000);
     let output = '';
     task.stdout.on('data', (data) => {
         output += data.toString();
     });
     task.on('close', (code) => {
+        clearTimeout(timeout);
         console.log(output);
         expect(output).toContain(package_json_1.version);
         expect(code).toBe(0);
         done();
     });
-});
+}, 10000);
 test('errors if no path is provided', (done) => {
-    const task = (0, child_process_1.spawn)('node', ['./index.js', '-p']);
+    const task = (0, child_process_1.spawn)('node', ['./dist/index.js', 'build']);
+    // Add timeout
+    const timeout = setTimeout(() => {
+        task.kill();
+        done.fail('Test timed out');
+    }, 5000);
     let output = '';
     task.stdout.on('data', (data) => {
         output += data.toString();
@@ -59,13 +70,20 @@ test('errors if no path is provided', (done) => {
         console.error(`stderr: ${data}`);
     });
     task.on('close', (code) => {
+        clearTimeout(timeout);
         console.log(output);
-        expect(code).toBe(1);
+        // The command should exit with non-zero code when required path is missing
+        expect(code).not.toBe(0);
         done();
     });
-});
+}, 10000);
 test('errors if incorrect command is provided', (done) => {
-    const task = (0, child_process_1.spawn)('node', ['./index.js', '-p', 'test', 'invalid']);
+    const task = (0, child_process_1.spawn)('node', ['./dist/index.js', 'invalidcommand']);
+    // Add timeout  
+    const timeout = setTimeout(() => {
+        task.kill();
+        done.fail('Test timed out');
+    }, 5000);
     let output = '';
     task.stdout.on('data', (data) => {
         output += data.toString();
@@ -74,11 +92,13 @@ test('errors if incorrect command is provided', (done) => {
         console.error(`stderr: ${data}`);
     });
     task.on('close', (code) => {
+        clearTimeout(timeout);
         console.log(output);
-        expect(code).toBe(1);
+        // Invalid command should exit with non-zero code
+        expect(code).not.toBe(0);
         done();
     });
-});
+}, 10000);
 test('runBuild exists', () => {
     const exists = typeof (tasks === null || tasks === void 0 ? void 0 : tasks.runBuild) === 'function';
     expect(exists).toBe(true);

package/dist/index.js

@@ -263,14 +263,14 @@ addCommonOptions(commander_1.program.command('session'))
     .option('-s, --intercept-stylesheet <stylesheet>', 'remote stylesheet to intercept')
     .option('-b, --local-bundle <path>', 'local bundle path')
     .option('-c, --local-css <path>', 'local CSS path')
-    .option('-f, --config <path>', 'config file path', 'dev-config.json')
+    .option('-f, --config <path>', 'config file path', 'session.config.json')
     .action((options) => {
     const { logger, tick } = setupExecutionContext(options);
     let result = 0;
     try {
         logger.log('[PCF Helper Run] ' + (0, performanceUtil_1.formatTime)(new Date()) + ' session started.\n');
         if (!options.url) {
-            const config = tasks.loadConfig(options.config || 'dev-config.json');
+            const config = tasks.loadConfig(options.config || 'session.config.json');
             options.url = config.remoteEnvironmentUrl;
             options.script = config.remoteScriptToIntercept;
             options.stylesheet = config.remoteStylesheetToIntercept;

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tywalk/pcf-helper-run",
-    "version": "1.2.9",
+    "version": "1.2.0",
     "description": "A simple command-line utility for building and publishing PCF controls to Dataverse.",
     "types": "./types/",
     "files": [
@@ -10,11 +10,16 @@
     "repository": {
         "url": "git+https://github.com/tywalk/pcf-helper.git"
     },
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
     "scripts": {
         "test": "jest",
         "build": "tsc",
         "upgrade": "npm version patch --no-git-tag-version",
-        "ready": "npm run upgrade && npm run build && npm publish --access public"
+        "ready": "npm run upgrade && npm run build",
+        "update": "npm run ready && npm publish --access public"
     },
     "keywords": [
         "pcf"
@@ -25,12 +30,16 @@
     },
     "dependencies": {
         "@tywalk/color-logger": "^1.0.3",
-        "@tywalk/pcf-helper": "^1.5.5"
+        "@tywalk/pcf-helper": "^1.5.6"
     },
     "devDependencies": {
+        "@semantic-release/git": "^10.0.1",
+        "@semantic-release/github": "^12.0.6",
+        "@semantic-release/npm": "^13.1.5",
         "@types/jest": "^29.5.14",
         "@types/node": "^22.19.3",
         "jest": "^29.7.0",
+        "semantic-release": "^25.0.3",
         "ts-jest": "^29.4.6",
         "typescript": "^5.9.3"
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tywalk/pcf-helper-run",
-  "version": "1.2.9",
+  "version": "1.2.12",
   "description": "A simple command-line utility for building and publishing PCF controls to Dataverse.",
   "types": "./types/",
   "files": [
@@ -10,11 +10,16 @@
   "repository": {
     "url": "git+https://github.com/tywalk/pcf-helper.git"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "scripts": {
     "test": "jest",
     "build": "tsc",
     "upgrade": "npm version patch --no-git-tag-version",
-    "ready": "npm run upgrade && npm run build && npm publish --access public"
+    "ready": "npm run upgrade && npm run build",
+    "update": "npm run ready && npm publish --access public"
   },
   "keywords": [
     "pcf"
@@ -25,12 +30,16 @@
   },
   "dependencies": {
     "@tywalk/color-logger": "^1.0.3",
-    "@tywalk/pcf-helper": "^1.5.5"
+    "@tywalk/pcf-helper": "^1.5.6"
   },
   "devDependencies": {
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
     "@types/jest": "^29.5.14",
     "@types/node": "^22.19.3",
     "jest": "^29.7.0",
+    "semantic-release": "^25.0.3",
     "ts-jest": "^29.4.6",
     "typescript": "^5.9.3"
   }