gandalf/secubox-openwrt
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
92f3318729
secubox-openwrt/secubox-tools/README.md
CyberMind-FR 92f3318729 feat: add comprehensive module validation tooling 
Add validate-modules.sh script that validates critical naming conventions
and module structure to prevent common RPC and HTTP 404 errors.

New validation checks:
- RPCD script names must match ubus object names (luci.* prefix)
- Menu paths must match view file locations
- View files must have corresponding menu entries
- RPCD scripts must be executable
- JSON files must have valid syntax
- ubus objects must follow naming convention

Updated CLAUDE.md documentation with:
- Critical naming conventions section with examples
- Common error patterns and solutions
- Updated development workflow to include validation
- Enhanced troubleshooting guide for RPC and 404 errors
- Updated package structure diagram with correct RPCD naming

Added secubox-tools/README.md:
- Detailed usage instructions for validation script
- Common fixes for naming issues
- CI/CD integration examples
- Quick reference for critical naming rules

This tooling prevents deployment of modules with naming mismatches that
cause runtime errors like:
- RPC call failed with error -32000: Object not found
- HTTP error 404 while loading view files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-24 09:56:42 +01:00

3.3 KiB
Raw Blame History

SecuBox Development Tools

This directory contains utilities for validating, debugging, and maintaining SecuBox modules.

Tools

validate-modules.sh

Comprehensive validation script that checks all critical naming conventions and module structure.

Usage:

./secubox-tools/validate-modules.sh

Checks performed:

  1. RPCD script names vs ubus objects - Ensures RPCD script filenames match JavaScript ubus object declarations
  2. Menu paths vs view files - Verifies menu.d JSON paths correspond to actual view files
  3. View files have menu entries - Checks that all view files are referenced in menus
  4. RPCD script permissions - Ensures scripts are executable
  5. JSON syntax validation - Validates all menu.d and acl.d JSON files
  6. ubus naming convention - Verifies all ubus objects use the luci. prefix

Exit codes:

  • 0 - All checks passed (or only warnings)
  • 1 - Critical errors found

Example output:

✓ luci-app-cdn-cache: RPCD script 'luci.cdn-cache' matches ubus object 'luci.cdn-cache'
✓ luci-app-cdn-cache: Menu path 'cdn-cache/overview' → file exists
❌ ERROR: luci-app-example: RPCD script 'example' does not match ubus object 'luci.example'

secubox-repair.sh

Auto-repair tool that fixes common issues in Makefiles and RPCD scripts.

Usage:

./secubox-tools/secubox-repair.sh

secubox-debug.sh

Validates individual package structure and dependencies.

Usage:

./secubox-tools/secubox-debug.sh luci-app-<module-name>

Recommended Workflow

Before committing changes:

  1. Run validation (CRITICAL):

    ./secubox-tools/validate-modules.sh

  2. Fix any errors reported

  3. Run shellcheck on RPCD scripts:

    shellcheck luci-app-*/root/usr/libexec/rpcd/*

  4. Commit changes

Common Fixes

Fix RPCD naming mismatch

If validation reports RPCD script name doesn't match ubus object:

# Rename the script to include luci. prefix
cd luci-app-example/root/usr/libexec/rpcd
mv example luci.example

Fix menu path mismatch

If validation reports menu path doesn't match view file:

# Option 1: Update menu.d JSON to match file location
# Edit: root/usr/share/luci/menu.d/luci-app-example.json
# Change: "path": "example/view" → "path": "example-dashboard/view"

# Option 2: Move view files to match menu path
mv htdocs/luci-static/resources/view/example-dashboard \
   htdocs/luci-static/resources/view/example

Fix non-executable RPCD script

chmod +x luci-app-example/root/usr/libexec/rpcd/luci.example

Integration with CI/CD

The validation script can be integrated into GitHub Actions workflows:

- name: Validate modules
  run: |
    chmod +x secubox-tools/validate-modules.sh
    ./secubox-tools/validate-modules.sh

Critical Naming Rules

These rules are MANDATORY - violations will cause runtime errors:

  1. RPCD scripts must be named luci.<module-name>

    • ✅ luci.cdn-cache
    • ❌ cdn-cache

  2. Menu paths must match view file locations

    • Menu: "path": "cdn-cache/overview"
    • File: view/cdn-cache/overview.js

  3. ubus objects must use luci. prefix

    • ✅ object: 'luci.cdn-cache'
    • ❌ object: 'cdn-cache'

See CLAUDE.md for complete documentation.