diff --git a/CLAUDE.md b/CLAUDE.md index 9db82ea0..c40d585d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -38,6 +38,9 @@ opkg install /tmp/luci-app-*.ipk ### Validation ```bash +# Run comprehensive module validation (RECOMMENDED) +./secubox-tools/validate-modules.sh + # Validate shell scripts (RPCD backends) shellcheck luci-app-*/root/usr/libexec/rpcd/* @@ -71,7 +74,8 @@ luci-app-/ └── root/ ├── etc/config/ # UCI configuration (optional) └── usr/ - ├── libexec/rpcd/ # RPCD backend script + ├── libexec/rpcd/ + │ └── luci. # RPCD backend script (MUST use luci. prefix!) └── share/ ├── luci/menu.d/ # Menu JSON definition │ └── luci-app-.json @@ -99,6 +103,93 @@ luci-app-/ - Defines access control for ubus methods - Maps read/write permissions to user groups +### Critical Naming Conventions + +**IMPORTANT**: The following naming rules are MANDATORY for modules to work correctly: + +#### 1. RPCD Script Must Match ubus Object Name + +The RPCD script filename MUST exactly match the ubus object name used in JavaScript: + +```javascript +// In JavaScript (htdocs/luci-static/resources/view/*/): +var callStatus = rpc.declare({ + object: 'luci.cdn-cache', // ← This object name + method: 'status' +}); +``` + +```bash +# RPCD script filename MUST match: +root/usr/libexec/rpcd/luci.cdn-cache # ← Must be exactly 'luci.cdn-cache' +``` + +**Common Error**: If the names don't match, you'll get: +- `RPC call to luci.cdn-cache/status failed with error -32000: Object not found` +- `Command failed: Method not found` + +**Solution**: All RPCD scripts MUST use the `luci.` prefix: +- ✅ Correct: `luci.cdn-cache`, `luci.system-hub`, `luci.wireguard-dashboard` +- ❌ Wrong: `cdn-cache`, `system-hub`, `wireguard-dashboard` + +#### 2. Menu Paths Must Match View File Locations + +Menu JSON path entries MUST correspond to actual view files: + +```json +// In menu.d/luci-app-netifyd-dashboard.json: +{ + "action": { + "type": "view", + "path": "netifyd-dashboard/overview" // ← Must match file location + } +} +``` + +```bash +# View file MUST exist at: +htdocs/luci-static/resources/view/netifyd-dashboard/overview.js +# ↑ Same path as menu ↑ +``` + +**Common Error**: If paths don't match: +- `HTTP error 404 while loading class file '/luci-static/resources/view/netifyd/overview.js'` + +**Solution**: Ensure menu paths match directory structure: +- ✅ Correct: Menu path `netifyd-dashboard/overview` → file `view/netifyd-dashboard/overview.js` +- ❌ Wrong: Menu path `netifyd/overview` → file `view/netifyd-dashboard/overview.js` + +#### 3. ubus Object Naming Convention + +All ubus objects MUST start with `luci.` prefix: + +```javascript +// ✅ Correct: +object: 'luci.cdn-cache' +object: 'luci.system-hub' +object: 'luci.wireguard-dashboard' + +// ❌ Wrong: +object: 'cdn-cache' +object: 'systemhub' +``` + +#### 4. Validation Before Deployment + +**ALWAYS** run validation before deploying: + +```bash +./secubox-tools/validate-modules.sh +``` + +This script checks: +- RPCD script names match ubus objects +- Menu paths match view file locations +- View files have corresponding menu entries +- RPCD scripts are executable +- JSON files are valid syntax +- ubus objects follow naming convention + ### Makefile Structure Each package Makefile must define: @@ -244,11 +335,49 @@ x86: x86-64, x86-generic ## Common Issues and Solutions +### RPC Errors: "Object not found" or "Method not found" + +**Error**: `RPC call to luci.cdn-cache/status failed with error -32000: Object not found` + +**Cause**: RPCD script name doesn't match ubus object name in JavaScript + +**Solution**: +1. Check JavaScript files for ubus object name: + ```bash + grep -r "object:" luci-app-*/htdocs --include="*.js" + ``` +2. Rename RPCD script to match exactly (including `luci.` prefix): + ```bash + mv root/usr/libexec/rpcd/cdn-cache root/usr/libexec/rpcd/luci.cdn-cache + ``` +3. Restart RPCD on router: + ```bash + /etc/init.d/rpcd restart + ``` + +### HTTP 404 Errors: View Files Not Found + +**Error**: `HTTP error 404 while loading class file '/luci-static/resources/view/netifyd/overview.js'` + +**Cause**: Menu path doesn't match actual view file location + +**Solution**: +1. Check menu JSON for path: + ```bash + grep '"path":' root/usr/share/luci/menu.d/*.json + ``` +2. Verify view file exists at matching location: + ```bash + ls htdocs/luci-static/resources/view/ + ``` +3. Update menu path to match file location OR move file to match menu path + ### RPCD Not Responding After installing/updating a package: ```bash /etc/init.d/rpcd restart +/etc/init.d/uhttpd restart ``` ### Menu Not Appearing @@ -257,30 +386,46 @@ Check that: 1. Menu JSON is valid: `jsonlint root/usr/share/luci/menu.d/*.json` 2. ACL grants access: Check `root/usr/share/rpcd/acl.d/*.json` 3. Dependencies are installed: Check Makefile `LUCI_DEPENDS` +4. Menu path matches view file location (see above) ### Build Failures Common causes: 1. Missing fields in Makefile (PKG_NAME, LUCI_TITLE, etc.) 2. Invalid JSON syntax in menu.d or acl.d -3. RPCD script not executable +3. RPCD script not executable (chmod +x needed) 4. Wrong include path (should be `include ../../luci.mk`) +5. RPCD script name doesn't match ubus object (must use `luci.` prefix) Use repair tool: `./secubox-tools/secubox-repair.sh` +### Quick Diagnosis + +Run the validation script to check all naming conventions: +```bash +./secubox-tools/validate-modules.sh +``` + ## Development Workflow 1. Make changes to module files -2. Test JSON syntax: `jsonlint .json` -3. Test shell scripts: `shellcheck