hazo_debug

Permission-gated debug toolkit for hazo_* packages. Provides a floating DevTools-like panel with 10 pluggable feature tabs for inspecting runtime state, API calls, errors, database queries, LLM prompts, file operations, and more.

Installation

npm install hazo_debug

Peer Dependencies (required)

npm install hazo_ui react react-dom

Optional Peer Dependencies

• hazo_auth — Permission-gated access in production
• hazo_config — INI config file reading
• hazo_connect — Database query logging
• hazo_files — File operation logging
• hazo_llm_api — LLM prompt/response logging
• hazo_logs (>=1.0.13) — Structured logging with on_log callback
• lucide-react — Icons

Quick Start

1. Wrap your app with DebugProvider

// app/layout.tsx
import { DebugProvider } from 'hazo_debug/client';

export default function Layout({ children }) {
  return (
    <DebugProvider
      force_enabled={process.env.NODE_ENV === 'development'}
      hazo_logs_endpoint="/api/hazo_logs/client-log"
      hazo_logs_api="/api/logs"
    >
      {children}
    </DebugProvider>
  );
}

2. The debug panel appears automatically

Press Ctrl+Shift+D or click the floating bug icon in the bottom-right corner.

3. Log with hazo_debug_console

import { use_debug_log } from 'hazo_debug/client';

function MyComponent({ data }) {
  const { hazo_debug_console, log_event } = use_debug_log('MyComponent');

  function handleClick() {
    hazo_debug_console('info', 'Button clicked', { data });
    log_event('user_action', 'Button clicked', { data });
  }

  return <button onClick={handleClick}>Do something</button>;
}

hazo_debug_console() entries appear in both the hazo_logs and hazo_console tabs, and are dual-written to the server when hazo_logs_endpoint is configured.

4. Add debug icons to components

import { DebugIcon } from 'hazo_debug/client';

function MyComponent({ data }) {
  return (
    <div>
      <DebugIcon data={data} label="Props" component_name="MyComponent" />
    </div>
  );
}

5. Set up the server API (optional)

// app/api/hazo_debug/[...path]/route.ts
import { create_debug_api_handler } from 'hazo_debug/server';
export const { GET } = create_debug_api_handler();

Debug Panel Tabs

| Tab | Description | |-----|-------------| | Network | Intercepts all fetch() calls. Shows URL, method, status, timing, headers, body. | | Events | Chronological log of user actions, navigation, state changes. Filterable by category. | | Errors | Catches errors via <DebugErrorBoundary>, window.onerror, and unhandledrejection. | | hazo_auth | Displays current auth state, permissions, and user info. | | hazo_config | Shows INI config values (with secrets masked) and environment variables. | | hazo_connect | Database query log — operation, table, WHERE conditions, timing, rows, errors. | | hazo_llm_api | LLM prompt/response viewer — provider, model, timing, errors. Click to see full prompt and response. | | hazo_files | File operation log — upload, download, delete, move, extract with size, storage, timing. | | hazo_logs | Server-side logs (polled via hazo_logs_api) + hazo_debug_console() entries with level filter. | | hazo_console | Filtered view showing only hazo_debug_console() entries — the console.log replacement. |

Hazo Package Integration Hooks

import {
  use_debug_query,   // hazo_connect: SQL queries
  use_debug_llm,     // hazo_llm_api: prompts/responses
  use_debug_files,   // hazo_files: file operations
  use_debug_log,     // hazo_logs: structured logging
} from 'hazo_debug/client';

// In components:
const { log_query } = use_debug_query();
const { log_llm_call } = use_debug_llm();
const { log_file_op } = use_debug_files();
const { hazo_debug_console } = use_debug_log('MyComponent');

Wire hazo_logs on_log callback

import { createClientLogger } from 'hazo_logs/ui';
import { use_debug_log } from 'hazo_debug/client';

const { hazo_debug_console } = use_debug_log('MyApp');
const logger = createClientLogger({
  packageName: 'my_app',
  on_log: hazo_debug_console,  // pipes all logs to debug panel + server
});

Permission Model

| Environment | Behavior | |-------------|----------| | NODE_ENV=development | Debug tools always available | | NODE_ENV=production | Requires debug_permission on user's hazo_auth role | | Config override | Set require_permission = false in hazo_debug_config.ini | | Prop override | Pass force_enabled={true} to <DebugProvider> |

When debug is disabled, all components render nothing and no data is captured (zero overhead).

Configuration

Copy config/hazo_debug_config.example.ini to your project's config/hazo_debug_config.ini:

[hazo_debug]
enabled = true
require_permission = true
permission_name = debug_permission
max_request_entries = 200
max_event_entries = 500
keyboard_shortcut = ctrl+shift+d
panel_position = bottom

Tailwind CSS

No configuration needed. hazo_debug injects its own self-contained stylesheet at runtime, scoped under [data-hazo-debug]. The debug panel works regardless of the consumer's Tailwind setup — no @source directive required.

API Reference

Components

• <DebugProvider> — Context provider. Wrap your app root. Accepts force_enabled, features, hazo_logs_endpoint, hazo_logs_api, keyboard_shortcut, api_base_path.
• <DebugIcon> — Bright blue bug icon that opens a debug dialog on click.
• <DebugDialog> — Modal for structured debug data.
• <DebugJsonView> — Collapsible JSON viewer.
• <DebugErrorBoundary> — Error boundary that reports to the debug panel.
• <DebugBadge> — Status/method/count pill (variants: default, success, warning, error, info).

Hooks

• use_debug_log(source) — Returns { hazo_debug_console, log_debug, log_event }.
• use_debug_query() — Returns { log_query } for hazo_connect SQL query logging.
• use_debug_llm() — Returns { log_llm_call } for hazo_llm_api prompt/response logging.
• use_debug_files() — Returns { log_file_op } for hazo_files operation logging.
• use_debug_enabled() — Returns true if debug is active.
• use_debug_context() — Full access to debug state and dispatch.

Server

• create_debug_api_handler() — Next.js route handler for /api/hazo_debug.
• get_debug_config() — Read INI config with masked secrets.
• check_debug_permission() — Server-side auth check.

Types

All entry types are exported from the root hazo_debug import:

import type {
  QueryLogEntry,    // hazo_connect queries
  LlmLogEntry,      // hazo_llm_api calls
  FileLogEntry,     // hazo_files operations
  DebugLogEntry,    // debug log entries
  RequestLogEntry,  // network requests
  DebugEventEntry,  // events
  DebugErrorEntry,  // errors
} from 'hazo_debug';