@boltic/cli 1.0.6-beta.11 → 1.0.6-beta.14

package/helper/validation.js

@@ -1,6 +1,21 @@
 import fs from "fs";
 import isEmpty from "lodash.isempty";
 import path from "path";
+import * as componentSchemas from "../templates/component-schemas.js";
+
+const validateOptionObject = (options, fieldName, fileLabel, errors) => {
+	options.forEach((opt, index) => {
+		const missingKeys = ["label", "value", "description"].filter(
+			(key) => !(key in opt)
+		);
+
+		if (missingKeys.length > 0) {
+			errors.add(
+				`"${fieldName}" field in "${fileLabel}" has an option at index ${index} missing keys: ${missingKeys.join(", ")}.`
+			);
+		}
+	});
+};
 
 const readAndParseJson = (filePath, fileLabel, errors) => {
 	try {
@@ -15,8 +30,7 @@ const readAndParseJson = (filePath, fileLabel, errors) => {
 		return null;
 	}
 };
-
-const findResourceFieldsWithOptions = (schema) => {
+const findResourceFieldsWithOptions = (schema, fileLabel, errors) => {
 	const resourceFields = [];
 	if (Array.isArray(schema?.parameters)) {
 		schema.parameters.forEach((param) => {
@@ -24,6 +38,12 @@ const findResourceFieldsWithOptions = (schema) => {
 				param.name === "resource" &&
 				Array.isArray(param.meta?.options)
 			) {
+				validateOptionObject(
+					param.meta.options,
+					"resource",
+					fileLabel,
+					errors
+				);
 				resourceFields.push(
 					...param.meta.options.map((opt) => opt.value)
 				);
@@ -32,24 +52,226 @@ const findResourceFieldsWithOptions = (schema) => {
 	}
 	return resourceFields;
 };
-
-const findOperationFieldsWithOptions = (schema) => {
+const findOperationFieldsWithOptions = (
+	schema,
+	fileLabel,
+	errors,
+	expectedResourceName
+) => {
 	const operationFields = [];
+
 	if (Array.isArray(schema?.parameters)) {
 		schema.parameters.forEach((param) => {
 			if (
 				param.name === "operation" &&
 				Array.isArray(param.meta?.options)
 			) {
-				operationFields.push(
-					...param.meta.options.map((opt) => opt.value)
+				validateOptionObject(
+					param.meta.options,
+					"operation",
+					fileLabel,
+					errors
 				);
+				param.meta.options.forEach((opt, index) => {
+					if (typeof opt.value === "string") {
+						const parts = opt.value.split(".");
+						if (parts.length < 2) {
+							errors.add(
+								`"operation" field in "${fileLabel}" has an invalid option at index ${index} with value "${opt.value}". Expected format "resource.operation".`
+							);
+						} else {
+							const resource = parts[0];
+							if (resource !== expectedResourceName) {
+								errors.add(
+									`"operation" field in "${fileLabel}" has an inconsistent resource prefix at index ${index}. Found "${resource}" but expected "${expectedResourceName}".`
+								);
+							}
+							operationFields.push(opt.value);
+						}
+					}
+				});
 			}
 		});
 	}
+
 	return operationFields;
 };
 
+// ─────────────────────────────────────────────────────────────────────────────
+// VALIDATE COMPONENT SCHEMAS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Extract all possible keys from a component schema structure recursively
+ * @param {Object} obj - The object to extract keys from
+ * @param {string} prefix - Current key prefix for nested objects
+ * @returns {Set<string>} Set of all allowed keys with dot notation for nested paths
+ */
+const extractAllowedKeys = (obj, prefix = "") => {
+	const allowedKeys = new Set();
+
+	Object.keys(obj).forEach((key) => {
+		const fullKey = prefix ? `${prefix}.${key}` : key;
+		allowedKeys.add(fullKey);
+
+		if (
+			typeof obj[key] === "object" &&
+			obj[key] !== null &&
+			!Array.isArray(obj[key])
+		) {
+			const nestedKeys = extractAllowedKeys(obj[key], fullKey);
+			nestedKeys.forEach((nestedKey) => allowedKeys.add(nestedKey));
+		}
+	});
+
+	return allowedKeys;
+};
+
+/**
+ * Validate that a schema object doesn't contain any extra keys
+ * @param {Object} schemaObj - The schema object to validate
+ * @param {Set<string>} allowedKeys - Set of allowed keys
+ * @param {string} schemaName - Name of the schema for error messages
+ * @param {string} displayType - The display type for error messages
+ * @param {Set} errors - Error collection
+ * @param {string} prefix - Current key prefix for nested objects
+ */
+const validateSchemaKeys = (
+	schemaObj,
+	allowedKeys,
+	schemaName,
+	displayType,
+	errors,
+	prefix = ""
+) => {
+	Object.keys(schemaObj).forEach((key) => {
+		const fullKey = prefix ? `${prefix}.${key}` : key;
+
+		if (!allowedKeys.has(fullKey)) {
+			errors.add(
+				`"${schemaName}" has an invalid key "${fullKey}" for displayType "${displayType}".`
+			);
+		}
+
+		if (
+			typeof schemaObj[key] === "object" &&
+			schemaObj[key] !== null &&
+			!Array.isArray(schemaObj[key])
+		) {
+			validateSchemaKeys(
+				schemaObj[key],
+				allowedKeys,
+				schemaName,
+				displayType,
+				errors,
+				fullKey
+			);
+		}
+	});
+};
+
+/**
+ * Validate a single component schema against its component type definition
+ * @param {Object} schema - The schema to validate
+ * @param {string} displayType - The display type to validate against
+ * @param {Set} errors - Error collection
+ */
+const validateComponentByType = (schema, displayType, errors) => {
+	// Get the component schema definition for this display type
+	const componentSchema = componentSchemas[displayType];
+
+	if (!componentSchema) {
+		errors.add(
+			`"${schema.name}" has an unsupported displayType "${displayType}".`
+		);
+		return;
+	}
+
+	if (!componentSchema.meta) {
+		errors.add(
+			`Component schema for "${displayType}" is missing meta definition.`
+		);
+		return;
+	}
+
+	// Extract allowed keys from the component schema
+	const allowedKeys = extractAllowedKeys(componentSchema.meta);
+
+	// Validate the schema meta object (excluding displayType which we already handled)
+	const { displayType: currentDisplayType, ...restMeta } = schema.meta;
+	validateSchemaKeys(
+		restMeta,
+		allowedKeys,
+		schema.name,
+		currentDisplayType,
+		errors
+	);
+};
+
+const validateComponentSchemas = (schemas, errors) => {
+	schemas.forEach((schema) => {
+		// Basic required field validation
+		if (!schema.name) {
+			errors.add(`Schema is missing a name.`);
+			return; // Can't continue without a name
+		}
+		if (!schema.meta) {
+			errors.add(`"${schema.name}" is missing a meta object.`);
+			return; // Can't continue without meta
+		}
+		if (!schema.meta.displayType) {
+			errors.add(`"${schema.name}" is missing a displayType.`);
+			return; // Can't continue without displayType
+		}
+
+		// Optional field validation (these are warnings, not blocking)
+		if (!schema.meta.displayName) {
+			errors.add(`"${schema.name}" is missing a displayName.`);
+		}
+
+		// Only require placeholder if the component schema defines it
+		const componentSchema = componentSchemas[schema.meta.displayType];
+		if (
+			componentSchema &&
+			componentSchema.meta &&
+			"placeholder" in componentSchema.meta &&
+			!schema.meta.placeholder
+		) {
+			errors.add(`"${schema.name}" is missing a placeholder.`);
+		}
+
+		// Only require description if the component schema defines it
+		if (
+			componentSchema &&
+			componentSchema.meta &&
+			"description" in componentSchema.meta &&
+			!schema.meta.description
+		) {
+			errors.add(`"${schema.name}" is missing a description.`);
+		}
+
+		// 🚨 Validate for duplicate options with same label and value
+		if (Array.isArray(schema.meta.options)) {
+			const seen = new Set();
+			schema.meta.options.forEach((option, index) => {
+				if (option && typeof option === "object") {
+					const key = `${option.label}::${option.value}`;
+					if (seen.has(key)) {
+						errors.add(
+							`"${schema.name}" contains duplicate option at index ${index} with label "${option.label}" and value "${option.value}".`
+						);
+					} else {
+						seen.add(key);
+					}
+				}
+			});
+		}
+
+		// Validate against the specific component type schema
+		validateComponentByType(schema, schema.meta.displayType, errors);
+	});
+};
+
 // ─────────────────────────────────────────────────────────────────────────────
 // INDIVIDUAL VALIDATORS
 // ─────────────────────────────────────────────────────────────────────────────
@@ -83,6 +305,18 @@ const validateWebhook = (webhookPath, spec, errors) => {
 			`"webhook.json" exists but trigger_type is not defined in spec.json.`
 		);
 	}
+
+	// Validate webhook schema parameters if webhook exists
+	if (hasWebhook) {
+		const webhookSchema = readAndParseJson(
+			webhookPath,
+			"webhook.json",
+			errors
+		);
+		if (webhookSchema && Array.isArray(webhookSchema.parameters)) {
+			validateComponentSchemas(webhookSchema.parameters, errors);
+		}
+	}
 };
 
 const validateBaseSchema = (baseSchemaPath, errors) => {
@@ -90,7 +324,49 @@ const validateBaseSchema = (baseSchemaPath, errors) => {
 		errors.add(`"base.json" not found in the "schemas" directory.`);
 		return null;
 	}
-	return readAndParseJson(baseSchemaPath, "base.json", errors);
+
+	const baseSchema = readAndParseJson(baseSchemaPath, "base.json", errors);
+
+	// Validate base schema parameters
+	if (baseSchema && Array.isArray(baseSchema.parameters)) {
+		validateComponentSchemas(baseSchema.parameters, errors);
+	}
+
+	return baseSchema;
+};
+
+const validateAuthentication = (authPath, errors) => {
+	// Authentication is optional, so only validate if it exists
+	if (fs.existsSync(authPath)) {
+		const authSchema = readAndParseJson(
+			authPath,
+			"authentication.json",
+			errors
+		);
+
+		// Validate authentication schema parameters
+		if (authSchema && Array.isArray(authSchema.parameters)) {
+			validateComponentSchemas(authSchema.parameters, errors);
+		}
+
+		// Validate authentication type-specific parameters (like api_key, oauth, etc.)
+		if (authSchema) {
+			Object.keys(authSchema).forEach((key) => {
+				if (
+					key !== "parameters" &&
+					typeof authSchema[key] === "object" &&
+					authSchema[key] !== null
+				) {
+					if (Array.isArray(authSchema[key].parameters)) {
+						validateComponentSchemas(
+							authSchema[key].parameters,
+							errors
+						);
+					}
+				}
+			});
+		}
+	}
 };
 
 const validateResources = (resourcesDir, resourceFields, errors) => {
@@ -121,7 +397,17 @@ const validateResources = (resourcesDir, resourceFields, errors) => {
 		);
 		if (!schema) return;
 
-		const operationFields = findOperationFieldsWithOptions(schema);
+		// Validate resource file parameters
+		if (Array.isArray(schema.parameters)) {
+			validateComponentSchemas(schema.parameters, errors);
+		}
+
+		const operationFields = findOperationFieldsWithOptions(
+			schema,
+			`${resourceFile}.json`,
+			errors,
+			resourceFile
+		);
 
 		operationFields.forEach((operation) => {
 			const operationMethod = operation.split(".")[1];
@@ -144,6 +430,11 @@ const validateResources = (resourcesDir, resourceFields, errors) => {
 				errors.add(
 					`Operation "${operationMethod}" in "${resourceFile}.json" is missing parameters.`
 				);
+			} else {
+				// Validate operation parameters using component schemas
+				if (Array.isArray(methodDef.parameters)) {
+					validateComponentSchemas(methodDef.parameters, errors);
+				}
 			}
 			if (!methodDef.definition) {
 				errors.add(
@@ -154,23 +445,6 @@ const validateResources = (resourcesDir, resourceFields, errors) => {
 	});
 };
 
-// const validateParametersScema = (schema, errors) => {
-// 	if (!schema || !Array.isArray(schema.parameters)) {
-// 		errors.add(
-// 			`Schema is missing or parameters are not defined as an array.`
-// 		);
-// 		return;
-// 	}
-// 	schema.parameters.forEach((param) => {
-// 		const { meta } = param;
-// 		if (!param.name) {
-// 			errors.add(
-// 				`Parameter in schema is missing a name. Ensure all parameters have a "name" field.`
-// 			);
-// 		}
-// 	});
-// };
-
 // ─────────────────────────────────────────────────────────────────────────────
 // MAIN FUNCTION
 // ─────────────────────────────────────────────────────────────────────────────
@@ -184,6 +458,7 @@ export const validateIntegrationSchemas = (currentDir) => {
 		resources: path.join(currentDir, "schemas", "resources"),
 		spec: path.join(currentDir, "spec.json"),
 		webhook: path.join(currentDir, "schemas", "webhook.json"),
+		authentication: path.join(currentDir, "schemas", "authentication.json"),
 		documentation: path.join(currentDir, "Documentation.mdx"),
 	};
 
@@ -192,10 +467,11 @@ export const validateIntegrationSchemas = (currentDir) => {
 
 	const spec = validateSpec(paths.spec, errors);
 	validateWebhook(paths.webhook, spec, errors);
+	validateAuthentication(paths.authentication, errors);
 
 	const baseSchema = validateBaseSchema(paths.base, errors);
 	const resourceFields = baseSchema
-		? findResourceFieldsWithOptions(baseSchema)
+		? findResourceFieldsWithOptions(baseSchema, "base.json", errors)
 		: [];
 
 	validateResources(paths.resources, resourceFields, errors);

package/llm.txt

@@ -0,0 +1,295 @@
+# Boltic CLI - Developer Documentation for AI Assistants
+
+## Overview
+The Boltic CLI is a Node.js command-line interface for managing Boltic Workflow integrations. It provides tools for creating, editing, syncing, and publishing integrations to the Boltic platform.
+
+**Package**: @boltic/cli
+**Repository**: https://github.com/bolticio/cli
+**License**: ISC
+
+## Core Architecture
+
+### Entry Point
+- `index.js` - Main entry point and binary executable
+- `cli.js` - Core CLI module with command routing and execution
+
+### Command Structure
+The CLI follows a modular command structure:
+
+```
+boltic [command] [subcommand] [options]
+```
+
+### Main Commands
+
+#### Authentication Commands (`commands/login.js`)
+- `boltic login` - Authenticate with Boltic platform
+- `boltic logout` - Clear authentication tokens
+
+#### Integration Commands (`commands/integration.js`)
+- `boltic integration create` - Create new integration
+- `boltic integration edit` - Edit existing integration
+- `boltic integration sync` - Sync changes to draft
+- `boltic integration submit` - Submit for review
+- `boltic integration publish` - Submit for review (deprecated, use submit)
+- `boltic integration pull` - Pull latest changes
+- `boltic integration status` - Show integration details
+
+#### Environment Commands (`commands/env.js`)
+- `boltic env list` - List available environments
+- `boltic env set` - Set current environment
+- `boltic env show` - Show current environment
+
+### API Layer (`api/`)
+- `integration.js` - Integration management API calls
+- `login.js` - Authentication API calls
+- `environment.js` - Environment management API calls
+
+### Helper Modules (`helper/`)
+- `validation.js` - Schema validation for integrations
+- `folder.js` - File system operations for integration folders
+- `secure-storage.js` - Secure credential storage using keytar
+- `env.js` - Environment configuration management
+- `error.js` - Error handling and formatting
+- `command-suggestions.js` - Command similarity suggestions
+- `verbose.js` - Verbose logging control
+
+### Templates (`templates/`)
+- `schemas.js` - Schema templates for integrations
+
+### Utilities (`utils/`)
+- `integration.js` - Integration utility functions
+
+## Key Features
+
+### Authentication
+- OAuth-based authentication with secure token storage
+- Multiple environment support (bolt, fcz0, fcz5)
+- Automatic token refresh and session management
+
+### Integration Management
+- **Create**: Interactive creation wizard with prompts for:
+  - Integration name (letters and underscores only)
+  - SVG icon upload
+  - Integration type (Activity, Trigger, or both)
+  - Descriptions (human and AI-generated)
+  - Integration group selection
+- **Edit**: Modify existing integrations
+- **Sync**: Upload changes to draft version
+- **Submit**: Submit integration for review
+- **Publish**: Submit integration for review (deprecated, use submit)
+- **Pull**: Download latest changes from cloud
+- **Status**: View integration details and metadata
+
+### Validation System
+The validation system (`helper/validation.js`) ensures integration schemas are correct:
+
+#### Required Files
+- `Documentation.mdx` - Integration documentation
+- `spec.json` - Integration specification
+- `schemas/base.json` - Base schema configuration
+- `schemas/resources/*.json` - Resource-specific schemas
+- `schemas/webhook.json` - Webhook configuration (if trigger_type defined)
+
+#### Schema Structure
+All option objects must include:
+- `label` - Human-readable label
+- `value` - Machine-readable value
+- `description` - Detailed description
+
+#### Validation Rules
+- Resource fields must reference existing resource files
+- Operation fields must reference valid operations in resource files
+- Operations must have both `parameters` and `definition` properties
+- Webhook configuration must match trigger_type in spec.json
+
+### Environment Configuration
+Three supported environments defined in `config/environments.js`:
+- **bolt** (production): console.boltic.io
+- **fcz0** (staging): fcz0.de
+- **fcz5** (UAT): uat.fcz0.de
+
+### File System Operations
+- Automatic folder structure creation
+- JSON file parsing and validation
+- SVG file handling for icons
+- Resource file management
+
+## Development Workflow
+
+### Testing
+- **Framework**: Jest with comprehensive test coverage
+- **Coverage**: 96.45% statement coverage, 91.68% branch coverage
+- **Test Files**: Located in `__tests__/` directory
+- **Run Tests**: `npm test`
+
+### Code Quality
+- **Linting**: ESLint with Prettier integration
+- **Pre-commit**: Husky hooks with lint-staged
+- **Standards**: ES6+ modules, async/await patterns
+
+### Dependencies
+**Production**:
+- `@inquirer/prompts` - Interactive CLI prompts
+- `axios` - HTTP client for API calls
+- `chalk` - Terminal string styling
+- `keytar` - Secure credential storage
+- `open` - Browser launching
+- `uuid` - Unique identifier generation
+- `lodash.isempty` - Empty value checking
+
+**Development**:
+- `jest` - Testing framework
+- `eslint` - Code linting
+- `prettier` - Code formatting
+- `husky` - Git hooks
+- `nodemon` - Development server
+
+## Common Patterns
+
+### Error Handling
+- Centralized error handling in `helper/error.js`
+- Axios error interception and formatting
+- User-friendly error messages with suggestions
+
+### Async Operations
+- Consistent async/await usage
+- Promise-based API calls
+- Proper error propagation
+
+### User Interaction
+- Interactive prompts using @inquirer/prompts
+- Progress indicators for long operations
+- Color-coded output using chalk
+
+### File Operations
+- Safe JSON parsing with error handling
+- Atomic file operations
+- Directory existence checking
+
+## Configuration
+
+### Schema Templates
+Integration schemas are generated from templates in `templates/schemas.js`:
+- **Authentication**: API key-based authentication
+- **Base**: Core integration configuration
+- **Webhook**: Trigger configuration
+- **Resource**: Resource-specific operations
+
+### Environment Variables
+- Environment selection stored in secure storage
+- API endpoints configured per environment
+- OAuth client IDs per environment
+
+## Security Considerations
+
+### Credential Storage
+- Secure token storage using keytar (OS keychain)
+- No plaintext credential storage
+- Automatic token cleanup on logout
+
+### API Security
+- OAuth 2.0 authentication flow
+- Bearer token authentication
+- Environment-specific API endpoints
+
+### Input Validation
+- Schema validation for all integration files
+- SVG file validation for icons
+- Input sanitization for user prompts
+
+## Troubleshooting
+
+### Common Issues
+1. **Authentication Errors**: Check network connectivity and credentials
+2. **Validation Errors**: Ensure all required schema fields are present
+3. **File System Errors**: Verify file permissions and paths
+4. **API Errors**: Check environment configuration and network
+
+### Debug Mode
+Use `--verbose` flag for detailed logging:
+```bash
+boltic --verbose integration create
+```
+
+### Log Files
+- API calls logged in verbose mode
+- Error stack traces available in debug mode
+- Progress indicators for long operations
+
+## Contributing
+
+### Code Style
+- ES6+ modules with import/export
+- Async/await for asynchronous operations
+- Functional programming patterns where applicable
+- Comprehensive error handling
+
+### Testing Requirements
+- Unit tests for all new features
+- Integration tests for API calls
+- Mocking external dependencies
+- Minimum 95% code coverage
+
+### Documentation
+- JSDoc comments for complex functions
+- README updates for new features
+- Schema documentation for integration formats
+- API documentation for external integrations
+
+## Integration Schema Format
+
+### Base Schema Structure
+```json
+{
+  "parameters": [
+    {
+      "name": "resource",
+      "meta": {
+        "options": [
+          {
+            "value": "users",
+            "label": "Users",
+            "description": "Manage users"
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Resource Schema Structure
+```json
+{
+  "parameters": [
+    {
+      "name": "operation",
+      "meta": {
+        "options": [
+          {
+            "value": "users.list",
+            "label": "List Users",
+            "description": "List all users"
+          }
+        ]
+      }
+    }
+  ],
+  "list": {
+    "parameters": [],
+    "definition": {}
+  }
+}
+```
+
+### Spec.json Format
+```json
+{
+  "name": "Integration Name",
+  "activity_type": "customActivity",
+  "trigger_type": "webhook" // optional
+}
+```
+
+This documentation provides a comprehensive guide for AI assistants working with the Boltic CLI codebase, covering architecture, features, development practices, and troubleshooting procedures.