@tywalk/pcf-helper 1.5.6 → 1.5.8

package/README.md

@@ -1,33 +1,257 @@
-# PCF Helper
+# PCF Helper Core 🔧
 
-A simple command-line tool that upgrades, builds, and imports your PCF control into your Dataverse environment.
+[![npm version](https://badge.fury.io/js/%40tywalk%2Fpcf-helper.svg)](https://badge.fury.io/js/%40tywalk%2Fpcf-helper)
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
-You can run commands separately or run `pcf-helper-deploy` to upgrade, build, and import with just one command.
+**Individual CLI commands and core library for Power Platform Component Framework (PCF) development.**
 
-## Requirements
+This package provides discrete command-line utilities for each PCF operation, making it ideal for automation scripts and developers who prefer granular control over their PCF workflows.
 
-This tool requires the following:
+## 📋 Table of Contents
 
-* `pac` cli installed on your machine.
-* `dotnet` cli or Visual Studio installed on your machine.
+- [Installation](#installation)
+- [Available Commands](#available-commands)
+- [Command Reference](#command-reference)
+- [API Reference](#api-reference)
+- [Troubleshooting](#troubleshooting)
 
-## Instructions
+## 📦 Installation
 
-1. In your project, run `npm install --save @tywalk/pcf-helper`. Or, install globally `npm install --save --global @tywalk/pcf-helper`.
-2. In your project's `package.json` file, add commands as npm scripts:
+### Global Installation (Recommended)
 
-```json
-"scripts": {
-  "upgrade": "pcf-helper-upgrade --path <path to pcf project folder>",
-  "build": "pcf-helper-build --path <path to pcf project folder>",
-  "import": "pcf-helper-import --path <path to pcf project folder> --environment <environment guid or url>",
-  "deploy": "pcf-helper-deploy --path <path to pcf project folder> --environment <environment guid or url>",
-  "init": "pcf-helper-init --path <path to pcf project folder (optional)> --name <name of the pcf project> --publisher-name <powerapps publisher name> --publisher-prefix <powerapps publisher prefix>"
-},
+```bash
+npm install -g @tywalk/pcf-helper
 ```
 
-## Contributing
+### Local Installation
 
-### Deployment
+```bash
+npm install @tywalk/pcf-helper
+```
+
+## 🛠️ Available Commands
+
+Each command is available as a standalone executable:
+
+| Command | Purpose | Global Usage |
+|---------|---------|--------------|
+| `pcf-helper-init` | Initialize new PCF project | `pcf-helper-init [options]` |
+| `pcf-helper-build` | Build PCF controls | `pcf-helper-build [options]` |
+| `pcf-helper-import` | Import controls to solution | `pcf-helper-import [options]` |
+| `pcf-helper-deploy` | Deploy controls (upgrade + build + import) | `pcf-helper-deploy [options]` |
+| `pcf-helper-upgrade` | Upgrade project dependencies | `pcf-helper-upgrade [options]` |
+| `pcf-helper-session` | Manage development sessions | `pcf-helper-session [options]` |
+
+## 📖 Command Reference
+
+### 🏗️ pcf-helper-init
+
+Initialize a new PCF project with proper scaffolding.
+
+```bash
+pcf-helper-init -n <control-name> [options]
+```
+
+#### Options
+
+| Option | Description | Required | Default |
+|--------|-------------|----------|---------|
+| `-n, --name <name>` | Name of the PCF control | ✅ | - |
+| `--publisher-name <name>` | Publisher name for the control | ❌ | - |
+| `--publisher-prefix <prefix>` | Publisher prefix | ❌ | - |
+| `-p, --path <path>` | Path to create the project | ❌ | Current directory |
+| `--run-npm-install` | Run npm install after init | ❌ | `true` |
+| `-V, --verbose` | Enable verbose logging | ❌ | `false` |
+| `-v, --version` | Display version | ❌ | - |
+
+#### Example
+
+```bash
+# Basic initialization
+pcf-helper-init -n MyCustomControl
+
+# Full initialization with custom settings
+pcf-helper-init -n MyCustomControl \
+  --publisher-name "Contoso" \
+  --publisher-prefix "con" \
+  -p ./my-pcf-project \
+  --verbose
+```
+
+### ⚡ pcf-helper-build
+
+Build and compile your PCF controls.
+
+```bash
+pcf-helper-build -p <solution-path> [options]
+```
+
+#### Options
+
+| Option | Description | Required | Default |
+|--------|-------------|----------|---------|
+| `-p, --path <path>` | Path to solution folder | ✅ | - |
+| `-t, --timeout <ms>` | Timeout in milliseconds | ❌ | 300000 |
+| `-V, --verbose` | Enable verbose logging | ❌ | `false` |
+| `-v, --version` | Display version | ❌ | - |
+
+#### Example
+
+```bash
+# Build with default settings
+pcf-helper-build -p ./MySolution
+
+# Build with custom timeout and verbose output
+pcf-helper-build -p ./MySolution --timeout 120000 --verbose
+```
+
+### 📦 pcf-helper-import
+
+Import PCF controls into your Dataverse solution.
+
+```bash
+pcf-helper-import -p <solution-path> [options]
+```
+
+#### Options
+
+| Option | Description | Required | Default |
+|--------|-------------|----------|---------|
+| `-p, --path <path>` | Path to solution folder | ✅ | - |
+| `-e, --environment <environment>` | Target environment | ❌ | - |
+| `-t, --timeout <ms>` | Timeout in milliseconds | ❌ | 300000 |
+| `-V, --verbose` | Enable verbose logging | ❌ | `false` |
+| `-v, --version` | Display version | ❌ | - |
+
+### 🚀 pcf-helper-deploy
+
+Deploy your PCF controls to the target environment. This command runs upgrade, build, and import in sequence.
+
+```bash
+pcf-helper-deploy -p <solution-path> [options]
+```
+
+#### Options
+
+Same as pcf-helper-import, but runs the full deployment pipeline.
+
+### 🔄 pcf-helper-upgrade
+
+Upgrade project dependencies and framework versions.
+
+```bash
+pcf-helper-upgrade -p <solution-path> [options]
+```
+
+#### Options
+
+| Option | Description | Required | Default |
+|--------|-------------|----------|---------|
+| `-p, --path <path>` | Path to solution folder | ✅ | - |
+| `-V, --verbose` | Enable verbose logging | ❌ | `false` |
+| `-v, --version` | Display version | ❌ | - |
+
+### 🎯 pcf-helper-session
+
+Manage development sessions with live reloading capabilities.
+
+```bash
+pcf-helper-session [options]
+```
+
+#### Options
+
+| Option | Description | Required | Default |
+|--------|-------------|----------|---------|
+| `-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 | ❌ | `session.config.json` |
+| `-V, --verbose` | Enable verbose logging | ❌ | `false` |
+| `-v, --version` | Display version | ❌ | - |
+
+## 🔧 API Reference
+
+You can also use PCF Helper programmatically in your Node.js applications:
+
+```typescript
+import * as pcfHelper from '@tywalk/pcf-helper';
+
+// Build a PCF control
+const result = pcfHelper.runBuild('./my-solution', true, 120000);
+
+// Initialize a new project
+const initResult = pcfHelper.runInit(
+  './new-project',
+  'MyControl',
+  'My Publisher',
+  'mp',
+  true,
+  true
+);
+
+// Set logging level
+pcfHelper.setLogLevel('debug');
+```
+
+### Available Functions
+
+- `runBuild(path, verbose, timeout?)` - Build PCF controls
+- `runInit(path, name, publisherName, publisherPrefix, runNpmInstall, verbose)` - Initialize new PCF project
+- `runImport(path, environment, verbose, timeout?)` - Import controls to solution
+- `runUpgrade(path, verbose)` - Upgrade project
+- `runSession(...)` - Manage development sessions
+- `setLogLevel(level)` - Set logging verbosity ('debug' | 'info' | 'warn' | 'error')
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### Build Failures
+
+```bash
+# Enable verbose logging for detailed error information
+pcf-helper-build -p . --verbose
+
+# Check if PAC CLI is properly installed
+pac --version
+
+# Verify .NET SDK installation
+dotnet --version
+```
+
+#### Timeout Errors
+
+```bash
+# Increase timeout for large projects
+pcf-helper-build -p . --timeout 600000  # 10 minutes
+```
+
+### Getting Help
+
+```bash
+# Show help for any command
+pcf-helper-build --help
+pcf-helper-init --help
+
+# Show version
+pcf-helper-build --version
+```
+
+## 📚 Additional Resources
+
+- [Power Platform Component Framework Documentation](https://docs.microsoft.com/en-us/powerapps/developer/component-framework/)
+- [Power Platform CLI Reference](https://docs.microsoft.com/en-us/powerapps/developer/data-platform/powerapps-cli)
+
+## 🔗 Related Packages
+
+- **[@tywalk/pcf-helper-run](../pcf-helper-run/README.md)** - Unified CLI interface
+- **[@tywalk/color-logger](https://www.npmjs.com/package/@tywalk/color-logger)** - Enhanced logging utilities
+
+---
+
+## 🏠 [← Back to Main Package](../../README.md)
 
-  
+For questions or issues, please visit our [GitHub Issues](https://github.com/tywalk/pcf-helper/issues) page.

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

@@ -12,14 +12,18 @@ test('build displays version', (done) => {
         console.error(`stderr: ${data}`);
     });
     task.on('close', (code) => {
-        console.log(output);
-        expect(output).toContain(`v${package_json_1.version}`);
+        expect(output).toContain(package_json_1.version);
         expect(code).toBe(0);
         done();
     });
 });
 test('build errors if no path is provided', (done) => {
     const task = (0, child_process_1.spawn)('node', ['./dist/bin/build.js', '-p']);
+    // Add timeout  
+    const timeout = setTimeout(() => {
+        task.kill();
+        done.fail('Test timed out');
+    }, 5000);
     let output = '';
     task.stdout.on('data', (data) => {
         output += data.toString();
@@ -28,8 +32,8 @@ test('build errors if no path is provided', (done) => {
         console.error(`stderr: ${data}`);
     });
     task.on('close', (code) => {
-        console.log(output);
         expect(code).toBe(1);
+        clearTimeout(timeout);
         done();
     });
 });

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

@@ -12,14 +12,18 @@ test('deploy displays version', (done) => {
         console.error(`stderr: ${data}`);
     });
     task.on('close', (code) => {
-        console.log(output);
-        expect(output).toContain(`v${package_json_1.version}`);
+        expect(output).toContain(package_json_1.version);
         expect(code).toBe(0);
         done();
     });
 });
 test('deploy errors if no path is provided', (done) => {
     const task = (0, child_process_1.spawn)('node', ['./dist/bin/deploy.js', '-p']);
+    // Add timeout  
+    const timeout = setTimeout(() => {
+        task.kill();
+        done.fail('Test timed out');
+    }, 5000);
     let output = '';
     task.stdout.on('data', (data) => {
         output += data.toString();
@@ -28,8 +32,8 @@ test('deploy errors if no path is provided', (done) => {
         console.error(`stderr: ${data}`);
     });
     task.on('close', (code) => {
-        console.log(output);
         expect(code).toBe(1);
+        clearTimeout(timeout);
         done();
     });
 });

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

@@ -9,14 +9,18 @@ test('import displays version', (done) => {
         output += data.toString();
     });
     task.on('close', (code) => {
-        console.log(output);
-        expect(output).toContain(`v${package_json_1.version}`);
+        expect(output).toContain(package_json_1.version);
         expect(code).toBe(0);
         done();
     });
 });
 test('import errors if no path is provided', (done) => {
     const task = (0, child_process_1.spawn)('node', ['./dist/bin/import.js', '-p']);
+    // Add timeout  
+    const timeout = setTimeout(() => {
+        task.kill();
+        done.fail('Test timed out');
+    }, 5000);
     let output = '';
     task.stdout.on('data', (data) => {
         output += data.toString();
@@ -25,8 +29,8 @@ test('import errors if no path is provided', (done) => {
         console.error(`stderr: ${data}`);
     });
     task.on('close', (code) => {
-        console.log(output);
         expect(code).toBe(1);
+        clearTimeout(timeout);
         done();
     });
 });

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

@@ -9,14 +9,18 @@ test('init displays version', (done) => {
         output += data.toString();
     });
     task.on('close', (code) => {
-        console.log(output);
-        expect(output).toContain(`v${package_json_1.version}`);
+        expect(output).toContain(package_json_1.version);
         expect(code).toBe(0);
         done();
     });
 });
 test('init errors if no path is provided', (done) => {
     const task = (0, child_process_1.spawn)('node', ['./dist/bin/init.js', '-p']);
+    // Add timeout  
+    const timeout = setTimeout(() => {
+        task.kill();
+        done.fail('Test timed out');
+    }, 5000);
     let output = '';
     task.stdout.on('data', (data) => {
         output += data.toString();
@@ -25,8 +29,8 @@ test('init errors if no path is provided', (done) => {
         console.error(`stderr: ${data}`);
     });
     task.on('close', (code) => {
-        console.log(output);
         expect(code).toBe(1);
+        clearTimeout(timeout);
         done();
     });
 });

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

@@ -9,14 +9,18 @@ test('session displays version', (done) => {
         output += data.toString();
     });
     task.on('close', (code) => {
-        console.log(output);
-        expect(output).toContain(`v${package_json_1.version}`);
+        expect(output).toContain(package_json_1.version);
         expect(code).toBe(0);
         done();
     });
 });
 test('session errors if no args are provided', (done) => {
     const task = (0, child_process_1.spawn)('node', ['./dist/bin/session.js', '-e']);
+    // Add timeout  
+    const timeout = setTimeout(() => {
+        task.kill();
+        done.fail('Test timed out');
+    }, 5000);
     let output = '';
     task.stdout.on('data', (data) => {
         output += data.toString();
@@ -25,8 +29,8 @@ test('session errors if no args are provided', (done) => {
         console.error(`stderr: ${data}`);
     });
     task.on('close', (code) => {
-        console.log(output);
         expect(code).toBe(1);
+        clearTimeout(timeout);
         done();
     });
 });

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

@@ -9,14 +9,18 @@ test('upgrade displays version', (done) => {
         output += data.toString();
     });
     task.on('close', (code) => {
-        console.log(output);
-        expect(output).toContain(`v${package_json_1.version}`);
+        expect(output).toContain(package_json_1.version);
         expect(code).toBe(0);
         done();
     });
 });
 test('upgrade errors if no path is provided', (done) => {
     const task = (0, child_process_1.spawn)('node', ['./dist/bin/upgrade.js', '-p']);
+    // Add timeout  
+    const timeout = setTimeout(() => {
+        task.kill();
+        done.fail('Test timed out');
+    }, 5000);
     let output = '';
     task.stdout.on('data', (data) => {
         output += data.toString();
@@ -25,8 +29,8 @@ test('upgrade errors if no path is provided', (done) => {
         console.error(`stderr: ${data}`);
     });
     task.on('close', (code) => {
-        console.log(output);
         expect(code).toBe(1);
+        clearTimeout(timeout);
         done();
     });
 });

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tywalk/pcf-helper",
-    "version": "1.5.6",
+    "version": "1.5.7",
     "description": "Command line helper for building and publishing PCF controls to Dataverse.",
     "main": "dist/index.js",
     "types": "./types/",
@@ -11,12 +11,17 @@
     "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",
-        "update": "npm run ready && npm publish --access public"
+        "update": "npm run ready && npm publish --access public",
+        "temp": "echo $version"
     },
     "keywords": [
         "pcf"
@@ -31,9 +36,13 @@
         "pcf-helper-session": "dist/bin/session.js"
     },
     "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.13.11",
         "jest": "^29.7.0",
+        "semantic-release": "^25.0.3",
         "ts-jest": "^29.2.6",
         "typescript": "^5.8.2"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tywalk/pcf-helper",
-  "version": "1.5.6",
+  "version": "1.5.8",
   "description": "Command line helper for building and publishing PCF controls to Dataverse.",
   "main": "dist/index.js",
   "types": "./types/",
@@ -11,12 +11,17 @@
   "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",
-    "update": "npm run ready && npm publish --access public"
+    "update": "npm run ready && npm publish --access public",
+    "temp": "echo $version"
   },
   "keywords": [
     "pcf"
@@ -31,9 +36,13 @@
     "pcf-helper-session": "dist/bin/session.js"
   },
   "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.13.11",
     "jest": "^29.7.0",
+    "semantic-release": "^25.0.3",
     "ts-jest": "^29.2.6",
     "typescript": "^5.8.2"
   },