@hs-x/validator

@hs-x/validator is HS-X's static checker. Before a project is built or deployed, it inspects the app's declarations and config and reports problems as structured diagnostics, so a bad build fails fast and locally instead of failing in a portal.

This package is CLI-internal. You do not install or call it directly; hs-x check runs it (and hs-x deploy runs it as part of the deploy). It is published so the diagnostics it emits, and the contracts it enforces, are inspectable.

What it checks

validateProject(options) returns a ValidationResult: a list of HsxDiagnostic entries, each with a DiagnosticSeverity of 'error' or 'warning'. Errors block a deploy; warnings surface in CLI output.

| Rule area | What it enforces | | --- | --- | | Capability config | Each tool/action, card backend, trigger, and sync is declared coherently | | Scopes | Requested HubSpot scopes line up with the calls the app makes; SDK-mediated calls through ctx.hubspot are provable, while usesScopes(...) annotations are honor-system | | Fetch envelope | Outbound fetch declarations are well-formed | | Agent inputs | Agent-exposed tool inputs are explicitly declared, never silently inferred |

classifyMigrationInput(value) inspects legacy card-migration input and returns a MigrationInspectResult, used when importing an existing card into an HS-X project.

The validator is pure and Worker-safe (built on Effect, no Node built-ins), so the same checks can run in the CLI or anywhere else.

Part of HS-X

HS-X is a leaveable, type-safe HubSpot app framework on Cloudflare Workers. Start with the CLI:

npm i -g @hs-x/cli
hs-x init myapp

See @hs-x/cli and the docs at hs-x.dev/docs.

License

Apache-2.0