claudecode-omc 4.9.4 → 5.0.0

package/dist/features/state-manager/index.js

@@ -1,669 +0,0 @@
-/**
- * State Manager
- *
- * Unified state management that standardizes state file locations:
- * - Local state: .omc/state/{name}.json
- * - Global state: XDG-aware user OMC state with legacy ~/.omc/state fallback
- *
- * Features:
- * - Type-safe read/write operations
- * - Auto-create directories
- * - Legacy location support (for migration)
- * - State cleanup utilities
- */
-import * as fs from "fs";
-import * as path from "path";
-import { atomicWriteJsonSync } from "../../lib/atomic-write.js";
-import { OmcPaths, getWorktreeRoot, validateWorkingDirectory, } from "../../lib/worktree-paths.js";
-import { getGlobalOmcStateRoot, getLegacyOmcPath } from "../../utils/paths.js";
-import { StateLocation, DEFAULT_STATE_CONFIG, } from "./types.js";
-// Standard state directories
-/** Get the absolute path to the local state directory, resolved from the git worktree root. */
-function getLocalStateDir() {
-    return path.join(validateWorkingDirectory(), OmcPaths.STATE);
-}
-/**
- * @deprecated for mode state. Global state directory is only used for analytics and daemon state.
- * Mode state should use LOCAL_STATE_DIR exclusively.
- */
-const GLOBAL_STATE_DIR = getGlobalOmcStateRoot();
-/** Maximum age for state files before they are considered stale (4 hours) */
-const MAX_STATE_AGE_MS = 4 * 60 * 60 * 1000;
-// Read cache: avoids re-reading unchanged state files within TTL
-const STATE_CACHE_TTL_MS = 5_000; // 5 seconds
-const MAX_CACHE_SIZE = 200;
-const stateCache = new Map();
-/**
- * Clear the state read cache.
- * Exported for testing and for write/clear operations to invalidate stale entries.
- */
-export function clearStateCache() {
-    stateCache.clear();
-}
-// Legacy state locations (for backward compatibility)
-const LEGACY_LOCATIONS = {
-    boulder: [".omc/state/boulder.json"],
-    autopilot: [".omc/state/autopilot-state.json"],
-    "autopilot-state": [".omc/state/autopilot-state.json"],
-    ralph: [".omc/state/ralph-state.json"],
-    "ralph-state": [".omc/state/ralph-state.json"],
-    "ralph-verification": [".omc/state/ralph-verification.json"],
-    ultrawork: [".omc/state/ultrawork-state.json"],
-    "ultrawork-state": [".omc/state/ultrawork-state.json"],
-    ultraqa: [".omc/state/ultraqa-state.json"],
-    "ultraqa-state": [".omc/state/ultraqa-state.json"],
-    "hud-state": [".omc/state/hud-state.json"],
-    prd: [".omc/state/prd.json"],
-};
-/**
- * Get the standard path for a state file
- */
-export function getStatePath(name, location) {
-    const baseDir = location === StateLocation.LOCAL ? getLocalStateDir() : GLOBAL_STATE_DIR;
-    return path.join(baseDir, `${name}.json`);
-}
-/**
- * Get legacy paths for a state file (for migration)
- */
-export function getLegacyPaths(name, location = StateLocation.LOCAL) {
-    const legacyPaths = [...(LEGACY_LOCATIONS[name] || [])];
-    if (location === StateLocation.GLOBAL) {
-        legacyPaths.push(getLegacyOmcPath("state", `${name}.json`));
-    }
-    return legacyPaths;
-}
-/**
- * Ensure state directory exists
- */
-export function ensureStateDir(location) {
-    const dir = location === StateLocation.LOCAL ? getLocalStateDir() : GLOBAL_STATE_DIR;
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-}
-/**
- * Read state from file
- *
- * Checks standard location first, then legacy locations if enabled.
- * Returns both the data and where it was found.
- */
-export function readState(name, location = StateLocation.LOCAL, options) {
-    const checkLegacy = options?.checkLegacy ?? DEFAULT_STATE_CONFIG.checkLegacy;
-    const standardPath = getStatePath(name, location);
-    const legacyPaths = checkLegacy ? getLegacyPaths(name, location) : [];
-    // Try standard location first
-    if (fs.existsSync(standardPath)) {
-        try {
-            // Get mtime BEFORE reading to prevent TOCTOU cache poisoning.
-            // Previously mtime was read AFTER readFileSync, so a concurrent write
-            // between the two could cache stale data under the new mtime.
-            const statBefore = fs.statSync(standardPath);
-            const mtimeBefore = statBefore.mtimeMs;
-            // Check cache: entry exists, mtime matches, TTL not expired
-            const cached = stateCache.get(standardPath);
-            if (cached &&
-                cached.mtime === mtimeBefore &&
-                Date.now() - cached.cachedAt < STATE_CACHE_TTL_MS) {
-                return {
-                    exists: true,
-                    data: structuredClone(cached.data),
-                    foundAt: standardPath,
-                    legacyLocations: [],
-                };
-            }
-            // Cache miss or stale — read from disk
-            const content = fs.readFileSync(standardPath, "utf-8");
-            const data = JSON.parse(content);
-            // Verify mtime unchanged during read to prevent caching inconsistent data.
-            // If the file was modified between our statBefore and readFileSync, we still
-            // return the data but do NOT cache it — the next read will re-read from disk.
-            try {
-                const statAfter = fs.statSync(standardPath);
-                if (statAfter.mtimeMs === mtimeBefore) {
-                    if (stateCache.size >= MAX_CACHE_SIZE) {
-                        const firstKey = stateCache.keys().next().value;
-                        if (firstKey !== undefined)
-                            stateCache.delete(firstKey);
-                    }
-                    stateCache.set(standardPath, {
-                        data: structuredClone(data),
-                        mtime: mtimeBefore,
-                        cachedAt: Date.now(),
-                    });
-                }
-            }
-            catch {
-                // statSync failed — skip caching, data is still returned
-            }
-            return {
-                exists: true,
-                data: structuredClone(data),
-                foundAt: standardPath,
-                legacyLocations: [],
-            };
-        }
-        catch (error) {
-            // Invalid JSON or read error - treat as not found
-            console.warn(`Failed to read state from ${standardPath}:`, error);
-        }
-    }
-    // Try legacy locations
-    if (checkLegacy) {
-        for (const legacyPath of legacyPaths) {
-            // Resolve relative paths
-            const resolvedPath = path.isAbsolute(legacyPath)
-                ? legacyPath
-                : path.join(getWorktreeRoot() || process.cwd(), legacyPath);
-            if (fs.existsSync(resolvedPath)) {
-                try {
-                    const content = fs.readFileSync(resolvedPath, "utf-8");
-                    const data = JSON.parse(content);
-                    return {
-                        exists: true,
-                        data: structuredClone(data),
-                        foundAt: resolvedPath,
-                        legacyLocations: legacyPaths,
-                    };
-                }
-                catch (error) {
-                    console.warn(`Failed to read legacy state from ${resolvedPath}:`, error);
-                }
-            }
-        }
-    }
-    return {
-        exists: false,
-        legacyLocations: checkLegacy ? legacyPaths : [],
-    };
-}
-/**
- * Write state to file
- *
- * Always writes to the standard location.
- * Creates directories if they don't exist.
- */
-export function writeState(name, data, location = StateLocation.LOCAL, options) {
-    const createDirs = options?.createDirs ?? DEFAULT_STATE_CONFIG.createDirs;
-    const statePath = getStatePath(name, location);
-    // Invalidate cache on write
-    stateCache.delete(statePath);
-    try {
-        // Ensure directory exists
-        if (createDirs) {
-            ensureStateDir(location);
-        }
-        atomicWriteJsonSync(statePath, data);
-        return {
-            success: true,
-            path: statePath,
-        };
-    }
-    catch (error) {
-        return {
-            success: false,
-            path: statePath,
-            error: error instanceof Error ? error.message : String(error),
-        };
-    }
-}
-/**
- * Clear state from all locations (standard + legacy)
- *
- * Removes the state file from both standard and legacy locations.
- * Returns information about what was removed.
- */
-export function clearState(name, location) {
-    // Invalidate cache for all possible locations
-    const locationsForCache = location
-        ? [location]
-        : [StateLocation.LOCAL, StateLocation.GLOBAL];
-    for (const loc of locationsForCache) {
-        stateCache.delete(getStatePath(name, loc));
-    }
-    const result = {
-        removed: [],
-        notFound: [],
-        errors: [],
-    };
-    // Determine which locations to check
-    const locationsToCheck = location
-        ? [location]
-        : [StateLocation.LOCAL, StateLocation.GLOBAL];
-    // Remove from standard locations
-    for (const loc of locationsToCheck) {
-        const standardPath = getStatePath(name, loc);
-        try {
-            if (fs.existsSync(standardPath)) {
-                fs.unlinkSync(standardPath);
-                result.removed.push(standardPath);
-            }
-            else {
-                result.notFound.push(standardPath);
-            }
-        }
-        catch (error) {
-            result.errors.push({
-                path: standardPath,
-                error: error instanceof Error ? error.message : String(error),
-            });
-        }
-    }
-    // Remove from legacy locations
-    const legacyPaths = getLegacyPaths(name, location ?? StateLocation.LOCAL);
-    for (const legacyPath of legacyPaths) {
-        const resolvedPath = path.isAbsolute(legacyPath)
-            ? legacyPath
-            : path.join(getWorktreeRoot() || process.cwd(), legacyPath);
-        try {
-            if (fs.existsSync(resolvedPath)) {
-                fs.unlinkSync(resolvedPath);
-                result.removed.push(resolvedPath);
-            }
-            else {
-                result.notFound.push(resolvedPath);
-            }
-        }
-        catch (error) {
-            result.errors.push({
-                path: resolvedPath,
-                error: error instanceof Error ? error.message : String(error),
-            });
-        }
-    }
-    return result;
-}
-/**
- * Migrate state from legacy location to standard location
- *
- * Finds state in legacy locations and moves it to the standard location.
- * Deletes the legacy file after successful migration.
- */
-export function migrateState(name, location = StateLocation.LOCAL) {
-    // Check if already in standard location
-    const standardPath = getStatePath(name, location);
-    if (fs.existsSync(standardPath)) {
-        return {
-            migrated: false,
-        };
-    }
-    // Look for legacy state
-    const readResult = readState(name, location, { checkLegacy: true });
-    if (!readResult.exists || !readResult.foundAt || !readResult.data) {
-        return {
-            migrated: false,
-            error: "No legacy state found",
-        };
-    }
-    // Check if it's actually from a legacy location
-    const isLegacy = readResult.foundAt !== standardPath;
-    if (!isLegacy) {
-        return {
-            migrated: false,
-        };
-    }
-    // Write to standard location
-    const writeResult = writeState(name, readResult.data, location);
-    if (!writeResult.success) {
-        return {
-            migrated: false,
-            error: `Failed to write to standard location: ${writeResult.error}`,
-        };
-    }
-    // Delete legacy file
-    try {
-        fs.unlinkSync(readResult.foundAt);
-    }
-    catch (error) {
-        // Migration succeeded but cleanup failed - not critical
-        console.warn(`Failed to delete legacy state at ${readResult.foundAt}:`, error);
-    }
-    return {
-        migrated: true,
-        from: readResult.foundAt,
-        to: writeResult.path,
-    };
-}
-/**
- * List all state files
- *
- * Returns information about all state files in the specified location(s).
- */
-export function listStates(options) {
-    const results = [];
-    const includeLegacy = options?.includeLegacy ?? false;
-    const pattern = options?.pattern;
-    // Helper to check if name matches pattern
-    const matchesPattern = (name) => {
-        if (!pattern)
-            return true;
-        // Simple glob: * matches anything
-        const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
-        return regex.test(name);
-    };
-    // Helper to add state files from a directory
-    const addStatesFromDir = (dir, location, isLegacy = false) => {
-        if (!fs.existsSync(dir))
-            return;
-        try {
-            const files = fs.readdirSync(dir);
-            for (const file of files) {
-                if (!file.endsWith(".json"))
-                    continue;
-                const name = file.slice(0, -5); // Remove .json
-                if (!matchesPattern(name))
-                    continue;
-                const filePath = path.join(dir, file);
-                const stats = fs.statSync(filePath);
-                results.push({
-                    name,
-                    path: filePath,
-                    location,
-                    size: stats.size,
-                    modified: stats.mtime,
-                    isLegacy,
-                });
-            }
-        }
-        catch (error) {
-            console.warn(`Failed to list states from ${dir}:`, error);
-        }
-    };
-    // Check standard locations
-    if (!options?.location || options.location === StateLocation.LOCAL) {
-        addStatesFromDir(getLocalStateDir(), StateLocation.LOCAL);
-    }
-    if (!options?.location || options.location === StateLocation.GLOBAL) {
-        addStatesFromDir(GLOBAL_STATE_DIR, StateLocation.GLOBAL);
-    }
-    // Check legacy locations if requested
-    if (includeLegacy) {
-        // Add logic to scan legacy locations
-        // This would require knowing all possible legacy locations
-        // For now, we skip this as legacy locations are name-specific
-    }
-    return results;
-}
-/**
- * Cleanup orphaned state files
- *
- * Removes state files that haven't been modified in a long time.
- * Useful for cleaning up abandoned states.
- */
-export function cleanupOrphanedStates(options) {
-    const maxAgeDays = options?.maxAgeDays ?? 30;
-    const dryRun = options?.dryRun ?? false;
-    const exclude = options?.exclude ?? [];
-    const result = {
-        deleted: [],
-        wouldDelete: dryRun ? [] : undefined,
-        spaceFreed: 0,
-        errors: [],
-    };
-    const cutoffDate = new Date();
-    cutoffDate.setDate(cutoffDate.getDate() - maxAgeDays);
-    const states = listStates({ includeLegacy: false });
-    for (const state of states) {
-        // Skip excluded patterns
-        if (exclude.some((pattern) => {
-            const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
-            return regex.test(state.name);
-        })) {
-            continue;
-        }
-        // Check if old enough
-        if (state.modified > cutoffDate) {
-            continue;
-        }
-        // Delete or record for dry run
-        if (dryRun) {
-            result.wouldDelete?.push(state.path);
-            result.spaceFreed += state.size;
-        }
-        else {
-            try {
-                fs.unlinkSync(state.path);
-                result.deleted.push(state.path);
-                result.spaceFreed += state.size;
-            }
-            catch (error) {
-                result.errors.push({
-                    path: state.path,
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
-        }
-    }
-    return result;
-}
-/**
- * Determine whether a state's metadata indicates staleness.
- *
- * A state is stale when **both** `updatedAt` and `heartbeatAt` (if present)
- * are older than `maxAgeMs`.  If either timestamp is recent the state is
- * considered alive — this allows long-running workflows that send heartbeats
- * to survive the stale-check.
- */
-export function isStateStale(meta, now, maxAgeMs) {
-    const updatedAt = meta.updatedAt
-        ? new Date(meta.updatedAt).getTime()
-        : undefined;
-    const heartbeatAt = meta.heartbeatAt
-        ? new Date(meta.heartbeatAt).getTime()
-        : undefined;
-    // If updatedAt is recent, not stale
-    if (updatedAt && !isNaN(updatedAt) && now - updatedAt <= maxAgeMs) {
-        return false;
-    }
-    // If heartbeatAt is recent, not stale
-    if (heartbeatAt && !isNaN(heartbeatAt) && now - heartbeatAt <= maxAgeMs) {
-        return false;
-    }
-    // At least one timestamp must exist and be parseable to declare staleness
-    const hasValidTimestamp = (updatedAt !== undefined && !isNaN(updatedAt)) ||
-        (heartbeatAt !== undefined && !isNaN(heartbeatAt));
-    return hasValidTimestamp;
-}
-/**
- * Scan all state files in a directory and mark stale ones as inactive.
- *
- * A state is considered stale if both `_meta.updatedAt` and
- * `_meta.heartbeatAt` are older than `maxAgeMs` (defaults to
- * MAX_STATE_AGE_MS = 4 hours).  States with a recent heartbeat are
- * skipped so that long-running workflows are not killed prematurely.
- *
- * This is the **only** place that deactivates stale states — the read
- * path (`readState`) is a pure read with no side-effects.
- *
- * @returns Number of states that were marked inactive.
- */
-export function cleanupStaleStates(directory, maxAgeMs = MAX_STATE_AGE_MS) {
-    const stateDir = directory
-        ? path.join(directory, ".omc", "state")
-        : getLocalStateDir();
-    if (!fs.existsSync(stateDir))
-        return 0;
-    let cleaned = 0;
-    const now = Date.now();
-    // Helper: scan JSON files in a directory and mark stale active states inactive
-    const scanDir = (dir) => {
-        try {
-            const files = fs.readdirSync(dir);
-            for (const file of files) {
-                if (!file.endsWith(".json"))
-                    continue;
-                const filePath = path.join(dir, file);
-                try {
-                    const content = fs.readFileSync(filePath, "utf-8");
-                    const data = JSON.parse(content);
-                    if (data.active !== true)
-                        continue;
-                    const meta = data._meta ?? {};
-                    if (isStateStale(meta, now, maxAgeMs)) {
-                        console.warn(`[state-manager] cleanupStaleStates: marking "${file}" inactive (last updated ${meta.updatedAt ?? "unknown"})`);
-                        data.active = false;
-                        // Invalidate cache for this path
-                        stateCache.delete(filePath);
-                        try {
-                            atomicWriteJsonSync(filePath, data);
-                            cleaned++;
-                        }
-                        catch {
-                            /* best-effort */
-                        }
-                    }
-                }
-                catch {
-                    // Skip files that can't be read/parsed
-                }
-            }
-        }
-        catch {
-            // Directory read error
-        }
-    };
-    // Scan top-level state files (.omc/state/*.json)
-    scanDir(stateDir);
-    // Scan session directories (.omc/state/sessions/*/*.json)
-    const sessionsDir = path.join(stateDir, "sessions");
-    if (fs.existsSync(sessionsDir)) {
-        try {
-            const sessionEntries = fs.readdirSync(sessionsDir, {
-                withFileTypes: true,
-            });
-            for (const entry of sessionEntries) {
-                if (entry.isDirectory()) {
-                    scanDir(path.join(sessionsDir, entry.name));
-                }
-            }
-        }
-        catch {
-            // Sessions directory read error
-        }
-    }
-    return cleaned;
-}
-// File locking for atomic read-modify-write operations
-const LOCK_STALE_MS = 30_000; // locks older than 30s are considered stale
-const LOCK_TIMEOUT_MS = 5_000; // max time to wait for lock acquisition
-const LOCK_POLL_MS = 10; // busy-wait interval between lock attempts
-/**
- * Execute a function while holding an exclusive file lock.
- * Uses O_EXCL lockfile for cross-process mutual exclusion.
- * Stale locks (older than LOCK_STALE_MS) are automatically broken.
- *
- * @throws Error if the lock cannot be acquired within LOCK_TIMEOUT_MS
- */
-function withFileLock(filePath, fn) {
-    const lockPath = `${filePath}.lock`;
-    const lockDir = path.dirname(lockPath);
-    const deadline = Date.now() + LOCK_TIMEOUT_MS;
-    // Ensure directory exists for lock file
-    if (!fs.existsSync(lockDir)) {
-        fs.mkdirSync(lockDir, { recursive: true });
-    }
-    // Acquire lock via exclusive file creation
-    while (true) {
-        try {
-            const fd = fs.openSync(lockPath, "wx", 0o600);
-            fs.writeSync(fd, `${process.pid}\n${Date.now()}`);
-            fs.closeSync(fd);
-            break;
-        }
-        catch (err) {
-            if (err.code !== "EEXIST")
-                throw err;
-            // Lock exists — check for staleness
-            try {
-                const lockStat = fs.statSync(lockPath);
-                if (Date.now() - lockStat.mtimeMs > LOCK_STALE_MS) {
-                    try {
-                        fs.unlinkSync(lockPath);
-                    }
-                    catch {
-                        /* race OK */
-                    }
-                    continue;
-                }
-            }
-            catch {
-                // Lock disappeared — retry immediately
-                continue;
-            }
-            if (Date.now() >= deadline) {
-                throw new Error(`Timed out acquiring state lock: ${lockPath}`);
-            }
-            // Brief pause before retry (sync spin intentional — this is a sync lock function)
-            const waitEnd = Date.now() + LOCK_POLL_MS;
-            while (Date.now() < waitEnd) {
-                /* spin */
-            }
-        }
-    }
-    try {
-        return fn();
-    }
-    finally {
-        try {
-            fs.unlinkSync(lockPath);
-        }
-        catch {
-            /* best-effort */
-        }
-    }
-}
-/**
- * State Manager Class
- *
- * Object-oriented interface for managing a specific state.
- *
- * @deprecated For mode state (autopilot, ralph, ultrawork, etc.), use `writeModeState`/`readModeState` from `src/lib/mode-state-io.ts` instead. StateManager is retained for non-mode state only.
- */
-export class StateManager {
-    name;
-    location;
-    constructor(name, location = StateLocation.LOCAL) {
-        this.name = name;
-        this.location = location;
-    }
-    read(options) {
-        return readState(this.name, this.location, options);
-    }
-    write(data, options) {
-        return writeState(this.name, data, this.location, options);
-    }
-    clear() {
-        return clearState(this.name, this.location);
-    }
-    migrate() {
-        return migrateState(this.name, this.location);
-    }
-    exists() {
-        return this.read({ checkLegacy: false }).exists;
-    }
-    get() {
-        return this.read().data;
-    }
-    set(data) {
-        return this.write(data).success;
-    }
-    update(updater) {
-        const statePath = getStatePath(this.name, this.location);
-        return withFileLock(statePath, () => {
-            // Invalidate cache to force a fresh read under lock,
-            // preventing stale cached data from being used as the base for updates.
-            stateCache.delete(statePath);
-            const current = this.get();
-            const updated = updater(current);
-            return this.set(updated);
-        });
-    }
-}
-/**
- * Create a state manager for a specific state
- */
-export function createStateManager(name, location = StateLocation.LOCAL) {
-    return new StateManager(name, location);
-}
-// Re-export enum, constants, and functions from types
-export { StateLocation, DEFAULT_STATE_CONFIG, isStateLocation, } from "./types.js";
-//# sourceMappingURL=index.js.map