@rglabs/butterfly 1.0.0 → 1.0.3

package/README.md

@@ -0,0 +1,226 @@
+# Butterfly CLI
+
+CLI tool for downloading and synchronizing resources from the Butterfly platform.
+
+## Installation
+
+```bash
+# Global installation
+npm install -g @rglabs/butterfly
+
+# Or use with npx (no installation required)
+npx @rglabs/butterfly <command>
+```
+
+## Quick Start
+
+```bash
+# 1. Configure authentication
+butterfly setup
+
+# 2. Download all resources
+butterfly download
+
+# 3. Start watching for changes
+butterfly start
+```
+
+## Commands
+
+### `butterfly setup`
+
+Configure authentication for the Butterfly platform.
+
+```bash
+butterfly setup
+```
+
+You'll be prompted to enter:
+- **Endpoint**: Your Butterfly platform URL (e.g., `https://app.example.com`)
+- **Email**: Your login email
+- **Password**: Your password
+
+Configuration is saved to `.butterfly/config.json`.
+
+---
+
+### `butterfly download`
+
+Download resources from the Butterfly platform.
+
+```bash
+# Download all resource types
+butterfly download
+
+# Download specific resource type
+butterfly download -t objects
+butterfly download -t reports
+butterfly download -t bfy_workflows
+butterfly download -t bfy_ai_tasks
+butterfly download -t bfy_state_machines
+butterfly download -t pages
+butterfly download -t bfy_cronjobs
+butterfly download -t cms_email_templates
+butterfly download -t cms_email_layouts
+
+# Download specific resource by name
+butterfly download -t objects -n users
+
+# Custom output directory
+butterfly download -o ./my-resources
+
+# Clean existing files before downloading
+butterfly download --cleanup
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `-t, --type <type>` | Resource type to download |
+| `-n, --name <name>` | Specific resource name |
+| `-o, --output <path>` | Output directory (default: `./butterfly-resources`) |
+| `--cleanup` | Clean existing contents before downloading |
+
+---
+
+### `butterfly start`
+
+Watch for local file changes and sync them to the Butterfly platform in real-time.
+
+```bash
+butterfly start
+
+# Custom directory
+butterfly start -o ./my-resources
+```
+
+Supported file types for sync:
+- Object specs (`spec.json`, `code.js`, `style.css`, `*.bfy`, `*.yaml`)
+- Reports (`report.json`, `query.json`, `*.bfy`, `*.js`)
+- Workflows (`workflow.json`, `version.json`, `node.json`, `code.bfy`, `params.yaml`, `connections.json`)
+- AI Tasks (`task.json`, `prompt.twig`, `*.twig`)
+- And more...
+
+---
+
+### `butterfly upload`
+
+Upload specific files or folders to the platform.
+
+```bash
+# Upload a single file
+butterfly upload butterfly-resources/objects/app/users/name/spec.json
+
+# Upload a folder
+butterfly upload butterfly-resources/objects/app/users
+
+# Upload multiple targets
+butterfly upload file1.json folder1 file2.json
+```
+
+---
+
+### `butterfly add`
+
+Create new resources via API and download them locally.
+
+```bash
+# Create a new workflow
+butterfly add -t workflow --title "My Workflow" --system-name my_workflow
+
+# Add a node to a workflow
+butterfly add -t workflow-node -w my_workflow --title "Process Data" --node-type CustomScript --node-group Code
+
+# Add a node and connect it to an existing node
+butterfly add -t workflow-node -w my_workflow --title "Send Email" --node-type Email --node-group Output --connect-from 123
+
+# Create a connection between nodes
+butterfly add -t workflow-connection -w my_workflow --from 123 --to 456
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `-t, --type <type>` | Resource type (`workflow`, `workflow-node`, `workflow-connection`) |
+| `-w, --workflow <name>` | Workflow name or ID |
+| `-v, --version <number>` | Version number (defaults to latest) |
+| `--title <title>` | Title/name of the resource |
+| `--node-type <type>` | Node identifier (e.g., `CustomScript`, `WebHook`, `RESTAPI`) |
+| `--node-group <group>` | Node group (e.g., `Code`, `Trigger`, `Connector`, `Output`) |
+| `--connect-from <spec>` | Connect from existing node to new node |
+| `--connect-to <spec>` | Connect from new node to existing node |
+
+---
+
+### `butterfly workflow-info`
+
+Get information about available workflow node types.
+
+```bash
+# List all node groups
+butterfly workflow-info --groups
+
+# List nodes in a specific group
+butterfly workflow-info --nodes Database
+
+# Get details for a specific node
+butterfly workflow-info --details RESTAPI --group Connector
+```
+
+## Directory Structure
+
+After downloading, resources are organized as follows:
+
+```
+butterfly-resources/
+├── objects/
+│   ├── butterfly/              # Core CMS objects
+│   └── app/                    # Application objects
+│       └── [table_name]/
+│           ├── object.json
+│           ├── listing_query.bfy
+│           └── [field_name]/
+│               ├── spec.json
+│               └── [code_files]
+├── reports/
+│   └── [report-alias]/
+│       ├── report.json
+│       ├── main_query.bfy
+│       ├── queries/
+│       └── specs/
+├── bfy_workflows/
+│   └── [workflow_name]/
+│       ├── workflow.json
+│       └── v1/
+│           ├── version.json
+│           ├── connections.json
+│           └── nodes/
+├── bfy_ai_tasks/
+├── bfy_state_machines/
+├── pages/
+├── bfy_cronjobs/
+├── cms_email_templates/
+└── cms_email_layouts/
+```
+
+## Field Type Code Files
+
+The CLI automatically extracts code from field specs:
+
+| Field Type | Parameter | Output File |
+|------------|-----------|-------------|
+| `calculated` | `val_1` | `code.bfy` |
+| `custom` | `val_1` | `template_code.bfy` |
+| `custom` | `val_2` | `processing_code.bfy` |
+| `filter` | `val_3` | `filter_code.bfy` |
+| `nested` | `val_1` | `configuration.yaml` |
+| `js_code` | - | `code.js` |
+| `css_code` | - | `style.css` |
+
+## Requirements
+
+- Node.js >= 16.0.0
+
+## License
+
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rglabs/butterfly",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "CLI tool to download resources from the Butterfly platform",
   "type": "module",
   "main": "dist/index.js",