@lumenflow/core 3.1.3 → 3.2.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope-checker.d.ts","sourceRoot":"","sources":["../../src/core/scope-checker.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAiBnD;;;;;;;;;GASG;AACH,iBAAS,UAAU,CAAC,IAAI,EAAE,SAAS,OAGlC;AAED;;GAEG;AACH,UAAU,qBAAqB;IAC7B,sCAAsC;IACtC,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IACnC,mCAAmC;IACnC,UAAU,CAAC,EAAE,OAAO,UAAU,CAAC;CAChC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAE,qBAA0B;;;UAiBvE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,WAoBlE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,EACnB,KAAK,EAAE,SAAS,EAChB,SAAS,SAAmB,QAsC7B"}

package/dist/core/scope-checker.js

@@ -0,0 +1,166 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file scope-checker.ts
+ * @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 packages/@lumenflow/cli/src/lib/core/worktree-guard.ts} - WU context detection
+ * @see {@link packages/@lumenflow/cli/src/lib/wu-schema.ts} - 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)
+`);
+    }
+}
+//# sourceMappingURL=scope-checker.js.map

package/dist/core/scope-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-checker.js","sourceRoot":"","sources":["../../src/core/scope-checker.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,UAAU,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;GAQG;AACH,SAAS,aAAa,CAAC,CAAY;IACjC,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,UAAU,CAAC,IAAe;IACjC,MAAM,MAAM,GAAG,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAC9B,CAAC;AAYD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,UAAiC,EAAE;IACtE,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,YAAY,CAAC;IAC1D,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,UAAU,CAAC;IAEpD,0DAA0D;IAC1D,MAAM,OAAO,GAAG,MAAM,YAAY,EAAE,CAAC;IACrC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAED,iCAAiC;IACjC,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,EAAE;KACpC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAAC,QAAmB,EAAE,KAAgB;IACjE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,KAAK,CAAC;IACf,CAAC;IAED,iEAAiE;IACjE,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6DAA6D;IAC7D,MAAM,cAAc,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAE/C,sCAAsC;IACtC,IAAI,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,uCAAuC;IACvC,OAAO,UAAU,CAAC,OAAO,CAAC,cAAc,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAmB,EACnB,KAAgB,EAChB,SAAS,GAAG,gBAAgB;IAE5B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb;;aAEO,SAAS;aACT,QAAQ;;;;CAIpB,CACI,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;QACpC,MAAM,cAAc,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;QAE/C,MAAM,IAAI,KAAK,CACb;;aAEO,SAAS;SACb,KAAK,CAAC,IAAI;aACN,cAAc;;;EAGzB,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAY,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;;;;;CAS9D,CACI,CAAC;IACJ,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,136 @@
+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 {};
+//# sourceMappingURL=tool-runner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-runner.d.ts","sourceRoot":"","sources":["../../src/core/tool-runner.ts"],"names":[],"mappings":"AA2CA,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,cAAc;IACtB,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAClE;AAED,UAAU,iBAAiB;IACzB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,UAAU;IAClB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,cAAc;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,UAAU,iBAAiB;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,UAAU,gBAAgB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,eAAe;IAC1B,yDAAyD;;IAGzD,sCAAsC;;IAGtC,iDAAiD;;IAGjD,oDAAoD;;CAErD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,OAAO,GAAE,iBAAsB,GAC9B,UAAU,CAWZ;AA2ED;;;;;;;;;;GAUG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAsPlB;AAED;;;;GAIG;AACH,qBAAa,UAAU;;IAKrB;;;;;;;OAOG;gBACS,OAAO,GAAE,iBAAsB;IAQ3C;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAUpC;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B;;;;;;;OAOG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBvF;;;;OAIG;IACH,SAAS,IAAI;QAAE,cAAc,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAI3D;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,KAAK,CAAC;QAC/C,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CAyBH"}