@boltic/cli 1.0.6-beta.7 → 1.0.6

package/README.md

@@ -1,147 +1,593 @@
 # ⚡ Boltic CLI
 
-> A powerful CLI tool for creating, managing, and publishing Boltic integrations.
+> **Professional CLI tool for creating, managing, and publishing Boltic Workflow integrations with enterprise-grade features and seamless developer experience.**
 
 [![NPM Version](https://img.shields.io/npm/v/@boltic/cli)](https://www.npmjs.com/package/@boltic/cli)
+[![GitHub Repo](https://img.shields.io/badge/GitHub-Repo-blue?logo=github)](https://github.com/bolticio/cli)
 [![License](https://img.shields.io/npm/l/@boltic/cli)](./LICENSE)
+[![Node.js Package](https://github.com/bolticio/cli/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/bolticio/cli/actions/workflows/npm-publish.yml)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/bolticio/cli/graphs/commit-activity)
+
+<div align="center">
+
+![Boltic CLI](https://img.shields.io/badge/Boltic-CLI-00D4AA?style=for-the-badge&logo=node.js&logoColor=white)
+
+**Streamline your integration development workflow with Boltic CLI**
+
+[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Contributing](#-contributing)
+
+</div>
+
+---
+
+## 📋 Table of Contents
+
+- [✨ Features](#-features)
+- [🚀 Quick Start](#-quick-start)
+- [📦 Installation](#-installation)
+- [🔐 Authentication](#-authentication)
+- [🧩 Integration Management](#-integration-management)
+- [📚 Command Reference](#-command-reference)
+- [🛠️ Development Workflow](#️-development-workflow)
+- [🔧 Configuration](#-configuration)
+- [🛡️ Security](#-security)
+- [🐛 Troubleshooting](#-troubleshooting)
+- [📖 Documentation](#-documentation)
+- [🤝 Contributing](#-contributing)
+- [📄 License](#-license)
+
+---
+
+## ✨ Features
+
+- 🔐 **Secure Authentication** - Enterprise-grade token management with secure storage
+- 🚀 **Rapid Integration Development** - Create integrations in minutes, not hours
+- 📦 **Smart Project Management** - Automated folder structure and configuration
+- 🔄 **Real-time Synchronization** - Instant sync with Boltic Cloud platform
+- 🎯 **Type-safe Development** - Support for Workflow Activities and Triggers
+- 🎨 **Rich Interactive UI** - Beautiful command-line interface with progress indicators
+- 📊 **Comprehensive Validation** - Built-in validation for all integration components
+- 🔧 **Developer Experience** - Hot reload, debugging tools, and comprehensive error handling
+- 🌐 **Multi-platform Support** - Works seamlessly on Windows, macOS, and Linux
+- 📈 **Version Control Integration** - Git-friendly workflow with proper ignore patterns
+
+---
+
+## 🚀 Quick Start
+
+Get up and running with Boltic CLI in under 2 minutes:
+
+```bash
+# Install Boltic CLI globally
+npm install -g @boltic/cli
+
+# Authenticate with your Boltic account
+boltic login
+
+# Create your first integration
+boltic integration create
+
+# Sync your changes
+boltic integration sync
+
+# Submit for review
+boltic integration submit
+```
 
 ---
 
 ## 📦 Installation
 
-Install Boltic CLI globally via NPM:
+### Prerequisites
+
+- **Node.js** 18.0.0 or higher
+- **npm** 8.0.0 or higher
+- **Git** (for version control)
+
+### Global Installation (Recommended)
 
 ```bash
 npm install -g @boltic/cli
 ```
 
+### Verify Installation
+
+```bash
+boltic --version
+```
+
 ---
 
 ## 🔐 Authentication
 
-To log in:
+Boltic CLI uses a secure OAuth 2.0 flow with browser-based authentication for enhanced security and user experience.
+
+### Initial Login
+
+```bash
+boltic login
+```
+
+The authentication process follows these steps:
+
+1. **Browser Launch**: CLI automatically opens your default browser to the Boltic login page
+2. **OAuth Flow**: Complete the authentication in your browser (email/password or SSO)
+3. **Token Exchange**: CLI automatically exchanges the authorization code for access tokens
+4. **Secure Storage**: Tokens are encrypted and stored in your system's keychain
+
+### Authentication Flow
+
+```bash
+# Start authentication
+boltic login
+
+# CLI will:
+# 1. Generate a unique request code
+# 2. Open browser to: https://console.fynd.com/auth/sign-in
+# 3. Wait for you to complete login in browser
+# 4. Poll for session data (up to 5 minutes)
+# 5. Exchange session for bearer token
+# 6. Store tokens securely
+```
+
+### Secure Token Storage
+
+Your authentication credentials are securely stored using your system's native keychain:
+
+- **macOS**: Keychain Access (`boltic-cli` service)
+- **Windows**: Credential Manager (`boltic-cli` service)
+- **Linux**: Secret Service API (`boltic-cli` service)
+
+**Stored Credentials:**
+
+- `token`: Bearer token for API authentication
+- `session`: Session cookie for web requests
+- `account_id`: Your Boltic account identifier
+
+### Logout and Token Management
+
+```bash
+# Clear all stored credentials
+boltic logout
+
+# Check authentication status
+boltic integration list  # Will prompt login if not authenticated
+```
+
+### Troubleshooting Authentication
+
+#### Common Issues
+
+**Browser doesn't open automatically:**
+
+```bash
+# Manual login URL will be displayed
+# Copy and paste the URL into your browser
+```
+
+**Authentication timeout:**
 
 ```bash
+# Retry login (5-minute timeout)
 boltic login
 ```
 
-Follow the interactive prompt to enter your credentials. Your token will be stored securely for future use.
+**Connection issues:**
+
+```bash
+# Check network connectivity
+ping console.fynd.com
+
+boltic login
+```
 
 ---
 
 ## 🧩 Integration Management
 
-### ➕ Create a New Integration
+### Creating New Integrations
 
 ```bash
 boltic integration create
 ```
 
-You’ll be prompted to enter:
+#### Interactive Setup Process
+
+The CLI will guide you through:
+
+1. **Integration Details**
+    - Name (alphanumeric + underscores only)
+    - Description (human-readable)
+    - AI-generated description
+
+2. **Visual Assets**
+    - Icon selection (SVG format required)
+    - Brand colors and styling
+
+3. **Integration Type**
+    - **Workflow Activity**: Reusable components for specific tasks
+    - **Workflow Trigger**: Event-driven components that initiate workflows
+    - **Both**: Create both types simultaneously
+
+4. **Categorization**
+    - Integration Group (Analytics, CRM, ERP, Marketing, etc.)
+    - Tags and metadata
+
+#### Generated Project Structure
+
+```
+my-integration/
+├── schemas/
+│   ├── resources/
+│   │   └── resource1.json
+│   ├── authentication.json
+│   ├── base.json
+│   └── webhook.json
+├── Authentication.mdx
+├── Documentation.mdx
+└── spec.json
+```
+
+**File Descriptions:**
 
-- **Name**: Letters and underscores only (e.g., My_Integration)
-- **Icon**: Select an SVG file from your computer
-- **Integration Type**:
-    - Workflow Activity: Reusable components that perform specific tasks
-    - Workflow Trigger: Components that start your workflow based on external events
-    - You can choose to create both types for the same integration
+- **`schemas/`** - Schema definitions for the integration
+    - **`resources/`** - Resource-specific schemas (e.g., `resource1.json`)
+    - **`authentication.json`** - Authentication configuration and parameters
+    - **`base.json`** - Base integration configuration and parameters
+    - **`webhook.json`** - Webhook configuration (for trigger integrations)
 
-- **Descriptions**
-    - Human-readable and AI-generated
+- **`Authentication.mdx`** - Authentication documentation in Markdown format
+- **`Documentation.mdx`** - General integration documentation
+- **`spec.json`** - Integration specification and metadata
 
-- **Integration Group**
-    - e.g., Analytics, CRM, ERP, Marketing, Payment, Social Media, Other
+### Managing Existing Integrations
 
-### ✏️ Edit an Integration
+#### Edit Integration
 
 ```bash
+# Edit current integration
 boltic integration edit
+
 ```
 
-### 🔄 Sync an Integration
+#### Sync Changes
 
 ```bash
+# Sync all changes
 boltic integration sync
 ```
 
-### 🚀 Publish an Integration
+#### Pull Latest Changes
 
 ```bash
-boltic integration publish
+# Pull latest from Boltic Cloud
+boltic integration pull
+```
+
+#### Submit for Review
+
+```bash
+# Submit for publishing review
+boltic integration submit
 ```
 
 ---
 
-## 📌 Command Reference
+## 📚 Command Reference
 
-| Command                      | Description                                              |
-| ---------------------------- | -------------------------------------------------------- |
-| `boltic login`               | Authenticate with Boltic                                 |
-| `boltic integration create`  | Create a new integration                                 |
-| `boltic integration sync`    | Sync changes to your draft                               |
-| `boltic integration publish` | Submit integration for review                            |
-| `boltic integration pull`    | Pull the latest changes of an integration from the Cloud |
-| `boltic integration edit`    | Edit an existing integration                             |
-| `boltic help`                | Show CLI help                                            |
-| `boltic version`             | Display CLI version                                      |
+### Core Commands
 
----
+| Command          | Description                       | Options |
+| ---------------- | --------------------------------- | ------- |
+| `boltic login`   | Authenticate with Boltic platform |         |
+| `boltic logout`  | Clear stored credentials          |         |
+| `boltic version` | Display CLI version               |         |
+| `boltic help`    | Show comprehensive help           |         |
 
-## 🔁 Typical Workflow
+### Integration Commands
+
+| Command                     | Description               | Options               |
+| --------------------------- | ------------------------- | --------------------- |
+| `boltic integration create` | Create new integration    | Interactive prompts   |
+| `boltic integration edit`   | Edit existing integration | Interactive prompt    |
+| `boltic integration sync`   | Sync local changes        | Interactive prompt    |
+| `boltic integration pull`   | Pull latest changes       | Interactive prompt    |
+| `boltic integration submit` | Submit for review         |                       |
+| `boltic integration status` | Check integration status  | Interactive selection |
+| `boltic integration help`   | Show integration help     |                       |
+
+### Help and Documentation
 
 ```bash
-# Step 1: Authenticate
-boltic login
+# General help
+boltic help
+
+# Command-specific help
+boltic integration help
+boltic login help
+```
+
+---
 
-# Step 2: Start a new integration
+## 🛠️ Development Workflow
+
+### Typical Development Cycle
+
+```bash
+# 1. Start Development
 boltic integration create
+cd my-integration
 
-# Step 3: Save changes
+# 2. Make Changes
+# Edit your integration files...
+
+# 3. Sync Changes
 boltic integration sync
 
-# Step 5: Submit for publishing and review
-boltic integration publish
+# 4. Iterate
+# Make more changes and sync...
+
+# 5. Submit for Review
+boltic integration submit
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Complete Troubleshooting Guide
+
+When encountering issues with Boltic CLI, follow this comprehensive troubleshooting guide:
+
+#### 1. Authentication Issues
+
+**Problem**: Cannot authenticate, login fails, or session expires
+
+**Solutions**:
+
+```bash
+# Clear stored credentials and re-authenticate
+boltic logout
+boltic login
+
+# Check network connectivity
+ping console.fynd.com
+
+# If browser doesn't open automatically, copy the manual URL
+boltic login  # Manual URL will be displayed
 
-# Step 6: Pull the latest changes of a integration. Please call this command inside a integration folder.
+# For authentication timeout (5-minute limit)
+boltic login  # Retry the login process
+```
+
+**Browser-specific issues**:
+
+- Manual login URL will be displayed if browser doesn't open
+- Copy and paste the URL into your browser
+- Ensure you're using a supported browser (Chrome, Firefox, Safari, Edge)
+
+#### 2. Integration Management Issues
+
+**Problem**: Cannot create, edit, sync, or submit integrations
+
+**Solutions**:
+
+```bash
+# Check integration status
+boltic integration status
+
+# Force sync all changes
+boltic integration sync
+
+# Pull latest changes from Boltic Cloud
 boltic integration pull
 
-# Step 7: Use this command if you don't have folder of a particular integration. Please call this command outside of any existing integration folder.
-boltic integration edit
+# Re-authenticate if needed
+boltic logout && boltic login
+
+# Check if you're in the correct directory
+ls -la  # Should show integration files (spec.json, etc.)
 ```
 
----
+#### 3. Network and Connectivity Issues
 
-## 🛠️ Troubleshooting
+**Problem**: Connection errors, timeouts, or API failures
 
-### Login Errors
+**Solutions**:
 
-- Make sure you're online and using valid credentials.
-- Retry `boltic login` if your token has expired.
+```bash
+# Test basic connectivity
+ping console.fynd.com
 
-### Integration Issues
+# Check API status
+boltic integration status
 
-- Ensure all required fields (e.g., name, type, icon URL) are filled.
-- Verify the icon URL is publicly accessible.
-- Double-check the selected integration type and group.
+# Enable verbose logging for detailed error information
+boltic --verbose integration sync
+boltic --verbose integration create
+boltic --verbose login
 
----
+# Check your internet connection and firewall settings
+```
+
+#### 4. File and Directory Issues
+
+**Problem**: Missing files, permission errors, or corrupted project structure
+
+**Solutions**:
+
+```bash
+# Verify project structure
+ls -la  # Should show: schemas/, Authentication.mdx, Documentation.mdx, spec.json
+
+# Check file permissions
+ls -la schemas/
+
+# Re-create integration if structure is corrupted
+boltic integration create  # Create new integration
+# Then manually copy your customizations
+```
+
+#### 5. Performance and Sync Issues
+
+**Problem**: Slow performance, hanging operations, or sync failures
+
+**Solutions**:
+
+```bash
+# Check integration status first
+boltic integration status
+
+# Force sync with verbose output
+boltic --verbose integration sync
+
+# Clear cache and re-authenticate
+boltic logout
+boltic login
+
+# Check system resources
+# Ensure sufficient disk space and memory
+```
+
+#### 6. Debug Mode and Logging
+
+**Enable detailed logging for any command**:
 
-## 📚 Help
+```bash
+# General verbose mode
+boltic --verbose <command>
+
+# Specific examples
+boltic --verbose integration create
+boltic --verbose integration sync
+boltic --verbose login
+boltic --verbose integration submit
+```
 
-Get help directly in the CLI:
+#### 7. Getting Help and Support
+
+**Built-in help system**:
 
 ```bash
-# View all commands
+# General help
 boltic help
 
-# View integration command options
+# Command-specific help
 boltic integration help
+boltic login help
+
+# Check CLI version
+boltic --version
+```
+
+**External resources**:
+
+- 📚 [Boltic Documentation](https://docs.boltic.io) - Complete guides and API reference
+- 🐛 [Issue Tracker](https://github.com/bolticio/cli/issues) - Report bugs and request features
+- 💬 [Discord Community](https://discord.gg/boltic) - Community support and discussions
+- 📧 [Support](https://support.boltic.io) - Official support channels
+
+#### 8. Advanced Troubleshooting
+
+**Keychain/Credential issues**:
+
+```bash
+# Manual credential cleanup (if logout fails)
+# macOS: Check Keychain Access for "boltic-cli" entries
+# Windows: Check Credential Manager for "boltic-cli" entries
+# Linux: Check Secret Service for "boltic-cli" entries
+
+# Force logout and clean authentication
+boltic logout
+boltic login
+```
+
+**Environment-specific issues**:
+
+```bash
+# Check Node.js version (requires 18.0.0+)
+node --version
+
+# Check npm version (requires 8.0.0+)
+npm --version
+
+# Update CLI to latest version
+npm install -g @boltic/cli@latest
+
+# Verify installation
+boltic --version
+```
+
+**Development mode troubleshooting**:
+
+```bash
+# For contributors using development installation
+npm install  # Update dependencies
+npm link     # Re-link CLI
+npm test     # Run test suite
+```
+
+#### 9. Emergency Recovery
+
+**If all else fails**:
+
+```bash
+# Complete reset
+boltic logout
+npm uninstall -g @boltic/cli
+npm install -g @boltic/cli
+boltic login
+
+# Backup and restore integration
+# Copy your integration files to a backup location
+# Re-create integration and restore customizations
 ```
 
-Or visit the [Boltic Docs](https://docs.boltic.io) for full documentation.
+**Still need help?**
+
+1. Check the [FAQ](https://docs.boltic.io/faq)
+2. Search [existing issues](https://github.com/bolticio/cli/issues)
+3. Create a new issue with:
+    - CLI version (`boltic --version`)
+    - Operating system
+    - Node.js version
+    - Complete error message
+    - Steps to reproduce
 
 ---
 
-## 🧾 License
+## 📖 Documentation
+
+### Official Resources
+
+- 📚 **[Boltic Documentation](https://docs.boltic.io)** - Complete API reference and guides
+
+### Community Resources
+
+- 🐛 **[Issue Tracker](https://github.com/bolticio/cli/issues)** - Report bugs and request features
+- 📝 **[Blog](https://boltic.io/blog)** - Latest updates and best practices
+
+---
+
+## 📄 License
+
+This project is licensed under the **ISC License** - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- **Boltic Team** - For building an amazing platform
+- **Open Source Contributors** - For their valuable contributions
+- **Community** - For feedback, bug reports, and feature requests
+
+---
+
+<div align="center">
+
+**Made with ❤️ by the Boltic Team**
+
+[Website](https://boltic.io) • [Documentation](https://docs.boltic.io) •
 
-MIT © [Boltic](https://boltic.io)
+</div>