codymaster 4.5.4 → 4.8.0

package/skills/cm-frappe-agent/resources/common_pitfalls.md

@@ -1,266 +0,0 @@
-# Common Frappe Pitfalls & Solutions
-
-Hard-won lessons from production Frappe apps.
-
-## 1. Forgetting `frappe.db.commit()` After Bulk Operations
-
-**Problem:** Batch task creates 100 records but none appear in DB.
-**Cause:** Frappe's auto-commit only works for single-request lifecycle.
-**Fix:** Always add `frappe.db.commit()` at the end of scheduler tasks and bulk API calls.
-
-```python
-# ✅ Correct
-def run_monthly():
-    for emp in employees:
-        frappe.get_doc({...}).insert(ignore_permissions=True)
-    frappe.db.commit()  # Don't forget!
-
-# ❌ Wrong — records may never be committed
-def run_monthly():
-    for emp in employees:
-        frappe.get_doc({...}).insert(ignore_permissions=True)
-```
-
-## 2. Querying Non-Submitted Documents
-
-**Problem:** Aggregation includes draft and cancelled records.
-**Fix:** Always filter by `docstatus = 1` for submitted records.
-
-```python
-# ✅ Correct
-frappe.db.sql("""
-    SELECT SUM(points) FROM `tabViolation`
-    WHERE employee = %s AND docstatus = 1
-""", employee)
-
-# ❌ Wrong — includes drafts and cancelled
-frappe.db.sql("""
-    SELECT SUM(points) FROM `tabViolation`
-    WHERE employee = %s
-""", employee)
-```
-
-## 3. NULL SUM Results
-
-**Problem:** `SUM()` returns NULL when no rows match, causing TypeError.
-**Fix:** Use `COALESCE(SUM(...), 0)`.
-
-```python
-# ✅ Correct
-result = frappe.db.sql("""
-    SELECT COALESCE(SUM(points), 0) AS total FROM `tabBonus`
-    WHERE employee = %(emp)s AND docstatus = 1
-""", {"emp": employee}, as_dict=True)
-total = result[0].total  # Always a number
-
-# ❌ Wrong — total could be None
-result = frappe.db.sql("""SELECT SUM(points) AS total ...""")
-total = result[0].total  # Could be None!
-```
-
-## 4. Non-Idempotent Install/Migrate Hooks
-
-**Problem:** `bench migrate` crashes because role/field already exists.
-**Fix:** Always check existence before creating.
-
-```python
-# ✅ Correct
-if not frappe.db.exists("Role", "My Role"):
-    frappe.get_doc({"doctype": "Role", "role_name": "My Role"}).insert()
-
-# ❌ Wrong — crashes on second migrate
-frappe.get_doc({"doctype": "Role", "role_name": "My Role"}).insert()
-```
-
-## 5. Modifying Fields in on_submit Without db_update
-
-**Problem:** Setting fields in `on_submit()` but changes don't persist.
-**Cause:** By on_submit time, the doc is already saved.
-**Fix:** Call `self.db_update()` after modifying fields.
-
-```python
-# ✅ Correct
-def on_submit(self):
-    self.confirmed_by = frappe.session.user
-    self.confirmed_at = now()
-    self.db_update()  # Persist the changes!
-
-# ❌ Wrong — changes are lost
-def on_submit(self):
-    self.confirmed_by = frappe.session.user
-    # Forgot db_update!
-```
-
-## 6. Business Logic in DocType Controllers
-
-**Problem:** Complex calculations in `.py` controller = untestable.
-**Fix:** Put logic in `engines/`, call from controller.
-
-```python
-# ✅ Correct — controller delegates to engine
-class MyDoc(Document):
-    def on_submit(self):
-        from my_app.engines.engine import process_submission
-        process_submission(self)
-
-# ❌ Wrong — 200 lines of business logic in controller
-class MyDoc(Document):
-    def on_submit(self):
-        # 200 lines of complex calculations here...
-```
-
-## 7. Hardcoded Company/Branch References
-
-**Problem:** App only works for one company.
-**Fix:** Always use Link fields and dynamic lookups.
-
-```python
-# ✅ Correct
-company = frappe.db.get_value("Employee", employee, "company")
-config = get_config(company=company)
-
-# ❌ Wrong
-config = get_config(company="Boxme Vietnam")
-```
-
-## 8. Missing Permission Checks in APIs
-
-**Problem:** Any logged-in user can call your API.
-**Fix:** Always check permissions first.
-
-```python
-# ✅ Correct
-@frappe.whitelist()
-def my_api(employee):
-    if not frappe.has_permission("My DocType", "write"):
-        frappe.throw(_("Permission denied"), frappe.PermissionError)
-    # ... proceed
-
-# ❌ Wrong — no permission check
-@frappe.whitelist()
-def my_api(employee):
-    # Anyone can call this!
-```
-
-## 9. Forgetting to Build After JS Changes
-
-**Problem:** JS changes don't appear in browser.
-**Fix:** Run `bench build --app my_app` after any JS/CSS change.
-
-```bash
-# After changing any .js or .css file:
-bench build --app my_app
-
-# Or for development with auto-rebuild:
-bench --site mysite clear-cache
-```
-
-## 10. SQL Injection via String Formatting
-
-**Problem:** User input injected directly into SQL.
-**Fix:** Always use parameterized queries.
-
-```python
-# ✅ Correct — parameterized
-frappe.db.sql("""
-    SELECT * FROM `tabEmployee` WHERE name = %(emp)s
-""", {"emp": employee}, as_dict=True)
-
-# ❌ Wrong — SQL injection risk
-frappe.db.sql(f"SELECT * FROM `tabEmployee` WHERE name = '{employee}'")
-```
-
-## 11. Workflow State Records Not Created
-
-**Problem:** Workflow fails because Workflow State records don't exist.
-**Fix:** Create all workflow states in `after_install` / `after_migrate`.
-
-## 12. Custom Fields Missing Module Property
-
-**Problem:** `bench export-fixtures` doesn't pick up custom fields.
-**Fix:** Always set `"module": "My App"` in custom field definitions.
-
-## 12b. Non-ASCII/Accented Characters in Schema (Names/Fieldnames)
-
-**Problem:** Creating DocTypes or fields with non-ASCII characters (e.g., Vietnamese `custom_tên_vi_phạm`) causes cryptic Frappe Builder and MariaDB SQL parsing errors, specifically breaking Frappe Insights and complex `apply_user_permissions` queries.
-**Fix:** **ALWAYS** use strict English for DocType `name` (Title Case) and `fieldname` (snake_case). Use the `label` property or Frappe Translation system for localized display in the UI. **NEVER** use non-ASCII characters in schema definitions.
-
----
-
-## Remote API & Operations Pitfalls
-
-## 13. Using `set_value()` in Web Form Client Scripts
-
-**Problem:** WebForm shows error or silently fails.
-**Cause:** WebForm extends `FieldGroup`, NOT `Form`. It uses `set_values()` (plural).
-**Fix:** Always use `frappe.web_form.set_values({...})`.
-
-```javascript
-// ✅ Correct
-frappe.ready(function() {
-    frappe.web_form.set_values({ date: frappe.datetime.get_today() });
-});
-
-// ❌ Wrong — set_value doesn't exist on WebForm
-frappe.web_form.set_value('date', frappe.datetime.get_today());
-```
-
-## 14. Web Form Code Outside `frappe.ready()`
-
-**Problem:** Code runs before form is loaded, fields are undefined.
-**Fix:** Always wrap Web Form client script code in `frappe.ready()`.
-
-```javascript
-// ❌ Wrong — form may not be loaded yet
-frappe.web_form.set_values({ field: 'value' });
-
-// ✅ Correct
-frappe.ready(function() {
-    frappe.web_form.set_values({ field: 'value' });
-});
-```
-
-## 15. Exposing API Keys in Output or Logs
-
-**Problem:** API keys leaked in console output, error logs, or AI responses.
-**Fix:** Always use environment variables, never hardcode credentials.
-
-```bash
-# ✅ Correct — use .env file
-source .env
-curl -sS "$FRAPPE_SITE/api/resource/Employee" \
-  -H "Authorization: token $FRAPPE_API_KEY:$FRAPPE_API_SECRET"
-
-# ❌ Wrong — hardcoded credentials
-curl -sS "https://mysite.com/api/resource/Employee" \
-  -H "Authorization: token abc123:xyz789"
-```
-
-## 16. Using `frappe.logger` Instead of `frappe.log_error`
-
-**Problem:** Log entries disappear, not visible in Error Log DocType.
-**Fix:** ALWAYS use `frappe.log_error()` for persistent logging.
-
-```python
-# ✅ Correct — visible in Error Log
-frappe.log_error(title="Debug", message=f"Value: {value}")
-
-# ❌ Wrong — logs to file only, easy to miss
-logger = frappe.logger("myapp")
-logger.info(f"Value: {value}")
-```
-
-## 17. Using `ignore_permissions=True` as a Bug Fix
-
-**Problem:** Permission error → developer bypasses permissions instead of fixing them.
-**Fix:** Fix the actual permission (add role, DocPerm, User Permission). Only use `ignore_permissions=True` for system operations (scheduler tasks, install hooks).
-
-```python
-# ✅ Correct — fix the permission
-# Add "My Role" to DocPerm for "My DocType" with read/write
-# Then users with "My Role" can access naturally
-
-# ❌ Wrong — bypassing permissions hides real issues
-doc = frappe.get_doc("My DocType", name)
-doc.save(ignore_permissions=True)  # DON'T do this to "fix" permission errors
-```

package/skills/cm-frappe-agent/resources/doctype-registry.md

@@ -1,158 +0,0 @@
-# DocType Registry
-
-> Reference for discovering and exploring DocTypes on Frappe/ERPNext sites.
-
----
-
-## How to Generate a Site-Specific Registry
-
-### Via bench console
-```python
-bench --site <sitename> console
-
-# List all DocTypes grouped by module
-import json
-from collections import defaultdict
-
-doctypes = frappe.get_all("DocType", fields=["name", "module"], limit_page_length=0)
-by_module = defaultdict(list)
-for dt in doctypes:
-    by_module[dt.module].append(dt.name)
-
-for module in sorted(by_module.keys()):
-    names = sorted(by_module[module])
-    print(f"\n## {module} ({len(names)})")
-    print(", ".join(names))
-```
-
-### Via REST API (remote sites)
-```bash
-curl -sS "https://{site}/api/method/frappe.client.get_list" \
-  -H "Authorization: token {key}:{secret}" \
-  -H "Content-Type: application/json" \
-  -d '{"doctype":"DocType","fields":["name","module"],"limit_page_length":0}' \
-  | jq '[.message[] | {name, module}] | group_by(.module) | map({module: .[0].module, count: length, doctypes: [.[].name]})'
-```
-
----
-
-## Core Frappe Modules (Standard)
-
-These modules exist on every Frappe site:
-
-| Module | Typical DocTypes | Purpose |
-|--------|-----------------|---------|
-| **Core** | DocType, User, Role, File, Report, Page | Framework foundation |
-| **Custom** | Custom Field, Client Script, Property Setter | Customization layer |
-| **Desk** | ToDo, Dashboard, Kanban Board, Workspace | User interface |
-| **Email** | Email Account, Notification, Email Template | Email system |
-| **Integrations** | Webhook, OAuth Client, Connected App | Third-party integrations |
-| **Printing** | Print Format, Letter Head | Print templates |
-| **Website** | Web Page, Web Form, Blog Post | Website/portal |
-| **Workflow** | Workflow, Workflow State, Workflow Action | Document workflows |
-| **Automation** | Assignment Rule, Auto Repeat | Automation rules |
-| **Contacts** | Address, Contact | Contact management |
-| **Geo** | Country, Currency | Geographic data |
-
----
-
-## ERPNext Modules (if installed)
-
-| Module | Key DocTypes | Purpose |
-|--------|-------------|---------|
-| **Accounts** | Sales Invoice, Purchase Invoice, Journal Entry, Payment Entry | Accounting |
-| **Selling** | Customer, Sales Order, Quotation | Sales management |
-| **Buying** | Supplier, Purchase Order, Request for Quotation | Procurement |
-| **Stock** | Item, Warehouse, Stock Entry, Delivery Note | Inventory |
-| **HR** | Employee, Leave Application, Attendance, Expense Claim | Human resources |
-| **Payroll** | Salary Slip, Salary Structure, Payroll Entry | Payroll processing |
-| **Manufacturing** | BOM, Work Order, Job Card | Manufacturing |
-| **Projects** | Project, Task, Timesheet | Project management |
-| **Assets** | Asset, Asset Movement, Depreciation Schedule | Fixed assets |
-| **CRM** | Lead, Opportunity, Campaign | Customer relationship |
-| **Support** | Issue, Service Level Agreement | Customer support |
-| **Setup** | Company, Department, Designation, Employee | Organization setup |
-
----
-
-## Quick DocType Discovery Commands
-
-### Find DocTypes by keyword
-```python
-# In bench console
-frappe.get_all("DocType",
-    filters={"name": ["like", "%Invoice%"]},
-    fields=["name", "module", "issingle"],
-    limit_page_length=0
-)
-```
-
-### Find custom app DocTypes
-```python
-frappe.get_all("DocType",
-    filters={"module": "My Custom Module"},
-    fields=["name", "issingle", "istable"],
-    limit_page_length=0
-)
-```
-
-### Check DocType metadata
-```python
-meta = frappe.get_meta("Sales Invoice")
-print(f"Fields: {len(meta.fields)}")
-print(f"Is Submittable: {meta.is_submittable}")
-print(f"Is Child Table: {meta.istable}")
-for df in meta.fields:
-    print(f"  {df.fieldname} ({df.fieldtype})" + (" *" if df.reqd else ""))
-```
-
-### Find child tables of a DocType
-```python
-meta = frappe.get_meta("Sales Invoice")
-for df in meta.fields:
-    if df.fieldtype == "Table":
-        print(f"  {df.fieldname} → {df.options}")
-```
-
----
-
-## Common Patterns
-
-### Get all Link fields pointing to a DocType
-```python
-# Find all DocTypes that link to "Customer"
-links = frappe.get_all("DocField",
-    filters={"fieldtype": "Link", "options": "Customer"},
-    fields=["parent", "fieldname"],
-    limit_page_length=0
-)
-for l in links:
-    print(f"  {l.parent}.{l.fieldname}")
-```
-
-### Export DocType Registry to File
-```python
-import json
-from collections import defaultdict
-
-doctypes = frappe.get_all("DocType",
-    fields=["name", "module", "issingle", "istable", "is_submittable"],
-    limit_page_length=0
-)
-by_module = defaultdict(list)
-for dt in doctypes:
-    by_module[dt.module].append(dt)
-
-output = {}
-for module in sorted(by_module.keys()):
-    output[module] = [{
-        "name": dt.name,
-        "single": bool(dt.issingle),
-        "child": bool(dt.istable),
-        "submittable": bool(dt.is_submittable)
-    } for dt in sorted(by_module[module], key=lambda x: x.name)]
-
-with open("doctype-registry.json", "w") as f:
-    json.dump(output, f, indent=2)
-print(f"Exported {len(doctypes)} DocTypes across {len(output)} modules")
-```

package/skills/cm-frappe-agent/resources/installation-guide.md

@@ -1,289 +0,0 @@
-# Frappe Installation & Setup Guide
-
-> Complete reference for installing bench, creating sites, and production deployment.
-
----
-
-## Prerequisites
-
-### System Requirements
-
-| Component | Minimum | Recommended |
-|-----------|---------|-------------|
-| OS | Ubuntu 22.04 / macOS 13+ | Ubuntu 22.04 LTS |
-| Python | 3.10+ | 3.11 |
-| Node.js | 18+ | 20 LTS |
-| MariaDB | 10.6+ | 10.11 |
-| Redis | 6+ | 7+ |
-| RAM | 2 GB | 4 GB+ |
-| Disk | 20 GB | 40 GB+ |
-
-### Install Prerequisites (Ubuntu)
-```bash
-# System packages
-sudo apt update && sudo apt upgrade -y
-sudo apt install -y git python3-dev python3-pip python3-venv \
-  redis-server mariadb-server mariadb-client \
-  libmysqlclient-dev libffi-dev libssl-dev \
-  wkhtmltopdf xvfb nginx supervisor
-
-# Node.js via nvm
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
-source ~/.bashrc
-nvm install 20
-npm install -g yarn
-
-# MariaDB configuration
-sudo mysql_secure_installation
-```
-
-### Install Prerequisites (macOS)
-```bash
-# Via Homebrew
-brew install python@3.11 node@20 mariadb redis
-brew services start mariadb
-brew services start redis
-
-npm install -g yarn
-```
-
-### MariaDB Configuration
-```ini
-# /etc/mysql/mariadb.conf.d/50-server.cnf (Ubuntu)
-# /opt/homebrew/etc/my.cnf (macOS)
-
-[mysqld]
-character-set-server = utf8mb4
-collation-server = utf8mb4_unicode_ci
-innodb_file_per_table = 1
-innodb_large_prefix = 1
-
-[client]
-default-character-set = utf8mb4
-```
-
-```bash
-# Restart MariaDB after config change
-sudo systemctl restart mariadb  # Ubuntu
-brew services restart mariadb   # macOS
-```
-
----
-
-## Bench Installation
-
-### Install via pip
-```bash
-pip3 install frappe-bench
-```
-
-### Initialize Bench
-```bash
-# Latest version
-bench init frappe-bench --frappe-branch version-15
-cd frappe-bench
-
-# Specific version
-bench init frappe-bench --frappe-branch version-14
-```
-
-### Verify Installation
-```bash
-bench --version
-bench find .  # Should find the bench directory
-```
-
----
-
-## Site Management
-
-### Create New Site
-```bash
-bench new-site mysite.localhost \
-  --mariadb-root-password <root_password> \
-  --admin-password <admin_password>
-
-# With PostgreSQL
-bench new-site mysite.localhost \
-  --db-type postgres \
-  --db-host localhost \
-  --db-port 5432
-```
-
-### Set Default Site
-```bash
-bench use mysite.localhost
-```
-
-### Install Apps on Site
-```bash
-# Get app from git
-bench get-app erpnext --branch version-15
-bench get-app https://github.com/user/my-custom-app.git
-
-# Install on site
-bench --site mysite.localhost install-app erpnext
-bench --site mysite.localhost install-app my_custom_app
-```
-
-### Start Development Server
-```bash
-bench start
-# Access at http://mysite.localhost:8000
-```
-
----
-
-## Custom App Development Setup
-
-### Create New App
-```bash
-bench new-app my_custom_app
-# Follow interactive prompts for title, description, etc.
-```
-
-### Install on Site
-```bash
-bench --site mysite.localhost install-app my_custom_app
-```
-
-### Development Workflow
-```bash
-# Watch for changes (auto-rebuild JS/CSS)
-bench watch
-
-# Manual build
-bench build --app my_custom_app
-
-# Run migrations after schema changes
-bench --site mysite.localhost migrate
-
-# Clear cache
-bench --site mysite.localhost clear-cache
-```
-
----
-
-## Production Setup
-
-### Setup Production (Ubuntu)
-```bash
-# Run as root or with sudo
-sudo bench setup production <user>
-
-# This configures:
-# - Nginx (reverse proxy)
-# - Supervisor (process manager)
-# - Redis (cache & queue)
-# - Fail2ban (security)
-```
-
-### Manual Production Setup
-
-#### Nginx Config
-```bash
-bench setup nginx
-sudo ln -s `pwd`/config/nginx.conf /etc/nginx/conf.d/frappe-bench.conf
-sudo nginx -t && sudo systemctl reload nginx
-```
-
-#### Supervisor Config
-```bash
-bench setup supervisor
-sudo ln -s `pwd`/config/supervisor.conf /etc/supervisor/conf.d/frappe-bench.conf
-sudo supervisorctl reread && sudo supervisorctl update
-```
-
-#### SSL with Certbot
-```bash
-sudo apt install certbot python3-certbot-nginx
-sudo certbot --nginx -d mysite.example.com
-```
-
-### Enable Scheduler (Production)
-```bash
-bench --site mysite.localhost enable-scheduler
-```
-
----
-
-## Docker Setup (Development)
-
-### Using frappe_docker
-```bash
-git clone https://github.com/frappe/frappe_docker.git
-cd frappe_docker
-
-# Development setup
-cp example.env .env
-docker compose -f compose.yaml \
-  -f overrides/compose.noproxy.yaml \
-  -f overrides/compose.mariadb.yaml \
-  up -d
-
-# Create site
-docker compose exec backend \
-  bench new-site mysite.localhost --mariadb-root-password 123
-```
-
----
-
-## Common Installation Errors
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `ERROR 1698: Access denied for user 'root'` | MariaDB auth method | `sudo mysql -e "ALTER USER 'root'@'localhost' IDENTIFIED BY 'password';"` |
-| `ModuleNotFoundError: No module named 'frappe'` | Virtualenv not activated | Run from bench directory, or `source env/bin/activate` |
-| `error: externally-managed-environment` | PEP 668 on Ubuntu 23+ | Use `pip install --break-system-packages` or use `pipx` |
-| `node: command not found` | Node.js not installed | Install via nvm: `nvm install 20` |
-| `Redis connection refused` | Redis not running | `sudo systemctl start redis` or `brew services start redis` |
-| `wkhtmltopdf not found` | PDF generation dependency | `sudo apt install wkhtmltopdf xvfb` |
-| `yarn: command not found` | Yarn not installed | `npm install -g yarn` |
-| `bench start` hangs | Port conflict | Check `lsof -i :8000` and kill conflicting process |
-
----
-
-## Multi-Site Setup
-
-```bash
-# Enable DNS-based multi-tenancy
-bench config dns_multitenant on
-
-# Create additional sites
-bench new-site site2.localhost
-bench --site site2.localhost install-app erpnext
-
-# Add to hosts file
-echo "127.0.0.1 site2.localhost" | sudo tee -a /etc/hosts
-```
-
----
-
-## Backup & Restore
-
-```bash
-# Backup
-bench --site mysite.localhost backup --with-files
-
-# List backups
-ls sites/mysite.localhost/private/backups/
-
-# Restore
-bench --site mysite.localhost restore \
-  sites/mysite.localhost/private/backups/<backup>.sql.gz \
-  --with-private-files <private.tar> \
-  --with-public-files <public.tar>
-```
-
----
-
-## Version Upgrade
-
-```bash
-# Update to latest patch
-bench update
-
-# Switch major version
-bench switch-to-branch version-15 frappe erpnext
-bench update --patch
-```