@lumenflow/core 1.0.0

package/dist/ports/dashboard-renderer.port.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Dashboard Renderer Port
+ *
+ * Hexagonal Architecture - Output Port
+ * Defines the contract for rendering orchestration dashboard data to any UI.
+ * This abstraction allows the application layer to remain independent of
+ * specific rendering implementations.
+ *
+ * Current Implementations:
+ * - TerminalDashboardRenderer (WU-1322) - ASCII/ANSI terminal output
+ *
+ * Future Implementations:
+ * - WebDashboardRenderer - Browser-based UI
+ * - VSCodeWebviewRenderer - VS Code extension panel
+ *
+ * SOLID Principles:
+ * - Dependency Inversion: Use cases depend on this abstraction, not concrete renderers
+ * - Interface Segregation: Focused on rendering, no data fetching concerns
+ * - Open/Closed: New renderers can be added without modifying existing code
+ *
+ * @module dashboard-renderer.port
+ * @see {@link ../domain/orchestration.types.ts} - Types used in this interface
+ * @see {@link ../../adapters/terminal-renderer.adapter.ts} - Terminal implementation (WU-1322)
+ */
+import type { DashboardData, Suggestion, ExecutionPlan, UserChoice } from '../domain/orchestration.types.js';
+/**
+ * Dashboard Renderer Port Interface
+ *
+ * Implementers must provide methods to render all dashboard sections
+ * and handle user interactions for execution plan approval.
+ *
+ * @example
+ * // Implementing a custom renderer
+ * class CustomRenderer implements IDashboardRenderer {
+ *   render(data: DashboardData): void {
+ *     // Render global status, agent metrics, WU progress, timeline, alerts
+ *   }
+ *
+ *   renderSuggestions(suggestions: Suggestion[]): void {
+ *     // Display prioritised suggestions
+ *   }
+ *
+ *   renderPlan(plan: ExecutionPlan): Promise<UserChoice> {
+ *     // Show plan and get user approval
+ *   }
+ *
+ *   clear(): void {
+ *     // Clear previous output
+ *   }
+ * }
+ *
+ * @example
+ * // Using in a use case
+ * class GetDashboardDataUseCase {
+ *   constructor(
+ *     private readonly renderer: IDashboardRenderer,
+ *     private readonly collector: IMetricsCollector,
+ *   ) {}
+ *
+ *   async execute(): Promise<void> {
+ *     const data = await this.collectData();
+ *     this.renderer.render(data);
+ *   }
+ * }
+ */
+export interface IDashboardRenderer {
+    /**
+     * Render the complete dashboard with all sections.
+     *
+     * Sections to render:
+     * 1. Global Status - Active WUs, completed, blocked, gates failing
+     * 2. Agent Small Multiples - Per-agent metrics comparison
+     * 3. WU Progress - DoD progress bars with agent status
+     * 4. Timeline - Recent orchestration events
+     * 5. Alerts - Items requiring attention
+     *
+     * @param data - Complete dashboard data from metrics collector
+     */
+    render(data: DashboardData): void;
+    /**
+     * Render a list of prioritised suggestions.
+     *
+     * Suggestions should be displayed with:
+     * - Priority indicator (HIGH/MEDIUM/LOW)
+     * - Action description
+     * - Reason for suggestion
+     * - Command to execute
+     *
+     * @param suggestions - Ordered list of suggestions (highest priority first)
+     */
+    renderSuggestions(suggestions: Suggestion[]): void;
+    /**
+     * Render an execution plan and get user approval.
+     *
+     * Should display:
+     * - WU being executed
+     * - Ordered list of steps
+     * - Estimated token cost
+     * - Approval prompt (approve/reject/edit)
+     *
+     * @param plan - Proposed execution plan
+     * @returns User's choice (approve, reject, or edit with modifications)
+     */
+    renderPlan(plan: ExecutionPlan): Promise<UserChoice>;
+    /**
+     * Clear any previous dashboard output.
+     *
+     * Used before re-rendering to prevent stale data display.
+     * Implementation depends on output medium (e.g., clear terminal, DOM update).
+     */
+    clear(): void;
+}

package/dist/ports/dashboard-renderer.port.js

@@ -0,0 +1,25 @@
+/**
+ * Dashboard Renderer Port
+ *
+ * Hexagonal Architecture - Output Port
+ * Defines the contract for rendering orchestration dashboard data to any UI.
+ * This abstraction allows the application layer to remain independent of
+ * specific rendering implementations.
+ *
+ * Current Implementations:
+ * - TerminalDashboardRenderer (WU-1322) - ASCII/ANSI terminal output
+ *
+ * Future Implementations:
+ * - WebDashboardRenderer - Browser-based UI
+ * - VSCodeWebviewRenderer - VS Code extension panel
+ *
+ * SOLID Principles:
+ * - Dependency Inversion: Use cases depend on this abstraction, not concrete renderers
+ * - Interface Segregation: Focused on rendering, no data fetching concerns
+ * - Open/Closed: New renderers can be added without modifying existing code
+ *
+ * @module dashboard-renderer.port
+ * @see {@link ../domain/orchestration.types.ts} - Types used in this interface
+ * @see {@link ../../adapters/terminal-renderer.adapter.ts} - Terminal implementation (WU-1322)
+ */
+export {};

package/dist/ports/metrics-collector.port.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Metrics Collector Port
+ *
+ * Hexagonal Architecture - Input Port
+ * Defines the contract for collecting orchestration metrics from various sources.
+ * This abstraction allows the application layer to remain independent of
+ * specific data sources (filesystem, database, API, etc.).
+ *
+ * Current Implementations:
+ * - FileSystemMetricsCollector (WU-1321) - Reads WU YAML, status.md, telemetry
+ *
+ * Future Implementations:
+ * - DatabaseMetricsCollector - Query from Supabase
+ * - APIMetricsCollector - Fetch from external service
+ * - MockMetricsCollector - Testing purposes
+ *
+ * SOLID Principles:
+ * - Dependency Inversion: Use cases depend on this abstraction, not concrete collectors
+ * - Interface Segregation: Each method has a single responsibility
+ * - Open/Closed: New collectors can be added without modifying existing code
+ *
+ * @module metrics-collector.port
+ * @see {@link ../domain/orchestration.types.ts} - Types returned by this interface
+ * @see {@link ../../adapters/filesystem-metrics.adapter.ts} - Filesystem implementation (WU-1321)
+ */
+import type { GlobalStatus, AgentMetric, WUProgress, TimelineEvent, Alert } from '../domain/orchestration.types.js';
+/**
+ * Metrics Collector Port Interface
+ *
+ * Implementers must provide methods to collect all metrics needed
+ * for dashboard rendering. Each method should be independently callable
+ * to allow selective data fetching.
+ *
+ * @example
+ * // Implementing a custom collector
+ * class CustomCollector implements IMetricsCollector {
+ *   async getGlobalStatus(): Promise<GlobalStatus> {
+ *     // Collect active WUs, completed count, blocked count, etc.
+ *   }
+ *
+ *   async getAgentMetrics(): Promise<Record<string, AgentMetric>> {
+ *     // Collect per-agent invocation counts, pass rates, timing
+ *   }
+ *
+ *   // ... other methods
+ * }
+ *
+ * @example
+ * // Using in a use case
+ * class GetDashboardDataUseCase {
+ *   constructor(private readonly collector: IMetricsCollector) {}
+ *
+ *   async execute(): Promise<DashboardData> {
+ *     const [globalStatus, agentMetrics, wuProgress, timeline, alerts] =
+ *       await Promise.all([
+ *         this.collector.getGlobalStatus(),
+ *         this.collector.getAgentMetrics(),
+ *         this.collector.getWUProgress(),
+ *         this.collector.getTimeline(this.since24h()),
+ *         this.collector.getAlerts(),
+ *       ]);
+ *
+ *     return { globalStatus, agentMetrics, wuProgress, timeline, alerts };
+ *   }
+ * }
+ */
+export interface IMetricsCollector {
+    /**
+     * Get global orchestration status.
+     *
+     * Should aggregate:
+     * - Count of WUs in 'in_progress' state
+     * - Count of WUs completed in last 24 hours
+     * - Count of currently blocked WUs
+     * - Count of WUs with failing gates
+     * - Longest running WU information
+     * - List of WUs with pending mandatory agents
+     *
+     * @returns Global status metrics
+     */
+    getGlobalStatus(): Promise<GlobalStatus>;
+    /**
+     * Get metrics for all known agents.
+     *
+     * Should collect for each agent:
+     * - Total invocation count
+     * - Pass rate (percentage)
+     * - Average duration in milliseconds
+     * - Information about most recent run
+     *
+     * @returns Record mapping agent names to their metrics
+     */
+    getAgentMetrics(): Promise<Record<string, AgentMetric>>;
+    /**
+     * Get progress for all active WUs.
+     *
+     * Should collect for each active WU:
+     * - WU ID and title
+     * - Lane assignment
+     * - DoD checkpoint progress
+     * - Agent run statuses
+     * - Headline sentence (Tufte principle)
+     *
+     * @returns Array of WU progress records, sorted by lane then WU ID
+     */
+    getWUProgress(): Promise<WUProgress[]>;
+    /**
+     * Get timeline events since a given date.
+     *
+     * Should collect events of types:
+     * - claim: WU claimed
+     * - done: WU completed
+     * - block: WU blocked
+     * - agent: Agent invoked with result
+     * - gates: Gates run with result
+     *
+     * @param since - Only return events after this timestamp
+     * @returns Array of timeline events, sorted by timestamp descending
+     */
+    getTimeline(since: Date): Promise<TimelineEvent[]>;
+    /**
+     * Get current alerts requiring attention.
+     *
+     * Should generate alerts for:
+     * - Mandatory agents not yet invoked (HIGH)
+     * - WUs near completion needing review (MEDIUM)
+     * - Available lanes with ready WUs (LOW)
+     *
+     * @returns Array of alerts, sorted by severity (high first)
+     */
+    getAlerts(): Promise<Alert[]>;
+}

package/dist/ports/metrics-collector.port.js

@@ -0,0 +1,26 @@
+/**
+ * Metrics Collector Port
+ *
+ * Hexagonal Architecture - Input Port
+ * Defines the contract for collecting orchestration metrics from various sources.
+ * This abstraction allows the application layer to remain independent of
+ * specific data sources (filesystem, database, API, etc.).
+ *
+ * Current Implementations:
+ * - FileSystemMetricsCollector (WU-1321) - Reads WU YAML, status.md, telemetry
+ *
+ * Future Implementations:
+ * - DatabaseMetricsCollector - Query from Supabase
+ * - APIMetricsCollector - Fetch from external service
+ * - MockMetricsCollector - Testing purposes
+ *
+ * SOLID Principles:
+ * - Dependency Inversion: Use cases depend on this abstraction, not concrete collectors
+ * - Interface Segregation: Each method has a single responsibility
+ * - Open/Closed: New collectors can be added without modifying existing code
+ *
+ * @module metrics-collector.port
+ * @see {@link ../domain/orchestration.types.ts} - Types returned by this interface
+ * @see {@link ../../adapters/filesystem-metrics.adapter.ts} - Filesystem implementation (WU-1321)
+ */
+export {};

package/dist/process-detector.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Background Process Detector (WU-1381)
+ *
+ * Detects running background processes that might interfere with wu:done
+ * gates execution. Warns agents when pnpm/node processes are running
+ * in the worktree directory to prevent confusion from mixed output.
+ *
+ * This is a NON-BLOCKING pre-flight check - it warns but doesn't fail wu:done.
+ *
+ * @see {@link tools/wu-done.mjs} - Integrates this as pre-flight check
+ * @see {@link tools/lib/wu-constants.mjs} - Constants for log prefixes
+ */
+/**
+ * Re-export interfering process names for external consumers.
+ * Source of truth is PROCESS_DETECTION.INTERFERING_NAMES in wu-constants.mjs
+ */
+export declare const INTERFERING_PROCESS_NAMES: string[];
+/**
+ * Filter processes that might interfere with wu:done in a specific worktree.
+ *
+ * A process is considered interfering if:
+ * 1. Its command contains the worktree path (directly running in worktree)
+ * 2. Its name matches known interfering process names (may affect gates)
+ *
+ * @param {Array<{pid: number, name: string, cmd?: string}>} processes - Process list from ps-list
+ * @param {string|null|undefined} worktreePath - Path to the worktree directory
+ * @returns {Array<{pid: number, name: string, cmd?: string}>} Filtered processes
+ *
+ * @example
+ * const processes = await psList();
+ * const interfering = filterProcessesForWorktree(processes, '/path/to/worktree');
+ */
+export declare function filterProcessesForWorktree(processes: any, worktreePath: any): any;
+/**
+ * Build a warning message for detected background processes.
+ *
+ * @param {Array<{pid: number, name: string, cmd?: string}>} processes - Detected processes
+ * @returns {string} Formatted warning message
+ */
+export declare function buildWarningMessage(processes: any): string;
+/**
+ * Detect background processes that might interfere with wu:done.
+ *
+ * Queries running processes and filters for those that might cause
+ * issues during gates execution. Returns detection result with
+ * warning messages suitable for display.
+ *
+ * @param {string} worktreePath - Path to the worktree directory
+ * @returns {Promise<{hasProcesses: boolean, processes: Array, warnings: string[], error?: string}>}
+ *
+ * @example
+ * const result = await detectBackgroundProcesses('/path/to/worktree');
+ * if (result.hasProcesses) {
+ *   console.warn(result.warnings.join('\n'));
+ * }
+ */
+export declare function detectBackgroundProcesses(worktreePath: any): Promise<{
+    hasProcesses: boolean;
+    processes: any[];
+    warnings: any[];
+} | {
+    hasProcesses: boolean;
+    processes: any;
+    warnings: string[];
+} | {
+    error: any;
+    hasProcesses: boolean;
+    processes: any[];
+    warnings: any[];
+}>;
+/**
+ * Run background process detection as a pre-flight check.
+ *
+ * This is the main entry point for wu-done.mjs integration.
+ * Logs warnings if background processes are detected but does NOT fail.
+ *
+ * @param {string} worktreePath - Path to the worktree directory
+ * @returns {Promise<void>}
+ *
+ * @example
+ * // In wu-done.mjs pre-flight checks:
+ * await runBackgroundProcessCheck(worktreePath);
+ */
+export declare function runBackgroundProcessCheck(worktreePath: any): Promise<void>;

package/dist/process-detector.js

@@ -0,0 +1,172 @@
+/**
+ * Background Process Detector (WU-1381)
+ *
+ * Detects running background processes that might interfere with wu:done
+ * gates execution. Warns agents when pnpm/node processes are running
+ * in the worktree directory to prevent confusion from mixed output.
+ *
+ * This is a NON-BLOCKING pre-flight check - it warns but doesn't fail wu:done.
+ *
+ * @see {@link tools/wu-done.mjs} - Integrates this as pre-flight check
+ * @see {@link tools/lib/wu-constants.mjs} - Constants for log prefixes
+ */
+import psList from 'ps-list';
+import { LOG_PREFIX, EMOJI, PROCESS_DETECTION, STRING_LITERALS } from './wu-constants.js';
+/**
+ * Re-export interfering process names for external consumers.
+ * Source of truth is PROCESS_DETECTION.INTERFERING_NAMES in wu-constants.mjs
+ */
+export const INTERFERING_PROCESS_NAMES = PROCESS_DETECTION.INTERFERING_NAMES;
+/**
+ * Filter processes that might interfere with wu:done in a specific worktree.
+ *
+ * A process is considered interfering if:
+ * 1. Its command contains the worktree path (directly running in worktree)
+ * 2. Its name matches known interfering process names (may affect gates)
+ *
+ * @param {Array<{pid: number, name: string, cmd?: string}>} processes - Process list from ps-list
+ * @param {string|null|undefined} worktreePath - Path to the worktree directory
+ * @returns {Array<{pid: number, name: string, cmd?: string}>} Filtered processes
+ *
+ * @example
+ * const processes = await psList();
+ * const interfering = filterProcessesForWorktree(processes, '/path/to/worktree');
+ */
+export function filterProcessesForWorktree(processes, worktreePath) {
+    // Handle null/undefined worktree path
+    if (!worktreePath) {
+        return [];
+    }
+    // Handle empty processes array
+    if (!processes || processes.length === 0) {
+        return [];
+    }
+    return processes.filter((proc) => {
+        const cmd = proc.cmd || '';
+        // Include only processes running in the worktree (cmd contains worktree path)
+        // We require worktree context to avoid flagging unrelated system processes
+        return cmd.includes(worktreePath);
+    });
+}
+/**
+ * Build a warning message for detected background processes.
+ *
+ * @param {Array<{pid: number, name: string, cmd?: string}>} processes - Detected processes
+ * @returns {string} Formatted warning message
+ */
+export function buildWarningMessage(processes) {
+    if (!processes || processes.length === 0) {
+        return '';
+    }
+    const processCount = processes.length;
+    const cmdLimit = PROCESS_DETECTION.CMD_DISPLAY_LIMIT;
+    const processList = processes
+        .map((p) => {
+        const cmd = p.cmd
+            ? ` (${p.cmd.slice(0, cmdLimit)}${p.cmd.length > cmdLimit ? '...' : ''})`
+            : '';
+        return `    - PID ${p.pid}: ${p.name}${cmd}`;
+    })
+        .join(STRING_LITERALS.NEWLINE);
+    const killCommands = processes.map((p) => `kill ${p.pid}`).join(' && ');
+    return `
+${EMOJI.WARNING} BACKGROUND PROCESSES DETECTED ${EMOJI.WARNING}
+
+Found ${processCount} process(es) that may interfere with wu:done:
+
+${processList}
+
+These processes may cause:
+  - Mixed stdout/stderr output (confusing errors)
+  - File lock conflicts during tests
+  - Resource contention affecting gate performance
+
+Options:
+  1. Wait for processes to complete naturally
+  2. Kill interfering processes:
+     ${killCommands}
+  3. Proceed anyway (output may be mixed)
+
+This is a NON-BLOCKING warning. wu:done will continue.
+`;
+}
+/**
+ * Detect background processes that might interfere with wu:done.
+ *
+ * Queries running processes and filters for those that might cause
+ * issues during gates execution. Returns detection result with
+ * warning messages suitable for display.
+ *
+ * @param {string} worktreePath - Path to the worktree directory
+ * @returns {Promise<{hasProcesses: boolean, processes: Array, warnings: string[], error?: string}>}
+ *
+ * @example
+ * const result = await detectBackgroundProcesses('/path/to/worktree');
+ * if (result.hasProcesses) {
+ *   console.warn(result.warnings.join('\n'));
+ * }
+ */
+export async function detectBackgroundProcesses(worktreePath) {
+    const noProcessesResult = {
+        hasProcesses: false,
+        processes: [],
+        warnings: [],
+    };
+    // Handle invalid worktree path
+    if (!worktreePath) {
+        return noProcessesResult;
+    }
+    try {
+        // Get all running processes
+        const allProcesses = await psList();
+        // Filter for worktree-related interfering processes
+        const interferingProcesses = filterProcessesForWorktree(allProcesses, worktreePath);
+        // Exclude the current process (wu-done itself)
+        const currentPid = process.pid;
+        const externalProcesses = interferingProcesses.filter((p) => p.pid !== currentPid);
+        if (externalProcesses.length === 0) {
+            return noProcessesResult;
+        }
+        // Build warning message
+        const warningMessage = buildWarningMessage(externalProcesses);
+        return {
+            hasProcesses: true,
+            processes: externalProcesses,
+            warnings: [warningMessage],
+        };
+    }
+    catch (error) {
+        // Handle ps-list errors gracefully (permission issues, etc.)
+        // Don't block wu:done on process detection failure
+        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not detect background processes: ${error.message}`);
+        return {
+            ...noProcessesResult,
+            error: error.message,
+        };
+    }
+}
+/**
+ * Run background process detection as a pre-flight check.
+ *
+ * This is the main entry point for wu-done.mjs integration.
+ * Logs warnings if background processes are detected but does NOT fail.
+ *
+ * @param {string} worktreePath - Path to the worktree directory
+ * @returns {Promise<void>}
+ *
+ * @example
+ * // In wu-done.mjs pre-flight checks:
+ * await runBackgroundProcessCheck(worktreePath);
+ */
+export async function runBackgroundProcessCheck(worktreePath) {
+    console.log(`${LOG_PREFIX.DONE} Checking for background processes...`);
+    const result = await detectBackgroundProcesses(worktreePath);
+    if (result.hasProcesses) {
+        // Log warning but don't fail
+        console.warn(`\n${LOG_PREFIX.DONE} ${result.warnings.join(STRING_LITERALS.NEWLINE)}`);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Proceeding with wu:done despite background processes`);
+    }
+    else {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} No interfering background processes detected`);
+    }
+}

package/dist/prompt-linter.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Prompt Linter with 3-Tier Token Budget Enforcement
+ *
+ * Enforces token budget constraints on LLM prompts:
+ * - BLOCK: >450 tokens OR +>120 delta (exit 1)
+ * - WARN: ≥400 tokens OR +>50 delta (continue, log warning)
+ * - LOG: Always log tokenCount, delta, hash, top 3 longest lines
+ *
+ * Uses proper telemetry via getLogger() (no console spam).
+ *
+ * Part of WU-676: Single-Call LLM Orchestrator token budget enforcement.
+ */
+/**
+ * Load config from YAML file with fallback to defaults
+ * @param {string} configPath - Path to config file (optional)
+ * @returns {Object} Configuration object
+ */
+export declare function loadConfig(configPath?: string): {
+    version: any;
+    token_budgets: {
+        default: {
+            hard_cap: any;
+            warn_threshold: any;
+        };
+        retry: {
+            hard_cap: any;
+        };
+    };
+    delta_budgets: {
+        warn: any;
+        block: any;
+    };
+    retry_pattern: any;
+};
+/**
+ * Options for linting prompts
+ */
+export interface LintPromptsOptions {
+    /** Suppress non-essential output */
+    quiet?: boolean;
+    /** Enable verbose output */
+    verbose?: boolean;
+}
+/**
+ * Main linter function
+ * @param {string[]} filePaths - Prompt files to lint (optional, finds all if empty)
+ * @param {string} mode - Mode (pre-commit, pre-push, ci, local)
+ * @param {string} configPath - Optional config file path
+ * @param {LintPromptsOptions} [options] - Output options
+ * @returns {Promise<{passed: boolean, results: Array, config: Object}>}
+ */
+export declare function lintPrompts(filePaths?: any[], mode?: string, configPath?: any, options?: LintPromptsOptions): Promise<{
+    passed: boolean;
+    results: any[];
+    config: {
+        version: any;
+        token_budgets: {
+            default: {
+                hard_cap: any;
+                warn_threshold: any;
+            };
+            retry: {
+                hard_cap: any;
+            };
+        };
+        delta_budgets: {
+            warn: any;
+            block: any;
+        };
+        retry_pattern: any;
+    };
+}>;