specweave 0.32.10 → 0.33.2

package/dist/src/utils/platform-utils.js

@@ -0,0 +1,366 @@
+/**
+ * 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 { execSync } from 'child_process';
+import { stat, mkdir, rmdir } from 'fs/promises';
+import { consoleLogger } from './logger.js';
+/**
+ * Gets the current platform
+ */
+export function getCurrentPlatform() {
+    return process.platform;
+}
+/**
+ * Checks if a process exists (cross-platform)
+ *
+ * @param pid - Process ID to check
+ * @returns true if process exists
+ */
+export function checkProcessExists(pid) {
+    try {
+        if (process.platform === 'win32') {
+            const output = execSync(`tasklist /FI "PID eq ${pid}" /NH`, {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            return output.includes(String(pid));
+        }
+        else {
+            execSync(`kill -0 ${pid}`, { stdio: 'ignore' });
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Gets file modification time in seconds since epoch (cross-platform)
+ *
+ * @param filePath - Path to file
+ * @returns Modification time in seconds since epoch
+ */
+export function getFileMtime(filePath) {
+    try {
+        if (process.platform === 'darwin') {
+            const output = execSync(`stat -f %m "${filePath}"`, { encoding: 'utf-8' });
+            return parseInt(output.trim(), 10);
+        }
+        else if (process.platform === 'win32') {
+            const output = execSync(`powershell -Command "(Get-Item '${filePath}').LastWriteTime.ToFileTimeUtc()"`, { encoding: 'utf-8' });
+            const fileTime = parseInt(output.trim(), 10);
+            return Math.floor((fileTime - 116444736000000000) / 10000000);
+        }
+        else {
+            const output = execSync(`stat -c %Y "${filePath}"`, { encoding: 'utf-8' });
+            return parseInt(output.trim(), 10);
+        }
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Kills a process (cross-platform)
+ *
+ * @param pid - Process ID to kill
+ * @param signal - Signal to send (default: SIGTERM)
+ */
+export function killProcess(pid, signal = 'SIGTERM') {
+    try {
+        if (process.platform === 'win32') {
+            execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore' });
+        }
+        else {
+            process.kill(pid, signal);
+        }
+    }
+    catch {
+        // Process may not exist, ignore
+    }
+}
+/**
+ * Acquires a file lock using atomic directory creation (cross-platform)
+ *
+ * @param lockPath - Path to lock directory
+ * @returns true if lock acquired
+ */
+export function acquireFileLock(lockPath) {
+    const fs = require('fs');
+    try {
+        fs.mkdirSync(lockPath, { recursive: false });
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            return false; // Lock already exists
+        }
+        throw err;
+    }
+}
+/**
+ * Enhanced cross-platform utility functions with async API and logger injection
+ */
+export class PlatformUtils {
+    constructor(options = {}) {
+        this.platform = process.platform;
+        this.logger = options.logger ?? consoleLogger;
+    }
+    /**
+     * Get current platform
+     */
+    getPlatform() {
+        return this.platform;
+    }
+    /**
+     * Check if current platform is Windows
+     */
+    isWindows() {
+        return this.platform === 'win32';
+    }
+    /**
+     * Check if current platform is POSIX (macOS or Linux)
+     */
+    isPosix() {
+        return this.platform === 'darwin' || this.platform === 'linux';
+    }
+    /**
+     * 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
+     */
+    async checkProcessExistsAsync(pid) {
+        try {
+            if (this.isWindows()) {
+                const output = execSync(`tasklist /FI "PID eq ${pid}" /NH`, {
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'ignore'],
+                    windowsHide: true
+                });
+                return output.includes(pid.toString());
+            }
+            else {
+                // Signal 0 = check existence without actually sending a signal
+                process.kill(pid, 0);
+                return true;
+            }
+        }
+        catch (err) {
+            if (err.code === 'ESRCH') {
+                // No such process
+                return false;
+            }
+            if (err.code === 'EPERM') {
+                // Process exists but we don't have permission to signal it
+                return true;
+            }
+            this.logger.error(`Error checking process ${pid}:`, err);
+            return false;
+        }
+    }
+    /**
+     * Get file modification time (async, uses fs.stat for cross-platform)
+     *
+     * @param path File path
+     * @returns Modification time in seconds since epoch
+     */
+    async getFileMtimeAsync(path) {
+        try {
+            const stats = await stat(path);
+            return Math.floor(stats.mtimeMs / 1000);
+        }
+        catch (err) {
+            this.logger.error(`Error getting mtime for ${path}:`, err);
+            throw err;
+        }
+    }
+    /**
+     * 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
+     */
+    async acquireFileLockAsync(lockPath, timeoutMs = 5000) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeoutMs) {
+            try {
+                await mkdir(lockPath, { recursive: false });
+                return true; // Lock acquired
+            }
+            catch (err) {
+                if (err.code === 'EEXIST') {
+                    // Lock exists, wait and retry
+                    await new Promise(resolve => setTimeout(resolve, 100));
+                    continue;
+                }
+                this.logger.error(`Error acquiring lock at ${lockPath}:`, err);
+                throw err;
+            }
+        }
+        this.logger.warn(`Lock acquisition timeout after ${timeoutMs}ms: ${lockPath}`);
+        return false;
+    }
+    /**
+     * Release file lock (async)
+     *
+     * @param lockPath Path to lock directory
+     */
+    async releaseFileLockAsync(lockPath) {
+        try {
+            await rmdir(lockPath);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                this.logger.error(`Error releasing lock at ${lockPath}:`, err);
+                throw err;
+            }
+        }
+    }
+    /**
+     * Kill process with signal (async)
+     *
+     * @param pid Process ID to kill
+     * @param signal Signal to send (default: SIGTERM)
+     */
+    async killProcessAsync(pid, signal = 'SIGTERM') {
+        try {
+            if (this.isWindows()) {
+                execSync(`taskkill /PID ${pid} /F`, {
+                    stdio: 'ignore',
+                    windowsHide: true
+                });
+                this.logger.debug(`Killed process ${pid} (Windows taskkill /F)`);
+            }
+            else {
+                process.kill(pid, signal);
+                this.logger.debug(`Killed process ${pid} with signal ${signal}`);
+            }
+        }
+        catch (err) {
+            if (err.code === 'ESRCH') {
+                this.logger.debug(`Process ${pid} doesn't exist (already terminated)`);
+                return;
+            }
+            this.logger.error(`Error killing process ${pid}:`, err);
+            throw err;
+        }
+    }
+    /**
+     * Kill process with graceful fallback (SIGTERM → SIGKILL)
+     *
+     * @param pid Process ID to kill
+     * @param gracePeriodMs Time to wait after SIGTERM before SIGKILL (default: 2000ms)
+     */
+    async killProcessGracefully(pid, gracePeriodMs = 2000) {
+        const exists = await this.checkProcessExistsAsync(pid);
+        if (!exists) {
+            this.logger.debug(`Process ${pid} doesn't exist, skipping kill`);
+            return;
+        }
+        try {
+            // Step 1: Send SIGTERM (graceful shutdown)
+            await this.killProcessAsync(pid, 'SIGTERM');
+            this.logger.debug(`Sent SIGTERM to process ${pid}, waiting ${gracePeriodMs}ms`);
+            // Step 2: Wait for grace period
+            await new Promise(resolve => setTimeout(resolve, gracePeriodMs));
+            // Step 3: Check if process still exists
+            const stillExists = await this.checkProcessExistsAsync(pid);
+            if (!stillExists) {
+                this.logger.debug(`Process ${pid} terminated gracefully after SIGTERM`);
+                return;
+            }
+            // Step 4: Force kill with SIGKILL
+            this.logger.warn(`Process ${pid} didn't terminate after SIGTERM, sending SIGKILL`);
+            await this.killProcessAsync(pid, 'SIGKILL');
+            this.logger.debug(`Sent SIGKILL to process ${pid}`);
+        }
+        catch (err) {
+            this.logger.error(`Error during graceful kill of process ${pid}:`, err);
+            throw err;
+        }
+    }
+    /**
+     * 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
+     */
+    async sendNotification(title, body) {
+        try {
+            if (this.platform === 'darwin') {
+                await this.sendNotificationMacOS(title, body);
+            }
+            else if (this.platform === 'linux') {
+                await this.sendNotificationLinux(title, body);
+            }
+            else if (this.platform === 'win32') {
+                await this.sendNotificationWindows(title, body);
+            }
+            this.logger.debug(`Sent notification: ${title}`);
+        }
+        catch (err) {
+            this.logger.warn(`Failed to send notification "${title}": ${err}`);
+        }
+    }
+    /**
+     * macOS notification using osascript
+     */
+    async sendNotificationMacOS(title, body) {
+        const escapedTitle = title.replace(/"/g, '\\"');
+        const escapedBody = body.replace(/"/g, '\\"');
+        const cmd = `osascript -e 'display notification "${escapedBody}" with title "${escapedTitle}"'`;
+        execSync(cmd, { stdio: 'ignore' });
+    }
+    /**
+     * Linux notification using notify-send
+     */
+    async sendNotificationLinux(title, body) {
+        try {
+            execSync('command -v notify-send', { stdio: 'ignore' });
+            const escapedTitle = title.replace(/"/g, '\\"');
+            const escapedBody = body.replace(/"/g, '\\"');
+            execSync(`notify-send "${escapedTitle}" "${escapedBody}"`, { stdio: 'ignore' });
+        }
+        catch (err) {
+            throw new Error('notify-send not available on this system');
+        }
+    }
+    /**
+     * Windows notification using PowerShell toast
+     */
+    async sendNotificationWindows(title, body) {
+        const escapedTitle = title.replace(/'/g, "''");
+        const escapedBody = body.replace(/'/g, "''");
+        const psScript = `
+      [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null;
+      $template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02);
+      $xml = [xml]$template.GetXml();
+      $xml.GetElementsByTagName('text')[0].AppendChild($xml.CreateTextNode('${escapedTitle}')) | Out-Null;
+      $xml.GetElementsByTagName('text')[1].AppendChild($xml.CreateTextNode('${escapedBody}')) | Out-Null;
+      $toast = [Windows.UI.Notifications.ToastNotification]::new($xml);
+      [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('SpecWeave').Show($toast);
+    `;
+        execSync(`powershell -Command "${psScript}"`, {
+            stdio: 'ignore',
+            windowsHide: true
+        });
+    }
+}
+// Export singleton instance for convenience
+export const platformUtils = new PlatformUtils();
+//# sourceMappingURL=platform-utils.js.map

package/dist/src/utils/platform-utils.js.map

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

package/dist/src/utils/session-registry.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Session Registry - Central tracking for all Claude Code sessions and child processes
+ *
+ * Provides atomic file-based operations for tracking active sessions, detecting
+ * stale/zombie processes, and coordinating cleanup across multiple sessions.
+ *
+ * Key Features:
+ * - Atomic operations using temp file + rename pattern
+ * - File locking via mkdir (cross-platform atomic operation)
+ * - Automatic corruption recovery with JSON validation
+ * - Concurrent-safe updates from multiple processes
+ *
+ * Registry Location: `.specweave/state/.session-registry.json`
+ */
+import { SessionInfo, RegisterSessionOptions, StaleSessionInfo, SessionStatus } from '../types/session.js';
+import { Logger } from './logger.js';
+export declare class SessionRegistry {
+    private registryPath;
+    private lockPath;
+    private logger;
+    constructor(projectRoot: string, options?: {
+        logger?: Logger;
+    });
+    /**
+     * Acquires an exclusive lock on the registry file
+     *
+     * Uses mkdir as an atomic operation (works cross-platform)
+     * Waits up to LOCK_TIMEOUT_MS before failing
+     *
+     * @returns true if lock acquired, false if timeout
+     */
+    private acquireLock;
+    /**
+     * Releases the lock on the registry file
+     */
+    private releaseLock;
+    /**
+     * Reads the registry file with corruption recovery
+     *
+     * If registry doesn't exist, creates a new empty one
+     * If registry is corrupted (invalid JSON), creates backup and reinitializes
+     *
+     * @returns The current registry state
+     */
+    private readRegistry;
+    /**
+     * Writes registry to disk atomically
+     *
+     * Uses temp file + rename pattern for atomic write
+     * This ensures registry is never left in a corrupted state
+     *
+     * @param registry - The registry state to write
+     */
+    private writeRegistry;
+    /**
+     * Creates a new empty registry
+     */
+    private createEmptyRegistry;
+    /**
+     * Registers a new session in the registry
+     *
+     * @param sessionId - Unique session identifier
+     * @param pid - Process ID of the session
+     * @param options - Optional configuration
+     * @returns true if registration successful
+     */
+    registerSession(sessionId: string, pid: number, options?: RegisterSessionOptions): Promise<boolean>;
+    /**
+     * Updates the heartbeat timestamp for a session
+     *
+     * @param sessionId - Session to update
+     * @returns true if update successful
+     */
+    updateHeartbeat(sessionId: string): Promise<boolean>;
+    /**
+     * Adds a child process PID to a session
+     *
+     * @param sessionId - Parent session ID
+     * @param childPid - Child process PID to add
+     * @returns true if successful
+     */
+    addChildProcess(sessionId: string, childPid: number): Promise<boolean>;
+    /**
+     * Removes a session from the registry
+     *
+     * @param sessionId - Session to remove
+     * @returns true if successful
+     */
+    removeSession(sessionId: string): Promise<boolean>;
+    /**
+     * Gets a session by ID
+     *
+     * @param sessionId - Session to retrieve
+     * @returns Session info or undefined
+     */
+    getSession(sessionId: string): Promise<SessionInfo | undefined>;
+    /**
+     * Gets all sessions
+     *
+     * @returns Array of all session info
+     */
+    getAllSessions(): Promise<SessionInfo[]>;
+    /**
+     * Updates the status of a session
+     *
+     * @param sessionId - Session to update
+     * @param status - New status
+     * @returns true if successful
+     */
+    updateStatus(sessionId: string, status: SessionStatus): Promise<boolean>;
+    /**
+     * Gets all stale sessions based on heartbeat threshold
+     *
+     * A session is considered stale if its last_heartbeat is older than
+     * the specified threshold.
+     *
+     * @param thresholdSeconds - Max age of last heartbeat before considered stale
+     * @returns Array of stale session info with staleness details
+     */
+    getStaleSessions(thresholdSeconds: number): Promise<StaleSessionInfo[]>;
+    /**
+     * Cleans up old sessions based on retention period
+     *
+     * Removes sessions that have been completed or stale for longer
+     * than the retention period.
+     *
+     * @param retentionHours - How long to keep old sessions (in hours)
+     * @returns Number of sessions removed
+     */
+    cleanupOldSessions(retentionHours: number): Promise<number>;
+    /**
+     * Checks if a PID exists (cross-platform)
+     *
+     * Uses kill -0 on Unix-like systems, which doesn't actually send a signal
+     * but checks if the process exists.
+     *
+     * @param pid - Process ID to check
+     * @returns true if process exists
+     */
+    private checkPidExists;
+}
+//# sourceMappingURL=session-registry.d.ts.map

package/dist/src/utils/session-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-registry.d.ts","sourceRoot":"","sources":["../../../src/utils/session-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EACL,WAAW,EAEX,sBAAsB,EACtB,gBAAgB,EAChB,aAAa,EACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAiB,MAAM,aAAa,CAAC;AAOpD,qBAAa,eAAe;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;gBAEX,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAclE;;;;;;;OAOG;YACW,WAAW;IA4BzB;;OAEG;IACH,OAAO,CAAC,WAAW;IAenB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAsCpB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAyBrB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;;;;;;OAOG;IACG,eAAe,CACnB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,OAAO,CAAC;IAuCnB;;;;;OAKG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyB1D;;;;;;OAMG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgC5E;;;;;OAKG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwBxD;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAcrE;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAc9C;;;;;;OAMG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAwB9E;;;;;;;;OAQG;IACG,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAyC7E;;;;;;;;OAQG;IACG,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgDjE;;;;;;;;OAQG;YACW,cAAc;CAuB7B"}