@aifabrix/builder 2.52.1 → 2.53.1

package/.cursor/rules/project-rules.mdc

@@ -1,913 +0,0 @@
----
-alwaysApply: true
----
-# AI Fabrix Builder - Cursor Rules - ISO 27001 Compliant Development Standards
-
-## Project Overview
-
-This is the AI Fabrix Builder - a CLI tool for local development infrastructure and Azure deployment. The builder provides:
-- **Local Infrastructure** - Postgres + Redis via Docker Compose
-- **Application Scaffolding** - Generate configuration files for apps
-- **Docker Generation** - Auto-detect runtime and generate Dockerfiles
-- **Template System** - Handlebars-based templates for TypeScript and Python
-- **Azure Deployment** - Push to ACR and deploy via Miso Controller
-- **Configuration Management** - YAML-based config with schema validation
-
-Technologies:
-- Node.js/JavaScript (CommonJS modules)
-- Commander.js for CLI
-- Handlebars for template generation
-- js-yaml for YAML parsing
-- AJV for JSON schema validation
-- Jest for testing
-- Docker for containerization
-
-## CLI layout and output
-
-When adding or changing CLI commands, subcommands, flags, help text, or terminal output (`lib/cli.js`, `lib/cli/**`, `lib/commands/**`, shared `lib/utils/cli-*layout*.js`), you must follow the CLI layout rule and its referenced source-of-truth docs:
-
-- **Rule**: `.cursor/rules/cli-layout.mdc`
-- **Visual/layout spec**: `.cursor/rules/layout.md`
-- **Per-command output profiles**: `.cursor/rules/cli-output-command-matrix.md` (update for every new leaf command; see matrix **Layout compliance** for `cli-test-layout-chalk` adoption status)
-
-## Architecture Patterns
-
-> **Visual Documentation**: When documenting architecture, workflows, or command flows, use the canonical Mermaid diagram templates from [flows-and-visuals.md](flows-and-visuals.md). These templates ensure consistent styling and accurate representation of Builder architecture.
-
-### Module Structure
-- All modules use CommonJS (`require`/`module.exports`)
-- Main entry point: `bin/aifabrix.js`
-- Core logic in `lib/` directory
-- Commands in `lib/cli.js` and `lib/commands/`
-- Utilities in `lib/utils/`
-- Schemas in `lib/schema/`
-- Templates in `templates/` directory
-
-### File Organization
-```yaml
-lib/
-├── cli.js              # CLI command definitions (Commander.js)
-├── commands/           # Command implementations
-├── app.js              # App creation and management
-├── generator.js        # Deployment JSON generation
-├── validator.js        # Schema validation
-├── build.js            # Docker build logic
-├── infra.js            # Infrastructure management
-├── deployer.js          # Azure deployment
-├── templates.js        # Template rendering
-├── secrets.js          # Secret resolution (kv://)
-├── config.js           # Configuration management
-├── api/                # Centralized API client structure
-│   ├── index.js        # Main API client class
-│   ├── types/          # JSDoc type definitions
-│   │   ├── auth.types.js
-│   │   ├── applications.types.js
-│   │   ├── deployments.types.js
-│   │   ├── environments.types.js
-│   │   ├── datasources.types.js
-│   │   ├── external-systems.types.js
-│   │   └── pipeline.types.js
-│   ├── auth.api.js     # Authentication API functions
-│   ├── applications.api.js
-│   ├── deployments.api.js
-│   ├── environments.api.js
-│   ├── datasources.api.js
-│   ├── external-systems.api.js
-│   └── pipeline.api.js
-├── utils/              # Utility functions
-└── schema/             # JSON schemas
-```
-
-### Generated Output (integration/ and builder/)
-
-Files under **integration/** and **builder/** are **auto-generated** by the CLI. When fixing bugs or changing behavior, validate **where** each file is produced so fixes go into the generator, not only into the generated artifact.
-
-- **integration/** – External system / wizard output:
-  - Path: `integration/<appName>/` (see `lib/utils/paths.js` → `getIntegrationPath`).
-  - Generated by: `lib/generator/wizard.js` (`generateWizardFiles`, `generateConfigFilesForWizard`), `lib/external-system/download.js`, wizard commands in `lib/commands/wizard-core.js` and `lib/commands/wizard.js`.
-  - Typical outputs: `application.yaml`, `env.template`, `README.md`, `*-system.json`, `*-datasource*.json`, `*-deploy.json`, deploy script (`deploy.js`), and optionally `wizard.yaml`, `error.log`.
-- **builder/** – Application (non-external) output:
-  - Path: `builder/<appName>/` or custom root via `AIFABRIX_BUILDER_DIR` (see `lib/utils/paths.js` → `getBuilderPath`).
-  - Generated by: app create/register flow, `lib/generator/index.js`, `lib/commands/up-common.js`, `lib/core/secrets.js`, and related app/deploy logic.
-  - Typical outputs: `application.yaml`, `env.template`, deploy JSON, `.env` (from secrets), and app-specific config.
-
-**Editable vs generated:**
-- Some generated files are **intended to be edited** (e.g. `application.yaml`, `env.template`, `README.md`, `wizard.yaml`). Improvements to defaults or structure still belong in the generator/templates.
-- **When debugging:** First identify the **source of generation** (which module and function write the file). Fix bugs in that generator or template; avoid treating a one-off edit in integration/ or builder/ as the permanent fix unless it’s a deliberate local override.
-
-### CLI Command Pattern
-Commands are defined in `lib/cli.js` using Commander.js:
-```javascript
-program.command('command-name')
-  .description('Command description')
-  .option('-f, --flag <value>', 'Option description', defaultValue)
-  .action(async (options) => {
-    try {
-      // Command implementation
-      await commandFunction(options);
-    } catch (error) {
-      console.error(chalk.red(`Error: ${error.message}`));
-      process.exit(1);
-    }
-  });
-```
-
-### Module Export Pattern
-- Use named exports for multiple functions
-- Use default exports for single-purpose modules
-- Pattern:
-```javascript
-/**
- * Module description
- * @fileoverview Brief description
- * @author AI Fabrix Team
- * @version 2.0.0
- */
-
-const dependency = require('./dependency');
-
-/**
- * Function description
- * @async
- * @function functionName
- * @param {string} param - Parameter description
- * @returns {Promise<Type>} Return description
- * @throws {Error} Error description
- */
-async function functionName(param) {
-  // Implementation
-}
-
-module.exports = { functionName };
-```
-
-### Template Generation Pattern
-Templates use Handlebars and are stored in `templates/`:
-```javascript
-const Handlebars = require('handlebars');
-const fs = require('fs');
-
-const templateContent = fs.readFileSync(templatePath, 'utf8');
-const template = Handlebars.compile(templateContent);
-const rendered = template(context);
-fs.writeFileSync(outputPath, rendered, 'utf8');
-```
-
-### YAML Processing Pattern
-All YAML files use js-yaml with proper error handling:
-```javascript
-const yaml = require('js-yaml');
-const fs = require('fs');
-
-try {
-  const content = fs.readFileSync(yamlPath, 'utf8');
-  const parsed = yaml.load(content);
-  // Process parsed YAML
-} catch (error) {
-  throw new Error(`Invalid YAML syntax: ${error.message}`);
-}
-```
-
-### Schema Validation Pattern
-Use AJV for JSON schema validation:
-```javascript
-const Ajv = require('ajv');
-const schema = require('./schema/application-schema.json');
-
-const ajv = new Ajv({ allErrors: true, strict: false });
-const validate = ajv.compile(schema);
-const valid = validate(data);
-
-if (!valid) {
-  const errors = formatValidationErrors(validate.errors);
-  throw new Error(`Validation failed: ${errors.join(', ')}`);
-}
-```
-
-### API Client Structure Pattern
-Use the centralized API client structure in `lib/api/` for all API calls. This provides typed interfaces, domain separation, and consistent error handling.
-
-**Structure**:
-- Base client (`lib/api/index.js`) - Main HTTP client with authentication and error handling
-- Type definitions (`lib/api/types/`) - JSDoc type definitions for request/response types
-- Domain modules (`lib/api/*.api.js`) - Domain-specific API functions
-
-**Type Definitions Pattern**:
-Use JSDoc `@typedef` for all request/response types in `lib/api/types/`:
-```javascript
-/**
- * @fileoverview Authentication API type definitions
- * @author AI Fabrix Team
- * @version 2.0.0
- */
-
-/**
- * Token request payload
- * @typedef {Object} TokenRequest
- * @property {string} clientId - Client ID
- * @property {string} clientSecret - Client secret
- */
-
-/**
- * Token response payload
- * @typedef {Object} TokenResponse
- * @property {boolean} success - Request success flag
- * @property {string} token - Authentication token
- * @property {number} expiresIn - Token expiration time in seconds
- * @property {string} expiresAt - Token expiration timestamp
- */
-```
-
-**API Module Pattern**:
-Each domain module exports typed API functions:
-```javascript
-/**
- * @fileoverview Authentication API functions
- * @author AI Fabrix Team
- * @version 2.0.0
- */
-
-const { ApiClient } = require('./index');
-const { TokenRequest, TokenResponse } = require('./types/auth.types');
-
-/**
- * Get authentication token using client credentials
- * @async
- * @function getToken
- * @param {string} clientId - Client ID
- * @param {string} clientSecret - Client secret
- * @param {string} controllerUrl - Controller base URL
- * @returns {Promise<TokenResponse>} Token response with access token
- * @throws {Error} If authentication fails
- */
-async function getToken(clientId, clientSecret, controllerUrl) {
-  const client = new ApiClient(controllerUrl);
-  return await client.post('/api/v1/auth/token', {
-    headers: {
-      'x-client-id': clientId,
-      'x-client-secret': clientSecret
-    }
-  });
-}
-
-module.exports = { getToken };
-```
-
-**Usage Pattern**:
-Import and use domain-specific API modules:
-```javascript
-const { getToken } = require('../api/auth.api');
-const { registerApplication } = require('../api/applications.api');
-
-// Use typed API functions
-const tokenResponse = await getToken(clientId, clientSecret, controllerUrl);
-const appResponse = await registerApplication(controllerUrl, environment, data, token);
-```
-
-**Migration Strategy**:
-- New code should use `lib/api/` modules
-- Existing code can continue using `lib/utils/api.js` (backward compatible)
-- Gradually migrate modules to use centralized API client
-- Eventually deprecate direct usage of `lib/utils/api.js`
-
-**API Permissions**: When adding or changing `lib/api` functions that call Controller or Dataplane, document required permissions. See [permissions-guide.md](permissions-guide.md) for how to update `@requiresPermission` JSDoc and [docs/commands/permissions.md](../docs/commands/permissions.md).
-
-## Code Style
-
-### JavaScript Conventions
-- Use strict mode where applicable
-- Use async/await for asynchronous operations
-- Use try-catch for error handling
-- Prefer const over let, avoid var
-- Use template literals for string interpolation
-- Use object destructuring where appropriate
-
-### Naming Conventions
-- **Files**: kebab-case (`app-deploy.js`, `env-reader.js`)
-- **Functions**: camelCase (`createApp`, `validateVariables`)
-- **Constants**: UPPER_SNAKE_CASE (`MAX_FILE_SIZE`, `DEFAULT_PORT`)
-- **Classes**: PascalCase (not common in this project, but if used)
-- **Private functions**: prefix with underscore if needed (rare in CommonJS)
-
-### Error Handling
-- Always wrap async operations in try-catch
-- Provide meaningful error messages
-- Include context in error messages (file path, app name, etc.)
-- Use chalk for colored error output
-- Pattern:
-```javascript
-try {
-  await operation();
-} catch (error) {
-  console.error(chalk.red(`Error: ${error.message}`));
-  throw new Error(`Operation failed: ${error.message}`);
-}
-```
-
-### Input Validation
-- Validate all function parameters
-- Check for null/undefined values
-- Validate file paths and existence
-- Validate app names (alphanumeric, hyphens, underscores)
-- Pattern:
-```javascript
-function validateAppName(appName) {
-  if (!appName || typeof appName !== 'string') {
-    throw new Error('App name is required and must be a string');
-  }
-  if (!/^[a-z0-9-_]+$/.test(appName)) {
-    throw new Error('App name must contain only lowercase letters, numbers, hyphens, and underscores');
-  }
-}
-```
-
-### Async/Await
-- Always use async/await, never raw promises
-- Always use try-catch with async operations
-- Return appropriate default values on error (empty arrays, null, etc.)
-- Pattern:
-```javascript
-async function getItems() {
-  try {
-    const items = await fetchItems();
-    return items || [];
-  } catch (error) {
-    console.error('Failed to get items:', error);
-    return [];
-  }
-}
-```
-
-### File Operations
-- Use `fs.promises` for async file operations
-- Use `fs.existsSync` for synchronous checks when needed
-- Always handle file not found errors
-- Use `path.join()` for cross-platform path construction
-- Pattern:
-```javascript
-const fs = require('fs').promises;
-const path = require('path');
-
-const filePath = path.join(process.cwd(), 'builder', appName, 'application.yaml');
-try {
-  const content = await fs.readFileSync(filePath, 'utf8');
-  // Process content
-} catch (error) {
-  if (error.code === 'ENOENT') {
-    throw new Error(`File not found: ${filePath}`);
-  }
-  throw error;
-}
-```
-
-## Testing Conventions
-
-### Test File Structure
-- Test files mirror source structure: `tests/lib/app.test.js`
-- Use Jest for testing framework
-- Mock all external dependencies (fs, axios, child_process)
-- Test both success and error paths
-- Test edge cases (missing files, invalid YAML, etc.)
-
-### Test Organization
-```yaml
-tests/
-├── lib/
-│   ├── app.test.js
-│   ├── validator.test.js
-│   ├── cli.test.js
-│   └── generator.test.js
-├── bin/
-│   └── aifabrix.test.js
-└── integration/
-    ├── build.test.js
-    └── deploy.test.js
-```
-
-### Mock Patterns
-- Mock fs operations: `jest.mock('fs')` or `jest.mock('fs').promises`
-- Mock axios: `jest.mock('axios')` or use `makeApiCall` mock
-- Mock API client: `jest.mock('../lib/api')` or mock individual API modules
-- Mock child_process: `jest.mock('child_process')`
-- Mock templates: provide test templates in `tests/fixtures/`
-- Pattern:
-```javascript
-jest.mock('fs');
-jest.mock('fs').promises;
-jest.mock('../lib/api/auth.api');
-
-const fs = require('fs');
-const fsp = require('fs').promises;
-const { getToken } = require('../lib/api/auth.api');
-
-describe('ModuleName', () => {
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
-
-  it('should handle success case', async () => {
-    fsp.readFile = jest.fn().resolves('content');
-    getToken = jest.fn().resolves({ success: true, token: 'test-token' });
-    // Test implementation
-  });
-
-  it('should handle error case', async () => {
-    fsp.readFile = jest.fn().rejects(new Error('File not found'));
-    getToken = jest.fn().resolves({ success: false, error: 'Auth failed' });
-    // Test error handling
-  });
-});
-```
-
-### API Client Testing Pattern
-Test API modules by mocking the base client:
-```javascript
-jest.mock('../lib/api/index');
-
-const { ApiClient } = require('../lib/api/index');
-const { getToken } = require('../lib/api/auth.api');
-
-describe('auth.api', () => {
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
-
-  it('should get token successfully', async () => {
-    const mockResponse = { success: true, token: 'test-token' };
-    ApiClient.prototype.post = jest.fn().resolves(mockResponse);
-    
-    const result = await getToken('client-id', 'secret', 'https://controller');
-    expect(result).toEqual(mockResponse);
-    expect(ApiClient.prototype.post).toHaveBeenCalledWith(
-      '/api/v1/auth/token',
-      expect.objectContaining({
-        headers: expect.objectContaining({
-          'x-client-id': 'client-id',
-          'x-client-secret': 'secret'
-        })
-      })
-    );
-  });
-});
-```
-
-### Test Coverage
-- Aim for 80%+ branch coverage
-- Test edge cases (null tokens, empty arrays, file errors)
-- Test validation failures
-- Test template rendering
-- Test Docker operations (mocked)
-
-## Security & Compliance (ISO 27001)
-
-### Information Security Management
-- All code must follow ISO 27001 information security standards
-- Implement proper access controls and authentication mechanisms
-- Ensure data confidentiality, integrity, and availability
-- Document all security-related decisions and implementations
-- Regular security reviews and vulnerability assessments required
-
-### Data Protection
-- **No hardcoded secrets, passwords, or sensitive data in code**
-- Use environment variables and secure configuration management
-- Implement proper input validation and sanitization
-- Follow principle of least privilege for all operations
-- Encrypt sensitive data at rest and in transit
-- Never log sensitive information (passwords, tokens, secrets)
-
-### Secret Management
-- Use `kv://` references in env.template for secrets
-- Resolve secrets via `lib/secrets.js` before deployment
-- Never expose secrets in generated files
-- Mask secrets in logs and error messages
-- Pattern:
-```javascript
-// In env.template
-DATABASE_PASSWORD=kv://secrets/database/password
-
-// In secrets.js
-function resolveSecret(key) {
-  // Resolve from secure key store
-  // Never log the actual value
-}
-```
-
-### Audit & Compliance
-- All actions must be logged and auditable
-- Use `lib/audit-logger.js` for audit logging
-- Maintain comprehensive documentation for compliance
-- Regular code reviews and security assessments
-- Version control all changes with proper commit messages
-- Document all dependencies and their security implications
-
-### Input Validation
-- Sanitize all user inputs (app names, file paths, URLs)
-- Validate YAML syntax before processing
-- Validate JSON schemas before deployment
-- Prevent path traversal attacks
-- Validate URLs and endpoints
-
-### Infrastructure Security
-- Use secure container configurations
-- Implement proper network security
-- Follow Docker security best practices
-- Use secure base images and dependencies
-- Validate Dockerfile security before generation
-
-## Code Quality Standards
-
-### File Size Limits
-- **Maximum 500 lines per file** - Split large files into smaller, focused modules
-- **Maximum 50 lines per function/method** - Break down complex functions
-- Use composition over inheritance to reduce complexity
-- Extract reusable components and utilities
-
-### Code Organization
-- Follow single responsibility principle
-- Use meaningful, descriptive names for variables and functions
-- Implement proper error handling and logging
-- Write self-documenting code with clear comments
-- Use JSDoc for all public functions
-
-### Documentation Requirements
-- **JSDoc comments for all public functions**
-- Include parameter types and return types
-- Document error conditions
-- Add examples in comments for complex methods
-- Document security considerations
-- **Visual Documentation**: Use canonical Mermaid diagram templates from [flows-and-visuals.md](flows-and-visuals.md) for architecture diagrams and workflow visualizations
-  - Use Template 1 for overall Builder architecture
-  - Use Template 2 for application creation flows
-  - Use Template 3 for development lifecycle workflows
-  - Use Template 4 for wizard/external system flows
-  - Follow strict styling guidelines (colors, fonts, spacing) defined in flows-and-visuals.md
-
-### Code Comments
-- Use JSDoc format for function documentation
-- Include `@fileoverview` at top of each file
-- Include `@author` and `@version` tags
-- Use inline comments for complex logic
-- Pattern:
-```javascript
-/**
- * Function description
- * @async
- * @function functionName
- * @param {string} appName - Application name
- * @param {Object} options - Configuration options
- * @param {number} [options.port] - Application port (optional)
- * @returns {Promise<void>} Resolves when operation completes
- * @throws {Error} If app name is invalid or operation fails
- *
- * @example
- * await functionName('myapp', { port: 3000 });
- */
-```
-
-## Development Workflow
-
-### Pre-Development
-1. Analyze requirements and create detailed specifications
-2. Design architecture following security best practices
-3. Plan test cases before writing implementation
-4. Review existing code for potential security vulnerabilities
-
-### During Development
-1. Write tests first (TDD approach)
-2. Implement functionality with security in mind
-3. Follow coding standards and file size limits
-4. Document all security-related decisions
-5. Use proper error handling and logging
-6. Validate all inputs
-7. Use JSDoc for documentation
-
-### Post-Development
-1. **Build project** - Run `npm run build` (lint + test)
-2. **Validate linting** - Run `npm run lint` and fix all issues
-3. **Run tests** - Execute `npm test` and ensure 100% pass rate
-4. **Check coverage** - Ensure 80%+ coverage for new code
-5. **Security review** - Check for vulnerabilities and compliance
-6. **Code review** - Peer review for quality and security
-
-## CLI Command Development
-
-### Adding New Commands
-1. Add command definition in `lib/cli.js`
-2. Implement command logic in `lib/commands/` or appropriate module
-3. Add input validation
-4. Add error handling with user-friendly messages
-5. Use chalk for colored output
-6. Write tests for the command
-
-### Command Pattern
-```javascript
-program.command('new-command')
-  .description('Clear description of what the command does')
-  .option('-f, --flag <value>', 'Option description', defaultValue)
-  .action(async (options) => {
-    try {
-      // Validate inputs
-      if (!options.required) {
-        throw new Error('Required option missing');
-      }
-
-      // Execute command
-      const result = await executeCommand(options);
-      
-      // Success message
-      console.log(chalk.green(`✓ Success: ${result}`));
-    } catch (error) {
-      console.error(chalk.red(`✗ Error: ${error.message}`));
-      process.exit(1);
-    }
-  });
-```
-
-### User Experience
-- Provide clear, actionable error messages
-- Use emoji/icons for visual feedback (✓, ✗, ⚠️, 🔐, etc.)
-- Show progress for long-running operations (use ora spinner)
-- Provide helpful hints in error messages
-- Use consistent formatting across commands
-
-## Template Development
-
-### Template Location
-- Templates in `templates/` directory
-- Organize by type: `templates/typescript/`, `templates/python/`, `templates/github/`
-- Use `.hbs` extension for Handlebars templates
-
-### Template Patterns
-- Use Handlebars helpers for conditionals: `{{#if condition}}`
-- Use Handlebars loops: `{{#each items}}`
-- Use context variables: `{{variableName}}`
-- Provide default values: `{{variableName default="value"}}`
-- Pattern:
-```handlebars
-# {{appName}} Dockerfile
-FROM {{baseImage}}
-{{#if hasDatabase}}
-ENV DATABASE_URL={{databaseUrl}}
-{{/if}}
-```
-
-### Template Context
-- Build context object with all necessary variables
-- Validate context before rendering
-- Provide sensible defaults for optional values
-- Document required context variables
-
-## Validation Patterns
-
-### Schema Validation
-- Define schemas in `lib/schema/` directory
-- Use JSON Schema format
-- Validate before deployment
-- Provide developer-friendly error messages
-- Pattern:
-```javascript
-const schema = require('./schema/application-schema.json');
-const ajv = new Ajv({ allErrors: true });
-const validate = ajv.compile(schema);
-
-if (!validate(data)) {
-  const errors = validate.errors.map(err => 
-    `${err.instancePath} ${err.message}`
-  ).join(', ');
-  throw new Error(`Validation failed: ${errors}`);
-}
-```
-
-### YAML Validation
-- Validate YAML syntax before parsing
-- Validate against schemas after parsing
-- Provide line numbers in error messages when possible
-- Pattern:
-```javascript
-try {
-  const parsed = yaml.load(content);
-  await validateAgainstSchema(parsed);
-} catch (error) {
-  if (error.message.includes('YAML')) {
-    throw new Error(`Invalid YAML syntax: ${error.message}`);
-  }
-  throw error;
-}
-```
-
-## Docker & Infrastructure
-
-### Dockerfile Generation
-- Auto-detect runtime (TypeScript/Python)
-- Use appropriate base images
-- Follow security best practices
-- Minimize image size
-- Pattern in `lib/app-dockerfile.js`:
-```javascript
-function detectRuntime(appPath) {
-  // Check for package.json (Node.js/TypeScript)
-  // Check for requirements.txt (Python)
-  // Return appropriate template
-}
-```
-
-### Docker Compose
-- Infrastructure templates in `templates/infra/`
-- Use environment variables for configuration
-- Follow Docker security best practices
-- Validate compose files before deployment
-
-## Common Patterns
-
-### App Name Validation
-```javascript
-function validateAppName(appName) {
-  if (!appName || typeof appName !== 'string') {
-    throw new Error('App name is required and must be a string');
-  }
-  if (!/^[a-z0-9-_]+$/.test(appName)) {
-    throw new Error('App name must contain only lowercase letters, numbers, hyphens, and underscores');
-  }
-}
-```
-
-### File Path Construction
-```javascript
-const path = require('path');
-
-const appPath = path.join(process.cwd(), 'builder', appName);
-const configPath = path.join(appPath, 'application.yaml');
-```
-
-### Configuration Loading
-```javascript
-async function loadConfig(appName) {
-  const configPath = path.join(process.cwd(), 'builder', appName, 'application.yaml');
-  const content = await fs.readFile(configPath, 'utf8');
-  return yaml.load(content);
-}
-```
-
-### Template Rendering
-```javascript
-const Handlebars = require('handlebars');
-const fs = require('fs');
-
-const templatePath = path.join(__dirname, '../templates/typescript/Dockerfile.hbs');
-const templateContent = fs.readFileSync(templatePath, 'utf8');
-const template = Handlebars.compile(templateContent);
-const rendered = template(context);
-await fs.writeFile(outputPath, rendered, 'utf8');
-```
-
-### API Client Usage
-Use the centralized API client for all API calls:
-```javascript
-const { getToken } = require('../api/auth.api');
-const { registerApplication } = require('../api/applications.api');
-
-// Typed API calls with automatic error handling
-try {
-  const tokenResponse = await getToken(clientId, clientSecret, controllerUrl);
-  if (!tokenResponse.success) {
-    throw new Error(tokenResponse.formattedError || 'Authentication failed');
-  }
-  
-  const appResponse = await registerApplication(
-    controllerUrl,
-    environment,
-    registrationData,
-    tokenResponse.token
-  );
-} catch (error) {
-  console.error(chalk.red(`Error: ${error.message}`));
-  throw error;
-}
-```
-
-### Type Definition Pattern
-Define request/response types using JSDoc `@typedef`:
-```javascript
-/**
- * Application registration request
- * @typedef {Object} RegisterApplicationRequest
- * @property {string} appKey - Application key
- * @property {string} name - Application name
- * @property {string} [description] - Application description (optional)
- * @property {string[]} [tags] - Application tags (optional)
- */
-
-/**
- * Application registration response
- * @typedef {Object} RegisterApplicationResponse
- * @property {boolean} success - Request success flag
- * @property {Object} data - Response data
- * @property {string} data.appKey - Registered application key
- * @property {string} data.clientId - Generated client ID
- * @property {string} data.clientSecret - Generated client secret
- */
-```
-
-## Quality Gates
-
-### Mandatory Checks Before Commit
-1. ✅ File size limits respected (≤500 lines, ≤50 lines per function)
-2. ✅ All functions have corresponding tests
-3. ✅ Tests are in `tests/` folder (not in code directories)
-4. ✅ Build process completes successfully (`npm run build`)
-5. ✅ Linting passes with no errors (`npm run lint`)
-6. ✅ All tests pass (100% success rate)
-7. ✅ Test coverage ≥80% for new code
-8. ✅ Security review completed
-9. ✅ Documentation updated (JSDoc comments)
-10. ✅ No hardcoded secrets or sensitive data
-
-### Continuous Integration
-- Automated testing on all pull requests
-- Security scanning and vulnerability assessment
-- Code quality metrics and coverage reporting
-- Automated deployment validation
-- Linting enforcement
-
-## Error Handling & Logging
-
-### Error Handling
-- Implement comprehensive error handling
-- Use structured error messages with context
-- Log all errors with appropriate context
-- Never expose sensitive information in error messages
-- Use chalk for colored error output
-- Provide actionable error messages
-
-### Logging Standards
-- Use console.log for normal output (with chalk coloring)
-- Use console.error for errors
-- Use console.warn for warnings
-- Use ora spinner for progress indication
-- Never log secrets, passwords, or tokens
-- Use structured logging for audit trail
-
-## Dependencies & Security
-
-### Dependency Management
-- Regularly update dependencies for security patches
-- Use only trusted and well-maintained packages
-- Implement dependency scanning and vulnerability assessment
-- Document all dependencies and their purposes
-- Review security advisories regularly
-
-### Security Scanning
-- Regular security scans of dependencies
-- Vulnerability assessment and remediation
-- Security testing in CI/CD pipeline
-- Regular security audits and reviews
-- Use `npm audit` regularly
-
-## When Adding New Features
-
-1. **Plan** - Analyze requirements and design architecture
-2. **Test First** - Write tests before implementation (TDD)
-3. **Implement** - Write code following all patterns and standards
-4. **Validate** - Run build, lint, and tests
-5. **Document** - Add JSDoc comments and update README if needed
-6. **Security Review** - Check for vulnerabilities and compliance
-7. **Code Review** - Peer review for quality and security
-
-## Critical Rules
-
-### Must Do (✅)
-- ✅ Validate all inputs (app names, file paths, URLs)
-- ✅ When fixing bugs in integration/ or builder/ output: identify the generator that produces the file and fix the source (lib/generator, lib/commands, templates), not only the generated artifact
-- ✅ Use try-catch for all async operations
-- ✅ Provide meaningful error messages with context
-- ✅ Use JSDoc for all public functions
-- ✅ Write tests for all functions
-- ✅ Keep files ≤500 lines and functions ≤50 lines
-- ✅ Use chalk for colored output in CLI
-- ✅ Use path.join() for cross-platform paths
-- ✅ Validate YAML syntax before parsing
-- ✅ Never log secrets or sensitive data
-- ✅ Use centralized API client (`lib/api/`) for new API calls
-- ✅ Define request/response types using JSDoc `@typedef` in `lib/api/types/`
-- ✅ Use domain-specific API modules (`lib/api/*.api.js`) instead of direct `makeApiCall`
-- ✅ When adding lib/api functions that call Controller/Dataplane, add `@requiresPermission` JSDoc per [permissions-guide.md](permissions-guide.md)
-
-### Must Not Do (❌)
-- ❌ Never hardcode secrets, passwords, or tokens
-- ❌ Never hardcode lab/training integration names, vendor names, or internal plan IDs in generic CLI/helpers (`lib/commands/**`, `lib/cli/**`, shared `lib/utils/*-error*.js`); use dynamic keys from user input, manifests, and secrets — see [cli-product-neutral.mdc](cli-product-neutral.mdc)
-- ❌ Never expose sensitive data in error messages
-- ❌ Never use synchronous file operations in async functions (unless necessary)
-- ❌ Never ignore errors or use empty catch blocks
-- ❌ Never commit files with secrets or sensitive data
-- ❌ Never skip input validation
-- ❌ Never skip tests for new functionality
-- ❌ Never use `eval()` or `Function()` constructor
-- ❌ Never use raw paths (always use path.join)
-- ❌ Never make direct API calls using `makeApiCall` in new code (use `lib/api/` modules)
-- ❌ Never treat one-off edits in integration/ or builder/ as the permanent fix for a bug—update the generator or template that produces the file
-- ❌ Never skip type definitions for API request/response types
-- ❌ Never log authentication tokens or secrets in API calls
-
----
-
-**Remember**: Security is not optional. Every line of code must be written with security and compliance in mind. When in doubt, choose the more secure option and document the decision.