specweave 0.32.10 → 0.33.2

package/dist/src/utils/lock-manager.js

@@ -0,0 +1,195 @@
+/**
+ * Lock Manager - File-based locking with staleness detection
+ *
+ * Provides atomic file locking using directory creation (mkdir)
+ * with automatic stale lock detection and removal.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { consoleLogger } from './logger.js';
+const DEFAULT_STALE_THRESHOLD_SECONDS = 300; // 5 minutes
+const LOCK_RETRY_DELAY_MS = 100;
+const LOCK_TIMEOUT_MS = 10000; // 10 seconds
+export class LockManager {
+    constructor(lockDir, staleThresholdSeconds = DEFAULT_STALE_THRESHOLD_SECONDS, options = {}) {
+        this.lockDir = lockDir;
+        this.staleThresholdSeconds = staleThresholdSeconds;
+        this.logger = options.logger ?? consoleLogger;
+    }
+    /**
+     * Acquires the lock with automatic stale lock detection
+     *
+     * @returns true if lock acquired, false if failed
+     */
+    async acquire() {
+        const startTime = Date.now();
+        while (Date.now() - startTime < LOCK_TIMEOUT_MS) {
+            // Check if lock exists
+            if (fs.existsSync(this.lockDir)) {
+                // Check if lock is stale
+                if (await this.isStale()) {
+                    this.logger.warn('Stale lock detected, removing...');
+                    await this.removeStale();
+                    continue; // Try to acquire again
+                }
+                // Lock is active, wait and retry
+                await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
+                continue;
+            }
+            // Try to acquire lock
+            try {
+                fs.mkdirSync(this.lockDir, { recursive: false });
+                // Write metadata
+                const pidFile = path.join(this.lockDir, 'pid');
+                const sessionFile = path.join(this.lockDir, 'session_id');
+                fs.writeFileSync(pidFile, String(process.pid));
+                fs.writeFileSync(sessionFile, process.env.SESSION_ID || 'unknown');
+                return true;
+            }
+            catch (err) {
+                if (err.code === 'EEXIST') {
+                    // Another process acquired the lock, retry
+                    continue;
+                }
+                this.logger.error('Failed to acquire lock:', err);
+                return false;
+            }
+        }
+        this.logger.error(`Lock acquisition timeout after ${LOCK_TIMEOUT_MS}ms`);
+        return false;
+    }
+    /**
+     * Releases the lock
+     */
+    async release() {
+        try {
+            if (!fs.existsSync(this.lockDir)) {
+                return;
+            }
+            // Remove metadata files
+            const pidFile = path.join(this.lockDir, 'pid');
+            const sessionFile = path.join(this.lockDir, 'session_id');
+            if (fs.existsSync(pidFile)) {
+                fs.unlinkSync(pidFile);
+            }
+            if (fs.existsSync(sessionFile)) {
+                fs.unlinkSync(sessionFile);
+            }
+            // Remove lock directory
+            fs.rmdirSync(this.lockDir);
+        }
+        catch (err) {
+            this.logger.error('Failed to release lock:', err);
+        }
+    }
+    /**
+     * Checks if the lock is stale
+     *
+     * A lock is stale if:
+     * 1. It's older than the threshold
+     * 2. The PID in the lock file no longer exists
+     *
+     * @returns true if lock is stale
+     */
+    async isStale() {
+        if (!fs.existsSync(this.lockDir)) {
+            return false;
+        }
+        try {
+            // Check lock age
+            const lockAge = await this.getLockAge();
+            if (lockAge < this.staleThresholdSeconds) {
+                return false; // Lock is fresh
+            }
+            // Check if PID exists
+            const pidFile = path.join(this.lockDir, 'pid');
+            if (!fs.existsSync(pidFile)) {
+                return true; // No PID file, assume stale
+            }
+            const pidStr = fs.readFileSync(pidFile, 'utf-8').trim();
+            const pid = parseInt(pidStr, 10);
+            if (isNaN(pid)) {
+                return true; // Invalid PID, assume stale
+            }
+            // Check if process exists
+            const pidExists = await this.checkPidExists(pid);
+            return !pidExists; // Stale if PID doesn't exist
+        }
+        catch (err) {
+            this.logger.error('Error checking lock staleness:', err);
+            return false; // Assume not stale on error
+        }
+    }
+    /**
+     * Removes a stale lock after validation
+     */
+    async removeStale() {
+        if (!(await this.isStale())) {
+            this.logger.warn('Attempted to remove non-stale lock, aborting');
+            return;
+        }
+        try {
+            const pidFile = path.join(this.lockDir, 'pid');
+            let pid = 'unknown';
+            if (fs.existsSync(pidFile)) {
+                pid = fs.readFileSync(pidFile, 'utf-8').trim();
+            }
+            this.logger.info(`Removing stale lock (PID: ${pid}, age: ${await this.getLockAge()}s)`);
+            // Remove lock
+            await this.release();
+            // Log removal
+            const logFile = path.join(path.dirname(this.lockDir), '..', 'logs', 'lock-cleanup.log');
+            const logDir = path.dirname(logFile);
+            if (!fs.existsSync(logDir)) {
+                fs.mkdirSync(logDir, { recursive: true });
+            }
+            const logEntry = `[${new Date().toISOString()}] Removed stale lock: ${this.lockDir} (PID: ${pid})\n`;
+            fs.appendFileSync(logFile, logEntry);
+        }
+        catch (err) {
+            this.logger.error('Failed to remove stale lock:', err);
+        }
+    }
+    /**
+     * Gets the age of the lock in seconds
+     */
+    async getLockAge() {
+        if (!fs.existsSync(this.lockDir)) {
+            return Infinity;
+        }
+        try {
+            const stats = fs.statSync(this.lockDir);
+            const mtimeMs = stats.mtimeMs;
+            const now = Date.now();
+            const ageMs = now - mtimeMs;
+            return ageMs / 1000;
+        }
+        catch (err) {
+            return Infinity;
+        }
+    }
+    /**
+     * Checks if a PID exists (cross-platform)
+     */
+    async checkPidExists(pid) {
+        try {
+            if (process.platform === 'win32') {
+                const { execSync } = await import('child_process');
+                const output = execSync(`tasklist /FI "PID eq ${pid}" /NH`, {
+                    encoding: 'utf-8',
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                });
+                return output.includes(String(pid));
+            }
+            else {
+                const { execSync } = await import('child_process');
+                execSync(`kill -0 ${pid}`, { stdio: 'ignore' });
+                return true;
+            }
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=lock-manager.js.map

package/dist/src/utils/lock-manager.js.map

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

package/dist/src/utils/notification-manager.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Notification Manager - Cross-platform system notifications
+ *
+ * Sends native notifications on macOS, Linux, and Windows
+ */
+import { Logger } from './logger.js';
+export declare class NotificationManager {
+    private logger;
+    constructor(options?: {
+        logger?: Logger;
+    });
+    /**
+     * Sends a system notification (cross-platform)
+     *
+     * @param title - Notification title
+     * @param body - Notification message
+     * @param sound - Optional sound name (macOS only)
+     */
+    sendNotification(title: string, body: string, sound?: string): Promise<void>;
+    /**
+     * Sends notification on macOS using osascript
+     */
+    private sendMacOSNotification;
+    /**
+     * Sends notification on Linux using notify-send
+     */
+    private sendLinuxNotification;
+    /**
+     * Sends notification on Windows using PowerShell toast
+     */
+    private sendWindowsNotification;
+    /**
+     * Escapes string for AppleScript
+     */
+    private escapeForAppleScript;
+    /**
+     * Escapes string for shell
+     */
+    private escapeForShell;
+    /**
+     * Escapes string for PowerShell
+     */
+    private escapeForPowerShell;
+}
+//# sourceMappingURL=notification-manager.d.ts.map

package/dist/src/utils/notification-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-manager.d.ts","sourceRoot":"","sources":["../../../src/utils/notification-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,MAAM,EAAiB,MAAM,aAAa,CAAC;AAEpD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAI7C;;;;;;OAMG;IACG,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBlF;;OAEG;YACW,qBAAqB;IAmBnC;;OAEG;YACW,qBAAqB;IAqBnC;;OAEG;YACW,uBAAuB;IA2BrC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,mBAAmB;CAG5B"}

package/dist/src/utils/notification-manager.js

@@ -0,0 +1,130 @@
+/**
+ * Notification Manager - Cross-platform system notifications
+ *
+ * Sends native notifications on macOS, Linux, and Windows
+ */
+import { exec } from 'child_process';
+import { consoleLogger } from './logger.js';
+export class NotificationManager {
+    constructor(options = {}) {
+        this.logger = options.logger ?? consoleLogger;
+    }
+    /**
+     * Sends a system notification (cross-platform)
+     *
+     * @param title - Notification title
+     * @param body - Notification message
+     * @param sound - Optional sound name (macOS only)
+     */
+    async sendNotification(title, body, sound) {
+        const platform = process.platform;
+        try {
+            if (platform === 'darwin') {
+                await this.sendMacOSNotification(title, body, sound);
+            }
+            else if (platform === 'linux') {
+                await this.sendLinuxNotification(title, body);
+            }
+            else if (platform === 'win32') {
+                await this.sendWindowsNotification(title, body);
+            }
+            else {
+                this.logger.warn(`Notifications not supported on platform: ${platform}`);
+                this.logger.info(`[Notification] ${title}: ${body}`);
+            }
+        }
+        catch (err) {
+            this.logger.error('Failed to send notification:', err);
+            // Fallback to console
+            this.logger.info(`[Notification] ${title}: ${body}`);
+        }
+    }
+    /**
+     * Sends notification on macOS using osascript
+     */
+    async sendMacOSNotification(title, body, sound) {
+        return new Promise((resolve, reject) => {
+            const soundParam = sound ? ` sound name "${sound}"` : '';
+            const script = `display notification "${this.escapeForAppleScript(body)}" with title "${this.escapeForAppleScript(title)}"${soundParam}`;
+            exec(`osascript -e '${script}'`, (error) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Sends notification on Linux using notify-send
+     */
+    async sendLinuxNotification(title, body) {
+        return new Promise((resolve, reject) => {
+            // Check if notify-send is available
+            exec('command -v notify-send', (error) => {
+                if (error) {
+                    this.logger.warn('notify-send not found, skipping notification');
+                    resolve();
+                    return;
+                }
+                exec(`notify-send "${this.escapeForShell(title)}" "${this.escapeForShell(body)}"`, (error) => {
+                    if (error) {
+                        reject(error);
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+        });
+    }
+    /**
+     * Sends notification on Windows using PowerShell toast
+     */
+    async sendWindowsNotification(title, body) {
+        return new Promise((resolve, reject) => {
+            const script = `
+        [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+        [Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
+
+        $template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+        $toastXml = [xml] $template.GetXml()
+        $toastXml.GetElementsByTagName("text")[0].AppendChild($toastXml.CreateTextNode("${this.escapeForPowerShell(title)}")) | Out-Null
+        $toastXml.GetElementsByTagName("text")[1].AppendChild($toastXml.CreateTextNode("${this.escapeForPowerShell(body)}")) | Out-Null
+
+        $xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+        $xml.LoadXml($toastXml.OuterXml)
+        $toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
+        [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("SpecWeave").Show($toast)
+      `;
+            exec(`powershell -Command "${script}"`, (error) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Escapes string for AppleScript
+     */
+    escapeForAppleScript(str) {
+        return str.replace(/"/g, '\\"').replace(/\\/g, '\\\\');
+    }
+    /**
+     * Escapes string for shell
+     */
+    escapeForShell(str) {
+        return str.replace(/"/g, '\\"').replace(/\$/g, '\\$');
+    }
+    /**
+     * Escapes string for PowerShell
+     */
+    escapeForPowerShell(str) {
+        return str.replace(/"/g, '`"').replace(/\$/g, '`$');
+    }
+}
+//# sourceMappingURL=notification-manager.js.map

package/dist/src/utils/notification-manager.js.map

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

package/dist/src/utils/platform-utils.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Platform Utilities - Cross-platform OS operations
+ *
+ * Abstracts platform-specific operations for macOS, Linux, and Windows
+ * Enhanced for process lifecycle management with async API, logger injection,
+ * and system notifications
+ */
+import { Logger } from './logger.js';
+export type Platform = 'darwin' | 'linux' | 'win32';
+/**
+ * Gets the current platform
+ */
+export declare function getCurrentPlatform(): Platform;
+/**
+ * Checks if a process exists (cross-platform)
+ *
+ * @param pid - Process ID to check
+ * @returns true if process exists
+ */
+export declare function checkProcessExists(pid: number): boolean;
+/**
+ * Gets file modification time in seconds since epoch (cross-platform)
+ *
+ * @param filePath - Path to file
+ * @returns Modification time in seconds since epoch
+ */
+export declare function getFileMtime(filePath: string): number;
+/**
+ * Kills a process (cross-platform)
+ *
+ * @param pid - Process ID to kill
+ * @param signal - Signal to send (default: SIGTERM)
+ */
+export declare function killProcess(pid: number, signal?: string): void;
+/**
+ * Acquires a file lock using atomic directory creation (cross-platform)
+ *
+ * @param lockPath - Path to lock directory
+ * @returns true if lock acquired
+ */
+export declare function acquireFileLock(lockPath: string): boolean;
+export interface PlatformUtilsOptions {
+    logger?: Logger;
+}
+/**
+ * Enhanced cross-platform utility functions with async API and logger injection
+ */
+export declare class PlatformUtils {
+    private platform;
+    private logger;
+    constructor(options?: PlatformUtilsOptions);
+    /**
+     * Get current platform
+     */
+    getPlatform(): Platform;
+    /**
+     * Check if current platform is Windows
+     */
+    isWindows(): boolean;
+    /**
+     * Check if current platform is POSIX (macOS or Linux)
+     */
+    isPosix(): boolean;
+    /**
+     * Check if a process exists by PID (async)
+     *
+     * - macOS/Linux: kill -0 $pid (signal 0 = existence check)
+     * - Windows: tasklist /FI "PID eq $pid"
+     *
+     * @param pid Process ID to check
+     * @returns true if process exists, false otherwise
+     */
+    checkProcessExistsAsync(pid: number): Promise<boolean>;
+    /**
+     * Get file modification time (async, uses fs.stat for cross-platform)
+     *
+     * @param path File path
+     * @returns Modification time in seconds since epoch
+     */
+    getFileMtimeAsync(path: string): Promise<number>;
+    /**
+     * Acquire file lock using atomic mkdir (async)
+     *
+     * @param lockPath Path to lock directory
+     * @param timeoutMs Maximum time to wait for lock (default: 5000ms)
+     * @returns true if lock acquired, false if timeout
+     */
+    acquireFileLockAsync(lockPath: string, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Release file lock (async)
+     *
+     * @param lockPath Path to lock directory
+     */
+    releaseFileLockAsync(lockPath: string): Promise<void>;
+    /**
+     * Kill process with signal (async)
+     *
+     * @param pid Process ID to kill
+     * @param signal Signal to send (default: SIGTERM)
+     */
+    killProcessAsync(pid: number, signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * Kill process with graceful fallback (SIGTERM → SIGKILL)
+     *
+     * @param pid Process ID to kill
+     * @param gracePeriodMs Time to wait after SIGTERM before SIGKILL (default: 2000ms)
+     */
+    killProcessGracefully(pid: number, gracePeriodMs?: number): Promise<void>;
+    /**
+     * Send system notification
+     *
+     * - macOS: osascript (AppleScript)
+     * - Linux: notify-send (if available)
+     * - Windows: PowerShell toast notification
+     *
+     * Fails gracefully if notification system is unavailable
+     *
+     * @param title Notification title
+     * @param body Notification body text
+     */
+    sendNotification(title: string, body: string): Promise<void>;
+    /**
+     * macOS notification using osascript
+     */
+    private sendNotificationMacOS;
+    /**
+     * Linux notification using notify-send
+     */
+    private sendNotificationLinux;
+    /**
+     * Windows notification using PowerShell toast
+     */
+    private sendNotificationWindows;
+}
+export declare const platformUtils: PlatformUtils;
+//# sourceMappingURL=platform-utils.d.ts.map

package/dist/src/utils/platform-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-utils.d.ts","sourceRoot":"","sources":["../../../src/utils/platform-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,MAAM,EAAiB,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAEpD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,QAAQ,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAevD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAmBrD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAkB,GAAG,IAAI,CAUzE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWzD;AAID,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,GAAE,oBAAyB;IAK9C;;OAEG;IACH,WAAW,IAAI,QAAQ;IAIvB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;;;;;OAQG;IACG,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4B5D;;;;;OAKG;IACG,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUtD;;;;;;OAMG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBxF;;;;OAIG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3D;;;;;OAKG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,OAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBtF;;;;;OAKG;IACG,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,GAAE,MAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCrF;;;;;;;;;;;OAWG;IACG,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAelE;;OAEG;YACW,qBAAqB;IAOnC;;OAEG;YACW,qBAAqB;IAWnC;;OAEG;YACW,uBAAuB;CAiBtC;AAGD,eAAO,MAAM,aAAa,eAAsB,CAAC"}