php-developer/TODO.md

TODO.md - core-developer

Last reviewed: 2026-01-29

P1 - Critical / Security

Completed

• Server model has no migration - FIXED: Migration created at src/Migrations/0001_01_01_000001_create_developer_tables.php
• Inconsistent Hades authorization in DevController - FIXED: Now uses $user->isHades() method
• SetHadesCookie uses env() directly - FIXED: Now uses config('developer.hades_token')
• HorizonServiceProvider gate is empty - FIXED: viewHorizon gate now checks $user->isHades()
• TelescopeServiceProvider gate emails empty - FIXED: Telescope gate now checks $user->isHades()

Open

No open P1 items.

Recently Fixed (Jan 2026)

• Database component SQL injection hardening - FIXED: isReadOnlyQuery() now blocks stacked queries by checking for semicolons followed by non-whitespace content using regex /;\s*\S/.

  • File: src/View/Modal/Admin/Database.php

• DevController missing strict types declaration - FIXED: Added declare(strict_types=1); at top of file.

  • File: src/Controllers/DevController.php

• Servers component writes private key to temp file - FIXED: Now uses tempnam() for atomic file creation and sets 0600 permissions before writing sensitive data.

  • File: src/View/Modal/Admin/Servers.php

• CopyDeviceFrames command lacks config validation - FIXED: Added validation for config existence and required keys (source_path, public_path, devices) with proper error messages.

  • File: src/Console/Commands/CopyDeviceFrames.php

P2 - High Priority

Completed

• Unify authorization pattern - Created RequireHades middleware for consistent authorization
• Add rate limiting to API routes - Added rate limiters in Boot.php for all endpoints
• Log clear action should be audited - clearLogs() now logs with user_id, email, previous_size, IP
• Remove duplicate log reading logic - Created LogReaderService used by both DevController and Logs component
• RemoteServerManager timeout is hardcoded - Added configurable timeouts via config

Open

• Tests pass without Hades tier set - Tests in DevToolsBasic.php create a user without Hades tier but tests pass, suggesting authorization may not be enforced correctly in test environment

  • File: src/Tests/UseCase/DevToolsBasic.php
  • Acceptance: Tests should fail when user is not Hades; add trait/helper to set Hades status in tests

• Clear logs button has no confirmation - Unlike cache management, the logs clear button executes immediately without confirmation

  • File: src/View/Modal/Admin/Logs.php and corresponding blade
  • Acceptance: Add confirmation modal similar to Cache component

• Activity log component shows all workspaces - ActivityLog queries all Activity records without workspace scoping

  • File: src/View/Modal/Admin/ActivityLog.php
  • Acceptance: Either scope to current workspace or document that this is intentional for Hades users

Recently Fixed (Jan 2026)

• Missing developer config file - FIXED: Config file exists at src/config.php with hades_token, ssh.connection_timeout, ssh.command_timeout, and horizon notification settings. Published via mergeConfigFrom() in Boot.php.

• Livewire pages have no route middleware - FIXED: RequireHades middleware applied to the /hub/dev/* route group in src/Routes/admin.php line 15. Authorization now enforced at route level.

P3 - Medium Priority

Completed

• Multi-log file support - Added getAvailableLogFiles() and getCurrentLogPath() to LogReaderService
• Command registration - CopyDeviceFrames now registered via onConsole() handler

Open

• Server model missing table name specification - Relies on Laravel convention; should explicitly set $table = 'servers'

  • File: src/Models/Server.php
  • Acceptance: Add protected $table property

• LogReaderService redaction patterns need review - IP redaction pattern may miss IPv6 addresses

  • File: src/Services/LogReaderService.php line 42
  • Acceptance: Add IPv6 support or document limitation

• RouteTestService environment check is permissive - isTestingAllowed() returns true for 'testing' environment which could be used in CI

  • File: src/Services/RouteTestService.php line 47
  • Acceptance: Consider adding config flag to explicitly enable route testing

• Database query tool lacks export functionality - Users can view results but cannot download/export them

  • Acceptance: Add CSV/JSON export button for query results

• Route inspector history not persisted - History is lost on page refresh

  • File: src/View/Modal/Admin/RouteInspector.php
  • Acceptance: Consider storing history in session or localStorage

• Missing translations for some UI elements - Servers, Database, and ActivityLog pages have hardcoded English strings instead of using translation keys

  • Files: Multiple blade files and components
  • Acceptance: Add translation keys to src/Lang/en_GB/developer.php and use them consistently

P4 - Low Priority / Improvements

Open

• DevController has redundant authorize() calls - The routes() and session() methods call $this->authorize() but API routes already have RequireHades middleware

  • File: src/Controllers/DevController.php
  • Acceptance: Remove redundant authorization checks or document the defence-in-depth approach

• LogReaderService could use generators - For very large log files, using generators instead of arrays would reduce memory usage

  • File: src/Services/LogReaderService.php
  • Acceptance: Refactor readLogEntries() to optionally yield entries

• RouteTestResult getFormattedResponseTime has edge case - Times under 1ms are converted to microseconds incorrectly (multiplied by 1000 instead of keeping as sub-millisecond)

  • File: src/Data/RouteTestResult.php line 93
  • Acceptance: Fix calculation or clarify the intended behaviour

• Server status enum should be a proper PHP enum - Currently uses string values ('pending', 'connected', 'failed')

  • File: src/Models/Server.php
  • Acceptance: Create ServerStatus backed enum and use it consistently

• ApplyIconSettings middleware has hardcoded defaults - Default values should come from config

  • File: src/Middleware/ApplyIconSettings.php
  • Acceptance: Move defaults to config file

• Pulse dashboard override lacks documentation - The custom Pulse view is registered but not documented

  • File: src/View/Blade/vendor/pulse/dashboard.blade.php
  • Acceptance: Add comment in Boot.php explaining the override purpose

P5 - Nice to Have / Future

From code-review.md (documented features)

• Server CRUD UI improvements - Add bulk actions, SSH key validation, connection health checks
• Log download/export - FIXED: downloadLogs() added, but could add format options (JSON, filtered export)
• Event log viewer - Activity logs exist on Server model but no dedicated UI to view activity per model

New Ideas

• Add log search functionality - Currently only filter by level, add full-text search within log messages
• Database saved queries - Allow saving frequently used queries with names
• Route documentation viewer - Parse DocBlocks from controllers and display in route inspector
• SSH terminal emulator - Interactive terminal for connected servers (complex, security considerations)
• Cache statistics dashboard - Show cache hit/miss rates, memory usage, key counts
• Config diff viewer - Compare current config values against defaults

P6+ - Backlog / Someday

• Real-time log streaming - WebSocket/SSE for live log tailing
• Query explain plan visualisation - Parse and display EXPLAIN output graphically
• Route performance profiling - Track response times over time, identify slow routes
• Deployment integration - Trigger deployments from server management UI
• Multi-database support - Query tool for multiple database connections
• Scheduled task monitoring - View and manage Laravel scheduled tasks

Test Coverage Gaps

Currently Tested

• Logs page renders with correct sections and translations
• Routes page renders with table headers
• Cache page renders with all cache action cards

Missing Tests

• DevController API endpoints (logs, routes, session, clear)
• Cache clearing actually executes and clears caches
• Log filtering by level
• Route filtering/searching
• Hades authorization enforcement (both allow and deny cases)
• RemoteServerManager SSH operations (mock phpseclib)
• Server model scopes and methods
• SetHadesCookie listener
• ApplyIconSettings middleware
• CopyDeviceFrames command
• LogReaderService redaction patterns
• RouteTestService route testing logic
• Database component query execution and validation
• ActivityLog filtering and pagination
• RouteInspector request building and execution

Notes

• All Hades-only features require the user's isHades() method to return true
• The module depends on host-uk/core and host-uk/core-admin
• UK English spellings must be used (colour, organisation, centre)
• All PHP files should have declare(strict_types=1);
• Testing uses Pest syntax, not PHPUnit