Adds structured logging with LogTape

Replaces console.* calls with LogTape-based structured logging featuring timestamped output, module-specific categories, and configurable log levels.

Introduces module-specific loggers (app, browser, scheduler, http, webhook, etc.) that provide hierarchical categorization and consistent formatting across the codebase.

Adds LOG_LEVEL environment variable and debug_logging add-on option to control verbosity from trace to fatal levels, enabling better debugging without code changes.

Improves observability by making log patterns more structured and searchable, while maintaining zero-dependency logging infrastructure.

Updates documentation with logging configuration, usage examples, and available logger categories.

Author: ikraamg

CLAUDE.md

@@ -67,6 +67,7 @@ HTTP Request → HttpRouter → RequestHandler → Browser (Puppeteer)
 | `lib/http-router.ts` | HTTP routing for UI, API, health, static files |
 | `lib/dithering.ts` | Image processing pipeline via GraphicsMagick |
 | `lib/scheduleStore.ts` | Schedule CRUD operations with JSON persistence |
+| `lib/logger.ts` | LogTape-based structured logging with module categories |
 | `const.ts` | All configuration constants, environment detection |
 | `error.ts` | Custom error classes for browser lifecycle management |
 
@@ -133,10 +134,44 @@ bun run mock:server
 MOCK_HA=true bun run dev
 ```
 
+## Logging
+
+Uses [LogTape](https://logtape.org) for structured, timestamped logging with zero dependencies.
+
+### Log Format
+```
+[2025-12-30T11:19:53.454Z] [INFO ] [scheduler] Starting scheduler...
+[2025-12-30T11:19:53.454Z] [INFO ] [app] Server started at http://localhost:10000
+```
+
+### Usage
+```typescript
+import { appLogger, browserLogger, schedulerLogger } from './lib/logger.js'
+
+const log = appLogger()
+log.info`Server started at ${url}`
+log.debug`Processing ${count} items`
+log.error`Failed: ${error.message}`
+```
+
+### Available Loggers
+- `appLogger()` - Main app lifecycle
+- `browserLogger()` - Puppeteer/browser operations
+- `screenshotLogger()` - Screenshot capture
+- `schedulerLogger()` - Cron scheduling
+- `cronLogger()` - Cron job management
+- `webhookLogger()` - Webhook delivery
+- `httpLogger()` - HTTP routing
+- `uiLogger()` - UI serving
+- `ditheringLogger()` - Image processing
+- `navigationLogger()` - Page navigation
+- `configLogger()` - Configuration loading
+
 ## Environment Variables
 
 | Variable | Default | Purpose |
 |----------|---------|---------|
+| `LOG_LEVEL` | `info` | Log verbosity: trace, debug, info, warning, error, fatal |
 | `MOCK_HA` | `false` | Use mock HA server for testing |
 | `BROWSER_TIMEOUT` | `60000` | Idle timeout before browser cleanup (ms) |
 | `MAX_SCREENSHOTS_BEFORE_RESTART` | `100` | Proactive browser restart threshold |

README.md

@@ -42,8 +42,6 @@ If running Home Assistant OS in Proxmox, set the VM host type to `host` for Chro
 - **Never expose port 10000** directly to the internet
 - Access tokens are stored securely in Home Assistant's add-on configuration
 
-The add-on includes an AppArmor security profile that restricts file and network access to only what's required for operation.
-
 ## Documentation
 
 | Topic | Description |

trmnl-ha/DOCS.md

@@ -186,7 +186,7 @@ For best e-ink results:
 - Tokens are passed to the browser in memory, not written to disk
 - Use a dedicated token for this add-on (revoke it to disable access)
 
-### AppArmor Profile
+### AppArmor Profile (TODO)
 
 The add-on includes an AppArmor security profile that:
 

trmnl-ha/README.md

@@ -42,8 +42,6 @@ If running Home Assistant OS in Proxmox, set the VM host type to `host` for Chro
 - **Never expose port 10000** directly to the internet
 - Access tokens are stored securely in Home Assistant's add-on configuration
 
-The add-on includes an AppArmor security profile that restricts file and network access to only what's required for operation.
-
 ## Documentation
 
 | Topic | Description |

trmnl-ha/config.yaml

@@ -34,12 +34,14 @@ options:
   access_token: ""
   home_assistant_url: "http://homeassistant:8123"
   keep_browser_open: false
+  debug_logging: false
 
 # Schema for options validation
 schema:
   access_token: str
   home_assistant_url: str?
   keep_browser_open: bool?
+  debug_logging: bool?
 
 # Exclude regeneratable data from HA backups
 backup_exclude:

trmnl-ha/ha-trmnl/bun.lock

@@ -21,6 +21,7 @@ interface Options {
   access_token?: string
   chromium_executable?: string
   keep_browser_open?: boolean
+  debug_logging?: boolean
 }
 
 /**
@@ -108,9 +109,10 @@ export const chromiumExecutable: string = isAddOn
 export const keepBrowserOpen: boolean = options.keep_browser_open ?? false
 
 /**
- * Enable debug logging
+ * Enable debug logging (from HA add-on configuration)
+ * When true, sets log level to 'debug' for verbose output
  */
-export const debug: boolean = false
+export const debugLogging: boolean = options.debug_logging ?? false
 
 // =============================================================================
 // SERVER CONFIGURATION
@@ -228,11 +230,6 @@ export const CONTENT_TYPES: ContentTypeMap = {
 // SCHEDULER CONFIGURATION
 // =============================================================================
 
-/**
- * Scheduler log prefix for console output
- */
-export const SCHEDULER_LOG_PREFIX: string = '[Scheduler]'
-
 /**
  * Schedule reload interval in milliseconds
  */

trmnl-ha/ha-trmnl/const.ts

@@ -24,6 +24,11 @@ export default tseslint.config(
       },
     },
     rules: {
+      // Allow tagged template literals (LogTape logging syntax: log.info`message`)
+      '@typescript-eslint/no-unused-expressions': [
+        'error',
+        { allowTaggedTemplates: true },
+      ],
       // Unused vars with underscore prefix are allowed
       '@typescript-eslint/no-unused-vars': [
         'error',

trmnl-ha/ha-trmnl/eslint.config.js

@@ -15,6 +15,9 @@ import {
 } from '../../const.js'
 import { CannotOpenPageError } from '../../error.js'
 import type { NavigationResult } from '../../types/domain.js'
+import { navigationLogger } from '../logger.js'
+
+const log = navigationLogger()
 
 /** Auth storage for localStorage injection */
 export type AuthStorage = Record<string, string>
@@ -163,7 +166,7 @@ export class WaitForPageLoad {
         { timeout: 10000, polling: 100 }
       )
     } catch (_err) {
-      console.log('Timeout waiting for HA to finish loading')
+      log.debug`Timeout waiting for HA to finish loading`
     }
   }
 }
@@ -215,9 +218,7 @@ export class WaitForPageStable {
         stableChecks++
         if (stableChecks >= requiredStableChecks) {
           const actualWait = Date.now() - start
-          console.debug(
-            `Page stable after ${actualWait}ms (${stableChecks} checks)`
-          )
+          log.debug`Page stable after ${actualWait}ms (${stableChecks} checks)`
           return actualWait
         }
       } else {
@@ -231,7 +232,7 @@ export class WaitForPageStable {
     }
 
     const actualWait = Date.now() - start
-    console.debug(`Page stability timeout after ${actualWait}ms`)
+    log.debug`Page stability timeout after ${actualWait}ms`
     return actualWait
   }
 }

trmnl-ha/ha-trmnl/lib/browser/navigation-commands.ts

@@ -7,6 +7,9 @@
  */
 
 import { BrowserRecoveryFailedError } from '../error.js'
+import { browserLogger } from './logger.js'
+
+const log = browserLogger()
 
 /** Browser instance interface (from screenshot.ts) */
 export interface BrowserInstance {
@@ -97,14 +100,12 @@ export class BrowserFacade {
     let attempts = 0
     let lastError: Error | null = null
 
-    console.log('[Recovery] Starting browser recovery...')
+    log.info`Starting browser recovery...`
 
     try {
       while (attempts < BrowserFacade.MAX_RECOVERY_ATTEMPTS) {
         attempts++
-        console.log(
-          `[Recovery] Attempt ${attempts}/${BrowserFacade.MAX_RECOVERY_ATTEMPTS}`
-        )
+        log.info`Recovery attempt ${attempts}/${BrowserFacade.MAX_RECOVERY_ATTEMPTS}`
 
         try {
           await this.#browser.cleanup().catch(() => {})
@@ -113,16 +114,13 @@ export class BrowserFacade {
 
           if (!this.#browser.isConnected()) throw new Error('Not connected')
 
-          console.log(`[Recovery] Success after ${attempts} attempt(s)`)
+          log.info`Recovery success after ${attempts} attempt(s)`
           this.#recoveries++
           this.#failures = 0
           return
         } catch (err) {
           lastError = err as Error
-          console.error(
-            `[Recovery] Attempt ${attempts} failed:`,
-            lastError.message
-          )
+          log.error`Recovery attempt ${attempts} failed: ${lastError.message}`
         }
       }
       throw new BrowserRecoveryFailedError(