@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/feature-api/copy-operation.md

@@ -0,0 +1,427 @@
+# Copy Operations Documentation
+
+## Overview
+
+The Copy Operations system is a build-time mechanism that copies files and directories from `node_modules` packages to specific locations in your application servers (frontend, backend, mobile, etc.). This ensures that necessary assets, workers, and modules are available at runtime in the correct locations.
+
+This system is framework-agnostic and can be used with any Node.js-based application that needs to distribute package assets to specific runtime locations.
+
+## Purpose
+
+The copy operations system serves several critical purposes:
+
+1. **Asset Distribution**: Copies static assets (like binary files, images, etc.) from npm packages to public directories
+2. **Worker Files**: Places web workers in accessible public directories for browser execution
+3. **Module Generation**: Automatically generates module configuration files for dynamic imports
+4. **Build Optimization**: Ensures assets are available without requiring runtime resolution from node_modules
+
+## Architecture
+
+### Configuration Files
+
+Copy operations are defined in two types of configuration files:
+
+#### 1. Package-Level Configuration (`package.json`)
+
+Individual packages can define their own copy operations in the `cdecode` section:
+
+```json
+{
+    "name": "@your-org/your-package-browser",
+    "cdecode": {
+        "copyOperations": [
+            {
+                "packageName": "@your-org/your-package-browser",
+                "sourcePath": "assets/data-file.bin",
+                "destPath": "../public/files/data-file.bin",
+                "generateModule": false
+            }
+        ]
+    }
+}
+```
+
+#### 2. Application-Level Configuration
+
+Applications define centralized copy operations in their configuration files. The location and naming can vary by project structure:
+
+- **Frontend Server**: `app/cde-webconfig.json` or `config.json`
+- **Backend Server**: `config.json`
+- **Mobile App**: `config.json`
+- **Custom Apps**: Any JSON configuration file you choose
+
+### Configuration Schema
+
+Each copy operation object supports the following properties:
+
+| Property         | Type    | Required | Description                                                                                                                               |
+| ---------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `packageName`    | string  | Yes      | The npm package name to copy from (e.g., `@my-org/my-package-browser`)                                                                    |
+| `sourcePath`     | string  | No       | Relative path within the package's `lib` directory. If omitted, copies the entire package                                                 |
+| `destPath`       | string  | Yes      | Destination path relative to the application's configured directory. Supports variable interpolation (e.g., `$.commonPaths.appStackPath`) |
+| `generateModule` | boolean | Yes      | Whether to generate a `modules.js` file listing all modules in the copied directory                                                       |
+
+### Variable Interpolation
+
+The `destPath` supports JSONPath-style variable interpolation using the `$.` prefix:
+
+```json
+{
+    "commonPaths": {
+        "appPath": "app",
+        "sharedLibPath": "shared-lib"
+    },
+    "copyOperations": [
+        {
+            "packageName": "@my-org/shared-components",
+            "destPath": "$.commonPaths.sharedLibPath",
+            "generateModule": true
+        }
+    ]
+}
+```
+
+In this example, `$.commonPaths.sharedLibPath` resolves to `shared-lib`.
+
+## Execution Flow
+
+### 1. Build Time Execution
+
+Copy operations execute at different stages depending on the environment:
+
+#### Production Build
+
+```typescript
+// In vite.config.ts
+const routesConfig = async (defineRoutes) => {
+    if (process.env.NODE_ENV === 'production') {
+        await performCopyOperations(config);
+    }
+    // ... route definitions
+};
+```
+
+#### Development/Server Start
+
+```javascript
+// In server.js
+const startServer = async () => {
+    await performCopyOperations(config);
+    // ... server initialization
+};
+```
+
+### 2. Copy Process
+
+The `performCopyOperations` function (from `@common-stack/rollup-vite-utils`):
+
+1. **Resolves Source**: Locates the package in `node_modules`
+2. **Constructs Source Path**: Combines package location with `lib/` directory and optional `sourcePath`
+3. **Resolves Destination**: Interpolates variables in `destPath` and constructs absolute path
+4. **Checks Freshness**: Compares timestamps to skip unnecessary copies
+5. **Performs Copy**: Copies file or directory recursively
+6. **Generates Module File**: If `generateModule: true`, creates a `modules.js` file
+
+### 3. Terminal Output
+
+During execution, you'll see output like:
+
+```
+Copy operation for @my-org/shared-components completed successfully.
+Copied directory from /path/to/node_modules/@my-org/my-package/lib/assets/data-file.bin
+  to /path/to/servers/frontend-server/public/files/data-file.bin
+Copy operation for @my-org/my-package completed successfully.
+```
+
+## Common Use Cases
+
+### 1. Copying Static Assets
+
+**Use Case**: Binary files, images, or data files needed at runtime
+
+```json
+{
+    "packageName": "@my-org/ml-models",
+    "sourcePath": "assets/model.bin",
+    "destPath": "../public/files/model.bin",
+    "generateModule": false
+}
+```
+
+**Result**: The binary file is accessible at `/files/model.bin` in the browser
+
+### 2. Copying Web Workers
+
+**Use Case**: Web Worker files that need to be loaded by the browser
+
+```json
+{
+    "packageName": "@my-org/worker-package",
+    "sourcePath": "main.worker.js",
+    "destPath": "../public/workers/main.worker.js",
+    "generateModule": true
+}
+```
+
+**Result**: Worker is available at `/workers/main.worker.js` for `new Worker()` instantiation
+
+### 3. Copying Entire Module Libraries
+
+**Use Case**: Full module with auto-discovery and dynamic imports
+
+```json
+{
+    "packageName": "@my-org/component-library",
+    "destPath": "$.commonPaths.componentLibPath",
+    "generateModule": true
+}
+```
+
+**Result**:
+
+- Entire package copied to `app/component-lib/`
+- `modules.js` file generated listing all available modules
+- Enables dynamic import: `import('@app/component-lib/lib/component.js')`
+
+### 4. Copying Source Maps
+
+**Use Case**: Debug support with source maps
+
+```json
+{
+    "packageName": "@my-org/worker-package",
+    "sourcePath": "main.worker.js.map",
+    "destPath": "../public/workers/main.worker.js.map",
+    "generateModule": false
+}
+```
+
+## Module Generation
+
+When `generateModule: true`, a `modules.js` file is created in the destination directory:
+
+```javascript
+// Generated modules.js
+export const modules = [
+    './lib/components/Button.js',
+    './lib/components/Form.js',
+    './lib/utils/helpers.js',
+    // ... all JS/TS files found
+];
+```
+
+This enables:
+
+- **Dynamic Discovery**: Runtime enumeration of available modules
+- **Lazy Loading**: On-demand imports based on configuration
+- **Plugin Systems**: Auto-registration of discovered modules
+
+## Example Configuration
+
+### Frontend Server Configuration
+
+```json
+{
+    "commonPaths": {
+        "appPath": "app",
+        "sharedLibPath": "shared-lib"
+    },
+    "copyOperations": [
+        {
+            "packageName": "@my-org/component-library",
+            "destPath": "$.commonPaths.sharedLibPath",
+            "generateModule": true
+        },
+        {
+            "packageName": "@my-org/ml-models",
+            "sourcePath": "assets/model.bin",
+            "destPath": "../public/files/model.bin",
+            "generateModule": false
+        },
+        {
+            "packageName": "@my-org/worker-package",
+            "sourcePath": "main.worker.js",
+            "destPath": "../public/workers/main.worker.js",
+            "generateModule": true
+        },
+        {
+            "packageName": "@my-org/worker-package",
+            "sourcePath": "main.worker.js.map",
+            "destPath": "../public/workers/main.worker.js.map",
+            "generateModule": false
+        }
+    ]
+}
+```
+
+### Mobile App Configuration
+
+```json
+{
+    "commonPaths": {
+        "appPath": "app",
+        "mobileLibPath": "mobile-shared"
+    },
+    "copyOperations": [
+        {
+            "packageName": "@my-org/mobile-components",
+            "destPath": "$.commonPaths.mobileLibPath",
+            "generateModule": true
+        }
+    ]
+}
+```
+
+## Integration Points
+
+### 1. Vite Configuration
+
+```typescript
+// vite.config.ts
+import { performCopyOperations } from '@common-stack/rollup-vite-utils/lib/preStartup/configLoader/configLoader.js';
+
+export default defineConfig(({ isSsrBuild }) => {
+    const routesConfig = async (defineRoutes) => {
+        if (process.env.NODE_ENV === 'production') {
+            await performCopyOperations(config);
+        }
+        // Route configuration...
+    };
+    // Vite config...
+});
+```
+
+### 2. Express Server
+
+```javascript
+// server.js
+import { performCopyOperations } from '@common-stack/rollup-vite-utils/lib/preStartup/configLoader/configLoader.js';
+
+const startServer = async () => {
+    await performCopyOperations(config);
+    // Server setup...
+};
+```
+
+### 3. Build Scripts
+
+```json
+{
+    "scripts": {
+        "build": "vite build",
+        "start": "node server.js"
+    }
+}
+```
+
+Copy operations run automatically during:
+
+- Production builds (`yarn build`)
+- Development server start (`yarn start`)
+
+## Best Practices
+
+### 1. Use Relative Paths Carefully
+
+```json
+{
+    "destPath": "../public/files/asset.bin"
+}
+```
+
+The path is relative to the `app` directory specified in `commonPaths.appPath`.
+
+### 2. Enable Module Generation Strategically
+
+- ✅ **Use `generateModule: true`** for: Full libraries, plugin systems, component libraries
+- ❌ **Use `generateModule: false`** for: Single files, binary assets, source maps
+
+### 3. Organize by Purpose
+
+Group copy operations logically:
+
+- Framework/stack modules first
+- Application modules second
+- Assets and workers third
+
+### 4. Version Consistency
+
+Ensure package versions in `package.json` match the expected structure in copy operations.
+
+### 5. Clean Builds
+
+Copy operations check timestamps to avoid unnecessary copying, but for clean builds:
+
+```bash
+# Clean and rebuild
+rm -rf servers/frontend-server/app/shared-lib
+rm -rf servers/frontend-server/public/files
+rm -rf servers/frontend-server/public/workers
+npm run build  # or yarn build
+```
+
+## Troubleshooting
+
+### Issue: "Source path not found"
+
+**Problem**: Package structure changed or `sourcePath` is incorrect
+
+**Solution**:
+
+1. Check the package in `node_modules/{packageName}/lib/`
+2. Verify the `sourcePath` matches the actual file structure
+3. Ensure the package is installed: `yarn install`
+
+### Issue: "Module generation failed"
+
+**Problem**: Destination directory doesn't exist or permissions issue
+
+**Solution**:
+
+1. Ensure parent directories exist
+2. Check write permissions
+3. Verify `destPath` is correct
+
+### Issue: "Copy operation skipped"
+
+**Problem**: Destination is newer than source (timestamp check)
+
+**Solution**: This is normal behavior. To force copy:
+
+1. Delete the destination directory/file
+2. Re-run the build
+
+### Issue: "Worker not loading in browser"
+
+**Problem**: Worker file not accessible or incorrect path
+
+**Solution**:
+
+1. Verify the file exists in `public/workers/`
+2. Check browser console for 404 errors
+3. Ensure the worker path in code matches `destPath`
+
+## Performance Considerations
+
+1. **Incremental Copies**: The system uses timestamp comparison to skip unchanged files
+2. **Production Only**: Some operations only run in production to speed up development
+3. **Parallel Operations**: Multiple copy operations can run concurrently
+4. **Caching**: Vite's build cache works with copied files
+
+## Related Tools
+
+- **Source**: `@common-stack/rollup-vite-utils` package
+- **Configuration Loader**: `configLoader.js`
+- **Environment Loader**: `envLoader.js`
+
+## Summary
+
+The Copy Operations system provides a declarative, configuration-driven approach to managing build-time asset distribution. It ensures that:
+
+- Static assets are accessible at runtime
+- Web workers are properly positioned for browser execution
+- Module libraries support dynamic imports
+- Build processes are efficient and incremental
+- Configuration is centralized and maintainable
+
+By understanding and properly configuring copy operations, you can ensure your application's assets and modules are correctly positioned for optimal runtime performance.

package/lib/templates/content/docs/feature-api/feature-browser/assets.md

@@ -0,0 +1,46 @@
+---
+meta:
+    title: Assets
+    description: Assets
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Assets...
+headers:
+    Cache-Control: no-cache
+---
+
+## Importing Assets
+
+CDEBase is a webpack-based project, so it follows the general approach to importing assets —
+[webpack dependency management]. You can look up the module `packages/assets` to see how assets are imported.
+
+As you can see in the code sample below, the project imports all the assets from the `modules/favicon/common/assets`
+folder:
+
+```js
+const exportedAssets = {};
+let isbrowser = typeof window !== 'undefined';
+if (isbrowser) {
+    // Favicon.ico should not be hashed, since browsers expect it to be exactly on /favicon.ico URL
+    require('!file-loader?name=[name].[ext]!./assets/favicon.ico'); // eslint-disable-line
+
+    // Require all files from assets dir recursively adding them into assets.json
+    const req = require.context('!file-loader?name=[hash].[ext]!./assets', true, /.*/);
+    req.keys().map((key) => {
+        exportedAssets[`${key.replace('./', '')}`] = req(key);
+    });
+}
+
+export default exportedAssets;
+```
+
+To use new assets in your client side react code, import from the favicon package as follows:
+
+```js
+import assets from '@admin-layout/assets';
+console.log('--ASSETS', assets);
+
+export const Favicon = <img src={assets['favicon.ico']} />;
+```
+
+<img width="1052" alt="image" src="https://user-images.githubusercontent.com/3382355/232731184-a5c3b622-48f0-41ac-a96c-678339d71558.png"/>

package/lib/templates/content/docs/feature-api/feature-browser/auth-permissions.md

@@ -0,0 +1,12 @@
+---
+meta:
+    title: Auth Permissions
+    description: Auth Permissions
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Auth Permissions...
+headers:
+    Cache-Control: no-cache
+---
+
+## Auth Permissions

package/lib/templates/content/docs/feature-api/feature-browser/feature.md

@@ -0,0 +1,131 @@
+---
+meta:
+    title: Feature Browser API
+    description: Feature Browser API
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Feature Browser API...
+headers:
+    Cache-Control: no-cache
+---
+
+# Feature Browser API
+
+Feature is a fractal-based modular architecture. It is like a module federation to create independent packages that have references to all that need to run a fullstack application. Each of these module should have code limited to its requirement that way we achieve seperation of concerns.
+
+It is opiniated and it supports following for client state management
+
+- redux
+- redux-persist
+- apollo-client
+- redux-observable
+
+Components are rendered only through `react-router`, for that we pass `routeConfig`.
+
+Dynamic Components are provided using `slot-fill` logic using `componentFillPlugins` configuration.
+
+Third-party Scripts can be inserted into HTML page as well.
+
+Each of these packaged module is used in the `frontend-server` like below
+
+```js
+import counterModule from '@sample-stack/counter-module-browser';
+import accountModule from '@sample-stack/account-module-browser';
+import paymentModule from '@sample-stack/payment-module-browser';
+
+const features = new Feature(FeatureWithRouterFactory, counterModule, accountModule, paymentModule);
+```
+
+The `frontend-server` have all required logic to consolidate the `reducers`, `epics`, `apollo-client configuration`, `react-router configuration` etc to run the application.
+
+For example provide all the required configuration to the `Feature` like below.
+
+```js
+const module = new Feature({
+    /**
+        Customizing ID in the apollo cache.
+    **/
+    dataIdFromObject,
+    /**
+        load apollo-client state management. 
+    **/
+    clientStateParams: { resolvers, typeDefs: schema },
+    /**
+        load redux-observables to manage the client state.
+    **/
+    epic: [onUserAccountNotFound],
+    /**
+        load react-router configuration to display component based on navigation. 
+        for more information check [Routing](./routing.mx)
+    **/
+    routeConfig: filteredRoutes,
+    componentFillPlugins: [
+        {
+            name: 'teams-contribution',
+            render: TeamsContribution,
+        },
+    ],
+    /**
+     load any scripts when this Feature Module is used.
+    **/
+    scriptsInsert: 'https://js.stripe.com/v3/',
+    createContainerFunc: [Auth0Module],
+    /**
+     load reducers to the Redux Store when this Feature Module is used.
+    **/
+    reducer: { user: userReducer, redirectRoutes: redirectRoutesReducer, authErrors: authErrorsReducer },
+    /**
+        By default all redux state is persisted using redux-persist, if you need to manipulate the persist state
+        add configuration here. 
+    **/
+    reduxPersistTransforms: [blacklistErrorFilter, blacklistUserFilter],
+});
+```
+
+We don't need to put the `redux` store creation nor apollo-client setup in the Module as this action will be taken care at the higher level (frontend-server).
+
+### Client State Management
+
+Applciation state can be managed using Apollo Link State and Redux.
+
+#### Redux
+
+Support [redux's reducers](https://redux.js.org/usage/structuring-reducers/basic-reducer-structure)
+Example:
+
+```js
+const module = new Feature({
+    reducer: { user: userReducer, redirectRoutes: redirectRoutesReducer, authErrors: authErrorsReducer },
+    ....
+});
+```
+
+#### Apollo Client State Management
+
+Support [interacting with local data in Apollo Client](https://www.apollographql.com/docs/react/local-state/local-state-management/)
+
+Example:
+
+```js
+const module = new Feature({
+    clientStateParams: { resolvers, typeDefs: schema, typePolicies },
+    ....
+});
+```
+
+##### dataIdFromObject
+
+Support cusotmizing the ID in the apollo cache. More infromation is [here](https://www.apollographql.com/docs/react/caching/cache-configuration/#dataidfromobject)
+
+#### Epic
+
+Support [redux-observable](https://redux-observable.js.org/docs/basics/Epics.html)
+
+Example:
+
+```js
+const module = new Feature({
+    epic: [onUserAccountNotFound],
+    ....
+});
+```

package/lib/templates/content/docs/feature-api/feature-browser/index.md

@@ -0,0 +1,22 @@
+---
+meta:
+    title: Feature Browser
+    description: Feature Browser
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Feature Browser...
+headers:
+    Cache-Control: no-cache
+---
+
+## Feature Browser
+
+**[Feature Browser API](/docs/feature-api/feature-browser/feature)**
+
+**[Routes and Menu](/docs/feature-api/feature-browser/routes-menu)**
+
+**[Routing Convetion](/docs/feature-api/feature-browser/routing-convention)**
+
+**[Routing](/docs/feature-api/feature-browser/routing)**
+
+**[Auth & Permissions](/docs/feature-api/feature-browser/auth-permissions)**