@el-j/magic-helix-plugins 4.0.0-beta.2 → 4.0.0-beta.3

package/dist/devops/docker-compose.md

@@ -0,0 +1,111 @@
+# Docker Compose Best Practices
+
+## Overview
+This project uses Docker Compose for multi-container orchestration.
+
+## Commands
+- Start services: `docker compose up`
+- Start in background: `docker compose up -d`
+- Stop services: `docker compose down`
+- View logs: `docker compose logs -f`
+- Rebuild: `docker compose up --build`
+- Run command: `docker compose exec <service> <command>`
+
+## Service Definition
+- Define services clearly with descriptive names
+- Specify image or build context
+- Set restart policies: `restart: unless-stopped`
+- Use environment variables
+- Define health checks
+
+## Networking
+- Services can communicate by service name
+- Define custom networks if needed
+- Use `depends_on` for startup order
+- Expose only necessary ports
+
+## Volumes
+- Use named volumes for persistent data
+- Use bind mounts for development
+- Mount volumes in development for hot reload
+- Example:
+  ```yaml
+  volumes:
+    - ./src:/app/src
+    - node_modules:/app/node_modules
+  ```
+
+## Environment Variables
+- Use `.env` file for environment variables
+- Reference in compose file: `${VARIABLE_NAME}`
+- Use `env_file` directive for multiple files
+- Never commit sensitive `.env` files
+
+## Development vs Production
+- Use `docker-compose.yml` for base configuration
+- Use `docker-compose.override.yml` for development
+- Use `docker-compose.prod.yml` for production
+- Override with: `docker compose -f docker-compose.yml -f docker-compose.prod.yml up`
+
+## Common Services
+- **Database**: PostgreSQL, MySQL, MongoDB
+- **Cache**: Redis, Memcached
+- **Queue**: RabbitMQ, Redis
+- **Web Server**: Nginx, Apache
+
+## Best Practices
+- Pin service versions
+- Use health checks for dependencies
+- Set resource limits in production
+- Use secrets for sensitive data (v3.1+)
+- Don't run containers as root
+- Use separate networks for isolation
+
+## Example Structure
+```yaml
+version: '3.8'
+
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=development
+    volumes:
+      - .:/app
+      - /app/node_modules
+    depends_on:
+      - db
+      - redis
+    
+  db:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_DB: myapp
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: password
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+
+volumes:
+  postgres_data:
+```
+
+## Troubleshooting
+- Check logs: `docker compose logs <service>`
+- Inspect containers: `docker compose ps`
+- Access shell: `docker compose exec <service> sh`
+- View networks: `docker network ls`
+- Clean up: `docker compose down -v` (removes volumes)
+
+## Performance
+- Use volumes for better I/O performance
+- Limit services to necessary ones during development
+- Use profiles to group optional services
+- Consider using `docker compose watch` for development

package/dist/devops/docker-dockerfile.md

@@ -0,0 +1,94 @@
+# Dockerfile Best Practices
+
+## Overview
+This project uses Docker for containerization. Follow Docker best practices for efficient and secure images.
+
+## Multi-Stage Builds
+- Use multi-stage builds to reduce final image size
+- Separate build and runtime stages
+- Copy only necessary artifacts to final stage
+- Example:
+  ```dockerfile
+  FROM node:20 AS builder
+  WORKDIR /app
+  COPY package*.json ./
+  RUN npm ci
+  COPY . .
+  RUN npm run build
+  
+  FROM node:20-slim
+  WORKDIR /app
+  COPY --from=builder /app/dist ./dist
+  COPY package*.json ./
+  RUN npm ci --only=production
+  CMD ["node", "dist/index.js"]
+  ```
+
+## Base Image Selection
+- Use official images when available
+- Choose slim or alpine variants for smaller sizes
+- Pin specific versions, avoid `latest` tag
+- Use distroless images for production when possible
+
+## Layer Optimization
+- Order instructions from least to most frequently changing
+- Combine RUN commands to reduce layers
+- Use `.dockerignore` to exclude unnecessary files
+- Clean up in the same RUN command (apt-get clean, rm cache)
+
+## Security Best Practices
+- Run as non-root user: `USER node` or custom user
+- Scan images for vulnerabilities regularly
+- Don't store secrets in images
+- Use `COPY` instead of `ADD` unless you need tar extraction
+- Keep base images updated
+
+## Dockerfile Instructions
+- `FROM`: Base image
+- `WORKDIR`: Set working directory
+- `COPY`: Copy files (preferred over ADD)
+- `RUN`: Execute commands
+- `CMD`: Default command (can be overridden)
+- `ENTRYPOINT`: Main executable (harder to override)
+- `ENV`: Set environment variables
+- `EXPOSE`: Document ports (doesn't actually publish)
+- `VOLUME`: Define mount points
+
+## Environment Variables
+- Use `ENV` for build-time variables
+- Use `ARG` for build arguments
+- Don't hardcode sensitive data
+- Use `.env` files with docker-compose
+
+## Health Checks
+- Define `HEALTHCHECK` instruction
+- Example: `HEALTHCHECK CMD curl -f http://localhost/ || exit 1`
+- Helps orchestrators know when container is ready
+
+## Image Tagging
+- Tag images with semantic versions
+- Use descriptive tags: `app:1.2.3`, `app:latest`, `app:dev`
+- Don't rely solely on `latest` tag
+
+## Build Context
+- Keep build context small
+- Use `.dockerignore` file
+- Exclude: `node_modules`, `.git`, `dist`, test files
+- Only include what's needed for the build
+
+## Performance Tips
+- Use layer caching effectively
+- Leverage BuildKit features
+- Use `--mount=type=cache` for package managers
+- Minimize the number of layers in final image
+
+## Common Patterns
+- Copy package files first, then install dependencies
+- This caches dependencies when source code changes
+- Use `COPY package*.json ./` before `RUN npm install`
+
+## Documentation
+- Add labels for metadata: `LABEL maintainer="team@example.com"`
+- Include README with Docker commands
+- Document exposed ports and volumes
+- Provide example docker-compose.yml

package/dist/devops/github-actions.md

@@ -0,0 +1,160 @@
+# GitHub Actions CI/CD Guidelines
+
+## Overview
+This project uses GitHub Actions for CI/CD workflows. Follow best practices for efficient and maintainable workflows.
+
+## Workflow Structure
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npm test
+```
+
+## Triggers
+- `push`: On push to branches
+- `pull_request`: On PRs
+- `workflow_dispatch`: Manual trigger
+- `schedule`: Cron-based scheduling
+- `release`: On release creation
+
+## Common Actions
+- `actions/checkout@v4`: Checkout code
+- `actions/setup-node@v4`: Setup Node.js
+- `actions/cache@v4`: Cache dependencies
+- `actions/upload-artifact@v4`: Upload artifacts
+- `actions/download-artifact@v4`: Download artifacts
+
+## Best Practices
+
+### Use Matrix Strategy
+```yaml
+strategy:
+  matrix:
+    node-version: [18, 20, 22]
+    os: [ubuntu-latest, windows-latest, macos-latest]
+```
+
+### Cache Dependencies
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+    restore-keys: |
+      ${{ runner.os }}-node-
+```
+
+### Use Secrets
+- Store sensitive data in GitHub Secrets
+- Access via: `${{ secrets.SECRET_NAME }}`
+- Never hardcode credentials
+
+### Conditional Steps
+```yaml
+- name: Deploy
+  if: github.ref == 'refs/heads/main'
+  run: npm run deploy
+```
+
+### Reusable Workflows
+- Create reusable workflows in `.github/workflows/`
+- Call with `uses: ./.github/workflows/reusable.yml`
+
+## Job Dependencies
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps: [...]
+  
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    steps: [...]
+```
+
+## Environment Variables
+```yaml
+env:
+  NODE_ENV: production
+  API_URL: https://api.example.com
+```
+
+## Artifacts
+- Upload build outputs for later jobs
+- Download in subsequent jobs or manually
+- Artifacts expire after 90 days by default
+
+## Concurrency Control
+```yaml
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+```
+
+## Performance Tips
+- Use caching for dependencies
+- Run independent jobs in parallel
+- Use `if` conditions to skip unnecessary steps
+- Use `continue-on-error` for non-critical steps
+
+## Security
+- Use pinned versions of actions: `actions/checkout@v4`
+- Review third-party actions before use
+- Use GITHUB_TOKEN for authentication
+- Enable branch protection rules
+- Use environments for deployment approvals
+
+## Debugging
+- Enable debug logging: Set secret `ACTIONS_STEP_DEBUG` to `true`
+- Use `actions/upload-artifact` to save debug files
+- Check workflow logs in Actions tab
+
+## Common Patterns
+
+### Build and Test
+```yaml
+- name: Install dependencies
+  run: npm ci
+- name: Build
+  run: npm run build
+- name: Test
+  run: npm test
+```
+
+### Deploy on Main
+```yaml
+- name: Deploy
+  if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+  run: npm run deploy
+```
+
+### Docker Build and Push
+```yaml
+- name: Build and push
+  uses: docker/build-push-action@v5
+  with:
+    push: true
+    tags: user/app:latest
+```
+
+## Monitoring
+- Check workflow status in Actions tab
+- Set up status checks for required workflows
+- Use workflow badges in README
+- Enable notifications for failures

package/dist/devops/gitlab-ci.md

@@ -0,0 +1,210 @@
+# GitLab CI/CD Guidelines
+
+## Overview
+This project uses GitLab CI/CD for continuous integration and deployment. Follow best practices for efficient pipelines.
+
+## Pipeline Structure
+```yaml
+stages:
+  - build
+  - test
+  - deploy
+
+variables:
+  NODE_VERSION: "20"
+
+build:
+  stage: build
+  image: node:${NODE_VERSION}
+  script:
+    - npm ci
+    - npm run build
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 1 hour
+
+test:
+  stage: test
+  image: node:${NODE_VERSION}
+  script:
+    - npm ci
+    - npm test
+  coverage: '/Coverage: \d+\.\d+%/'
+
+deploy:
+  stage: deploy
+  script:
+    - npm run deploy
+  only:
+    - main
+  environment:
+    name: production
+```
+
+## Stages
+- Define pipeline stages: `build`, `test`, `deploy`
+- Jobs in same stage run in parallel
+- Stages run sequentially
+- Use dependencies for job order within stage
+
+## Jobs
+- Each job runs in isolated environment
+- Define image for Docker-based runners
+- Use `script` for commands
+- Use `before_script` and `after_script` for setup/cleanup
+
+## Variables
+- Define global variables in `variables:` section
+- Use in scripts: `$VARIABLE_NAME`
+- Set in GitLab CI/CD settings for secrets
+- Use `file` type for certificates
+
+## Artifacts
+- Share files between jobs
+- Define in `artifacts:` section
+- Set expiration: `expire_in: 1 week`
+- Download from pipeline UI
+
+## Cache
+```yaml
+cache:
+  key: ${CI_COMMIT_REF_SLUG}
+  paths:
+    - node_modules/
+    - .npm/
+```
+
+## Rules and Conditions
+```yaml
+deploy:
+  script: deploy.sh
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+    - when: manual  # Require manual trigger
+```
+
+## Docker Integration
+```yaml
+build-docker:
+  image: docker:latest
+  services:
+    - docker:dind
+  script:
+    - docker build -t myapp .
+    - docker push myapp
+```
+
+## Services
+- Run side containers (database, cache)
+- Example: `services: - postgres:15`
+- Access via hostname: `postgres`
+
+## Environments
+- Define deployment environments
+- Track deployments in GitLab
+- Enable auto-rollback
+- Use protected environments
+
+## Include and Extends
+```yaml
+include:
+  - local: '/.gitlab-ci-template.yml'
+
+.node_job:
+  image: node:20
+  before_script:
+    - npm ci
+
+test:
+  extends: .node_job
+  script:
+    - npm test
+```
+
+## Parallel Jobs
+```yaml
+test:
+  parallel: 3
+  script:
+    - npm test -- --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL
+```
+
+## Triggers
+- `push`: On every push
+- `merge_request_event`: On MR creation/update
+- `schedule`: Scheduled pipelines
+- `api`: Triggered via API
+- `manual`: Requires manual action
+
+## Best Practices
+- Use `.gitlab-ci.yml` in repository root
+- Pin image versions
+- Use cache for dependencies
+- Separate build and deploy stages
+- Use artifacts for build outputs
+- Set appropriate timeout values
+- Use rules instead of only/except
+- Validate YAML before committing
+
+## Performance
+- Use cache effectively
+- Run jobs in parallel when possible
+- Use shallow clone: `GIT_DEPTH: 1`
+- Optimize Docker images
+- Use artifacts sparingly
+
+## Security
+- Never commit secrets to `.gitlab-ci.yml`
+- Use masked variables for secrets
+- Use protected variables for sensitive data
+- Scan for vulnerabilities in dependencies
+- Use SAST and DAST tools
+
+## Debugging
+- Check pipeline logs in CI/CD > Pipelines
+- Use `CI_DEBUG_TRACE: "true"` for verbose logs
+- Test locally with GitLab Runner
+- Use `when: always` to run on failure
+
+## Common Patterns
+
+### Node.js Project
+```yaml
+test:
+  image: node:20
+  script:
+    - npm ci
+    - npm test
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage/cobertura-coverage.xml
+```
+
+### Manual Deployment
+```yaml
+deploy:
+  stage: deploy
+  script:
+    - deploy.sh
+  when: manual
+  only:
+    - main
+```
+
+### Multi-Project Pipeline
+```yaml
+trigger_downstream:
+  trigger:
+    project: group/downstream-project
+    branch: main
+```
+
+## Monitoring
+- View pipeline status in GitLab UI
+- Enable email notifications
+- Use badges in README
+- Monitor pipeline duration
+- Track deployment frequency

package/dist/generic/lang-typescript.md

@@ -0,0 +1,57 @@
+# Language: TypeScript
+
+## Expert Identity
+You are an expert TypeScript developer with deep knowledge of static typing, modern ECMAScript features, and type-safe application development.
+
+## Core Capabilities
+- Write type-safe TypeScript code using strict mode
+- Design robust type systems with interfaces and utility types
+- Apply modern TypeScript patterns for null safety and immutability
+- Debug type errors and provide clear type annotations
+
+## Coding Standards
+
+### Type Safety
+* **ALWAYS** use strict mode (`"strict": true` in `tsconfig.json`).
+* **AVOID** the `any` type. Prefer `unknown` when the type is truly unknown.
+* **ALWAYS** use `interface` for public API definitions (e.g., function parameters, return types) and `type` for internal or utility types.
+
+### Modern Syntax
+* **ALWAYS** use optional chaining (`?.`) and nullish coalescing (`??`) over `&&` checks.
+* **NEVER** use `require`. Always use ES module `import` syntax.
+
+## Examples
+
+### Proper Interface Definition
+```typescript
+// ✅ Good: Interface for public API
+interface UserProfile {
+  id: string;
+  name: string;
+  email?: string; // Optional property
+}
+
+function getUser(id: string): Promise<UserProfile> {
+  // Implementation
+}
+```
+
+### Type-Safe Null Handling
+```typescript
+// ✅ Good: Using optional chaining and nullish coalescing
+const displayName = user?.profile?.name ?? 'Anonymous';
+
+// ❌ Bad: Manual null checks
+const displayName = user && user.profile && user.profile.name ? user.profile.name : 'Anonymous';
+```
+
+## Safety Guidelines
+- Never generate code that bypasses TypeScript's type system with `@ts-ignore` or `as any` without explicit user request
+- Always validate that suggested code compiles without type errors
+- Refuse to implement patterns that compromise type safety when asked
+
+## Tool Usage
+When using file editing or code generation tools:
+- Always include proper TypeScript type annotations
+- Ensure imports are typed correctly
+- Verify that generated code is compatible with strict mode

package/dist/generic/state-redux.md

@@ -0,0 +1,21 @@
+# State Management: Redux
+- **ALWAYS** use Redux Toolkit (`@reduxjs/toolkit`) for modern Redux development.
+- **ALWAYS** use `createSlice()` for reducer logic and actions.
+- **ALWAYS** use `configureStore()` for store setup with good defaults.
+- **ALWAYS** use TypeScript for type-safe Redux code.
+- **ALWAYS** define action types as string constants or use `createAction()`.
+- **ALWAYS** use `createAsyncThunk()` for async logic and API calls.
+- **ALWAYS** normalize state shape for better performance and consistency.
+- **ALWAYS** use selector functions with `createSelector()` for computed values.
+- **ALWAYS** use `useSelector()` and `useDispatch()` hooks in React components.
+- **ALWAYS** avoid direct state mutations - use immutable updates.
+- **ALWAYS** use `redux-persist` for state persistence when needed.
+- **ALWAYS** use `redux-saga` or `redux-thunk` for complex async flows.
+- **ALWAYS** use `redux-devtools-extension` for debugging in development.
+- **ALWAYS** write comprehensive tests for reducers and selectors.
+- **ALWAYS** use `entityAdapter` from RTK for CRUD operations.
+- **ALWAYS** handle loading and error states in async thunks.
+- **ALWAYS** use `extraReducers` in `createSlice()` for async thunk handling.
+- **ALWAYS** keep reducers pure and side-effect free.
+- **ALWAYS** use meaningful action names and payload structures.
+- **ALWAYS** document complex state transformations with comments.

package/dist/generic/state-rxjs.md

@@ -0,0 +1,6 @@
+# State: RxJS
+- **ALWAYS** suffix Observable variables with a `$` (e.g., `users$`).
+- **ALWAYS** use `BehaviorSubject` for state that needs to be "replayed" to new subscribers.
+- **ALWAYS** `pipe()` operators. Do not use chained `.` operators.
+- **NEVER** forget to `unsubscribe()`. Manage subscriptions in a central way, e.g., a `destroy$` Subject that completes `onComponentDestroy`.
+- **PREFER** `switchMap` for handling new inner observables (like HTTP requests) and `mergeMap` for parallel operations.

package/dist/generic/style-mui.md

@@ -0,0 +1,23 @@
+# Styling: Material-UI (MUI)
+- **ALWAYS** use `@mui/material` v5+ with Emotion styling engine.
+- **ALWAYS** use `sx` prop for component-level styling.
+- **ALWAYS** use `ThemeProvider` for consistent theming.
+- **ALWAYS** use `createTheme()` for custom theme configuration.
+- **ALWAYS** use semantic color tokens from the theme palette.
+- **ALWAYS** use `Box` component as a generic layout primitive.
+- **ALWAYS** use `Container` for max-width layouts and centering.
+- **ALWAYS** use `Grid` v2 (`Grid2`) for responsive layouts.
+- **ALWAYS** use `Typography` component for all text elements.
+- **ALWAYS** use `Button` variants (`contained`, `outlined`, `text`) appropriately.
+- **ALWAYS** use `IconButton` for icon-only actions.
+- **ALWAYS** use `TextField` with proper `label` and `helperText` props.
+- **ALWAYS** use `FormControl` and `FormLabel` for form organization.
+- **ALWAYS** use `Dialog` for modals with proper accessibility.
+- **ALWAYS** use `Menu` and `MenuItem` for dropdown menus.
+- **ALWAYS** use `Chip` for tags, filters, and small status indicators.
+- **ALWAYS** use `Avatar` for user profile images.
+- **ALWAYS** use `Card`, `CardContent`, and `CardActions` for content containers.
+- **ALWAYS** use `List`, `ListItem`, and `ListItemText` for list displays.
+- **ALWAYS** use `Table` components for tabular data.
+- **ALWAYS** use `useMediaQuery` hook for responsive behavior.
+- **ALWAYS** use `styled()` API for custom component styling when needed.