@rglabs/butterfly 2.0.1

package/docs/CLAUDE.md

@@ -0,0 +1,216 @@
+# CLAUDE.md
+
+## Translations in Twig
+
+```twig
+{{ "text"|trans }}
+{{ "Hello %name%"|trans({'name': value}) }}
+```
+
+## Resource Information Lookup
+
+1. **First, search in `butterfly-resources/` folder** - local resources are the source of truth
+2. **If not found locally**, use `butterfly-cli record get <table> --column <col> --value <val>`
+3. **For table/column info**, check `butterfly-resources/docs/` folder
+
+## Record Command Quick Reference
+
+| Operation | When to Use | Command |
+|-----------|-------------|---------|
+| **GET** | Not in `butterfly-resources/` | `butterfly-cli record get <table> --id <id>` |
+| **ADD** | **Always** (never create files manually) | `butterfly-cli record add <table> --data '{...}'` |
+| **EDIT** | Not in `butterfly-resources/` | `butterfly-cli record edit <table> --id <id> --data '{...}'` |
+| **DELETE** | Always (ask user first!) | `butterfly-cli record delete <table> --id <id>` |
+
+> **For EDIT operations only:** If the resource exists in `butterfly-resources/`, edit local files and use `butterfly-cli upload <path>` instead. **ADD operations must ALWAYS use `butterfly-cli record add`** - never create files manually in `butterfly-resources/`.
+
+See [docs/RECORD_COMMAND.md](docs/RECORD_COMMAND.md) for full documentation.
+
+## System Table Names
+
+| Correct Name | Wrong Alternatives | Description |
+|--------------|-------------------|-------------|
+| `objects` | `cms_objects` | Object definitions |
+| `object_specs` | `cms_object_specs` | Field specifications |
+| `object_tabs` | `cms_object_tabs` | Page tabs |
+| `bfy_sm_actions` | `bfy_state_machine_actions` | State machine actions |
+| `bfy_sm_transition_actions` | `bfy_state_machine_transition_actions` | Transition-action mappings |
+| `bfy_sm_action_specs` | `bfy_state_machine_action_specs` | Action form fields |
+| `cms_reports` | `reports` | Report definitions |
+| `cms_report_queries` | `report_queries` | Report queries |
+| `cms_report_specs` | `report_specs` | Report field specs |
+| `webservices` | - | Webservice endpoints |
+
+## Directory Structure
+
+```
+butterfly-resources/
+├── objects/[butterfly|app]/[table]/     # Objects and specs
+├── bfy_state_machines/[name]/           # State machines
+├── bfy_workflows/[name]/v[n]/           # Workflows
+├── reports/[alias]/                     # Reports
+├── webservices/[custom_seo]/            # Webservices
+├── pages/                               # Pages
+├── bfy_cronjobs/                        # Cron jobs
+└── docs/                                # Database docs
+```
+
+## Field Type Code Mappings (Quick Reference)
+
+| Field Type | Parameter | Export File |
+|------------|-----------|-------------|
+| `calculated` | `val_1` | `code.bfy` |
+| `custom` | `val_1`, `val_2` | `template_code.bfy`, `processing_code.bfy` |
+| `filter` | `val_3` | `filter_code.bfy` |
+| `nested`/`nested_single` | `val_1` | `configuration.yaml` |
+
+See [docs/field-types/code-mappings.md](docs/field-types/code-mappings.md) for full details.
+
+## CLI Commands (Quick Reference)
+
+| Command | Description |
+|---------|-------------|
+| `butterfly-cli setup` | Configure authentication |
+| `butterfly-cli download [-t type]` | Download resources |
+| `butterfly-cli upload <path>` | Upload files |
+| `butterfly-cli add -t workflow` | Create workflow |
+| `butterfly-cli code -c "..."` | Test Twig code |
+| `butterfly-cli layout -f file.json` | Update page layout |
+| `butterfly-cli translate <operation>` | Manage translations |
+
+See [docs/cli-commands.md](docs/cli-commands.md) for full documentation.
+
+## Translation Commands (Quick Reference)
+
+| Command | Description |
+|---------|-------------|
+| `butterfly-cli translate languages` | List languages with stats |
+| `butterfly-cli translate get-untranslated --lang tr` | Get untranslated texts |
+| `butterfly-cli translate add --lang tr --source "text" --text "çeviri"` | Add/update single translation |
+| `butterfly-cli translate bulk --lang tr --file translations.json` | Bulk import translations |
+
+**Bulk CSV format (tab-delimited):**
+```
+source	text
+Welcome	Hoş geldiniz
+Save	Kaydet
+```
+
+See [docs/translations.md](docs/translations.md) for full documentation.
+
+## Query Helpers (Quick Reference)
+
+```twig
+{% set records = db().table('users').where('status', 'active').get() %}
+{% set user = db().table('users').where('id', 5).first() %}
+{% set ids = db().table('users').column('id') %}
+{% set map = db().table('users').keyToValue('id', 'name') %}
+```
+
+See [docs/twig-helpers.md](docs/twig-helpers.md) for full documentation.
+
+## Settings (Quick Reference)
+
+```twig
+{# Get single setting value #}
+{% set value = setting('group_alias', 'setting_alias') %}
+
+{# Get all settings in a group #}
+{% set all = setting('group_alias') %}
+{{ all.setting_alias.value }}
+```
+
+**Tables:** `cms_setting_groups` (groups by alias) → `cms_settings` (individual settings)
+
+See [docs/twig-helpers.md](docs/twig-helpers.md#settings) for full documentation.
+
+## JavaScript Field Updates (Quick Reference)
+
+| Field Types | Method |
+|-------------|--------|
+| `calculated`, `custom`, `date` | `bfyRefresh_COLUMN_NAME(value)` |
+| All others | `$('[name="COLUMN"]').val(value).trigger('change')` |
+
+See [docs/object-specs/js-field-updates.md](docs/object-specs/js-field-updates.md) for full documentation.
+
+## Admin Page URL Format
+
+```
+/admin/SINGULAR_TABLE_NAME/list
+/admin/SINGULAR_TABLE_NAME/add
+/admin/SINGULAR_TABLE_NAME/edit/ID
+```
+
+For non-default database: `/admin/DATABASE_ALIAS/SINGULAR_TABLE_NAME/...`
+
+## Object Menu Placement
+
+Format: `MainMenu>SubMenu>MenuItemName` or with icons: `MainMenu::icon>SubMenu::icon>Item::icon`
+
+## Object Default Permissions
+
+Set `usergroup_id` on an object to define its default (maximum) permissions system-wide:
+
+```bash
+butterfly-cli record edit objects --id <object_id> --data '{"usergroup_id": <usergroup_id>}'
+```
+
+This assigns a user group as the permission template for the object. See [docs/permissions.md](docs/permissions.md) for full documentation.
+
+## Workspaces (bfy_workspaces)
+
+| `is_workspace_specific` | Scope | `bfy_workspace_id` Location |
+|-------------------------|-------|----------------------------|
+| `0` (default) | Object-level | `objects` table |
+| `1` | Record-level | Data table column |
+
+```bash
+# Assign object to workspace (object-level)
+butterfly-cli record edit objects --id <object_id> --data '{"bfy_workspace_id": <workspace_id>}'
+
+# Assign record to workspace (record-level)
+butterfly-cli record add <table_name> --data '{"bfy_workspace_id": <workspace_id>, ...}'
+```
+
+See [docs/workspaces.md](docs/workspaces.md) for full documentation.
+
+## Project-Specific Instructions
+
+Always check if `docs/PROJECT_SPECIFIC.md` exists and prioritize those instructions.
+
+## See Also
+
+**Core Documentation:**
+- [docs/cli-commands.md](docs/cli-commands.md) - Full CLI reference
+- [docs/RECORD_COMMAND.md](docs/RECORD_COMMAND.md) - Record command usage
+- [docs/twig-helpers.md](docs/twig-helpers.md) - Query helpers and CRUD
+- [docs/reports.md](docs/reports.md) - Report creation guide
+- [docs/webservices.md](docs/webservices.md) - Webservice/API creation
+
+**Field Types & Specs:**
+- [docs/field-types/](docs/field-types/) - Field type documentation
+- [docs/field-types/code-mappings.md](docs/field-types/code-mappings.md) - Code export mappings
+- [docs/object-specs/js-field-updates.md](docs/object-specs/js-field-updates.md) - JavaScript updates
+- [docs/object-specs/js-code-examples.md](docs/object-specs/js-code-examples.md) - JS code examples
+
+**Other Guides:**
+- [docs/state-machines.md](docs/state-machines.md) - State machine configuration
+- [docs/page-layout.md](docs/page-layout.md) - Page layout organization
+- [docs/permissions.md](docs/permissions.md) - Object permissions and user groups
+- [docs/workspaces.md](docs/workspaces.md) - Workspace scoping for objects and records
+- [docs/excel-export.md](docs/excel-export.md) - Excel export functionality
+- [docs/bfy-splitting.md](docs/bfy-splitting.md) - BFY file splitting for large files
+- [docs/translations.md](docs/translations.md) - Translations and i18n
+- [docs/WORKFLOW_API.md](docs/WORKFLOW_API.md) - Workflow node types
+
+**Slash Commands:**
+
+| Command | When to Use |
+|---------|-------------|
+| `/docs-cli` | When you need help with `butterfly-cli` commands (download, upload, setup, add, record, code, layout) |
+| `/docs-field-types` | When creating/editing object specs and need to know field type parameters (`val_1`, `val_2`, etc.) |
+| `/docs-twig` | When writing Twig code for reports, calculated fields, or processing code (`db()`, `crud()`, helpers) |
+| `/docs-state-machine` | When creating or modifying state machines, transitions, actions, or validation code |
+| `/docs-webservice` | When creating API endpoints or webservices using reports with `custom_seo` |
+
+> **AI INSTRUCTION:** Always use the relevant slash command before working on any task related to that topic. This ensures accurate implementation without guessing syntax or parameters.

package/docs/PROJECT_SPECIFIC.md

@@ -0,0 +1 @@
+## In this file, there should be project specific information ##

package/docs/RECORD_COMMAND.md

@@ -0,0 +1,262 @@
+# Record Command (Experimental)
+
+> **Note:** This command is experimental. Only use when explicitly requested by the user.
+
+## Overview
+
+```bash
+butterfly-cli record <operation> <table> [options]
+```
+
+Perform CRUD operations (get/add/edit/delete) on any Butterfly table with preview and approval.
+
+## Operations
+
+| Operation | Description | Required Options |
+|-----------|-------------|------------------|
+| `get` | Retrieve records | `--id` or `--column`/`--value` |
+| `add` | Create new record | `--data` or `--file` |
+| `edit` | Update record | `--id` + `--data` or `--file` |
+| `delete` | Delete record | `--id` |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--id <id>` | Record ID (required for edit/delete, optional for get) |
+| `--column <column>` | Filter column(s) for get (comma-separated for OR search) |
+| `--value <value>` | Filter value (use `*` for wildcard, e.g., `test*` for LIKE) |
+| `--columns <columns>` | Select specific columns to return (comma-separated) |
+| `--data <json>` | JSON data for add/edit operations |
+| `--file <path>` | Path to JSON file with data |
+| `--db-alias <alias>` | Database alias (default: "default") |
+| `--preview` | Show preview before executing (default: true) |
+| `--no-preview` | Skip preview and execute directly |
+| `-y, --yes` | Auto-confirm without prompting |
+| `--output <path>` | For get: save record(s) to file |
+
+## Resource Tables
+
+| Resource | Table Name |
+|----------|------------|
+| Objects | `objects` |
+| Object Specs | `object_specs` |
+| Reports | `cms_reports` |
+| Report Queries | `cms_report_queries` |
+| Report Specs | `cms_report_specs` |
+| Workflows | `bfy_workflows` |
+| Workflow Versions | `bfy_workflow_versions` |
+| Workflow Nodes | `bfy_workflow_nodes` |
+| State Machines | `bfy_state_machines` |
+| Pages | `pages` |
+| Cron Jobs | `bfy_cronjobs` |
+| Email Templates | `cms_email_templates` |
+
+## Examples
+
+### Get Records
+
+```bash
+# Get a single record by ID
+butterfly-cli record get users --id 5
+
+# Get all records from a table
+butterfly-cli record get bfy_cronjobs
+
+# Filter by column=value
+butterfly-cli record get users --column status --value "1"
+
+# OR search across multiple columns
+butterfly-cli record get users --column "name,email,title" --value "john"
+
+# Wildcard search (LIKE)
+butterfly-cli record get users --column name --value "john*"
+butterfly-cli record get users --column email --value "*@gmail.com"
+
+# Select specific columns only
+butterfly-cli record get users --columns "id,name,email"
+
+# Save results to file
+butterfly-cli record get users --column role --value "admin" --output ./admins.json
+```
+
+### Add Records
+
+```bash
+# Add a new record
+butterfly-cli record add bfy_cronjobs --data '{"name":"My Job","code":"// code"}'
+
+# Add from JSON file
+butterfly-cli record add pages --file ./new-page.json
+
+# Create an object
+butterfly-cli record add objects --data '{"name":"Products","table_name":"products"}'
+
+# Add a string field
+butterfly-cli record add object_specs --data '{"object_id":128,"name":"Title","column_name":"title","type":"string"}'
+
+# Add a dropdown field
+butterfly-cli record add object_specs --data '{"object_id":128,"name":"Status","column_name":"status","type":"from_list","val_1":"active,inactive"}'
+```
+
+### Edit Records
+
+```bash
+# Edit a record (shows preview with diff)
+butterfly-cli record edit bfy_cronjobs --id 5 --data '{"name":"Updated Name"}'
+
+# Skip confirmation with -y
+butterfly-cli record edit pages --id 1 --data '{"title":"New Title"}' -y
+```
+
+### Delete Records
+
+```bash
+# Delete a record (shows preview)
+butterfly-cli record delete bfy_cronjobs --id 5
+```
+
+### Reports
+
+> **IMPORTANT:** The `query` field in `cms_reports` is **deprecated**. Always use `cms_report_queries` for all Twig query code.
+
+```bash
+# Create a report (without query - query field is deprecated)
+butterfly-cli record add cms_reports --data '{
+  "name": "Sales Summary",
+  "alias": "sales_summary"
+}'
+# Response: SUCCESS (ID: 50)
+
+# Create a webservice report with custom_seo
+# URL will be: {BASE_URL}/{custom_seo} (no additional path segments)
+butterfly-cli record add cms_reports --data '{
+  "name": "User API",
+  "alias": "user_api",
+  "custom_seo": "api/users/list"
+}'
+# Response: SUCCESS (ID: 51)
+# Webservice URL: https://example.com/api/users/list
+
+# Add the main report query (use cms_report_queries, NOT cms_reports.query)
+butterfly-cli record add cms_report_queries --data '{
+  "cms_report_id": 50,
+  "name": "main",
+  "system_name": "main",
+  "query": "{% set records = db().table(\"orders\").where(\"created_at\", \">=\", getParameter(\"date_from\")).get() %}"
+}'
+
+# Add additional report queries with column_size for layout
+# column_size options: 1 (full), 1/2, 1/3, 2/3, 1/4, 3/4
+butterfly-cli record add cms_report_queries --data '{
+  "cms_report_id": 50,
+  "name": "totals",
+  "system_name": "totals",
+  "column_size": "1/3",
+  "query": "{% set records = db().table(\"orders\").selectRaw(\"COUNT(*) as count, SUM(total) as revenue\").get() %}"
+}'
+
+# Add a report query with JS processing (2/3 width)
+butterfly-cli record add cms_report_queries --data '{
+  "cms_report_id": 50,
+  "name": "monthly",
+  "system_name": "monthly",
+  "column_size": "2/3",
+  "query": "{% set records = db().table(\"orders\").selectRaw(\"DATE_FORMAT(created_at, \\\"%Y-%m\\\") as month, SUM(total) as revenue\").groupBy(\"month\").get() %}",
+  "js_code": "data.forEach(r => { r.formatted = \"$\" + r.revenue; }); return data;"
+}'
+
+# Add report specs (columns) - uses same types and parameters as object_specs
+butterfly-cli record add cms_report_specs --data '{"cms_report_id":50,"field_name":"order_number","title":"Order #","order_no":1}'
+butterfly-cli record add cms_report_specs --data '{"cms_report_id":50,"field_name":"total","title":"Total","order_no":2,"js_code":"return \"$\" + parseFloat(value).toFixed(2);"}'
+
+# Add report spec with field type (same as object_specs)
+butterfly-cli record add cms_report_specs --data '{"cms_report_id":50,"field_name":"calculated_field","title":"Calculated","type":"calculated","val_1":"{{ row.quantity * row.price }}"}'
+butterfly-cli record add cms_report_specs --data '{"cms_report_id":50,"field_name":"status","title":"Status","type":"from_list","val_1":"pending,completed,cancelled"}'
+```
+
+## Workflow: Get → Edit → Update
+
+```bash
+# 1. Get the record and save to file
+butterfly-cli record get bfy_cronjobs --id 5 --output ./cronjob.json
+
+# 2. Edit the JSON file locally with your editor
+
+# 3. Update the record with modified data
+butterfly-cli record edit bfy_cronjobs --id 5 --file ./cronjob.json
+```
+
+## Handling Confirmation Dialogs
+
+Some operations may require user confirmation before proceeding (e.g., when editing records with state machine transitions or validation rules). When the API response includes a confirmation request, you can programmatically confirm the action.
+
+### Detecting Confirmation Requests
+
+When a `record get` or `record edit` operation returns a response with:
+```json
+{
+  "xtra": {
+    "type": "confirm",
+    "alias": "some_action_alias",
+    "message": "Are you sure you want to proceed?"
+  }
+}
+```
+
+This indicates the operation requires confirmation.
+
+### Confirming the Action
+
+To confirm and proceed with the operation, add a parameter with the format:
+```
+confirm_message_<alias>=1
+```
+
+Where `<alias>` is the value returned by the API in `response.xtra.alias`. This alias is defined by the server and must be used exactly as returned.
+
+### Example
+
+```bash
+# Initial request returns confirmation dialog
+butterfly-cli record edit orders --id 5 --data '{"status": "cancelled"}'
+# Response: { "xtra": { "type": "confirm", "alias": "cancel_order", "message": "This will cancel the order. Continue?" } }
+
+# Confirm the action by adding the confirmation parameter
+butterfly-cli record edit orders --id 5 --data '{"status": "cancelled", "confirm_message_cancel_order": 1}'
+```
+
+### Using with --data Parameter
+
+When you need to include the confirmation in your data:
+
+```bash
+# Single confirmation
+butterfly-cli record edit TABLE --id ID --data '{"field": "value", "confirm_message_ALIAS": 1}'
+
+# Example with state machine transition
+butterfly-cli record edit invoices --id 123 --data '{"state": "void", "confirm_message_void_invoice": 1}'
+```
+
+> **AI INSTRUCTION:** When a `record` operation returns `response.xtra.type == "confirm"`, ask the user if they want to proceed. If yes, retry the operation with the additional parameter `confirm_message_<alias>: 1` included in the data payload, where `<alias>` is the exact value from `response.xtra.alias` returned by the API.
+
+## Non-Interactive Mode
+
+The record command automatically switches to non-interactive mode when:
+- Running in a non-TTY environment (subprocess, piped output, CI/CD)
+- Using `--yes` or `--no-preview` flags
+
+In non-interactive mode:
+- No Ink UI components are used (avoids "Raw mode not supported" errors)
+- Output is clean JSON (suitable for piping to `jq` or other tools)
+- Errors are written to stderr
+
+```bash
+# These automatically use non-interactive mode
+butterfly-cli record get users --no-preview
+butterfly-cli record get users -y
+butterfly-cli record get bfy_cronjobs | jq '.name'
+
+# Piping to file also triggers non-interactive mode
+butterfly-cli record get users > users.json
+```