mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-10 21:03:01 +00:00

Files

Chuck 441b3c56e9 fix(starlark): code review fixes - security, robustness, and schema parsing

## Security Fixes
- manager.py: Check _update_manifest_safe return values to prevent silent failures
- manager.py: Improve temp file cleanup in _save_manifest to prevent leaks
- manager.py: Fix uninstall order (manifest → memory → disk) for consistency
- api_v3.py: Add path traversal validation in uninstall endpoint
- api_v3.py: Implement atomic writes for manifest files with temp + rename
- pixlet_renderer.py: Relax config validation to only block dangerous shell metacharacters

## Frontend Robustness
- plugins_manager.js: Add safeLocalStorage wrapper for restricted contexts (private browsing)
- starlark_config.html: Scope querySelector to container to prevent modal conflicts

## Schema Parsing Improvements
- pixlet_renderer.py: Indentation-aware get_schema() extraction (handles nested functions)
- pixlet_renderer.py: Handle quoted defaults with commas (e.g., "New York, NY")
- tronbyte_repository.py: Validate file_name is string before path traversal checks

## Dependencies
- requirements.txt: Update Pillow (10.4.0), PyYAML (6.0.2), requests (2.32.0)

## Documentation
- docs/STARLARK_APPS_GUIDE.md: Comprehensive guide explaining:
  - How Starlark apps work
  - That apps come from Tronbyte (not LEDMatrix)
  - Installation, configuration, troubleshooting
  - Links to upstream projects

All changes improve security, reliability, and user experience.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-02-19 16:58:22 -05:00

README.md

LEDMatrix Documentation

Welcome to the LEDMatrix documentation! This directory contains comprehensive guides, specifications, and reference materials for the LEDMatrix project.

📚 Documentation Overview

This documentation has been recently consolidated (January 2026) to reduce redundancy while maintaining comprehensive coverage. We've reduced from 51 main documents to 16-17 well-organized files (~68% reduction) by merging duplicates, archiving ephemeral content, and unifying writing styles.

📖 Quick Start

For New Users

Installation: Follow the main README.md in the project root
First Setup: See GETTING_STARTED.md for first-time setup guide
Web Interface: Use WEB_INTERFACE_GUIDE.md to learn the control panel
Troubleshooting: Check TROUBLESHOOTING.md for common issues

For Developers

Plugin Development: See PLUGIN_DEVELOPMENT_GUIDE.md for complete guide
Advanced Patterns: Read ADVANCED_PLUGIN_DEVELOPMENT.md for advanced techniques
API Reference: Check PLUGIN_API_REFERENCE.md for available methods
Configuration: See PLUGIN_CONFIGURATION_GUIDE.md for config schemas

For API Integration

REST API: See REST_API_REFERENCE.md for all web interface endpoints
Plugin API: See PLUGIN_API_REFERENCE.md for plugin developer APIs
Developer Reference: See DEVELOPER_QUICK_REFERENCE.md for common tasks

📋 Documentation Categories

🚀 Getting Started & User Guides

GETTING_STARTED.md - First-time setup and quick start guide
WEB_INTERFACE_GUIDE.md - Complete web interface user guide
WIFI_NETWORK_SETUP.md - WiFi configuration and AP mode setup
PLUGIN_STORE_GUIDE.md - Installing and managing plugins
TROUBLESHOOTING.md - Common issues and solutions

⚡ Advanced Features

ADVANCED_FEATURES.md - Vegas scroll mode, on-demand display, cache management, background services, permissions

🔌 Plugin Development

PLUGIN_DEVELOPMENT_GUIDE.md - Complete plugin development workflow
PLUGIN_QUICK_REFERENCE.md - Plugin development quick reference
ADVANCED_PLUGIN_DEVELOPMENT.md - Advanced patterns and examples
PLUGIN_CONFIGURATION_GUIDE.md - Configuration schema design
PLUGIN_CONFIGURATION_TABS.md - Configuration tabs feature
PLUGIN_CONFIG_QUICK_START.md - Quick configuration guide
PLUGIN_DEPENDENCY_GUIDE.md - Managing plugin dependencies
PLUGIN_DEPENDENCY_TROUBLESHOOTING.md - Dependency troubleshooting

🏗️ Plugin Features & Extensions

PLUGIN_CUSTOM_ICONS.md - Custom plugin icons
PLUGIN_CUSTOM_ICONS_FEATURE.md - Custom icons implementation
PLUGIN_IMPLEMENTATION_SUMMARY.md - Plugin system implementation
PLUGIN_REGISTRY_SETUP_GUIDE.md - Setting up plugin registry
PLUGIN_WEB_UI_ACTIONS.md - Web UI actions for plugins

📡 API Reference

REST_API_REFERENCE.md - Complete REST API documentation (71+ endpoints)
PLUGIN_API_REFERENCE.md - Plugin developer API (Display Manager, Cache Manager, Plugin Manager)
DEVELOPER_QUICK_REFERENCE.md - Quick reference for common developer tasks

🏛️ Architecture & Design

PLUGIN_ARCHITECTURE_SPEC.md - Complete plugin system specification
PLUGIN_CONFIG_ARCHITECTURE.md - Configuration system architecture
PLUGIN_CONFIG_CORE_PROPERTIES.md - Core configuration properties

🛠️ Development & Tools

DEVELOPMENT.md - Development environment setup
EMULATOR_SETUP_GUIDE.md - Set up development environment with emulator
HOW_TO_RUN_TESTS.md - Testing documentation
MULTI_ROOT_WORKSPACE_SETUP.md - Multi-workspace development
FONT_MANAGER.md - Font management system

🔄 Migration & Updates

MIGRATION_GUIDE.md - Breaking changes and migration instructions
SSH_UNAVAILABLE_AFTER_INSTALL.md - SSH troubleshooting after install

📚 Miscellaneous

widget-guide.md - Widget development guide
Template files:
- plugin_registry_template.json - Plugin registry template
- PLUGIN_WEB_UI_ACTIONS_EXAMPLE.json - Web UI actions example

🎯 Key Resources by Use Case

I'm new to LEDMatrix

GETTING_STARTED.md - Start here for first-time setup
WEB_INTERFACE_GUIDE.md - Learn the control panel
PLUGIN_STORE_GUIDE.md - Install plugins

I want to create a plugin

PLUGIN_DEVELOPMENT_GUIDE.md - Complete development guide
PLUGIN_API_REFERENCE.md - Available methods and APIs
ADVANCED_PLUGIN_DEVELOPMENT.md - Advanced patterns
PLUGIN_CONFIGURATION_GUIDE.md - Configuration setup
PLUGIN_ARCHITECTURE_SPEC.md - Complete specification

I need to troubleshoot an issue

TROUBLESHOOTING.md - Comprehensive troubleshooting guide
WIFI_NETWORK_SETUP.md - WiFi/network issues
PLUGIN_DEPENDENCY_TROUBLESHOOTING.md - Dependency issues

I want to use advanced features

ADVANCED_FEATURES.md - Vegas scroll, on-demand display, background services
FONT_MANAGER.md - Font management
REST_API_REFERENCE.md - API integration

I want to understand the architecture

PLUGIN_ARCHITECTURE_SPEC.md - System architecture
PLUGIN_CONFIG_ARCHITECTURE.md - Configuration architecture
PLUGIN_IMPLEMENTATION_SUMMARY.md - Implementation details

🔄 Recent Consolidations (January 2026)

Major Consolidation Effort

Before: 51 main documentation files
After: 16-17 well-organized files
Reduction: ~68% fewer files
Archived: 33 files (consolidated sources + ephemeral docs)

New Consolidated Guides

GETTING_STARTED.md - New first-time user guide
WEB_INTERFACE_GUIDE.md - Consolidated web interface documentation
WIFI_NETWORK_SETUP.md - Consolidated WiFi setup (5 files → 1)
PLUGIN_STORE_GUIDE.md - Consolidated plugin store guides (2 files → 1)
TROUBLESHOOTING.md - Consolidated troubleshooting (4 files → 1)
ADVANCED_FEATURES.md - Consolidated advanced features (6 files → 1)

What Was Archived

Ephemeral debug documents (DEBUG_WEB_ISSUE.md, BROWSER_ERRORS_EXPLANATION.md, etc.)
Implementation summaries (PLUGIN_CONFIG_TABS_SUMMARY.md, STARTUP_OPTIMIZATION_SUMMARY.md, etc.)
Consolidated source files (WIFI_SETUP.md, V3_INTERFACE_README.md, etc.)
Testing documentation (CAPTIVE_PORTAL_TESTING.md, etc.)

All archived files are preserved in docs/archive/ with full git history.

Benefits

✅ Easier to find information (fewer files to search)
✅ No duplicate content
✅ Consistent writing style (professional technical)
✅ Updated outdated references
✅ Fixed broken internal links
✅ Better organization for users vs developers

📝 Contributing to Documentation

Documentation Standards

Use Markdown format with consistent headers
Professional technical writing style
Minimal emojis (1-2 per major section for navigation)
Include code examples where helpful
Provide both quick start and detailed reference sections
Cross-reference related documentation

Adding New Documentation

Consider if content should be added to existing docs first
Place in appropriate category (see sections above)
Update this README.md with the new document
Follow naming conventions (FEATURE_NAME.md)
Use consistent formatting and voice

Consolidation Guidelines

User Guides: Consolidate by topic (WiFi, troubleshooting, etc.)
Developer Guides: Keep development vs reference vs architecture separate
Debug Documents: Archive after issues are resolved
Implementation Summaries: Archive completed implementation details
Ephemeral Content: Archive, don't keep in main docs

Main Project README - Installation and basic usage
Web Interface README - Web interface details
GitHub Issues - Bug reports and feature requests
GitHub Discussions - Community support

📊 Documentation Statistics

Main Documents: 16-17 files (after consolidation)
Archived Documents: 33 files (in docs/archive/)
Categories: 9 major sections
Primary Language: English
Format: Markdown (.md)
Last Major Update: January 2026
Coverage: Installation, user guides, development, troubleshooting, architecture, API references

Documentation Highlights

✅ Comprehensive user guides for first-time setup
✅ Complete REST API documentation (71+ endpoints)
✅ Complete Plugin API reference (Display Manager, Cache Manager, Plugin Manager)
✅ Advanced plugin development guide with examples
✅ Consolidated configuration documentation
✅ Professional technical writing throughout
✅ ~68% reduction in file count while maintaining coverage

This documentation index was last updated: January 2026

For questions or suggestions about the documentation, please open an issue or start a discussion on GitHub.