@signapps/ha-tooling

The release CLI and build engine for modules and customers. It scaffolds authoring trees, versions and packages releases, drives the CI build/publish pipeline, and runs the compose step that turns module + customer sources into a deployable Home Assistant config.

• Workspace: packages/ha-tooling
• Depends on: @signapps/artifact-storage, tar, archiver, yaml
• Bin: ha-tooling → dist/cli.js

See also

The end-to-end deploy story (git tags, CI, registry, and the guided pnpm deploy:* wrappers) lives in Releases & deploys. This page documents the package itself.

CLI commands

Command	Root script	What it does
create-module <name>	pnpm create:module	Scaffold a module tree + draft registry entry
create-customer <name>	pnpm create:customer	Scaffold a customer tree + draft entry
add-customer-overlay <customer> <module>	pnpm add:customer-overlay	Add a module override skeleton under the customer
release <module> [--bump …]	pnpm module:release	Version, package, store, and register a module
release-customer <key> [--bump …]	pnpm customer:release	Same, for a customer
build-module / build-customer	—	CI: build the artifact only (no secrets)
publish-module / publish-customer	—	CI: publish a built artifact to R2 + API
parse-release-tag	—	Parse a git tag into kind/name/version/channel

Common flags: --bump major|minor|patch, --version X.Y.Z, --channel stable|beta|alpha, --force, --skip-registry.

Release flow

releaseModule() / releaseCustomer() follow the same shape:

• sourceHash is computed by recursively hashing file paths + contents (skipping version-history dirs and catalog files). If it's unchanged from the latest published version, the release is skipped unless --force.
• Version selection: explicit --version wins; otherwise --bump bumps the latest published version; otherwise it auto patch-bumps. The next version must not already be published (unless --force).
• Versioning lives in semver.ts (bumpVersion, compareVersions).

Compose pipeline

Called by the API server (not the CLI), composeCustomerBuild() turns resolved module versions + a customer into a device-deployable HA config:

Authoring layout

Modules and customers are authored on disk under home-assistant/:

home-assistant/modules/<name>/        module.yaml, defaults.yaml, packages/…
home-assistant/customers/<key>/       customer.yaml, automations.yaml,
                                      scenes.yaml, house_registry.yaml,
                                      extensions/<module>/  (overlays)

module.yaml / customer.yaml hold the authored version + channel (updated during release).

Environment

Variable	Purpose
ARTIFACT_STORAGE_MODE	local or s3 (default s3)
ARTIFACT_STORAGE_PATH	Local artifacts dir (default home-assistant/.local-artifacts)
PUBLISHER_MODULE_TOKEN / PUBLISHER_CUSTOMER_TOKEN	Scoped tokens for publish (CI)
R2_*	R2 credentials when publishing