@lumenflow/core 1.5.0 → 2.0.0

package/dist/domain/validation.schemas.js

@@ -0,0 +1,114 @@
+/**
+ * Validation Schemas
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Zod schemas for validation-related types in the context-aware validation system.
+ * Types are inferred from Zod schemas using z.infer<> for single source of truth.
+ *
+ * @module domain/validation.schemas
+ */
+import { z } from 'zod';
+import { LocationTypeSchema } from './context.schemas.js';
+// Re-export LocationTypeSchema for command definitions
+export { LocationTypeSchema };
+/**
+ * Validation error code values
+ *
+ * Mirrors CONTEXT_VALIDATION.ERROR_CODES from wu-constants.ts
+ */
+export const VALIDATION_ERROR_CODE_VALUES = [
+    'WRONG_LOCATION',
+    'WU_NOT_FOUND',
+    'WU_ALREADY_EXISTS',
+    'WRONG_WU_STATUS',
+    'LANE_OCCUPIED',
+    'WORKTREE_EXISTS',
+    'WORKTREE_MISSING',
+    'GATES_NOT_PASSED',
+    'DIRTY_GIT',
+    'REMOTE_UNAVAILABLE',
+    'INCONSISTENT_STATE',
+];
+/**
+ * Schema for validation error codes
+ */
+export const ValidationErrorCodeSchema = z.enum(VALIDATION_ERROR_CODE_VALUES);
+/**
+ * Severity values
+ *
+ * Mirrors CONTEXT_VALIDATION.SEVERITY from wu-constants.ts
+ */
+export const PREDICATE_SEVERITY_VALUES = ['error', 'warning'];
+/**
+ * Schema for predicate severity
+ */
+export const PredicateSeveritySchema = z.enum(PREDICATE_SEVERITY_VALUES);
+/**
+ * Schema for validation error with fix guidance
+ */
+export const ValidationErrorSchema = z.object({
+    /** Error code */
+    code: ValidationErrorCodeSchema,
+    /** Human-readable message */
+    message: z.string(),
+    /** Copy-paste ready fix command (if available) */
+    fixCommand: z.string().nullable(),
+    /** Additional context for debugging */
+    context: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Schema for validation warning (non-blocking)
+ */
+export const ValidationWarningSchema = z.object({
+    /** Warning ID */
+    id: z.string(),
+    /** Human-readable message */
+    message: z.string(),
+});
+/**
+ * Schema for validation result (partial, without context for serialization)
+ *
+ * Note: The full ValidationResult in types.ts includes the context object,
+ * but this schema is for serializable results without the context.
+ */
+export const ValidationResultSchema = z.object({
+    /** Whether command can proceed */
+    valid: z.boolean(),
+    /** Errors that block execution */
+    errors: z.array(ValidationErrorSchema),
+    /** Warnings that don't block execution */
+    warnings: z.array(ValidationWarningSchema),
+});
+/**
+ * Schema for command predicate configuration (serializable)
+ *
+ * This schema represents the serializable configuration of a predicate,
+ * not the full CommandPredicate which includes the check function.
+ */
+export const CommandPredicateConfigSchema = z.object({
+    /** Unique identifier for the predicate */
+    id: z.string(),
+    /** Human-readable description */
+    description: z.string(),
+    /** Severity: 'error' blocks execution, 'warning' allows with warning */
+    severity: PredicateSeveritySchema,
+});
+/**
+ * Schema for command definition configuration (serializable)
+ *
+ * This schema represents the serializable configuration of a command definition,
+ * not the full CommandDefinition which includes function references.
+ */
+export const CommandDefinitionConfigSchema = z.object({
+    /** Command name (e.g., 'wu:create') */
+    name: z.string(),
+    /** Human-readable description */
+    description: z.string(),
+    /** Required location type (null = any location) */
+    requiredLocation: LocationTypeSchema.nullable(),
+    /** Required WU status (null = no status requirement) */
+    requiredWuStatus: z.string().nullable(),
+    /** Predicate IDs for additional checks */
+    predicateIds: z.array(z.string()),
+});

package/dist/index.d.ts

@@ -49,3 +49,20 @@ export * from './lumenflow-home.js';
 export * from './force-bypass-audit.js';
 export { LUMENFLOW_PATHS, BEACON_PATHS } from './wu-constants.js';
 export * from './color-support.js';
+export * from './context/index.js';
+export * from './validation/index.js';
+export * from './recovery/index.js';
+export * from './context-validation-integration.js';
+export { CONTEXT_VALIDATION } from './wu-constants.js';
+export type { LocationType, ValidationErrorCode, RecoveryActionType, RecoveryIssueCode, PredicateSeverity, ValidationMode, } from './wu-constants.js';
+export type { ILocationResolver, IGitStateReader, IWuStateReader } from './ports/context.ports.js';
+export type { ICommandRegistry } from './ports/validation.ports.js';
+export type { IRecoveryAnalyzer } from './ports/recovery.ports.js';
+export type { IWuGitAdapter, IWuStatusCheckResult, IBranchValidationResult, IWuYamlReader, IWuYamlWriter, IWuStateStore, IWuCheckpointManager, IWuPaths, } from './ports/wu-helpers.ports.js';
+export type { IGitAdapter, IPhiScanner, PHIMatch, PHIScanResult, PHIScanOptions, MergeOptions, MergeResult, PushOptions, DeleteBranchOptions, WorktreeRemoveOptions, } from './ports/git-validator.ports.js';
+export { LOCATION_TYPE_VALUES, LocationTypeSchema, LocationContextSchema, GitStateSchema, WuStateResultSchema, SessionStateSchema, WuContextSchema, } from './domain/context.schemas.js';
+export { VALIDATION_ERROR_CODE_VALUES, ValidationErrorCodeSchema, PREDICATE_SEVERITY_VALUES, PredicateSeveritySchema, ValidationErrorSchema, ValidationWarningSchema, ValidationResultSchema, CommandPredicateConfigSchema, CommandDefinitionConfigSchema, type CommandPredicateConfig, type CommandDefinitionConfig, } from './domain/validation.schemas.js';
+export { RECOVERY_ISSUE_CODE_VALUES, RecoveryIssueCodeSchema, RECOVERY_ACTION_TYPE_VALUES, RecoveryActionTypeSchema, RecoveryIssueSchema, RecoveryActionSchema, RecoveryAnalysisSchema, } from './domain/recovery.schemas.js';
+export { SimpleGitLocationAdapter, SimpleGitStateAdapter, FileSystemWuStateAdapter, CommandRegistryAdapter, RecoveryAnalyzerAdapter, } from './adapters/index.js';
+export { ComputeContextUseCase, type ComputeContextOptions, ValidateCommandUseCase, AnalyzeRecoveryUseCase, } from './usecases/index.js';
+export { createContextAdapters, createValidationAdapters, createRecoveryAdapters, createComputeContextUseCase, createValidateCommandUseCase, createAnalyzeRecoveryUseCase, computeWuContext, validateCommand, analyzeRecoveryIssues, type ContextAdapters, type ValidationAdapters, type RecoveryAdapters, type CreateComputeContextOptions, type CreateValidateCommandOptions, type CreateAnalyzeRecoveryOptions, } from './context-di.js';

package/dist/index.js

@@ -77,3 +77,46 @@ export * from './force-bypass-audit.js';
 export { LUMENFLOW_PATHS, BEACON_PATHS } from './wu-constants.js';
 // WU-1085: Color support for NO_COLOR/FORCE_COLOR/--no-color
 export * from './color-support.js';
+// WU-1090: Context-aware state machine for WU lifecycle commands
+export * from './context/index.js';
+export * from './validation/index.js';
+export * from './recovery/index.js';
+export * from './context-validation-integration.js';
+// WU-1090: Context validation constants
+export { CONTEXT_VALIDATION } from './wu-constants.js';
+// WU-1093: Domain schemas for context-aware validation (Zod schemas)
+// Note: Types like LocationContext, GitState are already exported from context/index.js
+// so we only export the Zod schemas, not the inferred types.
+export { 
+// Context schemas
+LOCATION_TYPE_VALUES, LocationTypeSchema, LocationContextSchema, GitStateSchema, WuStateResultSchema, SessionStateSchema, WuContextSchema, } from './domain/context.schemas.js';
+export { 
+// Validation schemas
+VALIDATION_ERROR_CODE_VALUES, ValidationErrorCodeSchema, PREDICATE_SEVERITY_VALUES, PredicateSeveritySchema, ValidationErrorSchema, ValidationWarningSchema, ValidationResultSchema, CommandPredicateConfigSchema, CommandDefinitionConfigSchema, } from './domain/validation.schemas.js';
+export { 
+// Recovery schemas
+RECOVERY_ISSUE_CODE_VALUES, RecoveryIssueCodeSchema, RECOVERY_ACTION_TYPE_VALUES, RecoveryActionTypeSchema, RecoveryIssueSchema, RecoveryActionSchema, RecoveryAnalysisSchema, } from './domain/recovery.schemas.js';
+// WU-1094: Adapters - Concrete implementations of port interfaces
+export { 
+// Context adapters
+SimpleGitLocationAdapter, SimpleGitStateAdapter, FileSystemWuStateAdapter, 
+// Validation adapters
+CommandRegistryAdapter, 
+// Recovery adapters
+RecoveryAnalyzerAdapter, } from './adapters/index.js';
+// WU-1094: Use Cases - Application layer business logic
+export { 
+// Context use cases
+ComputeContextUseCase, 
+// Validation use cases
+ValidateCommandUseCase, 
+// Recovery use cases
+AnalyzeRecoveryUseCase, } from './usecases/index.js';
+// WU-1094: Dependency Injection - Factory functions for wiring
+export { 
+// Adapter factory functions
+createContextAdapters, createValidationAdapters, createRecoveryAdapters, 
+// Use case factory functions
+createComputeContextUseCase, createValidateCommandUseCase, createAnalyzeRecoveryUseCase, 
+// Backwards compatible convenience functions
+computeWuContext, validateCommand, analyzeRecoveryIssues, } from './context-di.js';

package/dist/lumenflow-config-schema.d.ts

@@ -205,6 +205,29 @@ export declare const AgentsConfigSchema: z.ZodObject<{
         notes: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * Validation mode for context-aware commands
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ */
+export declare const ValidationModeSchema: z.ZodDefault<z.ZodEnum<{
+    error: "error";
+    off: "off";
+    warn: "warn";
+}>>;
+/**
+ * Experimental features configuration
+ * WU-1090: Feature flags for gradual rollout
+ */
+export declare const ExperimentalConfigSchema: z.ZodObject<{
+    context_validation: z.ZodDefault<z.ZodBoolean>;
+    validation_mode: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        off: "off";
+        warn: "warn";
+    }>>;
+    show_next_steps: z.ZodDefault<z.ZodBoolean>;
+    recovery_command: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
 /**
  * Complete LumenFlow configuration schema
  */
@@ -335,6 +358,16 @@ export declare const LumenFlowConfigSchema: z.ZodObject<{
             notes: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    experimental: z.ZodDefault<z.ZodObject<{
+        context_validation: z.ZodDefault<z.ZodBoolean>;
+        validation_mode: z.ZodDefault<z.ZodEnum<{
+            error: "error";
+            off: "off";
+            warn: "warn";
+        }>>;
+        show_next_steps: z.ZodDefault<z.ZodBoolean>;
+        recovery_command: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
  * TypeScript types inferred from schemas
@@ -352,6 +385,8 @@ export type ClientBlock = z.infer<typeof ClientBlockSchema>;
 export type ClientSkills = z.infer<typeof ClientSkillsSchema>;
 export type ClientConfig = z.infer<typeof ClientConfigSchema>;
 export type AgentsConfig = z.infer<typeof AgentsConfigSchema>;
+export type ExperimentalConfig = z.infer<typeof ExperimentalConfigSchema>;
+export type ValidationMode = z.infer<typeof ValidationModeSchema>;
 export type LumenFlowConfig = z.infer<typeof LumenFlowConfigSchema>;
 /**
  * Validate configuration data
@@ -483,6 +518,12 @@ export declare function validateConfig(data: unknown): z.ZodSafeParseResult<{
             notes?: string;
         };
     };
+    experimental: {
+        context_validation: boolean;
+        validation_mode: "error" | "off" | "warn";
+        show_next_steps: boolean;
+        recovery_command: boolean;
+    };
 }>;
 /**
  * Parse configuration with defaults

package/dist/lumenflow-config-schema.js

@@ -281,6 +281,41 @@ export const AgentsConfigSchema = z.object({
     /** Project methodology defaults (agent-facing) */
     methodology: MethodologyDefaultsSchema.default(() => MethodologyDefaultsSchema.parse({})),
 });
+/**
+ * Validation mode for context-aware commands
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ */
+export const ValidationModeSchema = z.enum(['off', 'warn', 'error']).default('warn');
+/**
+ * Experimental features configuration
+ * WU-1090: Feature flags for gradual rollout
+ */
+export const ExperimentalConfigSchema = z.object({
+    /**
+     * Enable context-aware validation for wu:* commands
+     * When enabled, commands will check location, WU status, and predicates
+     * @default true
+     */
+    context_validation: z.boolean().default(true),
+    /**
+     * Validation behavior mode
+     * - 'off': No validation (legacy behavior)
+     * - 'warn': Show warnings but proceed
+     * - 'error': Block on validation failures
+     * @default 'warn'
+     */
+    validation_mode: ValidationModeSchema,
+    /**
+     * Show next steps guidance after successful command completion
+     * @default true
+     */
+    show_next_steps: z.boolean().default(true),
+    /**
+     * Enable wu:recover command for state recovery
+     * @default true
+     */
+    recovery_command: z.boolean().default(true),
+});
 /**
  * Complete LumenFlow configuration schema
  */
@@ -305,6 +340,8 @@ export const LumenFlowConfigSchema = z.object({
     yaml: YamlConfigSchema.default(() => YamlConfigSchema.parse({})),
     /** Agents configuration */
     agents: AgentsConfigSchema.default(() => AgentsConfigSchema.parse({})),
+    /** Experimental features (WU-1090) */
+    experimental: ExperimentalConfigSchema.default(() => ExperimentalConfigSchema.parse({})),
 });
 /**
  * Validate configuration data

package/dist/ports/context.ports.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Context Ports
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Port interfaces for context-aware validation system.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - ILocationResolver: Detect main checkout vs worktree
+ * - IGitStateReader: Read git branch, dirty state, ahead/behind
+ * - IWuStateReader: Read WU state from YAML and state store
+ *
+ * Current Implementations:
+ * - resolveLocation (location-resolver.ts)
+ * - readGitState (git-state-reader.ts)
+ * - readWuState (wu-state-reader.ts)
+ *
+ * @module ports/context
+ */
+import type { LocationContext } from '../context/location-resolver.js';
+import type { GitState } from '../context/git-state-reader.js';
+import type { WuStateResult } from '../context/wu-state-reader.js';
+/**
+ * Location Resolver Port Interface
+ *
+ * Resolves the current working directory context to determine:
+ * - Whether in main checkout or a worktree
+ * - Path to main checkout
+ * - Worktree name and associated WU ID (if applicable)
+ *
+ * @example
+ * // Custom implementation for testing
+ * const mockResolver: ILocationResolver = {
+ *   resolveLocation: async (cwd) => ({
+ *     type: 'main',
+ *     cwd: cwd || '/repo',
+ *     gitRoot: '/repo',
+ *     mainCheckout: '/repo',
+ *     worktreeName: null,
+ *     worktreeWuId: null,
+ *   }),
+ * };
+ *
+ * @example
+ * // Using default implementation
+ * import { resolveLocation } from './context/location-resolver.js';
+ * const resolver: ILocationResolver = { resolveLocation };
+ */
+export interface 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>;
+}
+/**
+ * Git State Reader Port Interface
+ *
+ * Reads the current git state including:
+ * - Current branch name
+ * - Whether HEAD is detached
+ * - Dirty working tree (uncommitted changes)
+ * - Staged changes
+ * - Commits ahead/behind tracking branch
+ *
+ * @example
+ * // Custom implementation for testing
+ * const mockReader: IGitStateReader = {
+ *   readGitState: async () => ({
+ *     branch: 'main',
+ *     isDetached: false,
+ *     isDirty: false,
+ *     hasStaged: false,
+ *     ahead: 0,
+ *     behind: 0,
+ *     tracking: 'origin/main',
+ *     modifiedFiles: [],
+ *     hasError: false,
+ *     errorMessage: null,
+ *   }),
+ * };
+ *
+ * @example
+ * // Using default implementation
+ * import { readGitState } from './context/git-state-reader.js';
+ * const reader: IGitStateReader = { readGitState };
+ */
+export interface 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>;
+}
+/**
+ * WU State Reader Port Interface
+ *
+ * Reads WU state from YAML file and optionally cross-references
+ * with state store for inconsistency detection.
+ *
+ * @example
+ * // Custom implementation for testing
+ * const mockReader: IWuStateReader = {
+ *   readWuState: async (wuId, repoRoot) => ({
+ *     id: wuId,
+ *     status: 'in_progress',
+ *     lane: 'Framework: Core',
+ *     title: 'Test WU',
+ *     yamlPath: `${repoRoot}/docs/04-operations/tasks/wu/${wuId}.yaml`,
+ *     isConsistent: true,
+ *     inconsistencyReason: null,
+ *   }),
+ * };
+ *
+ * @example
+ * // Using default implementation
+ * import { readWuState } from './context/wu-state-reader.js';
+ * const reader: IWuStateReader = { readWuState };
+ */
+export interface IWuStateReader {
+    /**
+     * Read WU state from YAML and detect inconsistencies.
+     *
+     * @param wuId - WU ID (e.g., 'WU-1093' or 'wu-1093')
+     * @param repoRoot - Repository root path
+     * @returns Promise<WuStateResult | null> - WU state or null if not found
+     */
+    readWuState(wuId: string, repoRoot: string): Promise<WuStateResult | null>;
+}
+export type { LocationContext, GitState, WuStateResult };

package/dist/ports/context.ports.js

@@ -0,0 +1,21 @@
+/**
+ * Context Ports
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Port interfaces for context-aware validation system.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - ILocationResolver: Detect main checkout vs worktree
+ * - IGitStateReader: Read git branch, dirty state, ahead/behind
+ * - IWuStateReader: Read WU state from YAML and state store
+ *
+ * Current Implementations:
+ * - resolveLocation (location-resolver.ts)
+ * - readGitState (git-state-reader.ts)
+ * - readWuState (wu-state-reader.ts)
+ *
+ * @module ports/context
+ */
+export {};