@capillarytech/cap-ui-dev-tools 1.0.0 → 1.2.0

package/README.md

@@ -1,13 +1,32 @@
-# Webpack Library Watcher Plugin
+# @capillarytech/cap-ui-dev-tools
 
-[![NPM version](https://img.shields.io/npm/v/cap-ui-dev-tools.svg)](https://www.npmjs.com/package/cap-ui-dev-tools)
-[![Build Status](https://img.shields.io/travis/your-username/cap-ui-dev-tools.svg)](https://travis-ci.org/your-username/cap-ui-dev-tools)
+[![NPM version](https://img.shields.io/npm/v/@capillarytech/cap-ui-dev-tools.svg)](https://www.npmjs.com/package/@capillarytech/cap-ui-dev-tools)
 
-A "zero-config" webpack plugin that **automatically aliases and hot-reloads** local libraries. Drastically reduces development iteration time when working with shared component libraries or utilities.
+**Development tools for Capillary UI projects** - Webpack hot-reload plugin + CapVision session recording
 
-This plugin solves the common "it takes forever to see my changes" problem in a micro-frontend or shared library architecture. It provides a single place to manage local library development, keeping your main webpack configuration clean.
+## 📦 What's Included
 
-## The Problem
+### 1. 🔥 Library Watcher Plugin (Webpack)
+A "zero-config" webpack plugin that **automatically aliases and hot-reloads** local libraries.
+
+### 2. 🎥 CapVision Session Recording (NEW in v1.1.0)
+Automatic session recording for WebdriverIO tests with HTML report integration.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install --save-dev @capillarytech/cap-ui-dev-tools
+```
+
+---
+
+## Feature 1: Webpack Library Watcher Plugin
+
+### The Problem
 
 When developing an application that consumes a local library, you typically have to manage two separate configurations:
 1.  **Webpack Alias:** You need to add a `resolve.alias` entry in your webpack config to point the library's package name to your local source code.
@@ -15,52 +34,37 @@ When developing an application that consumes a local library, you typically have
 
 Managing this in the main webpack config can be messy and error-prone.
 
-## The Solution: "Explicit Alias" Mode
+### The Solution
 
-This plugin provides a single, clean interface to handle both aliasing and watching. You explicitly tell the plugin which libraries to manage, and it handles the complex webpack configuration for you.
+This plugin provides a single, clean interface to handle both aliasing and watching.
 
 **Based on initial testing, this can reduce development iteration time by over 90% (e.g., from 3 minutes to under 10 seconds).**
 
 ![Architecture](architecture.png)
 
-## Installation
-
-```bash
-npm install --save-dev cap-ui-dev-tools
-```
-
-## Usage
-
-Add the plugin to your `webpack.config.js` file. It should only be active in `development` mode.
-
-### Configuration
+### Usage
 
 ```javascript
 // webpack.config.js
-const LibraryWatcherPlugin = require('cap-ui-dev-tools');
+const LibraryWatcherPlugin = require('@capillarytech/cap-ui-dev-tools');
+// or
+const LibraryWatcherPlugin = require('@capillarytech/cap-ui-dev-tools/webpack');
+
 const path = require('path');
 
 module.exports = {
   mode: 'development',
-  // ... your other webpack config
-
-  // NO need for a separate resolve.alias block for local development!
-  // The plugin handles it for you.
-  resolve: {
-    // ... any other aliases can stay here
-  },
-
+  
   plugins: [
-    // Ensure you have HotModuleReplacementPlugin enabled
     new webpack.HotModuleReplacementPlugin(),
-
+    
     new LibraryWatcherPlugin({
       // An array of libraries to alias and watch.
       libs: [
         {
           // The package name of the library (from its package.json).
           name: 'cap-creatives-ui',
-
+          
           // The absolute path to the library's source code.
           path: path.resolve(__dirname, '../cap-creatives-ui/src')
         },
@@ -69,12 +73,11 @@ module.exports = {
           path: path.resolve(__dirname, '../another-local-lib/src')
         }
       ],
-
+      
       // Enable verbose logging to the console.
       verbose: true,
-
+      
       // Optional: Options passed directly to chokidar.
-      // See https://github.com/paulmillr/chokidar#api for details.
       watchOptions: {
         // ..
       }
@@ -83,43 +86,191 @@ module.exports = {
 };
 ```
 
-## How It Works
+### How It Works
 
 1.  During initialization, the plugin reads your `libs` array.
-2.  It **programmatically modifies webpack's configuration**, adding a `resolve.alias` entry for each library. This means you don't have to.
+2.  It **programmatically modifies webpack's configuration**, adding a `resolve.alias` entry for each library.
 3.  It then uses `chokidar` to watch the provided `path` for each library.
 4.  It adds the watched paths to webpack's `contextDependencies` to make webpack aware of them.
 5.  When a file change is detected, the plugin tells webpack's own watcher that the file has been invalidated, triggering a standard recompilation and HMR update.
 
-## Troubleshooting
+---
+
+## Feature 2: CapVision Session Recording (NEW ✨)
+
+### Quick Start
+
+```javascript
+// wdio.conf.js
+const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools/capvision');
+
+const capVisionHooks = createWDIOCapVisionHooks({
+  recordingsOutputDir: './reports/recordings',
+  enabledClusters: ['staging', 'production']
+});
+
+exports.config = {
+  onPrepare: capVisionHooks.onPrepare,
+  beforeTest: (test, context) => capVisionHooks.beforeTest(test, context, browser),
+  afterTest: capVisionHooks.afterTest,
+  onComplete: capVisionHooks.onComplete
+};
+```
+
+### Features
+
+- ✅ **Automatic Recording** - Zero manual intervention
+- ✅ **Page Refresh Support** - Maintains recording across navigations
+- ✅ **HTML Report Integration** - Auto-embeds playback in reports
+- ✅ **Smart Filtering** - Configure by cluster, module, test type
+- ✅ **Console Recording** - Captures console logs with UI interactions
+- ✅ **Privacy First** - Auto-masks sensitive inputs
+- ✅ **Framework Agnostic Core** - Works with WebdriverIO, Playwright, Puppeteer
+
+### Full Documentation
+
+See [CAPVISION_USAGE.md](./CAPVISION_USAGE.md) for complete CapVision documentation including:
+- Configuration options
+- Usage patterns
+- API reference
+- Troubleshooting
+- Examples
+
+---
 
-### Changes are not detected.
+## 📦 Package Exports
+
+```javascript
+// Webpack Plugin (default export)
+const LibraryWatcherPlugin = require('@capillarytech/cap-ui-dev-tools');
+// or explicitly
+const LibraryWatcherPlugin = require('@capillarytech/cap-ui-dev-tools/webpack');
+
+// CapVision Recorder
+const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools/capvision');
+// or from main export
+const { createWDIOCapVisionHooks } = require('@capillarytech/cap-ui-dev-tools');
+
+// Full CapVision module
+const capVision = require('@capillarytech/cap-ui-dev-tools').capVisionRecorder;
+```
+
+---
+
+## 🎯 Use Cases
+
+### For UI Library Developers
+Use **LibraryWatcherPlugin** to:
+- Develop and test shared components in real-time
+- Eliminate slow "npm link" workflows
+- See changes instantly in consuming applications
+
+### For QA/Test Engineers
+Use **CapVision Recorder** to:
+- Automatically record test sessions
+- Debug test failures visually
+- Share test recordings with developers
+- Enhance HTML reports with playback
+
+### For Full-Stack Teams
+Use **both** for:
+- Fast UI development iteration
+- Automated test documentation
+- Better collaboration between dev and QA
+
+---
+
+## 📚 Documentation
+
+- **Webpack Plugin**: See sections above
+- **CapVision Recorder**: See [CAPVISION_USAGE.md](./CAPVISION_USAGE.md)
+- **Integration Guide**: See [INTEGRATION_GUIDE.md](./INTEGRATION_GUIDE.md)
+- **Testing Guide**: See [TESTING_GUIDE.md](./TESTING_GUIDE.md)
+
+---
+
+## 🔧 Troubleshooting
+
+### Webpack Plugin
+
+#### Changes are not detected
 -   **Check Paths**: Make sure the `path` in the `libs` configuration is an **absolute path** pointing to the **source code** of your library. Use `path.resolve(__dirname, '..', 'your-lib')`.
--   **Check Name**: Ensure the `name` property matches the package name your host application is trying to import (e.g., `'cap-creatives-ui'`).
--   **Enable `verbose` mode**: Set `verbose: true` to see detailed logs. It will confirm which aliases are being created and which paths are being watched.
+-   **Check Name**: Ensure the `name` property matches the package name your host application is trying to import.
+-   **Enable `verbose` mode**: Set `verbose: true` to see detailed logs.
+
+### CapVision Recorder
+
+See [CAPVISION_USAGE.md](./CAPVISION_USAGE.md#troubleshooting) for common issues and solutions.
 
-## For Maintainers: Publishing to NPM
+---
 
-To publish a new version of this package to the NPM registry, follow these steps.
+## 📝 Changelog
 
-1.  **Update Version Number**:
-    -   Update the `version` field in `package.json` according to [Semantic Versioning (SemVer)](https://semver.org/).
+### v1.1.0 (2025-11-12)
+- ✨ **NEW**: Added CapVision session recording module
+- ✅ Support for automatic test recording
+- ✅ HTML report enhancement with playback
+- ✅ WebdriverIO integration via hooks
+- ✅ Framework-agnostic core
+- 📚 Comprehensive documentation added
+
+### v1.0.0 (Initial Release)
+- ✅ Webpack Library Watcher Plugin
+- ✅ Hot-reload for local libraries
+- ✅ Zero-config webpack integration
+
+---
+
+## 🚀 Publishing to NPM
+
+For maintainers:
+
+1.  **Update Version Number**: Update the `version` field in `package.json` according to [SemVer](https://semver.org/).
 
 2.  **Log in to NPM**:
-    -   If you are not already logged in, run the following command and enter your credentials.
     ```bash
     npm login
     ```
 
 3.  **Perform a Dry Run**:
-    -   It is highly recommended to check what will be published without actually publishing it.
     ```bash
     npm publish --dry-run
     ```
-    -   This will list all files being included in the package. Verify that only necessary files (`src/LibraryWatcherPlugin.js`, `package.json`, `README.md`) are present.
 
 4.  **Publish**:
-    -   Once you have verified the package contents, run the publish command:
     ```bash
     npm publish
     ```
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! Please:
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+---
+
+## 📄 License
+
+ISC License
+
+---
+
+## 🙏 Acknowledgments
+
+- **CapVision**: Session recording solution (powered by rrweb)
+- **Chokidar**: File watching library
+- **Webpack**: Module bundler
+- **WebdriverIO**: Test automation framework
+
+---
+
+**Made with ❤️ by Capillary Technologies**
+
+**Version**: 1.1.0  
+**Includes**: Webpack Hot-Reload Plugin + CapVision Session Recording

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "@capillarytech/cap-ui-dev-tools",
-  "version": "1.0.0",
-  "main": "src/LibraryWatcherPlugin.js",
+  "version": "1.2.0",
+  "description": "Development tools for Capillary UI projects including webpack hot-reload plugin and CapVision session recording",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./webpack": "./src/LibraryWatcherPlugin.js",
+    "./capvision": "./src/capvision-recorder/index.js",
+    "./package.json": "./package.json"
+  },
   "files": [
-    "src/LibraryWatcherPlugin.js",
-    "README.md"
+    "src/",
+    "README.md",
+    "CAPVISION_USAGE.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -19,12 +27,24 @@
   "homepage": "https://github.com/cap-ui-dev-tools/cap-ui-dev-tools#readme",
   "scripts": {
     "start": "webpack serve",
-    "test": "jest"
+    "test": "jest",
+    "test:integration": "node test-integration.js",
+    "lint": "eslint src/**/*.js"
   },
-  "keywords": [],
-  "author": "",
+  "keywords": [
+    "webpack",
+    "plugin",
+    "hot-reload",
+    "library",
+    "development",
+    "capvision",
+    "session-recording",
+    "webdriverio",
+    "test-automation",
+    "capillary"
+  ],
+  "author": "Capillary Technologies",
   "license": "ISC",
-  "description": "",
   "dependencies": {
     "chokidar": "^3.6.0"
   },
@@ -37,6 +57,15 @@
     "webpack-hot-middleware": "^2.26.1"
   },
   "peerDependencies": {
-    "webpack": "^5.0.0"
+    "webpack": "^5.0.0",
+    "webdriverio": ">=7.0.0 || >=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "webpack": {
+      "optional": false
+    },
+    "webdriverio": {
+      "optional": true
+    }
   }
-}
+}

package/src/LibraryWatcherPlugin.js

@@ -2,8 +2,34 @@ const chokidar = require('chokidar');
 const path = require('path');
 const fs = require('fs');
 
+/**
+ * @typedef {object} LibraryOption
+ * @property {string} name The package name of the library (e.g., 'my-shared-lib').
+ * @property {string} path The absolute path to the library's source code directory.
+ */
+
+/**
+ * @typedef {object} PluginOptions
+ * @property {LibraryOption[]} libs An array of library objects to alias and watch.
+ * @property {boolean} [verbose=false] If true, prints detailed logs to the console.
+ * @property {import('chokidar').WatchOptions} [watchOptions] Options object passed directly to Chokidar.
+ */
+
+/**
+ * A webpack plugin that automatically aliases local libraries and triggers hot-reloading on change.
+ * This eliminates the need for manual rebuilds or complex webpack configuration when developing
+ * applications that consume local, unpublished libraries.
+ */
 class LibraryWatcherPlugin {
+  /**
+   * Creates an instance of LibraryWatcherPlugin.
+   * @param {PluginOptions} options The plugin options.
+   */
   constructor(options = {}) {
+    /**
+     * @private
+     * @type {PluginOptions}
+     */
     this.options = {
       libs: [],
       watchOptions: {
@@ -18,11 +44,30 @@ class LibraryWatcherPlugin {
       verbose: false,
       ...options
     };
+
+    /**
+     * @private
+     * @type {import('chokidar').FSWatcher | null}
+     */
     this.watcher = null;
+
+    /**
+     * @private
+     * @type {string | null}
+     */
     this.entryFile = null; // To hold the path to the host app's entry file
+
+    /**
+     * @private
+     * @type {string[]}
+     */
     this.watchPaths = this.options.libs.map(lib => lib.path);
   }
 
+  /**
+   * The main entry point for the webpack plugin.
+   * @param {import('webpack').Compiler} compiler The webpack compiler instance.
+   */
   apply(compiler) {
     if (compiler.options.mode !== 'development' || !this.options.libs.length) {
       return;
@@ -80,6 +125,10 @@ class LibraryWatcherPlugin {
     });
   }
 
+  /**
+   * Initializes the Chokidar file watcher if it hasn't been started already.
+   * @private
+   */
   startWatcher() {
     if (this.watcher || !this.watchPaths.length) return;
 
@@ -115,6 +164,10 @@ class LibraryWatcherPlugin {
     }
   }
 
+  /**
+   * Gracefully stops the file watcher.
+   * @private
+   */
   stopWatcher() {
     if (this.watcher) {
       this.watcher.close();