Implemented the capability registry module for the GuildPass SDK.

[Brainoncrack]

Description

Semver impact: minor

Linked Issue

Closes #455

Type of Change

• ✨ New feature / method (minor)

Changes Made

• src/capabilities/types.ts - Core type definitions (CapabilityDefinition, CapabilitySnapshot, RegistryOptions)
• src/capabilities/errors.ts - Custom error classes for validation failures
• src/capabilities/versionUtils.ts - Self-contained semantic version comparison utilities
• src/capabilities/CapabilityRegistry.ts - Main registry class with validation and immutability
• src/capabilities/index.ts - Module exports
• src/index.ts - Added capabilities module export
• tests/capabilities.test.ts - Comprehensive unit tests (46 test cases)

Public API Changes

// New exports:
export interface CapabilityDefinition {
  id: string;
  version: string;
}

export interface CapabilitySnapshot {
  readonly capabilities: ReadonlyMap<string, Readonly<CapabilityDefinition>>;
  readonly orderedIds: ReadonlyArray<string>;
}

export interface RegistryOptions {
  duplicatePolicy?: 'error' | 'ignore' | 'replace';
}

export class CapabilityRegistry {
  constructor(options?: RegistryOptions);
  register(definition: CapabilityDefinition): void;
  registerBatch(definitions: readonly CapabilityDefinition[]): void;
  hasCapability(id: string): boolean;
  getCapabilityVersion(id: string): string | undefined;
  satisfiesMinimumVersion(id: string, minimumVersion: string): boolean;
  listCapabilities(): readonly string[];
  listDefinitions(): readonly CapabilityDefinition[];
  size(): number;
  createSnapshot(): CapabilitySnapshot;
  clear(): void;
  static fromSnapshot(snapshot: CapabilitySnapshot): CapabilityRegistry;
}

export class InvalidCapabilityIdentifierError extends CapabilityError;
export class InvalidCapabilityVersionError extends CapabilityError;
export class DuplicateCapabilityError extends CapabilityError;

export function parseVersion(version: string): ParsedVersion;
export function compareVersions(versionA: string, versionB: string): number;
export function satisfiesMinimumVersion(versionA: string, versionB: string): boolean;
export function isValidVersion(version: string): boolean;

Test Evidence

pnpm test output:
✓ tests/capabilities.test.ts (46 tests) 47ms

Test Files  18 passed (18) 
     Tests  473 passed (473)

Build Evidence

pnpm build output:
$ tsc --noEmit
$ tsup
ESM dist/index.js     49.97 KB
ESM dist/index.js.map 129.05 KB
ESM ⚡️ Build success in 324ms
DTS Build start
DTS ⚡️ Build success in 1967ms
DTS dist/index.d.ts 40.47 KB

Checklist

• I have read CONTRIBUTING.md
• This PR is linked to an open issue
• pnpm typecheck passes
• pnpm lint passes
• pnpm test:run passes — all tests green
• pnpm build succeeds — dist/ generated cleanly
• All new public methods/types have TypeDoc comments
• New behaviour is covered by at least one Vitest unit test
• No new runtime dependencies added without prior maintainer approval
• docs/ updated if public API changed
• examples/ updated if new usage patterns were added
• Backwards compatibility maintained (or breaking change clearly noted above)

Additional Notes

The capability registry is fully independent of transport, API, or server changes as required. It provides:

• Strict validation of capability identifiers (lowercase alphanumeric with dot separators)
• Semantic version validation and comparison
• Configurable duplicate handling policies
• Deterministic alphabetical ordering
• Immutability protection against caller input mutation
• Snapshot support for state preservation
• Comprehensive test coverage including edge cases