@aifabrix/builder 2.11.0 → 2.21.0

package/lib/api/types/environments.types.js

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview Environments API type definitions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Pagination metadata
+ * @typedef {Object} PaginationMeta
+ * @property {number} page - Current page number
+ * @property {number} pageSize - Number of items per page
+ * @property {number} total - Total number of items
+ * @property {number} totalPages - Total number of pages
+ */
+
+/**
+ * Pagination links
+ * @typedef {Object} PaginationLinks
+ * @property {string} self - Current page URL
+ * @property {string} first - First page URL
+ * @property {string} last - Last page URL
+ * @property {string|null} prev - Previous page URL (null if on first page)
+ * @property {string|null} next - Next page URL (null if on last page)
+ */
+
+/**
+ * Environment configuration (references environment-config.schema.yaml)
+ * @typedef {Object} EnvironmentConfig
+ * @property {string} key - Environment key
+ * @property {string} environment - Environment type ('dev' | 'tst' | 'pro' | 'miso')
+ * @property {string} preset - Deployment preset size
+ * @property {string} serviceName - Service name
+ * @property {string} location - Azure region location
+ * @property {*} [additionalProperties] - Additional configuration properties
+ */
+
+/**
+ * Environment entity
+ * @typedef {Object} Environment
+ * @property {string} id - Environment ID
+ * @property {string} key - Environment key
+ * @property {string} environment - Environment type ('dev' | 'tst' | 'pro' | 'miso')
+ * @property {EnvironmentConfig} configuration - Environment configuration
+ * @property {string} status - Environment status
+ * @property {string} createdAt - Creation timestamp (ISO 8601)
+ * @property {string} updatedAt - Update timestamp (ISO 8601)
+ */
+
+/**
+ * List environments request options
+ * @typedef {Object} ListEnvironmentsRequest
+ * @property {number} [page] - Page number (default: 1)
+ * @property {number} [pageSize] - Items per page (default: 10)
+ * @property {string} [sort] - Sort parameter
+ * @property {string} [filter] - Filter parameter
+ * @property {string} [search] - Search term to match across key field
+ * @property {string} [environment] - Filter by environment type (legacy parameter)
+ * @property {string} [status] - Filter by status (legacy parameter)
+ */
+
+/**
+ * List environments response
+ * @typedef {Object} ListEnvironmentsResponse
+ * @property {PaginationMeta} meta - Pagination metadata
+ * @property {Environment[]} data - Array of environments
+ * @property {PaginationLinks} links - Pagination links
+ */
+
+/**
+ * Create environment request
+ * @typedef {Object} CreateEnvironmentRequest
+ * @property {string} key - Environment key (lowercase, numbers, hyphens only)
+ * @property {string} environment - Environment type ('dev' | 'tst' | 'pro')
+ * @property {EnvironmentConfig} configuration - Environment configuration
+ */
+
+/**
+ * Create environment response
+ * @typedef {Object} CreateEnvironmentResponse
+ * @property {Environment} data - Created environment
+ */
+
+/**
+ * Get environment response
+ * @typedef {Object} GetEnvironmentResponse
+ * @property {Environment} data - Environment details
+ */
+
+/**
+ * Update environment request
+ * @typedef {Object} UpdateEnvironmentRequest
+ * @property {EnvironmentConfig} [configuration] - Environment configuration
+ */
+
+/**
+ * Update environment response
+ * @typedef {Object} UpdateEnvironmentResponse
+ * @property {Environment} data - Updated environment
+ */
+
+/**
+ * Environment status
+ * @typedef {Object} EnvironmentStatus
+ * @property {number} id - Status ID
+ * @property {string} environmentId - Environment ID
+ * @property {string} status - Environment status ('healthy' | 'degraded' | 'deploying' | 'error' | 'maintenance')
+ * @property {Object} services - Services status object
+ * @property {number} resourceCount - Number of resources
+ * @property {number} costMonthly - Monthly cost
+ * @property {string} costCurrency - Cost currency
+ * @property {string|null} lastDeployment - Last deployment timestamp (ISO 8601)
+ * @property {string} healthCheckAt - Health check timestamp (ISO 8601)
+ */
+
+/**
+ * Get environment status response
+ * @typedef {Object} GetEnvironmentStatusResponse
+ * @property {EnvironmentStatus} data - Environment status
+ */
+
+/**
+ * List environment deployments request options
+ * @typedef {Object} ListEnvironmentDeploymentsRequest
+ * @property {number} [page] - Page number (default: 1)
+ * @property {number} [pageSize] - Items per page (default: 10)
+ * @property {string} [sort] - Sort parameter
+ * @property {string} [filter] - Filter parameter
+ * @property {string} [status] - Filter by deployment status (legacy parameter)
+ * @property {string} [deploymentType] - Filter by deployment type (legacy parameter)
+ */
+
+/**
+ * Deployment entity (for environment deployments list)
+ * @typedef {Object} Deployment
+ * @property {string} id - Deployment ID
+ * @property {string} deploymentType - Deployment type
+ * @property {string} status - Deployment status
+ * @property {number} progress - Deployment progress (0-100)
+ * @property {string} createdAt - Creation timestamp (ISO 8601)
+ */
+
+/**
+ * List environment deployments response
+ * @typedef {Object} ListEnvironmentDeploymentsResponse
+ * @property {PaginationMeta} meta - Pagination metadata
+ * @property {Deployment[]} data - Array of deployments
+ */
+
+/**
+ * Role mapping
+ * @typedef {Object} RoleMapping
+ * @property {string} id - Mapping ID
+ * @property {string} groupName - Group name
+ * @property {string|null} groupId - Group ID
+ * @property {boolean} isActive - Whether mapping is active
+ */
+
+/**
+ * Environment role
+ * @typedef {Object} EnvironmentRole
+ * @property {string} id - Role ID
+ * @property {string} name - Role name
+ * @property {string} value - Role value
+ * @property {string|null} description - Role description
+ * @property {RoleMapping[]} mappings - Role mappings
+ */
+
+/**
+ * List environment roles response
+ * @typedef {Object} ListEnvironmentRolesResponse
+ * @property {EnvironmentRole[]} data - Array of environment roles with mappings
+ */
+
+/**
+ * Role group mapping
+ * @typedef {Object} RoleGroupMapping
+ * @property {string} id - Mapping ID
+ * @property {string} roleId - Role ID
+ * @property {string} environmentId - Environment ID
+ * @property {string} groupName - Group name
+ * @property {boolean} isActive - Whether mapping is active
+ */
+
+/**
+ * Update role groups request
+ * @typedef {Object} UpdateRoleGroupsRequest
+ * @property {string[]} groups - Array of group names (minItems: 1)
+ */
+
+/**
+ * Update role groups response
+ * @typedef {Object} UpdateRoleGroupsResponse
+ * @property {RoleGroupMapping[]} data - Array of role group mappings
+ */
+
+module.exports = {};
+

package/lib/api/types/external-systems.types.js

@@ -0,0 +1,244 @@
+/**
+ * @fileoverview External Systems API type definitions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Pagination metadata
+ * @typedef {Object} PaginationMeta
+ * @property {number} page - Current page number
+ * @property {number} pageSize - Number of items per page
+ * @property {number} total - Total number of items
+ * @property {number} totalPages - Total number of pages
+ */
+
+/**
+ * Pagination links
+ * @typedef {Object} PaginationLinks
+ * @property {string} self - Current page URL
+ * @property {string} first - First page URL
+ * @property {string} last - Last page URL
+ * @property {string|null} prev - Previous page URL (null if on first page)
+ * @property {string|null} next - Next page URL (null if on last page)
+ */
+
+/**
+ * External system response
+ * @typedef {Object} ExternalSystemResponse
+ * @property {string} id - System ID
+ * @property {string} key - System key (unique identifier)
+ * @property {string} displayName - Display name
+ * @property {string|null} description - System description
+ * @property {string} type - System type ('openapi' | 'mcp' | 'custom')
+ * @property {string} status - Status ('draft' | 'published' | 'archived')
+ * @property {boolean} isActive - Whether system is active
+ * @property {Object} configuration - System configuration
+ * @property {string} createdAt - Creation timestamp (ISO 8601)
+ * @property {string} updatedAt - Update timestamp (ISO 8601)
+ */
+
+/**
+ * External system create request
+ * @typedef {Object} ExternalSystemCreate
+ * @property {string} key - System key
+ * @property {string} displayName - Display name
+ * @property {string} [description] - Description
+ * @property {string} type - System type ('openapi' | 'mcp' | 'custom')
+ * @property {Object} [configuration] - System configuration
+ */
+
+/**
+ * External system update request
+ * @typedef {Object} ExternalSystemUpdate
+ * @property {string} [displayName] - Display name
+ * @property {string} [description] - Description
+ * @property {Object} [configuration] - Configuration
+ * @property {boolean} [isActive] - Active status
+ */
+
+/**
+ * External system config response (with dataSources)
+ * @typedef {Object} ExternalSystemConfigResponse
+ * @property {ExternalSystemResponse} application - External system application schema
+ * @property {Object[]} dataSources - Array of datasource configurations
+ */
+
+/**
+ * List external systems request options
+ * @typedef {Object} ListExternalSystemsRequest
+ * @property {number} [page] - Page number (default: 1)
+ * @property {number} [pageSize] - Items per page (default: 20)
+ * @property {string} [sort] - Sort parameter
+ * @property {string} [filter] - Filter parameter
+ * @property {string} [search] - Search term
+ */
+
+/**
+ * List external systems response
+ * @typedef {Object} ListExternalSystemsResponse
+ * @property {ExternalSystemResponse[]} items - Array of external systems
+ * @property {PaginationMeta} meta - Pagination metadata
+ * @property {PaginationLinks} links - Pagination links
+ */
+
+/**
+ * Create external system request
+ * @typedef {ExternalSystemCreate} CreateExternalSystemRequest
+ */
+
+/**
+ * Create external system response
+ * @typedef {Object} CreateExternalSystemResponse
+ * @property {ExternalSystemResponse} data - Created external system
+ */
+
+/**
+ * Get external system response
+ * @typedef {Object} GetExternalSystemResponse
+ * @property {ExternalSystemResponse} data - External system details
+ */
+
+/**
+ * Update external system request
+ * @typedef {ExternalSystemUpdate} UpdateExternalSystemRequest
+ */
+
+/**
+ * Update external system response
+ * @typedef {Object} UpdateExternalSystemResponse
+ * @property {ExternalSystemResponse} data - Updated external system
+ */
+
+/**
+ * Delete external system response
+ * @typedef {Object} DeleteExternalSystemResponse
+ * @property {null} data - Always null for DELETE operations
+ */
+
+/**
+ * Get external system config response
+ * @typedef {Object} GetExternalSystemConfigResponse
+ * @property {ExternalSystemConfigResponse} data - Full config with application schema and dataSources
+ */
+
+/**
+ * Create from template request
+ * @typedef {Object} ExternalSystemCreateFromTemplate
+ * @property {string} templateIdOrKey - Integration template ID or key
+ * @property {string} key - System key
+ * @property {string} displayName - Display name
+ * @property {string} [description] - Description
+ * @property {Object} [configuration] - Override configuration
+ */
+
+/**
+ * Create from template request
+ * @typedef {ExternalSystemCreateFromTemplate} CreateFromTemplateRequest
+ */
+
+/**
+ * Create from template response
+ * @typedef {Object} CreateFromTemplateResponse
+ * @property {ExternalSystemResponse} data - Created external system (status='draft')
+ */
+
+/**
+ * List OpenAPI files request options
+ * @typedef {Object} ListOpenAPIFilesRequest
+ * @property {number} [page] - Page number
+ * @property {number} [pageSize] - Items per page
+ * @property {string} [sort] - Sort parameter
+ * @property {string} [filter] - Filter parameter
+ */
+
+/**
+ * List OpenAPI files response
+ * @typedef {Object} ListOpenAPIFilesResponse
+ * @property {Object[]} items - Array of OpenAPI files
+ * @property {PaginationMeta} meta - Pagination metadata
+ * @property {PaginationLinks} links - Pagination links
+ */
+
+/**
+ * List OpenAPI endpoints request options
+ * @typedef {Object} ListOpenAPIEndpointsRequest
+ * @property {number} [page] - Page number
+ * @property {number} [pageSize] - Items per page
+ * @property {string} [sort] - Sort parameter
+ * @property {string} [filter] - Filter parameter
+ */
+
+/**
+ * List OpenAPI endpoints response
+ * @typedef {Object} ListOpenAPIEndpointsResponse
+ * @property {Object[]} items - Array of OpenAPI endpoints
+ * @property {PaginationMeta} meta - Pagination metadata
+ * @property {PaginationLinks} links - Pagination links
+ */
+
+/**
+ * Publish external system request
+ * @typedef {Object} ExternalSystemPublishRequest
+ * @property {boolean} [generateMcpContract] - Whether to generate MCP contract
+ */
+
+/**
+ * Publish external system request
+ * @typedef {ExternalSystemPublishRequest} PublishExternalSystemRequest
+ */
+
+/**
+ * Publish external system response
+ * @typedef {Object} PublishExternalSystemResponse
+ * @property {ExternalSystemResponse} data - Published external system
+ */
+
+/**
+ * Rollback external system request
+ * @typedef {Object} ExternalSystemRollbackRequest
+ * @property {number} version - Version to rollback to
+ */
+
+/**
+ * Rollback external system request
+ * @typedef {ExternalSystemRollbackRequest} RollbackExternalSystemRequest
+ */
+
+/**
+ * Rollback external system response
+ * @typedef {Object} RollbackExternalSystemResponse
+ * @property {ExternalSystemResponse} data - Rolled back external system
+ */
+
+/**
+ * Save template request
+ * @typedef {Object} ExternalSystemSaveTemplateRequest
+ * @property {string} templateKey - Template key
+ * @property {string} templateName - Template name
+ * @property {string} [description] - Template description
+ */
+
+/**
+ * Save template request
+ * @typedef {ExternalSystemSaveTemplateRequest} SaveAsTemplateRequest
+ */
+
+/**
+ * Integration template response
+ * @typedef {Object} IntegrationTemplateResponse
+ * @property {string} id - Template ID
+ * @property {string} key - Template key
+ * @property {string} name - Template name
+ * @property {string} [description] - Template description
+ * @property {Object} configuration - Template configuration
+ */
+
+/**
+ * Save template response
+ * @typedef {Object} SaveAsTemplateResponse
+ * @property {IntegrationTemplateResponse} data - Saved integration template
+ */
+
+module.exports = {};
+

package/lib/api/types/pipeline.types.js

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview Pipeline API type definitions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Application configuration (references application-config.schema.yaml)
+ * @typedef {Object} ApplicationConfig
+ * @property {string} key - Unique application identifier
+ * @property {string} displayName - Human-readable application name
+ * @property {string} description - Application description
+ * @property {string} type - Azure application type
+ * @property {string} deploymentKey - SHA256 hash of deployment manifest
+ * @property {*} [additionalProperties] - Additional configuration properties
+ */
+
+/**
+ * Validation request
+ * @typedef {Object} ValidationRequest
+ * @property {string} clientId - Client ID for application authentication
+ * @property {string} repositoryUrl - Full repository URL for pipeline validation (GitHub, Azure DevOps, GitLab)
+ * @property {Object} applicationConfig - Application configuration
+ * @property {string} applicationConfig.key - Application key
+ */
+
+/**
+ * Validation response
+ * @typedef {Object} ValidationResponse
+ * @property {boolean} valid - Validation success flag
+ * @property {string|null} validateToken - One-time deployment token for /deploy endpoint (64 bytes, 512 bits entropy)
+ * @property {string|null} imageServer - Azure Container Registry server URL
+ * @property {string|null} imageUsername - ACR username for image push/pull
+ * @property {string|null} imagePassword - ACR password/token for image push/pull
+ * @property {string|null} expiresAt - Token expiration timestamp (ISO 8601)
+ * @property {string|null} draftDeploymentId - Draft deployment ID created during validation
+ * @property {string[]} errors - Array of validation errors (empty on success)
+ */
+
+/**
+ * Validate pipeline request
+ * @typedef {Object} ValidatePipelineRequest
+ * @property {string} clientId - Client ID (via x-client-id header or body)
+ * @property {string} repositoryUrl - Repository URL for validation
+ * @property {ApplicationConfig} applicationConfig - Application configuration to validate
+ */
+
+/**
+ * Validate pipeline response
+ * @typedef {Object} ValidatePipelineResponse
+ * @property {boolean} valid - Validation success flag
+ * @property {string|null} validateToken - One-time deployment token
+ * @property {string|null} imageServer - ACR server URL
+ * @property {string|null} imageUsername - ACR username
+ * @property {string|null} imagePassword - ACR password/token
+ * @property {string|null} expiresAt - Token expiration timestamp
+ * @property {string|null} draftDeploymentId - Draft deployment ID
+ * @property {string[]} errors - Validation errors array
+ */
+
+/**
+ * Deploy request
+ * @typedef {Object} DeployRequest
+ * @property {string} validateToken - One-time deployment token obtained from /validate endpoint (required)
+ * @property {string} imageTag - Container image tag to deploy (e.g., "latest", "v1.0.0", "main-abc123")
+ */
+
+/**
+ * Deploy pipeline request
+ * @typedef {Object} DeployPipelineRequest
+ * @property {string} validateToken - One-time deployment token (required)
+ * @property {string} imageTag - Container image tag to deploy
+ */
+
+/**
+ * Deploy pipeline response
+ * @typedef {Object} DeployPipelineResponse
+ * @property {boolean} success - Request success flag
+ * @property {string} deploymentId - Deployment ID
+ * @property {string} status - Deployment status (e.g., 'pending', 'deploying')
+ * @property {string|null} deploymentUrl - Deployment URL if available
+ * @property {string|null} healthCheckUrl - Health check URL if available
+ * @property {string} message - Deployment message
+ * @property {string} timestamp - Timestamp when deployment was initiated (ISO 8601)
+ */
+
+/**
+ * Pipeline deployment status
+ * @typedef {Object} PipelineDeploymentStatus
+ * @property {string} id - Deployment ID
+ * @property {string} status - Deployment status ('pending' | 'deploying' | 'completed' | 'failed')
+ * @property {number} progress - Deployment progress percentage (0-100)
+ * @property {string|null} message - Deployment message if available
+ * @property {string|null} error - Error message if deployment failed
+ * @property {string|null} startedAt - Deployment start timestamp (ISO 8601)
+ * @property {string|null} completedAt - Deployment completion timestamp (ISO 8601)
+ * @property {string|null} deploymentUrl - Deployment URL if available
+ * @property {string|null} healthCheckUrl - Health check URL if available
+ */
+
+/**
+ * Get pipeline deployment request
+ * @typedef {Object} GetPipelineDeploymentRequest
+ * @property {string} deploymentId - Deployment ID
+ */
+
+/**
+ * Get pipeline deployment response
+ * @typedef {Object} GetPipelineDeploymentResponse
+ * @property {boolean} success - Request success flag
+ * @property {PipelineDeploymentStatus} data - Minimal deployment status
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Pipeline health check response
+ * @typedef {Object} GetPipelineHealthResponse
+ * @property {boolean} success - Request success flag
+ * @property {Object} data - Health check data
+ * @property {boolean} data.healthy - Health status
+ * @property {string} data.environment - Environment key
+ */
+
+module.exports = {};
+

package/lib/app-list.js

@@ -11,7 +11,7 @@
 const chalk = require('chalk');
 const { getConfig } = require('./config');
 const { getOrRefreshDeviceToken } = require('./utils/token-manager');
-const { authenticatedApiCall } = require('./utils/api');
+const { listEnvironmentApplications } = require('./api/environments.api');
 const { formatApiError } = require('./utils/api-error-handler');
 const logger = require('./utils/logger');
 
@@ -22,7 +22,7 @@ const logger = require('./utils/logger');
  * 2. Direct array: { success: true, data: [...] }
  * 3. Paginated format: { success: true, data: { items: [...] } }
  * 4. Wrapped paginated: { success: true, data: { success: true, data: { items: [...] } } }
- * @param {Object} response - API response from authenticatedApiCall
+ * @param {Object} response - API response from centralized API client
  * @returns {Array} Array of applications
  * @throws {Error} If response format is invalid
  */
@@ -109,11 +109,9 @@ async function listApplications(options) {
     process.exit(1);
   }
 
-  const response = await authenticatedApiCall(
-    `${controllerUrl}/api/v1/environments/${options.environment}/applications`,
-    {},
-    token
-  );
+  // Use centralized API client
+  const authConfig = { type: 'bearer', token: token };
+  const response = await listEnvironmentApplications(controllerUrl, options.environment, authConfig);
 
   if (!response.success || !response.data) {
     const formattedError = response.formattedError || formatApiError(response);

package/lib/app-rotate-secret.js

@@ -11,7 +11,7 @@
 const chalk = require('chalk');
 const { getConfig } = require('./config');
 const { getOrRefreshDeviceToken } = require('./utils/token-manager');
-const { authenticatedApiCall } = require('./utils/api');
+const { rotateApplicationSecret } = require('./api/applications.api');
 const { formatApiError } = require('./utils/api-error-handler');
 const logger = require('./utils/logger');
 const { saveLocalSecret, isLocalhost } = require('./utils/local-secrets');
@@ -115,15 +115,9 @@ async function rotateSecret(appKey, options) {
   // Validate environment
   validateEnvironment(options.environment);
 
-  // OpenAPI spec: POST /api/v1/environments/{envKey}/applications/{appKey}/rotate-secret
-  // Path parameters: envKey, appKey (no query parameters)
-  const response = await authenticatedApiCall(
-    `${controllerUrl}/api/v1/environments/${encodeURIComponent(options.environment)}/applications/${encodeURIComponent(appKey)}/rotate-secret`,
-    {
-      method: 'POST'
-    },
-    token
-  );
+  // Use centralized API client
+  const authConfig = { type: 'bearer', token: token };
+  const response = await rotateApplicationSecret(controllerUrl, options.environment, appKey, authConfig);
 
   if (!response.success) {
     const formattedError = response.formattedError || formatApiError(response);

package/lib/cli.js

@@ -340,6 +340,36 @@ function setupCommands(program) {
       }
     });
 
+  program.command('app split-json <app-name>')
+    .description('Split deployment JSON into component files (env.template, variables.yaml, rbac.yml, README.md)')
+    .option('-o, --output <dir>', 'Output directory for component files (defaults to same directory as JSON)')
+    .action(async(appName, options) => {
+      try {
+        const fs = require('fs');
+        const { detectAppType, getDeployJsonPath } = require('./utils/paths');
+        const { appPath, appType } = await detectAppType(appName);
+        const deployJsonPath = getDeployJsonPath(appName, appType, true);
+
+        if (!fs.existsSync(deployJsonPath)) {
+          throw new Error(`Deployment JSON file not found: ${deployJsonPath}`);
+        }
+
+        const outputDir = options.output || appPath;
+        const result = await generator.splitDeployJson(deployJsonPath, outputDir);
+
+        logger.log(chalk.green('\n✓ Successfully split deployment JSON into component files:'));
+        logger.log(`  • env.template: ${result.envTemplate}`);
+        logger.log(`  • variables.yaml: ${result.variables}`);
+        if (result.rbac) {
+          logger.log(`  • rbac.yml: ${result.rbac}`);
+        }
+        logger.log(`  • README.md: ${result.readme}`);
+      } catch (error) {
+        handleCommandError(error, 'app split-json');
+        process.exit(1);
+      }
+    });
+
   program.command('json <app>')
     .description('Generate deployment JSON (aifabrix-deploy.json for normal apps, application-schema.json for external systems)')
     .action(async(appName) => {