Docskurby Output

Core Directive: @h-rig/core is a configuration and plugin composition library facilitating Rig’s specific OMP extension ecosystem. It acts as the task-graph engine and plugin host, strictly separating static metadata from executable runtime components.

🚀 Quick Start

• Plugin Authoring: Use definePlugin(meta, runtime?) to export a RigPluginWithRuntime that enforces static vs. executable parity.
• Config Assembly: Use defineConfig(cfg) to load and validate configurations while preserving runtime functions across effect schema boundaries.
• Engine Core: No app-shell assumptions. Keep reducers (engineReadModelReducer) and graph traversals (taskGraph) pure and reusable across CLI, desktop, and UI.

🔧 Configuration & Architecture

• Bifurcated Plugin Model: Plugins consist of Schema-validated static metadata (contributes) and an optional executable __runtime map.
• Host Aggregation: createPluginHost(plugins) indexes all validators, hooks, skills, and task sources, flattening them into querying registries.
• Task Graph Engine: Graph logic (computeTaskBlockingDepths, computeTaskDependencyBadges) uses cycle-safe memoized DFS to manage task dependencies, blocking statuses, and priority-based selection.

📦 Dependencies

• @rig/contracts: Interfaces and schema definitions.
• effect: Used for robust schema definition, decoding, and validation (Schema.decodeUnknownSync).

💡 Best Practices (Patterns)

• Strict Runtime-Metadata Parity: Ensure every executable item in __runtime has an exact corresponding metadata entry in contributes with identical IDs, kinds, and categories.
• Pure Configuration Assembly: Use pure builders (buildRigInitConfigSource) without FS or Node dependencies to allow safe bundling in both CLI and Web/Vite environments.
• Graceful Auto-Defaults: Wrap all incoming configuration in applyConfigDefaults() before decoding to ensure minimal configurations work out-of-the-box (e.g., auto-filling plugins: [] or normalizing workspace.checkout).
• Resilient Dependency Resolution: Fallback task dependency matching across exactId -> sourceIssueId -> externalId to bridge external trackers smoothly.

🚨 Gotchas / Anti-Patterns (Warnings)

• Losing Runtime Objects: Never pass config directly to Schema.decodeUnknownSync. This strips unknown fields and silently deletes the __runtime executable bits; always use defineConfig which reattaches them.
• Dual Hook Implementations: Defining both a command string (in metadata) and a typed function (in __runtime.hooks) for the same hook is an anti-pattern and triggers a crash. Pick one.
• Missing Implementations: Declaring an executable runtime category without supplying the implementations for all metadata entries of that category throws validation errors.
• Duplicate Registration: Reusing plugin names, contribution IDs, or task source kinds across the ecosystem throws explicit duplicate registration errors at host creation time.