@boltic/cli 1.0.26 → 1.0.27-1

package/README.md

@@ -225,7 +225,9 @@ my-integration/
 │   ├── base.json
 │   └── webhook.json
 ├── Authentication.mdx
-├── Documentation.mdx
+├── documentation/
+│   ├── integration.mdx
+│   └── trigger.mdx
 └── spec.json
 ```
 
@@ -237,9 +239,11 @@ my-integration/
     - **`base.json`** - Base integration configuration and parameters
     - **`webhook.json`** - Webhook configuration (for trigger integrations)
 
-- **`Authentication.mdx`** - Authentication documentation in Markdown format
-- **`Documentation.mdx`** - General integration documentation
-- **`spec.json`** - Integration specification and metadata
+**Documentation files:**
+- `Authentication.mdx` - Authentication documentation in Markdown format (optional, created when catalogue is enabled)
+- `documentation/integration.mdx` - Activity documentation (required when activity_type is present; falls back to legacy `Documentation.mdx`)
+- `documentation/trigger.mdx` - Trigger documentation (required when trigger_type is "CloudTrigger")
+- `spec.json` - Integration specification and metadata
 
 ### Managing Existing Integrations
 
@@ -419,7 +423,7 @@ boltic --verbose login
 
 ```bash
 # Verify project structure
-ls -la  # Should show: schemas/, Authentication.mdx, Documentation.mdx, spec.json
+ls -la  # Should show: schemas/, Authentication.mdx (optional), documentation/, spec.json
 
 # Check file permissions
 ls -la schemas/

package/commands/integration.js

@@ -114,6 +114,16 @@ async function readSchemaFiles(currentDir) {
 	// Read documentation files
 	const authDocPath = path.join(currentDir, "Authentication.mdx");
 	const generalDocPath = path.join(currentDir, "Documentation.mdx");
+	const docsIntegrationPath = path.join(
+		currentDir,
+		"documentation",
+		"integration.mdx"
+	);
+	const docsTriggerPath = path.join(
+		currentDir,
+		"documentation",
+		"trigger.mdx"
+	);
 
 	if (fs.existsSync(authDocPath)) {
 		schemas.authentication_documentation = fs.readFileSync(
@@ -122,8 +132,22 @@ async function readSchemaFiles(currentDir) {
 		);
 	}
 
-	if (fs.existsSync(generalDocPath)) {
-		schemas.documentation = fs.readFileSync(generalDocPath, "utf8");
+	// Build documentation object with backward compatibility
+	const documentation = {};
+	if (fs.existsSync(docsIntegrationPath)) {
+		documentation.integration = fs.readFileSync(
+			docsIntegrationPath,
+			"utf8"
+		);
+	} else if (fs.existsSync(generalDocPath)) {
+		// Fallback to legacy Documentation.mdx
+		documentation.integration = fs.readFileSync(generalDocPath, "utf8");
+	}
+	if (fs.existsSync(docsTriggerPath)) {
+		documentation.trigger = fs.readFileSync(docsTriggerPath, "utf8");
+	}
+	if (Object.keys(documentation).length > 0) {
+		schemas.documentation = documentation;
 	}
 
 	return schemas;
@@ -1091,7 +1115,25 @@ async function handleStatus() {
 
 		if (integration.documentation) {
 			console.log(chalk.cyan("\nDocumentation:"));
-			console.log(integration.documentation);
+			if (
+				typeof integration.documentation === "object" &&
+				integration.documentation !== null
+			) {
+				if (integration.documentation.integration) {
+					console.log(
+						chalk.dim("integration.mdx:\n") +
+							integration.documentation.integration
+					);
+				}
+				if (integration.documentation.trigger) {
+					console.log(
+						chalk.dim("\ntrigger.mdx:\n") +
+							integration.documentation.trigger
+					);
+				}
+			} else {
+				console.log(integration.documentation);
+			}
 		}
 	} catch (error) {
 		if (

package/helper/folder.js

@@ -47,6 +47,9 @@ export const createIntegrationFolderStructure = async (
 	const resourcesDir = path.join(schemasDir, "resources");
 	fs.mkdirSync(resourcesDir, { recursive: true });
 
+	const docsDir = path.join(integrationDir, "documentation");
+	fs.mkdirSync(docsDir, { recursive: true });
+
 	// Create template files
 	const files = {
 		"schemas/resources/resource1.json": JSON.stringify(resource1, null, 4),
@@ -69,7 +72,13 @@ export const createIntegrationFolderStructure = async (
 		...(create_catalogue && {
 			"Authentication.mdx": `# ${name} Authentication`,
 		}),
-		"Documentation.mdx": `# ${name} Documentation`,
+		// Documentation files (new structure)
+		...(!isEmpty(activity_type) && {
+			"documentation/integration.mdx": `# ${name} Integration`,
+		}),
+		...(trigger_type === "CloudTrigger" && {
+			"documentation/trigger.mdx": `# ${name} Trigger`,
+		}),
 	};
 
 	// Create all files
@@ -147,7 +156,14 @@ export const createExistingIntegrationsFolder = async (payload) => {
 	const resourcesDir = path.join(schemasDir, "resources");
 	fs.mkdirSync(resourcesDir, { recursive: true });
 
+	const docsDir = path.join(integrationDir, "documentation");
+	fs.mkdirSync(docsDir, { recursive: true });
+
 	const authentication_documentation = authentication?.documentation || "";
+	const isDocumentationObject =
+		documentation &&
+		typeof documentation === "object" &&
+		!Array.isArray(documentation);
 
 	// Define files and content
 	const files = {
@@ -168,7 +184,17 @@ export const createExistingIntegrationsFolder = async (payload) => {
 		...(authentication && {
 			"Authentication.mdx": authentication_documentation || "",
 		}),
-		"Documentation.mdx": documentation || "",
+		...(!isEmpty(activity_type) && {
+			"documentation/integration.mdx": isDocumentationObject
+				? documentation?.integration || `# ${name} Integration`
+				: (typeof documentation === "string" && documentation) ||
+					`# ${name} Integration`,
+		}),
+		...(trigger_type === "CloudTrigger" && {
+			"documentation/trigger.mdx": isDocumentationObject
+				? documentation?.trigger || `# ${name} Trigger`
+				: `# ${name} Trigger`,
+		}),
 	};
 
 	// Write resource files

package/helper/markdown.js

@@ -0,0 +1,32 @@
+import fs from "fs";
+
+const hasBalancedCodeFences = (content) => {
+	const fenceCount = (content.match(/```/g) || []).length;
+	return fenceCount % 2 === 0;
+};
+
+export const validateMarkdownString = (content, fileLabel, errors) => {
+	const label = fileLabel || "markdown";
+	if (!content || !content.trim()) {
+		errors.add(`"${label}" is empty.`);
+		return false;
+	}
+	// Keep checks minimal to avoid false positives in CLI usage
+	if (!hasBalancedCodeFences(content)) {
+		errors.add('"' + label + '" has unbalanced code fences (```).');
+	}
+	return true;
+};
+
+export const validateMarkdownFile = (filePath, errors, label) => {
+	try {
+		if (!fs.existsSync(filePath)) return false;
+		const content = fs.readFileSync(filePath, "utf8");
+		return validateMarkdownString(content, label || filePath, errors);
+	} catch (e) {
+		errors.add(
+			`Failed to read markdown file "${label || filePath}": ${e.message}`
+		);
+		return false;
+	}
+};

package/helper/validation.js

@@ -2,6 +2,7 @@ import fs from "fs";
 import isEmpty from "lodash.isempty";
 import path from "path";
 import * as componentSchemas from "../templates/component-schemas.js";
+import { validateMarkdownFile } from "./markdown.js";
 
 const validateOptionObject = (options, fieldName, fileLabel, errors) => {
 	options.forEach((opt, index) => {
@@ -325,9 +326,82 @@ const validateComponentSchemas = (schemas, errors, filename = "") => {
 // INDIVIDUAL VALIDATORS
 // ─────────────────────────────────────────────────────────────────────────────
 
-const validateDocumentation = (docPath, errors) => {
-	if (!fs.existsSync(docPath)) {
-		errors.add(`"Documentation.mdx" not found in the root directory.`);
+const validateDocumentation = (currentDir, spec, errors) => {
+	const docsIntegrationPath = path.join(
+		currentDir,
+		"documentation",
+		"integration.mdx"
+	);
+	const docsTriggerPath = path.join(
+		currentDir,
+		"documentation",
+		"trigger.mdx"
+	);
+	const legacyDocPath = path.join(currentDir, "Documentation.mdx");
+
+	const requiresIntegrationDoc = spec && !isEmpty(spec.activity_type);
+	const requiresTriggerDoc = spec && spec.trigger_type === "CloudTrigger";
+
+	// Backward-compatibility: if nothing specific is required by spec,
+	// ensure at least legacy Documentation.mdx or new docs exist
+	const hasLegacy = fs.existsSync(legacyDocPath);
+	const hasNewIntegration = fs.existsSync(docsIntegrationPath);
+	const hasNewTrigger = fs.existsSync(docsTriggerPath);
+
+	if (!requiresIntegrationDoc && !requiresTriggerDoc) {
+		if (!hasLegacy && !hasNewIntegration && !hasNewTrigger) {
+			errors.add('"Documentation.mdx" not found in the root directory.');
+			return; // No further checks needed
+		}
+		// If files exist, validate whatever is present
+		if (hasLegacy) {
+			validateMarkdownFile(legacyDocPath, errors, "Documentation.mdx");
+		}
+		if (hasNewIntegration) {
+			validateMarkdownFile(
+				docsIntegrationPath,
+				errors,
+				"documentation/integration.mdx"
+			);
+		}
+		if (hasNewTrigger) {
+			validateMarkdownFile(
+				docsTriggerPath,
+				errors,
+				"documentation/trigger.mdx"
+			);
+		}
+		return;
+	}
+
+	if (requiresIntegrationDoc) {
+		const hasNew = validateMarkdownFile(
+			docsIntegrationPath,
+			errors,
+			"documentation/integration.mdx"
+		);
+		const hasLegacyValidated = validateMarkdownFile(
+			legacyDocPath,
+			errors,
+			"Documentation.mdx"
+		);
+		if (!hasNew && !hasLegacyValidated) {
+			// Maintain backward-compatible error message expected by tests
+			errors.add('"Documentation.mdx" not found in the root directory.');
+		}
+	}
+
+	if (requiresTriggerDoc) {
+		const hasTrigger = validateMarkdownFile(
+			docsTriggerPath,
+			errors,
+			"documentation/trigger.mdx"
+		);
+		if (!hasTrigger) {
+			errors.add(
+				'"documentation/trigger.mdx" not found when trigger_type is "CloudTrigger".'
+			);
+		}
 	}
 };
 
@@ -525,13 +599,11 @@ export const validateIntegrationSchemas = (currentDir) => {
 		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"),
 	};
 
 	// Step-by-step validation
-	validateDocumentation(paths.documentation, errors);
-
 	const spec = validateSpec(paths.spec, errors);
+	validateDocumentation(currentDir, spec, errors);
 	validateWebhook(paths.webhook, spec, errors);
 	validateAuthentication(paths.authentication, errors);
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@boltic/cli",
-	"version": "1.0.26",
+	"version": "1.0.27-1",
 	"description": "A powerful CLI tool for managing Boltic Workflow integrations - create, sync, test, and publish integrations with ease",
 	"main": "index.js",
 	"bin": {