@tywalk/pcf-helper 1.5.6 → 1.6.0

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/bin/session.js

@@ -33,14 +33,11 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 const task = __importStar(require("../tasks/session-pcf"));
 const package_json_1 = require("../package.json");
-const color_logger_1 = __importDefault(require("@tywalk/color-logger"));
 const commander_1 = require("commander");
+const commandUtil_1 = require("../util/commandUtil");
 const program = new commander_1.Command();
 program
     .name('pcf-helper-session')
@@ -53,12 +50,15 @@ program
     .option('-b, --bundle <path>', 'local bundle path')
     .option('-c, --css <path>', 'local CSS path')
     .option('-f, --config <path>', 'config file path', 'session.config.json')
-    .parse();
-const options = program.opts();
-if (options.verbose) {
-    color_logger_1.default.setDebug(true);
-    color_logger_1.default.debug('Verbose logging enabled');
-}
-color_logger_1.default.log('PCF Helper version', package_json_1.version);
-const config = task.loadConfig(options.config);
-task.runSession(config.remoteEnvironmentUrl, config.remoteScriptToIntercept, config.remoteStylesheetToIntercept, config.localBundlePath, config.localCssPath);
+    .option('-w, --watch', 'start pcf-scripts watch process')
+    .parse()
+    .action((options) => {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const { logger, tick } = (0, commandUtil_1.setupExecutionContext)(options);
+    logger.log('PCF Helper version', package_json_1.version);
+    const config = task.loadConfig(options.config);
+    // Priority: CLI args > config file > environment variables
+    const startWatch = (_b = (_a = options.watch) !== null && _a !== void 0 ? _a : config.startWatch) !== null && _b !== void 0 ? _b : false;
+    task.runSession((_c = options.url) !== null && _c !== void 0 ? _c : config.remoteEnvironmentUrl, (_d = options.script) !== null && _d !== void 0 ? _d : config.remoteScriptToIntercept, (_e = options.stylesheet) !== null && _e !== void 0 ? _e : config.remoteStylesheetToIntercept, (_f = options.bundle) !== null && _f !== void 0 ? _f : config.localBundlePath, (_g = options.css) !== null && _g !== void 0 ? _g : config.localCssPath, startWatch);
+    (0, commandUtil_1.handleResults)('session', logger, tick, 0);
+});

package/dist/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"
     },

package/dist/tasks/session-pcf.js

@@ -18,6 +18,7 @@ const color_logger_1 = __importDefault(require("@tywalk/color-logger"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const playwright_1 = require("playwright");
+const child_process_1 = require("child_process");
 /**
  * Loads configuration for the session task, supporting a combination of config file, environment variables, and CLI arguments.
  * The priority order is: CLI arguments > environment variables > config file > defaults.
@@ -76,6 +77,8 @@ function loadConfig(config) {
         remoteStylesheetToIntercept: remoteStylesheetToIntercept,
         localCssPath: (_a = process.env.LOCAL_CSS_PATH) !== null && _a !== void 0 ? _a : fileConfig.localCssPath,
         localBundlePath: (_b = process.env.LOCAL_BUNDLE_PATH) !== null && _b !== void 0 ? _b : fileConfig.localBundlePath,
+        startWatch: process.env.START_WATCH === 'true' ||
+            fileConfig.startWatch || false,
     };
 }
 /**
@@ -87,183 +90,227 @@ function loadConfig(config) {
  * @param remoteStylesheetToIntercept The full URL of the remote stylesheet to intercept (e.g., https://app.your-remote-environment.com/static/css/remote-control-styles.css).
  * @param localBundlePath The local file path to the JavaScript bundle that should be served when the remote script URL is requested.
  * @param localCssPath The local file path to the CSS file that should be served when the remote stylesheet URL is requested.
+ * @param startWatch Optional flag to start the session in watch mode. If true, the process will kick off "pcf-scripts start watch" in parallel to automatically rebuild the bundle on changes.
+ * @returns A promise that resolves when the session is set up and running. The session will continue to run until the process is exited, at which point it will clean up and save state.
  */
-function runSession(remoteEnvironmentUrl, remoteScriptToIntercept, remoteStylesheetToIntercept, localBundlePath, localCssPath) {
-    if (!remoteEnvironmentUrl) {
-        color_logger_1.default.error('❌ Remote environment URL is required. Please provide it via CLI, config file, or environment variable.');
-        process.exit(1);
-    }
-    if (!remoteScriptToIntercept) {
-        color_logger_1.default.error('❌ Remote script URL to intercept is required. Please provide it via CLI, config file, or environment variable.');
-        process.exit(1);
-    }
-    if (!remoteStylesheetToIntercept) {
-        color_logger_1.default.error('❌ Remote stylesheet URL to intercept is required. Please provide it via CLI, config file, or environment variable.');
-        process.exit(1);
-    }
-    if (!localBundlePath) {
-        color_logger_1.default.error('❌ Local bundle path is required. Please provide it via CLI, config file, or environment variable.');
-        process.exit(1);
-    }
-    if (!localCssPath) {
-        color_logger_1.default.error('❌ Local CSS path is required. Please provide it via CLI, config file, or environment variable.');
-        process.exit(1);
-    }
-    const REMOTE_ENVIRONMENT_URL = remoteEnvironmentUrl;
-    const REMOTE_SCRIPT_TO_INTERCEPT = remoteScriptToIntercept;
-    const REMOTE_STYLESHEET_TO_INTERCEPT = remoteStylesheetToIntercept;
-    const LOCAL_BUNDLE_PATH = path_1.default.resolve(localBundlePath);
-    const LOCAL_CSS_PATH = path_1.default.resolve(localCssPath);
-    // Debug logging for URL construction
-    color_logger_1.default.debug('🔍 Debug - Final URLs:');
-    color_logger_1.default.debug(`   Remote Environment: ${REMOTE_ENVIRONMENT_URL}`);
-    color_logger_1.default.debug(`   Script to intercept: ${REMOTE_SCRIPT_TO_INTERCEPT}`);
-    color_logger_1.default.debug(`   CSS to intercept: ${REMOTE_STYLESHEET_TO_INTERCEPT}`);
-    color_logger_1.default.debug(`   Local bundle path: ${LOCAL_BUNDLE_PATH}`);
-    color_logger_1.default.debug(`   Local CSS path: ${LOCAL_CSS_PATH}`);
-    color_logger_1.default.debug('');
-    // Path to store your session cookies
-    const AUTH_DIR = path_1.default.join(process.cwd(), '.auth');
-    const STATE_FILE = path_1.default.join(AUTH_DIR, 'state.json');
-    (() => __awaiter(this, void 0, void 0, function* () {
-        color_logger_1.default.log('🚀 Starting ephemeral browser session...');
-        // 1. Prepare context options (load session if it exists)
-        let contextOptions = {};
-        if (fs_1.default.existsSync(STATE_FILE)) {
-            color_logger_1.default.log('🔓 Loading previous login session...');
-            contextOptions.storageState = STATE_FILE;
+function runSession(remoteEnvironmentUrl, remoteScriptToIntercept, remoteStylesheetToIntercept, localBundlePath, localCssPath, startWatch) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        if (!remoteEnvironmentUrl) {
+            color_logger_1.default.error('❌ Remote environment URL is required. Please provide it via CLI, config file, or environment variable.');
+            process.exit(1);
         }
-        else {
-            color_logger_1.default.log('⚠️ No previous session found. You may need to log in.');
+        if (!remoteScriptToIntercept) {
+            color_logger_1.default.error('❌ Remote script URL to intercept is required. Please provide it via CLI, config file, or environment variable.');
+            process.exit(1);
         }
-        // 2. Launch browser and apply context
-        const browser = yield playwright_1.chromium.launch({ headless: false, args: ['--auto-open-devtools-for-tabs'] });
-        const context = yield browser.newContext(Object.assign(Object.assign({}, contextOptions), { viewport: null, serviceWorkers: 'block' }));
-        // Shared cleanup function to save state and close browser
-        const cleanup = (...args_1) => __awaiter(this, [...args_1], void 0, function* (reason = 'unknown') {
-            try {
-                color_logger_1.default.log(`💾 Saving session state (${reason})...`);
-                // Ensure the .auth directory exists before saving
-                if (!fs_1.default.existsSync(AUTH_DIR)) {
-                    fs_1.default.mkdirSync(AUTH_DIR, { recursive: true });
-                }
-                if (!browser.isConnected()) {
-                    color_logger_1.default.log('Browser already disconnected.');
+        if (!remoteStylesheetToIntercept) {
+            color_logger_1.default.error('❌ Remote stylesheet URL to intercept is required. Please provide it via CLI, config file, or environment variable.');
+            process.exit(1);
+        }
+        if (!localBundlePath) {
+            color_logger_1.default.error('❌ Local bundle path is required. Please provide it via CLI, config file, or environment variable.');
+            process.exit(1);
+        }
+        if (!localCssPath) {
+            color_logger_1.default.error('❌ Local CSS path is required. Please provide it via CLI, config file, or environment variable.');
+            process.exit(1);
+        }
+        const REMOTE_ENVIRONMENT_URL = remoteEnvironmentUrl;
+        const REMOTE_SCRIPT_TO_INTERCEPT = remoteScriptToIntercept;
+        const REMOTE_STYLESHEET_TO_INTERCEPT = remoteStylesheetToIntercept;
+        const LOCAL_BUNDLE_PATH = path_1.default.resolve(localBundlePath);
+        const LOCAL_CSS_PATH = path_1.default.resolve(localCssPath);
+        // Debug logging for URL construction
+        color_logger_1.default.debug('🔍 Debug - Final URLs:');
+        color_logger_1.default.debug(`   Remote Environment: ${REMOTE_ENVIRONMENT_URL}`);
+        color_logger_1.default.debug(`   Script to intercept: ${REMOTE_SCRIPT_TO_INTERCEPT}`);
+        color_logger_1.default.debug(`   CSS to intercept: ${REMOTE_STYLESHEET_TO_INTERCEPT}`);
+        color_logger_1.default.debug(`   Local bundle path: ${LOCAL_BUNDLE_PATH}`);
+        color_logger_1.default.debug(`   Local CSS path: ${LOCAL_CSS_PATH}`);
+        color_logger_1.default.debug('');
+        // Path to store your session cookies
+        const AUTH_DIR = path_1.default.join(process.cwd(), '.auth');
+        const STATE_FILE = path_1.default.join(AUTH_DIR, 'state.json');
+        // Start watch process if requested
+        let watchProcess;
+        if (startWatch) {
+            color_logger_1.default.log('🔧 Starting pcf-scripts watch process...');
+            watchProcess = (0, child_process_1.spawn)('pcf-scripts', ['start', 'watch'], {
+                cwd: process.cwd(),
+                stdio: ['inherit', 'pipe', 'pipe'],
+                shell: true
+            });
+            (_a = watchProcess.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (data) => {
+                color_logger_1.default.log(`📦 [PCF Watch] ${data.toString().trim()}`);
+            });
+            (_b = watchProcess.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (data) => {
+                color_logger_1.default.warn(`⚠️ [PCF Watch] ${data.toString().trim()}`);
+            });
+            watchProcess.on('exit', (code) => {
+                if (code !== null && code !== 0) {
+                    color_logger_1.default.error(`❌ PCF watch process exited with code ${code}`);
                 }
                 else {
-                    // Save the cookies and local storage to the JSON file
-                    yield context.storageState({ path: STATE_FILE });
-                    color_logger_1.default.log('🛑 Tearing down rules and session.');
-                    yield browser.close();
+                    color_logger_1.default.log('✅ PCF watch process ended');
                 }
-            }
-            catch (error) {
-                color_logger_1.default.debug('Error during cleanup:', error);
-            }
-        });
-        // Handle process exit signals
-        process.on('SIGINT', () => __awaiter(this, void 0, void 0, function* () {
-            yield cleanup('SIGINT');
-            process.exit(0);
-        }));
-        process.on('SIGTERM', () => __awaiter(this, void 0, void 0, function* () {
-            yield cleanup('SIGTERM');
-            process.exit(0);
-        }));
-        process.on('beforeExit', () => __awaiter(this, void 0, void 0, function* () {
-            yield cleanup('beforeExit');
-        }));
-        // Handle uncaught exceptions
-        process.on('uncaughtException', (error) => __awaiter(this, void 0, void 0, function* () {
-            color_logger_1.default.error('Uncaught exception:', error);
-            yield cleanup('uncaughtException');
-            process.exit(1);
-        }));
-        process.on('unhandledRejection', (reason) => __awaiter(this, void 0, void 0, function* () {
-            color_logger_1.default.error('Unhandled promise rejection:', reason);
-            yield cleanup('unhandledRejection');
-            process.exit(1);
-        }));
-        // Handle browser disconnect
-        browser.on('disconnected', () => __awaiter(this, void 0, void 0, function* () {
-            color_logger_1.default.log('Browser disconnected');
-            yield cleanup('browser disconnected');
-        }));
-        // Handle context close (when all pages in context are closed)
-        context.on('close', () => __awaiter(this, void 0, void 0, function* () {
-            color_logger_1.default.log('Browser context closed');
-            yield cleanup('context closed');
-            process.exit(0);
-        }));
-        // 3. Programmatically apply your network interception rule with pattern matching
-        // Handle dynamic version segments in CRM URLs like /version?/webresources/...
-        const scriptPattern = REMOTE_SCRIPT_TO_INTERCEPT.replace(/^https?:\/\/[^\/]+/, '');
-        const stylesheetPattern = REMOTE_STYLESHEET_TO_INTERCEPT.replace(/^https?:\/\/[^\/]+/, '');
-        color_logger_1.default.debug(`📡 Setting up interception patterns:`);
-        color_logger_1.default.debug(`   Script pattern: **${scriptPattern}`);
-        color_logger_1.default.debug(`   CSS pattern: **${stylesheetPattern}`);
-        yield context.route(route => {
-            if (!route.href) {
-                return false;
-            }
-            // Match script URLs that end with the same path structure
-            return route.href.includes(scriptPattern);
-        }, (route) => __awaiter(this, void 0, void 0, function* () {
-            color_logger_1.default.log(`✅ Intercepted script request: ${route.request().url()}`);
-            color_logger_1.default.log(`   Serving local file: ${LOCAL_BUNDLE_PATH}`);
-            route.fulfill({
-                status: 200,
-                contentType: 'application/javascript',
-                body: fs_1.default.readFileSync(LOCAL_BUNDLE_PATH)
             });
-        }));
-        yield context.route(route => {
-            if (!route.href) {
-                return false;
-            }
-            // Match CSS URLs that end with the same path structure  
-            return route.href.includes(stylesheetPattern);
-        }, (route) => __awaiter(this, void 0, void 0, function* () {
-            color_logger_1.default.log(`✅ Intercepted CSS request: ${route.request().url()}`);
-            color_logger_1.default.log(`   Serving local file: ${LOCAL_CSS_PATH}`);
-            route.fulfill({
-                status: 200,
-                contentType: 'text/css',
-                body: fs_1.default.readFileSync(LOCAL_CSS_PATH)
+            watchProcess.on('error', (error) => {
+                color_logger_1.default.error('❌ Failed to start PCF watch process:', error);
             });
-        }));
-        // 4. Open a new tab and navigate to your remote environment
-        const page = yield context.newPage();
-        yield page.goto(REMOTE_ENVIRONMENT_URL);
-        // 5. Clean up and save state when the page is closed (but others may still be open)
-        page.on('close', () => __awaiter(this, void 0, void 0, function* () {
-            const pages = context.pages();
-            if (pages.length <= 1) {
-                // This was the last page, trigger full cleanup
-                yield cleanup('last page closed');
-                process.exit(0);
+        }
+        yield (() => __awaiter(this, void 0, void 0, function* () {
+            color_logger_1.default.log('🚀 Starting ephemeral browser session...');
+            // 1. Prepare context options (load session if it exists)
+            let contextOptions = {};
+            if (fs_1.default.existsSync(STATE_FILE)) {
+                color_logger_1.default.log('🔓 Loading previous login session...');
+                contextOptions.storageState = STATE_FILE;
             }
             else {
-                color_logger_1.default.debug(`Page closed, but ${pages.length - 1} pages still open. Keeping session alive.`);
+                color_logger_1.default.log('⚠️ No previous session found. You may need to log in.');
             }
-        }));
-        // 6. Watch the local bundle for changes and auto-reload
-        let reloadTimeout;
-        fs_1.default.watch(LOCAL_BUNDLE_PATH, (eventType) => {
-            if (eventType === 'change') {
-                // Clear the previous timer if the file changes again quickly
-                clearTimeout(reloadTimeout);
-                // Wait 300ms for the bundler to finish writing the file before reloading
-                reloadTimeout = setTimeout(() => __awaiter(this, void 0, void 0, function* () {
-                    color_logger_1.default.log(`\n🔄 Local bundle updated! Reloading the page...`);
-                    try {
-                        yield page.reload();
+            // 2. Launch browser and apply context
+            const browser = yield playwright_1.chromium.launch({ headless: false, args: ['--auto-open-devtools-for-tabs'] });
+            const context = yield browser.newContext(Object.assign(Object.assign({}, contextOptions), { viewport: null, serviceWorkers: 'block' }));
+            // Shared cleanup function to save state and close browser
+            const cleanup = (...args_1) => __awaiter(this, [...args_1], void 0, function* (reason = 'unknown') {
+                try {
+                    color_logger_1.default.log(`💾 Saving session state (${reason})...`);
+                    // Kill the watch process if it's running
+                    if (watchProcess && !watchProcess.killed) {
+                        color_logger_1.default.log('🛑 Terminating PCF watch process...');
+                        watchProcess.kill('SIGTERM');
+                        // Give it a chance to exit gracefully, then force kill if needed
+                        setTimeout(() => {
+                            if (watchProcess && !watchProcess.killed) {
+                                color_logger_1.default.warn('⚠️ Force killing PCF watch process...');
+                                watchProcess.kill('SIGKILL');
+                            }
+                        }, 2000);
                     }
-                    catch (err) {
-                        color_logger_1.default.error('⚠️ Could not reload page (browser might be closed).', err);
+                    // Ensure the .auth directory exists before saving
+                    if (!fs_1.default.existsSync(AUTH_DIR)) {
+                        fs_1.default.mkdirSync(AUTH_DIR, { recursive: true });
                     }
-                }), 300);
-            }
-        });
-    }))();
+                    if (!browser.isConnected()) {
+                        color_logger_1.default.log('Browser already disconnected.');
+                    }
+                    else {
+                        // Save the cookies and local storage to the JSON file
+                        yield context.storageState({ path: STATE_FILE });
+                        color_logger_1.default.log('🛑 Tearing down rules and session.');
+                        yield browser.close();
+                    }
+                }
+                catch (error) {
+                    color_logger_1.default.debug('Error during cleanup:', error);
+                }
+            });
+            // Handle process exit signals
+            process.on('SIGINT', () => __awaiter(this, void 0, void 0, function* () {
+                yield cleanup('SIGINT');
+                process.exit(0);
+            }));
+            process.on('SIGTERM', () => __awaiter(this, void 0, void 0, function* () {
+                yield cleanup('SIGTERM');
+                process.exit(0);
+            }));
+            process.on('beforeExit', () => __awaiter(this, void 0, void 0, function* () {
+                yield cleanup('beforeExit');
+            }));
+            // Handle uncaught exceptions
+            process.on('uncaughtException', (error) => __awaiter(this, void 0, void 0, function* () {
+                color_logger_1.default.error('Uncaught exception:', error);
+                yield cleanup('uncaughtException');
+                process.exit(1);
+            }));
+            process.on('unhandledRejection', (reason) => __awaiter(this, void 0, void 0, function* () {
+                color_logger_1.default.error('Unhandled promise rejection:', reason);
+                yield cleanup('unhandledRejection');
+                process.exit(1);
+            }));
+            // Handle browser disconnect
+            browser.on('disconnected', () => __awaiter(this, void 0, void 0, function* () {
+                color_logger_1.default.log('Browser disconnected');
+                yield cleanup('browser disconnected');
+            }));
+            // Handle context close (when all pages in context are closed)
+            context.on('close', () => __awaiter(this, void 0, void 0, function* () {
+                color_logger_1.default.log('Browser context closed');
+                yield cleanup('context closed');
+                process.exit(0);
+            }));
+            // 3. Programmatically apply your network interception rule with pattern matching
+            // Handle dynamic version segments in CRM URLs like /version?/webresources/...
+            const scriptPattern = REMOTE_SCRIPT_TO_INTERCEPT.replace(/^https?:\/\/[^\/]+/, '');
+            const stylesheetPattern = REMOTE_STYLESHEET_TO_INTERCEPT.replace(/^https?:\/\/[^\/]+/, '');
+            color_logger_1.default.debug(`📡 Setting up interception patterns:`);
+            color_logger_1.default.debug(`   Script pattern: **${scriptPattern}`);
+            color_logger_1.default.debug(`   CSS pattern: **${stylesheetPattern}`);
+            yield context.route(route => {
+                if (!route.href) {
+                    return false;
+                }
+                // Match script URLs that end with the same path structure
+                return route.href.includes(scriptPattern);
+            }, (route) => __awaiter(this, void 0, void 0, function* () {
+                color_logger_1.default.log(`✅ Intercepted script request: ${route.request().url()}`);
+                color_logger_1.default.log(`   Serving local file: ${LOCAL_BUNDLE_PATH}`);
+                route.fulfill({
+                    status: 200,
+                    contentType: 'application/javascript',
+                    body: fs_1.default.readFileSync(LOCAL_BUNDLE_PATH)
+                });
+            }));
+            yield context.route(route => {
+                if (!route.href) {
+                    return false;
+                }
+                // Match CSS URLs that end with the same path structure  
+                return route.href.includes(stylesheetPattern);
+            }, (route) => __awaiter(this, void 0, void 0, function* () {
+                color_logger_1.default.log(`✅ Intercepted CSS request: ${route.request().url()}`);
+                color_logger_1.default.log(`   Serving local file: ${LOCAL_CSS_PATH}`);
+                route.fulfill({
+                    status: 200,
+                    contentType: 'text/css',
+                    body: fs_1.default.readFileSync(LOCAL_CSS_PATH)
+                });
+            }));
+            // 4. Open a new tab and navigate to your remote environment
+            const page = yield context.newPage();
+            yield page.goto(REMOTE_ENVIRONMENT_URL);
+            // 5. Clean up and save state when the page is closed (but others may still be open)
+            page.on('close', () => __awaiter(this, void 0, void 0, function* () {
+                const pages = context.pages();
+                if (pages.length <= 1) {
+                    // This was the last page, trigger full cleanup
+                    yield cleanup('last page closed');
+                    process.exit(0);
+                }
+                else {
+                    color_logger_1.default.debug(`Page closed, but ${pages.length - 1} pages still open. Keeping session alive.`);
+                }
+            }));
+            // 6. Watch the local bundle for changes and auto-reload
+            let reloadTimeout;
+            fs_1.default.watch(LOCAL_BUNDLE_PATH, (eventType) => {
+                if (eventType === 'change') {
+                    // Clear the previous timer if the file changes again quickly
+                    clearTimeout(reloadTimeout);
+                    // Wait 300ms for the bundler to finish writing the file before reloading
+                    reloadTimeout = setTimeout(() => __awaiter(this, void 0, void 0, function* () {
+                        color_logger_1.default.log(`\n🔄 Local bundle updated! Reloading the page...`);
+                        try {
+                            yield page.reload();
+                        }
+                        catch (err) {
+                            color_logger_1.default.error('⚠️ Could not reload page (browser might be closed).', err);
+                        }
+                    }), 300);
+                }
+            });
+        }))();
+    });
 }

package/dist/util/commandUtil.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleResults = exports.setupExecutionContext = void 0;
+const color_logger_1 = require("@tywalk/color-logger");
+const performanceUtil_1 = require("./performanceUtil");
+const setupExecutionContext = (options) => {
+    const logger = new color_logger_1.Logger('log');
+    if (options.verbose) {
+        logger.setDebug(true);
+        logger.setLevel('debug');
+    }
+    else {
+        logger.setLevel('info');
+    }
+    return { logger, tick: performance.now() };
+};
+exports.setupExecutionContext = setupExecutionContext;
+// Helper function to execute tasks and handle results
+const handleResults = (taskName, logger, tick, result) => {
+    if (taskName !== 'session') {
+        if (result === 0) {
+            logger.log(`[PCF Helper] ${taskName} completed successfully!`);
+        }
+        else {
+            logger.log(`[PCF Helper] ${taskName} completed with errors.`);
+        }
+        const tock = performance.now();
+        logger.log((0, performanceUtil_1.formatMsToSec)(`[PCF Helper] ${(0, performanceUtil_1.formatTime)(new Date())} ${taskName} finished in %is.`, tock - tick));
+    }
+    if (taskName !== 'session' || result === 1) {
+        process.exit(result);
+    }
+};
+exports.handleResults = handleResults;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tywalk/pcf-helper",
-  "version": "1.5.6",
+  "version": "1.6.0",
   "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/types/tasks/session-pcf.d.ts

@@ -1,3 +1,13 @@
+export type SessionOptions = {
+    verbose?: boolean;
+    url?: string;
+    script?: string;
+    stylesheet?: string;
+    bundle?: string;
+    css?: string;
+    config?: string;
+    watch?: boolean;
+};
 /**
  * Loads configuration for the session task, supporting a combination of config file, environment variables, and CLI arguments.
  * The priority order is: CLI arguments > environment variables > config file > defaults.
@@ -11,12 +21,14 @@ declare function loadConfig(config?: string): {
     remoteStylesheetToIntercept?: undefined;
     localCssPath?: undefined;
     localBundlePath?: undefined;
+    startWatch?: undefined;
 } | {
     remoteEnvironmentUrl: any;
     remoteScriptToIntercept: any;
     remoteStylesheetToIntercept: any;
     localCssPath: any;
     localBundlePath: any;
+    startWatch: any;
 };
 /**
  * Runs an ephemeral browser session that intercepts requests to the specified remote script and stylesheet URLs, serving local files instead.
@@ -27,6 +39,8 @@ declare function loadConfig(config?: string): {
  * @param remoteStylesheetToIntercept The full URL of the remote stylesheet to intercept (e.g., https://app.your-remote-environment.com/static/css/remote-control-styles.css).
  * @param localBundlePath The local file path to the JavaScript bundle that should be served when the remote script URL is requested.
  * @param localCssPath The local file path to the CSS file that should be served when the remote stylesheet URL is requested.
+ * @param startWatch Optional flag to start the session in watch mode. If true, the process will kick off "pcf-scripts start watch" in parallel to automatically rebuild the bundle on changes.
+ * @returns A promise that resolves when the session is set up and running. The session will continue to run until the process is exited, at which point it will clean up and save state.
  */
-declare function runSession(remoteEnvironmentUrl: string, remoteScriptToIntercept: string, remoteStylesheetToIntercept: string, localBundlePath: string, localCssPath: string): void;
+declare function runSession(remoteEnvironmentUrl: string, remoteScriptToIntercept: string, remoteStylesheetToIntercept: string, localBundlePath: string, localCssPath: string, startWatch?: boolean): Promise<void>;
 export { runSession, loadConfig };

package/types/util/commandUtil.d.ts

@@ -0,0 +1,6 @@
+import { Logger } from '@tywalk/color-logger';
+export declare const setupExecutionContext: (options: CommonOptions) => {
+    logger: Logger;
+    tick: number;
+};
+export declare const handleResults: (taskName: string, logger: Logger, tick: number, result: number) => void;