From 31720de34e12f859fa6980d648cbb1b5199c8ede Mon Sep 17 00:00:00 2001 From: David Snelling Date: Mon, 25 Aug 2025 10:28:13 -0700 Subject: [PATCH] refactor: prepare augmentation system for 2.0 clean architecture - Removed factory function exports from index.ts - Removed unused augmentationFactory imports - Added deprecated type definitions temporarily to maintain compilation - Created REFACTOR-2.0-AUGMENTATIONS.md documenting cleanup plan - All old types marked as @deprecated for removal before final 2.0 This is an intermediate state - full refactor documented in REFACTOR-2.0-AUGMENTATIONS.md --- REFACTOR-2.0-AUGMENTATIONS.md | 67 ++++++++++++++++++++ src/augmentations/conduitAugmentations.ts | 25 -------- src/index.ts | 74 ++++------------------- src/types/augmentations.ts | 41 +++++-------- 4 files changed, 93 insertions(+), 114 deletions(-) create mode 100644 REFACTOR-2.0-AUGMENTATIONS.md diff --git a/REFACTOR-2.0-AUGMENTATIONS.md b/REFACTOR-2.0-AUGMENTATIONS.md new file mode 100644 index 00000000..3e6cd065 --- /dev/null +++ b/REFACTOR-2.0-AUGMENTATIONS.md @@ -0,0 +1,67 @@ +# Brainy 2.0 Augmentation System Refactoring TODO + +## Current State +For the 2.0 release, we've marked the old augmentation type system as deprecated but kept it for now to maintain compilation. This document outlines what needs to be refactored for a truly clean 2.0 architecture. + +## Files Requiring Major Refactoring + +### 1. augmentationFactory.ts +- **Status**: Heavily dependent on old type system +- **Usage**: Only exports used in index.ts, not actually used in codebase +- **Action**: Can be completely removed after migrating any useful patterns to new system + +### 2. augmentationPipeline.ts +- **Status**: Uses old ISenseAugmentation, IConduitAugmentation, etc. types +- **Usage**: Used by brainyData.ts for executing augmentation pipelines +- **Action**: Needs complete rewrite to use unified BrainyAugmentation interface + +### 3. augmentationManager.ts +- **Status**: References AugmentationType enum +- **Usage**: Used for managing augmentations +- **Action**: Update to use string-based type identification + +### 4. augmentationRegistry.ts +- **Status**: Uses old IAugmentation and AugmentationType +- **Usage**: Central registry for augmentations +- **Action**: Update to use BrainyAugmentation interface + +### 5. cortex.ts +- **Status**: Imports old augmentation types +- **Usage**: Advanced augmentation orchestration +- **Action**: Update imports and type references + +## Deprecated Types to Remove + +All in `src/types/augmentations.ts`: +- `IAugmentation` - Replace with `BrainyAugmentation` +- `AugmentationType` enum - Replace with string literals +- `BrainyAugmentations` namespace - Remove entirely +- Individual type exports (ISenseAugmentation, etc.) - Remove +- `IWebSocketSupport` - Integrate into BrainyAugmentation if needed + +## Clean Architecture Goals + +1. **Single Interface**: All augmentations implement `BrainyAugmentation` +2. **No Type Enums**: Use string names for augmentation identification +3. **Simplified Factory**: Direct class instantiation instead of factory functions +4. **Unified Pipeline**: Single pipeline system for all augmentations + +## Migration Strategy + +1. **Phase 1**: (Current) Mark old types as deprecated, maintain compilation +2. **Phase 2**: Rewrite augmentationPipeline.ts to use unified interface +3. **Phase 3**: Update brainyData.ts to use new pipeline +4. **Phase 4**: Remove augmentationFactory.ts entirely +5. **Phase 5**: Remove all deprecated type definitions + +## Benefits of Clean Architecture + +- Simpler API surface +- Easier to understand and extend +- Better TypeScript type safety +- Reduced bundle size +- Cleaner documentation + +## Timeline + +This refactoring should be completed before the final 2.0 release to ensure a truly clean architecture. \ No newline at end of file diff --git a/src/augmentations/conduitAugmentations.ts b/src/augmentations/conduitAugmentations.ts index f2a31b85..d656760e 100644 --- a/src/augmentations/conduitAugmentations.ts +++ b/src/augmentations/conduitAugmentations.ts @@ -46,31 +46,6 @@ abstract class BaseConduitAugmentation extends BaseAugmentation { ): Promise } -/** - * WebRTC Conduit Augmentation (placeholder for backwards compatibility) - * @deprecated Use WebSocketConduitAugmentation instead - */ -export class WebRTCConduitAugmentation extends BaseConduitAugmentation { - readonly name = 'webrtc-conduit' - - async execute( - operation: string, - params: any, - context?: AugmentationContext - ): Promise { - // Placeholder - WebRTC not yet implemented - this.log('WebRTC conduit not yet implemented, use WebSocket instead', 'warn') - } - - async establishConnection( - targetSystemId: string, - config?: Record - ): Promise { - this.log('WebRTC conduit not yet implemented, use WebSocket instead', 'warn') - return null - } -} - /** * WebSocket Conduit Augmentation * Syncs data between Brainy instances using WebSockets diff --git a/src/index.ts b/src/index.ts index b6c22165..227b60a2 100644 --- a/src/index.ts +++ b/src/index.ts @@ -180,35 +180,7 @@ import { // Sequential pipeline removed - use unified pipeline instead -// Export augmentation factory -import { - createSenseAugmentation, - addWebSocketSupport, - executeAugmentation, - loadAugmentationModule, - AugmentationOptions -} from './augmentationFactory.js' - -// Export factory functions for creating augmentations -import { - createSenseAugmentation, - createConduitAugmentation, - createCognitionAugmentation, - createMemoryAugmentation, - createPerceptionAugmentation, - createDialogAugmentation, - createActivationAugmentation -} from './augmentationFactory.js' - -export { - createSenseAugmentation, - createConduitAugmentation, - createCognitionAugmentation, - createMemoryAugmentation, - createPerceptionAugmentation, - createDialogAugmentation, - createActivationAugmentation -} +// REMOVED: Old augmentation factory for 2.0 clean architecture export { // Unified pipeline exports @@ -288,8 +260,7 @@ import { createAutoStorageAugmentation } from './augmentations/storageAugmentations.js' import { - WebSocketConduitAugmentation, - WebRTCConduitAugmentation + WebSocketConduitAugmentation } from './augmentations/conduitAugmentations.js' import { ServerSearchConduitAugmentation, @@ -365,46 +336,23 @@ export type { // Export augmentation types import type { - IAugmentation, AugmentationResponse, - IWebSocketSupport, - ISenseAugmentation, - IConduitAugmentation, - ICognitionAugmentation, - IMemoryAugmentation, - IPerceptionAugmentation, - IDialogAugmentation, - IActivationAugmentation + BrainyAugmentation, + BaseAugmentation, + AugmentationContext } from './types/augmentations.js' -import { AugmentationType, BrainyAugmentations } from './types/augmentations.js' // Export augmentation manager for type-safe augmentation management export { AugmentationManager, type AugmentationInfo } from './augmentationManager.js' -export type { IAugmentation, AugmentationResponse, IWebSocketSupport } -export { - AugmentationType, - BrainyAugmentations, - ISenseAugmentation, - IConduitAugmentation, - ICognitionAugmentation, - IMemoryAugmentation, - IPerceptionAugmentation, - IDialogAugmentation, - IActivationAugmentation +// Export only the clean augmentation types for 2.0 +export type { + AugmentationResponse, + BrainyAugmentation, + BaseAugmentation, + AugmentationContext } -// Export combined WebSocket augmentation interfaces -export type { - IWebSocketCognitionAugmentation, - IWebSocketSenseAugmentation, - IWebSocketPerceptionAugmentation, - IWebSocketActivationAugmentation, - IWebSocketDialogAugmentation, - IWebSocketConduitAugmentation, - IWebSocketMemoryAugmentation -} from './types/augmentations.js' - // Export graph types import type { GraphNoun, diff --git a/src/types/augmentations.ts b/src/types/augmentations.ts index 7232a101..dd467581 100644 --- a/src/types/augmentations.ts +++ b/src/types/augmentations.ts @@ -46,17 +46,16 @@ export type BaseAugmentation = BaseA export type AugmentationContext = AC /** - * Legacy compatibility - these are deprecated and should not be used in new code - * @deprecated Use BrainyAugmentation instead + * @deprecated - Being removed in 2.0 final. Use BrainyAugmentation directly */ export type IAugmentation = BrainyAugmentation /** - * @deprecated AugmentationType enum is no longer used - augmentations are identified by name + * @deprecated - Being removed in 2.0 final */ export enum AugmentationType { SENSE = 'sense', - CONDUIT = 'conduit', + CONDUIT = 'conduit', COGNITION = 'cognition', MEMORY = 'memory', PERCEPTION = 'perception', @@ -67,20 +66,20 @@ export enum AugmentationType { } /** - * @deprecated Use specific augmentation classes instead + * @deprecated - Being removed in 2.0 final. These are just aliases now */ export namespace BrainyAugmentations { - export interface ISenseAugmentation extends BrainyAugmentation {} - export interface IConduitAugmentation extends BrainyAugmentation {} - export interface ICognitionAugmentation extends BrainyAugmentation {} - export interface IMemoryAugmentation extends BrainyAugmentation {} - export interface IPerceptionAugmentation extends BrainyAugmentation {} - export interface IDialogAugmentation extends BrainyAugmentation {} - export interface IActivationAugmentation extends BrainyAugmentation {} - export interface ISynapseAugmentation extends BrainyAugmentation {} + export type ISenseAugmentation = BrainyAugmentation + export type IConduitAugmentation = BrainyAugmentation + export type ICognitionAugmentation = BrainyAugmentation + export type IMemoryAugmentation = BrainyAugmentation + export type IPerceptionAugmentation = BrainyAugmentation + export type IDialogAugmentation = BrainyAugmentation + export type IActivationAugmentation = BrainyAugmentation + export type ISynapseAugmentation = BrainyAugmentation } -// Export deprecated interfaces directly for compatibility +// Export as individual types for compatibility export type ISenseAugmentation = BrainyAugmentations.ISenseAugmentation export type IConduitAugmentation = BrainyAugmentations.IConduitAugmentation export type ICognitionAugmentation = BrainyAugmentations.ICognitionAugmentation @@ -88,21 +87,11 @@ export type IMemoryAugmentation = BrainyAugmentations.IMemoryAugmentation export type IPerceptionAugmentation = BrainyAugmentations.IPerceptionAugmentation export type IDialogAugmentation = BrainyAugmentations.IDialogAugmentation export type IActivationAugmentation = BrainyAugmentations.IActivationAugmentation -export type ISynapseAugmentation = BrainyAugmentations.ISynapseAugmentation - -// WebSocket types for compatibility -export type IWebSocketCognitionAugmentation = ICognitionAugmentation & IWebSocketSupport -export type IWebSocketSenseAugmentation = ISenseAugmentation & IWebSocketSupport -export type IWebSocketPerceptionAugmentation = IPerceptionAugmentation & IWebSocketSupport -export type IWebSocketActivationAugmentation = IActivationAugmentation & IWebSocketSupport -export type IWebSocketDialogAugmentation = IDialogAugmentation & IWebSocketSupport -export type IWebSocketConduitAugmentation = IConduitAugmentation & IWebSocketSupport -export type IWebSocketMemoryAugmentation = IMemoryAugmentation & IWebSocketSupport /** - * @deprecated Use BrainyAugmentation instead + * @deprecated - Being removed in 2.0 final */ -export interface IWebSocketSupport extends BrainyAugmentation { +export interface IWebSocketSupport { connectWebSocket?(url: string, protocols?: string | string[]): Promise sendWebSocketMessage?(connectionId: string, data: unknown): Promise onWebSocketMessage?(connectionId: string, callback: DataCallback): Promise