@lumenflow/core 1.0.0

package/dist/constants/dora-constants.d.ts

@@ -0,0 +1,49 @@
+/**
+ * DORA Metrics Constants
+ *
+ * Thresholds based on "Accelerate" research by Nicole Forsgren, Jez Humble, Gene Kim.
+ * Used by calculate-dora-metrics.mjs.
+ */
+/** Deployment frequency classification thresholds (deploys per week) */
+export declare const DEPLOYMENT_FREQUENCY: {
+    /** Elite: >5 deploys per week */
+    ELITE: number;
+    /** High: 1-5 deploys per week */
+    HIGH: number;
+    /** Medium: ~1 deploy per month (0.25/week) */
+    MEDIUM: number;
+};
+/** Lead time classification thresholds (hours) */
+export declare const LEAD_TIME_HOURS: {
+    /** Elite: <24 hours (<1 day) */
+    ELITE: number;
+    /** High: <168 hours (<7 days) */
+    HIGH: number;
+    /** Medium: <720 hours (<30 days) */
+    MEDIUM: number;
+};
+/** Change failure rate classification thresholds (percentage) */
+export declare const CFR_PERCENT: {
+    /** Elite: <15% failures */
+    ELITE: number;
+    /** High: 15-30% failures */
+    HIGH: number;
+    /** Medium: 30-45% failures */
+    MEDIUM: number;
+};
+/** Mean time to recovery classification thresholds (hours) */
+export declare const MTTR_HOURS: {
+    /** Elite: <1 hour */
+    ELITE: number;
+    /** High: <24 hours (<1 day) */
+    HIGH: number;
+    /** Medium: <168 hours (<7 days) */
+    MEDIUM: number;
+};
+/** Statistical constants */
+export declare const STATISTICS: {
+    /** 90th percentile for p90Hours calculation */
+    P90_PERCENTILE: number;
+    /** Decimal places for rounding (10 = 1 decimal place) */
+    ROUNDING_FACTOR: number;
+};

package/dist/constants/dora-constants.js

@@ -0,0 +1,53 @@
+/**
+ * DORA Metrics Constants
+ *
+ * Thresholds based on "Accelerate" research by Nicole Forsgren, Jez Humble, Gene Kim.
+ * Used by calculate-dora-metrics.mjs.
+ */
+/** Deployment frequency classification thresholds (deploys per week) */
+export const DEPLOYMENT_FREQUENCY = {
+    /** Elite: >5 deploys per week */
+    ELITE: 5,
+    /** High: 1-5 deploys per week */
+    HIGH: 1,
+    /** Medium: ~1 deploy per month (0.25/week) */
+    MEDIUM: 0.25,
+    // Low: <0.25 deploys per week (implicit)
+};
+/** Lead time classification thresholds (hours) */
+export const LEAD_TIME_HOURS = {
+    /** Elite: <24 hours (<1 day) */
+    ELITE: 24,
+    /** High: <168 hours (<7 days) */
+    HIGH: 168,
+    /** Medium: <720 hours (<30 days) */
+    MEDIUM: 720,
+    // Low: >720 hours (implicit)
+};
+/** Change failure rate classification thresholds (percentage) */
+export const CFR_PERCENT = {
+    /** Elite: <15% failures */
+    ELITE: 15,
+    /** High: 15-30% failures */
+    HIGH: 30,
+    /** Medium: 30-45% failures */
+    MEDIUM: 45,
+    // Low: >45% failures (implicit)
+};
+/** Mean time to recovery classification thresholds (hours) */
+export const MTTR_HOURS = {
+    /** Elite: <1 hour */
+    ELITE: 1,
+    /** High: <24 hours (<1 day) */
+    HIGH: 24,
+    /** Medium: <168 hours (<7 days) */
+    MEDIUM: 168,
+    // Low: >168 hours (implicit)
+};
+/** Statistical constants */
+export const STATISTICS = {
+    /** 90th percentile for p90Hours calculation */
+    P90_PERCENTILE: 0.9,
+    /** Decimal places for rounding (10 = 1 decimal place) */
+    ROUNDING_FACTOR: 10,
+};

package/dist/constants/gate-constants.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Gate Configuration Constants
+ *
+ * Centralizes magic numbers for pre-commit and local gates.
+ * Used by gates-pre-commit.mjs and gates-local.mjs.
+ */
+/** Gate execution configuration */
+export declare const GATE_CONFIG: {
+    /** Maximum execution time per gate step (ms) */
+    TIMEOUT_MS: number;
+    /** Maximum file size allowed in commits (bytes) - 5MB */
+    MAX_FILE_SIZE_BYTES: number;
+    /** Total number of gates (for progress display) */
+    TOTAL_GATES: number;
+};

package/dist/constants/gate-constants.js

@@ -0,0 +1,15 @@
+/**
+ * Gate Configuration Constants
+ *
+ * Centralizes magic numbers for pre-commit and local gates.
+ * Used by gates-pre-commit.mjs and gates-local.mjs.
+ */
+/** Gate execution configuration */
+export const GATE_CONFIG = {
+    /** Maximum execution time per gate step (ms) */
+    TIMEOUT_MS: 180000,
+    /** Maximum file size allowed in commits (bytes) - 5MB */
+    MAX_FILE_SIZE_BYTES: 5 * 1024 * 1024,
+    /** Total number of gates (for progress display) */
+    TOTAL_GATES: 14,
+};

package/dist/constants/linter-constants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Linter Configuration Constants
+ *
+ * Centralizes magic numbers for spec-linter and related validation tools.
+ * Used by packages/linters/spec-linter.mjs.
+ */
+/** Spec linter configuration */
+export declare const LINTER_CONFIG: {
+    /** Watchdog timeout for long-running linter operations (ms) */
+    WATCHDOG_TIMEOUT_MS: number;
+    /**
+     * Maximum allowed glass surfaces in UI components.
+     * Per Beacon spec glass cap artifacts rule.
+     */
+    MAX_GLASS_SURFACES: number;
+};

package/dist/constants/linter-constants.js

@@ -0,0 +1,16 @@
+/**
+ * Linter Configuration Constants
+ *
+ * Centralizes magic numbers for spec-linter and related validation tools.
+ * Used by packages/linters/spec-linter.mjs.
+ */
+/** Spec linter configuration */
+export const LINTER_CONFIG = {
+    /** Watchdog timeout for long-running linter operations (ms) */
+    WATCHDOG_TIMEOUT_MS: 55000,
+    /**
+     * Maximum allowed glass surfaces in UI components.
+     * Per Beacon spec glass cap artifacts rule.
+     */
+    MAX_GLASS_SURFACES: 6,
+};

package/dist/constants/tokenizer-constants.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tokenizer Constants
+ *
+ * Configuration for token estimation in documentation files.
+ * Used by token-count.mjs.
+ */
+/** Token estimation configuration */
+export declare const TOKENIZER: {
+    /**
+     * Word to token ratio for estimation.
+     * Industry standard approximation for GPT-family models.
+     * Anthropic's Claude uses similar tokenization.
+     */
+    WORD_TO_TOKEN_RATIO: number;
+};

package/dist/constants/tokenizer-constants.js

@@ -0,0 +1,15 @@
+/**
+ * Tokenizer Constants
+ *
+ * Configuration for token estimation in documentation files.
+ * Used by token-count.mjs.
+ */
+/** Token estimation configuration */
+export const TOKENIZER = {
+    /**
+     * Word to token ratio for estimation.
+     * Industry standard approximation for GPT-family models.
+     * Anthropic's Claude uses similar tokenization.
+     */
+    WORD_TO_TOKEN_RATIO: 1.33,
+};

package/dist/core/scope-checker.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @file scope-checker.mjs
+ * @description WU scope validation and code_paths enforcement (WU-1397)
+ *
+ * Provides runtime validation that file modifications stay within WU code_paths.
+ * Prevents scope creep and ensures agents only modify authorized files.
+ *
+ * Features:
+ * - Load code_paths from active WU YAML
+ * - Validate file paths against glob patterns
+ * - Throw descriptive errors for scope violations
+ * - Support both exact paths and glob patterns
+ *
+ * Used by wu- scripts and future file operation guards.
+ *
+ * @see {@link tools/lib/core/worktree-guard.mjs} - WU context detection
+ * @see {@link tools/lib/wu-schema.mjs} - WU YAML parsing
+ */
+import { getWUContext } from './worktree-guard.js';
+/**
+ * Load WU YAML data for a given WU ID
+ *
+ * Wrapper around readWU that constructs the path.
+ * Exported for testing injection.
+ *
+ * @param {string} wuId - WU identifier
+ * @returns {Object} Parsed WU YAML
+ * @private
+ */
+declare function loadWUYaml(wuId: any): any;
+/**
+ * Options for getActiveScope
+ */
+interface GetActiveScopeOptions {
+    /** WU context getter (for testing) */
+    getWUContext?: typeof getWUContext;
+    /** WU YAML loader (for testing) */
+    loadWUYaml?: typeof loadWUYaml;
+}
+/**
+ * Get active WU scope (WU ID + code_paths)
+ *
+ * Retrieves the current WU context and loads code_paths from WU YAML.
+ * Returns null if not in a WU workspace.
+ *
+ * @param {GetActiveScopeOptions} [options] - Options
+ * @returns {Promise<Object|null>} Scope object {wuId, code_paths} or null
+ *
+ * @example
+ * const scope = await getActiveScope();
+ * if (scope) {
+ *   console.log(`WU ${scope.wuId} code_paths:`, scope.code_paths);
+ * }
+ */
+export declare function getActiveScope(options?: GetActiveScopeOptions): Promise<{
+    wuId: string;
+    code_paths: any;
+}>;
+/**
+ * Check if a file path is within WU scope
+ *
+ * Validates a file path against the WU's code_paths using glob matching.
+ * Supports exact paths and glob patterns (*, **, {a,b}, etc.).
+ *
+ * Empty code_paths = no restrictions (documentation/process WUs).
+ *
+ * @param {string} filePath - File path to check
+ * @param {Object|null} scope - Scope object from getActiveScope()
+ * @param {string} scope.wuId - WU identifier
+ * @param {string[]} scope.code_paths - Allowed file paths/patterns
+ * @returns {boolean} True if path is in scope, false otherwise
+ *
+ * @example
+ * const scope = await getActiveScope();
+ * if (isPathInScope('apps/web/src/Header.tsx', scope)) {
+ *   console.log('Path is in scope');
+ * }
+ */
+export declare function isPathInScope(filePath: any, scope: any): any;
+/**
+ * Assert that a file path is within WU scope
+ *
+ * Throws descriptive error if path is outside WU code_paths.
+ * Use this for write operations that must enforce scope boundaries.
+ *
+ * @param {string} filePath - File path to check
+ * @param {Object|null} scope - Scope object from getActiveScope()
+ * @param {string} [operation] - Operation name for error message context
+ * @throws {Error} If path is outside scope or no scope available
+ *
+ * @example
+ * const scope = await getActiveScope();
+ * assertPathInScope('apps/web/src/Header.tsx', scope, 'file write');
+ * // Throws if path not in WU code_paths
+ */
+export declare function assertPathInScope(filePath: any, scope: any, operation?: string): void;
+export {};

package/dist/core/scope-checker.js

@@ -0,0 +1,163 @@
+/**
+ * @file scope-checker.mjs
+ * @description WU scope validation and code_paths enforcement (WU-1397)
+ *
+ * Provides runtime validation that file modifications stay within WU code_paths.
+ * Prevents scope creep and ensures agents only modify authorized files.
+ *
+ * Features:
+ * - Load code_paths from active WU YAML
+ * - Validate file paths against glob patterns
+ * - Throw descriptive errors for scope violations
+ * - Support both exact paths and glob patterns
+ *
+ * Used by wu- scripts and future file operation guards.
+ *
+ * @see {@link tools/lib/core/worktree-guard.mjs} - WU context detection
+ * @see {@link tools/lib/wu-schema.mjs} - WU YAML parsing
+ */
+import micromatch from 'micromatch';
+import { getWUContext } from './worktree-guard.js';
+import { readWU } from '../wu-yaml.js';
+import { WU_PATHS } from '../wu-paths.js';
+/**
+ * Normalize path separators to forward slashes
+ *
+ * Handles both Unix and Windows path separators for cross-platform compatibility.
+ *
+ * @param {string} p - Path to normalize
+ * @returns {string} Path with forward slashes
+ * @private
+ */
+function normalizePath(p) {
+    return p.replace(/\\/g, '/');
+}
+/**
+ * Load WU YAML data for a given WU ID
+ *
+ * Wrapper around readWU that constructs the path.
+ * Exported for testing injection.
+ *
+ * @param {string} wuId - WU identifier
+ * @returns {Object} Parsed WU YAML
+ * @private
+ */
+function loadWUYaml(wuId) {
+    const wuPath = WU_PATHS.WU(wuId);
+    return readWU(wuPath, wuId);
+}
+/**
+ * Get active WU scope (WU ID + code_paths)
+ *
+ * Retrieves the current WU context and loads code_paths from WU YAML.
+ * Returns null if not in a WU workspace.
+ *
+ * @param {GetActiveScopeOptions} [options] - Options
+ * @returns {Promise<Object|null>} Scope object {wuId, code_paths} or null
+ *
+ * @example
+ * const scope = await getActiveScope();
+ * if (scope) {
+ *   console.log(`WU ${scope.wuId} code_paths:`, scope.code_paths);
+ * }
+ */
+export async function getActiveScope(options = {}) {
+    const getContextFn = options.getWUContext || getWUContext;
+    const loadYamlFn = options.loadWUYaml || loadWUYaml;
+    // Get current WU context from worktree path or git branch
+    const context = await getContextFn();
+    if (!context) {
+        return null;
+    }
+    // Load WU YAML to get code_paths
+    const wuData = loadYamlFn(context.wuId);
+    return {
+        wuId: context.wuId,
+        code_paths: wuData.code_paths || [],
+    };
+}
+/**
+ * Check if a file path is within WU scope
+ *
+ * Validates a file path against the WU's code_paths using glob matching.
+ * Supports exact paths and glob patterns (*, **, {a,b}, etc.).
+ *
+ * Empty code_paths = no restrictions (documentation/process WUs).
+ *
+ * @param {string} filePath - File path to check
+ * @param {Object|null} scope - Scope object from getActiveScope()
+ * @param {string} scope.wuId - WU identifier
+ * @param {string[]} scope.code_paths - Allowed file paths/patterns
+ * @returns {boolean} True if path is in scope, false otherwise
+ *
+ * @example
+ * const scope = await getActiveScope();
+ * if (isPathInScope('apps/web/src/Header.tsx', scope)) {
+ *   console.log('Path is in scope');
+ * }
+ */
+export function isPathInScope(filePath, scope) {
+    if (!scope) {
+        return false;
+    }
+    // Empty code_paths = no restrictions (documentation/process WUs)
+    if (!scope.code_paths || scope.code_paths.length === 0) {
+        return true;
+    }
+    // Normalize path separators for cross-platform compatibility
+    const normalizedPath = normalizePath(filePath);
+    // Check exact match first (fast path)
+    if (scope.code_paths.includes(normalizedPath)) {
+        return true;
+    }
+    // Check glob patterns using micromatch
+    return micromatch.isMatch(normalizedPath, scope.code_paths);
+}
+/**
+ * Assert that a file path is within WU scope
+ *
+ * Throws descriptive error if path is outside WU code_paths.
+ * Use this for write operations that must enforce scope boundaries.
+ *
+ * @param {string} filePath - File path to check
+ * @param {Object|null} scope - Scope object from getActiveScope()
+ * @param {string} [operation] - Operation name for error message context
+ * @throws {Error} If path is outside scope or no scope available
+ *
+ * @example
+ * const scope = await getActiveScope();
+ * assertPathInScope('apps/web/src/Header.tsx', scope, 'file write');
+ * // Throws if path not in WU code_paths
+ */
+export function assertPathInScope(filePath, scope, operation = 'this operation') {
+    if (!scope) {
+        throw new Error(`❌ SCOPE VIOLATION: No active WU context.
+
+Operation: ${operation}
+File path: ${filePath}
+
+You must claim a WU before performing operations.
+Run: pnpm wu:claim --id WU-XXX --lane "<lane>"
+`);
+    }
+    if (!isPathInScope(filePath, scope)) {
+        const normalizedPath = normalizePath(filePath);
+        throw new Error(`❌ SCOPE VIOLATION: File path outside WU code_paths.
+
+Operation: ${operation}
+WU ID: ${scope.wuId}
+File path: ${normalizedPath}
+
+Allowed code_paths:
+${scope.code_paths.map((p) => `  - ${p}`).join('\n')}
+
+This file is not authorized for modification in this WU.
+Either:
+  1. Add this path to code_paths in WU YAML (if legitimately needed)
+  2. Create a separate WU for this change
+  3. Choose a different file within scope
+
+See: CLAUDE.md §2 (Worktree Discipline)
+`);
+    }
+}

package/dist/core/tool-runner.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @file tool-runner.mjs
+ * @description Unified tool execution layer integrating all core components (WU-1398)
+ *
+ * This module provides a higher-order function pattern for executing tools with:
+ * - Input validation via Zod schemas (tool.schemas.ts)
+ * - Worktree context detection (worktree-guard.mjs)
+ * - Scope validation against code_paths (scope-checker.mjs)
+ * - Audit logging for telemetry (.beacon/telemetry/tools.ndjson)
+ * - Consistent error handling with agent-friendly messages
+ *
+ * Usage:
+ *   import { runTool, ToolRunner, createToolConfig } from './tool-runner.js';
+ *
+ *   // Direct invocation
+ *   const result = await runTool(toolDefinition, { arg: 'value' });
+ *
+ *   // Registry-based invocation
+ *   const runner = new ToolRunner();
+ *   runner.register(myTool);
+ *   const result = await runner.run('tool:name', { arg: 'value' });
+ *
+ * @see tools/lib/core/tool.schemas.ts - Zod schemas for tool I/O
+ * @see tools/lib/core/worktree-guard.mjs - WU context detection
+ * @see tools/lib/core/scope-checker.mjs - Code path validation
+ */
+interface ToolMetadata {
+    name: string;
+    description: string;
+    domain?: string;
+    permission: string;
+    version?: string;
+}
+interface ToolDefinition {
+    metadata: ToolMetadata;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    execute: (input: unknown, context?: unknown) => Promise<unknown>;
+}
+interface ToolConfigOptions {
+    requiresWorktree?: boolean;
+    requiresScope?: boolean;
+    enableAuditLog?: boolean;
+    timeoutMs?: number;
+}
+interface ToolConfig {
+    requiresWorktree: boolean;
+    requiresScope: boolean;
+    enableAuditLog: boolean;
+    timeoutMs: number;
+}
+interface RunToolOptions {
+    dependencies?: Record<string, unknown>;
+    config?: ToolConfigOptions;
+    context?: unknown;
+}
+interface ToolRunnerOptions {
+    enableAuditLog?: boolean;
+    timeoutMs?: number;
+    dependencies?: Record<string, unknown>;
+}
+interface ListToolsOptions {
+    domain?: string;
+}
+/**
+ * Default configuration values for tool runner
+ */
+export declare const RUNNER_DEFAULTS: {
+    /** Default timeout for tool execution in milliseconds */
+    TIMEOUT_MS: number;
+    /** Enable audit logging by default */
+    ENABLE_AUDIT_LOG: boolean;
+    /** Default: read tools don't require worktree */
+    REQUIRES_WORKTREE: boolean;
+    /** Default: read tools don't require scope check */
+    REQUIRES_SCOPE: boolean;
+};
+/**
+ * Create tool configuration with sensible defaults
+ *
+ * @param {object} tool - Tool definition
+ * @param {object} options - Configuration overrides
+ * @returns {object} Merged configuration
+ */
+export declare function createToolConfig(tool: ToolDefinition, options?: ToolConfigOptions): ToolConfig;
+/**
+ * Run a tool with full validation and guards
+ *
+ * @param {object} tool - Tool definition (metadata, inputSchema, execute)
+ * @param {object} input - Tool input arguments
+ * @param {object} options - Execution options
+ * @param {object} options.dependencies - Injected dependencies (for testing)
+ * @param {object} options.config - Configuration overrides
+ * @param {object} options.context - Execution context (sessionId, etc.)
+ * @returns {Promise<object>} Tool output (success/failure with data/error)
+ */
+export declare function runTool(tool: ToolDefinition, input: unknown, options?: RunToolOptions): Promise<unknown>;
+/**
+ * Tool registry and runner class
+ *
+ * Provides a registry for tool definitions and a unified execution interface.
+ */
+export declare class ToolRunner {
+    #private;
+    /**
+     * Create a new ToolRunner instance
+     *
+     * @param {object} options - Runner options
+     * @param {boolean} options.enableAuditLog - Enable audit logging
+     * @param {number} options.timeoutMs - Default timeout
+     * @param {object} options.dependencies - Injected dependencies
+     */
+    constructor(options?: ToolRunnerOptions);
+    /**
+     * Register a tool definition
+     *
+     * @param {object} tool - Tool definition
+     * @throws {Error} If tool with same name already registered
+     */
+    register(tool: ToolDefinition): void;
+    /**
+     * Check if a tool is registered
+     *
+     * @param {string} name - Tool name
+     * @returns {boolean} True if tool exists
+     */
+    hasTool(name: string): boolean;
+    /**
+     * Run a registered tool by name
+     *
+     * @param {string} name - Tool name
+     * @param {object} input - Tool input
+     * @param {object} options - Execution options
+     * @returns {Promise<object>} Tool output
+     */
+    run(name: string, input: unknown, options?: RunToolOptions): Promise<unknown>;
+    /**
+     * Get runner configuration
+     *
+     * @returns {object} Current configuration
+     */
+    getConfig(): {
+        enableAuditLog: boolean;
+        timeoutMs: number;
+    };
+    /**
+     * List all registered tools
+     *
+     * @param {object} options - Filter options
+     * @param {string} options.domain - Filter by domain
+     * @returns {object[]} Array of tool metadata
+     */
+    listTools(options?: ListToolsOptions): Array<{
+        name: string;
+        description: string;
+        domain?: string;
+        permission: string;
+        version?: string;
+    }>;
+}
+export {};