hassio-addon-blocky: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Home Assistant Add-on wrapping Blocky, a DNS proxy and ad-blocker in Go. The add-on is a containerized integration layer: shell scripts + Tempio templates that translate Home Assistant config into Blocky's native YAML. No Go compilation — pre-built binaries are downloaded during Docker build.

Blocky version is pinned via BLOCKY_VERSION ARG in blocky/Dockerfile.

Development Commands

# Build (from repo root)
docker build --build-arg BUILD_ARCH=amd64 -t blocky-addon blocky

# Lint (matches CI)
hadolint blocky/Dockerfile
pnpm lint:shell         # ShellCheck over every shell script (rootfs + scripts/), same list as CI

# Test (from repo root)
pnpm check              # all three checks: contracts + guards + render
                        # render runs bare on Linux, auto-dispatched to Docker on macOS
pnpm check:contracts    # static three-file parity (options/schema/translations/template)
pnpm check:guards       # runtime guard functions vs committed render goldens
pnpm check:render       # real tempio+blocky render vs goldens; Linux only
                        # (on macOS it refuses with a Docker hint — use `pnpm check`)
pnpm check:release-notes # release tooling: preset/writer render real notes
                         # (not part of `pnpm check` — release tooling, not the pipeline)

# Release (semantic-release via pnpm)
pnpm release:dry-run    # preview what would be released
pnpm release            # create release (CI runs this via workflow_dispatch)

# Inside a running container — test template rendering
tempio -conf /data/options.json -template /usr/share/tempio/blocky.gtpl -out /etc/blocky/config.yml
blocky validate --config /etc/blocky/config.yml
curl http://localhost:4000/api/blocking/status

Architecture

User configures in HA UI
        ↓
blocky/config.yaml          — schema, defaults, validation rules
blocky/translations/en.yaml — UI field descriptions
        ↓
blocky/rootfs/usr/share/tempio/blocky.gtpl  — Go/Tempio template: HA options → Blocky YAML
        ↓
blocky/rootfs/etc/cont-init.d/config.sh     — runs template (or copies custom config)
blocky/rootfs/etc/services.d/blocky/run     — starts Blocky with generated config
blocky/rootfs/etc/services.d/blocky/finish  — handles crashes, prevents restart loops
        ↓
Blocky binary (DNS on :53, HTTP API on :4000)
        ↓
blocky/rootfs/etc/services.d/upstream-probe/run — Probe: queries through /api/query,
                                                  logs upstream reachability, never enforces (ADR-0012)