DOCSEARCHbyAlgolia
Submit Docs

NullHub Management Hub

repository·main·Indexed 40 days ago

https://github.com/nullclaw/nullhub

A Zig-based management hub for the NullClaw ecosystem with an embedded Svelte UI. NullHub allows users to install, configure, monitor, and update components such as NullClaw, NullBoiler, NullTickets, and NullWatch. It features a CLI for instance management, a reverse-proxy for ecosystem components, and Mission Control for deterministic agent mission replay and recovery.

Tokens
25.9K
Snippets
69
Records
109
Agent score
66%

What's inside NullHub

  1. Ecosystem Mapping in Mission Control

    main

    The ecosystem_mapping field in the replay export defines how the scenario fixture relates to specific NullClaw ecosystem components:

    • ecosystem_mapping.nulltickets: Points to tracker-style evidence (events[source=nulltickets], graph.nodes[kind=tracker]).
    • ecosystem_mapping.nullboiler: Points to NullBoiler workflow evidence (phase timing, workflow graph edges, workflow_evidence, checkpoint_id, failed/recovered run IDs, and human fork instructions).
    • ecosystem_mapping.nullclaw: Points to agent evidence (role-based agents, agent graph nodes, and NullClaw-style event source entries).
    • ecosystem_mapping.nullwatch: Points to NullWatch trace evidence (failed/recovered run IDs, events[].trace, telemetry counters, and failure/recovery run panels).

  2. Understand the report submission fallback chain

    main

    When submitting a report via the CLI or Web UI, the system attempts to authenticate with GitHub using the following priority order:

    1. gh CLI: Checks if gh is in PATH and gh auth status succeeds. It uses gh issue create.
    2. gh Token: If gh is present, it attempts to use the token from gh auth token via a direct curl POST to the GitHub API.
    3. GITHUB_TOKEN Env Var: If no gh auth is found, it attempts to use the $GITHUB_TOKEN environment variable via curl.
    4. Manual Fallback: If no authentication is available, the system outputs the formatted markdown and instructs the user to install/authenticate the gh CLI.

  3. How NullHub Proxies Ecosystem Components

    main

    NullHub acts as a central hub by reverse-proxying requests to other NullClaw ecosystem components. This allows the Web UI to interact with them through a single interface.

    • NullBoiler Proxy: Requests to /api/nullboiler/* are proxied via NULLBOILER_URL (e.g., http://localhost:8080) and an optional NULLBOILER_TOKEN.
    • NullTickets Store Proxy: Requests to /api/nulltickets/store/* are proxied via NULLTICKETS_URL and an optional NULLTICKETS_TOKEN.
    • NullWatch Proxy: Requests to /api/nullwatch/* are proxied to a managed NullWatch instance. You can override the target using NULLWATCH_URL and the token using NULLWATCH_TOKEN.

  4. How Mission Control works

    main

    Mission Control is a local replay and recovery workspace for NullHub. It provides a deterministic mission scenario using a versioned, built-in scenario fixture. This allows for a stable baseline state without requiring hosted services.

    When matching local instances of NullWatch or NullBoiler are running, Mission Control "hydrates" the scenario. This means it replaces fixture-only evidence with live trace and workflow evidence (such as real workflow run IDs and checkpoint metadata) in the UI and exported artifacts.

  5. Report Command Architecture

    main

    The reporting system is distributed across the CLI, API, and Web UI:

    • Core Logic (src/report.zig): Handles enums (ReportRepo, ReportType), system information collection, markdown body generation, and the GitHub submission fallback chain.
    • CLI Interface (src/report_cli.zig): Manages interactive stdin prompts, preview displays, $EDITOR integration, and flag-driven non-interactive execution.
    • API Layer (src/api/report.zig): Provides POST /api/report/preview and POST /api/report endpoints for JSON-based reporting.
    • Web UI (ui/src/routes/report/+page.svelte): A three-step Svelte form consisting of: Inputs $\rightarrow$ Preview (editable textarea) $\rightarrow$ Result.

  6. How the report CLI interactive flow works

    main

    The report_cli.run function manages an interactive or flag-driven workflow for reporting issues (bugs, features, etc.) to specific repositories.

    Interactive Mode (TTY)

    When running in a TTY, the CLI prompts the user for:

    1. Repository: Selection from supported repos (nullhub, nullclaw, nullboiler, nulltickets, nullwatch).
    2. Report Type: Selection from types (bug_crash, bug_behavior, regression, feature).
    3. Description: A text message describing the issue.

    After collection, it displays a Preview of the generated title and markdown body. The user can then:

    • Submit: Confirm with Y.
    • Cancel: Use n or N.
    • Edit: Use e or E to open the report body in the system's default editor (defined by the EDITOR environment variable, falling back to vi).

    Non-Interactive Mode (Non-TTY)

    If the input is not a TTY (e.g., a CI environment or piped input), all required information must be provided via CLI flags:

    • --repo
    • --type
    • --message

    If these flags are missing in non-interactive mode, the command returns an error.

    pub fn run(allocator: std.mem.Allocator, opts: cli.ReportOptions) !void {
    // ... logic for TTY detection and prompting ...
}

  7. Quick Start with NullHub

    main

    To build and run NullHub locally, use the Zig build system. This will compile the Zig backend and embed the Svelte web UI into a single binary.

    Once running, the server is accessible via several local hostnames. NullHub attempts to publish nullhub.local via dns-sd/Bonjour or avahi-publish if available.

    Access URLs:

    • http://nullhub.local:19800
    • http://nullhub.localhost:19800
    • http://127.0.0.1:19800
    zig build
./zig-out/bin/nullhub

  10. Set up a local NullWatch instance

    main

    To use the NullWatch Flight Recorder within NullHub, follow these steps:

    1. Start NullHub without automatically opening the browser:
      zig build run -- serve --no-open
    2. Open the Web UI in your browser.
    3. Navigate to Install Component.
    4. Select NullWatch.
    5. Set or keep the API port as 7710.
    6. Complete the wizard. The installer will start the NullWatch instance and the NullHub proxy will automatically discover it.
    zig build run -- serve --no-open

  12. Follow the NullHub TDD workflow

    main

    When contributing code or bug fixes, follow this Test-Driven Development (TDD) pattern:

    1. Identify: Pick one behavior, contract, or regression.
    2. Fail: Add a failing test that expresses the expected behavior.
    3. Implement: Make the smallest code change that makes the test pass.
    4. Validate: Run the smallest relevant validation first.
    5. Verify: Run the broader project gate before opening the PR.
    6. Document: If any validation steps are skipped, document why in the PR description.