@rglabs/butterfly 2.0.1

package/docs/state-machines.md

@@ -0,0 +1,544 @@
+# State Machines
+
+This document explains how to work with state machines in Butterfly.
+
+## Overview
+
+State machines define workflow states, transitions, roles, and actions for managing record lifecycles. When you create a new state machine, the system automatically creates default components.
+
+## Default State and Role Creation
+
+When a new state machine is created, the system **automatically creates**:
+
+1. **Default State**: A state named `"Created"` (system_name: `created`)
+2. **Default Role**: A role named `"General"`
+
+> **Important:** You don't need to manually create these. If you want to change the default state or role names, simply update them after creation.
+
+### Updating Default State Name
+
+```
+POST /admin/ajax/cms_object/operation?do=bfy_state_machine_states__edit
+Content-Type: application/x-www-form-urlencoded
+
+id=<STATE_ID>&name=New State Name&system_name=new_state_name
+```
+
+### Updating Default Role Name
+
+```
+POST /admin/ajax/cms_object/operation?do=bfy_state_machine_roles__edit
+Content-Type: application/x-www-form-urlencoded
+
+id=<ROLE_ID>&name=New Role Name
+```
+
+## Binding a State Machine to an Object
+
+To use a state machine with an object, add a field with type `state` and set the state machine ID as the parameter (`val_1`).
+
+### Adding a State Field to an Object
+
+```
+POST /admin/ajax/cms_object/operation?do=object_specs__add
+Content-Type: application/x-www-form-urlencoded
+
+object_id=<OBJECT_ID>&name=Status&column_name=state&type=state&val_1=<STATE_MACHINE_ID>&edit_position=1&edit_order_no=1
+```
+
+**Parameters for `state` field type:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `val_1` | State machine ID to bind |
+
+**Recommended positioning:**
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `edit_position` | `1` | Right column (sidebar) |
+| `edit_order_no` | `1` | Top of the column |
+
+**Example:**
+```
+POST /admin/ajax/cms_object/operation?do=object_specs__add
+Content-Type: application/x-www-form-urlencoded
+
+object_id=128&name=Order Status&column_name=state&type=state&val_1=5&edit_position=1&edit_order_no=1
+```
+
+This creates a "state" column in your object that:
+- Displays the current state from the bound state machine
+- Shows available transitions based on user roles
+- Tracks state history for the record
+
+> **Best Practice:** Place the state field in the right column (`edit_position=1`) at the top (`edit_order_no=1`) so it's always visible and accessible in the sidebar.
+
+> **Note:** The column name is typically `state`, but you can use any column name.
+
+## Tables Involved
+
+| Table | Purpose |
+|-------|---------|
+| `bfy_state_machines` | Main state machine definition |
+| `bfy_state_machine_states` | States within a state machine |
+| `bfy_state_machine_roles` | Roles that can perform transitions |
+| `bfy_state_machine_transitions` | Transitions between states |
+| `bfy_state_machine_transition_specs` | Form fields shown during transitions |
+| `bfy_sm_actions` | Reusable actions |
+| `bfy_sm_transition_actions` | Actions triggered by transitions |
+| `bfy_sm_action_specs` | Form fields for actions |
+
+## Directory Structure
+
+When downloading state machines, the CLI creates:
+
+```
+bfy_state_machines/
+└── [state_machine_name]/
+    ├── state_machine.json          # Main state machine data
+    ├── states/
+    │   └── [state_name]/
+    │       └── state.json
+    ├── roles/
+    │   └── [role_name]/
+    │       ├── role.json
+    │       └── validation_code.bfy  # If validation code exists
+    ├── transitions/
+    │   └── [transition_name]/
+    │       ├── transition.json
+    │       ├── action_code.bfy      # If action code exists
+    │       ├── validation_code.bfy  # If validation code exists
+    │       └── specs/               # Transition form fields
+    │           └── [spec_name]/
+    │               └── spec.json
+    ├── actions/
+    │   └── [action_name]/
+    │       ├── action.json
+    │       ├── code.bfy             # Action code
+    │       └── specs/               # Action form fields
+    │           └── [spec_name]/
+    │               └── spec.json
+    └── transition_actions/
+        └── [mapping_name].json      # Transition-action mappings
+```
+
+## State Machine Table (`bfy_state_machines`)
+
+| Column | Type | Required | Description |
+|--------|------|----------|-------------|
+| `name` | string | Yes | Display name of the state machine |
+| `bfy_state_machine_state_id` | int | No | Default/initial state ID |
+| `bfy_workspace_id` | int | No | Workspace ID |
+
+### Creating a State Machine
+
+```
+POST /admin/ajax/cms_object/operation?do=bfy_state_machines__add
+Content-Type: application/x-www-form-urlencoded
+
+name=Order Status
+```
+
+> **Note:** After creation, a default state "Created" and role "General" are automatically added.
+
+## States Table (`bfy_state_machine_states`)
+
+| Column | Type | Required | Description |
+|--------|------|----------|-------------|
+| `bfy_state_machine_id` | int | No | Parent state machine ID |
+| `name` | string | Yes | Display name |
+| `system_name` | string | No | System identifier (slug) |
+
+### Creating Additional States
+
+```
+POST /admin/ajax/cms_object/operation?do=bfy_state_machine_states__add
+Content-Type: application/x-www-form-urlencoded
+
+bfy_state_machine_id=<SM_ID>&name=Processing&system_name=processing
+```
+
+## Roles Table (`bfy_state_machine_roles`)
+
+| Column | Type | Required | Description |
+|--------|------|----------|-------------|
+| `bfy_state_machine_id` | int | No | Parent state machine ID |
+| `name` | string | Yes | Display name |
+| `validation_code` | string | No | Twig code to validate if user has this role |
+
+### Creating Additional Roles
+
+```
+POST /admin/ajax/cms_object/operation?do=bfy_state_machine_roles__add
+Content-Type: application/x-www-form-urlencoded
+
+bfy_state_machine_id=<SM_ID>&name=Admin
+```
+
+### Role Validation Code
+
+The `validation_code` field contains Twig code that determines if the current user has this role:
+
+```twig
+{# Example: Check if user is admin #}
+{% if user.role == 'admin' %}
+  {{ true }}
+{% endif %}
+```
+
+## Transitions Table (`bfy_state_machine_transitions`)
+
+| Column | Type | Required | Description |
+|--------|------|----------|-------------|
+| `bfy_state_machine_id` | int | No | Parent state machine ID |
+| `name` | string | Yes | Display name |
+| `from_bfy_state_machine_state_id` | int | No | Source state ID |
+| `to_bfy_state_machine_state_id` | int | No | Target state ID |
+| `bfy_state_machine_role_id` | int | No | Required role ID |
+| `action_code` | string | No | Twig code executed on transition (for single-use actions) |
+| `validation_code` | string | No | Twig code to validate transition |
+
+### Action Code vs Reusable Actions
+
+When adding logic to transitions, choose between:
+
+| Approach | When to Use | Location |
+|----------|-------------|----------|
+| `action_code` | Action is used in **only one transition** | Inline in `bfy_state_machine_transitions.action_code` |
+| `bfy_sm_actions` | Action is **reused across multiple transitions** | Separate record in `bfy_sm_actions`, linked via `bfy_sm_transition_actions` |
+
+**Use `action_code` when:**
+- The logic is specific to a single transition
+- You don't need to reuse the same logic elsewhere
+- The action is simple and self-contained
+
+**Use `bfy_sm_actions` when:**
+- The same action needs to run on multiple transitions
+- You want to maintain the logic in one place (DRY principle)
+- The action is complex and benefits from being modular
+
+### Accessing Transition Spec Values in Action Code
+
+When a transition has specs (form fields defined via `bfy_state_machine_transition_specs`), the values entered by the user during the transition are accessible in `action_code` using `params.XXX`:
+
+```twig
+{# Access transition spec values using params.column_name #}
+{% set rejectionReason = params.rejection_reason %}
+{% set notifyCustomer = params.notify_customer %}
+
+{# Example: Use spec values to update the record #}
+{{ setValue('rejection_reason', params.rejection_reason) }}
+
+{# Example: Conditional logic based on spec value #}
+{% if params.notify_customer == '1' %}
+  {# Send notification logic here #}
+{% endif %}
+```
+
+> **Important:** `params.XXX` is used to access transition spec values in `action_code`. This is different from `getParameter('XXX')` which accesses POST/GET parameters from HTTP requests elsewhere in the system.
+
+### Transition Validation Code
+
+The `validation_code` field in transitions determines whether a transition button should be shown and if the transition can be executed. Use `{{ info.XXX }}` to access current record data.
+
+#### Validation Functions
+
+| Function | Description |
+|----------|-------------|
+| *(no function)* | Transition is valid and button is shown |
+| `{{ notValid() }}` | Transition is not valid, button is hidden |
+| `{{ validRequire('Message') }}` | Button is shown but disabled with message; something must be fulfilled first |
+| `{{ validHidden() }}` | Transition is valid but button is hidden; can only be triggered programmatically |
+
+#### Examples
+
+**Simple condition - hide button if already processed:**
+```twig
+{% if info.is_processed == 1 %}
+  {{ notValid() }}
+{% endif %}
+```
+
+**Require a field to be filled before transition:**
+```twig
+{% if info.assigned_to is empty %}
+  {{ validRequire('Please assign a user first') }}
+{% endif %}
+```
+
+**Hidden transition (triggered from external code/API):**
+```twig
+{{ validHidden() }}
+```
+
+**Complex validation with multiple conditions:**
+```twig
+{% if info.total_amount <= 0 %}
+  {{ validRequire('Order must have items') }}
+{% elseif info.shipping_address is empty %}
+  {{ validRequire('Shipping address required') }}
+{% elseif info.is_cancelled == 1 %}
+  {{ notValid() }}
+{% endif %}
+```
+
+> **Note:** If no validation function is called, the transition is considered valid and the button will be displayed.
+
+### Creating a Transition
+
+```
+POST /admin/ajax/cms_object/operation?do=bfy_state_machine_transitions__add
+Content-Type: application/x-www-form-urlencoded
+
+bfy_state_machine_id=<SM_ID>&name=Start Processing&from_bfy_state_machine_state_id=<FROM_STATE_ID>&to_bfy_state_machine_state_id=<TO_STATE_ID>&bfy_state_machine_role_id=<ROLE_ID>
+```
+
+## Workflow Example
+
+### 1. Create State Machine
+
+```
+POST /admin/ajax/cms_object/operation?do=bfy_state_machines__add
+name=Order Workflow
+```
+
+Response includes the new state machine ID. Default "Created" state and "General" role are auto-created.
+
+### 2. Add Additional States
+
+```
+# Add "Processing" state
+POST /admin/ajax/cms_object/operation?do=bfy_state_machine_states__add
+bfy_state_machine_id=1&name=Processing&system_name=processing
+
+# Add "Completed" state
+POST /admin/ajax/cms_object/operation?do=bfy_state_machine_states__add
+bfy_state_machine_id=1&name=Completed&system_name=completed
+```
+
+### 3. Add Roles (Optional)
+
+```
+# Add "Manager" role
+POST /admin/ajax/cms_object/operation?do=bfy_state_machine_roles__add
+bfy_state_machine_id=1&name=Manager
+```
+
+### 4. Create Transitions
+
+```
+# Transition from Created to Processing
+POST /admin/ajax/cms_object/operation?do=bfy_state_machine_transitions__add
+bfy_state_machine_id=1&name=Start Processing&from_bfy_state_machine_state_id=1&to_bfy_state_machine_state_id=2&bfy_state_machine_role_id=1
+```
+
+### 5. Download to Local
+
+```bash
+butterfly-cli download -t bfy_state_machines -n "Order Workflow"
+```
+
+## Triggering State Transitions Programmatically
+
+State transitions can be triggered via the `butterfly-cli record edit` command by passing a special JSON structure to the `state` field.
+
+### Automatic Transitions (from State 0)
+
+When a record is created or saved, certain transitions are triggered automatically based on the `from_bfy_state_machine_state_id` value:
+
+| From State ID | To State ID | Trigger Condition |
+|---------------|-------------|-------------------|
+| `0` | Default state ID | **On record creation** - Automatically triggered when a new record is added |
+| `0` | `0` | **On every save** - Executed on all save operations (insert and update) |
+
+> **Note:** Transitions with `from_bfy_state_machine_state_id = 0` act as hooks that run automatically without manual triggering.
+
+### Manual Transition via CLI
+
+To manually trigger a state transition on an existing record, use `butterfly-cli record edit` with a JSON-encoded `state` field:
+
+```bash
+butterfly-cli record edit <table_name> --id <RECORD_ID> --data '{"state": "{\"state_transition_id\":<TRANSITION_ID>,\"params\":{}}"}'
+```
+
+**State field structure:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `state_transition_id` | int | The ID of the transition to execute (from `bfy_state_machine_transitions.id`) |
+| `params` | object | Key-value pairs for transition spec fields (`column_name: value`) |
+
+### Example: Transition without Parameters
+
+```bash
+butterfly-cli record edit orders --id 123 --data '{"state": "{\"state_transition_id\":2,\"params\":{}}"}'
+```
+
+### Example: Transition with Parameters
+
+If the transition has spec fields (form fields shown during transition), pass their values in `params`:
+
+```bash
+butterfly-cli record edit orders --id 123 --data '{"state": "{\"state_transition_id\":5,\"params\":{\"rejection_reason\":\"Out of stock\",\"notify_customer\":\"1\"}}"}'
+```
+
+In this example:
+- `state_transition_id: 5` - The transition to execute
+- `rejection_reason` and `notify_customer` - Transition spec column names with their values
+
+### Finding Transition IDs
+
+Transition IDs can be found in:
+1. **Local files**: `butterfly-resources/bfy_state_machines/[name]/transitions/[transition]/transition.json`
+2. **Database**: Query `bfy_state_machine_transitions` table
+
+```bash
+# Using CLI to get transition details
+butterfly-cli record get bfy_state_machine_transitions --column bfy_state_machine_id --value <SM_ID>
+```
+
+## CLI Commands
+
+### Download State Machines
+
+```bash
+# Download all state machines
+butterfly-cli download -t bfy_state_machines
+
+# Download specific state machine
+butterfly-cli download -t bfy_state_machines -n "Order Workflow"
+
+# Download with cleanup
+butterfly-cli download -t bfy_state_machines --cleanup
+```
+
+### Upload Changes
+
+```bash
+butterfly-cli upload <path>
+```
+
+Upload state machine files (state_machine.json, state.json, role.json, transition.json, code files) to sync changes to the platform.
+
+## CRUD Context in State Machine Code
+
+Within state machine transition code (`action_code`), validation code (`validation_code`), and action code, you have access to the current CRUD operation context using the `getCrud()` function.
+
+### Available Functions
+
+| Function | Description | Return Type |
+|----------|-------------|-------------|
+| `getCrud()` | Returns the current CRUD operation object | object |
+| `getCrud().get_difference()` | Returns changed fields with old and new values | array |
+| `getCrud().getOldData('column_name')` | Returns the previous value of a specific column | mixed |
+| `getValue('column_name')` | Returns the current value of a column | mixed |
+
+### Detecting Changes with `get_difference()`
+
+The `get_difference()` method returns an array of changed fields. Each changed field contains `old_data` and `new_data` keys:
+
+```twig
+{% set changes = getCrud().get_difference() %}
+
+{# Example return value when 'title' and 'status' changed: #}
+{# {
+     "title": {"old_data": "Old Title", "new_data": "New Title"},
+     "status": {"old_data": "draft", "new_data": "published"}
+   }
+#}
+
+{# If no changes, returns empty array: {} #}
+```
+
+### Common Use Cases
+
+#### 1. Update modification timestamp when any field changes
+
+```twig
+{% set changes = getCrud().get_difference() %}
+{% if changes|length > 0 %}
+  {{ setValue('modification_date', 'now'|date('Y-m-d H:i:s')) }}
+  {{ setValue('updated_by', currentUser('id')) }}
+{% endif %}
+```
+
+#### 2. Check if a specific field was changed
+
+```twig
+{% set changes = getCrud().get_difference() %}
+{% if changes.status is defined %}
+  {# Status field was modified #}
+  {% set oldStatus = changes.status.old_data %}
+  {% set newStatus = changes.status.new_data %}
+
+  {# Log the status change or trigger notifications #}
+{% endif %}
+```
+
+#### 3. Compare old and current values using getOldData()
+
+```twig
+{% set oldPrice = getCrud().getOldData('price') %}
+{% set currentPrice = getValue('price') %}
+
+{% if oldPrice != currentPrice %}
+  {# Price was changed, log the change #}
+  {% set response = crud()
+    .table('price_history')
+    .insert({
+      "product_id": getValue('id'),
+      "old_price": oldPrice,
+      "new_price": currentPrice,
+      "changed_at": 'now'|date('Y-m-d H:i:s')
+    })
+  %}
+{% endif %}
+```
+
+#### 4. Prevent transition if certain fields haven't changed
+
+```twig
+{# In validation_code - prevent completion if no work was done #}
+{% set changes = getCrud().get_difference() %}
+{% if changes.result is not defined and changes.notes is not defined %}
+  {{ errorMessage('Please fill in result or notes before completing this task.') }}
+{% endif %}
+```
+
+#### 5. Track who made changes
+
+```twig
+{% set changes = getCrud().get_difference() %}
+{% if changes|length > 0 %}
+  {{ setValue('last_modified_by', currentUser('id')) }}
+  {{ setValue('last_modified_at', 'now'|date('Y-m-d H:i:s')) }}
+
+  {# Optionally log all changes #}
+  {% for field, change in changes %}
+    {% set log = crud()
+      .table('audit_log')
+      .insert({
+        "record_id": getValue('id'),
+        "field_name": field,
+        "old_value": change.old_data,
+        "new_value": change.new_data,
+        "changed_by": currentUser('id'),
+        "changed_at": 'now'|date('Y-m-d H:i:s')
+      })
+    %}
+  {% endfor %}
+{% endif %}
+```
+
+### Important Notes
+
+- `getCrud()` is only available within state machine context (transitions, actions, validation code)
+- `get_difference()` returns an empty array `{}` if no fields were modified
+- `getOldData()` returns the value before the current save operation
+- `getValue()` returns the current/new value being saved
+- These functions are particularly useful for audit trails, conditional logic, and automatic field updates
+
+## Related
+
+- [Main CLAUDE.md](./CLAUDE.md) - Full CLI documentation

package/docs/tasks/create-object.md

@@ -0,0 +1,81 @@
+# Object Generation Prompt
+
+You are a database architect for Butterfly Platform. Create an object definition based on the user's request.
+
+## CRITICAL RULES
+
+### 1. Check Existing Tables First
+- Look in `butterfly-resources/objects/app/` for existing application tables
+- Look in `butterfly-resources/objects/butterfly/` for core/system tables
+- Use existing tables for dropdowns/autocomplete references
+
+### 2. Output Format: CSV with backtick (`) separator
+
+```
+[OBJECT]
+name`table_name`database_alias`has_item`seo`menu_path`section_title`auto_increment_column_name`left_column_size
+Display Name`table_name`default`0``Menu::icon>SubMenu::icon`Section Title`id`1/2
+
+[SPECS]
+name`column_name`type`val_1`val_2`val_3`val_4`val_5`column_size`required`tab_title`tab_placement`list_column`search_column`is_displayed_in_filter
+Field Name`column_name`type`0`0`0`0`0`1/2`1``0`1`1`0
+```
+
+### 3. Tab Title Rules
+- Use empty string for default tab (NOT "Genel", "General", etc.)
+- Only use specific tab names for additional grouped tabs
+
+### 4. Column Size Rules
+- Single word field names: can use `1/3` or `1/4`
+- Two+ word field names: must use `1/2` or `1`
+
+### 5. Field Types Reference
+
+| Type | val_1 | val_2 | val_3 | val_4 | val_5 |
+|------|-------|-------|-------|-------|-------|
+| `string` | 0 | 0 | 0 | 0 | 0 |
+| `textarea` | 0 | 0 | 0 | 0 | 0 |
+| `integer` | 0 | 0 | 0 | 0 | 0 |
+| `float` | 0 | 0 | 0 | 0 | 0 |
+| `money` | 0 | 0 | 0 | 0 | 0 |
+| `date` | 0 | 0 | 0 | 0 | 0 |
+| `datetime` | 0 | 0 | 0 | 0 | 0 |
+| `checkbox` | 0 | 0 | 0 | 0 | 0 |
+| `dropdown` | table_name | display_column | value_column | filter or 0 | 0 |
+| `autocomplete` | table_name | display_column | value_column | filter or 0 | 0 |
+| `from_list` | "key1:Label1\|key2:Label2" | 0 | 0 | 0 | 0 |
+| `file_upload` | upload | 0 | 0 | 0 | 0 |
+| `calculated` | twig_code | 0 | 0 | 0 | 0 |
+| `status` | 0 | 0 | 0 | 0 | 0 |
+
+### 6. Menu Path Format
+Format: `Category::icon>SubCategory::icon`
+Use Lucide icons: https://lucide.dev/icons
+
+Common icons:
+- Settings: `settings`, `sliders`
+- Finance: `wallet`, `coins`, `banknote`
+- Inventory: `package`, `boxes`, `warehouse`
+- Sales: `shopping-cart`, `receipt`
+- Master Data: `database`, `folder`
+- Users: `users`, `user`
+
+### 7. Layout Rules
+- `tab_placement`: 0 = left column, 1 = right column
+- `list_column`: 1 = show in listing table
+- `search_column`: 1 = searchable field
+- `is_displayed_in_filter`: 1 = show in filter bar
+
+### 8. Important Notes
+- Table names: plural, snake_case (e.g., `purchase_orders`)
+- Column names: singular, snake_case (e.g., `order_date`)
+- Foreign keys end with `_id` (e.g., `customer_id`)
+- System fields (id, created_at, updated_at) are auto-created, don't add them
+- Use Turkish characters properly (İ, Ş, Ü, Ğ, Ç, Ö) if source is Turkish
+
+## Task
+
+1. Read the user's request
+2. Check existing tables in `butterfly-resources/objects/` for related tables
+3. Generate a single object CSV definition
+4. Write the CSV to `butterfly-resources/.temp/new_object.csv`