@lumenflow/core 1.0.0

package/dist/lane-validator.d.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Lane-to-Code_Paths Validator (WU-1372)
+ *
+ * Validates that a WU's code_paths are consistent with its assigned lane.
+ * This is an advisory validation - it warns but never blocks wu:claim or wu:done.
+ *
+ * Uses LANE_PATH_PATTERNS from wu-constants.mjs to define which paths
+ * are discouraged for each lane parent.
+ *
+ * Part of INIT-002: Workflow Integrity initiative.
+ *
+ * @see {@link wu-constants.mjs} - LANE_PATH_PATTERNS definition
+ * @see {@link lane-checker.mjs} - extractParent for lane parsing
+ */
+/**
+ * @typedef {object} LaneValidationResult
+ * @property {boolean} hasWarnings - True if any code_paths violate lane patterns
+ * @property {string[]} warnings - Human-readable warning messages
+ * @property {string[]} violations - List of violating code_paths
+ * @property {boolean} skipped - True if validation was skipped (no patterns or no code_paths)
+ */
+/**
+ * Validate WU code_paths against lane's expected patterns.
+ *
+ * Checks if any code_paths match the "exclude" patterns for the lane,
+ * unless they also match an "allowExceptions" pattern.
+ *
+ * @param {object} doc - WU YAML document (parsed)
+ * @param {string} lane - Lane name (e.g., "Operations: Tooling")
+ * @returns {LaneValidationResult} Validation result with warnings if any
+ */
+export declare function validateLaneCodePaths(doc: any, lane: any): {
+    hasWarnings: boolean;
+    warnings: any;
+    violations: any;
+    skipped: boolean;
+};
+/**
+ * Log lane validation warnings to console.
+ *
+ * Helper function to format and display warnings consistently.
+ * Uses LOG_PREFIX.CLAIM format.
+ *
+ * @param {LaneValidationResult} result - Result from validateLaneCodePaths
+ * @param {string} logPrefix - Log prefix (e.g., "[wu-claim]")
+ */
+export declare function logLaneValidationWarnings(result: any, logPrefix?: string): void;

package/dist/lane-validator.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * Lane-to-Code_Paths Validator (WU-1372)
+ *
+ * Validates that a WU's code_paths are consistent with its assigned lane.
+ * This is an advisory validation - it warns but never blocks wu:claim or wu:done.
+ *
+ * Uses LANE_PATH_PATTERNS from wu-constants.mjs to define which paths
+ * are discouraged for each lane parent.
+ *
+ * Part of INIT-002: Workflow Integrity initiative.
+ *
+ * @see {@link wu-constants.mjs} - LANE_PATH_PATTERNS definition
+ * @see {@link lane-checker.mjs} - extractParent for lane parsing
+ */
+import micromatch from 'micromatch';
+import { extractParent } from './lane-checker.js';
+import { LANE_PATH_PATTERNS } from './wu-constants.js';
+/**
+ * @typedef {object} LaneValidationResult
+ * @property {boolean} hasWarnings - True if any code_paths violate lane patterns
+ * @property {string[]} warnings - Human-readable warning messages
+ * @property {string[]} violations - List of violating code_paths
+ * @property {boolean} skipped - True if validation was skipped (no patterns or no code_paths)
+ */
+/**
+ * Validate WU code_paths against lane's expected patterns.
+ *
+ * Checks if any code_paths match the "exclude" patterns for the lane,
+ * unless they also match an "allowExceptions" pattern.
+ *
+ * @param {object} doc - WU YAML document (parsed)
+ * @param {string} lane - Lane name (e.g., "Operations: Tooling")
+ * @returns {LaneValidationResult} Validation result with warnings if any
+ */
+export function validateLaneCodePaths(doc, lane) {
+    const codePaths = doc.code_paths || [];
+    // Skip validation if no code_paths
+    if (!codePaths || codePaths.length === 0) {
+        return {
+            hasWarnings: false,
+            warnings: [],
+            violations: [],
+            skipped: true,
+        };
+    }
+    // Extract parent lane (e.g., "Operations" from "Operations: Tooling")
+    const parentLane = extractParent(lane);
+    // Get patterns for this lane parent
+    const patterns = LANE_PATH_PATTERNS[parentLane];
+    // Skip validation if no patterns defined for this lane
+    if (!patterns) {
+        return {
+            hasWarnings: false,
+            warnings: [],
+            violations: [],
+            skipped: true,
+        };
+    }
+    const { exclude = [], allowExceptions = [] } = patterns;
+    // Find violations: paths that match exclude patterns but NOT exception patterns
+    const violations = codePaths.filter((codePath) => {
+        // Check if path matches any exclude pattern
+        const matchesExclude = micromatch.isMatch(codePath, exclude, { nocase: true });
+        if (!matchesExclude) {
+            return false; // Path doesn't match any exclude pattern, not a violation
+        }
+        // Check if path matches any exception pattern
+        if (allowExceptions.length > 0) {
+            const matchesException = micromatch.isMatch(codePath, allowExceptions, { nocase: true });
+            if (matchesException) {
+                return false; // Path is allowed by exception, not a violation
+            }
+        }
+        return true; // Path matches exclude and no exception, this is a violation
+    });
+    if (violations.length === 0) {
+        return {
+            hasWarnings: false,
+            warnings: [],
+            violations: [],
+            skipped: false,
+        };
+    }
+    // Build warning messages
+    const warnings = violations.map((path) => {
+        return `Lane "${lane}" typically doesn't include "${path}" (expected for different lane)`;
+    });
+    return {
+        hasWarnings: true,
+        warnings,
+        violations,
+        skipped: false,
+    };
+}
+/**
+ * Log lane validation warnings to console.
+ *
+ * Helper function to format and display warnings consistently.
+ * Uses LOG_PREFIX.CLAIM format.
+ *
+ * @param {LaneValidationResult} result - Result from validateLaneCodePaths
+ * @param {string} logPrefix - Log prefix (e.g., "[wu-claim]")
+ */
+export function logLaneValidationWarnings(result, logPrefix = '[wu-claim]') {
+    if (!result.hasWarnings) {
+        return;
+    }
+    console.warn(`${logPrefix} Lane/code_paths mismatch detected (advisory only):`);
+    for (const warning of result.warnings) {
+        console.warn(`${logPrefix}   ${warning}`);
+    }
+    console.warn(`${logPrefix} This is a warning only - proceeding with claim.`);
+}

package/dist/logs-lib.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Logs Library (WU-2064)
+ *
+ * Core library for unified log aggregation following Anthropic's agent logging patterns.
+ * Aggregates logs from multiple sources:
+ * - .logs/web.log (structured JSON from Next.js)
+ * - .beacon/commands.log (git command audit trail)
+ * - .beacon/flow.log (WU flow events)
+ * - .logs/tool-audit.ndjson (Claude Code tool usage audit)
+ *
+ * LIBRARY-FIRST: No general-purpose library exists for project-specific log
+ * aggregation across custom log locations. Uses native JSON.parse like existing
+ * tail-logs.mjs in the codebase.
+ *
+ * @see docs/02-technical/standards/logging.md
+ */
+/**
+ * Log source configurations
+ * Each source has a path relative to project root and a source identifier
+ */
+/**
+ * Log entry structure from JSON logs
+ */
+interface LogEntry {
+    time?: string;
+    level?: string;
+    msg?: string;
+    message?: string;
+    event?: string;
+    _source?: string;
+    [key: string]: unknown;
+}
+/**
+ * Parsed log arguments
+ */
+interface ParsedLogsArgs {
+    last?: number;
+    level?: string;
+    service?: string;
+    filter?: string;
+    json?: boolean;
+    help?: boolean;
+}
+export declare const LOG_SOURCES: {
+    path: string;
+    source: string;
+}[];
+/**
+ * Parse a single log line (NDJSON format)
+ *
+ * @param {string} line - JSON log line
+ * @returns {object|null} Parsed log object or null if invalid
+ */
+export declare function parseLogLine(line: any): any;
+/**
+ * Options for filtering logs
+ */
+export interface FilterLogsOptions {
+    /** Filter by log level (info, warn, error) */
+    level?: string;
+    /** Filter by service/message prefix */
+    service?: string;
+    /** Arbitrary text filter (searches in JSON) */
+    filter?: string;
+    /** Return only last N entries */
+    last?: number;
+}
+/**
+ * Filter log entries by criteria
+ *
+ * @param {object[]} logs - Array of log objects
+ * @param {FilterLogsOptions} options - Filter options
+ * @returns {object[]} Filtered logs
+ */
+export declare function filterLogs(logs: LogEntry[], options?: FilterLogsOptions): LogEntry[];
+/**
+ * Options for aggregating logs
+ */
+export interface AggregateLogsOptions {
+    /** Working directory (defaults to process.cwd()) */
+    cwd?: string;
+}
+/**
+ * Aggregate logs from all configured sources
+ *
+ * @param {AggregateLogsOptions} options - Options
+ * @returns {Promise<object[]>} Aggregated and sorted log entries
+ */
+export declare function aggregateLogs(options?: AggregateLogsOptions): Promise<any[]>;
+/**
+ * Parse command line arguments for logs command
+ *
+ * @param {string[]} args - Command line arguments (without node and script)
+ * @returns {object} Parsed options
+ */
+export declare function parseLogsArgs(args: string[]): ParsedLogsArgs;
+/**
+ * Format a log entry for console display
+ *
+ * @param {object} log - Log object
+ * @returns {string} Formatted log line
+ */
+export declare function formatLogEntry(log: LogEntry): string;
+export {};

package/dist/logs-lib.js

@@ -0,0 +1,207 @@
+/**
+ * Logs Library (WU-2064)
+ *
+ * Core library for unified log aggregation following Anthropic's agent logging patterns.
+ * Aggregates logs from multiple sources:
+ * - .logs/web.log (structured JSON from Next.js)
+ * - .beacon/commands.log (git command audit trail)
+ * - .beacon/flow.log (WU flow events)
+ * - .logs/tool-audit.ndjson (Claude Code tool usage audit)
+ *
+ * LIBRARY-FIRST: No general-purpose library exists for project-specific log
+ * aggregation across custom log locations. Uses native JSON.parse like existing
+ * tail-logs.mjs in the codebase.
+ *
+ * @see docs/02-technical/standards/logging.md
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+export const LOG_SOURCES = [
+    { path: '.logs/web.log', source: 'web.log' },
+    { path: '.beacon/commands.log', source: 'commands.log' },
+    { path: '.beacon/flow.log', source: 'flow.log' },
+    { path: '.logs/tool-audit.ndjson', source: 'tool-audit.ndjson' },
+];
+/**
+ * Parse a single log line (NDJSON format)
+ *
+ * @param {string} line - JSON log line
+ * @returns {object|null} Parsed log object or null if invalid
+ */
+export function parseLogLine(line) {
+    if (!line || typeof line !== 'string') {
+        return null;
+    }
+    const trimmed = line.trim();
+    if (!trimmed) {
+        return null;
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Filter log entries by criteria
+ *
+ * @param {object[]} logs - Array of log objects
+ * @param {FilterLogsOptions} options - Filter options
+ * @returns {object[]} Filtered logs
+ */
+export function filterLogs(logs, options = {}) {
+    const { level, service, filter, last } = options;
+    let result = logs;
+    // Filter by level
+    if (level) {
+        result = result.filter((log) => log.level === level);
+    }
+    // Filter by service (message prefix)
+    if (service) {
+        result = result.filter((log) => {
+            const msg = log.msg || log.message || '';
+            const pattern = '.' + service + '.';
+            return msg.startsWith(service) || msg.includes(pattern);
+        });
+    }
+    // Filter by arbitrary text pattern
+    if (filter) {
+        result = result.filter((log) => {
+            const jsonStr = JSON.stringify(log);
+            return jsonStr.includes(filter);
+        });
+    }
+    // Limit to last N entries
+    if (last && last > 0) {
+        result = result.slice(-last);
+    }
+    return result;
+}
+/**
+ * Read and parse a single log file
+ *
+ * @param {string} filePath - Path to log file
+ * @param {string} source - Source identifier for tagging
+ * @returns {object[]} Parsed log entries with _source field
+ */
+function readLogFile(filePath, source) {
+    if (!existsSync(filePath)) {
+        return [];
+    }
+    try {
+        const content = readFileSync(filePath, 'utf8');
+        const lines = content.split('\n').filter(Boolean);
+        const logs = [];
+        for (const line of lines) {
+            const parsed = parseLogLine(line);
+            if (parsed) {
+                parsed._source = source;
+                logs.push(parsed);
+            }
+        }
+        return logs;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Aggregate logs from all configured sources
+ *
+ * @param {AggregateLogsOptions} options - Options
+ * @returns {Promise<object[]>} Aggregated and sorted log entries
+ */
+export async function aggregateLogs(options = {}) {
+    const { cwd = process.cwd() } = options;
+    const allLogs = [];
+    for (const { path: logPath, source } of LOG_SOURCES) {
+        const fullPath = path.join(cwd, logPath);
+        const logs = readLogFile(fullPath, source);
+        allLogs.push(...logs);
+    }
+    // Sort by time (oldest first)
+    allLogs.sort((a, b) => {
+        const timeA = new Date(a.time || 0).getTime();
+        const timeB = new Date(b.time || 0).getTime();
+        return timeA - timeB;
+    });
+    return allLogs;
+}
+/**
+ * Parse command line arguments for logs command
+ *
+ * @param {string[]} args - Command line arguments (without node and script)
+ * @returns {object} Parsed options
+ */
+export function parseLogsArgs(args) {
+    const result = {};
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === '--last') {
+            i++;
+            result.last = parseInt(args[i], 10);
+        }
+        else if (arg === '--level') {
+            i++;
+            result.level = args[i];
+        }
+        else if (arg === '--service') {
+            i++;
+            result.service = args[i];
+        }
+        else if (arg === '--filter') {
+            i++;
+            result.filter = args[i];
+        }
+        else if (arg === '--json') {
+            result.json = true;
+        }
+        else if (arg === '--help' || arg === '-h') {
+            result.help = true;
+        }
+        // Ignore unknown flags
+        i++;
+    }
+    return result;
+}
+/**
+ * Format a log entry for console display
+ *
+ * @param {object} log - Log object
+ * @returns {string} Formatted log line
+ */
+export function formatLogEntry(log) {
+    const levelColors = {
+        debug: '\x1b[36m', // cyan
+        info: '\x1b[32m', // green
+        warn: '\x1b[33m', // yellow
+        error: '\x1b[31m', // red
+    };
+    const reset = '\x1b[0m';
+    const dim = '\x1b[2m';
+    const level = log.level || 'info';
+    const color = levelColors[level] || reset;
+    const time = log.time
+        ? new Date(log.time).toLocaleTimeString('en-GB', {
+            hour12: false,
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+        })
+        : '??:??:??';
+    const msg = log.msg || log.message || log.event || 'unknown';
+    const source = log._source ? dim + '[' + log._source + ']' + reset : '';
+    // Build metadata string excluding known fields
+    const knownFields = ['time', 'level', 'msg', 'message', 'event', '_source'];
+    const meta = {};
+    for (const [key, value] of Object.entries(log)) {
+        if (!knownFields.includes(key)) {
+            meta[key] = value;
+        }
+    }
+    const metaStr = Object.keys(meta).length > 0 ? ' ' + JSON.stringify(meta) : '';
+    const levelStr = level.toUpperCase().padEnd(5);
+    return color + '[' + time + '] ' + levelStr + reset + ' ' + source + ' ' + msg + metaStr;
+}