Skip to content
View as Markdown

Driver Validation ​

The Muxit driver validator checks every driver source project against the canonical manifest schema. It runs as:

  • CLI — node drivers.js validate (interactive) or node drivers.js validate --all (headless)
  • Server — (Phase 3) DllDriverValidator.cs runs at driver scan and surfaces diagnostics in the Extensions panel
  • Release preflight — --strict mode blocks a release if any rule fails

Rule definitions live in lib/driver-manager/schema.js. Each rule has an id, severity, and message template.

CLI usage ​

bash
node drivers.js validate              # interactive — pick one driver
node drivers.js validate --all        # validate every driver in drivers/ + drivers/js/
node drivers.js validate --all --json # structured output for tooling
node drivers.js validate --all --strict  # soft warnings become blocking

Exit codes: 0 when no hard errors (soft warnings allowed unless --strict), 1 otherwise.

Severity ​

  • hard — validator exits non-zero; the driver is unfit to ship. The server (Phase 3) refuses to register the driver and surfaces an error badge in the Extensions panel.
  • soft — validator warns but exits zero. --strict elevates soft warnings to failures. Useful for marketplace hygiene (missing description, unknown tag, etc.).

Rules ​

Manifest basics ​

Rule IDSeverityFires when
MANIFEST_MISSINGhardmanifest.json does not exist next to the driver source
ID_MISSING / ID_INVALIDhardid missing or does not match the id regex
NAME_MISSINGhardname missing
VERSION_MISSING / VERSION_INVALIDhardversion missing or not semver x.y.z
ENTRYPOINT_MISSING / ENTRYPOINT_UNSAFEhardentryPoint missing, or contains / or ..
FORMAT_VERSION_INVALIDhardformatVersion != 1
CATEGORY_MISSING / CATEGORY_INVALIDhardcategory missing (C#) or not free/premium
TIER_INVALIDhardtier not 1 or 3
JS_PREMIUM_FORBIDDENhardJS driver declares category: "premium" — not supported

Premium integrity ​

Rule IDSeverityFires when
PREMIUM_NO_DRIVER_IDhardPremium manifest but no [assembly: DriverId(...)] in source
PREMIUM_DRIVER_ID_MISMATCHhard[DriverId] first arg disagrees with short id from manifest
PREMIUM_DRIVER_ID_HASH_MISMATCHhardAttribute hash or driverIdSha256 disagrees with expected SHA256("muxit.io:driverId:{shortId}")
PREMIUM_MANIFEST_HASH_MISSINGhardPremium manifest is missing driverIdSha256
FREE_HAS_DRIVER_IDsoft at build, hard at load on a signed DLLcategory: "free" but the source declares [assembly: DriverId(...)]

FREE_HAS_DRIVER_ID is worth a note, because it is the one rule whose severity depends on where it fires. The server does not take manifest.category as the answer to "is this driver licensed?" — the manifest is plain text inside the package, while the DLL and its signature are not. What the server uses instead is the pair a repackager cannot forge: an official muxit signature over the DLL, and an [assembly: DriverId] whose hash checks out. A package carrying both is licensed as premium whatever its manifest says.

So at build time a free manifest over a [DriverId] source is advice — the DLL is not signed yet and nothing is being bypassed. Once that package is signed and installed, the manifest is contradicting the package about something the server has already decided, and the runtime validator raises it as a hard error. Set category to premium.

C# source ​

Rule IDSeverityFires when
CSPROJ_MISSINGhardNo .csproj file in the driver project
CSPROJ_SDK_MISSINGhard.csproj does not reference Muxit.Driver.Sdk
DRIVER_CS_MISSINGsoftNo *Driver.cs file found
DRIVER_GROUP_MISSINGsoftNo [assembly: DriverGroup(...)] — UI falls back to Instruments

JS source ​

Rule IDSeverityFires when
JS_DEFAULT_EXPORT_MISSINGhardDriver file has no export default
JS_META_MISSINGhardDefault export has no meta section

Marketplace hygiene ​

Rule IDSeverityFires when
DESCRIPTION_MISSING / DESCRIPTION_SHORTsoftdescription missing or under 40 characters
TAGS_MISSING / TAGS_TOO_MANY / TAGS_UNKNOWNsoftTags missing, more than 8, or not in the tag vocabulary
AUTHOR_MISSINGsoftauthor.name missing
GROUP_MISSING / GROUP_INVALIDsoftManifest group missing or not in instruments/motion/communication/utilities

Revision history ​

Every driver keeps its own CHANGELOG.md — that is the driver's revision history, kept separate from the core revision-history.md. Driver changes go here, never in a core revision fragment.

Rule IDSeverityFires when
CHANGELOG_MISSINGsoftNo CHANGELOG.md alongside the driver source
CHANGELOG_VERSION_MISSINGsoftThe current manifest.version has no matching ## <version> section in CHANGELOG.md

The published version's section is rendered on the driver's registry detail page. tools/check-revision-scope.js (run in CI) additionally fails a driver-only change that adds a core revision fragment.

Runtime capability audit (server only) ​

Rule IDSeverityFires when
FREE_DRIVER_CAPABILITIESsoftFree DLL driver references sensitive .NET APIs (FileSystem, Network, Process, Reflection, Registry) — shown as an advisory in the Extensions panel
FREE_DRIVER_CAPABILITY_SCAN_FAILEDsoftFree DLL driver could not be statically analyzed (typically because an out-of-band dependency like System.IO.Ports isn't resolvable from the runtime dir). No capability claim is made; still advises caution

JSON output ​

bash
node drivers.js validate --all --json
json
{
  "results": [
    {
      "driver": { "name": "Avantes", "type": "csharp", "dir": "/.../Muxit.Driver.Avantes" },
      "errors": [],
      "warnings": []
    }
  ],
  "summary": { "errors": 0, "warnings": 0, "strict": false }
}

Downstream tools (release preflight, Development web GUI) consume this format directly.

Muxit — Hardware Orchestration Platform