@metricinsights/pp-dev 0.19.0 → 1.0.0-beta.1

package/dist/README.md

@@ -45,142 +45,79 @@ import ppDev from '@metricinsights/pp-dev';
 // Plugin only (for Vite integration)
 import { vitePPDev } from '@metricinsights/pp-dev/plugin';
 
-// Helpers only (for utility functions)
-import { helpers } from '@metricinsights/pp-dev/helpers';
+// Helpers only (defineConfig and utility functions)
+import { defineConfig } from '@metricinsights/pp-dev/helpers';
 
 // Client assets (for development UI)
 import '@metricinsights/pp-dev/client/css/client.css';
 ```
 
-**Available Exports**:
-
-- **Main**: Complete pp-dev functionality with CLI and plugins
-- **Plugin**: Vite plugin for integration with build tools
-- **Helpers**: Utility functions for authentication and configuration
-- **Client**: Development UI assets and styles
-
-## 🚀 Performance & Build System
-
-The pp-dev package includes optimized startup performance and build system with multiple strategies:
-
-### Quick Start
-
-```bash
-# Standard build (parallel)
-npm run build
-
-# Fast development build
-npm run build:fast
-
-# Watch mode for development
-npm run build:watch
-
-# Bundle analysis
-npm run build:analyze
-
-# Performance profiling
-npm run startup:profile
-
-# Startup optimization
-npm run startup:optimize
-```
-
-### Performance Features
-
-- **40-50% faster startup** with intelligent caching
-- **60-70% faster subsequent starts** with connection pooling
-- **Lazy loading** of heavy modules (jsdom, esbuild)
-- **API response caching** with configurable TTL
-- **HTTP connection pooling** for reduced overhead
-- **Startup profiling** with detailed performance analysis
-- **Intelligent dependency optimization** based on profiling data
-
-### Build Features
-
-- **Parallel builds** for 40-60% faster build times
-- **Enhanced tree-shaking** for smaller bundles
-- **Multiple output formats** (ESM, CJS, Types)
-- **Bundle analysis** with visualizer support
-- **ESBuild integration** for faster TypeScript compilation
-- **Build optimization scripts** for performance tuning
-
-### Startup Optimization
-
-The new startup optimization system in v0.11.0 provides:
-
-- **Performance Monitoring**: Real-time startup time tracking and analysis
-- **Cache Optimization**: Intelligent cache management for config and API responses
-- **Dependency Analysis**: Identification of performance bottlenecks
-- **Optimization Suggestions**: Automated recommendations for performance improvements
-
-Run the startup optimizer to analyze and improve your development environment:
-
-```bash
-npm run startup:optimize
-```
-
-📖 See [BUILD_IMPROVEMENTS.md](./BUILD_IMPROVEMENTS.md) for build details.
-📖 See [STARTUP_PERFORMANCE.md](./STARTUP_PERFORMANCE.md) for performance details.
-
 ## Configuration
 
 ### Configuration File
 
 Create a configuration file named `pp-dev.config` with one of these extensions:
 
+- `.ts` (recommended)
 - `.js` or `.cjs` (for CommonJS)
-- `.ts` (for TypeScript)
 - `.json`
 
 Alternatively, you can define configuration in your `package.json` using the `pp-dev` key.
 
 ### Configuration Examples
 
-#### JavaScript (CommonJS)
-
-```javascript
-// pp-dev.config.js
-
-/**
- * @type {import('@metricinsights/pp-dev').PPDevConfig}
- */
-module.exports = {
-  backendBaseURL: 'https://mi.company.com',
-  appId: 1,
-  v7Features: true,
-  miHudLess: true,
-  integrateMiTopBar: true,
-};
-```
-
-#### TypeScript
+#### TypeScript (recommended)
 
 ```typescript
 // pp-dev.config.ts
+import { defineConfig } from '@metricinsights/pp-dev';
+
+export default defineConfig({
+  mi: {
+    url: 'https://mi.company.com',
+    token: process.env.MI_ACCESS_TOKEN,
+    mode: 'standalone',
+    apiVersion: 7,
+  },
+  app: {
+    id: 123,
+    type: 'template',
+  },
+});
+```
 
-import { PPDevConfig } from '@metricinsights/pp-dev';
+#### JavaScript (CommonJS)
 
-const config: PPDevConfig = {
-  backendBaseURL: 'https://mi.company.com',
-  appId: 1,
-  v7Features: true,
-  miHudLess: true,
-  integrateMiTopBar: true,
-};
+```javascript
+// pp-dev.config.js
+const { defineConfig } = require('@metricinsights/pp-dev');
 
-export default config;
+module.exports = defineConfig({
+  mi: {
+    url: 'https://mi.company.com',
+    mode: 'standalone',
+    apiVersion: 7,
+  },
+  app: {
+    id: 123,
+    type: 'template',
+  },
+});
 ```
 
 #### JSON
 
 ```json
-// pp-dev.config.json
 {
-  "backendBaseURL": "https://mi.company.com",
-  "appId": 1,
-  "v7Features": true,
-  "miHudLess": true,
-  "integrateMiTopBar": true
+  "mi": {
+    "url": "https://mi.company.com",
+    "mode": "standalone",
+    "apiVersion": 7
+  },
+  "app": {
+    "id": 123,
+    "type": "template"
+  }
 }
 ```
 
@@ -189,176 +126,138 @@ export default config;
 ```json
 {
   "name": "my-portal-page",
-  "version": "1.0.0",
   "pp-dev": {
-    "backendBaseURL": "https://mi.company.com",
-    "appId": 1,
-    "v7Features": true,
-    "miHudLess": true,
-    "integrateMiTopBar": true
+    "mi": {
+      "url": "https://mi.company.com",
+      "mode": "standalone"
+    },
+    "app": {
+      "id": 123
+    }
   }
 }
 ```
 
 ## Configuration Options
 
-> **Version Compatibility**: This documentation covers pp-dev v0.11.0+. Some options may not be available in older versions. Check the [CHANGELOG](./CHANGELOG.md) for version-specific information.
-
-### Required Options
-
-| Option           | Type   | Description                                                                 |
-| ---------------- | ------ | --------------------------------------------------------------------------- |
-| `backendBaseURL` | string | URL of the Metric Insights instance for API proxying                        |
-| `portalPageId`   | number | ID of the Portal Page for variable values (deprecated, use `appId` instead) |
-| `appId`          | number | ID of the Portal Page for variable values (synonym for `portalPageId`)      |
+### `mi` — Metric Insights connection
 
-### Optional Options
+| Field        | Type                              | Default        | Description                                               |
+|--------------|-----------------------------------|----------------|-----------------------------------------------------------|
+| `url`        | `string`                          | —              | URL of the Metric Insights instance                       |
+| `token`      | `string`                          | `MI_ACCESS_TOKEN` env | Personal access token for authentication           |
+| `mode`       | `'standalone' \| 'embedding'`     | `'standalone'` | Standalone hides the MI navigation; embedding keeps it    |
+| `include`    | `'top-bar' \| 'shared-components'`| —              | Bundle MI top-bar assets into the build (requires `standalone`) |
+| `apiVersion` | `6 \| 7`                          | `7`            | MI API version to target                                  |
 
-| Option                 | Type              | Default                       | Description                                                                                                                                                                                                                                                                     |
-| ---------------------- | ----------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `miHudLess`            | boolean           | `false`                       | Disables Metric Insights navigation bar in development                                                                                                                                                                                                                          |
-| `integrateMiTopBar`    | boolean \| object | `false`                       | Integrates MI Top Bar and scripts into the App build (requires `miHudLess: true`). When `true`, enables both `addRootElement` and `addSharedComponentsScripts`. When an object, allows selective enabling: `{ addRootElement?: boolean, addSharedComponentsScripts?: boolean }` |
-| `templateLess`         | boolean           | `false`                       | Disables template variable transformation                                                                                                                                                                                                                                       |
-| `enableProxyCache`     | boolean           | `true`                        | Enables caching of proxied requests                                                                                                                                                                                                                                             |
-| `proxyCacheTTL`        | number            | `600000`                      | Cache TTL in milliseconds (10 minutes)                                                                                                                                                                                                                                          |
-| `disableSSLValidation` | boolean           | `false`                       | Disables SSL certificate validation for proxy requests                                                                                                                                                                                                                          |
-| `imageOptimizer`       | boolean \| object | `true`                        | Controls image optimization. See [vite-plugin-image-optimizer](https://www.npmjs.com/package/vite-plugin-image-optimizer#plugin-options) for object options                                                                                                                     |
-| `outDir`               | string            | `dist`                        | Output directory for builds                                                                                                                                                                                                                                                     |
-| `distZip`              | boolean \| object | `true`                        | Controls build output zipping. Object options: `{ outDir?: string, outFileName?: string }`                                                                                                                                                                                      |
-| `syncBackupsDir`       | string            | `backups`                     | Directory for asset backups from MI server                                                                                                                                                                                                                                      |
-| `v7Features`           | boolean           | `false`                       | Enables Metric Insights v7 features                                                                                                                                                                                                                                             |
-| `personalAccessToken`  | string            | `process.env.MI_ACCESS_TOKEN` | Personal Access Token for the MI instance                                                                                                                                                                                                                                       |
+### `app` — Portal Page identity
 
-### integrateMiTopBar Details
+| Field  | Type                       | Default                  | Description                                                 |
+|--------|----------------------------|--------------------------|-------------------------------------------------------------|
+| `id`   | `number`                   | —                        | Portal Page ID used to fetch template variables             |
+| `type` | `'template' \| 'page'`     | `'template'`             | `template` syncs back to MI; `page` is standalone-only      |
+| `name` | `string`                   | `package.json#name`      | Template name on the MI instance (usually auto-resolved)    |
 
-The `integrateMiTopBar` option allows you to integrate the Metric Insights Top Bar and scripts directly into your application build. This is useful when you want to:
+### `proxy` — Request proxying
 
-1. **Customize the Top Bar**: Modify the appearance and behavior of the MI navigation
-2. **Bundle Integration**: Include MI scripts in your build instead of loading them dynamically
-3. **Offline Development**: Work with MI features even when disconnected from the server
+| Field               | Type      | Default  | Description                                          |
+|---------------------|-----------|----------|------------------------------------------------------|
+| `cache`             | `boolean` | `true`   | Enable caching of proxied requests                   |
+| `cacheTtl`          | `number`  | `600000` | Cache TTL in milliseconds (10 minutes)               |
+| `tls.allowSelfSigned` | `boolean` | `false` | Allow self-signed SSL certificates on the MI server |
 
-**Important**: This option can only be enabled when `miHudLess` is set to `true`.
+### `build` — Build output
 
-#### Configuration Options
+| Field               | Type                                                        | Default  | Description                                                                          |
+|---------------------|-------------------------------------------------------------|----------|--------------------------------------------------------------------------------------|
+| `outDir`            | `string`                                                    | `'dist'` | Output directory                                                                     |
+| `zip`               | `boolean \| { fileName?: string; outDir?: string; inDir?: string }` | `true` | Zip build output. Object form customizes filename and directories.        |
+| `versionFile`       | `boolean \| { enabled?: boolean; fileNameTemplate?: string }` | `true` | Write a VERSION file into the build                                                  |
+| `imageOptimisations`| `boolean \| Record<string, unknown>`                        | `true`   | Image optimization. See [vite-plugin-image-optimizer](https://www.npmjs.com/package/vite-plugin-image-optimizer#plugin-options) for object options |
 
-`integrateMiTopBar` can be configured in two ways:
+### `inspector` — Request Inspector
 
-**1. Boolean (Simple)**
+| Field          | Type      | Default     | Description                                                    |
+|----------------|-----------|-------------|----------------------------------------------------------------|
+| `enabled`      | `boolean` | `true`      | Enable the request inspector                                   |
+| `maxMemory`    | `number`  | `104857600` | Max total body memory (bytes) before oldest entries are evicted (default 100 MB) |
+| `captureLimit` | `number`  | `10485760`  | Max body size captured per request/response (bytes, default 10 MB). Larger bodies are stored truncated. |
 
-- `true`: Enables both `addRootElement` and `addSharedComponentsScripts`
-- `false`: Disables integration (default)
+### `sync` — Template sync
 
-**2. Object (Advanced)**
+| Field        | Type     | Default     | Description                             |
+|--------------|----------|-------------|-----------------------------------------|
+| `backupsDir` | `string` | `'backups'` | Directory for backups from the MI server |
 
-- `addRootElement`: Adds `<div id="mi-react-root">` element to the body for React mounting
-- `addSharedComponentsScripts`: Adds MI shared component scripts and styles:
-  - `/auth/info.js` - Authentication info script
-  - `/js/main.js` - Main MI JavaScript bundle
-  - `/css/main.css` - MI stylesheet
+### Validation
 
-#### Examples
-
-**Simple boolean configuration:**
-
-```javascript
-// pp-dev.config.js
-module.exports = {
-  backendBaseURL: 'https://mi.company.com',
-  appId: 1,
-  miHudLess: true, // Required: Disable dynamic MI scripts
-  integrateMiTopBar: true, // Enable: Integrate Top Bar into build
-};
-```
+pp-dev validates your config at startup and reports problems clearly:
 
-**Advanced object configuration (selective features):**
+| Condition | Behaviour |
+|---|---|
+| `mi.include` set + `mi.mode !== 'standalone'` | error |
+| `mi.url` missing + `mi.mode === 'embedding'` or `app.type === 'template'` | error |
+| `mi.url` missing + `mi.mode === 'standalone'` + `app.type === 'page'` | warning |
+| `app.type === 'template'` without `app.id` | error |
+| `app.type === 'page'` + `mi.mode === 'standalone'` without `app.id` | error |
+| `app.name` missing and no `package.json#name` | error |
 
-```javascript
-// pp-dev.config.js
-module.exports = {
-  backendBaseURL: 'https://mi.company.com',
-  appId: 1,
-  miHudLess: true,
-  integrateMiTopBar: {
-    addRootElement: true, // Add root element for React
-    addSharedComponentsScripts: true, // Add MI scripts and styles
-  },
-};
-```
+### Environment Variables
 
-**Partial integration (scripts only, manual root element):**
-
-```javascript
-// pp-dev.config.js
-module.exports = {
-  backendBaseURL: 'https://mi.company.com',
-  appId: 1,
-  miHudLess: true,
-  integrateMiTopBar: {
-    addRootElement: false, // Don't add root element
-    addSharedComponentsScripts: true, // Add MI scripts and styles
-  },
-};
-```
-
-### v7Features Details
-
-When enabled (`true`), this option:
-
-1. Changes development path from `/pt/<portal-page-name>` to `/pl/<portal-page-name>`
-2. Updates Code Sync feature to use v7.1.0+ URLs
-
-### Personal Access Token
-
-The `personalAccessToken` option allows you to authenticate with the Metric Insights instance. You can set it in your configuration or use the `MI_ACCESS_TOKEN` environment variable.
-
-Example with authentication and Top Bar integration:
-
-```javascript
-// pp-dev.config.js
-module.exports = {
-  backendBaseURL: 'https://mi.company.com',
-  appId: 1,
-  personalAccessToken: process.env.MI_ACCESS_TOKEN,
-  miHudLess: true,
-  integrateMiTopBar: true,
-};
-```
-
-**Environment Variable**: Set `MI_ACCESS_TOKEN` in your `.env` file:
-
-```bash
-MI_ACCESS_TOKEN=your_token_here
-```
+| Variable          | Description                                     |
+|-------------------|-------------------------------------------------|
+| `MI_ACCESS_TOKEN` | Default value for `mi.token` when not set in config |
 
 **Local development and network exposure**: pp-dev is a **development** tool. It assumes a trusted machine. Personal access tokens and session helpers are still sensitive: they can authenticate to your Metric Insights backend as you.
 
-- Prefer binding the dev server to **`localhost`** when you do not need access from other devices. If you use **`--host`** (or equivalent) so the app listens on **all interfaces** or your LAN, other machines on the same network can reach the dev server and its dev-only routes (for example the in-browser token login flow). Treat that like exposing credentials: use only on networks you trust, or restrict access with your OS firewall.
-- Do not commit real tokens; keep them in `.env` (gitignored) or your secret store. Avoid sharing screen recordings or logs that contain `MI_ACCESS_TOKEN` or bearer tokens.
-
-### Enhanced Authentication (v0.11.0+)
-
-The new authentication system in v0.11.0 provides:
-
-- **Automatic Environment Loading**: Automatically loads `MI_*` environment variables from `.env` files
-- **Token Validation**: Enhanced token validation and error handling
-- **Secure Headers**: Automatic header management for authenticated requests
-- **Connection Pooling**: Optimized HTTP connections for better performance
+- Prefer binding the dev server to **`localhost`** when you do not need access from other devices. If you use **`--host`** (or equivalent) so the app listens on **all interfaces** or your LAN, other machines on the same network can reach the dev server and its dev-only routes. Treat that like exposing credentials: use only on networks you trust, or restrict access with your OS firewall.
+- Do not commit real tokens; keep them in `.env` (gitignored) or your secret store.
 
-**Supported Environment Variables**:
+## Migrating from 0.x
 
-- `MI_ACCESS_TOKEN`: Personal access token for authentication
-- `MI_BACKEND_URL`: Alternative to `backendBaseURL` in config
-- `MI_APP_ID`: Alternative to `appId` in config
-
-**Automatic Loading**: pp-dev automatically detects and loads these variables from your project's `.env` file:
+Run the built-in codemod to upgrade your config automatically:
 
 ```bash
-# .env
-MI_ACCESS_TOKEN=your_personal_access_token
-MI_BACKEND_URL=https://mi.company.com
-MI_APP_ID=123
+npx @metricinsights/pp-dev migrate
 ```
 
+Options:
+
+| Option | Description |
+|---|---|
+| `[config]` | Path to config file (auto-detected if omitted) |
+| `--dry-run` | Preview the migrated output without writing |
+| `--format ts\|js\|json` | Override output format |
+| `--output <file>` | Write to a specific file instead of overwriting |
+| `--no-backup` | Skip creating a `.bak` backup of the original |
+
+The command detects flat 0.x configs and legacy `pp-watch.config.*` files, converts them to the new grouped format, and writes a `.bak` backup before overwriting.
+
+**Field mapping** (0.x → 1.0):
+
+| 0.x | 1.0 |
+|---|---|
+| `backendBaseURL` | `mi.url` |
+| `personalAccessToken` | `mi.token` |
+| `miHudLess: true` | `mi.mode: 'standalone'` |
+| `miHudLess: false` | `mi.mode: 'embedding'` |
+| `integrateMiTopBar: true` | `mi.mode: 'standalone'`, `mi.include: 'top-bar'` |
+| `integrateMiTopBar: { addSharedComponentsScripts: true }` | `mi.include: 'shared-components'` |
+| `v7Features: true` | `mi.apiVersion: 7` |
+| `v7Features: false` | `mi.apiVersion: 6` |
+| `appId` / `portalPageId` | `app.id` |
+| `templateName` | `app.name` (usually omit — auto-resolved from `package.json#name`) |
+| `templateLess: true` | `app.type: 'page'` |
+| `templateLess: false` | `app.type: 'template'` |
+| `enableProxyCache` | `proxy.cache` |
+| `proxyCacheTTL` | `proxy.cacheTtl` |
+| `disableSSLValidation: true` | `proxy.tls.allowSelfSigned: true` |
+| `distZip` | `build.zip` |
+| `versionPlugin` | `build.versionFile` |
+| `imageOptimizer` | `build.imageOptimisations` |
+| `outDir` | `build.outDir` |
+| `syncBackupsDir` | `sync.backupsDir` |
+
 ## CLI Commands
 
 ### Global Options
@@ -388,14 +287,11 @@ pp-dev [root] [options]
 
 **Development Shortcuts**:
 
-- `p` - Start/stop performance profiler (v0.11.0+)
 - `l` - Proxy re-login (refresh authentication)
 - `r` - Restart dev server
 - `u` - Show server URLs
 - `q` - Quit dev server
 
-**Performance Profiling**: Use the `p` shortcut to start/stop the Node.js profiler for detailed performance analysis during development.
-
 ### Next.js Development
 
 ```bash
@@ -423,6 +319,20 @@ pp-dev build [options]
 | `--assetsDir <dir>`  | `assets`  | Assets directory under outDir     |
 | `--changelog [file]` | `true`    | Create changelog file             |
 
+### Migration
+
+```bash
+pp-dev migrate [config] [options]
+```
+
+| Option | Description |
+|---|---|
+| `[config]` | Config file to migrate (auto-detected if omitted) |
+| `--dry-run` | Preview output without writing |
+| `--format ts\|js\|json` | Output format |
+| `--output <file>` | Write to a specific path |
+| `--no-backup` | Skip `.bak` backup |
+
 ### Changelog Generation
 
 ```bash
@@ -454,7 +364,7 @@ pp-dev generate-icon-font [source] [destination] [options]
 
 ## Next.js Integration
 
-1. Add pp-dev configuration to your project root
+1. Add a `pp-dev.config.ts` to your project root
 2. Update `package.json` scripts:
    ```json
    {
@@ -478,6 +388,68 @@ module.exports = withPPDev({
 
 For custom build configuration, create a `vite.config` file. See [Vite Configuration](https://vitejs.dev/config/) for details.
 
+## Request Inspector
+
+pp-dev includes a built-in request inspector that captures every proxied and locally-served HTTP request made during development. It is enabled by default.
+
+### Web UI
+
+Open `http://localhost:3000/@pp-dev/inspector` (replace port as needed) in any browser tab while the dev server is running. The UI shows:
+
+- A scrollable list of captured requests with method, status, source badge, and timing
+- Full request and response headers, with a **Copy** button per section
+- Request and response bodies rendered as text for JSON/HTML/CSS/plain-text content types, with **Copy** and **Save** buttons
+- Binary bodies (images, fonts, archives) show metadata only and offer a **Save** button
+- A **Clear** button in the top-right removes all stored entries
+
+### Source badges
+
+Each request in the list displays a colored letter badge to the left of the HTTP status:
+
+| Badge | Color  | Meaning                                      |
+|-------|--------|----------------------------------------------|
+| `P`   | Purple | Forwarded to the upstream Metric Insights server (proxy) |
+| `C`   | Amber  | Served from the local proxy cache             |
+| `L`   | Grey   | Served locally (static file, dev route, etc.) |
+
+### Console banner
+
+The dev panel script prints a one-line banner to the browser DevTools console when the page loads:
+
+```
+pp-dev  🔍 Request Inspector  →  http://localhost:3000/@pp-dev/inspector
+```
+
+The message persists in DevTools history so it is visible even when you open the console after the page has loaded.
+
+### REST API
+
+The inspector also exposes a lightweight JSON API, useful for tooling and AI agents:
+
+| Method   | Path                    | Description                                 |
+|----------|-------------------------|---------------------------------------------|
+| `GET`    | `/@api/requests`        | Paginated list of captured requests (metadata only, no bodies) |
+| `GET`    | `/@api/requests/:id`    | Full entry including captured request/response bodies (base64-encoded) |
+| `GET`    | `/@api/requests/stats`  | Store stats: entry count, memory usage, limits |
+| `DELETE` | `/@api/requests`        | Clear all stored entries                    |
+
+`GET /@api/requests` accepts `?limit=` (default 50) and `?offset=` query parameters for pagination.
+
+Bodies in `GET /@api/requests/:id` are returned as base64 strings in `requestBody` / `responseBody` fields alongside `requestContentType` / `responseContentType`. A `*Truncated: true` flag indicates the body exceeded `captureLimit` and was cut off.
+
+### Configuration
+
+```typescript
+// pp-dev.config.ts
+export default defineConfig({
+  inspector: {
+    enabled: true,         // set to false to disable entirely
+    maxMemory: 100 * 1024 * 1024,   // evict oldest entries above 100 MB
+    captureLimit: 10 * 1024 * 1024, // capture at most 10 MB per body
+  },
+});
+```
+
 ## Troubleshooting
 
 ### Common Issues
@@ -510,8 +482,8 @@ If you encounter an error like "Next.js is required but not available":
 #### Version Compatibility
 
 - **pp-dev** requires Next.js version 15 or higher (but less than 17)
-- **Node.js** version 20 or higher is required
-- **TypeScript** version 4.2 or higher is supported
+- **Node.js** version 24 or higher is required
+- **TypeScript** version 5 or higher is recommended
 
 ### Getting Help