feat: add introspect module with commands endpoint

[raman325]

Summary

• Adds a new introspect command module following the existing module pattern (node, controller, etc.)
• introspect.commands returns the full JSON Schema (Draft 7) describing all incoming message types
• Works before initialize, enabling API discovery pre-negotiation
• Schema is generated at build time via ts-json-schema-generator and served at runtime
• Interfaces renamed for $ref reuse in the generated schema (189KB vs 307KB)

Changes

• src/lib/introspect/ — new module with command, incoming_message, outgoing_message, message_handler
• src/lib/instance.ts — register introspect instance
• src/lib/command.ts — export IntrospectCommand
• src/lib/incoming_message.ts — add IncomingMessageIntrospect to union
• src/lib/outgoing_message.ts — add IntrospectResultTypes to result types
• src/lib/server.ts — wire IntrospectMessageHandler into instance handlers
• Interface renames in node, driver, controller, multicast_group incoming messages for $ref reuse
• package.json — add ts-json-schema-generator, generate:schema script, prebuild hook
• README.md — add introspection section with tool recommendations

Test plan

• npm test passes (schema generation, prettier, tsc, lint, integration tests)
• Send {"messageId": "1", "command": "introspect.commands"} before initialize — returns valid JSON Schema
• Returned schema validates actual command messages correctly

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an introspect module to enable API discovery by exposing a build-time generated JSON Schema for all incoming message types, accessible before initialize.

Changes:

• Introduces src/lib/introspect/* (command, message types, handler) and registers it as a new instance in the server routing.
• Extends incoming/outgoing type unions and exports to include introspection and renames several incoming-message interfaces to improve $ref reuse in the generated schema.
• Adds ts-json-schema-generator with generate:schema/prebuild hooks, updates docs, and git-ignores the generated schema output directory.

Reviewed changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/lib/server.ts	Registers the new introspect instance handler in the per-client instance handler map.
src/lib/outgoing_message.ts	Adds IntrospectResultTypes into the global result type union.
src/lib/node/incoming_message.ts	Renames several node incoming-message interfaces for improved schema $ref reuse and updates the union.
src/lib/multicast_group/incoming_message.ts	Renames the multicast group getDefinedValueIDs incoming-message interface and updates the union.
src/lib/introspect/outgoing_message.ts	Defines result types for introspect.commands.
src/lib/introspect/message_handler.ts	Implements the handler that returns the generated incoming-message JSON schema.
src/lib/introspect/incoming_message.ts	Defines incoming message type(s) for the new introspect module.
src/lib/introspect/command.ts	Defines the new IntrospectCommand enum.
src/lib/instance.ts	Adds introspect to the Instance enum for routing.
src/lib/incoming_message.ts	Adds IncomingMessageIntrospect to the top-level incoming message union.
src/lib/driver/incoming_message.ts	Renames driver incoming-message interfaces for schema $ref reuse and updates the union.
src/lib/controller/incoming_message.ts	Renames the controller firmware update “in progress” incoming-message interface and updates the union.
src/lib/command.ts	Exports IntrospectCommand (and ZnifferCommand) from the central command export module.
package.json	Adds schema generation tooling and hooks (generate:schema, prebuild) and runs generation in npm test.
package-lock.json	Locks the new ts-json-schema-generator dependency tree.
README.md	Documents the introspection capability and usage guidance.
.gitignore	Ignores /src/lib/generated/ where the schema is written.

Comments suppressed due to low confidence (1)

package.json:44

• IntrospectMessageHandler imports ../generated/incoming_message_schema.json, but the build pipeline (tsc + esm2cjs) does not copy JSON assets into dist-esm/dist-cjs. Since the published package only includes dist-* (see files), this will likely fail at runtime with a missing module. Consider adding a postbuild step to copy src/lib/generated/incoming_message_schema.json into dist-esm/lib/generated/ (and the CJS output), or generate the schema directly into the dist folders as part of the build.

    "test": "npm run generate:schema && prettier --check src && tsc --noEmit && npm run lint && tsx src/test/integration.ts",
    "generate:schema": "ts-json-schema-generator --path src/lib/incoming_message.ts --type IncomingMessage --tsconfig tsconfig.json --out src/lib/generated/incoming_message_schema.json",
    "prebuild": "npm run generate:schema",
    "build": "tsc -p .",
    "postbuild": "esm2cjs --in dist-esm --out dist-cjs -l error -t node20",
    "prepare": "npm run build",
    "prepublishOnly": "rm -rf dist-* && npm run build"

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The JSON import uses the newer import-attributes syntax (with { type: "json" }). Node 20 commonly supports JSON imports via assert { type: "json" }, but may not support the with form depending on the exact runtime version, which could make the server fail to start. Consider switching to the widely-supported assert { type: "json" } syntax for Node 20, or loading the JSON via fs/createRequire to avoid reliance on import attributes syntax evolution.

Suggested change

	import incomingMessageSchema from "../generated/incoming_message_schema.json" with { type: "json" };
	import incomingMessageSchema from "../generated/incoming_message_schema.json" assert { type: "json" };

[AlCalzone]

@raman325 The comment from Copilot here is a valid concern. If we want to use the with syntax (which is the standard way forward), we need to bump to Node.js 22 minimum.

[raman325]

if we bump to 22 here, we'd probably need to do the same in zwave-js-ui since it creates a server instance in code - is that preferred or should we stick with the deprecated syntax for now?

[AlCalzone]

AFAIK assert will be a SyntaxError on Node 22+. So I think there's no way around bumping and making a major version.

[AlCalzone]

Alternatively, can we just use node:fs/promises and await readFile instead?

[raman325]

Switched to readFile with caching per AlCalzone's suggestion in 1feec11. Also added a build copy step so the generated JSON lands in dist-esm/lib/generated/ (tsc doesn't emit it on its own). The existing createRequire usages in const.ts and server.ts are fine — they load package.json from the project root and user config paths, which are always present at runtime.

[raman325]

I made it simpler - convert the json to TS and then just import it. We keep the JSON in case it's useful for development workflows

[AlCalzone]

Curious, how does this feature take the minimum schema version for some commands into account?

[AlCalzone]

@raman325 The comment from Copilot here is a valid concern. If we want to use the with syntax (which is the standard way forward), we need to bump to Node.js 22 minimum.

[raman325]

Curious, how does this feature take the minimum schema version for some commands into account?

right now it doesn't and we haven't really encoded schema versioning into commands. We don't actually gate commands by schema, the only thing we do is add logic to make returns backwards compatible if something changes in the API.

Realistically, I am not sure how valuable being able to filter by schema version for commands is as helpful as e.g. seeing events and states for a given schema version. I was planning to add it for states because it's easy enough, we have all the types defined. Will hvae to work through how to do it for events and how it could be implemented for commands

[AlCalzone]

One more thing.