hbsguard

Template problems deserve first-class feedback.

Handlebars templates can accumulate small structural and formatting mistakes that are easy to miss in review and awkward to check consistently across a repository. The useful answer was not a formatter or a broad framework. It was a narrow verification tool that understands Handlebars syntax, reports exactly where a problem occurred, and behaves predictably in local development and automated checks.

hbsguard treats linting as inspection. It reads source, resolves configuration, and returns diagnostics; it never rewrites a template. That boundary makes it safer to add to an existing codebase and easier to trust as a step used by people or coding agents.

One product, from parser behavior to presentation.

I created the package and its public experience end to end: the lint rules and configuration model, file discovery and command-line behavior, programmatic API, diagnostic formats, test suite, documentation, identity, and browser playground.

The design work was part of the engineering work. Error messages, exit codes, defaults, examples, and the Playground’s split between source, problems, and resolved configuration all shape whether the tool is understandable in practice.

The same semantics across files, APIs, and the browser.

• Handlebars-aware parsing. Parse failures are reported independently of configured style rules, and diagnostics retain source locations and context.
• Repository-scale input. The CLI accepts globs, files, and directories, normalizes path forms across platforms, and applies built-in and project-specific ignores.
• Composable core. Text linting is browser-safe, while file discovery and CLI concerns stay in Node-specific modules.
• Owned editor grammar. The Playground uses a generated, project-owned Handlebars grammar for syntax-aware editing rather than treating templates as generic HTML.
• Behavioral coverage. Tests exercise rules, configuration, formatting, file discovery, CLI contracts, Playground state, browser behavior, and the static build.

Show the problem, then make the system inspectable.

The Playground opens with a deliberately flawed “kitchen sink” template so the product explains itself through use. Diagnostics are navigable and tied to source positions. Presets, live overrides, available rules, and the fully resolved configuration remain visible as separate concepts, turning configuration from a hidden mechanism into something a person can understand and copy.

Responsive light and dark themes keep the dense editor-and-results layout legible, while the visual identity stays warm and restrained enough to support long technical sessions.