Component Lifecycle

Install

wh component install <org/name> --repo org/repo

Only registered components (<org>/<name>) can be installed. To install your own component, register it first (wh component register <name> --org <org> --manifest <path>). The installer runs through these stages:

WarmHub’s own system components install the same way: the identity system is the registered component warmhub/identity. WarmHub-managed internal components are not installable.

1. Source resolution — Resolves the registered component reference to its latest published manifest snapshot from the component registry.

2. Parse and validate — Validates the resolved manifest’s JSON structure, required fields, and cross-references (for example, credentials and shapes referenced by subscriptions and seeds).

3. Ensure shared infrastructure — Creates the ComponentInstall and ComponentConfig shapes if they don’t already exist in the repo. These are system-managed shapes shared across all components.

4. Record install — Creates a ComponentInstall/<component-id> thing with state installing and the serialized manifest. This is the tracking record for all future operations.

5. Apply manifest-provisioned resources — In order:

   • Shapes: Created if they don’t exist. Tagged with the component’s ID.
   • Credential sets: Created if they don’t exist. Keys are declared but not populated — the user must set values after install.
   • Subscriptions: Manifest subscriptions are compiled into normal WarmHub webhook subscriptions, then bound to credential sets.
   • Seeds: Initial things created via a commit. Seeds targeting ComponentConfig and other shapes are batched.

   Resources marked provisioning: "setup" are skipped by the local installer and are expected to be created by the registered component’s setup callback.

6. Run registered setup — If a registered component advertises a setup endpoint, the CLI calls it after the local install succeeds. Setup-provisioned shapes, credential sets, and subscriptions are created by that external service.

7. Compute state — Checks whether all resources were created successfully. Sets the final state to ready when everything succeeded, or degraded when a resource failed. Missing credential values do not change the state — they surface as doctor findings instead.

8. Finalize — Updates the ComponentInstall record with the final state and a hash of the manifest for change detection.

Subscription compilation

The installer derives the effective subscription kind from trigger.kind:

• event triggers compile to normal webhook subscriptions with shape, filter, and webhookUrl

Component manifests declare webhook subscriptions only; handlers live outside the manifest and are referenced by webhook URL.

Reconciliation (reinstall)

If a component is already installed (a ComponentInstall record exists), the installer enters reconciliation mode:

• Missing resources are added — New shapes, subscriptions, and seeds from the updated manifest are created.
• Existing resources are preserved — The reconciler does not delete resources that were in the old manifest but absent from the new one.
• Seeds are updated — If a seed thing already exists, its data is revised to match the new manifest.
• Failed installs are retried — If the previous state was installing or error, the reconciler treats the old manifest as empty and retries all resources.
• Degraded installs are re-probed — If the previous state was degraded, the reconciler keeps the old manifest and probes the live resources, deciding per resource whether to add, revise, or update rather than retrying everything.
• Paused subscriptions are not automatically resumed — Reinstall adds missing subscriptions, but a subscription that still exists in paused state stays paused until you resume or recreate it yourself.
• Registered setup is replayed on update — wh component update for a registered install re-resolves the latest published manifest, reruns the local installer, and calls the setup endpoint again, bringing the component up to the latest published version.

Doctor

wh component doctor <org/name> --repo org/repo

Doctor checks an installed component against the manifest snapshot recorded for that install rather than your local files, so results reflect what is actually deployed. It checks:

Check	Pass	Fail
Shape exists and is active	ok	missing or inactive
Subscription exists and is active	ok	missing or inactive
Credential set exists with all required keys populated	ok	missing keys listed
Seed things exist	ok	missing

Doctor computes and persists the component state:

• All subscriptions paused, nothing else wrong → paused
• Missing resources, inactive non-subscription resources, or shape drift → degraded
• A mix of active and paused subscriptions does not by itself move the component out of ready
• Everything healthy → ready

Missing credential values are reported as doctor findings, but they do not change the component state — there is no credentials-required state. If a CLI method needs credentials that aren’t set, the call fails at invocation time with a precise error; populating those keys is the component setup’s job.

Teardown

wh component teardown <org/name> --repo org/repo

Teardown is a single, terminal operation. It:

• Pauses the component’s subscriptions.
• Revokes the install’s component tokens.
• Dispatches the uninstall callback, if the component declares an uninstall URL.
• Marks the install record uninstalled — a terminal state.

Teardown is terminal but non-destructive: it never retracts the component’s shapes or seeded data (only a repo hard-delete removes those), and the install record is retained.

To bring a torn-down component back, reinstall it. Reinstall revives the same install record; because subscriptions are left paused, a reinstall adds any missing ones but does not automatically resume subscriptions that still exist in paused state — resume or recreate those yourself:

wh sub resume <subscription-name> --repo org/repo

State transitions

install (new)     → installing → ready | degraded | error
install (exists)  → reconcile  → ready | degraded
doctor            →              ready | degraded | paused | uninstalled
teardown          →              uninstalled

Validate (offline)

wh component validate ./my-component

Runs all checks without connecting to a repo:

• JSON syntax and schema validation
• Cross-reference checks (credential refs, shape refs)
• Duplicate name detection
• Subscription trigger and webhook validation
• Component ID format
• Consistency between component.json and manifest.json