@aifabrix/builder 2.11.0 → 2.21.0

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

@@ -47,6 +47,23 @@ lib/
 ├── 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
 ```
@@ -140,6 +157,92 @@ if (!valid) {
 }
 ```
 
+### 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`
+
 ## Code Style
 
 ### JavaScript Conventions
@@ -255,15 +358,18 @@ tests/
 ### 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(() => {
@@ -272,16 +378,50 @@ describe('ModuleName', () => {
 
   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)
@@ -585,6 +725,54 @@ 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
@@ -663,6 +851,9 @@ await fs.writeFile(outputPath, rendered, 'utf8');
 - ✅ 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`
 
 ### Must Not Do (❌)
 - ❌ Never hardcode secrets, passwords, or tokens
@@ -674,6 +865,9 @@ await fs.writeFile(outputPath, rendered, 'utf8');
 - ❌ 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 skip type definitions for API request/response types
+- ❌ Never log authentication tokens or secrets in API calls
 
 ---
 

package/README.md

@@ -68,6 +68,18 @@ aifabrix run miso-controller
 4. **Run** - Start locally, connected to infrastructure
 5. **Deploy** - Push to ACR and deploy via controller
 
+```mermaid
+flowchart TD
+    Install[Install CLI] --> Up[Start Infrastructure]
+    Up --> Create[Create App]
+    Create --> Build[Build Image]
+    Build --> Run[Run Locally]
+    Run --> Deploy[Deploy to Azure]
+    
+    style Install fill:#0062FF,color:#FFFFFF
+    style Deploy fill:#10B981,color:#FFFFFF
+```
+
 ## Requirements
 
 - **Docker Desktop** - For running containers

package/lib/api/applications.api.js

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Applications API functions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { ApiClient } = require('./index');
+
+/**
+ * List all template applications
+ * GET /api/v1/applications
+ * @async
+ * @function listApplications
+ * @param {string} controllerUrl - Controller base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} [options] - List options
+ * @param {number} [options.page] - Page number
+ * @param {number} [options.pageSize] - Items per page
+ * @param {string} [options.sort] - Sort parameter
+ * @param {string} [options.filter] - Filter parameter
+ * @param {string} [options.search] - Search term
+ * @returns {Promise<Object>} Paginated list of template applications
+ * @throws {Error} If request fails
+ */
+async function listApplications(controllerUrl, authConfig, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get('/api/v1/applications', {
+    params: options
+  });
+}
+
+/**
+ * Create new template application
+ * POST /api/v1/applications
+ * @async
+ * @function createApplication
+ * @param {string} controllerUrl - Controller base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} applicationData - Application data
+ * @param {string} applicationData.key - Application key
+ * @param {string} applicationData.displayName - Display name
+ * @param {Object} applicationData.configuration - Application configuration
+ * @param {string} [applicationData.description] - Application description
+ * @param {string} [applicationData.url] - Application URL
+ * @returns {Promise<Object>} Created application response
+ * @throws {Error} If creation fails
+ */
+async function createApplication(controllerUrl, authConfig, applicationData) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post('/api/v1/applications', {
+    body: applicationData
+  });
+}
+
+/**
+ * Get template application details
+ * GET /api/v1/applications/{appKey}
+ * @async
+ * @function getApplication
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} appKey - Application key
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<Object>} Application details response
+ * @throws {Error} If request fails
+ */
+async function getApplication(controllerUrl, appKey, authConfig) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(`/api/v1/applications/${appKey}`);
+}
+
+/**
+ * Update template application
+ * PATCH /api/v1/applications/{appKey}
+ * @async
+ * @function updateApplication
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} appKey - Application key
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} updateData - Update data
+ * @param {string} [updateData.displayName] - Display name
+ * @param {string} [updateData.description] - Description
+ * @param {string} [updateData.url] - URL
+ * @param {Object} [updateData.configuration] - Configuration
+ * @param {string} [updateData.status] - Status
+ * @returns {Promise<Object>} Updated application response
+ * @throws {Error} If update fails
+ */
+async function updateApplication(controllerUrl, appKey, authConfig, updateData) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.patch(`/api/v1/applications/${appKey}`, {
+    body: updateData
+  });
+}
+
+/**
+ * Delete template application
+ * DELETE /api/v1/applications/{appKey}
+ * @async
+ * @function deleteApplication
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} appKey - Application key
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<Object>} Delete response
+ * @throws {Error} If deletion fails
+ */
+async function deleteApplication(controllerUrl, appKey, authConfig) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.delete(`/api/v1/applications/${appKey}`);
+}
+
+/**
+ * Register application in an environment
+ * POST /api/v1/environments/{envKey}/applications/register
+ * @async
+ * @function registerApplication
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} registrationData - Registration data
+ * @param {string} registrationData.key - Application key
+ * @param {string} registrationData.displayName - Display name
+ * @param {string} registrationData.type - Application type
+ * @param {string} [registrationData.description] - Application description
+ * @param {string} [registrationData.registryMode] - Registry mode
+ * @param {number} [registrationData.port] - Application port
+ * @param {string} [registrationData.image] - Container image
+ * @param {Object} [registrationData.externalIntegration] - External integration config
+ * @returns {Promise<Object>} Registration response with application and credentials
+ * @throws {Error} If registration fails
+ */
+async function registerApplication(controllerUrl, envKey, authConfig, registrationData) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(`/api/v1/environments/${envKey}/applications/register`, {
+    body: registrationData
+  });
+}
+
+/**
+ * Rotate application secret
+ * POST /api/v1/environments/{envKey}/applications/{appKey}/rotate-secret
+ * @async
+ * @function rotateApplicationSecret
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @param {string} appKey - Application key
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<Object>} Response with new credentials
+ * @throws {Error} If rotation fails
+ */
+async function rotateApplicationSecret(controllerUrl, envKey, appKey, authConfig) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(`/api/v1/environments/${envKey}/applications/${appKey}/rotate-secret`);
+}
+
+module.exports = {
+  listApplications,
+  createApplication,
+  getApplication,
+  updateApplication,
+  deleteApplication,
+  registerApplication,
+  rotateApplicationSecret
+};
+