@rglabs/butterfly 2.0.1

package/docs/cli-commands.md

@@ -0,0 +1,333 @@
+# Butterfly CLI Commands Reference
+
+Complete reference for all butterfly-cli commands.
+
+## Setup
+
+```bash
+butterfly-cli setup
+```
+
+Configure authentication (endpoint, email, password).
+
+---
+
+## Download
+
+```bash
+butterfly-cli download [options]
+```
+
+Download resources from the Butterfly platform.
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-t, --type <type>` | Resource type to download (see below) |
+| `-n, --name <name>` | Specific resource name to download |
+| `-o, --output <path>` | Output directory (default: ./butterfly-resources) |
+| `--cleanup` | Clean existing contents before downloading |
+
+### Resource Types
+
+| Type | Description |
+|------|-------------|
+| `objects` | CMS objects and their specs |
+| `reports` | Reports with queries and specs |
+| `webservices` | Webservice endpoints |
+| `bfy_ai_tasks` | AI tasks |
+| `bfy_state_machines` | State machines with states, transitions, actions |
+| `pages` | Pages |
+| `bfy_cronjobs` | Cron jobs |
+| `cms_email_templates` | Email templates |
+| `cms_email_layouts` | Email layouts |
+| `bfy_workflows` | Workflows with versions, nodes, and connections |
+
+### Examples
+
+```bash
+# Download all resources
+butterfly-cli download
+
+# Download only workflows
+butterfly-cli download -t bfy_workflows
+
+# Download specific object
+butterfly-cli download -t objects -n users
+
+# Download with cleanup
+butterfly-cli download -t bfy_workflows --cleanup
+```
+
+---
+
+## Upload
+
+```bash
+butterfly-cli upload <targets...>
+```
+
+Upload files or folders to the Butterfly platform.
+
+### Examples
+
+```bash
+# Upload specific file
+butterfly-cli upload path/to/file.bfy
+
+# Upload entire folder
+butterfly-cli upload butterfly-resources/objects/default/users/
+```
+
+---
+
+## Add
+
+```bash
+butterfly-cli add [options]
+```
+
+Create new resources via API and automatically download them.
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-t, --type <type>` | Resource type: `workflow`, `workflow-node` |
+| `-w, --workflow <name>` | Workflow name or ID (for workflow-node) |
+| `-v, --version <number>` | Version number (defaults to latest) |
+| `--title <title>` | Title/name of the resource |
+| `--node-type <type>` | Node type (see below) |
+| `--node-group <group>` | Node group (see below) |
+| `--system-name <name>` | System name for the resource |
+| `-o, --output <path>` | Output directory (default: ./butterfly-resources) |
+
+### Node Types
+
+| Type | Description |
+|------|-------------|
+| `CustomScript` | Custom code node (default) |
+| `WebHook` | Webhook trigger |
+| `RESTAPI` | REST API connector |
+| `ArkSigner` | ArkSigner integration |
+| `Redirect` | Redirect output |
+| `UserInteraction` | User interaction trigger |
+
+### Node Groups
+
+| Group | Description |
+|-------|-------------|
+| `Code` | Code execution nodes (default) |
+| `Trigger` | Trigger nodes (WebHook, UserInteraction) |
+| `Connector` | Connector nodes (RESTAPI) |
+| `Output` | Output nodes (Redirect) |
+| `ThirdParty` | Third-party integrations (ArkSigner) |
+
+### Examples
+
+```bash
+# Create a new workflow
+butterfly-cli add -t workflow --title "My New Workflow"
+
+# Add a CustomScript node to a workflow
+butterfly-cli add -t workflow-node -w "E-Imza" --title "Process Data"
+
+# Add a REST API connector node
+butterfly-cli add -t workflow-node -w "E-Imza" --title "API Call" --node-group Connector --node-type RESTAPI
+
+# Add a webhook trigger
+butterfly-cli add -t workflow-node -w "E-Imza" --title "My Webhook" --node-group Trigger --node-type WebHook
+
+# Add node with specific system name
+butterfly-cli add -t workflow-node -w "E-Imza" --title "Process Order" --system-name process_order
+
+# Add node to specific version
+butterfly-cli add -t workflow-node -w "E-Imza" -v 1 --title "New Node"
+```
+
+> **Note:** For detailed information about workflow node types, see [WORKFLOW_API.md](WORKFLOW_API.md).
+
+---
+
+## Layout
+
+```bash
+butterfly-cli layout [options]
+```
+
+Update object page layout (tab and field ordering).
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-f, --file <path>` | Path to JSON file with layout data |
+| `-d, --data <json>` | Inline JSON layout data |
+
+### Examples
+
+```bash
+# Update layout from a JSON file
+butterfly-cli layout -f layout.json
+
+# Update layout with inline JSON
+butterfly-cli layout -d '[{"id":0,"tabs":[{"id":0,"specs":[{"id":1323,"order_no":1}],"order_no":1}]}]'
+```
+
+> **Note:** For detailed layout structure, see [page-layout.md](page-layout.md).
+
+---
+
+## Code (Debug & Test Twig)
+
+```bash
+butterfly-cli code [options]
+```
+
+Execute Twig code on the server and retrieve variables/output. Useful for debugging queries and testing Twig code before deploying.
+
+> **WARNING:** This command executes code on the live server. Any CRUD operations (insert, update, delete) will be performed for real. Use with caution.
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-c, --code <code>` | Twig code to execute (inline) |
+| `-f, --file <path>` | Path to file containing Twig code |
+| `-o, --output <path>` | Save output to file instead of stdout |
+| `--vars` | Output only the vars object (variables set in the code) |
+| `--output-only` | Output only the rendered output field |
+| `--raw` | Output raw string (no JSON formatting) for `--output-only` |
+
+### Use Cases
+
+**1. Debug database queries:**
+```bash
+butterfly-cli code -c "{% set records = db().table('users').limit(5).get() %}{{ dump(records) }}"
+```
+
+**2. Inspect variable values:**
+```bash
+butterfly-cli code --vars -c "{% set count = db().table('orders').count() %}{% set total = db().table('orders').sum('amount') %}"
+```
+
+**3. Test complex Twig logic:**
+```bash
+butterfly-cli code -f my_query.bfy --vars
+```
+
+**4. Verify query results:**
+```bash
+butterfly-cli code -c "{% set data = db().table('products').where('status', 'active').get() %}{{ data|json_encode }}" --output-only --raw
+```
+
+### Example Output
+
+```json
+{
+  "success": true,
+  "vars": {
+    "records": [{"id": 1, "name": "Test"}, {"id": 2, "name": "Demo"}],
+    "count": 2
+  },
+  "output": "... rendered output ..."
+}
+```
+
+---
+
+## Record Commands
+
+For database record operations (get, add, edit, delete), see [RECORD_COMMAND.md](RECORD_COMMAND.md).
+
+Quick reference:
+```bash
+# Get record
+butterfly-cli record get <table> --id <id>
+butterfly-cli record get <table> --column <col> --value <val>
+
+# Add record
+butterfly-cli record add <table> --data '{...}'
+
+# Edit record
+butterfly-cli record edit <table> --id <id> --data '{...}'
+
+# Delete record (ask user first!)
+butterfly-cli record delete <table> --id <id>
+```
+
+---
+
+## Translate
+
+```bash
+butterfly-cli translate <operation> [options]
+```
+
+Manage translations efficiently without reading YAML files.
+
+### Operations
+
+| Operation | Description |
+|-----------|-------------|
+| `languages` | List all languages with translation statistics |
+| `get-untranslated` | Get untranslated texts for a language |
+| `add` | Add or update a single translation |
+| `bulk` | Bulk add/update translations from JSON file |
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--lang <iso_code>` | Language ISO code (e.g., `tr`, `de`, `en`) |
+| `--lang-id <id>` | Language ID (alternative to `--lang`) |
+| `--source <text>` | Source text to translate |
+| `--source-id <id>` | Source text ID (alternative to `--source`) |
+| `--text <translation>` | Translated text (for `add` operation) |
+| `-f, --file <path>` | CSV file path (tab-delimited) for `bulk` operation |
+| `--format <format>` | Output format: `json` or `table` (default: `table`) |
+| `--limit <count>` | Limit number of results |
+
+### Examples
+
+**List languages with stats:**
+```bash
+butterfly-cli translate languages
+```
+
+**Get untranslated texts:**
+```bash
+# Get all untranslated texts for Turkish
+butterfly-cli translate get-untranslated --lang tr
+
+# Get first 50 as JSON
+butterfly-cli translate get-untranslated --lang tr --limit 50 --format json
+```
+
+**Add single translation:**
+```bash
+# Add by source text
+butterfly-cli translate add --lang tr --source "Welcome" --text "Hoş geldiniz"
+
+# Add by source ID
+butterfly-cli translate add --lang tr --source-id 123 --text "Hoş geldiniz"
+```
+
+**Bulk translate from file:**
+```bash
+butterfly-cli translate bulk --lang tr --file translations.csv
+```
+
+### Bulk CSV Format (Tab-Delimited)
+
+```
+source	text
+Welcome	Hoş geldiniz
+Save	Kaydet
+Hello, World!	Merhaba, Dünya!
+```
+
+> **Note:** Use TAB as delimiter (not comma) to handle text containing commas. Header row is optional. The `add` command auto-detects existing translations and updates them. The `bulk` command creates missing source texts automatically.
+
+For full documentation, see [translations.md](translations.md).

package/docs/examples/README.md

@@ -0,0 +1,95 @@
+# Examples
+
+Practical examples for creating objects and specs via CLI.
+
+## Quick Start Examples
+
+| Example | Description |
+|---------|-------------|
+| [Product Catalog](./product-catalog.md) | E-commerce product with variants |
+| [User Management](./user-management.md) | Users with profiles and roles |
+| [Order System](./order-system.md) | Orders with nested line items |
+| [Blog](./blog.md) | Posts with categories and tags |
+| [Reports](./reports.md) | Reports with queries and specs |
+
+## Command Cheat Sheet
+
+### Get Object ID
+
+```bash
+# By table name
+butterfly-cli record get objects --column table_name --value "products"
+
+# List all app objects
+butterfly-cli record get objects --column is_cms_object --value 0
+```
+
+### Create Object
+
+```bash
+butterfly-cli record add objects --data '{
+  "name": "Display Name",
+  "table_name": "table_name",
+  "is_cms_object": 0
+}'
+```
+
+### Create Spec
+
+```bash
+butterfly-cli record add object_specs --data '{
+  "object_id": <ID>,
+  "name": "Field Name",
+  "column_name": "column_name",
+  "type": "string"
+}'
+```
+
+### Common Field Types
+
+```bash
+# String
+--data '{"type":"string"}'
+
+# Integer
+--data '{"type":"integer"}'
+
+# Textarea
+--data '{"type":"textarea","height":200}'
+
+# Dropdown
+--data '{"type":"from_list","val_1":"opt1:Label 1,opt2:Label 2"}'
+
+# Foreign Key
+--data '{"type":"dropdown","val_1":"table","val_2":"id","val_3":"name"}'
+
+# Date
+--data '{"type":"date"}'
+
+# Checkbox
+--data '{"type":"checkbox","default_value":"0"}'
+
+# Calculated
+--data '{"type":"calculated","val_1":"{{ info.qty * info.price }}"}'
+```
+
+## Full Workflow
+
+```bash
+# 1. Create the object
+butterfly-cli record add objects --data '{
+  "name": "Tasks",
+  "table_name": "tasks"
+}'
+# Response: SUCCESS (ID: 150)
+
+# 2. Add fields
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Title","column_name":"title","type":"string","required":1,"list_column":1,"edit_order_no":1}'
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Description","column_name":"description","type":"textarea","edit_order_no":2}'
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Status","column_name":"status","type":"from_list","val_1":"todo:To Do,progress:In Progress,done:Done","edit_order_no":3}'
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Due Date","column_name":"due_date","type":"date","edit_order_no":4}'
+butterfly-cli record add object_specs --data '{"object_id":150,"name":"Assigned To","column_name":"assigned_user_id","type":"dropdown","val_1":"users","val_2":"id","val_3":"name","edit_order_no":5}'
+
+# 3. Verify
+butterfly-cli record get object_specs --column object_id --value 150
+```

package/docs/examples/order-system.md

@@ -0,0 +1,147 @@
+# Order System Example
+
+Orders with nested line items (one-to-many relationship).
+
+## Step 1: Create Order Items Object (Child)
+
+```bash
+# Create child object first
+butterfly-cli record add objects --data '{
+  "name": "Order Items",
+  "table_name": "order_items"
+}'
+# Note ID (e.g., 152)
+
+# Add fields
+butterfly-cli record add object_specs --data '{"object_id":152,"name":"Order","column_name":"order_id","type":"dropdown","val_1":"orders","val_2":"id","val_3":"id","edit_order_no":1}'
+butterfly-cli record add object_specs --data '{"object_id":152,"name":"Product","column_name":"product_id","type":"dropdown","val_1":"products","val_2":"id","val_3":"title","edit_order_no":2}'
+butterfly-cli record add object_specs --data '{"object_id":152,"name":"Quantity","column_name":"quantity","type":"integer","default_value":"1","edit_order_no":3}'
+butterfly-cli record add object_specs --data '{"object_id":152,"name":"Unit Price","column_name":"unit_price","type":"decimal","edit_order_no":4}'
+butterfly-cli record add object_specs --data '{"object_id":152,"name":"Total","column_name":"line_total","type":"calculated","val_1":"{{ info.quantity * info.unit_price }}","edit_order_no":5}'
+```
+
+## Step 2: Create Orders Object (Parent)
+
+```bash
+# Create parent object
+butterfly-cli record add objects --data '{
+  "name": "Orders",
+  "table_name": "orders",
+  "has_trash": 1
+}'
+# Note ID (e.g., 153)
+
+# Order Info
+butterfly-cli record add object_specs --data '{
+  "object_id": 153,
+  "name": "Order Number",
+  "column_name": "order_number",
+  "type": "string",
+  "list_column": 1,
+  "section_title": "Order Information",
+  "edit_order_no": 1
+}'
+
+butterfly-cli record add object_specs --data '{
+  "object_id": 153,
+  "name": "Customer",
+  "column_name": "customer_id",
+  "type": "dropdown",
+  "val_1": "customers",
+  "val_2": "id",
+  "val_3": "name",
+  "required": 1,
+  "list_column": 1,
+  "edit_order_no": 2
+}'
+
+butterfly-cli record add object_specs --data '{
+  "object_id": 153,
+  "name": "Order Date",
+  "column_name": "order_date",
+  "type": "date",
+  "default_value": "today",
+  "list_column": 1,
+  "edit_order_no": 3
+}'
+
+# Nested Line Items
+butterfly-cli record add object_specs --data '{
+  "object_id": 153,
+  "name": "Line Items",
+  "column_name": "items",
+  "type": "nested",
+  "val_1": "table: order_items\nforeign_key: order_id\ncolumns:\n  - product_id\n  - quantity\n  - unit_price\n  - line_total",
+  "section_title": "Order Items",
+  "edit_order_no": 4
+}'
+
+# Totals
+butterfly-cli record add object_specs --data '{
+  "object_id": 153,
+  "name": "Subtotal",
+  "column_name": "subtotal",
+  "type": "decimal",
+  "section_title": "Totals",
+  "column_size": "col-md-4",
+  "edit_order_no": 5
+}'
+
+butterfly-cli record add object_specs --data '{
+  "object_id": 153,
+  "name": "Tax",
+  "column_name": "tax_amount",
+  "type": "decimal",
+  "column_size": "col-md-4",
+  "edit_order_no": 6
+}'
+
+butterfly-cli record add object_specs --data '{
+  "object_id": 153,
+  "name": "Total",
+  "column_name": "total",
+  "type": "decimal",
+  "column_size": "col-md-4",
+  "edit_order_no": 7
+}'
+
+# Sidebar
+butterfly-cli record add object_specs --data '{
+  "object_id": 153,
+  "name": "Status",
+  "column_name": "status",
+  "type": "from_list",
+  "val_1": "pending:Pending,processing:Processing,shipped:Shipped,delivered:Delivered,cancelled:Cancelled",
+  "default_value": "pending",
+  "edit_position": 1,
+  "edit_order_no": 1
+}'
+
+butterfly-cli record add object_specs --data '{
+  "object_id": 153,
+  "name": "Payment Status",
+  "column_name": "payment_status",
+  "type": "from_list",
+  "val_1": "unpaid:Unpaid,paid:Paid,refunded:Refunded",
+  "default_value": "unpaid",
+  "edit_position": 1,
+  "edit_order_no": 2
+}'
+```
+
+## Step 3: Add Auto-Calculate on Product Select
+
+Update the order items product field to auto-fill price:
+
+```bash
+butterfly-cli record edit object_specs --id <PRODUCT_SPEC_ID> --data '{
+  "js_code": "%element%.on(\"change\", function() { var id = $(this).val(); if(id) { $.post(\"/admin/ajax/cms_object/get\", {\"table_name\": \"products\", \"column\": \"id\", \"value\": id}, function(data) { if(data.data[0]) { $(this).closest(\"tr\").find(\"[name*=unit_price]\").val(data.data[0].price).trigger(\"change\"); } }.bind(this)); } })"
+}'
+```
+
+## Result
+
+- **Orders** with customer, date, status tracking
+- **Order Items** as nested sub-form
+- Auto-calculation of line totals
+- Status and payment tracking in sidebar