@lumenflow/core 1.4.0 → 1.6.0

package/README.md

@@ -8,6 +8,45 @@ Core WU lifecycle tools for the LumenFlow workflow framework.
 pnpm add @lumenflow/core
 ```
 
+## Architecture
+
+This package follows **hexagonal architecture** (ports and adapters) to enable dependency injection and testing.
+
+```
++---------------------------+
+|        Use Cases          |  Application layer
+|  ComputeContextUseCase    |
+|  ValidateCommandUseCase   |
+|  AnalyzeRecoveryUseCase   |
++------------+--------------+
+             |
+             | depends on
+             v
++---------------------------+
+|      Port Interfaces      |  Abstractions
+|    ILocationResolver      |
+|    IGitStateReader        |
+|    IWuStateReader         |
++------------+--------------+
+             ^
+             | implements
+             |
++---------------------------+
+|     Adapter Classes       |  Infrastructure
+|  SimpleGitLocationAdapter |
+|  FileSystemWuStateAdapter |
++---------------------------+
+```
+
+**Key Benefits:**
+
+- **Testability**: Inject mock adapters for deterministic testing
+- **Extensibility**: Replace adapters for different environments (CI/CD, testing)
+- **Maintainability**: Clear separation of concerns
+- **Backwards Compatible**: Original functions still work unchanged
+
+See [ADR-001: Hexagonal Architecture](../../docs/04-operations/adr/ADR-001-hexagonal-architecture.md) for the full decision record.
+
 ## Usage
 
 ### Git Operations
@@ -70,23 +109,54 @@ await worktrees.remove('worktrees/operations-wu-123');
 
 ### Agent Branch Patterns
 
-Check if a branch is an agent branch that can bypass worktree requirements. Patterns are fetched from a central registry with 7-day caching.
+Check if a branch is an agent branch that can bypass worktree requirements. Patterns are fetched from a central registry with 7-day caching, and can be configured via `.lumenflow.config.yaml`.
 
 ```typescript
-import { isAgentBranch, getAgentPatterns } from '@lumenflow/core';
+import { isAgentBranch, isAgentBranchWithDetails, resolveAgentPatterns } from '@lumenflow/core';
 
 // Check if branch can bypass worktree requirements (async, uses registry)
 if (await isAgentBranch('claude/session-12345')) {
   console.log('Agent branch - bypass allowed');
 }
 
-// Get the current list of agent patterns
-const patterns = await getAgentPatterns();
-// ['agent/*', 'claude/*', 'codex/*', 'copilot/*', 'cursor/*', ...]
+// Get detailed result for observability
+const result = await isAgentBranchWithDetails('claude/session-123');
+if (result.isMatch) {
+  console.log(`Matched via ${result.patternResult.source}`); // 'registry', 'merged', 'override', 'config', 'defaults'
+  console.log(`Registry fetched: ${result.patternResult.registryFetched}`);
+}
+
+// Resolve patterns with custom options (useful for testing)
+const resolved = await resolveAgentPatterns({
+  configPatterns: ['my-agent/*'], // Merge with registry
+  // overridePatterns: ['only-this/*'], // Replace registry entirely
+  // disableAgentPatternRegistry: true, // Airgapped mode
+});
+console.log(resolved.patterns, resolved.source);
 
 // Synchronous version (uses local config only, no registry fetch)
 import { isAgentBranchSync } from '@lumenflow/core';
-const result = isAgentBranchSync('agent/task-123');
+const syncResult = isAgentBranchSync('agent/task-123');
+```
+
+#### Configuration Options
+
+In `.lumenflow.config.yaml`:
+
+```yaml
+git:
+  # Patterns to MERGE with registry (default: [])
+  agentBranchPatterns:
+    - 'my-custom-agent/*'
+    - 'internal-tool/*'
+
+  # Patterns that REPLACE registry entirely (optional)
+  # agentBranchPatternsOverride:
+  #   - 'claude/*'
+  #   - 'codex/*'
+
+  # Disable registry fetch for airgapped environments (default: false)
+  # disableAgentPatternRegistry: true
 ```
 
 Protected branches (main, master, lane/\*) are **never** bypassed, regardless of patterns.
@@ -121,12 +191,295 @@ Protected branches (main, master, lane/\*) are **never** bypassed, regardless of
 | `list()`                 | List all worktrees              |
 | `exists(path)`           | Check if worktree exists        |
 
+### Context-Aware Validation Ports (WU-1093)
+
+Port interfaces for context-aware validation system. These abstractions allow external users to inject custom implementations.
+
+```typescript
+import type {
+  ILocationResolver,
+  IGitStateReader,
+  IWuStateReader,
+  ICommandRegistry,
+  IRecoveryAnalyzer,
+} from '@lumenflow/core';
+```
+
+### Adapter Classes (WU-1094)
+
+Concrete adapter implementations that wrap the existing functions:
+
+```typescript
+import {
+  // Context adapters
+  SimpleGitLocationAdapter,
+  SimpleGitStateAdapter,
+  FileSystemWuStateAdapter,
+  // Validation adapters
+  CommandRegistryAdapter,
+  // Recovery adapters
+  RecoveryAnalyzerAdapter,
+} from '@lumenflow/core';
+
+// Create adapters implementing port interfaces
+const locationResolver = new SimpleGitLocationAdapter();
+const gitStateReader = new SimpleGitStateAdapter();
+const wuStateReader = new FileSystemWuStateAdapter();
+const commandRegistry = new CommandRegistryAdapter();
+const recoveryAnalyzer = new RecoveryAnalyzerAdapter();
+
+// Use adapters
+const location = await locationResolver.resolveLocation();
+const gitState = await gitStateReader.readGitState();
+const wuState = await wuStateReader.readWuState('WU-1094', '/repo');
+const cmdDef = commandRegistry.getCommandDefinition('wu:done');
+const analysis = await recoveryAnalyzer.analyzeRecovery(context);
+```
+
+### Use Cases with Dependency Injection (WU-1094)
+
+Use case classes with constructor injection enable testing with mock adapters:
+
+```typescript
+import {
+  ComputeContextUseCase,
+  ValidateCommandUseCase,
+  AnalyzeRecoveryUseCase,
+  SimpleGitLocationAdapter,
+  SimpleGitStateAdapter,
+  FileSystemWuStateAdapter,
+  CommandRegistryAdapter,
+  RecoveryAnalyzerAdapter,
+} from '@lumenflow/core';
+
+// Manual wiring with real adapters
+const computeContext = new ComputeContextUseCase(
+  new SimpleGitLocationAdapter(),
+  new SimpleGitStateAdapter(),
+  new FileSystemWuStateAdapter(),
+);
+
+const validateCommand = new ValidateCommandUseCase(new CommandRegistryAdapter());
+
+const analyzeRecovery = new AnalyzeRecoveryUseCase(new RecoveryAnalyzerAdapter());
+
+// Execute use cases
+const context = await computeContext.execute({ wuId: 'WU-1094' });
+const validation = await validateCommand.execute('wu:done', context);
+const recovery = await analyzeRecovery.execute(context);
+```
+
+### DI Factory Functions (WU-1094)
+
+Factory functions create fully wired use cases with default or custom adapters:
+
+```typescript
+import {
+  createComputeContextUseCase,
+  createValidateCommandUseCase,
+  createAnalyzeRecoveryUseCase,
+} from '@lumenflow/core';
+
+// Use defaults - simplest approach
+const useCase = createComputeContextUseCase();
+const context = await useCase.execute({ wuId: 'WU-1094' });
+
+// Inject custom adapters for testing
+const mockLocationResolver = {
+  resolveLocation: async () => ({
+    type: 'main' as const,
+    cwd: '/test',
+    gitRoot: '/test',
+    mainCheckout: '/test',
+    worktreeName: null,
+    worktreeWuId: null,
+  }),
+};
+
+const testUseCase = createComputeContextUseCase({
+  locationResolver: mockLocationResolver,
+  // gitStateReader and wuStateReader use defaults
+});
+```
+
+### Convenience Functions (WU-1094)
+
+For simple use cases, backwards compatible functions are available:
+
+```typescript
+import { computeWuContext, validateCommand, analyzeRecoveryIssues } from '@lumenflow/core';
+
+// Compute context (uses default adapters internally)
+const context = await computeWuContext({ wuId: 'WU-1094' });
+
+// Validate a command
+const validation = await validateCommand('wu:done', context);
+if (!validation.valid) {
+  console.error(validation.errors[0].message);
+}
+
+// Analyze for recovery issues
+const recovery = await analyzeRecoveryIssues(context);
+if (recovery.hasIssues) {
+  for (const action of recovery.actions) {
+    console.log(`Fix: ${action.command}`);
+  }
+}
+```
+
+### Domain Schemas (Zod)
+
+Runtime validation schemas for domain types. Types are inferred from Zod schemas using `z.infer<>`.
+
+```typescript
+import {
+  // Context schemas
+  LocationContextSchema,
+  GitStateSchema,
+  WuStateResultSchema,
+  SessionStateSchema,
+  WuContextSchema,
+
+  // Validation schemas
+  ValidationErrorSchema,
+  ValidationWarningSchema,
+  ValidationResultSchema,
+  CommandPredicateConfigSchema,
+  CommandDefinitionConfigSchema,
+
+  // Recovery schemas
+  RecoveryIssueSchema,
+  RecoveryActionSchema,
+  RecoveryAnalysisSchema,
+
+  // Types (inferred from schemas)
+  type LocationContext,
+  type GitState,
+  type WuStateResult,
+  type ValidationError,
+  type RecoveryAnalysis,
+} from '@lumenflow/core';
+
+// Validate runtime data
+const result = LocationContextSchema.safeParse(unknownData);
+if (result.success) {
+  const location: LocationContext = result.data;
+  console.log(`Type: ${location.type}, CWD: ${location.cwd}`);
+}
+```
+
+## Testing with Custom Adapters
+
+The hexagonal architecture makes testing straightforward. Inject mock adapters to create deterministic tests without file system or git dependencies.
+
+### Example: Testing with Mock Adapters
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { createComputeContextUseCase } from '@lumenflow/core';
+import type { ILocationResolver, IGitStateReader, IWuStateReader } from '@lumenflow/core';
+
+describe('ComputeContextUseCase', () => {
+  it('should detect worktree context', async () => {
+    // Create mock adapters
+    const mockLocation: ILocationResolver = {
+      resolveLocation: async () => ({
+        type: 'worktree',
+        cwd: '/test/worktrees/ops-wu-1095',
+        gitRoot: '/test/worktrees/ops-wu-1095',
+        mainCheckout: '/test',
+        worktreeName: 'ops-wu-1095',
+        worktreeWuId: 'WU-1095',
+      }),
+    };
+
+    const mockGitState: IGitStateReader = {
+      readGitState: async () => ({
+        branch: 'lane/operations/wu-1095',
+        isDetached: false,
+        isDirty: false,
+        hasStaged: false,
+        ahead: 1,
+        behind: 0,
+        tracking: 'origin/lane/operations/wu-1095',
+        modifiedFiles: [],
+        hasError: false,
+        errorMessage: null,
+      }),
+    };
+
+    const mockWuState: IWuStateReader = {
+      readWuState: async () => ({
+        id: 'WU-1095',
+        status: 'in_progress',
+        lane: 'Content: Documentation',
+        title: 'Test WU',
+        yamlPath: '/test/docs/04-operations/tasks/wu/WU-1095.yaml',
+        isConsistent: true,
+        inconsistencyReason: null,
+      }),
+    };
+
+    // Create use case with mocks
+    const useCase = createComputeContextUseCase({
+      locationResolver: mockLocation,
+      gitStateReader: mockGitState,
+      wuStateReader: mockWuState,
+    });
+
+    // Execute
+    const context = await useCase.execute({ wuId: 'WU-1095' });
+
+    // Assert - fully deterministic
+    expect(context.location.type).toBe('worktree');
+    expect(context.location.worktreeWuId).toBe('WU-1095');
+    expect(context.wu?.status).toBe('in_progress');
+  });
+});
+```
+
+### Example: CI/CD Custom Adapter
+
+```typescript
+import type { ILocationResolver, LocationContext } from '@lumenflow/core';
+import { createComputeContextUseCase } from '@lumenflow/core';
+
+// CI environments always run in main checkout
+class CILocationResolver implements ILocationResolver {
+  constructor(private readonly repoPath: string) {}
+
+  async resolveLocation(cwd?: string): Promise<LocationContext> {
+    return {
+      type: 'main',
+      cwd: cwd || this.repoPath,
+      gitRoot: this.repoPath,
+      mainCheckout: this.repoPath,
+      worktreeName: null,
+      worktreeWuId: null,
+    };
+  }
+}
+
+// Usage in CI
+const useCase = createComputeContextUseCase({
+  locationResolver: new CILocationResolver('/github/workspace'),
+});
+```
+
 ## Features
 
 - **Type-safe**: Full TypeScript support with detailed type definitions
-- **Dependency injection**: Easy to test with mock git instances
+- **Dependency injection**: Easy to test with mock adapters
+- **Hexagonal architecture**: Port interfaces for external injection
 - **Safe worktree cleanup**: Handles orphan directories and corrupted metadata
 - **Modern**: Node 22+, ESM-only, strict TypeScript
+- **Zod schemas**: Runtime validation for all domain types
+
+## Further Reading
+
+- [ADR-001: Hexagonal Architecture](../../docs/04-operations/adr/ADR-001-hexagonal-architecture.md)
+- [Migration Guide](../../docs/04-operations/adr/migration-guide-hexagonal-architecture.md)
+- [Port Interfaces Reference](https://lumenflow.dev/reference/ports/)
 
 ## Status
 
@@ -134,6 +487,8 @@ This package is under active development. Current features:
 
 - Git operations (GitAdapter)
 - Worktree management (WorktreeManager)
+- Context-aware validation (WU-1090)
+- Hexagonal architecture with DI (INIT-002)
 - Modern tooling (Node 22, ESLint 9, TypeScript 5.7, Vitest 4)
 - Security and code quality linting
 

package/dist/adapters/context-adapters.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Context Adapters
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Concrete adapter implementations for context-related port interfaces.
+ * These adapters wrap the existing implementation functions to conform
+ * to the port interfaces, enabling dependency injection.
+ *
+ * Adapters:
+ * - SimpleGitLocationAdapter - Implements ILocationResolver
+ * - SimpleGitStateAdapter - Implements IGitStateReader
+ * - FileSystemWuStateAdapter - Implements IWuStateReader
+ *
+ * @module adapters/context-adapters
+ */
+import type { ILocationResolver, IGitStateReader, IWuStateReader, LocationContext, GitState, WuStateResult } from '../ports/context.ports.js';
+/**
+ * SimpleGitLocationAdapter
+ *
+ * Implements ILocationResolver by delegating to the resolveLocation function.
+ * Uses simple-git library under the hood.
+ *
+ * @example
+ * // Use default adapter
+ * const adapter = new SimpleGitLocationAdapter();
+ * const location = await adapter.resolveLocation();
+ *
+ * @example
+ * // Use as port interface
+ * const resolver: ILocationResolver = new SimpleGitLocationAdapter();
+ */
+export declare class SimpleGitLocationAdapter implements ILocationResolver {
+    /**
+     * Resolve location context for the given working directory.
+     *
+     * @param cwd - Current working directory (defaults to process.cwd())
+     * @returns Promise<LocationContext> - Resolved location context
+     */
+    resolveLocation(cwd?: string): Promise<LocationContext>;
+}
+/**
+ * SimpleGitStateAdapter
+ *
+ * Implements IGitStateReader by delegating to the readGitState function.
+ * Uses simple-git library under the hood.
+ *
+ * @example
+ * // Use default adapter
+ * const adapter = new SimpleGitStateAdapter();
+ * const gitState = await adapter.readGitState();
+ *
+ * @example
+ * // Use as port interface
+ * const reader: IGitStateReader = new SimpleGitStateAdapter();
+ */
+export declare class SimpleGitStateAdapter implements IGitStateReader {
+    /**
+     * Read current git state for the given working directory.
+     *
+     * @param cwd - Current working directory (defaults to process.cwd())
+     * @returns Promise<GitState> - Current git state
+     */
+    readGitState(cwd?: string): Promise<GitState>;
+}
+/**
+ * FileSystemWuStateAdapter
+ *
+ * Implements IWuStateReader by delegating to the readWuState function.
+ * Reads WU state from YAML files in the filesystem.
+ *
+ * @example
+ * // Use default adapter
+ * const adapter = new FileSystemWuStateAdapter();
+ * const wuState = await adapter.readWuState('WU-1094', '/repo');
+ *
+ * @example
+ * // Use as port interface
+ * const reader: IWuStateReader = new FileSystemWuStateAdapter();
+ */
+export declare class FileSystemWuStateAdapter implements IWuStateReader {
+    /**
+     * Read WU state from YAML and detect inconsistencies.
+     *
+     * @param wuId - WU ID (e.g., 'WU-1094' or 'wu-1094')
+     * @param repoRoot - Repository root path
+     * @returns Promise<WuStateResult | null> - WU state or null if not found
+     */
+    readWuState(wuId: string, repoRoot: string): Promise<WuStateResult | null>;
+}

package/dist/adapters/context-adapters.js

@@ -0,0 +1,99 @@
+/**
+ * Context Adapters
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Concrete adapter implementations for context-related port interfaces.
+ * These adapters wrap the existing implementation functions to conform
+ * to the port interfaces, enabling dependency injection.
+ *
+ * Adapters:
+ * - SimpleGitLocationAdapter - Implements ILocationResolver
+ * - SimpleGitStateAdapter - Implements IGitStateReader
+ * - FileSystemWuStateAdapter - Implements IWuStateReader
+ *
+ * @module adapters/context-adapters
+ */
+// Import existing implementations
+import { resolveLocation } from '../context/location-resolver.js';
+import { readGitState } from '../context/git-state-reader.js';
+import { readWuState } from '../context/wu-state-reader.js';
+/**
+ * SimpleGitLocationAdapter
+ *
+ * Implements ILocationResolver by delegating to the resolveLocation function.
+ * Uses simple-git library under the hood.
+ *
+ * @example
+ * // Use default adapter
+ * const adapter = new SimpleGitLocationAdapter();
+ * const location = await adapter.resolveLocation();
+ *
+ * @example
+ * // Use as port interface
+ * const resolver: ILocationResolver = new SimpleGitLocationAdapter();
+ */
+export class SimpleGitLocationAdapter {
+    /**
+     * Resolve location context for the given working directory.
+     *
+     * @param cwd - Current working directory (defaults to process.cwd())
+     * @returns Promise<LocationContext> - Resolved location context
+     */
+    async resolveLocation(cwd) {
+        return resolveLocation(cwd);
+    }
+}
+/**
+ * SimpleGitStateAdapter
+ *
+ * Implements IGitStateReader by delegating to the readGitState function.
+ * Uses simple-git library under the hood.
+ *
+ * @example
+ * // Use default adapter
+ * const adapter = new SimpleGitStateAdapter();
+ * const gitState = await adapter.readGitState();
+ *
+ * @example
+ * // Use as port interface
+ * const reader: IGitStateReader = new SimpleGitStateAdapter();
+ */
+export class SimpleGitStateAdapter {
+    /**
+     * Read current git state for the given working directory.
+     *
+     * @param cwd - Current working directory (defaults to process.cwd())
+     * @returns Promise<GitState> - Current git state
+     */
+    async readGitState(cwd) {
+        return readGitState(cwd);
+    }
+}
+/**
+ * FileSystemWuStateAdapter
+ *
+ * Implements IWuStateReader by delegating to the readWuState function.
+ * Reads WU state from YAML files in the filesystem.
+ *
+ * @example
+ * // Use default adapter
+ * const adapter = new FileSystemWuStateAdapter();
+ * const wuState = await adapter.readWuState('WU-1094', '/repo');
+ *
+ * @example
+ * // Use as port interface
+ * const reader: IWuStateReader = new FileSystemWuStateAdapter();
+ */
+export class FileSystemWuStateAdapter {
+    /**
+     * Read WU state from YAML and detect inconsistencies.
+     *
+     * @param wuId - WU ID (e.g., 'WU-1094' or 'wu-1094')
+     * @param repoRoot - Repository root path
+     * @returns Promise<WuStateResult | null> - WU state or null if not found
+     */
+    async readWuState(wuId, repoRoot) {
+        return readWuState(wuId, repoRoot);
+    }
+}

package/dist/adapters/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Adapters Index
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Re-exports all adapter implementations.
+ *
+ * @module adapters
+ */
+export { SimpleGitLocationAdapter, SimpleGitStateAdapter, FileSystemWuStateAdapter, } from './context-adapters.js';
+export { CommandRegistryAdapter } from './validation-adapters.js';
+export { RecoveryAnalyzerAdapter } from './recovery-adapters.js';
+export { TerminalDashboardRenderer } from './terminal-renderer.adapter.js';
+export { FileSystemMetricsCollector } from './filesystem-metrics.adapter.js';

package/dist/adapters/index.js

@@ -0,0 +1,18 @@
+/**
+ * Adapters Index
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Re-exports all adapter implementations.
+ *
+ * @module adapters
+ */
+// Context adapters
+export { SimpleGitLocationAdapter, SimpleGitStateAdapter, FileSystemWuStateAdapter, } from './context-adapters.js';
+// Validation adapters
+export { CommandRegistryAdapter } from './validation-adapters.js';
+// Recovery adapters
+export { RecoveryAnalyzerAdapter } from './recovery-adapters.js';
+// Existing adapters (pre-WU-1094)
+export { TerminalDashboardRenderer } from './terminal-renderer.adapter.js';
+export { FileSystemMetricsCollector } from './filesystem-metrics.adapter.js';

package/dist/adapters/recovery-adapters.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Recovery Adapters
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Concrete adapter implementations for recovery-related port interfaces.
+ * These adapters wrap the existing implementation functions to conform
+ * to the port interfaces, enabling dependency injection.
+ *
+ * Adapters:
+ * - RecoveryAnalyzerAdapter - Implements IRecoveryAnalyzer
+ *
+ * @module adapters/recovery-adapters
+ */
+import type { IRecoveryAnalyzer, WuContext, RecoveryAnalysis } from '../ports/recovery.ports.js';
+/**
+ * RecoveryAnalyzerAdapter
+ *
+ * Implements IRecoveryAnalyzer by delegating to the analyzeRecovery function.
+ * Analyzes WU context to detect state inconsistencies and suggests
+ * recovery actions.
+ *
+ * @example
+ * // Use default adapter
+ * const adapter = new RecoveryAnalyzerAdapter();
+ * const analysis = await adapter.analyzeRecovery(context);
+ *
+ * @example
+ * // Use as port interface
+ * const analyzer: IRecoveryAnalyzer = new RecoveryAnalyzerAdapter();
+ */
+export declare class RecoveryAnalyzerAdapter implements IRecoveryAnalyzer {
+    /**
+     * Analyze context for recovery issues.
+     *
+     * @param context - Current WU context
+     * @returns Promise<RecoveryAnalysis> - Recovery analysis with issues and suggested actions
+     */
+    analyzeRecovery(context: WuContext): Promise<RecoveryAnalysis>;
+}