@rglabs/butterfly 2.0.1

package/CLAUDE.md

@@ -0,0 +1,201 @@
+# 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.
+
+## 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/README.md

@@ -0,0 +1,371 @@
+# 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
+butterfly download -t webservices
+
+# 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
+```
+
+---
+
+### `butterfly diff`
+
+Compare local resources with remote server and apply changes interactively.
+
+```bash
+# Compare all objects
+butterfly diff -t objects
+
+# Compare specific object
+butterfly diff -t objects -n users
+
+# Compare reports
+butterfly diff -t reports -n my_report
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `-t, --type <type>` | Resource type to compare (objects, reports) |
+| `-n, --name <name>` | Specific resource name to compare |
+| `-o, --output <path>` | Base path (default: `./butterfly-resources`) |
+
+---
+
+### `butterfly record`
+
+Perform CRUD operations on any Butterfly table.
+
+```bash
+# Get a record by ID
+butterfly record get users --id 123
+
+# Get records by column filter
+butterfly record get users --column email --value "john@example.com"
+
+# Wildcard search
+butterfly record get users --column name --value "john*"
+
+# Add a new record
+butterfly record add users --data '{"name": "John", "email": "john@example.com"}'
+
+# Edit a record
+butterfly record edit users --id 123 --data '{"name": "Jane"}'
+
+# Delete a record (with confirmation)
+butterfly record delete users --id 123
+
+# Skip preview and auto-confirm
+butterfly record edit users --id 123 --data '{"status": "active"}' --no-preview -y
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--id <id>` | Record ID |
+| `--column <column>` | Filter column(s) for get |
+| `--value <value>` | Filter value (use `*` for wildcard) |
+| `--columns <cols>` | Select specific columns to return |
+| `--data <json>` | JSON data for the operation |
+| `--file <path>` | Path to JSON file with data |
+| `--db-alias <alias>` | Database alias (default: `default`) |
+| `--no-preview` | Skip preview |
+| `-y, --yes` | Auto-confirm without prompting |
+
+---
+
+### `butterfly code`
+
+Execute Twig code on the server.
+
+```bash
+# Execute inline code
+butterfly code -c "{{ db().table('users').count() }}"
+
+# Execute from file
+butterfly code -f query.bfy
+
+# Get only variables
+butterfly code -c "{% set users = db().table('users').get() %}" --vars
+
+# Get raw output
+butterfly code -c "{{ 'Hello World' }}" --output-only --raw
+```
+
+**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 |
+| `--vars` | Output only the vars object |
+| `--output-only` | Output only the output field |
+| `--raw` | Output raw string (no JSON formatting) |
+
+---
+
+### `butterfly layout`
+
+Update object page layout (tab and field ordering).
+
+```bash
+# Update layout from file
+butterfly layout -f layout.json
+
+# Update layout inline
+butterfly layout -d '{"object_id": 123, "tabs": [...]}'
+```
+
+---
+
+### `butterfly translate`
+
+Manage translations for multi-language support.
+
+```bash
+# List languages with translation stats
+butterfly translate languages
+
+# Get untranslated texts for a language
+butterfly translate get-untranslated --lang tr
+
+# Add a single translation
+butterfly translate add --lang tr --source "Welcome" --text "Hoş geldiniz"
+
+# Bulk import from CSV file (tab-delimited)
+butterfly translate bulk --lang tr --file translations.csv
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--lang <iso_code>` | Language ISO code (e.g., tr, de, en) |
+| `--source <text>` | Source text to translate |
+| `--text <translation>` | Translated text |
+| `-f, --file <path>` | CSV file for bulk operations |
+| `--format <format>` | Output format: json or table |
+| `--limit <count>` | Limit number of results |
+
+## 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/
+└── webservices/
+    └── [custom_seo]/
+        ├── webservice.json
+        └── queries/
+```
+
+## 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/dist/commands/add.d.ts

@@ -0,0 +1,23 @@
+import { ButterflyAPI } from '../utils/api.js';
+interface AddCommandProps {
+    api: ButterflyAPI;
+    options: {
+        type: string;
+        workflow?: string;
+        version?: string;
+        title?: string;
+        nodeType?: string;
+        nodeGroup?: string;
+        systemName?: string;
+        connectFrom?: string;
+        connectTo?: string;
+        from?: string;
+        fromOutput?: string;
+        to?: string;
+        toInput?: string;
+        output?: string;
+    };
+}
+export default function addCommand(options: AddCommandProps['options']): Promise<void>;
+export {};
+//# sourceMappingURL=add.d.ts.map