@lumenflow/core 3.1.3 → 3.2.1

package/dist/patrol-loop.js

@@ -0,0 +1,197 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Patrol Loop Module (WU-1242)
+ *
+ * Continuous patrol loop for monitoring spawn health.
+ * The 'Witness patrol' pattern - keeps the spawn fleet healthy by
+ * checking status at configurable intervals with exponential backoff
+ * on repeated failures.
+ *
+ * Features:
+ * - Configurable patrol interval (default 5min)
+ * - Exponential backoff on failures (max 1hr)
+ * - Graceful shutdown support
+ * - Cycle callbacks for status reporting
+ * - Error handling with continuation
+ *
+ * @see {@link packages/@lumenflow/cli/src/orchestrate-monitor.ts} - CLI integration
+ * @see {@link packages/@lumenflow/core/src/__tests__/patrol-loop.test.ts} - Tests
+ */
+/**
+ * Default patrol interval (5 minutes in milliseconds)
+ */
+export const DEFAULT_PATROL_INTERVAL_MS = 5 * 60 * 1000;
+/**
+ * Maximum backoff interval (1 hour in milliseconds)
+ */
+export const MAX_BACKOFF_MS = 60 * 60 * 1000;
+/**
+ * Calculates the backoff interval based on consecutive failures.
+ * Uses exponential backoff with a maximum of 1 hour.
+ *
+ * Backoff formula: baseInterval * 2^(failures-1), capped at MAX_BACKOFF_MS
+ *
+ * @param consecutiveFailures - Number of consecutive failures (1-indexed)
+ * @param baseIntervalMs - Base interval in milliseconds
+ * @returns Backoff interval in milliseconds
+ *
+ * @example
+ * calculateBackoff(1, 5*60*1000) // 5 minutes (no backoff yet)
+ * calculateBackoff(2, 5*60*1000) // 10 minutes (2x)
+ * calculateBackoff(3, 5*60*1000) // 20 minutes (4x)
+ */
+export function calculateBackoff(consecutiveFailures, baseIntervalMs) {
+    if (consecutiveFailures <= 1) {
+        return baseIntervalMs;
+    }
+    // Exponential backoff: baseInterval * 2^(failures-1)
+    const multiplier = Math.pow(2, consecutiveFailures - 1);
+    const backoffMs = baseIntervalMs * multiplier;
+    // Cap at maximum backoff
+    return Math.min(backoffMs, MAX_BACKOFF_MS);
+}
+/**
+ * Patrol loop for continuous spawn monitoring.
+ *
+ * @example
+ * const patrol = new PatrolLoop({
+ *   checkFn: async () => {
+ *     const result = await runMonitor();
+ *     return {
+ *       healthy: result.stuckSpawns.length === 0,
+ *       stuckCount: result.stuckSpawns.length,
+ *       zombieCount: result.zombieLocks.length,
+ *     };
+ *   },
+ *   intervalMs: 5 * 60 * 1000, // 5 minutes
+ *   onCycle: (result, meta) => {
+ *     console.log(`Cycle ${meta.cycleNumber}: ${result.healthy ? 'healthy' : 'issues detected'}`);
+ *   },
+ * });
+ *
+ * patrol.start();
+ * // Later...
+ * patrol.stop();
+ */
+export class PatrolLoop {
+    checkFn;
+    baseIntervalMs;
+    onCycle;
+    onError;
+    timer = null;
+    running = false;
+    failures = 0;
+    cycles = 0;
+    /**
+     * Creates a new PatrolLoop instance.
+     *
+     * @param options - Patrol loop configuration
+     */
+    constructor(options) {
+        this.checkFn = options.checkFn;
+        this.baseIntervalMs = options.intervalMs ?? DEFAULT_PATROL_INTERVAL_MS;
+        this.onCycle = options.onCycle;
+        this.onError = options.onError;
+    }
+    /**
+     * The configured base interval in milliseconds.
+     */
+    get intervalMs() {
+        return this.baseIntervalMs;
+    }
+    /**
+     * Whether the patrol loop is currently running.
+     */
+    get isRunning() {
+        return this.running;
+    }
+    /**
+     * Number of consecutive failures (resets on success).
+     */
+    get consecutiveFailures() {
+        return this.failures;
+    }
+    /**
+     * Total number of completed patrol cycles.
+     */
+    get totalCycles() {
+        return this.cycles;
+    }
+    /**
+     * Starts the patrol loop.
+     * Does nothing if already running.
+     */
+    start() {
+        if (this.running) {
+            return; // Already running, don't create duplicate timers
+        }
+        this.running = true;
+        this.scheduleNextCycle();
+    }
+    /**
+     * Stops the patrol loop.
+     * Safe to call even if not running.
+     */
+    stop() {
+        this.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Schedules the next patrol cycle.
+     */
+    scheduleNextCycle() {
+        if (!this.running) {
+            return;
+        }
+        const intervalMs = calculateBackoff(this.failures, this.baseIntervalMs);
+        this.timer = setTimeout(() => {
+            // WU-1551: Add .catch() to prevent unhandled promise rejections
+            void this.runCycle()
+                .then(() => this.scheduleNextCycle())
+                .catch(() => {
+                // Error already handled in runCycle's try/catch.
+                // This .catch() is a safety net to prevent unhandled rejections
+                // if runCycle itself throws before reaching its try/catch.
+                this.scheduleNextCycle();
+            });
+        }, intervalMs);
+    }
+    /**
+     * Runs a single patrol cycle.
+     */
+    async runCycle() {
+        if (!this.running) {
+            return;
+        }
+        this.cycles++;
+        const cycleNumber = this.cycles;
+        try {
+            const result = await this.checkFn();
+            // Success - reset failure count
+            this.failures = 0;
+            // Call cycle callback
+            if (this.onCycle) {
+                const meta = {
+                    cycleNumber,
+                    intervalMs: this.baseIntervalMs,
+                    consecutiveFailures: this.failures,
+                    timestamp: new Date(),
+                };
+                this.onCycle(result, meta);
+            }
+        }
+        catch (error) {
+            // Failure - increment failure count
+            this.failures++;
+            // Call error callback
+            if (this.onError) {
+                this.onError(error instanceof Error ? error : new Error(String(error)), cycleNumber);
+            }
+        }
+    }
+}
+//# sourceMappingURL=patrol-loop.js.map

package/dist/patrol-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patrol-loop.js","sourceRoot":"","sources":["../src/patrol-loop.ts"],"names":[],"mappings":"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"}

package/dist/piped-command-detector.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Check if a command is a piped pnpm dependency command
+ *
+ * Detects patterns like:
+ * - echo "y" | pnpm add foo
+ * - yes | pnpm install
+ * - pnpm add foo < /dev/null
+ * - pnpm install <<< "y"
+ *
+ * Does NOT flag:
+ * - pnpm test | grep foo (pnpm not receiving input)
+ * - pnpm add foo (no pipe)
+ *
+ * @param {string} command - Shell command to analyze
+ * @returns {boolean} True if command is a piped pnpm dependency command
+ */
+export declare function isPipedPnpmCommand(command: UnsafeAny): boolean;
+/**
+ * Check if a command contains UnsafeAny dependency-mutating pnpm subcommand
+ *
+ * @param {string} command - Shell command to analyze
+ * @returns {boolean} True if command contains pnpm dependency mutation
+ */
+export declare function containsPnpmDependencyCommand(command: UnsafeAny): boolean;
+//# sourceMappingURL=piped-command-detector.d.ts.map

package/dist/piped-command-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"piped-command-detector.d.ts","sourceRoot":"","sources":["../src/piped-command-detector.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,WAqBpD;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,SAAS,WAQ/D"}

package/dist/piped-command-detector.js

@@ -0,0 +1,67 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU-2278: Piped Command Detection
+ *
+ * Detects when pnpm dependency commands are being executed with piped input,
+ * which can bypass interactive prompts and cause security issues.
+ *
+ * Note: No external library exists for this specific shell command analysis.
+ *
+ * @module piped-command-detector
+ */
+/**
+ * List of pnpm commands that mutate dependencies
+ * @constant {string[]}
+ */
+const DEPENDENCY_COMMANDS = ['add', 'install', 'i', 'remove', 'rm', 'uninstall', 'update', 'up'];
+/**
+ * Check if a command is a piped pnpm dependency command
+ *
+ * Detects patterns like:
+ * - echo "y" | pnpm add foo
+ * - yes | pnpm install
+ * - pnpm add foo < /dev/null
+ * - pnpm install <<< "y"
+ *
+ * Does NOT flag:
+ * - pnpm test | grep foo (pnpm not receiving input)
+ * - pnpm add foo (no pipe)
+ *
+ * @param {string} command - Shell command to analyze
+ * @returns {boolean} True if command is a piped pnpm dependency command
+ */
+export function isPipedPnpmCommand(command) {
+    if (!command || typeof command !== 'string') {
+        return false;
+    }
+    // Pattern 1: Something piped TO pnpm (before pnpm in command)
+    // e.g., "echo y | pnpm add", "yes | pnpm install"
+    const pipeToPattern = /\|\s*pnpm\s+(add|install|i|remove|rm|uninstall|update|up)\b/i;
+    if (pipeToPattern.test(command)) {
+        return true;
+    }
+    // Pattern 2: Input redirection (< or <<<)
+    // e.g., "pnpm add foo < /dev/null", "pnpm install <<< y"
+    const redirectPattern = /pnpm\s+(add|install|i|remove|rm|uninstall|update|up)\b[^|]*<(?!<)/i;
+    const heredocPattern = /pnpm\s+(add|install|i|remove|rm|uninstall|update|up)\b[^|]*<<</i;
+    if (redirectPattern.test(command) || heredocPattern.test(command)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if a command contains UnsafeAny dependency-mutating pnpm subcommand
+ *
+ * @param {string} command - Shell command to analyze
+ * @returns {boolean} True if command contains pnpm dependency mutation
+ */
+export function containsPnpmDependencyCommand(command) {
+    if (!command || typeof command !== 'string') {
+        return false;
+    }
+    // eslint-disable-next-line security/detect-non-literal-regexp -- command names from internal constant array, not user input
+    const pattern = new RegExp(`pnpm\\s+(${DEPENDENCY_COMMANDS.join('|')})\\b`, 'i');
+    return pattern.test(command);
+}
+//# sourceMappingURL=piped-command-detector.js.map

package/dist/piped-command-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"piped-command-detector.js","sourceRoot":"","sources":["../src/piped-command-detector.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;;GASG;AAEH;;;GAGG;AACH,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;AAEjG;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAkB;IACnD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,8DAA8D;IAC9D,kDAAkD;IAClD,MAAM,aAAa,GAAG,8DAA8D,CAAC;IACrF,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0CAA0C;IAC1C,yDAAyD;IACzD,MAAM,eAAe,GAAG,oEAAoE,CAAC;IAC7F,MAAM,cAAc,GAAG,iEAAiE,CAAC;IACzF,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAClE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,OAAkB;IAC9D,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,4HAA4H;IAC5H,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,YAAY,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjF,OAAO,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC/B,CAAC"}

package/dist/ports/config.ports.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Configuration Ports (WU-2020)
+ *
+ * Focused interfaces for injecting configuration sections into command
+ * handlers and service functions. These replace module-level getConfig()
+ * calls with explicit parameter injection (DIP compliance).
+ *
+ * Each interface extracts the minimum config surface needed by its
+ * consumers, following the Interface Segregation Principle (ISP).
+ *
+ * @module ports/config
+ */
+/**
+ * Git-related configuration for branch checks and worktree operations.
+ *
+ * Consumers: branch-check.ts, micro-worktree-shared.ts, micro-worktree.ts
+ */
+export interface IGitConfig {
+    readonly mainBranch: string;
+    readonly defaultRemote: string;
+    readonly requireRemote: boolean;
+    readonly laneBranchPrefix?: string;
+    readonly agentBranchPatterns?: string[];
+    readonly agentBranchPatternsOverride?: string[];
+    readonly disableAgentPatternRegistry?: boolean;
+    readonly pushRetry?: {
+        readonly enabled: boolean;
+        readonly retries: number;
+        readonly min_delay_ms: number;
+        readonly max_delay_ms: number;
+        readonly jitter: boolean;
+    };
+}
+/**
+ * Directory paths configuration for WU file resolution.
+ *
+ * Consumers: wu-paths.ts, wu-list.ts, spawn-task-builder.ts
+ */
+export interface IDirectoriesConfig {
+    readonly wuDir: string;
+    readonly initiativesDir: string;
+    readonly backlogPath: string;
+    readonly statusPath: string;
+    readonly worktrees: string;
+    readonly stampsDir?: string;
+    readonly plansDir: string;
+    readonly templatesDir: string;
+    readonly onboardingDir: string;
+    readonly skillsDir: string;
+    readonly agentsDir: string;
+    readonly memoryBank: string;
+    readonly safeGitPath: string;
+}
+/**
+ * State paths configuration for store directory resolution.
+ *
+ * Consumers: wu-paths.ts, wu-backlog-updater.ts
+ */
+export interface IStateConfig {
+    readonly base: string;
+    readonly stampsDir: string;
+    readonly stateDir: string;
+}
+/**
+ * Minimal config interface for path-resolution consumers.
+ *
+ * Consumers that only need directory and state paths should depend
+ * on this interface rather than the full LumenFlowConfig.
+ */
+export interface IPathsConfig {
+    readonly directories: IDirectoriesConfig;
+    readonly state: IStateConfig;
+}
+/**
+ * Minimal config interface for git-operation consumers.
+ *
+ * Consumers that only need git configuration should depend on this
+ * interface rather than the full LumenFlowConfig.
+ */
+export interface IGitOperationConfig {
+    readonly git: IGitConfig;
+}
+//# sourceMappingURL=config.ports.d.ts.map

package/dist/ports/config.ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.ports.d.ts","sourceRoot":"","sources":["../../src/ports/config.ports.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,2BAA2B,CAAC,EAAE,OAAO,CAAC;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;KAC1B,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;CAC1B"}

package/dist/ports/config.ports.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};
+//# sourceMappingURL=config.ports.js.map

package/dist/ports/config.ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.ports.js","sourceRoot":"","sources":["../../src/ports/config.ports.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.ports.d.ts","sourceRoot":"","sources":["../../src/ports/context.ports.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;CAC5E;AAGD,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC"}

package/dist/ports/context.ports.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};
+//# sourceMappingURL=context.ports.js.map

package/dist/ports/context.ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.ports.js","sourceRoot":"","sources":["../../src/ports/context.ports.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC"}