eai-cli 0.0.0-bootstrap.0

package/resources/gofer/memory/diagrams/di-container.mmd

@@ -0,0 +1,321 @@
+```mermaid
+classDiagram
+    class Container {
+        <<Singleton>>
+        +registerSingleton(service)
+        +resolve(service)
+        +clearInstances()
+    }
+
+    %% Core Infrastructure Services
+    class Logger {
+        <<Injectable Singleton>>
+        +error(context, error, metadata)
+        +warn(context, message, metadata)
+        +info(context, message, metadata)
+        +debug(context, message, metadata)
+    }
+
+    class StateManager {
+        <<Injectable Singleton>>
+        -logger: Logger
+        +getState()
+        +setState(state)
+        +updateState(partial)
+        +resetState()
+    }
+
+    class DisposalService {
+        <<Injectable Singleton>>
+        -logger: Logger
+        +dispose(resources, workspacePath)
+        -disposeResource(resource)
+    }
+
+    %% Extension Services (Phase 3)
+    class EventHandlers {
+        <<Injectable Singleton>>
+        -logger: Logger
+        +registerHandlers(context)
+        -onWorkspaceFoldersChanged()
+        -onTextEditorChanged()
+        -onTextDocumentSaved()
+    }
+
+    class InitializationService {
+        <<Injectable Singleton>>
+        -logger: Logger
+        +initializeForWorkspace(context)
+        -setupMemoryManager()
+        -setupProgressProvider()
+        -setupBranchSpecManager()
+    }
+
+    class CommandRegistry {
+        <<Injectable Singleton>>
+        -logger: Logger
+        +registerCommands(context)
+        -registerMemoryCommands()
+        -registerSpecCommands()
+        -registerCouncilCommands()
+    }
+
+    %% Migration Services (Phase 4)
+    class VersionDetector {
+        <<Injectable Singleton>>
+        -logger: Logger
+        +detectFormat(workspacePath)
+        +getVersionInfo(workspacePath)
+        +compareVersions(a, b)
+        +exists(workspacePath)
+    }
+
+    class UpgradeService {
+        <<Injectable Singleton>>
+        -logger: Logger
+        -versionDetector: VersionDetector
+        +upgrade(workspacePath, resourceOps, options)
+        +updateGoferTemplates(workspacePath, resourceOps)
+        +getUpgradeRecommendation(workspacePath)
+    }
+
+    class ResourceSyncer {
+        <<Injectable Singleton>>
+        -logger: Logger
+        -workspacePath: string
+        +setWorkspacePath(path)
+        +installGoferCLI()
+        +setupClaudeCommands()
+        +setupClaudeAgents()
+        +createBashScripts()
+        +migrateJsonSpecs()
+    }
+
+    class PathMigrator {
+        <<Injectable Singleton>>
+        -logger: Logger
+        -workspacePath: string
+        +setWorkspacePath(path)
+        +migratePaths()
+        +verifyMigration()
+        +rollbackMigration()
+    }
+
+    %% Future Services (Phase 2 - Pending)
+    class SpecCache {
+        <<Injectable Singleton - Planned>>
+        -logger: Logger
+        +get(key)
+        +set(key, value)
+        -evictLRU()
+    }
+
+    class MemoryCache {
+        <<Injectable Singleton - Planned>>
+        -logger: Logger
+        +get(key)
+        +set(key, value)
+        -evictByTTL()
+    }
+
+    %% Dependencies
+    Container ..> Logger : resolves
+    Container ..> StateManager : resolves
+    Container ..> DisposalService : resolves
+    Container ..> EventHandlers : resolves
+    Container ..> InitializationService : resolves
+    Container ..> CommandRegistry : resolves
+    Container ..> VersionDetector : resolves
+    Container ..> UpgradeService : resolves
+    Container ..> ResourceSyncer : resolves
+    Container ..> PathMigrator : resolves
+
+    StateManager --> Logger : depends on
+    DisposalService --> Logger : depends on
+    EventHandlers --> Logger : depends on
+    InitializationService --> Logger : depends on
+    CommandRegistry --> Logger : depends on
+
+    VersionDetector --> Logger : depends on
+    UpgradeService --> Logger : depends on
+    UpgradeService --> VersionDetector : depends on
+    ResourceSyncer --> Logger : depends on
+    PathMigrator --> Logger : depends on
+
+    SpecCache -.-> Logger : will depend on
+    MemoryCache -.-> Logger : will depend on
+
+    note for Container "TSyringe container instance\nManages all service lifecycles\nSingletons cached after first resolve"
+
+    note for Logger "No dependencies\nFirst service registered\nUsed by all other services"
+
+    note for VersionDetector "Migration service\nPhase 4 - T026"
+
+    note for UpgradeService "Migration orchestration\nPhase 4 - T027"
+
+    note for ResourceSyncer "Resource synchronization\nPhase 4 - T028\nImplements IResourceOperations"
+
+    note for PathMigrator "Path migration\nPhase 4 - T029"
+```
+
+# DI Container Diagram
+
+This diagram shows all injectable services registered in the TSyringe DI
+container and their dependency relationships.
+
+## Service Scopes
+
+All services are registered as **Singletons** using
+`container.registerSingleton()`:
+
+- ✅ **Singleton**: One instance per container (shared across extension)
+- ❌ **Transient**: Not used (each resolve creates new instance)
+
+## Dependency Hierarchy
+
+### Layer 1: Foundation (No Dependencies)
+
+- **Logger**: Foundation service with no dependencies
+
+### Layer 2: Core Infrastructure (Depends on Logger)
+
+- **StateManager**: Global state management
+- **DisposalService**: Resource cleanup coordination
+
+### Layer 3: Extension Services (Phase 3 - Depends on Logger)
+
+- **EventHandlers**: Workspace event listeners
+- **InitializationService**: Workspace initialization
+- **CommandRegistry**: Command registration
+
+### Layer 4: Migration Services (Phase 4 - Depends on Logger, VersionDetector)
+
+- **VersionDetector**: Format detection
+- **UpgradeService**: Upgrade orchestration (also depends on VersionDetector)
+- **ResourceSyncer**: File/resource operations
+- **PathMigrator**: Path reference migration
+
+### Layer 5: Cache Services (Planned - Depends on Logger)
+
+- **SpecCache**: Spec file caching (Phase 2)
+- **MemoryCache**: Memory indexing cache (Phase 2)
+
+## Registration Order
+
+Services are registered in `extension/src/di/container.ts`:
+
+```typescript
+export function registerServices(): void {
+  // Phase 1: Core infrastructure services
+  container.registerSingleton(Logger);
+
+  // Phase 3: Extension.ts extracted services (T020-T025)
+  container.registerSingleton(DisposalService);
+  container.registerSingleton(EventHandlers);
+  container.registerSingleton(InitializationService);
+  container.registerSingleton(CommandRegistry);
+  container.registerSingleton(StateManager);
+
+  // Phase 4: GoferMigrator.ts extracted services (T026-T030)
+  container.registerSingleton(VersionDetector);
+  container.registerSingleton(UpgradeService);
+  container.registerSingleton(ResourceSyncer);
+  container.registerSingleton(PathMigrator);
+}
+```
+
+Order doesn't matter for registration (dependency resolution is lazy), but
+ordered logically for readability.
+
+## Resolution Examples
+
+### Simple Resolution (No Dependencies)
+
+```typescript
+const logger = container.resolve(Logger);
+logger.info('Context', 'Message');
+```
+
+### Dependency Injection (With Dependencies)
+
+```typescript
+@injectable()
+class UpgradeService {
+  constructor(
+    private readonly logger: Logger,
+    private readonly versionDetector: VersionDetector
+  ) {}
+}
+
+// Container automatically injects dependencies
+const upgradeService = container.resolve(UpgradeService);
+```
+
+### Manual Composition (Facade Pattern)
+
+```typescript
+class GoferMigrator {
+  constructor(workspacePath: string) {
+    const container = getContainer();
+    this.logger = container.resolve(Logger);
+    this.versionDetector = container.resolve(VersionDetector);
+    this.upgradeService = container.resolve(UpgradeService);
+    this.resourceSyncer = container.resolve(ResourceSyncer);
+    this.pathMigrator = container.resolve(PathMigrator);
+  }
+}
+```
+
+## Testing Support
+
+### Mock Injection
+
+```typescript
+// In test setup
+container.register(Logger, { useValue: mockLogger });
+
+// Test code resolves mock
+const service = container.resolve(UpgradeService);
+// service.logger === mockLogger
+```
+
+### Container Reset
+
+```typescript
+// Between tests
+afterEach(() => {
+  resetContainer(); // Clears all singleton instances
+});
+```
+
+## Benefits
+
+1. **Explicit dependencies**: Constructor signatures document what's needed
+2. **Singleton management**: Container ensures only one instance exists
+3. **Type safety**: TypeScript enforces dependency types at compile-time
+4. **Testability**: Easy to inject mocks via `container.register()`
+5. **Lazy initialization**: Services created only when first resolved
+6. **Circular dependency detection**: Container throws if circular deps detected
+
+## Limitations
+
+1. **Decorator overhead**: Requires `@injectable()` on every service
+2. **Runtime metadata**: Reflection adds small performance cost
+3. **Build config**: Requires `experimentalDecorators` in tsconfig.json
+4. **No hierarchical containers**: Single global container (acceptable for
+   extension)
+
+## Future Enhancements
+
+### Phase 2: Cache Services
+
+- Register `SpecCache` as singleton
+- Register `MemoryCache` as singleton
+- Both depend on `Logger` only
+
+### Advanced Features (If Needed)
+
+- **Factory providers**: For services needing dynamic configuration
+- **Multi-injection**: For plugin architectures (not currently needed)
+- **Scoped containers**: For request-scoped services (not applicable to VSCode
+  extensions)

package/resources/gofer/memory/diagrams/extension-activation.mmd

@@ -0,0 +1,184 @@
+```mermaid
+sequenceDiagram
+    autonumber
+    participant VSCode as VSCode Extension Host
+    participant Extension as extension.ts
+    participant Container as DI Container
+    participant Logger as Logger Service
+    participant Init as InitializationService
+    participant Commands as CommandRegistry
+    participant Events as EventHandlers
+    participant State as StateManager
+    participant Disposal as DisposalService
+
+    Note over VSCode,Disposal: Extension Activation Flow
+
+    VSCode->>Extension: activate(context)
+    activate Extension
+
+    Note over Extension: Phase 1: DI Container Setup
+    Extension->>Container: registerServices()
+    activate Container
+    Container->>Container: registerSingleton(Logger)
+    Container->>Container: registerSingleton(DisposalService)
+    Container->>Container: registerSingleton(EventHandlers)
+    Container->>Container: registerSingleton(InitializationService)
+    Container->>Container: registerSingleton(CommandRegistry)
+    Container->>Container: registerSingleton(StateManager)
+    Container->>Container: registerSingleton(VersionDetector)
+    Container->>Container: registerSingleton(UpgradeService)
+    Container->>Container: registerSingleton(ResourceSyncer)
+    Container->>Container: registerSingleton(PathMigrator)
+    Container-->>Extension: Services registered
+    deactivate Container
+
+    Note over Extension: Phase 2: Resolve Core Services
+    Extension->>Container: resolve(Logger)
+    Container-->>Extension: Logger instance
+    Extension->>Container: resolve(StateManager)
+    Container-->>Extension: StateManager instance
+
+    Extension->>Logger: info('Extension', 'Activating Gofer')
+    Logger-->>Extension: Logged
+
+    Note over Extension: Phase 3: Global Commands Registration
+    Extension->>Extension: registerGlobalCommands(context)
+    Extension->>VSCode: registerCommand('gofer.initializeWorkspace')
+    Extension->>VSCode: registerCommand('gofer.showConstitution')
+    Extension->>VSCode: registerCommand('gofer.checkForUpdates')
+    VSCode-->>Extension: Commands registered
+
+    Note over Extension: Phase 4: Workspace Initialization
+    Extension->>Container: resolve(InitializationService)
+    Container-->>Extension: InitializationService instance
+
+    Extension->>Init: initializeForWorkspace(context)
+    activate Init
+
+    Init->>Init: checkWorkspace()
+    alt No workspace folder
+        Init->>VSCode: showInformationMessage('No workspace')
+        Init-->>Extension: Initialization skipped
+    else Workspace exists
+        Init->>Init: setupWorkspaceResources()
+        Init->>Init: setupMemoryManager()
+        Init->>Init: setupProgressProvider()
+        Init->>Init: setupBranchSpecManager()
+
+        Note over Init,Commands: Phase 5: Register Workspace Commands
+        Init->>Container: resolve(CommandRegistry)
+        Container-->>Init: CommandRegistry instance
+
+        Init->>Commands: registerCommands(context)
+        activate Commands
+        Commands->>VSCode: registerCommand('gofer.viewProgress')
+        Commands->>VSCode: registerCommand('gofer.createSpec')
+        Commands->>VSCode: registerCommand('gofer.showMemory')
+        Commands->>VSCode: registerCommand('gofer.council.showStatus')
+        VSCode-->>Commands: Commands registered
+        Commands-->>Init: Commands registered
+        deactivate Commands
+
+        Note over Init,Events: Phase 6: Register Event Handlers
+        Init->>Container: resolve(EventHandlers)
+        Container-->>Init: EventHandlers instance
+
+        Init->>Events: registerHandlers(context)
+        activate Events
+        Events->>VSCode: onDidChangeWorkspaceFolders(handler)
+        Events->>VSCode: onDidChangeActiveTextEditor(handler)
+        Events->>VSCode: onDidSaveTextDocument(handler)
+        VSCode-->>Events: Handlers registered
+        Events-->>Init: Handlers registered
+        deactivate Events
+
+        Init-->>Extension: Workspace initialized
+    end
+    deactivate Init
+
+    Note over Extension: Phase 7: Language Server (Optional)
+    alt Language Server enabled
+        Extension->>Extension: startLanguageServer()
+        Extension->>VSCode: LanguageClient.start()
+        VSCode-->>Extension: LSP started
+    end
+
+    Note over Extension: Phase 8: Auto-Updater
+    Extension->>Extension: setupAutoUpdater()
+    Extension->>VSCode: Check for updates (24hr interval)
+
+    Extension->>Logger: info('Extension', 'Activation complete')
+    Logger-->>Extension: Logged
+
+    Extension-->>VSCode: Extension activated
+    deactivate Extension
+
+    Note over VSCode,Disposal: Extension Ready - Listening for commands and events
+```
+
+# Extension Activation Diagram
+
+This diagram shows the complete activation flow of the Gofer VSCode extension
+from the initial `activate()` call through service registration, initialization,
+and readiness.
+
+## Key Phases
+
+### Phase 1: DI Container Setup
+
+All injectable services are registered as singletons in the TSyringe container.
+This happens synchronously before any service resolution.
+
+### Phase 2: Resolve Core Services
+
+The `Logger` and `StateManager` are resolved first as they're needed throughout
+activation.
+
+### Phase 3: Global Commands Registration
+
+Commands that must be available immediately (before workspace initialization)
+are registered directly in `extension.ts`.
+
+### Phase 4: Workspace Initialization
+
+`InitializationService` handles workspace-specific setup including resource
+discovery and component initialization.
+
+### Phase 5: Register Workspace Commands
+
+Commands that depend on workspace resources (specs, memories) are registered
+after initialization.
+
+### Phase 6: Register Event Handlers
+
+`EventHandlers` sets up listeners for workspace changes, file saves, and editor
+changes.
+
+### Phase 7: Language Server (Optional)
+
+If enabled, the Language Server Protocol client is started for advanced features
+(go-to-definition, autocomplete).
+
+### Phase 8: Auto-Updater
+
+Background updater is configured to check for extension updates every 24 hours.
+
+## Service Resolution Order
+
+Services are resolved in this order to satisfy dependencies:
+
+1. **Logger** - No dependencies (except VSCode API)
+2. **StateManager** - Depends on Logger
+3. **InitializationService** - Depends on Logger, StateManager
+4. **CommandRegistry** - Depends on Logger, StateManager
+5. **EventHandlers** - Depends on Logger, StateManager
+
+## Error Handling
+
+All operations log via `Logger.error()` to ensure visibility. Critical failures
+during activation are surfaced to users via `vscode.window.showErrorMessage()`.
+
+## Deactivation
+
+When the extension deactivates, `deactivate()` resolves `DisposalService` to
+properly clean up all resources (file watchers, timers, LSP client, etc.).