Command registry practice

Updated Jul 27, 2026

Roadmap item 1.2.1 introduces shared command contracts and deterministic registry APIs. Follow these rules for command-system changes:

  • Define command contracts in shared/src/types/commands.ts and import them via @shared/types/commands from runtime modules.
  • Keep registry implementations deterministic by returning list() output in a stable order (CommandId lexical ordering).
  • When a command includes argsSchema, validate arguments via registry helpers and return structured CommandValidationError objects with code, commandId, and schema issues.
  • Preserve compatibility surfaces used by current runtime/plugin paths (registerCommandHandlers, getCommandHandler, and getRegisteredKeys) until dispatcher migration milestones replace those entry points.
  • Use detectKeybindingConflicts(...) in app/runtime/plugin-runtime.ts when testing exact shortcut collisions after precedence merges; the helper reports deterministic conflicts for remaining duplicate shortcuts.
  • Add or update unit coverage in test/unit/command-registry.test.ts and test/unit/command-registry-validation.test.ts for create, read, update, and delete (CRUD) semantics, deterministic ordering, compatibility aliases, invalid-schema handling, validator-cache invalidation, and validation error behaviour.
  • Add or update precedence/conflict coverage in test/unit/runtime-plugin-settings.test.ts when changing runtime keybinding merge or conflict-detection behaviour.