@rglabs/butterfly 2.0.1

package/docs/webservices.md

@@ -0,0 +1,159 @@
+# Webservices Guide
+
+Webservices are API endpoints created using the `webservices` table. They provide a dedicated way to build REST APIs and webhooks.
+
+> **Note:** Use the `webservices` table for creating API endpoints. Do NOT confuse this with `cms_reports` - they are separate tables for different purposes.
+
+## Table Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `custom_seo` | string | URL path for the webservice endpoint |
+| `method` | from_list | HTTP method: `GET`, `POST`, `ALL`, etc. |
+| `page_code` | code | Twig code that handles the request |
+
+## URL Format
+
+```
+{BASE_URL}/{custom_seo}
+```
+
+| `custom_seo` value | Resulting URL |
+|--------------------|---------------|
+| `api/users/list` | `https://example.com/api/users/list` |
+| `webhook/process` | `https://example.com/webhook/process` |
+| `hello-world` | `https://example.com/hello-world` |
+
+> **Important:** The `custom_seo` field maps **directly** to the URL path. No prefixes are added automatically.
+
+> **AI INSTRUCTION:** Do NOT invent or add any URL prefixes (such as `/ws/`, `/api/`, `/v1/`, etc.) to the `custom_seo` value unless the user explicitly requests it. Use exactly what the user specifies, or choose a simple descriptive path like `webhook/github` or `users/list`.
+
+## Creating a Webservice
+
+### Basic Example
+
+```bash
+butterfly-cli record add webservices --data '{
+  "custom_seo": "api/hello",
+  "method": "GET",
+  "page_code": "{{ {\"message\": \"Hello World\"}|json_encode|raw }}"
+}'
+```
+
+### JSON API Response
+
+```bash
+butterfly-cli record add webservices --data '{
+  "custom_seo": "api/users/list",
+  "method": "GET",
+  "page_code": "{% set users = db(\"default\", false).table(\"users\").select(\"id\", \"name\", \"email\").get() %}{{ users|json_encode|raw }}"
+}'
+```
+
+### POST Endpoint with Parameters
+
+```bash
+butterfly-cli record add webservices --data '{
+  "custom_seo": "api/contact/submit",
+  "method": "POST",
+  "page_code": "{% set response = crud(\"default\", false).table(\"contacts\").insert({\"name\": getParameter(\"name\"), \"email\": getParameter(\"email\"), \"message\": getParameter(\"message\")}) %}{{ response|json_encode|raw }}"
+}'
+```
+
+## Page Code Examples
+
+### Read Data (No Auth)
+
+For webservices that don't require authentication, use `db('default', false)`:
+
+```twig
+{% set records = db('default', false)
+    .table('products')
+    .where('is_active', 1)
+    .get()
+%}
+{{ records|json_encode|raw }}
+```
+
+### Write Data (No Auth)
+
+For CRUD operations without authentication, use `crud('default', false)`:
+
+```twig
+{% set response = crud('default', false)
+    .table('submissions')
+    .insert({
+      "name": getParameter('name'),
+      "email": getParameter('email')
+    })
+%}
+{{ response|json_encode|raw }}
+```
+
+### Get Request Parameters
+
+```twig
+{# GET or POST parameters #}
+{% set userId = getParameter('user_id') %}
+{% set action = getParameter('action') %}
+
+{# With default value #}
+{% set page = getParameter('page') ?: 1 %}
+```
+
+### Error Handling
+
+```twig
+{% set id = getParameter('id') %}
+
+{% if not id %}
+    {{ {"error": "ID is required"}|json_encode|raw }}
+{% else %}
+    {% set record = db('default', false).table('items').where('id', id).first() %}
+    {% if record %}
+        {{ record|json_encode|raw }}
+    {% else %}
+        {{ {"error": "Record not found"}|json_encode|raw }}
+    {% endif %}
+{% endif %}
+```
+
+### Set Response Headers
+
+```twig
+{% do header('Content-Type: application/json') %}
+{% do header('Access-Control-Allow-Origin: *') %}
+{{ data|json_encode|raw }}
+```
+
+## File Structure
+
+Downloaded webservices are stored in:
+
+```
+butterfly-resources/
+└── webservices/
+    └── [custom_seo]/
+        ├── webservice.json    # Webservice definition
+        └── page_code.bfy      # Twig code (if exists)
+```
+
+## Webhook Example
+
+Create a webhook endpoint for external services:
+
+```bash
+butterfly-cli record add webservices --data '{
+  "custom_seo": "webhook/github",
+  "method": "POST",
+  "page_code": "{% set payload = _POST %}{% set response = crud(\"default\", false).table(\"github_events\").insert({\"event_type\": payload.action, \"payload\": payload|json_encode, \"created_at\": \"now\"|date(\"Y-m-d H:i:s\")}) %}{{ {\"success\": response.success}|json_encode|raw }}"
+}'
+```
+
+## Best Practices
+
+1. **Always use `db('default', false)` and `crud('default', false)`** for public APIs to disable permission checks
+2. **Validate input parameters** before processing
+3. **Return proper JSON responses** with appropriate status information
+4. **Set Content-Type header** for JSON responses
+5. **Handle errors gracefully** and return meaningful error messages

package/docs/workspaces.md

@@ -0,0 +1,176 @@
+# Workspaces (bfy_workspaces)
+
+Workspaces provide multi-tenant data isolation in Butterfly. Objects can be scoped to workspaces at two levels.
+
+## Workspace Scope Modes
+
+| `is_workspace_specific` | Scope | `bfy_workspace_id` Location | Use Case |
+|-------------------------|-------|----------------------------|----------|
+| `0` (default) | Object-level | `objects` table | Object visible only in one workspace |
+| `1` | Record-level | Data table itself | Records filterable by workspace |
+
+## Object-Level Scope (`is_workspace_specific: 0`)
+
+The **entire object** belongs to a single workspace. The `bfy_workspace_id` is stored on the `objects` table.
+
+- Object appears in admin menu only for users in that workspace
+- All records of this object are implicitly in that workspace
+- Data table does NOT have `bfy_workspace_id` column
+
+### Assign Object to Workspace
+
+```bash
+butterfly-cli record edit objects --id <object_id> --data '{"bfy_workspace_id": <workspace_id>}'
+```
+
+### Query Objects by Workspace
+
+```twig
+{% set objects = db().table('objects').where('bfy_workspace_id', <workspace_id>).get() %}
+```
+
+## Record-Level Scope (`is_workspace_specific: 1`)
+
+**Each record** can belong to a different workspace. The `bfy_workspace_id` column exists on the data table itself.
+
+- Object visible in all workspaces (or controlled separately)
+- Records filtered by `bfy_workspace_id` automatically in admin
+- Useful for shared objects with workspace-specific data
+
+### Requirements
+
+The data table must have a `bfy_workspace_id` column:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `bfy_workspace_id` | INT | Foreign key to `bfy_workspaces.id` |
+
+### Enable Record-Level Tracking
+
+```bash
+butterfly-cli record edit objects --id <object_id> --data '{"is_workspace_specific": 1}'
+```
+
+### Add Record with Workspace
+
+```bash
+butterfly-cli record add <table_name> --data '{"bfy_workspace_id": <workspace_id>, "field": "value"}'
+```
+
+### Update Record Workspace
+
+```bash
+butterfly-cli record edit <table_name> --id <record_id> --data '{"bfy_workspace_id": <workspace_id>}'
+```
+
+### Query Records by Workspace
+
+```twig
+{% set records = db().table('<table_name>').where('bfy_workspace_id', <workspace_id>).get() %}
+```
+
+## Detect Workspace Mode
+
+```bash
+butterfly-cli record get objects --column table_name --value <table_name>
+```
+
+Check `is_workspace_specific` in response:
+- `0` or `null` = Object-level scope
+- `1` = Record-level scope
+
+## Decision Guide
+
+| Scenario | Mode | `is_workspace_specific` |
+|----------|------|------------------------|
+| Object only exists in one workspace | Object-level | `0` |
+| Object shared, records separated by workspace | Record-level | `1` |
+| Core system object (all workspaces) | None | `bfy_workspace_id: null` |
+
+## Twig Helpers
+
+```twig
+{# Get current user's workspace #}
+{% set workspace_id = currentUser('bfy_workspace_id') %}
+
+{# Filter records by current workspace #}
+{% set records = db().table('orders').where('bfy_workspace_id', currentUser('bfy_workspace_id')).get() %}
+```
+
+## Migrating Objects to a New Workspace
+
+When moving an object to a different workspace, several related resources must be updated.
+
+### Migration Checklist
+
+| Resource | Table | Action |
+|----------|-------|--------|
+| Object itself | `objects` | Update `bfy_workspace_id` |
+| Admin menus | `cms_admin_menus` | Update `bfy_workspace_id` |
+| State machines | `bfy_state_machines` | Update `bfy_workspace_id` |
+
+### Step 1: Update the Object
+
+```bash
+butterfly-cli record edit objects --id <object_id> --data '{"bfy_workspace_id": <new_workspace_id>}'
+```
+
+### Step 2: Update Admin Menus
+
+Objects have associated menu entries that must also be migrated:
+
+```bash
+# Get the object to find menu IDs
+butterfly-cli record get objects --id <object_id>
+
+# Update menu entries (main_menu_id, sub_menu_id, menu_id from object)
+butterfly-cli record edit cms_admin_menus --id <main_menu_id> --data '{"bfy_workspace_id": <new_workspace_id>}'
+butterfly-cli record edit cms_admin_menus --id <sub_menu_id> --data '{"bfy_workspace_id": <new_workspace_id>}'
+butterfly-cli record edit cms_admin_menus --id <menu_id> --data '{"bfy_workspace_id": <new_workspace_id>}'
+```
+
+### Step 3: Find and Update Related State Machines
+
+Objects with state management have `state` field type specs linked to state machines:
+
+```bash
+# Find state field specs for the object
+butterfly-cli record get object_specs --column objects_id --value <object_id>
+```
+
+Look for specs with `type: "state"`. The `val_1` parameter contains the state machine ID.
+
+```bash
+# Update the state machine workspace
+butterfly-cli record edit bfy_state_machines --id <state_machine_id> --data '{"bfy_workspace_id": <new_workspace_id>}'
+```
+
+### Step 4: Check for Non-Trivial Dependencies
+
+Before completing migration, verify these potential dependencies:
+
+| Dependency | How to Check | Action Required |
+|------------|--------------|-----------------|
+| Reports using this object | Check `cms_reports` with queries referencing the table | May need workspace update |
+| Workflows referencing the object | Check `bfy_workflows` | May need workspace update |
+| Other objects with relations | Check `object_specs` with `from_list` pointing to this table | User decision required |
+| Cronjobs processing this object | Check `bfy_cronjobs` | May need workspace update |
+
+> **AI INSTRUCTION:** When migrating objects, always ask the user about non-trivial dependencies like reports, workflows, and related objects before proceeding. These may need to stay in the original workspace or be migrated together.
+
+### Migration Query Helper
+
+To find all state machines linked to an object:
+
+```twig
+{% set state_specs = db()
+    .table('object_specs')
+    .where('objects_id', <object_id>)
+    .where('type', 'state')
+    .get()
+%}
+
+{% for spec in state_specs %}
+  State Machine ID: {{ spec.val_1 }}
+{% endfor %}
+```

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@rglabs/butterfly",
+  "version": "2.0.1",
+  "description": "CLI tool to download resources from the Butterfly platform",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "butterfly-cli": "./dist/index.js",
+    "butterfly": "./dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "lint": "eslint src/**/*.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node -e \"console.log('Butterfly CLI installed successfully!')\""
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "butterfly",
+    "cli",
+    "npx"
+  ],
+  "author": "",
+  "license": "ISC",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "@types/react": "^19.1.8",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
+    "eslint": "^10.0.1",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@types/chokidar": "^2.1.7",
+    "axios": "^1.10.0",
+    "axios-cookiejar-support": "^6.0.4",
+    "chokidar": "^4.0.3",
+    "commander": "^14.0.0",
+    "dotenv": "^17.2.0",
+    "ink": "^6.0.1",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^19.1.0",
+    "tough-cookie": "^5.1.2",
+    "yaml": "^2.8.1"
+  },
+  "overrides": {
+    "minimatch": "^10.2.1"
+  }
+}