codymaster 4.1.3 → 4.3.0

package/skills/cm-frappe-agent/commands/frappe-doctype-create.md

@@ -0,0 +1,272 @@
+---
+description: Create a new Frappe DocType with complete scaffolding including JSON definition, Python controller, JavaScript client script, and tests
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, TodoWrite
+argument-hint: <doctype_name> [module_name] [--child] [--single] [--submittable]
+---
+
+# Create Frappe DocType
+
+You are creating a new DocType in a Frappe application. Follow this systematic process to create a complete, working DocType with all necessary files.
+
+## Arguments
+
+Parse the user's input: $ARGUMENTS
+
+- **doctype_name**: Name of the DocType (e.g., "Project Task", "Customer Feedback")
+- **module_name**: (Optional) Module to create DocType in
+- **--child**: Create as child table (istable=1)
+- **--single**: Create as Single DocType (issingle=1)
+- **--submittable**: Create as submittable document (is_submittable=1)
+
+## Process
+
+### Step 1: Discover Project Structure
+
+1. Find the Frappe app in the current directory:
+   ```bash
+   find . -name "hooks.py" -path "*/apps/*" | head -5
+   ```
+
+2. Read hooks.py to understand the app structure:
+   ```bash
+   cat <app_path>/hooks.py
+   ```
+
+3. Check modules.txt for available modules:
+   ```bash
+   cat <app_path>/modules.txt
+   ```
+
+4. If module not specified, ask user which module to use
+
+### Step 2: Create Directory Structure
+
+Convert DocType name to directory name:
+- "Project Task" → "project_task"
+- Use snake_case
+
+Create the DocType directory:
+```bash
+mkdir -p <app>/<module>/doctype/<doctype_dir>
+touch <app>/<module>/doctype/<doctype_dir>/__init__.py
+```
+
+### Step 3: Ask About Fields
+
+Ask the user about the fields they want to add. Provide suggestions based on DocType name:
+
+- For "Invoice": items table, customer, amounts, dates
+- For "Task": title, description, status, assigned_to, dates
+- For "Settings": configuration fields, checkboxes
+- For child tables: item reference, qty, rate, amount
+
+Common field patterns to suggest:
+1. **Status field**: Draft → Active → Completed
+2. **Date range**: start_date, end_date
+3. **Amount fields**: qty, rate, amount, total
+4. **References**: customer, supplier, user links
+
+### Step 4: Create DocType JSON
+
+Create the JSON file with:
+
+```json
+{
+  "name": "<DocType Name>",
+  "module": "<Module Name>",
+  "doctype": "DocType",
+  "engine": "InnoDB",
+  "field_order": [],
+  "fields": [
+    // Fields based on user requirements
+  ],
+  "permissions": [
+    {
+      "role": "System Manager",
+      "read": 1,
+      "write": 1,
+      "create": 1,
+      "delete": 1
+    }
+  ],
+  "autoname": "naming_series:",
+  "naming_rule": "By \"Naming Series\" field",
+  "is_submittable": 0,
+  "istable": 0,
+  "issingle": 0,
+  "track_changes": 1,
+  "sort_field": "modified",
+  "sort_order": "DESC"
+}
+```
+
+### Step 5: Create Python Controller
+
+```python
+# <doctype>.py
+import frappe
+from frappe import _
+from frappe.model.document import Document
+
+
+class <ClassName>(Document):
+    def validate(self):
+        pass
+
+    def before_save(self):
+        pass
+
+    def after_insert(self):
+        pass
+
+    def on_update(self):
+        pass
+```
+
+Add relevant hooks based on DocType type:
+- For submittable: on_submit, on_cancel
+- For documents with calculations: validate with totals
+- For documents with dates: date validation
+
+### Step 6: Create JavaScript Client Script
+
+```javascript
+// <doctype>.js
+frappe.ui.form.on('<DocType Name>', {
+    refresh: function(frm) {
+        // Custom buttons and field toggles
+    },
+
+    validate: function(frm) {
+        // Client-side validation
+    }
+});
+```
+
+Add field handlers for:
+- Link fields that need to fetch data
+- Numeric fields that need calculations
+- Conditional field visibility
+
+### Step 7: Create Test File
+
+```python
+# test_<doctype>.py
+import frappe
+from frappe.tests.utils import FrappeTestCase
+
+
+class Test<ClassName>(FrappeTestCase):
+    def test_create_document(self):
+        doc = frappe.get_doc({
+            "doctype": "<DocType Name>",
+            # Required fields
+        })
+        doc.insert()
+        self.assertTrue(doc.name)
+
+    def test_validate(self):
+        # Test validation logic
+        pass
+```
+
+### Step 8: Update Module Files
+
+If this is a new module, update:
+- modules.txt (add module name)
+- Create module directory structure
+
+### Step 9: Migrate
+
+Remind user to run migration:
+```bash
+bench --site <sitename> migrate
+```
+
+## File Locations
+
+```
+<app_name>/
+└── <module_name>/
+    └── doctype/
+        └── <doctype_name>/
+            ├── __init__.py
+            ├── <doctype_name>.json      # DocType definition
+            ├── <doctype_name>.py        # Python controller
+            ├── <doctype_name>.js        # Client script
+            └── test_<doctype_name>.py   # Tests
+```
+
+## Field Type Quick Reference
+
+| Data | Field Type | Notes |
+|------|------------|-------|
+| Text (short) | Data | Max 140 chars |
+| Text (long) | Text | Unlimited |
+| Number | Int/Float | Use Float for decimals |
+| Money | Currency | Company currency aware |
+| Date | Date/Datetime | |
+| Yes/No | Check | Checkbox |
+| Dropdown | Select | Options separated by \n |
+| Reference | Link | options = DocType name |
+| Child items | Table | options = Child DocType |
+| File | Attach | Single file |
+| Image | Attach Image | With preview |
+
+## Common Patterns
+
+### Naming Series Field
+```json
+{
+  "fieldname": "naming_series",
+  "fieldtype": "Select",
+  "label": "Series",
+  "options": "NEW-.YYYY.-.####",
+  "default": "NEW-.YYYY.-.####",
+  "reqd": 1
+}
+```
+
+### Status Field
+```json
+{
+  "fieldname": "status",
+  "fieldtype": "Select",
+  "label": "Status",
+  "options": "\nDraft\nOpen\nClosed\nCancelled",
+  "default": "Draft",
+  "in_list_view": 1,
+  "in_standard_filter": 1
+}
+```
+
+### Amount Calculation (in child table)
+```json
+[
+  {"fieldname": "item", "fieldtype": "Link", "options": "Item", "in_list_view": 1},
+  {"fieldname": "qty", "fieldtype": "Float", "in_list_view": 1},
+  {"fieldname": "rate", "fieldtype": "Currency", "in_list_view": 1},
+  {"fieldname": "amount", "fieldtype": "Currency", "in_list_view": 1, "read_only": 1}
+]
+```
+
+## Output
+
+After completion, provide:
+
+1. Summary of files created
+2. List of fields added
+3. Next steps:
+   - Run `bench --site <site> migrate`
+   - Customize form layout in Desk
+   - Add more fields as needed
+   - Write controller logic
+   - Create tests
+
+## Important Notes
+
+- Use the doctype-architect agent for complex data modeling
+- Use the frappe-backend agent for controller logic
+- Use the frappe-frontend agent for client scripts
+- Always follow Frappe naming conventions
+- Test the migration before proceeding

package/skills/cm-frappe-agent/commands/frappe-doctype-field.md

@@ -0,0 +1,310 @@
+---
+description: Add, modify, or remove fields from an existing Frappe DocType with automatic JSON updates
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <doctype_name> <action> [field_details]
+---
+
+# Manage DocType Fields
+
+Add, modify, or remove fields from an existing Frappe DocType. This command helps you update the DocType JSON file correctly.
+
+## Arguments
+
+Parse the user's input: $ARGUMENTS
+
+- **doctype_name**: Name of the existing DocType
+- **action**: add, modify, remove, list
+- **field_details**: Field specifications (for add/modify)
+
+## Actions
+
+### List Fields
+Show current fields in the DocType:
+```
+/doctype-field "Sales Order" list
+```
+
+### Add Field
+Add a new field to the DocType:
+```
+/doctype-field "Sales Order" add customer_reference Data
+/doctype-field "Sales Order" add priority Select "Low\nMedium\nHigh"
+/doctype-field "Sales Order" add items Table "Sales Order Item"
+```
+
+### Modify Field
+Modify an existing field:
+```
+/doctype-field "Sales Order" modify customer_name label "Client Name"
+/doctype-field "Sales Order" modify status options "Draft\nActive\nClosed"
+```
+
+### Remove Field
+Remove a field (with confirmation):
+```
+/doctype-field "Sales Order" remove customer_reference
+```
+
+## Process
+
+### Step 1: Find DocType JSON
+
+```bash
+# Search for the DocType JSON file
+find . -name "*.json" -path "*/doctype/*" | xargs grep -l '"name": "<DocType Name>"'
+```
+
+Or if you know the app:
+```bash
+# Convert DocType name to path
+# "Sales Order" -> sales_order
+cat apps/<app>/<module>/doctype/<doctype_dir>/<doctype_dir>.json
+```
+
+### Step 2: Read Current Structure
+
+Read and parse the DocType JSON to understand:
+- Current fields and their order
+- Field types and options
+- Existing sections and columns
+
+### Step 3: Validate Field Operation
+
+For **add**:
+- Check field name doesn't exist
+- Validate field type
+- Suggest appropriate position
+
+For **modify**:
+- Verify field exists
+- Validate new property values
+
+For **remove**:
+- Check field exists
+- Warn about dependencies
+- Check if field is used in filters, reports, or code
+
+### Step 4: Apply Changes
+
+Modify the JSON file maintaining proper structure:
+
+#### Adding a Field
+
+Position options:
+- After a specific field
+- In a specific section
+- At the end
+
+```json
+{
+  "fieldname": "new_field",
+  "fieldtype": "Data",
+  "label": "New Field",
+  "insert_after": "existing_field"
+}
+```
+
+#### Modifying a Field
+
+Update only specified properties:
+```json
+{
+  "fieldname": "existing_field",
+  "label": "New Label",
+  "reqd": 1
+}
+```
+
+#### Removing a Field
+
+Remove from fields array and field_order.
+
+### Step 5: Update Related Files
+
+After JSON changes:
+
+1. **Client Script** - Add/remove field handlers
+2. **Controller** - Update validation/calculations
+3. **Migration Required** - Remind to run migrate
+
+## Field Type Reference
+
+### Basic Types
+| Type | Usage | Options |
+|------|-------|---------|
+| Data | Short text | - |
+| Text | Long text | - |
+| Select | Dropdown | Options separated by \n |
+| Check | Checkbox | - |
+| Int | Integer | - |
+| Float | Decimal | - |
+| Currency | Money | - |
+| Date | Date only | - |
+| Datetime | Date + time | - |
+
+### Link Types
+| Type | Usage | Options |
+|------|-------|---------|
+| Link | Reference | DocType name |
+| Dynamic Link | Polymorphic | Field containing DocType |
+| Table | Child table | Child DocType name |
+| Table MultiSelect | Many-to-many | Link DocType |
+
+### Special Types
+| Type | Usage |
+|------|-------|
+| Attach | File upload |
+| Attach Image | Image upload |
+| Section Break | Section divider |
+| Column Break | Column divider |
+| Tab Break | Tab navigation |
+| HTML | Static content |
+
+## Field Properties
+
+### Display Properties
+```json
+{
+  "label": "Field Label",
+  "description": "Help text shown below field",
+  "bold": 1,
+  "hidden": 0,
+  "read_only": 0,
+  "print_hide": 0
+}
+```
+
+### Data Properties
+```json
+{
+  "reqd": 1,
+  "unique": 0,
+  "default": "Default Value",
+  "options": "Option1\nOption2",
+  "allow_on_submit": 0,
+  "no_copy": 0,
+  "translatable": 0
+}
+```
+
+### Display Control
+```json
+{
+  "in_list_view": 1,
+  "in_standard_filter": 1,
+  "in_global_search": 1,
+  "in_preview": 1,
+  "allow_in_quick_entry": 1
+}
+```
+
+### Conditional Properties
+```json
+{
+  "depends_on": "eval:doc.enable_feature",
+  "mandatory_depends_on": "eval:doc.status=='Active'",
+  "read_only_depends_on": "eval:doc.docstatus==1"
+}
+```
+
+### Link Properties
+```json
+{
+  "options": "Customer",
+  "fetch_from": "customer.customer_name",
+  "fetch_if_empty": 1
+}
+```
+
+## Common Field Patterns
+
+### Status Field
+```json
+{
+  "fieldname": "status",
+  "fieldtype": "Select",
+  "label": "Status",
+  "options": "\nDraft\nPending\nApproved\nRejected",
+  "default": "Draft",
+  "in_list_view": 1,
+  "in_standard_filter": 1,
+  "read_only": 1
+}
+```
+
+### Customer with Fetch
+```json
+[
+  {
+    "fieldname": "customer",
+    "fieldtype": "Link",
+    "label": "Customer",
+    "options": "Customer",
+    "reqd": 1
+  },
+  {
+    "fieldname": "customer_name",
+    "fieldtype": "Data",
+    "label": "Customer Name",
+    "fetch_from": "customer.customer_name",
+    "read_only": 1
+  }
+]
+```
+
+### Date Range
+```json
+[
+  {
+    "fieldname": "from_date",
+    "fieldtype": "Date",
+    "label": "From Date",
+    "reqd": 1
+  },
+  {
+    "fieldname": "to_date",
+    "fieldtype": "Date",
+    "label": "To Date",
+    "reqd": 1
+  }
+]
+```
+
+### Amount Calculation
+```json
+[
+  {"fieldname": "qty", "fieldtype": "Float", "label": "Qty"},
+  {"fieldname": "rate", "fieldtype": "Currency", "label": "Rate"},
+  {"fieldname": "amount", "fieldtype": "Currency", "label": "Amount", "read_only": 1}
+]
+```
+
+## Post-Change Steps
+
+After modifying the DocType JSON:
+
+1. **Run Migration**
+   ```bash
+   bench --site <sitename> migrate
+   ```
+
+2. **Clear Cache** (if schema unchanged)
+   ```bash
+   bench --site <sitename> clear-cache
+   ```
+
+3. **Update Controller** (if logic needed)
+   - Add validation for new fields
+   - Update calculations
+
+4. **Update Client Script** (if UI logic needed)
+   - Add field change handlers
+   - Update visibility conditions
+
+## Output
+
+Provide:
+1. Summary of changes made
+2. Updated field list
+3. Migration command to run
+4. Any additional code changes needed